ADIC Digital Camera 601355 User Manual

API Guide

VolServ Version 5.0

September 2001

601355 Rev A

Trademark Notice

AMASS, DataMgr, EMASS, FileServ, and VolServ are either trademarks or registered
trademarks of ADIC, Advanced Digital Information Corporation. DAS is a trademark of
Grau, an ADIC subsidiary. All other product names and identifications are trademarks or
registered trademarks of their respective manufacturers.

Copyright Notice

© 1996-2001 ADIC®. All rights reserved. This document is the property of ADIC. No part
of this document may be reproduced, transmitted, transcribed, stored in a retrieval system,
or translated into any language or computer language in any form or by any means,
electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the
express written permission of:

ADIC
10949 East Peakview Ave.
Englewood, CO 80111 USA
Phone: [phone]
FAX: [phone]

U.S. Government Rights Restricted

Use, duplication, or disclosure of either the software or documentation is subject to
restrictions set forth by the U.S. Government in FAR 52.227-19(c)(2) and subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227­7013 and/or in similar or following clauses in the FAR, DoD, or NASA FAR Supplement.

Technical Assistance

ADIC Technical Assistance Center:

• In the USA and Canada, call 1-800-827-3822.

• Outside the USA and Canada, call 303-874-0188 or toll-free 00800-9999-3822.

• Send e-mail to: [e-mail].

Documentation

Although the material contained herein has been carefully reviewed, ADIC does not
warrant it to be free of errors or omissions. We reserve the right to make corrections,
updates, revisions, or changes to the information contained herein.

• Send e-mail to: [e-mail]

READER COMMENT FORM

ADIC includes this Form in an effort to provide the best possible documentation to our
customers. Please take a few moments to mail or FAX your response to:

ADIC
Software Documentation
10949 East Peakview Ave.
Englewood, CO 80111
FAX: [phone]

E-mail: [e-mail]

Question Circle One

Information was complete. Agree Disagree
Information was easy to find. Agree Disagree
Information was easy to follow. Agree Disagree

Is there anything you especially like or dislike about the organization, presentation,
or writing in this manual?_______________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________

Book Title Document Number
Customer Name Telephone
E-mail Address
Company Name
Address
City, State, Zip

NOTES

Contents

Preface

Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-3

Who Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-3

How This Book is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-3

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-4

Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-5

Getting Started 1

API Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3

Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

Client Interface Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7

Unsolicited Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9

VolServ API Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10

API Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-15

Dispatch Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-19

Global Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-20

API Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-22

Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-24

Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-28

API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-30

601355 Rev A i

API Guide

API Functions 2

VS_Archive_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11

VS_Archive_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15

VS_Archive_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25

VS_ArchiveMediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

VS_ArchiveMediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36

VS_ArchiveMediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41

VS_ArchiveMediaClass_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-49

VS_Command_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-58

VS_Command_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-61

VS_Command_GetErrorFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-65

VS_Command_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-68

VS_Command_GetStatusFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-72

VS_Command_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82

VS_Component_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-87

VS_Component_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-93

VS_Component_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-96

VS_Component_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-100

VS_Connect_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-107

VS_Connect_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-110

VS_Connect_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-114

VS_Connect_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-118

VS_Criteria_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-123

VS_Criteria_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-129

VS_Criteria_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-136

VS_Criteria_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-142

ii Contents 601355 Rev A

API Guide

VS_CriteriaGroup_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-149

VS_CriteriaGroup_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-155

VS_CriteriaGroup_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-161

VS_CriteriaGroup_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-166

VS_Drive_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-173

VS_Drive_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-177

VS_Drive_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-181

VS_Drive_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-187

VS_DrivePool_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-193

VS_DrivePool_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-196

VS_DrivePool_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-199

VS_DrivePool_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-204

VS_Error_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-208

VS_Expression_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-212

VS_Expression_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-218

VS_Expression_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-225

VS_Expression_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-231

VS_Global_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-238

VS_Global_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-243

VS_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-249

VS_Media_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-253

VS_Media_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-257

VS_Media_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-261

VS_Media_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-267

VS_MediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-273

VS_MediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-278

VS_MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-283

VS_MediaClass_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-291

601355 Rev A Contents iii

API Guide

VS_MediaType_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-299

VS_MediaType_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-302

VS_MediaType_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-305

VS_MediaType_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-309

VS_Mount_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-313

