OpenText™ Archive Server

Programming Guide for the OpenText

Archive Server API

This manual describes how to access Archive Server via the

OpenText Archive Server API. Beside some basics and detailed
reference information on all available API functions, the manual
provides a number of sample programs, which help the
programmer to become familiar with this interface.

AR100500-PSA-EN-3
OpenText™ Archive Server
Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
Rev.: 2015-Sept-08
This documentation has been created for software version 10.5.
It is also valid for subsequent software versions as long as no new document version is shipped with the product or is
published at https://knowledge.opentext.com.

Open Text SA

40 Avenue Monterey , Luxembourg, Luxembourg L-2163

Tel: 35 2 264566 1

Open Text Corporation

275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1

Tel: +1-519-888-7111
Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440
Fax: +1-519-888-0677
Support: http://support.opentext.com
For more information, visit https://www.opentext.com

Copyright © 2015 Open Text SA and/or Open Text ULC (in Canada). All Rights Reserved.
Trademarks owned by Open Text SA or Open Text ULC (in Canada). All rights reserved.

Disclaimer

No Warranties and Limitation of Liability

Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However,
Open Text Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the
accuracy of this publication.
 Table of Contents
1 Introduction ................................................................................ 7
1.1 About OpenText Archive Server API ................................................... 7
1.2 About this document .......................................................................... 7
1.2.1 Target group and prerequisites .......................................................... 7
1.2.2 Structure .......................................................................................... 7
1.2.2.1 What to read first? ............................................................................. 8
1.2.3 Related documentation ...................................................................... 9
1.3 Abbreviations and important terms ..................................................... 9

2 Concepts and basics ............................................................... 11

2.1 Archive Server and its neighbors ...................................................... 11
2.1.1 Servers, clients, leading application .................................................. 11
2.1.1.1 Logical archives, pools, storage tiers ................................................ 12
2.1.2 Proxy server ................................................................................... 13
2.2 Document structure and archive document model ............................. 14
2.2.1 Document model ............................................................................. 14
2.2.2 Document ID .................................................................................. 14
2.2.3 Components ................................................................................... 15
2.2.4 Attributes ........................................................................................ 16
2.2.5 Components in libdsh ...................................................................... 17
2.2.6 Document/component formats (renditions, file types) ......................... 19
2.2.7 Access protection via SecKeys (signed URLs) .................................. 22
2.2.8 Lifecycle management functionality .................................................. 23
2.2.8.1 Retention period ............................................................................. 24
2.3 libdsh library ................................................................................... 26
2.3.1 Functional overview ........................................................................ 27
2.3.1.1 Grouped function list ....................................................................... 28
2.3.2 SecKey handling in libdsh ................................................................ 31
2.3.3 Initializing and ending a libdsh session ............................................. 32
2.3.3.1 Logging .......................................................................................... 32
2.3.3.2 Initializing libdsh .............................................................................. 33
2.3.3.3 Setting parameters .......................................................................... 34
2.3.3.4 Error handling ................................................................................. 35
2.3.3.5 Ending libdsh .................................................................................. 36
2.3.4 Function parameters and return values ............................................. 36

3 libdsh function reference ........................................................ 37

3.1 dshClearLastError: Clear last error message ............................. 39
3.2 dshClose: Close connection to repository server ............................. 40
3.3 dshCompInfo: Get information on (unknown) components ............... 41

OpenText Archive Server – Programming Guide for the OpenText Archive Server API iii
AR100500-PSA-EN-3
Table of Contents

3.4 dshCompInfoStatus [DEPRECATED]:

Get information on (unknown) components ....................................... 45
3.5 dshDsAdmInfo2: Get information about archives ............................. 48
3.6 dshCsCache, dshCsCachePart: Cache a component or a part of
a component on Archive Cache Server ............................................. 52
3.7 dshCsFlush: Remove a component or an entire document from
Archive Cache Server ...................................................................... 54
3.8 dshDsAppendData, dshDsAppendFile: Append to a component ... 56
3.9 dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list .. 59
3.10 dshDsCreate*, dshDsCreateFile*: Create document/
Component ..................................................................................... 64
3.11 dshDsDelAttribute: Delete attribute ........................................... 70
3.12 dshDsDelete, dshDsDelete2: Delete document/Component ......... 72
3.13 dshDsGet*, dshGetFile*, dshDsGetPart*: Get component ....... 75
3.14 dshDsGetATS: Get evidence record of a component ........................ 79
3.15 dshDsGetAttribute: Get attributes .............................................. 81
3.16 dshDsGetDocumentHistory: Get document history ...................... 84
3.17 dshDsInfo: Get info string for document/Component ....................... 86
3.18 dshDsMigrate, dshDsMigrate2: Migrate document to another
logical archive or pool ...................................................................... 89
3.19 dshDsLock: Lock document ........................................................... 92
3.20 dshDsPutCert, dshDsPutCertFile: Put certificate to Archive
Server ............................................................................................ 94
3.21 dshDsPutCert2, dshDsPutCertFile2: Put certificate to
Archive Server ................................................................................ 97
3.22 dshDsReserveDocId: Get new document ID ................................ 100
3.23 dshDsSearch, dshDsSearch2: Search in component ................... 102
3.24 dshDsSetAttribute: Set attribute .............................................. 105
3.25 dshDsSetDocumentFlag: Start delayed processing ..................... 107
3.26 dshDsUnlock: Unlock document .................................................. 110
3.27 dshDsUpdate*, dshDsUpdateFile*: Update component ............ 112
3.28 dshDsValidUser2: Check user account ....................................... 117
3.29 dshDsVerifyATS: Verify signature of an ArchiSig timestamp ......... 119
3.30 dshDsVerifySig: Proof timestamp of a component ...................... 124
3.31 dshExit: Exit the libdsh library ..................................................... 127
3.32 dshFree: Release allocated memory ............................................. 128
3.33 dshGetAidRefreshInterval: Get aid refresh interval ................ 129
3.34 dshGetAidRefreshTime: Get time of next ADMS info refresh ...... 130
3.35 dshGetApplication: Get application name ................................ 131
3.36 dshGetAuthId: Get authenticity ID of client .................................. 132
3.37 dshGetCertificateFile: Get filename of certificate .................. 133
3.38 dshGetCompSize: Get size of component ..................................... 134
3.39 dshGetCompStatus: Get information on component ..................... 136

iv OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 Table of Contents

3.40 dshGetConfig: Get value of global configuration variable .............. 139

3.41 dshGetDocInfo, dshGetDocInfo2: Get status of a document ..... 140
3.42 dshGetDocStatus: Get information on document ......................... 144
3.43 dshGetExpTimeSecKey: Get expiration time of SecKey ................ 147
3.44 dshGetLastErrno: Get error number .......................................... 148
3.45 dshGetLastError: Get error message ........................................ 150
3.46 dshGetMimeType: Convert to MIME type ...................................... 152
3.47 dshGetPrivateKeyFile: Get filename of private key .................. 154
3.48 dshGetProxy: Get proxy server ................................................... 155
3.49 dshGetUser: Get user name ........................................................ 156
3.50 dshGetVersion: Get major and minor version number of libdsh .... 157
3.51 dshExtendRetention: Extend retention of a document ................ 158
3.52 dshIsArchive: Verify existence of an archive .............................. 160
3.53 dshIsComp: Verify existence of a component ................................. 162
3.54 dshIstreamClose: Close stream for reading a component ........... 164
3.55 dshIstreamOpen, dshIstreamOpen2, dshIstreamOpenPart,
dshIstreamOpenPart2: Open stream for reading a component .... 165
3.56 dshIstreamRead: Read opened stream ....................................... 168
3.57 dshOpen, dshOpen2: Open connection to repository server ........... 170
3.57.1 dshOpen ...................................................................................... 170
3.57.2 dshOpen2 .................................................................................... 172
3.58 dshSetAidRefreshInterval: Set refresh interval for ADMS info 174
3.59 dshSetAidRefreshTime: Set time of next ADMS info refresh ....... 175
3.60 dshSetApplication: Set application name ................................. 177
3.61 dshSetAuthId: Set authenticity ................................................... 178
3.62 dshSetCertificate, dshSetCertificateFile: Set certificate 179
3.63 dshSetConfig: Set value of global configuration variable .............. 181
3.64 dshSetExpTimeSecKey: Set expiration time for SecKey ............... 182
3.65 dshSetLogFile: Set log file ........................................................ 183
3.66 dshSetLogLevel: Set log level .................................................... 184
3.67 dshSetLogMaxSize: Set maximum size of log file ........................ 186
3.68 dshSetPrivateKey, dshSetPrivateKeyFile: Set private key .. 187
3.69 dshSetPrivateKeyPassphrase: Set passphrase to decrypt
encrypted private key file ............................................................... 189
3.70 dshSetProxy: Set proxy server .................................................... 190
3.71 dshSetUser: Set user name ........................................................ 191

4 Archive Server API in practice ............................................. 193

4.1 Preparations ................................................................................. 194
4.1.1 Files accompanying this manual ..................................................... 194
4.1.2 Include file .................................................................................... 194
4.1.3 Library files ................................................................................... 195

OpenText Archive Server – Programming Guide for the OpenText Archive Server API v
AR100500-PSA-EN-3
Table of Contents

4.1.4 Linking ......................................................................................... 196

4.2 Basic structure of the sample programs .......................................... 197
4.3 Sample programs in detail ............................................................. 198
4.3.1 dsh_put example: Archiving files in a single document .................. 199
4.3.2 dsh_get example: Get all archived files of a document/retrieve
component information .................................................................. 202
4.3.3 dsh_append example: Append data to an archived file ................... 206
4.3.4 dsh_attribute example: dealing with document attributes ........... 209
4.3.5 dsh_search example: Searching and getting the found piece of
data ............................................................................................. 214
4.3.6 dsh_lock example: Locking/unlocking documents ......................... 218
4.3.7 dsh_info example: Retrieving information about logical archives ... 222

5 References ............................................................................. 225

5.1 Further information sources ........................................................... 225
5.2 Events .......................................................................................... 225
5.2.1 Events in alphabetical order ........................................................... 225
5.2.2 Events in numerical order .............................................................. 226
5.3 Global environment variables ......................................................... 228
5.4 libdsh errors .................................................................................. 234
5.4.1 libdsh error messages in alphabetical order .................................... 234
5.4.2 libdsh errors in numerical order ...................................................... 236
5.5 Figures and tables ......................................................................... 237

vi OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
Chapter 1
Introduction

1.1 About OpenText Archive Server API

OpenText Archive Server provides a programming interface that allow other
software applications to directly store and retrieve documents on Archive Server on
a low abstraction layer: the Archive Server API (short: Archive API) in the following.

Archive Server The Archive Server API is a C++ and Java library primarily intended for being
API integrated into applications, operating on a less abstract level. Both provide direct
access to Archive Server and can be easily incorporated into your applications for
accessing and storing documents on the server, modifying document properties etc.

1.2 About this document

This manual describes the Archive Server API, what it does and does not do, and how
to integrate it into your own applications. As this manual is accompanied by several
sample programs, you get not only a reference of the available functionality, but also
an introduction to the practical use of the Archive Server API.

Note: This manual describes the C++ library.

1.2.1 Target group and prerequisites

The manual is written for programmers who want to enable their applications to
access Archive Server. To use it, you should have programming experience in C++.
The OS platform is of minor importance; libdsh (i.e. the API) supports C++ and
several UNIX/Linux platforms – see “libdsh library” on page 26. You should also
be familiar with at least one related component, for example, the imaging client, and
should know the principal client/server architecture of the system (see also “Archive
Server and its neighbors” on page 11).

1.2.2 Structure
The manual consists of five chapters:
• The first chapter (i.e. this chapter) provides some introductory information on a
high and abstract level – about the manual itself and about the Application
Programming Interfaces (API) related to Archive Server.
• The second chapter, “Concepts and basics“ on page 11 deals in greater detail
with basic ideas and concepts. Among other things, you will learn
• a bit of the topology in a system referring to Archive Server (in other words:
"your" future neighbors)

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 7
AR100500-PSA-EN-3
Chapter 1 Introduction

• what a document is,

• which functions are offered by Archive Server API, and
• The third chapter, “libdsh function reference“ on page 37, is a reference and a
detailed description of all functions offered by the Archive Server API.
• The fourth chapter, “Archive Server API in practice“ on page 193, gives an
introduction to integrating the Archive Server API into your applications and
using the most important functions in practice. In particular, it deals with several
sample programs coming with this manual and describes their internal structure
and their usage. In a few words: This chapter will help you to become familiar
with the Archive Server API.
• The fifth chapter, “References“ on page 225, provides references for error
messages and global variables and links for further information.

Troubleshooting information

This manual does not provide an explicit troubleshooting section. However,

troubleshooting hints appear in their respective contexts, throughout the
manual, and are collected in the index. So, if you encounter a problem and do
not know where to look for a solution, look for “Troubleshooting” in the index
and follow the most appropriate link there.

1.2.2.1 What to read first?

Introduction This manual is intended as both a reference for and an introduction to the Archive
and Reference Server API. So you surely will not and need not read the whole guide. If you feel
uncertain what you should read first, try the following:

1. Browse through the sections in “Concepts and basics“ on page 11 and check
which sections are important to you:

• In particular, you should become familiar with how documents are

structured on Archive Server (components, file types) and how they are
addressed for retrieval (“Document structure and archive document model”
on page 14). Also, you should know the general structure of “Archive
Server and its neighbors” on page 11.
• SecKeys[1] are relevant, to protect the access to the documents is protected
accordingly.
• In any case, you should read:

• “Functional overview” on page 27, “Initializing and ending a libdsh

session” on page 32 to learn how to initiate the library that provides the
API functionality, and
• “Function parameters and return values” on page 36 for an initial
overview of the most important functions and their usage.
[1] A means for protecting documents against unauthorized access.

8 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 1.3. Abbreviations and important terms

2. Then you may wish to browse through “libdsh function reference“ on page 37
and study the description of those functions that are important to you.
3. Finally – or as an alternative – look at “Archive Server API in practice“
on page 193 and work through the examples and consult the respective function
descriptions in Chapter 3 on page 37 for further details.

1.2.3 Related documentation

For general and detailed information on related tasks and components, in particular
the following documents are relevant:
• General concepts and administrative questions
• OpenText Archive Server - Administration Guide (AR-ACN)
• OpenText Enterprise Library - Scenario and Configuration Guide (EL-GGD)
• Other APIs that might be interesting
• Open Text Imaging ODMA - Programming Guide (CLDL-PGD)
• OpenText Enterprise Library - Programming Guide for the Metadata Services API
(ELWS-PGD) in the OpenText Developer Network (https://
knowledge.opentext.com/knowledge/cs.dll/Open/ELS)

1.3 Abbreviations and important terms

The following abbreviations and central terms are used in this manual:

ADMS
Administration Server (see “Servers, clients, leading application” on page 11).
AID
Archive ID, the name of a logical archive (see “Logical archives, pools, storage
tiers” on page 12).
API
Application Programming Interface
Archive Server
The central server unit and related services storing the content (documents) –
see “Servers, clients, leading application” on page 11.
DER
Distinguished Encoding Rules (DER)
A specific encoding method – see 3 on page 225 in “Further information
sources” on page 225
DLL
Dynamic Link Library
DMS
Document Management System.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 9
AR100500-PSA-EN-3
Chapter 1 Introduction

docid
Document ID (name), a unique identifier of a document (see “Document ID”
on page 14).
(“Record ID” in Systems based on AS)

DS (JDS for Java DS)

Document service, i.e. the document repository and management within
Archive Server (see “Servers, clients, leading application” on page 11).

GUI
Graphical user interface

HTTP/HTTPS
HTTP is an acronym for Hypertext Transfer Protocol, the most common
communication protocol for internet communication. HTTPS is a modification of
that protocol for secure (encrypted) communication.

libdsh
The core C++ library providing the local functionality for accessing the Archive
Server API.

MIME
Multipurpose Internet Mail Extensions, a convention for describing file formats
– see [2 on page 225] in “Further information sources” on page 225 and
“Document/component formats (renditions, file types)” on page 19.

PEM (Privacy Enhanced Mail)

Privacy Enhanced Mail, a convention dealing with key certification (Encryption
of Internet mails) – see [4 on page 225] in “Further information sources”
on page 225.

Repository server
The repository server is the central server, i.e. the communication peer for the
Archive Server API in your application. Depending on your actual system
configuration, this can be a TCP Context Server, a server hosting Enterprise
Library or Archive Server.

SecKey
A means for protecting documents against unauthorized access – see “Access
protection via SecKeys (signed URLs)” on page 22 for details.

URL
Uniform Resource Locator, an address on the Internet (or a file/document
location specification using this syntax)

WORM
Write Once, Read Many, a magneto-optical medium (disk) that can be
overwritten.

