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

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.

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

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

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

API Guide

Each handle has the four base routines descried in the table
below:

Routine Description

initializer The initializer creates and initializes the data

held by the handle and re turns a pointer to the
client that is used as a parameter to the
destructor, assignment, and accessor
functions.

destructer The destructor frees the space held by the

handle.

assignment The assignment function allows the client to

assign values to fields within the handle . A call
to the assignment function takes a variable
argument list that includes a handle and a list
of identifier-value pairs. The handle identifies
the handle for which field values are being
assigned. An identifier-value pair identifies the
field for which a value is being assigned and
the value being assigned to that fie ld.

accessor The accessor function allows the client to

retrieve v alues f rom fields wit hin the ha ndle. A
call to the accessor function takes a variable
argument list that includes a handle and a list
of identifier-pointer pairs. The handle identifies
the handle for which field values are to be
retrieved. An identifier-pointer pair identifies
the field for which the value is to be retrieved
and a pointer to the location where the field
value is to be stored.

Getting Started

The following example creates a command handle and uses the
assignment function to set the priority field within the command
object to a value of 10.

6-01004-01 Rev A Getting Started 1-13

API Guide

VST_COMMAND_HANDLE cmdh;
if ( (cmdh = VS_Command_Create()) != NULL )
{

VS_Command_SetFields (cmdh,

VSID_PRIORITY, 10,

VSID_ENDFIELD );
}

1-14 Getting Started 6-01004-01 Rev A

API Guide

Naming

The table below describes the API naming conventions:

Conventions

Item Description

Handles Handle names start with the VST prefix, followed by the specific

object name, and end with the HANDLE suffix. The name shou ld be
in all capitals. For example:

Types Types are defined in a client-accessed header file begin with the

VST prefix. For example:

Definitions Definitions that are defined in the client definition header file

should begin with the VSD prefix. For example:

VSD_DRIVE_NAME_LEN

Enumerations En umerations ha v e two con ventions t o follo w. The type begins with

the VST prefix. The values inside the enumeration structure begin
with the VSE prefix.

For example:

typedef enum {

VSE_DRIVETYPE_NONE

= 0,

VSE_DRIVETYPE_MAGTAPE =1

} VST_DRIVE_TYPE

VST_DRIVE_HANDLE

VST_DRIVE_ID

Getting Started

Global Variables Global variables begin with the VSG prefix. For example:

VSG_ERROR_CODE

Identifiers Identifiers that are used in the “assignment” and “accessor”

functions to identify the field being accessed within each handle
begin with the VSID prefix. The following identifier is for a drive
identifier, for example:

6-01004-01 Rev A Getting Started 1-15

VSID_DRIVE_ID

API Guide

Item Description

Functions Function names used in the VolServ API also follow a specific set

of rules. All function names exist in the format of the VS prefix,
followed by the object name, and ending with a condensed
description of the function. The following example shows the
overall form of function names:

VS_objectname_functiondescription()

The function descriptions also follo w a naming conv ention, with the
description coming from the following list: “GetFields”, “SetFields”,
“Create”, and “Destroy.” Refer to the following example:

VS_Drive_Create();
VS_Drive_Destroy(VS_DRIVE_HANDLE);
VS_Drive_GetFields(VS_DRIVE_HANDLE, ... )
VS_Drive_SetFields(VS_DRIVE_HANDLE, ... )

The “GetFields” and “SetFields” functions each take a
variable argument list beginning with a handle. After the
handle, the client specifies identifier-parameter pairs (or
triples in some cases). These identifiers tell the function what
field is to be accessed. The parameter tells the function either
the value to be assigned to the field or the location where the
filed value is to be retrie v ed. The identif ier VSID_ENDFIELD
must appear at the end of the variable argument list. Refer to
the following example:

mount_status ( VST_COMMAND_HANDLE

cmdh )

{

VST_STATUS_HANDLE statush;
VST_ERROR_HANDLE errorh
VST_STATUS_CODE satcode;
VST_MEDIA_ID media;
VST_DRIVE_ID drive;

1-16 Getting Started 6-01004-01 Rev A

Item Description

VS_Command_GetFields ( cmdh,

VSID_STATUS_HANDLE,

&statush,

VSID_ERROR_HANDLE

&errorh,

VSID_STATUS_CODE,

&statcode,

VSID_ENDFIELD );

if ( statcode == VSE_STATUS_OK )
{

VS_Status_GetFields ( status,

VSID_MEDIA_ID, media,
VSID_DRIVE_ID, &drive,
VSID_ENDFIELD );

printf ( “media [%s] mounted on
[%d]”, media, drive );
}
else
{

print_error_code ( errorh );
}

}

API Guide

Getting Started

Function names that map directly to a VolServ Command
begin with the VSCMD prefix, followed by the command
name. Refer to the following example:

VSCMD_command_option

ollowing is an actual command:

The f

VSCMD_DriveQuery

( VS_COMMAND_HANDLE, …);

6-01004-01 Rev A Getting Started 1-17

API Guide

Item Description

Parameter Defaults Two levels of default settings used in the API software—global

defaults and command-specific defaults.

• Global defaults are initialized at startup and can be set or
retrieved using the

VS_Global_SetFields() and

VS_Global_GetFields() calls.

• Command-specific defaults are set using the

VSCMD_commandname_SetDefaults() calls.

If command-specific defaults are set for a specific command (e.g.,
mount), they override the global defaults for all requests for
execution of that command. To override a default parameter value
for a specific instance of a command request, the parameter
identifier and the value to be used for the parameter can be
submitted on the command request (e.g.,
itself.

VSCMD_Mount())

1-18 Getting Started 6-01004-01 Rev A

API Guide

Dispatch Routines

Dispatch routines are functions within the client software that
the API automatically calls when status messages or
MediaClass callbacks are received from VolServ. The dispatch
routine for MediaClass callbacks (also referred to as
notifications) is described on the man page for

VS_Notify_SetFields(l).

Dispatch routines for status messages are set for all requests
with the VS_Global_SetFields() call, for all requests of a
given type with the VSCMD_request_SetDefaults() call, or as
part of the call that sends the VolServ request.

Dispatch routines are prototyped as follows:

• void dispatchroutine(VST_COMMAND_HANDLE handle)
The dispatch routine takes one argument. This is the command

handle for the request that received status.

Getting Started

6-01004-01 Rev A Getting Started 1-19

API Guide

Global Parameters

Global parameters are a group of parameters that are used by
the API for all VolServ requests. Most of these are sent to
VolServ, but some serve as control information for the API. The
following table describe these parameters.

Global Parameter Description

VSID_CLIENT_DISPATCH Pointer to the dispatch function for all commands.
VSID_ENTERPRISE_ID Identifier of the enterprise, if any, to receive intermediate and

final status on every command requ est.

VSID_NOTIFY_DISPATCH Pointer to the dispatch function used for notification

(MediaClass callback) processing.

VSID_PRIORITY
(defaults to 15)

VSID_RETRY_LIMIT Number of times the API software is to retry for command

Execution priority assigned to every command request.
Values range from 1 (highest) to 32 (lowest).

status from VolServ before returning a time-out to the client
software.

Total length of time the API software waits for a command
status from VolServ is (VSID_RETRY_LIMIT plus1) multiplied
by the VSID_TIMEOUT_VALUE.

VSID_RETRY_LIMIT is not applicable when the API software
executes in asynchronous mode.

VSID_STATUS_WAIT_FLAG Status wait flag for all commands. This flag controls whether

the API operates in synchronous or asynchronous mode. If its
value TRUE, the API waits for status (operate in synchronous
mode.) If its value is FALSE, the API operates in asynchronous
mode.

VSID_TIMEOUT_VALUE Amount of time, in seconds, VolServ waits for status before

timing-out to the client software for this request.

VSID_USER_FIELD A 16-character field provided for user information. Information

entered in this field is echoed back to the user in every status
message returned for each command. Neither the API
software nor VolServ uses USER_FIELD.

1-20 Getting Started 6-01004-01 Rev A

API Guide

Global Variables

The following global variables are available to any software
using the VolServ API.

Global Variable Description

VSG_Error Global error handle. It is set if an

error condition occurs in a
function that does not use a
command handle. This includes
the utility functions, handle
functions, and the functions that
set request- specific defaults.