VS_Mount_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-318

VS_MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-322

VS_Mount_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-330

VS_Notify_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-338

VS_Notify_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-343

VS_Notify_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-348

VS_Notify_Listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-356

VS_Notify_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-362

VS_Request_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-369

VS_Request_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-372

VS_Request_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-375

VS_Request_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-379

VS_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-383

VS_Status_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-386

VS_Table_AddEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-400

VS_Table_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-407

VS_Table_CreateAdd-Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-414

VS_Table_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-418

VS_Table_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-422

VS_Table_RemoveEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-426

VS_Table_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-430

VS_Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-435

VS_TypeCapacity_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-437

iv Contents 601355 Rev A

API Guide

VS_TypeCapacity_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-441

VS_TypeCapacity_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-446

VS_TypeCapacity_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-453

VSCMD_ArchiveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-460

VSCMD_ArchiveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-470

VSCMD_ArchiveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-476

VSCMD_ArchiveVary_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-484

VSCMD_Audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-490

VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-499

VSCMD_Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-505

VSCMD_Cancel_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-514

VSCMD_Checkin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-520

VSCMD_Checkin_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-529

VSCMD_Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-534

VSCMD_Checkout_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-543

VSCMD_ClearEject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-548

VSCMD_ClearEject_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-557

VSCMD_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-563

VSCMD_Connect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-575

VSCMD_Connect-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-581

VSCMD_Connect-Query_Set-Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-590

VSCMD_CreateArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-595

VSCMD_CreateArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . .2-609

VSCMD_CreateMedia-Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-619

VSCMD_CreateMedia-Class_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-632

VSCMD_DriveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-641

VSCMD_DriveVary_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-652

VSCMD_Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-660

601355 Rev A Contents v

API Guide

VSCMD_Export_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-669

VSCMD_Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-674

VSCMD_Import_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-684

VSCMD_Intransit-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-689

VSCMD_Intransit-Query_Set-Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-697

VSCMD_Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-702

VSCMD_Lock_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-712

VSCMD_MediaClass-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-717

VSCMD_MediaClass-Query_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-726

VSCMD_MediaQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-731

VSCMD_MediaQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-739

VSCMD_MediaType-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-744

VSCMD_MediaType-Query_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-753

VSCMD_ModifyMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-759

VSCMD_ModifyMedia_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-769

VSCMD_CreatePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-776

VSCMD_CreatePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-785

VSCMD_DeleteArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-791

VSCMD_DeleteArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . .2-800

VSCMD_DeleteMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-806

VSCMD_DeleteMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-814

VSCMD_DeletePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-819

VSCMD_DeletePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-827

VSCMD_Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-832

VSCMD_Disconnect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-842

VSCMD_Dismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-848

VSCMD_Dismount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-857

VSCMD_DrivePoolQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-863

vi Contents 601355 Rev A

API Guide

VSCMD_DrivePoolQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-872

VSCMD_DriveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-878

VSCMD_DriveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-887

VSCMD_ModifyArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-893

VSCMD_ModifyArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . .2-908

VSCMD_ModifyMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-914

VSCMD_ModifyMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-927

VSCMD_ModifyPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-935

VSCMD_ModifyPool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-945

VSCMD_Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-951

VSCMD_Mount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-967

VSCMD_Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-975

VSCMD_Move_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-986

VSCMD_MultiMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-992

VSCMD_MultiMount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1003

VSCMD_Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1009

VSCMD_QueryMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1013

VSCMD_QueryMount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1022

VSCMD_Reclassify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1027

VSCMD_Reclassify_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1039

VSCMD_Reprioritize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1045

VSCMD_Reprioritize_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1054

VSCMD_Request-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1060

VSCMD_RequestQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1068

VSCMD_Unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1073

VSCMD_Unlock_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1081

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

601355 Rev A Contents vii

API Guide

viii Contents 601355 Rev A

Preface

Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . .P-3

Who Should Read This Book. . . . . . . . . . . . . . . . .P-3

How This Book is Organized . . . . . . . . . . . . . . . .P-3

Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-4

Books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-5

Online Books . . . . . . . . . . . . . . . . . . . . . . . . . . . P-5

Related Publications . . . . . . . . . . . . . . . . . . . . .P-6

Contact Publications Department. . . . . . . . . .P-6

Secured Web Site. . . . . . . . . . . . . . . . . . . . . . . .P-6