XML
Extensible Markup Language, a universal file format for structured documents
and data on the Web (see http://www.w3c.org).

10 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
Chapter 2
Concepts and basics

2.1 Archive Server and its neighbors

Because the Archive Server API provides access to Archive Server at a low level, you
should be familiar with the basic architecture of the system, as it typically occurs in
the context of this API. This section shortly outlines this architecture and explains
the most important terms in this context.

libdsh Before looking at “your” neighbors, however, you should know a bit more about
library “yourself”, i.e. the Archive Server API: In fact, this API consists of a function library,
which you refer to from within your applications, and corresponding
communication partners on Archive Server. The library that provides the respective
functionality on your site is the libdsh library. So, as a rule, this manual deals with
the libdsh library rather than with the Archive Server API as a whole.

Java libraries The functionality provided by the libdsh library is also provided by Java libraries.

Note: This manual describes the C++ library.

2.1.1 Servers, clients, leading application

The typical system, where the Archive Server API is used, consists of the following
components:
• Leading application
As documents usually are dealt with in a certain context or business process,
there is one or more leading application that deals with these business processes. It
stores the data that is relevant for the business processes; this also includes
references to the documents that have been archived on Archive Server for this
business process. Examples for such leading applications are OpenText Content
Server, SAP, Microsoft SharePoint®, etc. But also any proprietary database
system within your company may operate as a leading application.
Leading applications are not further discussed in this document. Nevertheless,
they may be important for your programming work: Usually, they form (or
contain) the database, that provides your application with the necessary
information to obtain a document. Please refer to the documentation of your
respective system for information on how to address your leading application
from your programs.
• Clients
There are dedicated clients for administering the system (Administration Clients),
for archiving and retrieving archived documents (for example, OpenText
Imaging Windows Viewer) and for archiving documents at a scan station

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 11
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

(OpenText Imaging Enterprise Scan. Those clients, which are used by end users
to work with documents, are called OpenText Imaging Clients.

Note: Note that the term “server” may mean both the computer hardware
hosting the server software as well as the server functionality itself. This also
applies to the term “client”: It may mean either the specific functional unit on a
computer or the hosting computer itself.

2.1.1.1 Logical archives, pools, storage tiers

Content reposi- The content repository (i.e. document repository) within Archive Server is
tories / Logical subdivided into logical archives. These logical units are set up during the
Archives
customization of the system and are used to sort the documents according to
configurable criteria, e.g., different document retention periods or different types of
access authorization. Each logical archive has a unique name, the archive ID (AID),
which must be used to access the archive, for example, for storing or retrieving a
document.

Notes
• If using libdsh, please note that your application must specify both the
Document ID and the logical archive for retrieving or modifying a
document, and it must specify a logical archive for storing a document. In
other words, your application must provide a means for “remembering”
both the respective Document ID and the logical archive.
• Instead of “logical archive”, frequently just the term “archive” is used. Note,
however, that “archive” might also mean the document archive as a whole.
• See also Section 2.4 “Logical archives” in OpenText Archive Server -
Administration Guide (AR-ACN).

Document Each logical archive is subdivided into one or more document pools. These pools are
pools, storage needed to assign storage devices.
tiers
• Storage tiers
Used to sort components according to their use in the leading application, for
example, to distinguish between different relevance levels or to separate
documents according to their access frequency.
See Section 12.4 “Creating and modifying storage tiers” in OpenText Archive
Server - Administration Guide (AR-ACN) for further details.

Notes
• Storage tiers are available only in Archive Servers with software version
9.7 or higher and need libdsh_3 to be addressed.
• Some functions in libdsh provide parameters to specify a pool name and
a storage tier. Ensure that you do not specify more than one of these
parameters in a function call, otherwise the call will fail, if the parameters
result in specifying different pools to be used.

12 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.1. Archive Server and its neighbors

If a client stores a document in the respective (logical) archive and transmits a

storage tier for this document, Archive Server automatically stores the document in
the pool assigned to this storage tier, respectively (provided that such an assignment
has been configured before on the server). Documents with no assignment are stored
in the default pool which usually is available in every logical archive (i.e. the
document pool with the default type assigned; this pool must have been created by
the archive administrator).

Note: In libdsh functions for storing or modifying documents, the storage tier
can be specified via the storage_tier function parameter, respectively. Make
sure that the string specified in this parameter matches the corresponding
strings specified in the archive configuration. Note that these parameters are
case-sensitive (as most libdsh parameters are).

2.1.2 Proxy server

To improve accessibility, communication between libdsh and Archive Server, a
proxy server can be used, i.e. a server located anywhere between the computer
hosting your application and the computer hosting Archive Server.

libdsh supports the communication via a proxy server. As soon as you specify a
proxy server via the dshSetProxy function, libdsh and the repository server
communicate exclusively via this server. If the proxy server is not available, libdsh
cannot contact the repository server.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 13
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

2.2 Document structure and archive document

model
2.2.1 Document model
Document This section describes the Archive document model, i.e., the way documents are
model structured in Archive Server and addressed by the Archive Server API.

The Archive document model is a means to structure documents stored in Archive

Server. It provides structuring rules that are applied by and used from the Archive
Server API.

Calls coming from the Archive Server API always retrieve the current version of a
document.

Document In the Archive document model and thus in Archive Server, a document is a
logically encapsulated data package consisting of components (see sections
“Document ID” on page 14 and “Components” on page 15).

The central element in libdsh is the component, not the document (see “Components
in libdsh” on page 17).

2.2.2 Document ID
Alphanumeric Each archived document is identified in Archive Server by the Document ID, shortly
ASCII string DocID. This is simply a chain of alphanumeric ASCII characters[1] that appears quite
arbitrary to human users, e.g., aaay65qz5oytuj36zajhfgjmqxvzk. This Document
ID uniquely identifies a document within the archive.

Generation The DocID can be created by Archive Server: If a document is sent to Archive Server
of the DocID to be archived, the server automatically assigns a unique Document ID and returns
this ID to the process sending the document.

As an alternative, the Document ID can be specified by the calling process. If you

want your application to specify the Document IDs, note that your application is
responsible for specifying IDs which are unique in the whole archive system of your
company (world-wide); to provide these unique IDs, you may, for example, include
the archiving date and the IP address of the client in the ID. If in doubt, you may
contact your OpenText partner for assistance.

Notes
• Document ID and logical archive required for retrieval
When your application retrieves a document, it must specify the Document
ID and the logical archive where the document has been stored. Therefore
make sure that your applications store both the Document ID and the logical
archive for a document, when they send it to the archive.
[1] i.e. a...z, 0...9; no special characters, dashes or punctuation characters

14 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

• Length of the Document ID

Document IDs need not necessarily be as long as shown above (but as they
must be unique for many years, they usually will be). For better legibility,
the examples in this manual use shorter Document IDs at times.

2.2.3 Components
Components Documents are structured in several components. Each component is a file that is
not interpreted further. A document is thus similar to a directory in which the file/
component is located.

The components of a document may be located on different volumes, which means

that a document may extend over more than one volume. In addition, it is possible
to define access rights and attributes for each document and each component. The
system supports different component versions.

Component The following component types are supported:

types
• Main component
A document may consist of notes or annotations (see below) only, for example,
or may even contain several document files, each of which is a separate
component then. The first component of a document stored is interpreted by
Archive Server as the main component.
The content unit is supposed to be the main component of a document. Therefore
these two expressions are sometimes used synonymously. For documents that
are stored by components, the main component should be stored at first.
• Rendition
The component comprising the actual content of a document is the core of the
document, containing the file(s) which shall be stored in the archive, the content.
Content may be rendered in different file formats that are called renditions or
renderings, e.g., as a Word file[2], as a PDF file or as a TIFF file. Each rendition is
stored in another component.
For compatibility reasons, Archive Server does not store different renditions in
the same document, but generates a new document for each rendition. Therefore
you should not store more than one file in a document, unless you want to access
it via your own applications exclusively.
Each rendition may have several pages and may even consist of several physical
files (a multi-page fax, for example; but observe the notes below). Thus, each
rendition is a separate component; if a rendition consists of several files, each file
is a separate component.
• Multi-page Fax/TIFF
If you want to store a multi-page fax in TIFF format, you should either
(preferably) generate a multi-page TIFF file or save each page in a separate
[2] or another source file format; for example as SAP print list

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 15
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

component of the same document. You should not insert each TIFF page into a
separate document, as this may confuse the OpenText Imaging Clients.
• Notes and annotations
Notes and annotations can be added to the document by the user to highlight or
comment parts of the contents. Notes are text remarks, whereas annotations are
graphic markings (for example, yellow highlighting with a virtual text marker, or
underlining). These are stored in a separate graphic layer file.
All notes are collected in the notes component, whereas all the annotations
together make up the annotations component (but also see “Components in
libdsh” below).

2.2.4 Attributes
Attribute A document and each of its components may also have so-called document/component
attributes for administering the document; these are stored separately from the
document components, in the server database. The format of these attributes is
name=value, where name and value are character strings. Attributes can be defined
when the document is saved for the first time, or they can be deleted, modified, or
added at a later stage.

Predefined: Archive Server uses one predefined document attribute that should only be used in
TYPE attribute this context: The type attribute of the document defines the file type of its content
unit (see “Document/component formats (renditions, file types)” for further details).
Further arbitrary attributes can be defined by any application accessing Archive
Server, but are not supported by the OpenText Imaging Clients.

Additional information:

Important
• Apart from document attributes, Archive Server stores further information
for each component, but not via attributes. In particular, there is a type
specification for each component, too, which is no attribute.
See also “Document/component formats (renditions, file types)” on page 19
and “dshDsInfo: Get info string for document/Component” on page 86.
• Please note that no further data is stored on Archive Server itself, in
particular no information which could help to find a document later-on.
Therefore, you must have a Document ID (see below) in order to retrieve
a document from Archive Server. However, if the documents in the
archive are managed by an overlying application such as SAP or TCP,
you may use the database of that system to find a document according to
certain search criteria.

16 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

2.2.5 Components in libdsh

For libdsh, all components are equal; it does not distinguish among renditions,
notes, annotations, etc. libdsh can just generate, update or retrieve a component, and
may tell you the file type of a component (see “Formats” on page 19) or other
information found on a component. It treats all component types alike and does not
pay attention to their contents. Your application is responsible for using and
evaluating the contents of a component in the correct manner.

Note: libdsh deals exclusively with components, not with documents. If

several components are necessary to build an entire document, libdsh enables
you to load the individual components, but cannot assemble these components
to be displayed as a whole.

Important
Note that the first component usually is interpreted as the main component
(see “Main component” on page 15). Therefore always store the main
component at first.

If you want to access a certain component in a document, you must know the
respective component ID and specify it in the respective libdsh function. As a rule,
component names and types correspond to a convention, which is listed in
“Convention for component names and types ” on page 17. If you use component
names that do not correspond to this convention, your application should store these
names along with the Document ID and the logical archive. If you do not know the
name of a component, you can retrieve the names of all components in a document
using the dshDsInfo function within libdsh.

Table 2-1: Convention for component names and types

Component Name Type

Content unit(s) data or data<n>[a] file type, see “Formats” on page 19
for details
Add. information in XML meta.xml application/x-meta
format (XML meta)[b]
Notes note text/x-ascii_note
XML note note.ixos
Annotation anno.ixos application/x-anno
anno.ole application/x-oleanno
Form overlay FORM.INFO application/x-ascii
Component with MTA META_DOCUMENT file type of the contained MTA
documents documents
Component with MTA META_DOCUMENT_IN application/x-idx
mapping table DEX

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 17
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

Component Name Type

Components for SAP (do not descr application/x-r3_index
modify!)[c] PAGELIST application/x-
IM pagelistapplication/x-note
Components for SAP TATTRLIST application/x-attr
solutions (do not modify!)
[a]
Default name. If several files were archived in the same document (for example, several pages of
document which has been converted to single-page TIFF, data is extended by a running number.
Due to historical reasons, the content unit may also have the original file name, or may be named
<number.pg>.
[b] since software version 5
[c] see also “dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list” on page 59

Distributed on Note that the individual components of a document need not be located in the same
different place within the archive. In fact, notes and annotations are often stored in a different
storage devices
medium (i.e. logical archive or pool) than a content unit, as they can be modified or
extended, while the content unit stays unchanged. Moreover, a document may be
extended over time, when the volume containing the former components is already
full; then, extensions are stored in another volume. Still, these components form a
single document, still, and neither the programmer nor the user will notice this
distribution.

18 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

2.2.6 Document/component formats (renditions, file types)

Formats There are many different types of files, for example, plain ASCII files, Word and
Excel documents, TIFF images etc. Each has a specific file format and structure,
which often can be read only by certain applications. Therefore, if a file is stored in
the archive, it is neccessary to store the type of the file as well, for example, to enable
the OpenText Imaging Clients to open a file in the appropriate application.

Type Unlike Windows, Archive Server does not store or recognize the format of a file via
parameter the file extension, but via a document attribute (TYPE attribute) or the component
information, that is stored for each component in addition to the component
contents. Therefore, the libdsh functions for storing or modifying a document or
component require that the format of the document or component must be specified
in the function call parameters.

Note: Both the archive document and the component can have a type assigned
to them. For the document, the type is stored in a document attribute, but the
type definition for a component is stored in the component information, not in
an attribute.

The server software no longer requires the document type attribute, as the
relevant information is stored in the component type (this information is used
by the clients, for example, to display the document with the appropriate
viewer software). However, the document type is still maintained for
compatibility reasons, as this attribute may be evaluated by a super-ordinated
software.

Specifying In principle, there are two ways to specify a file type:

the type
• the MIME syntax (Multipurpose Internet Mail Extensions, defined by the
RFC1521 Internet standard, see [2 on page 225] in “Further information sources”
on page 225), for example, image/tiff; and
• the older proprietary syntax, which is based on the file extension of most file
types, for example, TIFF, ALF, FAX.

Use MIME In libdsh, you should always use MIME syntax to remain up-to-date and to avoid
types! confusion. libdsh converts a type specification that corresponds to the proprietary
syntax, to the MIME syntax, anyway. And some functions, especially if they are
related to component types, even refuse a type specification that does not
correspond to MIME syntax, and return an error.

On the other hand, if you retrieve documents or evaluate document attributes, a

proprietary type specification may be returned in some case. Your application
should be able to deal with this, if necessary.

Notes
• To convert a proprietary file type specification into a MIME type
specification, use the dshGetMimeType function. Table 2-2 provides a list of

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 19
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

all document/component types and component names currently known in

libdsh.
• In some SAP constellations, the file type specifications caused errors because
the SAP expected exactly the same type string as was set up in the SAP
customization process (case-sensitive). If your SAP system presents an error
message saying that there are no applicable presets or customization settings
or that you do not have sufficient access permission, this may be the reason.

libdsh file types The following file types are known by libdsh.

Table 2-2: File types known in libdsh

Document type Component Component MIME type

name type
ALF * * application/x-alf
* * ALF application/x-alf
* anno * application/x-anno
* * ASCII application/x-ascii
* * ASCII_NOTE application/x-note
* * ASCII_ANNO application/x-ascii_anno
* * ASCII_NOTE text/x-note
* * ATTR application/x-attr
BIN * * application/octet-stream
* * BIN application/octet-stream
BMP * * image/bmp
* * BMP image/bmp
data * application/x-<document type>
DOC * * application/msword
* * DOC application/msword
FAX <n>.pg * image/tiff
* * FAX image/tiff
GIF * * image/gif
* * GIF image/gif
HTM * * text/html
* * HTM text/html
* * IDX application/x-idx
* im * application/x-note
JPG * * image/jpeg

20 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

Document type Component Component MIME type

name type
* * JPG image/jpeg
* meta.xml META application/x-meta
MPP * * application/vnd.ms-project
* * MPP application/vnd.ms-project
* oleanno * application/x-oleanno
* * OLE2_ANNO application/x-anno_ole2
OTF * * application/x-otf
* * OTF application/x-otf
* * PAGE_LIST application/x-pagelist
PCX * * image/pcx
* * PCX image/pcx
PDF * * application/pdf
* * PDF application/pdf
PPT * * application/vnd.ms-powerpoint
* * PPT application/vnd.ms-powerpoint
PS * * application/postscript
* * PS application/postscript
RAW * * application/x-raw
* * RAW application/x-raw
REO * * application/octet-stream
* * REO application/x-reo
* R3_INDEX application/x-r3_index
RTF * * application/rtf
* * RTF application/rtf
SCR * * application/x-scr
* * SCR application/x-scr
TIF * * image/tiff
* * TIF image/tiff
TIFF * * image/tiff
* * TIFF image/tiff
TXT * * text/plain
* * TXT text/plain

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 21
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

Document type Component Component MIME type

name type
XLS * * application/vnd.ms-excel
* * XLS application/vnd.ms-excel
* * * application/octet-stream

2.2.7 Access protection via SecKeys (signed URLs)

SecKeys, A logical archive on Archive Server can be protected against unauthorized access via
signed URL so-called SecKeys (security keys, the concept is also known as signed URL) according
to the SAP ArchiveLink specification V. 4.5.

Working SecKeys are an implementation of the asymmetrical encryption method, which can be
principle customized on Archive Server. When a client application wants to access a
document protected via SecKey, it must generate a signed URL. For this purpose, it
creates a SecKey, an information package including an ID for the calling application
or user (the AuthId) and certain key information that allow the target application to
verify the call and the calling application. This SecKey is appended to the URL
addressing the document in the repository server; the URL then is called a signed
URL.

The server verifies the SecKey and gives access to the requested document only if
the verification is successful.

Activate Therefore, we strongly recommend to activate the protection via SecKeys.

SecKey
Protection!
To enable this protection mechanism, several preconditions must be fulfilled:

1. The SecKey protection must be enabled on the server for the respective archive.

2. The client must have a key pair (private key, public key and digital certificate)
that is used to create and verify the SecKey information.

3. The keys and the digital certificate must be introduced in libdsh (or the local
application refering to libdsh, respectively).

4. The client must transfer the public key and the digital certificate to Archive
Server (for example, via the respective libdsh functions).

5. The server administrator must accept the public key and certificate of the client
and enable it on the server.

SecKey On the server, the protection can be disabled or enabled for each access mode (read,
access mode update, create, delete) on each logical archive (but only for the whole logical
archive, not for individual documents). The libdsh functions for accessing a
document or component are assigned to one of these access modes. If protection is
enabled for the respective access mode in the requested archive, the function will fail
(DSH_ERR_HTTP_401), unless your application is able to generate SecKeys.

22 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

Important
• We strongly recommend to activate SecKey protection. Allowing access
via unsigned URL (no SecKey protection) is insecure.
• A SecKey is a general key, and it is assigned to applications, not to users.

2.2.8 Lifecycle management functionality

Since version 9.6, Archive Server provides functionality to support lifecycle
handling. In the libdsh context, this particularly means the following:
• Retention handling
You can store a rentention period with a document component now, when it is
created, using one of several options (see “Retention period” on page 24).
• Migration
You can move (migrate) a document into another logical archive, for example,
with different archive characteristics; the existing DocId is maintained (see
“dshDsMigrate, dshDsMigrate2: Migrate document to another logical
archive or pool” on page 89)
• Event history
Important events such as modifications are stored with each document now to
support audit trails, if the auditing feature is activated for an archive.
In libdsh, this audit information can be obtained using the function
dshDsGetDocumentHistory (see “dshDsGetDocumentHistory: Get document
history” on page 84).
• Timestamp functionality
Using encrypted timestamps, the server can verify the integrity of a component
when retrieving it, and can ensure that the component has not been modified
meanwhile. In this context, the new ArchiSig timestamp concept has been
introduced in version 9.6.
In libdsh, the function dshDsVerifySig has been added – see
“dshDsVerifySig: Proof timestamp of a component” on page 124 for details.
With version 9.7 (libdsh_3), another function, dshDsGetATS, has been added that
returns the evidence record for a component.
Moreover it is possible now that the leading application creates its own
timestamp for a document and hands it over to Archive Server, when it archives
the document – see “dshDsCreate*, dshDsCreateFile*: Create document/
Component” on page 64 and “dshDsUpdate*, dshDsUpdateFile*: Update
component” on page 112.
The hand-over of a timestamp in the functions dshDsCreate*2 and
dshDsUpdate*2 is optional; if a NULL pointer or an empty string is specified in
the function call, timestamp assignment is applied as configured for the
respective logical archive (see Section 12.2.3 “Configuring the archive settings” in
OpenText Archive Server - Administration Guide (AR-ACN)).

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 23
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

2.2.8.1 Retention period

When a document component is created, you can assign a retention period to it to
prevent it from being deleted for a certain time span.

The meaning of retention periods and the related further functionality is described
in detail in Section 12.1.3 “Retention” in OpenText Archive Server - Administration
Guide (AR-ACN) and Section 12.2.4 “Configuring the archive retention settings” in
OpenText Archive Server - Administration Guide (AR-ACN).

In libdsh, there are several ways to assign a retention period:

• You can specify it while you create the component using one of the
dshDsCreate* functions.
• If the document is migrated to another logical archive or document pool, a new
retention period can be assigned, using the dshDsMigrate function.

Note that there is no way to reduce the retention period once it has been set for a
component. The retention period can be extended by migrating the document to a
different archive (dshDsMigrate) or by using the dshExtendRetention function
introduced with Archive Server 10.5.0.

Admissible The value for the retention period in the function calls can have one of the following
Value values (see also Section 12.2.4 “Configuring the archive retention settings” in
OpenText Archive Server - Administration Guide (AR-ACN)):
• infinite: The retention never expires which means that the component cannot
be deleted.
• none: The component has no retention period, thus is not protected from
deletion, if no other settings prevent it from being deleted.
• Any number specifies the length of the retention period in days. The start of the
retention period depends on context in which the period is set:
• In the functions dshDsCreate* and dshDsSetDocumentFlag, the retention
period starts on the day when the function is called.
• In the dshDsMigrate function, the retention period starts on the creation day
of the (original) component.
• keep (dshDsMigrate read only): The existing retention period is kept.

Default (no setting in call)

If you do not specify the appropriate parameter for the retention period in the
function call, this has different consequences in the individual functions:
• In the dshDsCreate* and dshDsMigrate functions, the default retention period
of the archive, where the component is stored, is used.
Note that the value is stored with the document, not as a reference. So even if the
default retention period of an archive should be changed some day, existing
documents in that archive keep their original period.

24 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.2. Document structure and archive document model

• In dshDsSetDocumentFlag, the existing value for the retention period is kept

(this function is also used in other context)

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 25
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

2.3 libdsh library

As mentioned earlier in this manual, the complete functionality of Archive Server
API on the application (client) site is provided by the libdsh library.

Communication As a rule, libdsh uses the HTTP or HTTPS protocol to communicate with Archive
protocol Server.

See “Preparations” on page 194 for information on compiling/linking details for the
individual platforms; use of the libdsh library itself does not depend on the
platform.

Note: Some functions exist in slightly different variants such as dshDsCreate

and dshDsCreate2. Usually, the difference between such variants is a different
data type for the one or other parameter, or one or more additional parameters
in one variant. As these differences are not relevant for the basic functionality,
we only refer to one of these variants in conceptual descriptions. However, you
usually can also use another variant, as a rule.

All variants of a function are described in the same sections in the function
reference.

26 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.3. libdsh library

2.3.1 Functional overview

What is the “complete functionality of the Archive Server API” as mentioned above?

Core functions Of course, the most important functions deal with storing documents on Archive
Server and retrieving them:

• Storing a document component:

• dshDsCreate and dshDsCreateFile store a piece of data or a complete file,

respectively, as a document component in the archive. The document can be
either an existing one, or a new document is created in the archive, depending
on the parameters handed over to the respective function.
• If you need the Document ID of a document before you store it in the archive
at all, use the dshDsReserveDocId function to reserve a Document ID.
• Modifying or deleting a document component, moving a document:

• Before you modify or delete a document, use the dshDsLock function to set
the so-called locked flag
Do not forget to check the result returned by the function to make sure that
the document is not in use by another client before you access it yourself.
• dshDsAppendData and dshDsAppendFile append a piece of data (memory
buffer) or a complete file to an existing document component.
• dshDsUpdate and dshDsUpdateFile allow you to modify an existing
document component, i.e. to replace its contents with a newer version.
• To delete a document component, use the dshDsDelete function.
• As soon as the modification is complete, use the dshDsUnlock function to
reset the locked flag.
• The dshDsMigrate function allows you to move a document to a different
logical archive or document pool.
• Retrieval:

• To retrieve a certain document component, use dshDsGet, dsh or

dshDsGetPart. dshDsGet and dsh return a complete component and store it
in a memory buffer or file, respectively. dshDsGetPart allows you to retrieve
a fragment of a component, specified by its offset from the component
beginning and its size.
• The dshDsSearch function enables you to search for a certain string within a
component.
• If you do not know which components a document contains, or you need
other information on a document (for example, the date of archiving), use
dshDsInfo to request the information from the DS and then dshCompInfo to
evaluate this information.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 27
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

• To retrieve general information on a certain document or component, use

dshGetDocInfo, dshGetCompStatus, dshGetCompSize,or
dshDsGetDocumentHistory, respectively.
• Attributes for both documents and components can be set, retrieved and
deleted via dshDsSetAttribute, dshDsGetAttribute and
dshDsDelAttribute, respectively. If you are dealing with SAP printlists, you
can also search for attributes in the respective description files (see
“dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list”
on page 59 for details).

Management Apart from these core functions, there are many other functions for the management
functions, of the libdsh session itself and for setting and retrieving SecKey parameters (see
SecKey settings
“SecKey handling in libdsh” on page 31).

Full function list All libdsh functions are listed in alphabetical order in “libdsh function reference“
on page 37, which also provides a detailed description of each function. Another
list, sorted by functionality, is provided in “Grouped function list” on page 28
below.

2.3.1.1 Grouped function list

Programming framework, initial setting
• “dshOpen, dshOpen2: Open connection to repository server” on page 170
• “dshClose: Close connection to repository server” on page 40
• “dshFree: Release allocated memory ” on page 128
• “dshExit: Exit the libdsh library” on page 127
• “dshGetVersion: Get major and minor version number of libdsh”
on page 157
• “dshGetConfig: Get value of global configuration variable” on page 139
• “dshSetConfig: Set value of global configuration variable” on page 181

Logging
• “dshSetLogFile: Set log file” on page 183
• “dshSetLogMaxSize: Set maximum size of log file” on page 186
• “dshSetLogLevel: Set log level” on page 184

Accounting settings
• “dshSetApplication: Set application name ” on page 177
• “dshGetApplication: Get application name” on page 131
• “dshSetUser: Set user name” on page 191
• “dshGetUser: Get user name” on page 156
• “dshDsValidUser2: Check user account” on page 117

Error message evaluation

• “dshGetLastErrno: Get error number” on page 148
• “dshGetLastError: Get error message” on page 150

28 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.3. libdsh library

• “dshClearLastError: Clear last error message ” on page 39

Communication parameters
• “dshDsAdmInfo2: Get information about archives” on page 48
• “dshSetAidRefreshInterval: Set refresh interval for ADMS info”
on page 174
• “dshGetAidRefreshInterval: Get aid refresh interval” on page 129
• “dshSetAidRefreshTime: Set time of next ADMS info refresh”
on page 175
• “dshGetAidRefreshTime: Get time of next ADMS info refresh ”
on page 130
• “dshSetProxy: Set proxy server” on page 190
• “dshGetProxy: Get proxy server” on page 155

Retrieving information on a component or document

• “dshCompInfo: Get information on (unknown) components” on page 41
• “dshCompInfoStatus [DEPRECATED]:
Get information on (unknown) components” on page 45
• “dshDsInfo: Get info string for document/Component” on page 86
• “dshGetCompSize: Get size of component” on page 134
• “dshGetCompStatus: Get information on component” on page 136
• “dshGetDocInfo, dshGetDocInfo2: Get status of a document”
on page 140
• “dshGetDocStatus: Get information on document” on page 144
• “dshGetMimeType: Convert to MIME type” on page 152
• “dshIsArchive: Verify existence of an archive” on page 160
• “dshIsComp: Verify existence of a component” on page 162
• “dshDsGetDocumentHistory: Get document history” on page 84

Searching
• “dshDsSearch, dshDsSearch2: Search in component” on page 102
• “dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list”
on page 59

Document/component attributes
• “dshDsDelAttribute: Delete attribute” on page 70
• “dshDsGetAttribute: Get attributes” on page 81
• “dshDsSetAttribute: Set attribute” on page 105

Retrieving a component or component part

• “dshDsGet*, dshGetFile*, dshDsGetPart*: Get component”
on page 75
• “dshIstreamOpen, dshIstreamOpen2, dshIstreamOpenPart,
dshIstreamOpenPart2: Open stream for reading a component”
on page 165
• “dshIstreamClose: Close stream for reading a component” on page 164

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 29
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

Storing or changing components

• “dshDsCreate*, dshDsCreateFile*: Create document/Component”
on page 64
• “dshDsLock: Lock document” on page 92
• “dshDsUnlock: Unlock document” on page 110
• “dshDsAppendData, dshDsAppendFile: Append to a component”
on page 56
• “dshDsUpdate*, dshDsUpdateFile*: Update component” on page 112
• “dshDsReserveDocId: Get new document ID” on page 100
• “dshDsMigrate, dshDsMigrate2: Migrate document to another logical
archive or pool” on page 89
• “dshDsSetDocumentFlag: Start delayed processing” on page 107
• “dshExtendRetention: Extend retention of a document” on page 158

Deleting a component
• “dshDsDelete, dshDsDelete2: Delete document/Component”
on page 72

Cashing
• “dshCsCache, dshCsCachePart: Cache a component or a part of a
component on Archive Cache Server” on page 52
• “dshCsFlush: Remove a component or an entire document from Archive
Cache Server” on page 54

Security, SecKey handling, Timestamps

• “dshSetAuthId: Set authenticity” on page 178
• “dshGetAuthId: Get authenticity ID of client” on page 132
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182
• “dshGetExpTimeSecKey: Get expiration time of SecKey” on page 147
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshGetCertificateFile: Get filename of certificate” on page 133
• “dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”
on page 94
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshGetPrivateKeyFile: Get filename of private key” on page 154
• “dshSetPrivateKeyPassphrase: Set passphrase to decrypt encrypted
private key file” on page 189
• “dshDsGetATS: Get evidence record of a component” on page 79
• “dshDsVerifySig: Proof timestamp of a component” on page 124

30 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.3. libdsh library

2.3.2 SecKey handling in libdsh

If you want to access an archive protected by SecKeys via libdsh, your application is
responsible for all activities related to this subject:
• You or the administrators of your product must obtain a private key and a digital
certificate (which includes the public key) for each participating client; this
information is usually contained in two files which must be provided to the
clients (of course, the private key file must not be made available to any
computer other than the assigned client computer).
• Your application must be able to access these files and must transfer the public
key and the certificate to Archive Server. For this purpose, libdsh provides the
following functions:
• Via dshSetCertificate and dshSetCertificateFile, the digital certificate
(which includes the public key) is introduced in libdsh; these functions are
described in “dshSetCertificate, dshSetCertificateFile: Set
certificate ” on page 179.
• Via dshSetPrivateKey and dshSetPrivateKeyFile, the private key is
introduced in libdsh; these functions are described in
“dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179.
• The dshDsPutCert and dshDsPutCertFile functions transfer the certificate
and the public key to Archive Server; these functions are described in
“dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”
on page 94.

Note: The *PutCert* functions and the *SetCertificate* functions

are not related. The *SetCertificate* functions causes libdsh to read a
certificate for local usage, for example, for checking signed requests by
another client. In contrast, *PutCert* transmits the certificate to the
server, but libdsh does not memorize its contents for local usage.

The *File functions read appropriate information from a file, whereas the other
functions read them directly from a memory buffer, which is safer especially for
the private key, but complicates the configuration of several clients.
• Your application should also set two further parameters, a unique authentication
ID (client ID) and an expiry time period, which defines how long a SecKey is valid
after it is received on the server. These parameters are necessary to build correct
SecKeys. If you do not specify them, libdsh will use default values (see below).
• Use dshSetAuthId for setting the authentification ID (client ID) of the
respective client. The ID must exactly match the ID listed in the digital
certificate. If you do not set this ID, libdsh uses the client host name as
authentication ID. dshSetAuthId is described in “dshSetAuthId: Set
authenticity” on page 178.
• Use dshSetExpTimeSecKey to set the expiry time period. If you do not set
this value, libdsh will use the default value, 3600 s (1 hour).

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 31
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

dshSetExpTimeSecKey is described in “dshSetExpTimeSecKey: Set

expiration time for SecKey” on page 182.

Once these settings are in place, libdsh automatically builds and uses the SecKey
whenever necessary; you need no longer care for this subject then.

2.3.3 Initializing and ending a libdsh session

The libdsh library is written in C++. Its core part is the dsh class.

2.3.3.1 Logging
Logging to file Before you initialize a libdsh session, you should decide whether error messages
should be written to the STDERR stream (default) or whether you want to redirect
STDERR to a log file. If you want to use a log file, specify the path and file name of the
log file via the dshSetLogFile function. Moreover, you should specify a maximum
size for the log file (dshSetLogMaxSize). As soon as the size of the log file exceeds the
maximum, libdsh renames the log file to <log_file>.sav and creates a new, empty
<log_file> for logging (if there is an older <log_file>.sav file, it will be removed).

Log channels With the dshSetLogLevel function, you can specify, which messages should be
logged at all. libdsh distinguishes three log channels, that can be activated by this
function:

• All general information messages are written to the INFO channel.

• Debug messages are written to the DEBUG channel.
• The individual function calls are logged on the ENTRY channel.

Important
As STDERR is redirected to the log file, all messages written to STDERR are
written to this file, even if they are generated by your application.

Notes

• Of course, you could redirect STDERR to a file yourself, without using

dshSetLogFile. But in this case, libdsh cannot monitor the file size.
• Apart from these three channels, you can activate or deactivate further
channels via the global environment variables LOG_FATAL, LOG_ERROR and
LOG_WARNING (see “Global environment variables” on page 228).
• Unlike other settings, log settings are initialized at the first dshSetLog*
function call, not at dshOpen (see also “Initialvaluesvia environment
variables ” on page 35 below).
• In case of multithreading applications, you can cause libdsh to enter the
related thread ID into the log – see
DSH_LOG_THREAD_ID on page 229DSH_LOG_THREAD_ID.

32 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.3. libdsh library

2.3.3.2 Initializing libdsh

dsh object After specifying the log settings, you create an object of the dsh class in your
application.
• For Archive Server version 9.7 and later, use dshOpen2().

char *primary_host = "<Name of your repository server>";

char *protocol = "http";
char *port = "8080";
char *path = "/archive";

void *dsh = dshOpen2(primary_host,protocol,atoi(port),path,NULL,

NULL);

Communication As part of the dsh object creation, a connection to the repository server is established
session and a communication session is set up (Because this is the main purpose of the dsh
object, the following refers to the session rather than to the abstract object).

Parameters The parameters used in the function call have the following meaning:

secondary_host
Hostname of a second server to be addressed by the library if the primary server
is not available. Specify NULL if no second server is available. This second server
can be a replication server, for example (see “Servers, clients, leading
application” on page 11).

http_port_adms, http_port_ds, port

HTTP input (“listening”) ports adjusted in the ADMS and DS server
configuration. As a rule, the port addresses specified above are used, but check
with your server configuration.

Note: If using the HTTPS protocol (see below), libdsh automatically

increases the values specified here. So always specify the HTTP (not
HTTPS) ports.

protocol
Either HTTP or HTTPS, depending on the protocol you want to use.

Note: This setting is relevant only if the configuration of Archive Server

permits the clients to choose the protocol. Otherwise this setting is ignored
and the protocol specified in the server configuration is used.

Note: Also see the reference descriptions of the functions in “dshOpen,

dshOpen2: Open connection to repository server” on page 170.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 33
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

2.3.3.3 Setting parameters

Global/session Various functions within libdsh require that you (or the user) specify certain
parameters parameters before these functions can be used. In particular, this affects the
following items:
• Accounting:
If you want the server to keep a log of which users and which applications are
accessing it (for example, for accounting), you must declare the user name and
application name in libdsh via the dshSetUser and dshSetApplication
functions. As an alternative you can specify the respective values in the dshOpen
function call when you establish a connection to the server.
• SecKey handling:
If you want to enable your application to read documents that are protected via
SecKeys you must specify a number of further settings. See “SecKey handling in
libdsh” on page 31 and “Access protection via SecKeys (signed URLs)”
on page 22 for further information.

No automatic storage

Internal settings, including modifications of the global variables listed in

“Global environment variables” on page 228, are not automatically stored by
libdsh. If you deviate from their default and want to keep changes after
ending a session end, you must provide a corresponding storage mechanism.

This means:
• You must trigger their storage before you call up the dshClose() or
dshExit function, respectively (see below).
• When you begin the next session, you must cause your application to
read the respective configuration file.

Some settings Note that some settings applied via a libdsh function are assigned to a specific
are session, for example, the application name, user name, refresh time or SecKey
session‑specific
...
expiration time. Such a session is opened by dshOpen and closed by dshClose()
(not by dshExit!), and during the session, it is referenced by the dsh class handle in
the function parameters. This assignment implies two consequences if you should
happen to open more than one session at a time:
• Local settings must be specified in each of these sessions.
• The settings may differ for different repository servers and then require an
individual storage mechanism for each session (server); the values must be
stored, before dshClose is called.

... others are Other settings apply to all sessions, as they are assigned to the superordinated
global. libdsh object. They are initiated at the first dshOpen call and are available until
dshExit is called. This applies to the following settings:

• The global variables as described in “Global environment variables” on page 228

34 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 2.3. libdsh library

• Settings which are modified via one of the following functions:

• dshSetAidRefreshInterval
• dshSetProxy
• dshSetCertificateFile
• dshSetCertificate
• dshSetPrivateKeyFile
• dshSetPrivateKey
• dshSetAuthId

Initial values via For most settings, you can specify an initial value via corresponding environment
environment variables (see “Global environment variables” on page 228). Depending on the
variables
scope of the settings, the point at which the initialization takes place, differs:
• Settings for logging are initialized when the first dshLog* function is called.
• Session-specific settings are initialized when the session is established via
dshOpen.
• All other settings are initialized at the first dshOpen call only.

2.3.3.4 Error handling

Details on an If a function fails due to an error, the function returns 0 or NULL (see also “Function
error parameters and return values” on page 36). Call the dshGetLastError or
dshGetLastErrno function to retrieve further details on the error which that has
occurred.

Notes
• An error handler can only recognize errors that were foreseeable by the
development team. Therefore an error may occur (i.e. a function call returns
the value 0 or NULL, respectively), but dshGetLastError and
dshGetLastErrno do not recognize the error and return 0/NULL, too (“No
error information available”). A few situations of this kind were detected
during testing the software and are described then in the respective function
sections (dshGetUser).
Note that some functions do not return a value, because no error conditions
are anticipated; this applies in particular to the dshSet* functions (see also
“Function parameters and return values” on page 36).
• dshGetLastError and dshGetLastErrno can only be used for functions
related to a certain session, as the error information itself is assigned to a
session. Therefore, these functions cannot provide information on errors that
have occurred when calling dshOpen, dshSetLogFile, dshSetLogLevel,
dshSetLogMaxSize.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 35
AR100500-PSA-EN-3
Chapter 2 Concepts and basics

2.3.3.5 Ending libdsh

If you no longer need the libdsh library, especially at the end of your application,
call dshClose() for each dsh object generated earlier. Finally call dshExit() to free
all memory and resources that the library has allocated before.

2.3.4 Function parameters and return values

libdsh functions may return data in one of two ways: via the function return value or
the function parameters.

if ( function(parameter1, parameter2,...) == <return value x> )

{
...
}

Return value The return value always serves as an error indicator. If the function returns the value
0 or NULL, the function has failed, and you can get further information on the error
by calling the dshGetLastError or dshGetLastErrno function.

If successful, some functions return the requested data via the return value, others
return it via one or several parameters. This differs from function to function.

Note: The following functions do not provide a return value at all: All dshSet*
functions (except dshDsSetAttribute), dshClose, dshExit, dshFree,
dshGetVersion, dshClearLastError.

Allocation As a rule, you need not allocate memory for data or strings to be returned via a
before func- function return value. If strings or data are returned via function parameters, some
tion call
functions require that you allocate sufficient memory before calling the function,
others do not. See the respective function descriptions in “libdsh function reference“
on page 37 for details, in this case.

Freeing If a function itself has allocated memory for its return value or for a value returned
allocated by the parameters, you must release that memory buffer using the dshFree function.
memory
Do not use the standard free function here, as this may cause problems due to the
ownership of the memory buffer.

Case-sensitive! Note that most functions are case-sensitive, especially when you specify document
or component names or attributes. In the search functions (dshDsSearch,
dshDsAttrSearch), you can specify whether the search should be case-sensitive or
not.

36 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
Chapter 3
libdsh function reference

This chapter provides a reference of all functions available in libdsh. These functions
are listed in alphabetical order.

Notes
• “Grouped function list” on page 28 provides another overview of the libdsh
functions, grouped by functionality.
• All function names in the libdsh client library start with “dsh”. Functions
with a name starting with “dshDs” directly access the Document Service on
Archive Server. Others are either internal functions of libdsh that do not
access the server at all (to set or retrieve configuration parameters, for
example), or they combine a call to the server with some internal
functionality.
• See “Function parameters and return values” on page 36 for common
information on how to deal with function parameters and return values.

Structure of the function descriptions

The functions are described in a formal way, according to the following pattern:

• Purpose describes the meaning of the function and maybe special items which
you may not otherwise expect.
• Function header tells you how to call the function and what type the parameters
are.
• Parameters then provides detailed information on the individual parameters (for
example, their meaning, and whether you must specify a value (input), or
whether the parameter returns a value (output), or both).
• Return values tells you which values can be returned by the function itself, in
addition to the values that may be returned by some parameters. Usually, this
value is 0 or NULL if an error has occurred (see below), or the requested result, if
the function has been completed successfully.
• Errors that may occur provides a list of all errors that can cause this function to
break down. This enables you to check only the potential errors after calling a
function, in order to keep the error handler smaller and more precise.
• SecKey access mode tells you which access mode is assigned to the function, if the
logical archive hosting the document is protected via SecKeys; see “Access
protection via SecKeys (signed URLs)” on page 22.
• Example provides an example of calling the function; it is sometimes embedded
in a larger piece of code.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 37
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• Related functions lists those functions that are more or less directly related to the
described function. However, such a list depends on the context, in which a
function is used; therefore it may not be complete at times. In such a case, consult
“Grouped function list” on page 28 which lists the functions grouped by their
functionality.

38 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.1. dshClearLastError: Clear last error message

3.1 dshClearLastError: Clear last error message

Purpose
Clears the internal error message buffer of the session referenced by the dsh
parameter. A subsequent call of the dshGetLastErrno() or
dshGetLastError() function will always return 0 / NULL.

Function Header
void dshClearLastError(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
No return values

Example

int ret = dshClearLastError(dsh);

Related Functions
• “dshGetLastErrno: Get error number” on page 148

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 39
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.2 dshClose: Close connection to repository server

Purpose
Closes a connection to a repository server (previously opened via dshOpen()),
thereby ending the session referenced by the dsh parameter.

Notes
• Call dshClose() at the end of your program or when you no longer
need the connection to Archive Server. Only a dshExit must follow in
order to free all memory and resources allocated by the library.
• If you opened several connections to different repository servers, call
dshClose for each of them, before you call dshExit.
• Local settings get lost!
If you want to reuse local settings that you applied during this session,
you must store them before calling dshClose (see “Setting parameters”
on page 34 for details).

Function Header
void dshClose(void *dsh);

Parameters
• dsh (input)
class handle, obtained via a preceding dshOpen() call.

Return values
No return values

Example
See the examples in “Archive Server API in practice“ on page 193

Related Functions
• “dshOpen, dshOpen2: Open connection to repository server” on page 170
• “dshExit: Exit the libdsh library” on page 127

See also “Grouped function list” on page 28.

40 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.3. dshCompInfo: Get information on (unknown) components

3.3 dshCompInfo: Get information on (unknown)

components
Purpose
Interprets the so-called info string of a document or component; the resulting
status information on this document or component is returned via the various
output parameters of the function header.
In contrast to other functions, dshCompInfo does not directly refer to a
document or component. Instead it reads the info string which you must have
obtained beforehand via the dshDsInfo() function, either for an entire
document or for a single component. In a sequential listing, the info string
contains several types of information, first on the document in general, and then
– one after another – on each component it contains.
The function starts at the position handed over in the info pointer, which you
usually let point to the beginning of the info string when calling the function for
the first time. It processes the contents of the info string until it encounters the
end of a component info part; then it stops and returns the information it has
found. It also returns the current reading position via the info pointer. So if you
repeatedly call this function, it steps through the info string and returns the
component information for each component contained in the document (see
second example below).

Notes
• In particular, dshDsInfo() and dshCompInfo serve to obtain the names
of components in a document the structure of which you do not know. If
you want to retrieve information on a component the name of which you
do know, the dshGetCompStatus function is faster and more efficient
than dshCompInfo.
• To retrieve information on a document (in particular, the number of
components), use the dshGetDocInfo function.
• If you no longer need the info string, call dshFree() to free the
respective memory buffer (but be careful not to use the info pointer
here).
• dshCompInfo replaces the dshCompInfoStatus function that therefore is
deprectaed now. Note that order and naming of the parameters in
dshCompInfo is different, and that the parameters need no memory
allocation any longer.

Function Header
int dshCompInfo(
void *dsh,
char **info,
int utc_flag,
char **name,
char **status,

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 41
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

char **type,
char **c_date,
char **c_time,
char **m_date,
char **m_time,
char **length,
int *version,
char **vol_name,
char **sig_object);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• info (in/out)
Info string obtained via a preceding dshDsInfo() call. See Purpose above for
details.
• utc_flag (input)
Specify 0 to get date and time in localtime.
Specify 1 to get date and time in UTC (Greenwich time).
• name (output)
Component name
• status (output)
Document/component status, which may be one of the following values:
online, offline, unknown, error. error means that no further components
are listed in the info string.
• type (output)
File type of the component (see “Document/component formats (renditions,
file types)” on page 19)
• c_date (output)
Date when the component has (initially) been stored in the archive; format:
YYYYMMDD
• c_time (output)
Time when the component has (initially) been stored in the archive; format:
HHMMSS
• m_date (output)
Date of the most recent modification of the document that contains the
component; format: YYYYMMDD
• m_time (output)
Time of the most recent modification of the document that contains the
component; format: HHMMSS
• length (output)
Size of component in byte (-1 if size is unknown)
• version (output)

42 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.3. dshCompInfo: Get information on (unknown) components

Version of the component[1]

• vol_name (output)
Name of the volume assigned to the storage medium. This is particularly
helpful for logging purposes or if the medium is offline.
• sig_object (output)
Signature type. This parameter returns TSTMP if the component has a
signature and is empty if not.

Return values
1: Function completed successfully.
2: No more components are listed in the info string.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires read access permission for the document on the repository server.
Example
• Get status information of first component of document d1 in archive A1:
char *name, *status, *type, *c_date, *c_time, *m_date,
*m_time, *length, *vol_name, *sig_object;
int *version;
char *info = dshDsInfo(dsh,"A1","d1","");
char *save_info = info;
int ret = dshCompInfo(dsh,&info,0, &name, &status,
&type, &c_date, &c_time, &m_date,
&m_time, &length, &version,
&vol_name, &sig_object);
dshFree(save_info);
...

Note that dshFree() needs also be called for the function parameters after
their evaluation.
• Get status information of all components of document d1 in archive A1:
char *name, *status, *type, *c_date, *c_time, *m_date,
*m_time, *length, *vol_name, *sig_object;

[1] If a component is modified using DsUpdate*, a version counter for this component is increased. This
version counter is returned here.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 43
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

int version;
char *info = dshDsInfo(dsh,"A1","d1","");
char *save_info = info;
int ret;
while ( (ret=dshCompInfo(dsh,&info,0, &name, &status,
&type, &c_date, &c_time, &m_date,
&m_time, &length, &version,
&vol_name, &sig_object) == 1 ) {
printf("component=%s, length=%s\n",name,length);
dshFree(name);
dshFree(status);
dshFree(type);
dshFree(c_date);
dshFree(c_time);
dshFree(m_date);
dshFree(m_time);
dshFree(length);
dshFree(vol_name);
dshFree(sig_object);
}
dshFree(save_info);
if ( ret == 0 ) {
printf("Error in getting component info\n");
}

Note that the info string stored in save_info contains the information on all
components in both examples. The only difference is that the first example
evaluates only the first information set within the string, whereas the while
loop in the second example iteratively steps through the whole info string
and returns the information on all components.

See also “dsh_get example: Get all archived files of a document/retrieve

component information” on page 202

Related Functions
• “dshDsInfo: Get info string for document/Component” on page 86
• “dshGetCompStatus: Get information on component” on page 136
• “dshCompInfoStatus [DEPRECATED]:
Get information on (unknown) components” on page 45
• “dshDsMigrate, dshDsMigrate2: Migrate document to another logical
archive or pool” on page 89

See also “Grouped function list” on page 28.

44 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.4. dshCompInfoStatus [DEPRECATED]: Get information on (unknown) components

3.4 dshCompInfoStatus [DEPRECATED]:

Get information on (unknown) components
Purpose
Deprecated function to retreive information on a component, replaced by
dshCompInfo (see “dshCompInfo: Get information on (unknown) components”
on page 41 for details). If you switch to dshCompInfo, take care of the differences
in the function headers.

Notes
• Note that you must allocate sufficient memory for most parameters
before you call the function.
• In particular, dshDsInfo() and dshCompInfoStatus serve to obtain the
names of components in a document whose structure you do not know.
If you want to retrieve information on a component whose name you do
know, the dshGetCompStatus function is faster and more efficient than
dshCompInfoStatus.
• To retrieve information on a document (in particular, the number of
components), use the dshGetDocInfo function.
• If you no longer need the info string, call dshFree() to free the respective
memory buffer (but be careful not to use the info pointer here).

Function Header
int dshCompInfoStatus(
void *dsh,
char **info,
char *compid,
char *status,
char *type,
char *ar_date,
char *ar_time,
char *size,
int utc_flag
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• info (in/out)
Info string obtained via a preceding dshDsInfo() call. See Purpose for
details.
• compid (output)
Component name
Must be allocated by the calling application with a size >= 100 bytes.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 45
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• status (output)
Document/component status, which may be one of the following values:
ONLINE, OFFLINE, UNKNOWN, ERROR. ERROR means that no further components
are listed in the info string.
Must be allocated by the calling application with a size >= 21 bytes.
• type (output)
File type of the component (see “Document/component formats (renditions,
file types)” on page 19).
Must be allocated by the calling application with a size >= 41 bytes.
• ar_date (output)
Modification date, i.e. date when the document containing the component
has been modified most recently; format: YYYYMMDD.
Must be allocated by the calling application with a size = 9 bytes.
• ar_time (output)
Modification time, i.e. time when the document containing the component
has been modified most recently; format: HHMMSS.
Must be allocated by calling application with a size = 7 bytes.
• size (output)
Size of component in byte (-1 if unknown)
Must be allocated by calling application with a size > =14 bytes.
• utc_flag (input)
Specify 0 to get date and time in localtime.
Specify 1 to get date and time in UTC (Greenwich time).

Return values
1: Function completed successfully.
2: No more components are listed in the info string. The status parameter is set
to ERROR (however, this is not a libdsh error and thus cannot be investigated via
dshGetLastErrno or dshGetLastError).
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires read access permission for the document on the repository server.
Example
• Get status information of first component of document d1 in archive A1:
char compid[100], status[21], type[41], ar_date[9],
ar_time[7], size[14];

46 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.4. dshCompInfoStatus [DEPRECATED]: Get information on (unknown) components

char *info = dshDsInfo(dsh,"A1","d1","");

char *save_info = info;
int ret = dshCompInfoStatus(dsh,&info,compid,status,type,
ar_date,ar_time,size,0);
dshFree(save_info);
• Get status information of all components of document d1 in archive A1:

char compid[100], status[21], type[41], ar_date[9],

ar_time[7], size[14];
char *info = dshDsInfo(dsh,"A1","d1","");
char *save_info = info;
int ret;
while ( (ret=dshCompInfoStatus(dsh,&info,compid,status,
type,ar_date,ar_time,size,0)) == 1 ) {
printf("component=%s, size=%s\n",compid,size);
}
dshFree(save_info);
if ( ret == 0 ) {
printf("Error in getting component info\n");
}

Note that the info string stored in save_info contains the information on all
components in both examples. The only difference is that the first example
evaluates only the first information set within the string, whereas the while
loop in the second example iteratively steps through the whole info string
and returns the information on all components.

See also “dsh_get example: Get all archived files of a document/retrieve

component information” on page 202

Related Functions
• “dshDsInfo: Get info string for document/Component” on page 86
• “dshGetCompStatus: Get information on component” on page 136
• “dshCompInfo: Get information on (unknown) components” on page 41

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 47
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.5 dshDsAdmInfo2: Get information about archives

Purpose
Returns information about logical archives and the hosting Archive Server
(hostnames). The return string consists of lines, separated by CR+LF, each of
which corresponds to one logical archive. Each line consists of the following
fields in the given order, separeated by a space character:[2]

Archive ID
Name of the logical archive

Host name
Name of the server to be used for addressing the logical archive
Only in an archive-centric system, this parameter specifies Archive Server
where the logical archive actually is located; otherwise, this parameter
contains Archive Server that is the communication partner for the client.

Server type
either “O”=Orignal or “R”=Replicate

SSL mode

• ssl_off
SSL is not allowed.
• ssl_on
SSL is mandatory.
• ssl_allow
SSL is allowed but not mandatory.

Protection level (access level)

The protection level assigned to the logical archive; as several settings can be
combined, they are coded as a bit string in an integer value with the
following assignments:

PROT_READ = 0x001
PROT_CREATE = 0x002
PROT_UPDATE = 0x004
PROT_DELETE = 0x008

The protection level corresponds to the SecKey access mode on page 22

described in “Access protection via SecKeys (signed URLs)” on page 22
If the host is Archive Server, Version 9.7 or higher, the line contains following
additional fields:

HTTP port
The HTTP port as a number
[2] This applies only if pretty_print_flag==0; do not use pretty_print_flag==1.

48 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.5. dshDsAdmInfo2: Get information about archives

HTTPS port
The HTTPS port as a number
Archive Path
Part of the URL specifying the addressed server, including the leading slash.

Note: See also “dshOpen2” on page 172.

Original host name

A string representing Archive Server actually hosting the logical archive.

Note: Use this string just to verify whether two logical archives are
located on the same Archive Server; do not use it as an identifier for
the respective Archive Server, as its generation can be arbitrary and the
value can change between two software versions.
This parameter is intended primarily for the use within migration
scenarios using the dshDsMigrate* functions.

Storage tiers
List of all storage tiers, surrounded by curly brackets and separated by space
characters.

Notes
• Call dshFree() to free the memory buffer allocated for the function
return value.

Function Header
char *dshDsAdmInfo(
void *dsh,
int now_flag,
int pretty_print_flag
);

Parameters
• dsh (input)
Class handle, obtained by a preceding dshOpen() call.
• now_flag (input)
The list of available Archive Servers is loaded from the ADMS periodically
and stored in a local cache; now_flag specifies where to read the list from:
• Specify 0 to read the data from the cache (prefered value in nearly every
case).
• Specify 1 to obtain the most recent information directly from the ADMS.
This also updates the internal cache and resets the counter that triggers
the next automatic update (AidRefreshTime).
• pretty_print_flag (input)

• Specify 0 for getting the original message string assembled by the ADMS.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 49
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• Specify 1 for getting a “prettily printed” message string (see Purpose

above!).

If you parse the result of this call in an automated way, always specify 0
here.

Return values
Information string on success (see Purpose above).
NULL on error.

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_406 (11009):
HTTP error (not acceptable [406]): Certificate cannot be recognized
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_412 (11011):
HTTP error (precondition failed [412])
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.
Examples for returned strings:
• String returned from an Archive Server Version lower than 9.7:

CSAID misha O 11 ssl_off

D6 misha O 15 ssl_on
DX misha O 0 ssl_allow
• String returned from an Archive Server Version 9.7 or higher

CSAID misha O 11 ssl_off 8080 8090 /archive misha { slSlow

slFast }

50 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.5. dshDsAdmInfo2: Get information about archives

D6 misha O 15 ssl_on 8080 8090 /archive misha { slSlow slFast }

DX misha O 0 ssl_allow 8080 8090 /archive misha { slSlow
slFast }

See also “dsh_info example: Retrieving information about logical archives”

on page 222

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 51
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.6 dshCsCache, dshCsCachePart: Cache a

component or a part of a component on Archive
Cache Server
Purpose
Stores a document component (dshCsCache) or a part of a document component
(dshCsCachePart) on the Archive Cache Server. Note that the content is not
forwarded to a client.

Function Header
char *dshCsCache(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);
char *dshCsCachePart(
void *dsh,
const char *aid,
const char *docid,
const char *compid
int64_t char from_offset,
int64_t char to_offset,
const char *permanent
);

Parameters

• dsh (input)
Class handle, obtained by a preceding dshOpen() call.
• aid (input)
Name of the logical archive where the component to be cached resides
• docid (inputt)
ID of the document containing the component to be cached
• compid (input)
Component name of the componentn to be cached
If an empty string is specified, the component names “data” is taken.
• from_offset (input, dshCsCachePart only)
Byte offset of the beginning of the part to be cached (0 = start of component)
• to_offset (input, dshCsCachePart only)
Byte offset of the end of the part to be cached (-1 = part ends at the end of the
component)
• permanent (input, dshCsCachePart only)
optional flag for future use

52 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.6. dshCsCache, dshCsCachePart: Cache a component or a part of a component on
Archive Cache Server

Return values
1: Function completed successfully.
2: Error: No cache server available.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_UNKNOWN_ARCHIVE
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the repository server.

Examples
• Cache component c1 of document d1 of archive A1 on the Archive Cache
Server:

int ret = dshCsCache(dsh,"A1","d1","c1");

or

int ret = dshCsCachePart(dsh,"A1","d1","c1",0,-1,"");

• Cache the first 10 million bytes of component c1 of document d1 of archive
A1 on the Archive Cache Server:

int ret = dshCsCachePart(dsh, "A1", "d1", "c1",

(int64_t)0,(int64_t)10000000,"");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 53
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.7 dshCsFlush: Remove a component or an entire

document from Archive Cache Server
Purpose
Removes a document component or the entire document from the Archive
Cache Server to definitely ensure that the latest version of a document is
forwarded to the clients. The Document Service (DS) is not involved at this call.
Function Header
char *dshCsFlush(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);

Parameters
• dsh (input)
Class handle, obtained by a preceding dshOpen() call.
• aid (input)
Name of the logical archive (on Archive Server) where the cached
component resides
• docid (inputt)
ID of the document containing the cached component
• compid (input)
Component name of the componentn to be cached
If an empty string or NULL is specified, the entire document is removed from
the Cache Server.

Return values
1: Function completed successfully.
2: Error: No cache server available.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_UNKNOWN_ARCHIVE
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):

54 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.7. dshCsFlush: Remove a component or an entire document from Archive Cache Server

HTTP error (not found [404]): Document/component/archive not found

• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires delete access permission for the document on the repository server.

Examples
• Remove component c1 of document d1 of archive A1 from the Archive Cache
Server:

int ret = dshCsFlush(dsh,"A1","d1","c1");

• Remove the entire document d1 of archive A1 from the Archive Cache Server:

int ret = dshCsFlush(dsh,"A1","d1","");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 55
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.8 dshDsAppendData, dshDsAppendFile: Append

to a component
Purpose
Appends data read from a memory buffer or from a file to a component in the
archive. The component is addressed via the aid, docid and compid parameters.

Important
Do not modify composed documents (form overlay, notes,
annotations)
libdsh does not support composed documents, for example, form
overlays, notes or annotations. Therefore you should not modify or
replace components in a document using form overlays, notes or
annotations, as this may impact the structural relationship between the
individual components, and may destroy the document (see also
“Document model” on page 14).

Function Header
int dshDsAppendData(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
char *data,
long size
);
int dshDsAppendFile(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *path
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• data (input)
Memory buffer with data for appending

56 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.8. dshDsAppendData, dshDsAppendFile: Append to a component

• size (input)
Number of bytes of the data memory buffer to be appended to the compid
component (may be smaller than the real size of the buffer)
• path (input)
Local filename that should be appended to component compid

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_CREATE_CHECKSUM (11205):
Error in creating checksum
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires change access permission for the document on the server.
Example
Append the contents of a file x.txt to the component c1 of a document d1,
which is located in the A1 archive:

int ret = dshDsAppendFile(dsh,"A1","d1","c1","x.txt");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 57
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See also “dsh_append example: Append data to an archived file” on page 206
Related Functions
• “dshDsCreate*, dshDsCreateFile*: Create document/Component”
on page 64
• “dshDsLock: Lock document” on page 92

See also “Grouped function list” on page 28.

58 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.9. dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list

3.9 dshDsAttrSearch, dshDsAttrSearch2: Search

in SAP print list
Purpose
Searches for a pattern in the attributes of an SAP print list.
As SAP print lists often are very large files, they get an additional mapping table
listing all of their structural elements with their individual offsets and lengths.
This mapping table is the so-called index file or description file and allows to
quickly access a certain structure element within the print list.
Apart from the pure mapping index, the description file contains certain key
elements (for example, customer names), the attributes. The values of these
attributes are stored in so-called DAIN lines; each DAIN line represents a complete
set of attributes for one print list item (data set).

Figure 3-1: Each DAIN line represents a complete attribute set; within this
set, each attribute can be uniquely addressed by its local offset and its
string length.

Within each DAIN line, a certain attribute can be addressed by its offset, starting
at the beginning of the line, and by its length. The structure of the DAIN lines is
specified in a preceding set of DKEY lines; it is fixed for all DAIN lines succeeding
the DKEY line set (see Figure 3-1). Each DKEY line represents one attribute in the
DAIN lines, specifying the attribute name, its offset in the DAIN line and its
length.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 59
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

In Archive Server, both the print list itself and its description file are stored as
two components of the same document: The full print list is stored in the data
component, and the description file is stored in the descr component.

Notes
• For more information on print lists and their description files, see the
ArchiveLink 4.5 documentation by SAP (reference [1] in “Further
information sources” on page 225)
• Do not confuse the printlist attributes described above and the document
attributes of archive documents as described in “Document model”
on page 14.
• The only difference between two functions is the type assignment of the
parameters from_offset and to_offset.

Search pattern
The dshDsAttrSearch function exclusively searches in the attribute values (the
DAIN lines) of the description file of a print list. The search pattern handed over
in the pattern parameter must be structured as follows:
<offset>+<length>+<stringpattern>
If you want to search in all attributes of the description file, specify <offset> = 0
and the full length of the DAIN lines (which can be excerpted from the DKEY line
immediately preceding the DAIN lines). By specifying an offset > 0 and an
explicit length, you may restrict the search to a certain attribute or several
adjacent attributes. If you want to search in several attributes, that are not
neighbors, specify several patterns and concatenate them separated by a “#” (see
also Example below).
Search result
The search result consists of the number of hits and the offset and length for
each hit. The values are separated by semicolons, and the string ends with a
semicolon:
<number of hits(= n)>; <offset of hit 1>; <length of hit 1>; ...; <offset of
hit n>; <length of hit n>;

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned attribute string.

Function Header
char *dshDsAttrSearch(
void *dsh,
const char *aid,
const char *docid,
const char *pattern,
long from_offset,
long to_offset,
int num_results,
int case_sensitive
);

60 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.9. dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list

char *dshDsAttrSearch2(
void *dsh,
const char *aid,
const char *docid,
const char *pattern,
int64_t from_offset,
int64_t to_offset,
int num_results,
int case_sensitive
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• pattern (input)
Search pattern
• from_offset (input)
Offset in print list (data component) to start search

Note: Do not confuse from_offset and to_offset with the offset

values specified in pattern. from_offset and to_offset define the
upper and lower borders of the “search window” on the print list,
whereas the <offset> and <length> values in the pattern define the
left and right borders.
• to_offset (input)
Offset in print list (data component), where to stop search (-1 = to end)
• num_results (input)
Maximum number of search results; as soon as this number is reached, the
function stops searching and returns hits it has found.
• case_sensitive (input)
Specify 0 for non-case-insensitive search (a=A)
Specify 1 for case-sensitive search (a!=A)

Return values
Search result on success, see Purpose above.
“0;:” No hits were found.
NULL: Error; use the dshGetLastErrno function to obtain further error
information.
Errors that may occur
• DSH_ERR_HTTP_EMPTY_RESULT (11002):

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 61
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Wrong (empty) result from archive server

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires read access permission for the document on the server
Example
• Example for a search pattern:
By specifying pattern="15+25+GmbH" you search for “GmbH” in the
attribute which starts at offset 15 of each DAIN line and is 25 characters long.
• Example for a return string:
2;73;138;211;120; means that two hits were found; the first hit starts at
offset 73 with length 138, and the second hit starts at offset 211 with length
120. If no matching attribute was found, the function returns 0;.
• Example for a function call:
The term “GmbH” is searched for in a component in the attribute with offset
15 and length 25 in document d1 in archive A1. The search must be case-
sensitive:

char *retstring = dshDsAttrSearch(dsh,"A1","d1",

"15+25+GmbH",0,-1,1,1);

62 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.9. dshDsAttrSearch, dshDsAttrSearch2: Search in SAP print list

...
dshFree(retstring);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 63
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.10 dshDsCreate*, dshDsCreateFile*: Create

document/Component
Purpose
Creates a new component for a document already existing in the archive, or
creates a new document with a new component, respectively. To add a
component to an existing document, specify the Document ID of the respective
document in the docid parameter. Otherwise leave the docid parameter empty
(""); a new document with a new Document ID will be generated then in the
archive and the new Document ID will be returned via the docid parameter.
The contents of the new component can be read from a local file
(dshDsCreateFile*) or from a memory buffer (dshDsCreate*).
Compared to dshDsCreate and dshDsCreateFile, dshDsCreate2 and
dshDsCreateFile2 provide additional parameters to control retention
management or delayed archiving. dshDsCreate3 and dshDsCreateFile3
provide an additional parameter to specify a storage tier.

Notes
• You may also specify a Document ID that does not yet exist on the
server. Then a document with this ID is generated, and the component is
stored in this document. This allows you to define Document IDs
according to your own scheme; on the other hand, it is your
responsibility then to ensure that all Document IDs are unique in the
entire archive (see also “Document ID” on page 14).
• If you need the Document ID of a document even before you store it in
the archive, use the dshDsReserveDocId function to reserve a Document
ID.
• Note that the first component usually is interpreted as the main
component (see “Main component” on page 15). Therefore, always store
the main component at first.

Function Header
int dshDsCreate(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
);
int dshDsCreate2(
void *dsh,
const char *aid,

64 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.10. dshDsCreate*, dshDsCreateFile*: Create document/Component

char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
const char *timestamp,
const char *retention_period,
const char *store_param
);
int dshDsCreate3(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
const char *timestamp,
const char *retention_period,
const char *store_param
const char *storage_tier
);
int dshDsCreate4(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type,
const char *timestamp,
const char *retention_period,
const char *store_param,
const char *storage_tier,
const char *token);
int dshDsCreateFile(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 65
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

int dshDsCreateFile2(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
const char *timestamp,
const char *retention_period,
const char *store_param
);
int dshDsCreateFile3(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
const char *timestamp,
const char *retention_period,
const char *store_param
const char *storage_tier
);
int dshDsCreateFile6(
void *dsh,
const char *aid,
char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
const char *timestamp,
const char *retention_period,
const char *store_param
const char *storage_tier
const char *rms,
const char *token,
char **comp_info);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (in/out)

66 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.10. dshDsCreate*, dshDsCreateFile*: Create document/Component

Document ID (see Purpose above for details).

The minimum size of this parameter must be 40 bytes.
• compid (input)
Component name
• type (input)
File type of the component (see “Document/component formats (renditions,
file types)” on page 19).
• data (input)
Data of component compid
• size (input)
Size of the data buffer (i.e. size of the compid component)
• path (input)
Local filename of component compid
• app_type (input)
Application type for pool selection (see “Document pools, storage tiers”
on page 12). Specify the empty string ("") for the default pool.
• timestamp (input; dshDsCreateFile2/3/6, dshDsCreate2/3/4 only)
Optional timestamp for the component (format: DER–>BASE64) – see
“Timestamp functionality” on page 23.
This parameter is ignored, if a NULL pointer or an empty string is handed
over.
• retention_period (input; dshDsCreateFile2/3/6, dshDsCreate2/3/4
only)
Retention period of the document; see “Retention period” on page 24 for
details.
This parameter is ignored, if a NULL pointer or an empty string is handed
over, and the default retention period of the specified logical archive is
assigned.
• store_param (input; dshDsCreateFile2/3/6, dshDsCreate2/3/4 only)
Option to delay the storage in the archive:
• If you specify delayed, the component is stored in the disk buffer only,
but will not be stored in the final archive storage until the
dshDsSetDocumentFlag function is called with
store_param=immediate.
• For common archiving, specify the empty string, which is the default.
• storage_tier (input; dshDsCreateFile3/6, dshDsCreate3/4 only)
Option to assign the content to a storage tier (which results in storing the
content in a specific pool assigned to this storage tier). If the empty string
("") is specified, the default pool is used.
Do not specify a value other than NULL or empty string ("") for both
storage_tier and app_type in the same function call; if both are specified
and lead to different pools to be used, the call will fail.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 67
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See “Document pools, storage tiers” on page 12 for details.

• rms (input; dshDsCreateFile6 only)
Access token for Rights Management Services (RMS). For internal use only –
set to NULL.
• token (input; dshDsCreateFile6, dshDsCreate4 only)
A string that identifies a token given by the caller. DS keeps this token in
memory for a short period of time. If within this period a delete call arrives
given the same token, DS deletes (docid,compid) without checking any
retention period.
This allows for a short period of time to delete any document even if
retention is not yet expired. Used for cleaning up created documents in a
transactional manner.
Best be used in combination with store_param=deferred to hinder copying
of data to destination media.
Parameter is ignored if NULL pointer or "".
• comp_info (output; dshDsCreateFile6 only)
Return info string of archived component. This string should be parsed with
dshCompInfo. It will not contain all component information but in any case it
will contain the length of the archived component. This variable must be
freed by the calling function. In case you need returning information about
the newly created component, set this input variable to a value other than
NULL.

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_CREATE_CHECKSUM (11205):
Error in creating checksum
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_403 (11007):
HTTP error (forbidden [403]): Document/component already exists
• DSH_ERR_HTTP_500 (11012):

68 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.10. dshDsCreate*, dshDsCreateFile*: Create document/Component

HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires create access permission for the document on the server.

Example
Append the file x.txt as a new component c1 of type application/x-otf to
the d1 document in archive A1:

int ret = dshDsCreateFile("A1","d1","c1",

"application/x-otf","x.txt","");

See also “dsh_put example: Archiving files in a single document” on page 199

Related Functions
• “dshDsAppendData, dshDsAppendFile: Append to a component”
on page 56
• “dshDsLock: Lock document” on page 92
• “dshDsUpdate*, dshDsUpdateFile*: Update component” on page 112

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 69
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.11 dshDsDelAttribute: Delete attribute

Purpose
Deletes an attribute of a document or component. For deleting a document
attribute, specify an empty compid parameter ("").

Notes
• In an OpenText TCP system (context server), the access to an attribute
must be enabled via the Server Configuration.
• Do not delete the type attribute, as it is used internally by the server. Of
course, you also should not delete variables defined by other
applications, unless you are sure that they are no longer needed.

Function Header
int dshDsDelAttribute(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *attribute
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name; specify "" to delete a document attribute instead of a
component attribute.
• attribute (input)
Attribute name

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file

70 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.11. dshDsDelAttribute: Delete attribute

• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_DELA (11016):
HTTP error (not found [404]): Either the document, the component or the
attribute does not exist
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires delete access permission for the document on the server.

Example
Delete the author attribute of component c1 in document d1, located in the A1
archive:

int ret = dshDsDelAttribute(dsh,"A1","d1","c1","author");

See also “dsh_attribute example: dealing with document attributes”

on page 209

Related Functions
• “dshDsSetAttribute: Set attribute” on page 105

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 71
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.12 dshDsDelete, dshDsDelete2: Delete document/

Component
Purpose
Deletes a component or the entire document in the archive. The entire document
will be deleted if compid is set to "".

Important
Use this function with care: Once you apply dshDsDelete to a document
or component, it will be permanently deleted! There is no undo option
for dshDsDelete (or for any libdsh function).

If the document has been stored in an optical medium, it cannot be deleted, of

course. But any reference to it in the database is removed, and the document
cannot be found any longer. There is only a chance to restore a document after
dshDsDelete, if a database backup has been performed a short time before the
deletion.
As a rule, dshDsDelete is required only for test purposes or for optimization,
for example, by deleting documents, that no longer need to be archived, because
their legal retention period is over. If you intend to use the function in normal
operation, do not forget to inform your users accordingly: deletion of a
document is a quite unexpected feature in the context of an archive.
Function Header
int dshDsDelete(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);
int dshDsDelete2(
void *dsh,
const char *aid,
const char *docid,
const char *compid
const char *token)
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)

72 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.12. dshDsDelete, dshDsDelete2: Delete document/Component

Component name
• token (input)
Allows for a short period of time to delete any document even if retention is
not yet expired. Used for cleaning up created documents in a transactional
manner. See dshDsCreate calls for more information on parameter token.
Parameter is ignored if NULL pointer or "".

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires delete access permission for the document on the server.

Example
Delete component c1 of document d1 in archive A1:

int ret = dshDsDelete(dsh,"A1","d1","c1");

Related Functions

• “dshDsLock: Lock document” on page 92

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 73
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See also “Grouped function list” on page 28.

74 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.13. dshDsGet*, dshGetFile*, dshDsGetPart*: Get component

3.13 dshDsGet*, dshGetFile*, dshDsGetPart*: Get

component
Purpose
Reads a component of a document stored in the archive or a part of a
component:
• Call dshDsGetPart(), dshDsGetPart2(), or dshDsGetPart3() if you want
to get len bytes of a component compid, starting at position offset. The
read data is returned via the data parameter. – dshDsGetPart() and
dshDsGetPart2() just differ in the data type assigned to the offset
parameter.
• Call dshDsGet() or dshDsGet2() if you want to read a complete component
compid and want to store it in a memory buffer (returned via the data
parameter).
• Call dshDsGetFile(), dshDsGetFile2(), or dshDsGetFile3() if you want
to read a complete component compid and want to store it in a local file
(specified via the path parameter).

If compid is set to "", the data component is read (data is the default name for
components in Archive Server)

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned data element (not in dsh).

Function Header
int dshDsGet(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
char **data,
int *size
);
int dshDsGet2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
char **data,
int *size
const char *rms,
const char *origid
);
int dshDsGetFile(
void *dsh,
const char *aid,

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 75
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

const char *docid,

const char *compid,
const char *path
);
int dshDsGetFile2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *path,
const char *rms
);
int dshDsGetFile3(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *path,
const char *rms,
const char *origid
);
int dshDsGetPart(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
size_t offset,
int length,
char **data,
int *size
);
int dshDsGetPart2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
int64_t offset,
int length,
char **data,
int *size
);
int dshDsGetPart3(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
int64_t offset,

76 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.13. dshDsGet*, dshGetFile*, dshDsGetPart*: Get component

int length,
char **data,
int *size
const char *rms,
const char *origid
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• offset (input)
Offset in compid where reading should start (The byte with this offset is the
first byte to be returned)
• length (input)
Number of bytes of component compid to be read
• data (output)
Data (contents) of the requested component
• size (output)
Size of data
• path (input)
Path and name of the local destination file where the contents of the
component compid shall be stored.
• rms (input; dshDsGet2, dshDsGetPart3, dshDsGetFile2, dshDsGetFile3
only)
Access token for Rights Management Services (RMS). For internal use only –
set to NULL.
• origid (input; dshDsGet2, dshDsGetPart3, dshDsGetFile3 only)
Originator of request. Set to "" or NULL if not used.

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 77
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Get component c1 of document d1 in archive A1 and store its contents in the
local file x.txt:

int ret = dsh(dsh,"A1","d1","c1","x.txt");

See also “dsh_get example: Get all archived files of a document/retrieve

component information” on page 202,
“dsh_search example: Searching and getting the found piece of data”
on page 214

Related Functions
• “dshDsCreate*, dshDsCreateFile*: Create document/Component”
on page 64

See also “Grouped function list” on page 28.

78 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.14. dshDsGetATS: Get evidence record of a component

3.14 dshDsGetATS: Get evidence record of a

component
Purpose
Returns the evidence record that can be used to proof the integrity and
authenticity of a document component that has been signed according to the
ArchiSig concept.
Note that this call is required only if you want to use external tools for the
verification, for example, to prove the integrity for a third party. Inside Archive
Server system, you use dshDsVerifySig() to verify the document (which
implicitly processes the evidence record then).
For details on using the ArchiSig concept on Archive Server, see Section 14.4
“Timestamps” in OpenText Archive Server - Administration Guide (AR-ACN).

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned evidence record.

Function Header
char *dshDsGetAttribute(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *hash_alg
const char *vol_name
const char **data
const char *size
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• hash_alg (input)
Hash algorithm. If an empty string or NULL is specified, the default SHA1 is
used.
• vol_name (input, optional)
Name of the volume where the document is stored. This is helpful to find the
document faster in case the document is stored on an offline medium and the
leading application has stored the volume information.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 79
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

If an empty string or NULL is specified, the default volume is used.

• data (output)
Returned evidence record
• size (output)
Size of the returned evidence record

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Get the evidence record of component c1 of document d1 of archive A1:

char *data;
int size;
int ret = dshDsGetATS(dsh,"A1","d1","c1","","", &data,&size);
…
dshFree(data);

Related Functions
• “dshDsVerifySig: Proof timestamp of a component” on page 124

See also Section 14.4 “Timestamps” in OpenText Archive Server - Administration

Guide (AR-ACN).

80 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.15. dshDsGetAttribute: Get attributes

3.15 dshDsGetAttribute: Get attributes

Purpose
Returns one or all attributes of a document or component (attribute name and
attribute value).
To get the value of a certain attribute, specify the attribute name in attribute; if
attribute is empty (""), all attributes are returned.
If compid is empty (""), the attribute(s) of the document docid are returned;
otherwise the attribute(s) of the compid component in document docid are
returned.
The structure of the return string is a simple sequence of assignment pairs
(<attribute name>="<attribute value>"), separated by semicolons.

Notes
• If you operate in an OpenText TCP system, but want to keep the
attribute naming as used in archive-centric systems, a name mapping
must be defined via the Server Configuration.
• Call dshFree() to free the memory buffer that has been allocated for the
returned attribute string.

Function Header
char *dshDsGetAttribute(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *attribute
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name. Specify "" if you want to retrieve the attribute(s) of a
document.
• attribute (input)
Attribute name (case sensitive!). Specify "" if you want to retrieve all
attributes of a component or document

Return values
Requested attribute(s) on success, see Purpose above.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 81
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

NULL: Specified attribute was not found or another error occurred; use the
dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_GETA (11015):
HTTP error (not found [404]): Either the document, the component or the
attribute does not exist
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Get all attributes of component c1 of document d1 in archive A1:

char *retstring = dshDsGetAttribute(dsh,"A1","d1","c1","");

...
dshFree(retstring);

Example of the return string:

author="Gabriel";copyright="IXOS";created="2000";

See also “dsh_attribute example: dealing with document attributes”

on page 209

Related Functions

• “dshDsSetAttribute: Set attribute” on page 105

82 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.15. dshDsGetAttribute: Get attributes

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 83
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.16 dshDsGetDocumentHistory: Get document

history
Purpose
Returns a string describing the history of the document, i.e. a list of the events
that happened to the document. This list is a sequence of lines, where each line
represents one event, using the following syntax:
<ts>;<event>;<aid>;<docid>;<comp>;<cvers>;<volid1>;<volid2>;<caddr>

Each event is represented by a separate line in this string, containing the

following fields:

• <ts>: timestamp (seconds since 00:00 h on January 1, 1970.)[3]

• <event>: Event ID – see “Events” on page 225 for a reference of these IDs.
• <aid>: Archive name
• <docid>: Document ID
• <comp>: Component name
• <cvers>: Version of the component
• <volid1>: Volume name
• <volid2>: Second volume name (relevant only for events where a second
volume is involved, for example, migration)
• <caddr>: If the event was triggered by a client action, the IP address of the
client is returned in this field.

An example for a result string:

1023400002;12;A1;aaabbcdsewrdfa3yyx;data;1;A1_dsk1;-;127.0.0.1
1023404262;12;A1;aaabbcdsewrdfa3yyx;note;1;A1_dsk1;-;127.0.0.1

Notes
• If you no longer need the info string, call dshFree() to free the
respective memory buffer (but be careful not to use the info pointer
here).
• The document history is available only if the auditing feature is activated
for the appropriate logical archive (compliance mode – see Section 38.1
“Auditing” in OpenText Archive Server - Administration Guide (AR-ACN)
for details). If you call the function for documents on an archive for
which auditing is not active, the resulting info string is empty.

Function Header
char *dshDsGetDocumentHistory(
void *dsh,
const char *aid,
const char *docid
);

[3] In contrast to encrypted timestamps, this is just a common date/time value. Also see corresponding note
in “Timestamp functionality” on page 23.

84 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.16. dshDsGetDocumentHistory: Get document history

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID

Return values
Document history on success, see Purpose above.
NULL: Error; use the dshGetLastErrno function to obtain further error
information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
See Purpose above

Related Functions

• “dshDsInfo: Get info string for document/Component” on page 86

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 85
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.17 dshDsInfo: Get info string for document/

Component
Purpose
Returns a so-called info string for a document (if compID="") or component (if a
compid is specified). After calling dshDsInfo, call dshCompInfo to evaluate this
string (see “dshCompInfo: Get information on (unknown) components”
on page 41 for details).

Notes
• Do not evaluate the information string by means of your own functions.
The contents or structure of this string may change in later software
versions, and using the dshCompInfo function will help preserve their
compatibility.
• The function may also be used to check for the existence of a document:
If the function call causes a DSH_ERR_HTTP_404 error, the document does
not exist (or you specified an archive name that does not exist). – To
check for the existence of a document component, use the dshIsComp
function.
• Call dshFree() to free the memory buffer that has been allocated for the
returned info string.

Function Header
char *dshDsInfo(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name. Specify "" if you want to retrieve the information on all
components of the document.

Return values
Info string on success, to be evaluated via dshCompInfo.
NULL: Error; use the dshGetLastErrno function to obtain further error
information

86 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.17. dshDsInfo: Get info string for document/Component

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_ADD_MIME_PARSER (11000):
Can't add MIME parser to HTTP library
• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_INFO (11020):
HTTP error (conflict [409]): Administrative data is inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires read access permission for the document on the server.
Example
See “dshCompInfoStatus [DEPRECATED]:
Get information on (unknown) components” on page 45 and “dsh_get
example: Get all archived files of a document/retrieve component information”
on page 202
See also “dsh_get example: Get all archived files of a document/retrieve
component information” on page 202
Related Functions
• “dshCompInfoStatus [DEPRECATED]:
Get information on (unknown) components” on page 45
• “dshGetCompStatus: Get information on component” on page 136

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 87
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See also “Grouped function list” on page 28.

88 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.18. dshDsMigrate, dshDsMigrate2: Migrate document to another logical archive or
pool

3.18 dshDsMigrate, dshDsMigrate2: Migrate

document to another logical archive or pool
Purpose
Migrates (moves) the document <docid> from the archive <aid> to the archive
<aid_dest> (which can be identical). Unless other specified in <pool_name>, the
document is stored in the default pool of <aid_dest>. If a volume name
(<vol_name>) is specified, only the components of this volume are migrated.
Note that both source and target archive must be located on the same physical
Archive Server.
Compared to dshDsMigrate, dshDsMigrate2 provides an additional parameter
to specify a storage tier for the migration target. This is applicable only if
Archive Server uses software version 9.7 or higher and libdsh_3 is used.
Note that, by default, only components are touched for which source and
destination differ in archive, pool or both; this can be changed using the
<flags> parameter.

Function Header
int dshDsMigrate(
void *dsh,
const char *aid,
const char *docid,
const char *vol_name,
const char *pool_name,
const char *aid_dest,
const char *retention,
const char *comp_view,
int flag,
char **info
);
int dshDsMigrate2(
void *dsh,
const char *aid,
const char *docid,
const char *vol_name,
const char *pool_name,
const char *storage_tier,
const char *aid_dest,
const char *retention,
const char *comp_view,
int flag,
char **info
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 89
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• aid (input)
Name of the source archive, from which the document should be moved to
the target.
• docid (input)
Document ID of the document to be moved
• vol_name (input, optional)
Name of a source volume. If specified, only the components stored on this
volume are moved to the target.
• pool_name (input, optional)
Name of the target document pool. If not specified, the default pool of the
destination archive is used.[4]
• storage_tier (input, optional; dshDsMigrate2 only)
Name of the target storage tier; the server then looks for the pool assigned to
this tier in the target archive and stores the document/component there.
Do not specify both storage_tier and app_type in the same function call; if
both are specified and lead to different pools to be used, the call will fail.
• aid_dest (input)
Name of the destination archive. If not specified, the document remains in
the source archive, but is moved to the specified pool within this archive.
• retention (input, optional)
Retention period of the document – see “Retention period” on page 24 for
details. If not specified, the default retention period of the destination archive
is assigned.
Note that the retention period specified here is added to the date when the
component originally has been created, not to the date of the migration.
• comp_view (input, optional)
This parameter is used for service purposes only. Do not assign a value here.
• flag (input, optional)
Specify 1 if you want to force the migration even if the destination archive
and pool are identical to the source. Otherwise, only those components are
migrated where the destination differs from the source.
• info (output)
Info string for the component that can be evaluated with the dshCompInfo
function

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
[4] Note that this parameter refers to the pool name, not to the application type as other functions do.

90 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.18. dshDsMigrate, dshDsMigrate2: Migrate document to another logical archive or
pool

• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires update access permission for the document on the server.

Example
Migrate the document d1 from the archive A1 to the archive A2. The retention
period of the migrated document should be 720 days (2 years)

char *info;
int ret = dshDsMigrate(dsh,"A1","d1",NULL,NULL,"A2","720",
"all",0,&info);
...
dshFree(info);

Related Functions
• “dshCompInfo: Get information on (unknown) components” on page 41

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 91
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.19 dshDsLock: Lock document

Purpose
Sets the locked flag for a document to signal other applications that the document
is in use (for modification). If you specify a non-empty string in the locker
parameter, this string must be specified also in the dshDsUnlock function, later-
on, to reset the locked flag (usually the client ID is used for this parameter).
Note that the locked flag is not automatically evaluated by the server or by
libdsh; it must be evaluated by each of your applications. Therefore, after you
use the dshDsLock function, always check the result. In particular if the function
return value is 2 (which corresponds to the DSH_ERR_HTTP_409_LOCK error) the
document has been locked by another application and must not be modified
unless it is ensured that the other application does no longer deal with it.

Function Header
int dshDsLock(
void *dsh,
const char *aid,
const char *docid,
const char *locker
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• locker (input)
ID for later unlocking (see Purpose above).

Return values
1: Function completed successfully.
2: Document is already locked (corresponds to the DSH_ERR_HTTP_409_LOCK
error).
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter

92 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.19. dshDsLock: Lock document

• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_LOCK (11018):
HTTP error (conflict [409]): There was already a lock on the document
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires update access permission for the document on the server.

Example
Lock document d1 in archive A1 by specifying your client ID as locker string:

int ret = dshDsLock(dsh,"A1","d1","clientX");

See also “dsh_lock example: Locking/unlocking documents” on page 218

Related Functions
• “dshDsUnlock: Unlock document” on page 110

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 93
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.20 dshDsPutCert, dshDsPutCertFile: Put

certificate to Archive Server
Purpose
Transfers the digital certificate (including the public key) to a repository server.
A valid certificate for your client must be present on the server before you can
access documents that are protected via SecKeys (see “Access protection via
SecKeys (signed URLs)” on page 22).
The certificate may be read either from a memory buffer (dshDsPutCert) or
from a file (dshDsPutCertFile) – see Parameters below for details.
The client identifies itself via its authenticity, which must be specified via the
dshSetAuthId() function before calling dshDsPutCert or dshDsPutCertFile;
otherwise the server will assign a wrong client ID to the certificate and will not
accept your SecKeys.

Notes
• Instead of explicitly addressing a certain server, the function requires
that you specify a logical archive (aid parameter). The respective server
is then addressed automatically. If that server hosts several logical
archives protected by SecKeys, you must transfer the certificate once to
any of the archives involved.
• Apart from transferring the certificate to the server, the certificate must
also be declared locally (via dshSetCertificate or
dshSetCertificateFile) before the first document protected via
SecKeys can be requested.
In addition you must specify several further settings (see Related
functions below) that are also required for building SecKey requests.
See also “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for further details.

Function Header
int dshDsPutCert(
void *dsh,
const char *aid,
const unsigned char *cert_buf,
int cert_len
);
int dshDsPutCertFile(
void *dsh,
const char *aid,
const char *path
);

Parameters
• dsh (input)

94 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.20. dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server

Class handle, obtained via a preceding dshOpen() call.

• aid (input)
Archive name
• cert_buf (input)
Memory buffer containing the contents of the certificate. The certificate data
must be encoded according to the Distinguished Encoding Rules (DER, see [3
on page 225] in “Further information sources” on page 225).
• cert_len (input)
Size of cert_buf
• path (input)
Path of the certificate file. The file must correspond to the PEM standard
(RFC1424, see [2 on page 225] in “Further information sources” on page 225
for details).“Document/component formats (renditions, file types)”
on page 19

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_406 (11009):
HTTP error (not acceptable [406]): Certificate cannot be recognized
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

None

Example
Transfer certificate from file cert.pem to Archive Server hosting the A1 archive.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 95
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

int ret = dshDsPutCertFile(dsh,"A1","cert.pem");

Related Functions
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshSetAuthId: Set authenticity” on page 178
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182

See also “Grouped function list” on page 28.

96 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.21. dshDsPutCert2, dshDsPutCertFile2: Put certificate to Archive Server

3.21 dshDsPutCert2, dshDsPutCertFile2: Put

certificate to Archive Server
Purpose
Transfers the digital certificate (including the public key) to a repository server.
A valid certificate for your client must be present on the server before you can
access documents that are protected via SecKeys (see “Access protection via
SecKeys (signed URLs)” on page 22).
The certificate may be read either from a memory buffer (dshDsPutCert2) or
from a file (dshDsPutCertFile2) – see Parameters below for details.
The client identifies itself via its authenticity, which must be specified via the
dshSetAuthId() function before calling dshDsPutCert or dshDsPutCertFile;
otherwise the server will assign a wrong client ID to the certificate and will not
accept your SecKeys.

Notes

• Archive Server is the host, which was specified in method dshOpen or

dshOpen2 of the corresponding <dsh> handle.
For each Archive Server privileges for reading, creating, or deleting
documents and the privilege to pass by Enterprise Library service layer
can be granted (see <privileges> parameter.
• Apart from transferring the certificate to the server, the certificate must
also be declared locally (via dshSetCertificate or
dshSetCertificateFile) before the first document protected via
SecKeys can be requested.
In addition you must specify several further settings (see Related
functions below) that are also required for building SecKey requests.
See also “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for further details.

Function Header
int dshDsPutCert2(
void *dsh,
const char *aid,
const unsigned char *cert_buf,
int cert_len
const char *privileges;
);
int dshDsPutCertFile2(
void *dsh,
const char *aid,
const char *path
const char *privileges
);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 97
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name; the certificate is assigned to the archive specified with this
parameter (still must be enabled with administration client); empty string or
NULL pointer for a global certificate.
• cert_buf (input)
Memory buffer containing the contents of the certificate. The certificate data
must be encoded according to the Distinguished Encoding Rules (DER, see [3
on page 225] in “Further information sources” on page 225).
• cert_len (input)
Size of cert_buf
• path (input)
Path of the certificate file. The file must correspond to the PEM standard
(RFC1424, see [2 on page 225] in “Further information sources” on page 225
for details).“Document/component formats (renditions, file types)”
on page 19
• privileges (input)
Either a NULL pointer to assign the default access modes to the certificate.
or
A string with a combination of following access modes:
• r : to read documents
• c : to create documents
• u : to update documents
• d : to delete documents
• p : to pass by

Example: rcu = assign privileges to certificate for reading, creating and

updating documents of archive <aid>.

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_OUT_OF_MEMORY (11204):

98 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.21. dshDsPutCert2, dshDsPutCertFile2: Put certificate to Archive Server

Out of memory
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_406 (11009):
HTTP error (not acceptable [406]): Certificate cannot be recognized
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

None

Example
Transfer global certificate from local file cert.pem to Archive Server and set
privileges to allow to read, create, update and to delete documents.

int ret = dshPutCertFile2(dsh,"A1","cert.pem","rcud");

Related Functions
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshSetAuthId: Set authenticity” on page 178
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 99
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.22 dshDsReserveDocId: Get new document ID

Purpose
Reserves a Document ID for a document to be stored on the repository server in
the near future. This is useful for example, if the document shall contain a
reference to its own Document ID, or if you want to generate attributes for the
document before storing the document contents.
After getting the document id the status of the document will be ONLINE (see
function dshGetDocStatus).
To create the document, use dshDsCreate or dshDsCreateFile and specify the
Document ID obtained by dshDsReserveDocId in the docid parameter of the
dshDsCreate* function.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned Document ID.

Function Header
char *dshDsReserveDocId(
void *dsh,
const char *aid
const char *docid
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID. If you specify "", the Document ID is generated by the server
and returned via the function return value (not via the docid parameter!).
Otherwise a new document is generated with the specified ID; in this case,
you are responsible for providing a unique Document ID, which is not yet in
use. If you specify an existing Document ID, the function will return the
existing Document ID.

Return values
Document ID on success.
NULL: Error; use the dshGetLastErrno function to obtain further error
information
Errors that may occur
• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Unknown archive
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
Out of memory

100 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.22. dshDsReserveDocId: Get new document ID

• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_400 (11005):
HTTP error (not acceptable [406]): Certificate cannot be recognized
• DSH_ERR_HTTP_401 (11006):
HTTP error: connection was broken
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
HTTP error: unknown error
• DSH_ERR_ACCESS_FILE (11207):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Create

Example
Get a new Document ID from Archive Server of archive A1:

char *docid = dshDsReserveDocId(dsh,"A1",NULL);

Related Functions
• “dshDsCreate*, dshDsCreateFile*: Create document/Component”
on page 64

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 101
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.23 dshDsSearch, dshDsSearch2: Search in

component
Purpose
Searches for a string pattern in a component, starting at a given offset
from_offset and ending at a given offset to_offset.
The search result (return value of the function) contains the number of hits and
the start offset of each hit, separated by semicolons; moreover, the result string
ends with a semicolon:
<number of hits(= n)>;<offset of hit 1>;...;<offset of hit n>;
If no matches are found, the function returns “0;”.

Notes
• Call dshFree() to free the memory buffer that has been allocated for the
returned search result string.
• The only difference between two functions is the type assignment of the
parameters from_offset and to_offset.

Function Header
char *dshDsSearch(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *pattern,
long from_offset,
long to_offset,
int num_results,
int case_sensitive
);
char *dshDsSearch2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *pattern,
int64_t from_offset,
int64_t to_offset,
int num_results,
int case_sensitive
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

102 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.23. dshDsSearch, dshDsSearch2: Search in component

• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• pattern (input)
Search pattern
• from_offset (input)
Offset where to start search
• to_offset (input)
Offset where to stop search; specify -1 for searching until the end)
• num_results (input)
Maximum number of search results
• case_sensitive (input)
Specify 0 for case-insensitive search (a=A)
Specify 1 for case-sensitive search (a!=A)

Return values
Search result, see Purpose above.
“0;”: No hits have been found.
NULL: Error; use the dshGetLastErrno function to obtain further error
information.
Errors that may occur
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 103
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Search first two occurrences of pattern “Specification” in component c1 of
document d1 in archive A1:

char *retstring = dshDsSearch(dsh,"A1","d1","c1",

"Specification",0,-1,2,1);
...
dshFree(retstring);

This might be the returned string:

2;1010;2000;

meaning that 2 hits were found, one starting at offset 1010 and the other starting
at offset 2000 (but note that the document may contain further hits, which were
not found because the number of hits has been limited to 2 in the function call).
See also “dsh_search example: Searching and getting the found piece of data”
on page 214

104 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.24. dshDsSetAttribute: Set attribute

3.24 dshDsSetAttribute: Set attribute

Purpose
Sets an attribute for a document or component. If you specify compID="", the
attribute is set for the document; otherwise, it is set for the specified component.
You may specify arbitrary attributes if you like, but please note that the
OpenText Imaging Clients cannot evaluate such attributes. The only attribute
supported by OpenText Imaging Clients is the type attribute for documents. For
further details, see “Document/component formats (renditions, file types)”
on page 19 and “Document model” on page 14 (on attributes in general).

Note: If you operate in an OpenText TCP system, but want to keep the
attribute naming as used in archive-centric systems, a name mapping must
be defined via the Server Configuration.

Function Header
int dshDsSetAttribute(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *attribute,
const char *value
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name. Specify "" if you want to set the attribute for the docid
document instead of a certain component.
• attribute (input)
Attribute name
• value (input)
Attribute value

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 105
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Error in accessing file

• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_SETA (11017):
HTTP error (not found [404]): Either the document or the component does
not exist
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires update access permission for the document on the server.

Example
Set attribute author for component c1 of document d1, located in archive A1,
and assign Gabriel as value:

int ret = dshDsSetAttribute(dsh,"A1","d1","c1","author",

"Gabriel");

See also “dsh_attribute example: dealing with document attributes”

on page 209

Related Functions
• “dshDsGetAttribute: Get attributes” on page 81

See also “Grouped function list” on page 28.

106 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.25. dshDsSetDocumentFlag: Start delayed processing

3.25 dshDsSetDocumentFlag: Start delayed

processing
Purpose
Executive counterpart to functions that prepared a delayed archiving or an
event-based retention period assignment. See <store_param> parameter below
for details.
Function Header
int dshDsSetAttribute(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *retention_period,
const char *store_param
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name. Specify "" or NULL if you want to refer to the entire
document instead of a specific component.
• retention_period (input)
Retention period (in days) to be assigned to the component or document –
see “Retention period” on page 24 for details.
• store_param (input)
Sub-function to be processed:
• immediate: Apply to a document that has been stored using
dshDsCreate* with store_param="delayed" to send this document
from the disk buffer to the archive storage now.

Note: For compatibility reasons, the value “delayed” is also

accepted (having the same meaning as immediate), but preferably
should be replaced.
• setEvent: Apply to a document that has been archived with an event-
based retention to set a concrete retention period as specified in the
<retention_period> parameter.
See also “Retention period” on page 24.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 107
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• setEventAndArchive: This sub-function combines delayed and

setEvent. This is useful if archiving a document and setting the retention
period is done by separate applications, or an application cannot do both
in one step, for example, in a mass archiving scenario. In this case, the
documents are stored in Archive Server using the delayed archiving
option in dshDsCreate*, and a batch assigns a retention period for each
document later, using this sub-function.

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_SETA (11017):
HTTP error (not found [404]): Either the document or the component does
not exist
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires create access permission for the document on the server.

Example
Set retention period for event-based document d1 in archive A1 to 720 days (2
years):

int ret =
dshDsSetDocumentFlag(dsh,"A1","d1","","720","setEvent");;

Related Functions
• “dshDsMigrate, dshDsMigrate2: Migrate document to another logical
archive or pool” on page 89

108 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.25. dshDsSetDocumentFlag: Start delayed processing

• “dshDsCreate*, dshDsCreateFile*: Create document/Component”

on page 64

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 109
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.26 dshDsUnlock: Unlock document

Purpose
Resets the locked flag for a document that has been set previously via
dshDsLock, either by your application or by another.
The value of the locker parameter must be the same as specified in the
corresponding dshDsLock call (usually the client ID is used for this parameter).
As an alternative, you can specify force="yes" to force the flag to be reset even
without the correct locker parameter; of course this must be used only if you
ensured before that the document is no longer in use by the application that
locked it.
Function Header
int dshDsUnlock(
void *dsh,
const char *aid,
const char *docid,
const char *locker,
const char *force
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• locker (input)
ID for unlocking (must correspond to the locker parameter specified when
the document was locked).
• force (input)
Force unlocking (specify "yes" or "no")

Return values
1: Function completed successfully.
2: The specified locker parameter does not match the string used when the
document was locked. (corresponds to DSH_ERR_HTTP_409_UNLOCK).
3: The document is not locked at all (corresponds to
DSH_ERR_HTTP_412_UNLOCK).
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):

110 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.26. dshDsUnlock: Unlock document

Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_UNLOCK (11019):
HTTP error (conflict [409]): The document was not locked by locker.
Therefore the lock could not be removed
• DSH_ERR_HTTP_412_UNLOCK (11021):
HTTP error (precondition failed [412]): The document was not locked
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires update access permission for the document on the server.

Example
Force unlocking of document d1 in archive A1

int ret = dshDsUnlock(dsh,"A1","d1","","yes");

See also “dsh_lock example: Locking/unlocking documents” on page 218

Related Functions
• “dshDsLock: Lock document” on page 92

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 111
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.27 dshDsUpdate*, dshDsUpdateFile*: Update

component
Purpose
These functions replace a component of a document (for example, the notes or
annotations component) with a new version. The new component contents can
be read either from a buffer (dshDsUpdate) or from a file (dshDsUpdateFile). In
dshDsUpdate2 and dshDsUpdateFile2, a timestamp can be specified,
additionally, and in dshDsUpdate3 and dshDsUpdateFile3 a storage tier (see
Parameters below for details)

Important
• Use these functions with care:
Once you apply one of them to a document, the former component
version is permanently deleted! There is no undo option for these
functions (or for any libdsh function).
• Do not modify composed documents (form overlays, notes,
annotations)!
libdsh does not support composed documents, for example, form
overlays, notes or annotations. Therefore you should not modify or
replace components in a document using form overlays, notes or
annotations, as this may impact the structural relationship between
the individual components and may destroy the document (see also
“Document model” on page 14).

If the document has been stored on an optical medium, its components cannot
be changed, of course. Instead a new component (or even a completely new
document) is generated and any reference to the old component within the
database is removed; so the former component version cannot be found any
longer. There is only a chance to restore a component version after
dshDsUpdate(File), if a database backup has been performed short time before
deletion.
Note that these functions always replace a component as a whole; you cannot
modify a single component property (for example, type or compid) by
specifying the respective parameter and leaving the other parameters empty. In
particular if you specify an empty data parameter, this will generate an empty
document (and if you use an existing docid/compid pair, it will overwrite the
existing component!).
As a rule, dshDsUpdate* is required only for updating notes or annotations that
can be modified by definition, or for test purposes. If you intend to use the
function in a different context, do not forget to inform your users accordingly:
Modifications in a document are quite an unexpected feature in the context of an
archive.
Function Header
int dshDsUpdate(
void *dsh,

112 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.27. dshDsUpdate*, dshDsUpdateFile*: Update component

const char *aid,

const char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
);

int dshDsUpdate2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
const char *timestamp
);

int dshDsUpdate3(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *type,
char *data,
long size,
const char *app_type
const char *timestamp
const char *storage_tier
);

int dshDsUpdateFile(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
);

int dshDsUpdateFile2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *type,
const char *path,

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 113
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

const char *app_type

const char *timestamp
);
int dshDsUpdateFile3(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *type,
const char *path,
const char *app_type
const char *timestamp
const char *storage_tier
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• type (input)
File type of the component (see “Document/component formats (renditions,
file types)” on page 19).
• data (input)
Data of component compid
• size (input)
Size of the data buffer (= size of the compid component after the
modification)
• path (input)
Local filename of component compid
• app_type (input)
Application type for pool selection (see “Document pools, storage tiers”
on page 12).
Specify the empty string ("") for the default pool.
• timestamp (input; dshDsUpdate2/3, dshDsUpdateFile2/3 only)
Optional timestamp to be stored with the component (format: DER->BASE64)
– see “Timestamp functionality” on page 23.
If you specify "" or the NULL pointer, the parameter is ignored.
• storage_tier (input; dshDsUpdate3, dshDsUpdateFile3 only)

114 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.27. dshDsUpdate*, dshDsUpdateFile*: Update component

Optional storage tier to be assigned to the component; the server then looks
for the pool assigned to the storage tier and stores that component in that
pool.
If you specify "" or the NULL pointer, the default pool is used.
Do not specify both storage_tier and app_type in the same function call; if
both are specified and lead to different pools to be used, the call will fail.

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_CREATE_CHECKSUM (11205):
Error in creating checksum
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.
SecKey access mode
Requires update access permission for the document on the server.
Example
Replace component c1 of document d1 of archive A1 with content of file x.txt,
and set the type of the component to application/xyz:

int ret = dshDsUpdateFile(dsh,"A1","d1","c1","application/

xyz","x.txt","");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 115
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Related Functions
• “dshDsCreate*, dshDsCreateFile*: Create document/Component”
on page 64
• “dshDsLock: Lock document” on page 92

See also “Grouped function list” on page 28.

116 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.28. dshDsValidUser2: Check user account

3.28 dshDsValidUser2: Check user account

Purpose
Checks whether the given user and password comprise a valid user account.
This function returns the name of the groups to which the user belongs.
The structure of the return string is: group="<group 1>,...,<group n>"

Notes
• dshDsValidUser is deprecated since libdsh_3; use dshDsValidUser2
instead.
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.
• For the user_sys values DS, OS, and R3, user and passwords are sent via
HTTPS protocol to Archive Server.

Function Header
char *dshDsValidUser2(
void *dsh,
const char *user,
const char *passwd,
const char *user_sys
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• user (input)
Archive user
• passwd (input)
Password of archive user
• user_sys (input)
User management system that the ADMS shall use for checking and an
encryption option:
"DS" = DS user, no encryption
"DS_ENC" = DS user, encrypted transmission
"OS" = operating system user, no encryption
"OS_ENC" = operating system user, encrypted transmission
"R3" = SAP user, no encryption (not yet implemented)
"R3_ENC" = SAP user, encrypted transmission (not yet implemented)
As a rule, you should use one of the *_ENC options; only if that should fail,
you may try an option without encryption.

Return values
Groups of the user specified in user, see Purpose above.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 117
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

NULL: Error; use the dshGetLastErrno function to obtain further error

information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_VU (11014):
HTTP error (not found [404]): A user account with the specified user/passwd
combination does not exist. The user is not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Unknown

Example
Check whether user Gabriel with password PSWD is a valid user account in
archive A1:

char *retstring = dshDsValidUser(dsh,"A1","Gabriel","PSWD","DS");

...
dshFree(retstring);

The following string might be returned:

group="dsadmin,dpadmin"

meaning that user Gabriel belongs to two groups, dsadmin and dpadmin.

Related Functions
See also “Grouped function list” on page 28.

118 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.29. dshDsVerifyATS: Verify signature of an ArchiSig timestamp

3.29 dshDsVerifyATS: Verify signature of an

ArchiSig timestamp
Purpose
Proofs the timestamp (dated signature) of an ArchiSig Timestamp (ATS) of the
component <compid> or of the default component, if <compid> equals to "".
Additionally, the function can check whether a local component corresponds to
the verified component. This local component can be provided either as a file
(<file> parameter) or a memory buffer (<data> parameter); if both parameters
are specified, the file is prefered.

Notes
• The configuration variable DSH_VERIFY_SIG_TIMEOUT specifies a
timeout for this call. See “Global environment variables” on page 228 for
details.
• For further information on timestamps, see Section 14.4 “Timestamps” in
OpenText Archive Server - Administration Guide (AR-ACN).
• Using the dshCompInfo function, you can determine whether a
component has a timestamp (sig_object parameter).
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.

Function Header
int dshDsVerifyATS(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *vol_name,
const char *file,
const char *data,
long size,
const char *hashalg,
char **result_string
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 119
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Component name
• vol_name (input, optional)
Name of the harddisk volume containing the component to be checked.
Using this parameter, you can explicitly address a component on a specific
volume to be checked, in case that a components exists on several volumes
and you want to check a specific one of them.
• file (input, optional)
Name of a local file to be checked (see Purpose above)
• data (input, optional)
Pointer to a memory buffer to be proofed (see Purpose above)
• size (input, optional)
Number of bytes of the component to be proofed
• hashalg (input)
Choose hashing function of ArchiSig timestamp, examples:
• RMD160
• SHA256
• SHA512
• result_string (output)
Result string of the verification

Return values
1: Verification was successful.
2: Verification of signature was successful, but verification of certificate failed.
3: Other error returned from DS.
0: Other error; use the dshGetLastErrno function to obtain further error
information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken

120 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.29. dshDsVerifyATS: Verify signature of an ArchiSig timestamp

• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Read

Example
Verify ArchiSig signature (timestamp) of component c1 of document d1 of
archive A1:

char *result_string;
int ret = dshDsVerifyATS(dsh,"A1","d1","c1",NULL,NULL,
NULL,0,0,&result_string);
...
dshFree(result_string);

The <result_string> might look as follows:

result="0";resultDescr=""
docId="aaaad6ggguquucahbaaaaaev4ofv3";compId="9277.otf";compVers=
"1";volume="HD40";compSizeSigned="389";compSizeActual="389"
Sequence[1]:result="0";resultDescr="";hashAlg="SHA1"
Chain[1]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:09:00"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Chain[2]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:09:37"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Chain[3]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:10:01"

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 121
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Sequence[2]:result="0";resultDescr="";hashAlg="SHA256"
Chain[1]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:11:35"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Chain[2]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:13:56"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Sequence[3]:result="0";resultDescr="";hashAlg="SHA512"
Chain[1]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:14:39"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo
Root";result="0";resultDescr="Self-signed certificate enabled in
admin server.";expireDate="2015-05-30";expireTime="13:42:20"
Chain[2]:result="0";resultDescr="";signDate="2009-05-11";signTime
="11:15:13"
signer="/C=DE/O=OpenText/CN=Demo
TSS1";result="0";resultDescr="";expireDate="2015-05-28";expireTim
e="13:58:19"
signer="/C=DE/O=OpenText/CN=Demo
CA";result="0";resultDescr="";expireDate="2015-05-29";expireTime=
"13:49:42"
signer="/C=DE/O=OpenText/CN=Demo

122 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.29. dshDsVerifyATS: Verify signature of an ArchiSig timestamp

Root";result="0";resultDescr="Self-signed certificate enabled in

admin server.";expireDate="2015-05-30";expireTime="13:42:20"

Related Functions
• “dshCompInfo: Get information on (unknown) components” on page 41

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 123
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.30 dshDsVerifySig: Proof timestamp of a

component
Purpose
Proofs the timestamp (dated signature) of the component <compid> or of the
default component, if <compid> equals to "". Additionally, the function can
check whether a local component corresponds to the verified component. This
local component can be provided either as a file (<file> parameter) or a
memory buffer (<data> parameter); if both parameters are specified, the file is
prefered.

Notes
• The configuration variable DSH_VERIFY_SIG_TIMEOUT specifies a
timeout for this call. See “Global environment variables” on page 228 for
details.
• For further information on timestamps, see Section 14.4 “Timestamps” in
OpenText Archive Server - Administration Guide (AR-ACN).
• Using the dshCompInfo function, you can determine whether a
component has a timestamp (sig_object parameter).
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.

Function Header
int dshDsVerifySig(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *vol_name,
const char *file,
const char *data,
long size,
int flag,
char **result_string
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)

124 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.30. dshDsVerifySig: Proof timestamp of a component

Component name
• vol_name (input, optional)
Name of the harddisk volume containing the component to be checked.
Using this parameter, you can explicitly address a component on a specific
volume to be checked, in case that a components exists on several volumes
and you want to check a specific one of them.
• file (input, optional)
Name of a local file to be checked (see Purpose above)
• data (input, optional)
Pointer to a memory buffer to be proofed (see Purpose above)
• size (input, optional)
Number of bytes of the component to be proofed
• flags (input, optional)
Controls the output returned in the <result_string> parameter:
• Specify 0 to get default output (see example below).
• Specify 1 to get timestamp in the result string, additionally.
• Specify 2 to get the certificates in the result string, additionally.
• result_string (output)
Result string of the verification

Return values
1: Verification was successful.
2: Verification of signature was successful, but verification of certificate failed.
3: Other error returned from DS.
0: Other error; use the dshGetLastErrno function to obtain further error
information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404_VU (11014):
HTTP error (not found [404]): A user account with the specified user/passwd
combination does not exist. The user is not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 125
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

HTTP error: connection was broken

• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Read

Example
Verify signature (timestamp) of component c1 of document d1 of archive A1:

char *result_string;
int ret = dshDsVerifySig(dsh,"A1","d1","c1",NULL,NULL,
NULL,0,0,&result_string);
...
dshFree(result_string);

The <result_string> might look as follows:

result="0";resultDescr=""
docId="testdoc";compId="data";compVers="1";signDate="2003-12-01";
signTime="13:55:49";
signer="/C=DE/O=IXOS/OU=TSS/CN=TS00";result="0";resultDescr=""
signer="/C=DE/O=IXOS/CN=CA";result="0";resultDescr=""
signer="/C=DE/O=IXOS/CN=Root";result="0";resultDescr=""

Related Functions
• “dshCompInfo: Get information on (unknown) components” on page 41

See also “Grouped function list” on page 28.

126 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.31. dshExit: Exit the libdsh library

3.31 dshExit: Exit the libdsh library

Purpose
This is the last call of the libdsh library, it is used to free all remaining memory
and resources.
Before calling dshExit, close connections to any Archive Servers using the
dshClose function. If you modified any global variables (see “Global
environment variables” on page 228) and want to restore these modifications in
the next session, store the variables in a local file before calling dshExit; neither
these variables nor local settings (applied via dshSet* functions) are
automatically stored by libdsh (see also “Setting parameters” on page 34).

Function Header
void dshExit(void);

Parameters
none

Return values
No return values

Example
Your program source code may look as follows:
void *dsh = dshOpen(...); /* first call of library libdsh! */
...
... use library libdsh
... some dsh-function calls
...
dshClose(dsh); /* closing the connection */
dshExit(); /* last call of library libdsh! */
See also the examples in “Archive Server API in practice“ on page 193

Related Functions
• “dshClose: Close connection to repository server” on page 40

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 127
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.32 dshFree: Release allocated memory

Purpose
Frees memory, that has been allocated within the libdsh library. Note that all
character pointers returned by a libdsh function must be freed using
dshFree(). Do not use any other function for clearing this memory, as this may
lead to access problems.

Function Header
void dshFree(void *ptr);

Parameters
• ptr (input)
pointer to allocated memory

Return values
No return values

Example
char *search_result = dshDsSearch(...);
...
... doing something with server_info . . .
...
dshFree(search_result);
See also “dsh_attribute example: dealing with document attributes”
on page 209,
“dsh_search example: Searching and getting the found piece of data”
on page 214

128 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.33. dshGetAidRefreshInterval: Get aid refresh interval

3.33 dshGetAidRefreshInterval: Get aid refresh

interval
Purpose
Returns the refresh period for updating Archive Server information, specified in
seconds.
The default value for this period is 3600 (= 1 hour).

Note: Use the dshGetAidRefreshTime function to retrieve the

information, when Archive Server information is refreshed the next time.

Function Header
int dshGetAidRefreshInterval(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Refresh interval, specified in seconds.

Example

int interval_secs = dshGetAidRefreshInterval(dsh);

Related Functions
• “dshSetAidRefreshInterval: Set refresh interval for ADMS info”
on page 174
• “dshGetAidRefreshTime: Get time of next ADMS info refresh ”
on page 130

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 129
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.34 dshGetAidRefreshTime: Get time of next ADMS

info refresh
Purpose
Returns the time for the next update of Archive Server information.
The refresh time is returned in seconds since 00:00 Coordinated Universal Time
(UTC) on January 1, 1970.

Function Header
time_t dshGetAidRefreshTime(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Time of next ADMS refresh (see Purpose above)

Example

time_t refresh_time = dshGetAidRefreshTime(dsh);

Related Functions
• “dshSetAidRefreshTime: Set time of next ADMS info refresh”
on page 175
• “dshGetAidRefreshInterval: Get aid refresh interval” on page 129

See also “Grouped function list” on page 28.

130 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.35. dshGetApplication: Get application name

3.35 dshGetApplication: Get application name

Purpose
Returns the name of the application currently stored in libdsh. This name is used
for accounting in DS.
Use the dshSetApplication() function to set the application name (or specify
the application name in the initial dshOpen call). As long as no explicit
application is set, libdsh transmits “libdsh” as the application name to the DS for
accounting.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string.

Function Header
char * dshGetApplication(void *dsh);

Parameters
• dsh (input)
class handle, obtained via a preceding dshOpen() call.

Return values
Application name on success.
NULL on error.

Example

char *appl = dshGetApplication(dsh);

...
dshFree(appl);

Related Functions
• “dshSetApplication: Set application name ” on page 177

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 131
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.36 dshGetAuthId: Get authenticity ID of client

Purpose
Returns the (unique) client identifier. This identifier is required to access
documents that are protected via SecKeys.
Use the dshSetAuthId() function to set the client identifier. The default value of
this identifier is the current hostname.

Notes
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.
• See “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for details on the use of SecKeys.

Function Header
char * dshGetAuthId(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Client identifier (authenticity) on success.
NULL on error.

Example
Get the client identifier:

char *auth_id = dshGetAuthId(dsh);

...
dshFree(auth_id);

Related Functions
• “dshSetAuthId: Set authenticity” on page 178

See also “Grouped function list” on page 28.

132 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.37. dshGetCertificateFile: Get filename of certificate

3.37 dshGetCertificateFile: Get filename of

certificate
Purpose
Returns the filename of the digital certificate, including public key. The
certificate is required to access documents that are protected via SecKeys.
Before calling this function you must have set the certificate via the
dshSetCertificateFile() function.

Notes
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.
• See “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for details on the use of SecKeys.

Function Header
char *dshGetCertificateFile(void);

Parameters
none

Return values
Certificate filename on success.
NULL: Error; use the dshGetLastErrno function to obtain further error
information.

Example
Get the filename of the certificate:

char *filename = dshGetCertificateFile();

...
dshFree(filename);

Related Functions
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 133
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.38 dshGetCompSize: Get size of component

Purpose
Returns the size (in bytes) of component compid in document docid.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string.

Function Header
char *dshGetCompSize(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);

Parameters
• dsh (input)
class handle, obtained via a preceding dshOpen() call.
• aid (input)
archive name
• docid (input)
Document ID
• compid (input)
component name

Return values
String containing the size of component on success
-1: Size is unknown (for example, decomposed emails)
NULL: Error; use the dshGetLastErrno function to obtain further error
information

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_ADD_MIME_PARSER (11000):
Can't add MIME parser to HTTP library
• DSH_ERR_UNKNOWN_COMP (11209):
Unknown component
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):

134 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.38. dshGetCompSize: Get size of component

HTTP error (unauthorized [401]): Breach of security

• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Get the size of component c1 of document d1 in archive A1:

char *size = dshGetCompSize(dsh,"A1","d1","c1");

...
dshFree(size);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 135
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.39 dshGetCompStatus: Get information on

component
Purpose
Returns information on a document component including:

• the component status

• the archiving date and time
• the size of the component
• the file type (see “Document/component formats (renditions, file types)”
on page 19)

Note: If you do not know the components of a document (or their names),
use dshDsInfo and dshCompInfoStatus instead of dshGetCompStatus.

Function Header
int dshGetCompStatus(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
char *status,
char *type,
char *ar_date,
char *ar_time,
char *size,
int utc_flag
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name
• status (output)
Document/component status, which may be one of the following values:
ONLINE, OFFLINE, UNKNOWN, ERROR.
Must be allocated by the calling application with a size >= 21 bytes.
• type (output)
File type of the component (see “Document/component formats (renditions,
file types)” on page 19).

136 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.39. dshGetCompStatus: Get information on component

Must be allocated by the calling application with a size >= 100.

• ar_date (output)
Modification date, i.e. date when the document containing the component
has been modified most recently; format: YYYYMMDD.
Must be allocated by the calling application with a size = 9 bytes.
• ar_time (output)
Modification time, i.e. time when the document containing the component
has been modified most recently; format: HHMMSS.
Must be allocated by the calling application with a size = 7 bytes.
• size (output)
Size of the component.
Must be allocated by the calling application with a size > =14 bytes.
• utc_flag (input)
Specify 0 to get date and time in localtime.
Specify 1 to get date and time in UTC (Greenwich time).

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)
• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_UNKNOWN_COMP (11209):
Unknown component
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_INFO (11020):
HTTP error (conflict [409]): Administrative data is inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 137
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

HTTP error: connection was broken

• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Get the status information of component c1 in document d1, located in archive
A1:

char status[21], type[100], ar_date[9], ar_time[7], size[14];

int ret = dshGetCompStatus(dsh,"A1","d1","c1",status,
type,ar_date,ar_time,size,0);

Related Functions
• “dshCompInfo: Get information on (unknown) components” on page 41
• “dshCompInfo: Get information on (unknown) components” on page 41
• “dshDsMigrate, dshDsMigrate2: Migrate document to another logical
archive or pool” on page 89

See also “Grouped function list” on page 28.

138 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.40. dshGetConfig: Get value of global configuration variable

3.40 dshGetConfig: Get value of global configuration

variable
Purpose
Returns value of the libdsh configuration variable specified in <key>. If <key>
is the NULL pointer or "", a list of all libdsh configuration variable is returned,
using the format

{<key>=<value>\n}

Notes

• See “Global environment variables” on page 228 for a list of these

variables, and their meaning. Variables that are returned by this
function, but are not listed in Section 5.3 are internal and should not be
modified by your applications.
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.

Function Header
char * dshGetConfig(
void *dsh,
const char *key
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• key (input)
Name of the variable to be retrieved

Return values
Value of requested variable or list of all variables

Example
Get value (on or off) of the global HTTP log-setting LOG_DSH:

char *value = dsh(dsh,"LOG_DSH");

...
dshFree(value);

Related Functions

• “dshSetConfig: Set value of global configuration variable” on page 181

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 139
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.41 dshGetDocInfo, dshGetDocInfo2: Get status

of a document
Purpose
Returns information on a document such as time/date of archiving, modification
and others (see Parameters below). Compared to dshGetDocInfo,
dshGetDocInfo2 provides additional parameters related to the cache status and
delayed archiving (on_csrv, is_delayed).

Notes
• In case of unset or unknown values, the NULL pointer is returned in the
appropriate parameter.
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.

Function Header
int dshGetDocInfo(
void *dsh,
const char *aid,
const char *docid,
int utc_flag,
char **status,
char **c_date,
char **c_time,
char **m_date,
char **m_time,
char **retention,
char **r_date,
char **r_time,
int *is_locked,
int *num_comps,
char **info
);
int dshGetDocInfo2(
void *dsh,
const char *aid,
const char *docid,
int utc_flag,
char **status,
char **c_date,
char **c_time,
char **m_date,
char **m_time,
char **retention,
char **r_date,
char **r_time,
int *on_csrv,

140 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.41. dshGetDocInfo, dshGetDocInfo2: Get status of a document

int *is_locked,
int *is_delayed,
int *num_comps,
char **info
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call
• aid (input)
Archive name
• docid (input)
Document ID
• utc_flag (input)
Specify 0 to get date and time in localtime.
Specify 1 to get date and time in UTC (Greenwich time).
• status (output)
Online status of the document (online, offline)
• c_date (output)
Creation date of the document (date of first archiving), format YYYYMMDD
• c_time (output)
Creation time of the document (time of first archiving), format HHMMSS
• m_date (output)
Modification date of the document (date of most recent archiving), format
YYYYMMDD
• m_time (output)
Modification time of the document (time of most recent archiving), format
HHMMSS
• retention (output)
Retention mode (see “Retention period” on page 24)
In case of a concrete retention period, the value date is returned and the end
date is returned in r_date and r_time.
• r_date (output)
Retention date, if the retention mode is date (format: YYYYMMDD);
otherwise NULL
• r_time (output)
Retention time, if the retention mode is date (format: HHMMSS);
otherwise NULL
• on_csrv (output, dshGetDocInfo2 only)
Name of the Archive Cache Server where the document is stored if it is not
yet on Archive Server
• is_locked (output)

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 141
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Lock status
• is_delayed (output, dshGetDocInfo2 only)
Information on whether the status of the document in delayed archiving
mode:
1: The document does not use that mode or has already been finally stored in
the archive.
0: The document is waiting for the final archiving.
• num_comps (output)
Number of components
• info (output)
Component information (see dshDsInfo(), dshCompInfo())

Return values
1: Function completed successfully.
2: Document is unknown.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)
• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_INFO (11020):
HTTP error (conflict [409]): Administrative data is inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

142 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.41. dshGetDocInfo, dshGetDocInfo2: Get status of a document

Example
Get the status information for document d1 in archive A1
char *status, *c_date, *c_time, *m_date, *m_time,
*retention, *r_date, *r_time, *on_csrv, *info;
int is_locked, is_delayed, num_comps;
int ret = dshGetDocInfo2(dsh,"A1","d1",0,&status,&c_date,
&c_time,&m_date,&m_time,
&retention,&r_date,&r_time,
&on_csrv,&is_locked,&is_delayed,
&num_comps,&info);

Related Functions
• “dshDsInfo: Get info string for document/Component” on page 86

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 143
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.42 dshGetDocStatus: Get information on

document
Purpose
Returns information on a document including:

• the document status

• the document type (see “Document/component formats (renditions, file
types)” on page 19)
• the archiving date and time
• the number of components (but not their names, see note below)

Note: To retrieve the names of the document components, use the

dshDsInfo and dshCompInfo function pair.

Function Header
int dshGetDocStatus(
void *dsh,
const char *aid,
const char *docid,
char *status,
char *type,
char *ar_date,
char *ar_time,
int utc_flag,
int *num_comps
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• status (output)
Document status, which may be one of the following values:
ONLINE, OFFLINE, UNKNOWN, ERROR.
Must be allocated by the calling application with a size >= 21 bytes.
• type (output)
File type of the document (stored in the type document attribute; see also
“Document/component formats (renditions, file types)” on page 19).
Must be allocated by the calling application with a size >= 41 bytes.
• ar_date (output)
Date of (most recent) archiving; format: YYYYMMDD.

144 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.42. dshGetDocStatus: Get information on document

Must be allocated by the calling application with: size = 9 bytes.

• ar_time (output)
Time of (most recent) archiving. format: HHMMSS
Must be allocated by the calling application with a size = 7 bytes.
• utc_flag (input)
Specify 0 to get date and time in localtime.
Specify 1 to get date and time in UTC (Greenwich time).
• num_comps (output)
number of all components of document

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)
• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409_INFO (11020):
HTTP error (conflict [409]): Administrative data is inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 145
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Example
Get information on document d1 in archive A1:

int num_comps = 0;
char status[21], type[41], ar_date[9], ar_time[7];
int ret = dshGetDocStatus(dsh,"A1","d1",status,type,
ar_date,ar_time,0,&num_comps);

Related Functions
• “dshGetCompStatus: Get information on component” on page 136

See also “Grouped function list” on page 28.

146 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.43. dshGetExpTimeSecKey: Get expiration time of SecKey

3.43 dshGetExpTimeSecKey: Get expiration time of

SecKey
Purpose
Returns the expiration time span, which is assigned to SecKeys when they are
transmitted.
The default value is 3600; the unit is seconds.

Notes
• Use the dshSetExpTimeSecKey function to change the expiration time
span.
• See “Access protection via SecKeys (signed URLs)” on page 22and
“SecKey handling in libdsh” on page 31 for details on the use of SecKeys.

Function Header
int dshGetExpTimeSecKey(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Expiration time of SecKeys in seconds

Example

int expiration_time = dshGetExpTimeSecKey(dsh);

Related Functions
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 147
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.44 dshGetLastErrno: Get error number

Purpose
Returns the error number of the most recent error which occurred during a
libdsh function call.
For an overview of all errors that may occur in libdsh functions, see “libdsh
errors in numerical order” on page 236 or “libdsh error messages in alphabetical
order” on page 234, respectively.
If you prefer to receive an error message instead of an error number (for
example, to present it to the user), use the dshGetLastError function instead of,
or after, the dshGetLastErrno function.
After each call of a libdsh function, you should check, whether the return value
is 0 or NULL, respectively; if so, you should call dshGetLastErrno to get more
details on the error, and you should implement appropriate actions for each
error situation that may occur at the respective function call (This is the reason
why the function descriptions provide an Errors which might occur overview).

Notes
• The error code buffer is not reset, if you call dshGetLastErrno or
dshGetLastError. If you want to reset it, use the dshClearLastError
function.
• Some functions, particularly those used in getting and setting properties
within libdsh, dshExit, dshClose, dshFree) do not provide any return
value or explicit error condition. The dshGetProxy function does not
return NULL in case of an error; instead, it returns the empty string "".
• See also “Function parameters and return values” on page 36.

Function Header
int dshGetLastErrno(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Error number of the last function call that has failed.
0: No error information available (see “Error handling” on page 35).
Example:
Get the size of component c1 of document d1 in archive A1, check whether an
error occurred and react on it if necessary:

char *size = dshGetCompSize(dsh,"A1","d1","c1");

if (size == NULL) {
int errno = dshGetLastErrno(dsh)
switch (errno)
{

148 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.44. dshGetLastErrno: Get error number

case DSH_ERR_ACCESS_FILE : ...; break;

case DSH_ERR_UNKNOWN_ARCHIVE : ...; break;
case DSH_ERR_ADD_MIME_PARSER : ...; break;
case DSH_ERR_UNKNOWN_COMP : ...; break;
case DSH_ERR_HTTP_400 : ...; break;
case DSH_ERR_HTTP_401 : ...; break;
case DSH_ERR_HTTP_404 : ...; break;
case DSH_ERR_HTTP_409 : ...; break;
case DSH_ERR_HTTP_500 : ...; break;
case DSH_ERR_HTTP_CONNECTION_BROKEN: ...; break;
case DSH_ERR_HTTP_UNKNOWN : ...; break;
default : ...; break;
}
} else {
...
dshFree(size);
}

See also “Sample programs in detail” on page 198 (whch however use the
dshGetLastError function instead of dshGetLastErrno).

Related Functions
• “dshGetLastError: Get error message” on page 150
• “dshClearLastError: Clear last error message ” on page 39

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 149
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.45 dshGetLastError: Get error message

Purpose
Returns the error message of the most recent error which occurred during a
libdsh function call. See also “dshGetLastErrno: Get error number”
on page 148 for further information.
For an overview of all errors that may occur in libdsh functions, see “libdsh
errors in numerical order” on page 236 or “libdsh error messages in alphabetical
order” on page 234, respectively.
Use the dshGetLastErrno function if you want to get the error number (integer)
instead of the error message.

Notes

• The error code buffer is not reset, if you call dshGetLastErrno or

dshGetLastError. If you want to explicitly reset it, use the
dshClearLastError function.
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.

Function Header
char * dshGetLastError(void *dsh);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Error string of last libdsh function call that has failed
NULL: No error information available (see “Error handling” on page 35).

Example
After evaluating the error situation (see “dshGetLastErrno: Get error
number” on page 148), you may use the code below to provide an error message
for the user:

if (dshDsGetPart(...) == 0) {
char * message = dshGetLastError(dsh);
printf("ERROR: %s\n", message);
dshFree(message);
}

See also the examples in “Archive Server API in practice“ on page 193

Related Functions

• “dshGetLastErrno: Get error number” on page 148

• “dshClearLastError: Clear last error message ” on page 39

150 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.45. dshGetLastError: Get error message

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 151
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.46 dshGetMimeType: Convert to MIME type

Purpose
This function converts a file type string (document/component type) of the
proprietary style (for example, ALF, OTF or FAX) to its corresponding MIME type,
according to the conventions used by the DS.
See “Document/component formats (renditions, file types)” on page 19 for
details. That section also provides the assignment table (known file/MIME
types) used by libdsh.
Instead of a file type specification (or in addition to it), you can also hand over a
component name in the compid parameter. If this component name (or the type/
name combination specified via the parameters, respectively) corresponds to the
DS naming conventions and a unique MIME type is assigned to it, this MIME
type is returned.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string.

Function Header
char * dshGetMimeType(
void *dsh,
const char *doc_type,
const char *compid,
const char *comp_type
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• doc_type (input)
Document type.
Specify NULL or "" if unkown.
• compid (input)
Component name.
Specify NULL or "" if unkown.
• comp_type (input)
Component type.
Specify NULL or "" if unkown.

Return values
MIME type on success.
NULL: Error; use the dshGetLastErrno function to obtain further error
information.
Errors that may occur
• DSH_ERR_OUT_OF_MEMORY (11204):

152 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.46. dshGetMimeType: Convert to MIME type

Out of memory

For an overview of all error messages, see “libdsh errors” on page 234.

Example
1. Get corresponding MIME type for old component type ALF (without relation
to a concrete document/component):

char * mime_type = dshGetMimeType(dsh,NULL,NULL,"ALF");

...
dshFree(mime_type);

The returned value (before calling dshFree) is text/x-ascii_note.

2. Get the MIME type for component im:

char * mime_type = dshGetMimeType(dsh,NULL,"im",NULL);

...
dshFree(mime_type);

The returned value (before calling dshFree) is application/x-alf.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 153
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.47 dshGetPrivateKeyFile: Get filename of private

key
Purpose
Returns the filename of the file containing the private key. The private key is
required to access documents that are protected via SecKeys.
Before calling this function you must have set the private key file via the
dshSetPrivateKeyFile() function.

Notes
• Call dshFree() to free the memory buffer that has been allocated for the
returned string.
• See “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for details on the use of SecKeys.

Function Header
char *dshGetPrivateKeyFile(void);

Parameters
none

Return values
Filename of the private key on success.
NULL: The specified file could not be found (or the function failed due to another,
unknown error).

Example
Get the filename of the private key:

char *filename = dshGetPrivateKeyFile();

...
dshFree(filename);

Related Functions
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187

See also “Grouped function list” on page 28.

154 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.48. dshGetProxy: Get proxy server

3.48 dshGetProxy: Get proxy server

Purpose
Returns the URL of the proxy server set for the local client (for example,
http://misha:8080, see also “Proxy server” on page 13).
Use the dshSetProxy function to set (or change) the proxy server.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string. Note that even the memory allocated for an empty
returned string must be freed by the calling application.

Function Header
char * dshGetProxy(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
Name of the proxy server if set.
Empty string "" if no proxy server has been set before.

Example

char *proxy = dshGetProxy(dsh);

...
dshFree(proxy);

Related Functions
• “dshSetProxy: Set proxy server” on page 190

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 155
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.49 dshGetUser: Get user name

Purpose
Returns the name of the current user set in libdsh. This name is used for
accounting in the DS; it does not serve for authorization purposes and is not
validated anywhere.
Use the dshSetUser function to set or change the user name in libdsh. When no
explicit user is set, libdsh transmits the hostname of the local client as the user to
the DS for accounting.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string.

Function Header
char * dshGetUser(void *dsh);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.

Return values
User name on success.
NULL on error (Out of memory; not retrievable via dshGetLastErrNo or
dshGetLastError)

Example
Get user name:

char *user = dshGetUser(dsh);

...
dshFree(user);

Related Functions
• “dshSetUser: Set user name” on page 191

See also “Grouped function list” on page 28.

156 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.50. dshGetVersion: Get major and minor version number of libdsh

3.50 dshGetVersion: Get major and minor version

number of libdsh
Purpose
Returns (via its parameters) the major and minor version number and build
number string of the libdsh library.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned build_string parameter.

Function Header
void dshGetVersion(
int *major,
int *minor,
char **build_string
);

Parameters
• major (output)
Major version number of the libdsh library
• minor (output)
Minor version number of the libdsh library
• build_string (output)
Build number string (for example, 4.2.2001.0131)

Return values
No return values

Example

int major, minor;

char *build;
dshGetVersion(&major, &minor, &build);
...
dshFree(build);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 157
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.51 dshExtendRetention: Extend retention of a

document
Purpose
Extends the retention period of an already archived document. The retention
parameter can be set to one of the following values:
infinite
Retention is set to infinite.
event
Retention is set to event-based (period will be set by
dshDsSetDocumentFlag).

<n> days
Retention is set to <n> days.
Function Header
int dshExtendRetention(
void *dsh,
const char *aid,
const char *docid,
const char *retention
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call
• aid (input)
Archive name
• docid (input)
Document name
• retention (input)
Retention period of document. Value={infinite, event, <n days>}:
infinite: retention set to infinite
event: retention set to event-based
<n days>: retention set to <n> days

Return values
1: Function completed successfully.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter

158 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.51. dshExtendRetention: Extend retention of a document

• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234..

Example
Extend retention period of document d1 of archive A1 to 720 days (2 years):

int ret = dshExtendRetention(dsh,"A1","d1","720");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 159
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.52 dshIsArchive: Verify existence of an archive

Purpose
Verifies the existence of a (logical)[5] archive (“Does archive <xx> exist?”).

Function Header
int dshIsArchive(
void *dsh,
const char *aid
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name

Return values
1: The specified archive exists.
2: The specified archive is unknown.
0: Error; use the dshGetLastErrno function to obtain further error information.

Errors that may occur

• DSH_ERR_HTTP_EMPTY_RESULT (11002):
Wrong (empty) result from archive server
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.
[5] see “Logical archives, pools, storage tiers” on page 12

160 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.52. dshIsArchive: Verify existence of an archive

Example
Check the existence of archive A1:

int ret = dshIsArchive(dsh,"A1");

if ( ret == 1 ) { /* archive exists */ }

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 161
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.53 dshIsComp: Verify existence of a component

Purpose
Verifies the existence of a component (“Does component <xx> of document
<yy> exist?”).

Note: To check for the existence of a document, use the dshDsInfo

function – see “dshDsInfo: Get info string for document/Component”
on page 86 for details.

Function Header
int dshIsComp(
void *dsh,
const char *aid,
const char *docid,
const char *compid
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document ID
• compid (input)
Component name

Return values
1: The specified component exists.
2: The specified component is unknown.
0: Error; use the dshGetLastErrno function to obtain further error information

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_FUNCTION_ARGUMENT (11203):
Wrong function argument (for example, NULL pointer)
• DSH_ERR_HTTP_PARSE_HEADER (11001):
Error in parsing HTTP header
• DSH_ERR_UNKNOWN_COMP (11209):
Unknown component

162 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.53. dshIsComp: Verify existence of a component

• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the server.

Example
Check, whether component c1 of document d1, located in archive A1, exists:

int ret = dshIsComp(dsh,"A1","d1","c1);

if ( ret == 1 ) {
// component exists
}

Related Functions
• “dshDsInfo: Get info string for document/Component” on page 86

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 163
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.54 dshIstreamClose: Close stream for reading a

component
Purpose
Closes stream that was opened for reading by dshIstreamOpen to free allocated
resources.

Function Header
int dshIstreamClose(
void *dsh,
void *hd
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• hd (input)
Handle, received from function dshIstreamOpen

Return values
0: success
NULL: Error; use the dshGetLastErrno function to obtain further error
information

Errors that may occur

• DSH_ERR_FUNCTION_ARGUMENT:
Wrong function argument (for example, NULL pointer)
• DSH_ERR_DELETE_MUTEX:
Cannot delete mutex object
• DSH_ERR_DELETE_EVENT:
Cannot delete event object

For an overview of all error messages, see “libdsh errors” on page 234.

Example
Read component c1 of document d1 in archive A1 using streaming and print
content to stdout (Note: dsh received from dshOpen2):

...
void *hd = dshIstreamOpen(dsh,"A1","d1","c1",NULL);
char buf[1000+1];
int len = 0;
while ( (len=dshIstreamRead(dsh,hd,buf,1000)) > 0 ) {
print("%*s",len,buf);
}
int ret = dshIstreamClose(dsh,hd);

164 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.55. dshIstreamOpen, dshIstreamOpen2, dshIstreamOpenPart,
dshIstreamOpenPart2: Open stream for reading a component

3.55 dshIstreamOpen, dshIstreamOpen2,

dshIstreamOpenPart, dshIstreamOpenPart2:
Open stream for reading a component
Purpose
Open stream for reading a component of a document from Archive Server.

Notes
• Call dshIstreamClose() to free context and mutex resources!
• The reading will always stop at the end of the component. Therefore,
you will get less bytes than specified by parameter length if the sum of
offset and length is exceeding the size of component.

Function Header
void * dshIstreamOpen(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *rms
);
void * dshIstreamOpen2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
const char *rms
const char *origid
);
void * dshIstreamOpenPart(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
int64_t offset,
int64_t length,
const char *rms
const char *origid
);
void * dshIstreamOpenPart2(
void *dsh,
const char *aid,
const char *docid,
const char *compid,
int64_t offset,

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 165
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

int64_t length,
const char *rms
const char *origid
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• aid (input)
Archive name
• docid (input)
Document name
• compid (input)
Component name
• offset (input)
Offset to read from; value must be larger than or equal to 0
• length (input)
Number of bytes to be read; value must be larger than 0
• rms (input)
Access token for Rights Management Services (RMS). For internal use only –
set to NULL.
• origid (input; dshIstreamOpen2, dshIstreamOpenPart,
dshIstreamOpenPart2 only)
Originator of request. Set to "" or NULL if not used.

Return values
Stream handle on success
NULL: Error; use the dshGetLastErrno function to obtain further error
information

Errors that may occur

• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):

166 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.55. dshIstreamOpen, dshIstreamOpen2, dshIstreamOpenPart,
dshIstreamOpenPart2: Open stream for reading a component

HTTP error (conflict [409]): Document/component/administrat. data is

inaccessible
• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.
• DSH_ERR_OUT_OF_MEMORY (11204):
Out of memory
• DSH_ERR_CREATE_THREAD
Error in creating a thread

For an overview of all error messages, see “libdsh errors” on page 234.

Example
Read 10000 bytes, starting at offset 10, from component c1 of document d1 of
archive A1 using streaming and print content to stdout:

...
void *hd = dshIstreamOpenPart(dsh,"A1","d1","c1",10L,
10000L, NULL);
char buf[1000+1];
int len = 0;
while ( (len=dshIstreamRead(dsh,hd,buf,1000)) > 0 ) {
print("%*s",len,buf);
}
int ret = dshIstreamClose(dsh,hd);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 167
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.56 dshIstreamRead: Read opened stream

Purpose
Attempt to read n bytes (nbyte) from opened stream associated with the handle
that was returned by dshIstreamOpen(), and place the read bytes into the
buffer buf.
Function Header
int dshIstreamRead (
void *dsh,
void *context,
void *buf,
unsigned int nbyte
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• context (input)
Context object (handle) received from dshIstreamOpen()
• buf (input)
Buffer to read in, must be allocated by caller
• nbyte (input)
Number of bytes to read from stream and write into buffer buf

Return values
Number of read bytes where special value
0 means EOF reached
-1 means error; use the dshGetLastErrno function to obtain further error
information.
Errors that may occur
• DSH_ERR_ACCESS_FILE (11207):
Error in accessing file
• DSH_ERR_UNKNOWN_ARCHIVE (11206):
Unknown archive
• DSH_ERR_HTTP_400 (11005):
HTTP error (bad request [400]): Unknown function or parameter
• DSH_ERR_HTTP_401 (11006):
HTTP error (unauthorized [401]): Breach of security
• DSH_ERR_HTTP_404 (11008):
HTTP error (not found [404]): Document/component/archive not found
• DSH_ERR_HTTP_409 (11010):
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible

168 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.56. dshIstreamRead: Read opened stream

• DSH_ERR_HTTP_500 (11012):
HTTP error (Internal Server Error [500]): Internal error in archive server
• DSH_ERR_HTTP_CONNECTION_BROKEN (11003):
HTTP error: connection was broken
• DSH_ERR_HTTP_UNKNOWN (11004):
HTTP error: unknown error
• DSH_ERR_HTTP_560_ONTAPE
HTTP error (document not accessible [560]): The document cannot be
accessed because it is on tape.
• DSH_ERR_FUNCTION_ARGUMENT:
Wrong function argument (for example, NULL pointer)
• DSH_ERR_READ_FROM_CLOSED_STREAM
Stream to read from is closed

For an overview of all error messages, see “libdsh errors” on page 234.

SecKey access mode

Requires read access permission for the document on the repository server.

Example
Read data via streaming and print result to stdout (dsh received from
dshIstreamOpen()):

...
void *hd = dshIstreamOpen(dsh,"A1","doc1","data",NULL);
char buf[1000+1];
int len = 0;
while ( (len=dshIstreamRead(dsh,hd,buf,1000)) > 0 ) {
print("%*s",len,buf);
}
dshIstreamClose(dsh,hd);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 169
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.57 dshOpen, dshOpen2: Open connection to

repository server
dshOpen and dshOpen2 open a connection to the ADMS/DS on the primary_host
repository server. In other words, they establish a communication session between
libdsh and Archive Server and thus are the first function call in a libdsh session
(apart from functions for logging or local settings).

With Archive Server version 9.7, an alternative, more flexible concept has been
introduced to connect to Archive Server, which is reflected by the alternative
function call dshOpen2 in libdsh_3. For programs addressing Archive Server
version 9.7 or higher, you should preferably refer to dshOpen2; dshOpen currently is
still supported, but might be discontinued with a later release.

3.57.1 dshOpen
Purpose
Opens a connection to the ADMS/DS on the primary_host repository server
according to the fixed addressing concept used before Archive Server version
9.7.
If the connection to the primary_host server fails and another server is specified
in secondary_host, libdsh will try to connect to this server instead. You should
also take into account that the server you are trying to connect to may be
temporarily unavailable, for example, due to a short network problem or a boot
process. Therefore you should keep trying to call the function for a certain
period, if the connection establishment fails.

Notes
• The parameters specified in this function call are used only for initially
connecting to Archive Server. As soon as the connection has been
established, libdsh loads a list of the available Archive Servers and refers
to this list later on (for example, if the connection gets lost).
• Call dshClose() at the end of the session/application or when you no
longer need the connection to the primary_host Archive Server.
• If permitted by the server, you may choose the transmission protocol to
be used, in the protocol parameter. But even when you are using the
HTTPS protocol, you must specify the HTTP ports in the respective
parameters, not the HTTPS ports.
• The function also initializes the libdsh library itself, if it is called for the
first time (see also “Initializing and ending a libdsh session” on page 32).

Function Header
void *dshOpen(
const char *primary_host,
const char *secondary_host,
int http_port_adms,

170 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.57. dshOpen, dshOpen2: Open connection to repository server

int http_port_ds,
const char *protocol,
const char *user,
const char *application
);

Parameters

• primary_host (input)
Hostname of the next (primary) Archive Server (DS/ADMS)
• secondary_host (input)
Hostname of a secondary (replication) server; specify NULL if no secondary
server is available.
This host will only be connected, if the connection to the primary server fails.
• http_port_adms (input)
HTTP port number of ADMS (do not specify a HTTPS port, see above).

Note: If connecting to Archive Server version 9.7 or higher, this

parameter is ignored, and the DS port value is used for addressing the
ADMS, too.
• http_port_ds (input)
HTTP port number of DS (do not specify a HTTPS port, see above).
• protocol (input)
Specify "HTTP" for a insecure connection or "HTTPS" for a secure connection
(this setting may be ignored by the server).
• user (input)
User name, required for DS accounting (no validation on the server). If you
specify NULL, libdsh will transmit the hostname of the client to the server.
• application (input)
Application name, required for DS accounting. If you specify NULL, libdsh
will transmit “libdsh” to the server.

Return values
A handle, which will be needed for the most other libdsh functions, on success.
NULL: An error occurred.
Please note that the dshGetLastErrno and dshGetLastErrorfunctions cannot
be used in this case, as the error information evaluated by these functions is
assigned to a session (dsh handle) which has not yet been established at this
stage.

Example
Open a secure connection (HTTPS protocol) to server misha. The respective
HTTP ports are 4060 for ADMS and 8080 for DS (so the HTTPS ports, which are
actually used for the communication, are 4061 for ADMS and 8090 for DS):

void *dsh = dshOpen("misha", NULL, 4060, 8080, "https", NULL,

NULL);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 171
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See also the examples in “Archive Server API in practice“ on page 193

Related Functions
• “dshClose: Close connection to repository server” on page 40

See also “Grouped function list” on page 28.

3.57.2 dshOpen2
Purpose
Opens a connection to the ADMS/DS on the primary_host repository server
according to the flexible addressing concept introduced with Archive Server
version 9.7.

Notes
• The parameters specified in this function call are used only for initially
connecting to Archive Server. As soon as the connection has been
established, libdsh loads a list of the available Archive Servers and refers
to this list later on (for example, if the connection gets lost).
• Call dshClose() at the end of the session/application or when you no
longer need the connection to the primary_host Archive Server.
• If permitted by the server, you may choose the transmission protocol to
be used, in the protocol parameter. But even when you are using the
HTTPS protocol, you must specify the HTTP ports in the respective
parameters, not the HTTPS ports.
• The function also initializes the libdsh library itself, if it is called for the
first time (see also “Initializing and ending a libdsh session” on page 32).

Function Header
void *dshOpen2(
const char *archive_server,
const char *protocol,
const int port,
const char *url_path,
const char *user,
const char *application
);

Parameters
• archive_server (input)
Hostname of the next (primary) Archive Server (DS/ADMS)
• protocol (input)
Specify "HTTP" for a insecure connection or "HTTPS" for a secure connection
(this setting may be ignored by the server).
• port (input)

172 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.57. dshOpen, dshOpen2: Open connection to repository server

Port number for the communication to Archive Server

Note: If connecting to Archive Server version lower than 9.7, the ADMS
port is automatically assigned to 4060 (HTTP) or 4061 (HTTPS),
respectively, as required for these versions.

Important
If you used the dshOpen call up to now, take care that you refer to
the correct port with HTTPS: You must no longer specify the HTPP
port here, but the actual HTTPS port.
• url_path (input)
Part of the URL that specifies the server to be addressed, including the
leading slash (for example, “/archive”)
• user (input)
User name, required for DS accounting (no validation on the server). If you
specify NULL, libdsh will transmit the hostname of the client to the server.
• application (input)
Application name, required for DS accounting. If you specify NULL, libdsh
will transmit “libdsh” to the server.

Return values
A handle, which will be needed for the most other libdsh functions, on success.
NULL: An error occurred.
Please note that the dshGetLastErrno and dshGetLastErrorfunctions cannot
be used in this case, as the error information evaluated by these functions is
assigned to a session (dsh handle) which has not yet been established at this
stage.

Example
Open a secure connection (HTTPS) to server misha. The respective HTTPS port
is 8090:

void *dsh = dshOpen2("misha", "https", 8090, "/archive", NULL,

NULL);

See also “dsh_info example: Retrieving information about logical archives”

on page 222

Related Functions
• “dshClose: Close connection to repository server” on page 40

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 173
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.58 dshSetAidRefreshInterval: Set refresh

interval for ADMS info
Purpose
Sets the refresh period for updating information on available repository servers.
The unit is seconds, the default value is 3600 (= 1 hour).

Note: Use the dshGetAidRefreshInterval() function to retrieve the

current setting.

Function Header
void dshSetAidRefreshInterval(
void *dsh,
time_t refresh_interval
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• refresh_interval (input)
Specify the refresh interval in seconds.

Return values
No return values

Example
Set the refresh interval to 10 minutes:

dshSetAidRefreshInterval(dsh,"600");

Related Functions
• “dshGetAidRefreshInterval: Get aid refresh interval” on page 129
• “dshSetAidRefreshTime: Set time of next ADMS info refresh”
on page 175

See also “Grouped function list” on page 28.

174 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.59. dshSetAidRefreshTime: Set time of next ADMS info refresh

3.59 dshSetAidRefreshTime: Set time of next ADMS

info refresh
Purpose
Sets the time for the next update of information on available repository servers.
Specify the desired time as the number of seconds since 00:00 h Coordinated
Universal Time (UTC) on January 1, 1970. If you want to trigger an immediate
update, specify refresh_time=0. (The update is executed, if the current time
exceeds the specified time)

Notes

• dshSetAidRefreshTime also restarts the refresh interval, so the next

automatic refresh will not take place until the refresh interval, that you
have specified via the dshSetAidRefreshInterval function, has
elapsed.
• Use the dshGetAidRefreshTime() function to retrieve the current
setting.

Function Header
void dshSetAidRefreshTime(
void *dsh,
time_t refresh_time
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• refresh_time (input)
Refresh time (in seconds since January 1, 1970, 00:00 h)

Return values
No return values

Example
Set refresh time of next update to “now” + 10 minutes:

#include time.h
time_t refresh_time = time(NULL) + 300;
dshSetAidRefreshTime(dsh,refresh_time);

Related Functions

• “dshGetAidRefreshTime: Get time of next ADMS info refresh ”

on page 130
• “dshSetAidRefreshInterval: Set refresh interval for ADMS info”
on page 174

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 175
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

See also “Grouped function list” on page 28.

176 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.60. dshSetApplication: Set application name

3.60 dshSetApplication: Set application name

Purpose
Sets the application name within the libdsh library. This name is required for
accounting in DS.
As long as no explicit application is set, libdsh transmits “libdsh” as the
application name to the DS for accounting.

Note: Use the dshGetApplication() function to retrieve the current

application name setting.

Function Header
void dshSetApplication(
void *dsh,
const char *application
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• application (input)
Application name to be used for DS accounting.

Return values
No return values

Example
Set application name to IXOS-VIEWER:

dshSetApplication(dsh,"IXOS-VIEWER");

Related Functions
• “dshGetApplication: Get application name” on page 131

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 177
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.61 dshSetAuthId: Set authenticity

Purpose
Sets the client identifier for the local client; this identifier is required when
accessing documents that are protected via SecKeys. The default value of this
identifier is the current hostname.

Notes

• See “Access protection via SecKeys (signed URLs)” on page 22 and

“SecKey handling in libdsh” on page 31 for details on the use of SecKeys.
• Use the dshSetAuthId() function to retrieve the current client identifier
setting.

Function Header
void dshSetAuthId(
void *dsh,
const char *auth_id
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• auth_id (input)
Specify the client identifier to be used for SecKey authentification.

Return values
No return values

Example
Set client identifier to C11:

dshSetAuthId(dsh,"C11");

Related Functions

• “dshGetAuthId: Get authenticity ID of client” on page 132

• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182
• “dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”
on page 94

See also “Grouped function list” on page 28.

178 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.62. dshSetCertificate, dshSetCertificateFile: Set certificate

3.62 dshSetCertificate,
dshSetCertificateFile: Set certificate
Purpose
Introduces the digital certificate into the libdsh library; the digital certificate is
required when accessing documents that are protected via SecKeys.
The certificate may be read either from a memory buffer (dshSetCertificate)
or from a file (dshSetCertificateFile) – see Parameters below for details.

Note: Apart from being introduced locally, the certificate must also be
transferred to the respective repository server via dshDsPutCert or
dshDsPutCertFile before the first document protected via SecKeys can be
requested.
In addition you must specify a private key (via dshSetPriateKey), a client
identifier (via dshSetAuthId) and an expiration time (via
dshSetExpTimeSecKey); these are also required for building SecKey
requests.
See also “Access protection via SecKeys (signed URLs)” on page 22 and
“SecKey handling in libdsh” on page 31 for further details.

Function Header
void dshSetCertificateFile(const char *path);
void dshSetCertificate(
const unsigned char *cert_buf,
int cer_len
);

Parameters
• path (input)
Certificate file to be read; the file must correspond to the PEM standard
(RFC1424, see [2 on page 225] in “Further information sources” on page 225
for details).
• cert_buf (input)
Memory buffer containing the certificate data to be read. The certificate data
must be encoded according to the Distinguished Encoding Rules (DER, see [3
on page 225] in “Further information sources” on page 225).
• cert_len (input)
Length of cert_buf (number of bytes)

Return values
No return values
Example
Read the certificate from the cert.pem file:

dshSetCertificateFile("cert.pem");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 179
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

Related Functions
• “dshGetCertificateFile: Get filename of certificate” on page 133
• “dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”
on page 94
• “dshGetAuthId: Get authenticity ID of client” on page 132
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179

See also “Grouped function list” on page 28.

180 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.63. dshSetConfig: Set value of global configuration variable

3.63 dshSetConfig: Set value of global configuration

variable
Purpose
Sets value <value> for the libdsh configuration variable specified in <key> for
the current session. See “Global environment variables” on page 228 for a list of
these variables, their meaning and admissible values.

Note: Call dshFree() to free the memory buffer that has been allocated for
the returned string.

Function Header
int dshSetConfig(
void *dsh,
const char *key,
const char *value
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• key (input)
Name of the variable to be set
• value (input)
Value to be set

Return values
1: Function completed successfully.
2: Invalid key parameter
3: Invalid value parameter
0: Other error

Example
Set value on for the global HTTP log-setting LOG_DSH:

int ret = dshSetConfig(dsh,"LOG_DSH", "on");

Related Functions
• “dshGetConfig: Get value of global configuration variable” on page 139

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 181
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.64 dshSetExpTimeSecKey: Set expiration time for

SecKey
Purpose
Sets the expiration time for SecKey requests. The unit is seconds.

Note: Apart from setting the expiration time, further settings are required
before you can access documents that are protected via SecKeys. See also
“Access protection via SecKeys (signed URLs)” on page 22 and “SecKey
handling in libdsh” on page 31 for further details.

Function Header
void dshSetExpTimeSecKey(
void *dsh,
int seconds
);

Parameters

• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• seconds (input)
Expiration time for SecKey requests (in seconds)

Return values
No return values

Example
Set the expiration time for SecKey requests to 10 minutes:

dshSetExpTimeSecKey(dsh,600);

Related Functions

• “dshGetExpTimeSecKey: Get expiration time of SecKey” on page 147

• “dshGetAuthId: Get authenticity ID of client” on page 132
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshSetPrivateKey, dshSetPrivateKeyFile: Set private key”
on page 187
• “dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”
on page 94
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179

See also “Grouped function list” on page 28.

182 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.65. dshSetLogFile: Set log file

3.65 dshSetLogFile: Set log file

Purpose
Sets the path and file name of the libdsh log file. If no log file is specified, libdsh
writes all log messages to STDERR; therefore dshSetLogFile should be called
before dshOpen.

Important
• See “Logging” on page 32 for further details on logging.
• This function redirects the STDERR stream to the specified file. As a
consequence, all output sent to STDERR by your own application is
written to the log file, too.

Function Header
int dshSetLogFile(const char *file);

Parameters
• file (input)
Path and file name of the log file to be used. Both an absolute path
specification or a relative path specification (related to the working directory
of your application) are admissible.

Return values
1: Function completed successfully.
0: An error occurred.
Please note that the dshGetLastErrno and dshGetLastError functions cannot
be used in this case, as the error information evaluated by these functions is
assigned to a session (dsh handle) which has not yet been established at this
stage.

Example
Set log file to libdsh.txt:

dshSetLogFile("libdsh.txt");

Related Functions
• “dshSetLogMaxSize: Set maximum size of log file” on page 186
• “dshSetLogLevel: Set log level” on page 184

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 183
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.66 dshSetLogLevel: Set log level

Purpose
Enables or disables one of the three log channels known as INFO, DEBUG and
ENTRY. In other words, it determines whether messages assigned to the channel
specified in the level parameter are logged or not (on_or_off).

Important

• If you do not specify a log file (via dshSetLogFile), messages are

written to STDERR.
• See also “Logging” on page 32 for further details on logging.

Function Header
int dshSetLogLevel(
const char *level,
const char *on_or_off
);

Parameters

• level (input)
Log channel to be enabled or disabled:
INFO for information messages
DEBUG for debug messages
ENTRY for function entries (each function call is logged)
• on_or_off (input)
Specify on for enabling the channel specified in level
Specify off for disabling the channel specified in level

Return values
1: Function completed successfully.
0: An error occurred.
Please note that the dshGetLastErrno and dshGetLastError functions cannot
be used in this case, as the error information evaluated by these functions is
assigned to a session (dsh handle) which has not yet been established at this
stage.

Example
Enable all log channels (full logging):

dshSetLogLevel("INFO","on");
dshSetLogLevel("DEBUG","on");
dshSetLogLevel("ENTRY","on");

Related Functions

• “dshSetLogFile: Set log file” on page 183

• “dshSetLogMaxSize: Set maximum size of log file” on page 186

184 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.66. dshSetLogLevel: Set log level

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 185
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.67 dshSetLogMaxSize: Set maximum size of log

file
Purpose
Sets the maximum size of the <log_file>, specified via dshSetLogFile. If the
file exceeds this size, it is renamed to <log_file>.sav, and a new (empty)
<log_file> file is generated for logging. If there is an older <log_file>.sav
file, it is deleted.

Important

• Regardless of the size you specify, a minimum of 1,000 messages per

process are logged in the log file. “Per process” means that libdsh
starts counting the messages after its initialization process and
ignores the LogMaxSize setting until the counter exceeds 1,000.
• If you do not specify a log file (via dshSetLogFile), the
dshSetLogMaxSize function has no effect.
• See also “Logging” on page 32 for further details on logging.

Function Header
int dshSetMaxLogSize(unsigned long size);

Parameters

• size (input)
Maximum size of the log file in bytes.

Return values
1: Function completed successfully.
0: An error occurred.
Please note that the dshGetLastErrno and dshGetLastError functions cannot
be used in this case, as the error information evaluated by these functions is
assigned to a session (dsh handle) which has not yet been established at this
stage.

Example
Example: Set maximum size of the log file to 5 MB:

dshSetMaxLogSize(5242880);

Related Functions

• “dshSetLogFile: Set log file” on page 183

• “dshSetLogLevel: Set log level” on page 184

See also “Grouped function list” on page 28.

186 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.68. dshSetPrivateKey, dshSetPrivateKeyFile: Set private key

3.68 dshSetPrivateKey, dshSetPrivateKeyFile:

Set private key
Purpose
Sets the private key that is required for building SecKeys (see “Access protection
via SecKeys (signed URLs)” on page 22).
The private key may be read either from a file (dshSetPrivateKeyFile) or from
a memory buffer (dshSetPrivateKey).

Note: Apart from setting the private key, further settings are required
before you can access documents that are protected via SecKeys. See also
“Access protection via SecKeys (signed URLs)” on page 22 and “SecKey
handling in libdsh” on page 31 for further details.

Function Header
void dshSetPrivateKeyFile(const char *path);
void dshSetPrivateKey(
const unsigned char *key_buf,
int key_len
);

Parameters
• path (input)
Private key file; the file must correspond to the PEM standard (RFC1424, see
[2 on page 225] in “Further information sources” on page 225 for details).
• cert_buf (input)
Private key; the data must be encoded according to the Distinguished
Encoding Rules (DER, see [3 on page 225] in “Further information sources”
on page 225).
• cert_len (input)
Length of private key (in number of bytes)

Return values
No return values

Example
Read the private key from the key.pem file:

dshSetPrivateKeyFile("key.pem");

Related Functions
• “dshGetPrivateKeyFile: Get filename of private key” on page 154
• “dshGetAuthId: Get authenticity ID of client” on page 132
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179
• “dshSetExpTimeSecKey: Set expiration time for SecKey” on page 182

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 187
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

• “dshDsPutCert, dshDsPutCertFile: Put certificate to Archive Server”

on page 94
• “dshSetCertificate, dshSetCertificateFile: Set certificate ”
on page 179

See also “Grouped function list” on page 28.

188 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.69. dshSetPrivateKeyPassphrase: Set passphrase to decrypt encrypted private key
file

3.69 dshSetPrivateKeyPassphrase: Set

passphrase to decrypt encrypted private key file
Purpose
Sets the passphrase to decrypt the encrypted private key file handed over via
dshSetPrivateKey or dshSetPrivateKeyFile (see “Access protection via
SecKeys (signed URLs)” on page 22).

Function Header
void dshSetPrivateKeyPassphrase(const char *passphrase);

Parameters
• passphrase (input)
passphrase to decrypt the encrypted private key file

Return values
No return values

Example
The private key file was encrypted with “ixos”:

dshSetPrivateKeyPassphrase("ixos");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 189
AR100500-PSA-EN-3
Chapter 3 libdsh function reference

3.70 dshSetProxy: Set proxy server

Purpose
Sets the URL of the proxy server (for example, http://misha:8080, see also
“Proxy server” on page 13). Note that, after this function call, communication
with the repository server uses the proxy server instead of directly contacting
the repository server. If the proxy server is not available, the repository server
cannot be contacted.

Notes
• Use the dshGetProxy function to get the current proxy server setting.
• If you want to abort the communication via the proxy server, call
dshSetProxy again and specify the empty string ("") in the proxy
parameter.

Function Header
void dshSetProxy(
void *dsh,
const char *proxy
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• proxy (input)
Specify the proxy server to be used, for example, "http://misha:8080".

Return values
No return values

Example

dshSetProxy(dsh,"http://misha:8080");

Related Functions
• “dshGetProxy: Get proxy server” on page 155

See also “Grouped function list” on page 28.

190 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 3.71. dshSetUser: Set user name

3.71 dshSetUser: Set user name

Purpose
Sets the name of the current user. This name is used for accounting in the DS; it
does not serve any authorization purpose and is not validated anywhere.
As long as no explicit user is set, libdsh transmits the hostname of the local client
as user to the DS for accounting.

Note: Use the dshGetUser() function to retrieve the current user name
setting.

Function Header
void dshSetUser(
void *dsh,
const char *user
);

Parameters
• dsh (input)
Class handle, obtained via a preceding dshOpen() call.
• user (input)
Specify the user name, needed for DS accounting

Return values
No return values

Example
Set user name to Gabriel:

dshSetUser(dsh,"Gabriel");

Related Functions
• “dshGetUser: Get user name” on page 156

See also “Grouped function list” on page 28.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 191
AR100500-PSA-EN-3
Chapter 4
Archive Server API in practice

To give you a better idea of how to use libdsh and its functions, this chapter
provides a range of C++ example programs, each of which deals with a specific task,
for example, storing a document in the archive or dealing with document and
component attributes.

Started from The purpose of these example programs is to give you an introduction; therefore
command line they are quite simple and do not provide any comfort as a user would expect today
(but it may be your first exercise to add this comfort...); this also means that they
have no GUI, but are started from a command line.

Basics Before going into detail on the individual programs in “Sample programs in detail”
on page 198, the next two sections provide more basic descriptions:
• “Preparations” on page 194 tells you how to prepare the compilation of libdsh
programs on the supported platforms, for example, include files, linking
preconditions. It also tells you how to get the source code files of the sample
programs and other files that are required for you to compile your applications.
• “Basic structure of the sample programs” on page 197: As all sample programs
have a similar structure, this basic framework is presented in a separate section.
Specific details are described then in the individual program sections.

Equal for all Apart from the linking and compilation differences described in “Preparations”
platforms on page 194, the programs do not apply to a specific platform (operating system), so
you may use them on any supported platform.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 193
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.1 Preparations
4.1.1 Files accompanying this manual
This manual is accompanied by a set of files, that comprise the sample programs as
well as a range of include files, library files and other files required in using the
libdsh library.

KC These files are delivered in a ZIP file libdsh_sdk.zip, which is available for
download from the OpenText Knowledge Center (https://knowledge.opentext.com/
knowledge/llisapi.dll/Open/14841258). Note that you need a separate license to use
this API and thus to access these files.

Structure of Unpack this file in an empty directory anywhere on your hard disk; advice the unzip
serv- tool to maintain the folder structure. A libdsh_sdkfolder is generated that contains
er_API_SDK
a subfolder for each platform supported by libdsh. Within each platform, you will
find the usual structure for auxiliary files such as *.h header files and stub files (see
also next sections). Each platform subfolder also contains an examples subfolder
providing the source files of the sample programs described in “Sample programs in
detail” on page 198. These source code files are identical for all platform apart from
OS-specific differences (end-of-line mark). Even a simple make file is provided for a
common development environment on each platform; this enables you to quickly
compile a program.

Note: For compatibility reasons, most library and link files of software version
9.7 and higher are provided in a new version 3 now, instead of the former
version 2 (or even 1). If you have software projects from older API versions,
please do not forget to update these references, as the version is part of the file
names. See also “Library files” on page 195.

4.1.2 Include file

All public function prototypes of the libdsh library are provided in the platform-
independent header file libdsh.h. This file must be included by your C/C++-source
file:

...
#include "inlcude/libdsh/libdsh.h"
...
int main(int argc, char **argv)
{
...
}

Within the sample program structure of the libdsh_sdk folder, the include file is
located in the include subfolder of the respective platform folder:

libdsh_sdk/<platform>/include/libdsh/libdsh.h

(see also “Files accompanying this manual” on page 194).

194 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.1. Preparations

4.1.3 Library files

Enabling For each supported platform, the libdsh functionality is provided by two dynamic
access to linked libraries (DLL) or shared libraries (the naming depends on the operating
shared library /
DLL files
system), which must be made available to your applications. On most platforms, this
is done via a special environment variable of the operating system (OS). You must
either put these libraray files in a directory listed in this variable, or you must
append the path of the directory where you are placing these files, to this variable.
The respective variable may be changed locally (as in the examples in “Sample
programs in detail” on page 198) or globally in the Windows Control Panel (System
icon, Environment tab) or the .profile or .bashrc configuration file of your UNIX
shell, respectively.

The following table lists both the file names of the DLL/shared library and the
environment variable described above for each supported platform.

Within the sample program structure of the libdsh_sdk folder, the library files are
located in the lib subfolder of the respective platform folder:

libdsh_sdk/<platform>/lib/...

(see also “Files accompanying this manual” on page 194).

Platform/OS libdsh DLL/shared Environment Variable leading

library files to DLL/shared libraries[a]
Windows libLog_3MD.dll, Path
libdsh_3MD.dll,
libcrypto_2MD.dll, or put libdsh DLLs to the
libdsh_3MD.lib, %SystemRoot%\system32
libcurl_1MD.dll,, directory or into the directory of
libssl_2MD.dll, your application.

Oracle Solaris (64 Bit) libLog_3.so, LD_LIBRARY_PATH

libdsh_3.so,
libcrypto_2.so,
libcurl_1.so,
libssl_2.so
Hewlett-Packard UNIX libLog_3.so, LD_LIBRARY_PATH
Itanium libdsh_3.so
libcrypto_2.so,
libcurl_1.so,
libssl_2.so
IBM AIX (64 Bit) libLog_3.so, LIBPATH
libdsh_3.so
libcrypto_2.so,
libcurl_1.so,
libssl_2.so

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 195
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

Platform/OS libdsh DLL/shared Environment Variable leading

library files to DLL/shared libraries[a]
Linux (64 Bit) libLog_3.so, LIBPATH
libdsh_3.so
libcrypto_2.so,
libneon_0_26_1_2.so,
libssl_2.so
[a] (see text above for details)

4.1.4 Linking
To adapt the platform-independent libdsh library to the platform-specific
communication, a stub file is required to link your applications. The following table
lists the respective stub file name for each supported platform as well as the specific
link command and options for a commonly used linker program; foo represents
your program.

Note that only the Windows platform requires that you provide the stub file; on
UNIX platforms, the stub information is provided by the shared libraries, which
must therefore be linked with your application.

Within the sample program structure of the libdsh_sdk folder, the stub file for
Windows is located in the libdsh_sdk/windows/lib folder (see also “Files
accompanying this manual” on page 194).

Platform/OS libdsh library stub files Link program (foo) with libdsh
for linking
Linker
Windows PC / libdsh_3MD.lib link foo.obj
(Windows2003) libdsh_3MD.lib

Microsoft DevStudio (maybe you must add /

link with link LIBPATH:... for linking with
Microsoft libraries)
SUN / Solaris (64 Bit) Link to libdsh_3.so shared CC ‑o foo*.o libdsh_3.so
library, which provides the
SUN Workshop link stub information (LD_LIBRARY_PATH must
with CC contain the path of the libdsh
shared libraries)
Linux (64 Bit) Link to libdsh_3.so shared g++ ‑o foo *.o libdsh_3.so
library, which provides the
GNU Compiler g++ stub information (LD_LIBRARY_PATH must
contain the path of the libdsh
shared libraries)
HP / HP-UX Itanium Link to libdsh_3.so shared aCC ‑o foo*.o libdsh_3.so
library, which provides the
HP link with aCC stub information

196 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.2. Basic structure of the sample programs

Platform/OS libdsh library stub files Link program (foo) with libdsh
for linking
Linker
IBM / AIX (64 Bit) Link to libdsh_3.so shared xlC ‑o foo*.o libdsh_3.so
library, which provides the
IBM link with xlC stub information

4.2 Basic structure of the sample programs

All sample programs have a similar basic structure:
• After including the basic C++ header files stdio.h and string.h and the
libdsh.h file (see “Include file” on page 194), the main struct begins with a set of
initial settings and declarations.
• Then the program parameters (command line options) are parsed in a while
loop; because all options are selected via respective option flags (e.g., –a <aid>),
the order of the options is arbitrary.
• The found parameter value set is validated, and if a parameter is missing or has
an invalid value, a usage message is presented and the program exits.
• The connection to the repository server (which must be specified via the –h
option of each program) is established via the dshOpen function, presuming that
the server uses the default settings for the communication, HTTP protocol; see
also “Initializing and ending a libdsh session” on page 32). If the dshOpen
function fails, an error message is presented.
• Now, the core functionality of the program is executed (see Internal Structure:
Details of the individual sections in “Sample programs in detail” on page 198).
• Finally, the connection to the repository server is closed via the dshClose
function, and all resources previously allocated by libdsh are released via the
dshExit function.

Note: It may happen, that dshExit cannot release resources that have been
allocated directly by your application, due to different ownership.
Therefore, you should always explicitly release resources you have
allocated: Apply the dshFree function to resources allocated by a libdsh
function, and the free standard function on other resources (see also
“Function parameters and return values” on page 36).

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 197
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3 Sample programs in detail

The next sections present the individual sample programs, describe their usage, and
list their code. They also provide a Test steps section, which may help you to become
familiar with both the sample program itself and the reactions of the repository
server.

Note: The Test steps section relates to a Sun Solaris (UNIX) environment, but is
valid in principle for any supported platform.[1] The only differences are a
different way of calling the compiler in the first step of the section (see “Library
files” on page 195) and a different means of declaring the shared library
directory to your OS environment in the second step (“Linking” on page 196).

Each section deals with one sample program, each demonstrating a certain kind of
application. The source code for all sample programs is available as separate files, so
you need not re-type them (see “Files accompanying this manual” on page 194). You
can to modify the sample programs for learning or to reuse parts of the code in your
own applications.

Important
If possible, you should not use a life system storing relevant data for learning
or for testing your applications; if you do, you risk losing data and even
entire documents!

If you cannot use a separate system for testing, ask the administrator of your
archive system to establish a separate logical archive for your purposes and
use this archive exclusively.

[1] By the way: The “%” character used in the examples is the standard command prompt.

198 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

4.3.1 dsh_put example: Archiving files in a single document

Purpose
This example demonstrates how to store one or more files as a single document
in the <aid> archive.
You may specify a Document ID via the –d option, if you want to append the
files as additional components to an existing document (see Test example below)
or if you want to generate a new document with a specific Document ID. In the
latter case, it is your responsibility to ensure that the Document ID you specify
does not interfere with existing or future Document IDs.

Note: Note that the first component usually is interpreted as the main
component (see “Main component” on page 15). Therefore always store the
main component at first.

Source code file

The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_put.cxx
(see also “Files accompanying this manual” on page 194).

Usage
dsh_put ‑h <host> ‑a <aid> ‑f {<file>} [-d <docid>]
Options:

-h <host> hostname <host> of the archive server

-a <aid> archive name
-f {<file>} source file[s] to archive
-d <docid> optional: Document ID

Source code (dsh_put.cxx)

1 volatile static char *dsh_put_id = "$Id";
2
3 #include <stdio.h>
4 #include <string.h>
5 #include "libdsh/libdsh.h"
6
7
8 int main(int argc, char **argv)
9 {
10 int ret;
11 int i = 1;
12 char host[100] = "";
13 char aid [10] = "";
14 char docid[100] = "";
15 char file[10][256] = {"","","","","","","","","",""};
16 int nr_files = 0;
17
18 //-------------------------
19 // parse program parameters
20 //-------------------------
21 while( i < argc ) {
22 //------------------------
23 // get archive server name
24 //------------------------
25 if ( strcmp(argv[i],"-h") == 0 ) {
26 if ( ++i < argc ) {
27 strcpy(host,argv[i++]);

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 199
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

28 }
29 //---------------
30 // get archive id
31 //---------------
32 } else if ( strcmp(argv[i],"-a") == 0 ) {
33 if ( ++i < argc ) {
34 strcpy(aid,argv[i++]);
35 }
36 //---------------------
37 // get docid (optional)
38 //---------------------
39 } else if ( strcmp(argv[i],"-d") == 0 ) {
40 if ( ++i < argc ) {
41 strcpy(docid,argv[i++]);
42 }
43 //----------
44 // get files
45 //----------
46 } else if ( strcmp(argv[i],"-f") == 0 ) {
47 while ( (++i < argc) && (nr_files<10) ) {
48 if ( *argv[i] == '-' ) {
49 break;
50 }
51 strcpy(file[nr_files++],argv[i]);
52 }
53 } else {
54 printf("wrong program parameter\n");
55 break;
56 }
57 }
58 //--------------------------
59 // verify program parameters
60 //--------------------------
61 if ( (strlen(host) == 0) ||
62 (strlen(aid) == 0) ||
63 (strlen(file[0]) == 0) ) {
64 printf("\n");
65 printf("usage: %s -h <host> -a <aid> -f {<file>} [-d <docid>]\n",
66 argv[0]);
67 printf("\n");
68 printf("options:\n");
69 printf(" -h <host> hostname <host> of archive server.\n");
70 printf(" -a <aid> archive.\n");
71 printf(" -f {<file>} source file[s] to archive.\n");
72 printf(" -d <docid> optional: document id\n");
73 printf("\n");
74 printf("description: archive files in a document. The filename\n");
75 printf(" will also be taken as component name.\n");
76 printf("\n");
77 return 1;
78 }
79
80 //----------------------
81 // initialize Server API
82 //----------------------
83 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
84 if ( dsh == NULL ) {
85 //-----------------------------
86 // archive server not reachable
87 //-----------------------------
88 printf("error: archive server '%s' not reachable\n",host);
89 return 1;
90 }
91
92 //----------------------------
93 // store files in one document
94 //----------------------------
95 for ( int j=0; j<nr_files; j++ ) {
96 if ( (ret=dshDsCreateFile(dsh,aid,docid,file[j],
97 "application/octet-stream",file[j],"")) == 0 ) {
98 //--------------------
99 // print error message
100 //--------------------
101 printf("error: %s\n",dshGetLastError(dsh));
102 return 1;
103 }
104 }
105

200 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

106 //----------------
107 // free Server API
108 //----------------
109 dshClose(dsh);
110 dshExit();
111
112 printf("file[s] successfully archived in document '%s'\n",docid);
113 return 0;
114 }
115

Test example (Solaris)

1. Create program:
CC ‑o dsh_put dsh_put.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).
% set LD_LIBRARY_PATH[2]="$LD_LIBRARY_PATH;<path to shared libs>"
% export LD_LIBRARY_PATH

3. Send two files file1 and file2 to the A1 archive on the host1 server:

% dsh_put ‑h host1 ‑a A1 ‑f file1 file2

file[s] successful archived in document
'aaaakfsn4jidxcqfvaaa14mv4ocwk'[3]
%

4. Write down (copy/paste) the ID of the document returned by the program.

You will need it in the next step and later on to retrieve this document.

5. Add file file3 as a new component to the document you archived

previously:

% dsh_put‑h host1‑a A1‑f file3‑d <docid returned by Step 3>

file[s] successful archived in document '<docid returned by
Step 3>'
%

Internal structure: Details

In a for loop, the files are stored via the dshDsCreateFile function. If several
files are stored in a new document (no docid parameter specified), note that this
function re-uses the docid parameter that has been returned after the first call.

[2] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

[3] The Document ID will differ on your system, of course.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 201
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3.2 dsh_get example: Get all archived files of a document/

retrieve component information
Purpose
This example demonstrates how to retrieve files (i.e. components) of a document
on the repository server; by using the –i option, you retrieve the component
information only, without loading the component contents.
Source code file
The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_get.cxx
(see also “Files accompanying this manual” on page 194).
Usage
dsh_get ‑h <host> ‑a <aid> ‑d <docid> [-i]
Options:

-h <host> hostname <host> of repository server

-a <aid> archive name
-d <docid> Document ID
-i optional: print component information only.

Source code (dsh_get.cxx)

1 volatile static char *dsh_get_id = "$Id";
2
3 #include <stdio.h>
4 #include <string.h>
5 #include "libdsh/libdsh.h"
6
7
8 int main(int argc, char **argv)
9 {
10 int ret;
11 int i = 1;
12 char host[100] = "";
13 char aid[10] = "";
14 char docid[100] = "";
15 int i_option_flag= 0;
16
17 //-------------------------
18 // parse program parameters
19 //-------------------------
20 while( i < argc ) {
21 //------------------------
22 // get archive server name
23 //------------------------
24 if ( strcmp(argv[i],"-h") == 0 ) {
25 if ( ++i < argc ) {
26 strcpy(host,argv[i++]);
27 }
28 //---------------
29 // get archive id
30 //---------------
31 } else if ( strcmp(argv[i],"-a") == 0 ) {
32 if ( ++i < argc ) {
33 strcpy(aid,argv[i++]);
34 }
35 //----------
36 // get docid
37 //----------
38 } else if ( strcmp(argv[i],"-d") == 0 ) {
39 if ( ++i < argc ) {

202 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

40 strcpy(docid,argv[i++]);
41 }
42 //-------------------------------
43 // i-option (only show comp-info)
44 //-------------------------------
45 } else if ( strcmp(argv[i],"-i") == 0 ) {
46 i_option_flag = 1;
47 ++i;
48 } else {
49 printf("wrong program parameter\n");
50 break;
51 }
52 }
53 //--------------------------
54 // verify program parameters
55 //--------------------------
56 if ( (strlen(host) == 0) ||
57 (strlen(aid) == 0) ||
58 (strlen(docid) == 0) ) {
59 printf("\n");
60 printf("usage: %s -h <host> -a <aid> -d <docid> [-i]\n",argv[0]);
61 printf("\n");
62 printf("options:\n");
63 printf(" -h <host> hostname of archive server.\n");
64 printf(" -a <aid> archive.\n");
65 printf(" -d <docid> document id.\n");
66 printf(" -i optional: only print component information.\n");
67 printf("\n");
68 printf("description: get all files/components of a document \n");
69 printf(" and print component information to stdout.\n");
70 printf(" If i-option set, we only display information.\n");
71 printf("\n");
72 return 1;
73 }
74
75 //----------------------
76 // initialize Server API
77 //----------------------
78 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
79 if ( dsh == NULL ) {
80 //-----------------------------
81 // archive server not reachable
82 //-----------------------------
83 printf("error: archive server '%s' not reachable\n",host);
84 return 1;
85 }
86
87 //---------------------------------------------------
88 // get all components and print information to stdout
89 //---------------------------------------------------
90 char *info = dshDsInfo(dsh,aid,docid,"");
91 if ( info == NULL ) {
92 printf("error: can't get info of document '%s': %s\n",docid,
93 dshGetLastError(dsh));
94 return 1;
95 }
96 char *name;
97 char *status;
98 char *type;
99 char *c_date;
100 char *c_time;
101 char *m_date;
102 char *m_time;
103 char *length;
104 int version;
105 char *vol_name;
106 char *sig_object;
107 int heading_flag = 0;
108 while( (ret=dshCompInfo(dsh,&info,0,&name,&status,&type,
109 &c_date,&c_time,&m_date,&m_time,
110 &length,&version,&vol_name,&sig_object)) == 1 ) {
111 //----------------------------
112 // print component information
113 //----------------------------
114 if ( heading_flag == 0 ) {
115 heading_flag = 1;
116 printf("Status Date Time Size Type "
117 " Name\n");

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 203
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

118 printf("-----------------------------------------"
119 "---------------------------\n");
120 }
121 printf("%-8s %-8s %-6s %-8s %-24s %s\n",status,c_date,c_time,length,
122 type,name);
123 if ( i_option_flag == 1 ) {
124 //--------------------
125 // don't get component
126 //--------------------
127 dshFree(name);
128 dshFree(status);
129 dshFree(type);
130 dshFree(c_date);
131 dshFree(c_time);
132 dshFree(m_date);
133 dshFree(m_time);
134 dshFree(length);
135 dshFree(vol_name);
136 dshFree(sig_object);
137 continue;
138 }
139 //----------------------------
140 // get component (no i-option)
141 //----------------------------
142
143 if ( dshDsGetFile(dsh,aid,docid,name,name) == 0 ) {
144 printf("error: can't get component '%s' of document '%s': %s\n",
145 name,docid,dshGetLastError(dsh));
146 dshFree(save_info);
147 dshFree(name);
148 dshFree(status);
149 dshFree(type);
150 dshFree(c_date);
151 dshFree(c_time);
152 dshFree(m_date);
153 dshFree(m_time);
154 dshFree(length);
155 dshFree(vol_name);
156 dshFree(sig_object);
157 return 1;
158 }
159 dshFree(name);
160 dshFree(status);
161 dshFree(type);
162 dshFree(c_date);
163 dshFree(c_time);
164 dshFree(m_date);
165 dshFree(m_time);
166 dshFree(length);
167 dshFree(vol_name);
168 dshFree(sig_object);
169 }
170 if ( ret == 0 ) {
171 printf("error: can't get component status of document '%s': %s\n",
172 docid,dshGetLastError(dsh));
173 return 1;
174 }
175
176 //----------------
177 // free Server API
178 //----------------
179 dshClose(dsh);
180 dshExit();
181
182 return 0;
183

Test example (Solaris)

1. Create program:
CC ‑o dsh_get dsh_get.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).

204 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

% set LD_LIBRARY_PATH[4]="$LD_LIBRARY_PATH;<path to shared libs>"

% export LD_LIBRARY_PATH

3. Get all files/components of the document <docid> that you sent to the
archive in the dsh_put example page 201:

% dsh_get ‑h host1 ‑a A1 ‑d <docid>

Status Date Time Size Type Name
--------------------------------------------------------------------
ONLINE 20011004 150106 124 application/octet-stream file2
ONLINE 20011004 150051 124 application/octet-stream file1
%

4. Get the name, file size and type, and archiving date and time for all
components of this document, without loading the components themselves
(-i option):

% dsh_get ‑h host1 ‑a A1 ‑d <docid> ‑i

Status Date Time Size Type Name
--------------------------------------------------------------------
ONLINE 20011004 150106 124 application/octet-stream file2
ONLINE 20011004 150051 124 application/octet-stream file1
%

Internal structure: Details

First, the dshDsInfo function is called to retrieve the document information, in
particular for getting the number and names of the contained components at all.
The dshCompInfo function evaluates the document information and feeds a
while loop, which then does the following for each contained document
component:
• It prints some information data on the component.
• Unless the –i flag option has been used (info retrieval only), the component
is retrieved from the server via the dsh function and stored in a file named
<compid> (last parameter of the dsh function). Note that the file is stored in
the local directory.

[4] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 205
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3.3 dsh_append example: Append data to an archived file

Purpose
This example demonstrates how to append data to a document component that
has already been stored on the server. In contrast to the dsh_put example, the
data is not directly taken over from a file, but is the contents of a memory buffer
(which however has been filled from the <file> file before, in this example)

Source code file

The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_append.cxx
(see also “Files accompanying this manual” on page 194).

Usage
dsh_append ‑h <host> ‑a <aid> ‑d <docid> ‑c <comp> -f <file>
Options:

-h <host> hostname <host> of the repository server

-a <aid> archive name
-d <docid> Document ID
-c <comp> destination component name
-f <file>] source file

Source code (dsh_append.cxx)

1 volatile static char *dsh_append_id = "$Id";
2
3 #include <stdio.h>
4 #include <string.h>
5 #include "libdsh/libdsh.h"
6
7
8 int main(int argc, char **argv)
9 {
10 int i = 1;
11 char host[100] = "";
12 char aid[10] = "";
13 char docid[100] = "";
14 char compid[100]= "";
15 char file[256] = "";
16
17 //-------------------------
18 // parse program parameters
19 //-------------------------
20 while( i < argc ) {
21 //------------------------
22 // get archive server name
23 //------------------------
24 if ( strcmp(argv[i],"-h") == 0 ) {
25 if ( ++i < argc ) {
26 strcpy(host,argv[i++]);
27 }
28 //---------------
29 // get archive id
30 //---------------
31 } else if ( strcmp(argv[i],"-a") == 0 ) {
32 if ( ++i < argc ) {
33 strcpy(aid,argv[i++]);
34 }
35 //----------
36 // get docid
37 //----------

206 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

38 } else if ( strcmp(argv[i],"-d") == 0 ) {
39 if ( ++i < argc ) {
40 strcpy(docid,argv[i++]);
41 }
42 //--------------
43 // get component
44 //--------------
45 } else if ( strcmp(argv[i],"-c") == 0 ) {
46 if ( ++i < argc ) {
47 strcpy(compid,argv[i++]);
48 }
49 //-------------------
50 // get file to append
51 //-------------------
52 } else if ( strcmp(argv[i],"-f") == 0 ) {
53 if ( ++i < argc ) {
54 strcpy(file,argv[i++]);
55 }
56 } else {
57 printf("wrong program parameter\n");
58 break;
59 }
60 }
61 //--------------------------
62 // verify program parameters
63 //--------------------------
64 if ( (strlen(host) == 0) ||
65 (strlen(aid) == 0) ||
66 (strlen(docid) == 0) ||
67 (strlen(compid) == 0) ||
68 (strlen(file) == 0) ) {
69 printf("\n");
70 printf("usage: %s -h <host> -a <aid> -d <docid> -c <comp> -f <file>\n",
71 argv[0]);
72 printf("\n");
73 printf("options:\n");
74 printf(" -h <host> hostname of archive server.\n");
75 printf(" -a <aid> archive.\n");
76 printf(" -d <docid> document id.\n");
77 printf(" -c <comp> destination component.\n");
78 printf(" -f <file> source file.\n");
79 printf("\n");
80
81 printf("description: append file <file> to archived component\n");
82 printf(" <comp> of document <docid>\n");
83 printf("\n");
84 return 1;
85 }
86
87 //----------------------
88 // initialize Server API
89 //----------------------
90 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
91 if ( dsh == NULL ) {
92 //-------------------
93 // host not reachable
94 //-------------------
95 printf("error: archive server '%s' not reachable\n",host);
96 return 1;
97 }
98
99 //-------------------------
100 // append file to component
101 //-------------------------
102 if ( dshDsAppendFile(dsh,aid,docid,compid,file) == 0 ) {
103 printf("error: can't append file: %s\n",dshGetLastError(dsh));
104 return 1;
105 }
106
107 //----------------
108 // free Server API
109 //----------------
110 dshClose(dsh);
111 dshExit();
112
113 return 0;
114

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 207
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

Test example (Solaris)

1. Create program:
CC ‑o dsh_append dsh_append.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).
% set LD_LIBRARY_PATH[5]="$LD_LIBRARY_PATH;<path to shared libs>"
% export LD_LIBRARY_PATH

3. Read the contents of the file4 file to a memory buffer. Then append the
contents of this memory buffer to the file1 component of the document
<docid> that you sent to the archive in the dsh_put example page 201:

% dsh_append ‑h host1 ‑a A1 ‑d <docid> ‑c file1 ‑f file4

%

Internal structure: Details

This program simply applies the dshDsAppendFile function.

[5] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

208 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

4.3.4 dsh_attribute example: dealing with document

attributes
Purpose
This example demonstrates how to set (= change), obtain and delete attributes of
documents and components.

Note: If you operate in an OpenText TCP system, but want to keep the
attribute naming as used in archive-centric systems, a name mapping must
be defined via the Server Configuration.

Source code file

The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_attribute.cxx
(see also “Files accompanying this manual” on page 194).

Usage
usage: dsh_attribute ‑h<host> ‑a <aid> ‑d<docid> [-c <comp>]
( [-g [<attr>]] | [-s <attr>=<value>] | [-r <attr>] )
Options:

-h <host> hostname <host> of the repository server

-a <aid> archive name
-d <docid> Document ID
-c <comp> component name
-g [<attr>] get attribute. Get all attributes, if <attr> is not specified.
-s <attr>=<value>
set (change) attribute.
-r <attr> delete attribute

Source code (dsh_attribute.cxx)

1 volatile static char *dsh_attribute_id = "$Id";
2
3 #include <stdio.h>
4 #include <string.h>
5 #include "libdsh/libdsh.h"
6
7
8 int main(int argc, char **argv)
9 {
10 int ret;
11 int i = 1;
12 char host[100] = "";
13 char aid [10] = "";
14 char docid[100] = "";
15 char compid[100] = "";
16 char attr[100] = "";
17 char attr_value[100] = "";
18 int get_flag = 0;
19 int set_flag = 0;
20 int del_flag = 0;
21
22 //-------------------------
23 // parse program parameters

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 209
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

24 //-------------------------
25 while( i < argc ) {
26 //------------------------
27 // get archive server name
28 //------------------------
29 if ( strcmp(argv[i],"-h") == 0 ) {
30 if ( ++i < argc ) {
31 strcpy(host,argv[i++]);
32 }
33 //---------------
34 // get archive id
35 //---------------
36 } else if ( strcmp(argv[i],"-a") == 0 ) {
37 if ( ++i < argc ) {
38 strcpy(aid,argv[i++]);
39 }
40 //----------
41 // get docid
42 //----------
43 } else if ( strcmp(argv[i],"-d") == 0 ) {
44 if ( ++i < argc ) {
45 strcpy(docid,argv[i++]);
46 }
47 //--------------
48 // get attribute
49 //--------------
50 } else if ( strcmp(argv[i],"-g") == 0 ) {
51 get_flag = 1;
52 if ( ++i < argc ) {
53 if ( *argv[i] != '-' ) {
54 strcpy(attr,argv[i++]);
55 }
56 }
57 //---------------------------------------
58 // set attribute (-s <attribute>=<value>)
59 //---------------------------------------
60 } else if ( strcmp(argv[i],"-s") == 0 ) {
61 set_flag = 1;
62 if ( ++i < argc ) {
63 char *cp = strchr(argv[i],'=');
64 if ( cp != NULL ) {
65 strncpy(attr,argv[i],cp-argv[i]);
66 strcpy(attr_value,cp+1);
67 }
68 i++;
69 }
70 //-----------------
71 // delete attribute
72 //-----------------
73 } else if ( strcmp(argv[i],"-r") == 0 ) {
74 del_flag = 1;
75 if ( ++i < argc ) {
76 strcpy(attr,argv[i++]);
77 }
78 //-------------------------
79 // get component (optional)
80 //-------------------------
81 } else if ( strcmp(argv[i],"-c") == 0 ) {
82 if ( ++i < argc ) {
83 strcpy(compid,argv[i++]);
84 }
85 } else {
86 printf("wrong program parameter\n");
87 break;
88 }
89 }
90 //--------------------------
91 // verify program parameters
92 //--------------------------
93 if ( (strlen(host) == 0) ||
94 (strlen(aid) == 0) ||
95 (strlen(docid) == 0) ||
96 (set_flag + get_flag + del_flag != 1 ) ) {
97 printf("\n");
98 printf("usage: %s -h <host> -a <aid> -d <docid> [-c <comp>] \n"
99 " ([-g [<attr>]]|[-s <attr>=<value>]|[-r <attr>])"
100 "\n",argv[0]);
101 printf("\n");

210 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

102 printf("options:\n");
103 printf(" -h <host> hostname <host> of archive server.\n");
104 printf(" -a <aid> archive.\n");
105 printf(" -d <docid> document id.\n");
106 printf(" -c <comp> optional: component name.\n");
107 printf(" -g [<attr>] get attribute. Get all attributes,\n");
108 printf(" if <attr> was not specified.\n");
109 printf(" -s <attr>=<value> set (change) attribute.\n");
110 printf(" -r <attr> delete attribute.\n");
111 printf("\n");
112 printf("description: get/set/delete attribute(s) of a document\n");
113 printf(" (no c-option) or a component (c-option).\n");
114 printf("\n");
115 return 1;
116 }
117
118 //----------------------
119 // initialize Server API
120 //----------------------
121 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
122 if ( dsh == NULL ) {
123 //-----------------------------
124 // archive server not reachable
125 //-----------------------------
126 printf("error: archive server '%s' not reachable\n",host);
127 return 1;
128 }
129
130 //-----------------
131 // get attribute(s)
132 //-----------------
133 if ( get_flag == 1 ) {
134 char *pattr;
135 if ( (pattr=dshDsGetAttribute(dsh,aid,docid,compid,attr)) == NULL ) {
136 //--------------------
137 // print error message
138 //--------------------
139 printf("error: %s\n",dshGetLastError(dsh));
140 return 1;
141 }
142 printf("%s\n",pattr);
143 dshFree(pattr);
144
145 //--------------
146 // set attribute
147 //--------------
148 } else if ( set_flag == 1 ) {
149 if ((ret=dshDsSetAttribute(dsh,aid,docid,compid,attr,attr_value))==0){
150 //--------------------
151 // print error message
152 //--------------------
153 printf("error: %s\n",dshGetLastError(dsh));
154 return 1;
155 }
156
157 //-----------------
158 // delete attribute
159 //-----------------
160 } else {
161 if ( (ret=dshDsDelAttribute(dsh,aid,docid,compid,attr)) == 0 ) {
162 //--------------------
163 // print error message
164 //--------------------
165 printf("error: %s\n",dshGetLastError(dsh));
166 return 1;
167 }
168 }
169
170 //----------------
171 // free Server API
172 //----------------
173 dshClose(dsh);
174 dshExit();
175
176 return 0;
177 }
178
179

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 211
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

Test example (Solaris)

1. Create program:
CC ‑o dsh_attribute dsh_attribute.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).
% set LD_LIBRARY_PATH[6]="$LD_LIBRARY_PATH;<path to shared libs>"
% export LD_LIBRARY_PATH

3. Create an attribute Author with value Gabriel and another attribute

Version with value 1.0 for the document <docid> that you sent to the
archive in the dsh_put example page 201:
% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑s Author=Gabriel
% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑s Version=1.0
%

4. Retrieve the value of the Author attribute of the document:

% dsh_attribute ‑h host1 ‑a A1 ‑<docid>d ‑g Author
Author="Gabriel";
%

5. Retrieve all attributes of the document:

% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑g
Author="Gabriel";Version="1.0";
%

6. Delete the Author attribute of the document:

% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑r Author
%

7. Again, retrieve all attributes of the document (the Author attribute should
no longer be listed):
% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑g
Version="1.0";
%

8. Create a new attribute Age with value 5 for the file1 component of the
document:

% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑c file1 ‑s Age=5

%

9. Get all attributes of the file1 component of the document:

% dsh_attribute ‑h host1 ‑a A1 ‑d <docid> ‑g ‑c file1
Age="5";
%

Note that no document attributes (Version) are listed.

[6] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

212 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

Internal structure: Details

This program simply applies the dshDsSetAttribute, dshDsGetAttribute or
dshDsDelAttribute function, depending on the options specified in the
command line.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 213
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3.5 dsh_search example: Searching and getting the found

piece of data
Purpose
This example demonstrates how to search for a pattern in a component and, on
success, how to retrieve some bytes of the found piece of data in the component.

Source code file

The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_search.cxx
(see also “Files accompanying this manual” on page 194).

Usage
usage: dsh_search ‑h <host> ‑a <aid> ‑d <docid> ‑c <comp> ‑p <pattern>
[-n <bytes>]
Options:

-h <host> hostname <host> of the repository server

-a <aid> archive name
-d <docid> Document ID
-c <comp> component name
-p <pattern> search pattern
-n <bytes> optional: number of bytes to be returned (default=10)

Source code (dsh_search.cxx)

1 volatile static char *dsh_search_id = "$Id";
2
3 #include <stdio.h>
4 #include <stdlib.h>
5 #include <string.h>
6 #include "libdsh/libdsh.h"
7
8
9 int main(int argc, char **argv)
10 {
11 int i = 1;
12 char host[100] = "";
13 char aid [10] = "";
14 char docid[100] = "";
15 char compid[100] = "";
16 char pattern[100] = "";
17 int nr_of_bytes = 10;
18
19 //-------------------------
20 // parse program parameters
21 //-------------------------
22 while( i < argc ) {
23 //------------------------
24 // get archive server name
25 //------------------------
26 if ( strcmp(argv[i],"-h") == 0 ) {
27 if ( ++i < argc ) {
28 strcpy(host,argv[i++]);
29 }
30 //---------------
31 // get archive id
32 //---------------
33 } else if ( strcmp(argv[i],"-a") == 0 ) {
34 if ( ++i < argc ) {

214 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

35 strcpy(aid,argv[i++]);
36 }
37 //----------
38 // get docid
39 //----------
40 } else if ( strcmp(argv[i],"-d") == 0 ) {
41 if ( ++i < argc ) {
42 strcpy(docid,argv[i++]);
43 }
44 //--------------
45 // get component
46 //--------------
47 } else if ( strcmp(argv[i],"-c") == 0 ) {
48 if ( ++i < argc ) {
49 strcpy(compid,argv[i++]);
50 }
51 //------------
52 // get pattern
53 //------------
54 } else if ( strcmp(argv[i],"-p") == 0 ) {
55 if ( ++i < argc ) {
56 strcpy(pattern,argv[i++]);
57 }
58 //-----------------------
59 // number of bytes to get
60 //-----------------------
61 } else if ( strcmp(argv[i],"-n") == 0 ) {
62 if ( ++i < argc ) {
63 nr_of_bytes = atoi(argv[i++]);
64 }
65 } else {
66 printf("wrong program parameter\n");
67 break;
68 }
69 }
70 //--------------------------
71 // verify program parameters
72 //--------------------------
73 if ( (strlen(host) == 0) ||
74 (strlen(aid) == 0) ||
75 (strlen(docid) == 0) ||
76 (strlen(compid) == 0) ||
77 (strlen(pattern) == 0) ) {
78 printf("\n");
79 printf("usage: %s -h <host> -a <aid> -d <docid> -c <comp>\n",argv[0]);
80 printf(" -p <pattern> [-n <bytes>]\n");
81 printf("\n");
82 printf("options:\n");
83 printf(" -h <host> hostname <host> of archive server.\n");
84 printf(" -a <aid> archive.\n");
85 printf(" -d <docid> document id.\n");
86 printf(" -c <comp> component name.\n");
87 printf(" -p <pattern> search pattern.\n");
88 printf(" -n <bytes> number of bytes to get (default=10)\n");
89 printf("\n");
90 printf("description: search for a pattern in a component. On \n");
91 printf(" success we will print some bytes (<bytes>)\n");
92 printf(" of the found passages from component.\n");
93 printf("\n");
94 return 1;
95 }
96
97 //----------------------
98 // initialize Server API
99 //----------------------
100 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
101 if ( dsh == NULL ) {
102 //-----------------------------
103 // archive server not reachable
104 //-----------------------------
105 printf("error: archive server '%s' not reachable\n",host);
106 return 1;
107 }
108
109 //------------------------------------
110 // search for pattern (case sensitive)
111 //------------------------------------
112 char *result;

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 215
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

113 if ( (result=dshDsSearch(dsh,aid,docid,compid,pattern,0,-1,20,1))==NULL ) {
114 //--------------------
115 // print error message
116 //--------------------
117 printf("error: %s\n",dshGetLastError(dsh));
118 return 1;
119 }
120
121 //---------------------------------------------
122 // parse search result and print found passages
123 //---------------------------------------------
124 char *cp = result;
125 for ( int j=atoi(cp); j>0; j-- ) {
126 //----------------------
127 // get next found offset
128 //----------------------
129 if ( ((cp=strchr(cp,';')) == NULL) || (++cp == '\0') ) {
130 break;
131 }
132 size_t offset = atoi(cp);
133
134 //----------------------------
135 // get and print found passage
136 //----------------------------
137 char *buffer = NULL;
138 int size;
139 if ( dshDsGetPart(dsh,aid,docid,compid,offset,
140 nr_of_bytes,&buffer,&size) == 0 ) {
141 //--------------------
142 // print error message
143 //--------------------
144 printf("error: %s\n",dshGetLastError(dsh));
145 return 1;
146 }
147 printf("offset=%ld size=%d passage='%s'\n",offset,size,buffer);
148
149 //-----------------
150 // free data buffer
151 //-----------------
152 dshFree(buffer);
153 }
154
155 //-------------------
156 // free search result
157 //-------------------
158 dshFree(result);
159
160 //----------------
161 // free Server API
162 //----------------
163 dshClose(dsh);
164 dshExit();
165
166 return 0;
167 }
168
169

Test example (Solaris)

1. Create program:
CC ‑o dsh_search dsh_search.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).
% set LD_LIBRARY_PATH[7]="$LD_LIBRARY_PATH;<path to shared libs>"
% export LD_LIBRARY_PATH

[7] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

216 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

3. As a prerequisite to searching, first store the C++ source file

dsh_search.cxx in the archive and memorize the resulting Document ID.
% dsh_put ‑h host1 ‑a A1 ‑c dsh_search.cxx
file[s] successfully archived in document 'aaaat62sgqctxcqfvabltl3v4ocwk'[8]
%

Write down (copy/paste) the returned Document ID for use in the next step.

4. Then search for the pattern dshDs in the archived component:

% dsh_search ‑h host1 ‑a A1 ‑d <docid returned by step Step 3> ‑c dsh_search.cxx ‑p dshDs
‑n 20
offset=3698 size=20 passage='dshDsSearch(dsh,aid,'
offset=4580 size=20 passage='dshDsGetPart(dsh,aid'
%

Internal structure: Details

First, the dshDsSearch function is called to find all locations in the component
that match the search pattern. Note that – in contrast to most other functions – a
char pointer must be declared for the result of the dshDsSearch function before
the function is called. No memory must be allocated for this pointer, because it is
done by the dshDsSearch function itself, but the pointer must be freed via the
dshFree function before the end of the program.
As described in “dshDsSearch, dshDsSearch2: Search in component”
on page 102, the resulting string returned by dshDsSearch has the following
format:
number of hits(= n);offset of hit 1;...;offset of hit n;
By using a copy (cp) of this string and parsing this cp variable, a for loop is
controlled: The atoi function in the for loop definition returns the number of
hits (as it is the first part of the search result, ending with a semicolon) and thus
defines the number of for cycles.
Within each cycle,
• the for loop uses strchr for stepping to the next “;” within cp,
• and excerpts the next integer value – i.e. the offset of the individual hits – via
atoi.
• Then it calls the dshDsGetPart function to retrieve from the components the
number of bytes (nr_of_bytes) as specified by the user, starting at the
relevant offset.
• These bytes are stored in a buffer which again must be declared beforehand
and must be freed after usage.

[8] The Document ID will differ on your system, of course.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 217
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3.6 dsh_lock example: Locking/unlocking documents

Purpose
This example demonstrates how to set and unset the locked flag for a
document.
Source code file
The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_lock.cxx
(see also “Files accompanying this manual” on page 194).
Usage
usage: dsh_lock ‑h <host> ‑a <aid> ‑d <docid> ( ‑l [<locker>] |
‑u [<locker>] )
Options:

-h <host> hostname <host> of the repository server

-a <aid> archive name
-d <docid> Document ID
-l [<locker>] lock (optional: locker string).
-u [<locker>] unlock (optional: locker string)

Source code (dsh_lock.cxx)

1 volatile static char *dsh_lock_id = "$Id";
2
3 #include <stdio.h>
4 #include <stdlib.h>
5 #include <string.h>
6 #include "libdsh/libdsh.h"
7
8
9 int main(int argc, char **argv)
10 {
11 int i = 1;
12 int ret;
13 char host[100] = "";
14 char aid [10] = "";
15 char docid[100] = "";
16 char locker[100] = "";
17 int lock_flag = 0;
18 int unlock_flag = 0;
19
20 //-------------------------
21 // parse program parameters
22 //-------------------------
23 while( i < argc ) {
24 //------------------------
25 // get archive server name
26 //------------------------
27 if ( strcmp(argv[i],"-h") == 0 ) {
28 if ( ++i < argc ) {
29 strcpy(host,argv[i++]);
30 }
31 //---------------
32 // get archive id
33 //---------------
34 } else if ( strcmp(argv[i],"-a") == 0 ) {
35 if ( ++i < argc ) {
36 strcpy(aid,argv[i++]);
37 }
38 //----------
39 // get docid

218 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

40 //----------
41 } else if ( strcmp(argv[i],"-d") == 0 ) {
42 if ( ++i < argc ) {
43 strcpy(docid,argv[i++]);
44 }
45 //---------------------------------------------
46 // lock document (optional: with locker string)
47 //---------------------------------------------
48 } else if ( strcmp(argv[i],"-l") == 0 ) {
49 lock_flag = 1;
50 if ( ++i < argc ) {
51 if ( *argv[i] != '-' ) {
52 strcpy(locker,argv[i++]);
53 }
54 }
55 //-----------------------------------------------
56 // unlock document (optional: with locker string)
57 //-----------------------------------------------
58 } else if ( strcmp(argv[i],"-u") == 0 ) {
59 unlock_flag = 1;
60 if ( ++i < argc ) {
61 if ( *argv[i] != '-' ) {
62 strcpy(locker,argv[i++]);
63 }
64 }
65 } else {
66 printf("wrong program parameter\n");
67 break;
68 }
69 }
70 //--------------------------
71 // verify program parameters
72 //--------------------------
73 if ( (strlen(host) == 0) ||
74 (strlen(aid) == 0) ||
75 (strlen(docid) == 0) ||
76 ((lock_flag + unlock_flag) != 1) ) {
77 printf("\n");
78 printf("usage: %s -h <host> -a <aid> -d <docid>\n",argv[0]);
79 printf(" ( -l [<locker>] | -u [<locker>] )\n");
80 printf("\n");
81 printf("options:\n");
82 printf(" -h <host> hostname <host> of archive server.\n");
83 printf(" -a <aid> archive.\n");
84 printf(" -d <docid> document id.\n");
85 printf(" -l [<locker>] lock (optional: locker string)\n");
86 printf(" -u [<locker>] unlock (optional: locker string)\n");
87 printf("\n");
88 printf("description: lock or unlock document. If <locker> string\n");
89 printf(" is left empty, then everyone will be able\n");
90 printf(" to unlock the document!\n");
91 printf("\n");
92 return 1;
93 }
94
95 //----------------------
96 // initialize Server API
97 //----------------------
98 void *dsh = dshOpen(host,NULL,4060,8080,"http","user",*argv);
99 if ( dsh == NULL ) {
100 //-----------------------------
101 // archive server not reachable
102 //-----------------------------
103 printf("error: archive server '%s' not reachable\n",host);
104 return 1;
105 }
106
107 //--------------
108 // lock document
109 //--------------
110 if ( lock_flag == 1 ) {
111 if ( (ret=dshDsLock(dsh,aid,docid,locker)) == 0 ) {
112 //--------------------
113 // print error message
114 //--------------------
115 printf("error: %s\n",dshGetLastError(dsh));
116 return 1;
117 }

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 219
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

118 //-------------------------
119 // document already locked?
120 //-------------------------
121 if ( ret == 2 ) {
122 printf("warning: document is already locked\n");
123 } else {
124 printf("success: document is locked\n");
125 }
126
127 //----------------
128 // unlock document
129 //----------------
130 } else {
131 if ( (ret=dshDsUnlock(dsh,aid,docid,locker,"no")) == 0 ) {
132 //--------------------
133 // print error message
134 //--------------------
135 printf("error: %s\n",dshGetLastError(dsh));
136 return 1;
137 }
138 switch ( ret ) {
139 case 1:
140 printf("success: document is unlocked\n");
141 break;
142 case 2:
143 printf("warning: document is not locked by locker\n");
144 break;
145 case 3:
146 printf("warning: document is not locked\n");
147 break;
148 default:
149 printf("error: %s\n",dshGetLastError(dsh));
150 return 1;
151 }
152 }
153
154 //----------------
155 // free Server API
156 //----------------
157 dshClose(dsh);
158 dshExit();
159
160 return 0;
161 }
162
163

Test example (Solaris)

1. Create program:
CC ‑o dsh_lock dsh_lock.cxx libdsh_3.so

2. Append the directory, where you have placed the shared libraries, to the
LD_LIBRARY_PATH variable (see also “Library files” on page 195).
% set LD_LIBRARY_PATH[9]="$LD_LIBRARY_PATH;<path to shared libs>"
% export LD_LIBRARY_PATH

3. Lock the document <docid> that you sent to the archive in the dsh_put
example page 201. Do not specify a locker string:
% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑l
success: document is locked
%

4. Try to lock this document again. This should lead to a warning now,
because the document is already locked:
[9] Variable name for other platforms see “Library files” on page 195.

On a Windows system, specify set %path%=%path%;<path to DLL directory>

220 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑l

warning: document is already locked
%

5. Unlock the document:

% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑u
success: document is unlocked
%

6. Try to unlock the document a second time. Again this should result in a
warning:
% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑u
warning: document is not locked
%

7. Now lock the document and specify a locker string this time:

% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑l 12345

success: document is locked
%

8. Try to unlock the document without specifying a locker string:

% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑u
warning: document is not locked by locker
%

9. Unlock the document by specifying the correct locker string:

% dsh_lock ‑h host1 ‑a A1 ‑d <docid> ‑u 12345

success: document is unlocked
%

Internal structure: Details

The program simply applies the dshDsLock or dshDsUnlock function,
depending on the options specified in the command line. Unlike other example
programs, it provides a detailed error evaluation with corresponding error
messages.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 221
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

4.3.7 dsh_info example: Retrieving information about

logical archives
Purpose
This example demonstrates how to retrieve information about the version of
Archive Server and about all logical archives known to Archive Server.

Note: Please note that this sample is designed for connections to Archive
Server version 9.7 or higher, whereas the preceding samples also can be
used with a lower software version.

Source code file

The source code listed below is available in the file
server_API_SDK/<platform>/examples/dsh_info.cxx
(see also “Files accompanying this manual” on page 194).

Usage
usage: dsh_lock ‑h <host>
Options:

-h <host> hostname <host> of the repository server

Source code (dsh_info.cxx)

1 #include <stdio.h>
2 #include <string.h>
3 #include <stdlib.h>
4 #include "libdsh/libdsh.h"
5
6
7 int main(int argc, char **argv)
8 {
9 int i = 1;
10 char host[100] = "";
11 char port[100] = "8080";
12 char path[100] = "/archive";
13
14 //-------------------------
15 // parse program parameters
16 //-------------------------
17 while( i < argc ) {
18 //------------------------
19 // get archive server name
20 //------------------------
21 if ( strcmp(argv[i],"-h") == 0 ) {
22 if ( ++i < argc ) {
23 strcpy(host,argv[i++]);
24 }
25 //---------------------
26 // get HTTP port number
27 //---------------------
28 } else if ( strcmp(argv[i],"-p") == 0 ) {
29 if ( ++i < argc ) {
30 strcpy(port,argv[i++]);
31 }
32 //-------------------------------------
33 // get URL path name (default=/archive)
34 //-------------------------------------
35 } else if ( strcmp(argv[i],"-s") == 0 ) {
36 if ( ++i < argc ) {
37 strcpy(path,argv[i++]);
38 }
39 } else {
40 printf("wrong program parameter\n");

222 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 4.3. Sample programs in detail

41 break;
42 }
43 }
44 //--------------------------
45 // verify program parameters
46 //--------------------------
47 if ( (strlen(host) == 0) || (strlen(port) == 0) || (strlen(path) == 0) ) {
48 printf("\n");
49 printf("usage: %s -h <host> [-p <port>] [-s <path>]\n",argv[0]);
50 printf("\n");
51 printf("options:\n");
52 printf(" -h <host> hostname of archive server.\n");
53 printf(" -p <port> HTTP-port number (default=8080).\n");
54 printf(" -s <path> URL-path (default=/archive\n");
55 printf("\n");
56 printf("description: get information from Archive-Server about\n");
57 printf(" logical archives etc.\n");
58 printf("\n");
59 return 1;
60 }
61
62 //----------------------
63 // initialize Server API
64 //----------------------
65 void *dsh = dshOpen2(host,"http",atoi(port),path,"user","application");
66 if ( dsh == NULL ) {
67 //-----------------------------
68 // archive server not reachable
69 //-----------------------------
70 printf("error: archive server '%s' not reachable\n",host);
71 return 1;
72 }
73
74 //--------------------------------
75 // get info about logical archives
76 //--------------------------------
77 info = dshDsAdmInfo2(dsh,0,1);
78 if ( info == NULL ) {
79 printf("error: can't get info about logical archives: %s\n",
80 dshGetLastError(dsh));
81 return 1;
82 } else {
83 printf("\n");
84 printf("logical archive info:\n");
85 printf("-------------------- \n");
86 printf("\n%s\n\n",info);
87 }
88 dshFree(info);
89
90 //----------------
91 // free Server API
92 //----------------
93 dshClose(dsh);
94 dshExit();
95
96 return 0;
97 }
98
99

Test example (Linux)

1. Create program:
g++ -o dsh_info dsh_info.cxx libdsh_3.so

2. Run the program

>export LD_LIBRARY_PATH=`pwd`
>dsh_info -h vm91-sblqa

3. The exemplary result:

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 223
AR100500-PSA-EN-3
Chapter 4 Archive Server API in practice

logical archive info:

--------------------

archive server vers. type mode ssl-mode port_adms port_ds protocol security
connected http_port https_port url_path group storage_tiers
-----------------------------------------------------------------------------------------
----------------------------------------------------------------
AS samson 9.6 O ---- ssl_allow 4060 8080 http SEC_R3L2
yes 8080 8090 /archive samson
ASIG samson 9.6 O rcud ssl_allow 4060 8080 http SEC_R3L2
yes 8080 8090 /archive samson
CG samson 9.6 O rcud ssl_on 4061 8090 https SEC_R3L2
yes 8080 8090 /archive samson
...
OEWT vm91-sblqa 9.7 O ---- ssl_allow 4060 8080 http SEC_R3L2
yes 8080 8090 /archive vm91-sblqa
WX samson 9.6 O ---- ssl_on 4061 8090 https SEC_R3L2
yes 8080 8090 /archive samson
tts vm91-sblqa 9.7 O -cu- ssl_on 4061 8090 https SEC_R3L2
yes 8080 8090 /archive vm91-sblqa

Internal structure: Details

The program simply applies the dshDsLock or dshDsUnlock function,
depending on the options specified in the command line. Unlike other example
programs, it provides a detailed error evaluation with corresponding error
messages.

224 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
Chapter 5
References

5.1 Further information sources

1. SAP ArchiveLink 4.5 – HTTP Content Server Interface by SAP AG
2. Multipurpose Internet Mail Extensions (MIME),
normative Internet standard RFC 2045, available for example at
http://www.faqs.org/rfcs/rfc2045.html
3. Distinguished Encoding Rules (DER)
A specific encoding method. Further information is available for example at
http://www.faqs.org/rfcs/rfc1424.html
4. Privacy Enhanced Mail (PEM)
http://www.baltimore.com/devzone/standards/asn.1-ber-der.html

5.2 Events
This section gives a reference of all events that are tracked in the history of a
document, if the auditing feature is activated for an archive.[1] This feature is
available since software version 9.6.

The event list can be obtained using the dshDsGetDocumentHistory function.

Note: <volid1> and <volid2> are further parameters in the event list returned
by the dshDsGetDocumentHistory call.

5.2.1 Events in alphabetical order

EVENT_COMP_COPIED (value: 8)
Component has been copied from <volid1> to <volid2>.

EVENT_COMP_DELETED (value: 10)

Component has been deleted from the <volid1>.

EVENT_COMP_DELETE_FAILED (value: 11)

Component deletion from <volid1> failed.

EVENT_COMP_DESTROYED (value: 12)

Component on <volid1> has been destroyed (i.e. overwritten with changing bit
patterns, then deleted to ensure that it is definitely unrestorable)

EVENT_COMP_MOVED (value: 7)
Component has been moved moved from HDSK <volid1> to <volid2>.
[1] Compliance mode – see Section 38.1 “Auditing” in OpenText Archive Server - Administration Guide (AR-
ACN) for details.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 225
AR100500-PSA-EN-3
Chapter 5 References

EVENT_COMP_PURGED (value: 9)
After transfering a component from the hard disk buffer to its target location,
the component in the buffer has been deleted (purged).

EVENT_CREATE_COMP (value: 2)
Component has been created on <volid1>.

EVENT_CREATE_DOC (value: 1)
Document has been created.

EVENT_DOC_DELETED (value: 13)

Document has been deleted.

EVENT_DOC_MIGRATED (value: 14)

Document has been migrated.

EVENT_DOC_SECURITY (value: 16)

There was a security error during an attempt to read the document.

EVENT_DOC_SET_EVENT (value: 15)

Deferred setting of retention period has been applied (for example, via
dshDsSetDocumentFlag).

EVENT_TIMESTAMPED (value: 4)
Timestamp has been created on <volid1>.

EVENT_TIMESTAMP_VERIFIED (value: 5)
The timestamp has been verified on <volid1>.

EVENT_TIMESTAMP_VERIF_FAILED (value: 6)
The timestamp verification on <volid1> failed.

EVENT_UPDATE_ATTR (value: 3)
Attributes have been updated.

5.2.2 Events in numerical order

EVENT_CREATE_DOC (value: 1)
Document has been created.

EVENT_CREATE_COMP (value: 2)
Component has been created on <volid1>.

EVENT_UPDATE_ATTR (value: 3)
Attributes have been updated.

EVENT_TIMESTAMPED (value: 4)
Timestamp has been created on <volid1>.

EVENT_TIMESTAMP_VERIFIED (value: 5)
The timestamp has been verified on <volid1>.

EVENT_TIMESTAMP_VERIF_FAILED (value: 6)
The timestamp verification on <volid1> failed.

226 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.2. Events

EVENT_COMP_MOVED (value: 7)
Component has been moved from HDSK <volid1> to <volid2>.

EVENT_COMP_COPIED (value: 8)
Component has been copied copied from <volid1> to <volid2>.

EVENT_COMP_PURGED (value: 9)
After transfering a component from the hard disk buffer to its target location,
the component in the buffer has been deleted (purged).

EVENT_COMP_DELETED (value: 10)

Component has been deleted from <volid1>.

EVENT_COMP_DELETE_FAILED (value: 11)

Component deletion from <volid1> failed.

EVENT_COMP_DESTROYED (value: 12)

Component on <volid1> has been destroyed (i.e. overwritten with changing bit
patterns, then deleted to ensure that it is definitely unrestorable)

EVENT_DOC_DELETED (value: 13)

Document has been deleted.

EVENT_DOC_MIGRATED (value: 14)

Document has been migrated.

EVENT_DOC_SET_EVENT (value: 15)

Deferred setting of retention period has been applied (for example, via
dshDsSetDocumentFlag).

EVENT_DOC_SECURITY (value: 16)

There was a security error during an attempt to read the document.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 227
AR100500-PSA-EN-3
Chapter 5 References

5.3 Global environment variables

For a number of internal parameters of libdsh, you can predefine initial values via
corresponding environment variables, which are listed below. Depending on its
context (logging, not session-specific, session-specific), the respective internal
parameter is initialized at the first call of a dshSetLog* function or of dshOpen, or
when the session is initialized (i.e. at the dshOpen establishing the session) – see also
“Initializing and ending a libdsh session” on page 32. If a variable is not set in the
environment, libdsh assigns the value listed as internal default below.

Note: The environment variables are not modified by libdsh, if you change the
respective parameters within libdsh (via a dshSet* function, except
dshSetConfig). If you want to keep these modifications beyond the end of a
session, you must provide a corresponding storage procedure (see also
“Initializing and ending a libdsh session” on page 32).

DSH_ADMS_REFRESH_INTERVAL
Description: Refresh interval in seconds used to update server information, in
particular the hostname cache.
Admissible values: Integer value, max. 86400 (1 day)
Internal default: 3600
DSH_APPLICATION
Description: Name of the application using libdsh. This name is needed for
accounting purposes (see Section 2.3.3.3: “Setting parameters” on page 34).
Admissible values: String
Internal default: libdsh
DSH_AUTH_ID
Description: Unique client identifier (authenticity). See also “dshSetAuthId:
Set authenticity” on page 178 and “Access protection via SecKeys (signed
URLs)” on page 22.
Admissible values: String
Internal default: The host name
DSH_CHECKSUM
Description: If set to on, files sent to the archive get an additional checksum
which is checked by the Archive Server to avoid transmission errors. If the
server detects an error, the libdsh function fails and returns an error condition
DSH_ERR_CREATE_CHECKSUM). If DSH_CHECKSUM is set to off, this check is not
provided, resulting in faster transmission but a greater risk of errors. This setting
does not require a corresponding setting on the server.
Admissible values: on, off
Internal default: on
DSH_DS_REFRESH_INTERVAL
Description: Refresh interval for the hostname cache (in seconds).

228 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.3. Global environment variables

Admissible values: Integer value, max. 86400 (1 day)

Internal default: 3600
DSH_EXP_TIME_SEC_KEY
Description: Expiration time for SecKey (in seconds). See also “SecKey handling
in libdsh” on page 31.
Admissible values: Integer value
Internal default: 3600
DSH_HOST_RECONNECT_INTERVAL
Description: Specifies the time interval in seconds for libdsh to try to reconnect
to the repository server after losing a connection.
Admissible values: Integer value
Internal default: 60
DSH_LOG_THREAD_ID
Description: If set to yes, the ID of the current thread is written to the logging
output.
Admissible values: yes, no
Internal default: no
DSH_MAX_CONNECTION_RETRIES
Description: Specifies the maximum number of attempts for reconnecting to the
repository server after a connection is lost.
Admissible values:
Internal default: 1
DSH_MAX_MTA_INDEX
Description: Maximum number of documents per meta document.
Admissible values: Integer value
Internal default: 10000
DSH_MAX_MTA_SIZE
Description: Maximum size of a meta document in byte (default = 50MB).
Admissible values: Integer value
Internal default: 52428800
DSH_MAX_MTA_TIME
Description: Maximum time (in seconds) for appending further MTA sub
documents to a meta document.
Admissible values: Integer value
Internal default: 300 (5 minutes)
DSH_MAX_REQUEST_RETRY_TIME
Description: Specifies the maximum time (in seconds) to retry a request. See also
DSH_REQUEST_RETRY_INTERVAL_MS on page 230.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 229
AR100500-PSA-EN-3
Chapter 5 References

Admissible values: Integer value

Internal default: 20

DSH_PROXY
Description: URL of proxy server. See also “Proxy server” on page 13 and
“dshSetProxy: Set proxy server” on page 190.
Admissible values: String with format http://<host>:<port>
Internal default: undef

DSH_READ_BUFFER_SIZE
Description: Size of the read buffer
Admissible values: Integer value
Internal default: 65536

DSH_READ_TIMEOUT
Description: Timout period for reading a document from the archive (in
seconds)
Admissible values: Integer value
Internal default: 120

Note: For the retrieval of large documents with a timestamp, this value
possibly must be increased, because the timestamp verification of large
documents can take some extra time on the server.

DSH_REQUEST_RETRY_INTERVAL_MS
Description: Time interval (in milliseconds) to wait before a request is tried
again. See also DSH_MAX_REQUEST_RETRY_TIME on page 229.
Admissible values: Integer value
Internal default: 120

DSH_SCRIPT
Description: Parameter in the default HTTP URL: http://<server>:<port>/
<script>. Usually required for debugging purposes only.
Internal default: archive

DSH_USER
Description: User name. This name is needed for accounting purposes (see
Section 2.3.3.3: “Setting parameters” on page 34).
Admissible values: String
Internal default: The host name

DSH_VERIFY_SIG_TIMEOUT
Description: Internal timeout in seconds for a dshDsVerifySig call.
Admissible values: Integer value
Internal default: 5

230 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.3. Global environment variables

LOG_DEBUG
Description: If set to on, libdsh prints debug logging information to the stderr
stream or the log file, if set via the dshSetLogFile function. See “Logging”
on page 32 and “dshSetLogLevel: Set log level” on page 184.
Admissible values: on, off
Internal default: off

LOG_DSH[2]
Description: Activates/deactivates the tracing of the internal library, which is
used by libdsh for the HTTP communication. Depending on the version of the
used DLLs (see “Library files” on page 195), the meaning and the admissible
values of this variable are different:
• Version 5.5.2003.409 (build SV55–026) and later:
The variable just activates or deactivates the tracing, so admissible values are
on or off.
Admissible values:
Internal default: off
• Before Version 5.5.2003.409 (build SV55–026):
The value of LOG_DSH is a string of characters, each of which sets up one of
the following TRACE flags:
• a: show ANCHOR trace messages
• b: show BIND trace messages
• c: show CACHE trace messages
• f: show BASIC UTILITIES trace messages
• g: show SGML trace messages
• h: show AUTH trace messages
• i: show PICS trace messages
• l: show APPLICATION LEVEL trace msg.
• m: show MEMORY trace messages
• o: show CORE trace messages
• p: show PROTOCOL trace messages
• q: show SQL trace messages
• s: show STREAM trace messages
• t: show THREAD trace messages
• u: show URI trace messages

[2] It is possible that this variable may not be supported by your libdsh version (open item until the deadline
of this manual)

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 231
AR100500-PSA-EN-3
Chapter 5 References

• x: show MUX trace messages

• * show ALL trace messages

Internal default: undef

LOG_ENTRY
Description: If set to on, libdsh prints log messages regarding function entry
points to the stderr stream or the log file, if set via the dshSetLogFile
function. See also “Logging” on page 32 and “dshSetLogLevel: Set log level”
on page 184.
Admissible values: on, off
Internal default: off

LOG_ERROR
Description: If set to on, libdsh prints error messages to the stderr stream or the
log file, if set via the dshSetLogFile function – see also “Logging” on page 32
and “dshSetLogLevel: Set log level” on page 184. Note that this option can
only be set via this variable, not via the dshSetLogLevel function.
Admissible values: on, off
Internal default: off

LOG_FATAL
Description: If set to on, libdsh prints fatal error messages to the stderr stream
or the log file, if set via the dshSetLogFile function – see also “Logging”
on page 32 and “dshSetLogLevel: Set log level” on page 184. Note that this
option can only be set via this variable, not via the dshSetLogLevel function.
Admissible values: on, off
Internal default: on

LOG_IMPORTANT
Description: If set to on, libdsh prints information messages to the stderr
stream or the log file, if set via the dshSetLogFile function. See also “Logging”
on page 32 and “dshSetLogLevel: Set log level” on page 184.
Admissible values: on, off
Internal default: off

LOG_INFO
Description: If set to on, libdsh prints information messages to the stderr
stream or the log file, if set via the dshSetLogFile function. See also “Logging”
on page 32 and “dshSetLogLevel: Set log level” on page 184.
Admissible values: on, off
Internal default: off

LOG_REL
Description: If set to on, libdsh provided a more detailed time stamp in the log
file by adding a μs specification. This may be usefule, if timing problems occur.

232 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.3. Global environment variables

Admissible values: on, off

Internal default: off

LOG_WARNING
Description: If set to on, libdsh prints warning messages to the stderr stream or
the log file, if set via the dshSetLogFile function – see also “Logging”
on page 32 and “dshSetLogLevel: Set log level” on page 184. Note that this
option can only be set via this variable, not via the dshSetLogLevel function.
Admissible values: on, off
Internal default: off

MAXLOGSIZE
Description: This variable specifies the maximum size of the log file in Byte as
described in “dshSetLogMaxSize: Set maximum size of log file” on page 186.
Admissible values: Integer value
Internal default: 100000

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 233
AR100500-PSA-EN-3
Chapter 5 References

5.4 libdsh errors

The following two sections list the messages for all errors that may occur in a libdsh
function. The messages are listed in alphabetical order in the first section and in
numerical order in the second section.

5.4.1 libdsh error messages in alphabetical order

DSH_ERR_ACCESS_FILE
Error in accessing file (error no.: 11207)

DSH_ERR_ADD_MIME_PARSER
Can't add MIME parser to HTTP library (error no.: 11000)
Internal error, please inform IXOS if this error should occur.

DSH_ERR_CREATE_CHECKSUM
Error in creating checksum (error no.: 11205) – see DSH_CHECKSUM on page 228.

DSH_ERR_FUNCTION_ARGUMENT
Wrong function argument (for example, NULL pointer) (error no.: 11203)

DSH_ERR_HTTP_400
HTTP error (bad request [400]): Unknown function or parameter (error no.:
11005)

DSH_ERR_HTTP_401
HTTP error (unauthorized [401]): Breach of security (error no.: 11006). You tried
to access a document that is protected via SecKeys, and your application is not
able to generate the required SecKey – see also “Access protection via SecKeys
(signed URLs)” on page 22.

DSH_ERR_HTTP_403
HTTP error (forbidden [403]): Document/component already exists (error no.:
11007)

DSH_ERR_HTTP_404
HTTP error (not found [404]): Document/component/archive not found (error
no.: 11008)

Note: Under normal conditions, a missing archive is not indicated by this

error, but by DSH_ERR_UNKNOWN_ARCHIVE. If indeed a missing archive
caused this error, please inform IXOS as it may signal an internal error.

DSH_ERR_HTTP_404_DELA
HTTP error (not found [404]): Either the document, the component or the
attribute does not exist (error no.: 11016, caused by dshDsDelAttribute)

DSH_ERR_HTTP_404_GETA
HTTP error (not found [404]): Either the document, the component or the
attribute does not exist (error no.: 11015, caused by dshDsGetAttribute)

234 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.4. libdsh errors

DSH_ERR_HTTP_404_SETA
May occur in: dshDsSetAttribute

DSH_ERR_HTTP_404_VU
HTTP error (not found [404]): A user account with the specified user/passwd
combination does not exist. The user is not found (error no.: 11014)

DSH_ERR_HTTP_406
HTTP error (not acceptable [406]): Certificate cannot be recognized (error no.:
11009)

DSH_ERR_HTTP_409
HTTP error (conflict [409]): Document/component/administrat. data is
inaccessible (error no.: 11010)

DSH_ERR_HTTP_409_INFO
HTTP error (conflict [409]): Administrative data is inaccessible (error no.: 11020)

DSH_ERR_HTTP_409_LOCK
HTTP error (conflict [409]): There was already a lock on the document (error no.:
11018)

DSH_ERR_HTTP_409_UNLOCK
HTTP error (conflict [409]): The document was not locked by locker. Therefore
the lock could not be removed (error no.: 11019)

DSH_ERR_HTTP_412
HTTP error (precondition failed [412]) (error no.: 11011)

DSH_ERR_HTTP_412_UNLOCK
HTTP error (precondition failed [412]): The document was not locked (error no.:
11021)

DSH_ERR_HTTP_500
HTTP error (Internal Server Error [500]): Internal error in archive server (error
no.: 11012)

DSH_ERR_HTTP_CONNECTION_BROKEN
HTTP error: connection was broken (error no.: 11003)

DSH_ERR_HTTP_EMPTY_RESULT
Wrong (empty) result from archive server (error no.: 11002). libdsh expected the
repository server to return a non-empty piece of data (for example, a
component), but it returned an empty piece of data (for example, a component
with a size 0). This is not necessarily an error, in particular if testing is being
performed.

DSH_ERR_HTTP_PARSE_HEADER
Error in parsing HTTP header (error no.: 11001)
This error occurs, if the HTTP header does not correspond to the structure
expected by the libdsh function (for example, dshDsInfo). Probably this is
caused by a transmission error or is an internal error, please inform IXOS in this
case.

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 235
AR100500-PSA-EN-3
Chapter 5 References

DSH_ERR_HTTP_UNKNOWN
HTTP error: unknown error (error no.: 11004)
DSH_ERR_OUT_OF_MEMORY
Out of memory (error no.: 11204)
DSH_ERR_R3_INFO
No SAP information available (error no.: 11200)
DSH_ERR_UNKNOWN_ARCHIVE
Unknown archive (error no.: 11206). This error occurs if you try to access an
archive that is not listed in the hostname cache. The archive name may have
been misspelled, or the hostname cache may not be up-to-date (call
dshSetAidRefreshTime(<dsh handle>, 0) in this case to update the table).

DSH_ERR_UNKNOWN_COMP
Unknown component (error no.: 11209)

Note: Under normal conditions, a missing component is not indicated by

this error, but by DSH_ERR_HTTP_404(_*)DSH_ERR_UNKNOWN_ARCHIVE. If
indeed a missing component caused this error, please inform IXOS, as it
may signal an internal error.

5.4.2 libdsh errors in numerical order

Refer to “libdsh error messages in alphabetical order” on page 234 for further
information on the individual errors.

11000: DSH_ERR_ADD_MIME_PARSER
11001: DSH_ERR_HTTP_PARSE_HEADER
11002: DSH_ERR_HTTP_EMPTY_RESULT
11003: DSH_ERR_HTTP_CONNECTION_BROKEN
11004: DSH_ERR_HTTP_UNKNOWN
11005: DSH_ERR_HTTP_400
11006: DSH_ERR_HTTP_401
11007: DSH_ERR_HTTP_403
11008: DSH_ERR_HTTP_404
11009: DSH_ERR_HTTP_406
11010: DSH_ERR_HTTP_409
11011: DSH_ERR_HTTP_412
11012: DSH_ERR_HTTP_500
11014: DSH_ERR_HTTP_404_VU
11015: DSH_ERR_HTTP_404_GETA
11016: DSH_ERR_HTTP_404_DELA
11017: DSH_ERR_HTTP_404_SETA
11018: DSH_ERR_HTTP_409_LOCK
11019: DSH_ERR_HTTP_409_UNLOCK
11020: DSH_ERR_HTTP_409_INFO
11021: DSH_ERR_HTTP_412_UNLOCK
11203: DSH_ERR_FUNCTION_ARGUMENT
11204: DSH_ERR_OUT_OF_MEMORY

236 OpenText Archive Server – Programming Guide for the OpenText Archive Server API
AR100500-PSA-EN-3
 5.5. Figures and tables

11205: DSH_ERR_CREATE_CHECKSUM
11206: DSH_ERR_UNKNOWN_ARCHIVE
11207: DSH_ERR_ACCESS_FILE
11209: DSH_ERR_UNKNOWN_COMP

5.5 Figures and tables

List of Figures

Figure 3-1: “Each DAIN line represents a complete attribute set; within this set, each
attribute can be uniquely addressed by its local offset and its string length.”
on page 59

List of Tables

Table 2-1: “Convention for component names and types ” on page 17

Table 2-2: “File types known in libdsh” on page 20

OpenText Archive Server – Programming Guide for the OpenText Archive Server API 237
AR100500-PSA-EN-3