See the man page for
VS_Error_GetFields to learn
how to access error codes.

VSG_Command_Received Pointer to t he command handle

whose status was just received
from VolServ. The
VSG_Command_Received can
only be used in asynchronous
processing.

Getting Started

6-01004-01 Rev A Getting Started 1-21

API Guide

API Error Handling

The API differentiates between:

• Errors that occur during API processing.

• Errors that occur within VolServ.
To accomplish this, there are two identifying parts for each

error—the first part identifies where the error occurred—the
second part identifies the specific error.

The API tracks errors by using error handles. There is an error
handle associated with each command, as well as a global error
handle. The global error handle is used to track errors that
cannot be associated directly with a command (e.g., bad handle
type and null handle).

The error code returned by the API is of the form: AAANNN,
where AAA is a three-letter string designating where the error
originates, and NNN is a numeric code designating the specific
error. The three-letter string maps either to an API object or to
VolServ. The numeric code represents either an API internal
error or the VolServ error code returned in the command’s
status.

The following example shows how to access an error code:

int numcode, objcode;
VST_ERROR_CODE errcode;
VST_ERROR_HANDLE errorhandle;

VS_Error_GetFields (errorhandle,

VSID_ERROR_OBJECT,

&objcode,

VSID_ERROR_NUMBER,

&numcode,

VSID_ERROR_CODE,

errcode

1-22 Getting Started 6-01004-01 Rev A

VSID_ENDFIELD);

printf ( “error code %s\n”, errcode );
printf ( “object code for error: %d\n”,

objcode );

printf ( “numeric code for error: %d\n”,

numcode );

API Guide

Getting Started

6-01004-01 Rev A Getting Started 1-23

API Guide

Using the API

Command Handle

Command Calls

To send a command to VolServ, the client has to create a
command handle in which the request and its status is kept. The
command handle holds the information needed for the VolServ
API to process the command. The information in the command
handle is general for all commands (e.g., priority, time-out
values). Most fields are defaulted to values that can be
overridden by the client.

Each command has one entry point - a call of the form:

VSCMD_commandname

Each command accepts the command handle and a variable
length argument list with parameter name and value pairs. Each
parameter name and value pair specifies a command option and
its corresponding value.

The options are divided into two parts: the general command
options and the command-specific options. The general
command options are fields contained in all requests (e.g.,
priority). The specific command options are fields particular to
that type of request (e.g., archive name for the archive vary
command). A specific command option may not be unique to
one command, it can be used in several different commands.
Each command call returns a boolean value that indicates its
success or failure.

1-24 Getting Started 6-01004-01 Rev A

See the following example:

if ( VSCMD_Mount ( cmd_handle,

VSID_MEDIACLASS_NAME,”scratch”

VSID_DRIVEPOOL_NAME,

”stagepool”,

VSID_PRIORITY,1,

VSID_ENDFIELD ) )
{
printf ( “mount successful\n” );
}

API Guide

Getting Started

Command Defaults

Options that are not passed in the argument list are defaulted to
command-specific defaults. These defaults are kept on a
command basis and can be set to client-desired values. The
function to set command-specific defaults is of the form:

VSCMD_commandname_SetDefaults

The defaults are specified in a v ariable length argument list with
parameter name value pairs. The values in the command
parameter list supersede global default values. See the
following example:

VSCMD_Mount_SetDefaults (

VSID_PRIORITY, 1,
VSID_MEDIACLASS_NAME,”scratch”
VSID_DRIVEPOOL_NAME,
”defaultpool”,
VSID_ENDFIELD);

VSCMD_Mount (cmd_handle,

VSID_DRIVEPOOL_NAME,”stagepool”,

VSID_ENDFIELD );

6-01004-01 Rev A Getting Started 1-25

API Guide

These two commands perform the same function as the
previous example. The VSCMD_Mount_SetDefaults function
sets command-specific defaults for all future Mount commands
within this process. When the Mount command is issued, the
parameters that are not specified are defaulted to the current
command-specific defaults. The defaults specified by

VSCMD_Mount_SetDefaults are valid only for Mount

commands.

Command Status

After each status received from VolServ, the pertinent status
fields are stored in a status handle within the command handle.
The client can get the status handle from the command handle
with the VS_Command_GetFields function. After the status
handle is obtained, any command-specific field associated with
the status can be obtained through the

VS_Status_GetFields function. See to the following

example:

VST_MEDIA_ID mediaid;
VST_DRIVE_ID driveid;
VST_STATUS status;
VST_COMMAND_HANDLE cmd_handle;
VST_STATUS_HANDLE status_handle;

if ( (cmd_handle = VS_Command_Create ())

==

(VST_COMMAND_HANDLE) NULL )

{

return ( -1 );

}

1-26 Getting Started 6-01004-01 Rev A

if ( VSCMD_Mount (cmd_handle,

VSID_MEDIACLASS_NAME,

”scratch”,

VSID_DRIVEPOOL_NAME,

”stagepool”

VSID_ENDFIELD ) )
{

VS_Command_GetFields (

cmd_handle,

VSID_STATUS, &status,

VSID_STATUS_HANDLE,&status_handle,

VSID_ENDFIELD );

if ( status == VSE_STATUS_OK )
{

VS_Status_GetFields (
status_handle,

VSID_MEDIA_ID,

mediaid,

VSID_DRIVE_ID,
&driveid,

VSID_ENDFIELD );

API Guide

Getting Started

printf ( “Media [%s] mounted on
drive,

[%d]\n”,mediaid, driveid );
}

}

6-01004-01 Rev A Getting Started 1-27

API Guide

Processing

Asynchronous

The VolServ API allows for both asynchronous and
synchronous processing of VolServ commands.

For asynchronous processing, the VolServ API returns control
to the client after initial status is received.

2

VSCMD_

1

cmd

4

5

Client

Program

1. Client Program calls the command function (VSCMD_cmd).

2. The VSCMD_cmd calls the Volume Server.

3. VolServ returns initial status to VSCMD_cmd.

4. VSCMD_cmd returns control to the Client Program.

5. The Client Program calls the VS_Select loop to wait for status.

8

3

VS_Select

6

7

VS_CallBack

Volume
Server

6. VS_Select calls the command specific VS_CallBack.

7. VS_CallBack returns status to the VS_Select.

8. VS_Select returns status to the Client Program.

To receive subsequent status from VolServ API, the client
invokes the VolServ APIs

VS_Select function. It is the

responsibility of the client to place the VolServ API into its
select loop so all subsequent statuses can be received. In
asynchronous processing, the client can issue multiple VolServ
commands and immediately receive their statuses.

1-28 Getting Started 6-01004-01 Rev A

API Guide

Asynchronous processing also gives the client more control
over the processing en vironment. The VSID_RETRY_LIMIT is
not applicable when the API software executes in asynchronous
mode. If the VSID_STATUS_WAIT_FLAG value is FALSE, the
API operates in asynchronous mode.

Getting Started

Synchronous

For synchronous processing, the VolServ API returns control to
the client only after final status (or time-out) is received.

2

VSCMD_

cmd

4

8

1

Client

Program

1. Client Program calls the command function (VSCMD_cmd).

2. The VSCMD_cmd calls the Volume Server.

3. VolServ returns initial status to VSCMD_cmd.

4. VSCMD_cmd calls the VS_Select loop to wait for status.

5. VS_Select calls the command specific VS_Callback.

6. VS_Callback returns status to VS_Select.

7. VS_Select returns control to VSCMD_cmd.

8. VSCMD_cmd returns control to the Client Program.

7

3

VS_Select

6

VS_CallBack

5

Volume
Server

Synchronous processing allows processing of only one
command at a time. If the VSID_STATUS_WAIT_FLAG value is
TRUE, the API operates in synchronous mode.

6-01004-01 Rev A Getting Started 1-29

API Guide

API Functions

The API function descriptions in this book are presented as
follows:

Function Description

vsapi Provides a general introduction t o V olSe rv

API processing.

VS_cmdname Describes functions used to create,

destroy, assign, and access handles.
These functions are listed in alphabetical
within the subgroup.

VSCMD_cmdname Describes how a user accesses VS

commands through the API. These
functions are listed in alphabetical order
within the subgroup. The VolServ API
allows for both asynchronous and
synchronous processing of VolServ
commands.