P

Preface

API Guide

NOTES

P-2 Preface 601355 Rev A

API Guide

Preface

Purpose of This Book

Who Should Read This Book

How This Book is Organized

This book describes the VolServ application programming
interface (API). The API consists of functions, iterators,
symbolic names, type definitions, and data structures.

Using the API provides the programmer with the ability to
directly manipulate VolServ file system metadata and media.

This book is written for programmers who are creating or
modifying an application that requires tight control over data in
the file system managed by VolServ

This book contains the following chapters:
Chapter 1: Getting Started — Describes API types and

naming conventions, dispatch routines and global
parameters,.and error handling.

Chapter 2: Functions — Alphabetical list of API function
calls.

Appendix A: Valid Status Fields — A matrix shows which
status fields are valid for each command.

Appendix B: Error Codes.
Appendix C: Mount Example.

601355 Rev A Preface P-3

API Guide

Conventions

The conventions used throughout the VolServ technical books
are listed below:

Convention Example

Screen text, file names, program names, and
commands are in Courier font.

The root prompt is shown as a number
symbol.

What you should type in is shown in Courier
bold font.

Site-specific variables are in a Times italics
font.

A backward slash ( \ ) denotes the input is
continued onto the next line; the printed page
is just not wide enough to accommodate the
line.

Pressing <Return> after each command is
assumed.

Request to add a new volume:
Volume group will be “20”
Volume position will be “A123”.

# su root

vsarchiveqry

tar -xvf tapedevicename

#

remsh nodename -n dd if=/dev \

/tapedevicename/bs=20b | tar xvfb \

- 20

(You should type the entire command without
the backward slash.)

A menu name with an arrow refers to a
sequence of menus.

P-4 Preface 601355 Rev A

Config-->MediaType-->Redefine

API Guide

Preface

Books

The books described below are part of the technical
documentation set, and are shipped on CD along with the
VolServ software:

Overview

Provides an ov erview of VolServ. Contains a
glossary.

Installing VolServ
Describes server requirements, installation
instructions, troubleshooting procedures,
and configuration parameters.

Using the VolServ GUI

Describes how to perform system
administrative tasks using th e graphical user
interface.

API Guide

Provides a list of API functions.

Administrative Tasks

Describes how to perform system
administrative tasks using VolServ
commands.

Command Reference

Contains a list of VolServ commands

Error Messages

Provides corrective action f or system log
errors.

Quick Reference Card

Summarizes commands.

Online Books

The documentation CD contains VolServ book files and
Adobe® Acrobat® Reader. The Reader allows you to view and

navigate the online documentation files yet preserves the page
design and graphics from the printed books.

601355 Rev A Preface P-5

API Guide

Related Publications

Related Publications Description

“Release Notes” For each version of VolServ, the “Release Notes” contain:

“Product Alerts” Informs customers of technical problems and solutions.
“Product Bulletins” Conveys technical information—not problems—to

The publications described in the table below are created and
distributed on an as-needed basis.

• Summary of enhancements.

• Describes:

- Fixed problems.

- Known problems.

- Installation and configuration issues.

•Lists:

- Operating system patches.

- System requirements.

customers.

Contact Publications Department

Secured Web Site

To make corrections or to comment on VolServ publications,
please contact Software Technical Publications at our e-mail
address: [e-mail].

To receive access to the secured site on our home page contain­ing technical product information (Release Notes, Product
Alerts, Product Bulletins, FAQs), visit http://partners.adic.com/
and follow the password request procedure. In return, ADIC
will send you instructions and a password.

P-6 Preface 601355 Rev A

API Directory Structure . . . . . . . . . . . . . . . . . . . . . 1-3

Application Program Interface . . . . . . . . . . . . . . . 1-5

Extensible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Consistent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

1

Portable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Flexible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Client Interface Summary . . . . . . . . . . . . . . . . . . . 1-7

Unsolicited Communication . . . . . . . . . . . . . . . . . 1-9

VolServ API Integration. . . . . . . . . . . . . . . . . . . . 1-10

API Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Handles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . 1-15

Dispatch Routines . . . . . . . . . . . . . . . . . . . . . . . . . 1-19

Global Parameters. . . . . . . . . . . . . . . . . . . . . . . . . 1-20

Global Variables . . . . . . . . . . . . . . . . . . . . . . . 1-21

