Quantum API User Manual

API Guide

VolServ Version 5.2

November 2003

6-01004-01 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-2003 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 USA
Tel.: [phone]
Fax: [phone]
ATAC: 1-800-827-3822
http://www.adic.com

ADIC Europe
ZAC des Basses Auges
1, rue Alfred de Vigny
78112 Fourqueux, France
Tel.: [phone]
Fax: [phone]

ADIC Germany Beteiligungs
GmbH, KG
Eschenstraße 3
D-89558 Böhmenkirch, Germany
Tel:[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 USA
Tel.: [phone]
Fax: [phone]
ATAC: 1-800-827-3822
http://www.adic.com

ADIC Europe
ZAC des Basses Auges
1, rue Alfred de Vigny
78112 Fourqueux, France
Tel.: [phone]
Fax: [phone]

ADIC Germany Beteiligungs
GmbH, KG
Eschenstraße 3
D-89558 Böhmenkirch, Germany
Tel:[phone]

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

API Guide

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

6-01004-01 Rev A Contents i

API Guide

API Functions 2

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

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

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

VS_Archive

MediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32

VS_Archive

MediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36

VS_Archive

MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41

VS_Archive
MediaClass_

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

ii Contents 6-01004-01 Rev A

API Guide

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

VS_

CriteriaGroup_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-149

VS_

CriteriaGroup_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-155

VS_

CriteriaGroup_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-161

VS_

CriteriaGroup_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-166

6-01004-01 Rev A Contents iii

API Guide

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-226

VS_
Expression_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-232

VS_Global_

GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-239

VS_Global_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-244

VS_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-250

VS_Media_

Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-254

iv Contents 6-01004-01 Rev A

API Guide

VS_Media_

Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-259

VS_Media_

GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-263

VS_Media_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-269

VS_

MediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-275

VS_

MediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-280

VS_

MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-285

VS_
MediaClass_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-293

VS_
MediaType_

Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-301

VS_
MediaType_

Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-304

VS_
MediaType_

GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-307

VS_
MediaType_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-311

VS_Mount_

Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-315

VS_Mount_

Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-320

6-01004-01 Rev A Contents v

API Guide

VS_

MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-324

VS_Mount_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-333

VS_Notify_

Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-341

VS_Notify_

Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-346

VS_Notify_

GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-351

VS_Notify_

Listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-359

VS_Notify_

SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-366

VS_Request_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-373

VS_Request_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-376

VS_Request_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-379

VS_Request_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-383

VS_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-387

VS_Status_

GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-391

VS_Table_

AddEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-405

VS_Table_

Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-412

VS_Table_
CreateAdd-

Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-419

VS_Table_

Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-423

VS_Table_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-427

vi Contents 6-01004-01 Rev A

API Guide

VS_Table_

RemoveEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-431

VS_Table_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-435

VS_Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-440

VS_

TypeCapacity_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-442

VS_

TypeCapacity_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-446

VS_

TypeCapacity_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-451

VS_

TypeCapacity_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-458

VSCMD_

ArchiveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-465

VSCMD_

ArchiveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-475

VSCMD_

ArchiveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-481

VSCMD_

ArchiveVary_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-489

VSCMD_Audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-495

VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-504

VSCMD_

Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-509

VSCMD_
Cancel_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-518

VSCMD_

Checkin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-524

6-01004-01 Rev A Contents vii

API Guide

VSCMD_
Checkin_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-533

VSCMD_

Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-538

VSCMD_

Checkout_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-547

VSCMD_ClearEject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-552

VSCMD_ClearEject_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-561

VSCMD_

Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-567

VSCMD_

Connect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-579

VSCMD_
Connect-

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-585

VSCMD_
Connect­Query_

Set-Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-594

VSCMD_

CreateArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-599

VSCMD_
CreateArchiveMediaClass_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-613

VSCMD_
CreateMedia-

Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-623

viii Contents 6-01004-01 Rev A

API Guide

VSCMD_
CreateMedia­Class_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-636

VSCMD_DriveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-645

VSCMD_DriveVary_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-656

VSCMD_

Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-664

VSCMD_
Export_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-673

VSCMD_

Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-678

VSCMD_
Import_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-688

VSCMD_
Intransit-

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-693

VSCMD_
Intransit­Query_Set-

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-701

VSCMD_Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-706

VSCMD_Lock_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-716

VSCMD_
MediaClass-

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-721

6-01004-01 Rev A Contents ix

API Guide

VSCMD_
MediaClass­Query_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-730

VSCMD_

MediaQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-735

VSCMD_

MediaQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-743

VSCMD_
MediaType-

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-748

VSCMD_
MediaType­Query_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-757

VSCMD_

ModifyMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-763

VSCMD_

ModifyMedia_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-773

VSCMD_

CreatePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-780

VSCMD_
CreatePool_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-789

VSCMD_

DeleteArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-795

VSCMD_
DeleteArchiveMediaClass_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-804

VSCMD_
DeleteMedia

Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-810

xContents 6-01004-01 Rev A

API Guide

VSCMD_
DeleteMedia
Class_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-818

VSCMD_

DeletePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-823

VSCMD_
DeletePool_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-831

VSCMD_

Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-836

VSCMD_
Disconnect_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-846

VSCMD_

Dismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-852

VSCMD_

Dismount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-861

VSCMD_DrivePoolQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-867

VSCMD_DrivePoolQuery_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-876

VSCMD_DriveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-882

VSCMD_DriveQuery_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-891

VSCMD_
Modify

ArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-897

VSCMD_
Modify
ArchiveMediaClass_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-912

6-01004-01 Rev A Contents xi

API Guide

VSCMD_

ModifyMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-918

VSCMD_
ModifyMediaClass_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-931

VSCMD_

ModifyPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-938

VSCMD_
ModifyPool_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-949

VSCMD_

Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-955

VSCMD_
Mount_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-971

VSCMD_Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-979

VSCMD_Move_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-990

VSCMD_MultiMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-996

VSCMD_
MultiMount_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1007

VSCMD_Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1013

VSCMD_

QueryMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1017

VSCMD_

QueryMount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1026

VSCMD_

Reclassify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1031

VSCMD_
Reclassify_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1043

xii Contents 6-01004-01 Rev A

API Guide

VSCMD_

Reprioritize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1049

VSCMD_
Reprioritize_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1058

VSCMD_
Request-

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1064

VSCMD_
Request
Query_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1072

VSCMD_

Unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1077

VSCMD_
Unlock_Set

Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1085

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

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

6-01004-01 Rev A Contents xiii

API Guide

xiv Contents 6-01004-01 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 6-01004-01 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.

6-01004-01 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 witho ut
the backward slash.)

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

P-4 Preface 6-01004-01 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 . Co ntains 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
requires the Adobe® Acrobat® Reader to view the

accompanying electronic documentation. The Reader allows
you to view and navigate the electronic documentation files yet
preserves the page design and graphics from the printed books.

6-01004-01 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 6-01004-01 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 6-01004-01 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.

6-01004-01 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 6-01004-01 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. An y 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

6-01004-01 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 6-01004-01 Rev A