1-30 Getting Started 6-01004-01 Rev A

NOTES

API Guide

Getting Started

6-01004-01 Rev A Getting Started 1-31

API Guide

NOTES

1-32 Getting Started 6-01004-01 Rev A

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

2

API

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

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

Functions

Functions

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

API Guide

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

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

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

2-2 API Functions 6-01004-01 Rev A

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

VS_Notify_Create . . . . . . . . . . . . . . . . . . . . . . . . 2-339

VS_Notify_Destroy. . . . . . . . . . . . . . . . . . . . . . . 2-344

VS_Notify_GetFields . . . . . . . . . . . . . . . . . . . . . 2-349

VS_Notify_Listen . . . . . . . . . . . . . . . . . . . . . . . . 2-357

VS_Notify_SetFields. . . . . . . . . . . . . . . . . . . . . . 2-363

API Guide

VS_Request_Create. . . . . . . . . . . . . . . . . . . . . . .2-370

VS_Request_Destroy . . . . . . . . . . . . . . . . . . . . . 2-373

VS_Request_GetFields . . . . . . . . . . . . . . . . . . . . 2-376

VS_Request_SetFields . . . . . . . . . . . . . . . . . . . . 2-380

VS_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-384

VS_Status_GetFields. . . . . . . . . . . . . . . . . . . . . .2-387

VS_Table_AddEntry. . . . . . . . . . . . . . . . . . . . . .2-401

VS_Table_Create. . . . . . . . . . . . . . . . . . . . . . . . .2-408

VS_Table_CreateAddEntry . . . . . . . . . . . . . . . . 2-415

VS_Table_Destroy. . . . . . . . . . . . . . . . . . . . . . . .2-419

VS_Table_GetFields . . . . . . . . . . . . . . . . . . . . . .2-423

VS_Table_RemoveEntry . . . . . . . . . . . . . . . . . . 2-427

VS_Table_SetFields. . . . . . . . . . . . . . . . . . . . . . .2-431

VS_Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-436

VS_TypeCapacity_Create . . . . . . . . . . . . . . . . .2-438

VS_TypeCapacity_Destroy . . . . . . . . . . . . . . . .2-442

VS_TypeCapacity_GetFields. . . . . . . . . . . . . . .2-447

Functions

6-01004-01 Rev A API Functions 2-3

API Guide

VS_TypeCapacity_SetFields . . . . . . . . . . . . . . .2-455

VSCMD_ArchiveQuery . . . . . . . . . . . . . . . . . . . 2-462

VSCMD_ArchiveQuery_SetDefaults. . . . . . . . 2-472

VSCMD_ArchiveVary . . . . . . . . . . . . . . . . . . . . 2-478

VSCMD_ArchiveVary_SetDefaults . . . . . . . . .2-486

VSCMD_Audit . . . . . . . . . . . . . . . . . . . . . . . . . . 2-492

VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . 2-501

VSCMD_Cancel. . . . . . . . . . . . . . . . . . . . . . . . . .2-506

VSCMD_Cancel_SetDefaults. . . . . . . . . . . . . . . 2-515

VSCMD_Checkin . . . . . . . . . . . . . . . . . . . . . . . .2-521

VSCMD_Checkin_SetDefaults . . . . . . . . . . . . . 2-530

VSCMD_Checkout . . . . . . . . . . . . . . . . . . . . . . .2-535

VSCMD_Checkout_SetDefaults . . . . . . . . . . . . 2-544

VSCMD_ClearEject. . . . . . . . . . . . . . . . . . . . . . .2-549

VSCMD_ClearEject_SetDefaults. . . . . . . . . . . . 2-558

VSCMD_Connect . . . . . . . . . . . . . . . . . . . . . . . . 2-564

VSCMD_Connect_SetDefaults . . . . . . . . . . . . .2-576

VSCMD_ConnectQuery. . . . . . . . . . . . . . . . . . .2-582

VSCMD_ConnectQuery_Set-Defaults . . . . . . .2-591

VSCMD_CreateArchiveMediaClass . . . . . . . . 2-596

VSCMD_CreateArchiveMediaClass_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-610

VSCMD_CreateMediaClass. . . . . . . . . . . . . . . . 2-620

VSCMD_CreateMediaClass_SetDefaults . . . .2-633

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

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

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

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

2-4 API Functions 6-01004-01 Rev A

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

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

VSCMD_IntransitQuery . . . . . . . . . . . . . . . . . . 2-689

VSCMD_IntransitQuery_SetDefaults . . . . . . .2-697

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

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

VSCMD_MediaClass-Query . . . . . . . . . . . . . . . 2-718

VSCMD_MediaClassQuery_SetDefaults. . . . . 2-727

VSCMD_MediaQuery . . . . . . . . . . . . . . . . . . . .2-732

VSCMD_MediaQuery_SetDefaults . . . . . . . . . 2-740

VSCMD_MediaTypeQuery. . . . . . . . . . . . . . . .2-745

API Guide

VSCMD_MediaTypeQuery_SetDefaults. . . . . 2-754

VSCMD_ModifyMedia . . . . . . . . . . . . . . . . . . . 2-760

VSCMD_ModifyMedia_SetDefaults . . . . . . . . 2-770

VSCMD_CreatePool . . . . . . . . . . . . . . . . . . . . . .2-777

VSCMD_CreatePool_SetDefaults. . . . . . . . . . . 2-786

VSCMD_DeleteArchiveMediaClass. . . . . . . . . 2-792

VSCMD_DeleteArchiveMediaClass_

SetDefaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-801

VSCMD_DeleteMediaClass. . . . . . . . . . . . . . . .2-807

VSCMD_DeleteMediaClass_SetDefaults. . . . . 2-815

VSCMD_DeletePool . . . . . . . . . . . . . . . . . . . . . . 2-820

VSCMD_DeletePool_SetDefaults . . . . . . . . . . .2-828

VSCMD_Disconnect. . . . . . . . . . . . . . . . . . . . . .2-833

VSCMD_Disconnect_SetDefaults. . . . . . . . . . . 2-843

VSCMD_Dismount. . . . . . . . . . . . . . . . . . . . . . . 2-850

VSCMD_Dismount_SetDefaults. . . . . . . . . . . .2-859

VSCMD_DrivePoolQuery . . . . . . . . . . . . . . . . . 2-865

Functions

6-01004-01 Rev A API Functions 2-5

API Guide

VSCMD_DrivePoolQuery_SetDefaults . . . . . .2-874

VSCMD_DriveQuery . . . . . . . . . . . . . . . . . . . . . 2-880

VSCMD_DriveQuery_SetDefaults . . . . . . . . . .2-889

VSCMD_ModifyArchiveMediaClass. . . . . . . .2-895

VSCMD_ModifyArchiveMediaClass_

SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-909

VSCMD_ModifyMediaClass. . . . . . . . . . . . . . . 2-915

VSCMD_ModifyMediaClass_SetDefaults. . . . 2-928

VSCMD_ModifyPool . . . . . . . . . . . . . . . . . . . . . 2-936

VSCMD_ModifyPool_SetDefaults . . . . . . . . . . 2-946

VSCMD_Mount. . . . . . . . . . . . . . . . . . . . . . . . . .2-952

VSCMD_Mount_SetDefaults. . . . . . . . . . . . . . . 2-968

VSCMD_Move. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-976

VSCMD_Move_SetDefaults . . . . . . . . . . . . . . . 2-987

VSCMD_MultiMount. . . . . . . . . . . . . . . . . . . . . 2-993

VSCMD_MultiMount_SetDefaults. . . . . . . . . 2-1004

VSCMD_Ping. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1010

VSCMD_QueryMount . . . . . . . . . . . . . . . . . . . 2-1014

VSCMD_QueryMount_SetDefaults . . . . . . . .2-1023

VSCMD_Reclassify. . . . . . . . . . . . . . . . . . . . . . 2-1028

VSCMD_Reclassify_SetDefaults. . . . . . . . . . .2-1040

VSCMD_Reprioritize . . . . . . . . . . . . . . . . . . . .2-1046

VSCMD_Reprioritize_SetDefaults . . . . . . . . . 2-1055

VSCMD_RequestQuery . . . . . . . . . . . . . . . . . . 2-1061

VSCMD_RequestQuery_SetDefaults. . . . . . . 2-1070

