Acer 9920G Series Laptop User Manual

API Guide
VolServ Version 5.0
September 2001
601355 Rev A
Trademark Notice
AMASS, DataMgr, EMASS, FileServ, and VolServ are either trademarks or registered
trademarks of ADIC, Advanced Digital Information Corporation. DAS is a trademark of
Grau, an ADIC subsidiary. All other product names and identifications are trademarks or
registered trademarks of their respective manufacturers.
Copyright Notice
© 1996-2001 ADIC®. All rights reserved. This document is the property of ADIC. No part
of this document may be reproduced, transmitted, transcribed, stored in a retrieval system,
or translated into any language or computer language in any form or by any means,
electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the
express written permission of:
ADIC
10949 East Peakview Ave.
Englewood, CO 80111 USA
Phone: 303-792-9700
FAX: 303-792-2465
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.2277013 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: support@adic.com.
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: techdocs@adic.com
READER COMMENT FORM
ADIC includes this Form in an effort to provide the best possible documentation to our
customers. Please take a few moments to mail or FAX your response to:
ADIC
Software Documentation
10949 East Peakview Ave.
Englewood, CO 80111
FAX: 303-792-2465
E-mail: techdocs@adic.com
Question
Circle One
Information was complete.
Agree
Disagree
Information was easy to find.
Agree
Disagree
Information was easy to follow.
Agree
Disagree
Is there anything you especially like or dislike about the organization, presentation,
or writing in this manual?_______________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
Book Title
Document Number
Customer Name
Telephone
E-mail Address
Company Name
Address
City, State, Zip
NOTES
Contents
Preface
Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Who Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How This Book is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Started
P-3
P-3
P-3
P-4
P-5
1
API Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5
Client Interface Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Unsolicited Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
VolServ API Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
API Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-15
Dispatch Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-19
Global Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-20
API Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-22
Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-24
Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-28
API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-30
601355 Rev A
i
API Guide
API Functions
2
VS_Archive_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
VS_Archive_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
VS_Archive_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
VS_ArchiveMediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
VS_ArchiveMediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36
VS_ArchiveMediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41
VS_ArchiveMediaClass_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-49
VS_Command_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-58
VS_Command_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-61
VS_Command_GetErrorFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-65
VS_Command_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-68
VS_Command_GetStatusFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-72
VS_Command_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-82
VS_Component_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-87
VS_Component_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-93
VS_Component_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-96
VS_Component_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-100
VS_Connect_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-107
VS_Connect_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-110
VS_Connect_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-114
VS_Connect_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-118
VS_Criteria_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-123
VS_Criteria_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-129
VS_Criteria_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-136
VS_Criteria_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-142
ii
Contents
601355 Rev A
API Guide
VS_CriteriaGroup_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-149
VS_CriteriaGroup_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-155
VS_CriteriaGroup_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-161
VS_CriteriaGroup_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-166
VS_Drive_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-173
VS_Drive_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-177
VS_Drive_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-181
VS_Drive_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-187
VS_DrivePool_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-193
VS_DrivePool_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-196
VS_DrivePool_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-199
VS_DrivePool_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-204
VS_Error_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-208
VS_Expression_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-212
VS_Expression_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-218
VS_Expression_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-225
VS_Expression_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-231
VS_Global_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-238
VS_Global_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-243
VS_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-249
VS_Media_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-253
VS_Media_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-257
VS_Media_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-261
VS_Media_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-267
VS_MediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-273
VS_MediaClass_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-278
VS_MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-283
VS_MediaClass_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-291
601355 Rev A
Contents
iii
API Guide
VS_MediaType_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-299
VS_MediaType_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-302
VS_MediaType_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-305
VS_MediaType_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-309
VS_Mount_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-313
VS_Mount_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-318
VS_MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-322
VS_Mount_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-330
VS_Notify_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-338
VS_Notify_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-343
VS_Notify_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-348
VS_Notify_Listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-356
VS_Notify_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-362
VS_Request_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-369
VS_Request_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-372
VS_Request_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-375
VS_Request_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-379
VS_Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-383
VS_Status_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-386
VS_Table_AddEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-400
VS_Table_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-407
VS_Table_CreateAdd-Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-414
VS_Table_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-418
VS_Table_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-422
VS_Table_RemoveEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-426
VS_Table_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-430
VS_Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-435
VS_TypeCapacity_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-437
iv
Contents
601355 Rev A
API Guide
VS_TypeCapacity_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-441
VS_TypeCapacity_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-446
VS_TypeCapacity_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-453
VSCMD_ArchiveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-460
VSCMD_ArchiveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-470
VSCMD_ArchiveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-476
VSCMD_ArchiveVary_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-484
VSCMD_Audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-490
VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-499
VSCMD_Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-505
VSCMD_Cancel_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-514
VSCMD_Checkin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-520
VSCMD_Checkin_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-529
VSCMD_Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-534
VSCMD_Checkout_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-543
VSCMD_ClearEject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-548
VSCMD_ClearEject_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-557
VSCMD_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-563
VSCMD_Connect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-575
VSCMD_Connect-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-581
VSCMD_Connect-Query_Set-Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-590
VSCMD_CreateArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-595
VSCMD_CreateArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . .2-609
VSCMD_CreateMedia-Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-619
VSCMD_CreateMedia-Class_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-632
VSCMD_DriveVary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-641
VSCMD_DriveVary_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-652
VSCMD_Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-660
601355 Rev A
Contents
v
API Guide
VSCMD_Export_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-669
VSCMD_Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-674
VSCMD_Import_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-684
VSCMD_Intransit-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-689
VSCMD_Intransit-Query_Set-Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-697
VSCMD_Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-702
VSCMD_Lock_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-712
VSCMD_MediaClass-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-717
VSCMD_MediaClass-Query_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-726
VSCMD_MediaQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-731
VSCMD_MediaQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-739
VSCMD_MediaType-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-744
VSCMD_MediaType-Query_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-753
VSCMD_ModifyMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-759
VSCMD_ModifyMedia_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-769
VSCMD_CreatePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-776
VSCMD_CreatePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-785
VSCMD_DeleteArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-791
VSCMD_DeleteArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . .2-800
VSCMD_DeleteMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-806
VSCMD_DeleteMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-814
VSCMD_DeletePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-819
VSCMD_DeletePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-827
VSCMD_Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-832
VSCMD_Disconnect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-842
VSCMD_Dismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-848
VSCMD_Dismount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-857
VSCMD_DrivePoolQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-863
vi
Contents
601355 Rev A
API Guide
VSCMD_DrivePoolQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-872
VSCMD_DriveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-878
VSCMD_DriveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-887
VSCMD_ModifyArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-893
VSCMD_ModifyArchiveMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . .2-908
VSCMD_ModifyMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-914
VSCMD_ModifyMediaClass_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-927
VSCMD_ModifyPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-935
VSCMD_ModifyPool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-945
VSCMD_Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-951
VSCMD_Mount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-967
VSCMD_Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-975
VSCMD_Move_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-986
VSCMD_MultiMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-992
VSCMD_MultiMount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1003
VSCMD_Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1009
VSCMD_QueryMount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1013
VSCMD_QueryMount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1022
VSCMD_Reclassify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1027
VSCMD_Reclassify_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1039
VSCMD_Reprioritize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1045
VSCMD_Reprioritize_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1054
VSCMD_Request-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1060
VSCMD_RequestQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1068
VSCMD_Unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1073
VSCMD_Unlock_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1081
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
601355 Rev A
Contents
vii
API Guide
viii
Contents
601355 Rev A
Preface
Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . .P-3
Who Should Read This Book. . . . . . . . . . . . . . . . .P-3
How This Book is Organized . . . . . . . . . . . . . . . .P-3
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-4
Books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-5
Online Books . . . . . . . . . . . . . . . . . . . . . . . . . . .P-5
Related Publications . . . . . . . . . . . . . . . . . . . . .P-6
Contact Publications Department. . . . . . . . . .P-6
Secured Web Site. . . . . . . . . . . . . . . . . . . . . . . .P-6
P
Preface
API Guide
NOTES
P-2
Preface
601355 Rev A
Purpose of
This Book
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.
Who Should
Read This
Book
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
How This
Book is
Organized
This book contains the following chapters:
Chapter 1: Getting Started — Describes API types and
naming conventions, dispatch routines and global
parameters,.and error handling.
Chapter 2: Functions — Alphabetical list of API function
calls.
Appendix A: Valid Status Fields — A matrix shows which
status fields are valid for each command.
Appendix B: Error Codes.
Appendix C: Mount Example.
601355 Rev A
Preface
P-3
Preface
API Guide
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.
Request to add a new volume:
Volume group will be “20”
Volume position will be “A123”.
The root prompt is shown as a number
symbol.
# su root
What you should type in is shown in Courier
bold font.
vsarchiveqry
Site-specific variables are in a Times italics
font.
tar -xvf tapedevicename
A backward slash ( \ ) denotes the input is
continued onto the next line; the printed page
is just not wide enough to accommodate the
line.
# remsh nodename -n dd if=/dev \
/tapedevicename/bs=20b | tar xvfb \
- 20
(You should type the entire command without
the backward slash.)
Pressing <Return> after each command is
assumed.
A menu name with an arrow refers to a
sequence of menus.
P-4
Preface
Config-->MediaType-->Redefine
601355 Rev A
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 overview of VolServ. Contains a
glossary.
Installing VolServ
Describes server requirements, installation
instructions, troubleshooting procedures,
and configuration parameters.
Using the VolServ GUI
Describes how to perform system
administrative tasks using the graphical user
interface.
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 for system log
errors.
Quick Reference Card
Summarizes commands.
API Guide
Provides a list of API functions.
Online Books
601355 Rev A
The documentation CD contains VolServ book files and
Adobe® Acrobat® Reader. The Reader allows you to view and
navigate the online documentation files yet preserves the page
design and graphics from the printed books.
Preface
P-5
Preface
API Guide
API Guide
Related
Publications
The publications described in the table below are created and
distributed on an as-needed basis.
Related Publications
“Release Notes”
Description
For each version of VolServ, the “Release Notes” contain:
• Summary of enhancements.
• Describes:
- Fixed problems.
- Known problems.
- Installation and configuration issues.
• Lists:
- Operating system patches.
- System requirements.
“Product Alerts”
Informs customers of technical problems and solutions.
“Product Bulletins”
Conveys technical information—not problems—to
customers.
Contact
Publications
Department
To make corrections or to comment on VolServ publications,
please contact Software Technical Publications at our e-mail
address: techdocs@adic.com.
Secured Web
Site
To receive access to the secured site on our home page containing technical product information (Release Notes, Product
Alerts, Product Bulletins, FAQs), visit http://partners.adic.com/
and follow the password request procedure. In return, ADIC
will send you instructions and a password.
P-6
Preface
601355 Rev A
1
Getting
Started
Getting Started
API Directory Structure . . . . . . . . . . . . . . . . . . . . . 1-3
Application Program Interface . . . . . . . . . . . . . . . 1-5
Extensible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Consistent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
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
Command Status. . . . . . . . . . . . . . . . . . . . . . . 1-26
Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
Asynchronous . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
Synchronous . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30
API Guide
Roadmap
Topic
Naming conventions.
Refer To
Chapter
1
Global parameters.
Error handling.
1-2
Getting Started
API functions.
2
Valid staus fields.
A
Error codes.
B
Mount example.
C
601355 Rev A
API Guide
API Directory
Structure
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 following figure
and defined in the table below.
/volserv/vsapi
/include
Directory
601355 Rev A
/lib
/man
/util
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.
Getting Started
1-3
Getting Started
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.
API Guide
Directory
util
1-4
Getting Started
Contents
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.
601355 Rev A
API Guide
Application
Program
Interface
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.
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.
Extensible
The VolServ API is extensible. Any change in the VolServ RPC
interface is handled by the API. Thus, the client program does
not have to be updated to maintain compatibility when the
VolServ RPC interface is modified. The client program is
updated only to use new VolServ features.
Consistent
The VolServ API is consistent. All commands and their related
functions have the same interface and operate similarly.
Portable
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.)
Flexible
The VolServ API is flexible. A client program can send a
command to VolServ and either
601355 Rev A
Getting Started
1-5
Getting Started
The VolServ API allows the user to send commands, receive
command statuses, and receive VolServ MediaClass
notifications.
API Guide
•
Wait for final status before continuing processing
(synchronous processing).
•
Or, continue processing after VolServ has received the
command. The client software receives the command’s
status at a later time (asynchronous processing).
A client program can also mix these operation modes.
1-6
Getting Started
601355 Rev A
API Guide
Client
Interface
Summary
The figure below illustrates the communication paths supported
by VolServ:
Command
Line
Interface
Client Software
using API
API
Getting Started
Clients using
Commands in
Client scripts
RPC
RPC
Client Software
using
RPC/XDR protocol
VolServ
RPC
The following outline shows the flow of information through
these communication paths.
•
601355 Rev A
Clients using the Command Line Interface and Client
Scripts.
-
The client-to-client script issues a request from the
command line.
-
The CLI software performs first-level validation 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.
Getting Started
1-7
API Guide
•
•
1-8
Getting Started
-
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.
601355 Rev A
API Guide
Unsolicited
Communication
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.”
•
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, and
VSCMD_Reclassify can generate unsolicited communication
from VolServ. This unsolicited communication is returned to
the client issuing the command only if that client is specified in
the processing parameters as the destination for all unsolicited
communication for the MediaClass group.
601355 Rev A
Getting Started
1-9
Getting Started
Unsolicited communication from VolServ can be directed to
either:
API Guide
VolServ API
Integration
To integrate the VolServ API in a client application, the client
includes the header file vs_client.h in the source modules
that reference the VolServ API types and functions. The client
then links the program with the VolServ API library
libvsapi.a with the -lvsapi option for the cc or ld
commands.
The following five header files are delivered with the VolServ
API:
Header Files
Description
vs_client.h
Includes the VolServ API header files needed
by the client.
vs_defs.h
Includes the VolServ API definitions needed
for the parameter lists.
vs_types.h
Includes the VolServ API types and
enumerations.
vs_globals.h
Includes the VolServ API global variables that
are accessible to the client.
vs_proto.h
Includes the prototypes for all VolServ API
functions.
Before any command can be sent by the client program, the
VolServ API must by initialized with a call to
VS_Initialize. The routine VS_Initialize creates and
initializes the APIs required variables and creates a
communication link with VolServ. Before the client program
terminates, it calls the VS_Terminate routine to allow the
VolServ API to clean up its processing.
For example:
1-10
Getting Started
601355 Rev A
API Guide
#include <stdio.h>
#include <vs_client.h>
main()
{
VST_HOSTNAME vshost;
Getting Started
/* get volserv host name from the user */
printf ( “Enter the name of the VolServ host
computer ==> “ );
scanf ( “%s”, vshost );
/*
/*
/*
if
{
initialize the VolServ API. */
returns TRUE if successful, */
FALSE if fails. */
( VS_Initialize ( vshost, 0, 30 ) )
/* send and create commands */
.............
/* allow VolServ API to */
/* terminate properly */
VS_Terminate();
}
else
{
printf ( “Error initializing VolServ
API” );
}
}
601355 Rev A
Getting Started
1-11
API Guide
API Types
API objects and handles are described below.
Objects
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
1-12
Getting Started
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.
601355 Rev A
API Guide
Each handle has the four base routines descried in the table
below:
Routine
Description
The initializer creates and initializes the data
held by the handle and returns 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 field.
accessor
The accessor function allows the client to
retrieve values from fields within the handle. 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.
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.
601355 Rev A
Getting Started
1-13
Getting Started
initializer
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
601355 Rev A
API Guide
Naming
Conventions
The table below describes the API naming conventions:
Item
Description
Handle names start with the VST prefix, followed by the specific
object name, and end with the HANDLE suffix. The name should be
in all capitals. For example: VST_DRIVE_HANDLE
Types
Types are defined in a client-accessed header file begin with the
VST prefix. For example: VST_DRIVE_ID
Definitions
Definitions that are defined in the client definition header file
should begin with the VSD prefix. For example:
Getting Started
Handles
VSD_DRIVE_NAME_LEN
Enumerations
Enumerations have two conventions to follow. 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
Global Variables
Global variables begin with the VSG prefix. For example:
VSG_ERROR_CODE
Identifiers
601355 Rev A
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: VSID_DRIVE_ID
Getting Started
1-15
API Guide
Item
Functions
Description
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 follow a naming convention, 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 retrieved. The identifier 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
601355 Rev A
API Guide
Item
Description
Getting Started
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 );
}
}
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
The following
is an actual command:
VSCMD_DriveQuery
( VS_COMMAND_HANDLE, …);
601355 Rev A
Getting Started
1-17
API Guide
Item
Parameter Defaults
Description
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., VSCMD_Mount())
itself.
1-18
Getting Started
601355 Rev A
API Guide
Dispatch
Routines
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.
601355 Rev A
Getting Started
1-19
Getting Started
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).
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 request.
VSID_NOTIFY_DISPATCH
Pointer to the dispatch function used for notification
(MediaClass callback) processing.
VSID_PRIORITY
Execution priority assigned to every command request.
(defaults to 15)
Values range from 1 (highest) to 32 (lowest).
VSID_RETRY_LIMIT
Number of times the API software is to retry for command
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
601355 Rev A
API Guide
Global
Variables
The following global variables are available to any software
using the VolServ API.
Global Variable
VSG_Error
Description
Getting Started
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
601355 Rev A
Pointer to the command handle
whose status was just received
from VolServ. The
VSG_Command_Received can
only be used in asynchronous
processing.
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,
VST_ERROR_CODE
VST_ERROR_HANDLE
objcode;
errcode;
errorhandle;
VS_Error_GetFields
(errorhandle,
VSID_ERROR_OBJECT,
&objcode,
VSID_ERROR_NUMBER,
&numcode,
VSID_ERROR_CODE,
errcode
1-22
Getting Started
601355 Rev A
API Guide
VSID_ENDFIELD);
601355 Rev A
Getting Started
Getting Started
printf ( “error code %s\n”, errcode );
printf ( “object code for error: %d\n”,
objcode );
printf ( “numeric code for error: %d\n”,
numcode );
1-23
API Guide
Using the API
Command
Handle
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.
Command Calls
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
601355 Rev A
API Guide
See the following example:
if ( VSCMD_Mount ( cmd_handle,
Getting Started
VSID_MEDIACLASS_NAME,”scratch”
VSID_DRIVEPOOL_NAME,
”stagepool”,
VSID_PRIORITY,1,
VSID_ENDFIELD ) )
{
printf ( “mount successful\n” );
}
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 variable 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 );
601355 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
601355 Rev A
API Guide
Getting Started
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 );
printf ( “Media [%s] mounted on
drive,
[%d]\n”,mediaid, driveid );
}
}
601355 Rev A
Getting Started
1-27
API Guide
Processing
The VolServ API allows for both asynchronous and
synchronous processing of VolServ commands.
Asynchronous
For asynchronous processing, the VolServ API returns control
to the client after initial status is received.
2
3
VSCMD_cmd
VS_Select
4
1
Volume
Server
5
7
Client
6
8
Program
VS_CallBack
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.
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
601355 Rev A
API Guide
Asynchronous processing also gives the client more control
over the processing environment. 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.
For synchronous processing, the VolServ API returns control to
the client only after final status (or time-out) is received.
2
3
VSCMD_cmd
4
1
8
Volume
Server
VS_Select
7
6
5
Client
Program
VS_CallBack
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.
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.
601355 Rev A
Getting Started
1-29
Getting Started
Synchronous
API Guide
API Functions
The API function descriptions in this book are presented as
follows:
Function
1-30
Getting Started
Description
vsapi
Provides a general introduction to VolServ
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.
601355 Rev A
API Guide
NOTES
Getting Started
601355 Rev A
Getting Started
1-31
API Guide
NOTES
1-32
Getting Started
601355 Rev A
2
API
Functions
Functions
VS_Archive_Destroy . . . . . . . . . . . . . . . . . . . . . . 2-11
VS_Archive_GetFields . . . . . . . . . . . . . . . . . . . . . 2-15
VS_Archive_SetFields . . . . . . . . . . . . . . . . . . . . . 2-25
VS_ArchiveMediaClass_Create . . . . . . . . . . . . . 2-32
VS_ArchiveMediaClass_Destroy . . . . . . . . . . . . 2-36
VS_ArchiveMediaClass_GetFields. . . . . . . . . . . 2-41
VS_ArchiveMediaClass_SetFields . . . . . . . . . . . 2-49
VS_Command_Create . . . . . . . . . . . . . . . . . . . . . 2-58
VS_Command_Destroy . . . . . . . . . . . . . . . . . . . . 2-61
VS_Command_GetErrorFields . . . . . . . . . . . . . . 2-65
VS_Command_GetFields. . . . . . . . . . . . . . . . . . . 2-68
VS_Command_GetStatusFields . . . . . . . . . . . . . 2-72
VS_Command_SetFields . . . . . . . . . . . . . . . . . . . 2-82
VS_Component_Create . . . . . . . . . . . . . . . . . . . . 2-87
VS_Component_Destroy . . . . . . . . . . . . . . . . . . . 2-93
VS_Component_GetFields. . . . . . . . . . . . . . . . . . 2-96
VS_Component_SetFields . . . . . . . . . . . . . . . . . 2-100
VS_Connect_Create . . . . . . . . . . . . . . . . . . . . . . 2-107
VS_Connect_Destroy . . . . . . . . . . . . . . . . . . . . . 2-110
VS_Connect_GetFields . . . . . . . . . . . . . . . . . . . . 2-114
VS_Connect_SetFields . . . . . . . . . . . . . . . . . . . . 2-118
VS_Criteria_Create . . . . . . . . . . . . . . . . . . . . . . . 2-123
VS_Criteria_Destroy . . . . . . . . . . . . . . . . . . . . . . 2-129
VS_Criteria_GetFields . . . . . . . . . . . . . . . . . . . . 2-136
VS_Criteria_SetFields . . . . . . . . . . . . . . . . . . . . . 2-142
VS_CriteriaGroup_Create . . . . . . . . . . . . . . . . . 2-149
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
601355 Rev A
API Guide
601355 Rev A
Functions
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
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
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
601355 Rev A
API Guide
601355 Rev A
Functions
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
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
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
601355 Rev A
API Guide
Roadmap
Topic
Refer To
Chapter
Naming conventions.
1
Global parameters.
Error handling.
API functions.
2
Valid staus fields.
A
Error codes.
B
Mount example.
C
Functions
601355 Rev A
API Functions
2-7
API Guide
VS_Archive_
Create
VS_Archive_Create allocates a VolServ API archive
handle. An archive handle is used to pass archive information to
and from VolServ.
Synopsis
VST_ARCHIVE_HANDLE VS_Archive_Create ( void )
Arguments
None
Return Values
VS_Archive_Create returns:
Example
•
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2-8
API Functions
/****************************************
*********
*
* FUNCTION: vst_archive_handle
*
* PURPOSE:
* This function tests an archive handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_archive_handle(void)
#else
VST_BOOLEAN vst_archive_handle(void)
#endif
{
601355 Rev A
API Guide
18
19
20
21
22
23
24
25
26
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
601355 Rev A
rc =
h;
FillMode;
/* create the handle */
h = VS_Archive_Create();
if (h != (VST_ARCHIVE_HANDLE) NULL)
{
/* get values from user */
printf(“*** Archive Handle
***\n”);
printf(“Enter Archive Type ==> “);
ArchiveType = atoi(gets(input));;
printf(“Enter Archive Name ==> “);
gets(ArchiveName);
printf(“Enter Console Display
Location ==> “);
gets(ConsoleLoc);
printf(“Enter archive state ==>
“);
ComponentState =
atoi(gets(input));
printf(“Enter Archive Mode ==> “);
ArchiveMode = atoi(gets(input));
printf(“Enter Fill Mode ==> “);
FillMode = atoi(gets(input));;
printf(“Enter Config State ==> “);
ConfigState = atoi(gets(input));;
/* set the fields in the handle */
API Functions
2-9
Functions
27
28
29
30
31
32
33
VST_BOOLEAN
VSE_FALSE;
VST_ARCHIVE_HANDLE
VST_ARCHIVE_TYPE
ArchiveType;
VST_ARCHIVE_NAME
ArchiveName;
VST_HOSTNAME
ConsoleLoc;
VST_COMP_STATE
ComponentState;
VST_ARCHIVE_MODE
ArchiveMode;
VST_ARCHIVE_FILL_MODE
VST_ARCHIVE_CONFIG_STATE
ConfigState;
API Guide
49
50
51
rc = VS_Archive_SetFields(h,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_ARCHIVE_TYPE,
ArchiveType,
52
53
54
55
56
VSID_ARCHIVE_CONSOLE_LOCATION,Con
soleLoc,
VSID_COMP_STATE,
ComponentState,
VSID_ARCHIVE_MODE,
ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
FillMode,
VSID_ARCHIVE_CONFIG_STATE,
ConfigState,
VSID_ENDFIELD);
if (rc)
{
vst_print_archive(h);
}
VS_Archive_Destroy(h);
57
58
59
60
61
62
63
}
64 return(rc);
65 }
See Also
2-10
API Functions
•
vsapi(l),
•
VS_Archive_Destroy(l),
•
VS_Archive_GetFields(l),
•
VS_Archive_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
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.
Synopsis
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.
Example
601355 Rev A
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
API Functions
2-11
Functions
VS_Archive_
Destroy
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
601355 Rev A
API Guide
109
110
111
112
113
114
printf(“Enter Config State ==> “);
ConfigState = atoi(gets(input));;
/* set the fields in the handle */
rc = VS_Archive_SetFields(h,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_ARCHIVE_TYPE,
ArchiveType,
115
116
117
118
120
121
122
123
124
125
126
}
127return(rc);
128}
Notes
601355 Rev A
After VS_Archive_Destroy has been called for an archive
handle, that handle is no longer valid and should not be used.
API Functions
2-13
Functions
119
VSID_ARCHIVE_CONSOLE_LOCATION,Con
soleLoc,
VSID_COMP_STATE,
ComponentState,
VSID_ARCHIVE_MODE,
ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
FillMode,
VSID_ARCHIVE_CONFIG_STATE,
ConfigState,
VSID_ENDFIELD);
if (rc)
{
vst_print_archive(h);
}
VS_Archive_Destroy(h);
API Guide
See Also
2-14
API Functions
•
vsapi(l),
•
VS_Archive_Create(l),
•
VS_Archive_GetFields(l),
•
VS_Archive_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
VS_Archive_GetFields retrieves information associated
with an archive handle. An archive handle is used to pass
archive information to and from VolServ.
Synopsis
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.
Parameters
Parameter Type
VSID_ARCHIVE_CONFIG_STATE
(VST_ARCHIVE_CONFIG_STATE*)
Description
Pointer to a boolean 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.
VSID_ARCHIVE_CONSOLE_LOCATION
(VST_HOSTNAME)
601355 Rev A
Pointer to the location of the archive’s console
display.
API Functions
2-15
Functions
VS_Archive_
GetFields
API Guide
Parameter Type
Description
VSID_ARCHIVE_FILL_MODE
(VST_ARCHIVE_FILL_MODE*)
Pointer to the method of allocating bins to new
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 archive media class handle in the
MediaClass capacity table.
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.
Pointer to the location to store the archive
media class handle.
Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.
VSID_DRIVE_ID (int)
2-16
API Functions
Index of the drive in the drive identifier table.
601355 Rev A
API Guide
Parameter Type
Description
(VST_DRIVE_ID *)
Pointer to the first drive id in the drive identifier
table.
VSID_DRIVE_ID_ENTRY
(int, VST_Drive_ID *)
Index of the drive in the drive identifier table.
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 drive
identifier
Functions
Pointer to the location to store the media
identifier.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media identifiers (in table
format) that are currently in this archive.
VSID_NUMBER_ARCHIVEMEDIACLASS_H
ANDLES (int *)
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.
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 number 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.
601355 Rev A
API Functions
2-17
API Guide
Parameter Type
VSID_TYPECAPACITY_HANDLE_ENTRY
(int, VSID_TYPECAPACITY_HANDLE *)
Description
Index of the type capacity handle in the
MediaType capacity table.
Pointer to the location to store the type
capacity handle.
VSID_TYPECAPACITY_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Return Values
2-18
API Functions
Pointer to the type capacity (in table format)
for this archive.
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.
•
VSE_ERR_OUTOFRANGE - An index value was out of
range.
601355 Rev A
API Guide
Example
API Functions
2-19
Functions
601355 Rev A
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;
API Guide
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
VST_TABLE_HANDLE
ClassCapacityTable;
VST_TABLE_HANDLE
TypeCapacityHandleTable;
int
int
VST_DRIVE_ID *
DriveID;
char *
MediaID;
VST_ARCHIVEMEDIACLASS_HANDLE
arcmc_handle;
VST_TYPECAPACITY_HANDLE
typecap_handle;
n;
i;
VS_Archive_GetFields(h,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_ARCHIVE_TYPE,
&ArchiveType,
VSID_ARCHIVE_CONSOLE_LOCATION,
ConsoleLoc,
VSID_COMP_STATE,
&ComponentState,
VSID_ARCHIVE_MODE,
&ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
&FillMode,
VSID_ARCHIVE_CONFIG_STATE,
&ConfigState,
VSID_DRIVE_ID_TABLE,
&DriveIDTable,
VSID_MEDIA_ID_TABLE,
&MediaIDTable,
176
177
178
179
2-20
API Functions
VSID_ARCHIVEMEDIACLASS_HANDLE_TAB
LE, &ClassCapacityTable,
VSID_TYPECAPACITY_HANDLE_TABLE,
&TypeCapacityHandleTable,
VSID_ENDFIELD);
601355 Rev A
API Guide
180
181
182
183
184
185
186
187
190
191
192
193
if (DriveIDTable !=
(VST_TABLE_HANDLE) NULL)
{
/* Get # of entries */
VS_Table_GetFields(DriveIDTable,
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
194
195
196
197
VS_Table_GetFields(DriveIDTable,
VSID_TABLE_ENTRY,
i, &DriveID,
VSID_ENDFIELD);
printf(“DriveID Entry #%d =
%d\n”,i,*DriveID);
}
198
199
200
201
202
203
204
205
206
207
601355 Rev A
}
if (MediaIDTable !=
(VST_TABLE_HANDLE) NULL)
{
/* Get # of entries */
VS_Table_GetFields(MediaIDTable,
API Functions
2-21
Functions
188
189
printf(“*** Archive Handle
Information ***\n”);
printf(“Archive Type = %d\n”,
ArchiveType);
printf(“Archive Name = %s\n”,
ArchiveName);
printf(“Console Display Location =
%s\n”, ConsoleLoc);
printf(“Component State = %d\n”,
ComponentState);
printf(“Archive Mode = %d\n”,
ArchiveMode);
printf(“Archive Fill Mode = %d\n”,
FillMode);
printf(“Config State = %d\n”,
ConfigState);
API Guide
208
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
209
210
211
212
VS_Table_GetFields(MediaIDTable,
VSID_TABLE_ENTRY,
i, &MediaID,
VSID_ENDFIELD);
printf(“Media ID Entry #%d =
%s\n”,i,MediaID);
}
213
214
215
216
217
218
219
220
221
222
}
if (ClassCapacityTable !=
(VST_TABLE_HANDLE) NULL)
{
/* Get # of entries */
VS_Table_GetFields(ClassCapacityT
able,
223
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
224
225
226
227
VS_Table_GetFields(ClassCapacityT
able,
VSID_TABLE_ENTRY, i,
&arcmc_handle,
VSID_ENDFIELD);
228
229
230
231
232
233
234
235
2-22
API Functions
vst_print_archivemediaclass(arcmc
_handle);
}
}
if (TypeCapacityHandleTable !=
(VST_TABLE_HANDLE) NULL)
{
601355 Rev A
API Guide
236
237
/* Get # of entries */
VS_Table_GetFields(TypeCapacityHa
ndleTable,
238
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
239
240
241
242
VS_Table_GetFields(TypeCapacityHa
ndleTable,
VSID_TABLE_ENTRY, i,
&typecap_handle,
VSID_ENDFIELD);
243
244
245
}
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 available bin at the first
physical bin location. The first empty, on-line bin encountered
is assigned.
601355 Rev A
API Functions
2-23
Functions
246
247
248}
vst_print_typecapacity(typecap_ha
ndle);
}
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.
See Also
2-24
API Functions
•
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.
•
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
601355 Rev A
API Guide
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.
Synopsis
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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_CONFIG_STATE
(VST_ARCHIVE_CONFIG_STATE)
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.
VSID_ARCHIVE_CONSOLE_LOCATION
(VST_HOSTNAME)
The location of the archive’s console display.
601355 Rev A
API Functions
2-25
Functions
VS_Archive_
SetFields
API Guide
Parameter Type
VSID_ARCHIVE_FILL_MODE
(VST_ARCHIVE_FILL_MODE)
Description
The method of allocating bins to new 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_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE)
The MediaClass capacity (in table format) for
this archive.
VSID_ARCHIVE_MODE
(VST_ARCHIVE_MODE)
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)
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)
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)
The drive identifiers (in table format)
associated with this archive.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE)
The media identifiers (in table format) that are
currently in this archive.
VSID_TYPECAPACITY_HANDLE_TABLE
(VST_TABLE_HANDLE)
The type capacity (in table format) for this
archive.
2-26
API Functions
601355 Rev A
API Guide
Return Values
601355 Rev A
•
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.
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;
API Functions
2-27
Functions
Example
VS_Archive_SetFields returns:
API Guide
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
2-28
API Functions
VST_ARCHIVE_HANDLE
VST_ARCHIVE_TYPE
ArchiveType;
VST_ARCHIVE_NAME
ArchiveName;
VST_HOSTNAME
ConsoleLoc;
VST_COMP_STATE
ComponentState;
VST_ARCHIVE_MODE
ArchiveMode;
VST_ARCHIVE_FILL_MODE
VST_ARCHIVE_CONFIG_STATE
ConfigState;
h;
FillMode;
/* create the handle */
h = VS_Archive_Create();
if (h != (VST_ARCHIVE_HANDLE) NULL)
{
/* get values from user */
printf(“*** Archive Handle
***\n”);
printf(“Enter Archive Type ==> “);
ArchiveType = atoi(gets(input));;
printf(“Enter Archive Name ==> “);
gets(ArchiveName);
printf(“Enter Console Display
Location ==> “);
gets(ConsoleLoc);
printf(“Enter archive state ==>
“);
ComponentState =
atoi(gets(input));
printf(“Enter Archive Mode ==> “);
ArchiveMode = atoi(gets(input));
printf(“Enter Fill Mode ==> “);
FillMode = atoi(gets(input));;
printf(“Enter Config State ==> “);
ConfigState = atoi(gets(input));;
/* set the fields in the handle */
rc = VS_Archive_SetFields(h,
601355 Rev A
API Guide
298
299
300
301
302
303
304
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_ARCHIVE_TYPE,
ArchiveType,
VSID_ARCHIVE_CONSOLE_LOCATION,
ConsoleLoc,
VSID_COMP_STATE,
ComponentState,
VSID_ARCHIVE_MODE,
ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
FillMode,
VSID_ARCHIVE_CONFIG_STATE,
ConfigState,
VSID_ENDFIELD);
if (rc)
{
vst_print_archive(h);
}
VS_Archive_Destroy(h);
Functions
305
306
307
308
309
310
311
}
312return(rc);
313}
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 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 available bin at the first
physical bin location. The first empty, on-line bin encountered
is assigned.
2-30
API Functions
601355 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
601355 Rev A
•
API Functions
2-31
API Guide
VS_Archive
MediaClass_
Create
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.
Synopsis
VST_ARCHIVEMEDIACLASS_HANDLE
VS_ArchiveMediaClass_Create
( void )
Arguments
None
Return Values
VS_ArchiveMediaClass_Create returns:
Example
2-32
•
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.
314/**************************************
***********
315*
316* FUNCTION:
vst_archivemediaclass_handle
317*
318* PURPOSE:
319* This function tests an
archivemediaclass handle.
320*
321* PARAMETERS:
322* none
323*
324***************************************
**********/
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-33
Functions
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 */
API Guide
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
2-34
API Functions
printf(“** Archive Media Class
handle **\n”);
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter MediaClass Percent
==> “);
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
Archive,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
Capacity,
601355 Rev A
API Guide
376
377
378
379
380
VSID_PERCENT,
MediaClassPercent,
VSID_ARCHIVE_ACTION,
ActionMode,
VSID_HIGH_MARK,
HighMark,
VSID_LOW_MARK,
LowMark,
VSID_FILL_LEVEL,
FillLevel,
381
VSID_MIGRATION_PRIORITY,Migration
Priority,
382
387
388
389
390
391}
vst_print_archivemediaclass(h);
}
VS_ArchiveMediaClass_Destroy(h);
}
return(rc);
Notes
None
See Also
•
vsapi(l),
•
VS_ArchiveMediaClass_Destroy(l)
•
VS_ArchiveMediaClass_GetFields(l),
•
VS_ArchiveMediaClass_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-35
Functions
383
384
385
386
VSID_TARGET_ARCHIVE_NAME,TargetAr
chive,
VSID_ENDFIELD);
if (rc)
{
API Guide
VS_Archive
MediaClass_
Destroy
VS_ArchiveMediaClass_Destroy deallocates an
archive media class handle that was allocated with
VS_ArchiveMediaClass_Create.
Synopsis
VST_BOOLEAN VS_ArchiveMediaClass_Destroy
(VST_ARCHIVEMEDIACLASS
_HANDLE
handle)
Arguments
•
Return Values
VS_ArchiveMediaClass_Destroy returns:
Example
handle = Archive media class handle to be destroyed.
•
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.
1
2
3
4
5
6
7
2-36
API Functions
/****************************************
*********
*
* FUNCTION:
vst_archivemediaclass_handle
*
* PURPOSE:
* This function tests an
archivemediaclass handle.
*
601355 Rev A
API Guide
8
9
10
11
12
13
14
15
16
17
18
19
20
22
23
24
25
26
27
28
29
30
31
32
33
601355 Rev A
/* create the handle */
h = VS_ArchiveMediaClass_Create();
API Functions
2-37
Functions
21
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_archivemediaclass_handle(void
)
#else
VST_BOOLEAN
vst_archivemediaclass_handle()
#endif
{
VST_BOOLEAN rc;
VST_ARCHIVEMEDIACLASS_HANDLE h;
VST_ARCHIVE_NAME
Archive;
VST_MEDIA_CLASS_NAME
MediaClass;
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
Capacity;
VST_PERCENT
MediaClassPercent;
VST_ARCHIVE_ACTION_OPTION
ActionMode;
VST_HIGH_MARK
HighMark;
VST_LOW_MARK
LowMark;
VST_FILL_LEVEL
FillLevel;
VST_PRIORITY
MigrationPriority;
VST_ARCHIVE_NAME
TargetArchive;
API Guide
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
2-38
API Functions
if (h !=
(VST_ARCHIVEMEDIACLASS_HANDLE)
NULL)
{
/* get the values from the user */
printf(“** Archive Media Class
handle **\n”);
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter MediaClass Percent
==> “);
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
Archive,
601355 Rev A
API Guide
60
61
62
63
64
65
66
67
68
70
71
72
73
74
75
76
77
78 }
Notes
601355 Rev A
Functions
69
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
Capacity,
VSID_PERCENT,
MediaClassPercent,
VSID_ARCHIVE_ACTION,
ActionMode,
VSID_HIGH_MARK,
HighMark,
VSID_LOW_MARK,
LowMark,
VSID_FILL_LEVEL,
FillLevel,
VSID_MIGRATION_PRIORITY,
MigrationPriority,
VSID_TARGET_ARCHIVE_NAME,
TargetArchive,
VSID_ENDFIELD);
if (rc)
{
vst_print_archivemediaclass(h);
}
VS_ArchiveMediaClass_Destroy(h);
}
return(rc);
After VS_ArchiveMediaClass_Destroy has been called for
an archive media class handle, that handle is no longer valid and
should not be used.
API Functions
2-39
API Guide
See Also
2-40
API Functions
•
vsapi(l),
•
VS_ArchiveMediaClass_Create(l),
•
VS_ArchiveMediaClass_GetFields(l),
•
VS_ArchiveMediaClass_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
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.
Synopsis
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.
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION*)
601355 Rev A
Description
Pointer to the archive action 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 Functions
2-41
Functions
VS_Archive
MediaClass_
GetFields
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 percentage of the archive media
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.
Valid MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
2-42
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the media type associated with the
archive media class. Valid media type names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MIGRATION_PRIORITY
(VST_PRIORITY *)
Pointer to the migration priority to be applied
to this archive media class.
VSID_NUMBER_COMPONENT_HANDLES
(int *)
Pointer to the number of component handles
present in the component handle table.
VSID_PERCENT (VST_PERCENT *)
Pointer to the percentage of the media
assigned to the related MediaClass group
allowed in the archive associated with the
archive media class relationship.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the destination archive for media
automatically migrated out of this archive
media class. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
Return Values
601355 Rev A
VS_ArchiveMediaClass_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 media class handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-43
Functions
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2-44
API Functions
/****************************************
*********
*
* FUNCTION: vst_print_archivemediaclass
*
* PURPOSE:
* This function prints out the
information stored in
* an Archive Media Class handle.
*
* PARAMETERS:
* h : the Archive Media Class handle to
print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_archivemediaclass
(VST_ARCHIVEMEDIACLASS_HANDLE h)
#else
void vst_print_archivemediaclass(h)
VST_ARCHIVEMEDIACLASS_HANDLE h;
#endif
{
VST_ARCHIVE_NAME
Archive;
VST_MEDIA_CLASS_NAME
MediaClass;
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
Capacity;
VST_PERCENT
MediaClassPercent;
VST_ARCHIVE_ACTION_OPTION
ActionMode;
VST_HIGH_MARK
HighMark;
VST_LOW_MARK
LowMark;
VST_FILL_LEVEL
FillLevel;
VST_PRIORITY
MigrationPriority;
601355 Rev A
API Guide
30
31
32
33
34
35
36
37
38
39
40
42
43
44
45
46
47
i;
n;
VS_ArchiveMediaClass_GetFields(h,
VSID_ARCHIVE_NAME,
Archive,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
&Capacity,
VSID_PERCENT,
&MediaClassPercent,
VSID_ARCHIVE_ACTION,
&ActionMode,
VSID_HIGH_MARK,
&HighMark,
VSID_LOW_MARK,
&LowMark,
VSID_FILL_LEVEL,
&FillLevel,
VSID_MIGRATION_PRIORITY,
&MigrationPriority,
VSID_TARGET_ARCHIVE_NAME,
TargetArchive,
Functions
41
VST_ARCHIVE_NAME
TargetArchive;
VST_TABLE_HANDLE
RestrictedComps;
int
int
VST_COMPONENT_HANDLE
Component;
48
49
50
51
52
601355 Rev A
VSID_COMPONENT_HANDLE_TABLE,&Rest
rictedComps,
VSID_ENDFIELD);
printf(“*** Archive Media Class
Handle ***\n”);
printf(“Archive Name = %s\n”,
Archive);
printf(“Media Class Name = %s\n”,
MediaClass);
API Functions
2-45
API Guide
53
54
55
56
57
58
59
60
61
62
63
64
65
printf(“Media Type Name = %s\n”,
MediaType);
printf(“Capacity = %d\n”, Capacity);
printf(“Media Class percent = %d\n”,
MediaClassPercent);
printf(“Archive Action Mode = %d\n”,
ActionMode);
printf(“High Mark = %d\n”, HighMark);
printf(“Low Mark = %d\n”, LowMark);
printf(“Fill Level = %d\n”,
FillLevel);
printf(“Migration Priority = %d\n”,
MigrationPriority);
printf(“Target Archive = %s\n”,
TargetArchive);
if (RestrictedComps !=
(VST_TABLE_HANDLE) NULL)
{
/* get number of entries */
VS_Table_GetFields(RestrictedComp
s,
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for (i = 0; i < n; i++)
{
66
67
68
69
70
VS_Table_GetFields(RestrictedComp
s,
VSID_TABLE_ENTRY, i,
&Component,
VSID_ENDFIELD);
71
72
73
74
75
76 }
2-46
API Functions
vst_print_component(Component);
}
}
601355 Rev A
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
The migration policy options for are no action, operator
notification, and automatic migration.
When the number of media in an archive media class reaches
the high mark threshold, VolServ:
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
When the number of media in an archive media class drops to
the low mark threshold, VolServ:
601355 Rev A
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
•
Terminates automatic migration of media if the migration
policy is set to migrate.
API Functions
2-47
Functions
•
API Guide
See Also
2-48
API Functions
•
vsapi(l),
•
VS_Archive_GetFields(l),
•
VS_ArchiveMediaClass_Create(l),
•
VS_ArchiveMediaClass_Destroy(l),
•
VS_ArchiveMediaClass_SetFields(l),
•
VS_Error_GetFields(l),
•
VSCMD_ArchiveQuery(l)
601355 Rev A
API Guide
VS_ArchiveMediaClass_SetFields sets the value of
one or more fields in an archive media class handle. An archive
media class handle is used to pass archive media class
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_ArchiveMediaClass_SetFields
(VST_ARCHIVEMEDIACLASS
_HANDLE
handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle =Archive media class 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.
601355 Rev A
API Functions
2-49
Functions
VS_Archive
MediaClass_
SetFields
API Guide
Parameters
Parameter Type
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION)
Description
The archive action 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.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The name of the archive to be 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)
The percentage of the total MediaClass
capacity that can be stored in this archive.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE)
The preferred locations (in table format)
for media assigned to this archive media
class.
VSID_FILL_LEVEL
(VST_FILL_LEVEL)
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.
2-50
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The percentage of the archive media class
capacity below which automatic migration
of media out of the archive media class
stops. A message is generated to the
operator whenever the number of media in
the archive media class drops below this
threshold. 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)
The name of the MediaClass group to be
associated with the archive media class
relationship. Valid MediaClass names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing
spaces are not permitted.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
The media type associated with the archive
media class. Valid media type names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing
spaces are not permitted.
601355 Rev A
API Functions
2-51
Functions
VSID_LOW_MARK (VST_LOW_MARK)
API Guide
Parameter Type
VSID_MIGRATION_PRIORITY(VST_
PRIORITY)
Description
The migration priority to be applied to this
archive media class.
Increasing the archive media class
migration priority results in media being
selected from this archive media class
archive media class before media from
archive media classes with lower migration
priorities.
Likewise, decreasing the archive media
class migration priority results in media
being selected from this archive media
class after media from archive media
classes with higher migration priorities.
VSID_PERCENT (VST_PERCENT)
The percentage of the media assigned to
the related MediaClass group allowed in
the archive associated with the archive
media class relationship.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The destination archive for media
automatically migrated out of this archive
media class. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing
spaces are not permitted.
Return Values
2-52
API Functions
VS_ArchiveMediaClass_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
601355 Rev A
API Guide
Example
•
VSE_ERR_BADHANDLE - Specified handle was not an
archive media class 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.
1
4
5
6
7
8
9
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;
601355 Rev A
API Functions
2-53
Functions
2
3
/****************************************
*********
*
* FUNCTION:
vst_archivemediaclass_handle
*
* PURPOSE:
* This function tests an
archivemediaclass handle.
*
* PARAMETERS:
* none
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
2-54
API Functions
VST_ARCHIVE_NAME
Archive;
VST_MEDIA_CLASS_NAME
MediaClass;
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
Capacity;
VST_PERCENT
MediaClassPercent;
VST_ARCHIVE_ACTION_OPTION
ActionMode;
VST_HIGH_MARK
HighMark;
VST_LOW_MARK
LowMark;
VST_FILL_LEVEL
FillLevel;
VST_PRIORITY
MigrationPriority;
VST_ARCHIVE_NAME
TargetArchive;
/* create the handle */
h = VS_ArchiveMediaClass_Create();
if (h !=
(VST_ARCHIVEMEDIACLASS_HANDLE)
NULL)
{
/* get the values from the user */
printf(“** Archive Media Class
handle **\n”);
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
601355 Rev A
API Guide
46
47
48
49
50
51
52
53
54
55
57
58
59
60
61
62
63
64
65
66
67
68
601355 Rev A
API Functions
2-55
Functions
56
printf(“Enter MediaClass Percent
==> “);
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
Archive,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
Capacity,
VSID_PERCENT,
MediaClassPercent,
VSID_ARCHIVE_ACTION,
ActionMode,
VSID_HIGH_MARK,
HighMark,
VSID_LOW_MARK,
LowMark,
VSID_FILL_LEVEL,
FillLevel,
VSID_MIGRATION_PRIORITY,
MigrationPriority,
API Guide
69
70
71
72
73
74
75
76
77
78 }
Notes
VSID_TARGET_ARCHIVE_NAME,
TargetArchive,
VSID_ENDFIELD);
if (rc)
{
vst_print_archivemediaclass(h);
}
VS_ArchiveMediaClass_Destroy(h);
}
return(rc);
The migration policy options for are no action, operator
notification, and automatic migration.
When the number of media in an archive media class reaches
the high mark threshold, VolServ:
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
When the number of media in an archive media class drops to
the low mark threshold, VolServ:
2-56
API Functions
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
601355 Rev A
API Guide
•
Terminates automatic migration of media if the migration
policy is set to migrate.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_ArchiveMediaClass_Create(l),
•
VS_ArchiveMediaClass_Destroy(l),
•
VS_ArchiveMediaClass_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Table_Create(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l)
Functions
601355 Rev A
•
API Functions
2-57
API Guide
VS_
Command_
Create
VS_Command_Create allocates a VolServ API command
handle. A command handle is used to pass command
information to and from VolServ.
Synopsis
VST_COMMAND_HANDLE VS_Command_Create ( void )
Arguments
None
Return Values
VS_Command_Create returns:
Example
•
A command handle, if one can be allocated.
•
NULL, if a command handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2-58
API Functions
/****************************************
*********
*
* FUNCTION: vst_command_handle
*
* PURPOSE:
* This function tests a command handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_command_handle(void)
#else
VST_BOOLEAN vst_command_handle(void)
#endif
601355 Rev A
API Guide
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
31
39
40
41
42
43
44
45
46
47
48
49
50
601355 Rev A
rc = VSE_FALSE;
h;
requestid;
reqtype;
retrylimit;
timeout;
waitflag;
/* create the handle */
h = VS_Command_Create();
if (h != (VST_COMMAND_HANDLE) NULL)
{
/* get values from user */
printf(“*** Command Handle
***\n”);
printf(“Enter Request ID ==> “);
requestid = atol(gets(input));
printf(“Enter Request type ==> “);
reqtype = atol(gets(input));
printf(“Enter Retry Limit ==> “);
retrylimit = atol(gets(input));
printf(“Enter Timeout Value ==>
“);
timeout = atol(gets(input));
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
VSID_ENDFIELD);
if (rc)
{
API Functions
2-59
Functions
32
33
34
35
36
37
38
VST_BOOLEAN
VST_COMMAND_HANDLE
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_RETRY_LIMIT
VST_TIME_OUT
VST_STATUS_WAIT_FLAG
API Guide
51
52
53
54
55
56
57 }
/* print the handle and destroy
it */
vst_print_command(h);
}
VS_Command_Destroy(h);
}
return(rc);
Notes
A command handle must be used for only one outstanding
command at any given time.
See Also
•
vsapi(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
•
VS_Command_SetFields(l),
•
VS_Error_GetFields(l)
2-60
API Functions
601355 Rev A
API Guide
VS_
Command_
Destroy
VS_Command_Destroy deallocates a command handle that
was allocated with VS_Command_Create. A command
handle is used to pass command information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_Command_Destroy
(VST_COMMAND_HANDLE
cmdhandle)
Arguments
•
Return Values
VS_Command_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 a
command handle.
•
VSE_ERR_EXECUTING - Final status has not been
returned for the command associated with the specified
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-61
Functions
601355 Rev A
cmdhandle = Command handle to be destroyed.
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
2-62
API Functions
/****************************************
*********
*
* FUNCTION: vst_command_handle
*
* PURPOSE:
* This function tests a command handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_command_handle(void)
#else
VST_BOOLEAN vst_command_handle(void)
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_COMMAND_HANDLE
h;
VST_REQUEST_ID
requestid;
VST_REQUEST_TYPE
reqtype;
VST_RETRY_LIMIT
retrylimit;
VST_TIME_OUT
timeout;
VST_STATUS_WAIT_FLAG waitflag;
/* create the handle */
h = VS_Command_Create();
if (h != (VST_COMMAND_HANDLE) NULL)
{
/* get values from user */
printf(“*** Command Handle
***\n”);
printf(“Enter Request ID ==> “);
requestid = atol(gets(input));
printf(“Enter Request type ==> “);
reqtype = atol(gets(input));
printf(“Enter Retry Limit ==> “);
retrylimit = atol(gets(input));
printf(“Enter Timeout Value ==>
“);
601355 Rev A
API Guide
39
40
41
42
43
44
45
46
47
52
53
54
55
56
57 }
Notes
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
VSID_ENDFIELD);
if (rc)
{
/* print the handle and destroy
it */
vst_print_command(h);
}
VS_Command_Destroy(h);
}
return(rc);
A command handle should be used for only one outstanding
command at any given time.
After VS_Command_Destroy has been called for a command
handle, that handle is no longer valid and should not be used.
If final status has not been received for a command, the API
software fails a VS_Command_Destroy request for the
associated command handle.
601355 Rev A
API Functions
2-63
Functions
48
49
50
51
timeout = atol(gets(input));
API Guide
See Also
2-64
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_GetFields(l),
•
VS_Command_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
VS_Command_GetErrorFields retrieves information
associated with the command’s error handle. It can be used in
place of the VS_Error_GetFields routine when the user
does not want to retrieve the error handle explicitly from the
command handle.
Synopsis
VST_BOOLEAN VS_Command_GetErrorFields
(VST_COMMAND_HANDLE cmdhandle,
Arguments
•
cmdhandle = Command handle where the status
information is retrieved.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by 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 section.
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
VSID_ERROR_CODE (VST_ERROR_CODE)
Pointer to the error code for the given error.
VSID_ERROR_FILE (VST_ERROR_FILE)
The name of the source file where the error
occurred (API internal errors only).
VSID_ERROR_LINE (int *)
Pointer to the source line number where the
error occurred (API internal errors only).
601355 Rev A
API Functions
2-65
Functions
VS_
Command_
GetErrorFields
API Guide
Parameter Type
Description
VSID_ERROR_NUMBER
(VST_ERROR_NUMCODE *)
Pointer to the field that indicates which error
occurred.
VSID_ERROR_OBJECT
(VST_ERROR_OBJCODE *)
Pointer to the field that indicates the location
of the error.
Return Values
Notes
2-66
VS_Command_GetErrorFields 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 a
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
VS_Error_GetErrorFields returns
API Functions
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not an
error handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
601355 Rev A
API Guide
See Also
•
VS_Command_Create,
•
VS_Command_Destroy,
•
VS_Command_GetFields,
•
VS_Command_SetFields,
•
VS_Error_GetFields
Functions
601355 Rev A
API Functions
2-67
API Guide
VS_
Command_
GetFields
VS_Command_GetFields retrieves information associated
with a command handle. A command handle is used to pass
command information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Command_GetFields
(VST_COMMAND_HANDLE cmdhandle,
"…",
VSID_ENDFIELD)
Arguments
•
cmdhandle = Command 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.
Parameters
Parameter Type
Description
VSID_ERROR_HANDLE
(VST_ERROR_HANDLE *)
Pointer to the error handle associated with this
command.
VSID_REQUEST_ID (VST_REQUEST_ID *)
Pointer to the request identifier associated
with this command.
2-68
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE *)
Pointer to the type of command. Valid
VSID_REQUEST_TYPE values are
enumerated in the vs_type.h file.
VSID_STATUS_HANDLE
(VST_STATUS_HANDLE *)
Pointer to the status handle associated with
this command.
Return Values
601355 Rev A
•
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 a
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
Functions
Example
VS_Command_GetFields returns:
1
/****************************************
*********
2 *
3 * FUNCTION: vst_print_command
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a command handle.
8 *
9 * PARAMETERS:
10 * h : the command handle to print
11 *
API Functions
2-69
API Guide
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_command(VST_COMMAND_HAN
DLE h)
15 #else
16
void vst_print_command(h)
17
VST_COMMAND_HANDLE h;
18 #endif
19 {
20
VST_REQUEST_ID
requestid;
21
VST_REQUEST_TYPE
reqtype;
22
VST_RETRY_LIMIT
retrylimit;
23
VST_TIME_OUT
timeout;
24
VST_STATUS_WAIT_FLAG waitflag;
25
VST_ERROR_HANDLE
eh;
26
VST_STATUS_HANDLE
sh;
27
28
VS_Command_GetFields(h,
29
VSID_REQUEST_ID,
&requestid,
30
VSID_REQUEST_TYPE,
&reqtype,
31
VSID_RETRY_LIMIT,
&retrylimit,
32
VSID_TIMEOUT_VALUE,
&timeout,
33
VSID_STATUS_WAIT_FLAG,
&waitflag,
34
VSID_ERROR_HANDLE,
&eh,
35
VSID_STATUS_HANDLE,
&sh,
36
VSID_ENDFIELD);
37
38
printf(“ ****Command Handle
Information****\n\n”);
39
printf(“RequestID = %luRequestType =
%d\n”,requestid,reqtype);
40
printf(“Retry Limit = %dTime Out =
%d\n”,retrylimit,timeout);
2-70
API Functions
601355 Rev A
API Guide
41
42
43
44
45 }
Notes
printf(“StatusWait =
%d\n”,waitflag);
vst_print_status(sh);
vst_print_error(eh);
The command’s status is kept in its status handle.
The command’s error is kept in its error handle.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_SetFields(l),
•
VS_Error_GetFields(l)
Functions
See Also
API Functions
2-71
API Guide
VS_
Command_
GetStatusFields
VS_Command_GetStatusFields retrieves information
associated with the command’s status handle. It can be used in
place of the VS_Status_GetFields routine when the user does
not want to retrieve the status handle explicitly from the
command handle
Synopsis
VST_BOOLEAN VS_Command_GetStatusFields
(VST_COMMAND_HANDLE cmdhandle, “…”,
VSID_ENDFIELD )
Arguments
•
cmdhandle = Command handle from where the status
information is retrieved.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by 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 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 section.
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
2-72
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Pointer to the first entry in the action code
table.
VSID_ACTION_CODE_ENTRY (int)
Index of the appropriate entry in the action
code table.
(VST_ACTION_CODE *)
Pointer to the appropriate entry in the action
code table.
VSID_ACTION_CODE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the action code table associated
with this status.
VSID_ARCHIVE_HANDLE
(VST_ARCHIVE_HANDLE *)
Pointer to the first archive handle in the
archive handle table.
VSID_ARCHIVE_HANDLE_ENTRY (int)
Index of the appropriate archive handle in the
archive handle table.
(VST_ARCHIVE_HANDLE *)
Pointer to the appropriate archive handle in
the archive handle table.
VSID_ARCHIVE_HANDLE_TABLE
Pointer to the archive handle table associated
with this status.
(VST_TABLE_HANDLE *)
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the name of the archive associated
with this status. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_ARCHIVEMEDIACLASS_HANDLE
Pointer to the first archive media class handle
in the archive media class table.
(VST_ARCHIVE_MEDIACLAS_HANDLE *)
VSID_ARCHIVEMEDIACLASS_HANDLE_
ENTRY (int)
Index of the appropriate archive media class
handle in the archive media class handle
table.
(VST_ARCHIVEMEDIACLASS_HANDLE *)
Pointer to the appropriate archive media class
handle in the archive media class handle
table.
601355 Rev A
API Functions
2-73
Functions
VSID_ACTION_CODE
(VST_ACTION_CODE *)
API Guide
Parameter Type
Description
VSID_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE *)
Pointer to the archive media class handle
table associated with this status.
VSID_COMPONENT_HANDLE
Pointer to the first component handle in the
component handle table.
(VST_COMPONENT_HANDLE *)
VSID_COMPONENT_HANDLE_ENTRY (int)
(VST_COMPONENT_HANDLE *)
Index of the appropriate component handle in
the component handle table.
Pointer to the appropriate component handle
in the component handle table.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the component handle table
associated with this status.
VSID_COMP_ID (VST_COMPONENT_ID *)
Pointer to the first component identifier in the
component identifier table.
VSID_COMP_ID_ENTRY (int)
Index of the appropriate component identifier
in the component identifier table.
(VST_COMPONENT_ID *)
Pointer to the appropriate component identifier
in the component identifier table.
VSID_COMP_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the component identifier table
associated with this status.
VSID_COMP_STATE
(VST_COMPONENT_STATE *)
Pointer to the component state for this status.
Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE *)
Pointer to the first entry in the connect handle
table.
VSID_CONNECT_HANDLE_ENTRY (int)
Index of the appropriate connect handle in the
connect handle table.
(VST_CONNECT_HANDLE *)
Pointer to the appropriate connect handle in
the connect handle table.
VSID_CONNECT_HANDLE_TABLE
Pointer to the connect handle table associated
with this status.
(VST_TABLE_HANDLE *)
2-74
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the first drive handle in the drive
handle table.
VSID_DRIVE_HANDLE_ENTRY (int)
Index the appropriate drive handle in the drive
handle table.
(VST_DRIVE_HANDLE *)
Pointer to the appropriate drive handle in the
drive handle table.
VSID_DRIVE_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive handle table associated
with this status.
VSID_DRIVE_ID (VST_DRIVE_ID *)
Pointer to the first drive identifier in the drive
identifier table.
VSID_DRIVE_ID_ENTRY (int)
Index of the appropriate drive identifier in the
drive identifier table.
(VST_DRIVE_ID *)
Pointer to the appropriate drive identifier in the
drive identifier table.
VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive identifier table associated
with this status.
VSID_DRIVEPOOL_HANDLE
Pointer to the first drive pool handle in the
drive pool handle table.
(VST_DRIVE_POOL_HANDLE *)
VSID_DRIVEPOOL_HANDLE_ENTRY (int)
Index of the appropriate drive pool handle in
the drive pool handle table.
(VST_DRIVEPOOL_HANDLE *)
Pointer to the appropriate drive pool handle in
the drive pool handle table.
VSID_DRIVEPOOL_HANDLE_TABLE
Pointer to the drive pool handle table
associated with this status.
(VST_TABLE_HANDLE *)
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Pointer to the name of the drive pool group.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the identifier of the enterprise, if any,
to receive command status.
601355 Rev A
API Functions
2-75
Functions
VSID_DRIVE_HANDLE
(VST_DRIVE_HANDLE *)
API Guide
Parameter Type
Description
VSID_ERROR_CODE
(VST_VOLERR_CODE *)
Pointer to the first error code in the error code
table.
VSID_ERROR_CODE_ENTRY (int)
Index of the appropriate error code in the error
code table.
(VST_VOLERR_CODE *)
Pointer to the appropriate error code in the
error code table.
VSID_ERROR_TABLE
(VST_TABLE_HANDLE *)
Pointer to the error code table associated with
this status.
VSID_FIELD (int *)
Pointer to the first field in the user-defined
media statistics field table.
VSID_FIELD_ENTRY (int)
Index of the appropriate field in the
user-defined media statistics field table.
(int *)
Pointer to the appropriate field in the
user-defined media statistics field table.
VSID_FIELD_TABLE
(VST_TABLE_HANDLE *)
Pointer to the user-defined media statistics
field table associated with this status.
VSID_LOCK_ID (VST_LOCK_ID *)
Pointer to the lock identifier associated with
this status.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass name associated
with this status.
VSID_MEDIA_HANDLE
(VST_MEDIA_HANDLE *)
Pointer to the first media handle in the media
handle table.
VSID_MEDIA_HANDLE_ENTRY (int)
Index of the appropriate media handle in the
media handle table.
(VST_MEDIA_HANDLE *)
Pointer to the appropriate media handle in the
media handle table.
VSID_MEDIA_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media handle table associated
with this status.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the first media identifier in the media
identifier table.
2-76
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_MEDIA_ID_ENTRY (int)
Index of the appropriate entry in the media
identifier table.
(VST_MEDIA_ID *)
Pointer to the appropriate media identifier in
the media identifier table.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media identifier table associated
with this status.
VSID_MEDIACLASS_HANDLE
Pointer to the first MediaClass handle in the
MediaClass handle table.
(VST_MEDIACLASS_HANDLE *)
Index of the appropriate MediaClass handle in
the MediaClass handle table
(VST_MEDIACLASS_HANDLE *)
Pointer to the appropriate MediaClass handle
in the MediaClass handle table.
VSID_MEDIACLASS_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the MediaClass handle table
associated with this status.
VSID_MEDIATYPE_HANDLE
Pointer to the first media type handle in the
media type handle table.
(VST_MEDIATYPE_HANDLE *)
VSID_MEDIATYPE_HANDLE_ENTRY (int)
Index of the appropriate media type handle in
the media type handle table.
(VST_MEDIATYPE_HANDLE *)
Pointer to the appropriate media type handle
in the media type handle table.
VSID_MEDIATYPE_HANDLE_TABLE
Pointer to the media type handle table
associated with this status.
(VST_TABLE_HANDLE *)
VSID_NUMBER_ACTION_CODES (int *)
Pointer to the number of action codes in the
action code table.
VSID_NUMBER_ARCHIVE_HANDLES (int *)
Pointer to the number of archive handles in
the archive handle table.
VSID_NUMBER_COMP_IDS (int *)
Pointer to the number of component ids in the
component identifier table.
601355 Rev A
API Functions
2-77
Functions
VSID_MEDIACLASS_HANDLE_ENTRY (int)
API Guide
Parameter Type
Description
VSID_NUMBER_COMPONENT_HANDLES
(int *)
Pointer to the number of component handles
in the component handle table.
VSID_NUMBER_CONNECT_HANDLES
(int *)
Pointer to the number of connect handles in
the connect handle table.
VSID_NUMBER_DRIVE_HANDLES (int *)
Pointer to the number of drive handles in the
drive handle table.
VSID_NUMBER_DRIVE_IDS (int *)
Pointer to the number of drive ids in the drive
id table.
VSID_NUMBER_DRIVEPOOL_HANDLES
(int *)
Pointer to the number of drive pool handles in
the drive pool handle table.
VSID_NUMBER_ERROR_CODES (int *)
Pointer to the number of error codes in the
error code table.
VSID_NUMBER_FIELDS (int *)
Pointer to the number of field ids in the field
identifier table.
VSID_NUMBER_MEDIA_HANDLES (int *)
Pointer to the number of media handles
present in the media handle table.
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of media ids in the
media id table.
VSID_NUMBER_MEDIACLASS_HANDLES
(int *)
Pointer to the number of media class handles
in the media class handle table.
VSID_NUMBER_MEDIATYPE_HANDLES
(int *)
Pointer to the number of media type handles
in the media type handle table.
VSID_NUMBER_REQUEST_IDS (int *)
Pointer to the number of request ids present in
the request id table.
VSID_NUMBER_REQUEST_HANDLES
(int *)
Pointer to the number of request handles in
the request handle table.
VSID_PID (VST_PID *)
Pointer to the VolServ identifier for the Ping
status.
VSID_QRY_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the enterprise identifier, if any, for
the Connect Query command.
2-78
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the query option for this status.
VSID_REQUEST_HANDLE
(VST_REQUEST_HANDLE *)
Pointer to the first request handle in the
request handle table.
VSID_REQUEST_HANDLE_ENTRY (int)
Index of the appropriate request handle in the
request handle table.
(VST_REQUEST_HANDLE *)
Pointer to the appropriate request handle in
the request handle table.
VSID_REQUEST_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the request handle table associated
with this status.
VSID_REQUEST_ID (VST_REQUEST_ID *)
Pointer to the request identifier of the target
command for a Cancel or Reprioritize request.
VSID_SEQUENCE_NUM (int *)
Pointer to the sequence number of this status.
Initial status for a command request is
sequence number 0. Sequence numbers for
subsequent statuses for the same command
request are assigned as one-up numbers. For
example, the first intermediate status (if there
is an intermediate status) or the final status (if
there is no intermediate status) is sequence
number 1.
VSID_SEQUENCE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the sequence numbers (in table
format) of the statuses received for this
command.
VSID_STATUS_CODE
(VST_STATUS_CODE *)
Pointer to the status code for this status.
Indicates whether the command was
successful or failed. Valid
VSID_STATUS_CODE values are enumerated
in the vs_types.h file.
VSID_STATUS_TYPE
(VST_STATUS_TYPE *)
Pointer to the status type (intermediate or
final) for this status. Valid
VSID_STATUS_TYPE values are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-79
Functions
VSID_QRY_OPTION (VST_QRY_OPTION *)
API Guide
Parameter Type
Description
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the enterprise identifier for a
ConnectQuery or Disconnect command.
VSID_USER_FIELD (VST_USER_FIELD)
Pointer to the user field contents for the
associated command. USER_FIELD is 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.
VSID_WAIT_REASON
(VST_WAIT_REASON *)
Pointer to the wait reason for an intermediate
status. Valid VSID_WAIT_REASON values are
enumerated in the vs_types.h file.
Return Values
2-80
API Functions
VS_Command_GetStatusFields 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 a
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
601355 Rev A
API Guide
Notes
The command’s status is kept in its status handle, and the
command’s error is kept in its error handle.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
VS_Command_Create,
•
VS_Command_Destroy,
•
VS_Command_GetFields,
•
VS_Command_SetFields,
•
VS_Status_GetFields
Functions
601355 Rev A
•
API Functions
2-81
API Guide
VS_
Command_
SetFields
VS_Command_Setfields sets the value of one or more
fields in a command handle. A command handle is used to pass
command information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Command_Setfields
( VST_COMMAND_HANDLE cmdhandle,
"…",
VSID_ENDFIELD )
Arguments
•
cmdhandle = Command 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.
2-82
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
VSID_ERROR_HANDLE
(VST_ERROR_HANDLE)
Error handle associated with this command.
VSID_REQUEST_ID (VST_REQUEST_ID)
Request identifier associated with this
command.
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE)
Type of command. Valid
VSID_REQUEST_TYPE values are
enumerated in the vs_type.h file.
VSID_STATUS_HANDLE
(VST_STATUS_HANDLE)
Status handle associated with this command.
601355 Rev A
VS_Command_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
command 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.
API Functions
2-83
Functions
Return Values
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
2-84
API Functions
/****************************************
*********
*
* FUNCTION: vst_command_handle
*
* PURPOSE:
* This function tests a command handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_command_handle(void)
#else
VST_BOOLEAN vst_command_handle(void)
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_COMMAND_HANDLE
h;
VST_REQUEST_ID
requestid;
VST_REQUEST_TYPE
reqtype;
VST_RETRY_LIMIT
retrylimit;
VST_TIME_OUT
timeout;
VST_STATUS_WAIT_FLAG waitflag;
/* create the handle */
h = VS_Command_Create();
if (h != (VST_COMMAND_HANDLE) NULL)
{
/* get values from user */
printf(“*** Command Handle
***\n”);
printf(“Enter Request ID ==> “);
requestid = atol(gets(input));
printf(“Enter Request type ==> “);
reqtype = atol(gets(input));
printf(“Enter Retry Limit ==> “);
retrylimit = atol(gets(input));
printf(“Enter Timeout Value ==>
“);
601355 Rev A
API Guide
39
40
41
42
43
44
45
46
47
52
53
54
55
56
57 }
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
VSID_ENDFIELD);
if (rc)
{
/* print the handle and destroy
it */
vst_print_command(h);
}
VS_Command_Destroy(h);
}
return(rc);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
API Functions
2-85
Functions
48
49
50
51
timeout = atol(gets(input));
API Guide
•
2-86
API Functions
VS_Error_GetFields(l)
601355 Rev A
API Guide
VS_
Component_
Create
VS_Component_Create allocates a VolServ API
component handle. A component handle is used to pass
component information to and from VolServ.
Synopsis
VST_COMPONENT_HANDLE VS_Component_Create
( void )
Arguments
None
Return Values
VS_Component_Create returns:
601355 Rev A
A component handle, if one can be allocated.
•
NULL, if a component handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
Functions
Example
•
1
/****************************************
*********
2 *
3 *FUNCTION:
vst_modarchivemediaclass_execute
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_ModifyArchiveMediaClass
7 * API all.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13
API Functions
2-87
API Guide
14 #ifdef ANSI_C
15
VST_BOOLEAN
vst_modarchivemediaclass_execute(
void)
16 #else
17
VST_BOOLEAN
vst_modarchivemediaclass_execute(
)
18 #endif
19 {
20
int
i;
21
int count;
22
VST_BOOLEAN
rc =
VSE_FALSE;
23
VST_ARCHIVE_NAME
archive;
24
VST_MEDIA_CLASS_NAME
mediaclass;
25
VST_CAPACITY
capacity;
26
VST_ARCHIVE_ACTION_OPTION action;
27
VST_HIGH_MARK
highmark;
28
VST_LOW_MARK
lowmark;
29
VST_PRIORITY
migpri;
30
VST_ARCHIVE_NAME
targetarchive;
31
VST_TABLE_HANDLE
comphandletable;
32
VST_COMPONENT_HANDLE
comphandle;
33
VST_COMP_TYPE
CompType =
VSE_COMPTYPE_COLUMN;
34
VST_COMPONENT_ID
CompID;
35
VST_COMMAND_HANDLE
cmd;
36
37
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
38
/* get parameters from user */
39
printf(“Modify archive media class
parameters \n” );
40
printf(“The archive media class must
exist. \n”);
41
printf(“Enter Archive Name ==> “ );
42
gets( archive );
2-88
API Functions
601355 Rev A
API Guide
43
44
45
46
47
48
49
50
51
52
53
54
57
58
59
60
61
62
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
printf(“Enter Target Archive ==> “
);
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
/* These only need to be set when
*/
/* migration is used. */
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
63
64
65
66
67
68
69
70
601355 Rev A
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
API Functions
2-89
Functions
55
56
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==>“ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
API Guide
71
72
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
73
74
75
76
77
78
79
80
81
82
83
84
85
86
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
VSID_ENDFIELD);
87
88
89
90
VS_Table_AddEntry(comphandletable
,comphandle);
}
91
92
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
VSID_ENDFIELD);
93
94
95
2-90
API Functions
}
601355 Rev A
API Guide
96
97
98
99
100
101
102
103
104
105
106
107
109
110
111
112
113
114
115
116
117
118
119}
Notes
601355 Rev A
None
API Functions
2-91
Functions
108
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, */
/* but in vst_dispatch */
/* when final status is received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
vst_dispatch */
/* routine. Also, note that
default values such */
/* as timeout, value retry limit
and priority */
/* are set as default parameters.
*/
rc =
VSCMD_ModifyArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
}
return ( rc );
API Guide
See Also
2-92
API Functions
•
vsapi(l),
•
VS_Component_Destroy(l),
•
VS_Component_GetFields(l),
•
VS_Component_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
VS_
Component_
Destroy
VS_Component_Destroy deallocates a component handle
that was allocated with VS_Component_Create. A
component handle is used to pass component information to
and from VolServ.
Synopsis
VST_BOOLEAN VS_Component_Destroy
( VST_COMPONENT_HANDLE handle )
Arguments
•
Return Values
VS_Component_Destroy returns:
601355 Rev A
•
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
component handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_component_handle
4 *
5 * PURPOSE:
6 * This function tests the component
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
2-93
Functions
Example
handle = Component handle to be destroyed.
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_component_handle(void)
14 #else
15
VST_BOOLEAN vst_component_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_TRUE;
19
VST_COMPONENT_HANDLE
comph;
20
VST_COMP_TYPE
comptype;
21
VST_COMPONENT_ID
id;
22
23
comph = VS_Component_Create();
24
if (comph != (VST_COMPONENT_HANDLE)
NULL)
25
{
26
printf(“enter component type
==>”);
27
comptype = atoi(gets(input));
28
printf(“enter 4 values for the
component id (e.g. 3 2 4 1) ==>”);
29
scanf(“%hd %hd %hd %hd”, &id[0],
&id[1], &id[2], &id[3]);
30
gets(input);
31
VS_Component_SetFields(comph,
32
VSID_COMP_TYPE,
comptype,
33
VSID_COMP_ID,
id,
34
VSID_ENDFIELD);
35
vst_print_component(comph);
36
VS_Component_Destroy(comph);
37
}
38
else
39
{
40
rc = VSE_FALSE;
41
}
42
return(rc);
43 }
2-94
API Functions
601355 Rev A
API Guide
Notes
After VS_Component_Destroy has been called for a
component handle, that handle is no longer valid and should not
be used.
See Also
•
vsapi(l),
•
VS_Component_Create(l),
•
VS_Component_GetFields(l),
•
VS_Component_SetFields(l),
•
VS_Error_GetFields(l)
Functions
601355 Rev A
API Functions
2-95
API Guide
VS_
Component_
GetFields
VS_Component_GetFields retrieves information from a
component handle. The component handle is used to pass
component information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Component_GetFields
( VST_COMPONENT_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Component handle for which 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.
Parameters
Parameter Type
Description
VSID_COMP_ID (VST_COMP_ID *)
Pointer to the identifier of the component.
VSID_COMP_TYPE (VST_COMP_TYPE *)
Pointer to the type of this component.
2-96
API Functions
601355 Rev A
API Guide
Return Values
•
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 a
component handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_print_component
*
* PURPOSE:
* This function prints out the
information stored in
* a component handle.
*
* PARAMETERS:
* h : the component handle to print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_component(VST_COMPONENT
_HANDLE h)
#else
void vst_print_component(h)
VST_COMPONENT_HANDLE h;
#endif
{
VST_COMP_TYPE
CompType;
API Functions
2-97
Functions
Example
VS_Component_GetFields returns:
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_COMPONENT_ID
int
CompID;
i;
VS_Component_GetFields(h,
VSID_COMP_TYPE,
&CompType,
VSID_COMP_ID,
CompID,
VSID_ENDFIELD);
printf(“******* Component Handle
*******\n”);
printf(“Component Type = %d\n”,
CompType);
printf(“Component ID = “);
for (i = 0; i < VSD_MAX_COMPONENT_ID;
i++)
{
printf(“%d”, CompID[i]);
if (i < VSD_MAX_COMPONENT_ID - 1)
{
printf(“, “);
}
}
printf(“\n”);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-98
API Functions
•
vsapi(l),
•
VS_Component_Create(l),
•
VS_Component_Destroy(l),
•
VS_Component_SetFields(l),
601355 Rev A
API Guide
•
VS_Error_GetFields(l),
•
VS_Table_Create(l),
•
VS_Table_SetFields(l),
•
VS_TableAddEntry(l),
•
VSCMD_CreateArchiveMediaClass(l),
•
VSCMD_ModifyArchiveMediaClass(l)
Functions
601355 Rev A
API Functions
2-99
API Guide
VS_
Component_
SetFields
VS_Component_SetFields sets the value of one or more
fields in a VolServ API component handle. A component
handle is used to pass component information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_Component_SetFields
( VST_COMPONENT_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Component 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.
Parameters
Parameter Type
Description
VSID_COMP_ID (VST_COMP_ID)
Identifier of the component.
VSID_COMP_TYPE (VST_COMP_TYPE)
Type of this component. Valid
VSID_COMP_TYPE values are enumerated in
the vs_types.h file.
2-100
API Functions
601355 Rev A
API Guide
Return Values
•
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
component 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
/****************************************
*********
*
*FUNCTION:
vst_modarchivemediaclass_execute
*
* PURPOSE:
* This executes the
VSCMD_ModifyArchiveMediaClass
* API all.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modarchivemediaclass_execute(
void)
#else
API Functions
2-101
Functions
Example
VS_Component_SetFields returns:
API Guide
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
2-102
API Functions
VST_BOOLEAN
vst_modarchivemediaclass_execute(
)
#endif
{
int
i;
int count;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_CAPACITY
capacity;
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
highmark;
VST_LOW_MARK
lowmark;
VST_PRIORITY
migpri;
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE
CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
CompID;
VST_COMMAND_HANDLE
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
/* get parameters from user */
printf(“*** Modify Archive Media
Class parameters ***\n” );
printf(“*** The archive media class
must exist. ***\n”);
printf(“Enter Archive Name ==> “ );
gets( archive ); archive media class
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
601355 Rev A
API Guide
45
46
47
48
49
50
51
52
53
54
55
58
59
60
61
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
printf(“Enter Target Archive ==> “
);
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
/* These only need to be set when
migration */
/* is used. */
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
62
63
64
65
66
67
68
69
70
71
601355 Rev A
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
API Functions
2-103
Functions
56
57
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==>“ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
API Guide
72
73
74
75
76
77
78
79
80
81
82
83
84
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
86
87
88
89
90
91
92
93
94
95
96
2-104
API Functions
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
}
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
601355 Rev A
API Guide
97
98
99
100
101
102
103
104
105
106
108
109
110
111
112
113
114
115
116
117
118}
601355 Rev A
API Functions
2-105
Functions
107
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc =
VSCMD_ModifyArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
}
return ( rc );
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-106
API Functions
•
vsapi(l),
•
VS_Component_Create(l),
•
VS_Component_Destroy(l),
•
VS_Component_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Table_Create(l),
•
VS_Table_SetFields(l),
•
VS_TableAddEntry(l)
601355 Rev A
API Guide
VS_Connect_
Create
VS_Connect_Create allocates a VolServ API connect
handle. A connect handle is used to pass connect information to
and from VolServ.
Synopsis
VST_CONNECT_HANDLE VS_Connect_Create ( void )
Arguments
None
Return Values
VS_Connect_Create returns:
A connect handle, if one can be allocated.
•
NULL, if a connect handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_connect_handle
*
* PURPOSE:
* This function tests a connect handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_connect_handle(void)
#else
VST_BOOLEAN vst_connect_handle()
#endif
{
API Functions
2-107
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
2-108
API Functions
VST_CONNECT_HANDLE
h;
VST_BOOLEAN
rc = VSE_FALSE;
VST_ENTERPRISE_ID
EnterpriseID;
VST_SOCKADDR_IN
SocketAddress;
VST_PROGRAM_NUMBER
ProgramNumber;
VST_VERSION_NUMBER
VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
VST_PROTOCOL Protocol;
/* create the handle */
h = VS_Connect_Create();
if (h != (VST_CONNECT_HANDLE) NULL)
{
/* get values from user */
printf(“*** connect handle
***\n”);
printf(“Enter enterprise ID ==>
“);
EnterpriseID = atol(gets(input));
printf(“Enter Internet sin_port
value ==> “);
SocketAddress.sin_port = (short)
atoi(gets(input));;
printf(“Enter Internet sin_family
value ==> “);
SocketAddress.sin_family =
(short)
atoi(gets(input));
printf(“Enter Internet sin_addr
value ==> “);
SocketAddress.sin_addr =
atol(gets(input));
printf(“Enter program number ==>
“);
ProgramNumber =
atol(gets(input));
printf(“Enter version number ==>
“);
VersionNumber =
atol(gets(input));
601355 Rev A
API Guide
45
46
47
48
49
50
51
52
53
54
55
57
58
59
60
61
62
63
64
65 }
}
return(rc);
Notes
None
See Also
•
vsapi(l),
•
VS_Connect_Destroy(l),
•
VS_Connect_GetFields(l),
•
VS_Connect_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-109
Functions
56
printf(“Enter procedure number
==> “);
ProcedureNumber =
atol(gets(input));
printf(“Enter Protocol ==> “);
Protocol = atol(gets(input));
/* set the fields */
rc = VS_Connect_SetFields(h,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
VSID_ENDFIELD);
if (rc)
{
vst_print_connect(h);
}
VS_Connect_Destroy(h);
API Guide
VS_Connect_
Destroy
VS_Connect_Destroy deallocates a connect handle that
was allocated with VS_Connect_Create. A connect handle
is used to pass connect information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Connect_Destroy
(VST_CONNECT_HANDLE handle)
Arguments
•
Return Values
VS_Connect_Destroy returns:
Example
2-110
handle = Connect handle to be destroyed.
•
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
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_connect_handle
4 *
5 * PURPOSE:
6 * This function tests a connect handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
API Functions
601355 Rev A
API Guide
12
13
14
15
16
17
18
19
20
21
22
23
24
601355 Rev A
API Functions
2-111
Functions
#ifdef ANSI_C
VST_BOOLEAN vst_connect_handle(void)
#else
VST_BOOLEAN vst_connect_handle()
#endif
{
VST_CONNECT_HANDLE
h;
VST_BOOLEAN
rc = VSE_FALSE;
VST_ENTERPRISE_ID
EnterpriseID;
VST_SOCKADDR_IN
SocketAddress;
VST_PROGRAM_NUMBER
ProgramNumber;
VST_VERSION_NUMBER
VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
25
VST_PROTOCOL Protocol;
26
27
/* create the handle */
28
h = VS_Connect_Create();
29
if (h != (VST_CONNECT_HANDLE) NULL)
30
{
31
/* get values from user */
32
printf(“*** connect handle
***\n”);
33
printf(“Enter enterprise ID ==>
“);
34
EnterpriseID = atol(gets(input));
35
printf(“Enter Internet sin_port
value ==> “);
36
SocketAddress.sin_port = (short)
atoi(gets(input));;
37
printf(“Enter Internet sin_family
value ==> “);
38
SocketAddress.sin_family =
(short)
atoi(gets(input));
39
printf(“Enter Internet sin_addr
value ==> “);
40
SocketAddress.sin_addr =
atol(gets(input));
41
printf(“Enter program number ==>
“);
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65 }
ProgramNumber =
atol(gets(input));
printf(“Enter version number ==>
“);
VersionNumber =
atol(gets(input));
printf(“Enter procedure number
==> “);
ProcedureNumber =
atol(gets(input));
printf(“Enter Protocol ==> “);
Protocol = atol(gets(input));
/* set the fields */
rc = VS_Connect_SetFields(h,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
VSID_ENDFIELD);
if (rc)
{
vst_print_connect(h);
}
VS_Connect_Destroy(h);
}
return(rc);
Notes
After VS_Connect_Destroy has been called for a connect
handle, that handle is no longer valid and should not be used.
See Also
•
2-112
API Functions
vsapi(l),
601355 Rev A
API Guide
•
VS_Connect_Create(l),
•
VS_Connect_GetFields(l),
•
VS_Connect_SetFields(l),
•
VS_Error_GetFields(l)
Functions
601355 Rev A
API Functions
2-113
API Guide
VS_Connect_
GetFields
VS_Connect_GetFields retrieves information associated
with a connect handle. A connect handle is used to pass connect
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Connect_GetFields
(VST_CONNECT_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Connect 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.
Parameters
Parameter Type
Description
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the enterprise identifier associated
with this client.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER *)
Pointer to the RPC procedure number of the
client process to receive status messages
from VolServ.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
Pointer to the RPC program number of the
client process to receive status messages.
2-114
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL *)
Pointer to the Internet protocol to use to return
status messages to the connected client
process. Valid VSID_PROTOCOL values are
enumerated in the vs_types.h file.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN *)
Pointer to the Internet socket address for the
client process.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER *)
Pointer to the RPC version number of the
client process to receive status messages.
Return Values
•
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 a
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_print_connect
*
* PURPOSE:
* This function prints out the
information stored in
* a connect handle.
*
* PARAMETERS:
API Functions
2-115
Functions
Example
VS_Connect_GetFields returns:
API Guide
10 * h : the connect handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_connect(VST_CONNECT_HAN
DLE h)
15 #else
16
void vst_print_connect(h)
17
VST_CONNECT_HANDLE h;
18 #endif
19 {
20
VST_ENTERPRISE_ID
EnterpriseID;
21
VST_SOCKADDR_IN
SocketAddress;
22
VST_PROGRAM_NUMBER
ProgramNumber;
23
VST_VERSION_NUMBER
VersionNumber;
24
VST_PROCEDURE_NUMBER
ProcedureNumber;
25
VST_PROTOCOL
Protocol;
26
27
VS_Connect_GetFields(h,
28
VSID_ENTERPRISE_ID,
&EnterpriseID,
29
VSID_SOCKADDR_IN,
&SocketAddress,
30
VSID_PROGRAM_NUMBER,
&ProgramNumber,
31
VSID_VERSION_NUMBER,
&VersionNumber,
32
VSID_PROCEDURE_NUMBER,
&ProcedureNumber,
33
VSID_PROTOCOL,
&Protocol,
34
VSID_ENDFIELD);
35
36
printf(“******* Connect Handle
*******\n”);
2-116
API Functions
601355 Rev A
API Guide
37
38
39
40
41
42
43
44
45 }
printf(“Enterprise ID = %d\n”,
EnterpriseID);
printf(“Socket Family = %d\n”,
SocketAddress.sin_family);
printf(“Socket Port = %d\n”,
SocketAddress.sin_port);
printf(“Socket Address = %lu\n”,
SocketAddress.sin_addr);
printf(“Program Number = %lu\n”,
ProgramNumber);
printf(“Version Number = %lu\n”,
VersionNumber);
printf(“Procedure Number = %lu\n”,
ProcedureNumber);
printf(“Protocol = %d\n”, Protocol);
Functions
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Connect_Create(l),
•
VS_Connect_Destroy(l),
•
VS_Connect_SetFields(l),
•
VS_Error_GetFields(l),
•
VSCMD_ConnectQuery(l),
•
VSCMD_Connect(l),
•
VSCMD_Disconnect(l)
API Functions
2-117
API Guide
VS_Connect_
SetFields
VS_Connect_SetFields sets the value of one or more
fields in a connect handle. A connect handle is used to pass
connect information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Connect_SetFields
(VST_CONNECT_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Connect 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.
Parameters
Parameter Type
Description
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Enterprise identifier to associate with this
client.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
to receive status messages from VolServ.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process to
receive status messages.
2-118
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol to use to transmit status
messages to this client. Valid
VSID_PROTOCOL values are enumerated in
the vs_types.h file.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN)
Internet socket address for this client.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process to
receive status messages.
Return Values
•
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
connect 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.
1
2
3
4
5
6
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_connect_handle
*
* PURPOSE:
* This function tests a connect handle.
API Functions
2-119
Functions
Example
VS_Connect_SetFields returns:
API Guide
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
2-120
API Functions
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_connect_handle(void)
#else
VST_BOOLEAN vst_connect_handle()
#endif
{
VST_CONNECT_HANDLE
h;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ENTERPRISE_ID
EnterpriseID;
VST_SOCKADDR_IN
SocketAddress;
VST_PROGRAM_NUMBER
ProgramNumber;
VST_VERSION_NUMBER
VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
VST_PROTOCOL Protocol;
/* create the handle */
h = VS_Connect_Create();
if (h != (VST_CONNECT_HANDLE) NULL)
{
/* get values from user */
printf(“*** connect handle
***\n”);
printf(“Enter enterprise ID ==>
“);
EnterpriseID = atol(gets(input));
printf(“Enter Internet sin_port
value ==> “);
SocketAddress.sin_port = (short)
atoi(gets(input));;
601355 Rev A
API Guide
37
38
39
40
41
42
43
44
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
601355 Rev A
API Functions
2-121
Functions
45
printf(“Enter Internet sin_family
value ==> “);
SocketAddress.sin_family =
(short)
atoi(gets(input));
printf(“Enter Internet sin_addr
value ==> “);
SocketAddress.sin_addr =
atol(gets(input));
printf(“Enter program number ==>
“);
ProgramNumber =
atol(gets(input));
printf(“Enter version number ==>
“);
VersionNumber =
atol(gets(input));
printf(“Enter procedure number
==> “);
ProcedureNumber =
atol(gets(input));
printf(“Enter Protocol ==> “);
Protocol = atol(gets(input));
/* set the fields */
rc = VS_Connect_SetFields(h,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
VSID_ENDFIELD);
if (rc)
{
vst_print_connect(h);
}
API Guide
62
63
64
65 }
VS_Connect_Destroy(h);
}
return(rc);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-122
API Functions
•
vsapi(l),
•
VS_Connect_Create(l),
•
VS_Connect_Destroy(l),
•
VS_Connect_GetFields(l),
•
VS_Error_GetFields(l),
•
VSCMD_Connect(l),
•
VSCMD_ConnectQuery(l),
•
VSCMD_Disconnect(l)
601355 Rev A
API Guide
VS_Criteria_
Create
VS_Criteria_Create allocates a VolServ API criteria
handle. A criteria handle is used to pass criteria information to
and from VolServ.
A criteria has three parts: the field number corresponding to a
media statistic, a sort order (ascending/descending), and a
group of expression handles.
Together, the group of expression commands form a single
criteria to test against media that have the given field number.
The criteria group handle uses criteria handles to build a
comparison function that uses more than one field numbers.
VST_CRITERIA_HANDLE VS_Criteria_Create
( void )
Arguments
None
Return Values
VS_Criteria_Create returns:
601355 Rev A
•
A criteria handle, if one can be allocated
•
NULL, if a criteria handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
API Functions
Functions
Synopsis
2-123
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2-124
API Functions
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle and sets the values in it
according to user
* input.
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
#else
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
#endif
{
int
i;
int
j;
int
numcrit;
int
numexpr;
VST_BOOLEAN
rc =
VSE_TRUE;
VST_EXPRESSION_HANDLE
exprh;
VST_CRITERIA_HANDLE
criteriah;
VST_CRITERIAGROUP_HANDLE
grouph;
VST_COUNT
field;
VST_MOUNT_CRITERIA_ORDER
sort;
VST_MEDIA_STAT_VALUE
value;
VST_MOUNT_CRITERIA_OPT
relopt;
VST_CONNECTIVE_OP
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
601355 Rev A
API Guide
35
36
37
38
39
40
41
42
43
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
601355 Rev A
/* populate the criteria group with
criteria (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
*/
/* stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
API Functions
2-125
Functions
44
45
46
47
48
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
API Guide
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
2-126
API Functions
VS_Criteria_SetFields (
criteriah,
VSID_FIELD, field,
VSID_MOUNT_CRITERIA_ORDER, sort
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (up to 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for this
criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
601355 Rev A
API Guide
95
96
97
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
98
99
100
101
102
103
104
105
106
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
}
107
108
109
110
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,
i, criteriah,
VSID_ENDFIELD );
111
112
113
114
115
116
117
118
119
120
121
601355 Rev A
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
API Functions
2-127
Functions
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
API Guide
122
VS_CriteriaGroup_Destroy ( grouph
);
123
124
125
126
127
128}
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
Notes
None
See Also
•
vsapi(l),
•
VS_Criteria_Delete(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Delete(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
2-128
API Functions
601355 Rev A
API Guide
VS_Criteria_
Destroy
VS_Criteria_Destroy deallocates a criteria handle that was
allocated with VS_Criteria_Create. A criteria handle is
Synopsis
VST_BOOLEAN VS_Criteria_Destroy
( VST_CRITERIA_HANDLE handle )
Arguments
•
Return Values
VS_Criteria_Destroy returns:
601355 Rev A
handle = Criteria handle to be destroyed.
•
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
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_criteria
4 *
5 * PURPOSE:
6 * This function creates the mount
criteria group
7 * handle and sets the values in it
according to user
8 *input.
9 *
10 * PARAMETERS:
11 * none
API Functions
2-129
Functions
Example
used to pass criteria information to and from VolServ.
API Guide
12 *
13 ****************************************
*********/
14 #ifdef ANSI_C
15
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
16 #else
17
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
18 #endif
19 {
20
int
i;
21
int
j;
22
int
numcrit;
23
int
numexpr;
24
VST_BOOLEAN
rc =
VSE_TRUE;
25
VST_EXPRESSION_HANDLE
exprh;
26
VST_CRITERIA_HANDLE
criteriah;
27
VST_CRITERIAGROUP_HANDLE
grouph;
28
VST_COUNT
field;
29
VST_MOUNT_CRITERIA_ORDER
sort;
30
VST_MEDIA_STAT_VALUE
value;
31
VST_MOUNT_CRITERIA_OPT
relopt;
32
VST_CONNECTIVE_OP
conop;
33
34
/* create the criteria group */
35
grouph = VS_CriteriaGroup_Create();
36
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
37
{
38
/* out of memory -- return */
39
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
40
}
41
/* populate the criteria group with
criteria */
42
/* (upto 5) */
43
printf ( “Enter number of Criteria in
group ==> “ );
2-130
API Functions
601355 Rev A
API Guide
44
45
46
47
48
49
50
51
52
53
54
55
56
57
61
62
63
64
65
66
67
68
69
70
71
72
601355 Rev A
API Functions
2-131
Functions
58
59
60
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==>“ );
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER,
sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
API Guide
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
93
94
95
96
97
2-132
API Functions
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
601355 Rev A
API Guide
98
99
100
101
102
103
104
105
106
107
108
110
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us, so the only thing that
is really */
/* needed here is a call to*/
/* VS_CriteriaGroup_Destroy. This
is written*/
/* out the ’long way’ for
documentation*/
/* purposes. First, get the number
of criteria */
111
112
113
114
115
116
117
118
119
120
VS_CriteriaGroup_GetFields(grouph
,
VSID_NUMBER_ENTRIES,
&numcrit,
VSID_ENDFIELD);
for (i = 0; i < numcrit; i++)
{
/* get a criteria handle */
VS_CriteriaGroup_GetFields(grouph
,
VSID_CRITERIA_HANDLE_ENTRY,
i, &criteriah,
VSID_ENDFIELD);
/* get the number of
expressions */
121
122
601355 Rev A
VS_Criteria_GetFields(criteriah,
VSID_NUMBER_ENTRIES,
&numexpr,
API Functions
2-133
Functions
109
VSID_CRITERIA_HANDLE_ENTRY,
i, criteriah,
VSID_ENDFIELD );
API Guide
123
124
125
126
VSID_ENDFIELD);
for (j = 0; j < numexpr; j++)
{
/* get the expressions from
the criteria */
127
VS_Criteria_GetFields(criteriah,
128
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
129
130
131
132
133
VSID_ENDFIELD);
/* destroy the expression
handle */
/*
VS_Expression_Destroy(exprh);*/
/* let criteria handle know
that the */
/* expression handle has
been destroyed */
134
VS_Criteria_SetFields(criteriah,
135
136
137
138
VSID_EXPRESSION_HANDLE_ENTRY, j,
NULL,
VSID_ENDFIELD);
}
/* now, destroy Criteria
handle. */
139
140
141
142
143
VS_Criteria_Destroy(criteriah);
/* let the criteria group
handle know */
/* that Criteria handle has
been */
/* destroyed. */
VS_CriteriaGroup_SetFields(grouph
,
144
145
2-134
API Functions
VSID_CRITERIA_HANDLE_ENTRY, i,
NULL,
VSID_ENDFIELD);
601355 Rev A
API Guide
146
147
148
149
150
151
152}
}
/* finally, destroy the criteria
group handle. */
VS_CriteriaGroup_Destroy ( grouph
);
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
After VS_Criteria_Destroy has been called for a criteria
handle, that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create,(l)
•
VS_Expression_Delete(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
Functions
Notes
API Functions
2-135
API Guide
VS_Criteria_
GetFields
VS_Criteria_GetFields retrieves information
associated with a criteria handle. A criteria group handle is used
to pass criteria information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Criteria_GetFields
( VST_CRITERIA_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Criteria 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 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.
Parameters
Parameter Type
Description
VSID_NUMBER_ENTRIES (VST_COUNT *)
Pointer to the number of expression handles
within this criteria handle.
VSID_FIELD (VST_COUNT *)
Pointer to the field number of the media
statistic for this criteria.
VSID_MOUNT_CRITERIA_ORDER
(VST_MOUNT_CRITERIA_ORDER*)
Pointer to the sort ordering for the media that
pass the given criteria expressions.
VSID_EXPRESSION_HANDLE_ENTRY (int)
Expression handle and its place in the criteria.
2-136
API Functions
601355 Rev A
API Guide
Parameter Type
Description
(VST_EXPRESSION_HANDLE *)
Return Values
VS_Criteria_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 a
criteria handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
10
11
12
13
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_print_criteria_group
*
* PURPOSE:
* This function prints out the
information stored in
* a criteria group handle.
*
* PARAMETERS:
* grouph : the mount handle to print
*
****************************************
*********/
#ifdef ANSI_C
API Functions
2-137
Functions
Example
Pointer to the expression handle and its place
in the criteria.
API Guide
14
void
vst_print_criteria_group
(VST_CRITERIAGROUP_HANDLE grouph)
15 #else
16
void
vst_print_criteria_group(grouph)
17
VST_CRITERIAGROUP_HANDLE grouph;
18 #endif
19 {
20
int
i, j;
21
int
numcrit =
0;
22
int
numexpr =
0;
23
24
VST_EXPRESSION_HANDLE
exprh =
(VST_EXPRESSION_HANDLE) NULL;
25
VST_CRITERIA_HANDLE
criteriah =
(VST_CRITERIA_HANDLE) NULL;
26
27
VST_COUNT
field;
28
VST_MOUNT_CRITERIA_ORDER
sort;
29
VST_MEDIA_STAT_VALUE
value;
30
VST_MOUNT_CRITERIA_OPT
relopt;
31
VST_CONNECTIVE_OP
conop;
32
33
/* get the number of criteria within
this group */
34
VS_CriteriaGroup_GetFields ( grouph,
35
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
36
37
for ( i = 0 ; i < numcrit ; i++ )
38
{
39
/* get the criteria to print */
40
VS_CriteriaGroup_GetFields (
grouph,
41
VSID_CRITERIA_HANDLE_ENTRY, i,
&criteriah,
42
VSID_ENDFIELD );
2-138
API Functions
601355 Rev A
API Guide
43
44
45
46
47
48
49
50
51
52
53
55
56
57
58
59
printf ( “*** Criteria # %d
***\n”, i );
printf ( “ Field Index ==> %d\n”,
field );
printf ( “ Mount Criteria Order
==> %d\n”, sort );
printf ( “Number of Expressions
==> %d\n”, numexpr );
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
VS_Criteria_GetFields (
criteriah,
60
61
62
63
64
65
66
67
601355 Rev A
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
VSID_ENDFIELD );
/* get the expression’s
parameters */
VS_Expression_GetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
API Functions
2-139
Functions
54
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
VSID_ENDFIELD );
API Guide
68
69
70
VSID_ENDFIELD );
printf ( “*** Expression # %d
***\n”, j );
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value );
printf ( “ Connective
Operation ==> %d\n”, conop );
}
71
72
73
74
75
76
77
78 }
Notes
}
return;
The VSID_EXPRESSION_HANDLE_ENTRY parameter requires
that two arguments be passed instead of one.
•
The first argument is the entry number in the criteria.
•
The second argument is Pointer to the location where the
value is stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-140
API Functions
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_SetFields(l),
•
VS_Error_Getfields(l),
•
VS_Expression_Create(l),
601355 Rev A
API Guide
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields (l),
•
VS_Expression_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VSCMD_Mount(l)
Functions
601355 Rev A
API Functions
2-141
API Guide
VS_Criteria_
SetFields
VS_Criteria_SetFields sets the value of one or more
field in a criteria handle. A criteria handle is used to pass
criteria information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Criteria_SetFields
( VST_CRITERIA_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Criteria 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.
Parameters
Parameter Type
Description
VSID_FIELD (VST_COUNT)
Field number of the media statistic for this
criteria.
VSID_MOUNT_CRITERIA_ORDER
(VST_MOUNT_CRITERIA_ORDER)
Sort ordering for the media that pass the given
criteria expressions.
VSID_EXPRESSION_HANDLE_ENTRY (int)
Expression handle and its place in the criteria.
(VST_EXPRESSION_HANDLE)
Expression handle for the criteria.
2-142
API Functions
601355 Rev A
API Guide
Return Values
•
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 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle and sets the values in it
according to
* user input.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
API Functions
2-143
Functions
Example
VS_Criteria_SetFields returns:
API Guide
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
2-144
API Functions
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
#else
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
#endif
{
int
i;
int
j;
int
numcrit;
int
numexpr;
VST_BOOLEAN
rc =
VSE_TRUE;
VST_EXPRESSION_HANDLE
exprh;
VST_CRITERIA_HANDLE
criteriah;
VST_CRITERIAGROUP_HANDLE
grouph;
VST_COUNT
field;
VST_MOUNT_CRITERIA_ORDER
sort;
VST_MEDIA_STAT_VALUE
value;
VST_MOUNT_CRITERIA_OPT
relopt;
VST_CONNECTIVE_OP
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
/* populate the criteria group with
criteria */
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
601355 Rev A
API Guide
48
49
50
51
52
53
54
55
56
57
58
59
60
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
601355 Rev A
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
VSID_FIELD, field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
API Functions
2-145
Functions
61
62
63
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
API Guide
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
2-146
API Functions
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
/* add the expression to the
criteria */
601355 Rev A
API Guide
106
VS_Criteria_SetFields (
criteriah,
107
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
}
108
109
110
111
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
112
113
118
119
120
121
122
123
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
124
125
126
127
128
129}
601355 Rev A
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
API Functions
2-147
Functions
114
115
116
117
API Guide
Notes
The VSID_EXPRESSION_HANDLE_ENTRY parameter requires
that two arguments be passed instead of one.
•
The first argument is the entry number in the criteria.
•
The second argument is Pointer to the location where the
value is stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-148
API Functions
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
API Guide
VS_
CriteriaGroup
_Create
VS_CriteriaGroup_Create allocates a VolServ API
criteria group handle. A criteria group handle is used to pass
criteria group information to and from VolServ.
Synopsis
VST_CRITERIAGROUP_HANDLE
VS_CriteriaGroup_Create
( void )
Arguments
None
Return Values
VS_CriteriaGroup_Create returns:
601355 Rev A
A criteria group handle, if one can be allocated.
•
NULL, if a criteria group handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_criteria
4 *
5 * PURPOSE:
6 * This function creates the mount
criteria group
7 * handle and sets the values in it
according to user
8 * input.
9 *
10 * PARAMETERS:
11 * none
12 *
API Functions
2-149
Functions
Example
•
API Guide
13 ****************************************
*********/
14 #ifdef ANSI_C
15
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
16 #else
17
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
18 #endif
19 {
20
int
i;
21
int
j;
22
int
numcrit;
23
int
numexpr;
24
VST_BOOLEAN
rc =
VSE_TRUE;
25
VST_EXPRESSION_HANDLE
exprh;
26
VST_CRITERIA_HANDLE
criteriah;
27
VST_CRITERIAGROUP_HANDLE
grouph;
28
VST_COUNT
field;
29
VST_MOUNT_CRITERIA_ORDER
sort;
30
VST_MEDIA_STAT_VALUE
value;
31
VST_MOUNT_CRITERIA_OPT
relopt;
32
VST_CONNECTIVE_OP
conop;
33
34
/* create the criteria group */
35
grouph = VS_CriteriaGroup_Create();
36
37
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
{
39
/* out of memory -- return */
40
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
41
}
42
43
/* populate the criteria group with
criteria */
44
/* (upto 5) */
2-150
API Functions
601355 Rev A
API Guide
45
46
47
48
49
50
51
52
53
61
62
63
64
65
66
67
68
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
69
70
71
72
73
74
75
601355 Rev A
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
API Functions
2-151
Functions
54
55
56
57
58
59
60
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
API Guide
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
2-152
API Functions
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
601355 Rev A
API Guide
104
105
106
VSID_ENDFIELD );
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
107
108
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
127
128
129
130}
601355 Rev A
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
API Functions
2-153
Functions
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
API Guide
Notes
A criteria group can hold up to five criteria handles.
A criteria group is used by the Mount and MultiMount
commands when a client specifies criteria to be used by
VolServ when selecting the medium or media to honor the
Mount/MultiMount request. Criteria groups applicable to a
Mount/MultiMount request can be specified either on the
command itself or in a Mount handle.
See Also
2-154
API Functions
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l), V
•
S_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VS_Mount_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
API Guide
VS_
CriteriaGroup
_Destroy
VS_CriteriaGroup_Destroy deallocates a criteria group
handle that was allocated with
VS_CriteriaGroup_Create. A criteria group handle is
used to pass criteria group information to and from VolServ.
Synopsis
VST_BOOLEAN VS_CriteriaGroup_Destroy
( VST_CRITERIAGROUP_HANDLE handle )
Arguments
•
Return Values
VS_CriteriaGroup_Destroy returns a criteria group
handle if one can be allocated.
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADHANDLE - Specified handle was not a
criteria group handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle and sets the values in it
according to
* user input.
API Functions
2-155
Functions
Example
handle = Criteria group handle to be destroyed.
API Guide
9
10
11
12
13
*
* PARAMETERS:
* none
*
****************************************
*********/
14 #ifdef ANSI_C
15
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
16 #else
17
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
18 #endif
19 {
20
int
i;
21
int
j;
22
int
numcrit;
23
int
numexpr;
24
VST_BOOLEAN
rc =
VSE_TRUE;
25
VST_EXPRESSION_HANDLE
exprh;
26
VST_CRITERIA_HANDLE
criteriah;
27
VST_CRITERIAGROUP_HANDLE
grouph;
28
VST_COUNT
field;
29
VST_MOUNT_CRITERIA_ORDER
sort;
30
VST_MEDIA_STAT_VALUE
value;
31
VST_MOUNT_CRITERIA_OPT
relopt;
32
VST_CONNECTIVE_OP
conop;
33
34
/* create the criteria group */
35
grouph = VS_CriteriaGroup_Create();
36
37
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
{
39
/* out of memory -- return */
40
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
41
}
42
2-156
API Functions
601355 Rev A
API Guide
43
44
45
46
47
48
49
50
51
52
53
61
62
63
64
65
66
67
68
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
69
70
71
72
73
601355 Rev A
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
API Functions
2-157
Functions
54
55
56
57
58
59
60
/* populate the criteria group with
criteria */
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
API Guide
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
2-158
API Functions
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
601355 Rev A
API Guide
102
VSID_CONNECTIVE_OP,
conop,
103
VSID_MEDIA_STAT_VALUE,
value,
104
105
106
VSID_ENDFIELD );
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
107
108
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
127
128
129
601355 Rev A
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
API Functions
2-159
Functions
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
API Guide
130}
Notes
After VS_CriteriaGroup_Destroy has been called for a
criteria group handle, that handle is no longer valid and should
not be used.
Destroying the CriteriaGroup handle automatically destroys the
underlying criteria and expressions.
See Also
2-160
API Functions
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
API Guide
VS_CriteriaGroup_GetFields retrieves information
associated with a criteria group handle. A criteria group handle
is used to pass criteria group information to and from VolServ.
Synopsis
VST_BOOLEAN VS_CriteriaGroup_GetFields
(VST_CRITERIAGROUP_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = Media 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 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.
Parameters
Parameter Type
Description
VSID_NUMBER_ENTRIES (VST_COUNT *)
Pointer to the number of criteria handles within
this criteria group handle.
VSID_CRITERIA_HANDLE_ENTRY (int)
Criteria handle and its place in the criteria
group.
(VST_CRITERIA_HANDLE *)
Pointer to Criteria handle for this group.
Return Values
601355 Rev A
VS_CriteriaGroup_GetFields returns:
API Functions
2-161
Functions
VS_
CriteriaGroup
_GetFields
API Guide
Example
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a
criteria group handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2-162
API Functions
/****************************************
*********
*
* FUNCTION: vst_print_criteria_group
*
* PURPOSE:
* This function prints out the
information stored in
* a criteria group handle.
*
* PARAMETERS:
* grouph : the mount handle to print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_criteria_group
(VST_CRITERIAGROUP_HANDLE grouph)
#else
void
vst_print_criteria_group(grouph)
VST_CRITERIAGROUP_HANDLE grouph;
#endif
{
int
i, j;
601355 Rev A
API Guide
21
int
numcrit =
0;
22
int
numexpr =
0;
23
24
VST_EXPRESSION_HANDLE exprh =
(VST_EXPRESSION_HANDLE) NULL;
VST_CRITERIA_HANDLE criteriah =
(VST_CRITERIA_HANDLE) NULL;
25
26
27
28
29
30
31
32
33
42
43
44
45
46
47
48
49
50
51
601355 Rev A
sort;
value;
relopt;
conop;
/* get the number of criteria within
this group */
VS_CriteriaGroup_GetFields ( grouph,
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
for ( i = 0 ; i < numcrit ; i++ )
{
/* get the criteria to print */
VS_CriteriaGroup_GetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
&criteriah,
VSID_ENDFIELD );
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
VSID_ENDFIELD );
API Functions
2-163
Functions
34
35
36
37
38
39
40
41
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
API Guide
52
printf ( “*** Criteria # %d
***\n”, i );
printf ( “ Field Index ==> %d\n”,
field );
printf ( “ Mount Criteria Order
==> %d\n”, sort );
printf ( “Number of Expressions
==> %d\n”, numexpr );
53
54
55
56
57
58
59
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
VS_Criteria_GetFields (
criteriah,
60
61
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
VSID_ENDFIELD );
62
63
64
/* get the expression’s
parameters */
VS_Expression_GetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
65
66
67
68
69
70
71
printf ( “*** Expression # %d
***\n”, j );
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value);
printf ( “ Connective
Operation ==> %d\n”, conop);
}
72
73
74
75
76
2-164
API Functions
}
601355 Rev A
API Guide
77
78
79 }
Notes
return;
The VSID_CRITERIA_HANDLE_ENTRY parameter requires
that two arguments be passed instead of one. The first argument
passed is the entry number in the criteria group table. The
second argument is a pointer to the location where the value is
stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
Functions
See Also
API Functions
2-165
API Guide
VS_
CriteriaGroup
_SetFields
VS_CriteriaGroup_SetFields sets the value of one or
more fields in a criteria group handle. A criteria group handle is
used to pass information to and from VolServ.
Synopsis
VST_BOOLEAN VS_CriteriaGroup_SetFields
( VST_CRITERIAGROUP_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Criteria group 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
valid parameter identifiers and types for this function 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.
Parameters
Parameter Type
Description
VSID_CRITERIA_HANDLE_ENTRY(int)
Criteria handle and its place in the criteria
group.
(VST_CRITERIA_HANDLE)
Criteria handle for this group.
2-166
API Functions
601355 Rev A
API Guide
Return Values
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a
criteria group 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle and sets the values in it
according to user
* input.
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
API Functions
2-167
Functions
Example
VS_CriteriaGroup_SetFields returns:
API Guide
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
2-168
API Functions
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
#else
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
#endif
{
int
i;
int
j;
int
numcrit;
int
numexpr;
VST_BOOLEAN
rc =
VSE_TRUE;
VST_EXPRESSION_HANDLE
exprh;
VST_CRITERIA_HANDLE
criteriah;
VST_CRITERIAGROUP_HANDLE
grouph;
VST_COUNT
field;
VST_MOUNT_CRITERIA_ORDER
sort;
VST_MEDIA_STAT_VALUE
value;
VST_MOUNT_CRITERIA_OPT
relopt;
VST_CONNECTIVE_OP
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
/* populate the criteria group with
criteria */
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
601355 Rev A
API Guide
47
48
49
50
51
52
53
54
55
56
57
58
59
63
64
65
66
67
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
68
69
70
71
72
73
74
75
76
77
601355 Rev A
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the criteria with
expressions */
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
API Functions
2-169
Functions
60
61
62
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
API Guide
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
2-170
API Functions
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
601355 Rev A
API Guide
105
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
106
107
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
108
109
110
111
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
112
113
118
119
120
121
122
123
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
124
125
126
127
128
129}
601355 Rev A
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
API Functions
2-171
Functions
114
115
116
117
API Guide
Notes
The VSID_CRITERIA_HANDLE_ENTRY parameter requires that
two arguments be passed instead of one. The first argument
passed is the entry number in the criteria group table. The
second argument is the value to be stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-172
API Functions
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
API Guide
VS_Drive_
Create
The VS_Drive_Create function allocates a VolServ API
drive handle. A drive handle is used to pass drive information to
and from VolServ.
Synopsis
VST_DRIVE_HANDLE VS_Drive_Create ( void )
Arguments
None
Return Values
VS_Drive_Create returns:
A drive handle, if one can be allocated.
•
NULL, if a drive handle cannot be allocated. An appropriate
error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_drive_handle
*
* PURPOSE:
* This function tests a drive handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_drive_handle(void)
#else
VST_BOOLEAN vst_drive_handle()
#endif
{
API Functions
2-173
Functions
Example
•
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
2-174
API Functions
VST_BOOLEAN
VST_DRIVE_HANDLE
VST_DRIVE_ID
VST_DRIVE_TYPE
VST_ARCHIVE_NAME
VST_COMP_STATE
VST_ASSIGNMENT
VST_MOUNT_STATE
VST_USAGE_COUNT
VST_USAGE
VST_USAGE
VST_COUNT
VST_MEDIA_ID
rc = VSE_FALSE;
h;
DriveID;
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
/* create the handle */
h = VS_Drive_Create();
if (h != (VST_DRIVE_HANDLE) NULL)
{
/* get values from user */
printf(“Enter Drive ID ==> “);
DriveID = atoi(gets(input));
printf(“Enter Drive Type ==> “);
DriveType = atoi(gets(input));
printf(“Enter Associated Archive
==> “);
gets(ArchiveName);
printf(“Enter Component State ==>
“);
ComponentState =
atoi(gets(input));
printf(“Enter Assignment ==> “);
Assignment = atoi(gets(input));
printf(“Enter Mount State ==> “);
MountState = atoi(gets(input));
printf(“Enter Usage Count ==> “);
UsageCount = atoi(gets(input));
printf(“Enter Current Usage Time
==> “);
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
TotalTime = atoi(gets(input));
601355 Rev A
API Guide
55
56
57
58
59
60
61
62
63
64
65
67
68
69
70
71
72
73
74
75
76
77
78
79
80 }
Notes
601355 Rev A
}
return(rc);
None
API Functions
2-175
Functions
66
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
VSID_DRIVE_TYPE,
DriveType,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_COMP_STATE,
ComponentState,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_STATE,
MountState,
VSID_USAGE_COUNT,
UsageCount,
VSID_USAGE_TIME,
CurrentTime,
VSID_TOTAL_USAGE_TIME,
TotalTime,
VSID_ERROR_COUNT,
ErrorCount,
VSID_MEDIA_ID,
MountedMediaID,
VSID_ENDFIELD);
if (rc)
{
vst_print_drive(h);
}
VS_Drive_Destroy(h);
API Guide
See Also
2-176
API Functions
•
vsapi(l),
•
VS_Drive_Destroy(l),
•
VS_Drive_GetFields(l),
•
VS_Drive_SetFields(l),
•
VS_Error_GetFields(l)
601355 Rev A
API Guide
VS_Drive_
Destroy
The VS_Drive_Destroy deallocates a drive handle that was
allocated with VS_Drive_Create. A drive handle is used to
pass drive information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Drive_Destroy
( VST_DRIVE_HANDLE handle )
Arguments
•
Return Values
VS_Drive_Destroy returns:
601355 Rev A
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_drive_handle
4 *
5 * PURPOSE:
6 * This function tests a drive handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
API Functions
2-177
Functions
Example
handle = Drive handle to be destroyed.
API Guide
13
VST_BOOLEAN vst_drive_handle(void)
14 #else
15
VST_BOOLEAN vst_drive_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc = VSE_FALSE;
19
VST_DRIVE_HANDLE
h;
20
VST_DRIVE_ID
DriveID;
21
VST_DRIVE_TYPE
DriveType;
22
VST_ARCHIVE_NAME
ArchiveName;
23
VST_COMP_STATE
ComponentState;
24
VST_ASSIGNMENT
Assignment;
25
VST_MOUNT_STATE
MountState;
26
VST_USAGE_COUNT
UsageCount;
27
VST_USAGE
CurrentTime;
28
VST_USAGE
TotalTime;
29
VST_COUNT
ErrorCount;
30
VST_MEDIA_ID
MountedMediaID;
31
32
/* create the handle */
33
h = VS_Drive_Create();
34
if (h != (VST_DRIVE_HANDLE) NULL)
35
{
36
/* get values from user */
37
printf(“Enter Drive ID ==> “);
38
DriveID = atoi(gets(input));
39
printf(“Enter Drive Type ==> “);
40
DriveType = atoi(gets(input));
41
printf(“Enter Associated Archive
==> “);
42
gets(ArchiveName);
43
printf(“Enter Component State ==>
“);
44
ComponentState =
atoi(gets(input));
45
printf(“Enter Assignment ==> “);
46
Assignment = atoi(gets(input));
47
printf(“Enter Mount State ==> “);
48
MountState = atoi(gets(input));
49
printf(“Enter Usage Count ==> “);
50
UsageCount = atoi(gets(input));
2-178
API Functions
601355 Rev A
API Guide
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
601355 Rev A
}
API Functions
2-179
Functions
printf(“Enter Current Usage Time
==> “);
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
TotalTime = atoi(gets(input));
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
VSID_DRIVE_TYPE,
DriveType,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_COMP_STATE,
ComponentState,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_STATE,
MountState,
VSID_USAGE_COUNT,
UsageCount,
VSID_USAGE_TIME,
CurrentTime,
VSID_TOTAL_USAGE_TIME,
TotalTime,
VSID_ERROR_COUNT,
ErrorCount,
VSID_MEDIA_ID,
MountedMediaID,
VSID_ENDFIELD);
if (rc)
{
vst_print_drive(h);
}
VS_Drive_Destroy(h);
API Guide
79
80 }
return(rc);
Notes
After VS_Drive_Destroy has been called for a drive handle,
that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Drive_Create(l),
•
VS_Drive_GetFields(l),
•
VS_Drive_SetFields(l),
•
VS_Error_GetFields(l)
2-180
API Functions
601355 Rev A
API Guide
VS_Drive_GetFields retrieves information associated
with a drive handle. A drive handle is used to pass drive
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Drive_GetFields
( VST_DRIVE_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Drive handle for which information is being
requested.
•
“…” = 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the name of the archive with which
this drive is associated. Valid archive names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_ASSIGNMENT (VST_ASSIGNMENT *)
Pointer to the current assignment of this drive.
Valid VSID_ASSIGNMENT values are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-181
Functions
VS_Drive_Get
Fields
API Guide
Parameter Type
Description
VSID_COMP_STATE (VST_COMP_STATE *)
Pointer to the operational state of this drive.
Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.
VSID_DRIVE_ID (VST_DRIVE_ID *)
Pointer to the identifier of this drive.
VSID_DRIVE_TYPE (VST_DRIVE_TYPE *)
Pointer to the type of this drive. Valid
VSID_DRIVE_TYPE values are enumerated
in the vs_types.h file.
VSID_ERROR_COUNT (VST_COUNT *)
Pointer to the error count of the drive.
VSID_MEDIA_ID (VST_MEDIA_ID)
If the VSID_MOUNT_STATE of this drive is
VSE_MOUNT_MOUNTED, identifier of the
medium mounted on this drive.
VSID_MEDIA_TYPE_ENTRY (int)
Index of a specific media type handle in the
media type handle table.
(VST_MEDIATYPE_HANDLE *)
Pointer to the location where the media type
handle should be stored.
VSID_MEDIA_TYPE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media types (in table format)
supported by this drive.
VSID_MOUNT_STATE
(VST_MOUNT_STATE *)
Pointer to the mount state of this drive. Valid
VSID_MOUNT_STATE values are enumerated
in the vs_types.h file.
VSID_NUMBER_MEDIA TYPES (int *)
Pointer to the number of media types present
in the media type name table.
VSID_USAGE_COUNT
(VST_USAGE_COUNT *)
Pointer to the number of times this drive has
been mounted.
VSID_USAGE_TIME (VST_USAGE *)
Pointer to the current usage time of the drive.
VSID_TOTAL_USAGE_TIME
(VST_USAGE *)
Pointer to the total usage time of the drive.
Return Values
2-182
API Functions
VS_Drive_GetFields returns:
601355 Rev A
API Guide
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
•
VSE_ERR_OUTOFRANGE - An index value was out of
range.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_print_drive
*
* PURPOSE:
* This function prints out the
information stored in
* a drive handle.
*
* PARAMETERS:
* h : the drive handle to print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_drive(VST_DRIVE_HANDLE
h)
#else
void vst_print_drive(h)
VST_DRIVE_HANDLE h;
#endif
{
API Functions
2-183
Functions
Example
•
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
2-184
API Functions
VST_DRIVE_ID
VST_DRIVE_TYPE
VST_ARCHIVE_NAME
VST_COMP_STATE
VST_ASSIGNMENT
VST_MOUNT_STATE
VST_USAGE_COUNT
VST_USAGE
VST_USAGE
VST_COUNT
VST_MEDIA_ID
char
VST_TABLE_HANDLE
int
int
DriveID;
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
* MediaType;
MediaTypeTable;
i;
n;
VS_Drive_GetFields(h,
VSID_DRIVE_ID,
&DriveID,
VSID_DRIVE_TYPE,
&DriveType,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_COMP_STATE,
&ComponentState,
VSID_ASSIGNMENT,
&Assignment,
VSID_MOUNT_STATE,
&MountState,
VSID_USAGE_COUNT,
&UsageCount,
VSID_USAGE_TIME,
&CurrentTime,
VSID_TOTAL_USAGE_TIME,
&TotalTime,
VSID_ERROR_COUNT,
&ErrorCount,
VSID_MEDIA_ID,
MountedMediaID,
VSID_MEDIA_TYPE_TABLE,
&MediaTypeTable,
VSID_ENDFIELD);
601355 Rev A
API Guide
50
51
52
53
54
55
56
57
60
61
62
/* DrivePoolQuery Doesn’t use this
Field */
if (MediaTypeTable !=
(VST_TABLE_HANDLE)NULL)
{
VS_Table_GetFields(MediaTypeTable
,
63
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
64
65
66
67
VS_Table_GetFields(MediaTypeTable
,
VSID_TABLE_ENTRY, i,
&MediaType,
VSID_ENDFIELD);
printf(“MediaType Entry #%d =
%s\n”,i,MediaType);
}
68
69
70
71
72
73 }
601355 Rev A
}
API Functions
2-185
Functions
58
59
printf(“******Drive
Handle******\n”);
printf(“Drive ID = %dDriveType =
%d\n”,DriveID,DriveType);
printf(“ArchiveName =
%s\n”,ArchiveName);
printf(“Comp State = %dAssignment =
%d\n”,ComponentState,Assignment);
printf(“Mount State = %dUsageCount =
%d\n”,MountState,UsageCount);
printf(“Current Usage = %dTotal
Usage = %d\n”, CurrentTime,
TotalTime);
printf(“Error Count = %d\n”,
ErrorCount );
printf(“MediaID =
%s\n”,MountedMediaID);
API Guide
Notes
VolServ may place a drive in the VSE_COMP_UNAVAIL state
when a parent component goes off-line.
The VSID_MEDIA_TYPE_ENTRY parameter requires that two
arguments be passed instead of one. The first argument passed
is the entry number in the drive table. The second argument is a
pointer to the location where the value is stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-186
API Functions
•
vsapi(l),
•
VS_Drive_Create(l),
•
VS_Drive_Destroy(l),
•
VS_Drive_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_GetFields(l),
•
VS_MediaType_SetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_DriveQuery(l),
•
VSCMD_DrivePoolQuery(l)
601355 Rev A
API Guide
VS_Drive_SetFields sets the value of one or more fields
in a drive handle. A drive handle is used to pass information to
and from VolServ.
Synopsis
VST_BOOLEAN VS_Drive_SetFields
( VST_DRIVE_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Drive 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Name of the archive with which this drive is
associated. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_ASSIGNMENT (VST_ASSIGNMENT)
Current assignment of this drive. Valid
VSID_ASSIGNMENT values are enumerated
in the vs_type.h file.
601355 Rev A
API Functions
2-187
Functions
VS_Drive_Set
Fields
API Guide
Parameter Type
Description
VSID_COMP_STATE (VST_COMP_STATE)
Operational state of this archive. Valid
VSID_COMP_STATE values are enumerated
in the vs_types.h file.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of this drive.
VSID_DRIVE_TYPE (VST_DRIVE_TYPE)
Type of this drive. Valid VSID_DRIVE_TYPE
values are enumerated in the vs_types.h
file.
VSID_ERROR_COUNT (VST_COUNT)
Error count of the drive.
VSID_MEDIA_ID (VST_MEDIA_ID)
If the VSID_MOUNT_STATE of this drive is
VSE_MOUNT_MOUNTED, the identifier of the
medium mounted on this drive.
VSID_MEDIA_TYPE_TABLE
(VST_TABLE_HANDLE)
Media types (in table format) supported by this
drive.
VSID_MOUNT_STATE
(VST_MOUNT_STATE)
Mount state of this drive. Valid
VSID_MOUNT_STATE values are enumerated
in the vs_types.h file.
VSID_USAGE_COUNT
(VST_USAGE_COUNT)
Number of times this drive has been mounted.
VSID_USAGE_TIME (VST_USAGE_TIME)
Current usage time of the drive.
VSID_TOTAL_USAGE_TIME (VST_USAGE)
Total usage time of the drive.
Return Values
2-188
API Functions
VS_Drive_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Guide
Example
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
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.
1
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
601355 Rev A
API Functions
2-189
Functions
2
3
4
5
6
7
8
9
10
11
/****************************************
*********
*
* FUNCTION: vst_drive_handle
*
* PURPOSE:
* This function tests a drive handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_drive_handle(void)
#else
VST_BOOLEAN vst_drive_handle()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_DRIVE_HANDLE
h;
VST_DRIVE_ID
DriveID;
VST_DRIVE_TYPE
DriveType;
VST_ARCHIVE_NAME
ArchiveName;
VST_COMP_STATE
ComponentState;
VST_ASSIGNMENT
Assignment;
VST_MOUNT_STATE
MountState;
VST_USAGE_COUNT
UsageCount;
API Guide
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
2-190
API Functions
VST_USAGE
VST_USAGE
VST_COUNT
VST_MEDIA_ID
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
/* create the handle */
h = VS_Drive_Create();
if (h != (VST_DRIVE_HANDLE) NULL)
{
/* get values from user */
printf(“Enter Drive ID ==> “);
DriveID = atoi(gets(input));
printf(“Enter Drive Type ==> “);
DriveType = atoi(gets(input));
printf(“Enter Associated Archive
==> “);
gets(ArchiveName);
printf(“Enter Component State ==>
“);
ComponentState =
atoi(gets(input));
printf(“Enter Assignment ==> “);
Assignment = atoi(gets(input));
printf(“Enter Mount State ==> “);
MountState = atoi(gets(input));
printf(“Enter Usage Count ==> “);
UsageCount = atoi(gets(input));
printf(“Enter Current Usage Time
==> “);
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
TotalTime = atoi(gets(input));
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
601355 Rev A
API Guide
62
63
64
65
66
67
68
69
70
72
73
74
75
76
77
78
79
80 }
Notes
Functions
71
VSID_DRIVE_TYPE,
DriveType,
VSID_ARCHIVE_NAME,
ArchiveName,
VSID_COMP_STATE,
ComponentState,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_STATE,
MountState,
VSID_USAGE_COUNT,
UsageCount,
VSID_USAGE_TIME,
CurrentTime,
VSID_TOTAL_USAGE_TIME,
TotalTime,
VSID_ERROR_COUNT,
ErrorCount,
VSID_MEDIA_ID,
MountedMediaID,
VSID_ENDFIELD);
if (rc)
{
vst_print_drive(h);
}
VS_Drive_Destroy(h);
}
return(rc);
VolServ may place a drive in the VSE_COMP_UNAVAIL state
when a parent component goes off-line. The
VSE_COMP_UNAVAIL state cannot be specified by the user.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-191
API Guide
See Also
2-192
API Functions
•
vsapi(l),
•
VS_Drive_Create(l),
•
VS_Drive_Destroy(l),
•
VS_Drive_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_GetFields(l),
•
VS_MediaType_SetFields(l),
•
VS_Table_GetFields(l)
601355 Rev A
API Guide
VS_DrivePool
_Create
VS_DrivePool_Create allocates a VolServ API drive pool
handle. A drive pool handle is used to pass drive pool
information to and from VolServ.
Synopsis
VST_DRIVEPOOL_HANDLE VS_DrivePool_Create
( void )
Arguments
None
Return Values
VS_DrivePool_Create returns:
A drive pool handle, if one can be allocated.
•
NULL, if a drive pool handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_drivepool_handle
*
* PURPOSE:
* This function tests a drive pool
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivepool_handle(void)
#else
API Functions
2-193
API Guide
15
16
17
18
19
20
VST_BOOLEAN
vst_drivepool_handle(void)
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_DRIVEPOOL_HANDLE
h;
VST_DRIVE_POOL_NAME
DrivePoolName;
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
Notes
2-194
/* create the handle */
h = VS_DrivePool_Create();
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
{
/* get values from user */
printf(“*** Drive Pool Handle
***\n”);
printf(“Enter Drive Pool Name ==>
“);
gets(DrivePoolName);
rc = VS_DrivePool_SetFields(h,
VSID_DRIVEPOOL_NAME,
DrivePoolName,
VSID_ENDFIELD);
if (rc)
{
vst_print_drivepool(h);
}
VS_DrivePool_Destroy(h);
}
return(rc);
None
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_DrivePool_Destroy(l),
•
VS_DrivePool_GetFields(l),
•
VS_DrivePool_SetFields(l),
•
VS_Error_GetFields(l)
Functions
601355 Rev A
API Functions
2-195
API Guide
VS_DrivePool
_Destroy
VS_DrivePool_Destroy deallocates a drive pool handle
that was allocated with VS_DrivePool_Create. A drive
pool handle is used to pass drive pool information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_DrivePool_Destroy
( VST_DRIVEPOOL_HANDLE handle )
Arguments
•
Return Values
VS_DrivePool_Destroy returns:
Example
2-196
handle = Drive pool handle to be destroyed.
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
pool handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_drivepool_handle
4 *
5 * PURPOSE:
6 * This function tests a drive pool
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-197
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivepool_handle(void)
14 #else
15
VST_BOOLEAN
vst_drivepool_handle(void)
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_DRIVEPOOL_HANDLE
h;
20
VST_DRIVE_POOL_NAME
DrivePoolName;
21
22
/* create the handle */
23
h = VS_DrivePool_Create();
24
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
25
{
26
/* get values from user */
27
printf(“*** Drive Pool Handle
***\n”);
28
printf(“Enter Drive Pool Name ==>
“);
29
gets(DrivePoolName);
30
rc = VS_DrivePool_SetFields(h,
31
VSID_DRIVEPOOL_NAME,
DrivePoolName,
32
VSID_ENDFIELD);
33
if (rc)
34
{
35
vst_print_drivepool(h);
36
}
37
VS_DrivePool_Destroy(h);
38
}
39
return(rc);
40 }
API Guide
Notes
After VS_DrivePool_Destroy has been called for a drive
pool handle, that handle is no longer valid and should not be
used.
See Also
•
vsapi(l),
•
VS_DrivePool_Create(l),
•
VS_DrivePool_GetFields(l),
•
VS_DrivePool_SetFields(l),
•
VS_Error_GetFields(l)
2-198
API Functions
601355 Rev A
API Guide
VS_DrivePool_GetFields retrieves information
associated with a drive pool handle. A drive pool handle is used
to pass drive pool information to and from VolServ.
Synopsis
VST_BOOLEAN VS_DrivePool_GetFields
( VST_DRIVEPOOL_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Drive pool handle for which 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.
Parameters
Parameter Type
Description
VSID_DRIVE_HANDLE_ENTRY (int)
Index of the drive handle to retrieve.
(VST_DRIVE_HANDLE *)
Pointer to the location to store the drive
handle.
VSID_DRIVE_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drives (in table format) that
belong to this drive pool group.
VSID_DRIVE_ID (VST_DRIVE_ID *)
Pointer to the first drive id in the drive handle
table.
601355 Rev A
API Functions
2-199
Functions
VS_DrivePool
_GetFields
API Guide
Parameter Type
Description
VSID_DRIVE_ID_Entry
(int, VST_DRIVE_ID *)
Index of the drive in the drive handle table.
Pointer to the location to store the drive
identifier.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Pointer to the name associated with the drive
pool group. Valid drive pool names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_NUMBER_DRIVE_HANDLES (int *)
Pointer to the number of drive handles in the
drive handle table.
Return Values
2-200
API Functions
VS_DrivePool_GetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
pool handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
•
VSE_ERR_OUTOFRANGE - An index value was out of
range.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
22
23
24
25
26
27
28
29
30
31
32
601355 Rev A
VS_DrivePool_GetFields(h,
VSID_DRIVEPOOL_NAME,
DrivePoolName,
VSID_DRIVE_HANDLE_TABLE
&DriveHandleTable,
VSID_ENDFIELD);
printf(“DrivePoolName =
%s\n”,DrivePoolName);
/* Get # of entries */
if ( DriveHandleTable !=
(VST_TABLE_HANDLE) NULL )
API Functions
2-201
Functions
15
16
17
18
19
20
21
/****************************************
*********
*
* FUNCTION: vst_print_drivepool
*
* PURPOSE:
* This function prints out the
information stored in
* in a drive pool handle.
*
* PARAMETERS:
* h : the drive pool handle to print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_drivepool(VST_DRIVEPOOL
_HANDLE h)
#else
void vst_print_drivepool(h)
VST_DRIVEPOOL_HANDLE h;
#endif
{
VST_DRIVE_POOL_NAME DrivePoolName;
VST_TABLE_HANDLE
DriveHandleTable;
VST_DRIVE_HANDLE
DriveHandle;
int
i;
int
n;
API Guide
33
34
{
VS_Table_GetFields(DriveHandleTab
le,
VSID_NUMBER_ENTRIES,
&n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
35
36
37
38
39
VS_Table_GetFields(DriveHandleTab
le,
VSID_TABLE_ENTRY, i,
&DriveHandle,
VSID_ENDFIELD);
vst_print_drive(DriveHandle);
}
40
41
42
43
44
45 }
Notes
}
The VSID_DRIVE_HANDLE_ENTRY parameter requires that
two arguments be passed instead of one. The first argument
passed is the entry number in the drive pool table. The second
argument is a pointer to the location where the value is stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-202
API Functions
•
vsapi(l),
•
VS_DrivePool_Create(l),
•
VS_DrivePool_Destroy(l),
•
VS_DrivePool_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Table_GetFields(l)
601355 Rev A
API Guide
•
VSCMD_DrivePoolQuery(l)
Functions
601355 Rev A
API Functions
2-203
API Guide
VS_DrivePool
_SetFields
VS_DrivePool_SetFields sets the value of one or more
fields in a drive pool handle. A drive pool handle is used to pass
drive pool information to and from VolServ.
Synopsis
VST_BOOLEAN VS_DrivePool_SetFields
( VST_DRIVEPOOL_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = Drive pool 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.
Parameters
Parameter Type
Description
VSID_DRIVE_HANDLE_TABLE
(VST_TABLE_HANDLE)
Drive handles (in table format) that belong to
this drive pool group.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Name associated with the drive pool group.
Valid drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
Return Values
2-204
API Functions
VS_DrivePool_SetFields returns:
601355 Rev A
API Guide
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a drive
pool 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_drivepool_handle
*
* PURPOSE:
* This function tests a drive pool
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivepool_handle(void)
#else
VST_BOOLEAN
vst_drivepool_handle(void)
API Functions
2-205
Functions
Example
•
API Guide
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_DRIVEPOOL_HANDLE
h;
20
VST_DRIVE_POOL_NAME
DrivePoolName;
21
22
/* create the handle */
23
h = VS_DrivePool_Create();
24
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
25
{
26
/* get values from user */
27
printf(“*** Drive Pool Handle
***\n”);
28
printf(“Enter Drive Pool Name ==>
“);
29
gets(DrivePoolName);
30
rc = VS_DrivePool_SetFields(h,
31
VSID_DRIVEPOOL_NAME,
DrivePoolName,
32
VSID_ENDFIELD);
33
if (rc)
34
{
35
vst_print_drivepool(h);
36
}
37
VS_DrivePool_Destroy(h);
38
}
39
return(rc);
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-206
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_DrivePool_Create(l),
•
VS_DrivePool_Destroy(l),
•
VS_DrivePool_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Table_Getfields(l)
Functions
601355 Rev A
API Functions
2-207
API Guide
VS_Error_Get
Fields
VS_Error_GetFields retrieves information associated
with an error handle. An error handle is used to pass error
information to and from VolServ.
An error handle is associated with each command handle and
with each notify handle. There is also a global error handle for
errors that cannot be associated with a command.
After a VolServ request or an attempt to receive callbacks fails,
information is stored in an error handle.
VS_Error_GetFields allows the user to retrieve this
information.
Synopsis
VST_BOOLEAN VS_Error_GetFields
( VST_ERROR_HANDLE handle,
"…",
VSID_ENDFIELD )
Arguments
•
handle = The error 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.
2-208
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
VSID_ERROR_CODE (VST_ERROR_CODE)
Pointer to the error code for the given error.
VSID_ERROR_FILE (VST_ERROR_FILE)
Name of the source file where the error
occurred (API internal errors only).
VSID_ERROR_LINE (int *)
Pointer to the source line number where the
error occurred (API internal errors only).
VSID_ERROR_NUMBER
(VST_ERROR_NUMCODE *)
Pointer to the field that indicates which error
occurred.
VSID_ERROR_OBJECT
(VST_ERROR_OBJCODE *)
Pointer to the field that indicates the location
of the error.
Example
VS_Error_GetFields returns
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not an
error handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
601355 Rev A
Functions
Return Values
/****************************************
*********
*
* FUNCTION: vst_print_error
*
* PURPOSE:
API Functions
2-209
API Guide
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
* This function prints out the
information stored in
* an error handle.
*
* PARAMETERS:
* h : the error handle to print
*
****************************************
**********/
#ifdef ANSI_C
void
vst_print_error(VST_ERROR_HANDLE
h)
#else
void vst_print_error(h)
VST_ERROR_HANDLE h;
#endif
{
VST_ERROR_CODE
err;
int
line;
VST_ERROR_FILE
file;
26
27
28
29
30
31
32
33
34 }
2-210
API Functions
VS_Error_GetFields(h,
VSID_ERROR_CODE,
err,
VSID_ERROR_LINE,
&line,
VSID_ERROR_FILE,
file,
VSID_ENDFIELD);
printf(“******Error
Handle******\n”);
printf(“Error Code = %s\n”,err);
printf(“Error File = %s\n”,file);
printf(“Error Line = %d\n”,line);
601355 Rev A
API Guide
Notes
The VSID_ERROR_OBJECT parameter tells specifically where
(in VolServ or an API object) the error occurred. If its value is
VSE_VOLSERV, the VSID_ERROR_NUMBER parameter matches
a VolServ error code in the VST_VOLERR_CODE error code. If
not, the VSID_ERROR_NUMBER parameter matches a value in
the VST_ERROR_NUMCODE type.
The VSID_ERROR_FILE and VSID_ERROR_LINE parameters
are valid only for API internal errors (e.g.,
VSE_ERR_OUTOFMEM).
If the string parameters are not sufficiently long, unpredictable
results occur.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Command_GetFields(l),
•
VS_Notify_GetFields(l)
API Functions
2-211
Functions
The VSID_ERROR_CODE parameter is a human-readable code
that tells where the error occurred and gives the error number. It
is in the form AAAnnn, where AAA is an abbreviation that
corresponds with the VST_ERROR_OBJCODE type. If this
abbreviation is VOL, the error number is a VolServ error code.
Otherwise, it is in the VST_ERROR_NUMCODE type.
API Guide
VS_
Expression_
Create
VS_Expression_Create allocates a VolServ API
expression handle. An expression handle is used to pass
expression information to and from VolServ.
An expression handle has three parts: a relation operator (=, >,
<, >=, <=, <>), a connective option (and/or/none), and a
comparison value. A criteria handle uses expression handles to
build the comparison function when using mount-by-selection
criteria.
Synopsis
VST_EXPRESSION_HANDLE VS_Expression_Create
( void )
Arguments
•
Return Values
VS_Expression_Create returns:
Example
handle = The expression handle to be created.
•
An expression handle, if one can be allocated.
•
NULL, if the expression handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
2-212
API Functions
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle and sets the values in it
according to
* user input.
601355 Rev A
API Guide
9
10
11
12
13
14
15
16
17
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
601355 Rev A
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
API Functions
2-213
Functions
18
19
20
21
22
23
24
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
#else
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
#endif
{
int
i;
int
j;
int
numcrit;
int
numexpr;
VST_BOOLEAN
rc =
VSE_TRUE;
VST_EXPRESSION_HANDLE
exprh;
VST_CRITERIA_HANDLE
criteriah;
VST_CRITERIAGROUP_HANDLE
grouph;
VST_COUNT
field;
VST_MOUNT_CRITERIA_ORDER
sort;
VST_MEDIA_STAT_VALUE
value;
VST_MOUNT_CRITERIA_OPT
relopt;
VST_CONNECTIVE_OP
conop;
API Guide
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
/* populate the criteria group with
criteria */
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
69
70
71
72
73
2-214
API Functions
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
601355 Rev A
API Guide
74
75
76
77
78
79
80
81
82
83
84
91
92
93
94
95
96
97
98
99
100
101
601355 Rev A
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
API Functions
2-215
Functions
85
86
87
88
89
90
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
API Guide
102
VSID_CONNECTIVE_OP,
conop,
103
VSID_MEDIA_STAT_VALUE,
value,
104
105
106
VSID_ENDFIELD );
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
107
108
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
109
110
111
112
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
113
114
115
116
117
118
119
120
121
122
123
124
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
127
128
129
2-216
API Functions
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
601355 Rev A
API Guide
130}
None
See Also
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
Functions
Notes
API Functions
2-217
API Guide
VS_
Expression_
Destroy
VS_Expression_Destroy deallocates an expression
handle that was allocated with VS_Expression_Create.
An expression handle is used to pass expression information to
and from VolServ.
Synopsis
VST_BOOLEAN VS_EXPRESSION_DESTROY
(VST_EXPRESSION_HANDLE handle)
Arguments
•
Return Values
VS_Expression_Destroy returns:
Example
handle = The expression handle to be destroyed.
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADHANDLE - Specified handle was not an
expression handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
2-218
API Functions
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group handle
* and sets the values in it according to
user input.
*
* PARAMETERS:
601355 Rev A
API Guide
601355 Rev A
API Functions
2-219
Functions
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
15 #else
16
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
17 #endif
18 {
19
int
i;
20
int
j;
21
int
numcrit;
22
int
numexpr;
23
VST_BOOLEAN
rc =
VSE_TRUE;
24
VST_EXPRESSION_HANDLE
exprh;
25
VST_CRITERIA_HANDLE
criteriah;
26
VST_CRITERIAGROUP_HANDLE
grouph;
27
VST_COUNT
field;
28
VST_MOUNT_CRITERIA_ORDER
sort;
29
VST_MEDIA_STAT_VALUE
value;
30
VST_MOUNT_CRITERIA_OPT
relopt;
31
VST_CONNECTIVE_OP
conop;
32
33
/* create the criteria group */
34
grouph = VS_CriteriaGroup_Create();
35
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
36
{
37
/* out of memory -- return */
38
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
39
}
40
/* populate the criteria group with
criteria */
41
/* (upto 5) */
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==>“ );
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
61
62
63
64
65
66
67
68
69
70
2-220
API Functions
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
601355 Rev A
API Guide
71
72
73
74
75
76
77
78
79
80
81
82
85
86
87
88
89
90
91
92
93
94
95
601355 Rev A
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
API Functions
2-221
Functions
83
84
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
API Guide
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us, so the only thing that
is really */
/* needed here is a call to */
/* VS_CriteriaGroup_Destroy. */
/* This is written out the ’long
way’ for */
/* documentation purposes. First,
get the */
/* number of criteria */
VS_CriteriaGroup_GetFields(grouph
,
VSID_NUMBER_ENTRIES,
&numcrit,
VSID_ENDFIELD);
for (i = 0; i < numcrit; i++)
{
/* get a criteria handle */
VS_CriteriaGroup_GetFields(grouph
,
VSID_CRITERIA_HANDLE_ENTRY,
i, &criteriah,
VSID_ENDFIELD);
/* get the number of
expressions */
121
VS_Criteria_GetFields(criteriah,
2-222
API Functions
601355 Rev A
API Guide
122
123
124
125
126
VSID_NUMBER_ENTRIES,
&numexpr,
VSID_ENDFIELD);
for (j = 0; j < numexpr; j++)
{
/* get the expressions from
the criteria */
127
VS_Criteria_GetFields(criteriah,
128
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
129
130
VSID_ENDFIELD);
/* destroy the expression
handle */
131
133
VS_Expression_Destroy(exprh);
/* let Criteria handle know
that the */
/* expression handle has
been destroyed */
134
VS_Criteria_SetFields(criteriah,
135
136
137
138
VSID_EXPRESSION_HANDLE_ENTRY, j,
NULL,
VSID_ENDFIELD);
}
/* now, destroy Criteria
handle. */
139
140
141
142
143
144
601355 Rev A
VS_Criteria_Destroy(criteriah);
/*let the criteria group handle
know */
/* that Criteria handle has
been */
/* destroyed. */
VS_CriteriaGroup_SetFields(grouph
,
VSID_CRITERIA_HANDLE_ENTRY,
i, NULL,
API Functions
2-223
Functions
132
API Guide
145
146
147
148
149
150
151
152}
VSID_ENDFIELD);
}
/* finally, destroy the criteria
group handle. */
VS_CriteriaGroup_Destroy ( grouph
);
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
return ( grouph );
Notes
After VS_Expression_Destroy has been called for an
expression handle, that handle is no longer valid and should not
be used.
See Also
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l)
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_GetFields(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
2-224
API Functions
601355 Rev A
API Guide
VS_Expression_GetFields retrieves information
associated with an expression handle. An expression handle is
used to pass expression information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Expression_GetFields
( VST_EXPRESSION_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = The expression 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.
Parameters
Parameter Type
VSID_MOUNT_CRITERIA_OP
(VST_MOUNT_CRITERIA_OPT *)
601355 Rev A
Description
Pointer to the relational operation for this
expression:
API Functions
2-225
Functions
VS_
Expression_
GetFields
API Guide
Parameter Type
Description
VSID_CONNECTIVE_OP
(VST_CONNECTIVE_OP *)
Pointer to the connective operation between
two expressions. Valid
VS_Expression_GetFields values are
enumerated in the vs_types.h file. The last
expression in a criteria must have the connect
operator set to none.
VSID_MEDIA_STAT_VALUE
(VST_MEDIA_STAT_VALUE)
Value for comparison. All values are
compared as strings. If numbers are needed,
they must be left filled with zeros within the
string.
Return Values
Example
VS_Expression_GetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not an
error handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
2-226
API Functions
/****************************************
*********
*
* FUNCTION: vst_print_criteria_group
*
* PURPOSE:
* This function prints out the
information stored in
* a criteria group handle.
*
601355 Rev A
API Guide
9
10
11
12
13
14
15
16
17
18
19
20
21
23
24
VST_EXPRESSION_HANDLE exprh =
(VST_EXPRESSION_HANDLE) NULL;
VST_CRITERIA_HANDLE criteriah =
(VST_CRITERIA_HANDLE) NULL;
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
601355 Rev A
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
sort;
value;
relopt;
conop;
/* get the number of criteria within
this group */
VS_CriteriaGroup_GetFields ( grouph,
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
for ( i = 0 ; i < numcrit ; i++ )
{
/* get the criteria to print */
API Functions
2-227
Functions
22
* PARAMETERS:
* grouph : the mount handle to print
*
****************************************
*********/
#ifdef ANSI_C
void
vst_print_criteria_group(VST_CRIT
ERIAGROUP_HANDLE grouph)
#else
void
vst_print_criteria_group(grouph)
VST_CRITERIAGROUP_HANDLE grouph;
#endif
{
int
i, j;
int
numcrit =
0;
int
numexpr =
0;
API Guide
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
VS_CriteriaGroup_GetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
&criteriah,
VSID_ENDFIELD );
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
VSID_ENDFIELD );
printf ( “*** Criteria # %d
***\n”, i );
printf ( “ Field Index ==> %d\n”,
field );
printf ( “ Mount Criteria Order
==> %d\n”, sort );
printf ( “Number of Expressions
==> %d\n”, numexpr );
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
VS_Criteria_GetFields (
criteriah,
61
62
63
64
65
2-228
API Functions
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
VSID_ENDFIELD );
/* get the expression’s
parameters */
VS_Expression_GetFields (
exprh,
601355 Rev A
API Guide
66
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
67
68
69
70
71
printf ( “*** Expression # %d
***\n”, j );
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value);
printf ( “ Connective
Operation ==> %d\n”, conop);
}
72
73
74
}
Functions
75
76
77
78
79 }
return;
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
API Functions
2-229
API Guide
2-230
API Functions
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Expression_Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_SetFields(l),
•
VSCMD_Mount(l)
601355 Rev A
API Guide
VS_Expression_SetFields sets the value of one or more
fields in an expression handle. An expression handle is used to
pass information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Expression_SetFields
( VST_EXPRESSION_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = The expression 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.
Parameters
Parameter Type
Description
VSID_MOUNT_CRITERIA_OP
(VST_MOUNT_CRITERIA_OPT)
Relational operation for this expression:
VSID_CONNECTIVE_OP
(VST_CONNECTIVE_OP)
Connective operation between two
expressions. Valid VSID_CONNECTIVE_OP
values are enumerated in the vs_types.h
file. The last expression in a criteria must have
the connect operator set to NONE.
601355 Rev A
API Functions
2-231
Functions
VS_
Expression_
SetFields
API Guide
Parameter Type
Description
VSID_MEDIA_STAT_VALUE
(VST_MEDIA_STAT_VALUE)
Return Values
Example
Value for comparison. All values are
compared as strings. If numbers are needed,
they are left filled with zeros within the string.
VS_Expression_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not an
expression 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.
1
2
3
4
5
6
7
2-232
API Functions
/****************************************
*********
*
* FUNCTION: vst_create_mount_criteria
*
* PURPOSE:
* This function creates the mount
criteria group
* handle andsets the values in it
according to
601355 Rev A
API Guide
8
9
10
11
12
13
14
15
16
17
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
601355 Rev A
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
API Functions
2-233
Functions
18
19
20
21
22
23
24
* user input.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
#else
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
#endif
{
int
i;
int
j;
int
numcrit;
int
numexpr;
VST_BOOLEAN
rc =
VSE_TRUE;
VST_EXPRESSION_HANDLE
exprh;
VST_CRITERIA_HANDLE
criteriah;
VST_CRITERIAGROUP_HANDLE
grouph;
VST_COUNT
field;
VST_MOUNT_CRITERIA_ORDER
sort;
VST_MEDIA_STAT_VALUE
value;
VST_MOUNT_CRITERIA_OPT
relopt;
VST_CONNECTIVE_OP
conop;
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
/* populate the criteria group with
criteria */
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
VSID_FIELD,
field,
69
70
71
72
2-234
API Functions
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
601355 Rev A
API Guide
73
74
75
76
77
78
79
80
81
82
83
84
85
92
93
94
95
96
97
98
99
100
101
601355 Rev A
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this */
/* criteria */
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
conop = atoi(gets(input));
/* set the expression’s
parameters */
VS_Expression_SetFields (
exprh,
API Functions
2-235
Functions
86
87
88
89
90
91
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
API Guide
102
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
VSID_ENDFIELD );
103
104
105
106
107
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
108
109
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
VSID_ENDFIELD );
110
111
112
113
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY, i,
criteriah,
VSID_ENDFIELD );
114
115
116
117
118
119
120
121
122
123
124
125
}
/* if it failed, destroy the criteria
group handle */
if ( rc == VSE_FALSE )
{
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
126
127
128
2-236
API Functions
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
}
601355 Rev A
API Guide
129
130
131}
return ( grouph );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l), VS_Criteria_Create(l),
•
VS_Criteria_Destroy(l),
•
VS_Criteria_GetFields(l),
•
VS_Criteria_SetFields(l),
•
VS_CriteriaGroup_Create(l),
•
VS_CriteriaGroup_Destroy(l),
•
VS_CriteriaGroup_GetFields(l),
•
VS_CriteriaGroup_SetFields(l),
•
VS_Expression__Create(l),
•
VS_Expression_Destroy(l),
•
VS_Expression_GetFields(l),
•
VSCMD_Mount(l).
Functions
601355 Rev A
•
API Functions
2-237
API Guide
VS_Global_
GetFields
VS_Global_GetFields retrieves global default parameters
for all commands. A global handle is used to maintain global
default parameter values for VolServ commands.
Tip
Global defaults can be overridden by command-level specific
defaults. Command-specific defaults, in turn, can be
overridden by parameter values specified in an actual
command’s parameter list.
Synopsis
VST_BOOLEAN VS_Global_GetFields
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = 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.
2-238
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Pointer to the RPC program number to use for
asynchronous processing.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH *)
Pointer to the dispatch function for all
commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the identifier of the enterprise, if any,
to receive intermediate and final status on
every command request.
VSID_INIT (int *)
Pointer to a flag that indicates whether the API
is initialized. The value is VSE_TRUE if the API
is initialized and VSE_FALSE otherwise.
VSID_NOTIFY_DISPATCH
(VST_NOTIFY_DISPATCH *)
Pointer to the dispatch function used for
notification (MediaClass callback) processing.
VSID_PRIORITY (VST_PRIORITY *)
Pointer to the default execution priority to be
assigned to every command request. Default
priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT *)
Pointer to the default number of times the API
software retries for command status from
VolServ before returning a time-out to the
client software for every command request.
Total length of time the API software waits for
a command status from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. Default value is 3.
601355 Rev A
API Functions
2-239
Functions
VSID_ASYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG*)
Pointer to a flag that indicates whether the API
software is to wait for final status from VolServ
(or to time-out) for a request. Valid options are
VSE_TRUE (API is to wait for final status) and
VSE_FALSE (API is not to wait for final status).
Also determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE).
Default value is VSE_TRUE.
VSID_SYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
Pointer to the RPC program number to use for
synchronous processing.
VSID_TIMEOUT_VALUE (VST_TIME_OUT *)
Pointer to the amount of time (in seconds) the
API software is to wait for status from VolServ
before returning a time-out to the client
software. Default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Pointer to the default value to be placed in the
VSID_USER_FIELD for every command
request. USER_FIELD is 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.
Return Values
2-240
API Functions
VS_Global_GetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
26
27
28
29
30
31
32
601355 Rev A
VS_Global_GetFields(VSID_PRIORITY,
&priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
&timeout,
VSID_RETRY_LIMIT,
&retries,
VSID_STATUS_WAIT_FLAG,
&wait,
VSID_ENTERPRISE_ID,
&enterprise,
VSID_ENDFIELD);
printf(“*** Global Parameters
***\n”);
API Functions
2-241
Functions
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/****************************************
*********
*
* FUNCTION: vst_show_globals
*
* PURPOSE:
* This function allows the user to
display the
* VolServ API’s global parameters.
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_show_globals( void )
#else
VST_BOOLEAN vst_show_globals()
#endif
{
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait;
VST_ENTERPRISE_ID
enterprise;
API Guide
33
34
35
printf(“Priority = %d User field =
[%s]\n”, priority, user_field);
printf(“Time out value = %d Retry
count = %d\n”, timeout, retries);
printf(“Status wait = %d Enterprise =
%lu\n”, wait, enterprise);
36 }
Notes
If a string that is passed to hold the user field does not have
enough space allocated, unpredictable results may occur.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-242
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Select(l)
601355 Rev A
API Guide
VS_Global_
SetFields
VS_Global_SetFields sets the value of one or more fields
in a global handle. A global handle is used to maintain global
default parameter values for VolServ commands.
Tip
Global defaults can be overridden by command-level specific
defaults. Command-specific defaults, in turn, can be
overridden by parameter values specified in an actual
command’s parameter list.
VST_BOOLEAN VS_Global_SetFields
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = 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.
601355 Rev A
API Functions
2-243
Functions
Synopsis
API Guide
Parameters
Parameter Type
Description
VSID_ASYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number to use for
asynchronous processing. If not specified or
0, the API uses a transient number. Default
value is 0.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Dispatch function for all commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on every
command request.
VSID_NOTIFY_DISPATCH
(VST_NOTIFY_DISPATCH)
Pointer to the dispatch function used for
notification (MediaClass callback) processing.
VSID_PRIORITY (VST_PRIORITY)
Default execution priority to be assigned to
every command. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. Default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Default number of times the API software is to
retry for command status from VolServ before
returning a time-out to the client software for
every command request.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. Default value is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software is to
wait for final status from VolServ (or to
time-out) for a command. Valid options are
VSE_TRUE (API is to wait for final status) and
VSE_FALSE (API is not to wait for final status).
Also determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE).
Default value is VSE_TRUE.
2-244
API Functions
601355 Rev A
API Guide
Parameter Type
Description
RPC program number to use for synchronous
processing. If not specified or 0, the API uses
a transient number. Default value is 0.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. Default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Pointer to the default value to be put in the
VSID_USER_FIELD for every command.
USER_FIELD is 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.
Return Values
601355 Rev A
VS_Global_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADHANDLE - Specified handle was not an
expression 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.
API Functions
2-245
Functions
VSID_SYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2-246
API Functions
/****************************************
*********
*
* FUNCTION: vst_set_globals
*
* PURPOSE:
* This function allows the user to set
VolServ API’s
* global parameters.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_set_globals( void )
#else
VST_BOOLEAN vst_set_globals()
#endif
{
VST_PRIORITY priority;
VST_USER_FIELD user_field;
VST_TIME_OUT timeout;
VST_RETRY_LIMIT retries;
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID enterprise_id;
VST_BOOLEAN rc;
printf(“*** Set Global Parameters
***\n\n”);
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
rc =
VS_Global_SetFields(VSID_PRIORITY
, priority,
601355 Rev A
API Guide
30
31
32
33
34
35
36
37 }
Notes
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return (rc);
This function can be called before VS_Initialize. To set the
SYNC/ASYNC program numbers, this function must be called
before VS_Initialize.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_GetFields(l),
•
VS_Select(l),
API Functions
2-247
Functions
Total length of time the API software waits for a command
status from VolServ is (VSID_RETRY_LIMIT plus 1)
multiplied by VSID_TIMEOUT_VALUE.
API Guide
•
2-248
API Functions
VS_Initialize(l)
601355 Rev A
API Guide
VS_Initialize
VS_Initialize readies the VolServ API library for use by
the client software.
VS_Initialize creates and registers RPC transports for
receiving VolServ status messages and also performs
initialization processing required by other API functions.
VS_Initialize must be called before any API command
functions are called.
VST_BOOLEAN VS_Initialize
( VST_HOSTNAME hostname,
VST_PROGRAM_NUMBER prognum,
int time-out )
Arguments
•
hostname = Name of the computer running VolServ.
-
•
601355 Rev A
If NULL is specified, hostname defaults to the current
host machine.
prognum = Program number on which VolServ is
registered.
-
•
Functions
Synopsis
If 0 is specified, prognum defaults to 300016 - the
VolServ default.
timeout = Amount of time, in seconds, to wait for an
initial status from VolServ before timing out.
API Functions
2-249
API Guide
Return Values
Example
VS_Initialize returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - The appropriate error code is
set in VSG_Error.
•
VSE_ERR_INITIALIZED - VolServ API is already
initialized.
•
VSE_ERR_OUTOFMEM - Memory allocation call failed.
•
VSE_ERR_PMAPFAILED - RPC registration for return
status failed. RPC address specified could not be registered
with the local machine’s port mapper.
•
VSE_ERR_SYSTEMCALL - A system call failed (usually
from RPC). This generic error code covers an error that
stems from a system call. The API sets this error code when
encountering a failure during RPC setup.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2-250
API Functions
/****************************************
*********
*
* FUNCTION: vst_initialize
*
* PURPOSE:
* This function initializes the VolServ
API.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_initialize(void)
#else
VST_BOOLEAN vst_initialize()
#endif
{
601355 Rev A
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
601355 Rev A
timeout;
host;
prognum;
syncnum;
asyncnum;
rc = VSE_FALSE;
/* get parameters from user */
printf(“*** Initialize parameters
***\n” );
printf(“Enter VolServ Host ==> “ );
gets( host );
printf(“Enter VolServ Program Number
==> “ );
prognum = atol(gets(input));
printf(“Enter Timeout Value ==> “ );
timeout = atoi(gets(input));
/* change the sync/async program
numbers */
printf(“*** RPC Program numbers
***\n” );
printf(“Enter Sync Program Number (0
for default) ==> “ );
syncnum = atol(gets(input));
printf(“Enter Async Program Number (0
for default) ==> “ );
asyncnum = atol(gets(input));
if ( syncnum != 0 )
{
VS_Global_SetFields (
VSID_SYNC_PROGRAM_NUMBER,
syncnum,
VSID_ENDFIELD );
}
if ( asyncnum != 0 )
{
VS_Global_SetFields (
API Functions
2-251
Functions
30
31
32
33
34
int
VST_HOSTNAME
VST_PROGRAM_NUMBER
VST_PROGRAM_NUMBER
VST_PROGRAM_NUMBER
VST_BOOLEAN
API Guide
51
52
53
54
55
56 }
Notes
VSID_ASYNC_PROGRAM_NUMBER,
asyncnum,
VSID_ENDFIELD );
}
rc = VS_Initialize(host, prognum,
timeout);
return(rc);
VS_Global_SetDefaults must be called before
VS_Initialize is called to set the SYNC/ASYNC program
numbers.
All command functions fail if VS_Initialize is not invoked.
VS_Initialize does not verify that VolServ is currently
running on the given host. Use VS_Ping to check VolServ's
status.
See Also
2-252
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Terminate(1),
•
VS_Global_SetFields(l)
601355 Rev A
API Guide
VS_Media_
Create
VS_Media_Create allocates a VolServ API media handle.
A media handle is used to pass media information to and from
VolServ.
Synopsis
VST_MEDIA_HANDLE VS_Media_Create ( void )
Arguments
None
Return Values
VS_Media_Create returns:
A media handle, if one could be allocated.
•
NULL, if a media handle could not be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_media_handle
*
* PURPOSE:
* This function tests a media handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_media_handle(void)
#else
VST_BOOLEAN vst_media_handle()
#endif
{
API Functions
2-253
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
2-254
API Functions
VST_BOOLEAN
VSE_FALSE;
VST_MEDIA_HANDLE
VST_MEDIA_ID
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_BATCH_NAME
VST_MANUFACTURER_NAME
Manufacturer;
VST_MEDIA_CLASS_NAME
MediaClassName;
VST_MEDIA_LOC_STATE
LocationState;
VST_ACTION_STATE
VST_ARCHIVE_NAME
CurrentArchive;
VST_ARCHIVE_NAME
PendingArchive;
VST_TIME
VST_TIME
LastDismount;
VST_ASSIGNMENT
int
int
rc =
h;
MediaID;
BatchName;
ActionState;
ImportDate;
Assignment;
MountCount;
MoveCount;
/* create the handle */
h = VS_Media_Create();
if (h != (VST_MEDIA_HANDLE) NULL)
{
/* get values from user */
printf(“*** Media Handle ***\n”);
printf(“Enter media id ==> “);
gets(MediaID);
printf(“Enter media type ==> “);
gets(MediaTypeName);
printf(“Enter batch name ==> “);
gets(BatchName);
printf(“Enter Manufacturer ==>
“);
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
601355 Rev A
API Guide
50
51
52
53
54
55
56
57
58
59
68
69
70
71
72
73
74
75
76
601355 Rev A
API Functions
2-255
Functions
60
61
62
63
64
65
66
67
gets(MediaClassName);
printf(“Enter media location
state ==> “);
LocationState =
atoi(gets(input));
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
gets(PendingArchive);
printf(“enter assignment value
==> “);
Assignment = atoi(gets(input));
printf(“enter mount count ==> “);
MountCount = atoi(gets(input));
printf(“enter move count ==> “);
MoveCount = atoi(gets(input));
/* set the fields in the handle */
rc = VS_Media_SetFields(h,
VSID_MEDIA_ID,
MediaID,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_BATCH_NAME,
BatchName,
VSID_MANUFACTURER,
Manufacturer,
VSID_MEDIA_CLASS_NAME,
MediaClassName,
VSID_MEDIA_LOC_STATE,
LocationState,
VSID_ACTION_STATE,
ActionState,
VSID_CURRENT_ARCHIVE_NAME,
CurrentArchive,
VSID_PENDING_ARCHIVE_NAME,
PendingArchive,
VSID_ASSIGNMENT,
Assignment,
API Guide
77
78
79
80
81
82
83
84
85
86
87 }
VSID_MOUNT_COUNT,
MountCount,
VSID_MOVE_COUNT,
MoveCount,
VSID_ENDFIELD);
if (rc)
{
vst_print_media(h);
}
VS_Media_Destroy(h);
}
return(rc);
Notes
None
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Media_Destroy(l),
•
VS_Media_GetFields(l),
•
VS_Media_SetFields(l)
2-256
API Functions
601355 Rev A
API Guide
VS_Media_
Destroy
VS_Media_Destroy deallocates a VolServ API media
handle that was allocated by VS_Media_Create. A media
destroy handle is used to pass media information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_Media_Destroy
(VST_MEDIA_HANDLE handle)
Arguments
•
Return Values
VS_Media_Destroy returns:
601355 Rev A
•
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
media handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_media_handle
4 *
5 * PURPOSE:
6 * This function tests a media handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
API Functions
2-257
Functions
Example
handle = The media handle to be destroyed.
API Guide
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
2-258
API Functions
#ifdef ANSI_C
VST_BOOLEAN vst_media_handle(void)
#else
VST_BOOLEAN vst_media_handle()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_MEDIA_HANDLE
h;
VST_MEDIA_ID
MediaID;
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_BATCH_NAME
BatchName;
VST_MANUFACTURER_NAME
Manufacturer;
VST_MEDIA_CLASS_NAME
MediaClassName;
VST_MEDIA_LOC_STATE
LocationState;
VST_ACTION_STATE
ActionState;
VST_ARCHIVE_NAME
CurrentArchive;
VST_ARCHIVE_NAME
PendingArchive;
VST_TIME
ImportDate;
VST_TIME
LastDismount;
VST_ASSIGNMENT
Assignment;
int
MountCount;
int
MoveCount;
/* create the handle */
h = VS_Media_Create();
if (h != (VST_MEDIA_HANDLE) NULL)
{
/* get values from user */
printf(“*** Media Handle ***\n”);
printf(“Enter media id ==> “);
gets(MediaID);
printf(“Enter media type ==> “);
gets(MediaTypeName);
printf(“Enter batch name ==> “);
601355 Rev A
API Guide
46
47
48
49
50
51
52
53
54
55
56
57
60
61
62
63
64
65
66
67
68
69
70
71
72
73
601355 Rev A
API Functions
2-259
Functions
58
59
gets(BatchName);
printf(“Enter Manufacturer ==>
“);
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
gets(MediaClassName);
printf(“Enter media location
state ==> “);
LocationState =
atoi(gets(input));
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
gets(PendingArchive);
printf(“enter assignment value
==> “);
Assignment = atoi(gets(input));
printf(“enter mount count ==> “);
MountCount = atoi(gets(input));
printf(“enter move count ==> “);
MoveCount = atoi(gets(input));
/* set the fields in the handle */
rc = VS_Media_SetFields(h,
VSID_MEDIA_ID,
MediaID,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_BATCH_NAME,
BatchName,
VSID_MANUFACTURER,
Manufacturer,
VSID_MEDIA_CLASS_NAME,
MediaClassName,
VSID_MEDIA_LOC_STATE,
LocationState,
VSID_ACTION_STATE,
ActionState,
API Guide
74
75
76
77
78
79
80
81
82
83
84
85
86
87 }
VSID_CURRENT_ARCHIVE_NAME,
CurrentArchive,
VSID_PENDING_ARCHIVE_NAME,
PendingArchive,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_COUNT,
MountCount,
VSID_MOVE_COUNT,
MoveCount,
VSID_ENDFIELD);
if (rc)
{
vst_print_media(h);
}
VS_Media_Destroy(h);
}
return(rc);
Notes
After VS_Media_Destroy has been called for a media handle,
that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Media_Create(l),
•
VS_Media_GetFields(l),
•
VS_Media_SetFields(l)
2-260
API Functions
601355 Rev A
API Guide
VS_Media_GetFields retrieves information associated
with a media handle. A media handle is used to pass media
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Media_GetFields
(VST_MEDIA_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The media 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.
Parameters
Parameter Type
Description
VSID_ACTION_STATE
(VST_ACTION_STATE *)
Action state associated with this medium.
Valid VSID_ACTION_STATE values are
enumerated in the vs_types.h file.
VSID_ASSIGNMENT (VST_ASSIGNMENT *)
Current assignment of this medium. Valid
VSID_ASSIGNMENT values are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-261
Functions
VS_Media_
GetFields
API Guide
Parameter Type
Description
VSID_BATCH_NAME (VST_BATCH_NAME)
Pointer to the name of the batch associated
with this medium. Valid batch names may
contain up to 32 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_CURRENT_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the name of the archive where the
medium is currently stored. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_IMPORT_DATE (VST_TIME *)
Pointer to the date this medium was imported
into the VolServ system.
VSID_LAST_DISMOUNT (VST_TIME *)
Pointer to the time this medium was last
dismounted.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
Pointer to the manufacturer associated with
this medium. Valid manufacturer names may
contain up to 32 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass group with which
this medium is associated.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the identifier of this medium.
VSID_MEDIA_LOC_STATE
(VST_MEDIA_LOC_STATE *)
Pointer to the location state of this medium.
Valid VSID_MEDIA_LOC_STATE values are
enumerated in the vs_types.h file
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Pointer to the media type associated with this
medium. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_MOUNT_COUNT (VST_COUNT *)
Pointer to the number of times this medium
has been mounted.
2-262
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_MOVE_COUNT (VST_COUNT *)
Pointer to the number of times this medium
has been moved from one archive to another.
VSID_PENDING_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the name of the destination archive
for this medium. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
Return Values
601355 Rev A
•
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 a
media handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_print_media
4 *
5 * PURPOSE:
6 * This function prints out the
information stored
7 * in a media handle.
8 * PARAMETERS:
9 * h : the media handle to print
10 *
API Functions
2-263
Functions
Example
VS_Media_GetFields returns:
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13 void vst_print_media(VST_MEDIA_HANDLE
h)
14 #else
15 void vst_print_media(h)
16 VST_MEDIA_HANDLE h;
17 #endif
18 {
19
VST_MEDIA_ID
MediaID;
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
VST_BATCH_NAME
BatchName;
22
VST_MANUFACTURER_NAME
Manufacturer;
23
VST_MEDIA_CLASS_NAME
MediaClassName;
24
VST_MEDIA_LOC_STATE
LocationState;
25
VST_ACTION_STATE
ActionState;
26
VST_ARCHIVE_NAME
CurrentArchive;
27
VST_ARCHIVE_NAME
PendingArchive;
28
VST_TIME
ImportDate;
29
VST_TIME
LastDismount;
30
VST_ASSIGNMENT
Assignment;
31
int
MountCount;
32
int
MoveCount;
33
34
VS_Media_GetFields(h,
35
VSID_MEDIA_ID,
MediaID,
36
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
37
VSID_BATCH_NAME,
BatchName,
38
VSID_MANUFACTURER,
Manufacturer,
2-264
API Functions
601355 Rev A
API Guide
39
40
41
42
43
44
45
46
47
49
50
51
52
53
54
55
56
57
58
59
60
601355 Rev A
API Functions
2-265
Functions
48
VSID_MEDIA_CLASS_NAME,
MediaClassName,
VSID_MEDIA_LOC_STATE,
&LocationState,
VSID_ACTION_STATE,
&ActionState,
VSID_CURRENT_ARCHIVE_NAME,
CurrentArchive,
VSID_PENDING_ARCHIVE_NAME,
PendingArchive,
VSID_IMPORT_DATE,
&ImportDate,
VSID_LAST_DISMOUNT,
&LastDismount,
VSID_ASSIGNMENT,
&Assignment,
VSID_MOUNT_COUNT,
&MountCount,
VSID_MOVE_COUNT,
&MoveCount,
VSID_ENDFIELD);
printf(“******Media
Handle******\n”);
printf(“Media ID = %s\n”,MediaID);
printf(“Media Type Name =
%s\n”,MediaTypeName);
printf(“Batch Name =
%s\n”,BatchName);
printf(“Manufacturer =
%s\n”,Manufacturer);
printf(“Media Class Name =
%s\n”,MediaClassName);
printf(“Media Loc State =
%d\n”,LocationState);
printf(“Action State =
%d\n”,ActionState);
printf(“Current Archive =
%s\n”,CurrentArchive);
printf(“Pending Archive =
%s\n”,PendingArchive);
printf(“Import Date =
%d\n”,ImportDate);
API Guide
61
62
63
64
printf(“Last Dismount =
%d\n”,LastDismount);
printf(“Assignment =
%d\n”,Assignment);
printf(“Move Count =
%d\n”,MoveCount);
printf(“Mount Count =
%d\n”,MountCount);
65 }
Notes
The VSID_IMPORT_DATE and last VSID_LAST_DISMOUNT are
kept as long integers; use the ctime function to convert either of
these values to a string.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-266
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Media_Create(l),
•
VS_Media_Destroy(l),
•
VS_Media_SetFields(l),
•
VSCMS_MediaQuery(l),
•
VSCMD_MediaClassQuery(l)
601355 Rev A
API Guide
VS_Media_SetFields sets the value of one or more fields
associated with a media handle. A media handle is used to pass
media information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Media_SetFields
(VST_MEDIA_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The media handle where information is stored or
updated.
•
“…” = 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.
Parameters
Parameter Type
Description
VSID_ACTION_STATE
(VST_ACTION_STATE)
Action state associated with this medium.
Valid VSID_ACTION_STATE values are
enumerated in the vs_types.h file.
VSID_ASSIGNMENT (VST_ASSIGNMENT)
Current assignment of this medium. Valid
VSID_ASSIGNMENT values are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-267
Functions
VS_Media_
SetFields
API Guide
Parameter Type
Description
VSID_BATCH_NAME (VST_BATCH_NAME)
Name of the batch associated with this
medium. Valid batch names may contain 32
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_CURRENT_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Name of the archive where the medium is
currently stored. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_IMPORT_DATE (VST_TIME)
Date this medium was imported into the
VolServ system.
VSID_LAST_DISMOUNT (VST_TIME)
Time this medium was last dismounted.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
Manufacturer associated with this medium.
Valid manufacturer names may contain 32
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
MediaClass group with which this medium is
associated.
VSID_MEDIA_ID (VST_MEDIA_ID)
Identifier of this medium.
VSID_MEDIA_LOC_STATE
(VST_MEDIA_LOC_STATE)
Location state of this medium. Valid
VSID_MEDIA_LOC_STATE values are
enumerated in the vs_types.h file
VSID_MEDIA_TYPE_NAM
(VST_MEDIA_TYPE_NAME)
Media type associated with this medium. Valid
media types may contain 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MOUNT_COUNT (VST_COUNT)
Number of times this medium has been
mounted.
VSID_MOVE_COUNT (VST_COUNT)
Number of times this medium has been
moved from one archive to another.
2-268
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_PENDING_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Return Values
VS_Media_SetFields 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 a
media 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.
1
2
3
4
5
6
7
8
9
601355 Rev A
Functions
Example
Name of the destination archive for this
medium. Valid archive names may contain up
to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
/****************************************
*********
*
* FUNCTION: vst_media_handle
*
* PURPOSE:
* This function tests a media handle.
*
* PARAMETERS:
* none
API Functions
2-269
API Guide
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_media_handle(void)
14 #else
15
VST_BOOLEAN vst_media_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIA_HANDLE
h;
20
VST_MEDIA_ID
MediaID;
21
VST_MEDIA_TYPE_NAME
MediaTypeName;
22
VST_BATCH_NAME
BatchName;
23
VST_MANUFACTURER_NAME
Manufacturer;
24
VST_MEDIA_CLASS_NAME
MediaClassName;
25
VST_MEDIA_LOC_STATE
LocationState;
26
VST_ACTION_STATE
ActionState;
27
VST_ARCHIVE_NAME
CurrentArchive;
28
VST_ARCHIVE_NAME
PendingArchive;
29
VST_TIME
ImportDate;
30
VST_TIME
LastDismount;
31
VST_ASSIGNMENT
Assignment;
32
int
MountCount;
33
int
MoveCount;
34
35
/* create the handle */
36
h = VS_Media_Create();
37
if (h != (VST_MEDIA_HANDLE) NULL)
38
{
39
/* get values from user */
40
printf(“*** Media Handle ***\n”);
41
printf(“Enter media id ==> “);
42
gets(MediaID);
2-270
API Functions
601355 Rev A
API Guide
43
44
45
46
47
48
49
50
51
52
53
54
55
58
59
60
61
62
63
64
65
66
67
68
69
70
71
601355 Rev A
API Functions
2-271
Functions
56
57
printf(“Enter media type ==> “);
gets(MediaTypeName);
printf(“Enter batch name ==> “);
gets(BatchName);
printf(“Enter Manufacturer ==>
“);
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
gets(MediaClassName);
printf(“Enter media location
state ==> “);
LocationState =
atoi(gets(input));
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
gets(PendingArchive);
printf(“enter assignment value
==> “);
Assignment = atoi(gets(input));
printf(“enter mount count ==> “);
MountCount = atoi(gets(input));
printf(“enter move count ==> “);
MoveCount = atoi(gets(input));
/* set the fields in the handle */
rc = VS_Media_SetFields(h,
VSID_MEDIA_ID,
MediaID,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_BATCH_NAME,
BatchName,
VSID_MANUFACTURER,
Manufacturer,
VSID_MEDIA_CLASS_NAME,
MediaClassName,
API Guide
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87 }
VSID_MEDIA_LOC_STATE,
LocationState,
VSID_ACTION_STATE,
ActionState,
VSID_CURRENT_ARCHIVE_NAME,
CurrentArchive,
VSID_PENDING_ARCHIVE_NAME,
PendingArchive,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_COUNT,
MountCount,
VSID_MOVE_COUNT,
MoveCount,
VSID_ENDFIELD);
if (rc)
{
vst_print_media(h);
}
VS_Media_Destroy(h);
}
return(rc);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-272
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Media_Create(l),
•
VS_Media_Destroy(l),
•
VS_Media_SetFields(l)
601355 Rev A
API Guide
VS_
MediaClass_
Create
VS_MediaClass_Create allocates a VolServ API
MediaClass handle. A MediaClass handle is used to pass
MediaClass information to and from VolServ.
Synopsis
VST_MEDIACLASS_HANDLE VS_MediaClass_Create
(void)
Arguments
None
Return Values
VS_MediaClass_Create returns:
A MediaClass handle, if one can be allocated.
•
NULL, if a MediaClass handle could not be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_mediaclass_handle
*
* PURPOSE:
* This function tests a mediaclass
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediaclass_handle(void)
API Functions
2-273
Functions
Example
•
API Guide
14 #else
15
VST_BOOLEAN vst_mediaclass_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIACLASS_HANDLE
h;
20
VST_MEDIA_CLASS_NAME
MediaClass;
21
VST_MEDIA_TYPE_NAME
MediaTypeName;
22
VST_PRIORITY
ReleasePriority;
23
VST_CAPACITY
Capacity;
24
VST_FILL_LEVEL
FillLevel;
25
VST_CLASS_MOUNT_STATE
MountState;
26
VST_HIGH_MARK
HighMark;
27
VST_CLASS_RPC_OPTION
RPC_Option;
28
VST_HOSTNAME
RPC_HostName;
29
VST_PROGRAM_NUMBER
RPC_ProgNum;
30
VST_VERSION_NUMBER
RPC_VersNum;
31
VST_PROCEDURE_NUMBER
RPC_ProcNum;
32
VST_PROTOCOL
RPC_Protocol;
33
VST_ENTERPRISE_ID
EnterpriseID;
34
VST_NOTIFY_COMMENT
NotifyComment;
35
36
/* create the handle */
37
h = VS_MediaClass_Create();
38
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
{
40
/* get values from user */
41
printf(“*** Media Class Handle
***\n”);
42
printf(“Enter mediaclass name ==>
“);
43
gets(MediaClass);
44
printf(“Enter media type name ==>
“);
2-274
API Functions
601355 Rev A
API Guide
45
46
47
48
49
50
51
52
53
54
55
56
57
58
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
601355 Rev A
API Functions
2-275
Functions
59
60
gets(MediaTypeName);
printf(“Enter release priority
==> “);
ReleasePriority =
atoi(gets(input));
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter mount state ==> “);
MountState = atoi(gets(input));
printf(“Enter high mark ==> “);
HighMark = atoi(gets(input));
printf(“Enter class RPC option ==>
“);
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
gets(NotifyComment);
/* set the fields */
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
API Guide
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97 }
Notes
2-276
VSID_RELEASE_PRIORITY,
ReleasePriority,
VSID_CAPACITY,
Capacity,
VSID_FILL_LEVEL,
FillLevel,
VSID_CLASS_MOUNT_STATE,
MountState,
VSID_HIGH_MARK,
HighMark,
VSID_CLASS_RPC_OPTION,
RPC_Option,
VSID_HOST_NAME,
RPC_HostName,
VSID_PROGRAM_NUMBER,
RPC_ProgNum,
VSID_VERSION_NUMBER,
RPC_VersNum,
VSID_PROCEDURE_NUMBER,
RPC_ProcNum,
VSID_PROTOCOL,
RPC_Protocol,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_NOTIFY_COMMENT,
NotifyComment,
VSID_ENDFIELD);
if (rc)
{
vst_print_mediaclass(h);
}
VS_MediaClass_Destroy(h);
}
return(rc);
None
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaClass_Destroy(l),
•
VS_MediaClass_GetFields(l),
•
VS_MediaClass_SetFields(l)
Functions
601355 Rev A
API Functions
2-277
API Guide
VS_
MediaClass_
Destroy
VS_MediaClass_Destroy deallocates a VolServ API
MediaClass handle that was allocated with
VS_MediaClass_Create. A MediaClass handle is used to
pass MediaClass information to and from VolServ.
Synopsis
VST_BOOLEAN VS_MediaClass_Destroy
(VST_MEDIACLASS_HANDLE handle)
Arguments
•
Return Values
VS_MediaClass_Destroy returns:
Example
2-278
handle = The MediaClass handle to be destroyed.
•
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
MediaClass handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_mediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests a mediaclass
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-279
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediaclass_handle(void)
14 #else
15
VST_BOOLEAN vst_mediaclass_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIACLASS_HANDLE
h;
20
VST_MEDIA_CLASS_NAME
MediaClass;
21
VST_MEDIA_TYPE_NAME
MediaTypeName;
22
VST_PRIORITY
ReleasePriority;
23
VST_CAPACITY
Capacity;
24
VST_FILL_LEVEL
FillLevel;
25
VST_CLASS_MOUNT_STATE
MountState;
26
VST_HIGH_MARK
HighMark;
27
VST_CLASS_RPC_OPTION
RPC_Option;
28
VST_HOSTNAME
RPC_HostName;
29
VST_PROGRAM_NUMBER
RPC_ProgNum;
30
VST_VERSION_NUMBER
RPC_VersNum;
31
VST_PROCEDURE_NUMBER
RPC_ProcNum;
32
VST_PROTOCOL
RPC_Protocol;
33
VST_ENTERPRISE_ID
EnterpriseID;
34
VST_NOTIFY_COMMENT
NotifyComment;
35
36
/* create the handle */
37
h = VS_MediaClass_Create();
38
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
{
40
/* get values from user */
41
printf(“*** Media Class Handle
***\n”);
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
2-280
API Functions
printf(“Enter mediaclass name ==>
“);
gets(MediaClass);
printf(“Enter media type name ==>
“);
gets(MediaTypeName);
printf(“Enter release priority
==> “);
ReleasePriority =
atoi(gets(input));
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter mount state ==> “);
MountState = atoi(gets(input));
printf(“Enter high mark ==> “);
HighMark = atoi(gets(input));
printf(“Enter class RPC option ==>
“);
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
gets(NotifyComment);
/* set the fields */
601355 Rev A
API Guide
73
74
75
76
77
78
79
80
81
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97 }
601355 Rev A
}
return(rc);
API Functions
2-281
Functions
82
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_RELEASE_PRIORITY,
ReleasePriority,
VSID_CAPACITY,
Capacity,
VSID_FILL_LEVEL,
FillLevel,
VSID_CLASS_MOUNT_STATE,
MountState,
VSID_HIGH_MARK,
HighMark,
VSID_CLASS_RPC_OPTION,
RPC_Option,
VSID_HOST_NAME,
RPC_HostName,
VSID_PROGRAM_NUMBER,
RPC_ProgNum,
VSID_VERSION_NUMBER,
RPC_VersNum,
VSID_PROCEDURE_NUMBER,
RPC_ProcNum,
VSID_PROTOCOL,
RPC_Protocol,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_NOTIFY_COMMENT,
NotifyComment,
VSID_ENDFIELD);
if (rc)
{
vst_print_mediaclass(h);
}
VS_MediaClass_Destroy(h);
API Guide
Notes
After VS_MediaClass_Destroy has been called for a
MediaClass handle, that handle is no longer valid and should
not be used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaClass_Create(l),
•
VS_MediaClass_GetFields(l),
•
VS_MediaClass_SetFields(l)
2-282
API Functions
601355 Rev A
API Guide
VS_MediaClass_GetFields retrieves information
associated with a MediaClass handle. A MediaClass handle is
used to pass MediaClass information to and from VolServ.
Synopsis
VST_BOOLEAN VS_MediaClass_GetFields
(VST_MEDIACLASS_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The MediaClass 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.
Parameters
Parameter Type
Description
VSID_CAPACITY (VST_CAPACITY *)
Pointer to the maximum number of media
allowed in this MediaClass group.
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE *)
Pointer that indicates whether this MediaClass
group supports the “mount by MediaClass”
functionality. Valid
VSID_CLASS_MOUNT_STATE values are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-283
Functions
VS_
MediaClass_
GetFields
API Guide
Parameter Type
Description
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION *)
Pointer that indicates whether callbacks are to
be activated for this MediaClass group and if
they are, which callback scheme is to be used.
Valid VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE, a pointer to
the identifier of the enterprise to receive
unsolicited callbacks. Otherwise,
VSID_ENTERPRISE_ID is not applicable.
VSID_FILL_LEVEL (VST_FILL_LEVEL *)
Pointer to the current number of media in this
MediaClass group.
VSID_HIGH_MARK (VST_HIGH_MARK *)
Pointer to the percentage of the MediaClass
capacity above which notification or automatic
media migration is initiated.
VSID_HOST_NAME (VST_HOSTNAME)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, a pointer to the
network-assigned name of the computer
where the task that “listens” for unsolicited
callbacks executes. Otherwise,
VSID_HOST_NAME is not applicable.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the name of this MediaClass group.
VSID_MEDIA_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Media (in table format) that belong to this
MediaClass group.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the first media id in the media
handle table.
VSID_MEDIA_ID_ENTRY (int,
VST_MEDIA_ID)
Index of the medium in the media handle
table. Pointer to the location to store the media
identifier.
2-284
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the media type supported by this
MediaClass group. Valid media type names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
Pointer to the user-specified comment to be
included in a system log message when the
number of media in the MediaClass group
exceeds the high mark threshold or drops
below the low mark threshold.
VSID_NUMBER_MEDIA_HANDLES (int *)
Pointer to the number of media handles in the
media handle table.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER *)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, a pointer to the
RPC procedure number of the “listening task.”
Otherwise, VSID_PROCEDURE_NUMBER is not
applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, a pointer to the
RPC program number of the client process to
receive MediaClass notification messages
from VolServ. If the
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_NONE or
VSE_CLASS_RPC_ENTERPRISE,
VSID_PROGRAM_NUMBER is not applicable.
VSID_PROTOCOL (VST_PROTOCOL *)
If the VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, a pointer
where Internet protocol to use to return
unsolicited callbacks to the client. Valid
VSID_PROTOCOL values are enumerated in
the vs_types.h file.
VSID_RELEASE_PRIORITY
(VST_PRIORITY *)
Pointer to the release priority for this
MediaClass group.
601355 Rev A
API Functions
2-285
Functions
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
API Guide
Parameter Type
Description
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER *)
Return Values
Example
If the VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, a pointer to the
RPC version number of the “listening task.”
Otherwise, VSID_VERSION_NUMBER is not
applicable.
VS_MediaClass_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 a
MediaClass handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
10
11
12
13
2-286
API Functions
/****************************************
*********
*
* FUNCTION: vst_print_mediaclass
*
* PURPOSE:
* This function prints out the
information stored in
* a media class handle.
*
* PARAMETERS:
* h : the media class handle to print
*
****************************************
*********/
#ifdef ANSI_C
601355 Rev A
API Guide
14
15
16
17
18
19
20
21
22
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
601355 Rev A
VS_MediaClass_GetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_RELEASE_PRIORITY,
&ReleasePriority,
API Functions
2-287
Functions
23
24
25
26
27
28
void
vst_print_mediaclass(VST_MEDIACLA
SS_HANDLEh)
#else
void vst_print_mediaclass(h)
VST_MEDIACLASS_HANDLE h;
#endif
{
VST_MEDIA_CLASS_NAME
MediaClass;
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_PRIORITY
ReleasePriority;
VST_CAPACITY
Capacity;
VST_FILL_LEVEL
FillLevel;
VST_CLASS_MOUNT_STATE
MountState;
VST_HIGH_MARK
HighMark;
VST_CLASS_RPC_OPTION
RPC_Option;
VST_HOSTNAME
RPC_HostName;
VST_PROGRAM_NUMBER
RPC_ProgNum;
VST_VERSION_NUMBER
RPC_VersNum;
VST_PROCEDURE_NUMBER
RPC_ProcNum;
VST_PROTOCOL
RPC_Protocol;
VST_ENTERPRISE_ID
EnterpriseID;
VST_NOTIFY_COMMENT
NotifyComment;
VST_TABLE_HANDLE
MediaHandleTable;
int
NumEntries;
int
i;
VST_MEDIA_HANDLE
Media;
API Guide
44
45
46
47
48
49
50
51
52
53
54
55
VSID_CAPACITY,
&Capacity,
VSID_FILL_LEVEL,
&FillLevel,
VSID_CLASS_MOUNT_STATE,
&MountState,
VSID_HIGH_MARK,
&HighMark,
VSID_CLASS_RPC_OPTION,
&RPC_Option,
VSID_HOST_NAME,
RPC_HostName,
VSID_PROGRAM_NUMBER,
&RPC_ProgNum,
VSID_VERSION_NUMBER,
&RPC_VersNum,
VSID_PROCEDURE_NUMBER,
&RPC_ProcNum,
VSID_PROTOCOL,
&RPC_Protocol,
VSID_ENTERPRISE_ID,
&EnterpriseID,
VSID_NOTIFY_COMMENT,
NotifyComment,
56
57
58
59
60
61
62
63
64
65
2-288
API Functions
VSID_MEDIA_HANDLE_TABLE,&MediaHan
dleTable,
VSID_ENDFIELD);
printf(“****** Media Class Handle
******\n”);
printf(“Media Class = %s\n”,
MediaClass);
printf(“Media Type = %s\n”,
MediaTypeName);
printf(“Release Priority=%d\n”,
ReleasePriority);
printf(“Capacity = %d\n”, Capacity);
printf(“Fill Level = %d\n”,
FillLevel);
printf(“Mount State = %d\n”,
MountState);
printf(“High Mark = %d\n”, HighMark);
601355 Rev A
API Guide
66
67
68
69
70
71
72
73
74
VS_Table_GetFields(MediaHandleTab
le,
VSID_NUMBER_ENTRIES,
&NumEntries,
VSID_ENDFIELD);
for (i = 0; i < NumEntries; i++)
{
77
78
79
80
81
VS_Table_GetFields(MediaHandleTab
le,
VSID_TABLE_ENTRY, i,
&Media,
VSID_ENDFIELD);
vst_print_media(Media);
}
82
83
84
85
86
87 }
601355 Rev A
}
API Functions
2-289
Functions
75
76
printf(“RPC Option = %d\n”,
RPC_Option);
printf(“Host Name = %s\n”,
RPC_HostName);
rintf(“Program Number = %ld\n”,
RPC_ProgNum);
printf(“Version Number = %d\n”,
RPC_VersNum);
printf(“Procedure Number = %d\n”,
RPC_ProcNum);
printf(“RPC Protocol = %d\n”,
RPC_Protocol);
printf(“Enterprise ID = %ld\n”,
EnterpriseID);
printf(“Notify Comment = %s\n”,
NotifyComment);
if ( MediaHandleTable !=
(VST_TABLE_HANDLE) NULL)
{
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-290
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Media_GetFields(l),
•
VS_MediaClass_Create(l),
•
VS_MediaClass_Destroy(l),
•
VS_MediaClass_SetFields(l),
•
VS_Table_Create(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l),
•
VSCMD_MediaClassQuery(l)
601355 Rev A
API Guide
VS_MediaClass_SetFields sets the value for one or
more fields in a specified MediaClass handle. A MediaClass
handle is used to pass MediaClass information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_MediaClass_SetFields
(VST_MEDIACLASS_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The MediaClass handle where the 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.
Parameters
Parameter Type
Description
VSID_CAPACITY (VST_CAPACITY)
Maximum number of media allowed in this
MediaClass group.
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
Indicates whether this MediaClass group
supports the “mount by MediaClass”
functionality. Valid values for this field are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-291
Functions
VS_
MediaClass_
SetFields
API Guide
Parameter Type
Description
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION)
Indicates whether callbacks are to be
activated for this MediaClass group and if they
are, which callback scheme is to be used.
Valid VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
If the VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE, the identifier
of the enterprise to receive unsolicited
callbacks. Otherwise,
VSID_ENTERPRISE_ID is not applicable.
VSID_FILL_LEVEL (VST_FILL_LEVEL)
Current number of media in this MediaClass
group.
VSID_HIGH_MARK (VST_HIGH_MARK)
Percentage of the MediaClass capacity above
which notification or automatic media
migration is initiated.
VSID_HOST_NAME (VST_HOSTNAME)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, the
network-assigned name of the computer
where the task that “listens” for unsolicited
callbacks executes. Otherwise,
VSID_HOST_NAME is not applicable.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of this MediaClass group.Valid
MediaClass names may contain up to 16
alphanumeric characters, including spaces.
VSID_MEDIA_HANDLE_TABLE
(VST_TABLE_HANDLE)
Media (in table format) that belong to this
MediaClass group.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Media type supported by this MediaClass
group. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces.
2-292
API Functions
601355 Rev A
API Guide
Parameter Type
Description
User-specified comment to be included in a
system log message when the number of
media in the MediaClass group exceeds the
high mark threshold. The MediaClass name,
fill level, high mark threshold, and capacity
values are automatically included in the
system log message and need not be
included in VSID_NOTIFY_COMMENT.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, the RPC
procedure number of the “listening task.”
Otherwise, VSID_PROCEDURE_NUMBER is not
applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, the RPC
program number of the client process to
receive MediaClass notification messages. If
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_NONE or
VSE_CLASS_RPC_ENTERPRISE,
VSID_PROGRAM_NUMBER is not applicable.
VSID_PROTOCOL (VST_PROTOCOL)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, the Internet
protocol to use to return unsolicited callbacks
to the client. Valid VSID_PROTOCOL values
are enumerated in the vs_types.h file.
VSID_RELEASE_PRIORITY
(VST_PRIORITY)
Release priority for this MediaClass group.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
If VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_STANDARD, the RPC
version number of the “listening task.”
Otherwise, VSID_VERSION_NUMBER is not
applicable.
601355 Rev A
API Functions
2-293
Functions
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
API Guide
Return Values
Example
VS_MediaClass_SetFields 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 a
MediaClass 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2-294
API Functions
/****************************************
*********
*
* FUNCTION: vst_mediaclass_handle
*
* PURPOSE:
* This function tests a mediaclass
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediaclass_handle(void)
#else
VST_BOOLEAN vst_mediaclass_handle()
601355 Rev A
API Guide
601355 Rev A
API Functions
2-295
Functions
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIACLASS_HANDLE
h;
20
VST_MEDIA_CLASS_NAME
MediaClass;
21
VST_MEDIA_TYPE_NAME
MediaTypeName;
22
VST_PRIORITY
ReleasePriority;
23
VST_CAPACITY
Capacity;
24
VST_FILL_LEVEL
FillLevel;
25
VST_CLASS_MOUNT_STATE
MountState;
26
VST_HIGH_MARK
HighMark;
27
VST_CLASS_RPC_OPTION
RPC_Option;
28
VST_HOSTNAME
RPC_HostName;
29
VST_PROGRAM_NUMBER
RPC_ProgNum;
30
VST_VERSION_NUMBER
RPC_VersNum;
31
VST_PROCEDURE_NUMBER
RPC_ProcNum;
32
VST_PROTOCOL
RPC_Protocol;
33
VST_ENTERPRISE_ID
EnterpriseID;
34
VST_NOTIFY_COMMENT
NotifyComment;
35
36
/* create the handle */
37
h = VS_MediaClass_Create();
38
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
{
40
/* get values from user */
41
printf(“*** Media Class Handle
***\n”);
42
printf(“Enter mediaclass name ==>
“);
43
gets(MediaClass);
44
printf(“Enter media type name ==>
“);
45
gets(MediaTypeName);
API Guide
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
2-296
API Functions
printf(“Enter release priority
==> “);
ReleasePriority =
atoi(gets(input));
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter mount state ==> “);
MountState = atoi(gets(input));
printf(“Enter high mark ==> “);
HighMark = atoi(gets(input));
printf(“Enter class RPC option ==>
“);
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
gets(NotifyComment);
/* set the fields */
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
601355 Rev A
API Guide
76
77
78
79
80
81
82
83
84
86
87
88
89
90
91
92
93
94
95
96
97 }
601355 Rev A
Functions
85
VSID_RELEASE_PRIORITY,
ReleasePriority,
VSID_CAPACITY,
Capacity,
VSID_FILL_LEVEL,
FillLevel,
VSID_CLASS_MOUNT_STATE,
MountState,
VSID_HIGH_MARK,
HighMark,
VSID_CLASS_RPC_OPTION,
RPC_Option,
VSID_HOST_NAME,
RPC_HostName,
VSID_PROGRAM_NUMBER,
RPC_ProgNum,
VSID_VERSION_NUMBER,
RPC_VersNum,
VSID_PROCEDURE_NUMBER,
RPC_ProcNum,
VSID_PROTOCOL,
RPC_Protocol,
VSID_ENTERPRISE_ID,
EnterpriseID,
VSID_NOTIFY_COMMENT,
NotifyComment,
VSID_ENDFIELD);
if (rc)
{
vst_print_mediaclass(h);
}
VS_MediaClass_Destroy(h);
}
return(rc);
API Functions
2-297
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-298
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaClass_Create(l),
•
VS_MediaClass_Destroy(l),
•
VS_MediaClass_GetFields(l),
•
VS_Table_Create(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l)
601355 Rev A
API Guide
VS_
MediaType_
Create
VS_MediaType_Create allocates a VolServ API media
type handle. A media type handle is used to pass media type
information to and from VolServ.
Synopsis
VST_MEDIATYPE_HANDLE VS_MediaType_Create (void)
Arguments
None
Return Values
VS_MediaType_Create returns:
A media type handle, if one can be allocated
•
NULL, if a media type handle could be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_mediatype_handle
*
* PURPOSE:
* This function tests a mediatype
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediatype_handle(void)
#else
API Functions
2-299
API Guide
15
VST_BOOLEAN vst_mediatype_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIATYPE_HANDLE
h;
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
int
NumberSides;
22
VST_MEDIA_TYPE_CAPACITY Capacity;
23
24
h = VS_MediaType_Create();
25
if (h != (VST_MEDIATYPE_HANDLE) NULL)
26
{
27
/* get values from user */
28
printf(“Enter Media Type Name ==>
“);
29
gets(MediaTypeName);
30
printf(“Enter number of sides ==>
“);
31
NumberSides = atoi(gets(input));
32
printf(“Enter media type capacity
==> “);
33
Capacity = atof(gets(input));
34
rc = VS_MediaType_SetFields(h,
35
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
VSID_NUMBER_SIDES,
NumberSides,
37
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
VSID_ENDFIELD);
39
if (rc)
40
{
41
vst_print_mediatype(h);
42
}
43
VS_MediaType_Destroy(h);
44
}
45
return(rc);
46 }
2-300
API Functions
601355 Rev A
API Guide
Notes
None
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_Destroy(l),
•
VS_MediaType_GetFields(l),
•
VS_MediaType_SetFields(l)
Functions
601355 Rev A
API Functions
2-301
API Guide
VS_
MediaType_
Destroy
VS_MediaType_Destroy deallocates a VolServ API media
type handle that was allocated with
VS_MediaType_Create. A media type handle is used to
pass information to and from VolServ.
Synopsis
VST_BOOLEAN VS_MediaType_Destroy
(VST_MEDIATYPE_HANDLE handle)
Arguments
•
Return Values
VS_MediaType_Destroy returns:
Example
2-302
handle = The media type handle to be destroyed.
•
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
media type handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_mediatype_handle
4 *
5 * PURPOSE:
6 * This function tests a mediatype
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-303
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediatype_handle(void)
14 #else
15
VST_BOOLEAN vst_mediatype_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIATYPE_HANDLE
h;
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
int
NumberSides;
22
VST_MEDIA_TYPE_CAPACITY Capacity;
23
24
h = VS_MediaType_Create();
25
if (h != (VST_MEDIATYPE_HANDLE) NULL)
26
{
27
/* get values from user */
28
printf(“Enter Media Type Name ==>
“);
29
gets(MediaTypeName);
30
printf(“Enter number of sides ==>
“);
31
NumberSides = atoi(gets(input));
32
printf(“Enter media type capacity
==> “);
33
Capacity = atof(gets(input));
34
rc = VS_MediaType_SetFields(h,
35
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
VSID_NUMBER_SIDES,
NumberSides,
37
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
VSID_ENDFIELD);
39
if (rc)
40
{
41
vst_print_mediatype(h);
42
}
API Guide
43
44
45
46 }
VS_MediaType_Destroy(h);
}
return(rc);
Notes
After VS_MediaType_Destroy has been called for a media
type handle, that handle is no longer valid and should not be
used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_Create(l),
•
VS_MediaType_GetFields(l),
•
VS_MediaType_SetFields(l)
2-304
API Functions
601355 Rev A
API Guide
VS_MediaType_GetFields retrieves information
associated with a media type handle. A media type handle is
used to pass media type information to and from VolServ.
Synopsis
VST_BOOLEAN VS_MediaType_GetFields
(VST_MEDIATYPE_HANDLE handle,
“…”
VSID_ENDFIELD)
Arguments
•
handle = The media type 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.
Parameters
Parameter Type
Description
VSID_MEDIA_TYPE_CAPACITY
(VST_MEDIA_TYPE_CAPACITY *)
Pointer to the capacity (in megabytes) of a
medium belonging to this media type
classification.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Pointer to the name of this media type
classification. Valid media type names may
contain up to 16 alphanumeric characters,
including spaces.
601355 Rev A
API Functions
2-305
Functions
VS_
MediaType_
GetFields
API Guide
Parameter Type
Description
VSID_NUMBER_SIDES (int *)
Return Values
Example
Pointer to the number of sides a medium
belonging to this media type classification
supports.
VS_MediaType_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 a
media type handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
10
11
12
13
2-306
API Functions
/****************************************
*********
*
* FUNCTION: vst_print_mediatype
*
* PURPOSE:
* This function prints out the
information stored in
* a media type handle.
*
* PARAMETERS:
* h : the media type handle to print
*
****************************************
*********/
#ifdef ANSI_C
601355 Rev A
API Guide
14
15
16
17
18
19
20
21
22
23
24
25
void
vst_print_mediatype(VST_MEDIATYPE
_HANDLE h)
#else
void vst_print_mediatype(h)
VST_MEDIATYPE_HANDLE h;
#endif
{
VST_MEDIA_TYPE_NAME
MediaTypeName;
int
NumberSides;
VST_MEDIA_TYPE_CAPACITY Capacity;
26
28
29
30
31
32
Functions
27
VS_MediaType_GetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_NUMBER_SIDES,
&NumberSides,
VSID_MEDIA_TYPE_CAPACITY,
&Capacity,
VSID_ENDFIELD);
printf(“*** Media Type Handle
***\n”);
printf(“media type name = %s\n”,
MediaTypeName);
printf(“number of sides = %d\n”,
NumberSides);
printf(“Capacity = %.2f\n”,
Capacity);
33 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-307
API Guide
See Also
2-308
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_Create(l),
•
VS_MediaType_Destroy(l),
•
VS_MediaType_SetFields(l),
•
VSCMD_MediaTypeQuery(l)
601355 Rev A
API Guide
VS_MediaType_SetFields sets the value for one or more
fields associated with a media type handle. A media type handle
is used to pass media type information to and from VolServ.
Synopsis
VST_BOOLEAN VS_MediaType_SetFields
(VST_MEDIATYPE_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The media type handle where information is
stored or updated.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. 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.
Parameters
Parameter Type
Description
VSID_MEDIA_TYPE_CAPACITY
(VST_MEDIA_TYPE_CAPACITY)
Capacity (in megabytes) of a medium
belonging to this media type classification.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Name of this media type classification.
Valid media type names may contain up to 16
alphanumeric characters, including spaces.
No leading or trailing spaces are permitted.
601355 Rev A
API Functions
2-309
Functions
VS_
MediaType_
SetFields
API Guide
Parameter Type
Description
VSID_NUMBER_SIDES (int)
Return Values
Example
2-310
Number of sides a medium belonging to this
media type classification supports.
VS_MediaType_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 a
media type 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.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_mediatype_handle
4 *
5 * PURPOSE:
6 * This function tests a mediatype
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-311
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediatype_handle(void)
14 #else
15
VST_BOOLEAN vst_mediatype_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIATYPE_HANDLE
h;
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
int
NumberSides;
22
VST_MEDIA_TYPE_CAPACITY Capacity;
23
24
h = VS_MediaType_Create();
25
if (h != (VST_MEDIATYPE_HANDLE) NULL)
26
{
27
/* get values from user */
28
printf(“Enter Media Type Name ==>
“);
29
gets(MediaTypeName);
30
printf(“Enter number of sides ==>
“);
31
NumberSides = atoi(gets(input));
32
printf(“Enter media type capacity
==> “);
33
Capacity = atof(gets(input));
34
rc = VS_MediaType_SetFields(h,
35
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
VSID_NUMBER_SIDES,
NumberSides,
37
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
VSID_ENDFIELD);
39
if (rc)
40
{
41
vst_print_mediatype(h);
42
}
API Guide
43
44
45
46 }
VS_MediaType_Destroy(h);
}
return(rc);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-312
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_MediaType_Create(l),
•
VS_MediaType_Destroy(l),
•
VS_MediaType_GetFields(l),
•
VSCMD_MediaTypeQuery(l)
601355 Rev A
API Guide
VS_Mount_
Create
VS_Mount_Create function allocates a VolServ API mount
handle. A mount handle is used to pass mount information to
and from VolServ.
Synopsis
VST_MOUNT_HANDLE VS_Mount_Create (void)
Arguments
None
Return Values
VS_Mount_Create returns:
A mount handle, if one can be allocated.
•
NULL, if the mount handle cannot be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_create_mount_handle
*
* PURPOSE:
* This function creates the mount handle
and sets the
* values in it according to user input.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_MOUNT_HANDLE
vst_create_mount_handle ( void )
#else
API Functions
2-313
API Guide
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
2-314
API Functions
VST_MOUNT_HANDLE
vst_create_mount_handle
#endif
{
int
int
VST_DRIVE_ID
VST_DRIVE_POOL_NAME
drivepool;
VST_MEDIA_ID
VST_MEDIA_CLASS_NAME
mediaclass;
VST_MOUNT_HANDLE
VST_CRITERIAGROUP_HANDLE
()
i;
entry;
driveid;
mediaid;
mounth;
grouph;
/* create the handle */
mounth = VS_Mount_Create();
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
{
return ( (VST_MOUNT_HANDLE) NULL
);
}
/* prompt user for values */
printf ( “Mount by (1) Media ID or (2)
Media Class ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Media ID for
mounting ==> “ );
gets(mediaid);
VS_Mount_SetFields ( mounth,
VSID_MEDIA_ID, mediaid,
VSID_ENDFIELD );
}
else
{
printf ( “Enter Media Class for
mounting ==> “ );
gets(mediaclass);
601355 Rev A
API Guide
50
51
52
53
54
55
56
57
58
59
60
61
62
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
601355 Rev A
printf ( “Reclassify media (1) yes
or (2) no ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Target Media
Class ==> “ );
gets(mediaclass);
VS_Mount_SetFields( mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD );
}
}
printf ( “Mount by (1) Drive ID or (2)
Drive Pool ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Drive ID for
mounting ==> “ );
driveid = atoi(gets(input));
VS_Mount_SetFields ( mounth,
VSID_DRIVE_ID,
driveid,
VSID_ENDFIELD );
}
else
{
printf ( “Enter Drive Pool for
mount ==> “ );
gets(drivepool);
VS_Mount_SetFields ( mounth,
API Functions
2-315
Functions
63
64
65
66
VS_Mount_SetFields ( mounth,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD );
API Guide
82
VSID_DRIVEPOOL_NAME,
drivepool,
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106}
Notes
VSID_ENDFIELD );
}
printf ( “Mount by criteria (1) yes
or (2) no ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter number of criteria
groups ==> “ );
entry = atoi(gets(input));
for ( i = 0 ; i < entry ; i++ )
{
/* create a criteria group
handle */
grouph =
vst_create_mount_criteria();
if ( grouph !=
(VST_CRITERIAGROUP_HANDLE) NULL )
{
VS_Mount_SetFields (
mounth,
VSID_CRITERIA_GROUP_HANDLE,
i, grouph,
VSID_ENDFIELD );
}
}
}
return ( mounth );
VS_Mount_Create is used with the Mount or Multimount
commands.
2-316
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Mount_Destroy(l),
•
VS_Mount_GetFields(l),
•
VS_Mount_SetFields(l),
•
VSCMD_Mount(l),
•
VSCMD_MultiMount(l)
Functions
601355 Rev A
API Functions
2-317
API Guide
VS_Mount_
Destroy
VS_Mount_Destroy deallocates a VolServ mount handle
that was allocated with VS_Mount_Create. A mount handle
is used to pass mount information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Mount_Destroy
(VST_MOUNT_HANDLE handle)
Arguments
•
Return Values
VS_Mount_Destroy returns:
Example
handle = The mount handle to be destroyed.
•
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
mount handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_multimount_execute
*
* PURPOSE:
* This function will test the
VSCMD_Multimount call.
*
* PARAMETERS:
* none
7
8
9
10
11 ****************************************
*********/
2-318
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-319
Functions
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_multimount_execute(void)
14 #else
15
VST_BOOLEAN vst_multimount_execute()
16 #endif
17 {
18
int i;
19
int num;
20
VST_BOOLEAN rc = VSE_FALSE;
21
VST_COMMAND_HANDLE cmdh;
22
VST_MOUNT_HANDLE
mounth[VSD_MAX_MOUNT_REQS];
23
24
/* get parameters from user */
25
printf(“*** MultiMount Parameters
***\n”);
26
printf(“Enter the number of mount
requests ==> “ );
27
num = atoi(gets(input));
28
29
/* loop through the number of mount
request */
30
for ( i = 0 ; i < num ; i++ )
31
{
32
/* Create a mount handle. */
33
/* Each mount handle stores a
single mount */
34
/* request.The MultiMount command
accepts */
35
/* multiple mount requests and
executes */
36
/* them all as one operation.*/
37
mounth[i] =
vst_create_mount_handle();
38
if ( mounth[i] !=
(VST_MOUNT_HANDLE) NULL )
39
{
40
/* add the mount request to the
multimount */
41
/* via the command default
function */
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
2-320
API Functions
VSCMD_MultiMount_SetDefaults (
VSID_MOUNT_HANDLE, i,
mounth[i],
VSID_ENDFIELD );
}
else
{
rc = VSE_FALSE;
break;
}
}
if ( rc )
{
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
{
/* execute the multimount
command, note */
/* that all parameters have
been set via */
/* default functions if sync,
we will */
/* wait for all mounts to
complete */
/* if async, we will leave once
initial */
/* status has been returned */
rc = VSCMD_MultiMount ( cmdh,
VSID_ENDFIELD );
}
else
{
rc = VSE_FALSE;
}
}
/* destroy the mount handles that
contain the */
/* individual mount requests. */
601355 Rev A
API Guide
75
76
77
78
79
80 }
for ( i = 0 ; i < num ; i++ )
{
VS_Mount_Destroy ( mounth[i] );
}
return ( rc );
After VS_Mount_Destroy has been called for a mount handle,
that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Mount_Create(l),
•
VS_Mount_GetFields(l),
•
VS_Mount_SetFields(l),
•
VSCMD_Mount(l),
•
VSCMD_MultiMount(l)
601355 Rev A
Functions
Notes
API Functions
2-321
API Guide
VS_
MediaClass_
GetFields
VS_Mount_GetFields retrieves information associated
with a mount handle. A mount handle is used to pass mount
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Mount_GetFields
(VST_MOUNT_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The mount 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.
Parameters
Parameter Type
Description
VSID_CRITERIA_GROUP_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the table of criteria group handles
associated with the mount handle.
VSID_DRIVE_SELECT
(VST_DRIVE_SELECT *)
Pointer to the type of drive selection (drive
identifier or drive pool) to associate with the
mount command. Valid
VSID_DRIVE_SELECT values are
enumerated in the vs_types.h file.
2-322
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the drive identifier to mount when
mounting by drive identifier.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Pointer to the name of a drive pool group from
which to select a drive when mounting by
drive pool group. Valid DrivePool names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the list of drives to exclude from the
given drive pool group when mounting by
drive pool group.
VSID_LOCK_ID (VST_LOCK_ID *)
Pointer to the lock identifier that is required if a
drive is locked.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass name from which a
medium is selected to mount. Valid
MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the identifier of the medium to be
mounted.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media identifier list (in table
format) from which the medium to be mounted
is selected when mounting by media list.
VSID_MEDIA_SELECT
(VST_MEDIA_SELECT *)
Pointer to the type of media selection (media
identifier, media list, or MediaClass group).
VSID_MOUNT_OPTION
(VST_MOUNT_OPTION *)
Pointer to a flag that indicates which mount
processing options are in effect for the mount
command. Valid VSID_MOUNT_OPTION
values are listed in the vs_defs.h file.
601355 Rev A
API Functions
2-323
Functions
VSID_DRIVE_ID (VST_DRIVE_ID *)
API Guide
Parameter Type
Description
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION *)
Pointer to a flag that indicates how VolServ is
to process a mount request that requires an
inter-archive move. Valid
VSID_MOVEWAIT_OPTION values are
enumerated in the vs_types.h file.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass name where the
mounted media is reclassified if the reclassify
option is in effect for the mount command.
Return Values
Example
2-324
VS_Mount_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 a
mount handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_print_mount
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a mount handle.
8 * PARAMETERS:
9 * mounth : the mount handle to print
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-325
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
void
vst_print_mount(VST_MOUNT_HANDLE
mounth)
14 #else
15
void vst_print_mount(mounth)
16
VST_MOUNT_HANDLE mounth;
17 #endif
18 {
19
int
i, size;
20
VST_DRIVE_SELECT
driveselect;
21
VST_DRIVE_ID
driveid;
22
VST_DRIVE_POOL_NAME
drivepool;
23
VST_MEDIA_SELECT
mediaselect;
24
VST_MEDIA_ID
mediaid;
25
VST_MEDIA_CLASS_NAME
mediaclass;
26
VST_MEDIA_CLASS_NAME
targetmediaclass;
27
VST_MOUNT_OPTION
mountopt;
28
VST_CRITERIAGROUP_HANDLE
grouph;
29
VST_TABLE_HANDLE
tableh;
30
31
/* check for a null handle */
32
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
33
{
34
printf(“error…mount handle is
null\n”);
35
return;
36
}
37
38
VS_Mount_GetFields ( mounth,
39
VSID_DRIVE_SELECT,
&driveselect,
40
VSID_MEDIA_SELECT,
&mediaselect,
API Guide
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
2-326
API Functions
VSID_MOUNT_OPTION,
&mountopt,
VSID_ENDFIELD );
printf(“**** Mount Handle Values
****\n”);
switch ( driveselect )
{
case VSE_DRIVE_SELECT_ID:
VS_Mount_GetFields ( mounth,
VSID_DRIVE_ID,
&driveid,
VSID_ENDFIELD );
printf ( “Drive ID: %d\n”,
driveid );
break;
case VSE_DRIVE_SELECT_POOL:
VS_Mount_GetFields ( mounth,
VSID_DRIVEPOOL_NAME,
drivepool,
VSID_ENDFIELD );
printf ( “Drive Pool: %s\n”,
drivepool );
break;
default:
printf ( “error…incorrect
drive select value\n”);
break;
}
switch ( mediaselect )
{
case VSE_MEDIA_SELECT_ID:
VS_Mount_GetFields ( mounth,
VSID_MEDIA_ID,
mediaid,
VSID_ENDFIELD );
printf ( “Media ID: %s\n”,
mediaid );
break;
case VSE_MEDIA_SELECT_LIST:
printf ( “Media List:\n” );
601355 Rev A
API Guide
74
75
76
77
78
79
80
81
82
83
84
85
86
95
96
97
98
99
100
101
102
103
104
601355 Rev A
VS_Table_GetFields ( tableh,
VSID_NUMBER_ENTRIES,
&size,
VSID_ENDFIELD );
for ( i = 0 ; i < size ; i++ )
{
VS_Table_GetFields (
tableh,
VSID_TABLE_ENTRY, i,
&mediaid,
VSID_ENDFIELD );
printf ( “%s”, mediaid );
}
break;
case VSE_MEDIA_SELECT_CLASS:
VS_Mount_GetFields(mounth,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD);
printf( “Media Class: %s\n”,
mediaclass);
if (mountopt &
VSD_MOUNT_OPTION_RECLASS)
{
VS_Mount_GetFields(mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
targetmediaclass,
VSID_ENDFIELD );
printf(“Target Media Class:
%s\n”,
targetmediaclass );
}
API Functions
2-327
Functions
87
88
89
90
91
92
93
94
VS_Mount_GetFields ( mounth,
VSID_MEDIA_ID_TABLE,
&tableh,
VSID_ENDFIELD );
API Guide
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131}
2-328
API Functions
break;
default:
printf(“error
media select
value\n”);
break;
…incorrect
}
if (mountopt &
VSD_MOUNT_OPTION_CRITERIA)
{
VS_Mount_GetFields(mounth,
VSID_CRITERIA_GROUP_HANDLE_TABLE,
&tableh,
VSID_ENDFIELD);
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&size,
VSID_ENDFIELD);
for (i = 0; i < size; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i,
&grouph,
VSID_ENDFIELD);
vst_print_criteria_group(grouph);
}
}
return;
601355 Rev A
API Guide
Notes
The mount handle contains all relevant mount information. The
user can set all mount parameters in a mount handle and pass
the mount handle to the Mount or Multimount command. The
Mount or Multimount command retrieves the required
information from the handle.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Mount_Create(l),
•
VS_Mount_Destroy(l),
•
VS_Mount_SetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_Mount(l),
•
VSCMD_MultiMount(l)
Functions
601355 Rev A
•
API Functions
2-329
API Guide
VS_Mount_
SetFields
VS_Mount_SetFields sets the value for one or more fields
associated with the mount handle. A mount handle is used to
pass mount information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Mount_SetFields
(VST_MOUNT_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The mount 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.
Parameters
Parameter Type
Description
VSID_CRITERIA_GROUP_HANDLE (int)
Number of the specified criteria group. A
criteria group number can be 0 through 3,
inclusive.
(VST_CRITERIAGROUP_HANDLE)
A criteria group to be used by the mount
command in selecting media for mounting.
VSID_DRIVE_ID (VST_DRIVE_ID)
Drive identifier to mount when mounting by
drive identifier. If VSID_DRIVE_ID is
specified, VSID_DRIVEPOOL_NAME and
VSID_DRIVE_EXCL_LIST cannot be
specified.
2-330
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Drive pool group from which a drive is
selected to mount when mounting by drive
pool group. If VSID_DRIVEPOOL_NAME is
specified, VSID_DRIVE_ID cannot be
specified. Valid DrivePool names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_DRIVE_EXCL_LIST (int)
Number of drives to exclude from the specified
drive pool group when mounting by drive pool
group.
(VST_DRIVE_ID *)
List of drives to exclude from the specified
drive pool group when mounting by drive pool
group.
VSID_LOCK_ID (VST_LOCK_ID)
Lock identifier that is required if a drive is
locked.
VSID_MEDIA_ID (VST_MEDIA_ID)
Identifier of the medium to be mounted when
mounting by medium identifier. If
VSID_MEDIA_ID is specified,
VSID_MEDIA_CLASS_NAME and
VSID_MEDIA_ID_LIST cannot be specified.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of the MediaClass group from which a
medium is selected to mount when mounting
by MediaClass group. If
VSID_MEDIA_CLASS_NAME is specified,
VSID_MEDIA_ID and
VSID_MEDIA_ID_LIST cannot be specified.
VSID_MEDIA_ID_LIST (int)
Number of media in the list.
(char *)
List of media from which one medium is
selected for mounting. If
VSID_MEDIA_ID_LIST is specified,
VSID_MEDIA_CLASS_NAME and
VSID_MEDIA_ID cannot be specified.
601355 Rev A
API Functions
2-331
Functions
VSID_DRIVEPOOL_NAME
(VS_DRIVE_POOL_NAME)
API Guide
Parameter Type
Description
VSID_MOUNT_OPTION
(VST_MOUNT_OPTION)
Flag that indicates which mount processing
options are in effect for the mount command.
Valid VSID_MOUNT_OPTION values are listed
in the vs_defs.h file.
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION)
Flag that indicates how VolServ is to process
a mount request that requires an inter-archive
move. Valid VSID_MOVEWAIT_OPTION
values are enumerated in the vs_types.h
file.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_TARGET_MEDIA_CLASS_NAME)
Name of the MediaClass group where the
mounted medium is reclassified if the
reclassify option is in effect for the mount
command.
Return Values
2-332
API Functions
VS_Mount_SetFields 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 a
mount 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.
601355 Rev A
API Guide
•
Example
VSE_ERR_OUTOFRANGE - Specified entry does not exist
in the table’s range of values.
1
2
3
4
5
6
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
601355 Rev A
/* create the handle */
mounth = VS_Mount_Create();
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
API Functions
2-333
Functions
7
8
9
10
11
12
/****************************************
*********
*
* FUNCTION: vst_create_mount_handle
*
* PURPOSE:
* This function creates the mount handle
and sets the
* values in it according to user input.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_MOUNT_HANDLE
vst_create_mount_handle ( void )
#else
VST_MOUNT_HANDLE
vst_create_mount_handle ()
#endif
{
int
i;
int
entry;
VST_DRIVE_ID
driveid;
VST_DRIVE_POOL_NAME
drivepool;
VST_MEDIA_ID
mediaid;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_MOUNT_HANDLE
mounth;
VST_CRITERIAGROUP_HANDLE
grouph;
API Guide
31
32
{
33
34
35
}
/* prompt user for values */
printf ( “Mount by (1) Media ID or (2)
Media Class ==> “ );
entry = atoi(gets(input));
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
2-334
API Functions
return ( (VST_MOUNT_HANDLE) NULL
);
if ( entry == 1 )
{
printf ( “Enter Media ID for
mounting ==> “ );
gets(mediaid);
VS_Mount_SetFields ( mounth,
VSID_MEDIA_ID, mediaid,
VSID_ENDFIELD );
}
else
{
printf ( “Enter Media Class for
mounting ==> “ );
gets(mediaclass);
VS_Mount_SetFields ( mounth,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD );
printf ( “Reclassify media (1) yes
or (2) no ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Target Media
Class ==> “ );
gets(mediaclass);
VS_Mount_SetFields( mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD );
601355 Rev A
API Guide
64
65
66
67
68
69
70
71
72
73
74
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
601355 Rev A
if ( entry == 1 )
{
printf ( “Enter Drive ID for
mounting ==> “ );
driveid = atoi(gets(input));
VS_Mount_SetFields ( mounth,
VSID_DRIVE_ID,
driveid,
VSID_ENDFIELD );
}
else
{
printf ( “Enter Drive Pool for
mount ==> “ );
gets(drivepool);
VS_Mount_SetFields ( mounth,
VSID_DRIVEPOOL_NAME, drivepool,
VSID_ENDFIELD );
}
printf ( “Mount by criteria (1) yes
or (2) no ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter number of criteria
groups ==> “ );
entry = atoi(gets(input));
for ( i = 0 ; i < entry ; i++ )
{
/* create a criteria group
handle */
grouph =
vst_create_mount_criteria();
API Functions
2-335
Functions
75
76
77
78
79
}
}
printf ( “Mount by (1) Drive ID or (2)
Drive Pool ==> “ );
entry = atoi(gets(input));
API Guide
97
98
99
if ( grouph !=
(VST_CRITERIAGROUP_HANDLE) NULL )
{
VS_Mount_SetFields (
mounth,
100
101
102
103
104
105
106}
Notes
VSID_CRITERIA_GROUP_HANDLE, i,
grouph,
VSID_ENDFIELD );
}
}
}
return ( mounth );
The mount handle contains all relevant mount information. The
user can set all mount parameters in a mount handle and pass
the mount handle to the Mount or Multimount command. The
Mount or Multimount command retrieves the required
information from the handle.
The VSID_CRITERIA_GROUP_HANDLE,
VSID_DRIVE_EXCL_LIST, and VSID_MEDIA_ID_LIST
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 a pointer to the values for setting.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-336
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Mount_Create(l),
•
VS_Mount_Destroy(l),
•
VS_Mount_GetFields(l),
•
VSCMD_Mount(l),
•
VSCMD_MultiMount(l)
Functions
601355 Rev A
API Functions
2-337
API Guide
VS_Notify_
Create
VS_Notify_Create allocates a VolServ API notify handle.
A notify handle is used by the API to allow a client to listen for
MediaClass notifications.
Synopsis
VST_NOTIFY_HANDLE VS_Notify_Create (void)
Arguments
None
Return Values
VS_Notify_Create returns:
Example
•
A notify handle, if one can be allocated
•
NULL, if a notify handle could not be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation call failed.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2-338
API Functions
/****************************************
*********
*
* FUNCTION: vst_notify
*
* PURPOSE:
* This routine is used to test the notify
loop.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_notify( void )
#else
VST_BOOLEAN
vst_notify()
601355 Rev A
API Guide
601355 Rev A
API Functions
2-339
Functions
17 #endif
18 {
19
VST_BOOLEAN
done, rc;
20
int
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
22
VST_TIME_OUT
t;
23
VST_TABLE_HANDLE
table;
24
VST_MEDIA_CLASS_NAME class,
newclass;
25
VST_NOTIFY_HANDLE
h;
26
27
rc = VSE_TRUE;
28
done = VSE_FALSE;
29
NumNotifies = 0;
30
31
/* get parameters from user */
32
printf(“*** Notify Parameters ***\n”
);
33
printf(“Program Number ==> “ );
34
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
printf(“Version Number ==> “ );
37
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
printf(“Procedure Number ==> “ );
40
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
count = atoi(gets(input));
44
45
printf(“Timeout Value ==> “ );
46
t = atoi(gets(input));
47
48
printf(“Number of Timeouts to process
==> “ );
49
timeout = atoi(gets(input));
API Guide
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
2-340
API Functions
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER, prognum,
VSID_VERSION_NUMBER, versnum,
VSID_PROCEDURE_NUMBER,procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
VSID_TIMEOUT_VALUE,
t,
VSID_ENDFIELD );
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
break;
default:
601355 Rev A
API Guide
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
Notes
601355 Rev A
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
if ( timeout <= 0 )
{
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
}
}
Functions
99
100
101
102
103
104
105
106
107
108
109
110
111
112}
printf(“Select Error
%d\n”, i );
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
/* destroy the notify handle */
VS_Notify_Destroy ( h );
}
else
{
rc = VSE_FALSE;
}
return ( rc );
None
API Functions
2-341
API Guide
See Also
2-342
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Notify_Destroy(l),
•
VS_Notify_GetFields(l),
•
VS_Notify_Listen(l),
•
VS_Notify_SetFields(l)
601355 Rev A
API Guide
VS_Notify_
Destroy
VS_Notify_Destroy deallocates a VolServ API notify
handle that was allocated with VS_Notify_Create.
Synopsis
VST_BOOLEAN VS_Notify_Destroy
(VST_NOTIFY_HANDLE notifyhandle)
Arguments
•
Return Values
VS_Notify_Destroy returns:
601355 Rev A
•
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
notify handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_notify
4 *
5 * PURPOSE:
6 * This routine is used to test the notify
loop.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
API Functions
2-343
Functions
Example
notifyhandle = The notify handle to be destroyed.
API Guide
13
VST_BOOLEAN vst_notify( void )
14 #else
15
VST_BOOLEAN
16
vst_notify()
17 #endif
18 {
19
VST_BOOLEAN
done, rc;
20
int
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
22
VST_TIME_OUT
t;
23
VST_TABLE_HANDLE
table;
24
VST_MEDIA_CLASS_NAME class,
newclass;
25
VST_NOTIFY_HANDLE
h;
26
27
rc = VSE_TRUE;
28
done = VSE_FALSE;
29
NumNotifies = 0;
30
31
/* get parameters from user */
32
printf(“*** Notify Parameters ***\n”
);
33
printf(“Program Number ==> “ );
34
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
printf(“Version Number ==> “ );
37
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
printf(“Procedure Number ==> “ );
40
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
count = atoi(gets(input));
44
45
printf(“Timeout Value ==> “ );
46
t = atoi(gets(input));
2-344
API Functions
601355 Rev A
API Guide
47
48
49
50
51
52
53
54
55
56
57
58
59
60
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
601355 Rev A
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
VSID_VERSION_NUMBER,
versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
VSID_TIMEOUT_VALUE,
t,
VSID_ENDFIELD );
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
API Functions
2-345
Functions
61
printf(“Number of Timeouts to process
==> “ );
timeout = atoi(gets(input));
API Guide
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112}
2-346
API Functions
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
break;
default:
printf(“Select Error
%d\n”, i );
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
if ( timeout <= 0 )
{
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
}
}
/* destroy the notify handle */
VS_Notify_Destroy ( h );
}
else
{
rc = VSE_FALSE;
}
return ( rc );
601355 Rev A
API Guide
Notes
After VS_Notify_Destroy has been called for a notify
handle, that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Notify_Create(l),
•
VS_Notify_GetFields(l),
•
VS_Notify_Listen(l),
•
VS_Notify_SetFields(l)
Functions
601355 Rev A
API Functions
2-347
API Guide
VS_Notify_
GetFields
VS_Notify_GetFields retrieves information associated
with a notify handle. A notify handle is used by the API to
allow a client to listen for MediaClass notifications.
Synopsis
VST_BOOLEAN VS_Notify_GetFields
(VST_NOTIFY_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The notify 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the archive name for this callback.
Valid archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_DRIVE_ID (VST_DRIVEID *)
Pointer to the drive identifier for this callback.
VSID_DRIVE_ID_ENTRY (int)
Index of a specific entry in the drive identifier
table.
2-348
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to a specific entry in the drive identifier
table.
VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive identifiers (in table format)
associated with this callback.
VSID_ERROR_HANDLE
(VST_ERROR_HANDLE *)
Pointer to the error handle for this callback.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass name for this
callback.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the media identifier for this callback.
VSID_MEDIA_ID_ENTRY (int)
Number of media in the media identifier table.
(VST_MEDIA_ID *)
Pointer to the media identifier table.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media identifiers (in table
format) associated with this callback.
VSID_NOTIFY_TYPE
(VST_NOTIFY_TYPE *)
Pointer to the type of VolServ command that
generated this callback. Valid
VSID_NOTIFY_TYPE values are enumerated
in the vs_types.h file.
VSID_NUMBER_DRIVE_IDS (int *)
Pointer to the number of drive ids present in
the drive id table.
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of media ids present in
the media id table.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER *)
Pointer to the RPC procedure number of the
client process to receive callbacks generated
for this MediaClass group.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
Pointer to the RPC program number of the
client process to receive MediaClass
callbacks.
601355 Rev A
API Functions
2-349
Functions
(VST_DRIVE_ID *)
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL *)
Pointer to the RPC protocol the API should
use for callbacks. Valid VSID_PROTOCOL
values for this field are enumerated in the
vs_types.h file.
VSID_STATUS_CODE
(VST_STATUS_CODE *)
Pointer to the status code stating whether the
enter or eject passed or failed.
VSID_STATUS_CODE is returned only for
enter and eject callbacks.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the target MediaClass name for this
callback.
VSID_TIMEOUT_VALUE (VST_TIME_OUT *)
Pointer to the amount of time (in seconds) the
API software is to wait for status from VolServ
before returning a time-out to the client
software. The default time-out value is 120
seconds.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER *)
Pointer to the RPC version number the API
should use to receive callbacks.
Return Values
2-350
API Functions
VS_Notify_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 a
notify handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
25
26
27
28
29
30
31
32
33
34
601355 Rev A
/* increment a counter for the number
of */
/* notifies processed */
NumNotifies++;
/* initialize values in the notify
handle. */
VS_Notify_GetFields ( h,
API Functions
2-351
Functions
15
16
17
18
19
20
21
22
23
24
/****************************************
*********
*
* FUNCTION: vst_notify_dispatch
*
* PURPOSE:
* This is the dispatch routine used to
test the
* notify loop.
*
* PARAMETERS:
* h : the notify handle to print
*
****************************************
*********/
#ifdef ANSI_C
int
vst_notify_dispatch (
VST_NOTIFY_HANDLE h )
#else
int
vst_notify_dispatch ( h )
VST_NOTIFY_HANDLE h;
#endif
{
int
i, n;
VST_ARCHIVE_NAME
archive;
VST_DRIVE_ID
* did;
char
* mid;
VST_MEDIA_CLASS_NAME
class,
newclass;
VST_NOTIFY_TYPE
type;
VST_ERROR_HANDLE
eh;
VST_TABLE_HANDLE
dt, mt;
VST_STATUS_CODE
sc;
API Guide
35
VSID_NOTIFY_TYPE,
&type,
36
37
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
class,
38
39
40
41
42
43
44
45
46
47
48
49
VSID_TARGET_MEDIA_CLASS_NAME,
newclass,
VSID_DRIVE_ID_TABLE,
&dt,
VSID_MEDIA_ID_TABLE,
&mt,
VSID_ERROR_HANDLE,
&eh,
VSID_ENDFIELD );
printf(“***************** Notify
Handle Information
*************\\pn” );
printf(“Notify Type = %d\n”, type );
if ((type == VSE_NOTIFY_EJECT) ||
(type == VSE_NOTIFY_ENTER))
{
VS_Notify_GetFields ( h,
VSID_STATUS_CODE, &sc,
50
51
52
53
54
55
56
57
58
59
60
61
62
2-352
API Functions
VSID_ENDFIELD );
if (sc == VSE_STATUS_OK)
printf(“Successful\n”);
else
printf(“Failure\n”);
}
printf(“Archive Name = %s\n”, archive
);
printf(“Media Class = %s\n”, class );
switch(type)
{
case VSE_NOTIFY_IMPORT:
case VSE_NOTIFY_EXPORT:
case VSE_NOTIFY_ENTER:
601355 Rev A
API Guide
63
64
65
66
67
68
69
70
71
72
73
74
75
76
82
83
84
85
86
87
88
89
90
91
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD );
for ( i = 0 ; i < n ; i++ )
{
VS_Table_GetFields ( mt,
VSID_TABLE_ENTRY, i, &mid,
VSID_ENDFIELD
);
printf(“Media ID Entry #
%d = %s\n“,
i, mid );
}
}
break;
case VSE_NOTIFY_MOUNT:
case VSE_NOTIFY_DISMOUNT:
/* print the drive and media id
*/
VS_Notify_GetFields(h,
VSID_MEDIA_ID, mid,
92
VSID_DRIVE_ID, &did,
601355 Rev A
API Functions
2-353
Functions
77
78
79
80
81
case VSE_NOTIFY_EJECT:
case VSE_NOTIFY_CHECKIN:
case VSE_NOTIFY_CHECKOUT:
case VSE_NOTIFY_RECLASSIFY:
/* media callbacks */
/* -- print the media table */
if (type ==
VSE_NOTIFY_RECLASSIFY)
{
printf(“New Media Class =
%s\n”, newclass);
}
if ( mt != (VST_TABLE_HANDLE)
NULL )
{
VS_Table_GetFields ( mt,
API Guide
93
94
95
96
97
98
99
100
101
102}
Notes
VSID_ENDFIELD);
printf(“media id = %s\n”, mid);
printf(“drive id = %d\n”, did);
break;
default:
break;
}
/* print the error handle */
vst_print_error ( eh );
The VSID_DRIVE_ID_ENTRY and VSID_MEDIA_ID_ENTRY
parameters require that two arguments be retrieved instead of
one. The first argument retrieved is the entry number in the
appropriate table. The second argument is a pointer to the
location where the value should be stored.
After the client receives a MediaClass notification from
VS_Notify_Listen, the Notify handle contains the notify
information. To determine the Notify type, the client then
retrieves the relevant information from the Notify handle (i.e.,
for a Mount notification, the media identifier and drive
identifier must be retrieved).
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-354
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Notify_Create(l),
•
VS_Notify_Destroy(l),
•
VS_Notify_Listen (l),
•
VS_Notify_SetFields(l),
•
VS_Table_GetFields(l)
Functions
601355 Rev A
API Functions
2-355
API Guide
VS_Notify_
Listen
VS_Notify_Listen listens for MediaClass callbacks from
VolServ.
Client registers a notify dispatch routine with the API using
either the VS_Global_SetFields or the
VS_Notify_SetFields function. Client is then responsible
for putting the API into a “listening” state by calling
VS_Notify_Listen. VS_Notify_Listen terminates
either after receiving a MediaClass callback and notifying the
client’s notify dispatch routine or after timing out.
Synopsis
int VS_Notify_Listen (VST_NOTIFY_HANDLE handle)
Arguments
•
Return Values
VS_Notify_Listen returns:
2-356
API Functions
handle = The notify handle used to listen for MediaClass
callbacks.
•
VSE_ERR_BADHANDLE - Specified handle was not a
notify handle.
•
VSE_ERR_NONE - Successfully received and processed a
callback.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
handle.
•
VSE_ERR_SELECT - An error occurred during a select
system call.
•
VSE_ERR_SIGNAL - A select system call was interrupted
by a signal.
601355 Rev A
API Guide
•
Example
VSE_ERR_TIMEOUT - The VolServ API timed out waiting
for MediaClass callbacks from VolServ.
1
2
3
4
5
6
7
8
9
10
11
21
22
23
24
25
26
27
28
29
30
31
601355 Rev A
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
API Functions
2-357
Functions
12
13
14
15
16
17
18
19
20
/****************************************
*********
*
* FUNCTION: vst_notify
*
* PURPOSE:
* This routine is used to test the notify
loop.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_notify( void )
#else
VST_BOOLEAN
vst_notify()
#endif
{
VST_BOOLEAN
done, rc;
int
i, count,
timeout;
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
t;
VST_TABLE_HANDLE
table;
VST_MEDIA_CLASS_NAME class,
newclass;
VST_NOTIFY_HANDLE
h;
API Guide
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
2-358
API Functions
printf(“*** Notify Parameters ***\n”
);
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
printf(“Number of Notifies to listen
==> “ );
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
printf(“Number of Timeouts to process
==> “ );
timeout = atoi(gets(input));
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
VSID_VERSION_NUMBER, versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
VSID_TIMEOUT_VALUE,
t,
601355 Rev A
API Guide
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
601355 Rev A
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
break;
default:
printf(“Select Error
%d\n”, i );
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
if ( timeout <= 0 )
{
API Functions
2-359
Functions
79
VSID_ENDFIELD );
API Guide
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112}
Notes
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
}
}
/* destroy the notify handle */
VS_Notify_Destroy ( h );
}
else
{
rc = VSE_FALSE;
}
return ( rc );
Client uses VS_Notify_GetFields to access the MediaClass
callback information in a notify handle.
If a VSE_ERR_SIGNAL is returned, any client error handling
routines that have been installed for that signal have been
called.
VS_Notify_Listen returns error codes instead of the normal
VST_BOOLEAN values (VSE_TRUE, VSE_FALSE). This
simplifies client code when performing asynchronous
processing. Client can use the “switch” statement on the return
code directly from the routine without having to retrieve error
codes.
2-360
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Notify_Create(l),
•
VS_Notify_Destroy(l),
•
VS_Notify_GetFields(l),
•
VS_Notify_SetFields(l)
Functions
601355 Rev A
API Functions
2-361
API Guide
VS_Notify_
SetFields
VS_Notify_SetFields sets the value of one or more fields
in a notify handle. A notify handle is used to pass notify
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Notify_SetFields
(VST_NOTIFY_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The notify handle where information is stored or
updated.
•
“…” = 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.
Parameters
Parameter Type
Description
VSID_NOTIFY_DISPATCH
(VST_NOTIFY_DISPATCH)
Function in the client’s program that the
VolServ API calls when a MediaClass callback
is received.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
that the VolServ API calls when a MediaClass
callback is received.
2-362
API Functions
601355 Rev A
API Guide
Parameter Type
Description
RPC program number of the client process
that the VolServ API calls when a MediaClass
callback is received. If
VSID_PROGRAM_NUMBER is not specified, the
program number defaults to 0. When
VSID_PROGRAM_NUMBER is allowed to default
to 0, the API software obtains a transient RPC
number.
VSID_PROTOCOL (VST_PROTOCOL)
RPC protocol that the VolServ API uses for
callbacks. The default VSID_PROTOCOL is
VSE_PROT_TCP.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) that the VolServ
API waits for a MediaClass callback from
VolServ before timing out.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process that
the VolServ API calls when a MediaClass
callback is received.
Return Values
601355 Rev A
VS_Notify_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_BADFIELD - An invalid parameter was specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a
notify handle.
•
VSE_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-363
Functions
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2-364
API Functions
/****************************************
*********
*
* FUNCTION: vst_notify
*
* PURPOSE:
* This routine is used to test the notify
loop.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_notify( void )
#else
VST_BOOLEAN
vst_notify()
#endif
{
VST_BOOLEAN
done, rc;
int
i, count,
timeout;
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
t;
VST_TABLE_HANDLE
table;
VST_MEDIA_CLASS_NAME class,
newclass;
VST_NOTIFY_HANDLE
h;
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
601355 Rev A
API Guide
32
33
34
35
36
37
38
39
40
41
42
49
50
51
52
53
54
55
56
57
58
59
60
61
62
601355 Rev A
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
printf(“Number of Notifies to listen
==> “ );
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
printf(“Number of Timeouts to process
==> “ );
timeout = atoi(gets(input));
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
VSID_VERSION_NUMBER,
versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
API Functions
2-365
Functions
43
44
45
46
47
48
printf(“*** Notify Parameters ***\n”
);
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
API Guide
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
2-366
API Functions
VSID_TIMEOUT_VALUE,
VSID_ENDFIELD );
t,
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
break;
default:
printf(“Select Error
%d\n”, i );
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
if ( timeout <= 0 )
601355 Rev A
API Guide
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112}
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
}
}
/* destroy the notify handle */
VS_Notify_Destroy ( h );
}
else
{
rc = VSE_FALSE;
}
return ( rc );
Functions
Notes
{
Client dispatch function must be prototypes as follows:
void NotifyClientDispatch (VST_NOTIFY_HANDLE handle)
RPC information (protocol, program, procedure, and version)
must be set to match the callback information for the
MediaClass group the user wants to monitor.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-367
API Guide
See Also
2-368
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Notify_Create(l),
•
VS_Notify_Destroy(l),
•
VS_Notify_GetFields(l),
•
VS_Notify_Listen(l)
601355 Rev A
API Guide
VS_Request_
Create
VS_Request_Create allocates a VolServ API request
handle. A request handle is used to pass request information to
and from VolServ.
Synopsis
VST_REQUEST_HANDLE VS_Request_Create (void)
Arguments
None
Return Values
VS_Request_Create returns:
A request handle, if one can be allocated.
•
NULL, if a request handle could not be allocated An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
601355 Rev A
Functions
Example
•
/****************************************
*********
*
* FUNCTION: vst_request_handle
*
* PURPOSE:
* This function tests a request handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_request_handle(void)
#else
VST_BOOLEAN vst_request_handle()
#endif
{
API Functions
2-369
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53 }
2-370
API Functions
VST_BOOLEAN
VST_REQUEST_HANDLE
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_REQUEST_STATE
VST_PRIORITY
rc = VSE_FALSE;
h;
RequestID;
RequestType;
State;
Priority;
/* create the handle */
h = VS_Request_Create();
if (h != (VST_REQUEST_HANDLE) NULL)
{
/* get values from user */
printf(“*** Request Handle
***\n”);
printf(“Enter request id ==> “);
RequestID = atol(gets(input));
printf(“Enter request type ==> “);
RequestType = atoi(gets(input));
printf(“Enter request state ==>
“);
State = atoi(gets(input));
printf(“Enter Priority ==> “);
Priority = atoi(gets(input));
/* set the fields */
rc = VS_Request_SetFields(h,
VSID_REQUEST_ID,
RequestID,
VSID_REQUEST_TYPE,
RequestType,
VSID_REQUEST_STATE,
State,
VSID_PRIORITY,
Priority,
VSID_ENDFIELD);
if (rc)
{
vst_print_request(h);
}
VS_Request_Destroy(h);
}
return(rc);
601355 Rev A
API Guide
Notes
None
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Request_Destroy(l),
•
VS_Request_GetFields(l),
•
VS_Request_SetFields(l)
Functions
601355 Rev A
API Functions
2-371
API Guide
VS_Request_
Destroy
VS_Request_Destroy deallocates a VolServ API request
handle that was allocated with VS_Request_Create. A
request handle is used to pass request information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_Request_Destroy
(VST_REQUEST_HANDLE handle)
Arguments
•
Return Values
VS_Request_Destroy returns:
Example
2-372
handle = The request handle to be destroyed.
•
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
request handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_request_handle
4 *
5 * PURPOSE:
6 * This function tests a request handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-373
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_request_handle(void)
14 #else
15
VST_BOOLEAN vst_request_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc = VSE_FALSE;
19
VST_REQUEST_HANDLE
h;
20
VST_REQUEST_ID
RequestID;
21
VST_REQUEST_TYPE
RequestType;
22
VST_REQUEST_STATE
State;
23
VST_PRIORITY
Priority;
24
25
/* create the handle */
26
h = VS_Request_Create();
27
if (h != (VST_REQUEST_HANDLE) NULL)
28
{
29
/* get values from user */
30
printf(“*** Request Handle
***\n”);
31
printf(“Enter request id ==> “);
32
RequestID = atol(gets(input));
33
printf(“Enter request type ==> “);
34
RequestType = atoi(gets(input));
35
printf(“Enter request state ==>
“);
36
State = atoi(gets(input));
37
printf(“Enter Priority ==> “);
38
Priority = atoi(gets(input));
39
/* set the fields */
40
rc = VS_Request_SetFields(h,
41
VSID_REQUEST_ID,
RequestID,
42
VSID_REQUEST_TYPE,
RequestType,
43
VSID_REQUEST_STATE,
State,
44
VSID_PRIORITY,
Priority,
45
VSID_ENDFIELD);
API Guide
46
47
48
49
50
51
52
53 }
if (rc)
{
vst_print_request(h);
}
VS_Request_Destroy(h);
}
return(rc);
Notes
After VS_Request_Destroy has been called for a request
handle, that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Request_Create(l),
•
VS_Request_GetFields(l),
•
VS_Request_SetFields(l)
2-374
API Functions
601355 Rev A
API Guide
VS_Request_GetFields retrieves information associated
with a request handle. A request handle is used to pass request
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Request_GetFields
(VST_REQUEST_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The request 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.
Parameters
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY *)
Pointer to the execution priority of this request.
VSID_REQUEST_ID (VST_REQUEST_ID *)
Pointer to the request identifier associated
with the indicated request handle.
VSID_REQUEST_STATE
(VST_REQUEST_STATE *)
Pointer to the execution state of the request.
Valid VSID_REQUEST_STATE values are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-375
Functions
VS_Request_
GetFields
API Guide
Parameter Type
Description
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE *)
Pointer to the request type of the request.
Valid VSID_REQUEST_TYPE values are
enumerated in the vs_types.h file.
VSID_TIME (VST_TIME *)
Pointer to the arrival time of the request.
Return Values
Example
2-376
VS_Request_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 a
request handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_print_request
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a request handle.
8 *
9 * PARAMETERS:
10 * h : the request handle to print
11 *
12 ****************************************
*********/
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-377
Functions
13 #ifdef ANSI_C
14
void
vst_print_request(VST_REQUEST_HAN
DLE h)
15 #else
16
void vst_print_request(h)
17
VST_REQUEST_HANDLE h;
18 #endif
19 {
20
VST_REQUEST_ID
RequestID;
21
VST_REQUEST_TYPE
RequestType;
22
VST_TIME
InTime;
23
VST_REQUEST_STATE
State;
24
VST_PRIORITY
Priority;
25
26
VS_Request_GetFields(h,
27
VSID_REQUEST_ID,
&RequestID,
28
VSID_REQUEST_TYPE,
&RequestType,
29
VSID_TIME,
&InTime,
30
VSID_REQUEST_STATE,
&State,
31
VSID_PRIORITY,
&Priority,
32
VSID_ENDFIELD);
33
printf(“******Request
Handle******\n”);
34
printf(“Request ID = %d\n”,
RequestID);
35
printf(“Request Type = %d\n”,
RequestType);
36
printf(“Time = %s”, ctime((time_t *)
&InTime));
37
printf(“Request state = %d\n”,
State);
38
printf(“Priority = %d\n”, Priority);
39 }
API Guide
Notes
VSID_TIME is kept as a long integer. Use the ctime function to
convert it to a string.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-378
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Request_Create(l),
•
VS_Request_Destroy(l),
•
VS_Request_SetFields(l),
•
VSCMD_RequestQuery(l)
601355 Rev A
API Guide
VS_Request_SetFields sets the value of one or more
fields in a request handle. A request handle is used to pass
request information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Request_SetFields
(VST_REQUEST_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The request handle where information is stored
or updated.
•
“…” = Each pair of arguments consists of a parameter
identifier, followed by the value of the field to store. 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.
Parameters
Parameter Type
VSID_PRIORITY (VST_PRIORITY)
601355 Rev A
Description
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
API Functions
2-379
Functions
VS_Request_
SetFields
API Guide
Parameter Type
VSID_REQUEST_ID (VST_REQUEST_ID)
Description
Identifier of the request (assigned by VolServ)
associated with the specified request handle.
A valid request identifier must be specified in
the yyyyddmm format where yyyy
represents the year, dd represents the day,
and mm is a month.
VSID_REQUEST_STATE
(VST_REQUEST_STATE)
The execution state of the request. Valid
VSID_REQUEST_STATE values are
enumerated in the vs_types.h file.
VSID_REQUEST_TYPE
(VST_RQUEST_TYPE)
The request type to be associated with the
request handle. Valid VSID_REQUEST_TYPE
values are enumerated in the vs_types.h file.
VSID_TIME (VST_TIME)
Arrival time of the request.
Return Values
2-380
API Functions
VS_Request_SetFields returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_FIELD - An invalid parameter was specified.
•
VSE_ERR_BADHANDLE - Specified handle was not a
request handle.
•
VSE_ERR_BADSIZE - 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.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
31
32
33
34
35
36
37
38
601355 Rev A
/* create the handle */
h = VS_Request_Create();
if (h != (VST_REQUEST_HANDLE) NULL)
{
/* get values from user */
printf(“*** Request Handle
***\n”);
printf(“Enter request id ==> “);
RequestID = atol(gets(input));
printf(“Enter request type ==> “);
RequestType = atoi(gets(input));
printf(“Enter request state ==>
“);
State = atoi(gets(input));
printf(“Enter Priority ==> “);
Priority = atoi(gets(input));
API Functions
2-381
Functions
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/****************************************
*********
*
* FUNCTION: vst_request_handle
*
* PURPOSE:
* This function tests a request handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_request_handle(void)
#else
VST_BOOLEAN vst_request_handle()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_REQUEST_HANDLE
h;
VST_REQUEST_ID
RequestID;
VST_REQUEST_TYPE
RequestType;
VST_REQUEST_STATE
State;
VST_PRIORITY
Priority;
API Guide
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53 }
/* set the fields */
rc = VS_Request_SetFields(h,
VSID_REQUEST_ID,
RequestID,
VSID_REQUEST_TYPE,
RequestType,
VSID_REQUEST_STATE,
State,
VSID_PRIORITY,
Priority,
VSID_ENDFIELD);
if (rc)
{
vst_print_request(h);
}
VS_Request_Destroy(h);
}
return(rc);
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-382
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Request_Create(l),
•
S_Request_Destroy(l),
•
VS_Request_GetFields(l)
601355 Rev A
API Guide
VS_Select
VS_Select requests the VolServ API to wait for command
status from VolServ when the API in operating in asynchronous
mode.
In asynchronous mode, the client issues a VolServ command
through the API, immediately receives initial status for the
command, issues VS_Select to request that the API wait for
intermediate and/or final status, and continues processing.
When the API receives intermediate or final status from
VolServ, it calls the specified client dispatch routine to process
the status and the outstanding VS_Select function
terminates. It is the client’s responsibility to issue the
VS_Select for each intermediate and final status expected for
a command.
int VS_Select (void)
Arguments
None
Return Values
VS_Select returns:
601355 Rev A
Functions
Synopsis
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_NONE - Successfully received and processed
status.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_SELECT - An error occurred during a select
system call.
API Functions
2-383
API Guide
Example
•
VSE_ERR_SIGNAL - A select system call was interrupted
by a signal.
•
VSE_ERR_TIMEOUT - The VolServ API timed out waiting
for status from VolServ.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
2-384
API Functions
/****************************************
*********
*
* FUNCTION: vst_select
*
* PURPOSE:
* This function tests the VS_Select
loop.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_select ( void )
#else
VST_BOOLEAN vst_select ()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
errcode;
errcode = VS_Select();
switch (errcode)
{
case VSE_ERR_NONE:
printf(“*** No Error -Successful Operation ***\n“);
rc = VSE_TRUE;
break;
case VSE_ERR_TIMEOUT:
printf(“*** Select Timed Out
***\n”);
break;
601355 Rev A
API Guide
31
32
33
34
35
36 }
Notes
default:
printf(“*** A Select Error
Occurred ***\n”);
break;
}
return(rc);
VS_Select calls fail if VS_Initialize has not been
invoked.
VS_Select is used only when the API is operating in
asynchronous mode. Therefore, clients that use synchronous
processing do not use the VS_Select routine.
The total amount time the API waits for status is
VSID_TIMEOUT_VALUE.
VS_Select returns error codes instead of the normal
VST_BOOLEAN values (VSE_TRUE, VSE_FALSE). This
simplifies client code when performing asynchronous
processing. Client can use the “switch” statement on the return
code directly from the routine without having to retrieve error
codes.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetDefaults(l),
•
VS_Initialize(l)
API Functions
2-385
Functions
The VolServ API uses the client dispatch routine identification
information, set with the VS_Global_SetDefaults function
or with the command default function, to determine which
routine to notify when intermediate and final command status is
received.
API Guide
VS_Status_
GetFields
VS_Status_GetFields retrieves information associated
with a status handle. A status handle is used to pass status
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Status_GetFields
(VST_STATUS_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The status 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.
Parameters
Parameter Type
VSID_ACTION_CODE
(VST_ACTION_CODE *)
Description
Pointer to the first entry in the action code
table.
VSID_ACTION_CODE_ENTRY (int)
Index of the appropriate entry in the action
code table.
(VST_ACTION_CODE *)
Pointer to the appropriate entry in the action
code table.
2-386
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the action code table associated
with this status.
VSID_ARCHIVE_HANDLE
(VST_ARCHIVE_HANDLE *)
Pointer to the first archive handle in the
archive handle table.
VSID_ARCHIVE_HANDLE_ENTRY (int)
Index of the appropriate archive handle in the
archive handle table.
(VST_ARCHIVE_HANDLE *)
Pointer to the appropriate archive handle in
the archive handle table.
VSID_ARCHIVE_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the archive handle table associated
with this status.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Pointer to the name of the archive associated
with this status. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_ARCHIVEMEDIACLASS_HANDLE
(VST_ARCHIVE_MEDIACLAS_HANDLE *)
Pointer to the first archive media class handle
in the archive media class table.
VSID_ARCHIVEMEDIACLASS_HANDLE_
ENTRY (int)
Index of the appropriate archive media class
handle in the archive media class handle
table.
(VST_ARCHIVEMEDIACLASS_HANDLE *)
Pointer to the appropriate archive media class
handle in the archive media class handle
table.
VSID_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE *)
Pointer to the archive media class handle
table associated with this status.
VSID_COMPONENT_HANDLE
(VST_COMPONENT_HANDLE *)
Pointer to the first component handle in the
component handle table.
VSID_COMPONENT_HANDLE_ENTRY (int)
Index of the appropriate component handle in
the component handle table.
(VST_COMPONENT_HANDLE *)
Pointer to the appropriate component handle
in the component handle table.
601355 Rev A
API Functions
2-387
Functions
VSID_ACTION_CODE_TABLE
(VST_TABLE_HANDLE *)
API Guide
Parameter Type
Description
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the component handle table
associated with this status.
VSID_COMP_ID (VST_COMPONENT_ID *)
Pointer to the first component identifier in the
component identifier table.
VSID_COMP_ID_ENTRY (int)
Index of the appropriate component identifier
in the component identifier table.
(VST_COMPONENT_ID *)
Pointer to the appropriate component identifier
in the component identifier table.
VSID_COMP_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the component identifier table
associated with this status.
VSID_COMP_STATE
(VST_COMPONENT_STATE *)
Pointer to the component state for this status.
Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE *)
Pointer to the first entry in the connect handle
table.
VSID_CONNECT_HANDLE_ENTRY (int)
Index of the appropriate connect handle in
the connect handle table.
(VST_CONNECT_HANDLE *)
Pointer to the appropriate connect handle in
the connect handle table.
VSID_CONNECT_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the connect handle table associated
with this status.
VSID_DRIVE_HANDLE
(VST_DRIVE_HANDLE *)
Pointer to the first drive handle in the drive
handle table.
VSID_DRIVE_HANDLE_ENTRY (int)
Index the appropriate drive handle in the
drive handle table.
(VST_DRIVE_HANDLE *)
Pointer to the appropriate drive handle in the
drive handle table.
VSID_DRIVE_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive handle table associated
with this status.
2-388
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the first drive identifier in the drive
identifier table.
VSID_DRIVE_ID_ENTRY (int)
Index of the appropriate drive identifier in the
drive identifier table.
(VST_DRIVE_ID *)
Pointer to the appropriate drive identifier in the
drive identifier table.
VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive identifier table associated
with this status.
VSID_DRIVEPOOL_HANDLE
(VST_DRIVE_POOL_HANDLE *)
Pointer to the first drive pool handle in the
drive pool handle table.
VSID_DRIVEPOOL_HANDLE_ENTRY (int)
Index of the appropriate drive pool handle in
the drive pool handle table.
(VST_DRIVEPOOL_HANDLE *)
Pointer to the appropriate drive pool handle in
the drive pool handle table.
VSID_DRIVEPOOL_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drive pool handle table
associated with this status.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Pointer to the name of the drive pool group.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the identifier of the enterprise, if any,
to receive command status.
VSID_ERROR_CODE
(VST_VOLERR_CODE *)
Pointer to the first error code in the error code
table.
VSID_ERROR_CODE_ENTRY (int)
Index of the appropriate error code in the error
code table.
(VST_VOLERR_CODE *)
Pointer to the appropriate error code in the
error code table.
VSID_ERROR_TABLE
(VST_TABLE_HANDLE *)
Pointer to the error code table associated with
this status.
VSID_FIELD (int *)
Pointer to the first field in the user-defined
media statistics field table.
601355 Rev A
API Functions
2-389
Functions
VSID_DRIVE_ID (VST_DRIVE_ID *)
API Guide
Parameter Type
Description
VSID_FIELD_ENTRY (int)
The index of the appropriate field in the
user-defined media statistics field table.
(int *)
Pointer to the appropriate field in the
user-defined media statistics field table.
VSID_FIELD_TABLE
(VST_TABLE_HANDLE *)
Pointer to the user-defined media statistics
field table associated with this status.
VSID_LOCK_ID (VST_LOCK_ID *)
Pointer to the lock identifier associated with
this status.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Pointer to the MediaClass name associated
with this status.
VSID_MEDIA_HANDLE
(VST_MEDIA_HANDLE *)
Pointer to the first media handle in the media
handle table.
VSID_MEDIA_HANDLE_ENTRY (int)
The index of the appropriate media handle in
the media handle table.
(VST_MEDIA_HANDLE *)
Pointer to the appropriate media handle in the
media handle table.
VSID_MEDIA_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media handle table associated
with this status.
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the first media identifier in the media
identifier table.
VSID_MEDIA_ID_ENTRY (int)
The index of the appropriate entry in the
media identifier table.
(VST_MEDIA_ID *)
Pointer to the appropriate media identifier in
the media identifier table.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media identifier table associated
with this status.
VSID_MEDIACLASS_HANDLE
(VST_MEDIACLASS_HANDLE *)
Pointer to the first MediaClass handle in the
MediaClass handle table.
VSID_MEDIACLASS_HANDLE_ENTRY (int)
The index of the appropriate MediaClass
handle in the MediaClass handle table
2-390
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the appropriate MediaClass handle
in the MediaClass handle table.
VSID_MEDIACLASS_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the MediaClass handle table
associated with this status.
VSID_MEDIATYPE_HANDLE
(VST_MEDIATYPE_HANDLE *)
Pointer to the first media type handle in the
media type handle table.
VSID_MEDIATYPE_HANDLE_ENTRY (int)
The index of the appropriate media type
handle in the media type handle table.
(VST_MEDIATYPE_HANDLE *)
Pointer to the appropriate media type handle
in the media type handle table.
VSID_MEDIATYPE_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the media type handle table
associated with this status.
VSID_NUMBER_ACTION_CODES (int *)
Pointer to the number of action codes in the
action code table.
VSID_NUMBER_ARCHIVE_HANDLES (int *)
Pointer to the number of archive handles in
the archive handle table.
VSID_NUMBER_COMP_IDS (int *)
Pointer to the number of component ids in the
component identifier table.
VSID_NUMBER_COMPONENT_HANDLES
(int *)
Pointer to the number of component handles
in the component handle table.
VSID_NUMBER_CONNECT_HANDLES (int
*)
Pointer to the number of connect handles in
the connect handle table.
VSID_NUMBER_DRIVE_HANDLES (int *)
Pointer to the number of drive handles in the
drive handle table.
VSID_NUMBER_DRIVE_IDS (int *)
Pointer to the number of drive ids in the drive
id table.
VSID_NUMBER_DRIVEPOOL_HANDLES
(int *)
Pointer to the number of drive pool handles in
the drive pool handle table.
VSID_NUMBER_ERROR_CODES (int *)
Pointer to the number of error codes in the
error code table.
601355 Rev A
API Functions
2-391
Functions
(VST_MEDIACLASS_HANDLE *)
API Guide
Parameter Type
Description
VSID_NUMBER_FIELDS (int *)
Pointer to the number of field ids in the field
identifier table.
VSID_NUMBER_MEDIA_HANDLES (int *)
Pointer to the number of media handles
present in the media handle table.
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of media ids in the
media id table.
VSID_NUMBER_MEDIACLASS_HANDLES
(int *)
Pointer to the number of media class handles
in the media class handle table.
VSID_NUMBER_MEDIATYPE_HANDLES
(int *)
Pointer to the number of media type handles
in the media type handle table.
VSID_NUMBER_REQUEST_IDS (int *)
Pointer to the number of request ids present in
the request id table.
VSID_NUMBER_REQUEST_HANDLES
(int *)
Pointer to the number of request handles in
the request handle table.
VSID_PID (VST_PID *)
Pointer to the VolServ identifier for the Ping
status.
VSID_QRY_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the enterprise identifier, if any, for
the Connect Query command.
VSID_QRY_OPTION (VST_QRY_OPTION *)
Pointer to the query option for this status.
VSID_REQUEST_HANDLE
(VST_REQUEST_HANDLE *)
Pointer to the first request handle in the
request handle table.
VSID_REQUEST_HANDLE_ENTRY (int)
The index of the appropriate request handle in
the request handle table.
(VST_REQUEST_HANDLE *)
Pointer to the appropriate request handle in
the request handle table.
VSID_REQUEST_HANDLE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the request handle table associated
with this status.
VSID_REQUEST_ID (VST_REQUEST_ID *)
Pointer to the request identifier of the target
command for a Cancel or Reprioritize request.
2-392
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the sequence number of this status.
Initial status for a command request is
sequence number 0. Sequence numbers for
subsequent statuses for the same command
request are assigned as one-up numbers. For
example, the first intermediate status (if there
is an intermediate status) or the final status (if
there is no intermediate status) is sequence
number 1.
VSID_SEQUENCE_TABLE
(VST_TABLE_HANDLE *)
Pointer to the sequence numbers (in table
format) of the statuses received for this
command.
VSID_STATUS_CODE
(VST_STATUS_CODE *)
Pointer to the status code for this status.
Indicates whether the command was
successful or failed. Valid
VSID_STATUS_CODE values are enumerated
in the vs_types.h file.
VSID_STATUS_TYPE
(VST_STATUS_TYPE *)
Pointer to the status type (intermediate or
final) for this status. Valid
VSID_STATUS_TYPE values are enumerated
in the vs_types.h file.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
Pointer to the enterprise identifier for a
ConnectQuery or Disconnect command.
VSID_USER_FIELD (VST_USER_FIELD)
Pointer to the user field contents for the
associated command. USER_FIELD is 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.
VSID_WAIT_REASON
(VST_WAIT_REASON *)
Pointer to the wait reason for an intermediate
status. Valid VSID_WAIT_REASON values are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-393
Functions
VSID_SEQUENCE_NUM (int *)
API Guide
Return Values
Example
VS_Status_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 a
request handle.
•
VSE_ERR_BADSIZE - 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2-394
API Functions
/****************************************
*********
*
* FUNCTION: vst_mediaquery_execute_sync
*
* PURPOSE:
* This executes the VSCMD_MediaQuery API
call in a
* synchronous mode. It shows how to
process status
* in synchronous mode without using a
dispatch
* routine.
*
* PARAMETERS:
* none
*
****************************************
*********/
601355 Rev A
API Guide
601355 Rev A
API Functions
2-395
Functions
15 #ifdef ANSI_C
16
VST_BOOLEAN
vst_mediaquery_execute_sync(void)
17 #else
18
VST_BOOLEAN
vst_mediaquery_execute_sync()
19 #endif
20 {
21
VST_BOOLEAN
rc = VSE_FALSE;
22
VST_QUERY_OPTION
queryopt;
23
int
i;
24
int
count;
25
char
*
medialist[VST_MAX_ITEMS];
26
VST_COMMAND_HANDLE
cmd;
27
VST_STATUS_HANDLE
status;
28
VST_TABLE_HANDLE
mediahandletable;
29
VST_MEDIA_HANDLE
media;
30
31
/* get parameters from user */
32
printf(“*** Media Query parameters
***\n” );
33
printf(“0) Query by media list, 1)
Query all ==> “ );
34
queryopt = atoi(gets(input));
35
36
if (queryopt == 0)
37
{
38
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
39
}
40
41
/* create the command handle */
42
/* Note that the command handle is
not */
43
/* destroyed in this routine, but in
*/
44
/* vst_dispatch when final status is
*/
45
/* received */
API Guide
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
2-396
API Functions
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead,it is processed in the
*/
/* vst_dispatch routine. */
/* Also, note that default values,
such as */
/* timeout, value retry limit, and
priority */
/* are set as default parameters.
*/
rc = VSCMD_MediaQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_MEDIA_ID_LIST, count,
medialist,
VSID_CLIENT_DISPATCH, NULL,
/* no dispatch routine */
VSID_STATUS_WAIT_FLAG,
VSE_TRUE,
/* synchronous mode */
VSID_ENDFIELD);
if (rc)
{
/* the command was successful
*/
/* get the status */
VS_Command_GetFields(cmd,
VSID_STATUS_HANDLE, &status,
VSID_ENDFIELD);
/* get the media handle table
from the */
/* status handle */
VS_Status_GetFields(status,
601355 Rev A
API Guide
75
76
77
78
VSID_MEDIA_HANDLE_TABLE
&mediahandletable,
VSID_ENDFIELD);
/* Get the number of entries in
the table */
79
VS_Table_GetFields(mediahandletab
le,
80
81
82
83
88
89
90
91
92
93
94
95
96
97 }
Notes
VS_Table_GetFields(mediahandletab
le,
VSID_TABLE_ENTRY,
i, &media,
VSID_ENDFIELD);
vst_print_media(media);
}
}
/* destroy the command */
VS_Command_Destroy(cmd);
}
return ( rc );
The parameters listed below require that two arguments be
passed instead of one.
•
601355 Rev A
/* loop through the table and
print out */
/* the entries */
for (i = 0; i < count; i++)
{
The first argument passed is the index of the entry in the
appropriate table.
API Functions
2-397
Functions
84
85
86
87
VSID_NUMBER_ENTRIES, &count
VSID_ENDFIELD);
API Guide
•
The second argument is a pointer to the location where the
retrieved value is stored.
-
VSID_ACTION_CODE_ENTRY,
-
VSID_ARCHIVE_HANDLE_ENTRY,
-
VSID_ARCHIVEMEDIACLASS_ENTRY,
-
VSID_COMPONENT_ENTRY,
- VSID_COMP_ID_ENTRY,
- VSID_CONNECT_HANDLE_ENTRY,
- VSID_DRIVE_HANDLE_ENTRY,
- VSID_DRIVEPOOL_HANDLE_ENTRY,
- VSID_ERROR_CODE_ENTRY,
-
VSID_FIELD_ENTRY,
-
VSID_MEDIA_HANDLE_ENTRY,
-
VSID_MEDIA_ID_ENTRY,
-
VSID_MEDIACLASS_HANDLE_ENTRY,
-
VSID_MEDIATYPE_HANDLE_ENTRY,
- VSID_REQUEST_HANDLE_ENTRY
Table entries are zero-based (like arrays in C). The first entry in
an empty table is stored in position 0, the second entry in a table
is stored in position 1, and the nth entry in a table is stored in
position n-1.
2-398
API Functions
601355 Rev A
API Guide
The status handle is associated with a command handle. To
retrieve status information, the status handle must first be
retrieved from the command handle using
VS_Command_GetFields.
The VSID_STATUS_TYPE, VSID_STATUS_CODE,
VSID_USER_FIELD and VSID_REQUEST_ID parameters are
valid status handle fields for all VolServ requests.
The status fields that are valid for each command are identified
in the “Notes” paragraph for that command. A matrix
showing which status fields are valid for which commands is in
Appendix A.
Note
Functions
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Command_GetFields(l),
•
VS_Error_GetFields(l)
API Functions
2-399
API Guide
VS_Table_
AddEntry
VS_Table_AddEntry adds an entry to the specified table at
the first available location.
When a client adds an entry to a table using
VS_Table_AddEntry, the client is responsible for
allocating and maintaining the space to contain the information
maintained in the table.
Synopsis
VST_BOOLEAN VS_Table_AddEntry
(VST_TABLE_HANDLE handle,
void * entry)
Arguments
•
handle = Handle of the table where an entry is added.
•
entry = Pointer to the data to be stored in the table.
Return Values
2-400
API Functions
VS_Table_AddEntry returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_BADENTRY - Pointer to store was null.
•
VSE_ERR_BADHANDLE - Specified handle was not a table
handle.
•
VSE_ERR_FULL - The table is full and the entry could not
be added.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
601355 Rev A
API Functions
2-401
Functions
13
14
/****************************************
*********
*
* FUNCTION:
vst_createarchivemediaclass_execu
te
*
* PURPOSE:
* This executes the
VSCMD_CreateArchiveMediaClass
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createarchivemediaclass_execu
te(void)
#else
VST_BOOLEAN
vst_createarchivemediaclass_execu
te()
#endif
{
int
i;
int
count;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_CAPACITY
capacity;
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
highmark;
VST_LOW_MARK
lowmark;
VST_PRIORITY
migpri;
VST_ARCHIVE_NAME
targetarchive;
API Guide
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
2-402
API Functions
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
ST_COMPONENT_ID
VST_COMMAND_HANDLE
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
/* these parameters only need to
be set */
/* if the archivemediaclass is
being */
/* set up to support migration */
printf(“Enter Target Archive ==> “
);
601355 Rev A
API Guide
58
59
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
60
61
VSCMD_CreateArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
62
63
64
65
66
67
72
73
74
75
76
77
78
79
80
81
82
83
84
601355 Rev A
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
if (comphandletable
==(VST_TABLE_HANDLE)NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
API Functions
2-403
Functions
68
69
70
71
}
API Guide
85
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
VSID_ENDFIELD);
86
87
88
89
VS_Table_AddEntry(comphandletable
,comphandle);
}
/* This also only needs to be set
if it is */
/* actually being used. */
/* It is not needed otherwise. */
90
91
92
93
94
VSCMD_CreateArchiveMediaClass_Set
Defaults(
VSID_COMPONENT_HANDLE_TABLE
comphandletable,
VSID_ENDFIELD);
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
2-404
API Functions
}
/* create the command handle */
/* Note that the command handle is not
destroyed */
/* in this routine, but in
vst_dispatch */
/* when final status is received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
vst_dispatch */
/* Also, note that default values
such as */
601355 Rev A
API Guide
110
111
112
113
114
115
116
117
118
119
120
121
122}
Notes
}
return ( rc );
A table cannot store NULL pointers.
VS_Table_AddEntry determines the position in the table to
store the new entry using a first available algorithm.
Table entries are zero-based (like arrays in C). The first entry in
an empty table is stored in position 0, the second entry in a table
is stored in position 1, and the nth entry in a table is stored in
position n-1.
601355 Rev A
API Functions
2-405
Functions
/* timeout value retry limit, and
priority */
/* are set as default parameters.
*/
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
API Guide
See Also
2-406
API Functions
•
VS_Table_Create(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l),
•
VS_Table_CreateAddEntry(l),
•
VS_Table_RemoveEntry(l)
601355 Rev A
API Guide
VS_Table_
Create
VS_Table_Create allocates a VolServ API table handle. A
table handle is used to pass table information to and from
VolServ.
A table is used to store a group of pointers of the same type
within a single construct (much like an array or a linked list).
VST_TABLE_HANDLE VS_Table_Create
(VST_HANDLE_TYPE type,
int size)
Arguments
•
type = The type of the pointers to be stored in the table.
Valid TableCreate value types are enumerated in the
vs_types.h file.
•
size = The maximum number of entries to stored in the
table.
Return Values
601355 Rev A
VS_Table_Create returns:
•
A table handle, if one can be allocated.
•
NULL, if a table handle cannot be allocated. An appropriate
error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
API Functions
2-407
Functions
Synopsis
API Guide
Example
2-408
1
/****************************************
*********
2 *
3 * FUNCTION:
vst_createarchivemediaclass_execu
te
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_CreateArchiveMediaClass
7 * API call.
8 *
9 * PARAMETERS:
10 * none
11
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_createarchivemediaclass_execu
te(void)
15 #else
16
VST_BOOLEAN
vst_createarchivemediaclass_execu
te()
17 #endif
18 {
19
int
i;
20
int
count;
21
VST_BOOLEAN
rc =
VSE_FALSE;
22
VST_ARCHIVE_NAME
archive;
23
VST_MEDIA_CLASS_NAME
mediaclass;
24
VST_CAPACITY
capacity;
25
VST_ARCHIVE_ACTION_OPTION action;
26
VST_HIGH_MARK
highmark;
27
VST_LOW_MARK
lowmark;
28
VST_PRIORITY
migpri;
29
VST_ARCHIVE_NAME
targetarchive;
API Functions
601355 Rev A
API Guide
30
31
32
33
34
35
36
37
38
39
40
41
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
601355 Rev A
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
/* these parameters only need to
be set */
/* if the archivemediaclass is
being */
/* set up to support migration. */
printf(“Enter Target Archive ==> “
);
API Functions
2-409
Functions
42
43
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
ST_COMPONENT_ID
VST_COMMAND_HANDLE
API Guide
59
60
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
61
62
VSCMD_CreateArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
2-410
API Functions
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
601355 Rev A
API Guide
86
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
VSID_ENDFIELD);
87
88
89
90
VS_Table_AddEntry(comphandletable
,comphandle);
}
/* This also only needs to be set
if it is */
/* actually being used. */
/* It is not needed otherwise. */
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
601355 Rev A
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is not
destroyed*/
/* in this routine, but in
vst_dispatch when */
/* final status is received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
vst_dispatch */
/* routine. Also, note that
default values */
API Functions
2-411
Functions
VSCMD_CreateArchiveMediaClass_Set
Defaults(
API Guide
111
/* such as timeout, value retry
limit, and */
/* priority are set as default
parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
112
113
114
115
116
117
118
119
120
121
122
123}
Notes
}
return ( rc );
Client adds entries with the VS_Table_AddEntry,
VS_Table_SetFields, and/or
VS_Table_CreateAddEntry functions.
When a client adds an entry to a table using the
VS_Table_AddEntry or VS_Table_SetFields
function, the client is responsible for allocating and maintaining
the space to contain the information maintained in the table.
When a client adds an entry to a table using the
VS_Table_CreateAddEntry function, the API allocates
space for a table entry, copies the client’s data to the allocated
space, and adds the entry to the specified table. After calling
VS_Table_CreateAddEntry, a client is no longer
required to maintain the space containing the information added
to the table.
2-412
API Functions
601355 Rev A
API Guide
Client deletes entries from a table with the
VS_Table_RemoveEntry function. If the entry to be
deleted from the table was added with either the
VS_Table_AddEntry or the VS_Table_SetFields
function, it is the client’s responsibility to free the space for the
entry after it has been removed from the table. If the entry to be
deleted from the table was added with the
VS_Table_CreateAddEntry function, the API frees the
space for the entry after it has been removed from the table.
See Also
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l),
•
VS_Table_AddEntry(l),
•
VS_Table_CreateAddEntry(l),
•
VS_Table_RemoveEntry(l)
Functions
601355 Rev A
•
API Functions
2-413
API Guide
VS_Table_
CreateAddEntry
VS_Table_CreateAddEntry adds an entry to the
specified table at the first available location.
Synopsis
VST_BOOLEAN VS_Table_CreateAddEntry
(VST_TABLE_HANDLE handle,
void * entry,
int size)
Arguments
•
handle = Handle of the table where the specified entry is
added.
•
entry = Pointer to the entry to be copied and added to the
specified table.
•
size = The size, in bytes, of the entry to be copied and
added to the specified table.
Return Values
2-414
API Functions
When a client adds an entry to a table using
VS_Table_CreateAddEntry, the VolServ API allocates
space for a table entry, copies the client’s data to the allocated
space, and adds an entry to the specified table for the copied
data. After calling VS_Table_CreateAddEntry, a client is
not required to maintain the information that has been stored in
the table.
VS_Table_CreateAddEntry returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_BADENTRY - Pointer to the entry to be stored
was null.
601355 Rev A
API Guide
Example
•
VSE_ERR_BADHANDLE - Specified handle was not a table
handle.
•
VSE_ERR_FULL - The table is full and the entry could not
be added
•
VSE_ERR_NULLHANDLE -Specified handle was a null
pointer.
•
VSE_ERR_OUTOFMEM - The allocation request for space
to copy the client’s data failed.
1
12
13
14
15
16
17
18
19
20
21
22
23
24
25
601355 Rev A
API Functions
2-415
Functions
2
3
4
5
6
7
8
9
10
11
/****************************************
*********
*
* FUNCTION: vst_table_handle
*
* PURPOSE:
* This function tests the table handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_table_handle(void)
#else
VST_BOOLEAN vst_table_handle()
#endif
{
VST_BOOLEAN
rc =
VSE_TRUE;
VST_TABLE_HANDLE
tableh;
int
numdrives;
int
i;
VST_DRIVE_ID
testdriveid
= 9999;
int
numentries;
VST_DRIVE_ID
* ip;
API Guide
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
2-416
API Functions
printf(“*** Table Handle test
***\n”);
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
}
/* get the number of entries in the
table */
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
VSID_ENDFIELD);
/* loop through the table and print
the entries */
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY,
i, &ip,
VSID_ENDFIELD);
/* remove the entry from the table
*/
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
601355 Rev A
API Guide
55
56
57
58
59
60 }
Notes
printf(“Drive ID #%d = %d\n”, i,
*ip);
}
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
A table cannot store NULL pointers.
VS_Table_CreateAddEntry determines the location in the
table to store the entry using a first available algorithm.
See Also
601355 Rev A
•
VS_Table_AddEntry(l),
•
VS_Table_Create(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_RemoveEntry(l),
•
VS_Table_SetFields(l)
API Functions
2-417
Functions
Table entries are zero-based (like arrays in C). The first entry in
an empty table is stored in position 0, the second entry in a table
is stored in position 1, and the nth entry in a table is stored in
position n-1.
API Guide
VS_Table_
Destroy
VS_Table_Destroy deallocates a VolServ API table handle
that was allocated with the VS_Table_Create function. A
table handle is used to pass table information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_Table_Destroy
(VST_TABLE_HANDLE handle)
Arguments
•
Return Values
VS_Table_Destroy returns:
Example
2-418
handle = The table handle to be destroyed.
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
•
VSE_ERR_BADHANDLE - Specified handle was not a table
handle.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_table_handle
4 *
5 * PURPOSE:
6 * This function tests the table handle.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-419
Functions
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_table_handle(void)
14 #else
15
VST_BOOLEAN vst_table_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_TRUE;
19
VST_TABLE_HANDLE
tableh;
20
int
numdrives;
21
int
i;
22
VST_DRIVE_ID
testdriveid
= 9999;
23
int
numentries;
24
VST_DRIVE_ID
* ip;
25
26
printf(“*** Table Handle test
***\n”);
27
printf(“How many drives? “);
28
numdrives = atoi(gets(input));
29
30
/* create the table handle */
31
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
/* generate drive ids */
34
for (i = 0; i < numdrives; i++)
35
{
36
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
37
}
38
/* get the number of entries in the
table */
39
VS_Table_GetFields(tableh,
40
VSID_NUMBER_ENTRIES,
&numentries,
41
VSID_ENDFIELD);
42
/* loop through the table and print
the entries */
API Guide
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60 }
Notes
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i, &ip,
VSID_ENDFIELD);
/* remove the entry from the table
*/
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
printf(“Drive ID #%d = %d\n”, i,
*ip);
}
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
After VS_Table_Destroy has been called for a table handle,
that handle is no longer valid and should not be used.
If a client adds entries to a table using VS_Table_AddEntry
or VS_Table_SetFields functions, it is the client’s
responsibility to maintain the data after it is stored in the table.
It is also the client’s responsibility to deallocate the space
containing the data after the entry has been deleted from the
table and is no longer needed.
2-420
API Functions
601355 Rev A
API Guide
If a client adds entries to a table using
VS_Table_CreateAddEntry, the VolServ API maintains the
data that is stored in the table and frees the space allocated for
all table entries when the VS_Table_Destroy function is
called.
See Also
VS_Table_AddEntry(l),
•
VS_Table_Create(l),
•
VS_Table_CreateAddEntry(l),
•
VS_Table_GetFields(l),
•
VS_Table_RemoveEntry(l),
•
VS_Table_SetFields(l)
Functions
601355 Rev A
•
API Functions
2-421
API Guide
VS_Table_Get
Fields
VS_Table_GetFields retrieves information associated
with a table handle. A table handle is used to pass table
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Table_GetFields
(VST_TABLE_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = Table 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.
Parameters
Parameter Type
Description
VSID_NUMBER_ENTRIES (int *)
Pointer to the number of entries in the table.
VSID_TABLE_ENTRY (int)
Index of a specific entry in the table.
(void **)
Pointer to a specific entry in the table.
2-422
API Functions
601355 Rev A
API Guide
Return Values
•
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 a
request handle.
•
VSE_ERR_BADSIZE - 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.
•
VSE_ERR_OUTOFRANGE - Specified entry does not exist
in the table’s range of values.
1
2
3
4
5
6
7
8
9
10
11
12
13
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_print_drivepool
*
* PURPOSE:
* This function prints out the
information stored in
* a drive pool handle.
*
* PARAMETERS:
* h : the drive pool handle to print
*
****************************************
*********/
#ifdef ANSI_C
API Functions
2-423
Functions
Example
VS_Table_GetFields returns:
API Guide
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
void
vst_print_drivepool(VST_DRIVEPOOL
_HANDLE h)
#else
void vst_print_drivepool(h)
VST_DRIVEPOOL_HANDLE h;
#endif
{
VST_DRIVE_POOL_NAME DrivePoolName;
VST_TABLE_HANDLE
DriveHandleTable;
VST_DRIVE_HANDLE
DriveHandle;
int
i;
int
n;
VS_DrivePool_GetFields(h,
VSID_DRIVEPOOL_NAME,
DrivePoolName,
VSID_DRIVE_HANDLE_TABLE,
&DriveHandleTable,
VSID_ENDFIELD);
printf(“DrivePoolName =
%s\n”,DrivePoolName);
/* Get # of entries */
if ( DriveHandleTable !=
(VST_TABLE_HANDLE) NULL )
{
VS_Table_GetFields(DriveHandleTab
le,
35
36
37
38
39
40
41
42
2-424
API Functions
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
VS_Table_GetFields(DriveHandleTab
le,
VSID_TABLE_ENTRY, i,
&DriveHandle,
VSID_ENDFIELD);
vst_print_drive(DriveHandle);
601355 Rev A
API Guide
43
44
45 }
Notes
}
}
A table is a VolServ API structure that holds a group of like
pointers. Table handles are used to return lists of information to
the client software. VS_Table_GetFields allows the user to
access the entries in the table.
The VSID_TABLE_ENTRY parameter requires that two
arguments be passed instead of one. The first argument is the
index of the entry in the appropriate table. The second argument
is a pointer to a location where the value is stored.
Note
Functions
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
•
•
•
•
•
•
•
•
•
•
•
•
•
vsapi(l),
VS_Archive_GetFields(l),
VS_Criteria_GetFields(l),
VS_CriteriaGroup_GetFields(l),
VS_Drive_GetFields(l),
VS_DrivePool_GetFields(l),
VS_Notify_GetFields(l),
VS_Status_GetFields(l),
VS_Table_AddEntry(l),
VS_Table_Create(l),
VS_Table_CreateAddEntry(l),
VS_Table_Destroy(l),
VS_Table_RemoveEntry(l),
VS_Table_SetFields(l)
API Functions
2-425
API Guide
VS_Table_
RemoveEntry
VS_Table_RemoveEntry removes an entry from the
specified VolServ API table. A table handle is used to pass table
information to and from VolServ.
Synopsis
VST_BOOLEAN VS_Table_RemoveEntry
(VST_TABLE_HANDLE handle,
void * entry)
Arguments
•
handle = Handle of the table where the entry is removed.
•
entry = Pointer to the entry to be removed from the table.
Return Values
2-426
API Functions
VS_Table_RemoveEntry returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_BADENTRY - Pointer to the entry to be removed
was null
•
VSE_ERR_BADHANDLE - Specified handle was not a table
handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
601355 Rev A
printf(“*** Table Handle test
***\n”);
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
API Functions
2-427
Functions
12
13
14
15
16
17
18
/****************************************
*********
*
* FUNCTION: vst_table_handle
*
* PURPOSE:
* This function tests the table handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_table_handle(void)
#else
VST_BOOLEAN vst_table_handle()
#endif
{
VST_BOOLEAN
rc =
VSE_TRUE;
VST_TABLE_HANDLE
tableh;
int
numdrives;
int
i;
VST_DRIVE_ID
testdriveid
= 9999;
int
numentries;
VST_DRIVE_ID
* ip;
API Guide
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60 }
2-428
API Functions
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
}
/* get the number of entries in the
table */
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
VSID_ENDFIELD);
/* loop through the table and print
the entries */
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i, &ip,
VSID_ENDFIELD);
/* remove the entry from the table
*/
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
printf(“Drive ID #%d = %d\n”, i,
*ip);
}
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
601355 Rev A
API Guide
Notes
VS_Table_RemoveEntry verifies that entry (a pointer
value) matches an entry in the specified table. (Note that all
table entries are pointers to data.) VS_Table_RemoveEntry
does not verify that the data pointed to by entry matches the
data pointed to by the corresponding table entry. As long as the
pointer values match, VS_Table_RemoveEntry removes
the entry from the table.
If a client adds entries to a table using VS_Table_AddEntry
or VS_Table_SetFields functions, it is the client’s
responsibility to maintain the data after it is stored in the table.
It is also the client’s responsibility to deallocate the space
containing the data after the entry has been deleted from the
table and is no longer needed.
data that is stored in the table and frees the space allocated for
all table entries when the VS_Table_Destroy function is
called.
See Also
601355 Rev A
•
VS_Table_AddEntry(l),
•
VS_Table_Create(l),
•
VS_Table_CreateAddEntry(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_SetFields(l)
API Functions
2-429
Functions
If a client adds entries to a table using
VS_Table_CreateAddEntry, the VolServ API maintains the
API Guide
VS_Table_Set
Fields
VS_Table_SetFields adds an entry to the specified table
at the specified location.
When a client adds an entry to a table using
VS_Table_SetFields, the client is responsible for
allocating and maintaining the space to contain the information
maintained in the table.
Synopsis
VST_BOOLEAN VS_Table_GetFields
(VST_TABLE_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = Handle of the table where an entry is added.
•
“…” = 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.
Parameters
Parameter Type
Description
SID_NUMBER_ENTRIES (int)
Number of entries in the table.
VSID_TABLE_ENTRY (int)
Position where the specified entry is added to
the table.
(void *)
Pointer to the entry to be stored in the table.
2-430
API Functions
601355 Rev A
API Guide
Return Values
•
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 a
request handle.
•
VSE_ERR_BADSIZE - 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.
•
VSE_ERR_OUTOFRANGE - Specified entry does not exist
in the table’s range of values.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_table_handle
*
* PURPOSE:
* This function tests the table handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_table_handle(void)
#else
API Functions
2-431
Functions
Example
VS_Table_GetFields returns:
API Guide
15
VST_BOOLEAN vst_table_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_TRUE;
19
VST_TABLE_HANDLE
tableh;
20
int
numdrives;
21
int
i;
22
VST_DRIVE_ID
testdriveid
= 9999;
23
int
numentries;
24
VST_DRIVE_ID
* ip;
25
26
printf(“*** Table Handle test
***\n”);
27
printf(“How many drives? “);
28
numdrives = atoi(gets(input));
29
30
/* create the table handle */
31
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
/* generate drive ids */
34
for (i = 0; i < numdrives; i++)
35
{
36
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
37
}
38
/* get the number of entries in the
table */
39
VS_Table_GetFields(tableh,
40
VSID_NUMBER_ENTRIES,
&numentries,
41
VSID_ENDFIELD);
42
/* loop through the table and print
the entries */
43
for (i = 0; i < numentries; i++)
44
{
45
VS_Table_GetFields(tableh,
46
VSID_TABLE_ENTRY, i, &ip,
2-432
API Functions
601355 Rev A
API Guide
47
48
49
50
51
52
53
54
55
Notes
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
printf(“Drive ID #%d = %d\n”, i,
*ip);
}
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
Functions
56
57
58
59
60 }
VSID_ENDFIELD);
/* remove the entry from the table
*/
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
VS_Table_SetFields(tableh,
A table cannot store NULL pointers.
Table entries are zero-based (like arrays in C). The first entry in
an empty table is stored in position 0, the second entry in a table
is stored in position 1, and the nth entry in a table is stored in
position n-1.
The VSID_TABLE_ENTRY parameter requires that two
arguments be passed instead of one. The first argument is the
position where the specified entry is added to the table. The
second argument is the entry to be added to the table.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-433
API Guide
See Also
2-434
API Functions
•
vsapi(l),
•
VS_Archive_GetFields(l),
•
VS_DrivePool_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_MediaClass_Getfields(l),
•
VS_Table_AddEntry(l),
•
VS_Table_Create(l),
•
VS_Table_CreateAddEntry(l),
•
VS_Table_Destroy(l),
•
VS_Table_GetFields(l),
•
VS_Table_RemoveEntry(l)
601355 Rev A
API Guide
VS_Terminate
VS_Terminate terminates the VolServ API software.
VS_Terminate releases all memory allocated by the API and
deregisters and frees all RPC transports.
Synopsis
VST_BOOLEAN VS_Terminate (void)
Arguments
None
Return Values
VS_Terminate returns:
601355 Rev A
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_SYSTEMCALL - A system call failed (usually
from RPC). This generic error code covers an error that
stems from a system call. The API sets this when
encountering a failure during RPC setup.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_terminate
4 *
5 * PURPOSE:
6 * This function shuts down the VolServ
API.
7 *
8 * PARAMETERS:
9 * none
10 *
API Functions
2-435
Functions
Example
•
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_terminate ( void )
14 #else
15
VST_BOOLEAN vst_terminate ()
16 #endif
17 {
18
VST_BOOLEAN
rc = VSE_FALSE;
19
20
rc = VS_Terminate();
21
return(rc);
22 }
Notes
All command functions fail after VS_Terminate has been
invoked.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l)
2-436
API Functions
601355 Rev A
API Guide
VS_
TypeCapacity
_Create
VS_TypeCapacity_Create allocates a VolServ API
archive type capacity handle. A type capacity handle is used to
pass archive type capacity information from VolServ in
response to an Archive Query command request with the type
capacity option specified.
Synopsis
VST_TYPECAPACITY_HANDLE VS_TypeCapacity_Create
(void)
Arguments
None
Example
601355 Rev A
VS_TypeCapacity_Create returns:
•
A type capacity handle, if one can be allocated.
•
NULL, if a type capacity handle could not be allocated. An
appropriate error code is set in VSG_Error.
•
VSE_ERR_OUTOFMEM - Memory allocation error.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_typecapacity_handle
4 *
5 * PURPOSE:
6 * This function tests a typecapacity
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
**********/
12 #ifdef ANSI_C
API Functions
2-437
Functions
Return Values
API Guide
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
2-438
API Functions
VST_BOOLEAN
vst_typecapacity_handle(void)
#else
VST_BOOLEAN
vst_typecapacity_handle()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_TYPECAPACITY_HANDLE
h;
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
Capacity;
VST_HIGH_MARK
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
int AssignedBins;
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
VST_BOOLEAN
AutoCheckinFlag;
VST_BOOLEAN
AutoImportFlag;
VST_BATCH_NAME
ImportBatch;
VST_MANUFACTURER_NAME
ImportManufacturer;
VST_MEDIA_CLASS_NAME
ImportClass;
/* create the handle */
h = vS_TypeCapacity_Create();
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
{
/* get values from user */
printf(“Enter media type name ==>
“);
gets(MediaType);
601355 Rev A
API Guide
40
41
42
43
44
45
46
47
48
49
50
51
55
56
57
58
59
60
61
62
63
64
65
66
601355 Rev A
API Functions
2-439
Functions
52
53
54
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
API Guide
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84 }
VSID_MANUFACTURER,
ImportManufacturer,
VSID_CAPACITY,
Capacity,
VSID_HIGH_MARK,
HighMarkPercent,
VSID_LOW_MARK,
LowMarkPercent,
VSID_FILL_LEVEL,
FillLevel,
VSID_ASSIGNED_BINS,
AssignedBins,
VSID_ARCHIVE_ACTION,
ActionOpt,
VSID_AUTOIMPORT_FLAG,
AutoImportFlag,
VSID_AUTOCHECKIN_FLAG,
AutoCheckinFlag,
VSID_ENDFIELD);
if (rc)
{
vst_print_typecapacity(h);
}
VS_TypeCapacity_Destroy(h);
}
return(rc);
Notes
None
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_TypeCapacity_Destroy(l),
•
VS_TypeCapacity_GetFields(l),
•
VS_TypeCapacity_SetFields(l)
2-440
API Functions
601355 Rev A
API Guide
VS_
TypeCapacity
_Destroy
VS_TypeCapacity_Destroy deallocates a type capacity
handle that was allocated by VS_TypeCapacity_Create.
A type capacity handle is used to pass archive type capacity
information from VolServ in response to an Archive Query
command request with the type capacity option specified.
Synopsis
VST_BOOLEAN VS_TypeCapacity_Destroy
(VST_TYPECAPACITY_HANDLE handle)
Arguments
•
Return Values
VS_TypeCapacity_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 a type
capacity handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
1
2
3
4
5
6
7
8
9
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_typecapacity_handle
*
* PURPOSE:
* This function tests a typecapacity
handle.
*
* PARAMETERS:
* none
API Functions
2-441
Functions
Example
handle = The type capacity handle to be destroyed.
API Guide
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_typecapacity_handle(void)
14 #else
15
VST_BOOLEAN
vst_typecapacity_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_TYPECAPACITY_HANDLE
h;
20
VST_MEDIA_TYPE_NAME
MediaType;
21
VST_CAPACITY
Capacity;
22
VST_HIGH_MARK
HighMarkPercent;
23
VST_LOW_MARK
LowMarkPercent;
24
VST_FILL_LEVEL
FillLevel;
25
int AssignedBins;
26
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
27
VST_BOOLEAN
AutoCheckinFlag;
28
VST_BOOLEAN
AutoImportFlag;
29
VST_BATCH_NAME
ImportBatch;
30
VST_MANUFACTURER_NAME
ImportManufacturer;
31
VST_MEDIA_CLASS_NAME
ImportClass;
32
33
/* create the handle */
34
h = vS_TypeCapacity_Create();
35
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
36
{
2-442
API Functions
601355 Rev A
API Guide
37
38
39
40
41
42
43
44
45
46
47
48
49
51
52
53
54
55
56
57
58
59
60
61
62
63
64
601355 Rev A
API Functions
2-443
Functions
50
/* get values from user */
printf(“Enter media type name ==>
“);
gets(MediaType);
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
API Guide
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84 }
Notes
2-444
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
VSID_MANUFACTURER,
ImportManufacturer,
VSID_CAPACITY,
Capacity,
VSID_HIGH_MARK,
HighMarkPercent,
VSID_LOW_MARK,
LowMarkPercent,
VSID_FILL_LEVEL,
FillLevel,
VSID_ASSIGNED_BINS,
AssignedBins,
VSID_ARCHIVE_ACTION,
ActionOpt,
VSID_AUTOIMPORT_FLAG,
AutoImportFlag,
VSID_AUTOCHECKIN_FLAG,
AutoCheckinFlag,
VSID_ENDFIELD);
if (rc)
{
vst_print_typecapacity(h);
}
VS_TypeCapacity_Destroy(h);
}
return(rc);
After VS_TypeCapacity_Destroy has been called for a type
capacity handle, that handle is no longer valid and should not be
used.
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_TypeCapacity_Create(l),
•
VS_TypeCapacity_GetFields(l),
•
VS_TypeCapacity_SetFields(l)
Functions
601355 Rev A
API Functions
2-445
API Guide
VS_
TypeCapacity
_GetFields
VS_TypeCapacity_GetFields retrieves information
from a type capacity handle. A type capacity handle is used to
pass archive type capacity information from VolServ in
response to an Archive Query command request with the type
capacity option specified.
Synopsis
VST_BOOLEAN VS_TypeCapacity_GetFields
(VST_TYPECAPACITY_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The type capacity 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.
Parameters
Parameter Type
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION*)
2-446
API Functions
Description
Pointer to the action taken by VolServ when
the number of media of this media type
classification reaches the high mark threshold
(migrate, notify, or none) in the archive. Valid
VSID_ARCHIVE_ACTION values are
enumerated in the vs_types.h file.
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the number of bins to be assigned
to this media type classification within the
archive.
VSID_AUTOIMPORT_FLAG
(VST_BOOLEAN *)
Pointer to a flag indicating whether automatic
import is allowable for the archive.
VSID_AUTOCHECKIN_FLAG
(VST_BOOLEAN *)
Pointer to a flag indicating whether automatic
checkin is active for the archive.
VSID_BATCH_NAME (VST_BATCH_NAME)
Pointer to the batch name to be assigned to
automatically imported/checked in media.
Valid batch names may contain up to 32
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_CAPACITY (VST_CAPACITY *)
Pointer to the maximum number of media of
this media type classification that can be in
this archive.
VSID_FILL_LEVEL (VST_FILL_LEVEL *)
Pointer to the current number of media of this
media type classification in this archive.
VSID_HIGH_MARK (VST_HIGH_MARK *)
Pointer to the percentage of VSID_CAPACITY
above which the specified migration policy
option is performed or initiated.
VSID_LOW_MARK (VST_LOW_MARK *)
Pointer to the percentage of VSID_CAPACITY
below which the specified migration policy
option is performed or terminated.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
Pointer to the manufacturer to be assigned to
automatically imported/checked in media.
Valid manufacturer names may contain up to
32 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS)
Pointer to the MediaClass classification where
automatically imported/checked in media are
assigned.
601355 Rev A
API Functions
2-447
Functions
VSID_ASSIGNED_BINS (VST_COUNT *)
API Guide
Parameter Type
Description
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Return Values
Example
2-448
Pointer to the name of this media type
classification. Valid media type names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VS_TypeCapacity_GetField 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_NULLHANDLE - Specified handle was a null
pointer.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_print_typecapacity
4 *
5 * PURPOSE:
6 * This function prints out the
information stored
7 * in a type capacity handle.
8 *
9 * PARAMETERS:
10 * h : the type capacity handle to print
11 *
12 ****************************************
*********/
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-449
Functions
13 #ifdef ANSI_C
14
void
vst_print_typecapacity(VST_TYPECA
PACITY_HANDLEh)
15 #else
16
void vst_print_typecapacity(h)
17
VST_TYPECAPACITY_HANDLE h;
18 #endif
19 {
20
VST_MEDIA_TYPE_NAME
MediaType;
21
VST_CAPACITY
Capacity;
22
VST_HIGH_MARK
HighMarkPercent;
23
VST_LOW_MARK
LowMarkPercent;
24
VST_FILL_LEVEL
FillLevel;
25
int
AssignedBins;
26
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
27
VST_BOOLEAN
AutoCheckinFlag;
28
VST_BOOLEAN
AutoImportFlag;
29
VST_BATCH_NAME
ImportBatch;
30
VST_MANUFACTURER_NAME
ImportManufacturer;
31
VST_MEDIA_CLASS_NAME
ImportClass;
32
33
VS_TypeCapacity_GetFields(h,
34
VSID_MEDIA_TYPE_NAME,
MediaType,
35
VSID_MEDIA_CLASS_NAME,
ImportClass,
36
VSID_BATCH_NAME,
ImportBatch,
37
VSID_MANUFACTURER,
ImportManufacturer,
API Guide
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
2-450
API Functions
VSID_CAPACITY,
&Capacity,
VSID_HIGH_MARK,
&HighMarkPercent,
VSID_LOW_MARK,
&LowMarkPercent,
VSID_FILL_LEVEL,
&FillLevel,
VSID_ASSIGNED_BINS,
&AssignedBins,
VSID_ARCHIVE_ACTION,
&ActionOpt,
VSID_AUTOIMPORT_FLAG,
&AutoImportFlag,
VSID_AUTOCHECKIN_FLAG,
&AutoCheckinFlag,
VSID_ENDFIELD);
printf(“******* Type Capacity Handle
*******\n”);
printf(“Media type = %s\n”,
MediaType);
printf(“Capacity = %d\n”, Capacity);
printf(“High Mark Percent = %d\n”,
HighMarkPercent);
printf(“Low Mark Percent = %d\n”,
LowMarkPercent);
printf(“Fill Level = %d\n”,
FillLevel);
printf(“Assigned Bins = %d\n”,
AssignedBins);
printf(“Archive Action Option =
%d\n”, ActionOpt);
printf(“Auto Checkin = %d\n”,
AutoCheckinFlag);
printf(“Auto Import = %d\n”,
AutoImportFlag);
printf(“Import Class = %s\n”,
ImportClass);
printf(“Import Batch = %s\n”,
ImportBatch);
printf(“Import Manufacturer = %s\n”,
ImportManufacturer);
601355 Rev A
API Guide
60 }
Notes
The migration policy options for VSID_HIGH_MARK are no
action, operator notification, and automatic migration.
When the number of media in a media type classification
reaches the high mark threshold, VolServ:
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
•
Terminates automatic migration of media if the migration
policy is set to migrate.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-451
Functions
When the number of media in a media type classification drops
to the low mark threshold, VolServ:
API Guide
See Also
2-452
API Functions
•
vsapi(l),
•
VS_Archive_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_TypeCapacity_Create(l),
•
VS_TypeCapacity_Destroy(l),
•
VS_TypeCapacity_SetFields(l),
•
VSCMD_ArchiveQuery(l)
601355 Rev A
API Guide
VS_TypeCapacity_SetFields sets the value of one or
more fields in a type capacity handle. A type capacity handle is
used to pass archive type capacity information to and from
VolServ.
Synopsis
VST_BOOLEAN VS_TypeCapacity_SetFields
(VST_TYPECAPACITY_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The type capacity handle where information is
stored or updated.
•
“…” = 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION)
Action taken by VolServ when the number of
media of this media type classification
reaches the high mark threshold (migrate,
notify, or none). Valid
VSID_ARCHIVE_ACTION values are
enumerated in the vs_types.h file.
VSID_ASSIGNED_BINS (VST_COUNT)
Number of bins to be assigned to the media
type classification within the archive.
601355 Rev A
API Functions
2-453
Functions
VS_
TypeCapacity
_SetFields
API Guide
Parameter Type
Description
VSID_AUTOCHECKIN_FLAG
(VST_BOOLEAN)
Flag indicating whether automatic checkin is
active for the archive.
VSID_AUTOIMPORT_FLAG
(VST_BOOLEAN)
Flag indicating whether automatic import is
active for the archive.
VSID_BATCH_NAME (VST_BATCH_NAME)
Batch name to be assigned to automatically
imported/checked in media. Valid batch
names may contain 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CAPACITY (VST_CAPACITY)
Maximum number of media of this media type
classification that can be in this archive.
VSID_FILL_LEVEL (VST_FILL_LEVEL)
Current number of media of this media type
classification in this archive.
VSID_HIGH_MARK (VST_HIGH_MARK)
Percentage of VSID_CAPACITY above which
the specified migration policy option is
performed or initiated.
VSID_LOW_MARK (VST_LOW_MARK)
Percentage of VSID_CAPACITY below which
the specified migration policy option is
performed or terminated.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
Manufacturer to be assigned to automatically
imported/checked in media. Valid
manufacturer names may contain up to 32
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS)
MediaClass group where automatically
imported/checked in media are assigned.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Name of this media type classification. Valid
media type names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
2-454
API Functions
601355 Rev A
API Guide
Return Values
•
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 a type
capacity handle.
•
VSE_ERR_BADSIZE - 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_typecapacity_handle
*
* PURPOSE:
* This function tests a typecapacity
handle.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_typecapacity_handle(void)
#else
API Functions
2-455
Functions
Example
VS_TypeCapacity_SetFields returns:
API Guide
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
2-456
API Functions
VST_BOOLEAN
vst_typecapacity_handle()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_TYPECAPACITY_HANDLE
h;
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
Capacity;
VST_HIGH_MARK
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
int AssignedBins;
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
VST_BOOLEAN
AutoCheckinFlag;
VST_BOOLEAN
AutoImportFlag;
VST_BATCH_NAME
ImportBatch;
VST_MANUFACTURER_NAME
ImportManufacturer;
VST_MEDIA_CLASS_NAME
ImportClass;
/* create the handle */
h = vS_TypeCapacity_Create();
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
{
/* get values from user */
printf(“Enter media type name ==>
“);
gets(MediaType);
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
601355 Rev A
API Guide
43
44
45
46
47
48
49
50
51
52
53
54
57
58
59
60
61
62
63
64
65
66
67
68
601355 Rev A
API Functions
2-457
Functions
55
56
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
VSID_MANUFACTURER,
ImportManufacturer,
VSID_CAPACITY,
Capacity,
API Guide
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84 }
Notes
VSID_HIGH_MARK,
HighMarkPercent,
VSID_LOW_MARK,
LowMarkPercent,
VSID_FILL_LEVEL,
FillLevel,
VSID_ASSIGNED_BINS,
AssignedBins,
VSID_ARCHIVE_ACTION,
ActionOpt,
VSID_AUTOIMPORT_FLAG,
AutoImportFlag,
VSID_AUTOCHECKIN_FLAG,
AutoCheckinFlag,
VSID_ENDFIELD);
if (rc)
{
vst_print_typecapacity(h);
}
VS_TypeCapacity_Destroy(h);
}
return(rc);
The migration policy options for VSID_HIGH_MARK are no
action, operator notification, and automatic migration.
When the number of media in a media type classification
reaches the high mark threshold, VolServ:
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
When the number of media in a media type classification drops
to the low mark threshold, VolServ:
2-458
API Functions
601355 Rev A
API Guide
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
•
Terminates automatic migration of media if the migration
policy is set to migrate.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_TypeCapacity_Create(l),
•
VS_TypeCapacity_Destroy(l),
•
VS_TypeCapacity_GetFields(l)
Functions
601355 Rev A
•
API Functions
2-459
API Guide
VSCMD_
ArchiveQuery
VSCMD_ArchiveQuery queries for information associated
with a VolServ archive.
Upon receipt of an Archive Query command, VolServ obtains
information about the specified archive. This information is
returned to the client in the status of the command.
Synopsis
VST_BOOLEAN VSCMD_ArchiveQuery
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Archive Query
command.
•
“…” = 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 use for this
command. 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.
Parameters
Parameter Type
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
2-460
API Functions
Description
Name of the archive to be queried. Valid
archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
601355 Rev A
API Guide
Parameter Type
Description
Specifies the type (or types) of archive
information being requested. Valid
VSID_ARCHIVE_QUERY_OPTION values are
defined in the vs_defs.h file. Multiple values
can be specified by connecting them with the
“|” operator.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single archive or for all
archives. Valid VSID_QUERY_OPTION values
are enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software is to wait for final status) and
VSE_FALSE (API software is not to wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE).
601355 Rev A
API Functions
2-461
Functions
VSID_ARCHIVE_QUERY_OPTION
(VST_ARCHIVE_QUERY_OPTION)
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
ArchiveQuery command request.
USER_FIELD is 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 this request.
Neither the API software nor VolServ uses
USER_FIELD.
Return Values
VSCMD_ArchiveQuery returns:
•
•
2-462
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
601355 Rev A
API Guide
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-463
Functions
601355 Rev A
•
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2-464
API Functions
/****************************************
*********
*
* FUNCTION: vst_archivequery_execute
*
* PURPOSE:
* This executes the VSCMD_ArchiveQuery
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_archivequery_execute(void)
#else
VST_BOOLEAN
vst_archivequery_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
int
ok;
VST_QUERY_OPTION
queryopt;
VST_ARCHIVE_QUERY_OPTION
arcqueryopt;
VST_ARCHIVE_NAME
archive;
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf( “*** Archive Query parameters
***\n” );
printf(“Query all archives? (1) yes,
(0) no: “);
queryopt = (VST_QUERY_OPTION)
atoi(gets(input));
if (queryopt == 0)
{
601355 Rev A
API Guide
32
33
34
35
36
37
38
39
40
41
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
601355 Rev A
}
else
{
strcpy(archive, VSD_STRING_INIT);
}
/* Initialize the Archive Query
Option */
arcqueryopt =
VSD_ARCQRY_OPTION_NONE;
printf( “query drive information? (1)
yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
{
/* Add the option to query for */
/* drive information */
arcqueryopt +=
VSD_ARCQRY_OPTION_DRIVE;
}
printf( “query media information? (1)
yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
{
/* add the option to query for
media */
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_MEDIA;
}
printf( “query media class
information? (1) yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
{
/* add the option to query media
class */
API Functions
2-465
Functions
42
43
44
45
46
47
printf( “\nEnter Archive Name
==>”);
gets(archive);
API Guide
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
2-466
API Functions
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_CLASS;
}
printf( “query media type
information? (1) yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
{
/* add the option to query media
type */
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_TYPE;
}
/* create the command handle */
/* Note that the command handle is
not destroyed in */
/* this routine, but in vst_dispatch
when final */
/* status is received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the
VolServ. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit parameters and
priority are */
/* set as default parameters. */
if (queryopt ==
VSE_QUERY_OPTION_ALL)
{
601355 Rev A
API Guide
92
93
94
95
96
97
98
99
100
101
102
103
Notes
}
return ( rc );
Functions
104
105
106
107
108
109}
/* query all archives */
rc = VSCMD_ArchiveQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_ARCHIVE_QRY_OPTION,
arcqueryopt,
VSID_ENDFIELD);
}
else
{
/* query a specific archive */
rc = VSCMD_ArchiveQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_ARCHIVE_QRY_OPTION,
arcqueryopt,
VSID_ARCHIVE_NAME, archive,
VSID_ENDFIELD);
}
The API must be initialized with a call to VS_Initialize
before this function can be executed.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the API cannot receive status for this request.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
VolServ generates intermediate status in response to an Archive
Query request if:
601355 Rev A
API Functions
2-467
API Guide
•
Information is being requested for more than one archive.
•
Any archive query option is specified.
Archive Query statuses are cumulative. Each status is added to
the previous status; therefore, after the final status, the status
handle contains all needed information.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Archive
Query command are set with
VSCMD_ArchiveQuery_SetDefaults. If
command-specific defaults are set for the Archive Query
command, they override the global defaults for all Archive
Query requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Archive
Query request, the parameter identifier and the value to be
used for the parameter can be submitted on the command
request itself.
The following fields can be retrieved from the status handle
after a successful Archive Query request:
2-468
API Functions
•
VSID_ARCHIVE_HANDLE,
•
VSID_ARCHIVE_HANDLE_ENTRY,
•
VSID_ARCHIVE_HANDLE_TABLE,
•
VSID_QUERY_OPTION, VSID_SEQUENCE_NUM,
601355 Rev A
API Guide
•
VSID_SEQUENCE_TABLE, VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
VSCMD_ArchiveQuery does not trigger any MediaClass
callbacks from VolServ.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Archive_GetFields(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Global_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_ArchiveQuery_SetDefaults(l)
Functions
601355 Rev A
•
API Functions
2-469
API Guide
VSCMD_
ArchiveQuery
_SetDefaults
VSCMD_ArchiveQuery_SetDefaults sets the
command-level default parameters for Archive Query
command requests.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Archive
Query command are set with
VSCMD_ArchiveQuery_SetDefaults. If
command-specific defaults are set for the Archive Query
command, they override the global defaults for all Archive
Query requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Archive
Query request, the parameter identifier and the value to be
used for the parameter can be submitted on the command
request itself.
Synopsis
2-470
API Functions
VST_BOOLEAN VSCMD_ArchiveQuery_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. 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.
Parameters
Parameter Type
Description
Name of the archive to be queried on all
Archive Query requests. Valid archive names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_ARCHIVE_QUERY_OPTION
(VST_ARCHIVE_QUERY_OPTION)
Type (or types) of information being requested
on Archive Query requests. Valid
VSID_ARCHIVE_QUERY_OPTION values are
defined in the vs_defs.h file. Multiple values
may be specified by connecting them with the
“|” operator.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Archive Query requests.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Archive Query
requests.
VSID_PRIORITY (VST_PRIORITY)
Execution priority for Archive Query requests.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
601355 Rev A
API Functions
2-471
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single specified archive or for
all archives. Valid VSID_QUERY_OPTION
values are enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Archive Query requests.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software is to
wait for final status from VolServ (or to
time-out) for Archive Query requests. Valid
options are VSE_TRUE (API software is to wait
for final status) and VSE_FALSE (API software
is not to wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE).
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for every
Archive Query command request.
USER_FIELD is 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 Archive Query
requests. Neither the API software nor
VolServ uses USER_FIELD.
2-472
API Functions
601355 Rev A
API Guide
Return Values
•
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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_archivequery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ArchiveQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_archivequery_defaults(void)
#else
VST_BOOLEAN
vst_archivequery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
API Functions
2-473
Functions
Example
VSCMD_ArchiveQuery_SetDefaults returns:
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Archive Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ArchiveQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-474
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ArchiveQuery(l)
Functions
601355 Rev A
API Functions
2-475
API Guide
VSCMD_
ArchiveVary
VSCMD_ArchiveVary changes the state of a VolServ
configured archive. Name of the archive and the target state
must be specified.
Upon receipt of a VSCMD_ArchiveVary command, VolServ
attempts to change the state of the specified archive. The return
code presented to the client indicates the success or failure of
the command.
Synopsis
VST_BOOLEAN VSCMD_ArchiveVary
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Archive Vary
command.
•
“…” = 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 apply to this
command. 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.
2-476
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the archive to be varied. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on this command.
VSID_COMP_STATE (VST_COMP_STATE)
State where the archive is varied. Valid
VSID_COMP_STATE values are enumerated
in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Valid
options are VSE_TRUE (API software is to wait
for final status) and VSE_FALSE (API software
is not to wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE).
601355 Rev A
API Functions
2-477
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in the USER_FIELD for this
command. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_ArchiveVary returns:
•
•
2-478
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
601355 Rev A
API Guide
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-479
Functions
601355 Rev A
•
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2-480
API Functions
/****************************************
*********
*
* FUNCTION: vst_archivevary_execute
*
* PURPOSE:
* This executes the VSCMD_ArchiveVary
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_archivevary_execute(void)
#else
VST_BOOLEAN
vst_archivevary_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_COMP_STATE
state;
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Archive Vary parameters
***\n” );
printf(“\nEnter Archive “);
gets(archive);
printf(“\nEnter Archive State (1)
ONLINE (2) OFFLINE (3) DIAG: “);
state = (VST_COMP_STATE)
atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
601355 Rev A
API Guide
33
34
35
36
37
38
39
40
41
42
46
47
48
49
50 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the API is not able to receive status for this
request.
601355 Rev A
API Functions
2-481
Functions
43
44
45
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the
VolServ. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters.*/
rc = VSCMD_ArchiveVary(cmd,
VSID_COMP_STATE,
state,
VSID_ARCHIVE_NAME,
archive,
VSID_ENDFIELD);
}
return ( rc );
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Archive Vary
command are set with
VSCMD_ArchiveVary_SetDefaults. If
command-specific defaults are set for the Archive Vary
command, they override the global defaults for all Archive
Vary requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Archive Vary
request, the parameter identifier and the value to be used
for the parameter can be submitted on the command
request itself.
The following fields can be retrieved from the status handle
after a successful reprioritize request:
2-482
API Functions
•
VSID_ARCHIVE_NAME,
•
VSID_COMP_STATE,
•
VSID_SEQUENCE_NUMBER,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
601355 Rev A
API Guide
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
VolServ does not generate intermediate status in response to an
Archive Vary request.
VSCMD_ArchiveVary does not trigger any MediaClass
callbacks from VolServ.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Status_GetFields(l),
•
VSCMD_ArchiveVary_SetDefaults(l)
Functions
601355 Rev A
•
API Functions
2-483
API Guide
VSCMD_
ArchiveVary_
SetDefaults
VSCMD_ArchiveVary_SetDefaults sets the
command-level default parameters for Archive Vary command
requests.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Archive Vary
command are set with
VSCMD_ArchiveVary_SetDefaults. If
command-specific defaults are set for the Archive Vary
command, they override the global defaults for all Archive
Vary requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Archive Vary
request, the parameter identifier and the value to be used
for the parameter can be submitted on the command
request itself.
Synopsis
2-484
API Functions
VST_BOOLEAN VSCMD_ArchiveVary_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. 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.
Parameters
Parameter Type
Description
Name of the archive to be varied on Archive
Vary requests. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Archive Vary requests.
VSID_COMP_STATE (VST_COMP_STATE)
State where the archive is varied on Archive
Vary requests. Valid VSID_COMP_STATE
values are enumerated in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on Archive Vary requests.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Archive Vary
requests. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
601355 Rev A
API Functions
2-485
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Archive Vary requests. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software is to
wait for final status from VolServ (or to
timeout) for a command. Valid options are
VSE_TRUE (API is to wait for final status) and
VSE_FALSE (API is not to wait for final status).
Valid options are VSE_TRUE (API software is
to wait for final status) and VSE_FALSE (API
software is not to wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE).
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for every
Archive Vary command request.
USER_FIELD is 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 this request.
Neither the API software nor VolServ uses
USER_FIELD.
2-486
API Functions
601355 Rev A
API Guide
Return Values
Example
VSCMD_ArchiveVary_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
7
8
9
10
11
12
13
14
15
16
17
18
19
20
601355 Rev A
API Functions
2-487
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_archivevary_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ArchiveVary API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_archivevary_defaults(void)
#else
VST_BOOLEAN
vst_archivevary_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Archive Vary default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ArchiveVary_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-488
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ArchiveVary(l)
Functions
601355 Rev A
API Functions
2-489
API Guide
VSCMD_Audit
VSCMD_Audit performs archive inventory verification of the
specified archive.
•
If the specified archive is robotically controlled, the robot
scans each physical bin location and verifies that the
database is consistent with the actual location of media. Any
detected inconsistencies are returned to the client, logged in
a system log file, and VolServ take appropriate action based
on the circumstances of the discrepancy.
•
On the other hand, if the specified archive is a manual
archive, the archive operator is directed to generate the audit
report. The operator may then request the report be printed
or verify the information on-line. Either way, the operator
must actually perform the inventory and then correct any
reported discrepancies. Discrepancies are resolved by
issuing appropriate media management commands (for
example, Move and Eject commands) to relocate media to
the reported locations. Inconsistencies detected in a manual
archive are not reported to the client.
Audit requests are for full archive audits only; no subset audits
are permitted from the API. Subset audits are conducted from
the system operator GUI. Full archive audits can be lengthy and
must be requested with discretion.
Synopsis
2-490
API Functions
VST_BOOLEAN VSCMD_Audit
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
•
•
handle = Handle of the Audit command.
“…” =Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. 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.
Parameters
Parameter Type
Description
Name of the archive to audit. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Client dispatch routine for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
2-491
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software is to wait for final status) and
VSE_FALSE (API software is not to wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE).
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this Audit
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_Audit returns:
•
VSE_TRUE
-
•
2-492
API Functions
Successful execution if the API is operating in
synchronous mode.
- Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
601355 Rev A
API Guide
-
•
•
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
- If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
601355 Rev A
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-493
Functions
•
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
- If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2-494
API Functions
/****************************************
*********
*
* FUNCTION: vst_audit_execute
*
* PURPOSE:
* This executes the VSCMD_Audit API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_audit_execute(void)
#else
VST_BOOLEAN vst_audit_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Audit parameters ***\n”
);
printf(“Enter Archive Name ==> “ );
gets(archive);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when finalstatus is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
601355 Rev A
API Guide
35
36
37
38
39
40
41
42
Notes
}
return ( rc );
Functions
43
44
45
46 }
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as*/
/* default parameters. */
rc = VSCMD_Audit(cmd,
VSID_ARCHIVE_NAME,
archive,
VSID_ENDFIELD);
The API must be initialized with a call to VS_Initialize
before this function can be executed.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE. Because of the time required for
robotic audits, the time-out value or retries may need to be
increased from the API default values.
VolServ can generate intermediate status in response to an
Audit request.
VSCMD_Audit can trigger MediaClass callbacks from VolServ.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the API is not able to receive status for this
request.
601355 Rev A
API Functions
2-495
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system. With the exceptions of the
manual archives, a pending or executing Audit command can
be cancelled using the VolServ Cancel command.
A pending or executing Audit command can be reprioritized
using the VolServ Reprioritize command.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Audit
command are set with VSCMD_Audit_SetDefaults. If
command-specific defaults are set for the Audit command,
they override the global defaults for all Audit requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Audit request,
the parameter identifier and the value to be used for the
parameter can be submitted on the command request
itself.
The following fields can be retrieved from the status handle
after a successful Audit:
•
•
•
•
2-496
API Functions
VSID_ACTION_CODE,
VSID_ACTION_CODE_ENTRY,
VSID_ACTION_CODE_TABLE,
VSID_COMP_ID,
601355 Rev A
API Guide
VSID_COMP_ID_ENTRY,
VSID_COMP_ID_TABLE,
VSID_ERROR,
VSID_ERROR_ENTRY,
VSID_ERROR_TABLE,
VSID_MEDIA_ID,
VSID_MEDIA_ID_ENTRY,
VSID_MEDIA_ID_TABLE,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD,
VSID_WAIT_REASON.
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-497
API Guide
See Also
2-498
•
•
•
•
•
•
•
•
•
•
•
API Functions
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Command_GetFields(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VS_Initialize(l),
VS_Media_GetFields(l),
VS_Status_GetFields(l),
VS_Table_GetFields(l),
VSCMD_Audit_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_Audit
_SetDefaults
VSCMD_Audit_SetDefaults sets command-level default
parameters for Audit commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Audit commands
are set with VSCMD_Audit_SetDefaults. If
command-specific defaults are set for Audit commands,
they override the global defaults for all commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Audit
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
VST_BOOLEAN VSCMD_Audit_SetDefaults
(
“…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
Arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
API Functions
2-499
API Guide
2-500
API Functions
601355 Rev A
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
Name of the archive to audit. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
intermediate and final status for Audit
commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for Audit
commands.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Audit
commands.Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Audit commands. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode. The default retry limit is
3.
601355 Rev A
API Functions
2-501
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Audit commands. Valid options are VSE_TRUE
(API software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
The value to be put in USER_FIELD for Audit
commands. USER_FIELD is 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 Audit
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
2-502
API Functions
VSCMD_Audit_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
601355 Rev A
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
601355 Rev A
/* get parameters from user */
printf(“*** Audit default parameters
***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
API Functions
2-503
Functions
7
8
9
10
11
12
/****************************************
*********
*
* FUNCTION: vst_audit_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Audit API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_audit_defaults(void)
#else
VST_BOOLEAN vst_audit_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
31
32
33
34
35
36
37
38
39
40 }
rc = VSCMD_Audit_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-504
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Audit(l)
601355 Rev A
API Guide
VSCMD_
Cancel
VSCMD_Cancel stops a pending request from executing or
aborts an executing Audit request.
Upon receipt of a Cancel request, VolServ returns final status to
the client that requested the cancellation. If the specified request
is capable of being cancelled, a good status is returned.
Otherwise, a status that indicates why the request cannot be
cancelled is returned.
If the specified request is pending execution, the request is
directed to terminate after any allocated resources are released.
A final status that indicates “failure due to cancellation” is sent
to the original issuer of the cancelled request.
To issue a valid Cancel request, the client must supply the
request identifier and request type of the request to be canceled.
The VSCMD_Cancel function can either take these parameters
separately or retrieve them from a command handle.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_Cancel
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
API Functions
2-505
Functions
Upon receipt of a Cancel request of an executing Audit request,
the processing is directed to abort, and the remainder of the
Audit request is cancelled. A final status that indicates “failure
due to cancellation” is sent to the original issuer of the
cancelled request.
API Guide
Arguments
•
handle = The command handle for this Cancel request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_COMMAND_HANDLE
(VST_COMMAND_HANDLE)
The command handle of the request to
cancel.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_REQUEST_ID (VST_REQUEST_ID)
The request identifier of the request to cancel.
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE)
The request type of the request to cancel.
Valid VSID_REQUEST_TYPE values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-506
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
The value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
601355 Rev A
API Functions
2-507
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
Return Values
VSCMD_Cancel returns:
•
•
API Functions
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
•
2-508
VSE_TRUE
-
If the object code value is VSE_VOLSERV, the
error occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific
error.
-
If the object code value is not VSE_VOLSERV and
is not VSE_NONE, the error occurred in the API
and the client uses VST_ERROR_CODE to identify
the specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Guide
Example
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
601355 Rev A
API Functions
2-509
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_cancel_execute
*
* PURPOSE:
* This executes the VSCMD_Cancel API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_cancel_execute(void)
#else
VST_BOOLEAN vst_cancel_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_REQUEST_ID
req;
VST_REQUEST_TYPE
c;
VST_COMMAND_HANDLE
cmd;
API Guide
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
/* get parameters from user */
printf(“*** Cancel parameters ***\n”
);
printf(“Enter Request ID ==> “ );
req = (VST_REQUEST_ID)
atol(gets(input));
printf(“Enter Command Request Type
==> “ );
c = (VST_REQUEST_TYPE)
atol(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_Cancel(cmd,
VSID_REQUEST_ID, req,
46
47
48
2-510
API Functions
VSID_REQUEST_TYPE, c,
VSID_ENDFIELD);
}
601355 Rev A
API Guide
49
50 }
Notes
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Cancel request.
VSCMD_Cancel does not trigger any MediaClass callbacks
from VolServ.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Cancel request submitted through the API interface to the
VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
601355 Rev A
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
API Functions
2-511
Functions
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
API Guide
•
Command-specific parameter defaults for Cancel
commands are set with VSCMD_Cancel_SetDefaults. If
command-specific defaults are set for Cancel commands,
they override the global defaults for all commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Cancel
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Cancel request:
•
VSID_REQUEST_ID,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-512
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Cancel_SetDefaults(l)
Functions
601355 Rev A
API Functions
2-513
API Guide
VSCMD_
Cancel_
SetDefaults
VSCMD_Cancel_SetDefaults sets command-level
default parameters for Cancel commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Cancel
commands are set with VSCMD_Cancel_SetDefaults. If
command-specific defaults are set for Cancel commands,
they override the global defaults for all commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Cancel
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
Synopsis
2-514
API Functions
VST_BOOLEAN VSCMD_Cancel_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for Cancel commands.
VSID_COMMAND_HANDLE
(VST_COMMAND_HANDLE)
The command handle of the request to
cancel.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on Cancel commands.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Cancel
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_REQUEST_ID (VST_REQUEST_ID)
The request identifier of the request to cancel.
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE)
The request type of the request to cancel.
Valid VSID_REQUEST_TYPE values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Cancel commands. VSID_RETRY_LIMIT is
not applicable when the API software
executes in asynchronous mode.
601355 Rev A
API Functions
2-515
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Indicates whether the API software waits for
final status from VolServ (or times-out) for
Cancel commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The total wait time for a command is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
The value to be put in USER_FIELD for
Cancel commands. USER_FIELD is 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 Cancel commands.
Neither the API software nor VolServ uses
USER_FIELD.
2-516
API Functions
601355 Rev A
API Guide
Return Values
•
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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_cancel_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Cancel API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_cancel_defaults(void)
#else
VST_BOOLEAN vst_cancel_defaults()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_PRIORITY
priority;
API Functions
2-517
Functions
Example
VSCMD_Cancel_SetDefaults returns:
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
user_field;
timeout;
retries;
wait_flag;
enterprise_id;
/* get parameters from user */
printf(“*** Cancel default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Cancel_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-518
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Cancel(l)
Functions
601355 Rev A
API Functions
2-519
API Guide
VSCMD_
Checkin
VSCMD_Checkin checks media into the VolServ system.
Only media that have been previously checked out can be
checked in.
Checkin is a logical operation. After a medium is logically
checked into the VolServ system, the medium must be
physically entered into an archive before becoming available
for client use (mounting,…).
A medium is physically entered into the VolServ system via the
Enter functionality available from the appropriate archive's
console display. The Enter functionality is not available through
the API interface.
If a destination archive is not specified on a VSCMD_Checkin
request, the media are returned to the archive where they were
checked-out.
Synopsis
VST_BOOLEAN VSCMD_Checkin
(VST_COMMAND_HANDLE
handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Checkin request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
2-520
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the archive where the specified
media are to be checked-in. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on this request.
VSID_MEDIA_ID_LIST (int)
Number of media to check-in.
(char **)
An array of the identifiers of the media to
check-in.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-521
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request.
The default time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_CheckIn returns:
•
•
2-522
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The request failed.A return code of
VSE_FALSE (which is 0) means the request failed.
601355 Rev A
API Guide
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
API Functions
2-523
Functions
601355 Rev A
-
API Guide
•
Example
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2-524
API Functions
/****************************************
*********
*
* FUNCTION: vst_checkin_execute
*
* PURPOSE:
* This function sends a checkin command
to the
* VolServ software, prompting for all
values needed.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_checkin_execute(void)
#else
VST_BOOLEAN vst_checkin_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
char
*
medialist[VST_MAX_ITEMS];
VST_ARCHIVE_NAME
archive;
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Check-in parameters
***\n” );
printf(“\nEnter Archive name (return
for default) “);
601355 Rev A
API Guide
28
29
30
31
32
33
34
35
36
37
38
40
41
42
43
44
45
46
47
48
49
50
51
52 }
601355 Rev A
return ( rc );
API Functions
2-525
Functions
39
gets( archive);
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle Note
that the */
/* command handle is not destroyed in
this*/
/* routine, but in vst_dispatch when
final */
/* status is received. */
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. *Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_Checkin(cmd,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_ID_LIST,
count, medialist,
VSID_ENDFIELD);
}
API Guide
Notes
The API must be initialized with a call to VS_Initialize
before this function may be executed.
VolServ does not generate intermediate status messages for a
Checkin request.
VSCMD_Checkin can trigger MediaClass callbacks from
VolServ.
Media must be checked-out before they can be specified on a
Checkin request.
Media checked-out of one archive can be checked into another
archive, as long as the MediaClass group where the media
belong are associated with archive media class(es) in the
receiving archive.
Failure of a Checkin request for one medium does not fail the
request for all specified media.
Media checked out from more than one archive can be checked
in as a single group into a single new archive (assuming
necessary archive media class associations are defined.)
Media that are checked out from more than one archive and are
checked in as a single group without a target archive specified
(the archive name is set to the empty string, “ “) are returned to
their respective check-out archives.
The total length of time the API software waits for a command
status from VolServ is (VSID_RETRY_LIMIT plus 1)
multiplied by VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
2-526
API Functions
601355 Rev A
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on a Checkin request submitted through the API
interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Checkin
commands are set with VSCMD_Checkin_SetDefaults.
If command-specific defaults are set for Checkin
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Checkin
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Checkin command:
•
VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_ID, V
• SID_MEDIA_ID_ENTRY,
• VSID_MEDIA_ID_TABLE,
601355 Rev A
API Functions
2-527
Functions
•
API Guide
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
• VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-528
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Checkin_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
Checkin_
SetDefaults
VSCMD_Checkin_SetDefaults sets command-level
default parameters for Checkin commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Checkin
commands are set with VSCMD_Checkin_SetDefaults.
If command-specific defaults are set for Checkin
commands, they override the global defaults for all
commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Checkin
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
VST_BOOLEAN VSCMD_Checkin_SetDefaults
(
“…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
API Functions
2-529
API Guide
•
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_NAME
(VST_ARCHIVE_NAME)
Name of the archive inwhere the specified
media are to be checked-in. Valid archive
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
intermediate and final status for Checkin
commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for Checkin
commands.
VSID_MEDIA_ID_LIST (int)
Number of media to check-in.
(char **)
An array of the identifiers of the media to
check-in.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Checkin
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Checkin commands. VSID_RETRY_LIMIT is
not applicable when the API software
executes in asynchronous mode.
2-530
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Checkin commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The total wait time for a command is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
The default time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Checkin
commands. USER_FIELD is 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 this
Checkin command. Neither the API software
nor VolServ uses USER_FIELD.
Return Values
601355 Rev A
VSCMD_Checkin_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
API Functions
2-531
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
2-532
API Functions
/****************************************
*********
*
* FUNCTION: vst_checkin_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Checkin API call.
*
* PARAMETERS:
* none
*
****************************************
**********/
#ifdef ANSI_C
VST_BOOLEAN
vst_checkin_defaults(void)
#else
VST_BOOLEAN vst_checkin_defaults()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
char
archive[VSD_ARCHIVE_NAME_LEN];
/* get parameters from user */
printf(“*** Check-in default
parameters ***\n” );
601355 Rev A
API Guide
31
32
33
34
35
36
37
38
39
40
42
43
44
45
46 }
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Checkin(l)
API Functions
2-533
Functions
41
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
printf(“\nEnter Archive “);
gets( archive);
/* set the default parameters */
rc = VSCMD_Checkin_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ARCHIVE_NAME,
archive,
VSID_ENDFIELD);
API Guide
VSCMD_
Checkout
VSCMD_Checkout checks media out of the VolServ system.
Media that are checked out are still known by VolServ, but are
unavailable for client allocation.
Upon receipt of a Checkout request, VolServ marks the
specified media for check out. If the specified media are
contained in archives, VolServ adds the media to the eject
candidate list of the containing archive. An operator must select
the Eject functionality from the appropriate archive’s console
display to physically remove the checked-out media from the
containing archive. The VolServ Eject functionality is not
available over the API interface.
The client may specify a comment on the VSCMD_Checkout
command. This comment is displayed on the applicable archive
console eject list for each medium being checked out.
Synopsis
VST_BOOLEAN VSCMD_Checkout
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Checkout request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
2-534
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_COMMENT (VST_COMMENT)
The text information (comment) to appear on
the appropriate archive console eject list for
each medium specified for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on this request.
VSID_MEDIA_ID_LIST (int)
Number of media to check-out.
(char **)
An array of the identifiers of the media to
check-out.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
601355 Rev A
API Functions
2-535
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_Checkout returns:
•
•
2-536
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
601355 Rev A
API Guide
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-537
Functions
601355 Rev A
•
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2-538
API Functions
/****************************************
*********
*
* FUNCTION: vst_checkout_execute
*
* PURPOSE:
* This function sends a checkout command
to the
* VolServ software, prompting for all
values needed.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_checkout_execute(void)
#else
VST_BOOLEAN vst_checkout_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
char
*
medialist[VST_MAX_ITEMS];
VST_COMMENT
comment;
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Check-out Parameters
***\n” );
printf(“\nEnter Checkout Comment “);
gets( comment);
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
601355 Rev A
API Guide
33
34
35
36
37
38
39
40
41
42
44
45
46
47
48
49
50
51
52
53 }
601355 Rev A
return ( rc );
API Functions
2-539
Functions
43
/* vst_dispatch when finalstatus is
received. */
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the
VolServ */
/* software. Note that status
is not */
/* processed here. Instead, it
is */
/* processed it the
vst_dispatch */
/* routine. Also, note that
default */
/* values such as timeout,
value retry */
/* limit and priority are set
as default */
/* parameters. */
rc = VSCMD_Checkout(cmd,
VSID_COMMENT, comment,
VSID_MEDIA_ID_LIST, count,
medialist,
VSID_ENDFIELD);
}
API Guide
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ does not generate intermediate status messages in
response to a Checkout request.
A Checkout request can trigger unsolicited status messages
from VolServ.
Checked-out media are unavailable for use by VolServ clients.
Failure of a Checkout request for one medium does not fail the
request for all specified media.
A medium can be checked out even if it is currently allocated.
Attempts to physically eject an allocated medium fail until the
medium is no longer is use.
The Checkout request only marks a specified medium for
logical check out and places the medium on the appropriate
archive’s Eject list. The medium is physically removed from the
archive when the operator ejects the medium from the archive.
A medium marked for check out can be unmarked (removed
from the Eject list) by the ClearEject request. An operator can
also remove a medium from the Eject list by performing an
Eject Fail operation from an archive console. The Eject Fail
functionality is available over the API interface via the
ClearEject request.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
2-540
API Functions
601355 Rev A
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on a Checkout request submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Checkin
commands are set with VSCMD_Checkout_SetDefaults.
If command-specific defaults are set for Checkout
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Checkout
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Checkout request:
•
VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_ID,
• VSID_MEDIA_ID_ENTRY,
• VSID_MEDIA_ID_TABLE,
601355 Rev A
API Functions
2-541
Functions
•
API Guide
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
• VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-542
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Checkout_SetDefaults(l
601355 Rev A
API Guide
VSCMD_
Checkout_Set
Defaults
VSCMD_Checkout_SetDefaults sets the command-level
default parameters for Checkout commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Checkout
commands are set with VSCMD_Checkout_SetDefaults.
If command-specific defaults are set for Checkout
commands, they override the global defaults for all
commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Checkout
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
Synopsis
VST_BOOLEAN VSCMD_Checkout_SetDefaults
(
“…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
API Functions
2-543
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Checkout commands.
VSID_COMMENT (VST_COMMENT)
The text information (comment) to appear on
the appropriate archive console Eject list for
each medium specified for Checkout
commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for Checkout
commands.
VSID_MEDIA_ID_LIST (int)
Number of media to check out with Checkout
commands.
(char **)
An array of the identifiers of the media to
check out with Checkout commands.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Checkout
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Checkout commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode.
2-544
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Checkout commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Checkout
commands. USER_FIELD is 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
Checkout commands. Neither the API
software nor VolServ uses USER_FIELD.
Return Values
601355 Rev A
VSCMD_Checkout_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
API Functions
2-545
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2-546
API Functions
/****************************************
*********
*
* FUNCTION: vst_checkout_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Checkout API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_checkout_defaults(void)
#else
VST_BOOLEAN vst_checkout_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
VST_COMMENT
comment;
/* get parameters from user */
printf(“*** Check-out Default
Parameters ***\n” );
601355 Rev A
API Guide
30
31
32
33
34
35
36
37
38
39
41
42
43
44
45 }
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Checkout(l)
API Functions
2-547
Functions
40
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
printf(“\nEnter Checkout Comment “);
gets( comment);
/* set the default parameters */
rc = VSCMD_Checkout_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_COMMENT,
comment,
VSID_ENDFIELD);
API Guide
VSCMD_Clear
Eject
VSCMD_ClearEject reverses the scheduled ejection of one
or more media from an archive.
Ejects can be generated during processing of the VolServ
Checkout, Export, Mount, and Move commands. Ejects can
also be generated during automatic migration of media.
The ClearEject command essentially undoes the completion of
these commands. Media are removed from the Eject list and
returned to the available state.
For example, if a client issues an Export request for a specific
medium, the specified medium is scheduled for removal by
adding the medium to the Eject list for the archive associated
with the medium. If the client decides the medium should not be
removed from its associated archive, the client can issue a
ClearEject request, and VolServ removes the medium from the
Eject list.
Synopsis
VST_BOOLEAN VSCMD_ClearEject
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this ClearEject
request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function are shown in the following "Parameters"
paragraph.
2-548
API Functions
601355 Rev A
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for ClearEject commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for ClearEject
commands.
VSID_MEDIA_ID_LIST (int)
Number of media to remove from the Eject list.
(char **)
An array of the identifiers of the media to
remove from the Eject list.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for ClearEject
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software
ClearEject commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode.
601355 Rev A
API Functions
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
2-549
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
ClearEject commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The total wait time for a command is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for ClearEject
commands. USER_FIELD is 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
ClearEject commands. Neither the API
software nor VolServ uses USER_FIELD.
Return Values
VSCMD_ClearEject returns:
•
2-550
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
601355 Rev A
API Guide
•
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
API Functions
2-551
Functions
601355 Rev A
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
API Guide
•
Example
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2-552
API Functions
/****************************************
*********
*
* FUNCTION: vst_cleareject_execute
*
* PURPOSE:
* This function sends an cleareject
command to the
* VolServ software, prompting for all
values needed.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_cleareject_execute(void)
#else
VST_BOOLEAN vst_cleareject_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
char
*
medialist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** ClearEject Parameters
***\n” );
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle */
601355 Rev A
API Guide
28
29
30
31
32
33
34
35
36
37
39
40
41
42
43
44
45
46
47
48 }
Notes
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ does not generate intermediate status messages in
response to a ClearEject request.
601355 Rev A
API Functions
2-553
Functions
38
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_ClearEject(cmd,
VSID_MEDIA_ID_LIST, count,
medialist,
VSID_ENDFIELD);
}
API Guide
A ClearEject request can trigger MediaClass callbacks from
VolServ.
Failure of a ClearEject request for one medium does not fail the
request for all media.
An operator can also remove a medium from the Eject list by
performing an Eject Fail from the appropriate archive console.
The Eject Fail functionality is not available over the API
interface.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on a ClearEject request submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
2-554
API Functions
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for ClearEject
commands are set with
VSCMD_ClearEject_SetDefaults. If
601355 Rev A
API Guide
command-specific defaults are set for ClearEject
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a ClearEject
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Checkout request:
•
VSID_ERROR_CODE,
Functions
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_ID,
• VSID_MEDIA_ID_ENTRY,
• VSID_MEDIA_ID_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
• VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-555
API Guide
See Also
2-556
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_ClearEject_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_Clear
Eject_
SetDefaults
VSCMD_ClearEject_SetDefaults sets command-level
default parameters for ClearEject commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific parameter
defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for ClearEject
commands are set with
VSCMD_ClearEject_SetDefaults. If
command-specific defaults are set for the ClearEject
command, they override the global defaults for all
ClearEject commands.
Functions
•
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a ClearEject
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_ClearEject_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-557
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for ClearEject commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for ClearEject
commands.
VSID_MEDIA_ID_LIST (int)
Number of media to remove from the Eject list
with ClearEject commands.
(char **)
An array of the identifiers of the media to
remove from the Eject list with ClearEject
commands.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for ClearEject
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
ClearEject commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode.
2-558
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
ClearEject commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for ClearEject
commands. USER_FIELD is 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
ClearEject commands. Neither the API
software nor VolServ uses USER_FIELD.
601355 Rev A
API Functions
2-559
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
Return Values
Example
VSCMD_ClearEject_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2-560
API Functions
/****************************************
*********
*
* FUNCTION: vst_cleareject_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ClearEject API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_cleareject_defaults(void)
#else
VST_BOOLEAN
vst_cleareject_defaults()
#endif
{
601355 Rev A
API Guide
19
20
21
22
23
24
25
26
27
28
29
34
35
36
37
38
39
40
41 }
rc =
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** ClearEject Default
Parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ClearEject_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-561
Functions
30
31
32
33
VST_BOOLEAN
VSE_FALSE;
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
API Guide
See Also
2-562
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ClearEject(l)
601355 Rev A
API Guide
VSCMD_
Connect
VSCMD_Connect associates a specified Internet address with
a specified enterprise identifier. After this association is
established, the client can listen for MediaClass callbacks and
VolServ statuses that are generated for that enterprise.
Any Internet address can be associated with more than one
enterprise identifier. In addition, there is no limit to the number
of Internet addresses that can be associated with any given
enterprise identifier.
If an enterprise has multiple clients, each client is kept on a
receiving queue. If the first enterprise client cannot receive
status or MediaClass callback (because of an RPC error), the
next client in the queue is tried. This continues until a client
successfully receives the status/callback or until the receiving
queue is exhausted. If no client successfully receives the status,
it is logged and VolServ invokes its retry scheme. If no client
successfully receives a MediaClass callback, it is logged and
discarded.
There are two methods for scheduling status/callbacks to
enterprise clients:
•
601355 Rev A
Round Robin
API Functions
2-563
Functions
When sending intermediate or final status to the client
associated with an enterprise, VolServ uses the enterprise
identifier to determine the address to use for the status. This is
done by matching the enterprise identifier passed in the request
with those in the internal table and using the associated address
information.
API Guide
The statuses and callbacks are distributed evenly among the
connected clients. After a status or callback is received by a
client, that client is placed at the end of the receiving queue.
This method is used by distributed processing systems that want
to distribute the work among clients.
•
First Received/First Scheduled
The statuses and callbacks are issued to the client that
successfully received the previous status or callback. The only
time a different client is tried is when the first client fails (at
which time the failed client is placed at the end of the queue).
The scheduling method selected by VolServ is dictated by the
ENTERPRISE_ROUND_SCHEDULING environmental
variable. If this variable is set to ‘Y’, the Round Robin
scheduling method is used. Otherwise, the First Received/First
Scheduled method is used. (The
ENTERPRISE_ROUND_SCHEDULING environmental
variable is in the envvar.config configuration file.)
Synopsis
VST_BOOLEAN VSCMD_Connect
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Connect request.
•
“…” = 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 use for this
command. The valid parameter identifiers and types for this
function are shown in the following "Parameters"
paragraph.
2-564
API Functions
601355 Rev A
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE)
The connect handle that contains the
enterprise callback address information to be
used by VolServ when returning status and
MediaClass callbacks to an enterprise.
VSID_CONNECT_HANDLE is not applicable if
VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBER are specified.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
to receive status messages and MediaClass
callbacks from VolServ.
VSID_PROCEDURE_NUMBER is not applicable
if VSID_CONNECT_HANDLE is specified.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process to
receive status messages and MediaClass
callbacks from VolServ.
VSID_PROGRAM_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
601355 Rev A
API Functions
2-565
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol VolServ uses to return status
messages and MediaClass callbacks to this
client. The default VSID_PROTOCOL is
VSE_PROT_UDP. VSID_PROTOCOL is not
applicable if VSID_CONNECT_HANDLE is
specified.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN)
Internet socket address for this client.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The enterprise identifier of the enterprise with
which a connection is desired.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
2-566
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process to
receive status messages and MediaClass
callbacks from VolServ.
VSID_VERSION_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
VSCMD_Connect returns:
•
•
601355 Rev A
Functions
Return Values
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
API Functions
2-567
API Guide
Example
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
2-568
API Functions
/****************************************
*********
*
* FUNCTION: vst_connect_execute
*
* PURPOSE:
601355 Rev A
API Guide
6
7
8
9
10
11
12
13
14
15
16
17
18
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
601355 Rev A
/* get parameters from user */
printf(“*** Connect parameters
***\n” );
printf(“Enter Enterprise ID ==> “ );
TargetEnterpriseID =
(VST_ENTERPRISE_ID)
atoi(gets(input));
printf(“Enter program number ==>”);
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“Enter Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
printf(“Enter Procedure Number ==> “
);
API Functions
2-569
Functions
19
* This executes the VSCMD_Connect API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_connect_execute(void)
#else
VST_BOOLEAN vst_connect_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ENTERPRISE_ID
TargetEnterpriseID;
VST_SOCKADDR_IN
socketaddress;
VST_PROGRAM_NUMBER
prognum;
VST_COMMAND_HANDLE
cmd;
VST_VERSION_NUMBER
versnum;
VST_PROCEDURE_NUMBER
procnum;
int
temp;
API Guide
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
2-570
API Functions
procnum = (VST_PROCEDURE_NUMBER)
atoi(gets(input));
printf(“Enter Socket sin family ==> “
);
temp = atoi(gets(input));
socketaddress.sin_family = (short)
temp;
printf(“Enter Socket sin port ==> “
);
temp = atoi(gets(input));
socketaddress.sin_port = (u_short)
temp;
printf(“Enter Socket sin address ==>
“ );
temp = atoi(gets(input));
socketaddress.sin_addr = (u_long)
temp;
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_Connect(cmd,
601355 Rev A
API Guide
62
63
64
65
66
67
VSID_TARGET_ENTERPRISE_ID,TargetE
nterpriseID
VSID_PROGRAM_NUMBER,
prognum,
VSID_VERSION_NUMBER,
versnum,
VSID_PROCEDURE_NUMBER, procnum,
VSID_PROTOCOL,
VSE_PROT_TCP,
VSID_SOCKADDR_IN,
socketaddress,
VSID_ENDFIELD);
68
69
}
70 return ( rc );
71 }
Notes
VolServ generates no intermediate status in response to a
Connect command.
The Connect command cannot trigger MediaClass callbacks
from VolServ.
The VSID_CONNECT_HANDLE parameter may be used after a
Connect Query command to reconnect an enterprise after the
client has gone down.
The Connect command cannot be cancelled. The client may
remove an enterprise/address association by issuing a
VSCMD_Disconnect command to the VolServ system.
A client may use the VSCMD_ConnectQuery command to
determine if an enterprise is already registered and, if so, under
what address.
601355 Rev A
API Functions
2-571
Functions
The API must be initialized with a call to VS_Initialize
before this function can be executed.
API Guide
If a client sends a VSCMD_Connect command for an
enterprise that already exists, future status messages may be
returned to a different client. When a client specifies
“enterprise” in the client header message, the resultant status
messages may be returned to any client associated with the
same enterprise identifier.
The MediaClass callback receiving queue is kept separate from
the command status receiving queue. Each of these queues is
scheduled separately. Therefore, a client for an enterprise that
receives both statuses and callbacks may receive a command
status and a MediaClass callback before another client receives
either message.
The VSCMD_Connect command can be issued only through
the client interface. The association between an enterprise and
its client cannot be established via the GUI.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this command is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Connect command submitted through the API interface to the
VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
A client can issue the Connect Query command to determine if
an enterprise is already registered and, if so, under what
address.
2-572
API Functions
601355 Rev A
API Guide
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Connect
command are set with VSCMD_Connect_SetDefaults. If
command-specific defaults are set for the Connect
command, they override the global defaults for all
commands.
Tip
Functions
To override a default (global or command-specific)
parameter value for a specific instance of a Connect
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Connect command:
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_TARGET_ENTERPRISE_ID,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-573
API Guide
See Also
2-574
API Functions
•
vsapi(l),
•
VS_Connect_Create(l),
•
VS_Connect_Destroy(l),
•
VS_Connect_GetFields(l),
•
VS_Connect_SetFields(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_ConnectQuery(l),
•
VSCMD_Connect_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
Connect_Set
Defaults
VSCMD_Connect_SetDefaults sets command-level
default parameters for Connect commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Archive
Media Class commands are set with
VSCMD_CreateArchiveMediaClass_SetDefaults. If
command-specific defaults are set for Create Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Archive
Media Class command, the parameter identifier and the
value to be used for
Synopsis
VST_BOOLEAN VSCMD_Connect_SetDefaults
(
“…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
API Functions
2-575
Functions
•
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Connect commands.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE)
The connect handle that contains the
enterprise callback address information to be
used by VolServ when returning status and
MediaClass callbacks to an enterprise.
VSID_CONNECT_HANDLE is not applicable if
VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBER are specified.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Connect requests.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Connect
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
to receive status messages and MediaClass
callbacks from VolServ.
VSID_PROCEDURE_NUMBER is not applicable
if VSID_CONNECT_HANDLE is specified.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process to
receive status messages and MediaClass
callbacks from VolServ.
VSID_PROGRAM_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
2-576
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Internet protocol VolServ uses to return status
messages and MediaClass callbacks to this
client. The default VSID_PROTOCOL is
VSE_PROT_TCP. VSID_PROTOCOL is not
applicable if VSID_CONNECT_HANDLE is
specified.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Connect commands. VSID_RETRY_LIMIT is
not applicable when the API software
executes in asynchronous mode.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN)
Internet socket address for this client.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Connect commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The enterprise identifier of the enterprise with
which a connection is desired.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
601355 Rev A
API Functions
2-577
Functions
VSID_PROTOCOL (VST_PROTOCOL)
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Connect
commands. USER_FIELD is 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 Connect
commands. Neither the API software nor
VolServ uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process to
receive status messages and MediaClass
callbacks from VolServ.
VSID_VERSION_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
Return Values
Example
VSCMD_Connect_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
2-578
API Functions
/****************************************
*********
*
* FUNCTION: vst_connect_defaults
*
* PURPOSE:
601355 Rev A
API Guide
6
7
8
9
10
11
12
13
14
15
16
17
18
19
26
27
28
29
30
31
32
33
34
35
601355 Rev A
/* get parameters from user */
printf(“*** Connect default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Connect_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
API Functions
2-579
Functions
20
21
22
23
24
25
* This function sets the default
parameters for the
* VSCMD_Connect API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_connect_defaults(void)
#else
VST_BOOLEAN vst_connect_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
36
37
38
39
40 }
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-580
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Connect(l)
601355 Rev A
API Guide
VSCMD_
ConnectQuery
VSCMD_ConnectQuery returns a list of all client Internet
addresses currently associated with the specified enterprise
identifier.
The Connect Query command can be issued through either the
client interface or the GUI. However, only from the GUI can
“query all” be specified to list all enterprises. From the client
interface, only one enterprise can be specified within a single
command. This restriction prevents any client from listing the
clients of other enterprises being serviced by VolServ.
VST_BOOLEAN VSCMD_ConnectQuery
(VST_COMMAND_HANDLE handle
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Connect Query
command.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
601355 Rev A
API Functions
Functions
Synopsis
2-581
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_QUERY_ENTERPRISE_ID
(VST_REQUEST_ID)
Identifier of the enterprise to be queried.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this command. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
2-582
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
VSCMD_ConnectQuery returns:
•
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-583
Functions
•
601355 Rev A
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
API Guide
2-584
API Functions
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
601355 Rev A
/* get parameters from user */
printf(“*** Connect Query parameters
***\n” );
printf(“\nEnter Enterprise ID ==>”);
enterprise = (VST_ENTERPRISE_ID)
atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
API Functions
2-585
Functions
14
15
/****************************************
*********
*
* FUNCTION: vst_connectquery_execute
*
* PURPOSE:
* This executes the VSCMD_ConnectQuery
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_connectquery_execute(void)
#else
VST_BOOLEAN
vst_connectquery_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_ENTERPRISE_ID
enterprise;
VST_COMMAND_HANDLE
cmd;
API Guide
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46 }
Notes
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_ConnectQuery(cmd,
VSID_QRY_ENTERPRISE_ID,
enterprise,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Connect Query request.
The Connect Query command does not trigger unsolicited
MediaClass callbacks from VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
2-586
API Functions
601355 Rev A
API Guide
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this command is returned to
the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Connect Query command submitted through the API interface
to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
A client can issue the Connect Query command to determine
if an enterprise is already registered. If it is registered, its
address is also reported.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Connect
Query command are set with
VSCMD_ConnectQuery_SetDefaults. If
command-specific defaults are set for the Connect Query
command, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Connect
Query command, the parameter identifier and the
value to be used for the parameter can be submitted
on the specific command itself.
The following fields can be retrieved from the status handle
after a successful Connect Query command:
601355 Rev A
API Functions
2-587
Functions
•
API Guide
•
VSID_CONNECT_HANDLE,
• VSID_CONNECT_HANDLE_ENTRY,
• VSID_CONNECT_HANDLE_TABLE,
•
VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
•
VSID_QUERY_ENTERPRISE_ID,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-588
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_Table(l),
•
VS_Command_GetFields(l),
•
VS_Connect_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Connect_Handle_Table(l),
601355 Rev A
API Guide
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VS_Table_GetFields(l),
Functions
601355 Rev A
API Functions
2-589
API Guide
VSCMD_
ConnectQuery_
Set-Defaults
VSCMD_ConnectQuery_SetDefaults sets
command-level default parameters for Connect Query
commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Archive
Media Class commands are set with
VSCMD_CreateArchiveMediaClass_SetDefaults. If
command-specific defaults are set for Create Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
Synopsis
2-590
API Functions
VST_BOOLEAN VSCMD_ConnectQuery_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for Connect Query commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Connect Query commands.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Connect
Query commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise whose connection
is queried.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Connect Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-591
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Connect Query commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The total wait time for a command is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE. The default time-out
value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Connect
Query commands. USER_FIELD is 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 Connect Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
2-592
API Functions
VSCMD_ConnectQuery_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
601355 Rev A
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
601355 Rev A
/* get parameters from user */
printf(“*** Connect Query default
parameters ***\n” );
API Functions
2-593
Functions
7
8
9
10
11
12
/****************************************
*********
*
* FUNCTION: vst_connectquery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ConnectQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_connectquery_defaults(void)
#else
VST_BOOLEAN
vst_connectquery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
29
30
31
32
33
34
35
36
37
38
39
40 }
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ConnectQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-594
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ConnectQuery(l)
601355 Rev A
API Guide
VSCMD_
CreateArchiv
eMediaClass
VSCMD_CreateArchiveMediaClass creates an archive
media class association. An archive media class association is
the association of a MediaClass group with a defined archive.
A MediaClass group establishes common characteristics for the
media it contains; no inherent restrictions are placed on where
those media can reside within an archive.
Archive media class associations provide the ability to:
601355 Rev A
Restrict which archives can contain specific classes/types of
media.
•
Constrain the number of specific media classes/types that
can be associated with any given archive.
•
Preclude the erroneous assignment of media into an archive
that is incompatible with that media type.
•
Ensure an archive has a desired mix of classes of media.
•
If needed, preclude media of a known data format from
being assigned into an archive that does not have access to a
drive compatible with that media type.
VST_BOOLEAN VSCMD_CreateArchiveMediaClass
(VST_COMMAND_HANDLE
handle,
“…”,
VSID_ENDFIELD)
API Functions
2-595
Functions
Synopsis
•
API Guide
Arguments
•
handle = The command handle for this Create Archive
Media Class command.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
Specifies what action VolServ takes 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.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Name of the archive to be 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)
Percentage of the total MediaClass capacity
that can be stored in this archive.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE)
Preferred locations (in table format) for media
assigned to this archive media class.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
2-596
API Functions
601355 Rev A
API Guide
Parameter Type
Description
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)
Percentage of VSID_CAPACITY below which
the specified migration policy option is
performed or terminated. 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)
MediaClass group associated with the archive
media class relationship. Valid MediaClass
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MIGRATION_PRIORITY
(VST_PRIORITY)
The migration priority to be applied to this
archive media class.
VSID_PERCENT (VST_PERCENT)
Percentage of the MediaClass capacity
allowed in the archive associated with the
archive media class relationship.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-597
Functions
VSID_HIGH_MARK (VST_HIGH_MARK)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The destination archive for media
automatically migrated out of this archive
media class. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
2-598
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_CreateArchiveMediaClass returns:
•
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-599
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2-600
API Functions
/****************************************
*********
*
* FUNCTION:
vst_createarchivemediaclass_execu
te
*
* PURPOSE:
* This executes the
VSCMD_CreateArchiveMediaClass
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createarchivemediaclass_execu
te(void)
#else
VST_BOOLEAN
vst_createarchivemediaclass_execu
te()
601355 Rev A
API Guide
601355 Rev A
API Functions
2-601
Functions
17 #endif
18 {
19
int
i;
20
int
count;
21
VST_BOOLEAN
rc =
VSE_FALSE;
22
VST_ARCHIVE_NAME
archive;
23
VST_MEDIA_CLASS_NAME
mediaclass;
24
VST_CAPACITY
capacity;
25
VST_ARCHIVE_ACTION_OPTION action;
26
VST_HIGH_MARK
highmark;
27
VST_LOW_MARK
lowmark;
28
VST_PRIORITY
migpri;
29
VST_ARCHIVE_NAME
targetarchive;
30
VST_TABLE_HANDLE
comphandletable;
31
VST_COMPONENT_HANDLE
comphandle;
32
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
33
VST_COMPONENT_ID
CompID;
34
VST_COMMAND_HANDLE
cmd;
35
36
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
/* get parameters from user */
38
printf(“*** Create Archive Media
Class parameters ***\n” );
39
printf(“Enter Archive Name ==> “ );
40
gets( archive );
41
printf(“Enter Media Class Name ==> “
);
42
gets( mediaclass );
43
printf(“Enter Capacity Percent ==> “
);
44
capacity = atoi(gets(input));
45
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
46
action = atoi(gets(input));
API Guide
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
/* these parameters only need to
be set if */
/* the archivemediaclass is being
set up to */
/* support migration. */
printf(“Enter Target Archive ==> “
);
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
62
63
64
65
66
67
68
69
70
71
72
73
2-602
API Functions
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
601355 Rev A
API Guide
74
75
76
77
78
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
79
80
81
82
83
84
85
86
87
88
89
VS_Table_AddEntry(comphandletable
,comphandle);
}
/* This also only needs to be set
if it is */
/* actually being used. It is not
needed */
/* otherwise. */
90
91
92
93
94
VSCMD_CreateArchiveMediaClass_Set
Defaults(
95
96
97
98
99
601355 Rev A
VSID_COMPONENT_HANDLE_TABLE,comph
andletable,
VSID_ENDFIELD);
}
/* create the command handle */
API Functions
2-603
Functions
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE, CompType,
VSID_COMP_ID, CompID,
VSID_ENDFIELD);
API Guide
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123}
2-604
API Functions
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
}
return ( rc );
601355 Rev A
API Guide
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Create Archive Media Class command.
VSCMD_CreateArchiveMediaClass does not trigger
unsolicited MediaClass callbacks from VolServ.
The migration policy options for are no action, operator
notification, and automatic migration.
When the number of media in an archive media class reaches
the high mark threshold, VolServ:
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
When the number of media in an archive media class drops to
the low mark threshold, VolServ:
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
•
Terminates automatic migration of media if the migration
policy is set to migrate.
The capacity value of an archive media class is relative to the
MediaClass group specified overall capacity. Consideration
should be given to all MediaClass groups that are able to share
this archive to ensure that reasonably comparable capacity
limitations and high/low marks are set for each archive media
class.
601355 Rev A
API Functions
2-605
Functions
•
API Guide
Archive media class computed capacity limits are “soft”, that is,
they can be exceeded when media are imported or moved in
from another archive. If automigration is specified, media of
this MediaClass group is then marked for movement to their
target archive. The media type capacity designates the “hard”
limit when entering media into an archive.
Media can only reside in an archive if their associated
MediaClass group has an archive media class assignment in that
archive.
An archive media class computed capacity is refigured if the
capacity of a MediaClass group changes.
Checks to determine if the high mark has been reached or
exceeded or the low mark has been reached or passed occur:
•
After any Eject, Enter, Reclassify, or Modify Archive
Media Class command executes.
•
After the MediaClass group or archive media class
association are redefined.
The sum of all archive media class capacities can exceed the
archive’s physical ability to house media. If VSID_CAPACITY
values are set unrealistically high and VSID_HIGH_MARK is
similarly high, the archive may physically completely fill
before any automigration procedure is triggered.
Components listed as preferred for storage of media of this
MediaClass group do not have exclusive ownership of those
components.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
2-606
API Functions
601355 Rev A
API Guide
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Create Archive Media Class request submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Archive
Media Class commands are set with
VSCMD_CreateArchiveMediaClass_SetDefaults. If
command-specific defaults are set for Create Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Create Archive Media Class request:
•
VSID_ARCHIVE_NAME,
•
VSID_COMPONENT_HANDLE,
• VSID_COMPONENT_HANDLE_ENTRY,
601355 Rev A
API Functions
2-607
Functions
•
API Guide
• VSID_COMPONENT_HANDLE_TABLE,
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_CLASS_NAME,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-608
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreateArchiveMediaClass_SetDefaults(l),
•
VSCMD_DeleteArchiveMediaClass(l),
•
VSCMD_ModifyArchiveMediaClass(l)
601355 Rev A
API Guide
VSCMD_
CreateArchiv
eMediaClass_
SetDefaults
VSCMD_CreateArchvieMediaClass_SetDefaults
sets the command-level default parameters for Create Archive
Media Class commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Media
Class commands are set with
VSCMD_CreateMediaClass_SetDefaults. If
command-specific defaults are set for Create Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_CreateArchive
MediaClass_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-609
Functions
•
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
Specifies what action VolServ takes 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.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Name of the archive to be 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)
Percentage of the total MediaClass capacity
that can be stored in this archive.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Create Archive Media Class
commands.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE)
Preferred locations (in table format) for media
assigned to this archive media class.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Create Archive Media Class
commands.
2-610
API Functions
601355 Rev A
API Guide
Parameter Type
Description
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)
Percentage of VSID_CAPACITY below which
the specified migration policy option is
performed or terminated. 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)
MediaClass group associated with the archive
media class relationship. Valid MediaClass
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MIGRATION_PRIORITY
(VST_PRIORITY)
The migration priority to be applied to this
archive media class.
VSID_PERCENT (VST_PERCENT)
Percentage of the MediaClass group capacity
allowed in the archive associated with the
archive media class relationship.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Create Archive Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-611
Functions
VSID_HIGH_MARK (VST_HIGH_MARK)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Create Archive Media Class commands. Valid
options are VSE_TRUE (API software waits for
final status) and VSE_FALSE (API software
does not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The destination archive for media
automatically migrated out of this archive
media class. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The total wait time for a command is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE. The default time-out
value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Create
Archive Media Class commands.
USER_FIELD is 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 Create Archive
Media Class commands. Neither the API
software nor VolServ uses USER_FIELD.
2-612
API Functions
601355 Rev A
API Guide
Return Values
•
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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
/****************************************
*********
*
* FUNCTION:
vst_createarchivemediaclass_execu
te
*
* PURPOSE:
* This executes the
VSCMD_CreateArchiveMediaClass
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createarchivemediaclass_execu
te(void)
#else
API Functions
2-613
Functions
Example
VSCMD_CreateArchiveMediaClass_SetDefaults
returns:
API Guide
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
2-614
API Functions
VST_BOOLEAN
vst_createarchivemediaclass_execu
te()
#endif
{
int
i;
int
count;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_CAPACITY
capacity;
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
highmark;
VST_LOW_MARK
lowmark;
VST_PRIORITY
migpri;
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
CompID;
VST_COMMAND_HANDLE
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
capacity = atoi(gets(input));
601355 Rev A
API Guide
45
46
47
48
49
50
51
52
53
54
55
58
59
60
61
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
/* these parameters only need to
be set if */
/* the archivemediaclass is being
set up to */
/* support migration. */
printf(“Enter Target Archive ==> “
);
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
62
63
64
65
66
67
68
69
70
71
601355 Rev A
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
API Functions
2-615
Functions
56
57
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
API Guide
72
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
73
74
75
76
77
78
79
80
81
82
83
84
85
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE, CompType,
VSID_COMP_ID, CompID,
VSID_ENDFIELD);
86
87
88
89
VS_Table_AddEntry(comphandletable
,comphandle);
}
/* This also only needs to be set
if it is */
/* actually being used. It is not
needed */
/* otherwise. */
90
91
92
93
94
VSCMD_CreateArchiveMediaClass_Set
Defaults(
95
96
97
2-616
API Functions
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
VSID_ENDFIELD);
}
601355 Rev A
API Guide
98
99
100
101
102
103
104
105
106
107
108
110
111
112
113
114
115
116
117
118
119
120
121
122
123}
601355 Rev A
return ( rc );
API Functions
2-617
Functions
109
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
}
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-618
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_CreateArchiveMediaClass(l)
601355 Rev A
API Guide
VSCMD_
CreateMediaClass
VSCMD_CreateMediaClass creates a new MediaClass
group.
Synopsis
VST_BOOLEAN VSCMD_CreateMediaClass
(
VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Create Media
Class request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
API Functions
2-619
Functions
601355 Rev A
A MediaClass group establishes common characteristics for the
media it contains.
API Guide
Parameters
Parameter Type
Description
VSID_CAPACITY (VST_CAPACITY)
Maximum number of media allowed in this
MediaClass group.
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
Indicates whether this MediaClass group
supports the “mount by MediaClass”
functionality.
Valid VSID_CLASS_MOUNT_STATE values
are enumerated in the vs_types.h file.
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION)
Indicates whether callbacks are activated for
this MediaClass group, and if they are, which
callback scheme is used. Valid
VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_HIGH_MARK (VST_HIGH_MARK)
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_HOST_NAME (VST_HOST_NAME)
Network-assigned name of the computer
where the task that “listens” for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTION is set to
VSE_CLASS_RPC_STANDARD.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Unique name assigned to the new
MediaClass group.
2-620
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Media type supported by this MediaClass
group. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
User-specified comment included in a system
log message when the number of media in the
MediaClass group exceeds the high mark
threshold. MediaClass name, fill level, high
mark threshold, and capacity values are
automatically included in the system log
message and need not be included in
VSID_NOTIFY_COMMENT.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for this request.
Assignable priority values are restricted to a
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
to receive callbacks generated for this
MediaClass group.
VSID_PROCEDURE_NUMBER is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBER is not applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process to
receive callbacks generated for this
MediaClass group. VSID_PROGRAM_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBER is not
applicable.
601355 Rev A
API Functions
2-621
Functions
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol VolServ uses to send
callbacks for this MediaClass group. The
default VSID_PROTOCOL is VSE_PROT_TCP.
VSID_PROTOCOL is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOL is not applicable.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise to receive callbacks
for this MediaClass group.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
2-622
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process to
receive callbacks generated for this
MediaClass group. VSID_VERSION_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBER is not
applicable.
VSCMD_CreateMediaClass returns:
•
•
601355 Rev A
Functions
Return Values
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
API Functions
2-623
API Guide
2-624
API Functions
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
/****************************************
*********
*
* FUNCTION:
vst_createmediaclass_execute
*
* PURPOSE:
* This executes the
VSCMD_CreateMediaClass API call.
*
* PARAMETERS:
* none
601355 Rev A
API Functions
2-625
Functions
7
8
9
10
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_createmediaclass_execute(void
)
14 #else
15
VST_BOOLEAN
vst_createmediaclass_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_MEDIA_CLASS_NAME
mediaclass;
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
VST_CAPACITY
capacity;
22
VST_CLASS_MOUNT_STATE
mountstate;
23
VST_HIGH_MARK
highmark;
24
VST_COMMAND_HANDLE
cmd;
25
VST_NOTIFY_COMMENT
comment;
26
VST_CLASS_RPC_OPTION
rpc_option;
27
VST_HOSTNAME
rpc_hostname;
28
VST_PROGRAM_NUMBER
rpc_prognum;
29
VST_VERSION_NUMBER
rpc_versnum;
30
VST_PROCEDURE_NUMBER
rpc_procnum;
31
VST_PROTOCOL
rpc_protocol;
API Guide
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
2-626
API Functions
VST_ENTERPRISE_ID
enterpriseid;
/* get parameters from user */
printf(“*** Create Media Class
parameters ***\n” );
printf(“\nEnter Media Class Name
==>”);
gets( mediaclass);
printf(“\nEnter Media Type Name ==>
“);
gets( MediaTypeName);
printf(“\nEnter capacity==>”);
capacity = atoi(gets(input));
printf(“\nEnter class mount state (0)
no, (1) ok: “);
mountstate = atoi(gets(input));
printf(“\nEnter high mark ==>”);
highmark = atoi(gets(input));
printf(“\nEnter notify comment
==>”);
gets(comment);
printf(“\nEnter Option (0) no
callbacks, (1) standard, (2)
Enterprise==>”);
rpc_option = (VST_CLASS_RPC_OPTION)
atoi(gets(input));
if (rpc_option ==
VSE_CLASS_RPC_NONE)
{
VSCMD_CreateMediaClass_SetDefault
s(
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_STANDARD)
{
printf(“\nEnter RPC Host Name
==>”);
601355 Rev A
API Guide
59
60
61
62
63
64
65
66
68
69
70
71
72
73
74
75
76
77
78
79
601355 Rev A
VSCMD_CreateMediaClass_SetDefault
s(
VSID_HOST_NAME,
rpc_hostname,
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_PROGRAM_NUMBER,
rpc_prognum,
VSID_VERSION_NUMBER,
rpc_versnum,
VSID_PROCEDURE_NUMBER,
rpc_procnum,
VSID_PROTOCOL,
rpc_protocol,
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_ENTERPRISE)
{
printf(“\nEnter enterprise id
==>”);
API Functions
2-627
Functions
67
gets(rpc_hostname);
printf(“\nEnter program number
==>”);
rpc_prognum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter version number
==>”);
rpc_versnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter procedure number
==>”);
rpc_procnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter Protocol (6) TCP
or (17) UDP ==>”);
rpc_protocol = (VST_PROTOCOL)
atoi(gets(input));
API Guide
80
enterpriseid =
(VST_ENTERPRISE_ID)
atol(gets(input));
81
VSCMD_CreateMediaClass_SetDefault
s(
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_TARGET_ENTERPRISE_ID,
enterpriseid,
VSID_ENDFIELD);
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
2-628
API Functions
}
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_CreateMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
601355 Rev A
API Guide
104
105
106
107
108
109
110
111}
Notes
VSID_CAPACITY,
capacity,
VSID_CLASS_MOUNT_STATE,
mountstate,
VSID_HIGH_MARK,
highmark,
VSID_NOTIFY_COMMENT,
comment,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
The Create Media Class command does not trigger unsolicited
MediaClass callbacks from VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
Name specified for the MediaClass group must be unique. Any
requests to create non-unique MediaClass names fail.
MediaClass groups can span archives.
MediaClass groups may contain only one type of media.
Checks to determine if VSID_HIGH_MARK has been reached
or exceeded occur after any Reclassify, Import, or Modify
Media Class command.
601355 Rev A
API Functions
2-629
Functions
VolServ generates no intermediate status in response to a
Create Media Class request.
API Guide
VSID_CAPACITY is a “hard” limit. VolServ does not permit
the number of media assigned to a MediaClass group to exceed
the VSID_CAPACITY for that MediaClass group.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Create Media Class request submitted through the API
interface to the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Media
Class commands are set with
VSCMD_CreateMediaClass_SetDefaults. If
command-specific defaults are set for Create Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Create Media Class command:
•
2-630
API Functions
VSID_MEDIA_CLASS_NAME,
601355 Rev A
API Guide
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreateMediaClass_SetDefaults(l),
•
VSCMD_DeleteMediaClass(l),
•
VSCMD_ModifyMediaClass(l)
Functions
601355 Rev A
•
API Functions
2-631
API Guide
VSCMD_
CreateMediaClass_
SetDefaults
VSCMD_CreateMediaClass_SetDefaults sets the
command-level default parameters for Create Media Class
commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Media
Class commands are set with
VSCMD_CreateMediaClass_SetDefaults. If
command-specific defaults are set for Create Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
Synopsis
2-632
API Functions
VST_BOOLEAN VSCMD_CreateMediaClass
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value used as a command default
value for the field. The valid parameter identifiers and types
for this function 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.
Parameters
Parameter Type
Description
Maximum number of media allowed in this
MediaClass group.
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
Indicates whether this MediaClass group
supports the “mount by MediaClass”
functionality. Valid
VSID_CLASS_MOUNT_STATE values are
enumerated in the vs_types.h file.
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION)
Indicates whether callbacks are to be
activated for this MediaClass group, and if
they are, which callback scheme is used. Valid
VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Create Media Class commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on Create Media Class
commands.
601355 Rev A
API Functions
Functions
VSID_CAPACITY (VST_CAPACITY)
2-633
API Guide
Parameter Type
Description
VSID_HIGH_MARK (VST_HIGH_MARK)
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_HOST_NAME (VST_HOST_NAME)
Network-assigned name of the computer
where the task that “listens” for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTION is set to
VSE_CLASS_RPC_STANDARD.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Unique name to be assigned to the new
MediaClass group.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
Media type supported by this MediaClass
group. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
User-specified comment to be included in a
system log message when the number of
media in the MediaClass group exceeds the
high mark threshold. MediaClass name, fill
level, high mark threshold, and capacity
values are automatically included in the
system log message and need not be
included in VSID_NOTIFY_COMMENT.
VSID_PRIORITY (VST_PRIORITY)
Requested execution priority for Create Media
Class commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
2-634
API Functions
601355 Rev A
API Guide
Parameter Type
Description
RPC procedure number of the client process
to receive callbacks generated for this
MediaClass group.
VSID_PROCEDURE_NUMBER is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBER is not applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process to
receive callbacks generated for this
MediaClass group. VSID_PROGRAM_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBER is not
applicable.
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol VolServ uses to send
callbacks for this MediaClass group. The
default VSID_PROTOCOL is VSE_PROT_TCP.
VSID_PROTOCOL is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOL is not applicable.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Create Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-635
Functions
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Create Media Class commands. Valid options
are VSE_TRUE (API software waits for final
status) and VSE_FALSE (API software does
not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise to receive callbacks
for this MediaClass group.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a timeout to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Create
Media Class commands. USER_FIELD is 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 Create Media Class
commands. Neither the API software nor
VolServ uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
RPC version number of the client process to
receive callbacks generated for this
MediaClass group. VSID_VERSION_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBER is not
applicable.
2-636
API Functions
601355 Rev A
API Guide
Return Values
•
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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
601355 Rev A
/****************************************
*********
*
* FUNCTION:
vst_createmediaclass_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_CreateMediaClass API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createmediaclass_defaults(voi
d)
#else
VST_BOOLEAN
vst_createmediaclass_defaults()
API Functions
2-637
Functions
Example
VSCMD_CreateMediaClass_SetDefaults returns:
API Guide
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
VST_PRIORITY
priority;
21
VST_USER_FIELD
user_field;
22
VST_TIME_OUT
timeout;
23
VST_RETRY_LIMIT
retries;
24
VST_STATUS_WAIT_FLAG
wait_flag;
25
VST_ENTERPRISE_ID
enterprise_id;
26
27
/* get parameters from user */
28
printf(“*** Create Archive Media
Class default parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
30
/* set the default parameters */
31
rc =
VSCMD_CreateMediaClass_SetDefault
s(
32
VSID_PRIORITY,
priority,
33
VSID_USER_FIELD,
user_field,
34
VSID_TIMEOUT_VALUE,
timeout,
35
VSID_RETRY_LIMIT,
retries,
36
VSID_STATUS_WAIT_FLAG,
wait_flag,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
2-638
API Functions
601355 Rev A
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_CreateMediaClass(l),
•
VSCMD_DeleteMediaClass(l),
•
VSCMD_ModifyMediaClass(l)
Functions
601355 Rev A
•
API Functions
2-639
API Guide
2-640
API Functions
601355 Rev A
API Guide
VSCMD_Drive
Vary
VSCMD_DriveVary is issued to execute VolServ Drive Vary
requests and to change the operational availability of a drive.
The drive and target state (VSE_COMP_ONLINE,
VSE_COMP_OFFLINE, or VSE_COMP_DIAGNOSTIC) must
be specified.
A drive in the off-line, unavailable, or diagnostic state is
excluded from VolServ's drive selection algorithm.
A Mount or Lock request for an off-line, unavailable, or
diagnostic drive fails.
Conversely, varying a drive to the on-line state makes it
available for selection for Mount or Lock requests.
Functions
Upon receipt of a Drive Vary request, VolServ attempts to
change the state of the specified drive. The return code
presented to the client indicates the success or failure of the
command.
Synopsis
VST_BOOLEAN VSCMD_DriveVary
( VST_COMMAND_HANDLE handle,
"…",
VSID_ENDFIELD )
Arguments
•
handle = The command handle for this Drive Vary
request.
•
"…" = 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 use for this
request. The valid parameter identifiers and types for this
function are shown in the following "Parameters"
paragraph.
601355 Rev A
API Functions
2-641
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_COMP_STATE (VST_COMP_STATE)
The target state for the individual drive
specified in VSID_DRIVE_ID or drive pool
group given in VSID_DRIVEPOOL_NAME.
Used when varying all drives to the same
state. Valid VSID_COMP_STATE values are
enumerated in the vs.types.h file.
VSID_COMP_STATE_LIST (int)
Number of states contained in this list.
(VST_COMP_STATE *)
Pointer to the list of one or more target states
for the drives specified in
VSID_DRIVE_ID_LIST. Used when varying
the drives to different states. Valid
VSID_COMP_STATE_LIST values are
enumerated in the vs_types.h file.
VSID_DRIVE_ID (VST_DRIVE_ID)
An individual drive whose state is varied. Not
necessary when specifying a drive list or drive
pool.
VSID_DRIVE_ID_LIST (int)
Number of drives contained in this list used
with VSID_COMP_STATE_LIST.
(VST_DRIVE_ID *)
Pointer to a list of one or more drives whose
states are to be varied. Not necessary when
specifying a drive list or drive identifier.
2-642
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Name of a drive pool group to vary the state of
all drives associated with the drive pool group.
Valid drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
Not necessary when specifying a drive list or
drive identifier.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
command. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software is to retry
for command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE
(API software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The default time-out value is 120 seconds.
601355 Rev A
API Functions
2-643
Functions
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
API Guide
Return Values
VSCMD_DriveVary returns:
•
•
API Functions
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
•
2-644
VSE_TRUE
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
601355 Rev A
API Functions
2-645
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_drivevary_execute
*
* PURPOSE:
* This executes the VSCMD_DriveVary API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivevary_execute(void)
#else
VST_BOOLEAN vst_drivevary_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
VST_DRIVE_ID
temp_drive_id;
VST_COMP_STATE
temp_state;
API Guide
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
VST_COMP_STATE
statelist[VST_MAX_ITEMS];
VST_DRIVE_POOL_NAME poolname;
int
i;
VST_COMMAND_HANDLE
cmd;
int
varyopt;
int
stateopt;
/* get parameters from user */
printf(“*** Drive Vary parameters
***\n” );
printf(“0) Vary by drive list , 1)
Vary by drive pool 2) Vary by
drive ID ==> “ );
varyopt = atoi(gets(input));
if (varyopt == 0)
{
/* vary by drive list */
/* get the list */
count =
vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
VSCMD_DriveVary_SetDefaults(
VSID_DRIVE_ID_LIST,
count,drivelist,
VSID_ENDFIELD);
}
else if (varyopt == 1)
{
/* vary by drive pool */
return(vst_drivevary_pool_execute
());
48
49
50
51
52
53
54
2-646
API Functions
}
else
{
/* vary a single drive */
printf(“\nEnter Drive ID ==> “);
temp_drive_id =
atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
601355 Rev A
API Guide
55
56
57
58
59
60
61
62
63
64
65
66
67
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
601355 Rev A
}
printf(“0) Vary by state list , 1)
Vary single state ==> “ );
stateopt = atoi(gets(input));
if (stateopt == 0)
{
/* vary by using a list of
component states */
printf(“\nEnter New States
(1)ONLINE (2)OFFLINE (3) DIAG”);
for (i = 0; i < count; i++)
{
printf(“State #%d: “,
count+1);
statelist[i] =
atoi(gets(input));
}
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE_LIST,
count,statelist,
VSID_ENDFIELD);
}
else
{
/* vary everyting to a single
state */
printf(“\nEnter New State (1)
ONLINE (2) OFFLINE (3) DIAG ==>”);
temp_state = atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE,
temp_state,
VSID_ENDFIELD);
}
/* create the command handle */
API Functions
2-647
Functions
68
VSID_DRIVE_ID,
temp_drive_id,
VSID_ENDFIELD);
API Guide
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103}
Notes
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_DriveVary(cmd,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a Drive
Vary request.
VSCMD_DriveVary does not trigger any MediaClass
callbacks from VolServ.
If a list of media specified in a Drive Vary request contains
media of more than one type, the request fails.
2-648
API Functions
601355 Rev A
API Guide
Mounted drives that have their state changed remain in-use;
varying a drive has no impact on client data transfer operations
in progress, and the client receives no automatic notification of
a drive state change.
Drives can be varied regardless of whether or not they are
associated with an archive.
Drives can be varied regardless of whether or not they are
allocated; however, allocated drives that are not on-line
cannot be dismounted.
Drives can be varied by an operator and over the client interface
into the off-line, on-line, and diagnostic states
only.
The VSID_DRIVE_ID_LIST and
VSID_COMP_STATE_LIST parameters require that two
arguments be passed instead of one.
All parameters can be set for the specific request being sent by
passing them to this function, or they can be set for all Drive
Vary requests using the
VSCMD_DriveVary_SetDefaults command.
It is possible to vary drives to different states with one request.
To do this, use the VSID_DRIVE_ID_LIST and
VSID_COMP_STATE_LIST parameters.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
601355 Rev A
API Functions
2-649
Functions
The unavailable state is only assignable by VolServ when
a higher level component in the archive system is no longer
on-line. For example, varying a CLM off-line causes
the associated drive to be viewed as unavailable.
API Guide
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, intermediate and final status for this request is
returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Drive Vary
command are set with
VSCMD_DriveVary_SetDefaults. If command-specific
defaults are set for the Drive Vary command, they override
the global defaults for all commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Drive Vary
command, the parameter identifier and the value to be
used for the parameter can be submitted on the command
request itself.
The following fields can be retrieved from the status handle
after a successful DriveVary request:
2-650
API Functions
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_DRIVE_ID,
601355 Rev A
API Guide
•
VSID_DRIVE_ID_ENTRY,
•
VSID_DRIVE_ID_TABLE,
•
VSID_MEDIA_ID,
•
VSID_MEDIA_ID_ENTRY,
•
VSID_MEDIA_ID_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE, VSID_USER_FIELD.
Note
Functions
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_DriveVary_SetDefaults(l)
API Functions
2-651
API Guide
VSCMD_Drive
Vary_
SetDefaults
VSCMD_DriveVary_SetDefaults is the call issued to set
the command default parameters for Drive Vary commands.
Synopsis
VST_BOOLEAN VSCMD_DriveVary_SetDefaults
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_COMP_STATE (VST_COMP_STATE)
The target state for the individual drive or drive
pool group specified in VSID_DRIVE_ID.
Used when varying the drives to different
states. Valid VSID_COMP_STATE values are
enumerated in the vs_types.h file.
VSID_COMP_STATE_LIST (int)
Number of states contained in this list.
2-652
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Pointer to the list of one or more target states
for the drive specified in
VSID_DRIVE_ID_LIST. Used when varying
the drives to different states. Valid
VSID_COMP_STATE_LIST values are
enumerated in the vs_types.h file.
VSID_DRIVE_ID (VST_DRIVE_ID)
An individual drive whose state is varied. Not
necessary when specifying drives to different
states.
VSID_DRIVE_ID_LIST (int)
Number of drives contained in this list.
(VST_DRIVE_ID *)
Pointer to the list of one or more drives whose
states are to be varied. Not necessary when
specifying drives to different states.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Name of a drive pool group to vary the state of
all drives associated with the drive pool group.
Valid drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
Not necessary when specifying drives to
different states.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Drive Vary commands.
VSID_PRIORITY (VST_PRIORITY)
The execution priority (to override the default
global execution priority) for Drive Vary
command requests.
Assignable priority values are restricted to the
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
601355 Rev A
API Functions
2-653
Functions
(VST_COMP_STATE *)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software is to retry
for command status from VolServ before
returning a time-out to the client software (to
override the default global retry limit) for Drive
Vary command requests.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in the USER_FIELD for Drive
Vary commands. USER_FIELD is 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 Drive Vary commands.
Neither the API software nor VolServ uses
USER_FIELD.
2-654
API Functions
601355 Rev A
API Guide
Return Values
Example
VSCMD_DriveVary_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
7
8
9
10
11
12
13
14
15
16
17
18
19
20
601355 Rev A
API Functions
2-655
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_drivevary_execute
*
* PURPOSE:
* This executes the VSCMD_DriveVary API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivevary_execute(void)
#else
VST_BOOLEAN vst_drivevary_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
VST_DRIVE_ID
temp_drive_id;
VST_COMP_STATE
temp_state;
VST_COMP_STATE
statelist[VST_MAX_ITEMS];
VST_DRIVE_POOL_NAME poolname;
int
i;
VST_COMMAND_HANDLE
cmd;
int
varyopt;
int
stateopt;
/* get parameters from user */
printf(“*** Drive Vary parameters
***\n” );
printf(“0) Vary by drive list , 1)
Vary by drive pool 2) Vary by
drive ID ==> “ );
varyopt = atoi(gets(input));
if (varyopt == 0)
{
/* vary by drive list */
/* get the list */
count =
vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
VSCMD_DriveVary_SetDefaults(
VSID_DRIVE_ID_LIST,
count,drivelist,
VSID_ENDFIELD);
}
else if (varyopt == 1)
{
/* vary by drive pool */
return(vst_drivevary_pool_execute
());
48
49
50
51
52
2-656
API Functions
}
else
{
/* vary a single drive */
printf(“\nEnter Drive ID ==> “);
601355 Rev A
API Guide
53
temp_drive_id =
atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
VSID_DRIVE_ID,
temp_drive_id,
VSID_ENDFIELD);
54
55
56
57
58
59
60
61
62
63
64
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
601355 Rev A
printf(“0) Vary by state list , 1)
Vary single state ==> “ );
stateopt = atoi(gets(input));
if (stateopt == 0)
{
/* vary by using a list of
component states */
printf(“\nEnter New States
(1)ONLINE (2)OFFLINE (3) DIAG”);
for (i = 0; i < count; i++)
{
printf(“State #%d: “,
count+1);
statelist[i] =
atoi(gets(input));
}
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE_LIST,
count,statelist,
VSID_ENDFIELD);
}
else
{
/* vary everyting to a single
state */
printf(“\nEnter New State (1)
ONLINE (2) OFFLINE (3) DIAG ==>”);
temp_state = atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE,
temp_state,
VSID_ENDFIELD);
}
API Functions
2-657
Functions
65
66
67
}
API Guide
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103}
Notes
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that,*/
/* default values such as timeout,
value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_DriveVary(cmd,
VSID_ENDFIELD);
}
return ( rc );
The VSID_DRIVE_ID_LIST and VSID_COMP_STATE_LIST
parameters require that two arguments be passed instead of one.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-658
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_DriveVary(l)
Functions
601355 Rev A
API Functions
2-659
API Guide
VSCMD_
Export
VSCMD_Export is issued to execute the VolServ Export
request.
A client uses the Export request to mark media and related
information for removal from the VolServ system. If the
specified media are not associated with an archive, they are
logically removed from the VolServ system. If the specified
media are associated with an archive, they are placed on the
eject list of the appropriate archive.
A client can also use the Export request to remove information
about media that have been checked out of the archive and are
physically out of the archive.
Upon receipt of an Export request, VolServ marks the specified
media for ejection and returns a successful return code to the
client. A message is sent to the operator console indicating
which media need to be ejected from the archive.
To physically remove media from the archive system, an
operator must select the eject function from the appropriate
archive's console display. The eject function is not available
from the API.
After a medium specified on an Export request is physically
removed from the archive system, the medium is no longer
under the control of VolServ. Consequently, all information
related to exported medium is deleted from the VolServ system.
Synopsis
2-660
API Functions
VST_BOOLEAN VSCMD_Export (
VST_COMMAND_HANDLE handle,
"…",
VSID_ENDFIELD )
601355 Rev A
API Guide
Arguments
•
handle = The command handle for this Export request.
•
"…" = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_COMMENT (VST_COMMENT)
The export comment to use for these media.
This comment appears with the media on the
archive’s eject list.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_MEDIA_ID_LIST (int)
Number of media identified in the list.
(char **)
Identifiers of the media to export.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software is to retry
for command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-661
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
2-662
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_Export returns:
•
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-663
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2-664
API Functions
/****************************************
*********
*
* FUNCTION: vst_export_execute
*
* PURPOSE:
* This function sends an export command
to the
* Volserv, prompting for all values
needed.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_export_execute(void)
#else
VST_BOOLEAN vst_export_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
char
*
medialist[VST_MAX_ITEMS];
VST_COMMENT
comment;
601355 Rev A
API Guide
23
24
25
26
27
28
29
30
31
32
33
37
38
39
40
41
42
43
44
45
46
47
48
49
50
601355 Rev A
cmd;
/* get parameters from user */
printf(“*** Export Parameters ***\n”
);
printf(“\nEnter Export Comment “);
gets( comment);
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as time
out, value */
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_Export(cmd,
VSID_COMMENT, comment,
VSID_MEDIA_ID_LIST,
count, medialist,
VSID_ENDFIELD);
}
API Functions
2-665
Functions
34
35
36
VST_COMMAND_HANDLE
API Guide
51
52 }
Notes
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ does not generate intermediate status in response to an
Export request.
VSCMD_Export triggers MediaClass callbacks from VolServ.
The VSID_Media_ID_LIST parameter requires that two
arguments be passed instead of one.
If a list of media specified in an Export request contains media
of more than one type, the request fails.
The Export command cannot be cancelled. Media can be
“unmarked” for export via the ClearEject request.
A medium that is marked for export from the archive system
cannot be reallocated to satisfy a client request, except to satisfy
a query of the medium. Any other request (except ClearEject)
received for that medium fails.
A medium can be exported even if it is currently allocated.
Attempts to physically eject the medium fail until the medium
is no longer in-use.
The total length of time the API software waits for a command
status in asynchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
2-666
API Functions
601355 Rev A
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Export
command are set with VSCMD_Export_SetDefaults. If
command-specific defaults are set for all commands, they
override the global defaults for all commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Export
command, the parameter identifier and the value to be
used for the parameter can be submitted on the command
itself.
The following fields can be retrieved from the status handle
after a successful Export request:
601355 Rev A
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_ID,
•
VSID_MEDIA_ID_ENTRY,
•
VSID_MEDIA_ID_TABLE,
•
VSID_SEQUENCE_NUM,
API Functions
2-667
API Guide
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-668
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Status_GetFields(l),
•
VS_Initialize(l),
•
VSCMD_Export_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
Export_
SetDefaults
VSCMD_Export_SetDefaults sets command-level
default parameters for the Export command.
Synopsis
VST_BOOLEAN VSCMD_Export_SetDefaults
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_COMMENT (VST_COMMENT)
The export comment to use for these media.
The comment appears with media on the
archive’s eject list.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Export commands.
VSID_MEDIA_ID_LIST (int)
Number of media in the list.
601355 Rev A
API Functions
2-669
Functions
Parameters
API Guide
Parameter Type
Description
(char **)
Array of media identifiers to export.
VSID_PRIORITY (VST_PRIORITY)
The execution priority (to override the default
global execution priority) for Export
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Export commands. VSID_RETRY_LIMIT is
not applicable when the API software
executes in asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Export
commands. USER_FIELD is 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 Export
commands. Neither the API software nor
VolServ uses USER_FIELD.
2-670
API Functions
601355 Rev A
API Guide
Return Values
Example
VSCMD_Export_SetDefaults returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
1
2
3
4
5
6
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
601355 Rev A
/* get parameters from user */
printf(“*** Export default
parameters ***\n” );
API Functions
2-671
Functions
7
8
9
10
11
12
/****************************************
*********
*
* FUNCTION: vst_export_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Export API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_export_defaults(void)
#else
VST_BOOLEAN vst_export_defaults()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
VST_COMMENT
comment;
API Guide
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45 }
Notes
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
printf(“\nEnter Export Comment “);
gets( comment);
/* set the default parameters */
rc = VSCMD_Export_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_COMMENT,
comment,
VSID_ENDFIELD);
return ( rc );
The VSID_MEDIA_ID_LIST parameter requires that two
arguments be passed instead of one.
If a list of media specified in an Export request contains media
of more than one type, the request fails.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-672
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Export(l)
Functions
601355 Rev A
API Functions
2-673
API Guide
VSCMD_
Import
VSCMD_Import is issued to request execution of VolServ
Import requests.
A client uses Import requests to logically add media to the
VolServ system. Upon receipt of an Import request, the
specified media are added to the VolServ system. If a
non-unique media identifier is specified, the Import for that
medium fails.
Import is a logical operation. Media must be physically entered
into an archive before they are available for client use
(mounting,"…"). Entry is performed by an operator selecting
the Enter function from the appropriate archive's console
display. The Enter function is not available from the API.
Synopsis
VST_BOOLEAN VSCMD_Import (
VST_COMMAND_HANDLE handle,
"…",
VSID_ENDFIELD )
Arguments
•
handle = The command handle for this Import request.
•
"…" = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
2-674
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
The destination archive for the imported
media. Valid archive names may contain up to
16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_BATCH_NAME (VST_BATCH_NAME)
The batch name to be assigned to media that
are automatically imported/checked in. Valid
batch names may contain up to 32
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_MANUFACTURER
(VST_MANUFACTURER)
The manufacturer to be assigned to the
imported media. Valid VSID_MANUFACTURER
names may contain up to 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The MediaClass group where imported media
is assigned.
VSID_MEDIA_ID_LIST (int)
Number of media in the list.
(char **)
Array of media identifiers to import.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
601355 Rev A
API Functions
2-675
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
2-676
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_Import returns:
•
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-677
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2-678
API Functions
/****************************************
*********
*
* FUNCTION: vst_import_execute
*
* PURPOSE:
* This function sends a import command
to the
* VolServ software, prompting for all
values needed.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_import_execute(void)
#else
VST_BOOLEAN vst_import_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
int
count;
char
*
medialist[VST_MAX_ITEMS];
VST_ARCHIVE_NAME
archive;
601355 Rev A
API Guide
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
41
42
43
44
45
46
47
48
49
50
51
52
601355 Rev A
mediaclass;
batch;
manuf;
cmd;
/* get parameters from user */
printf(“*** Import parameters ***\n”
);
printf(“\nEnter Archive “);
gets( archive);
printf(“\nEnter Media Class “);
gets( mediaclass);
printf(“\nEnter Batch “);
gets( batch);
printf(“\nEnter Manufacturer “);
gets( manuf);
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
/* make sure that the command handle
is not */
/* null. */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
API Functions
2-679
Functions
39
40
VST_MEDIA_CLASS_NAME
VST_BATCH_NAME
VST_MANUFACTURER_NAM
VST_COMMAND_HANDLE
API Guide
53
/* retry limit and priority are
set as */
/* default parameters. */
rc = VSCMD_Import(cmd,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_BATCH_NAME,
batch,
VSID_MANUFACTURER,
manuf,
VSID_MEDIA_ID_LIST,
count,
medialist,
VSID_ENDFIELD);
54
55
56
57
58
59
60
61
62
63
64
65 }
Notes
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ does not generate intermediate status in response to an
Import request.
VSCMD_Import triggers MediaClass callbacks from VolServ.
The VSID_MEDIA_ID_LIST parameter requires that two
arguments be passed instead of one.
If a list of media specified in an Import request contains media
of more than one type, the request fails.
Import is a logical operation. Media must be physically entered
into an archive by an operator before they are available for
general use.
Media identifier values must be unique throughout a VolServ
system. Non-unique names are rejected.
2-680
API Functions
601355 Rev A
API Guide
Media identifiers of media being imported into manual archives
may contain alphanumeric and special characters, including
spaces. However, spaces cannot be used as leading or trailing
characters. If media in a manual archive can later be moved into
an automated archive, the media identifiers must also conform
to any naming restrictions imposed by the automated archive.
For example, special characters may not be allowed in media
identifiers in the automated archive.
Media type for the media is determined by the media type of the
specified MediaClass group.
After the MediaClass capacity is reached, no additional media
can be imported into the MediaClass group.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for Import
requests is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
601355 Rev A
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
API Functions
2-681
Functions
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
API Guide
•
Command-specific parameter defaults for Import
commands are set with VSCMD_Import_SetDefaults. If
command-specific defaults are set for import commands,
they override the global defaults for all commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of an Import
command, the parameter identifier and the value to be
used for the parameter can be submitted on the request
itself.
The following fields can be retrieved from the status handle
after a successful Import request:
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_ID,
•
VSID_MEDIA_ID_ENTRY,
•
VSID_MEDIA_ID_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE, V
•
SID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-682
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Import_SetDefaults(l)
Functions
601355 Rev A
API Functions
2-683
API Guide
VSCMD_
Import_
SetDefaults
VSCMD_Import_SetDefaults is the call issued to set the
command default parameters for Import commands.
Synopsis
VST_BOOLEAN VSCMD_Import_SetDefaults
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Parameters
Parameter Type
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
2-684
API Functions
Description
The destination archive (to override the default
global destination archive) for the imported
media. Valid archive names may contain up to
16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
601355 Rev A
API Guide
Parameter Type
Description
The batch name to be assigned to media that
are imported. Valid batch names may contain
up to 32 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Import commands.
VSID_MANUFACTURER
(VST_MANUFACTURER)
The manufacturer to be assigned to the
imported media. Valid manufacturer names
may contain up to 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The MediaClass group where imported media
are assigned.
VSID_MEDIA_ID_LIST (int)
Number of media in the list.
(char **)
Pointer to an array of media identifiers to
import.
VSID_PRIORITY (VST_PRIORITY)
The execution priority for Import commands.
Assignable priority values are restricted to the
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Import commands. VSID_RETRY_LIMIT is
not applicable when the API software
executes in asynchronous mode.
601355 Rev A
API Functions
2-685
Functions
VSID_BATCH_NAME (VST_BATCH_NAME)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Import
commands. USER_FIELD is a 16-character
field provided for user information. Information
entered in this field is echoed back to the user
in status messages returned for Import
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
2-686
API Functions
VSCMD_Import_SetDefaults returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
20
21
22
23
24
25
26
27
28
29
30
31
32
33
601355 Rev A
/* get parameters from user */
printf(“*** Import default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
printf(“\nEnter Batch “);
gets( batch);
API Functions
2-687
Functions
15
16
17
18
19
/****************************************
*********
*
* FUNCTION: vst_import_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Import API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_import_defaults(void)
#else
VST_BOOLEAN vst_import_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
VST_BATCH_NAME
batch;
VST_MANUFACTURER_NAME
manuf;
API Guide
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49 }
Notes
printf(“\nEnter Manufacturer “);
gets( manuf);
/* set the default parameters */
rc = VSCMD_Import_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_BATCH_NAME,
batch,
VSID_MANUFACTURER,
manuf,
VSID_ENDFIELD);
return ( rc );
The VSID_MEDIA_ID_LIST parameter requires that two
arguments be passed instead of one. The first argument passed
is the entry number in the appropriate table. The second
argument is a pointer to the location where the value is stored.
If a list of media specified in an Import request contains media
of more than one type, the request fails.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-688
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Import(l)
601355 Rev A
API Guide
VSCMD_
IntransitQuery
VSCMD_IntransitQuery is issued to request execution of
VolServ Intransit Query commands.
A client uses Intransit Query requests to obtain information
about media in the intransit state. The query returns a list of
media identifiers.
A medium is considered to be intransit if it satisfies either of the
following conditions:
•
It is waiting to be entered into an archive as a result of
Import, Mount, Move, Check-in, or a migration activity
processing.
•
It is in the homeless state.
Functions
Synopsis
VST_BOOLEAN VSCMD_IntransitQuery
( VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = The command handle for this Intransit Query
request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
601355 Rev A
API Functions
2-689
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status for this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
2-690
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
VSCMD_IntransitQuery returns:
•
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-691
Functions
•
601355 Rev A
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
API Guide
Example
2-692
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_intransitquery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_IntransitQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-693
Functions
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_intransitquery_execute(void)
14 #else
15
VST_BOOLEAN
vst_intransitquery_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
VST_COMMAND_HANDLE
cmd;
20
21
printf(“*** Intransit Query ***\n” );
22
23
/* create the command handle */
24
/* Note that the command handle is
not */
25
/* destroyed in this routine, but in
*/
26
/* vst_dispatch when final status is
received. */
27
cmd = VS_Command_Create();
28
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
29
{
30
/* Send the command to the VolServ
software. */
31
/* Note that status is not
processed here. */
32
/* Instead, it is processed in the
*/
33
/* vst_dispatch routine. Also,
note that */
34
/* default values such as timeout,
value */
35
/* retry limit and priority are
set as */
36
/* default parameters. There are
no */
37
/* command-specific parameters
for */
38
/* intransit query. */
API Guide
39
40
41
42
43 }
Notes
rc = VSCMD_IntransitQuery(cmd,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to an
Intransit Query request.
VSCMD_IntransitQuery does not trigger any MediaClass
callbacks from VolServ.
The query option on the Intransit Query command is not
currently supported by VolServ. VolServ unconditionally
returns the identifiers of all media in the intransit state.
Only media in the intransit state are queried and returned.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
2-694
API Functions
601355 Rev A
API Guide
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Intransit
Query request are set with
VSCMD_IntransitQuery_SetDefaults. If
command-specific defaults are set for Intransit Query
commands, they override the global defaults for all
commands.
Tip
Functions
To override a default (global or command-specific)
parameter value for a specific instance of an Intransit
Query request, the parameter identifier and the value to be
used for the parameter can be submitted on the request
itself.
The following fields can be retrieved from the status handle
after a successful Intransit Query request:
•
VSID_MEDIA_ID,
•
VSID_MEDIA_ID_ENTRY,
•
VSID_MEDIA_ID_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-695
API Guide
See Also
2-696
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Intransit_GetFields(l),
•
VS_Status_GetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_IntransitQuery_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
IntransitQuery_SetDefaults
VSCMD_IntransitQuery_SetDefaults is issued to set
command-level default parameters for Intransit Query
commands.
Synopsis
VST_BOOLEAN VSCMD_IntransitQuery_SetDefaults (
“…”,
VSID_ENDFIELD )
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH
Name of the client dispatch routine to receive
status for Intransit Query commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID
Identifier of the enterprise, if any, to receive
final status for Intransit Query commands.
601355 Rev A
API Functions
2-697
Functions
Parameters
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
The execution priority (to override the default
global execution priority) for Intransit Query
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive.The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Intransit Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Intransit
Query commands. USER_FIELD is 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 Intransit Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
2-698
API Functions
601355 Rev A
API Guide
Return Values
Example
VSCMD_IntransitQuery_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
7
8
9
10
11
12
13
14
15
16
17
18
19
601355 Rev A
API Functions
2-699
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_intransitquery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_IntransitQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_intransitquery_defaults(void)
#else
VST_BOOLEAN
vst_intransitquery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Intransit Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_IntransitQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-700
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_IntransitQuery(l)
Functions
601355 Rev A
API Functions
2-701
API Guide
VSCMD_Lock
VSCMD_Lock is issued to request execution of the VolServ
Lock command.
The lock identifier assigned to the locked drive is returned to
the client. This lock identifier must be used by clients on
subsequent requests (such as Mount) for those drives.
A request to lock a drive that is busy (mounted or previously
locked) queues until the drive becomes available.
A Lock request that specifies a drive pool or a list of drives
should also indicate the number of drives from the pool/list to
be locked. VolServ selects the drives to lock from within the
pool/list according to drive availability.
A Lock request cannot specify a drive pool or a list of drives
that spans archives.
A Lock request reserves one drive for exclusive use, if a
quantity is not specified on the command.
VolServ considers only on-line drives as candidates to be
locked. If there is not a sufficient number of on-line drives in
the same archive to satisfy a Lock request, the Lock request
fails.
If there is a sufficient number of on-line drives in the same
archive to satisfy a Lock request, but the number of available
on-line drives is not sufficient, the request waits until sufficient
drives become available. Partial locks are not set.
Synopsis
2-702
API Functions
VST_BOOLEAN VSCMD_Lock
( VST_COMMAND_HANDLE handle,
"…",
VSID_ENDFIELD )
601355 Rev A
API Guide
Arguments
•
handle = The command handle for this Lock request.
•
"…" = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVE_COUNT (int)
Number of drives to lock.
VSID_DRIVE_EXCL_LIST (int)
Number of drives in the drive exclusion list.
(VST_DRIVE_ID *)
Pointer to the identifiers of the drives in the
specified drive pool that are not to be locked.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of a single drive to be reserved for
exclusive use.
VSID_DRIVE_ID_LIST (int)
Number of drives in list.
(VST_DRIVE_ID *)
Pointer to the identifiers of one or more drives
to be reserved for exclusive use.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Name of the drive pool group to be reserved
for exclusive use. Valid drive pool names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
601355 Rev A
API Functions
2-703
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
2-704
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_Lock returns:
•
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-705
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2-706
API Functions
/****************************************
*********
*
* FUNCTION: vst_lock_pool_execute
*
* PURPOSE:
* This executes the VSCMD_Lock API call
for drive
* pools.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_lock_pool_execute(void)
#else
VST_BOOLEAN vst_lock_pool_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_DRIVE_ID
excllist[VST_MAX_ITEMS];
int
count;
601355 Rev A
API Guide
22
23
24
25
26
27
28
29
30
35
36
37
38
39
40
41
42
43
44
45
46
47
48
601355 Rev A
dp;
drivecount;
cmd;
printf(“\nEnter Drive Pool Name
==>”);
gets( dp );
printf(“\nEnter drive exclusion
list\n”);
count =
vst_getdrivelist(excllist,
VST_MAX_ITEMS);
printf(“Enter number of drives to
lock ==> “);
drivecount = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_Lock(cmd,
VSID_DRIVEPOOL_NAME, dp,
API Functions
2-707
Functions
31
32
33
34
VST_DRIVE_POOL_NAME
int
VST_COMMAND_HANDLE
API Guide
49
50
51
52
53
54 }
Notes
VSID_DRIVE_EXCL_LIST,
count,excllist,
VSID_DRIVE_COUNT,
drivecount,
VSID_ENDFIELD);
}
return(rc);
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a Lock
request.
VSCMD_Lock does not trigger any MediaClass callbacks from
VolServ.
The VSID_DRIVE_ID_LIST and
VSID_DRIVE_EXCEL_LIST parameters require that two
arguments be passed instead of one.
A Lock command that specifies a list of drives fails if the drives
are not contained within the same physical archive.
A Lock command that specifies a drive pool that spans archives
fails.
Any Mount or Dismount request containing the proper lock
identifier has access to a locked drive.
If a Mount request does not specify a lock identifier for a locked
drive, whether the drive is available for use or not, the Mount
request waits until the drive is both unlocked and available.
2-708
API Functions
601355 Rev A
API Guide
If a Mount request specifies a drive pool and does not specify a
lock identifier, only available and unlocked drives in the
specified drive pool are considered to satisfy the Mount request.
If there are no available, unlocked drives in the specified drive
pool, the Mount request waits until a drive from the specified
drive pool becomes available and unlocked.
There are three ways to specify drives for locking: by drive
identifier, drive list, or drive pool (with or without the exclusion
list).
A Lock command that is queued and awaiting resources can be
cancelled via the Cancel command.
An Unlock command should be issued when the client no
longer needs drives for exclusive use.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the API is not able to receive status for this
request.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
601355 Rev A
API Functions
2-709
Functions
All parameters can be set for the specific request being sent by
passing them to this function, or they can be set for all Lock
requests using the VSCMD_Lock_SetDefaults function.
API Guide
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Lock
command are set with VSCMD_Lock_SetDefaults. If
command-specific defaults are set for the Lock command,
they override the global defaults for all Lock requests.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Lock request,
the parameter identifier and the value to be used for the
parameter can be submitted on the command request
itself.
The following fields can be retrieved from the status handle
after a successful Lock request:
2-710
API Functions
•
VSID_Drive_ID,
•
VSID_DRIVE_ID_ENTRY,
•
VSID_DRIVE_ID_TABLE,
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_TABLE,
•
VSID_LOCK_ID,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
601355 Rev A
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Lock_SetDefaults(l),
•
VSCMD_Unlock(l)
Functions
601355 Rev A
•
API Functions
2-711
API Guide
VSCMD_Lock
_SetDefaults
VSCMD_Lock_SetDefaults is issued to set the
command-level default parameters for the Lock command.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Synopsis
VST_BOOLEAN VSCMD_Lock_SetDefaults
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVE_COUNT (int)
Number of drives to lock.
VSID_DRIVE_EXCL_LIST (int)
Number of drives in list.
(VST_DRIVE_ID *)
Pointer to a list of drives to exclude from the
drive pool.
VSID_DRIVE_ID (VST_DRIVE_ID)
Drive identifier of drive to lock.
2-712
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Number of drives in list.
(VST_DRIVE_ID *)
Pointer to a list of drives to lock.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
The drive pool of drives to lock. Valid drive
pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Lock commands.
VSID_PRIORITY (VST_PRIORITY)
The execution priority for Lock commands.
Assignable priority values are restricted to the
range from 1 (highest) to 32 (lowest) inclusive.
The default priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software (to
override the default global retry limit) for Lock
commands. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
601355 Rev A
API Functions
2-713
Functions
VSID_DRIVE_ID_LIST (int)
API Guide
Parameter Type
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
2-714
API Functions
Description
Value to be put in USER_FIELD for Lock
commands. USER_FIELD is 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 Lock
commands. Neither the API software nor
VolServ uses USER_FIELD.
VSCMD_Lock_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
20
21
22
23
24
25
26
27
28
29
30
31
32
601355 Rev A
/* get parameters from user */
printf(“*** Lock default parameters
***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Lock_SetDefaults(
VSID_PRIORITY,
priority,
API Functions
2-715
Functions
13
14
15
16
17
18
19
/****************************************
*********
*
* FUNCTION: vst_lock_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Lock API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_lock_defaults(void)
#else
VST_BOOLEAN vst_lock_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
33
34
35
36
37
38
39
40 }
Notes
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
The VSID_DRIVE_ID_LIST and VSID_DRIVE_EXCL_LIST
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 a pointer to the location where
the value is stored.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-716
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Lock(l)
601355 Rev A
API Guide
VSCMD_
MediaClassQuery
VSCMD_MediaClassQuery is issued to request execution of
VolServ Media Class Query commands.
Media Class Query commands are used to obtain information
about MediaClass groups in the VolServ system.
Upon receipt of a Media Class Query command, where obtains
the requested information about the specified MediaClass
groups and returns this information to the client.
VST_BOOLEAN VSCMD_MediaClassQuery
( VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD )
Arguments
•
handle = The command handle for this Media Class
Query request.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
601355 Rev A
API Functions
Functions
Synopsis
2-717
API Guide
Parameters
Parameter Type
Description
VSID_CLASS_QUERY_OPT
(VST_QUERY_LIST_OPTION)
Indicates the amount of media information
being requested for each medium in each
reported MediaClass group. Valid
VSID_CLASS_QUERY_OPT values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
If information is being requested on a single
MediaClass group, specifies the name of that
MediaClass group. Valid MediaClass names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single specified MediaClass
group or on all MediaClass groups. Valid
VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-718
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_MediaClassQuery returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
API Functions
2-719
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
2-720
API Functions
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
601355 Rev A
/* get parameters from user */
printf(“*** MediaClass Query
parameters ***\n” );
printf(“0) Query by Media Class Name,
1) Query all ==> “ );
queryopt = atoi(gets(input));
if (queryopt == 0)
{
printf(“\nEnter Media Class Name
==>”);
gets( mediaclass);
}
API Functions
2-721
Functions
14
15
/****************************************
*********
*
* FUNCTION: vst_mediaclassquery_execute
*
* PURPOSE:
* This executes the
VSCMD_MediaClassQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediaclassquery_execute(void)
#else
VST_BOOLEAN
vst_mediaclassquery_execute()
#endif
{
VST_BOOLEAN rc = VSE_FALSE;
VST_QUERY_OPTION queryopt;
VST_QUERY_LIST_OPTION querylistopt;
VST_MEDIA_CLASS_NAME mediaclass;
VST_COMMAND_HANDLE cmd;
API Guide
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
2-722
API Functions
printf(“\n0) no media list, 1) Media
List, 2) Media List Details ==>
“);
querylistopt = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
if (queryopt == 0)
{
/* query one media class */
rc =
VSCMD_MediaClassQuery(cmd,
VSID_QRY_OPTION,
queryopt,
VSID_CLASS_QRY_OPTION,
querylistopt,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD);
}
601355 Rev A
API Guide
60
61
62
63
64
else
{
/* query all media classes */
rc =
VSCMD_MediaClassQuery(cmd,
VSID_QRY_OPTION,
queryopt,
65
66
67
68
69
70 }
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a
MediaClassQuery request.
VSCMD_MediaClassQuery does not trigger any
MediaClass callbacks from VolServ.
When all media classes are requested, each MediaClass status is
reported in a group of one or more intermediate status
messages.
If a request for MediaClass status determines there is no
MediaClass status on which to report, the status message
returns a STATUS_FAIL with error of ERR_NOTFOUND.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
601355 Rev A
API Functions
2-723
Functions
Notes
VSID_CLASS_QRY_OPTION,
querylistopt,
VSID_ENDFIELD);
}
API Guide
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status for Media Class Query requests submitted
through the API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—.global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Media Class
Query commands are set with
VSCMD_MediaClassQuery_SetDefaults. If
command-specific defaults are set for the Media Class
Query commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Media Class
Query command, the parameter identifier and the value to
be used for the parameter can be submitted for the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Media Class Query request:
2-724
API Functions
•
VSID_MEDIACLASS_HANDLE,
•
VSID_MEDIACLASS_HANDLE_ENTRY,
•
VSID_MEDIACLASS_HANDLE_TABLE,
601355 Rev A
API Guide
•
VSID_QUERY_OPTION,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_MediaClass_GetFields(l),
•
VS_Status_GetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_MediaClassQuery_SetDefaults(l)
Functions
601355 Rev A
•
API Functions
2-725
API Guide
VSCMD_
MediaClassQuery_
SetDefaults
VSCMD_MediaClassQuery_SetDefaults is issued to
set the command-level default parameters for the Media Class
Query command.
Synopsis
VST_BOOLEAN VSCMD_MediaClassQuery_SetDefaults (
“…”,
VSID_ENDFIELD )
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Parameters
Parameter Type
Description
VSID_CLASS_QUERY_OPT
(VST_QUERY_LIST_OPTION)
Indicates the amount of media information
being requested for each medium in each
reported MediaClass group. Valid
VSID_CLASS_QUERY_OPT values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Media Class Query commands.
2-726
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Identifier of the enterprise, if any, to receive
intermediate and final status for Media Class
Query commands.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
If information is being requested on a single
MediaClass group, specifies the name of that
MediaClass group. Valid MediaClass names
may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_PRIORITY (VST_PRIORITY)
The execution priority for Media Class Query
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single specified MediaClass
group or on all MediaClass groups. Valid
VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Media Class Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
601355 Rev A
API Functions
2-727
Functions
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Media
Class Query commands. USER_FIELD is 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 Media Class Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
Example
VSCMD_MediaClassQuery_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
2-728
API Functions
/****************************************
*********
*
* FUNCTION:
vst_mediaclassquery_defaults
*
* PURPOSE:
601355 Rev A
API Guide
6
7
8
9
10
11
12
13
14
15
16
20
21
22
23
24
25
26
27
28
29
30
31
32
33
601355 Rev A
/* get parameters from user */
printf(“*** Media Class Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_MediaClassQuery_SetDefaults
(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
API Functions
2-729
Functions
17
18
19
* This function sets the default
parameters for the
* VSCMD_MediaClassQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediaclassquery_defaults(void
)
#else
VST_BOOLEAN
vst_mediaclassquery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
34
35
36
37
38
39
40 }
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-730
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_MediaClassQuery(l)
601355 Rev A
API Guide
VSCMD_
MediaQuery
VSCMD_MediaQuery is issued to request execution of the
VolServ Media Query command.
Upon receipt of a Media Query command, VolServ obtains the
requested information about the specified media and returns
this information to the client.
VST_BOOLEAN VSCMD_MediaQuery
( VST_COMMAND_HANDLE handle,
"…",
VSID_ENDFIELD )
Arguments
•
"…" = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_MEDIA_ID_LIST (int)
Number of media in the list.
(char **)
List of media identifiers to query.
601355 Rev A
API Functions
2-731
Functions
Synopsis
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for each medium specified in a list
of one or more media or whether information
is being requested for all media. Valid
VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
2-732
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
VSCMD_MediaQuery returns:
•
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
API Functions
2-733
Functions
•
601355 Rev A
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
API Guide
Example
2-734
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_mediaquery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_MediaQuery API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
API Functions
601355 Rev A
API Guide
601355 Rev A
API Functions
2-735
Functions
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediaquery_execute(void)
14 #else
15
VST_BOOLEAN vst_mediaquery_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc = VSE_FALSE;
19
VST_QUERY_OPTION
queryopt;
20
int
count;
21
char
*
medialist[VST_MAX_ITEMS];
22
VST_COMMAND_HANDLE
cmd;
23
24
/* get parameters from user */
25
printf(“*** Media Query parameters
***\n” );
26
printf(“0) Query by media list, 1)
Query all ==> “ );
27
queryopt = atoi(gets(input));
28
29
if (queryopt == 0)
30
{
31
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
32
}
33
34
/* create the command handle */
35
/* Note that the command handle is
not */
36
/* destroyed in this routine, but in
*/
37
/* vst_dispatch when final status is
received. */
38
cmd = VS_Command_Create();
39
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
40
{
41
/* Send the command to the VolServ
software. */
API Guide
42
43
44
45
46
47
48
49
50
51
52
53
54 }
Notes
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_MediaQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_MEDIA_ID_LIST, count,
medialist,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a Media
Query request.
VSCMD_MediaQuery does not trigger any MediaClass
callbacks from VolServ.
The VSID_MEDIA_ID_LIST parameter requires that two
arguments be passed instead of one.
When information is requested for more than one media, the
grouped information is returned in one or more intermediate
status messages.
A Media Query can query any media in the VolServ system.
Media specified in a single Media Query request are not
required to be located in the same archive.
2-736
API Functions
601355 Rev A
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status for Media Query requests submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Media Query
commands are set with
VSCMD_MediaQuery_SetDefaults. If
command-specific defaults are set for the Media Query
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Media Query
command, the parameter identifier and the value to be
used for the parameter can be submitted for the specific
command itself.
The following fields can be retrieved from the Status handle
after a successful Media Query request:
601355 Rev A
API Functions
2-737
Functions
•
API Guide
•
•
•
•
•
•
•
•
•
•
•
VSID_ERROR_CODE,
VSID_ERROR_CODE_ENTRY,
VISD_ERROR_CODE_TABLE,
VSID_MEDIA_HANDLE,
VSID_MEDIA_HANDLE_ENTRY,
VSID_MEDIA_HANDLE_TABLE,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-738
API Functions
•
•
•
•
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Command_GetFields(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Media_GetFields(l),
VS_Status_GetFields(l),
VS_Table_GetFields(l),
•
VSCMD_MediaQuery_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
MediaQuery_
SetDefaults
VSCMD_MediaQuery_SetDefaults sets the
command-level default parameters for the Media Query
commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
VST_BOOLEAN VSCMD_MediaQuery_SetDefaults
(
"…",
VSID_ENDFIELD )
Arguments
•
"…" = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Media Query commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Media Query
commands.
VSID_MEDIA_ID_LIST (int)
Number of media identified in the list.
(char **)
List of media identifier to query.
601355 Rev A
API Functions
2-739
Functions
Synopsis
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
The execution priority for Media Query
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for each medium specified in a list
of one or more media or whether information
is being requested for all media. Valid
VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Media Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
2-740
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
601355 Rev A
VSCMD_MediaQuery_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
/****************************************
*********
2 *
3 * FUNCTION: vst_mediaquery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_MediaQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
API Functions
2-741
Functions
Example
Value to be put in USER_FIELD for Media
Query commands. USER_FIELD is 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 Media Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
API Guide
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_mediaquery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_mediaquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
VST_PRIORITY
priority;
21
VST_USER_FIELD
user_field;
22
VST_TIME_OUT
timeout;
23
VST_RETRY_LIMIT
retries;
24
VST_STATUS_WAIT_FLAG
wait_flag;
25
VST_ENTERPRISE_ID
enterprise_id;
26
27
/* get parameters from user */
28
printf(“*** Media Query default
parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
30
/* set the default parameters */
31
rc = VSCMD_MediaQuery_SetDefaults(
32
VSID_PRIORITY,
priority,
33
VSID_USER_FIELD,
user_field,
34
VSID_TIMEOUT_VALUE,
timeout,
35
VSID_RETRY_LIMIT,
retries,
36
VSID_STATUS_WAIT_FLAG,
wait_flag,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
2-742
API Functions
601355 Rev A
API Guide
40 }
Notes
The VSID_MEDIA_ID_LIST parameter requires that two
arguments be passed instead of one. The first argument passed
is the entry number in the appropriate table. The second
argument is a pointer to the location where the value is stored.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_MediaQuery(l)
Functions
601355 Rev A
•
API Functions
2-743
API Guide
VSCMD_
MediaTypeQuery
VSCMD_MediaTypeQuery is issued to request execution of
the VolServ Media Type Query request.
The Media Type Query request is used to obtain information
about media types defined in the VolServ system.
Upon receipt of a Media Type Query request, VolServ obtains
the requested information about the specified media type and
returns this information to the client.
Synopsis
VST_BOOLEAN VSCMD_MediaTypeQuery
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on this request.
2-744
API Functions
601355 Rev A
API Guide
Parameter Type
Description
If VSE_QUERY_OPTION_NONE was specified
for VSID_QUERY_OPTION, indicates the
number of media types specified in the Media
Type list. The maximum number of media
types that can be specified is 32.
(char **)
If VSE_QUERY_OPTION_NONE was specified
for VSID_QUERY_OPTION, specifies the
names of the media types for which
information is being requested.
Valid Media Type names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for each media type specified in a
list of one or more media types or whether
information is being requested for all media
types. Valid VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-745
Functions
VSID_MEDIA_TYPE_LIST (int)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_MediaTypeQuery returns:
•
•
2-746
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
601355 Rev A
API Guide
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the
error occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific
error.
-
If the object code’s value is not VSE_VOLSERV
and is not VSE_NONE, the error occurred in the
API, and the client uses VST_ERROR_CODE to
identify the specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
API Functions
2-747
Functions
601355 Rev A
-
API Guide
•
Example
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
2-748
API Functions
/****************************************
*********
*
* FUNCTION: vst_mediatypequery_execute
*
* PURPOSE:
* This executes the VSCMD_MediaTypeQuery
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediatypequery_execute(void)
#else
VST_BOOLEAN
vst_mediatypequery_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_BOOLEAN
done =
VSE_FALSE;
VST_QUERY_OPTION
queryopt;
int
/count = 0;
char
*
temp_media_type;
char
*
mediatypelist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
601355 Rev A
API Guide
27
28
29
30
31
32
33
34
35
36
37
38
40
41
42
43
44
45
46
47
48
49
50
51
52
53
601355 Rev A
if (queryopt == 0)
{
count =
vst_getmediatypelist(mediatypelis
t, VST_MAX_ITEMS);
}
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
if (queryopt == 0)
{
/* query a list of media types
*/
rc = VSCMD_MediaTypeQuery(cmd,
API Functions
2-749
Functions
39
printf(“*** Media Type Query
parameters ***\n” );
printf(“0) Query by media type list,
1) Query all ==> “ );
queryopt = atoi(gets(input));
API Guide
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71 }
Notes
VSID_QRY_OPTION,
queryopt,
VSID_MEDIA_TYPE_LIST, count,
mediatypelist,
VSID_ENDFIELD);
}
else
{
/* query all media types */
rc = VSCMD_MediaTypeQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_ENDFIELD);
}
}
else
{
rc = VSE_FALSE;
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a Media
Type Query request.
Media Type Query status are cumulative. Each status is added
to the previous status; therefore, after the final status, the status
handle contains all desired information.
VSCMD_MediaTypeQuery does not trigger any MediaClass
callbacks from VolServ.
The VSID_MEDIA_TYPE_LIST parameter requires that two
arguments be passed instead of one.
2-750
API Functions
601355 Rev A
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status for Media Type Query requests submitted
through the API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Media Type
Query commands are set with
VSCMD_MediaQuery_SetDefaults. If
command-specific defaults are set for the Media Type
Query commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Media Type
Query command, the parameter identifier and the value to
be used for the parameter can be submitted for the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Media Type Query request:
601355 Rev A
API Functions
2-751
Functions
•
API Guide
•
•
•
•
•
•
•
•
•
•
•
VSID_ERROR_CODE,
VSID_ERROR_CODE_ENTRY,
VSID_ERROR_CODE_TABLE,
VSID_MEDIATYPE_HANDLE,
VSID_MEDIATYPE_HANDLE_ENTRY,
VSID_MEDIATYPE_HANDLE_TABLE,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-752
•
•
•
•
•
•
•
•
•
•
API Functions
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Command_GetFields(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Media_GetFields(l),
VS_Status_GetFields(l),
VS_Table_GetFields(l),
VSCMD_MediaTypeQuery_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
MediaTypeQuery_
SetDefaults
VSCMD_MediaTypeQuery_SetDefaults is issued to set
the command-level default parameters for Media Type Query
commands.
Synopsis
VST_BOOLEAN VSCMD_MediaTypeQuery_SetDefaults (
“…”,
VSID_ENDFIELD )
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
API Functions
2-753
Functions
601355 Rev A
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Media Type Query commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Media Type
Query commands.
VSID_MEDIA_TYPE_LIST (int)
If VSE_QUERY_OPTION_NONE was specified
for VSID_QUERY_OPTION, indicates the
number of media types specified in the list of
media types.
(char **)
If VSE_QUERY_OPTION_NONE was specified
for VSID_QUERY_OPTION, specifies the
names of the media types for which
information is being requested. Valid Media
Type Query names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_PRIORITY (VST_PRIORITY)
The execution priority for Media Type Query
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicate whether information is being
requested for each media type specified in a
list of one or more media types or whether
information is being requested for all media
types. Valid VSID_QUERY_OPTION values are
enumerated in the vs_types.h file.
2-754
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Media Type Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Media
Type Query commands. USER_FIELD is 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 Media Type Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
601355 Rev A
VSCMD_MediaTypeQuery_SetDefaults returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
API Functions
2-755
Functions
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
API Guide
Example
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2-756
API Functions
/****************************************
*********
*
* FUNCTION: vst_mediatypequery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_MediaTypeQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_mediatypequery_defaults(void)
#else
VST_BOOLEAN
vst_mediatypequery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
601355 Rev A
API Guide
26
27
28
29
30
31
32
33
34
35
37
38
39
40 }
Notes
The VSID_MEDIA_TYPE_LIST parameters requires that two
arguments be passed instead of one.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
API Functions
2-757
Functions
36
/* get parameters from user */
printf(“*** Modify Pool default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_MediaTypeQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
API Guide
•
2-758
API Functions
VSCMD_MediaTypeQuery(l)
601355 Rev A
API Guide
A client uses Modify Media requests to create or modify the
attribute values of an existing medium.
Synopsis
VST_BOOLEAN VSCMD_ModifyMedia
(
“…”,
VSID_ENDFIELD )
Arguments
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
Description
VSID_BATCH_NAME (VST_BATCH_NAME)
The batch name of the medium. A valid batch
name may contain up to 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on all requests.
VSID_FIELD_LIST (int)
Number of field identifiers in the list.
601355 Rev A
API Functions
2-759
Functions
VSCMD_
ModifyMedia
API Guide
Parameter Type
Description
(VST_COUNT *)
Pointer to an array of field identifiers to
associate with the user statistics.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
The manufacturer to be assigned to imported
medium. Valid manufacturer names may
contain up to 32 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_MEDIA_ID (VST_MEDIA_ID)
Media identifier of the medium to update.
VSID_MEDIA_STAT_VALUE_LIST (int)
Number of user statistics in the list.
(char **)
An array of user statistics to associate with the
medium.
VSID_MEDIA_STAT_OPTION_LIST (int)
Number of media statistic options in the list.
(VST_MEDIA_STAT_OPTION *)
An array of media statistic options to place on
the list of user statistics. Valid
VSID_MEDIA_STAT_OPTION_LIST values
are enumerated in the vs_types.h file.
VSID_MODMEDIA_OPTION
(VST_MODMEDIA_OPTION)
The option for the medium's user statistics.
Valid VSID_MODMEDIA_OPTION values are
enumerated in the vs_types.h file.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-760
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status).Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VS_MediaType_SetFields returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed. A return code of
VSE_FALSE (which is 0) means the command failed.
API Functions
2-761
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
2-762
API Functions
-
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
17
18
19
20
21
22
23
24
25
26
27
28
29
30
601355 Rev A
API Functions
2-763
Functions
15
16
/****************************************
*********
*
* FUNCTION: vst_modifymedia_execute
*
* PURPOSE:
* This function actually tests the
VSCMD_ModifyMedia
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modifymedia_execute(void)
#else
VST_BOOLEAN
vst_modifymedia_execute()
#endif
{
int
i;
int
num;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_COMMAND_HANDLE
cmdh;
VST_MEDIA_ID
mediaid;
VST_BATCH_NAME
batch;
VST_MANUFACTURER_NAME
manufacturer;
VST_MODMEDIA_OPTION
modopt;
VST_COUNT
field[VSD_MAX_MEDIA_STATS];
VST_MEDIA_STAT_OPTION
option[VSD_MAX_MEDIA_STATS];
char
* value[VSD_MAX_MEDIA_STATS];
char
valuearray[VSD_MAX_MEDIA_STATS][V
SD_MEDIA_STAT_VALUE_LEN];
API Guide
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
2-764
API Functions
/* get parameters from user */
printf(“*** Modify Media Parameters
***\n”);
printf ( “Enter the media id to
modify ==> “ );
gets(mediaid);
printf ( “Enter the batch name
(return for none) ==> “ );
gets(batch);
printf ( “Enter the manufacturer name
==> “ );
gets(manufacturer);
printf ( “Enter the modify media
option
(1-Delete/2-Update/3-Replace)==>
“ );
modopt = (VST_MODMEDIA_OPTION)
atoi(gets(input));
printf ( “Enter the number of user
statistics ==> “ );
num = atoi(gets(input));
/* loop through the number of user
statistics */
for ( i = 0 ; i < num && i <
VSD_MAX_MEDIA_STATS ; i++ )
{
printf ( “Enter field index[%d]
==> “, i );
field[i] = (VST_COUNT)
atoi(gets(input));
printf ( “Enter user
statistic[%d] ==> “, i );
gets(valuearray[i]);
value[i] = valuearray[i];
printf ( “Enter user stat
option[%d] (1-delete/2-update)
==>“, i );
option[i] =
(VST_MEDIA_STAT_OPTION)
atoi(gets(input));
601355 Rev A
API Guide
55
56
57
58
59
60
61
62
63
64
65
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
601355 Rev A
/* Create the command (assume that
the api is */
/* initialized). Note that status is
processed */
/* in the vst_dispatch routine. */
/* Also, the command handle created
here is */
/* destroyed in the dispatch routine.
*/
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
{
/* execute the modify media command
*/
/* common parameters such as
priority, timeout */
/* value, etc, have been set through
the */
/* VS_Global_SetFields or */
/* VSCMD_ModifyMedia_SetDefaults. */
rc = VSCMD_ModifyMedia ( cmdh,
VSID_MEDIA_ID,
mediaid,
VSID_BATCH_NAME,
batch,
VSID_MANUFACTURER,
manufacturer,
VSID_MODMEDIA_OPTION,
modopt,
VSID_FIELD_LIST,
num, field,
VSID_MEDIA_STAT_VALUE_LIST,
num, value,
VSID_MEDIA_STAT_OPTION_LIST,
num,option,
VSID_ENDFIELD );
}
return ( rc );
API Functions
2-765
Functions
66
}
API Guide
82 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ does not generate intermediate status in response to a
Modify Media request.
VSCMD_ModifyMedia does not trigger any MediaClass
callbacks from VolServ.
The VSID_FIELD_LIST,
VSID_MEDIA_STAT_OPTION_LIST, and
VSID_MEDIA_STAT_VALUE_LIST parameters require that
two arguments be passed instead of one.
Number of items in the field, media stat, and media stat option
lists must be equal.
If the VSID_MODMEDIA_OPTION is set to
VSE_MODMEDIA_OPTION_REPLACE, the current medium
statistics are deleted, and the statistics given in the
VSID_MEDIA_STAT_VALUE_LIST are added for the
medium.
If the VSID_MODMEDIA_OPTION is set to
VSE_MODMEDIA_OPTION_DELETE, the field, stat option,
and stat value lists are ignored, and all current medium statistics
are deleted.
A medium may have as many field values as desired. However,
only up to 16 can be updated at one time through the Modify
Media command.
All medium statistics are kept in character format. If numeric
values are to be kept, they should be left-filled with zeros for
proper comparisons.
2-766
API Functions
601355 Rev A
API Guide
When a medium is exported, its statistics are deleted after the
medium is ejected from the system.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive intermediate
and final status for Modify Media requests submitted through
the API interface to the VolServ system.
Functions
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFields and
VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Modify Media
commands are set with
VSCMD_ModifyMedia_SetDefaults. If
command-specific defaults are set for the Modify Media
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Media
command, the parameter identifier and the value to be
used for the parameter can be submitted for the specific
command itself.
601355 Rev A
API Functions
2-767
API Guide
The following fields can be retrieved from the status handle
after a successful Modify Media request:
•
•
•
•
•
•
•
•
•
VSID_ERROR_CODE,
VSID_ERROR_CODE_ENTRY,
VSID_ERROR_CODE_TABLE,
VSID_FIELD,
VSID_FIELD_ENTRY,
VSID_FIELD_TABLE,
VSID_MEDIA_ID,
VSID_MEDIA_ID_ENTRY,
VSID_MEDIA_ID_TABLE,
•
•
•
•
•
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-768
API Functions
•
VS_Global_SetFields(l),
•
VSCMD_ModifyMedia_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
ModifyMedia_
SetDefaults
VSCMD_ModifyMedia_SetDefaults sets
command-level default parameters for all
VSCMD_ModifyMedia commands.
These defaults override those set in
VS_Global_SetFields. Also, the values set here can be
overridden by passing parameters to VSCMD_ModifyMedia.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
VST_BOOLEAN VSCMD_ModifyMedia_SetDefaults
(
“…”,
VSID_ENDFIELD )
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
601355 Rev A
API Functions
2-769
Functions
Synopsis
API Guide
Parameters
Parameter Type
Description
VSID_BATCH_NAME (VST_BATCH_NAME)
The batch name of the medium. A valid batch
name may contain up to 32 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for Modify Media commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for Modify Media commands.
VSID_FIELD_LIST (int)
Number of field identifiers in the list.
(VST_COUNT *)
Pointer to an array of field identifiers to
associate with the user statistics.
VSID_MANUFACTURER
(VST_MANUFACTURER_NAME)
The manufacturer to be assigned to imported
medium. Valid manufacturer names may
contain up to 32 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_MEDIA_ID (VST_MEDIA_ID)
Media identifier of the medium to modify.
VSID_MEDIA_STAT_OPTION_LIST (int)
Number of items in the list.
(VST_MEDIA_STAT_OPTION *)
An array of media statistic options to place on
the list of user statistics.
VSID_MEDIA_STAT_VALUE_LIST (int)
Number of user statistics in the list.
(char **)
An array of user statistics to associate with the
medium.
VSID_MODMEDIA_OPTION
(VST_MODMEDIA_OPTION)
The option for the medium's user statistics.
Valid VSID_MODMEDIA_OPTION values
are enumerated in the vs_types.h
file.
2-770
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The requested execution priority for Modify
Media commands. Assignable priority values
are restricted to the range from 1 (highest) to
32 (lowest) inclusive. The default priority value
is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Modify Media commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG(VST_STATUS_
WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
a command. Valid options are VSE_TRUE
(API waits for final status) and VSE_FALSE
(API does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Modify
Media commands. USER_FIELD is 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 Modify Media
commands. Neither the API software nor
VolServ uses USER_FIELD.
601355 Rev A
API Functions
2-771
Functions
VSID_PRIORITY (VST_PRIORITY)
API Guide
Return Values
Example
VSCMD_ModifyMedia 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2-772
API Functions
/****************************************
*********
*
* FUNCTION: vst_modifymedia_execute
*
* PURPOSE:
* This function actually tests the
VSCMD_ModifyMedia
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modifymedia_execute(void)
#else
VST_BOOLEAN
vst_modifymedia_execute()
#endif
{
int
i;
int
num;
601355 Rev A
API Guide
21
22
23
24
25
26
27
28
29
30
VST_BOOLEAN
rc =
VSE_FALSE;
VST_COMMAND_HANDLE
cmdh;
VST_MEDIA_ID
mediaid;
VST_BATCH_NAME
batch;
VST_MANUFACTURER_NAME
manufacturer;
VST_MODMEDIA_OPTION
modopt;
VST_COUNT
field[VSD_MAX_MEDIA_STATS];
VST_MEDIA_STAT_OPTION
option[VSD_MAX_MEDIA_STATS];
char
value[VSD_MAX_MEDIA_STATS];
char
valuearray[VSD_MAX_MEDIA_STATS]
34
35
36
37
38
39
40
41
42
43
44
601355 Rev A
/* get parameters from user */
printf(“*** Modify Media Parameters
***\n”);
printf ( “Enter the media id to
modify ==> “ );
gets(mediaid);
printf ( “Enter the batch name
(return for none) ==> “ );
gets(batch);
printf ( “Enter the manufacturer name
==> “ );
gets(manufacturer);
printf ( “Enter the modify media
option
(1-Delete/2-Update/3-Replace)==>
“ );
modopt = (VST_MODMEDIA_OPTION)
atoi(gets(input));
printf ( “Enter the number of user
statistics ==> “ );
num = atoi(gets(input));
API Functions
2-773
Functions
[VSD_MEDIA_STAT_VALUE_LEN];
31
32
33
API Guide
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
2-774
API Functions
/* loop through the number of user
statistics */
for ( i = 0 ; i < num && i <
VSD_MAX_MEDIA_STATS ; i++ )
{
printf ( “Enter field index[%d]
==> “, i );
field[i] = (VST_COUNT)
atoi(gets(input));
printf ( “Enter user
statistic[%d] ==> “, i );
gets(valuearray[i]);
value[i] = valuearray[i];
printf ( “Enter user stat
option[%d] (1-delete/2-update)
==>“, i );
option[i] =
(VST_MEDIA_STAT_OPTION)
atoi(gets(input));
}
/* Create the command (assume that
the api is */
/* initialized). Note that status is
processed */
/* in the vst_dispatch routine. */
/* Also, the command handle created
here is */
/* destroyed in the dispatch routine.
*/
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
{
/* execute the modify media command
*/
/* common parameters such as
priority, timeout */
/* value, etc, have been set through
the */
/* VS_Global_SetFields or */
/* VSCMD_ModifyMedia_SetDefaults. */
601355 Rev A
API Guide
70
71
72
73
74
75
76
77
Notes
Functions
78
79
80
81
82 }
rc = VSCMD_ModifyMedia ( cmdh,
VSID_MEDIA_ID,
mediaid,
VSID_BATCH_NAME,
batch,
VSID_MANUFACTURER,
manufacturer,
VSID_MODMEDIA_OPTION,
modopt,
VSID_FIELD_LIST,
num, field,
VSID_MEDIA_STAT_VALUE_LIST,
num, value,
VSID_MEDIA_STAT_OPTION_LIST,
num, option,
VSID_ENDFIELD );
}
return ( rc );
The VSID_FIELD_LIST,
VSID_MEDIA_STAT_OPTION_LIST, and
VSID_MEDIA_STAT_VALUE_LIST parameters require that two
arguments be passed instead of one.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
VS_Global_SetFields(l),
•
VSCMD_ModifyMedia(l)
API Functions
2-775
API Guide
VSCMD_
CreatePool
VSCMD_CreatePool creates a new VolServ drive pool. The
drive members of the drive pools are specified in the command.
Drive pools are non-exclusive; drives may exist in more than
one pool. Drive pools allow logical groupings of system drives
for simplified reference when a specific drive does not need to
be specified in a command, such as the Mount command.
After receiving a VSCMD_CreatePool request, VolServ
creates a new drive pool and returns status to the client which
indicates the success or failure of the request.
Synopsis
VST_BOOLEAN VSCMD_CreatePool
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Create Pool request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
2-776
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Name of the drive pool to be created. Valid
drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_DRIVE_ID_LIST (int)
Number of drives to include in the new drive
pool.
(VST_DRIVE_ID *)
Pointer to the list of drives to be included in the
new drive pool.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-777
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_CreatePool returns:
•
•
2-778
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
601355 Rev A
API Guide
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API software
and the client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-779
Functions
601355 Rev A
-
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2-780
API Functions
/****************************************
*********
*
* FUNCTION: vst_createpool_execute
*
* PURPOSE:
* This executes the VSCMD_CreatePool API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createpool_execute(void)
#else
VST_BOOLEAN vst_createpool_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_DRIVE_POOL_NAME dp;
int
count;
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Create Pool Parameters
***\n” );
printf(“\nEnter Drive Pool Name
==>”);
gets( dp );
count = vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
601355 Rev A
API Guide
33
34
35
36
37
38
39
40
46
47
48
49 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Create Pool request.
VSCMD_CreatePool does not trigger any MediaClass
callbacks from VolServ.
The name specified for a new drive pool must be unique. A
request to create a drive pool with a non-unique name will fail.
Drive pools can contain zero or more drives.
601355 Rev A
API Functions
2-781
Functions
41
42
43
44
45
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also
retry limit */
/* and priority are set as */
/* default parameters. */
rc = VSCMD_CreatePool(cmd,
VSID_DRIVEPOOL_NAME, dp,
VSID_DRIVE_ID_LIST, count,
drivelist,
VSID_ENDFIELD);
}
return ( rc );
API Guide
Drives belonging to a single drive pool can be associated with
different archives. Drives are not required to be associated with
an archive to belong to a drive pool.
Drive pools can contain drives that support incompatible media
types.
If a drive pool is specified on a Mount request and the specified
drive pool spans archives, VolServ may select a drive to honor
the Mount request that is in a different archive than the medium
that is selected to honor the request. If this occurs, a
Move-Mount action is required. If permitted, the medium is
scheduled for ejection from its parent archive and eventually
entered into the archive associated with the assigned drive.
Whether or not Move-Mount action processing is permitted is
specified at the archive level. The ACTION_MODE and
MOVEWAIT_OPTION attributes control whether or not
Move-Mount processing is allowed for a specific archive.
These attributes are discussed under the
VS_Archive_SetFields and
VS_Archive_GetFields functions.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Create Pool request submitted through the API interface to the
VolServ system.
2-782
API Functions
601355 Rev A
API Guide
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
The VSID_DRIVE_ID_LIST and VSID_COMP_STATE_LIST
parameters require that two arguments be passed instead of one.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Pool
commands are set with
VSCMD_CreatePool_SetDefaults. If
command-specific defaults are set for Create Pool
commands, they override the global defaults for all
commands.
Functions
•
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Create Pool request:
601355 Rev A
•
VSID_DRIVE_ID,
•
VSID_DRIVE_ID_ENTRY,
•
VSID_DRIVE_ID_TABLE,
•
VSID_DRIVEPOOL_NAME,
•
VSID_ERROR_CODE,
API Functions
2-783
API Guide
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-784
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_DeletePool(l),
•
VSCMD_ModifyPool(l)
601355 Rev A
API Guide
VSCMD_
CreatePool_
SetDefaults
VSCMD_CreatePool_SetDefaults sets the
command-level default parameters for Create Pool commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Create Pool
commands are set with
VSCMD_CreatePool_SetDefaults. If
command-specific defaults are set for Create Pool
commands, they override the global defaults for all
commands.
Functions
•
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Create Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_CreatePool_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-785
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Create Pool commands.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Name of the drive pool to be created. Valid
drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_DRIVE_ID_LIST (int)
Number of drives to include in the new drive
pool.
(VST_DRIVE_ID *)
Pointer to the list of drives to be included in the
new drive pool.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Create Pool
commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Create
Pool commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
2-786
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Create Pool commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Create Pool commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Create
Pool commands. USER_FIELD is 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 Create Pool commands.
Neither the API software nor VolServ uses
USER_FIELD.
601355 Rev A
API Functions
2-787
Functions
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
API Guide
Return Values
Example
VSCMD_CreatePool_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2-788
API Functions
/****************************************
*********
*
* FUNCTION: vst_createpool_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_CreatePool API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_createpool_defaults(void)
#else
VST_BOOLEAN
vst_createpool_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
601355 Rev A
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
34
35
36
37
38
39
40 }
Notes
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Create Drive Pool default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_CreatePool_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
The VSID_DRIVE_ID_LIST and VSID_COMP_STATE_LIST
parameters require that two arguments be passed instead of one.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
601355 Rev A
API Functions
2-789
Functions
33
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-790
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_CreatePool(l)
601355 Rev A
API Guide
VSCMD_
DeleteArchive
MediaClass
VSCMD_DeleteArchiveMediaClass deletes an existing
archive media class relationship.
Synopsis
VST_BOOLEAN VSCMD_DeleteArchiveMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Delete Archive
Media Class request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
API Functions
2-791
Functions
601355 Rev A
Upon receipt of a VSCMD_DeleteArchiveMediaClass
request, VolServ disassociates the archive media class
relationship and returns status to the client indicating the
success or failure of the request.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
Name of the archive associated with the
archive media class relationship to be deleted.
Valid archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of the MediaClass group associated
with the archive media class relationship to be
deleted. Valid MediaClass names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-792
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_DeleteArchiveMediaClass returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
API Functions
2-793
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
2-794
API Functions
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
601355 Rev A
/* get parameters from user */
printf(“*** Delete Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
/* create the command handle */
API Functions
2-795
Functions
13
14
/****************************************
*********
*
* FUNCTION:
vst_deletearchivemediaclass_execu
te
*
* PURPOSE:
* This executes the
VSCMD_DeleteArchiveMediaClass
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletearchivemediaclass_execu
te(void)
#else
VST_BOOLEAN
vst_deletearchivemediaclass_execu
te()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_MEDIA_CLASS_NAME mediaclass;
VST_COMMAND_HANDLE
cmd;
API Guide
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50 }
2-796
API Functions
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vs_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
value */
/* limit and priority are
setarchive */
/* retry mediaclassas default
parameters. */
rc =
VSCMD_DeleteArchiveMediaClass(cmd
,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD);
}
return ( rc );
601355 Rev A
API Guide
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Delete Archive Media Class request.
VSCMD_DeleteArchiveMediaClass does not trigger
any MediaClass callbacks from VolServ.
If the archive media class contains any media, the
VSCMD_DeleteArchiveMediaClass request fails. This
includes media that are currently marked for checkout or export
and have not yet been ejected.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Delete Archive Media Class request submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
•
601355 Rev A
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
Command-specific parameter defaults for Delete Archive
Media Class commands are set with
VSCMD_DeleteArchiveMediaClass_SetDefaults. If
API Functions
2-797
Functions
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
API Guide
command-specific defaults are set for Delete Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Archive
Media Class command, the parameter identifier and the
value to be used for the parameter can be submitted on
the specific request itself.
The following fields can be retrieved from the status handle
after a successful Delete Archive Media Class request:
•
•
•
•
•
•
•
VSID_ARCHIVE_NAME,
VSID_MEDIA_CLASS_NAME,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-798
API Functions
601355 Rev A
API Guide
See Also
•
•
•
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_CreateArchiveMediaClass(l),
VSCMD_ModifyArchiveMediaClass(l)
Functions
601355 Rev A
API Functions
2-799
API Guide
VSCMD_
DeleteArchive
MediaClass_
SetDefaults
VSCMD_DeleteArchiveMediaClass_SetDefaults
sets the command-level default parameters for Delete Archive
Media Class commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Delete Archive
Media Class commands are set with
VSCMD_DeleteArchiveMediaClass_SetDefaults. If
command-specific defaults are set for Delete Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Archive
Media Class command, the parameter identifier and the
value to be used for the parameter can be submitted on
the specific request itself.
Synopsis
2-800
API Functions
VST_BOOLEAN VSCMD_DeleteArchiveMedia
Class_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the archive associated with the
archive media class relationship to be deleted.
Valid archive names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Delete Archive Media Class
commands.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of the MediaClass group associated
with the archive media class relationship to be
deleted. Valid MediaClass names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Delete
Archive Media Class commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Delete
Archive Media Class commands. Assignable
priority values are restricted to a range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
601355 Rev A
API Functions
2-801
Functions
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Delete Archive Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Delete Archive Media Class commands. Valid
options are VSE_TRUE (API software waits for
final status) and VSE_FALSE (API software
does not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Delete
Archive Media Class commands.
USER_FIELD is 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 Delete Archive
Media Class commands. Neither the API
software nor VolServ uses USER_FIELD.
2-802
API Functions
601355 Rev A
API Guide
Return Values
•
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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
/****************************************
*********
*
* FUNCTION:
vst_deletearchivemediaclass_defau
lts
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_DeleteArchiveMediaClass API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletearchivemediaclass_defau
lts(void)
#else
API Functions
2-803
Functions
Example
VSCMD_DeleteArchiveMediaClass_SetDefaults
returns:
API Guide
16
17
18
19
20
21
22
23
24
25
VST_BOOLEAN
vst_deleteaarchivemediaclass_defa
ults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
2-804
API Functions
/* get parameters from user */
printf(“*** Delete Archive Media
Class default parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_DeleteArchiveMediaClass_Set
Defaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
601355 Rev A
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_DeleteArchiveMediaClass(l)
Functions
601355 Rev A
API Functions
2-805
API Guide
VSCMD_
DeleteMedia
Class
VSCMD_DeleteMediaClass deletes an existing
MediaClass group from the VolServ system.
Synopsis
VST_BOOLEAN VSCMD_DeleteMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Delete Media Class
request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
2-806
API Functions
Upon receipt of a VSCMD_DeleteMediaClass command,
VolServ removes the MediaClass group and returns status to
the client indicating the success or failure of the request.
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of the MediaClass group to be deleted.
Valid MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
601355 Rev A
API Functions
2-807
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_DeleteMediaClass returns:
•
•
2-808
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
601355 Rev A
API Guide
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
API Functions
2-809
Functions
601355 Rev A
•
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2-810
API Functions
/****************************************
*********
*
* FUNCTION:
vst_deletemediaclass_execute
*
* PURPOSE:
* This executes the
VSCMD_DeleteMediaClass API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletemediaclass_execute(void
)
#else
VST_BOOLEAN
vst_deletemediaclass_execute()
#endif
{
VST_MEDIA_CLASS_NAME
mediaclass;
VST_COMMAND_HANDLE
cmd;
VST_BOOLEAN
rc =
VSE_FALSE;
/* get parameters from user */
printf(“*** Delete Media Class
parameters ***\n” );
printf(“\nEnter Media Class name to
delete ==>”);
gets( mediaclass);
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
601355 Rev A
API Guide
30
31
32
33
34
35
36
37
38
39
43
44
45
46 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Delete Media Class request.
VSCMD_DeleteMediaClass does not trigger any
MediaClass callbacks from VolServ.
If the specified MediaClass group is associated with any
archive media class relationship, the
VSCMD_DeleteMediaClass request fails.
601355 Rev A
API Functions
2-811
Functions
40
41
42
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_DeleteMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_ENDFIELD);
}
return ( rc );
API Guide
If the specified MediaClass group contains any media, the
VSCMD_DeleteMediaClass request fails.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Delete Media Class request submitted through the API
interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Delete Media
Class commands are set with
VSCMD_DeleteMediaClass_SetDefaults. If
command-specific defaults are set for Delete Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Media
Class command, the parameter identifier and the value to
be used for the parameter can be submitted on the specific
request itself.
2-812
API Functions
601355 Rev A
API Guide
The following fields can be retrieved from the status handle
after a successful Delete Media Class request:
•
VSID_MEDIA_CLASS_NAME,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreateMediaClass(l),
•
VSCMD_ModifyMediaClass(l)
Functions
See Also
API Functions
2-813
API Guide
VSCMD_
DeleteMedia
Class_Set
Defaults
VSCMD_DeleteMediaClass_SetDefaults sets the
command-level default parameters for Delete Archive Media
Class commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Delete Archive
Media Class commands are set with
VSCMD_DeleteMediaClass_SetDefaults. If
command-specific defaults are set for Delete Archive Media
Class commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Media
Class command, the parameter identifier and the value to
be used for the parameter can be submitted on the specific
request itself.
Synopsis
2-814
API Functions
VST_BOOLEAN VSCMD_DeleteMediaClass_
SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
•
VSID_ENDFIELD = Rquired at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status on Delete Archive Media Class
commands.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
Name of the MediaClass group to delete. Valid
MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Delete
Archive Media Class commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Delete
Archive Media Class commands. Assignable
priority values are restricted to a range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Delete Archive Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
601355 Rev A
API Functions
2-815
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Delete Archive Media Class commands. Valid
options are VSE_TRUE (API software waits for
final status) and VSE_FALSE (API software
does not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Delete
Archive Media Class commands.
USER_FIELD is 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 Delete Archive
Media Class commands. Neither the API
software nor VolServ uses USER_FIELD.
Return Values
2-816
API Functions
VSCMD_DeleteMediaClass_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
601355 Rev A
API Guide
•
Example
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
601355 Rev A
/* get parameters from user */
printf(“*** Create Archive Media
Class default parameters ***\n” );
API Functions
2-817
Functions
7
8
9
10
11
12
/****************************************
*********
*
* FUNCTION:
vst_deletemediaclass_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_DeleteMediaClass API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletemediaclass_defaults(voi
d)
#else
VST_BOOLEAN
vst_deletemediaclass_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
API Guide
29
30
31
32
33
34
35
36
37
38
39
40 }
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_DeleteMediaClass_SetDefault
s(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-818
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_DeleteMediaClass(l)
601355 Rev A
API Guide
VSCMD_
DeletePool
VSCMD_DeletePool deletes an existing drive pool.
Synopsis
VST_BOOLEAN VSCMD_DeletePool
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Delete Pool request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
API Functions
2-819
Functions
601355 Rev A
Upon receipt of a VSCMD_DeletePool request, VolServ
removes the specified drive pool definition, as well as any drive
pool member associations, and returns status to the client
indicating the success or failure of the request.
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Name of the drive pool to delete. Valid drive
pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
2-820
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
VSCMD_DeletePool returns:
•
•
601355 Rev A
Functions
Return Values
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
API Functions
2-821
API Guide
2-822
API Functions
•
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
19
20
21
22
23
24
25
26
27
28
29
30
31
601355 Rev A
/* get parameters from user */
printf(“*** Delete Pool Parameters
***\n” );
printf(“\nEnter Drive Pool name to
delete ==>”);
gets( dp );
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
API Functions
2-823
Functions
14
15
16
17
18
/****************************************
*********
*
* FUNCTION: vst_deletepool_execute
*
* PURPOSE:
* This executes the VSCMD_DeletePool API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletepool_execute(void)
#else
VST_BOOLEAN vst_deletepool_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_DRIVE_POOL_NAME
dp;
VST_COMMAND_HANDLE
cmd;
API Guide
32
33
34
35
36
37
38
39
40
41
42
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_DeletePool(cmd,
VSID_DRIVEPOOL_NAME, dp,
43
44
45
46 }
Notes
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Delete Pool request.
VSCMD_DeletePool does not trigger any MediaClass
callbacks from VolServ.
Requests submitted prior to a Delete Pool request are not
updated if a drive has already been allocated to the request.
2-824
API Functions
601355 Rev A
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Delete Pool request submitted through the API interface to the
VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Delete Pool
commands are set with
VSCMD_DeletePool_SetDefaults. If
command-specific defaults are set for Delete Pool
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Delete Pool request:
601355 Rev A
API Functions
2-825
Functions
•
API Guide
•
VSID_DRIVEPOOL_NAME,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-826
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreatePool(l),
•
VSCMD_ModifyPool(l)
601355 Rev A
API Guide
VSCMD_
DeletePool_
SetDefaults
VSCMD_DeletePool_SetDefaults sets the
command-level default parameters for Delete Pool commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Delete Pool
commands are set with
VSCMD_DeletePool_SetDefaults. If
command-specific defaults are set for Delete Pool
commands, they override the global defaults for all
commands.
Functions
•
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Delete Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_DeletePool_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-827
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Delete Pool commands.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
Name of the drive pool to delete. Valid drive
pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Delete Pool
commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Delete
Pool commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Delete Pool commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
2-828
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Delete Pool commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Delete
Pool commands. USER_FIELD is 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 Delete Pool commands.
Neither the API software nor VolServ uses
USER_FIELD.
Return Values
601355 Rev A
VSCMD_DeletePool_SetDefaults returns:
•
VSE_TRUE - Successful execution.
•
VSE_FALSE - API failure - An appropriate error code is set
in VSG_Error.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
API Functions
2-829
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2-830
API Functions
/****************************************
*********
*
* FUNCTION: vst_deletepool_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_DeletePool API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_deletepool_defaults(void)
#else
VST_BOOLEAN
vst_deletepool_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
/* get parameters from user */
printf(“*** Delete Pool default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_DeletePool_SetDefaults(
601355 Rev A
API Guide
32
33
34
35
36
37
38
39
40 }
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Functions
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_DeletePool(l)
API Functions
2-831
API Guide
VSCMD_
Disconnect
VSCMD_Disconnect disconnects a specified Internet
address from the specified enterprise identifier. This association
of Internet address with an enterprise identifier was made via
the Connect command.
Even though the specified client Internet address is
disassociated from the given enterprise identifier, the address
can remain active for a different enterprise.
Upon receipt of a VSCMD_Disconnect request, VolServ
verifies that the specified enterprise is associated with the given
Internet address. If the association exists, VolServ removes the
Internet address from the database and returns final status to
inform the client that the request has been completed. If the
association does not exist, the command fails, and failure status
is returned (if possible) to the client.
Synopsis
VST_BOOLEAN VSCMD_Disconnect
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Disconnect request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
2-832
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE)
The connect handle that contains the
enterprise callback address information of the
enterprise whose connection to the VolServ
system is broken. VSID_CONNECT_HANDLE is
not applicable if VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBER are specified.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status for this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
The RPC procedure number of the client
process to disconnect from VolServ.
VSID_PROCEDURE_NUMBER is not applicable
if VSID_CONNECT_HANDLE is specified.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
The RPC program number of the client
process to disconnect from VolServ.
VSID_PROGRAM_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
VSID_PROTOCOL (VST_PROTOCOL)
The Internet protocol VolServ uses to return
status messages and MediaClass callbacks to
the client to be disconnected from VolServ.
VSID_PROTOCOL is not applicable if
VSID_CONNECT_HANDLE is specified.
601355 Rev A
API Functions
2-833
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN)
The Internet socket address for the client to
disconnect from VolServ.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The enterprise identifier of the enterprise to
disconnect from VolServ.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
A value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
The RPC version number of the client process
to disconnect from VolServ.
2-834
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_Disconnect returns:
•
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed.A return code of
VSE_FALSE (which is 0) means the command failed.
To determine where the error occurred, and what the
error was, the client queries the command’s error
handle (with VS_Error_GetFields) to retrieve
the error handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-835
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2-836
API Functions
/****************************************
*********
*
* FUNCTION: vst_disconnect_execute
*
* PURPOSE:
* This executes the VSCMD_Disconnect API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_disconnect_execute(void)
#else
VST_BOOLEAN vst_disconnect_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ENTERPRISE_ID
TargetEnterpriseID;
VST_SOCKADDR_IN
socketaddress;
601355 Rev A
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
38
39
40
41
42
43
44
45
46
47
48
49
50
601355 Rev A
prognum;
cmd;
versnum;
procnum;
temp;
/* get parameters from user */
printf(“*** Disconnect parameters
***\n” );
printf(“Enter Enterprise ID ==> “ );
TargetEnterpriseID =
atoi(gets(input));
printf(“Enter Program Number ==> “ );
prognum = atoi(gets(input));
printf(“Enter Version Number ==> “ );
versnum = atoi(gets(input));
printf(“Enter Procedure Number ==> “
);
procnum = atoi(gets(input));
printf(“Enter Socket sin family ==> “
);
temp = atoi(gets(input));
socketaddress.sin_family = (short)
temp;
printf(“Enter Socket sin port ==> “
);
temp = atoi(gets(input));
socketaddress.sin_port = (u_short)
temp;
printf(“Enter Socket sin address ==>
“ );
temp = atoi(gets(input));
socketaddress.sin_addr = (u_long)
temp;
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
API Functions
2-837
Functions
36
37
VST_PROGRAM_NUMBER
VST_COMMAND_HANDLE
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
int
API Guide
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70 }
Notes
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_Disconnect(cmd,
VSID_TARGET_ENTERPRISE_ID,
TargetEnterpriseID,
VSID_PROGRAM_NUMBER, prognum,
VSID_VERSION_NUMBER, versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_SOCKADDR_IN,
socketaddress,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Disconnect command.
The Disconnect command cannot trigger MediaClass callbacks
from VolServ.
2-838
API Functions
601355 Rev A
API Guide
The VSID_CONNECT_HANDLE parameter may be used after a
Connect Query command to disconnect an enterprise after the
client has gone down.
A VSCMD_Disconnect request can be issued only through
the client interface. The association between an enterprise and
its clients cannot be established via the GUI.
A Disconnect request cannot be cancelled. The client may
reestablish a connection by issuing a Connect request.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Disconnect command submitted through the API interface to
the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
601355 Rev A
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for the Disconnect
command are set with
VSCMD_Disconnect_SetDefaults. If
API Functions
2-839
Functions
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this command is returned to the
enterprise registered with VolServ.
API Guide
command-specific defaults are set for the Disconnect
command, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Disconnect
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
command itself.
The following fields can be retrieved from the status handle
after a successful Disconnect request:
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_TARGET_ENTERPRISE_ID,
•
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-840
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_Connect(l),
•
VSCMD_ConnectQuery(l)
Functions
601355 Rev A
API Functions
2-841
API Guide
VSCMD_
Disconnect_
SetDefaults
VSCMD_Disconnect_SetDefaults sets the
command-level default parameters for Disconnect commands.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Disconnect
commands are set with
VSCMD_Disconnect_SetDefaults. If
command-specific defaults are set for Disconnect
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Disconnect
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
2-842
API Functions
VST_BOOLEAN VSCMD_Disconnect_SetDefaults
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status on Disconnect commands.
VSID_CONNECT_HANDLE
(VST_CONNECT_HANDLE)
The connect handle that contains the
enterprise callback address information of the
enterprise whose connection to the VolServ
system is broken. VSID_CONNECT_HANDLE is
not applicable if VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBER are specified.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Disconnect
commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for
Disconnect commands. Assignable priority
values are restricted to a range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
The RPC procedure number of the client
process to disconnect from VolServ.
VSID_PROCEDURE_NUMBER is not applicable
if VSID_CONNECT_HANDLE is specified.
601355 Rev A
API Functions
2-843
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
The RPC program number of the client
process to disconnect from VolServ.
VSID_PROGRAM_NUMBER is not applicable if
VSID_CONNECT_HANDLE is specified.
VSID_PROTOCOL (VST_PROTOCOL)
The Internet protocol VolServ uses to return
status messages and MediaClass callbacks to
the client to be disconnected from VolServ.
VSID_PROTOCOL is not applicable if
VSID_CONNECT_HANDLE is specified.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Disconnect commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
VSID_SOCKADDR_IN
(VST_SOCKADDR_IN)
The Internet socket address for the client to
disconnect from VolServ.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
The Internet socket address for the client to
disconnect from VolServ. Flag indicating
whether the API software waits for final status
from VolServ (or times-out) for Disconnect
commands. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The enterprise identifier of the enterprise to
disconnect from VolServ.
2-844
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for
Disconnect commands. USER_FIELD is 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 Disconnect commands.
Neither the API software nor VolServ uses
USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
The RPC version number of the client process
to disconnect from VolServ.
Return Values
601355 Rev A
VSCMD_DeletePool_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
API Functions
2-845
Functions
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2-846
API Functions
/****************************************
*********
*
* FUNCTION: vst_disconnect_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Disconnect API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_disconnect_defaults(void)
#else
VST_BOOLEAN
vst_disconnect_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
/* get parameters from user */
printf(“*** Disconnect default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Disconnect_SetDefaults(
601355 Rev A
API Guide
32
33
34
35
36
37
38
39
40 }
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Functions
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
601355 Rev A
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Connect(l),
•
VSCMD_ConnectQuery(l)
API Functions
2-847
API Guide
VSCMD_
Dismount
A VSCMD_Dismount request informs VolServ that the client
is finished using a drive and the medium mounted in the drive.
Upon receipt of a VSCMD_Dismount request for an
automated archive, VolServ determines whether the medium
has been ejected from the drive by the storage subsystem.
If the medium has been ejected from the drive, VolServ
commands the archive robotics to move the medium from the
drive pickup point to a bin within the archive system. A
successful return code is returned to the client after the medium
movement has completed.
If the medium has not been ejected from the drive, the dismount
request fails, and VolServ returns a failure status to the client.
For manual archives, a dismount notice is sent to the
appropriate archive's console display for action. An operator
must dismount the specified medium and then notify VolServ
the medium dismount is complete. VolServ returns status to the
client only after the operator confirms the dismount is complete.
The Dismount command supports a lock identifier parameter.
This parameter is required if the drive to be dismounted has
been previously locked with a Lock request.
Synopsis
2-848
API Functions
VST_BOOLEAN VSCMD_Dismount
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
handle = The command handle for the Dismount request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of the drive to dismount.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_ERROR_COUNT (VST_COUNT)
Number of read/write errors encountered
while the drive was mounted.
VSID_LOCK_ID (VST_LOCK_ID)
The drive’s lock identifier, required if a drive is
locked.
VSID_MEDIA_ID (VST_MEDIA_ID)
Identifier of the medium to dismount.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
601355 Rev A
API Functions
2-849
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
VSID_USAGE_TIME (VST_USAGE)
The length of time, in seconds, the drive was
in use.
2-850
API Functions
601355 Rev A
API Guide
Return Values
VSCMD_Dismount returns:
•
•
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Functions
2-851
Functions
-
•
•
601355 Rev A
VSE_TRUE
API Guide
Example
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2-852
API Functions
/****************************************
*********
*
* FUNCTION: vst_dismount_execute
*
* PURPOSE:
* This routine tests the VSCMD_Dismount
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN vst_dismount_execute(
void )
#else
VST_BOOLEAN vst_dismount_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_MEDIA_ID
media;
VST_DRIVE_ID
drive;
VST_LOCK_ID
lock;
VST_USAGE
time;
601355 Rev A
API Guide
23
24
25
26
27
40
41
42
43
44
45
46
47
48
49
50
51
52
53
601355 Rev A
err;
cmd;
/* get parameters from user */
printf(“*** Dismount parameters
***\n” );
printf(“Enter Media ID ==> “ );
gets( media );
printf(“Enter Drive ID ==> “ );
drive = atoi(gets(input));
printf(“Enter Lock ID ==> “ );
lock = atol(gets(input));
printf(“Enter Usage Time ==> “ );
time = atol(gets(input));
printf(“Enter Error Count ==> “ );
err = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd!= (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_Dismount(cmd,
VSID_DRIVE_ID,
drive,
API Functions
2-853
Functions
28
29
30
31
32
33
34
35
36
37
38
39
VST_COUNT
VST_COMMAND_HANDLE
API Guide
54
VSID_MEDIA_ID,
media,
55
VSID_LOCK_ID,
lock,
56
VSID_USAGE_TIME, time,
57
58
59
60
61 }
Notes
VSID_ERROR_COUNT, err,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Dismount request.
VSCMD_Dismount can trigger MediaClass callbacks from
VolServ.
VSID_USAGE_TIME and VSID_ERROR_COUNT are optional
parameters provided for the client that wants to maintain drive
statistics. Correct values for these parameters are the
responsibility of the client. When VolServ detects these
parameters on a Dismount command, the usage time and/or
error count fields for the specified drive are incremented by the
amount specified on the Dismount command.
A Dismount request cannot be cancelled. If necessary, the client
may request the medium be remounted by issuing a Mount
request.
If the drive specified in a Dismount request is off-line,
unavailable, or in the diagnostic state, the Dismount request
fails.
2-854
API Functions
601355 Rev A
API Guide
If the lock identifier specified on a Dismount request differs
from the lock identifier associated with the specified drive, the
Dismount request fails.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Dismount
commands are set with VSCMD_Dismount_SetDefaults.
If command-specific defaults are set for Dismount
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Dismount
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
601355 Rev A
API Functions
2-855
Functions
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Dismount request submitted through the API interface to the
VolServ system.
API Guide
The following fields can be retrieved from the status handle
after a successful Dismount request:
•
•
•
•
•
•
•
•
•
VSID_DRIVE_ID,
VSID_DRIVE_ID_ENTRY,
VSID_DRIVE_ID_TABLE,
VSID_LOCK_ID,
VSID_MEDIA_ID,
VSID_MEDIA_ID_ENTRY,
VSID_MEDIA_ID_TABLE,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
•
•
•
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-856
•
•
•
•
•
•
•
•
•
API Functions
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_Dismount_SetDefaults(l),
VSCMD_Mount(l),
VSCMD_Lock(l)
601355 Rev A
API Guide
VSCMD_
Dismount_Set
Defaults
VSCMD_Dismount_SetDefaults sets the command-level
default parameters for Dismount commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Dismount
commands are set with VSCMD_Dismount_SetDefaults.
If command-specific defaults are set for Dismount
commands, they override the global defaults for all
commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Dismount
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_Dismount_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-857
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Dismount commands.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of the drive to dismount.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Dismount
commands.
VSID_ERROR_COUNT (VST_COUNT)
Number of read/write errors encountered
while the drive was mounted.
VSID_LOCK_ID (VST_LOCK_ID)
The drive’s lock identifier, required if a drive is
locked.
VSID_MEDIA_ID (VST_MEDIA_ID)
Identifier of the medium to dismount.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Dismount
commands. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
2-858
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Dismount commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Dismount commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Dismount
commands. USER_FIELD is 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
Dismount commands. Neither the API
software nor VolServ uses USER_FIELD.
VSID_USAGE_TIME (VST_USAGE)
The length of time, in seconds, the drive was
in use.
601355 Rev A
API Functions
2-859
Functions
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
API Guide
Return Values
Example
VSCMD_Dismount_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2-860
API Functions
/****************************************
*********
*
* FUNCTION: vst_dismount_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_Dismount API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_dismount_defaults(void)
#else
VST_BOOLEAN vst_dismount_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
601355 Rev A
API Guide
21
22
23
24
25
26
27
28
29
30
31
32
34
35
36
37
38
39
40 }
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Dismount default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Dismount_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-861
Functions
33
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
API Guide
See Also
2-862
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_Dismount(l)
601355 Rev A
API Guide
VSCMD_Drive
PoolQuery
The VSCMD_DrivePoolQuery queries for information
about one drive pool or about all drive pools known to the
VolServ system.
Upon receipt of a Drive Pool Query request, VolServ obtains
the requested information about the specified drive pool and
returns this information to the client.
VST_BOOLEAN VSCMD_DrivePoolQuery
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Drive Pool Query
request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
601355 Rev A
API Functions
2-863
Functions
Synopsis
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Name of the drive pool to query. Valid drive
pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_POOL_QUERY_OPT
(VST_QUERY_LIST_OPTION)
Specifies what drive information, if any, is
requested for each specified drive pool. The
client can request no drive information, a list of
drive identifiers associated with each drive
pool, or detailed information about each drive
associated with each drive pool. Valid
VSID_POOL_QUERY_OPT values are
enumerated in the vs_types.h file.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single specified drive pool or
for all drive pools. Valid VSE_QUERY_OPTION
values are enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-864
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_DrivePoolQuery returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
API Functions
2-865
Functions
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
2-866
API Functions
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
601355 Rev A
API Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
601355 Rev A
/* get parameters from user */
printf(“*** DrivePool Query
parameters ***\n” );
printf(“0) Query by drive pool Name,
1) Query all ==> “ );
queryopt = atoi(gets(input));
if (queryopt == 0)
{
printf(“\nEnter drive pool Name
==>”);
API Functions
2-867
Functions
14
15
/****************************************
*********
*
* FUNCTION: vst_drivepoolquery_execute
*
* PURPOSE:
* This executes the VSCMD_DrivePoolQuery
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivepoolquery_execute(void)
#else
VST_BOOLEAN
vst_drivepoolquery_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_QUERY_OPTION
queryopt;
VST_QUERY_LIST_OPTION
querylistopt;
int
count;
VST_DRIVE_POOL_NAME
drivepool;
VST_COMMAND_HANDLE
cmd;
API Guide
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
2-868
API Functions
gets( drivepool);
}
printf(“\n1) DriveList , 2) DriveList
Details ==> “ );
querylistopt = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
if (queryopt == 0)
{
/* query a single drive pool */
rc = VSCMD_DrivePoolQuery(cmd,
VSID_QRY_OPTION,
queryopt,
VSID_POOL_QRY_OPT,
querylistopt,
VSID_DRIVEPOOL_NAME,
drivepool,
VSID_ENDFIELD);
}
601355 Rev A
API Guide
61
62
63
64
65
66
67
68
69
70
71 }
Notes
else
{
/* query all drive pools */
rc =
VSCMD_DrivePoolQuery(cmd,
VSID_QRY_OPTION,
queryopt,
VSID_POOL_QRY_OPT,
querylistopt,
VSID_ENDFIELD);
}
}
return ( rc );
VolServ can generate intermediate status in response to a Drive
Pool Query request. Statuses are cumulative. Each status is
appended to the previous status so that after the final status is
given, the status handle contains information from all statuses.
VSCMD_CreatePool does not trigger any MediaClass
callbacks from VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Drive Pool Query request submitted through the API interface
to the VolServ system.
601355 Rev A
API Functions
2-869
Functions
The API must be initialized with a call to VS_Initialize
before this function can be executed.
API Guide
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Drive Pool Query
commands are set with
VSCMD_DrivePoolQuery_SetDefaults. If
command-specific defaults are set for Drive Pool Query
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Drive Pool
Query command, the parameter identifier and the value to
be used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Drive Pool Query request:
2-870
API Functions
•
VSID_DRIVEPOOL_HANDLE,
•
VSID_DRIVEPOOL_HANDLE_ENTRY,
•
VSID_DRIVEPOOL_HANDLE_TABLE,
•
VSID_QUERY_OPTION,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
601355 Rev A
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Command_GetFields(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VS_Table_GetFields(l),
•
VSCMD_DrivePoolQuery_SetDefaults(l)
Functions
601355 Rev A
•
API Functions
2-871
API Guide
VSCMD_Drive
PoolQuery_
SetDefaults
VSCMD_DrivePoolQuery_SetDefaults sets the
command-level default parameters for Drive Pool Query
commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Drive Pool Query
commands are set with
VSCMD_DrivePoolQuery_SetDefaults. If
command-specific defaults are set for Drive Pool Query
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Drive Pool
Query command, the parameter identifier and the value to
be used for the parameter can be submitted on the specific
request itself.
Synopsis
2-872
API Functions
VST_BOOLEAN
VSCMD_DrivePoolQuery_SetDefaults (
“…”,
VSID_ENDFIELD)
601355 Rev A
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
Name of the client dispatch routine to receive
status on Drive Pool Query commands.
VSID_DRIVEPOOL_NAME
(VST_DRIVEPOOL_NAME)
Name of the drive pool to query. Valid drive
pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Drive Pool
Query commands.
VSID_POOL_QUERY_OPT
(VST_QUERY_LIST_OPTION)
Specifies what drive information, if any, is
requested for each specified drive pool. The
client can request no drive information, a list of
drive identifiers associated with each drive
pool, or detailed information about each drive
associated with each drive pool. Valid
VSID_POOL_QUERY_OPT values are
enumerated in the vs_types.h file.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Drive Pool
Query commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
601355 Rev A
API Functions
2-873
Functions
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
API Guide
Parameter Type
Description
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for a single specified drive pool or
for all drive pools. Valid VSE_QUERY_OPTION
values are enumerated in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Drive Pool Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Drive Pool Query commands. Valid options
are VSE_TRUE (API software waits for final
status) and VSE_FALSE (API software does
not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELD for Drive Pool
Query commands. USER_FIELD is 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 Drive Pool Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
2-874
API Functions
601355 Rev A
API Guide
Return Values
Example
VSCMD_DrivePoolQuery_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
7
8
9
10
11
12
13
14
15
16
17
18
19
601355 Rev A
API Functions
2-875
Functions
2
3
4
5
6
/****************************************
*********
*
* FUNCTION: vst_drivepoolquery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_DrivePoolQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivepoolquery_defaults(void)
#else
VST_BOOLEAN
vst_drivepoolquery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 }
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** drive pool Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_DrivePoolQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-876
API Functions
601355 Rev A
API Guide
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_DrivePoolQuery(l)
Functions
601355 Rev A
API Functions
2-877
API Guide
VSCMD_Drive
Query
VSCMD_DriveQuery queries for information about one or
more drives known to the VolServ system.
Upon receipt of a Drive Query command, VolServ obtains the
requested information and returns this information to the client.
Synopsis
VST_BOOLEAN VSCMD_DriveQuery
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Drive Query request.
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of a single drive to query.
VSID_DRIVE_ID_LIST (int)
Number of drives to query. Can be greater
than or equal to 1.
(VST_DRIVE_ID *)
Pointer to a list of identifiers of drives to query.
2-878
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Identifier of the enterprise, if any, to receive
final status on this request.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is requested for
all drives known to the VolServ system or for
the drives identified in a list specified with the
Drive Query request. Valid
VSE_QUERY_OPTION values are enumerated
in the vs_types.h file.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
this request. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software for this
request. The default time-out value is 120
seconds.
601355 Rev A
API Functions
2-879
Functions
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
Value to put in USER_FIELD for this request.
USER_FIELD is 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 this request.
Neither the API software nor VolServ uses
USER_FIELD.
VSCMD_DriveQuery returns:
•
VSE_TRUE
-
•
Successful execution if the API is operating in
synchronous mode
- Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
-
•
•
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
- If the object code value is VSE_NONE, the client must
query the global error code (VSG_Error) to
determine where the error occurred.
VSE_ERR_BADHANDLE - Specified handle was not a
valid command handle.
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
2-880
API Functions
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
601355 Rev A
API Guide
-
•
•
VSE_ERR_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
601355 Rev A
/****************************************
*********
*
* FUNCTION: vst_drivequery_execute
*
* PURPOSE:
* This executes the VSCMD_DriveQuery API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivequery_execute(void)
#else
VST_BOOLEAN vst_drivequery_execute()
API Functions
2-881
Functions
Example
If the object code value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
VSE_ERR_BADFIELD - An invalid parameter was
specified.
API Guide
16 #endif
17 {
18
VST_BOOLEAN
rc = VSE_FALSE;
19
VST_QUERY_OPTION
queryopt;
20
int
count;
21
VST_DRIVE_ID
temp_drive_id;
22
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
23
VST_COMMAND_HANDLE
cmd;
24
25
/* get parameters from user */
26
printf(“*** Drive Query parameters
***\n” );
27
printf(“0) Query by drive list, 1)
Query all, 2) Query single
DriveID==> “ );
28
queryopt = atoi(gets(input));
29
30
if (queryopt == 0)
31
{
32
count =
vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
33
}
34
else if (queryopt == 2)
35
{
36
printf(“\nEnter Drive ID to query:
“);
37
temp_drive_id =
atoi(gets(input));
38
}
39
40
/* create the command handle */
41
/* Note that the command handle is
not */
42
/* destroyed in this routine, but in
*/
43
/* vst_dispatch when final status is
received. */
44
cmd = VS_Command_Create();
45
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
2-882
API Functions
601355 Rev A
API Guide
46
47
48
49
50
51
52
58
59
60
61
62
63
64
65
66
67
68
69
70 }
Notes
601355 Rev A
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine Also, note
that */
/* default values such as
timeout,*/
/* value retry limit and priority
are set as */
/* default parameters. */
if(queryopt == 2)
{
rc = VSCMD_DriveQuery(cmd,
VSID_QRY_OPTION,
VSE_QUERY_OPTION_NONE,
VSID_DRIVE_ID,
temp_drive_id,
VSID_ENDFIELD);
}
else
{
rc = VSCMD_DriveQuery(cmd,
VSID_QRY_OPTION,
queryopt,
VSID_DRIVE_ID_LIST,
count,drivelist,
VSID_ENDFIELD);
}
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
API Functions
2-883
Functions
53
54
55
56
57
{
API Guide
VolServ can generate intermediate status in response to a Drive
Query request. Statuses are cumulative. Each status is added to
the previous status so that after the final status is given, the
status handle contains information from all statuses.
VSCMD_DriveQuery does not trigger any MediaClass
callbacks from VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
The VSID_DRIVE_ID_LIST and
VSID_COMP_STATE_LIST parameters require that two
arguments be passed instead of one.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Drive Query request submitted through the API interface to
the VolServ system.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
2-884
API Functions
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Drive Query
commands are set with
VSCMD_DriveQuery_SetDefaults. If
601355 Rev A
API Guide
command-specific defaults are set for Drive Query
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Drive Query
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Drive Query request:
VSID_DRIVE_HANDLE,
VSID_DRIVE_HANDLE_ENTRY,
VSID_DRIVE_HANDLE_TABLE,
VSID_ERROR_CODE,
VSID_ERROR_CODE_ENTRY,
VSID_ERROR_CODE_TABLE,
VSID_SEQUENCE_NUM,
VSID_SEQUENCE_TABLE,
VSID_STATUS_CODE,
VSID_STATUS_TYPE,
VSID_USER_FIELD.
Functions
•
•
•
•
•
•
•
•
•
•
•
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-885
API Guide
See Also
2-886
•
•
•
•
•
•
•
•
•
•
API Functions
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Command_GetFields(l),
VS_Drive_GetFields(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VS_Table_GetFields(l),
VSCMD_DriveQuery_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_Drive
Query_
SetDefaults
VSCMD_DriveQuery_SetDefaults sets the
command-level default parameters for Drive Query commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Drive Query
commands are set with VSCMD_Drive
Query_SetDefaults. If command-specific defaults are
set for Drive Query commands, they override the global
defaults for all commands.
Functions
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Drive Query
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
601355 Rev A
VST_BOOLEAN VSCMD_DriveQuery_SetDefaults
(
“…”,
VSID_ENDFIELD)
API Functions
2-887
API Guide
Arguments
•
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status on Drive Query commands.
VSID_DRIVE_ID (VST_DRIVE_ID)
Identifier of a single drive to query.
VSID_DRIVE_ID_LIST (int)
Number of drives to query. May be greater
than or equal to 1.
(VST_DRIVE_ID *)
Pointer to a list of identifiers of drives to query.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
Identifier of the enterprise, if any, to receive
intermediate and final status on Drive Query
commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Drive
Query commands. Assignable priority values
are restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_QUERY_OPTION
(VST_QUERY_OPTION)
Indicates whether information is being
requested for all drives known to the VolServ
system or for the drives identified in a list
specified with the Drive Query request. Valid
VSE_QUERY_OPTION values are enumerated
in the vs_types.h file.
2-888
API Functions
601355 Rev A
API Guide
Parameter Type
Description
Number of times the API software retries for
command status from VolServ before
returning a time-out to the client software for
Drive Query commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
Flag indicating whether the API software waits
for final status from VolServ (or times-out) for
Drive Query commands. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
Amount of time (in seconds) the API software
waits for status from VolServ before returning
a time-out to the client software. The default
time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
Value to put in USER_FIELD for Drive Query
commands. USER_FIELD is 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 Drive
Query commands. Neither the API software
nor VolServ uses USER_FIELD.
601355 Rev A
API Functions
2-889
Functions
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
API Guide
Return Values
Example
VSCMD_DriveQuery_SetDefaults 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_BADSIZE - Value passed for a string parameter
exceeds the maximum allowable length for that parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2-890
API Functions
/****************************************
*********
*
* FUNCTION: vst_drivequery_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_DriveQuery API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_drivequery_defaults(void)
#else
VST_BOOLEAN
vst_drivequery_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
601355 Rev A
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
34
35
36
37
38
39
40 }
Notes
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Drive Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_DriveQuery_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
The VSID_DRIVE_ID_LIST and VSID_COMP_STATE_LIST
parameters require that two arguments be passed instead of one.
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
601355 Rev A
API Functions
2-891
Functions
33
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
• VSCMD_DriveQuery(l)
2-892
API Functions
601355 Rev A
API Guide
VSCMD_
Modify
ArchiveMedia
Class
VSCMD_ModifyArchiveMediaClass modifies the value
of one or more attributes of an archive media class. An archive
media class is the association of a MediaClass group with a
defined archive.
Synopsis
VST_BOOLEAN VSCMD_ModifyArchiveMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Modify Archive
Media Class command.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
API Functions
2-893
Functions
601355 Rev A
All archive media class attributes must be specified on a
Modify Archive Media Class request, whether the value of an
attribute is being modified or not.
API Guide
2-894
API Functions
601355 Rev A
API Guide
Parameters
Parameter Type
Description
Specifies what action 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.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The name of the archive associated with the
archive media class. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_CAPACITY (VST_CAPACITY)
The percentage of the total MediaClass
capacity that can be stored in this archive.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status for this request.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE)
Preferred locations (in table format) for media
assigned to this archive media class
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status for this
request.
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)
The percentage of VSID_CAPACITY below
which the specified migration policy option is
performed or terminated. This field is
applicable only if VSID_ARCHIVE_ACTION is
set to VSE_ARCHIVE_ACTION_NOTIFY or
VSE_ARCHIVE_ACTION_MIG.
601355 Rev A
API Functions
Functins
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
2-895
API Guide
Parameter Type
Description
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The name of the MediaClass group
associated with the archive media class. Valid
MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_MIGRATION_PRIORITY
(VST_PRIORITY)
The migration priority applied to this archive
media class.
VSID_PERCENT (VST_PERCENT)
The percentage of the MediaClass capacity
allowed in the archive associated with the
archive media class.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
A flag indicating whether the API software
waits for final status from VolServ (times-out)
for this request. Valid options are VSE_TRUE
(API software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
2-896
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The destination archive for media
automatically migrated out of this archive
media class. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software for
this request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
A value to put in USER_FIELD for this request.
USER_FIELD is 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 this request.
Neither the API software nor VolServ uses
USER_FIELD.
Return Values
VSCMD_ModifyArchiveMediaClass returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed.
A return code of VSE_FALSE (which is 0) means the
command failed.
To determine where the error occurred, and what the error
was, the client queries the command’s error handle (with
VS_Error_GetFields) to retrieve the error handle’s
object code.
API Functions
2-897
Functins
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
API Guide
-
Example
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
2-898
API Functions
/****************************************
*********
*
601355 Rev A
API Guide
3
4
5
6
7
8
9
10
11
12
13
14
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
601355 Rev A
API Functions
2-899
Functins
15
16
* FUNCTION:
vst_modarchivemediaclass_execute
*
* PURPOSE:
* This executes the
VSCMD_ModifyArchiveMediaClass
* API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modarchivemediaclass_execute(
void)
#else
VST_BOOLEAN
vst_modarchivemediaclass_execute(
)
#endif
{
int
i;
int
count;
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ARCHIVE_NAME
archive;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_CAPACITY
capacity;
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
highmark;
VST_LOW_MARK
lowmark;
VST_PRIORITY
migpri;
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
API Guide
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
2-900
API Functions
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
VST_COMMAND_HANDLE
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
/* get parameters from user */
printf(“*** Modify parameters ***\n”
);
printf(“*** The archive media class
grouping must exist. ***\n”);
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
{
printf(“Enter Target Archive ==> “
);
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
migpri = atoi(gets(input));
/* These only need to be set when
migration */
/* is used. */
601355 Rev A
API Guide
61
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
VSID_ENDFIELD );
62
63
64
65
66
67
68
69
70
71
73
74
75
76
77
78
79
80
81
82
83
84
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
86
601355 Rev A
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
API Functions
2-901
Functins
72
}
API Guide
87
VSID_COMP_ID,
CompID,
88
89
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
}
90
91
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
2-902
API Functions
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout
*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc =
VSCMD_ModifyArchiveMediaClass(cmd
,
601355 Rev A
API Guide
111
VSID_ARCHIVE_NAME,
archive,
112
113
114
115
116
117
118
119}
Notes
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
VSID_ENDFIELD);
}
return ( rc );
VolServ generates no intermediate status in response to a
Modify Archive Media Class.
VSCMD_ModifyArchiveMediaClass does not trigger
unsolicited MediaClass callbacks from VolServ.
The migration policy options for are no action, operator
notification, and automatic migration.
When the number of media in an archive media class reaches
the high mark threshold, VolServ:
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy option is
set to notify.
•
Initiates automatic migration of media if the migration
policy is set to migrate.
When the number of media in an archive media class drops to
the low mark threshold, VolServ:
601355 Rev A
API Functions
2-903
Functins
The API must be initialized with a call to VS_Initialize
before this function can be executed.
API Guide
•
Does nothing if the migration policy option is set to none.
•
Issues an operator message if the migration policy is set to
notify.
•
Terminates automatic migration of media if the migration
policy is set to migrate.
The capacity value of an archive media class is relative to the
MediaClass group specified overall capacity. Consideration
should be given to all media classes that are able to share this
archive to ensure that reasonably comparable capacity
limitations and high/low marks are set for each archive media
class.
Media can reside in an archive only if their associated
MediaClass group has an archive media class assignment in that
archive.
Archive media class computed capacity limits are “soft”, that is,
they can be exceeded when media are imported or moved in
from another archive. If automigration is specified, media of
this MediaClass group is marked for movement to their target
archive. The media type capacity designates the “hard” limit
when entering media into an archive.
An archive media class computed capacity is refigured if the
capacity of a MediaClass group changes.
Checks to determine if the high mark has been reached or
exceeded or the low mark has been reached or passed occur:
2-904
API Functions
•
After any Eject, Enter, Reclassify, or Modify Archive
Media Class command executes.
•
After the MediaClass group or archive media class are
redefined.
601355 Rev A
API Guide
The sum of all archive media class capacities can exceed the
archive’s physical ability to house media. If VSID_CAPACITY
values are set unrealistically high and VSID_HIGH_MARK is
similarly high, the archive may physically completely fill
before any automigration procedure is triggered.
Components listed as preferred for storage of media of this
MediaClass group do not have exclusive ownership of those
components.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Modify Archive Media Class request submitted through the
API interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
Note
Global defaults for all commands are initialized at startup
and can be set or retrieved using
VS_Global_SetFields and VS_Global_GetFields
function calls.
601355 Rev A
API Functions
2-905
Functins
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this request is returned to the
enterprise registered with VolServ.
API Guide
•
Command-specific parameter defaults for Modify Media
Class commands are set with
VSCMD_ModifyMediaClass_SetDefaults. If
command-specific defaults are set for Modify Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Modify Archive Media Class request:
2-906
API Functions
•
VSID_ARCHIVE_NAME,
•
VSID_COMPONENT_HANDLE,
•
VSID_COMPONENT_HANDLE_ENTRY,
•
VSID_COMPONENT_HANDLE_TABLE,
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_MEDIA_CLASS_NAME,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
601355 Rev A
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreateArchiveMediaClass(l),
•
VSCMD_DeleteArchiveMediaClass(l),
•
VSCMD_ModifyArchiveMediaClass_SetDefaults(l)
API Functions
Functins
601355 Rev A
•
2-907
API Guide
VSCMD_
Modify
ArchiveMedia
Class_Set
Defaults
VSCMD_ModifyArchieMediaClass_SetDefaults
sets the command-level default parameters for Modify Archive
Media Class commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Modify Media
Class commands are set with
VSCMD_ModifyMediaClass_SetDefaults. If
command-specific defaults are set for Modify Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself
Synopsis
VST_BOOLEAN VSCMD_ModifyArchiveMediaClass
_SetDefaults
( “…”,
VSID_ENDFIELD)
Arguments
•
2-908
API Functions
“…” = Variable length argument list consisting of pairs of
Arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value used as a command default
601355 Rev A
API Guide
value for the field. The valid parameter identifiers and types
for this function 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.
Parameters
Parameter Type
Description
Specifies what action 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.
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The name of the archive associated with the
archive media class. Valid archive names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_CAPACITY (VST_CAPACITY)
The percentage of the total MediaClass
capacity that can be stored in this archive.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status on Modify Archive Media Class
commands.
VSID_COMPONENT_HANDLE_TABLE
(VST_TABLE_HANDLE)
Preferred locations (in table format) for media
assigned to this archive media class.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
Modify Archive Media Class commands.
601355 Rev A
API Functions
2-909
Functins
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
API Guide
Parameter Type
Description
VSID_PRIORITY)
The requested execution priority for Modify
Archive Media Class commands. Assignable
priority values are restricted to the range from
1 (highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
Modify Archive Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
A flag indicating whether the API software
waits for final status from VolServ (or
times-out) for Modify Archive Media Class
commands. Valid options are VSE_TRUE (API
software waits for final status) and
VSE_FALSE (API software does not wait for
final status). Also determines whether the API
software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The destination archive for media
automatically migrated out of this archive
media class. Valid archive names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software. The
default time-out value is 120 seconds.
2-910
API Functions
601355 Rev A
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Return Values
VSCMD_ModifyArchiveMediaClass_SetDefaults
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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
601355 Rev A
/****************************************
*********
*
* FUNCTION:
vst_modarchivemediaclass_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
API Functions
2-911
Functins
Example
The value to put in USER_FIELD for Modify
Archive Media Class commands.
USER_FIELD is 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 Modify Archive
Media Class commands. Neither the API
software nor VolServ uses USER_FIELD.
API Guide
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2-912
API Functions
* VSCMD_ModifyArchiveMediaClass API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modarchivemediaclass_defaults
(void)
#else
VST_BOOLEAN
vst_modarchivemediaclass_defaults
()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
priority;
VST_USER_FIELD
user_field;
VST_TIME_OUT
timeout;
VST_RETRY_LIMIT
retries;
VST_STATUS_WAIT_FLAG
wait_flag;
VST_ENTERPRISE_ID
enterprise_id;
/* get parameters from user */
printf(“*** Modify Archive Media
Class default parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
601355 Rev A
API Guide
35
36
37
38
39
40 }
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
retries,
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
Functins
See Also
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ModifyArchiveMediaClass(l)
API Functions
2-913
API Guide
VSCMD_
ModifyMedia
Class
VSCMD_ModifyMediaClass modifies the value of one or
more attributes of a MediaClass group. A MediaClass group
establishes common characteristics for the media it contains.
All MediaClass group attributes must be specified on a Modify
Media Class request, whether the value of an attribute is being
modified or not.
Synopsis
VST_BOOLEAN VSCMD_ModifyMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for this Modify Media
Class command.
•
“…” = 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 use for this
request. The valid parameter identifiers and types for this
function 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.
Parameters
Parameter Type
VSID_CAPACITY (VST_CAPACITY)
2-914
API Functions
Description
The maximum number of media allowed in
this MediaClass group.
601355 Rev A
API Guide
Parameter Type
Description
Indicates whether this MediaClass group
supports the mount by MediaClass
functionality. Valid
VSID_CLASS_MOUNT_STATE values are
enumerated in the vs_types.h file.
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION)
Indicates whether callbacks are activated for
this MediaClass group and if they are, which
callback scheme is used. Valid
VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status for this
request.
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_HOST_NAME (VST_HOST_NAME)
The network-assigned name of the computer
where the task that listens for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTION is set to
VSE_CLASS_RPC_STANDARD.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The unique name assigned to the MediaClass
group.
VSID_NEW_MEDIA_CLASS_NAME
(VST_NEW_MEDIA_CLASS_NAME)
The new, unique name assigned to the
specified MediaClass group.
601355 Rev A
API Functions
2-915
Functins
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
API Guide
Parameter Type
Description
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
The media type supported by this MediaClass
group. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
The user-specified comment included in a
system log message when the number of
media in the MediaClass group exceeds the
high mark threshold. The MediaClass name,
fill level, high mark threshold, and capacity
values are automatically included in the
system log message and need not be
included in VSID_NOTIFY_COMMENT.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Modify
Media Class commands. Assignable priority
values are restricted to a range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
The RPC procedure number of the client
process to receive callbacks generated for this
MediaClass group.
VSID_PROCEDURE_NUMBER is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBER is not applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
The RPC program number of the client
process to receive callbacks generated for this
MediaClass group. VSID_PROGRAM_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBER is not
applicable.
2-916
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The Internet protocol VolServ is to use to send
callbacks for this MediaClass group. The
default VSID_PROTOCOL is VSE_PROT_TCP.
VSID_PROTOCOL is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOL is not applicable.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
Modify Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
A flag indicating whether the API software
waits for final status from VolServ (or
times-out) for Modify Media Class commands.
Valid options are VSE_TRUE (API software
waits for final status) and VSE_FALSE (API
software does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise to receive
callbacks for this MediaClass group.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software for
this request. The default time-out value is 120
seconds.
601355 Rev A
API Functions
2-917
Functins
VSID_PROTOCOL (VST_PROTOCOL)
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
A value to put in USER_FIELD for Modify
Media Class commands. USER_FIELD is 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 Modify Media Class
commands. Neither the API software nor
VolServ uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
The RPC version number of the client process
to receive callbacks generated for this
MediaClass group. VSID_VERSION_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBER is not
applicable.
Return Values
VSCMD_ModifyMediaClass returns:
•
•
2-918
API Functions
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
VSE_FALSE - The command failed.
A return code of VSE_FALSE (which is 0) means the
command failed.
To determine where the error occurred, and what the error
was, the client queries the command’s error handle (with
VS_Error_GetFields) to retrieve the error handle’s
object code.
601355 Rev A
API Guide
-
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
•
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
601355 Rev A
/****************************************
*********
*
API Functions
2-919
Functins
Example
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
API Guide
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
2-920
API Functions
* FUNCTION: vst_modmediaclass_execute
*
* PURPOSE:
* This executes the VSCMD_ModMediaClass
API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modmediaclass_execute(void)
#else
VST_BOOLEAN
vst_modmediaclass_execute()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
VST_MEDIA_CLASS_NAME
mediaclass;
VST_MEDIA_CLASS_NAME
newclass;
VST_CAPACITY
capacity;
VST_CLASS_MOUNT_STATE
mountstate;
VST_HIGH_MARK
highmark;
VST_COMMAND_HANDLE
cmd;
VST_NOTIFY_COMMENT
comment;
VST_CLASS_RPC_OPTION
rpc_option;
VST_HOSTNAME
rpc_hostname;
VST_PROGRAM_NUMBER
rpc_prognum;
VST_VERSION_NUMBER
rpc_versnum;
VST_PROCEDURE_NUMBER
rpc_procnum;
VST_PROTOCOL
rpc_protocol;
VST_ENTERPRISE_ID
enterpriseid;
/* get parameters from user */
printf(“*** Modify Media Class
parameters ***\n” );
601355 Rev A
API Guide
36
37
38
39
40
41
42
43
44
45
46
47
48
50
51
52
53
54
55
56
57
58
59
60
61
601355 Rev A
VSCMD_ModifyMediaClass_SetDefault
s(
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_STANDARD)
{
printf(“\nEnter RPC Host Name
==>”);
gets(rpc_hostname);
printf(“\nEnter program number
==>”);
rpc_prognum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
API Functions
2-921
Functins
49
printf(“\nEnter Media Class to modify
==>”);
gets( mediaclass);
printf(“\nEnter New Media Class Name
(return to leave unchanged) ==>“);
gets( newclass);
printf(“\nEnter capacity==>”);
capacity = atoi(gets(input));
printf(“\nEnter class mount state (0)
no, (1) ok: “);
mountstate = atoi(gets(input));
printf(“\nEnter high mark ==>”);
highmark = atoi(gets(input));
printf(“\nEnter notify comment
==>”);
gets(comment);
printf(“\nEnter Option (0) no
callbacks, (1) standard, (2)
Enterprise ==>”);
rpc_option = (VST_CLASS_RPC_OPTION)
atoi(gets(input));
if (rpc_option ==
VSE_CLASS_RPC_NONE)
{
API Guide
62
63
64
65
66
67
printf(“\nEnter version number
==>”);
rpc_versnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter procedure number
==>”);
rpc_procnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter Protocol (6) TCP
or (17) UDP ==>”);
rpc_protocol = (VST_PROTOCOL)
atoi(gets(input));
68
69
70
71
72
73
74
75
76
77
78
79
80
VSCMD_ModifyMediaClass_SetDefault
s(
VSID_HOST_NAME, rpc_hostname,
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_PROGRAM_NUMBER,
rpc_prognum,
VSID_VERSION_NUMBER,
rpc_versnum,
VSID_PROCEDURE_NUMBER,
rpc_procnum,
VSID_PROTOCOL,
rpc_protocol,
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_ENTERPRISE)
{
printf(“\nEnter enterprise id
==>”);
enterpriseid =
(VST_ENTERPRISE_ID)
atol(gets(input));
81
VSCMD_ModifyMediaClass_SetDefault
s(
2-922
API Functions
601355 Rev A
API Guide
82
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_TARGET_ENTERPRISE_ID,
enterpriseid,
VSID_ENDFIELD);
83
84
85
86
87
88
89
90
91
92
95
96
97
98
99
100
101
102
103
104
105
106
601355 Rev A
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout
*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_ModifyMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_NEW_MEDIA_CLASS_NAME,
newclass,
VSID_CAPACITY,
capacity,
VSID_CLASS_MOUNT_STATE,
mountstate,
VSID_HIGH_MARK,
highmark,
API Functions
2-923
Functins
93
94
}
API Guide
107
108
109
110
111}
Notes
VSID_NOTIFY_COMMENT,
comment,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response to a
Modify Media Class request.
The Modify Media Class command triggers unsolicited
MediaClass callbacks from VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
The name specified for the MediaClass group must be unique.
Any requests to create non-unique MediaClass names fail.
MediaClass groups can span archives.
MediaClass groups may contain only one type of media.
Checks to determine if VSID_HIGH_MARK has been reached
or exceeded occur after any Reclassify, Import, or Modify
Media Class command.
VSID_CAPACITY is a hard limit. VolServ does not permit the
number of media assigned to a MediaClass group to exceed the
VSID_CAPACITY for that MediaClass group.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, final status for this request is returned to the
enterprise registered with VolServ.
2-924
API Functions
601355 Rev A
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Modify Media Class request submitted through the API
interface to the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Modify Media
Class commands are set with
VSCMD_ModifyMediaClass_SetDefaults. If
command-specific defaults are set for Modify Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
The following fields can be retrieved from the status handle
after a successful Modify Media Class command:
601355 Rev A
•
VSID_MEDIA_CLASS_NAME,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
API Functions
2-925
Functins
•
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-926
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreateMediaClass(l),
•
VSCMD_DeleteMediaClass(l),
•
VSCMD_ModifyMediaClass_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
ModifyMedia
Class_Set
Defaults
VSCMD_ModifyMediaClass_SetDefaults sets the
command-level default parameters for Modify Media Class
commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Modify Media
Class commands are set with
VSCMD_ModifyMediaClass_SetDefaults. If
command-specific defaults are set for Modify Media Class
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Media
Class command, the parameter identifier and the value
used for the parameter can be submitted on the specific
request itself.
Synopsis
VST_BOOLEAN VSCMD_ModifyMediaClass
( “…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value used as a command default
API Functions
2-927
Functins
•
API Guide
value for the field. The valid parameter identifiers and types
for this function 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.
Parameters
Parameter Type
Description
VSID_CAPACITY (VST_CAPACITY)
The maximum number of media allowed in
this MediaClass group.
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
Indicates whether this MediaClass group
supports the “mount by MediaClass”
functionality. Valid
VSID_CLASS_MOUNT_STATE values are
enumerated in the vs_types.h file.
VSID_CLASS_RPC_OPTION
(VST_CLASS_RPC_OPTION)
Indicates whether callbacks are activated for
this MediaClass group and if they are, which
callback scheme is used. Valid
VSID_CLASS_RPC_OPTION values are
enumerated in the vs_types.h file.
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status for this request.
VSID_ENTERPRISE_ID (int)
The number of enterprise identifiers in the list.
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status for this
request.
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.
2-928
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The network-assigned name of the computer
where the task that listens for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTION is set to
VSE_CLASS_RPC_STANDARD.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The current name assigned to the MediaClass
group.
VSID_NEW_MEDIA_CLASS_NAME
(VST_NEW_MEDIA_CLASS_NAME)
The current name assigned to the MediaClass
group.
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
The media type supported by this MediaClass
group. Valid media type names may contain
up to 16 alphanumeric characters, including
spaces. Leading and trailing spaces are not
permitted.
VSID_NOTIFY_COMMENT
(VST_NOTIFY_COMMENT)
The user-specified comment included in a
system log message when the number of
media in the MediaClass group exceeds the
high mark threshold. The MediaClass name,
fill level, high mark threshold, and capacity
values are automatically included in the
system log message and need not be
included in VSID_NOTIFY_COMMENT.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Modify
Media Class commands. Assignable priority
values are restricted to a range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
The RPC procedure number of the client
process to receive callbacks generated for this
MediaClass group.
VSID_PROCEDURE_NUMBER is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBER is not applicable.
601355 Rev A
API Functions
2-929
Functins
VSID_HOST_NAME (VST_HOST_NAME)
API Guide
Parameter Type
Description
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
The RPC program number of the client
process to receive callbacks generated for this
MediaClass group. VSID_PROGRAM_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBER is not
applicable.
VSID_PROTOCOL (VST_PROTOCOL)
The Internet protocol VolServ is to use to send
callbacks for this MediaClass group. The
default VSID_PROTOCOL is VSE_PROT_TCP.
VSID_PROTOCOL is required if
VSID_CLASS_RPC_OPTION is set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOL is not applicable.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
Modify Media Class commands.
VSID_RETRY_LIMIT is not applicable when
the API software executes in asynchronous
mode.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
A flag indicating whether the API software
waits for final status from VolServ (or
times-out) for Modify Media Class commands.
Valid options are VSE_TRUE (API software
waits for final status) and VSE_FALSE (API
software does not wait for final status). Also
determines whether the API software
operates in synchronous mode (VSE_TRUE)
or in asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TARGET_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise to receive
callbacks for this MediaClass group.
2-930
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software for
this request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
A value to put in USER_FIELD for Modify
Media Class commands. USER_FIELD is 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 Modify Media Class
commands. Neither the API software nor
VolServ uses USER_FIELD.
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER)
The RPC version number of the client process
to receive callbacks generated for this
MediaClass group. VSID_VERSION_NUMBER
is required if VSID_CLASS_RPC_OPTION is
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBER is not
applicable.
Return Values
601355 Rev A
VSCMD_ModifyMediaClass_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
API Functions
2-931
Functins
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
API Guide
•
Example
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2-932
API Functions
/****************************************
*********
*
* FUNCTION: vst_modmediaclass_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ModMediaClass API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modmediaclass_defaults(void)
#else
VST_BOOLEAN
vst_modmediaclass_defaults()
#endif
{
VST_BOOLEAN rc = VSE_FALSE;
VST_PRIORITY priority;
VST_USER_FIELD user_field;
VST_TIME_OUT timeout;
VST_RETRY_LIMIT retries;
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID enterprise_id;
/* get parameters from user */
printf(“*** Create Archive Media
Class default parameters ***\n” );
601355 Rev A
API Guide
29
30
31
32
33
34
35
36
38
39
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-933
Functins
37
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
VSCMD_ModifyMediaClass_SetDefault
s(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
API Guide
See Also
2-934
API Functions
•
vsapi(l),
•
VS_Error_GetFields(l),
•
VS_Global_SetFields(l),
•
VSCMD_ModifyMediaClass(l)
601355 Rev A
API Guide
VSCMD_ModifyPool modifies the list of drives associated
with a drive pool. A client issues a VSCMD_ModifyPool
request to modify the list of drives that are included in a drive
pool description. The client can add drives to and/or delete
drives from the specified drive pool with a single
VSCMD_ModifyPool request.
Synopsis
VST_BOOLEAN VSCMD_ModifyPool
(VST_COMMAND_HANDLE handle,
“…”,
VSID_ENDFIELD)
Arguments
•
handle = The command handle for the Modify Pool
request.
•
“…” = Variable length argument list consisting of pairs of
Arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value used as a command default
value for the field. The valid parameter identifiers and types
for this function 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.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status for this request.
VSID_DRIVE_ID_LIST (int)
The number of drives added to or deleted from
the specified drive pool.
601355 Rev A
API Functions
2-935
Functins
VSCMD_
ModifyPool
API Guide
Parameter Type
Description
(VST_DRIVE_ID)
The identifier of drives added to or deleted
from the specified drive pool.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
The name of the drive pool whose list of drives
are modified. Valid drive pool names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_MODPOOL_OPTION_LIST
(VST_POOL_DRIVE_OPTION)
A pointer to the list of actions that correspond
to the drives identified in the VSID_DRIVE_ID
table. An entry in the
VSID_MODPOOL_OPTION_LIST indicates
whether the corresponding entry in
VSID_DRIVE_ID_LIST is added to or
deleted from the specified drive pool. Valid
VSID_MODPOOL_OPTION values are
enumerated in the vs_types.h file.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
request. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
this request. VSID_RETRY_LIMIT is not
applicable when the API software executes in
asynchronous mode.
2-936
API Functions
601355 Rev A
API Guide
Parameter Type
Description
A flag indicating whether the API software
waits for final status from VolServ (or
times-out) for this request. Valid options are
VSE_TRUE (API software waits for final status)
and VSE_FALSE (API software does not wait
for final status). Also determines whether the
API software operates in synchronous mode
(VSE_TRUE) or in asynchronous mode
(VSE_FALSE). The default
VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software for
this request. The default time-out value is 120
seconds.
VSID_USER_FIELD (VST_USER_FIELD)
The value to put in USER_FIELD for this
request. USER_FIELD is 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 this
request. Neither the API software nor VolServ
uses USER_FIELD.
Return Values
VSCMD_ModifyPool returns:
•
•
601355 Rev A
VSE_TRUE
-
Successful execution if the API is operating in
synchronous mode
-
Good initial status received if the API is operating in
asynchronous mode
VSE_FALSE - The request failed. A return code of
VSE_FALSE (which is 0) means the request failed.
API Functions
2-937
Functins
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
API Guide
2-938
API Functions
-
To determine where the error occurred, and what the
error was, the client queries the request’s error handle
(with VS_Error_GetFields) to retrieve the error
handle’s object code.
-
If the object code’s value is VSE_NONE, the client
must query the global error code (VSG_Error) to
determine where the error occurred.
•
VSE_ERR_BADHANDLE - Specified handle was not a valid
command handle.
•
VSE_ERR_NULLHANDLE - Specified handle was a null
pointer.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODE to identify the specific error.
-
If the object code’s value is not VSE_VOLSERV and is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODE to identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
•
VSE_ERR_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NOTINITIALIZED - The VolServ API is not
initialized.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument.
601355 Rev A
API Guide
•
Example
VSE_ERR_SEND - The API software could not send the
command request to VolServ. This may be an RPC
communication error and can indicate VolServ is not
executing.
1
2
3
4
5
6
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
601355 Rev A
/* get parameters from user */
printf(“*** Modify Pool Parameters
***\n” );
API Functions
2-939
Functins
7
8
9
10
11
/****************************************
*********
*
* FUNCTION: vst_modpool_execute
*
* PURPOSE:
* This executes the VSCMD_ModifyPool API
call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modpool_execute(void)
#else
VST_BOOLEAN vst_modpool_execute()
#endif
{
VST_BOOLEAN
rc = VSE_FALSE;
VST_DRIVE_POOL_NAME
dp;
int
count;
int
i;
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
VST_POOL_DRIVE_OPTION
optionlist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE
cmd;
API Guide
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
2-940
API Functions
printf(“\nEnter Drive Pool to modify
==>”);
gets( dp );
count = vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
printf(“\nPlease select the action to
take on each drive\n”);
for (i = 0; i < count; i++)
{
printf(“drive %d: (1) add to pool,
(2) delete: “, drivelist[i]);
optionlist[i] =
(VST_POOL_DRIVE_OPTION)
atoi(gets(input));
}
/* create the command handle */
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
/* Send the command to the VolServ
software. */
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
*/
/* value retry limit and priority
are set as */
/* default parameters. */
rc = VSCMD_ModifyPool(cmd,
VSID_DRIVEPOOL_NAME, dp,
601355 Rev A
API Guide
54
55
56
57
58
59 }
Notes
VSID_DRIVE_ID_LIST, count,
drivelist,
VSID_MODPOOL_OPTION_LIST,
count, optionlist,
VSID_ENDFIELD);
}
return ( rc );
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate status in response to a
Modify Pool request.
Functins
VSCMD_ModifyPool does not trigger any MediaClass
callbacks from VolServ.
The name specified for a new drive pool must be unique. A
request to create a drive pool with a non-unique name fails.
Drive pools can contain zero or more drives.
Drives belonging to a single drive pool can be associated with
different archives. Drives are not required to be associated with
an archive to belong to a drive pool.
Drive pools can contain drives that support incompatible media
types.
If a drive pool is specified on a Mount request and the specified
drive pool spans archives, VolServ can select a drive to honor
the Mount request that is in a different archive than the medium
that is selected to honor the request. If this occurs, a
Move-Mount action is required. If permitted, the medium is
scheduled for ejection from its parent archive and eventually
enters the archive associated with the assigned drive.
601355 Rev A
API Functions
2-941
API Guide
Whether or not Move-Mount action processing is permitted is
specified at the archive level. The ACTION_MODE and
MOVEWAIT_OPTION attributes control whether or not
Move-Mount processing is allowed for a specific archive.
These attributes are discussed under the
VS_Archive_SetFields and
VS_Archive_GetFields functions.
The VSID_DRIVE_ID_LIST and
VSID_MODPOOL_OPTION_LIST parameters require that two
arguments be passed instead of one.
•
The first argument passed is the number of drives to add to
or delete from the specified drive pool.
•
The second argument is the list of identifier of the drives to
add or delete from the specified drive pool.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMIT plus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_ID parameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
When the API software is operating in asynchronous mode,
client software must call VS_Select to receive final status on
a Modify Pool request submitted through the API interface to
the VolServ system.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
•
2-942
API Functions
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
601355 Rev A
API Guide
•
Command-specific parameter defaults for Modify Pool
commands are set with
VSCMD_ModifyPool_SetDefaults. If
command-specific defaults are set for Modify Pool
commands, they override the global defaults for all
commands.
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
601355 Rev A
•
VSID_DRIVE_ID,
•
VSID_DRIVE_ID_ENTRY,
•
VSID_DRIVE_ID_TABLE,
•
VSID_DRIVEPOOL_NAME,
•
VSID_ERROR_CODE,
•
VSID_ERROR_CODE_ENTRY,
•
VSID_ERROR_CODE_TABLE,
•
VSID_SEQUENCE_NUM,
•
VSID_SEQUENCE_TABLE,
•
VSID_STATUS_CODE,
•
VSID_STATUS_TYPE,
•
VSID_USER_FIELD.
API Functions
Functins
The following fields can be retrieved from the status handle
after a successful Modify Pool request:
2-943
API Guide
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
2-944
API Functions
•
vsapi(l),
•
VS_Command_Create(l),
•
VS_Command_Destroy(l),
•
VS_Error_GetFields(l),
•
VS_Initialize(l),
•
VS_Status_GetFields(l),
•
VSCMD_CreatePool(l),
•
VSCMD_DeletePool(l),
•
VSCMD_ModifyPool_SetDefaults(l)
601355 Rev A
API Guide
VSCMD_
ModifyPool_
SetDefaults
VSCMD_ModifyPool_SetDefaults sets the
command-level default parameters for Modify Pool commands.
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFields function calls.
•
Command-specific parameter defaults for Modify Pool
commands are set with
VSCMD_ModifyPool_SetDefaults. If
command-specific defaults are set for Modify Pool
commands, they override the global defaults for all
commands.
Functins
•
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Modify Pool
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
Synopsis
VST_BOOLEAN VSCMD_ModifyPool_SetDefaults
( “…”,
VSID_ENDFIELD)
Arguments
•
601355 Rev A
“…” = Variable length argument list consisting of pairs of
Arguments. Each pair of Arguments consists of a parameter
identifier, followed by the value to be used as a command
default value for the field. The valid parameter identifiers
and types for this function are shown in the following
"Parameters" paragraph.
API Functions
2-945
API Guide
•
VSID_ENDFIELD = Required at the end of the variable
length argument list to indicate the end of the list.
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status on Modify Pool commands.
VSID_DRIVE_ID_LIST (int)
The number of drives to be added to or
deleted from the specified drive pool.
(VST_DRIVE_ID *)
A pointer to the list of drives to be added to or
deleted from the specified drive pool.
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
The name of the drive pool whose list of drives
is modified. Valid drive pool names may
contain up to 16 alphanumeric characters,
including spaces. Leading and trailing spaces
are not permitted.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_MODPOOL_OPTION_LIST (int)
The number of entries in the modify pool
option list.
(VST_POOL_DRIVE_OPTION *)
A pointer to the list of actions that correspond
to the drives identified in the VSID_DRIVE_ID
table.
VSID_MODPOOL_OPTION
(VST_POOL_DRIVE_OPTION)
An overall option to perform for all drives in
VSID_DRIVE_ID_LIST.
VSID_MODPOOL_OPTION replaces
VSID_MODPOOL_OPTION_LIST when all
drives are to be modified in some manner.
2-946
API Functions
601355 Rev A
API Guide
Parameter Type
Description
The requested execution priority for Modify
Pool commands. Assignable priority values
are restricted to the range from 1 (highest) to
32 (lowest) inclusive. The default priority value
is 15.
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
Modify Pool commands. VSID_RETRY_LIMIT
is not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
VSID_STATUS_WAIT_FLAG
(VST_STATUS_WAIT_FLAG)
A flag indicating whether the API software
waits for final status from VolServ (or
times-out) for Modify Pool commands. Valid
options are VSE_TRUE (API software waits for
final status) and VSE_FALSE (API software
does not wait for final status). Also determines
whether the API software operates in
synchronous mode (VSE_TRUE) or in
asynchronous mode (VSE_FALSE). The
default VSID_STATUS_WAIT_FLAG value is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The amount of time (in seconds) the API
software waits for status from VolServ before
returning a time-out to the client software. The
default time-out value is 120 seconds.
VSID_USER_FIELD (VST_USER_FIELD)
The value to put in USER_FIELD for Modify
Pool commands. USER_FIELD is 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 Modify Pool commands.
Neither the API software nor VolServ uses
USER_FIELD.
601355 Rev A
API Functions
2-947
Functins
VSID_PRIORITY (VST_PRIORITY)
API Guide
Return Values
Example
VSCMD_ModifyPool_SetDefaults 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_BADSIZE - The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2-948
API Functions
/****************************************
*********
*
* FUNCTION: vst_modpool_defaults
*
* PURPOSE:
* This function sets the default
parameters for the
* VSCMD_ModifyPool API call.
*
* PARAMETERS:
* none
*
****************************************
*********/
#ifdef ANSI_C
VST_BOOLEAN
vst_modpool_defaults(void)
#else
VST_BOOLEAN vst_modpool_defaults()
#endif
{
VST_BOOLEAN
rc =
VSE_FALSE;
601355 Rev A
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
34
35
36
37
38
39
40 }
Notes
priority;
user_field;
timeout;
retries;
wait_flag;
/* get parameters from user */
printf(“*** Modify Pool default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ModifyPool_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
The VSID_DRIVE_ID_LIST and
VSID_MODPOOL_OPTION_LIST parameters require that two
arguments be passed instead of one.
•
601355 Rev A
The first argument passed is the number of