API Error Handling . . . . . . . . . . . . . . . . . . . . . . . 1-22

Using the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24

Command Handle . . . . . . . . . . . . . . . . . . . . . 1-24

Command Calls. . . . . . . . . . . . . . . . . . . . . . . . 1-24

Command Defaults. . . . . . . . . . . . . . . . . . . . . 1-25

Getting Started

Getting

Started

Command Status. . . . . . . . . . . . . . . . . . . . . . . 1-26

Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28

Asynchronous . . . . . . . . . . . . . . . . . . . . . . . . . 1-28

Synchronous . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29

API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30

API Guide

Roadmap

Topic

Naming conventions.
Global parameters.
Error handling.

API functions. 2
Valid staus fields. A
Error codes. B
Mount example . C

Refer To
Chapter

1

1-2 Getting Started 601355 Rev A

API Guide

API Directory Structure

All files necessary for client interface to the VolServ software
are contained in the volserv/vsapi directory by default.
However, the installer may choose a different location during
execution of the installation script, except that the vsapi
directory is always appended to the specified location. Refer to
Installing VolServ for more information.

Client software may use the API to interface to VolServ
software. Clients are responsible for creating and linking their
own applications to the appropriate API header and library files.

The default API directory structure is shown in follo wing f igure
and defined in the table below.

/volserv/vsapi

/lib/include /man

/util

Getting Started

Directory Contents

include Contains six header files used by API library.
lib Contains the API library.
man Contains man pages for all VolServ API library

functions.

601355 Rev A Getting Started 1-3

API Guide

Directory Contents

util Contains various utilities used to clean up

configuration problems, save copies of
VolServ software logs, change the number
sequence of label pattern generation, or to
perform maintenance.

1-4 Getting Started 601355 Rev A

API Guide

Application Program Interface

Extensible

The VolServ Application Programmer’s Interface (API) allows
a programmer to interface with VolServ. The VolServ API is a
set of ‘C’ library routines, written for a UNIX system, that the
client software uses to communicate with VolServ.

Getting Started

The VolServ API allows the user to send commands, receive
command statuses, and receive VolServ MediaClass
notifications.

The VolServ API interface uses the VolServ Remote Procedure
Call (RPC) interface to communicate with VolServ. All features
available in the VolServ RPC interface are supported in the
VolServ API.

The VolServ API is extensible. Any change in the VolServ RPC
interface is handled by the API. Thus, the client program does
not have to be updated to maintain compatibility when the
VolServ RPC interface is modified. The client program is
updated only to use new VolServ features.

Consistent

Portable

Flexible

601355 Rev A Getting Started 1-5

The VolServ API is consistent. All commands and their related
functions have the same interface and operate similarly.

The VolServ API is designed to be highly portable to other
platforms. (If the client program is ported to a platform
supported by the VolServ API, the client program does not need
to be concerned with VolServ connectivity.)

The VolServ API is flexible. A client program can send a
command to VolServ and either

API Guide

• Wait for final status before continuing processing
(synchronous processing).

• Or, continue processing after VolServ has received the
command. The client software receives the command’s
status at a later time (asynchronous processing).

A client program can also mix these operation modes.

1-6 Getting Started 601355 Rev A

API Guide

Client Interface Summary

The figure below illustrates th e communication paths supported
by VolServ:

Clients using

Commands in
Client scripts

Client Software

using API

Client Software

using

RPC/XDR protocol

Command

Line

Interface

API

RPC

RPC

RPC

VolServ

The following outline shows the flow of information through
these communication paths.

• Clients using the Command Line Interface and Client

Scripts.

Getting Started

- The client-to-client script issues a request from the
command line.

- The CLI software performs first-lev el v alidation on the
request and forwards the request to the API software.

- The API software serializes the request into XDR
format and transmits the request to VolServ using the
RPC/XDR protocol.

- VolServ returns data and/or status to the API software
using the RPC/XDR protocol.

601355 Rev A Getting Started 1-7

API Guide

- The API software deserializes the data and/or status
from the XDR formats and forwards the information to
the CLI software.

- The CLI software formats the data and/or status and
forwards this information to the client that issued the
request.

- The client/client script processes the data and/or status
returned by the CLI software.

• Client software using the API.

- The client software issues a request to the API
software by calling an API function/routine.

- The API software serializes the request into XDR
format and transmits the request to VolServ using the
RPC/XDR protocol.