VSCMD_Unlock . . . . . . . . . . . . . . . . . . . . . . . . 2-1075

VSCMD_Unlock_SetDefaults . . . . . . . . . . . . .2-1083

2-6 API Functions 6-01004-01 Rev A

Roadmap

API Guide

Topic

Naming conventions.
Global parameters.
Error handling.

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

Refer To

Chapter

1

Functions

6-01004-01 Rev A API Functions 2-7

API Guide

VS_Archive_
Create

Synopsis

VS_Archive_Create allocates a VolServ API archive
handle. An archive handle is used to pass archi v e information to
and from VolServ.

VST_ARCHIVE_HANDLE VS_Archive_Create ( void )

Arguments None

Return Values

VS_Archive_Create returns:

• An archive handle, if one can be allocated.

• NULL, if an archive handle cannot be allocated. An
appropriate error code is set in VSG_Error.

• VSE_ERR_OUTOFMEM - Memory allocation error.

Example 1 /****************************************

*********
2*
3 * FUNCTION: vst_archive_handle
4*
5 * PURPOSE:
6 * This function tests an archive handle.
7*
8 * PARAMETERS:
9 * none
10 *
11 ****************************************

*********/
12 #ifdef ANSI_C
13 VST_BOOLEAN vst_archive_handle(void)
14 #else
15 VST_BOOLEAN vst_archive_handle(void)
16 #endif
17 {

2-8 API Functions 6-01004-01 Rev A

API Guide

18 VST_BOOLEAN rc =

VSE_FALSE;
19 VST_ARCHIVE_HANDLE h;
20 VST_ARCHIVE_TYPE

ArchiveType;
21 VST_ARCHIVE_NAME

ArchiveName;
22 VST_HOSTNAME

ConsoleLoc;
23 VST_COMP_STATE

ComponentState;
24 VST_ARCHIVE_MODE

ArchiveMode;
25 VST_ARCHIVE_FILL_MODE FillMode;
26 VST_ARCHIVE_CONFIG_STATE

ConfigState;
27
28 /* create the handle */

Functions

29 h = VS_Archive_Create();
30 if (h != (VST_ARCHIVE_HANDLE) NULL)
31 {
32 /* get values from user */
33 printf(“*** Archive Handle

***\n”);
34 printf(“Enter Archive Type ==> “);
35 ArchiveType = atoi(gets(input));;
36 printf(“Enter Archive Name ==> “);
37 gets(ArchiveName);
38 printf(“Enter Console Display

Location ==> “);
39 gets(ConsoleLoc);
40 printf(“Enter archive state ==>

“);
41 ComponentState =

atoi(gets(input));
42 printf(“Enter Archive Mode ==> “);
43 ArchiveMode = atoi(gets(input));
44 printf(“Enter Fill Mode ==> “);
45 FillMode = atoi(gets(input));;
46 printf(“Enter Config State ==> “);
47 ConfigState = atoi(gets(input));;
48 /* set the fields in the handle */

6-01004-01 Rev A API Functions 2-9

API Guide

49 rc = VS_Archive_SetFields(h,
50 VSID_ARCHIVE_NAME,

ArchiveName,

51 VSID_ARCHIVE_TYPE,

ArchiveType,

52

VSID

_ARCHIVE_CONSOLE_LOCATION,Con

soleLoc,

53 VSID_COMP_STATE,

ComponentState,

54 VSID_ARCHIVE_MODE,

ArchiveMode,

55 VSID_ARCHIVE_FILL_MODE,

FillMode,

56 VSID_ARCHIVE_CONFIG_STATE,

ConfigState,
57 VSID_ENDFIELD);
58 if (rc)
59 {
60 vst_print_archive(h);
61 }
62 VS_Archive_Destroy(h);
63 }
64 return(rc);
65 }

See Also

• vsapi(l),

• VS_Archive_Destroy(l),

• VS_Archive_GetFields(l),

• VS_Archive_SetFields(l),

• VS_Error_GetFields(l)

2-10 API Functions 6-01004-01 Rev A

API Guide

VS_Archive_ Destroy

Synopsis

VS_Archive_Destroy deallocates an archive handle that
was allocated with VS_Archive_Create. An archive
handle is used to pass archive information to and from VolServ.

VST_BOOLEAN VS_Archive_Destroy
(VST_ARCHIVE_HANDLE handle)

Arguments • handle = Archive handle to destroy.

Return Values

• VS_Archive_Destroy returns:

• VSE_TRUE - Successful execution.

• VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.

• VSE_ERR_BADHANDLE - Specified handle was not an
archive handle.

• VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.

Functions

Example 66 /***************************************

**********
67 * FUNCTION: vst_archive_handle
68 *
69 * PURPOSE:
70 * This function tests an archive handle.
71 * PARAMETERS:
72 * none
73 *
74 ****************************************

*********/
75 #ifdef ANSI_C
76 VST_BOOLEAN vst_archive_handle(void)
77 #else

6-01004-01 Rev A API Functions 2-11

API Guide

78 VST_BOOLEAN vst_archive_handle(void)
79 #endif
80 {
81 VST_BOOLEAN rc =

VSE_FALSE;
82 VST_ARCHIVE_HANDLE h;
83 VST_ARCHIVE_TYPE

ArchiveType;
84 VST_ARCHIVE_NAME

ArchiveName;
85 VST_HOSTNAME

ConsoleLoc;
86 VST_COMP_STATE

ComponentState;
87 VST_ARCHIVE_MODE

ArchiveMode;
88 VST_ARCHIVE_FILL_MODE FillMode;
89 VST_ARCHIVE_CONFIG_STATE

ConfigState;
90
91 /* create the handle */
92 h = VS_Archive_Create();
93 if (h != (VST_ARCHIVE_HANDLE) NULL)
94 {
95 /* get values from user */
96 printf(“*** Archive Handle

***\n”);
97 printf(“Enter Archive Type ==> “);
98 ArchiveType = atoi(gets(input));;
99 printf(“Enter Archive Name ==> “);
100 gets(ArchiveName);
101 printf(“Enter Console Display

Location ==> “);
102 gets(ConsoleLoc);
103 printf(“Enter archive state ==>

“);
104 ComponentState =

atoi(gets(input));
105 printf(“Enter Archive Mode ==> “);
106 ArchiveMode = atoi(gets(input));
107 printf(“Enter Fill Mode ==> “);
108 FillMode = atoi(gets(input));;

2-12 API Functions 6-01004-01 Rev A

API Guide

109 printf(“Enter Config State ==> “);
110 ConfigState = atoi(gets(input));;
111 /* set the fields in the handle */
112 rc = VS_Archive_SetFields(h,
113 VSID_ARCHIVE_NAME,

ArchiveName,

114 VSID_ARCHIVE_TYPE,

ArchiveType,

115

VSID

_ARCHIVE_CONSOLE_LOCATION,Con

soleLoc,

116 VSID_COMP_STATE,

ComponentState,

117 VSID_ARCHIVE_MODE,

ArchiveMode,

118 VSID_ARCHIVE_FILL_MODE,

FillMode,

119 VSID_ARCHIVE_CONFIG_STATE,

ConfigState,
120 VSID_ENDFIELD);
121 if (rc)
122 {
123 vst_print_archive(h);
124 }
125 VS_Archive_Destroy(h);
126 }
127return(rc);
128}

Functions

Notes

Note

After VS_Archive_Destroy has been called for an archive
handle, that handle is no longer valid and should not be used.

6-01004-01 Rev A API Functions 2-13

API Guide

See Also

• vsapi(l),

• VS_Archive_Create(l),

• VS_Archive_GetFields(l),

• VS_Archive_SetFields(l),

• VS_Error_GetFields(l)

2-14 API Functions 6-01004-01 Rev A

API Guide

VS_Archive_ GetFields

Synopsis

VS_Archive_GetFields retrieves information associated
with an archive handle. An archive handle is used to pass
archive information to and from VolServ.

VST_BOOLEAN VS_Archive_GetFields
(VST_ARCHIVE_HANDLE handle,
“…”,
VSID_ENDFIELD )

Arguments • handle = Archive handle where information is retrieved.

• “…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by a pointer to a location where the
value of the parameter may be stored. The parameter
identifiers and types this function accepts are shown in the
following "Parameters" paragraph.

• VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.

Functions

Parameters

Parameter Type Description

VSID_ARCHIVE_CONFIG_STATE
(VST_ARCHIVE_CONFIG_STATE*)

VSID_ARCHIVE_CONSOLE_LOCATION
(VST_HOSTNAME)

6-01004-01 Rev A API Functions 2-15

Pointer to a boole an flag that indicates
whether the archive is currently being
configured or reconfigured.

Valid VSID_ARCHIVE_CONFG_STATE values
are enumerated in the vs_types.h file.

Pointer to the location of the archive’ s console
display.

API Guide

Parameter Type Description

VSID_ARCHIVE_FILL_MODE
(VST_ARCHIVE_FILL_MODE*)

Pointer to th e method of allocatin g bins to ne w
media as they are entered into an archive.
VSID_ARCHIVE_FILL_MODE is applicable
only to the DataShelf and DataLibrary
archives. Valid VSID_ARCHIVE_FILL_MODE
values are enumerated in the vs_types.h file.

VSID_ARCHIVE_MODE
(VST_ARCHIVE_MODE *)

Pointer that specifies whether this archive is
attended by an operator to handle media
movement commands that require human
intervention. Valid VSID_ARCHIVE_MODE
values are enumerated in the vs_types.h file.

VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)

Pointer to the name of this archive. Valid
archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.

VSID_ARCHIVE_TYPE
(VST_ARCHIVE_TYPE *)

Pointer to the type of this archive. Valid
VSID_ARCHIVE_TYPE values are
enumerated in the vs_types.h file.

VSID_ARCHIVEMEDIACLASS_HANDLE (int) Index of the archive media class handle in the

MediaClass capacity table.

(VST_ARCHIVEMEDIACLASS_HANDLE *) Pointer to the first archive media class handle

in the MediaClass capacity table.

VSID_ARCHIVEMEDIACLASS_HANDLE_EN
TRY
(int,VST_ARCHIVEMEDIACLASS_HANDLE)

Index of the archiv e med ia class handle in the
MediaClass capacity table.

Pointer to the location to store the archive
media class handle.

VSID_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE *)

Pointer to the MediaClass capacity (in table
format) for this archive.

VSID_COMP_STATE (VST_COMP_STATE *) Pointer to the operational state of this archive.

Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.

VSID_DRIVE_ID (int) Index of the drive in the drive identifier table.

2-16 API Functions 6-01004-01 Rev A

API Guide

Parameter Type Description

(VST_DRIVE_ID *) Pointer to the first drive id in the driv e identifier

table.

VSID_DRIVE_ID_ENTRY
(int, VST_Drive_ID *)

Index of the drive in the drive identifier table.
Pointer to the location to store the drive

identifier

VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)

Pointer to the drives (in table format)
associated with this archive.

VSID_MEDIA_ID (int) Index of the medium in the media identifier

table.

(VST_MEDIA_ID ) Pointer to the first media id in the media

identifier table.

VSID_MEDIA_ID_ENTRY (int, VST_
MEDIA_ID)

Index of the medium in the media identifier
table.

Pointer to the location to store the media
identifier.

VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)

VSID_NUMBER_ARCHIVEMEDIACLASS_H
ANDLES (int *)

Pointer to the media identifiers (in table
format) that are currently in this archive.

Pointer to the number of archive media class
handles present in the archive media class
handle table.

VSID_NUMBER_DRIVE_ID (int *) Pointer to the number of drive ids present in

the drive id table.

Functions

VSID_NUMBER_MEDIA_IDS (int *) Pointer to the number of media ids present in

the media id table.

VSID_NUMBER_TYPECAPACITY_HANDLE
S (int *)

Pointer to the n umber of type capacity handles

present in the type capacity handle table.
VSID_TYPECAPACITY_HANDLE (int) Index of the type capacity handle in the table.
(VST_TYPECAPACITY_HANDLE *) Pointer to the first archive type capacity

handle in the MediaType capacity table.

6-01004-01 Rev A API Functions 2-17

API Guide

Parameter Type Description

VSID_TYPECAPACITY_HANDLE_ENTRY
(int, VSID_TYPECAPACITY_HANDLE *)

VSID_TYPECAPACITY_HANDLE_TABLE
(VST_TABLE_HANDLE *)

Return Values

VS_Archive_GetFields returns:

• VSE_TRUE - Successful execution.

• VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.

• VSE_ERR_BADFIELD - An invalid parameter was
specified.

• VSE_ERR_BADHANDLE - Specified handle was not an
archive handle.

• VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.

Index of the type capacity handle in the
MediaType capacity table.

Pointer to the location to store the type
capacity handle.

Pointer to the type capacity (in table format)
for this archive.

• VSE_ERR_OUTOFRANGE - An index value was out of
range.

2-18 API Functions 6-01004-01 Rev A

API Guide

Example 129/**************************************

***********
130*
131* FUNCTION: vst_print_archive
132*
133* PURPOSE:
134* This function prints out the

information stored in
135* an archive handle.
136*
137* PARAMETERS:
138* h : the archive handle to print
139*
140***************************************

**********/
141#ifdef ANSI_C
142 void

vst_print_archive(VST_ARCHIVE_HAN

DLE h)
143#else
144 void vst_print_archive(h)
145 VST_ARCHIVE_HANDLE h;
146#endif
147{
148 VST_ARCHIVE_TYPE

ArchiveType;
149 VST_ARCHIVE_NAME

ArchiveName;
150 VST_HOSTNAME

ConsoleLoc;
151 VST_COMP_STATE

ComponentState;
152 VST_ARCHIVE_MODE

ArchiveMode;
153 VST_ARCHIVE_FILL_MODE FillMode;
154 VST_ARCHIVE_CONFIG_STATE

ConfigState;
155 VST_TABLE_HANDLE

DriveIDTable;
156 VST_TABLE_HANDLE

MediaIDTable;

Functions

6-01004-01 Rev A API Functions 2-19

API Guide

157 VST_TABLE_HANDLE

ClassCapacityTable;

158 VST_TABLE_HANDLE

TypeCapacityHandleTable;
159 int n;
160 int i;
161 VST_DRIVE_ID *

DriveID;
162 char *

MediaID;
163 VST_ARCHIVEMEDIACLASS_HANDLE

arcmc_handle;
164 VST_TYPECAPACITY_HANDLE

typecap_handle;
165
166 VS_Archive_GetFields(h,
167 VSID_ARCHIVE_NAME,

ArchiveName,
168 VSID_ARCHIVE_TYPE,

&ArchiveType,
169

VSID_ARCHIVE_CONSOLE_LOCATION,

ConsoleLoc,
170 VSID_COMP_STATE,

&ComponentState,
171 VSID_ARCHIVE_MODE,

&ArchiveMode,
172 VSID_ARCHIVE_FILL_MODE,

&FillMode,
173 VSID_ARCHIVE_CONFIG_STATE,

&ConfigState,
174 VSID_DRIVE_ID_TABLE,

&DriveIDTable,
175 VSID_MEDIA_ID_TABLE,

&MediaIDTable,
176

VSID_ARCHIVEMEDIACLASS_HANDLE_TAB

LE, &ClassCapacityTable,
177 VSID_TYPECAPACITY_HANDLE_TABLE,

&TypeCapacityHandleTable,
178 VSID_ENDFIELD);
179

2-20 API Functions 6-01004-01 Rev A

API Guide

180 printf(“*** Archive Handle

Information ***\n”);

181 printf(“Archive Type = %d\n”,

ArchiveType);

182 printf(“Archive Name = %s\n”,

ArchiveName);

183 printf(“Console

Display Location =

%s\n”, ConsoleLoc);

184 printf(“Component State = %d\n”,

ComponentState);

185 printf(“Archive Mode = %d\n”,

ArchiveMode);

186 printf(“Archive Fill Mode = %d\n”,

FillMode);

187 printf(“Config State = %d\n”,

ConfigState);
188
189 if (DriveIDTable !=

Functions

(VST_TABLE_HANDLE) NULL)
190 {
191 /* Get # of entries */
192 VS_Table_GetFields(DriveIDTable,
193

VSID_NUMBER_ENTRIES, &n,
194 VSID_ENDFIELD);
195 for ( i = 0; i < n; i++)
196 {
197

VS_Table_GetFields(DriveIDTable,
198 VSID_TABLE_ENTRY,

i, &DriveID,
199 VSID_ENDFIELD);
200 printf(“DriveID Entry #%d =

%d\n”,i,*DriveID);
201 }
202 }
203
204 if (MediaIDTable !=

(VST_TABLE_HANDLE) NULL)
205 {
206 /* Get # of entries */
207 VS_Table_GetFields(MediaIDTable,

6-01004-01 Rev A API Functions 2-21

API Guide

208

VSID_NUMBER_ENTRIES, &n,
209 VSID_ENDFIELD);
210 for ( i = 0; i < n; i++)
211 {
212

VS_Table_GetFields(MediaIDTable,
213 VSID_TABLE_ENTRY,

i, &MediaID,
214 VSID_ENDFIELD);
215 printf(“Media ID Entry #%d =

%s\n”,i,MediaID);
216 }
217 }
218
219 if (ClassCapacityTable !=

(VST_TABLE_HANDLE) NULL)
220 {
221 /* Get # of entries */
222

VS_Table_GetFields(ClassCapacityT

able,
223

VSID_NUMBER_ENTRIES, &n,
224 VSID_ENDFIELD);
225 for ( i = 0; i < n; i++)
226 {
227

VS_Table_GetFields(ClassCapacityT

able,
228 VSID_TABLE_ENTRY, i,

&arcmc_handle,
229 VSID_ENDFIELD);
230

vst_print_archivemediaclass(arcmc

_handle);
231 }
232 }
233
234 if (TypeCapacityHandleTable !=

(VST_TABLE_HANDLE) NULL)
235 {

2-22 API Functions 6-01004-01 Rev A

API Guide

236 /* Get # of entries */
237

VS_Table_GetFields(TypeCapacityHa
ndleTable,

238

VSID_NUMBER_ENTRIES, &n,
239 VSID_ENDFIELD);
240 for ( i = 0; i < n; i++)
241 {
242

VS_Table_GetFields(TypeCapacityHa

ndleTable,
243 VSID_TABLE_ENTRY, i,

&typecap_handle,
244 VSID_ENDFIELD);
245

vst_print_typecapacity(typecap_ha

ndle);
246 }
247 }
248}

Functions

Notes

Note

If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.

VolServ assigns additional bins according to one of two
user-specified algorithms: “wrap” or “first fill.” Using the wrap
algorithm, VolServ assigns additional bins in order until the last
bin in the archive has been assigned. VolServ then wraps to the
first physical bin, goes through the bins in order, and assigns
empty bins as they are encountered. Using the first fill
algorithm, VolServ starts looking for an av ailable bin at the f irst
physical bin location. The first empty, on-line bin encountered
is assigned.

6-01004-01 Rev A API Functions 2-23

API Guide

The VST_ARCHIVEMEDIACLASS_HANDLE, VST_DRIVE_ID,

VST_MEDIA_ID, and VST_TYPECAPACITY_HANDLE

parameters require that two arguments be passed instead of one.

• The first argument passed is the entry number in the
appropriate table.

• The second argument is Pointer to the location where the
value is stored.

See Also

• vsapi(l),

• VS_Archive_Create(l),

• VS_Archive_Destroy(l),

• VS_Archive_SetFields(l),

• VS_ArchiveMediaClass_GetFields(l),

• VS_ArchiveMediaClass_SetFields(l),

• VS_Error_GetFields(l),

• VS_Table_GetFields(l),

• VS_TypeCapacity_GetFields(l),

• VS_TypeCapacity_SetFields(l),

• VSCMD_Archive_Query(l

2-24 API Functions 6-01004-01 Rev A

API Guide

VS_Archive_S etFields

Synopsis

VS_Archive_SetFields sets the value of one or more
field in an archive handle. An archive handle is used to pass
archive information to and from VolServ.

VST_BOOLEAN VS_Archive_SetFields
(VST_ARCHIVE_HANDLE
handle,
“…”,
VSID_ENDFIELD )

Arguments • handle = Archive handle where information is stored.

• “…” = Variable length argument list consisting of pairs of

arguments. Each pair of arguments consists of a parameter
identifier, followed by the value of the field to store. The
parameter identifiers and types this function accepts are
shown in the following "Parameters" paragraph.

• VSID_ENDFIELD = Required at the end of the variable

length argument list to indicate the end of the list.

Functions

Parameters

Parameter Type Description

VSID_ARCHIVE_CONFIG_STATE
(VST_ARCHIVE_CONFIG_STATE)

VSID_ARCHIVE_CONSOLE_LOCATION
(VST_HOSTNAME)

6-01004-01 Rev A API Functions 2-25

A boolean flag that indicates whether the
archive is currently being configured or
reconfigured. Valid
VSID_ARCHIVE_CONFIG_STATE values are
enumerated in the vs_types.h file.

The location of the archive’s console display.

API Guide

Parameter Type Description

VSID_ARCHIVE_FILL_MODE
(VST_ARCHIVE_FILL_MODE)

VSID_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE)

VSID_ARCHIVE_MODE
(VST_ARCHIVE_MODE)

VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)

VSID_ARCHIVE_TYPE
(VST_ARCHIVE_TYPE)

The method of allocating bins to ne w media as
they are entered into an archive.
VSID_ARCHIVE_FILL_MODE is applicable
only to the DataShelf and DataLibrary
archives.

Valid VSID_ARCHIVE_FILL_MODE values
are enumerated in the vs_types.h file.

The MediaClass capacity (in table format) for
this archive.

Specifies whether this archive is attended by
an operator to handle media movement
commands that require human intervention.
Valid VSID_ARCHIVE_MODE values are
enumerated in the vs_types.h file.

The name of this archive . Valid archive names
may contain up to 16 alph anumeric
characters, including spaces. Leading and
trailing spaces are not permitted.

Type of this archive. Valid
VSID_ARCHIVE_TYPE values are
enumerated in the vs_types.h file.

VSID_COMP_STATE (VST_COMP_STATE) The operational state of this archive. Valid

VSID_COMP_STATE values are enumerated
in the vs_types.h file.

VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE)

VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE)

VSID_TYPECAPACITY_HANDLE_TABLE
(VST_TABLE_HANDLE)

2-26 API Functions 6-01004-01 Rev A

The drive identifiers (in table format)
associated with this archive.

The media identifiers (in table format) that are
currently in this archive.

The type capacity (in table format) for this
archive.

API Guide

Return Values

VS_Archive_SetFields returns:

• VSE_TRUE - Successful execution.

• VSE_FALSE - API failure - An appropriate error code is set

in VSG_Error.

• VSE_ERR_BADHANDLE - Specified handle was not a

criteria handle.

• VSE_ERR_BADSIZE - The value passed for a string

parameter exceeds the maximum allowable length for that
parameter.

• VSE_ERR_NULLHANDLE - Specified handle was a null

pointer.

• VSE_ERR_NULLSTRING - A null value was passed to a

string argument.