- VolServ returns data and/or status to the API software
using the RPC/XDR protocol.

- The API software deserializes the data and/or status
from the XDR formats and forwards the information to
the client software.

- The client software processes the data and/or status
returned by the API software.

• Client software using the RPC/XDR protocol.

- The client software serializes the request into XDR
format and transmits the request to VolServ using the
RPC/XDR protocol.

- VolServ returns data and/or status to the client
software using the RPC/XDR protocol.

- The client software deserializes the information from
the XDR format and processes the returned
information.

1-8 Getting Started 601355 Rev A

API Guide

Unsolicited
Communica­tion

VolServ can generate unsolicited communication after specific
client and operator commands. This unsolicited communication
is referred to in some VolServ documentation as “Callbacks” or
“Notifications.”

Getting Started

Unsolicited communication from VolServ can be directed to
either:

• A preselected RPC address.

• Or, to an internet address associated with an enterprise. The
RPC address or enterprise assigned for unsolicited
communication is assignable at the MediaClass level. Refer
to the Command Reference book for detailed information
about defining unsolicited communication parameters for a
MediaClass group.

This address is used as the receiver for unsolicited messages
that VolServ transmits. These messages are transmitted at
the completion of VolServ processing that had an impact on
any medium associated with the particular MediaClass
group.

Running the following commands: VSCMD_Import,

VSCMD_Export, VSCMD_CheckIn, VSCMD_CheckOut,
VSCMD_Mount, VSCMD_Dismount,
VSCMD_Reclassify can generate unsolicited communication

from VolServ. This unsolicited communication is returned to
the client issuing the command only if that client is specified in
the processing parameters as the destination for all unsolicited
communication for the MediaClass group.

601355 Rev A Getting Started 1-9

and

API Guide

VolServ API Integration

To integrate the VolServ API in a client application, the client
includes the header file vs_client.h in the source modules
that reference the VolServ API types and functions. The client
then links the program with the VolServ API library

libvsapi.a with the -lvsapi option for the cc or ld

commands.
The following five header files are delivered with the VolServ

API:

Header Files Description

vs_client.h Includes the VolServ API header files needed

by the client.

vs_defs.h Includes the VolServ API definitions needed

for the parameter lists.

vs_types.h Includes the VolServ API types and

enumerations.

vs_globals.h Includes the VolServ API global variables that

are accessible to the client.

vs_proto.h Includes the prototypes for all VolServ API

functions.

Before any command can be sent by the client program, the
VolServ API must by initialized with a call to

VS_Initialize. The routine VS_Initialize creates and

initializes the APIs required variables and creates a
communication link with VolServ. Before the client program
terminates, it calls the

VS_Terminate routine to allow the

VolServ API to clean up its processing.
For example:

1-10 Getting Started 601355 Rev A

#include <stdio.h>
#include <vs_client.h>
main()
{

VST_HOSTNAME vshost;

API Guide

/* get volserv host name from the user */
printf ( “Enter the name of the VolServ host

computer ==> “ );

scanf ( “%s”, vshost );

/* initialize the VolServ API. */
/* returns TRUE if successful, */
/* FALSE if fails. */
if ( VS_Initialize ( vshost, 0, 30 ) )
{

/* send and create commands */

.............

/* allow VolServ API to */
/* terminate properly */

VS_Terminate();
}
else
{

printf ( “Error initializing VolServ

API” );

}
}

Getting Started

601355 Rev A Getting Started 1-11

API Guide

API Types

Objects

API objects and handles are described below.

The VolServ API uses an object-oriented metaphor for tracking
VolServ items. Each object contains several fields that describe
the object, routines that create and destroy the object, and
routines that access the data contained within the object.

The following objects mirror items found in VolServ: archive,
archive media class, archive type capacity, component, drive,
drive pool, enterprise group, enterprise connection, media,
MediaClass group, media type, mount selection expression,
mount selection criteria, mount selection criteria group, and
request. These objects usually store information relating only to
their VolServ counterparts.

Note

The following objects are specific to the VolServ API:
command, error, notify, status, and table. These objects
contain information about the associated command and its
statuses.

Handles

A handle is a pointer to a VolServ API object. An object is
created by an initialization routine that returns a handle that
points to the newly allocated object. After a handle is created, it
is passed as a parameter to the routines that access the handle’s
data.

1-12 Getting Started 601355 Rev A