Example 249/**************************************

***********
250*
251* FUNCTION: vst_archive_handle
252*
253* PURPOSE:
254* This function tests an archive handle.
255*
256* PARAMETERS:
257* none
258*
259***************************************

**********/
260#ifdef ANSI_C
261 VST_BOOLEAN vst_archive_handle(void)
262#else
263 VST_BOOLEAN vst_archive_handle(void)
264#endif
265{
266 VST_BOOLEAN rc =

VSE_FALSE;

Functions

6-01004-01 Rev A API Functions 2-27

API Guide

267 VST_ARCHIVE_HANDLE h;
268 VST_ARCHIVE_TYPE

ArchiveType;

269 VST_ARCHIVE_NAME

ArchiveName;

270 VST_HOSTNAME

ConsoleLoc;

271 VST_COMP_STATE

ComponentState;

272 VST_ARCHIVE_MODE

ArchiveMode;
273 VST_ARCHIVE_FILL_MODE FillMode;
274 VST_ARCHIVE_CONFIG_STATE

ConfigState;
275
276 /* create the handle */
277 h = VS_Archive_Create();
278 if (h != (VST_ARCHIVE_HANDLE) NULL)
279 {
280 /* get values from user */
281 printf(“*** Archive Handle

***\n”);
282 printf(“Enter Archive Type ==> “);
283 ArchiveType = atoi(gets(input));;
284 printf(“Enter Archive Name ==> “);
285 gets(ArchiveName);
286 printf(“Enter Console Display

Location ==> “);
287 gets(ConsoleLoc);
288 printf(“Enter archive state ==>

“);
289 ComponentState =

atoi(gets(input));
290 printf(“Enter Archive Mode ==> “);
291 ArchiveMode = atoi(gets(input));
292 printf(“Enter Fill Mode ==> “);
293 FillMode = atoi(gets(input));;
294 printf(“Enter Config State ==> “);
295 ConfigState = atoi(gets(input));;
296 /* set the fields in the handle */
297 rc = VS_Archive_SetFields(h,

2-28 API Functions 6-01004-01 Rev A

API Guide

298 VSID_ARCHIVE_NAME,

ArchiveName,

299 VSID_ARCHIVE_TYPE,

ArchiveType,

300

VSID_ARCHIVE_CONSOLE_LOCATION,

ConsoleLoc,

301 VSID_COMP_STATE,

ComponentState,

302 VSID_ARCHIVE_MODE,

ArchiveMode,

303 VSID_ARCHIVE_FILL_MODE,

FillMode,

304 VSID_ARCHIVE_CONFIG_STATE,

ConfigState,
305 VSID_ENDFIELD);
306 if (rc)
307 {
308 vst_print_archive(h);
309 }
310 VS_Archive_Destroy(h);
311 }
312return(rc);
313}

Functions

Notes

Note

If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.

6-01004-01 Rev A API Functions 2-29

API Guide

VolServ assigns additional bins according to one of two
user-specified algorithms: “wrap” or “first fill.” Using the wrap
algorithm, VolServ assigns additional bins in order until the last
bin in the archive has been assigned. VolServ then wraps to the
first physical bin, goes through the bins in order, and assigns
empty bins as they are encountered. Using the first fill
algorithm, VolServ starts looking for an av ailable bin at the f irst
physical bin location. The first empty, on-line bin encountered
is assigned.

2-30 API Functions 6-01004-01 Rev A

API Guide

See Also

• vsapi(l),

• VS_Archive_Create(l),

• VS_Archive_Destroy(l),

• VS_Archive_SetFields(l),

• VS_ArchiveMediaClass_GetFields(l),

• VS_ArchiveMediaClass_SetFields(l),

• VS_Error_GetFields(l),

• VS_Global_SetFields(l),

• VS_Table_Create(l),

• VS_Table_Destroy(l),

• VS_Table_GeFields(l),

• VS_Table_SetFields(l),

• VS_TypeCapacity_GetFields(l),

• VS_TypeCapacity_SetFields(l)

Functions

6-01004-01 Rev A API Functions 2-31

API Guide

VS_Archive MediaClass_ Create

Synopsis

VS_ArchiveMediaClass_Create allocates a VolServ
API archive media class handle. An archive media class handle
is used to pass archive media class information to and from
VolServ.

VST_ARCHIVEMEDIACLASS_HANDLE
VS_ArchiveMediaClass_Create
( void )

Arguments None

Return Values

VS_ArchiveMediaClass_Create returns:

• An archive media class handle, if one can be allocated.

• NULL, if an archive media class handle cannot be allocated.
An appropriate error code is set in VSG_Error.

• VSE_ERR_OUTOFMEM - Memory allocation error.

Example 314/**************************************

***********
315*
316* FUNCTION:

vst_archivemediaclass_handle
317*
318* PURPOSE:
319* This function tests an

archivemediaclass handle.
320*
321* PARAMETERS:
322* none
323*
324***************************************

**********/

2-32 API Functions 6-01004-01 Rev A

API Guide

325#ifdef ANSI_C
326 VST_BOOLEAN

vst_archivemediaclass_handle(void

)
327#else
328 VST_BOOLEAN

vst_archivemediaclass_handle()
329#endif
330{
331 VST_BOOLEAN rc;
332 VST_ARCHIVEMEDIACLASS_HANDLE h;
333 VST_ARCHIVE_NAME

Archive;
334 VST_MEDIA_CLASS_NAME

MediaClass;
335 VST_MEDIA_TYPE_NAME

MediaType;
336 VST_CAPACITY

Capacity;
337 VST_PERCENT

MediaClassPercent;
338 VST_ARCHIVE_ACTION_OPTION

ActionMode;
339 VST_HIGH_MARK

HighMark;
340 VST_LOW_MARK

LowMark;
341 VST_FILL_LEVEL

FillLevel;
342 VST_PRIORITY

MigrationPriority;
343 VST_ARCHIVE_NAME

TargetArchive;
344
345 /* create the handle */
346 h = VS_ArchiveMediaClass_Create();
347 if (h !=

(VST_ARCHIVEMEDIACLASS_HANDLE)

NULL)
348 {
349 /* get the values from the user */

Functions

6-01004-01 Rev A API Functions 2-33

API Guide

350 printf(“** Archive Media Class

handle **\n”);
351 printf(“Enter Archive Name ==> “);
352 gets(Archive);
353 printf(“Enter Media Class Name ==>

“);
354 gets(MediaClass);
355 printf(“Enter Media Type Name ==>

“);
356 gets(MediaType);
357 printf(“Enter Capacity ==> “);
358 Capacity = atoi(gets(input));
359 printf(“Enter MediaClass Percent

==> “);
360 MediaClassPercent =

atoi(gets(input));
361 printf(“Enter Archive Action Mode

==> “);
362 ActionMode = atoi(gets(input));
363 printf(“Enter High Mark Mode ==>

“);
364 HighMark = atoi(gets(input));
365 printf(“Enter Fill Level Mode ==>

“);
366 FillLevel = atoi(gets(input));
367 printf(“Enter Migration Priority

==> “);
368 MigrationPriority =

atoi(gets(input));
369 printf(“Enter Target Archive ==>

“);
370 gets(TargetArchive);
371 rc =

VS_ArchiveMediaClass_SetFields(h,
372 VSID_ARCHIVE_NAME,

Archive,
373 VSID_MEDIA_CLASS_NAME,

MediaClass,
374 VSID_MEDIA_TYPE_NAME,

MediaType,
375 VSID_CAPACITY,

Capacity,

2-34 API Functions 6-01004-01 Rev A

API Guide

376 VSID_PERCENT,

MediaClassPercent,

377 VSID_ARCHIVE_ACTION,

ActionMode,

378 VSID_HIGH_MARK,

HighMark,

379 VSID_LOW_MARK,

LowMark,

380 VSID_FILL_LEVEL,

FillLevel,

381

VSID_MIGRATION_PRIORITY,Migration
Priority,

382

VSID

_TARGET_ARCHIVE_NAME,TargetAr

chive,
383 VSID_ENDFIELD);
384 if (rc)
385 {
386

vst_print_archivemediaclass(h);
387 }
388 VS_ArchiveMediaClass_Destroy(h);
389 }
390 return(rc);
391}

Functions

Notes

See Also

None

• vsapi(l),

• VS_ArchiveMediaClass_Destroy(l)

• VS_ArchiveMediaClass_GetFields(l),

• VS_ArchiveMediaClass_SetFields(l),

• VS_Error_GetFields(l)

6-01004-01 Rev A API Functions 2-35

API Guide

VS_Archive
MediaClass_

VS_ArchiveMediaClass_Destroy deallocates an
archive media class handle that was allocated with
VS_ArchiveMediaClass_Create.

Destroy

Synopsis

Arguments • handle = Archive media class handle to be destroyed.

Return Values

VST_BOOLEAN VS_ArchiveMediaClass_Destroy
(VST_ARCHIVEMEDIACLASS
_HANDLE
handle)

VS_ArchiveMediaClass_Destroy returns:

• VSE_TRUE - Successful execution.

• VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.

• VSE_ERR_BADHANDLE - Specified handle was not an
archive media class handle.

• VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.

Example 1 /****************************************

*********
2*
3 * FUNCTION:

vst_archivemediaclass_handle
4*
5 * PURPOSE:
6 * This function tests an

archivemediaclass handle.
7*

2-36 API Functions 6-01004-01 Rev A

API Guide

8 * PARAMETERS:
9 * none
10 *
11 ****************************************

*********/
12 #ifdef ANSI_C
13 VST_BOOLEAN

vst_archivemediaclass_handle(void

)
14 #else
15 VST_BOOLEAN

vst_archivemediaclass_handle()
16 #endif
17 {
18 VST_BOOLEAN rc;
19 VST_ARCHIVEMEDIACLASS_HANDLE h;
20 VST_ARCHIVE_NAME

Archive;
21 VST_MEDIA_CLASS_NAME

MediaClass;
22 VST_MEDIA_TYPE_NAME

MediaType;
23 VST_CAPACITY

Capacity;
24 VST_PERCENT

MediaClassPercent;
25 VST_ARCHIVE_ACTION_OPTION

ActionMode;
26 VST_HIGH_MARK

HighMark;
27 VST_LOW_MARK

LowMark;
28 VST_FILL_LEVEL

FillLevel;
29 VST_PRIORITY

MigrationPriority;
30 VST_ARCHIVE_NAME

TargetArchive;
31
32 /* create the handle */
33 h = VS_ArchiveMediaClass_Create();

Functions

6-01004-01 Rev A API Functions 2-37

API Guide

34 if (h !=

(VST_ARCHIVEMEDIACLASS_HANDLE)

NULL)
35 {
36 /* get the values from the user */
37 printf(“** Archive Media Class

handle **\n”);
38 printf(“Enter Archive Name ==> “);
39 gets(Archive);
40 printf(“Enter Media Class Name ==>

“);
41 gets(MediaClass);
42 printf(“Enter Media Type Name ==>

“);
43 gets(MediaType);
44 printf(“Enter Capacity ==> “);
45 Capacity = atoi(gets(input));
46 printf(“Enter MediaClass Percent

==> “);
47 MediaClassPercent =

atoi(gets(input));
48 printf(“Enter Archive Action Mode

==> “);
49 ActionMode = atoi(gets(input));
50 printf(“Enter High Mark Mode ==>

“);
51 HighMark = atoi(gets(input));
52 printf(“Enter Fill Level Mode ==>

“);
53 FillLevel = atoi(gets(input));
54 printf(“Enter Migration Priority

==> “);
55 MigrationPriority =

atoi(gets(input));
56 printf(“Enter Target Archive ==>

“);
57 gets(TargetArchive);
58 rc =

VS_ArchiveMediaClass_SetFields(h,
59 VSID_ARCHIVE_NAME,

Archive,

2-38 API Functions 6-01004-01 Rev A

API Guide

60 VSID_MEDIA_CLASS_NAME,

MediaClass,

61 VSID_MEDIA_TYPE_NAME,

MediaType,

62 VSID_CAPACITY,

Capacity,

63 VSID_PERCENT,

MediaClassPercent,

64 VSID_ARCHIVE_ACTION,

ActionMode,

65 VSID_HIGH_MARK,

HighMark,

66 VSID_LOW_MARK,

LowMark,

67 VSID_FILL_LEVEL,

FillLevel,

68 VSID

_MIGRATION_PRIORITY,

MigrationPriority,

69 VSID_TARGET_ARCHIVE_NAME,

TargetArchive,
70 VSID_ENDFIELD);
71 if (rc)
72 {
73

vst_print_archivemediaclass(h);
74 }
75 VS_ArchiveMediaClass_Destroy(h);
76 }
77 return(rc);
78 }

Functions

Notes

Note

After VS_ArchiveMediaClass_Destroy has been called for an
archive media class handle, that ha ndle is no longer valid and
should not be used.

6-01004-01 Rev A API Functions 2-39

API Guide

See Also

• vsapi(l),

• VS_ArchiveMediaClass_Create(l),

• VS_ArchiveMediaClass_GetFields(l),

• VS_ArchiveMediaClass_SetFields(l),

• VS_Error_GetFields(l)

2-40 API Functions 6-01004-01 Rev A

API Guide

VS_Archive MediaClass_ GetFields

Synopsis

VS_ArchiveMediaClass_GetFields retrieves
information associated with an archive media class handle. An
archive media class handle is used to pass archive media class
information to and from VolServ.

VST_BOOLEAN VS_ArchiveMediaClass_GetFields
( VST_ARCHIVEMEDIACLASS
_HANDLE handle,
“…”,
VSID_ENDFIELD )

Arguments • handle =Archive media class handle where information is

retrieved.

• “…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by a pointer to a location where the
value of the parameter may be stored. The parameter
identifiers and types this function accepts are shown in the
following "Parameters" paragraph.

Functions

• VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.

Parameters

Parameter Type Description

VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION*)

6-01004-01 Rev A API Functions 2-41

Pointer to th e archiv e a ction VolServ is to take
when the number of media in the archive
media class exceeds the specified high mark
threshold. Valid VSID_ARCHIVE_ACTION
values are enumerated in the vs_types.h file.

API Guide

Parameter Type Description

VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)

Pointer to the name of the archive associated
with the archive media class relationship. Valid
archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.

VSID_CAPACITY (VST_CAPACITY *) Pointer to the percentage of the total

MediaClass capacity that can be stored in this
archive.

VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE *)

Pointer to the preferred locations for media
assigned to this archive media class.

VSID_FILL_LEVEL (VST_FILL_LEVEL *) Pointer to the number of media currently in

this archive media class.

VSID_HIGH_MARK (VST_HIGH_MARK *) The percentage of VSID_CAPACITY above

which the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTION is set to

VSE_ARCHIVE_ACTION_NOTIFY or
VSE_ARCHIVE_ACTION_MIG.

VSID_LOW_MARK (VST_LOW_MARK *) Pointer to the p ercentage of the archiv e medi a

class capacity below which automatic
migration of media out of the archive media
class stops. This field is applicable only if

VSID_ARCHIVE_ACTION is set to
VSE_ARCHIVE_ACTION_NOTIFY or
VSE_ARCHIVE_ACTION_MIG.

VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)

Pointer to the MediaClass name associated
with the archive media class relationship.

V alid MediaClass names may con tain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.

2-42 API Functions 6-01004-01 Rev A

Parameter Type Description

API Guide

VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)

VSID_MIGRATION_PRIORITY
(VST_PRIORITY *)

VSID_NUMBER_COMPONENT_HANDLES
(int *)

VSID_PERCENT (VST_PERCENT *) Pointer to the percentage of the media

VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)

Return Values

VS_ArchiveMediaClass_GetFields returns:

Pointer to the media type associated with the
archive media class. Valid media type names
may contain up to 16 alph anumeric
characters, including spaces. Leading and
trailing spaces are not permitted.

Pointer to the migration priority to be applied
to this archive media class.

Pointer to the number of component handles
present in the component handle table.

assigned to the related MediaClass group
allowed in the archive associated with the
archive media class relationship.

Pointer to the destination archive for media
automatically migrated out of this archive
media class. Valid archive names may co ntain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.

Functions

• VSE_TRUE - Successful execution.

• VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.

• VSE_ERR_BADFIELD - An invalid parameter was
specified.

• VSE_ERR_BADHANDLE - Specified handle was not an
archive media class handle.

• VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.

6-01004-01 Rev A API Functions 2-43

API Guide

Example 1 /****************************************

*********
2*
3 * FUNCTION: vst_print_archivemediaclass
4*
5 * PURPOSE:
6 * This function prints out the

information stored in
7 * an Archive Media Class handle.
8*
9 * PARAMETERS:
10 * h : the Archive Media Class handle to

print
11 *
12 ****************************************

*********/
13 #ifdef ANSI_C
14 void

vst_print_archivemediaclass

(VST_ARCHIVEMEDIACLASS_HANDLE h)
15 #else
16 void vst_print_archivemediaclass(h)
17 VST_ARCHIVEMEDIACLASS_HANDLE h;
18 #endif
19 {
20 VST_ARCHIVE_NAME Archive;
21 VST_MEDIA_CLASS_NAME

MediaClass;
22 VST_MEDIA_TYPE_NAME

MediaType;
23 VST_CAPACITY Capacity;
24 VST_PERCENT

MediaClassPercent;
25 VST_ARCHIVE_ACTION_OPTION

ActionMode;
26 VST_HIGH_MARK HighMark;
27 VST_LOW_MARK LowMark;
28 VST_FILL_LEVEL

FillLevel;
29 VST_PRIORITY

MigrationPriority;

2-44 API Functions 6-01004-01 Rev A