API Guide
VolServ Version 5.0
September 2001
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Information was complete.
Circle One
Disagree
Agree
Agree
Agree
Information was easy to find.
Information was easy to follow.
Disagree
Disagree
Is there anything you especially like or dislike about the organization, presentation,
or writing in this manual?_______________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
Book Title
Document Number
Telephone
Customer Name
E-mail Address
Company Name
Address
City, State, Zip
Download from Www.Somanuals.com. All Manuals Search And Download.
NOTES
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Archive_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
VS_Archive_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
VS_Archive_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
VS_ArchiveMediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
VS_ArchiveMediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41
VS_Command_GetErrorFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-65
VS_Command_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-68
VS_Component_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-93
VS_Component_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-96
VS_Connect_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-107
VS_Connect_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-114
VS_Criteria_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-123
VS_Criteria_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-129
VS_Criteria_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-142
ii
Contents
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-187
VS_DrivePool_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-193
VS_DrivePool_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-196
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_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-243
VS_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-249
VS_Media_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-257
VS_Media_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-261
VS_Media_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-267
VS_MediaClass_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-273
VS_MediaClass_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-283
601355 Rev A
Contents
iii
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-418
VS_Table_RemoveEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-426
VS_Table_SetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-430
VS_Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-435
VS_TypeCapacity_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-437
iv
Contents
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_TypeCapacity_GetFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-446
VSCMD_ArchiveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-460
VSCMD_ArchiveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-470
VSCMD_Audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-490
VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-499
VSCMD_Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-505
VSCMD_Cancel_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-514
VSCMD_Checkin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-520
VSCMD_ClearEject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-548
VSCMD_ClearEject_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-557
VSCMD_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-563
VSCMD_Connect-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-581
VSCMD_CreateArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-595
VSCMD_CreateMedia-Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-619
VSCMD_Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-660
601355 Rev A
Contents
v
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Export_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-669
VSCMD_Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-674
VSCMD_Import_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-684
VSCMD_Intransit-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-689
VSCMD_Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-702
VSCMD_MediaClass-Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-717
VSCMD_MediaQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-731
VSCMD_ModifyMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-759
VSCMD_ModifyMedia_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-769
VSCMD_CreatePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-776
VSCMD_CreatePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-785
VSCMD_DeleteArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-791
VSCMD_DeleteMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-806
VSCMD_DeletePool_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-827
VSCMD_Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-832
VSCMD_Disconnect_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-842
VSCMD_Dismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-848
VSCMD_Dismount_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-857
vi
Contents
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DriveQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-878
VSCMD_DriveQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-887
VSCMD_ModifyArchiveMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-893
VSCMD_ModifyMediaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-914
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_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1054
VSCMD_RequestQuery_SetDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1068
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
601355 Rev A
Contents
vii
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
viii
Contents
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
P-2
Preface
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
This book describes the VolServ application programming
interface (API). The API consists of functions, iterators,
symbolic names, type definitions, and data structures.
Purpose of
This Book
Using the API provides the programmer with the ability to
directly manipulate VolServ file system metadata and media.
This book is written for programmers who are creating or
modifying an application that requires tight control over data in
the file system managed by VolServ
Who Should
Read This
Book
This book contains the following chapters:
How This
Book is
Organized
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The conventions used throughout the VolServ technical books
are listed below:
Conventions
Convention
Example
Screen text, file names, program names, and Request to add a new volume:
commands are in Courierfont.
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 vsarchiveqry
bold font.
Site-specific variables are in a Times italics
tar -xvf tapedevicename
font.
A backward slash ( \ ) denotes the input is
continued onto the next line; the printed page
is just not wide enough to accommodate the
line.
# remshnodename -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.
Config-->MediaType-->Redefine
P-4
Preface
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The books described below are part of the technical
documentation set, and are shipped on CD along with the
VolServ software:
Books
Overview
Administrative Tasks
Provides an overview of VolServ. Contains a
glossary.
Describes how to perform system
administrative tasks using VolServ
commands.
Installing VolServ
Describes server requirements, installation
instructions, troubleshooting procedures,
and configuration parameters.
Command Reference
Contains a list of VolServ commands
Error Messages
Using the VolServ GUI
Provides corrective action for system log
errors.
Describes how to perform system
administrative tasks using the graphical user
interface.
Quick Reference Card
Summarizes commands.
API Guide
Provides a list of API functions.
The documentation CD contains VolServ book files and
Online Books
®
®
Adobe Acrobat Reader. The Reader allows you to view and
navigate the online documentation files yet preserves the page
design and graphics from the printed books.
601355 Rev A
Preface
P-5
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The publications described in the table below are created and
distributed on an as-needed basis.
Related
Publications
Related Publications
Description
“Release Notes”
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.
To make corrections or to comment on VolServ publications,
please contact Software Technical Publications at our e-mail
address: [email protected].
Contact
Publications
Department
To receive access to the secured site on our home page contain-
ing technical product information (Release Notes, Product
Alerts, Product Bulletins, FAQs), visit http://partners.adic.com/
and follow the password request procedure. In return, ADIC
will send you instructions and a password.
Secured Web
Site
P-6
Preface
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Roadmap
Refer To
Chapter
Topic
Naming conventions.
Global parameters.
Error handling.
1
API functions.
Valid staus fields.
Error codes.
2
A
B
C
Mount example.
1-2
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
All files necessary for client interface to the VolServ software
are contained in the volserv/vsapidirectory 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 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
/util
/include
/lib
/man
Directory
include
Contents
Contains six header files used by API library.
Contains the API library.
lib
man
Contains man pages for all VolServ API library
functions.
601355 Rev A
Getting Started
1-3
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Directory
util
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.
1-4
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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.
Application
Program
Interface
The VolServ API allows the user to send commands, receive
command statuses, and receive VolServ MediaClass
notifications.
The VolServ API interface uses the VolServ Remote Procedure
Call (RPC) interface to communicate with VolServ. All features
available in the VolServ RPC interface are supported in the
VolServ API.
The VolServ API is extensible. Any change in the VolServ RPC
interface is handled by the API. Thus, the client program does
not have to be updated to maintain compatibility when the
VolServ RPC interface is modified. The client program is
updated only to use new VolServ features.
Extensible
The VolServ API is consistent. All commands and their related
functions have the same interface and operate similarly.
Consistent
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.)
The VolServ API is flexible. A client program can send a
command to VolServ and either
Flexible
601355 Rev A
Getting Started
1-5
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The figure below illustrates the communication paths supported
by VolServ:
Client
Interface
Summary
Command
Line
Interface
Clients using
Commands in
Client scripts
RPC
RPC
Client Software
using API
API
RPC
VolServ
Client Software
using
RPC/XDR protocol
The following outline shows the flow of information through
these communication paths.
•
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.
601355 Rev A
Getting Started
1-7
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
-
-
The API software deserializes the data and/or status
from the XDR formats and forwards the information to
the CLI software.
The CLI software formats the data and/or status and
forwards this information to the client that issued the
request.
The client/client script processes the data and/or status
returned by the CLI software.
•
Client software using the API.
-
-
The client software issues a request to the API
software by calling an API function/routine.
The API software serializes the request into XDR
format and transmits the request to VolServ using the
RPC/XDR protocol.
-
-
VolServ returns data and/or status to the API software
using the RPC/XDR protocol.
The API software deserializes the data and/or status
from the XDR formats and forwards the information to
the client software.
-
The client software processes the data and/or status
returned by the API software.
•
Client software using the RPC/XDR protocol.
-
The client software serializes the request into XDR
format and transmits the request to VolServ using the
RPC/XDR protocol.
-
-
VolServ returns data and/or status to the client
software using the RPC/XDR protocol.
The client software deserializes the information from
the XDR format and processes the returned
information.
1-8
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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.”
Unsolicited
Communica-
tion
Unsolicited communication from VolServ can be directed to
either:
•
•
A preselected RPC address.
Or, to an internet address associated with an enterprise. The
RPC address or enterprise assigned for unsolicited
communication is assignable at the MediaClass level. Refer
to the Command Reference book for detailed information
about defining unsolicited communication parameters for a
MediaClass group.
This address is used as the receiver for unsolicited messages
that VolServ transmits. These messages are transmitted at
the completion of VolServ processing that had an impact on
any medium associated with the particular MediaClass
group.
Running the following commands: VSCMD_Import,
VSCMD_Export, VSCMD_CheckIn, VSCMD_CheckOut,
VSCMD_Mount, VSCMD_Dismount,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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
To integrate the VolServ API in a client application, the client
includes the header file vs_client.hin the source modules
that reference the VolServ API types and functions. The client
then links the program with the VolServ API library
libvsapi.awith the -lvsapi option for the cc or ld
commands.
VolServ API
Integration
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
vs_globals.h
vs_proto.h
Includes the VolServ API types and
enumerations.
Includes the VolServ API global variables that
are accessible to the client.
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_Initializecreates and
initializes the APIs required variables and creates a
communication link with VolServ. Before the client program
terminates, it calls the VS_Terminateroutine to allow the
VolServ API to clean up its processing.
For example:
1-10
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
#include <stdio.h>
#include <vs_client.h>
main()
{
VST_HOSTNAME vshost;
/* get volserv host name from the user */
printf ( “Enter the name of the VolServ host
computer ==> “ );
scanf ( “%s”, vshost );
/* initialize the VolServ API. */
/* returns TRUE if successful, */
/* FALSE if fails. */
if ( VS_Initialize ( vshost, 0, 30 ) )
{
/* send and create commands */
.............
/* allow VolServ API to */
/* terminate properly */
VS_Terminate();
}
else
{
printf ( “Error initializing VolServ
API” );
}
}
601355 Rev A
Getting Started
1-11
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
API objects and handles are described below.
API Types
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.
Objects
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.
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.
Handles
1-12
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Each handle has the four base routines descried in the table
below:
Routine
Description
initializer
The initializer creates and initializes the data
held by the handle and 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The table below describes the API naming conventions:
Naming
Conventions
Item
Description
Handles
Handle names start with the VSTprefix, followed by the specific
object name, and end with the HANDLEsuffix. 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
VSTprefix. For example: VST_DRIVE_ID
Definitions
Definitions that are defined in the client definition header file
should begin with the VSDprefix. For example:
VSD_DRIVE_NAME_LEN
Enumerations
Enumerations have two conventions to follow. The type begins with
the VSTprefix. The values inside the enumeration structure begin
with the VSEprefix.
For example:
typedef enum {
VSE_DRIVETYPE_NONE
= 0,
VSE_DRIVETYPE_MAGTAPE =1
} VST_DRIVE_TYPE
Global Variables
Identifiers
Global variables begin with the VSGprefix. For example:
VSG_ERROR_CODE
Identifiers that are used in the “assignment” and “accessor”
functions to identify the field being accessed within each handle
begin with the VSIDprefix. The following identifier is for a drive
identifier, for example: VSID_DRIVE_ID
601355 Rev A
Getting Started
1-15
Download from Www.Somanuals.com. All Manuals Search And Download.
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 VSprefix,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Item
Description
VS_Command_GetFields ( cmdh,
VSID_STATUS_HANDLE,
&statush,
VSID_ERROR_HANDLE
&errorh,
VSID_STATUS_CODE,
&statcode,
VSID_ENDFIELD );
if ( statcode == VSE_STATUS_OK )
{
VS_Status_GetFields ( status,
VSID_MEDIA_ID, media,
VSID_DRIVE_ID, &drive,
VSID_ENDFIELD );
printf ( “media [%s] mounted on
[%d]”, media, drive );
}
else
{
print_error_code ( errorh );
}
}
Function names that map directly to a VolServ Command
begin with the VSCMDprefix, 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Dispatch routines are functions within the client software that
the API automatically calls when status messages or
MediaClass callbacks are received from VolServ. The dispatch
routine for MediaClass callbacks (also referred to as
notifications) is described on the man page for
VS_Notify_SetFields(l).
Dispatch
Routines
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_HANDLEhandle)
The dispatch routine takes one argument. This is the command
handle for the request that received status.
601355 Rev A
Getting Started
1-19
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
Parameters
Global Parameter
Description
VSID_CLIENT_DISPATCH
VSID_ENTERPRISE_ID
Pointer to the dispatch function for all commands.
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
(defaults to 15)
Execution priority assigned to every command request.
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_LIMITplus1) multiplied
by the VSID_TIMEOUT_VALUE.
VSID_RETRY_LIMITis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The following global variables are available to any software
using the VolServ API.
Global
Variables
Global Variable
Description
VSG_Error
Global error handle. It is set if an
error condition occurs in a
function that does not use a
command handle. This includes
the utility functions, handle
functions, and the functions that
set request- specific defaults.
See the man page for
VS_Error_GetFieldsto learn
how to access error codes.
VSG_Command_Received
Pointer to the command handle
whose status was just received
from VolServ. The
VSG_Command_Receivedcan
only be used in asynchronous
processing.
601355 Rev A
Getting Started
1-21
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The API differentiates between:
API Error
Handling
•
•
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 AAAis a three-letter string designating where the error
originates, and NNNis a numeric code designating the specific
error. The three-letter string maps either to an API object or to
VolServ. The numeric code represents either an API internal
error or the VolServ error code returned in the command’s
status.
The following example shows how to access an error code:
int numcode,
objcode;
VST_ERROR_CODE
VST_ERROR_HANDLE
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSID_ENDFIELD);
printf ( “error code %s\n”, errcode );
printf ( “object code for error: %d\n”,
objcode );
printf ( “numeric code for error: %d\n”,
numcode );
601355 Rev A
Getting Started
1-23
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Using the API
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
Handle
Each command has one entry point - a call of the form:
VSCMD_commandname
Command Calls
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See the following example:
if ( VSCMD_Mount ( cmd_handle,
VSID_MEDIACLASS_NAME,”scratch”
VSID_DRIVEPOOL_NAME,
”stagepool”,
VSID_PRIORITY,1,
VSID_ENDFIELD ) )
{
printf ( “mount successful\n” );
}
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:
Command
Defaults
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
These two commands perform the same function as the
previous example. The VSCMD_Mount_SetDefaultsfunction
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_SetDefaultsare valid only for Mount
commands.
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_GetFieldsfunction. After the status
handle is obtained, any command-specific field associated with
the status can be obtained through the
Command
Status
VS_Status_GetFieldsfunction. See to the following
example:
VST_MEDIA_ID
VST_DRIVE_ID
VST_STATUS
mediaid;
driveid;
status;
VST_COMMAND_HANDLE
VST_STATUS_HANDLE
cmd_handle;
status_handle;
if ( (cmd_handle = VS_Command_Create ())
==
(VST_COMMAND_HANDLE) NULL )
{
return ( -1 );
}
1-26
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VolServ API allows for both asynchronous and
synchronous processing of VolServ commands.
Processing
For asynchronous processing, the VolServ API returns control
to the client after initial status is received.
Asynchronous
2
3
VSCMD_cmd
Volume
Server
VS_Select
4
1
5
6
7
8
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 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_Selectfunction. 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Asynchronous processing also gives the client more control
over the processing environment. The VSID_RETRY_LIMITis
not applicable when the API software executes in asynchronous
mode. If the VSID_STATUS_WAIT_FLAGvalue 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.
Synchronous
2
3
VSCMD_cmd
4
Volume
Server
VS_Select
8
1
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_FLAGvalue is
TRUE, the API operates in synchronous mode.
601355 Rev A
Getting Started
1-29
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The API function descriptions in this book are presented as
follows:
API Functions
Function
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.
1-30
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
601355 Rev A
Getting Started
1-31
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
1-32
Getting Started
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
2-2
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_Listen . . . . . . . . . . . . . . . . . . . . . . . . 2-357
601355 Rev A
API Functions
2-3
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Audit_SetDefaults . . . . . . . . . . . . . . . 2-501
2-4
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreatePool . . . . . . . . . . . . . . . . . . . . . . 2-777
601355 Rev A
API Functions
2-5
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyArchiveMediaClass. . . . . . . . 2-895
2-6
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Roadmap
Refer To
Chapter
Topic
Naming conventions.
Global parameters.
Error handling.
1
API functions.
Valid staus fields.
Error codes.
2
A
B
C
Mount example.
601355 Rev A
API Functions
2-7
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Archive_Createallocates a VolServ API archive
handle. An archive handle is used to pass archive information to
and from VolServ.
VS_Archive_
Create
VST_ARCHIVE_HANDLE VS_Archive_Create ( void )
Synopsis
Arguments
None
Return Values
VS_Archive_Createreturns:
•
•
An archive handle, if one can be allocated.
NULL, if an archive handle cannot be allocated. An
appropriate error code is set in VSG_Error.
• VSE_ERR_OUTOFMEM- Memory allocation error.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_archive_handle
4 *
5 * PURPOSE:
6 * This function tests an archive handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_archive_handle(void)
14 #else
15
VST_BOOLEAN vst_archive_handle(void)
16 #endif
17 {
2-8
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
VST_ARCHIVE_HANDLE
VST_ARCHIVE_TYPE
ArchiveType;
h;
21
22
23
24
VST_ARCHIVE_NAME
ArchiveName;
VST_HOSTNAME
ConsoleLoc;
VST_COMP_STATE
ComponentState;
VST_ARCHIVE_MODE
ArchiveMode;
25
26
VST_ARCHIVE_FILL_MODE
VST_ARCHIVE_CONFIG_STATE
ConfigState;
FillMode;
27
28
29
30
31
32
33
/* create the handle */
h = VS_Archive_Create();
if (h != (VST_ARCHIVE_HANDLE) NULL)
{
/* get values from user */
printf(“*** Archive Handle
***\n”);
34
35
36
37
38
printf(“Enter Archive Type ==> “);
ArchiveType = atoi(gets(input));;
printf(“Enter Archive Name ==> “);
gets(ArchiveName);
printf(“Enter Console Display
Location ==> “);
39
40
gets(ConsoleLoc);
printf(“Enter archive state ==>
“);
41
ComponentState =
atoi(gets(input));
42
43
44
45
46
47
48
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 */
601355 Rev A
API Functions
2-9
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
49
50
rc = VS_Archive_SetFields(h,
VSID_ARCHIVE_NAME,
ArchiveName,
51
52
VSID_ARCHIVE_TYPE,
ArchiveType,
VSID_ARCHIVE_CONSOLE_LOCATION,Con
soleLoc,
53
54
55
56
VSID_COMP_STATE,
ComponentState,
VSID_ARCHIVE_MODE,
ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
FillMode,
VSID_ARCHIVE_CONFIG_STATE,
ConfigState,
57
58
59
60
61
62
63
VSID_ENDFIELD);
if (rc)
{
vst_print_archive(h);
}
VS_Archive_Destroy(h);
}
64 return(rc);
65 }
See Also
•
•
•
•
•
vsapi(l),
VS_Archive_Destroy(l),
VS_Archive_GetFields(l),
VS_Archive_SetFields(l),
VS_Error_GetFields(l)
2-10
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Archive_Destroydeallocates an archive handle that
was allocated with VS_Archive_Create. An archive
handle is used to pass archive information to and from VolServ.
VS_Archive_
Destroy
VST_BOOLEAN VS_Archive_Destroy
(VST_ARCHIVE_HANDLE handle)
Synopsis
Arguments
• handle= Archive handle to destroy.
Return Values
• VS_Archive_Destroyreturns:
• 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
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
601355 Rev A
API Functions
2-11
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
78
VST_BOOLEAN vst_archive_handle(void)
79 #endif
80 {
81
VST_BOOLEAN
rc =
h;
VSE_FALSE;
82
83
VST_ARCHIVE_HANDLE
VST_ARCHIVE_TYPE
ArchiveType;
84
85
86
87
VST_ARCHIVE_NAME
ArchiveName;
VST_HOSTNAME
ConsoleLoc;
VST_COMP_STATE
ComponentState;
VST_ARCHIVE_MODE
ArchiveMode;
88
89
VST_ARCHIVE_FILL_MODE
VST_ARCHIVE_CONFIG_STATE
ConfigState;
FillMode;
90
91
92
93
94
95
96
/* create the handle */
h = VS_Archive_Create();
if (h != (VST_ARCHIVE_HANDLE) NULL)
{
/* get values from user */
printf(“*** Archive Handle
***\n”);
97
98
99
100
101
printf(“Enter Archive Type ==> “);
ArchiveType = atoi(gets(input));;
printf(“Enter Archive Name ==> “);
gets(ArchiveName);
printf(“Enter Console Display
Location ==> “);
102
103
gets(ConsoleLoc);
printf(“Enter archive state ==>
“);
104
ComponentState =
atoi(gets(input));
105
106
107
108
printf(“Enter Archive Mode ==> “);
ArchiveMode = atoi(gets(input));
printf(“Enter Fill Mode ==> “);
FillMode = atoi(gets(input));;
2-12
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
109
110
111
112
113
printf(“Enter Config State ==> “);
ConfigState = atoi(gets(input));;
/* set the fields in the handle */
rc = VS_Archive_SetFields(h,
VSID_ARCHIVE_NAME,
ArchiveName,
114
115
VSID_ARCHIVE_TYPE,
ArchiveType,
VSID_ARCHIVE_CONSOLE_LOCATION,Con
soleLoc,
116
117
118
119
VSID_COMP_STATE,
ComponentState,
VSID_ARCHIVE_MODE,
ArchiveMode,
VSID_ARCHIVE_FILL_MODE,
FillMode,
VSID_ARCHIVE_CONFIG_STATE,
ConfigState,
120
121
VSID_ENDFIELD);
if (rc)
122
{
123
124
vst_print_archive(h);
}
125
VS_Archive_Destroy(h);
126 }
127return(rc);
128}
Notes
After VS_Archive_Destroyhas been called for an archive
handle, that handle is no longer valid and should not be used.
601355 Rev A
API Functions
2-13
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Archive_Create(l),
VS_Archive_GetFields(l),
VS_Archive_SetFields(l),
VS_Error_GetFields(l)
2-14
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Archive_GetFieldsretrieves information associated
with an archive handle. An archive handle is used to pass
archive information to and from VolServ.
VS_Archive_
GetFields
VST_BOOLEAN VS_Archive_GetFields
(VST_ARCHIVE_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_ARCHIVE_CONFIG_STATE
(VST_ARCHIVE_CONFIG_STATE*)
Pointer to a boolean flag that indicates
whether the archive is currently being
configured or reconfigured.
Valid VSID_ARCHIVE_CONFG_STATEvalues
are enumerated in the vs_types.h file.
VSID_ARCHIVE_CONSOLE_LOCATION
(VST_HOSTNAME)
Pointer to the location of the archive’s console
display.
601355 Rev A
API Functions
2-15
Download from Www.Somanuals.com. All Manuals Search And Download.
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_TYPEvalues 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 Index of the archive media class handle in the
TRY
MediaClass capacity table.
(int,VST_ARCHIVEMEDIACLASS_HANDLE)
Pointer to the location to store the archive
media class handle.
VSID_ARCHIVEMEDIACLASS_HANDLE_TA
BLE (VST_TABLE_HANDLE *)
Pointer to the MediaClass capacity (in table
format) for this archive.
VSID_COMP_STATE (VST_COMP_STATE *)
Pointer to the operational state of this archive.
Valid VSID_COMP_STATEvalues are
enumerated in the vs_types.h file.
VSID_DRIVE_ID (int)
Index of the drive in the drive identifier table.
2-16
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
(VST_DRIVE_ID *)
Description
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.
Pointer to the location to store the drive
identifier
VSID_DRIVE_ID_TABLE
(VST_TABLE_HANDLE *)
Pointer to the drives (in table format)
associated with this archive.
VSID_MEDIA_ID (int)
Index of the medium in the media identifier
table.
(VST_MEDIA_ID )
Pointer to the first media id in the media
identifier table.
VSID_MEDIA_ID_ENTRY (int, VST_
MEDIA_ID)
Index of the medium in the media identifier
table.
Pointer to the location to store the media
identifier.
VSID_MEDIA_ID_TABLE
(VST_TABLE_HANDLE *)
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 *)
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of drive ids present in
the drive id table.
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)
(VST_TYPECAPACITY_HANDLE *)
Index of the type capacity handle in the table.
Pointer to the first archive type capacity
handle in the MediaType capacity table.
601355 Rev A
API Functions
2-17
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_TYPECAPACITY_HANDLE_ENTRY
(int, VSID_TYPECAPACITY_HANDLE *)
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 *)
Pointer to the type capacity (in table format)
for this archive.
Return Values
VS_Archive_GetFieldsreturns:
• 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.
2-18
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
129/**************************************
***********
130*
131* FUNCTION: vst_print_archive
132*
133* PURPOSE:
134* This function prints out the
information stored in
135* an archive handle.
136*
137* PARAMETERS:
138* h : the archive handle to print
139*
140***************************************
**********/
141#ifdef ANSI_C
142 void
vst_print_archive(VST_ARCHIVE_HAN
DLE h)
143#else
144 void vst_print_archive(h)
145 VST_ARCHIVE_HANDLE h;
146#endif
147{
148 VST_ARCHIVE_TYPE
ArchiveType;
149 VST_ARCHIVE_NAME
ArchiveName;
150 VST_HOSTNAME
ConsoleLoc;
151 VST_COMP_STATE
ComponentState;
152 VST_ARCHIVE_MODE
ArchiveMode;
153 VST_ARCHIVE_FILL_MODE
154 VST_ARCHIVE_CONFIG_STATE
ConfigState;
FillMode;
155 VST_TABLE_HANDLE
DriveIDTable;
156 VST_TABLE_HANDLE
MediaIDTable;
601355 Rev A
API Functions
2-19
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
157 VST_TABLE_HANDLE
ClassCapacityTable;
158 VST_TABLE_HANDLE
TypeCapacityHandleTable;
159 int
160 int
n;
i;
161 VST_DRIVE_ID *
DriveID;
162 char *
MediaID;
163 VST_ARCHIVEMEDIACLASS_HANDLE
arcmc_handle;
164 VST_TYPECAPACITY_HANDLE
typecap_handle;
165
166 VS_Archive_GetFields(h,
167
168
169
170
171
172
173
174
175
176
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,
VSID_ARCHIVEMEDIACLASS_HANDLE_TAB
LE, &ClassCapacityTable,
VSID_TYPECAPACITY_HANDLE_TABLE,
&TypeCapacityHandleTable,
VSID_ENDFIELD);
177
178
179
2-20
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
180 printf(“*** Archive Handle
Information ***\n”);
181 printf(“Archive Type = %d\n”,
ArchiveType);
182 printf(“Archive Name = %s\n”,
ArchiveName);
183 printf(“Console Display Location =
%s\n”, ConsoleLoc);
184 printf(“Component State = %d\n”,
ComponentState);
185 printf(“Archive Mode = %d\n”,
ArchiveMode);
186 printf(“Archive Fill Mode = %d\n”,
FillMode);
187 printf(“Config State = %d\n”,
ConfigState);
188
189 if (DriveIDTable !=
(VST_TABLE_HANDLE) NULL)
190 {
191
192
193
/* 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,
198
199
200
VSID_ENDFIELD);
printf(“DriveID Entry #%d =
%d\n”,i,*DriveID);
}
201
202 }
203
204 if (MediaIDTable !=
(VST_TABLE_HANDLE) NULL)
205 {
206
/* Get # of entries */
207
VS_Table_GetFields(MediaIDTable,
601355 Rev A
API Functions
2-21
Download from Www.Somanuals.com. All Manuals Search And Download.
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,
213
214
215
VSID_ENDFIELD);
printf(“Media ID Entry #%d =
%s\n”,i,MediaID);
}
216
217 }
218
219 if (ClassCapacityTable !=
(VST_TABLE_HANDLE) NULL)
220 {
221
222
/* 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,
228
VSID_TABLE_ENTRY, i,
&arcmc_handle,
229
230
VSID_ENDFIELD);
vst_print_archivemediaclass(arcmc
_handle);
}
231
232 }
233
234 if (TypeCapacityHandleTable !=
(VST_TABLE_HANDLE) NULL)
235 {
2-22
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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,
243
VSID_TABLE_ENTRY, i,
&typecap_handle,
244
245
VSID_ENDFIELD);
vst_print_typecapacity(typecap_ha
ndle);
}
246
247 }
248}
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VST_ARCHIVEMEDIACLASS_HANDLE, VST_DRIVE_ID,
VST_MEDIA_ID, and VST_TYPECAPACITY_HANDLE
parameters require that two arguments be passed instead of one.
•
The first argument passed is the entry number in the
appropriate table.
•
The second argument is Pointer to the location where the
value is stored.
See Also
•
•
•
•
•
•
•
•
•
•
•
vsapi(l),
VS_Archive_Create(l),
VS_Archive_Destroy(l),
VS_Archive_SetFields(l),
VS_ArchiveMediaClass_GetFields(l),
VS_ArchiveMediaClass_SetFields(l),
VS_Error_GetFields(l),
VS_Table_GetFields(l),
VS_TypeCapacity_GetFields(l),
VS_TypeCapacity_SetFields(l),
VSCMD_Archive_Query(l
2-24
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Archive_SetFieldssets the value of one or more
field in an archive handle. An archive handle is used to pass
archive information to and from VolServ.
VS_Archive_
SetFields
VST_BOOLEAN VS_Archive_SetFields
(VST_ARCHIVE_HANDLE
handle,
Synopsis
“…”,
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_STATEvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_ARCHIVE_FILL_MODE
(VST_ARCHIVE_FILL_MODE)
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_MODEvalues
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_MODEvalues 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_TYPEvalues are
enumerated in the vs_types.h file.
VSID_COMP_STATE (VST_COMP_STATE)
The operational state of this archive. Valid
VSID_COMP_STATEvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Archive_SetFieldsreturns:
• VSE_TRUE- Successful execution.
• VSE_FALSE- API failure - An appropriate error code is set
in VSG_Error.
• VSE_ERR_BADHANDLE- Specified handle was not a
criteria handle.
• VSE_ERR_BADSIZE- The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
• VSE_ERR_NULLHANDLE- Specified handle was a null
pointer.
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
249/**************************************
***********
250*
251* FUNCTION: vst_archive_handle
252*
253* PURPOSE:
254* This function tests an archive handle.
255*
256* PARAMETERS:
257* none
258*
259***************************************
**********/
260#ifdef ANSI_C
261 VST_BOOLEAN vst_archive_handle(void)
262#else
263 VST_BOOLEAN vst_archive_handle(void)
264#endif
265{
266 VST_BOOLEAN
VSE_FALSE;
rc =
601355 Rev A
API Functions
2-27
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
267 VST_ARCHIVE_HANDLE
268 VST_ARCHIVE_TYPE
ArchiveType;
h;
269 VST_ARCHIVE_NAME
ArchiveName;
270 VST_HOSTNAME
ConsoleLoc;
271 VST_COMP_STATE
ComponentState;
272 VST_ARCHIVE_MODE
ArchiveMode;
273 VST_ARCHIVE_FILL_MODE
274 VST_ARCHIVE_CONFIG_STATE
ConfigState;
FillMode;
275
276 /* create the handle */
277 h = VS_Archive_Create();
278 if (h != (VST_ARCHIVE_HANDLE) NULL)
279 {
280
281
/* get values from user */
printf(“*** Archive Handle
***\n”);
282
283
284
285
286
printf(“Enter Archive Type ==> “);
ArchiveType = atoi(gets(input));;
printf(“Enter Archive Name ==> “);
gets(ArchiveName);
printf(“Enter Console Display
Location ==> “);
287
288
gets(ConsoleLoc);
printf(“Enter archive state ==>
“);
289
ComponentState =
atoi(gets(input));
290
291
292
293
294
295
296
297
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,
2-28
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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,
305
306
VSID_ENDFIELD);
if (rc)
307
{
308
309
vst_print_archive(h);
}
310
VS_Archive_Destroy(h);
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-31
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_ArchiveMediaClass_Createallocates a VolServ
API archive media class handle. An archive media class handle
is used to pass archive media class information to and from
VolServ.
VS_Archive
MediaClass_
Create
VST_ARCHIVEMEDIACLASS_HANDLE
VS_ArchiveMediaClass_Create
( void )
Synopsis
Arguments
None
Return Values
VS_ArchiveMediaClass_Createreturns:
•
•
An archive media class handle, if one can be allocated.
NULL, if an archive media class handle cannot be allocated.
An appropriate error code is set in VSG_Error.
• VSE_ERR_OUTOFMEM- Memory allocation error.
Example
314/**************************************
***********
315*
316* FUNCTION:
vst_archivemediaclass_handle
317*
318* PURPOSE:
319* This function tests an
archivemediaclass handle.
320*
321* PARAMETERS:
322* none
323*
324***************************************
**********/
2-32
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
325#ifdef ANSI_C
326 VST_BOOLEAN
vst_archivemediaclass_handle(void
)
327#else
328 VST_BOOLEAN
vst_archivemediaclass_handle()
329#endif
330{
331 VST_BOOLEAN rc;
332 VST_ARCHIVEMEDIACLASS_HANDLE h;
333 VST_ARCHIVE_NAME
Archive;
334 VST_MEDIA_CLASS_NAME
MediaClass;
335 VST_MEDIA_TYPE_NAME
MediaType;
336 VST_CAPACITY
Capacity;
337 VST_PERCENT
MediaClassPercent;
338 VST_ARCHIVE_ACTION_OPTION
ActionMode;
339 VST_HIGH_MARK
HighMark;
340 VST_LOW_MARK
LowMark;
341 VST_FILL_LEVEL
FillLevel;
342 VST_PRIORITY
MigrationPriority;
343 VST_ARCHIVE_NAME
TargetArchive;
344
345 /* create the handle */
346 h = VS_ArchiveMediaClass_Create();
347 if (h !=
(VST_ARCHIVEMEDIACLASS_HANDLE)
NULL)
348 {
349
/* get the values from the user */
601355 Rev A
API Functions
2-33
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
350
printf(“** Archive Media Class
handle **\n”);
351
352
353
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
354
355
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
356
357
358
359
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter MediaClass Percent
==> “);
360
361
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
362
363
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
364
365
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
366
367
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
368
369
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
370
371
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
Archive,
VSID_MEDIA_CLASS_NAME,
MediaClass,
372
373
374
375
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
Capacity,
2-34
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
376
377
378
379
380
381
VSID_PERCENT,
MediaClassPercent,
VSID_ARCHIVE_ACTION,
ActionMode,
VSID_HIGH_MARK,
HighMark,
VSID_LOW_MARK,
LowMark,
VSID_FILL_LEVEL,
FillLevel,
VSID_MIGRATION_PRIORITY,Migration
Priority,
382
VSID_TARGET_ARCHIVE_NAME,TargetAr
chive,
383
384
385
386
VSID_ENDFIELD);
if (rc)
{
vst_print_archivemediaclass(h);
387
}
388
VS_ArchiveMediaClass_Destroy(h);
389 }
390 return(rc);
391}
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_ArchiveMediaClass_Destroydeallocates an
archive media class handle that was allocated with
VS_ArchiveMediaClass_Create.
VS_Archive
MediaClass_
Destroy
VST_BOOLEAN VS_ArchiveMediaClass_Destroy
(VST_ARCHIVEMEDIACLASS
Synopsis
_HANDLE
handle)
Arguments
• handle= Archive media class handle to be destroyed.
Return Values
VS_ArchiveMediaClass_Destroy returns:
• VSE_TRUE- Successful execution.
• VSE_FALSE- API failure - An appropriate error code is set
in VSG_Error.
• VSE_ERR_BADHANDLE- Specified handle was not an
archive media class handle.
• VSE_ERR_NULLHANDLE- Specified handle was a null
pointer.
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_archivemediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests an
archivemediaclass handle.
7 *
2-36
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_archivemediaclass_handle(void
)
14 #else
15
VST_BOOLEAN
vst_archivemediaclass_handle()
16 #endif
17 {
18
19
20
VST_BOOLEAN rc;
VST_ARCHIVEMEDIACLASS_HANDLE h;
VST_ARCHIVE_NAME
Archive;
21
22
23
24
25
26
27
28
29
30
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;
31
32
33
/* create the handle */
h = VS_ArchiveMediaClass_Create();
601355 Rev A
API Functions
2-37
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
34
if (h !=
(VST_ARCHIVEMEDIACLASS_HANDLE)
NULL)
35
36
37
{
/* get the values from the user */
printf(“** Archive Media Class
handle **\n”);
38
39
40
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
41
42
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
43
44
45
46
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter MediaClass Percent
==> “);
47
48
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
49
50
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
51
52
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
53
54
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
55
56
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
57
58
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
59
Archive,
2-38
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
60
61
62
63
64
65
66
67
68
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)
70
71
72
73
{
vst_print_archivemediaclass(h);
74
}
75
VS_ArchiveMediaClass_Destroy(h);
76
}
77
return(rc);
78 }
Notes
After VS_ArchiveMediaClass_Destroyhas been called for
an archive media class handle, that handle is no longer valid and
should not be used.
601355 Rev A
API Functions
2-39
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_ArchiveMediaClass_Create(l),
VS_ArchiveMediaClass_GetFields(l),
VS_ArchiveMediaClass_SetFields(l),
VS_Error_GetFields(l)
2-40
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_ArchiveMediaClass_GetFieldsretrieves
VS_Archive
MediaClass_
GetFields
information associated with an archive media class handle. An
archive media class handle is used to pass archive media class
information to and from VolServ.
VST_BOOLEAN VS_ArchiveMediaClass_GetFields
( VST_ARCHIVEMEDIACLASS
_HANDLE handle,
Synopsis
“…”,
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
Description
VSID_ARCHIVE_ACTION
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.
(VST_ARCHIVE_ACTION_OPTION*)
601355 Rev A
API Functions
2-41
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CAPACITYabove
which the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
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_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
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
VS_ArchiveMediaClass_GetFieldsreturns:
• 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.
601355 Rev A
API Functions
2-43
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_archivemediaclass
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * an Archive Media Class handle.
8 *
9 * PARAMETERS:
10 * h : the Archive Media Class handle to
print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_archivemediaclass
(VST_ARCHIVEMEDIACLASS_HANDLE h)
15 #else
16
void vst_print_archivemediaclass(h)
17 VST_ARCHIVEMEDIACLASS_HANDLE h;
18 #endif
19 {
20
21
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
MediaClass;
Archive;
22
VST_MEDIA_TYPE_NAME
MediaType;
23
24
VST_CAPACITY
VST_PERCENT
Capacity;
MediaClassPercent;
VST_ARCHIVE_ACTION_OPTION
ActionMode;
25
26
27
28
VST_HIGH_MARK
VST_LOW_MARK
VST_FILL_LEVEL
FillLevel;
HighMark;
LowMark;
29
VST_PRIORITY
MigrationPriority;
2-44
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
31
VST_ARCHIVE_NAME
TargetArchive;
VST_TABLE_HANDLE
RestrictedComps;
int
32
33
34
i;
n;
int
VST_COMPONENT_HANDLE
Component;
35
36
37
VS_ArchiveMediaClass_GetFields(h,
VSID_ARCHIVE_NAME,
Archive,
38
39
40
41
42
43
44
45
46
47
48
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_COMPONENT_HANDLE_TABLE,&Rest
rictedComps,
49
50
VSID_ENDFIELD);
printf(“*** Archive Media Class
Handle ***\n”);
51
52
printf(“Archive Name = %s\n”,
Archive);
printf(“Media Class Name = %s\n”,
MediaClass);
601355 Rev A
API Functions
2-45
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
53
printf(“Media Type Name = %s\n”,
MediaType);
54
55
printf(“Capacity = %d\n”, Capacity);
printf(“Media Class percent = %d\n”,
MediaClassPercent);
56
printf(“Archive Action Mode = %d\n”,
ActionMode);
57
58
59
printf(“High Mark = %d\n”, HighMark);
printf(“Low Mark = %d\n”, LowMark);
printf(“Fill Level = %d\n”,
FillLevel);
60
61
62
printf(“Migration Priority = %d\n”,
MigrationPriority);
printf(“Target Archive = %s\n”,
TargetArchive);
if (RestrictedComps !=
(VST_TABLE_HANDLE) NULL)
{
63
64
65
/* get number of entries */
VS_Table_GetFields(RestrictedComp
s,
66
67
68
69
70
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for (i = 0; i < n; i++)
{
VS_Table_GetFields(RestrictedComp
s,
71
VSID_TABLE_ENTRY, i,
&Component,
72
73
VSID_ENDFIELD);
vst_print_component(Component);
74
75
}
}
76 }
2-46
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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:
•
•
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.
601355 Rev A
API Functions
2-47
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
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)
2-48
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_ArchiveMediaClass_SetFieldssets 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.
VS_Archive
MediaClass_
SetFields
VST_BOOLEAN VS_ArchiveMediaClass_SetFields
(VST_ARCHIVEMEDIACLASS
Synopsis
_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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION)
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_ACTIONvalues
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_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
2-50
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_LOW_MARK (VST_LOW_MARK) 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_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MIGRATION_PRIORITY(VST_ The migration priority to be applied to this
PRIORITY)
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
VS_ArchiveMediaClass_SetFieldsreturns:
• VSE_TRUE- Successful execution.
• VSE_FALSE- API failure - An appropriate error code is set
in VSG_Error.
2-52
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_archivemediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests an
archivemediaclass handle.
7 *
8 * PARAMETERS:
9 * none
10
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_archivemediaclass_handle(void
)
14 #else
15
VST_BOOLEAN
vst_archivemediaclass_handle()
16 #endif
17 {
18
19
VST_BOOLEAN rc;
VST_ARCHIVEMEDIACLASS_HANDLE h;
601355 Rev A
API Functions
2-53
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
26
27
28
29
30
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;
31
32
33
34
/* create the handle */
h = VS_ArchiveMediaClass_Create();
if (h !=
(VST_ARCHIVEMEDIACLASS_HANDLE)
NULL)
35
36
37
{
/* get the values from the user */
printf(“** Archive Media Class
handle **\n”);
38
39
40
printf(“Enter Archive Name ==> “);
gets(Archive);
printf(“Enter Media Class Name ==>
“);
41
42
gets(MediaClass);
printf(“Enter Media Type Name ==>
“);
43
44
45
gets(MediaType);
printf(“Enter Capacity ==> “);
Capacity = atoi(gets(input));
2-54
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
48
printf(“Enter MediaClass Percent
==> “);
MediaClassPercent =
atoi(gets(input));
printf(“Enter Archive Action Mode
==> “);
49
50
ActionMode = atoi(gets(input));
printf(“Enter High Mark Mode ==>
“);
51
52
HighMark = atoi(gets(input));
printf(“Enter Fill Level Mode ==>
“);
53
54
FillLevel = atoi(gets(input));
printf(“Enter Migration Priority
==> “);
55
56
MigrationPriority =
atoi(gets(input));
printf(“Enter Target Archive ==>
“);
57
58
gets(TargetArchive);
rc =
VS_ArchiveMediaClass_SetFields(h,
VSID_ARCHIVE_NAME,
Archive,
VSID_MEDIA_CLASS_NAME,
MediaClass,
VSID_MEDIA_TYPE_NAME,
MediaType,
VSID_CAPACITY,
Capacity,
59
60
61
62
63
64
65
66
67
68
VSID_PERCENT,
MediaClassPercent,
VSID_ARCHIVE_ACTION,
ActionMode,
VSID_HIGH_MARK,
HighMark,
VSID_LOW_MARK,
LowMark,
VSID_FILL_LEVEL,
FillLevel,
VSID_MIGRATION_PRIORITY,
MigrationPriority,
601355 Rev A
API Functions
2-55
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
69
VSID_TARGET_ARCHIVE_NAME,
TargetArchive,
VSID_ENDFIELD);
if (rc)
70
71
72
73
{
vst_print_archivemediaclass(h);
74
}
75
VS_ArchiveMediaClass_Destroy(h);
76
}
77
return(rc);
78 }
Notes
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.
2-56
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-57
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Command_Createallocates a VolServ API command
handle. A command handle is used to pass command
information to and from VolServ.
VS_
Command_
Create
VST_COMMAND_HANDLE VS_Command_Create ( void )
Synopsis
Arguments
None
Return Values
VS_Command_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_command_handle
4 *
5 * PURPOSE:
6 * This function tests a command handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_command_handle(void)
14 #else
15
VST_BOOLEAN vst_command_handle(void)
16 #endif
2-58
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
31
VST_BOOLEAN
VST_COMMAND_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_RETRY_LIMIT
VST_TIME_OUT
rc = VSE_FALSE;
requestid;
reqtype;
retrylimit;
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”);
32
33
34
35
36
37
38
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 ==>
“);
39
40
41
42
43
timeout = atol(gets(input));
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
44
45
46
47
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
48
49
50
VSID_ENDFIELD);
if (rc)
{
601355 Rev A
API Functions
2-59
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
51
/* print the handle and destroy
it */
vst_print_command(h);
52
53
}
54
VS_Command_Destroy(h);
55
}
56
return(rc);
57 }
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Command_Destroydeallocates a command handle that
was allocated with VS_Command_Create. A command
handle is used to pass command information to and from
VolServ.
VS_
Command_
Destroy
VST_BOOLEAN VS_Command_Destroy
(VST_COMMAND_HANDLE
cmdhandle)
Synopsis
Arguments
• cmdhandle = Command handle to be destroyed.
Return Values
VS_Command_Destroyreturns:
• 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.
601355 Rev A
API Functions
2-61
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_command_handle
4 *
5 * PURPOSE:
6 * This function tests a command handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_command_handle(void)
14 #else
15
VST_BOOLEAN vst_command_handle(void)
16 #endif
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
31
VST_BOOLEAN
VST_COMMAND_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_RETRY_LIMIT
VST_TIME_OUT
rc = VSE_FALSE;
requestid;
reqtype;
retrylimit;
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”);
32
33
34
35
36
37
38
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 ==>
“);
2-62
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
40
41
42
43
timeout = atol(gets(input));
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
44
45
46
47
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
48
49
50
51
VSID_ENDFIELD);
if (rc)
{
/* print the handle and destroy
it */
52
53
vst_print_command(h);
}
54
VS_Command_Destroy(h);
55
}
56
return(rc);
57 }
Notes
A command handle should be used for only one outstanding
command at any given time.
After VS_Command_Destroyhas 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_Destroyrequest for the
associated command handle.
601355 Rev A
API Functions
2-63
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_GetFields(l),
VS_Command_SetFields(l),
VS_Error_GetFields(l)
2-64
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Command_GetErrorFieldsretrieves information
VS_
associated with the command’s error handle. It can be used in
place of the VS_Error_GetFieldsroutine when the user
does not want to retrieve the error handle explicitly from the
command handle.
Command_
GetError-
Fields
VST_BOOLEAN VS_Command_GetErrorFields
(VST_COMMAND_HANDLE cmdhandle,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VS_Command_GetErrorFieldsreturns:
• 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.
Notes
VS_Error_GetErrorFieldsreturns
• 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.
2-66
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
VS_Command_Create,
VS_Command_Destroy,
VS_Command_GetFields,
VS_Command_SetFields,
VS_Error_GetFields
601355 Rev A
API Functions
2-67
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Command_GetFieldsretrieves information associated
with a command handle. A command handle is used to pass
command information to and from VolServ.
VS_
Command_
GetFields
VST_BOOLEAN VS_Command_GetFields
(VST_COMMAND_HANDLE cmdhandle,
"…",
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
VSID_REQUEST_TYPE
Description
Pointer to the type of command. Valid
VSID_REQUEST_TYPEvalues are
enumerated in the vs_type.h file.
(VST_REQUEST_TYPE *)
VSID_STATUS_HANDLE
(VST_STATUS_HANDLE *)
Pointer to the status handle associated with
this command.
Return Values
VS_Command_GetFieldsreturns:
• 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.
Example
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 *
601355 Rev A
API Functions
2-69
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_command(VST_COMMAND_HAN
DLE h)
15 #else
16
17
void vst_print_command(h)
VST_COMMAND_HANDLE h;
18 #endif
19 {
20
21
22
23
24
25
26
27
28
29
VST_REQUEST_ID
requestid;
reqtype;
retrylimit;
timeout;
VST_REQUEST_TYPE
VST_RETRY_LIMIT
VST_TIME_OUT
VST_STATUS_WAIT_FLAG waitflag;
VST_ERROR_HANDLE
VST_STATUS_HANDLE
eh;
sh;
VS_Command_GetFields(h,
VSID_REQUEST_ID,
&requestid,
VSID_REQUEST_TYPE,
30
31
32
33
34
35
&reqtype,
VSID_RETRY_LIMIT,
&retrylimit,
VSID_TIMEOUT_VALUE,
&timeout,
VSID_STATUS_WAIT_FLAG,
&waitflag,
VSID_ERROR_HANDLE,
&eh,
VSID_STATUS_HANDLE,
VSID_ENDFIELD);
&sh,
36
37
38
printf(“ ****Command Handle
Information****\n\n”);
39
40
printf(“RequestID = %luRequestType=
%d\n”,requestid,reqtype);
printf(“Retry Limit = %dTime Out =
%d\n”,retrylimit,timeout);
2-70
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
41
printf(“StatusWait =
%d\n”,waitflag);
42
43
44
vst_print_status(sh);
vst_print_error(eh);
45 }
Notes
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.
See Also
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Command_SetFields(l),
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-71
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
VS_
Command_
GetStatus-
Fields
VST_BOOLEAN VS_Command_GetStatusFields
(VST_COMMAND_HANDLEcmdhandle, “…”,
VSID_ENDFIELD)
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ACTION_CODE
(VST_ACTION_CODE *)
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
(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.
601355 Rev A
API Functions
2-73
Download from Www.Somanuals.com. All Manuals Search And Download.
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
(VST_COMPONENT_HANDLE *)
Pointer to the first component handle in the
component handle table.
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)
(VST_COMPONENT_ID *)
Index of the appropriate component identifier
in the component identifier table.
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
Pointer to the component state for this status.
(VST_COMPONENT_STATE *)
Valid VSID_COMP_STATEvalues are
enumerated in the vs_types.hfile.
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.
2-74
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
VSID_DRIVE_HANDLE
Description
Pointer to the first drive handle in the drive
handle table.
(VST_DRIVE_HANDLE *)
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 *)
VSID_DRIVE_ID_ENTRY (int)
(VST_DRIVE_ID *)
Pointer to the first drive identifier in the drive
identifier table.
Index of the appropriate drive identifier in the
drive identifier table.
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
(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.
601355 Rev A
API Functions
2-75
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(VST_VOLERR_CODE *)
Index of the appropriate error code in the error
code table.
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 *)
VSID_FIELD_ENTRY(int)
(int *)
Pointer to the first field in the user-defined
media statistics field table.
Index of the appropriate field in the
user-defined media statistics field table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
(VST_MEDIACLASS_HANDLE *)
Pointer to the first MediaClass handle in the
MediaClass handle table.
VSID_MEDIACLASS_HANDLE_ENTRY (int)
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
(VST_MEDIATYPE_HANDLE *)
Pointer to the first media type handle in the
media type handle table.
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
(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.
601355 Rev A
API Functions
2-77
Download from Www.Somanuals.com. All Manuals Search And Download.
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 *)
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of media handles
present in the media handle table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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)
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_CODEvalues 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_TYPEvalues are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-79
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDis 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_REASONvalues are
enumerated in the vs_types.hfile.
Return Values
VS_Command_GetStatusFieldsreturns:
• 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.
2-80
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
601355 Rev A
API Functions
2-81
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Command_Setfieldssets the value of one or more
fields in a command handle. A command handle is used to pass
command information to and from VolServ.
VS_
Command_
SetFields
VST_BOOLEAN VS_Command_Setfields
( VST_COMMAND_HANDLE cmdhandle,
"…",
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_TYPEvalues are
enumerated in the vs_type.h file.
VSID_STATUS_HANDLE
(VST_STATUS_HANDLE)
Status handle associated with this command.
Return Values
VS_Command_Setfieldsreturns:
• 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.
601355 Rev A
API Functions
2-83
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_command_handle
4 *
5 * PURPOSE:
6 * This function tests a command handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_command_handle(void)
14 #else
15
VST_BOOLEAN vst_command_handle(void)
16 #endif
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
31
VST_BOOLEAN
VST_COMMAND_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_RETRY_LIMIT
VST_TIME_OUT
rc = VSE_FALSE;
requestid;
reqtype;
retrylimit;
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”);
32
33
34
35
36
37
38
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 ==>
“);
2-84
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
40
41
42
43
timeout = atol(gets(input));
/* set fields in handle */
rc = VS_Command_SetFields(h,
VSID_REQUEST_ID,
requestid,
44
45
46
47
VSID_REQUEST_TYPE,
reqtype,
VSID_RETRY_LIMIT,
retrylimit,
VSID_TIMEOUT_VALUE,
timeout,
VSID_STATUS_WAIT_FLAG,
waitflag,
48
49
50
51
VSID_ENDFIELD);
if (rc)
{
/* print the handle and destroy
it */
52
53
vst_print_command(h);
}
54
VS_Command_Destroy(h);
55
}
56
return(rc);
57 }
Notes
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),
601355 Rev A
API Functions
2-85
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
VS_Error_GetFields(l)
2-86
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Component_Createallocates a VolServ API
component handle. A component handle is used to pass
component information to and from VolServ.
VS_
Component_
Create
VST_COMPONENT_HANDLE VS_Component_Create
( void )
Synopsis
Arguments
None
Return Values
VS_Component_Createreturns:
•
•
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.
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
601355 Rev A
API Functions
2-87
Download from Www.Somanuals.com. All Manuals Search And Download.
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
21
22
int
int count;
VST_BOOLEAN
i;
rc =
VSE_FALSE;
23
24
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
25
26
27
28
29
30
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
capacity;
highmark;
lowmark;
migpri;
VST_PRIORITY
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
31
32
33
VST_COMP_TYPE
CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
VST_COMMAND_HANDLE
34
35
36
37
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
38
39
/* get parameters from user */
printf(“Modify archive media class
parameters \n” );
40
printf(“The archive media class must
exist. \n”);
41
42
printf(“Enter Archive Name ==> “ );
gets( archive );
2-88
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
printf(“Enter Media Class Name ==> “
);
44
45
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
46
47
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==>“ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
48
49
50
51
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
52
53
54
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
55
56
{
printf(“Enter Target Archive ==> “
);
57
58
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
59
60
migpri = atoi(gets(input));
/* These only need to be set when
*/
61
62
/* migration is used. */
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
63
64
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
65
66
67
68
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
69
70
count = atoi(gets(input));
if (count > 0)
601355 Rev A
API Functions
2-89
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
71
72
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
73
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
74
75
76
77
78
79
80
81
82
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
83
84
85
CompID[3] = 0;
comphandle =
VS_Component_Create();
86
VS_Component_SetFields(comphandle
,
87
88
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
89
90
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
}
91
92
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
93
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
94
95
VSID_ENDFIELD);
}
2-90
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
96
97
/* create the command handle */
/* Note that the command handle is
not */
98
99
/* destroyed in this routine, */
/* but in vst_dispatch */
100 /* when final status is received. */
101 cmd = VS_Command_Create();
102 if (cmd != (VST_COMMAND_HANDLE )NULL)
103 {
104
105
106
107
108
109
110
/* 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
,
111
112
113
114
115
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
116
VSID_ENDFIELD);
117 }
118 return ( rc );
119}
Notes
None
601355 Rev A
API Functions
2-91
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Component_Destroy(l),
VS_Component_GetFields(l),
VS_Component_SetFields(l),
VS_Error_GetFields(l)
2-92
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Component_Destroydeallocates a component handle
that was allocated with VS_Component_Create. A
component handle is used to pass component information to
and from VolServ.
VS_
Component_
Destroy
VST_BOOLEAN VS_Component_Destroy
( VST_COMPONENT_HANDLE handle )
Synopsis
Arguments
• handle= Component handle to be destroyed.
Return Values
VS_Component_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_component_handle
4 *
5 * PURPOSE:
6 * This function tests the component
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
601355 Rev A
API Functions
2-93
Download from Www.Somanuals.com. All Manuals Search And Download.
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
20
21
22
23
24
VST_COMPONENT_HANDLE
VST_COMP_TYPE
VST_COMPONENT_ID
comph;
comptype;
id;
comph = VS_Component_Create();
if (comph != (VST_COMPONENT_HANDLE)
NULL)
25
26
{
printf(“enter component type
==>”);
27
28
comptype = atoi(gets(input));
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
31
32
gets(input);
VS_Component_SetFields(comph,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
After VS_Component_Destroyhas 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)
601355 Rev A
API Functions
2-95
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Component_GetFieldsretrieves information from a
component handle. The component handle is used to pass
component information to and from VolServ.
VS_
Component_
GetFields
VST_BOOLEAN VS_Component_GetFields
( VST_COMPONENT_HANDLE handle,
“…”,
Synopsis
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.
Pointer to the type of this component.
VSID_COMP_TYPE (VST_COMP_TYPE *)
2-96
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Component_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_component
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a component handle.
8 *
9 * PARAMETERS:
10 * h : the component handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_component(VST_COMPONENT
_HANDLE h)
15 #else
16
17
void vst_print_component(h)
VST_COMPONENT_HANDLE h;
18 #endif
19 {
20
VST_COMP_TYPE
CompType;
601355 Rev A
API Functions
2-97
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
VST_COMPONENT_ID CompID;
int i;
VS_Component_GetFields(h,
VSID_COMP_TYPE,
&CompType,
26
VSID_COMP_ID,
CompID,
27
28
VSID_ENDFIELD);
printf(“******* Component Handle
*******\n”);
29
printf(“Component Type = %d\n”,
CompType);
30
31
printf(“Component ID = “);
for (i = 0; i < VSD_MAX_COMPONENT_ID;
i++)
32
{
33
printf(“%d”, CompID[i]);
34
if (i < VSD_MAX_COMPONENT_ID - 1)
35
{
36
printf(“, “);
37
}
38
}
39
printf(“\n”);
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
vsapi(l),
VS_Component_Create(l),
VS_Component_Destroy(l),
VS_Component_SetFields(l),
2-98
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
•
•
•
•
VS_Error_GetFields(l),
VS_Table_Create(l),
VS_Table_SetFields(l),
VS_TableAddEntry(l),
VSCMD_CreateArchiveMediaClass(l),
VSCMD_ModifyArchiveMediaClass(l)
601355 Rev A
API Functions
2-99
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Component_SetFieldssets 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.
VS_
Component_
SetFields
VST_BOOLEAN VS_Component_SetFields
( VST_COMPONENT_HANDLE handle,
“…”,
Synopsis
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_TYPEvalues are enumerated in
the vs_types.h file.
2-100
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Component_SetFieldsreturns:
• 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.
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 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modarchivemediaclass_execute(
void)
15 #else
601355 Rev A
API Functions
2-101
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16
VST_BOOLEAN
vst_modarchivemediaclass_execute(
)
17 #endif
18 {
19
20
21
int
int count;
VST_BOOLEAN
i;
rc =
VSE_FALSE;
22
23
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
24
25
26
27
28
29
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
capacity;
highmark;
lowmark;
migpri;
VST_PRIORITY
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
30
31
32
VST_COMP_TYPE
CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
VST_COMMAND_HANDLE
33
34
35
36
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Modify Archive Media
Class parameters ***\n” );
printf(“*** The archive media class
must exist. ***\n”);
39
40
41
42
printf(“Enter Archive Name ==> “ );
gets( archive ); archive media class
printf(“Enter Media Class Name ==> “
);
43
44
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
2-102
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
46
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==>“ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
47
48
49
50
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
51
52
53
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
54
55
{
printf(“Enter Target Archive ==> “
);
56
57
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
58
59
migpri = atoi(gets(input));
/* These only need to be set when
migration */
60
61
/* is used. */
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
62
63
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
64
65
66
67
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
68
69
70
71
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
601355 Rev A
API Functions
2-103
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
72
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
73
74
75
76
77
78
79
80
81
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
82
83
84
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
VS_Component_SetFields(comphandle
,
86
87
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
88
89
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
}
90
91
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
92
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
93
94
95
96
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
2-104
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
97
98
99
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
100 if (cmd != (VST_COMMAND_HANDLE )NULL)
101 {
102
103
104
105
106
107
/* 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 */
108
109
/* default parameters. */
rc =
VSCMD_ModifyArchiveMediaClass(cmd
,
110
111
112
113
114
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
115
VSID_ENDFIELD);
116 }
117 return ( rc );
118}
601355 Rev A
API Functions
2-105
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
•
•
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)
2-106
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Connect_Createallocates a VolServ API connect
handle. A connect handle is used to pass connect information to
and from VolServ.
VS_Connect_
Create
VST_CONNECT_HANDLE VS_Connect_Create ( void )
Synopsis
Arguments
None
Return Values
VS_Connect_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connect_handle
4 *
5 * PURPOSE:
6 * This function tests a connect handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_connect_handle(void)
14 #else
15
VST_BOOLEAN vst_connect_handle()
16 #endif
17 {
601355 Rev A
API Functions
2-107
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
18
19
20
21
22
23
24
VST_CONNECT_HANDLE h;
VST_BOOLEAN
rc = VSE_FALSE;
VST_ENTERPRISE_ID
VST_SOCKADDR_IN
EnterpriseID;
SocketAddress;
VST_PROGRAM_NUMBER ProgramNumber;
VST_VERSION_NUMBER VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
25
26
27
28
29
30
31
32
VST_PROTOCOL Protocol;
/* create the handle */
h = VS_Connect_Create();
if (h != (VST_CONNECT_HANDLE) NULL)
{
/* get values from user */
printf(“*** connect handle
***\n”);
33
printf(“Enter enterprise ID ==>
“);
34
35
EnterpriseID = atol(gets(input));
printf(“Enter Internet sin_port
value ==> “);
36
37
38
SocketAddress.sin_port = (short)
atoi(gets(input));;
printf(“Enter Internet sin_family
value ==> “);
SocketAddress.sin_family =
(short)
atoi(gets(input));
39
40
41
42
43
44
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));
2-108
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
46
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,
47
48
49
50
51
52
53
54
55
56
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
57
58
VSID_ENDFIELD);
if (rc)
59
{
60
61
vst_print_connect(h);
}
62
VS_Connect_Destroy(h);
63
}
64
return(rc);
65 }
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Connect_Destroydeallocates a connect handle that
was allocated with VS_Connect_Create. A connect handle
is used to pass connect information to and from VolServ.
VS_Connect_
Destroy
VST_BOOLEAN VS_Connect_Destroy
(VST_CONNECT_HANDLE handle)
Synopsis
Arguments
• handle= Connect handle to be destroyed.
Return Values
VS_Connect_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connect_handle
4 *
5 * PURPOSE:
6 * This function tests a connect handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
2-110
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
12 #ifdef ANSI_C
13 VST_BOOLEAN vst_connect_handle(void)
14 #else
15
VST_BOOLEAN vst_connect_handle()
16 #endif
17 {
18
19
20
21
22
23
24
VST_CONNECT_HANDLE h;
VST_BOOLEAN
VST_ENTERPRISE_ID
VST_SOCKADDR_IN
rc = VSE_FALSE;
EnterpriseID;
SocketAddress;
VST_PROGRAM_NUMBER ProgramNumber;
VST_VERSION_NUMBER VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
25
26
27
28
29
30
31
32
VST_PROTOCOL Protocol;
/* create the handle */
h = VS_Connect_Create();
if (h != (VST_CONNECT_HANDLE) NULL)
{
/* get values from user */
printf(“*** connect handle
***\n”);
33
printf(“Enter enterprise ID ==>
“);
34
35
EnterpriseID = atol(gets(input));
printf(“Enter Internet sin_port
value ==> “);
36
37
38
SocketAddress.sin_port = (short)
atoi(gets(input));;
printf(“Enter Internet sin_family
value ==> “);
SocketAddress.sin_family =
(short)
atoi(gets(input));
39
40
41
printf(“Enter Internet sin_addr
value ==> “);
SocketAddress.sin_addr =
atol(gets(input));
printf(“Enter program number ==>
“);
601355 Rev A
API Functions
2-111
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
43
44
45
46
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,
47
48
49
50
51
52
53
54
55
56
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
57
VSID_ENDFIELD);
58
if (rc)
59
{
60
61
vst_print_connect(h);
}
62
VS_Connect_Destroy(h);
63
}
64
return(rc);
65 }
Notes
After VS_Connect_Destroyhas been called for a connect
handle, that handle is no longer valid and should not be used.
See Also
•
vsapi(l),
2-112
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
•
•
VS_Connect_Create(l),
VS_Connect_GetFields(l),
VS_Connect_SetFields(l),
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-113
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Connect_GetFields retrieves information associated
with a connect handle. A connect handle is used to pass connect
information to and from VolServ.
VS_Connect_
GetFields
VST_BOOLEAN VS_Connect_GetFields
(VST_CONNECT_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_PROTOCOLvalues 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
VS_Connect_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_connect
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a connect handle.
8 *
9 * PARAMETERS:
601355 Rev A
API Functions
2-115
Download from Www.Somanuals.com. All Manuals Search And Download.
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
17
void vst_print_connect(h)
VST_CONNECT_HANDLE h;
18 #endif
19 {
20
21
22
23
24
VST_ENTERPRISE_ID
EnterpriseID;
VST_SOCKADDR_IN
SocketAddress;
VST_PROGRAM_NUMBER
ProgramNumber;
VST_VERSION_NUMBER
VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
VST_PROTOCOL
25
26
27
28
Protocol;
VS_Connect_GetFields(h,
VSID_ENTERPRISE_ID,
&EnterpriseID,
29
30
31
32
33
VSID_SOCKADDR_IN,
&SocketAddress,
VSID_PROGRAM_NUMBER,
&ProgramNumber,
VSID_VERSION_NUMBER,
&VersionNumber,
VSID_PROCEDURE_NUMBER,
&ProcedureNumber,
VSID_PROTOCOL,
&Protocol,
34
35
36
VSID_ENDFIELD);
printf(“******* Connect Handle
*******\n”);
2-116
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
37
38
39
40
41
42
43
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);
44
printf(“Protocol = %d\n”, Protocol);
45 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
•
•
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)
601355 Rev A
API Functions
2-117
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Connect_SetFieldssets the value of one or more
fields in a connect handle. A connect handle is used to pass
connect information to and from VolServ.
VS_Connect_
SetFields
VST_BOOLEAN VS_Connect_SetFields
(VST_CONNECT_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol to use to transmit status
messages to this client. Valid
VSID_PROTOCOLvalues 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
VS_Connect_SetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connect_handle
4 *
5 * PURPOSE:
6 * This function tests a connect handle.
601355 Rev A
API Functions
2-119
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_connect_handle(void)
14 #else
15
VST_BOOLEAN vst_connect_handle()
16 #endif
17 {
18
19
VST_CONNECT_HANDLE
VST_BOOLEAN
h;
rc =
VSE_FALSE;
20
21
22
23
24
VST_ENTERPRISE_ID
EnterpriseID;
VST_SOCKADDR_IN
SocketAddress;
VST_PROGRAM_NUMBER
ProgramNumber;
VST_VERSION_NUMBER
VersionNumber;
VST_PROCEDURE_NUMBER
ProcedureNumber;
VST_PROTOCOL Protocol;
25
26
27
28
29
30
31
32
/* create the handle */
h = VS_Connect_Create();
if (h != (VST_CONNECT_HANDLE) NULL)
{
/* get values from user */
printf(“*** connect handle
***\n”);
33
printf(“Enter enterprise ID ==>
“);
34
35
EnterpriseID = atol(gets(input));
printf(“Enter Internet sin_port
value ==> “);
36
SocketAddress.sin_port = (short)
atoi(gets(input));;
2-120
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
37
38
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 ==>
“);
39
40
41
42
43
44
45
46
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,
47
48
49
50
51
52
53
54
55
56
VSID_SOCKADDR_IN,
SocketAddress,
VSID_PROGRAM_NUMBER,
ProgramNumber,
VSID_VERSION_NUMBER,
VersionNumber,
VSID_PROCEDURE_NUMBER,
ProcedureNumber,
VSID_PROTOCOL,
Protocol,
57
58
59
60
61
VSID_ENDFIELD);
if (rc)
{
vst_print_connect(h);
}
601355 Rev A
API Functions
2-121
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
62
63
64
VS_Connect_Destroy(h);
return(rc);
}
65 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
•
•
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)
2-122
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Criteria_Createallocates a VolServ API criteria
handle. A criteria handle is used to pass criteria information to
and from VolServ.
VS_Criteria_
Create
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 )
Synopsis
Arguments
None
Return Values
VS_Criteria_Createreturns:
•
•
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.
601355 Rev A
API Functions
2-123
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
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 * PARAMETERS:
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
20
21
22
23
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
24
25
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
26
27
28
29
30
31
32
33
34
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
2-124
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
35
36
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
37
38
39
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
40
41
42
}
/* populate the criteria group with
criteria (upto 5) */
43
printf ( “Enter number of Criteria in
group ==> “ );
44
45
46
47
48
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
*/
49
50
51
52
/* stat field */
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
53
54
55
56
57
58
59
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
60
61
62
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
63
64
65
sort = atoi(gets(input));
/* set the criteria parameters */
601355 Rev A
API Functions
2-125
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
66
VS_Criteria_SetFields (
criteriah,
67
68
VSID_FIELD, field,
VSID_MOUNT_CRITERIA_ORDER, sort
VSID_ENDFIELD );
69
70
71
/* populate the critera with
expressions */
72
73
/* (up to 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
74
75
76
77
78
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for this
criteria */
79
exprh =
VS_Expression_Create();
80
81
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
82
83
{
/* could not allocate memory
for this handle */
84
85
86
87
88
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
89
90
91
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
92
93
94
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
2-126
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
95
96
97
conop = atoi(gets(input));
/* set the expression’s
parameters */
98
VS_Expression_SetFields (
exprh,
99
VSID_MOUNT_CRITERIA_OPT,
relopt,
100
101
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
102
103
104
VSID_ENDFIELD );
/* add the expression to the
criteria */
105
106
VS_Criteria_SetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
107
108
109
110
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
111
112
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,
i, criteriah,
113
VSID_ENDFIELD );
114 }
115
116 /* if it failed, destroy the criteria
group handle */
117 if ( rc == VSE_FALSE )
118 {
119
120
121
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us */
601355 Rev A
API Functions
2-127
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
122
VS_CriteriaGroup_Destroy ( grouph
);
123
124
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
125 }
126
127 return ( grouph );
128}
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Criteria_Destroydeallocates a criteria handle that was
allocated with VS_Criteria_Create. A criteria handle is
used to pass criteria information to and from VolServ.
VS_Criteria_
Destroy
VST_BOOLEAN VS_Criteria_Destroy
( VST_CRITERIA_HANDLE handle )
Synopsis
Arguments
• handle= Criteria handle to be destroyed.
Return Values
VS_Criteria_Destroyreturns:
• 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.
Example
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
601355 Rev A
API Functions
2-129
Download from Www.Somanuals.com. All Manuals Search And Download.
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
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
37
38
39
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
40
41
}
/* populate the criteria group with
criteria */
42
43
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
2-130
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
44
45
46
47
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
48
49
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
50
51
52
53
54
55
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
56
57
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==>“ );
58
59
60
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
61
62
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER,
sort,
63
64
VSID_ENDFIELD );
/* populate the critera with
expressions */
65
66
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
67
68
69
70
/* create an expression for
this criteria */
71
72
exprh =
VS_Expression_Create();
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
601355 Rev A
API Functions
2-131
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
73
74
{
/* could not allocate memory
for this */
/* handle */
75
76
77
78
79
rc = VSE_FALSE;
break;
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
80
81
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
82
83
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
84
85
conop = atoi(gets(input));
/* set the expression’s
parameters */
86
87
88
89
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
90
91
VSID_ENDFIELD );
/* add the expression to the
criteria */
92
93
VS_Criteria_SetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
94
95
96
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
97
2-132
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
98
VSID_CRITERIA_HANDLE_ENTRY,
i, criteriah,
VSID_ENDFIELD );
99
100 }
101 /* if it failed, destroy the criteria
group handle */
102 if ( rc == VSE_FALSE )
103 {
104
105
106
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us, so the only thing that
is really */
107
108
/* needed here is a call to*/
/* VS_CriteriaGroup_Destroy. This
is written*/
109
110
111
/* out the ’long way’ for
documentation*/
/* purposes. First, get the number
of criteria */
VS_CriteriaGroup_GetFields(grouph
,
112
VSID_NUMBER_ENTRIES,
&numcrit,
113
114
115
116
117
VSID_ENDFIELD);
for (i = 0; i < numcrit; i++)
{
/* get a criteria handle */
VS_CriteriaGroup_GetFields(grouph
,
118
VSID_CRITERIA_HANDLE_ENTRY,
i,&criteriah,
119
120
VSID_ENDFIELD);
/* get the number of
expressions */
121
122
VS_Criteria_GetFields(criteriah,
VSID_NUMBER_ENTRIES,
&numexpr,
601355 Rev A
API Functions
2-133
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
123
124
125
126
VSID_ENDFIELD);
for (j = 0; j < numexpr; j++)
{
/* get the expressions from
the criteria */
127
128
VS_Criteria_GetFields(criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
129
130
VSID_ENDFIELD);
/* destroy the expression
handle */
131
132
133
134
135
/*
VS_Expression_Destroy(exprh);*/
/* let criteria handle know
that the */
/* expression handle has
been destroyed */
VS_Criteria_SetFields(criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
NULL,
136
137
138
VSID_ENDFIELD);
}
/* now, destroy Criteria
handle. */
139
140
141
VS_Criteria_Destroy(criteriah);
/* let the criteria group
handle know */
/* that Criteria handle has
been */
142
143
/* destroyed. */
VS_CriteriaGroup_SetFields(grouph
,
144
145
VSID_CRITERIA_HANDLE_ENTRY, i,
NULL,
VSID_ENDFIELD);
2-134
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
146
147
}
/* finally, destroy the criteria
group handle. */
148
VS_CriteriaGroup_Destroy ( grouph
);
149
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
150 }
151 return ( grouph );
152}
Notes
After VS_Criteria_Destroyhas 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
API Functions
2-135
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Criteria_GetFieldsretrieves information
associated with a criteria handle. A criteria group handle is used
to pass criteria information to and from VolServ.
VS_Criteria_
GetFields
VST_BOOLEAN VS_Criteria_GetFields
( VST_CRITERIA_HANDLE handle,
“…”,
Synopsis
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 *)
VSID_FIELD (VST_COUNT *)
Pointer to the number of expression handles
within this criteria handle.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
(VST_EXPRESSION_HANDLE *)
Pointer to the expression handle and its place
in the criteria.
Return Values
VS_Criteria_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_criteria_group
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a criteria group handle.
8 *
9 * PARAMETERS:
10 * grouph : the mount handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
601355 Rev A
API Functions
2-137
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14
void
vst_print_criteria_group
(VST_CRITERIAGROUP_HANDLE grouph)
15 #else
16
void
vst_print_criteria_group(grouph)
VST_CRITERIAGROUP_HANDLE grouph;
17
18 #endif
19 {
20
21
int
int
i, j;
numcrit=
0;
0;
22
int
numexpr=
23
24
VST_EXPRESSION_HANDLE
exprh =
(VST_EXPRESSION_HANDLE) NULL;
VST_CRITERIA_HANDLE
25
criteriah =
(VST_CRITERIA_HANDLE) NULL;
26
27
28
29
30
31
32
33
VST_COUNT
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
field;
value;
relopt;
conop;
/* get the number of criteria within
this group */
34
35
VS_CriteriaGroup_GetFields ( grouph,
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
36
37
38
39
40
for ( i = 0 ; i < numcrit ; i++ )
{
/* get the criteria to print */
VS_CriteriaGroup_GetFields (
grouph,
41
42
VSID_CRITERIA_HANDLE_ENTRY,i,
&criteriah,
VSID_ENDFIELD );
2-138
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
45
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
46
47
48
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
49
50
51
VSID_ENDFIELD );
printf ( “*** Criteria # %d
***\n”, i );
52
53
54
printf ( “ Field Index ==> %d\n”,
field );
printf ( “ Mount Criteria Order
==> %d\n”, sort );
printf ( “Number of Expressions
==> %d\n”, numexpr );
55
56
57
58
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
59
60
VS_Criteria_GetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
61
62
63
VSID_ENDFIELD );
/* get the expression’s
parameters */
64
65
66
67
VS_Expression_GetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
601355 Rev A
API Functions
2-139
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
68
69
70
VSID_ENDFIELD );
printf ( “*** Expression # %d
***\n”, j );
71
72
73
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value );
printf ( “ Connective
Operation ==> %d\n”, conop );
}
74
75
}
76
77
return;
78 }
Notes
The VSID_EXPRESSION_HANDLE_ENTRYparameter 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
•
•
•
•
•
•
vsapi(l),
VS_Criteria_Create(l),
VS_Criteria_Destroy(l),
VS_Criteria_SetFields(l),
VS_Error_Getfields(l),
VS_Expression_Create(l),
2-140
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-141
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Criteria_SetFieldssets the value of one or more
field in a criteria handle. A criteria handle is used to pass
criteria information to and from VolServ.
VS_Criteria_
SetFields
VST_BOOLEAN VS_Criteria_SetFields
( VST_CRITERIA_HANDLE handle,
“…”,
Synopsis
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)
(VST_EXPRESSION_HANDLE)
Expression handle and its place in the criteria.
Expression handle for the criteria.
2-142
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Criteria_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
criteria handle.
• VSE_ERR_BADSIZE- The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
• VSE_ERR_NULLHANDLE- Specified handle was a null
pointer.
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
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
8 * user input.
9 *
10 * PARAMETERS:
11 * none
12 *
13 ****************************************
*********/
14 #ifdef ANSI_C
601355 Rev A
API Functions
2-143
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
15
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
16 #else
17
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
18 #endif
19 {
20
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
37
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
39
40
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
41
42
43
/* populate the criteria group with
criteria */
44
45
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
46
47
numcrit = atoi(gets(input));
2-144
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
48
49
50
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
51
52
53
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
54
55
56
57
58
59
60
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
61
62
63
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
64
65
66
67
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
68
69
VSID_FIELD, field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
70
71
72
73
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
74
75
76
77
78
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
601355 Rev A
API Functions
2-145
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
79
exprh =
VS_Expression_Create();
80
81
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
82
83
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
84
85
86
87
88
89
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
90
91
92
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
93
94
95
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
96
97
98
conop = atoi(gets(input));
/* set the expression’s
parameters */
99
VS_Expression_SetFields (
exprh,
100
101
102
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
103
104
105
VSID_ENDFIELD );
/* add the expression to the
criteria */
2-146
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
106
107
VS_Criteria_SetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
108
109
110
111
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
112
113
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
114
VSID_ENDFIELD );
115 }
116
117 /* if it failed, destroy the criteria
group handle */
118 if ( rc == VSE_FALSE )
119 {
120
/* criteria group will destroy any
*/
121
/* criteria and their expressions
*/
122
123
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
124
125
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
126 }
127
128 return ( grouph );
129}
601355 Rev A
API Functions
2-147
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
The VSID_EXPRESSION_HANDLE_ENTRYparameter 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
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
2-148
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_CriteriaGroup_Createallocates a VolServ API
criteria group handle. A criteria group handle is used to pass
criteria group information to and from VolServ.
VS_
CriteriaGroup
_Create
VST_CRITERIAGROUP_HANDLE
VS_CriteriaGroup_Create
( void )
Synopsis
Arguments
None
Return Values
VS_CriteriaGroup_Createreturns:
•
•
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.
Example
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 *
601355 Rev A
API Functions
2-149
Download from Www.Somanuals.com. All Manuals Search And Download.
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
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
37
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
39
40
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
41
42
43
/* populate the criteria group with
criteria */
44
/* (upto 5) */
2-150
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
printf ( “Enter number of Criteria in
group ==> “ );
46
47
48
49
50
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
51
52
53
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
54
55
56
57
58
59
60
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
61
62
63
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
64
65
66
67
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
68
69
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
70
71
72
/* populate the critera with
expressions */
73
74
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
75
601355 Rev A
API Functions
2-151
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
76
77
78
79
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
80
exprh =
VS_Expression_Create();
81
82
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
83
84
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
85
86
87
88
89
90
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
91
92
93
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
94
95
96
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
97
98
99
conop = atoi(gets(input));
/* set the expression’s
parameters */
100
101
102
103
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
2-152
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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,
109
110
111
112
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
113
114
115
VSID_ENDFIELD );
116 }
117
118 /* if it failed, destroy the criteria
group handle */
119 if ( rc == VSE_FALSE )
120 {
121
/* criteria group will destroy any
*/
122
/* criteria and their expressions
*/
123
124
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
127 }
128
129 return ( grouph );
130}
601355 Rev A
API Functions
2-153
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
2-154
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_CriteriaGroup_Destroydeallocates 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.
VS_
CriteriaGroup
_Destroy
VST_BOOLEAN VS_CriteriaGroup_Destroy
( VST_CRITERIAGROUP_HANDLE handle )
Synopsis
Arguments
• handle = Criteria group handle to be destroyed.
Return Values
VS_CriteriaGroup_Destroyreturns 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.
Example
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
8 * user input.
601355 Rev A
API Functions
2-155
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
9 *
10 * PARAMETERS:
11 * none
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
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
37
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
39
40
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
41
42
2-156
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
/* populate the criteria group with
criteria */
44
45
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
46
47
48
49
50
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
51
52
53
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
54
55
56
57
58
59
60
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
61
62
63
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
64
65
66
67
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
68
69
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
70
71
72
/* populate the critera with
expressions */
73
/* (upto 4) */
601355 Rev A
API Functions
2-157
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
75
76
77
78
79
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
80
exprh =
VS_Expression_Create();
81
82
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
83
84
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
85
86
87
88
89
90
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
91
92
93
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
94
95
96
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
97
98
99
conop = atoi(gets(input));
/* set the expression’s
parameters */
100
101
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
2-158
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
102
103
VSID_CONNECTIVE_OP,
conop,
value,
VSID_MEDIA_STAT_VALUE,
VSID_ENDFIELD );
104
105
106
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
107
108
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
109
110
111
112
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
113
114
115
VSID_ENDFIELD );
116 }
117
118 /* if it failed, destroy the criteria
group handle */
119 if ( rc == VSE_FALSE )
120 {
121
/* criteria group will destroy any
*/
122
/* criteria and their expressions
*/
123
124
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
127 }
128
129 return ( grouph );
601355 Rev A
API Functions
2-159
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
130}
Notes
After VS_CriteriaGroup_Destroyhas 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
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
2-160
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_CriteriaGroup_GetFieldsretrieves information
associated with a criteria group handle. A criteria group handle
is used to pass criteria group information to and from VolServ.
VS_
CriteriaGroup
_GetFields
VST_BOOLEAN VS_CriteriaGroup_GetFields
(VST_CRITERIAGROUP_HANDLE handle,
“…”,
Synopsis
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 *)
VSID_CRITERIA_HANDLE_ENTRY (int)
(VST_CRITERIA_HANDLE *)
Pointer to the number of criteria handles within
this criteria group handle.
Criteria handle and its place in the criteria
group.
Pointer to Criteria handle for this group.
Return Values
VS_CriteriaGroup_GetFieldsreturns:
601355 Rev A
API Functions
2-161
Download from Www.Somanuals.com. All Manuals Search And Download.
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
criteria group handle.
• VSE_ERR_NULLHANDLE- Specified handle was a null
pointer.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_criteria_group
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a criteria group handle.
8 *
9 * PARAMETERS:
10 * grouph : the mount handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_criteria_group
(VST_CRITERIAGROUP_HANDLE grouph)
15 #else
16
void
vst_print_criteria_group(grouph)
VST_CRITERIAGROUP_HANDLE grouph;
17
18 #endif
19 {
20
int
i, j;
2-162
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
int
int
numcrit=
numexpr=
0;
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
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* get the number of criteria within
this group */
34
35
36
VS_CriteriaGroup_GetFields ( grouph,
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
37
38
for ( i = 0 ; i < numcrit ; i++ )
39 {
40
41
/* get the criteria to print */
VS_CriteriaGroup_GetFields (
grouph,
42
VSID_CRITERIA_HANDLE_ENTRY,i,
&criteriah,
43
44
45
46
VSID_ENDFIELD );
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
47
48
49
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
50
51
VSID_ENDFIELD );
601355 Rev A
API Functions
2-163
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
52
53
54
55
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 );
56
57
58
59
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
60
61
VS_Criteria_GetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
62
63
64
VSID_ENDFIELD );
/* get the expression’s
parameters */
65
66
67
68
VS_Expression_GetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
69
70
71
VSID_ENDFIELD );
printf ( “*** Expression # %d
***\n”, j );
72
73
74
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value);
printf ( “ Connective
Operation ==> %d\n”, conop);
}
75
76
}
2-164
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
77
78
return;
79 }
Notes
The VSID_CRITERIA_HANDLE_ENTRYparameter 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.
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_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 Functions
2-165
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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.
VS_
CriteriaGroup
_SetFields
VST_BOOLEAN VS_CriteriaGroup_SetFields
( VST_CRITERIAGROUP_HANDLE handle,
“…”,
Synopsis
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)
(VST_CRITERIA_HANDLE)
Criteria handle and its place in the criteria
group.
Criteria handle for this group.
2-166
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_CriteriaGroup_SetFieldsreturns:
• 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.
Example
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 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
601355 Rev A
API Functions
2-167
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria(void)
15 #else
16
VST_CRITERIAGROUP_HANDLE
vst_create_mount_criteria()
17 #endif
18 {
19
20
21
22
23
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
24
25
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
26
27
28
29
30
31
32
33
34
35
36
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
37
38
39
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
40
41
42
/* populate the criteria group with
criteria */
43
44
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
45
46
numcrit = atoi(gets(input));
2-168
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
47
48
49
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
50
51
52
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
53
54
55
56
57
58
59
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
60
61
62
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
63
64
65
66
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
67
68
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
69
70
71
/* populate the criteria with
expressions */
72
73
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
74
75
76
77
for ( j = 0 ; j < numexpr ; j++ )
{
601355 Rev A
API Functions
2-169
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
78
79
/* create an expression for
this criteria */
exprh =
VS_Expression_Create();
80
81
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
82
83
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
84
85
86
87
88
89
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
90
91
92
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
93
94
95
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
96
97
98
conop = atoi(gets(input));
/* set the expression’s
parameters */
99
VS_Expression_SetFields (
exprh,
100
101
102
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
103
104
VSID_ENDFIELD );
2-170
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
105
106
107
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
108
109
110
111
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
112
113
114
VSID_ENDFIELD );
115 }
116
117 /* if it failed, destroy the criteria
group handle */
118 if ( rc == VSE_FALSE )
119 {
120
/* criteria group will destroy any
*/
121
/* criteria and their expressions
*/
122
123
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
124
125
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
126 }
127
128 return ( grouph );
129}
601355 Rev A
API Functions
2-171
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
The VSID_CRITERIA_HANDLE_ENTRYparameter 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
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
2-172
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VS_Drive_Createfunction allocates a VolServ API
drive handle. A drive handle is used to pass drive information to
and from VolServ.
VS_Drive_
Create
VST_DRIVE_HANDLE VS_Drive_Create ( void )
Synopsis
Arguments
None
Return Values
VS_Drive_Createreturns:
•
•
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.
Example
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
13
VST_BOOLEAN vst_drive_handle(void)
14 #else
15
VST_BOOLEAN vst_drive_handle()
16 #endif
17 {
601355 Rev A
API Functions
2-173
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VST_BOOLEAN
rc = VSE_FALSE;
h;
DriveID;
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
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
VST_USAGE
VST_COUNT
VST_MEDIA_ID
/* 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
==> “);
42
43
gets(ArchiveName);
printf(“Enter Component State ==>
“);
44
ComponentState =
atoi(gets(input));
45
46
47
48
49
50
51
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
==> “);
52
53
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
54
TotalTime = atoi(gets(input));
2-174
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
55
56
57
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
58
59
60
61
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
62
63
64
65
66
67
68
69
70
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)
72
73
74
{
75
76
vst_print_drive(h);
}
77
VS_Drive_Destroy(h);
78
}
79
return(rc);
80 }
Notes
None
601355 Rev A
API Functions
2-175
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Drive_Destroy(l),
VS_Drive_GetFields(l),
VS_Drive_SetFields(l),
VS_Error_GetFields(l)
2-176
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VS_Drive_Destroydeallocates a drive handle that was
allocated with VS_Drive_Create. A drive handle is used to
pass drive information to and from VolServ.
VS_Drive_
Destroy
VST_BOOLEAN VS_Drive_Destroy
( VST_DRIVE_HANDLE handle )
Synopsis
Arguments
• handle= Drive handle to be destroyed.
Return Values
VS_Drive_Destroyreturns:
• 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.
Example
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
601355 Rev A
API Functions
2-177
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
13
VST_BOOLEAN vst_drive_handle(void)
14 #else
15
VST_BOOLEAN vst_drive_handle()
16 #endif
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
VST_BOOLEAN
rc = VSE_FALSE;
h;
DriveID;
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
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
VST_USAGE
VST_COUNT
VST_MEDIA_ID
/* 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
==> “);
42
43
gets(ArchiveName);
printf(“Enter Component State ==>
“);
44
ComponentState =
atoi(gets(input));
45
46
47
48
49
50
printf(“Enter Assignment ==> “);
Assignment = atoi(gets(input));
printf(“Enter Mount State ==> “);
MountState = atoi(gets(input));
printf(“Enter Usage Count ==> “);
UsageCount = atoi(gets(input));
2-178
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
51
printf(“Enter Current Usage Time
==> “);
52
53
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
54
55
56
57
TotalTime = atoi(gets(input));
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
58
59
60
61
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
62
63
64
65
66
67
68
69
70
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)
72
73
74
75
76
77
78
{
vst_print_drive(h);
}
VS_Drive_Destroy(h);
}
601355 Rev A
API Functions
2-179
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
79
return(rc);
80 }
Notes
After VS_Drive_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Drive_GetFieldsretrieves information associated
with a drive handle. A drive handle is used to pass drive
information to and from VolServ.
VS_Drive_Get
Fields
VST_BOOLEAN VS_Drive_GetFields
( VST_DRIVE_HANDLE handle,
“…”,
Synopsis
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_ASSIGNMENTvalues are
enumerated in the vs_types.hfile.
601355 Rev A
API Functions
2-181
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_COMP_STATE (VST_COMP_STATE *)
Pointer to the operational state of this drive.
Valid VSID_COMP_STATEvalues are
enumerated in the vs_types.hfile.
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_TYPEvalues are enumerated
in the vs_types.hfile.
VSID_ERROR_COUNT (VST_COUNT *)
VSID_MEDIA_ID (VST_MEDIA_ID)
Pointer to the error count of the drive.
If the VSID_MOUNT_STATEof this drive is
VSE_MOUNT_MOUNTED, identifier of the
medium mounted on this drive.
VSID_MEDIA_TYPE_ENTRY (int)
(VST_MEDIATYPE_HANDLE *)
Index of a specific media type handle in the
media type handle table.
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_STATEvalues are enumerated
in the vs_types.hfile.
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.
Pointer to the total usage time of the drive.
VSID_TOTAL_USAGE_TIME
(VST_USAGE *)
Return Values
VS_Drive_GetFieldsreturns:
2-182
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_drive
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a drive handle.
8 *
9 * PARAMETERS:
10 * h : the drive handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_drive(VST_DRIVE_HANDLE
h)
15 #else
16
17
void vst_print_drive(h)
VST_DRIVE_HANDLE h;
18 #endif
19 {
601355 Rev A
API Functions
2-183
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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
DriveID;
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
CurrentTime;
TotalTime;
ErrorCount;
MountedMediaID;
* MediaType;
MediaTypeTable;
i;
int
n;
VS_Drive_GetFields(h,
VSID_DRIVE_ID,
&DriveID,
38
39
40
41
42
43
44
45
46
47
48
49
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);
2-184
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
50
51
52
53
54
55
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);
56
57
printf(“Error Count = %d\n”,
ErrorCount );
printf(“MediaID =
%s\n”,MountedMediaID);
58
59
/* DrivePoolQuery Doesn’t use this
Field */
60
if (MediaTypeTable !=
(VST_TABLE_HANDLE)NULL)
{
61
62
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
,
68
VSID_TABLE_ENTRY, i,
&MediaType,
69
70
VSID_ENDFIELD);
printf(“MediaType Entry #%d =
%s\n”,i,MediaType);
71
72
}
}
73 }
601355 Rev A
API Functions
2-185
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
VolServ may place a drive in the VSE_COMP_UNAVAILstate
when a parent component goes off-line.
The VSID_MEDIA_TYPE_ENTRYparameter 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
•
•
•
•
•
•
•
•
•
•
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)
2-186
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Drive_SetFieldssets the value of one or more fields
in a drive handle. A drive handle is used to pass information to
and from VolServ.
VS_Drive_Set
Fields
VST_BOOLEAN VS_Drive_SetFields
( VST_DRIVE_HANDLE handle,
“…”,
Synopsis
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_ASSIGNMENTvalues are enumerated
in the vs_type.h file.
601355 Rev A
API Functions
2-187
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_COMP_STATE (VST_COMP_STATE)
Operational state of this archive. Valid
VSID_COMP_STATEvalues 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)
VSID_MEDIA_ID (VST_MEDIA_ID)
Error count of the drive.
If the VSID_MOUNT_STATEof 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_STATEvalues are enumerated
in the vs_types.hfile.
VSID_USAGE_COUNT
(VST_USAGE_COUNT)
Number of times this drive has been mounted.
VSID_USAGE_TIME (VST_USAGE_TIME)
VSID_TOTAL_USAGE_TIME (VST_USAGE)
Current usage time of the drive.
Total usage time of the drive.
Return Values
VS_Drive_SetFieldsreturns:
• 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.
2-188
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
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
13
VST_BOOLEAN vst_drive_handle(void)
14 #else
15
VST_BOOLEAN vst_drive_handle()
16 #endif
17 {
18
19
20
21
22
23
24
25
26
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
rc = VSE_FALSE;
h;
DriveID;
DriveType;
ArchiveName;
ComponentState;
Assignment;
MountState;
UsageCount;
601355 Rev A
API Functions
2-189
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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
==> “);
42
43
gets(ArchiveName);
printf(“Enter Component State ==>
“);
44
ComponentState =
atoi(gets(input));
45
46
47
48
49
50
51
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
==> “);
52
53
CurrentTime = atoi(gets(input));
printf(“Enter Total Usage Time ==>
“);
54
55
56
57
TotalTime = atoi(gets(input));
printf(“Enter Error Count ==> “);
ErrorCount = atoi(gets(input));
printf(“Enter Mounted Media ID ==>
“);
58
59
60
61
gets(MountedMediaID);
/* set the fields */
rc = VS_Drive_SetFields(h,
VSID_DRIVE_ID,
DriveID,
2-190
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
62
63
64
65
66
67
68
69
70
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)
72
73
74
{
75
vst_print_drive(h);
76
}
77
78
79
VS_Drive_Destroy(h);
return(rc);
}
80 }
Notes
VolServ may place a drive in the VSE_COMP_UNAVAILstate
when a parent component goes off-line. The
VSE_COMP_UNAVAILstate 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
•
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)
2-192
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_DrivePool_Createallocates a VolServ API drive pool
handle. A drive pool handle is used to pass drive pool
information to and from VolServ.
VS_DrivePool
_Create
VST_DRIVEPOOL_HANDLE VS_DrivePool_Create
( void )
Synopsis
Arguments
None
Return Values
VS_DrivePool_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivepool_handle
4 *
5 * PURPOSE:
6 * This function tests a drive pool
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivepool_handle(void)
14 #else
601355 Rev A
API Functions
2-193
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
15
VST_BOOLEAN
vst_drivepool_handle(void)
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
VST_DRIVEPOOL_HANDLE
VST_DRIVE_POOL_NAME
DrivePoolName;
rc =
h;
19
20
21
22
23
24
25
26
27
/* create the handle */
h = VS_DrivePool_Create();
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
{
/* get values from user */
printf(“*** Drive Pool Handle
***\n”);
28
printf(“Enter Drive Pool Name ==>
“);
29
30
31
gets(DrivePoolName);
rc = VS_DrivePool_SetFields(h,
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
None
2-194
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_DrivePool_Destroy(l),
VS_DrivePool_GetFields(l),
VS_DrivePool_SetFields(l),
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-195
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_DrivePool_Destroydeallocates 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.
VS_DrivePool
_Destroy
VST_BOOLEAN VS_DrivePool_Destroy
( VST_DRIVEPOOL_HANDLE handle )
Synopsis
Arguments
• handle= Drive pool handle to be destroyed.
Return Values
VS_DrivePool_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivepool_handle
4 *
5 * PURPOSE:
6 * This function tests a drive pool
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-196
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
VSE_FALSE;
VST_DRIVEPOOL_HANDLE
VST_DRIVE_POOL_NAME
DrivePoolName;
rc =
h;
19
20
21
22
23
24
25
26
27
/* create the handle */
h = VS_DrivePool_Create();
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
{
/* get values from user */
printf(“*** Drive Pool Handle
***\n”);
28
printf(“Enter Drive Pool Name ==>
“);
29
30
31
gets(DrivePoolName);
rc = VS_DrivePool_SetFields(h,
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 }
601355 Rev A
API Functions
2-197
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
After VS_DrivePool_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
VS_DrivePool
_GetFields
VST_BOOLEAN VS_DrivePool_GetFields
( VST_DRIVEPOOL_HANDLE handle,
“…”,
Synopsis
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)
(VST_DRIVE_HANDLE *)
Index of the drive handle to retrieve.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VS_DrivePool_GetFieldsreturns:
• 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.
2-200
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_drivepool
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * in a drive pool handle.
8 *
9 * PARAMETERS:
10 * h : the drive pool handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_drivepool(VST_DRIVEPOOL
_HANDLE h)
15 #else
16
17
void vst_print_drivepool(h)
VST_DRIVEPOOL_HANDLE h;
18 #endif
19 {
20
21
VST_DRIVE_POOL_NAME DrivePoolName;
VST_TABLE_HANDLE
DriveHandleTable;
VST_DRIVE_HANDLE
int
22
23
24
25
26
27
DriveHandle;
i;
n;
int
VS_DrivePool_GetFields(h,
VSID_DRIVEPOOL_NAME,
DrivePoolName,
28
VSID_DRIVE_HANDLE_TABLE
&DriveHandleTable,
29
30
VSID_ENDFIELD);
printf(“DrivePoolName =
%s\n”,DrivePoolName);
/* Get # of entries */
if ( DriveHandleTable !=
(VST_TABLE_HANDLE) NULL )
31
32
601355 Rev A
API Functions
2-201
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
34
{
VS_Table_GetFields(DriveHandleTab
le,
35
36
37
38
39
VSID_NUMBER_ENTRIES,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
&n,
VS_Table_GetFields(DriveHandleTab
le,
40
VSID_TABLE_ENTRY, i,
&DriveHandle,
41
VSID_ENDFIELD);
42
43
vst_print_drive(DriveHandle);
}
44
}
45 }
Notes
The VSID_DRIVE_HANDLE_ENTRYparameter 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
•
•
•
•
•
•
vsapi(l),
VS_DrivePool_Create(l),
VS_DrivePool_Destroy(l),
VS_DrivePool_SetFields(l),
VS_Error_GetFields(l),
VS_Table_GetFields(l)
2-202
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
VSCMD_DrivePoolQuery(l)
601355 Rev A
API Functions
2-203
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_DrivePool_SetFieldssets 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.
VS_DrivePool
_SetFields
VST_BOOLEAN VS_DrivePool_SetFields
( VST_DRIVEPOOL_HANDLE handle,
“…”,
Synopsis
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
VS_DrivePool_SetFieldsreturns:
2-204
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivepool_handle
4 *
5 * PURPOSE:
6 * This function tests a drive pool
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivepool_handle(void)
14 #else
15
VST_BOOLEAN
vst_drivepool_handle(void)
601355 Rev A
API Functions
2-205
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16 #endif
17 {
18
VST_BOOLEAN
rc =
h;
VSE_FALSE;
19
20
VST_DRIVEPOOL_HANDLE
VST_DRIVE_POOL_NAME
DrivePoolName;
21
22
23
24
25
26
27
/* create the handle */
h = VS_DrivePool_Create();
if (h != (VST_DRIVEPOOL_HANDLE) NULL)
{
/* get values from user */
printf(“*** Drive Pool Handle
***\n”);
28
printf(“Enter Drive Pool Name ==>
“);
29
30
31
gets(DrivePoolName);
rc = VS_DrivePool_SetFields(h,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-207
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Error_GetFieldsretrieves information associated
with an error handle. An error handle is used to pass error
information to and from VolServ.
VS_Error_Get
Fields
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.
VST_BOOLEAN VS_Error_GetFields
( VST_ERROR_HANDLE handle,
"…",
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_ERROR_LINE (int *)
Name of the source file where the error
occurred (API internal errors only).
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.
Return Values
VS_Error_GetFieldsreturns
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_error
4 *
5 * PURPOSE:
601355 Rev A
API Functions
2-209
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This function prints out the
information stored in
7 * an error handle.
8 *
9 * PARAMETERS:
10 * h : the error handle to print
11 *
12 ****************************************
**********/
13 #ifdef ANSI_C
14
void
vst_print_error(VST_ERROR_HANDLE
h)
15 #else
16
17
void vst_print_error(h)
VST_ERROR_HANDLE h;
18 #endif
19 {
20
21
22
23
24
25
VST_ERROR_CODE
int
VST_ERROR_FILE
err;
line;
file;
VS_Error_GetFields(h,
VSID_ERROR_CODE,
err,
26
27
VSID_ERROR_LINE,
VSID_ERROR_FILE,
VSID_ENDFIELD);
&line,
file,
28
29
30
printf(“******Error
Handle******\n”);
31
32
33
printf(“Error Code = %s\n”,err);
printf(“Error File = %s\n”,file);
printf(“Error Line = %d\n”,line);
34 }
2-210
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
The VSID_ERROR_OBJECTparameter tells specifically where
(in VolServ or an API object) the error occurred. If its value is
VSE_VOLSERV, the VSID_ERROR_NUMBERparameter matches
a VolServ error code in the VST_VOLERR_CODEerror code. If
not, the VSID_ERROR_NUMBERparameter matches a value in
the VST_ERROR_NUMCODE type.
The VSID_ERROR_FILEand VSID_ERROR_LINEparameters
are valid only for API internal errors (e.g.,
VSE_ERR_OUTOFMEM).
The VSID_ERROR_CODEparameter is a human-readable code
that tells where the error occurred and gives the error number. It
is in the form AAAnnn, where AAAis 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_NUMCODEtype.
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
•
•
•
vsapi(l),
VS_Command_GetFields(l),
VS_Notify_GetFields(l)
601355 Rev A
API Functions
2-211
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Expression_Createallocates a VolServ API
expression handle. An expression handle is used to pass
expression information to and from VolServ.
VS_
Expression_
Create
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.
VST_EXPRESSION_HANDLE VS_Expression_Create
( void )
Synopsis
Arguments
• handle= The expression handle to be created.
VS_Expression_Createreturns:
Return Values
•
•
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.
Example
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
8 * user input.
2-212
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
9 *
10 * PARAMETERS:
11 * none
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
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
37
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
39
40
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
41
42
601355 Rev A
API Functions
2-213
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
/* populate the criteria group with
criteria */
44
45
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
46
47
48
49
50
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
51
52
53
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
54
55
56
57
58
59
60
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
61
62
63
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
64
65
66
67
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
68
69
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
70
71
72
/* populate the critera with
expressions */
73
/* (upto 4) */
2-214
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
75
76
77
78
79
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this criteria */
80
exprh =
VS_Expression_Create();
81
82
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
83
84
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
85
86
87
88
89
90
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
91
92
93
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
94
95
96
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
97
98
99
conop = atoi(gets(input));
/* set the expression’s
parameters */
100
101
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
601355 Rev A
API Functions
2-215
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
102
103
VSID_CONNECTIVE_OP,
VSID_MEDIA_STAT_VALUE,
VSID_ENDFIELD );
conop,
value,
104
105
106
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
107
108
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
109
110
111
112
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
113
114
115
VSID_ENDFIELD );
116 }
117
118 /* if it failed, destroy the criteria
group handle */
119 if ( rc == VSE_FALSE )
120 {
121
/* criteria group will destroy any
*/
122
/* criteria and their expressions
*/
123
124
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
125
126
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
127 }
128
129 return ( grouph );
2-216
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
130}
Notes
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
API Functions
2-217
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Expression_Destroydeallocates an expression
handle that was allocated with VS_Expression_Create.
An expression handle is used to pass expression information to
and from VolServ.
VS_
Expression_
Destroy
VST_BOOLEAN VS_EXPRESSION_DESTROY
(VST_EXPRESSION_HANDLE handle)
Synopsis
Arguments
• handle= The expression handle to be destroyed.
Return Values
VS_Expression_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_criteria
4 *
5 * PURPOSE:
6 * This function creates the mount
criteria group handle
7 * and sets the values in it according to
user input.
8 *
9 * PARAMETERS:
2-218
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
20
21
22
23
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
24
25
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
26
27
28
29
30
31
32
33
34
35
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
36
37
38
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
39
40
}
/* populate the criteria group with
criteria */
41
/* (upto 5) */
601355 Rev A
API Functions
2-219
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
printf ( “Enter number of Criteria in
group ==> “ );
43
44
45
46
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
47
48
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
{
49
50
51
52
53
54
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
55
56
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==>“ );
57
58
59
sort = atoi(gets(input));
/* set the criteria parameters */
VS_Criteria_SetFields (
criteriah,
60
61
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
/* populate the critera with
expressions */
62
63
64
65
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
for ( j = 0 ; j < numexpr ; j++ )
{
66
67
68
69
/* create an expression for
this criteria */
70
exprh =
VS_Expression_Create();
2-220
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
71
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
{
/* could not allocate memory
for this */
72
73
74
75
76
77
78
/* 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 ==> “ );
79
80
81
82
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
83
84
conop = atoi(gets(input));
/* set the expression’s
parameters */
85
86
87
88
VS_Expression_SetFields (
exprh,
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
conop,
VSID_MEDIA_STAT_VALUE,
value,
89
90
VSID_ENDFIELD );
/* add the expression to the
criteria */
91
92
VS_Criteria_SetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
93
94
95
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
601355 Rev A
API Functions
2-221
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
96
97
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
98
99
VSID_ENDFIELD );
}
100 /* if it failed, destroy the criteria
group handle */
101 if ( rc == VSE_FALSE )
102 {
103
104
105
/* criteria group will destroy any
*/
/* criteria and their expressions
*/
/* for us, so the only thing that
is really */
106
107
108
/* needed here is a call to */
/* VS_CriteriaGroup_Destroy. */
/* This is written out the ’long
way’ for */
109
/* documentation purposes. First,
get the */
110
111
/* number of criteria */
VS_CriteriaGroup_GetFields(grouph
,
112
VSID_NUMBER_ENTRIES,
&numcrit,
113
114
115
116
117
VSID_ENDFIELD);
for (i = 0; i < numcrit; i++)
{
/* get a criteria handle */
VS_CriteriaGroup_GetFields(grouph
,
118
VSID_CRITERIA_HANDLE_ENTRY,
i, &criteriah,
119
120
VSID_ENDFIELD);
/* get the number of
expressions */
121
VS_Criteria_GetFields(criteriah,
2-222
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
122
VSID_NUMBER_ENTRIES,
&numexpr,
VSID_ENDFIELD);
for (j = 0; j < numexpr; j++)
{
/* get the expressions from
the criteria */
123
124
125
126
127
128
VS_Criteria_GetFields(criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
129
130
VSID_ENDFIELD);
/* destroy the expression
handle */
131
132
133
134
135
VS_Expression_Destroy(exprh);
/* let Criteria handle know
that the */
/* expression handle has
been destroyed */
VS_Criteria_SetFields(criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
NULL,
136
137
138
VSID_ENDFIELD);
}
/* now, destroy Criteria
handle. */
139
140
141
VS_Criteria_Destroy(criteriah);
/*let the criteria group handle
know */
/* that Criteria handle has
been */
142
143
/* destroyed. */
VS_CriteriaGroup_SetFields(grouph
,
144
VSID_CRITERIA_HANDLE_ENTRY,
i, NULL,
601355 Rev A
API Functions
2-223
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
145
146
147
VSID_ENDFIELD);
}
/* finally, destroy the criteria
group handle. */
148
VS_CriteriaGroup_Destroy ( grouph
);
149
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
150 }
151 return ( grouph );
152}
Notes
After VS_Expression_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Expression_GetFieldsretrieves information
associated with an expression handle. An expression handle is
used to pass expression information to and from VolServ.
VS_
Expression_
GetFields
VST_BOOLEAN VS_Expression_GetFields
( VST_EXPRESSION_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_MOUNT_CRITERIA_OP
(VST_MOUNT_CRITERIA_OPT *)
Pointer to the relational operation for this
expression:
601355 Rev A
API Functions
2-225
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_CONNECTIVE_OP
(VST_CONNECTIVE_OP *)
Pointer to the connective operation between
two expressions. Valid
VS_Expression_GetFieldsvalues are
enumerated in the vs_types.hfile. 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
VS_Expression_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_criteria_group
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a criteria group handle.
8 *
2-226
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
9 * PARAMETERS:
10 * grouph : the mount handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
void
vst_print_criteria_group(VST_CRIT
ERIAGROUP_HANDLE grouph)
15 #else
16
void
vst_print_criteria_group(grouph)
VST_CRITERIAGROUP_HANDLE grouph;
17
18 #endif
19 {
20
21
int
int
i, j;
numcrit=
0;
0;
22
int
numexpr=
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
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* get the number of criteria within
this group */
34
35
36
VS_CriteriaGroup_GetFields ( grouph,
VSID_NUMBER_ENTRIES, &numcrit,
VSID_ENDFIELD );
37
38
39 {
40
for ( i = 0 ; i < numcrit ; i++ )
/* get the criteria to print */
601355 Rev A
API Functions
2-227
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
41
42
VS_CriteriaGroup_GetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
&criteriah,
43
44
45
46
VSID_ENDFIELD );
/* get the criteria parameters */
VS_Criteria_GetFields (
criteriah,
47
48
49
VSID_FIELD,
&field,
VSID_MOUNT_CRITERIA_ORDER,
&sort,
VSID_NUMBER_ENTRIES,
&numexpr,
50
51
52
VSID_ENDFIELD );
printf ( “*** Criteria # %d
***\n”, i );
53
54
55
printf ( “ Field Index ==> %d\n”,
field );
printf ( “ Mount Criteria Order
==> %d\n”, sort );
printf ( “Number of Expressions
==> %d\n”, numexpr );
56
57
58
59
for ( j = 0 ; j < numexpr ; j++ )
{
/* get the expression to print
*/
60
61
VS_Criteria_GetFields (
criteriah,
VSID_EXPRESSION_HANDLE_ENTRY, j,
&exprh,
62
63
64
VSID_ENDFIELD );
/* get the expression’s
parameters */
65
VS_Expression_GetFields (
exprh,
2-228
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
66
67
68
VSID_MOUNT_CRITERIA_OPT,
&relopt,
VSID_CONNECTIVE_OP,
&conop,
VSID_MEDIA_STAT_VALUE,
value,
69
70
71
VSID_ENDFIELD );
printf ( “*** Expression # %d
***\n”, j );
72
73
74
printf ( “Mount Criteria
Option ==> %d\n”, relopt);
printf ( “ Media Stat Value ==>
%s\n”, value);
printf ( “ Connective
Operation ==> %d\n”, conop);
}
75
76
}
77
78
return;
79 }
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),
601355 Rev A
API Functions
2-229
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
•
•
•
•
•
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)
2-230
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Expression_SetFieldssets the value of one or more
fields in an expression handle. An expression handle is used to
pass information to and from VolServ.
VS_
Expression_
SetFields
VST_BOOLEAN VS_Expression_SetFields
( VST_EXPRESSION_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MEDIA_STAT_VALUE
(VST_MEDIA_STAT_VALUE)
Value for comparison. All values are
compared as strings. If numbers are needed,
they are left filled with zeros within the string.
Return Values
VS_Expression_SetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_criteria
4 *
5 * PURPOSE:
6 * This function creates the mount
criteria group
7 * handle andsets the values in it
according to
2-232
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
8 * user input.
9 *
10 * PARAMETERS:
11 * none
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
21
22
23
24
int
int
int
int
i;
j;
numcrit;
numexpr;
rc =
VST_BOOLEAN
VSE_TRUE;
25
26
VST_EXPRESSION_HANDLE
VST_CRITERIA_HANDLE
criteriah;
exprh;
27
28
29
30
31
32
33
34
35
36
37
VST_CRITERIAGROUP_HANDLE grouph;
VST_COUNT field;
VST_MOUNT_CRITERIA_ORDER sort;
VST_MEDIA_STAT_VALUE
VST_MOUNT_CRITERIA_OPT
VST_CONNECTIVE_OP
value;
relopt;
conop;
/* create the criteria group */
grouph = VS_CriteriaGroup_Create();
if ( grouph ==
(VST_CRITERIAGROUP_HANDLE) NULL )
38
39
40
{
/* out of memory -- return */
return (
(VST_CRITERIAGROUP_HANDLE) NULL
);
}
41
601355 Rev A
API Functions
2-233
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
43
/* populate the criteria group with
criteria */
44
45
/* (upto 5) */
printf ( “Enter number of Criteria in
group ==> “ );
46
47
48
49
50
numcrit = atoi(gets(input));
for ( i = 0 ; i < numcrit ; i++ )
{
/* create the criteria for a media
stat field */
51
52
53
criteriah = VS_Criteria_Create();
if ( criteriah ==
(VST_CRITERIA_HANDLE) NULL )
54
55
56
57
58
59
60
{
/* could not allocate handle */
rc = VSE_FALSE;
break;
}
printf ( “Enter the media’s field
number ==> “ );
61
62
63
field = atoi(gets(input));
printf ( “Enter the sort order
(Ascending - 1, Descending - 2)
==> “ );
64
65
66
67
sort = atoi(gets(input));
/* set the criteria parameters */
/VS_Criteria_SetFields (
criteriah,
68
69
VSID_FIELD,
field,
VSID_MOUNT_CRITERIA_ORDER, sort,
VSID_ENDFIELD );
70
71
72
/* populate the critera with
expressions */
2-234
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
73
74
/* (upto 4) */
printf ( “Enter the number of
criteria expressions ==> “ );
numexpr = atoi(gets(input));
75
76
77
78
79
for ( j = 0 ; j < numexpr ; j++ )
{
/* create an expression for
this */
80
81
/* criteria */
exprh =
VS_Expression_Create();
82
83
if ( exprh ==
(VST_EXPRESSION_HANDLE) NULL )
84
85
{
/* could not allocate memory
for this */
/* handle */
rc = VSE_FALSE;
break;
86
87
88
89
90
91
}
printf ( “Enter relational
option (eq 1, gt 2, ge 3, lt 4, le
5, ne 6) ==> “ );
92
93
94
relopt = atoi(gets(input));
printf ( “Enter the media field
value ==> “ );
95
96
97
gets( value);
printf ( “Enter connective
operation (none 0, and 1, or 2)
==> “ );
98
conop = atoi(gets(input));
99
100
/* set the expression’s
parameters */
101
VS_Expression_SetFields (
exprh,
601355 Rev A
API Functions
2-235
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
102
103
104
VSID_MOUNT_CRITERIA_OPT,
relopt,
VSID_CONNECTIVE_OP,
VSID_MEDIA_STAT_VALUE,
VSID_ENDFIELD );
conop,
value,
105
106
107
/* add the expression to the
criteria */
VS_Criteria_SetFields (
criteriah,
108
109
VSID_EXPRESSION_HANDLE_ENTRY, j,
exprh,
110
111
112
113
VSID_ENDFIELD );
}
/* add the criteria to the
criteria group */
VS_CriteriaGroup_SetFields (
grouph,
VSID_CRITERIA_HANDLE_ENTRY,i,
criteriah,
114
115
116
VSID_ENDFIELD );
117 }
118
119 /* if it failed, destroy the criteria
group handle */
120 if ( rc == VSE_FALSE )
121 {
122
/* criteria group will destroy any
*/
123
/* criteria and their expressions
*/
124
125
/* for us */
VS_CriteriaGroup_Destroy ( grouph
);
126
127
grouph =
(VST_CRITERIAGROUP_HANDLE) NULL;
128 }
2-236
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
129
130 return ( grouph );
131}
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).
601355 Rev A
API Functions
2-237
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Global_GetFieldsretrieves global default parameters
for all commands. A global handle is used to maintain global
default parameter values for VolServ commands.
VS_Global_
GetFields
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_GetFields
(
Synopsis
"…",
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ASYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
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_TRUEif the API
is initialized and VSE_FALSEotherwise.
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
VSID_RETRY_LIMITis not applicable when
the API software executes in asynchronous
mode. Default value is 3.
601355 Rev A
API Functions
2-239
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor every command
request. USER_FIELDis 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
VS_Global_GetFieldsreturns:
• 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.
2-240
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_show_globals
4 *
5 * PURPOSE:
6 * This function allows the user to
display the
7 * VolServ API’s global parameters.
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_show_globals( void )
14 #else
15
VST_BOOLEAN vst_show_globals()
16 #endif
17 {
18
19
20
21
22
23
24
25
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
priority;
user_field;
timeout;
retries;
wait;
enterprise;
VS_Global_GetFields(VSID_PRIORITY,
&priority,
26
27
28
29
30
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
&timeout,
VSID_RETRY_LIMIT,
&retries,
VSID_STATUS_WAIT_FLAG,
&wait,
VSID_ENTERPRISE_ID,
&enterprise,
31
32
VSID_ENDFIELD);
printf(“*** Global Parameters
***\n”);
601355 Rev A
API Functions
2-241
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
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);
34
35
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_Selectto 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
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VS_Select(l)
2-242
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Global_SetFieldssets 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.
VS_Global_
SetFields
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
(
Synopsis
"…",
VSID_ENDFIELD )
• "…"= 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.
Arguments
• 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_SYNC_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Pointer to the default value to be put in the
VSID_USER_FIELDfor every command.
USER_FIELDis 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
VS_Global_SetFieldsreturns:
• 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.
601355 Rev A
API Functions
2-245
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_set_globals
4 *
5 * PURPOSE:
6 * This function allows the user to set
VolServ API’s
7 * global parameters.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_set_globals( void )
15 #else
16
VST_BOOLEAN vst_set_globals()
17 #endif
18 {
19
20
21
22
23
24
25
26
27
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”);
28
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
rc =
VS_Global_SetFields(VSID_PRIORITY
, priority,
2-246
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
31
32
33
34
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);
35
36
37 }
Notes
Total length of time the API software waits for a command
status from VolServ is (VSID_RETRY_LIMITplus 1)
multiplied by VSID_TIMEOUT_VALUE.
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_Selectto receive intermediate
and final status on command requests submitted through the
API interface to the VolServ system.
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_GetFields(l),
VS_Select(l),
601355 Rev A
API Functions
2-247
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
VS_Initialize(l)
2-248
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Initializereadies the VolServ API library for use by
the client software.
VS_Initialize
VS_Initializecreates and registers RPC transports for
receiving VolServ status messages and also performs
initialization processing required by other API functions.
VS_Initializemust be called before any API command
functions are called.
VST_BOOLEAN VS_Initialize
( VST_HOSTNAME hostname,
VST_PROGRAM_NUMBER prognum,
int time-out )
Synopsis
Arguments
• hostname= Name of the computer running VolServ.
-
If NULL is specified, hostname defaults to the current
host machine.
• prognum= Program number on which VolServ is
registered.
-
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.
601355 Rev A
API Functions
2-249
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Initializereturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_initialize
4 *
5 * PURPOSE:
6 * This function initializes the VolServ
API.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_initialize(void)
14 #else
15
VST_BOOLEAN vst_initialize()
16 #endif
17 {
2-250
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
18
19
20
21
22
23
24
25
26
int
timeout;
host;
VST_HOSTNAME
VST_PROGRAM_NUMBER prognum;
VST_PROGRAM_NUMBER syncnum;
VST_PROGRAM_NUMBER asyncnum;
VST_BOOLEAN
rc = VSE_FALSE;
/* get parameters from user */
printf(“*** Initialize parameters
***\n” );
27
28
29
printf(“Enter VolServ Host ==> “ );
gets( host );
printf(“Enter VolServ Program Number
==> “ );
30
31
32
33
34
prognum = atol(gets(input));
printf(“Enter Timeout Value ==> “ );
timeout = atoi(gets(input));
/* change the sync/async program
numbers */
35
36
printf(“*** RPC Program numbers
***\n” );
printf(“Enter Sync Program Number (0
for default) ==> “ );
37
38
syncnum = atol(gets(input));
printf(“Enter Async Program Number (0
for default) ==> “ );
39
40
41
42
43
44
asyncnum = atol(gets(input));
if ( syncnum != 0 )
{
VS_Global_SetFields (
VSID_SYNC_PROGRAM_NUMBER,
syncnum,
45
46
47
48
49
50
VSID_ENDFIELD );
}
if ( asyncnum != 0 )
{
VS_Global_SetFields (
601355 Rev A
API Functions
2-251
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
51
VSID_ASYNC_PROGRAM_NUMBER,
asyncnum,
52
53
54
VSID_ENDFIELD );
}
rc = VS_Initialize(host, prognum,
timeout);
55
return(rc);
56 }
Notes
VS_Global_SetDefaultsmust be called before
VS_Initializeis called to set the SYNC/ASYNC program
numbers.
All command functions fail if VS_Initializeis not invoked.
VS_Initializedoes not verify that VolServ is currently
running on the given host. Use VS_Pingto check VolServ's
status.
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Terminate(1),
VS_Global_SetFields(l)
2-252
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Media_Createallocates a VolServ API media handle.
A media handle is used to pass media information to and from
VolServ.
VS_Media_
Create
VST_MEDIA_HANDLE VS_Media_Create ( void )
Synopsis
Arguments
None
Return Values
VS_Media_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_media_handle
4 *
5 * PURPOSE:
6 * This function tests a media handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_media_handle(void)
14 #else
15
VST_BOOLEAN vst_media_handle()
16 #endif
17 {
601355 Rev A
API Functions
2-253
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
21
VST_MEDIA_HANDLE
VST_MEDIA_ID
h;
MediaID;
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
22
23
BatchName;
24
25
26
27
ActionState;
ImportDate;
28
29
30
VST_TIME
LastDismount;
VST_ASSIGNMENT
int
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
Assignment;
MountCount;
MoveCount;
int
/* 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 ==>
“);
48
49
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
2-254
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
50
51
gets(MediaClassName);
printf(“Enter media location
state ==> “);
52
LocationState =
atoi(gets(input));
53
54
55
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
56
57
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
58
59
gets(PendingArchive);
printf(“enter assignment value
==> “);
60
61
62
63
64
65
66
67
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,
68
69
70
71
72
73
74
75
76
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,
601355 Rev A
API Functions
2-255
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
77
78
VSID_MOUNT_COUNT,
MountCount,
VSID_MOVE_COUNT,
MoveCount,
VSID_ENDFIELD);
if (rc)
79
80
81
{
82
vst_print_media(h);
83
}
84
85
86
VS_Media_Destroy(h);
return(rc);
}
87 }
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Media_Destroydeallocates a VolServ API media
VS_Media_
Destroy
handle that was allocated by VS_Media_Create. A media
destroy handle is used to pass media information to and from
VolServ.
VST_BOOLEAN VS_Media_Destroy
(VST_MEDIA_HANDLE handle)
Synopsis
Arguments
• handle= The media handle to be destroyed.
Return Values
VS_Media_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_media_handle
4 *
5 * PURPOSE:
6 * This function tests a media handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
601355 Rev A
API Functions
2-257
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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;
VST_MEDIA_HANDLE
VST_MEDIA_ID
19
20
21
h;
MediaID;
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
22
23
BatchName;
24
25
26
27
ActionState;
ImportDate;
28
29
30
VST_TIME
LastDismount;
VST_ASSIGNMENT
int
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
Assignment;
MountCount;
MoveCount;
int
/* 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 ==> “);
2-258
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
gets(BatchName);
printf(“Enter Manufacturer ==>
“);
48
49
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
50
51
gets(MediaClassName);
printf(“Enter media location
state ==> “);
52
LocationState =
atoi(gets(input));
53
54
55
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
56
57
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
58
59
gets(PendingArchive);
printf(“enter assignment value
==> “);
60
61
62
63
64
65
66
67
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,
68
69
70
71
72
73
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,
601355 Rev A
API Functions
2-259
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
75
76
77
78
VSID_CURRENT_ARCHIVE_NAME,
CurrentArchive,
VSID_PENDING_ARCHIVE_NAME,
PendingArchive,
VSID_ASSIGNMENT,
Assignment,
VSID_MOUNT_COUNT,
MountCount,
VSID_MOVE_COUNT,
MoveCount,
79
80
VSID_ENDFIELD);
if (rc)
81
{
82
83
vst_print_media(h);
}
84
VS_Media_Destroy(h);
85
}
86
return(rc);
87 }
Notes
After VS_Media_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Media_GetFieldsretrieves information associated
with a media handle. A media handle is used to pass media
information to and from VolServ.
VS_Media_
GetFields
VST_BOOLEAN VS_Media_GetFields
(VST_MEDIA_HANDLE handle,
“…”,
Synopsis
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_STATEvalues are
enumerated in the vs_types.h file.
VSID_ASSIGNMENT (VST_ASSIGNMENT *) Current assignment of this medium. Valid
VSID_ASSIGNMENTvalues are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-261
Download from Www.Somanuals.com. All Manuals Search And Download.
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 *)
VSID_LAST_DISMOUNT (VST_TIME *)
Pointer to the date this medium was imported
into the VolServ system.
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_STATEvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VS_Media_GetFieldsreturns:
• 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.
Example
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 *
601355 Rev A
API Functions
2-263
Download from Www.Somanuals.com. All Manuals Search And Download.
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
20
VST_MEDIA_ID
MediaID;
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
21
22
BatchName;
23
24
25
26
ActionState;
ImportDate;
27
28
29
VST_TIME
LastDismount;
VST_ASSIGNMENT
int
30
31
32
33
34
35
Assignment;
MountCount;
MoveCount;
int
VS_Media_GetFields(h,
VSID_MEDIA_ID,
MediaID,
36
37
38
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_BATCH_NAME,
BatchName,
VSID_MANUFACTURER,
Manufacturer,
2-264
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
40
41
42
43
44
45
46
47
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,
49
50
VSID_ENDFIELD);
printf(“******Media
Handle******\n”);
51
52
printf(“Media ID = %s\n”,MediaID);
printf(“Media Type Name =
%s\n”,MediaTypeName);
printf(“Batch Name =
%s\n”,BatchName);
53
54
55
56
57
58
59
60
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);
601355 Rev A
API Functions
2-265
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
61
printf(“Last Dismount =
%d\n”,LastDismount);
printf(“Assignment =
%d\n”,Assignment);
printf(“Move Count =
%d\n”,MoveCount);
62
63
64
printf(“Mount Count =
%d\n”,MountCount);
65 }
Notes
The VSID_IMPORT_DATEand last VSID_LAST_DISMOUNTare
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
•
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Media_Create(l),
VS_Media_Destroy(l),
VS_Media_SetFields(l),
VSCMS_MediaQuery(l),
VSCMD_MediaClassQuery(l)
2-266
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Media_SetFieldssets 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.
VS_Media_
SetFields
VST_BOOLEAN VS_Media_SetFields
(VST_MEDIA_HANDLE handle,
“…”,
Synopsis
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_STATEvalues are
enumerated in the vs_types.h file.
VSID_ASSIGNMENT (VST_ASSIGNMENT)
Current assignment of this medium. Valid
VSID_ASSIGNMENTvalues are enumerated
in the vs_types.h file.
601355 Rev A
API Functions
2-267
Download from Www.Somanuals.com. All Manuals Search And Download.
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_STATEvalues 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)
VSID_MOVE_COUNT (VST_COUNT)
Number of times this medium has been
mounted.
Number of times this medium has been
moved from one archive to another.
2-268
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PENDING_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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
VS_Media_SetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_media_handle
4 *
5 * PURPOSE:
6 * This function tests a media handle.
7 *
8 * PARAMETERS:
9 * none
601355 Rev A
API Functions
2-269
Download from Www.Somanuals.com. All Manuals Search And Download.
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;
VST_MEDIA_HANDLE
VST_MEDIA_ID
19
20
21
h;
MediaID;
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
22
23
BatchName;
24
25
26
27
ActionState;
ImportDate;
28
29
30
VST_TIME
LastDismount;
VST_ASSIGNMENT
int
31
32
33
34
35
36
37
38
39
40
41
42
Assignment;
MountCount;
MoveCount;
int
/* 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);
2-270
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
45
46
47
printf(“Enter media type ==> “);
gets(MediaTypeName);
printf(“Enter batch name ==> “);
gets(BatchName);
printf(“Enter Manufacturer ==>
“);
48
49
gets(Manufacturer);
printf(“Enter Media Class Name ==>
“);
50
51
gets(MediaClassName);
printf(“Enter media location
state ==> “);
52
LocationState =
atoi(gets(input));
53
54
55
printf(“Enter action state ==> “);
ActionState = atoi(gets(input));
printf(“Enter current archive ==>
“);
56
57
gets(CurrentArchive);
printf(“Enter pending archive ==>
“);
58
59
gets(PendingArchive);
printf(“enter assignment value
==> “);
60
61
62
63
64
65
66
67
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,
68
69
70
71
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_BATCH_NAME,
BatchName,
VSID_MANUFACTURER,
Manufacturer,
VSID_MEDIA_CLASS_NAME,
MediaClassName,
601355 Rev A
API Functions
2-271
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
72
73
74
75
76
77
78
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,
79
80
VSID_ENDFIELD);
if (rc)
81
{
82
83
vst_print_media(h);
}
84
VS_Media_Destroy(h);
85
}
86
return(rc);
87 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Media_Create(l),
VS_Media_Destroy(l),
VS_Media_SetFields(l)
2-272
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaClass_Createallocates a VolServ API
MediaClass handle. A MediaClass handle is used to pass
MediaClass information to and from VolServ.
VS_
MediaClass_
Create
VST_MEDIACLASS_HANDLE VS_MediaClass_Create
(void)
Synopsis
Arguments
None
Return Values
VS_MediaClass_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests a mediaclass
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediaclass_handle(void)
601355 Rev A
API Functions
2-273
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14 #else
15
VST_BOOLEAN vst_mediaclass_handle()
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
VST_MEDIACLASS_HANDLE h;
rc =
19
20
21
VST_MEDIA_CLASS_NAME
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_PRIORITY
MediaClass;
22
ReleasePriority;
VST_CAPACITY
VST_FILL_LEVEL
VST_CLASS_MOUNT_STATE MountState;
VST_HIGH_MARK
23
24
25
26
27
28
Capacity;
FillLevel;
HighMark;
RPC_Option;
VST_CLASS_RPC_OPTION
VST_HOSTNAME
RPC_HostName;
29
30
31
32
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
RPC_ProgNum;
RPC_VersNum;
RPC_ProcNum;
RPC_Protocol;
33
34
VST_ENTERPRISE_ID
EnterpriseID;
VST_NOTIFY_COMMENT
NotifyComment;
35
36
37
38
/* create the handle */
h = VS_MediaClass_Create();
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
40
41
{
/* get values from user */
printf(“*** Media Class Handle
***\n”);
42
printf(“Enter mediaclass name ==>
“);
43
44
gets(MediaClass);
printf(“Enter media type name ==>
“);
2-274
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
46
gets(MediaTypeName);
printf(“Enter release priority
==> “);
47
ReleasePriority =
atoi(gets(input));
48
49
50
51
52
53
54
55
56
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 ==>
“);
57
58
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
59
60
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
61
62
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
63
64
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
65
66
67
68
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
69
70
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
71
72
73
74
gets(NotifyComment);
/* set the fields */
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
75
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
601355 Rev A
API Functions
2-275
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
76
77
78
79
80
81
82
83
84
85
86
87
88
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)
89
90
91
{
92
93
vst_print_mediaclass(h);
}
94
VS_MediaClass_Destroy(h);
95
}
96
return(rc);
97 }
Notes
None
2-276
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_MediaClass_Destroy(l),
VS_MediaClass_GetFields(l),
VS_MediaClass_SetFields(l)
601355 Rev A
API Functions
2-277
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaClass_Destroydeallocates 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.
VS_
MediaClass_
Destroy
VST_BOOLEAN VS_MediaClass_Destroy
(VST_MEDIACLASS_HANDLE handle)
Synopsis
Arguments
•
handle = The MediaClass handle to be destroyed.
Return Values
VS_MediaClass_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests a mediaclass
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-278
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
VSE_FALSE;
VST_MEDIACLASS_HANDLE h;
rc =
19
20
21
VST_MEDIA_CLASS_NAME
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_PRIORITY
MediaClass;
22
ReleasePriority;
VST_CAPACITY
VST_FILL_LEVEL
VST_CLASS_MOUNT_STATE MountState;
VST_HIGH_MARK
23
24
25
26
27
28
Capacity;
FillLevel;
HighMark;
RPC_Option;
VST_CLASS_RPC_OPTION
VST_HOSTNAME
RPC_HostName;
29
30
31
32
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
RPC_ProgNum;
RPC_VersNum;
RPC_ProcNum;
RPC_Protocol;
33
34
VST_ENTERPRISE_ID
EnterpriseID;
VST_NOTIFY_COMMENT
NotifyComment;
35
36
37
38
/* create the handle */
h = VS_MediaClass_Create();
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
40
41
{
/* get values from user */
printf(“*** Media Class Handle
***\n”);
601355 Rev A
API Functions
2-279
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
printf(“Enter mediaclass name ==>
“);
43
44
gets(MediaClass);
printf(“Enter media type name ==>
“);
45
46
gets(MediaTypeName);
printf(“Enter release priority
==> “);
47
ReleasePriority =
atoi(gets(input));
48
49
50
51
52
53
54
55
56
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 ==>
“);
57
58
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
59
60
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
61
62
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
63
64
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
65
66
67
68
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
69
70
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
71
72
gets(NotifyComment);
/* set the fields */
2-280
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
73
74
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
75
76
77
78
79
80
81
82
83
84
85
86
87
88
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)
89
90
91
{
92
93
vst_print_mediaclass(h);
}
94
VS_MediaClass_Destroy(h);
95
}
96
return(rc);
97 }
601355 Rev A
API Functions
2-281
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
After VS_MediaClass_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaClass_GetFieldsretrieves information
associated with a MediaClass handle. A MediaClass handle is
used to pass MediaClass information to and from VolServ.
VS_
MediaClass_
GetFields
VST_BOOLEAN VS_MediaClass_GetFields
(VST_MEDIACLASS_HANDLE handle,
“…”,
Synopsis
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_STATEvalues are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-283
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues are
enumerated in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID *)
If VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE,a pointer to
the identifier of the enterprise to receive
unsolicited callbacks. Otherwise,
VSID_ENTERPRISE_IDis not applicable.
VSID_FILL_LEVEL (VST_FILL_LEVEL *)
VSID_HIGH_MARK (VST_HIGH_MARK *)
Pointer to the current number of media in this
MediaClass group.
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_OPTIONis 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_NAMEis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MEDIA_TYPE_NAME
(VST_MEDIA_TYPE_NAME)
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_OPTIONis set to
VSE_CLASS_RPC_STANDARD, a pointer to the
RPC procedure number of the “listening task.”
Otherwise, VSID_PROCEDURE_NUMBERis not
applicable.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER *)
If VSID_CLASS_RPC_OPTIONis 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_OPTIONis set to
VSE_CLASS_RPC_NONEor
VSE_CLASS_RPC_ENTERPRISE,
VSID_PROGRAM_NUMBERis not applicable.
VSID_PROTOCOL (VST_PROTOCOL *)
If the VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_STANDARD, a pointer
where Internet protocol to use to return
unsolicited callbacks to the client. Valid
VSID_PROTOCOLvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_VERSION_NUMBER
(VST_VERSION_NUMBER *)
If the VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_STANDARD, a pointer to the
RPC version number of the “listening task.”
Otherwise, VSID_VERSION_NUMBERis not
applicable.
Return Values
VS_MediaClass_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_mediaclass
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a media class handle.
8 *
9 * PARAMETERS:
10 * h : the media class handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
2-286
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14
void
vst_print_mediaclass(VST_MEDIACLA
SS_HANDLEh)
15 #else
16
17
void vst_print_mediaclass(h)
VST_MEDIACLASS_HANDLE h;
18 #endif
19 {
20
21
VST_MEDIA_CLASS_NAME
MediaClass;
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_PRIORITY
22
ReleasePriority;
VST_CAPACITY
VST_FILL_LEVEL
23
24
25
26
27
28
Capacity;
FillLevel;
VST_CLASS_MOUNT_STATE MountState;
VST_HIGH_MARK
VST_CLASS_RPC_OPTION
VST_HOSTNAME
HighMark;
RPC_Option;
RPC_HostName;
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
29
30
31
32
RPC_ProgNum;
RPC_VersNum;
RPC_ProcNum;
RPC_Protocol;
VST_ENTERPRISE_ID
EnterpriseID;
VST_NOTIFY_COMMENT
NotifyComment;
VST_TABLE_HANDLE
MediaHandleTable;
int
33
34
35
36
37
38
39
40
41
NumEntries;
i;
Media;
int
VST_MEDIA_HANDLE
VS_MediaClass_GetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
42
43
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
VSID_RELEASE_PRIORITY,
&ReleasePriority,
601355 Rev A
API Functions
2-287
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
44
45
46
47
48
49
50
51
52
53
54
55
56
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_MEDIA_HANDLE_TABLE,&MediaHan
dleTable,
57
58
VSID_ENDFIELD);
printf(“****** Media Class Handle
******\n”);
59
60
61
printf(“Media Class = %s\n”,
MediaClass);
printf(“Media Type = %s\n”,
MediaTypeName);
printf(“Release Priority=%d\n”,
ReleasePriority);
62
63
printf(“Capacity = %d\n”, Capacity);
printf(“Fill Level = %d\n”,
FillLevel);
64
65
printf(“Mount State = %d\n”,
MountState);
printf(“High Mark = %d\n”, HighMark);
2-288
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
66
67
68
69
70
71
72
73
74
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)
{
75
76
VS_Table_GetFields(MediaHandleTab
le,
77
VSID_NUMBER_ENTRIES,
&NumEntries,
78
79
80
81
VSID_ENDFIELD);
for (i = 0; i < NumEntries; i++)
{
VS_Table_GetFields(MediaHandleTab
le,
82
VSID_TABLE_ENTRY, i,
&Media,
83
VSID_ENDFIELD);
84
vst_print_media(Media);
85
86
}
}
87 }
601355 Rev A
API Functions
2-289
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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)
2-290
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaClass_SetFieldssets the value for one or
VS_
MediaClass_
SetFields
more fields in a specified MediaClass handle. A MediaClass
handle is used to pass MediaClass information to and from
VolServ.
VST_BOOLEAN VS_MediaClass_SetFields
(VST_MEDIACLASS_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues are
enumerated in the vs_types.h file.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
If the VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE, the identifier
of the enterprise to receive unsolicited
callbacks. Otherwise,
VSID_ENTERPRISE_IDis not applicable.
VSID_FILL_LEVEL (VST_FILL_LEVEL)
VSID_HIGH_MARK (VST_HIGH_MARK)
Current number of media in this MediaClass
group.
Percentage of the MediaClass capacity above
which notification or automatic media
migration is initiated.
VSID_HOST_NAME (VST_HOSTNAME)
If VSID_CLASS_RPC_OPTIONis 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_NAMEis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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. 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_OPTIONis set to
VSE_CLASS_RPC_STANDARD, the RPC
procedure number of the “listening task.”
Otherwise, VSID_PROCEDURE_NUMBERis 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_OPTIONis set to
VSE_CLASS_RPC_NONEor
VSE_CLASS_RPC_ENTERPRISE,
VSID_PROGRAM_NUMBERis not applicable.
VSID_PROTOCOL (VST_PROTOCOL)
If VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_STANDARD, the Internet
protocol to use to return unsolicited callbacks
to the client. Valid VSID_PROTOCOLvalues
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_OPTIONis set to
VSE_CLASS_RPC_STANDARD, the RPC
version number of the “listening task.”
Otherwise, VSID_VERSION_NUMBERis not
applicable.
601355 Rev A
API Functions
2-293
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_MediaClass_SetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediaclass_handle
4 *
5 * PURPOSE:
6 * This function tests a mediaclass
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediaclass_handle(void)
14 #else
15
VST_BOOLEAN vst_mediaclass_handle()
2-294
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
VST_MEDIACLASS_HANDLE h;
rc =
19
20
21
VST_MEDIA_CLASS_NAME
VST_MEDIA_TYPE_NAME
MediaTypeName;
VST_PRIORITY
MediaClass;
22
ReleasePriority;
VST_CAPACITY
VST_FILL_LEVEL
VST_CLASS_MOUNT_STATE MountState;
VST_HIGH_MARK
23
24
25
26
27
28
Capacity;
FillLevel;
HighMark;
RPC_Option;
VST_CLASS_RPC_OPTION
VST_HOSTNAME
RPC_HostName;
29
30
31
32
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
RPC_ProgNum;
RPC_VersNum;
RPC_ProcNum;
RPC_Protocol;
33
34
VST_ENTERPRISE_ID
EnterpriseID;
VST_NOTIFY_COMMENT
NotifyComment;
35
36
37
38
/* create the handle */
h = VS_MediaClass_Create();
if (h != (VST_MEDIACLASS_HANDLE)
NULL)
39
40
41
{
/* get values from user */
printf(“*** Media Class Handle
***\n”);
42
printf(“Enter mediaclass name ==>
“);
43
44
gets(MediaClass);
printf(“Enter media type name ==>
“);
45
gets(MediaTypeName);
601355 Rev A
API Functions
2-295
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
printf(“Enter release priority
==> “);
ReleasePriority =
atoi(gets(input));
48
49
50
51
52
53
54
55
56
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 ==>
“);
57
58
RPC_Option = atoi(gets(input));
printf(“Enter RPC host name ==>
“);
59
60
gets(RPC_HostName);
printf(“Enter RPC program number
==> “);
61
62
RPC_ProgNum = atol(gets(input));
printf(“Enter RPC version number
==> “);
63
64
RPC_VersNum = atol(gets(input));
printf(“Enter RPC procedure
number ==> “);
65
66
67
68
RPC_ProcNum = atol(gets(input));
printf(“Enter RPC protocol ==> “);
RPC_Protocol = atoi(gets(input));
printf(“Enter enterprise id ==>
“);
69
70
EnterpriseID = atol(gets(input));
printf(“Enter notify comment ==>
“);
71
72
73
74
gets(NotifyComment);
/* set the fields */
rc = VS_MediaClass_SetFields(h,
VSID_MEDIA_CLASS_NAME,
MediaClass,
75
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
2-296
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
76
77
78
79
80
81
82
83
84
85
86
87
88
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)
89
90
91
{
92
93
94
95
vst_print_mediaclass(h);
VS_MediaClass_Destroy(h);
return(rc);
}
}
96
97 }
601355 Rev A
API Functions
2-297
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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)
2-298
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaType_Createallocates a VolServ API media
type handle. A media type handle is used to pass media type
information to and from VolServ.
VS_
MediaType_
Create
VST_MEDIATYPE_HANDLE VS_MediaType_Create (void)
Synopsis
Arguments
None
Return Values
VS_MediaType_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediatype_handle
4 *
5 * PURPOSE:
6 * This function tests a mediatype
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediatype_handle(void)
14 #else
601355 Rev A
API Functions
2-299
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
15
VST_BOOLEAN vst_mediatype_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
h;
VSE_FALSE;
VST_MEDIATYPE_HANDLE
VST_MEDIA_TYPE_NAME
MediaTypeName;
int
19
20
21
22
23
24
25
26
27
28
NumberSides;
VST_MEDIA_TYPE_CAPACITY Capacity;
h = VS_MediaType_Create();
if (h != (VST_MEDIATYPE_HANDLE) NULL)
{
/* get values from user */
printf(“Enter Media Type Name ==>
“);
29
30
gets(MediaTypeName);
printf(“Enter number of sides ==>
“);
31
32
NumberSides = atoi(gets(input));
printf(“Enter media type capacity
==> “);
33
34
35
Capacity = atof(gets(input));
rc = VS_MediaType_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
37
VSID_NUMBER_SIDES,
NumberSides,
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
VSID_ENDFIELD);
39
if (rc)
40
{
41
42
vst_print_mediatype(h);
}
43
44
VS_MediaType_Destroy(h);
}
45
return(rc);
46 }
2-300
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
None
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_MediaType_Destroy(l),
VS_MediaType_GetFields(l),
VS_MediaType_SetFields(l)
601355 Rev A
API Functions
2-301
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaType_Destroydeallocates 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.
VS_
MediaType_
Destroy
VST_BOOLEAN VS_MediaType_Destroy
(VST_MEDIATYPE_HANDLE handle)
Synopsis
Arguments
•
handle = The media type handle to be destroyed.
Return Values
VS_MediaType_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediatype_handle
4 *
5 * PURPOSE:
6 * This function tests a mediatype
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-302
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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 =
h;
VSE_FALSE;
VST_MEDIATYPE_HANDLE
VST_MEDIA_TYPE_NAME
MediaTypeName;
int
19
20
21
22
23
24
25
26
27
28
NumberSides;
VST_MEDIA_TYPE_CAPACITY Capacity;
h = VS_MediaType_Create();
if (h != (VST_MEDIATYPE_HANDLE) NULL)
{
/* get values from user */
printf(“Enter Media Type Name ==>
“);
29
30
gets(MediaTypeName);
printf(“Enter number of sides ==>
“);
31
32
NumberSides = atoi(gets(input));
printf(“Enter media type capacity
==> “);
33
34
35
Capacity = atof(gets(input));
rc = VS_MediaType_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
37
VSID_NUMBER_SIDES,
NumberSides,
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
39
40
41
42
VSID_ENDFIELD);
if (rc)
{
vst_print_mediatype(h);
}
601355 Rev A
API Functions
2-303
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
45
VS_MediaType_Destroy(h);
return(rc);
}
46 }
Notes
After VS_MediaType_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaType_GetFieldsretrieves information
associated with a media type handle. A media type handle is
used to pass media type information to and from VolServ.
VS_
MediaType_
GetFields
VST_BOOLEAN VS_MediaType_GetFields
(VST_MEDIATYPE_HANDLE handle,
“…”
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_NUMBER_SIDES (int *)
Pointer to the number of sides a medium
belonging to this media type classification
supports.
Return Values
VS_MediaType_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_mediatype
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a media type handle.
8 *
9 * PARAMETERS:
10 * h : the media type handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
2-306
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14
void
vst_print_mediatype(VST_MEDIATYPE
_HANDLE h)
15 #else
16
17
void vst_print_mediatype(h)
VST_MEDIATYPE_HANDLE h;
18 #endif
19 {
20
VST_MEDIA_TYPE_NAME
MediaTypeName;
21
22
23
24
25
int
NumberSides;
VST_MEDIA_TYPE_CAPACITY Capacity;
VS_MediaType_GetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
26
27
VSID_NUMBER_SIDES,
&NumberSides,
VSID_MEDIA_TYPE_CAPACITY,
&Capacity,
28
29
VSID_ENDFIELD);
printf(“*** Media Type Handle
***\n”);
30
printf(“media type name = %s\n”,
MediaTypeName);
31
printf(“number of sides = %d\n”,
NumberSides);
32
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_MediaType_Create(l),
VS_MediaType_Destroy(l),
VS_MediaType_SetFields(l),
VSCMD_MediaTypeQuery(l)
2-308
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_MediaType_SetFieldssets 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.
VS_
MediaType_
SetFields
VST_BOOLEAN VS_MediaType_SetFields
(VST_MEDIATYPE_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_NUMBER_SIDES (int)
Number of sides a medium belonging to this
media type classification supports.
Return Values
VS_MediaType_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediatype_handle
4 *
5 * PURPOSE:
6 * This function tests a mediatype
handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-310
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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 =
h;
VSE_FALSE;
VST_MEDIATYPE_HANDLE
VST_MEDIA_TYPE_NAME
MediaTypeName;
int
19
20
21
22
23
24
25
26
27
28
NumberSides;
VST_MEDIA_TYPE_CAPACITY Capacity;
h = VS_MediaType_Create();
if (h != (VST_MEDIATYPE_HANDLE) NULL)
{
/* get values from user */
printf(“Enter Media Type Name ==>
“);
29
30
gets(MediaTypeName);
printf(“Enter number of sides ==>
“);
31
32
NumberSides = atoi(gets(input));
printf(“Enter media type capacity
==> “);
33
34
35
Capacity = atof(gets(input));
rc = VS_MediaType_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
36
37
VSID_NUMBER_SIDES,
NumberSides,
VSID_MEDIA_TYPE_CAPACITY,
Capacity,
38
39
40
41
42
VSID_ENDFIELD);
if (rc)
{
vst_print_mediatype(h);
}
601355 Rev A
API Functions
2-311
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
45
VS_MediaType_Destroy(h);
return(rc);
}
46 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_MediaType_Create(l),
VS_MediaType_Destroy(l),
VS_MediaType_GetFields(l),
VSCMD_MediaTypeQuery(l)
2-312
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Mount_Createfunction allocates a VolServ API mount
handle. A mount handle is used to pass mount information to
and from VolServ.
VS_Mount_
Create
VST_MOUNT_HANDLE VS_Mount_Create (void)
Synopsis
Arguments
None
Return Values
VS_Mount_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_handle
4 *
5 * PURPOSE:
6 * This function creates the mount handle
and sets the
7 * values in it according to user input.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_MOUNT_HANDLE
vst_create_mount_handle ( void )
15 #else
601355 Rev A
API Functions
2-313
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16
VST_MOUNT_HANDLE
vst_create_mount_handle ()
17 #endif
18 {
19
20
21
22
int
int
i;
entry;
driveid;
VST_DRIVE_ID
VST_DRIVE_POOL_NAME
drivepool;
23
24
VST_MEDIA_ID
VST_MEDIA_CLASS_NAME
mediaclass;
VST_MOUNT_HANDLE
mediaid;
mounth;
25
26
27
28
29
30
VST_CRITERIAGROUP_HANDLE grouph;
/* create the handle */
mounth = VS_Mount_Create();
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
31
32
{
return ( (VST_MOUNT_HANDLE) NULL
);
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
if ( entry == 1 )
{
printf ( “Enter Media ID for
mounting ==> “ );
gets(mediaid);
VS_Mount_SetFields ( mounth,
VSID_MEDIA_ID, mediaid,
VSID_ENDFIELD );
}
41
42
43
44
45
46
47
48
else
{
printf ( “Enter Media Class for
mounting ==> “ );
gets(mediaclass);
49
2-314
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
50
51
VS_Mount_SetFields ( mounth,
VSID_MEDIA_CLASS_NAME,
mediaclass,
52
53
54
VSID_ENDFIELD );
printf ( “Reclassify media (1) yes
or (2) no ==> “ );
55
56
57
58
59
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Target Media
Class ==> “ );
60
61
62
gets(mediaclass);
VS_Mount_SetFields( mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
mediaclass,
63
64
65
66
VSID_ENDFIELD );
}
}
printf ( “Mount by (1) Drive ID or (2)
Drive Pool ==> “ );
67
68
69
70
71
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Drive ID for
mounting ==> “ );
driveid = atoi(gets(input));
VS_Mount_SetFields ( mounth,
VSID_DRIVE_ID,
72
73
74
driveid,
75
76
77
78
79
VSID_ENDFIELD );
}
else
{
printf ( “Enter Drive Pool for
mount ==> “ );
80
81
gets(drivepool);
VS_Mount_SetFields ( mounth,
601355 Rev A
API Functions
2-315
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
82
VSID_DRIVEPOOL_NAME,
VSID_ENDFIELD );
drivepool,
83
84
85
}
printf ( “Mount by criteria (1) yes
or (2) no ==> “ );
86
87
88
89
90
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter number of criteria
groups ==> “ );
91
92
93
94
95
entry = atoi(gets(input));
for ( i = 0 ; i < entry ; i++ )
{
/* create a criteria group
handle */
96
97
grouph =
vst_create_mount_criteria();
if ( grouph !=
(VST_CRITERIAGROUP_HANDLE) NULL )
98
99
{
VS_Mount_SetFields (
mounth,
100
VSID_CRITERIA_GROUP_HANDLE,
i, grouph,
101
102
103
VSID_ENDFIELD );
}
}
104 }
105 return ( mounth );
106}
Notes
VS_Mount_Createis used with the Mount or Multimount
commands.
2-316
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-317
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Mount_Destroydeallocates a VolServ mount handle
that was allocated with VS_Mount_Create. A mount handle
is used to pass mount information to and from VolServ.
VS_Mount_
Destroy
VST_BOOLEAN VS_Mount_Destroy
(VST_MOUNT_HANDLE handle)
Synopsis
Arguments
•
handle = The mount handle to be destroyed.
Return Values
VS_Mount_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_multimount_execute
4 *
5 * PURPOSE:
6 * This function will test the
VSCMD_Multimount call.
7 *
8 * PARAMETERS:
9 * none
10
11 ****************************************
*********/
2-318
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
12 #ifdef ANSI_C
13 VST_BOOLEAN
vst_multimount_execute(void)
14 #else
15 VST_BOOLEAN vst_multimount_execute()
16 #endif
17 {
18
19
20
21
22
int i;
int num;
VST_BOOLEAN rc = VSE_FALSE;
VST_COMMAND_HANDLE cmdh;
VST_MOUNT_HANDLE
mounth[VSD_MAX_MOUNT_REQS];
23
24
25
/* get parameters from user */
printf(“*** MultiMount Parameters
***\n”);
26
printf(“Enter the number of mount
requests ==> “ );
27
28
29
num = atoi(gets(input));
/* loop through the number of mount
request */
30
31
32
33
for ( i = 0 ; i < num ; i++ )
{
/* Create a mount handle. */
/* Each mount handle stores a
single mount */
34
35
/* request.The MultiMount command
accepts */
/* multiple mount requests and
executes */
36
37
/* them all as one operation.*/
mounth[i] =
vst_create_mount_handle();
if ( mounth[i] !=
38
(VST_MOUNT_HANDLE) NULL )
{
/* add the mount request to the
multimount */
39
40
41
/* via the command default
function */
601355 Rev A
API Functions
2-319
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
43
VSCMD_MultiMount_SetDefaults (
VSID_MOUNT_HANDLE,i,
mounth[i],
44
45
46
47
48
49
50
51
52
53
54
55
56
VSID_ENDFIELD );
}
else
{
rc = VSE_FALSE;
break;
}
}
if ( rc )
{
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
57
58
{
/* execute the multimount
command, note */
59
60
61
62
/* 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 */
63
64
65
/* status has been returned */
rc = VSCMD_MultiMount ( cmdh,
VSID_ENDFIELD );
66
67
68
69
70
71
72
73
}
else
{
rc = VSE_FALSE;
}
}
/* destroy the mount handles that
contain the */
74
/* individual mount requests. */
2-320
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
75
76
for ( i = 0 ; i < num ; i++ )
{
77
VS_Mount_Destroy ( mounth[i] );
78
}
79
return ( rc );
80 }
Notes
After VS_Mount_Destroyhas 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
API Functions
2-321
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Mount_GetFieldsretrieves information associated
with a mount handle. A mount handle is used to pass mount
information to and from VolServ.
VS_
MediaClass_
GetFields
VST_BOOLEAN VS_Mount_GetFields
(VST_MOUNT_HANDLE handle,
“…”,
Synopsis
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_SELECTvalues are
enumerated in the vs_types.h file.
2-322
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVE_ID (VST_DRIVE_ID *)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues 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
VS_Mount_GetFieldsreturns:
• 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.
Example
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 *
2-324
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
void
vst_print_mount(VST_MOUNT_HANDLE
mounth)
14 #else
15
16
void vst_print_mount(mounth)
VST_MOUNT_HANDLE mounth;
17 #endif
18 {
19
20
int
i, size;
driveid;
VST_DRIVE_SELECT
driveselect;
VST_DRIVE_ID
VST_DRIVE_POOL_NAME
drivepool;
21
22
23
VST_MEDIA_SELECT
mediaselect;
24
25
VST_MEDIA_ID
VST_MEDIA_CLASS_NAME
mediaclass;
mediaid;
26
VST_MEDIA_CLASS_NAME
targetmediaclass;
VST_MOUNT_OPTION
VST_CRITERIAGROUP_HANDLE grouph;
VST_TABLE_HANDLE tableh;
27
28
29
30
31
32
mountopt;
/* check for a null handle */
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
33
34
{
printf(“error…mount handle is
null\n”);
35
36
37
38
39
return;
}
VS_Mount_GetFields ( mounth,
VSID_DRIVE_SELECT,
&driveselect,
40
VSID_MEDIA_SELECT,
&mediaselect,
601355 Rev A
API Functions
2-325
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
41
VSID_MOUNT_OPTION,
&mountopt,
42
43
44
VSID_ENDFIELD );
printf(“**** Mount Handle Values
****\n”);
45
46
47
48
49
switch ( driveselect )
{
case VSE_DRIVE_SELECT_ID:
VS_Mount_GetFields ( mounth,
VSID_DRIVE_ID,
&driveid,
50
51
VSID_ENDFIELD );
printf ( “Drive ID: %d\n”,
driveid );
52
53
54
55
break;
case VSE_DRIVE_SELECT_POOL:
VS_Mount_GetFields ( mounth,
VSID_DRIVEPOOL_NAME,
drivepool,
56
57
VSID_ENDFIELD );
printf ( “Drive Pool: %s\n”,
drivepool );
58
59
60
break;
default:
printf ( “error…incorrect
drive select value\n”);
break;
61
62
63
64
65
66
67
68
}
switch ( mediaselect )
{
case VSE_MEDIA_SELECT_ID:
VS_Mount_GetFields ( mounth,
VSID_MEDIA_ID,
mediaid,
69
70
VSID_ENDFIELD );
printf ( “Media ID: %s\n”,
mediaid );
71
72
73
break;
case VSE_MEDIA_SELECT_LIST:
printf ( “Media List:\n” );
2-326
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
75
76
VS_Mount_GetFields ( mounth,
VSID_MEDIA_ID_TABLE,
&tableh,
77
78
79
80
VSID_ENDFIELD );
VS_Table_GetFields ( tableh,
VSID_NUMBER_ENTRIES,
&size,
81
82
83
84
85
VSID_ENDFIELD );
for ( i = 0 ; i < size ; i++ )
{
VS_Table_GetFields (
tableh,
&mediaid,
86
VSID_TABLE_ENTRY, i,
VSID_ENDFIELD );
87
88
89
90
91
92
93
94
printf ( “%s”, mediaid );
}
break;
case VSE_MEDIA_SELECT_CLASS:
VS_Mount_GetFields(mounth,
VSID_MEDIA_CLASS_NAME,
mediaclass,
95
96
VSID_ENDFIELD);
printf( “Media Class: %s\n”,
mediaclass);
97
98
if (mountopt &
VSD_MOUNT_OPTION_RECLASS)
{
99
100
101
VS_Mount_GetFields(mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
targetmediaclass,
VSID_ENDFIELD );
printf(“Target Media Class:
%s\n”,
102
103
targetmediaclass );
}
104
601355 Rev A
API Functions
2-327
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
105
106
107
break;
default:
printf(“error …incorrect
media select
value\n”);
break;
108
109 }
110
111 if (mountopt &
VSD_MOUNT_OPTION_CRITERIA)
112 {
113
VS_Mount_GetFields(mounth,
114
VSID_CRITERIA_GROUP_HANDLE_TABLE,
&tableh,
115
116
117
118
VSID_ENDFIELD);
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&size,
119
120
121
122
123
124
VSID_ENDFIELD);
for (i = 0; i < size; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i,
&grouph,
125
126
127
VSID_ENDFIELD);
vst_print_criteria_group(grouph);
}
128
129 }
130 return;
131}
2-328
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-329
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Mount_SetFieldssets 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.
VS_Mount_
SetFields
VST_BOOLEAN VS_Mount_SetFields
(VST_MOUNT_HANDLE handle,
“…”,
Synopsis
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)
VSID_DRIVE_ID (VST_DRIVE_ID)
A criteria group to be used by the mount
command in selecting media for mounting.
Drive identifier to mount when mounting by
drive identifier. If VSID_DRIVE_IDis
specified, VSID_DRIVEPOOL_NAMEand
VSID_DRIVE_EXCL_LISTcannot be
specified.
2-330
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVEPOOL_NAME
(VS_DRIVE_POOL_NAME)
Drive pool group from which a drive is
selected to mount when mounting by drive
pool group. If VSID_DRIVEPOOL_NAMEis
specified, VSID_DRIVE_IDcannot 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)
(VST_DRIVE_ID *)
Number of drives to exclude from the specified
drive pool group when mounting by drive pool
group.
List of drives to exclude from the specified
drive pool group when mounting by drive pool
group.
VSID_LOCK_ID (VST_LOCK_ID)
VSID_MEDIA_ID (VST_MEDIA_ID)
Lock identifier that is required if a drive is
locked.
Identifier of the medium to be mounted when
mounting by medium identifier. If
VSID_MEDIA_IDis specified,
VSID_MEDIA_CLASS_NAMEand
VSID_MEDIA_ID_LISTcannot 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_NAMEis specified,
VSID_MEDIA_IDand
VSID_MEDIA_ID_LISTcannot 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_LISTis specified,
VSID_MEDIA_CLASS_NAMEand
VSID_MEDIA_IDcannot be specified.
601355 Rev A
API Functions
2-331
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues are listed
in the vs_defs.hfile.
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
VS_Mount_SetFieldsreturns:
• 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.
2-332
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_OUTOFRANGE- Specified entry does not exist
in the table’s range of values.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_create_mount_handle
4 *
5 * PURPOSE:
6 * This function creates the mount handle
and sets the
7 * values in it according to user input.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_MOUNT_HANDLE
vst_create_mount_handle ( void )
15 #else
16
VST_MOUNT_HANDLE
vst_create_mount_handle ()
17 #endif
18 {
19
20
21
22
int
int
i;
entry;
driveid;
VST_DRIVE_ID
VST_DRIVE_POOL_NAME
drivepool;
23
24
VST_MEDIA_ID
VST_MEDIA_CLASS_NAME
mediaclass;
VST_MOUNT_HANDLE
VST_CRITERIAGROUP_HANDLE grouph;
mediaid;
mounth;
25
26
27
28
29
30
/* create the handle */
mounth = VS_Mount_Create();
if ( mounth == (VST_MOUNT_HANDLE)
NULL )
601355 Rev A
API Functions
2-333
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
32
{
}
return ( (VST_MOUNT_HANDLE) NULL
);
33
34
35
/* prompt user for values */
printf ( “Mount by (1) Media ID or (2)
Media Class ==> “ );
36
37
38
39
40
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Media ID for
mounting ==> “ );
gets(mediaid);
41
42
43
44
45
46
47
48
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,
49
50
51
52
53
54
VSID_ENDFIELD );
printf ( “Reclassify media (1) yes
or (2) no ==> “ );
55
56
57
58
59
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Target Media
Class ==> “ );
60
61
62
gets(mediaclass);
VS_Mount_SetFields( mounth,
VSID_TARGET_MEDIA_CLASS_NAME,
mediaclass,
63
VSID_ENDFIELD );
2-334
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
64
65
66
}
}
printf ( “Mount by (1) Drive ID or (2)
Drive Pool ==> “ );
67
68
69
70
71
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter Drive ID for
mounting ==> “ );
driveid = atoi(gets(input));
VS_Mount_SetFields ( mounth,
VSID_DRIVE_ID,
72
73
74
driveid,
75
76
77
78
79
VSID_ENDFIELD );
}
else
{
printf ( “Enter Drive Pool for
mount ==> “ );
80
81
82
gets(drivepool);
VS_Mount_SetFields ( mounth,
VSID_DRIVEPOOL_NAME, drivepool,
VSID_ENDFIELD );
83
84
85
}
printf ( “Mount by criteria (1) yes
or (2) no ==> “ );
86
87
88
89
90
entry = atoi(gets(input));
if ( entry == 1 )
{
printf ( “Enter number of criteria
groups ==> “ );
91
92
93
94
95
entry = atoi(gets(input));
for ( i = 0 ; i < entry ; i++ )
{
/* create a criteria group
handle */
96
grouph =
vst_create_mount_criteria();
601355 Rev A
API Functions
2-335
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
97
if ( grouph !=
(VST_CRITERIAGROUP_HANDLE) NULL )
98
99
{
VS_Mount_SetFields (
mounth,
100
VSID_CRITERIA_GROUP_HANDLE, i,
grouph,
101
VSID_ENDFIELD );
102
103
}
}
104 }
105 return ( mounth );
106}
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.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
vsapi(l),
VS_Mount_Create(l),
VS_Mount_Destroy(l),
VS_Mount_GetFields(l),
VSCMD_Mount(l),
VSCMD_MultiMount(l)
601355 Rev A
API Functions
2-337
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_Createallocates a VolServ API notify handle.
A notify handle is used by the API to allow a client to listen for
MediaClass notifications.
VS_Notify_
Create
VST_NOTIFY_HANDLE VS_Notify_Create (void)
Synopsis
Arguments
None
Return Values
VS_Notify_Createreturns:
•
•
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.
Example
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
13
VST_BOOLEAN vst_notify( void )
14 #else
15
16
VST_BOOLEAN
vst_notify()
2-338
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
17 #endif
18 {
19
20
VST_BOOLEAN
int
done, rc;
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
VST_TABLE_HANDLE
VST_MEDIA_CLASS_NAME class,
newclass;
22
23
24
t;
table;
25
26
27
28
29
30
31
32
VST_NOTIFY_HANDLE
h;
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
printf(“*** Notify Parameters ***\n”
);
33
34
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
37
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
40
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
44
45
46
47
48
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
printf(“Number of Timeouts to process
==> “ );
49
timeout = atoi(gets(input));
601355 Rev A
API Functions
2-339
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
50
51
52
53
54
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
55
56
57
58
59
60
61
62
/* 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,
63
64
65
66
67
68
69
VSID_TIMEOUT_VALUE, t,
VSID_ENDFIELD );
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
70
71
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
72
73
74
75
76
77
78
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
79
80
81
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
82
83
break;
default:
2-340
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
84
printf(“Select Error
%d\n”, i );
85
86
87
88
89
90
91
92
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
93
94
95
96
97
98
if ( timeout <= 0 )
{
printf(“Timeout value
reached\n” );
99
done = VSE_TRUE;
100
101
}
}
102
103
104
/* destroy the notify handle */
VS_Notify_Destroy ( h );
105 }
106 else
107 {
108
rc = VSE_FALSE;
109 }
110
111 return ( rc );
112}
Notes
None
601355 Rev A
API Functions
2-341
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Notify_Destroy(l),
VS_Notify_GetFields(l),
VS_Notify_Listen(l),
VS_Notify_SetFields(l)
2-342
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_Destroydeallocates a VolServ API notify
handle that was allocated with VS_Notify_Create.
VS_Notify_
Destroy
VST_BOOLEAN VS_Notify_Destroy
(VST_NOTIFY_HANDLE notifyhandle)
Synopsis
Arguments
• notifyhandle= The notify handle to be destroyed.
Return Values
VS_Notify_Destroyreturns:
• 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.
Example
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
601355 Rev A
API Functions
2-343
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
13
VST_BOOLEAN vst_notify( void )
14 #else
15
16
VST_BOOLEAN
vst_notify()
17 #endif
18 {
19
20
VST_BOOLEAN
int
done, rc;
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
VST_TABLE_HANDLE
VST_MEDIA_CLASS_NAME class,
newclass;
22
23
24
t;
table;
25
26
27
28
29
30
31
32
VST_NOTIFY_HANDLE
h;
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
printf(“*** Notify Parameters ***\n”
);
33
34
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
37
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
40
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
44
45
46
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
2-344
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
47
48
printf(“Number of Timeouts to process
==> “ );
49
50
51
52
53
54
timeout = atoi(gets(input));
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
55
56
57
58
59
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
60
61
62
VSID_VERSION_NUMBER,
versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
63
64
65
66
67
68
69
VSID_TIMEOUT_VALUE,
VSID_ENDFIELD );
t,
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
70
71
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
72
73
74
75
76
77
78
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
601355 Rev A
API Functions
2-345
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
79
80
81
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
82
83
84
break;
default:
printf(“Select Error
%d\n”, i );
rc = VSE_FALSE;
85
86
87
88
89
90
91
92
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
93
94
95
96
97
98
if ( timeout <= 0 )
{
printf(“Timeout value
reached\n” );
99
done = VSE_TRUE;
100
101
}
}
102
103
104
/* destroy the notify handle */
VS_Notify_Destroy ( h );
105 }
106 else
107 {
108
rc = VSE_FALSE;
109 }
110
111 return ( rc );
112}
2-346
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
After VS_Notify_Destroyhas 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)
601355 Rev A
API Functions
2-347
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_GetFieldsretrieves information associated
with a notify handle. A notify handle is used by the API to
allow a client to listen for MediaClass notifications.
VS_Notify_
GetFields
VST_BOOLEAN VS_Notify_GetFields
(VST_NOTIFY_HANDLE handle,
“…”,
Synopsis
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 *)
VSID_DRIVE_ID_ENTRY (int)
Pointer to the drive identifier for this callback.
Index of a specific entry in the drive identifier
table.
2-348
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
(VST_DRIVE_ID *)
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)
VSID_MEDIA_ID_ENTRY (int)
(VST_MEDIA_ID *)
Pointer to the media identifier for this callback.
Number of media in the media identifier table.
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_TYPEvalues are enumerated
in the vs_types.h file.
VSID_NUMBER_DRIVE_IDS (int *)
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of drive ids present in
the drive id table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VS_Notify_GetFieldsreturns:
• 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.
2-350
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_notify_dispatch
4 *
5 * PURPOSE:
6 * This is the dispatch routine used to
test the
7 * notify loop.
8 *
9 * PARAMETERS:
10 * h : the notify handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
int
vst_notify_dispatch (
VST_NOTIFY_HANDLE h )
15 #else
16
17
int
vst_notify_dispatch ( h )
VST_NOTIFY_HANDLE h;
18 #endif
19 {
20
21
22
23
24
int
i, n;
VST_ARCHIVE_NAME
VST_DRIVE_ID
char
VST_MEDIA_CLASS_NAME
newclass;
archive;
* did;
* mid;
class,
25
26
27
28
29
30
VST_NOTIFY_TYPE
VST_ERROR_HANDLE
VST_TABLE_HANDLE
VST_STATUS_CODE
type;
eh;
dt, mt;
sc;
/* increment a counter for the number
of */
31
32
33
/* notifies processed */
NumNotifies++;
/* initialize values in the notify
handle. */
34
VS_Notify_GetFields ( h,
601355 Rev A
API Functions
2-351
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
35
36
37
38
VSID_NOTIFY_TYPE,
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
&type,
class,
VSID_TARGET_MEDIA_CLASS_NAME,
newclass,
39
40
41
VSID_DRIVE_ID_TABLE,
&dt,
VSID_MEDIA_ID_TABLE,
&mt,
VSID_ERROR_HANDLE,
&eh,
42
43
44
VSID_ENDFIELD );
printf(“***************** Notify
Handle Information
*************\\pn” );
45
46
printf(“Notify Type = %d\n”, type );
if ((type == VSE_NOTIFY_EJECT) ||
(type == VSE_NOTIFY_ENTER))
{
47
48
49
VS_Notify_GetFields ( h,
VSID_STATUS_CODE, &sc,
50
VSID_ENDFIELD );
51
52
53
54
55
56
if (sc == VSE_STATUS_OK)
printf(“Successful\n”);
else
printf(“Failure\n”);
}
printf(“Archive Name = %s\n”, archive
);
57
58
59
60
61
62
printf(“Media Class = %s\n”, class );
switch(type)
{
case VSE_NOTIFY_IMPORT:
case VSE_NOTIFY_EXPORT:
case VSE_NOTIFY_ENTER:
2-352
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
63
64
65
66
67
68
69
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);
}
70
71
72
73
if ( mt != (VST_TABLE_HANDLE)
NULL )
74
75
76
{
VS_Table_GetFields ( mt,
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD );
77
78
79
80
81
for ( i = 0 ; i < n ; i++ )
{
VS_Table_GetFields ( mt,
VSID_TABLE_ENTRY, i, &mid,
82
83
VSID_ENDFIELD
);
printf(“Media ID Entry #
%d = %s\n“,
i, mid );
84
85
86
87
88
89
}
}
break;
case VSE_NOTIFY_MOUNT:
case VSE_NOTIFY_DISMOUNT:
/* print the drive and media id
*/
90
91
VS_Notify_GetFields(h,
VSID_MEDIA_ID, mid,
VSID_DRIVE_ID, &did,
92
601355 Rev A
API Functions
2-353
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
93
VSID_ENDFIELD);
94
95
96
97
98
99
printf(“media id = %s\n”, mid);
printf(“drive id = %d\n”, did);
break;
default:
break;
}
100 /* print the error handle */
101 vst_print_error ( eh );
102}
Notes
The VSID_DRIVE_ID_ENTRYand 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-355
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_Listenlistens for MediaClass callbacks from
VolServ.
VS_Notify_
Listen
Client registers a notify dispatch routine with the API using
either the VS_Global_SetFieldsor the
VS_Notify_SetFieldsfunction. Client is then responsible
for putting the API into a “listening” state by calling
VS_Notify_Listen. VS_Notify_Listenterminates
either after receiving a MediaClass callback and notifying the
client’s notify dispatch routine or after timing out.
int VS_Notify_Listen (VST_NOTIFY_HANDLE handle)
Synopsis
Arguments
• handle= The notify handle used to listen for MediaClass
callbacks.
Return Values
VS_Notify_Listenreturns:
• 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.
2-356
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_TIMEOUT- The VolServ API timed out waiting
for MediaClass callbacks from VolServ.
Example
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
13
VST_BOOLEAN vst_notify( void )
14 #else
15
16
VST_BOOLEAN
vst_notify()
17 #endif
18 {
19
20
VST_BOOLEAN
int
done, rc;
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
VST_TABLE_HANDLE
VST_MEDIA_CLASS_NAME class,
newclass;
22
23
24
t;
table;
25
26
27
28
29
30
31
VST_NOTIFY_HANDLE
h;
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
601355 Rev A
API Functions
2-357
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
printf(“*** Notify Parameters ***\n”
);
33
34
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
37
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
40
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
44
45
46
47
48
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
printf(“Number of Timeouts to process
==> “ );
49
50
51
52
53
54
timeout = atoi(gets(input));
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
55
56
57
58
59
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
60
61
VSID_VERSION_NUMBER, versnum,
VSID_PROCEDURE_NUMBER,
procnum,
62
63
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
VSID_TIMEOUT_VALUE,
t,
2-358
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
64
65
66
67
68
69
VSID_ENDFIELD );
done = VSE_FALSE;
while ( ! done )
{
/* “listen” for callbacks and
act on the */
/* error code */
switch ( (i = VS_Notify_Listen(
h )) )
70
71
72
73
74
75
76
77
78
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
79
80
81
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
82
83
84
break;
default:
printf(“Select Error
%d\n”, i );
85
86
87
88
89
90
91
92
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
93
94
95
96
97
if ( timeout <= 0 )
{
601355 Rev A
API Functions
2-359
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
98
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
99
100
}
101
}
102
103
104
/* destroy the notify handle */
VS_Notify_Destroy ( h );
105 }
106 else
107 {
108
rc = VSE_FALSE;
109 }
110
111 return ( rc );
112}
Notes
Client uses VS_Notify_GetFieldsto access the MediaClass
callback information in a notify handle.
If a VSE_ERR_SIGNALis returned, any client error handling
routines that have been installed for that signal have been
called.
VS_Notify_Listenreturns error codes instead of the normal
VST_BOOLEANvalues (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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-361
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Notify_SetFieldssets the value of one or more fields
in a notify handle. A notify handle is used to pass notify
information to and from VolServ.
VS_Notify_
SetFields
VST_BOOLEAN VS_Notify_SetFields
(VST_NOTIFY_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
RPC program number of the client process
that the VolServ API calls when a MediaClass
callback is received. If
VSID_PROGRAM_NUMBERis not specified, the
program number defaults to 0. When
VSID_PROGRAM_NUMBERis 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_PROTOCOLis
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
VS_Notify_SetFieldsreturns:
• 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.
601355 Rev A
API Functions
2-363
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
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
13
VST_BOOLEAN vst_notify( void )
14 #else
15
16
VST_BOOLEAN
vst_notify()
17 #endif
18 {
19
20
VST_BOOLEAN
int
done, rc;
i, count,
timeout;
21
unsigned long
prognum,
versnum, procnum;
VST_TIME_OUT
VST_TABLE_HANDLE
VST_MEDIA_CLASS_NAME class,
newclass;
22
23
24
t;
table;
25
26
27
28
29
30
31
VST_NOTIFY_HANDLE
h;
rc = VSE_TRUE;
done = VSE_FALSE;
NumNotifies = 0;
/* get parameters from user */
2-364
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
printf(“*** Notify Parameters ***\n”
);
33
34
printf(“Program Number ==> “ );
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
35
36
37
printf(“Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
38
39
40
printf(“Procedure Number ==> “ );
procnum = (VST_PROCEDURE_NUMBER)
atol(gets(input));
41
42
printf(“Number of Notifies to listen
==> “ );
43
44
45
46
47
48
count = atoi(gets(input));
printf(“Timeout Value ==> “ );
t = atoi(gets(input));
printf(“Number of Timeouts to process
==> “ );
49
50
51
52
53
54
timeout = atoi(gets(input));
printf(“\nlistening…\n” );
/* create the notify handle */
if ( (h = VS_Notify_Create()) !=
(VST_NOTIFY_HANDLE) NULL )
{
55
56
57
58
59
/* initialize the notify handle */
VS_Notify_SetFields ( h,
VSID_PROTOCOL, VSE_PROT_TCP,
VSID_PROGRAM_NUMBER,
prognum,
60
61
62
VSID_VERSION_NUMBER,
versnum,
VSID_PROCEDURE_NUMBER,
procnum,
VSID_CLIENT_DISPATCH,
vst_notify_dispatch,
601355 Rev A
API Functions
2-365
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
63
64
65
66
67
68
69
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 )) )
70
71
72
73
74
75
76
77
78
{
case VSE_ERR_TIMEOUT:
printf(“Timed out\n” );
timeout--;
break;
case VSE_ERR_NONE:
/* This is the successful
case. */
79
80
81
/* Nothing is printed
here because */
/* the notify handle is
printed in */
/* vst_notify_dispatch
*/
82
83
84
break;
default:
printf(“Select Error
%d\n”, i );
85
86
87
88
89
90
91
92
rc = VSE_FALSE;
done = VSE_TRUE;
break;
}
if ( NumNotifies > count )
{
printf(“Number of Notifies
reached\n” );
done = VSE_TRUE;
}
93
94
95
96
if ( timeout <= 0 )
2-366
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
97
98
{
printf(“Timeout value
reached\n” );
done = VSE_TRUE;
99
100
}
101
}
102
103
104
/* destroy the notify handle */
VS_Notify_Destroy ( h );
105 }
106 else
107 {
108
rc = VSE_FALSE;
109 }
110
111 return ( rc );
112}
Notes
Client dispatch function must be prototypes as follows:
void NotifyClientDispatch (VST_NOTIFY_HANDLEhandle)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
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)
2-368
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Request_Create allocates a VolServ API request
handle. A request handle is used to pass request information to
and from VolServ.
VS_Request_
Create
VST_REQUEST_HANDLE VS_Request_Create (void)
Synopsis
Arguments
None
Return Values
VS_Request_Createreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_request_handle
4 *
5 * PURPOSE:
6 * This function tests a request handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_request_handle(void)
14 #else
15
VST_BOOLEAN vst_request_handle()
16 #endif
17 {
601355 Rev A
API Functions
2-369
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
18
19
20
21
22
23
24
25
26
27
28
29
30
VST_BOOLEAN
VST_REQUEST_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_REQUEST_STATE
VST_PRIORITY
rc = VSE_FALSE;
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”);
31
32
33
34
35
printf(“Enter request id ==> “);
RequestID = atol(gets(input));
printf(“Enter request type ==> “);
RequestType = atoi(gets(input));
printf(“Enter request state ==>
“);
36
37
38
39
40
41
State = atoi(gets(input));
printf(“Enter Priority ==> “);
Priority = atoi(gets(input));
/* set the fields */
rc = VS_Request_SetFields(h,
VSID_REQUEST_ID,
RequestID,
42
43
44
VSID_REQUEST_TYPE,
RequestType,
VSID_REQUEST_STATE,
State,
VSID_PRIORITY,
Priority,
45
VSID_ENDFIELD);
46
if (rc)
47
{
48
49
vst_print_request(h);
}
50
51
VS_Request_Destroy(h);
}
52
return(rc);
53 }
2-370
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
None
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Request_Destroy(l),
VS_Request_GetFields(l),
VS_Request_SetFields(l)
601355 Rev A
API Functions
2-371
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Request_Destroydeallocates 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.
VS_Request_
Destroy
VST_BOOLEAN VS_Request_Destroy
(VST_REQUEST_HANDLE handle)
Synopsis
Arguments
• handle= The request handle to be destroyed.
Return Values
VS_Request_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_request_handle
4 *
5 * PURPOSE:
6 * This function tests a request handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-372
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_request_handle(void)
14 #else
15
VST_BOOLEAN vst_request_handle()
16 #endif
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
VST_BOOLEAN
VST_REQUEST_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_REQUEST_STATE
VST_PRIORITY
rc = VSE_FALSE;
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”);
31
32
33
34
35
printf(“Enter request id ==> “);
RequestID = atol(gets(input));
printf(“Enter request type ==> “);
RequestType = atoi(gets(input));
printf(“Enter request state ==>
“);
36
37
38
39
40
41
State = atoi(gets(input));
printf(“Enter Priority ==> “);
Priority = atoi(gets(input));
/* set the fields */
rc = VS_Request_SetFields(h,
VSID_REQUEST_ID,
RequestID,
42
43
44
45
VSID_REQUEST_TYPE,
RequestType,
VSID_REQUEST_STATE,
State,
VSID_PRIORITY,
Priority,
VSID_ENDFIELD);
601355 Rev A
API Functions
2-373
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
if (rc)
{
48
vst_print_request(h);
49
}
50
VS_Request_Destroy(h);
51
}
52
return(rc);
53 }
Notes
After VS_Request_Destroyhas 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Request_GetFieldsretrieves information associated
with a request handle. A request handle is used to pass request
information to and from VolServ.
VS_Request_
GetFields
VST_BOOLEAN VS_Request_GetFields
(VST_REQUEST_HANDLE handle,
“…”,
Synopsis
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_STATEvalues are
enumerated in the vs_types.h file.
601355 Rev A
API Functions
2-375
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_REQUEST_TYPE
(VST_REQUEST_TYPE *)
Pointer to the request type of the request.
Valid VSID_REQUEST_TYPEvalues are
enumerated in the vs_types.h file.
VSID_TIME (VST_TIME *)
Pointer to the arrival time of the request.
Return Values
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.
Example
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 ****************************************
*********/
2-376
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
13 #ifdef ANSI_C
14
void
vst_print_request(VST_REQUEST_HAN
DLE h)
15 #else
16
17
void vst_print_request(h)
VST_REQUEST_HANDLE h;
18 #endif
19 {
20
21
22
23
24
25
26
27
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_TIME
VST_REQUEST_STATE
VST_PRIORITY
RequestID;
RequestType;
InTime;
State;
Priority;
VS_Request_GetFields(h,
VSID_REQUEST_ID,
&RequestID,
VSID_REQUEST_TYPE,
&RequestType,
VSID_TIME,
28
29
30
31
&InTime,
VSID_REQUEST_STATE,
&State,
VSID_PRIORITY,
&Priority,
VSID_ENDFIELD);
printf(“******Request
Handle******\n”);
32
33
34
35
36
37
printf(“Request ID = %d\n”,
RequestID);
printf(“Request Type = %d\n”,
RequestType);
printf(“Time = %s”, ctime((time_t *)
&InTime));
printf(“Request state = %d\n”,
State);
38
printf(“Priority = %d\n”, Priority);
39 }
601355 Rev A
API Functions
2-377
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
VSID_TIMEis 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
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Request_Create(l),
VS_Request_Destroy(l),
VS_Request_SetFields(l),
VSCMD_RequestQuery(l)
2-378
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Request_SetFieldssets the value of one or more
fields in a request handle. A request handle is used to pass
request information to and from VolServ.
VS_Request_
SetFields
VST_BOOLEAN VS_Request_SetFields
(VST_REQUEST_HANDLE handle,
“…”,
Synopsis
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
Description
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.
601355 Rev A
API Functions
2-379
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_REQUEST_ID (VST_REQUEST_ID)
Identifier of the request (assigned by VolServ)
associated with the specified request handle.
A valid request identifier must be specified in
the yyyyddmmformat where yyyy
represents the year, ddrepresents the day,
and mmis a month.
VSID_REQUEST_STATE
(VST_REQUEST_STATE)
The execution state of the request. Valid
VSID_REQUEST_STATEvalues 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
VS_Request_SetFieldsreturns:
• 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.
2-380
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_request_handle
4 *
5 * PURPOSE:
6 * This function tests a request handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_request_handle(void)
14 #else
15
VST_BOOLEAN vst_request_handle()
16 #endif
17 {
18
19
20
21
22
23
24
25
26
27
28
29
30
VST_BOOLEAN
VST_REQUEST_HANDLE h;
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_REQUEST_STATE
VST_PRIORITY
rc = VSE_FALSE;
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”);
31
32
33
34
35
printf(“Enter request id ==> “);
RequestID = atol(gets(input));
printf(“Enter request type ==> “);
RequestType = atoi(gets(input));
printf(“Enter request state ==>
“);
36
37
38
State = atoi(gets(input));
printf(“Enter Priority ==> “);
Priority = atoi(gets(input));
601355 Rev A
API Functions
2-381
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
40
41
/* set the fields */
rc = VS_Request_SetFields(h,
VSID_REQUEST_ID,
RequestID,
42
43
44
VSID_REQUEST_TYPE,
RequestType,
VSID_REQUEST_STATE,
State,
VSID_PRIORITY,
Priority,
45
46
VSID_ENDFIELD);
if (rc)
47
{
48
49
vst_print_request(h);
}
50
VS_Request_Destroy(h);
51
}
52
return(rc);
53 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Request_Create(l),
S_Request_Destroy(l),
VS_Request_GetFields(l)
2-382
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Selectrequests the VolServ API to wait for command
status from VolServ when the API in operating in asynchronous
mode.
VS_Select
In asynchronous mode, the client issues a VolServ command
through the API, immediately receives initial status for the
command, issues VS_Selectto 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_Selectfunction
terminates. It is the client’s responsibility to issue the
VS_Selectfor each intermediate and final status expected for
a command.
int VS_Select (void)
None
Synopsis
Arguments
Return Values
VS_Selectreturns:
• 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.
601355 Rev A
API Functions
2-383
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_select
4 *
5 * PURPOSE:
6 * This function tests the VS_Select
loop.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_select ( void )
14 #else
15
VST_BOOLEAN vst_select ()
16 #endif
17 {
18
19
20
21
22
23
24
25
VST_BOOLEAN
int
rc = VSE_FALSE;
errcode;
errcode = VS_Select();
switch (errcode)
{
case VSE_ERR_NONE:
printf(“*** No Error --
Successful Operation ***\n“);
rc = VSE_TRUE;
26
27
28
29
break;
case VSE_ERR_TIMEOUT:
printf(“*** Select Timed Out
***\n”);
30
break;
2-384
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
32
default:
printf(“*** A Select Error
Occurred ***\n”);
break;
33
34
}
35
return(rc);
36 }
Notes
VS_Selectcalls fail if VS_Initializehas not been
invoked.
VS_Selectis used only when the API is operating in
asynchronous mode. Therefore, clients that use synchronous
processing do not use the VS_Select routine.
The VolServ API uses the client dispatch routine identification
information, set with the VS_Global_SetDefaultsfunction
or with the command default function, to determine which
routine to notify when intermediate and final command status is
received.
The total amount time the API waits for status is
VSID_TIMEOUT_VALUE.
VS_Selectreturns error codes instead of the normal
VST_BOOLEANvalues (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
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetDefaults(l),
VS_Initialize(l)
601355 Rev A
API Functions
2-385
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Status_GetFieldsretrieves information associated
with a status handle. A status handle is used to pass status
information to and from VolServ.
VS_Status_
GetFields
VST_BOOLEAN VS_Status_GetFields
(VST_STATUS_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_ACTION_CODE
(VST_ACTION_CODE *)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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
(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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_STATEvalues are
enumerated in the vs_types.hfile.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVE_ID (VST_DRIVE_ID *)
Pointer to the first drive identifier in the drive
identifier table.
VSID_DRIVE_ID_ENTRY (int)
(VST_DRIVE_ID *)
Index of the appropriate drive identifier in the
drive identifier table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_FIELD_ENTRY (int)
(int *)
The index of the appropriate field in the
user-defined media statistics field table.
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)
VSID_MEDIA_ID_ENTRY (int)
(VST_MEDIA_ID *)
Pointer to the first media identifier in the media
identifier table.
The index of the appropriate entry in the
media identifier table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
(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
(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
Download from Www.Somanuals.com. All Manuals Search And Download.
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 *)
VSID_NUMBER_MEDIA_IDS (int *)
Pointer to the number of media handles
present in the media handle table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_CODEvalues 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_TYPEvalues 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_FIELDis 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_REASONvalues are
enumerated in the vs_types.hfile.
601355 Rev A
API Functions
2-393
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Status_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediaquery_execute_sync
4 *
5 * PURPOSE:
6 * This executes the VSCMD_MediaQuery API
call in a
7 * synchronous mode. It shows how to
process status
8 * in synchronous mode without using a
dispatch
9 * routine.
10 *
11 * PARAMETERS:
12 * none
13 *
14 ****************************************
*********/
2-394
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
VST_QUERY_OPTION
int
int
char
rc = VSE_FALSE;
queryopt;
i;
count;
*
22
23
24
25
medialist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE cmd;
26
27
28
VST_STATUS_HANDLE
VST_TABLE_HANDLE
mediahandletable;
VST_MEDIA_HANDLE
status;
29
30
31
32
media;
/* get parameters from user */
printf(“*** Media Query parameters
***\n” );
33
printf(“0) Query by media list, 1)
Query all ==> “ );
34
35
36
37
38
queryopt = atoi(gets(input));
if (queryopt == 0)
{
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
}
39
40
41
42
/* create the command handle */
/* Note that the command handle is
not */
43
44
45
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
*/
/* received */
601355 Rev A
API Functions
2-395
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
48
49
{
/* Send the command to the VolServ
software. */
50
51
/* Note that status is not
processed here. */
/* Instead,it is processed in the
*/
52
53
/* vst_dispatch routine. */
/* Also, note that default values,
such as */
54
55
/* timeout, value retry limit, and
priority */
/* are set as default parameters.
*/
56
57
58
rc = VSCMD_MediaQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_MEDIA_ID_LIST, count,
medialist,
59
60
61
VSID_CLIENT_DISPATCH, NULL,
/* no dispatch routine */
VSID_STATUS_WAIT_FLAG,
VSE_TRUE,
62
63
64
65
66
/* synchronous mode */
VSID_ENDFIELD);
if (rc)
{
/* the command was successful
*/
67
68
69
/* get the status */
VS_Command_GetFields(cmd,
VSID_STATUS_HANDLE, &status,
VSID_ENDFIELD);
70
71
72
/* get the media handle table
from the */
73
74
/* status handle */
VS_Status_GetFields(status,
2-396
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
75
VSID_MEDIA_HANDLE_TABLE
&mediahandletable,
76
77
78
VSID_ENDFIELD);
/* Get the number of entries in
the table */
79
80
VS_Table_GetFields(mediahandletab
le,
VSID_NUMBER_ENTRIES, &count
VSID_ENDFIELD);
81
82
83
/* loop through the table and
print out */
84
85
86
87
/* the entries */
for (i = 0; i < count; i++)
{
VS_Table_GetFields(mediahandletab
le,
88
VSID_TABLE_ENTRY,
i, &media,
89
VSID_ENDFIELD);
90
vst_print_media(media);
91
}
92
}
93
94
/* destroy the command */
VS_Command_Destroy(cmd);
95
}
96
return ( rc );
97 }
Notes
The parameters listed below require that two arguments be
passed instead of one.
•
The first argument passed is the index of the entry in the
appropriate table.
601355 Rev A
API Functions
2-397
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDand VSID_REQUEST_IDparameters are
valid status handle fields for all VolServ requests.
The status fields that are valid for each command are identified
in the “Notes” paragraphfor that command. A matrix
showing which status fields are valid for which commands is in
Appendix A.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
vsapi(l),
VS_Command_GetFields(l),
VS_Error_GetFields(l)
601355 Rev A
API Functions
2-399
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_AddEntryadds an entry to the specified table at
the first available location.
VS_Table_
AddEntry
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.
VST_BOOLEAN VS_Table_AddEntry
(VST_TABLE_HANDLE handle,
void * entry)
Synopsis
Arguments
• handle= Handle of the table where an entry is added.
• entry= Pointer to the data to be stored in the table.
Return Values
VS_Table_AddEntryreturns:
• 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.
2-400
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
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
20
21
int
int
VST_BOOLEAN
i;
count;
rc =
VSE_FALSE;
22
23
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
24
25
26
27
28
29
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
VST_PRIORITY
capacity;
highmark;
lowmark;
migpri;
VST_ARCHIVE_NAME
targetarchive;
601355 Rev A
API Functions
2-401
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
31
32
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
ST_COMPONENT_ID
33
34
35
36
CompID;
cmd;
VST_COMMAND_HANDLE
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
39
40
41
printf(“Enter Media Class Name ==> “
);
42
43
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
44
45
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
46
47
48
49
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
50
51
52
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
53
54
{
/* these parameters only need to
be set */
55
/* if the archivemediaclass is
being */
56
57
/* set up to support migration */
printf(“Enter Target Archive ==> “
);
2-402
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
58
59
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
60
61
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
62
63
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
64
65
66
67
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
68
69
70
71
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
72
if (comphandletable
==(VST_TABLE_HANDLE)NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
73
74
75
76
77
78
79
80
81
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
82
83
84
CompID[3] = 0;
comphandle =
VS_Component_Create();
601355 Rev A
API Functions
2-403
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
85
VS_Component_SetFields(comphandle
,
86
87
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
88
89
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
90
91
}
/* This also only needs to be set
if it is */
92
93
94
/* actually being used. */
/* It is not needed otherwise. */
VSCMD_CreateArchiveMediaClass_Set
Defaults(
95
VSID_COMPONENT_HANDLE_TABLE
comphandletable,
96
97
98
99
VSID_ENDFIELD);
}
/* create the command handle */
100 /* Notethatthecommand handle is not
destroyed */
101 /* in this routine, but in
vst_dispatch */
102 /* when final status is received. */
103 cmd = VS_Command_Create();
104 if (cmd != (VST_COMMAND_HANDLE )NULL)
105 {
106
107
108
109
/* 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 */
2-404
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
110
111
112
/* timeout value retry limit, and
priority */
/* are set as default parameters.
*/
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
113
114
115
116
117
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
118
VSID_ENDFIELD);
119 }
120
121 return ( rc );
122}
Notes
A table cannot store NULL pointers.
VS_Table_AddEntrydetermines 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
VS_Table_Create(l),
VS_Table_Destroy(l),
VS_Table_GetFields(l),
VS_Table_SetFields(l),
VS_Table_CreateAddEntry(l),
VS_Table_RemoveEntry(l)
2-406
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_Createallocates a VolServ API table handle. A
table handle is used to pass table information to and from
VolServ.
VS_Table_
Create
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)
Synopsis
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
VS_Table_Createreturns:
•
•
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.
601355 Rev A
API Functions
2-407
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
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
20
21
int
int
VST_BOOLEAN
i;
count;
rc =
VSE_FALSE;
22
23
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
24
25
26
27
28
29
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
VST_PRIORITY
capacity;
highmark;
lowmark;
migpri;
VST_ARCHIVE_NAME
targetarchive;
2-408
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
31
32
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
ST_COMPONENT_ID
33
34
35
36
CompID;
cmd;
VST_COMMAND_HANDLE
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
39
40
41
printf(“Enter Media Class Name ==> “
);
42
43
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
44
45
46
47
48
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
49
50
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
51
52
53
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
54
55
{
/* these parameters only need to
be set */
56
/* if the archivemediaclass is
being */
57
58
/* set up to support migration. */
printf(“Enter Target Archive ==> “
);
601355 Rev A
API Functions
2-409
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
59
60
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
61
62
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
63
64
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
65
66
67
68
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
69
70
71
72
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
73
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
74
75
76
77
78
79
80
81
82
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
83
84
85
CompID[3] = 0;
comphandle =
VS_Component_Create();
2-410
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
86
VS_Component_SetFields(comphandle
,
87
88
VSID_COMP_TYPE,
CompType,
VSID_COMP_ID,
CompID,
89
90
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
91
92
}
/* This also only needs to be set
if it is */
93
94
95
/* actually being used. */
/* It is not needed otherwise. */
VSCMD_CreateArchiveMediaClass_Set
Defaults(
96
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
97
98
99
VSID_ENDFIELD);
}
100 /* create the command handle */
101 /* Notethatthecommand handleis not
destroyed*/
102 /* in this routine, but in
vst_dispatch when */
103 /* final status is received. */
104 cmd = VS_Command_Create();
105 if (cmd != (VST_COMMAND_HANDLE )NULL)
106 {
107
108
109
110
/* 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 */
601355 Rev A
API Functions
2-411
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
111
112
113
/* such as timeout, value retry
limit, and */
/* priority are set as default
parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
114
115
116
117
118
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
119
VSID_ENDFIELD);
120 }
121
122 return ( rc );
123}
Notes
Client adds entries with the VS_Table_AddEntry,
VS_Table_SetFields, and/or
VS_Table_CreateAddEntryfunctions.
When a client adds an entry to a table using the
VS_Table_AddEntryor 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_CreateAddEntryfunction, 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Client deletes entries from a table with the
VS_Table_RemoveEntryfunction. If the entry to be
deleted from the table was added with either the
VS_Table_AddEntryor 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_CreateAddEntryfunction, 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)
601355 Rev A
API Functions
2-413
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_CreateAddEntryadds an entry to the
specified table at the first available location.
VS_Table_
CreateAdd-
Entry
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.
VST_BOOLEAN VS_Table_CreateAddEntry
(VST_TABLE_HANDLE handle,
void * entry,
Synopsis
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
VS_Table_CreateAddEntryreturns:
• 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.
2-414
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_table_handle
4 *
5 * PURPOSE:
6 * This function tests the table handle.
7 *
8 * PARAMETERS:
9 * none
10 *
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;
VST_TABLE_HANDLE
int
19
20
21
22
tableh;
numdrives;
i;
int
VST_DRIVE_ID
= 9999;
testdriveid
23
24
25
int
numentries;
* ip;
VST_DRIVE_ID
601355 Rev A
API Functions
2-415
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
26
printf(“*** Table Handle test
***\n”);
27
28
29
30
31
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
34
35
36
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
}
37
38
/* get the number of entries in the
table */
39
40
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
41
42
VSID_ENDFIELD);
/* loop through the table and print
the entries */
43
44
45
46
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY,
i, &ip,
47
48
VSID_ENDFIELD);
/* remove the entry from the table
*/
49
50
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
51
52
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
53
54
2-416
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
55
printf(“Drive ID #%d = %d\n”, i,
*ip);
56
}
57
58
59
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
60 }
Notes
A table cannot store NULL pointers.
VS_Table_CreateAddEntrydetermines the location in the
table to store the 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
th
is stored in position 1, and the n entry in a table is stored in
position n-1.
See Also
•
•
•
•
•
•
VS_Table_AddEntry(l),
VS_Table_Create(l),
VS_Table_Destroy(l),
VS_Table_GetFields(l),
VS_Table_RemoveEntry(l),
VS_Table_SetFields(l)
601355 Rev A
API Functions
2-417
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_Destroydeallocates a VolServ API table handle
that was allocated with the VS_Table_Createfunction. A
table handle is used to pass table information to and from
VolServ.
VS_Table_
Destroy
VST_BOOLEAN VS_Table_Destroy
(VST_TABLE_HANDLE handle)
Synopsis
Arguments
• handle= The table handle to be destroyed.
Return Values
VS_Table_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_table_handle
4 *
5 * PURPOSE:
6 * This function tests the table handle.
7 *
8 * PARAMETERS:
9 * none
10 *
2-418
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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;
VST_TABLE_HANDLE
int
19
20
21
22
tableh;
numdrives;
i;
int
VST_DRIVE_ID
= 9999;
testdriveid
23
24
25
26
int
numentries;
* ip;
VST_DRIVE_ID
printf(“*** Table Handle test
***\n”);
27
28
29
30
31
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
34
35
36
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
}
37
38
/* get the number of entries in the
table */
39
40
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
41
42
VSID_ENDFIELD);
/* loop through the table and print
the entries */
601355 Rev A
API Functions
2-419
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
45
46
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i, &ip,
47
48
VSID_ENDFIELD);
/* remove the entry from the table
*/
49
50
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
51
52
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
53
54
55
printf(“Drive ID #%d = %d\n”, i,
*ip);
56
}
57
58
59
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
60 }
Notes
After VS_Table_Destroyhas 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_SetFieldsfunctions, 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_Destroyfunction 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)
601355 Rev A
API Functions
2-421
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_GetFieldsretrieves information associated
with a table handle. A table handle is used to pass table
information to and from VolServ.
VS_Table_Get
Fields
VST_BOOLEAN VS_Table_GetFields
(VST_TABLE_HANDLE handle,
“…”,
Synopsis
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 *)
VSID_TABLE_ENTRY (int)
(void **)
Pointer to the number of entries in the table.
Index of a specific entry in the table.
Pointer to a specific entry in the table.
2-422
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Table_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_print_drivepool
4 *
5 * PURPOSE:
6 * This function prints out the
information stored in
7 * a drive pool handle.
8 *
9 * PARAMETERS:
10 * h : the drive pool handle to print
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
601355 Rev A
API Functions
2-423
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
14
void
vst_print_drivepool(VST_DRIVEPOOL
_HANDLE h)
15 #else
16
17
void vst_print_drivepool(h)
VST_DRIVEPOOL_HANDLE h;
18 #endif
19 {
20
21
VST_DRIVE_POOL_NAME DrivePoolName;
VST_TABLE_HANDLE
DriveHandleTable;
VST_DRIVE_HANDLE
int
22
23
24
25
26
27
DriveHandle;
i;
n;
int
VS_DrivePool_GetFields(h,
VSID_DRIVEPOOL_NAME,
DrivePoolName,
28
VSID_DRIVE_HANDLE_TABLE,
&DriveHandleTable,
VSID_ENDFIELD);
29
30
printf(“DrivePoolName =
%s\n”,DrivePoolName);
/* Get # of entries */
if ( DriveHandleTable !=
(VST_TABLE_HANDLE) NULL )
{
31
32
33
34
VS_Table_GetFields(DriveHandleTab
le,
35
VSID_NUMBER_ENTRIES, &n,
VSID_ENDFIELD);
for ( i = 0; i < n; i++)
{
36
37
38
39
VS_Table_GetFields(DriveHandleTab
le,
40
VSID_TABLE_ENTRY, i,
&DriveHandle,
41
42
VSID_ENDFIELD);
vst_print_drive(DriveHandle);
2-424
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_GetFieldsallows the user to
access the entries in the table.
The VSID_TABLE_ENTRYparameter 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
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
601355 Rev A
API Functions
2-425
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_RemoveEntryremoves an entry from the
specified VolServ API table. A table handle is used to pass table
information to and from VolServ.
VS_Table_
RemoveEntry
VST_BOOLEAN VS_Table_RemoveEntry
(VST_TABLE_HANDLE handle,
void * entry)
Synopsis
Arguments
• handle= Handle of the table where the entry is removed.
• entry= Pointer to the entry to be removed from the table.
Return Values
VS_Table_RemoveEntryreturns:
• 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.
2-426
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_table_handle
4 *
5 * PURPOSE:
6 * This function tests the table handle.
7 *
8 * PARAMETERS:
9 * none
10 *
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;
VST_TABLE_HANDLE
int
19
20
21
22
tableh;
numdrives;
i;
int
VST_DRIVE_ID
= 9999;
testdriveid
23
24
25
26
int
numentries;
* ip;
VST_DRIVE_ID
printf(“*** Table Handle test
***\n”);
27
28
29
30
31
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
34
35
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
601355 Rev A
API Functions
2-427
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
36
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
37
38
}
/* get the number of entries in the
table */
39
40
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
41
42
VSID_ENDFIELD);
/* loop through the table and print
the entries */
43
44
45
46
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i, &ip,
VSID_ENDFIELD);
/* remove the entry from the table
*/
47
48
49
50
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
51
52
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
53
54
55
printf(“Drive ID #%d = %d\n”, i,
*ip);
56
}
57
58
59
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
60 }
2-428
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
VS_Table_RemoveEntryverifies 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 entrymatches the
data pointed to by the corresponding table entry. As long as the
pointer values match, VS_Table_RemoveEntryremoves
the entry from the table.
If a client adds entries to a table using VS_Table_AddEntry
or VS_Table_SetFieldsfunctions, 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.
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_Destroyfunction is
called.
See Also
•
•
•
•
•
•
VS_Table_AddEntry(l),
VS_Table_Create(l),
VS_Table_CreateAddEntry(l),
VS_Table_Destroy(l),
VS_Table_GetFields(l),
VS_Table_SetFields(l)
601355 Rev A
API Functions
2-429
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Table_SetFieldsadds an entry to the specified table
at the specified location.
VS_Table_Set
Fields
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.
VST_BOOLEAN VS_Table_GetFields
(VST_TABLE_HANDLE handle,
“…”,
Synopsis
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)
VSID_TABLE_ENTRY (int)
Number of entries in the table.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_Table_GetFieldsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_table_handle
4 *
5 * PURPOSE:
6 * This function tests the table handle.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_table_handle(void)
14 #else
601355 Rev A
API Functions
2-431
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
15
VST_BOOLEAN vst_table_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_TRUE;
VST_TABLE_HANDLE
int
19
20
21
22
tableh;
numdrives;
i;
int
VST_DRIVE_ID
= 9999;
testdriveid
23
24
25
26
int
numentries;
* ip;
VST_DRIVE_ID
printf(“*** Table Handle test
***\n”);
27
28
29
30
31
printf(“How many drives? “);
numdrives = atoi(gets(input));
/* create the table handle */
tableh =
VS_Table_Create(VSE_INTEGER_PTR,
numdrives);
32
33
34
35
36
/* generate drive ids */
for (i = 0; i < numdrives; i++)
{
VS_Table_CreateAddEntry(tableh,
&i, sizeof(VST_DRIVE_ID));
}
37
38
/* get the number of entries in the
table */
39
40
VS_Table_GetFields(tableh,
VSID_NUMBER_ENTRIES,
&numentries,
41
42
VSID_ENDFIELD);
/* loop through the table and print
the entries */
43
44
45
46
for (i = 0; i < numentries; i++)
{
VS_Table_GetFields(tableh,
VSID_TABLE_ENTRY, i, &ip,
2-432
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
47
48
VSID_ENDFIELD);
/* remove the entry from the table
*/
49
50
VS_Table_RemoveEntry(tableh, ip);
/* set this entry to a NULL
pointer */
51
52
VS_Table_SetFields(tableh,
VSID_TABLE_ENTRY, i, NULL,
VSID_ENDFIELD);
/* print the value retrieved from
the table */
53
54
55
printf(“Drive ID #%d = %d\n”, i,
*ip);
56
}
57
58
59
/* destroy the table */
VS_Table_Destroy(tableh);
return(rc);
60 }
Notes
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_ENTRYparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
•
•
•
•
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)
2-434
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_Terminateterminates the VolServ API software.
VS_Terminatereleases all memory allocated by the API and
VS_Terminate
deregisters and frees all RPC transports.
VST_BOOLEAN VS_Terminate (void)
None
Synopsis
Arguments
Return Values
VS_Terminatereturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_terminate
4 *
5 * PURPOSE:
6 * This function shuts down the VolServ
API.
7 *
8 * PARAMETERS:
9 * none
10 *
601355 Rev A
API Functions
2-435
Download from Www.Somanuals.com. All Manuals Search And Download.
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
21
rc = VS_Terminate();
return(rc);
22 }
Notes
All command functions fail after VS_Terminatehas been
invoked.
See Also
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Initialize(l)
2-436
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_TypeCapacity_Createallocates a VolServ API
VS_
TypeCapacity
_Create
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.
VST_TYPECAPACITY_HANDLE VS_TypeCapacity_Create
(void)
Synopsis
Arguments
None
Return Values
VS_TypeCapacity_Createreturns:
•
•
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.
Example
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
601355 Rev A
API Functions
2-437
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
13
VST_BOOLEAN
vst_typecapacity_handle(void)
14 #else
15
VST_BOOLEAN
vst_typecapacity_handle()
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
VST_TYPECAPACITY_HANDLE
VST_MEDIA_TYPE_NAME
MediaType;
rc =
h;
19
20
21
22
VST_CAPACITY
VST_HIGH_MARK
Capacity;
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
23
24
25
26
int AssignedBins;
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
27
28
29
30
31
VST_BOOLEAN
AutoCheckinFlag;
VST_BOOLEAN
AutoImportFlag;
VST_BATCH_NAME
ImportBatch;
VST_MANUFACTURER_NAME
ImportManufacturer;
VST_MEDIA_CLASS_NAME
ImportClass;
32
33
34
35
/* create the handle */
h = vS_TypeCapacity_Create();
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
36
37
38
{
/* get values from user */
printf(“Enter media type name ==>
“);
39
gets(MediaType);
2-438
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
40
41
42
43
44
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
45
46
47
48
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
49
50
51
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
52
53
54
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
55
56
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
57
58
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
59
60
61
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
62
63
64
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
65
66
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
601355 Rev A
API Functions
2-439
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
67
68
69
70
71
72
73
74
75
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)
76
77
78
{
79
80
vst_print_typecapacity(h);
}
81
VS_TypeCapacity_Destroy(h);
82
}
83
return(rc);
84 }
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_TypeCapacity_Destroydeallocates 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.
VS_
TypeCapacity
_Destroy
VST_BOOLEAN VS_TypeCapacity_Destroy
(VST_TYPECAPACITY_HANDLE handle)
Synopsis
Arguments
• handle= The type capacity handle to be destroyed.
Return Values
VS_TypeCapacity_Destroyreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_typecapacity_handle
4 *
5 * PURPOSE:
6 * This function tests a typecapacity
handle.
7 *
8 * PARAMETERS:
9 * none
601355 Rev A
API Functions
2-441
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSE_FALSE;
VST_TYPECAPACITY_HANDLE
VST_MEDIA_TYPE_NAME
MediaType;
rc =
h;
19
20
21
22
VST_CAPACITY
VST_HIGH_MARK
Capacity;
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
23
24
25
26
int AssignedBins;
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
27
28
29
30
31
VST_BOOLEAN
AutoCheckinFlag;
VST_BOOLEAN
AutoImportFlag;
VST_BATCH_NAME
ImportBatch;
VST_MANUFACTURER_NAME
ImportManufacturer;
VST_MEDIA_CLASS_NAME
ImportClass;
32
33
34
35
/* create the handle */
h = vS_TypeCapacity_Create();
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
{
36
2-442
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
37
38
/* get values from user */
printf(“Enter media type name ==>
“);
39
40
41
42
43
44
gets(MediaType);
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
45
46
47
48
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
49
50
51
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
52
53
54
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
55
56
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
57
58
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
59
60
61
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
62
63
64
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
601355 Rev A
API Functions
2-443
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
65
66
67
68
69
70
71
72
73
74
75
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)
76
77
78
{
79
80
vst_print_typecapacity(h);
}
81
VS_TypeCapacity_Destroy(h);
82
}
83
return(rc);
84 }
Notes
After VS_TypeCapacity_Destroyhas been called for a type
capacity handle, that handle is no longer valid and should not be
used.
2-444
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_TypeCapacity_Create(l),
VS_TypeCapacity_GetFields(l),
VS_TypeCapacity_SetFields(l)
601355 Rev A
API Functions
2-445
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_TypeCapacity_GetFieldsretrieves 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.
VS_
TypeCapacity
_GetFields
VST_BOOLEAN VS_TypeCapacity_GetFields
(VST_TYPECAPACITY_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_OPTION*)
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_ACTIONvalues are
enumerated in the vs_types.h file.
2-446
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_ASSIGNED_BINS (VST_COUNT *)
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 *)
VSID_HIGH_MARK (VST_HIGH_MARK *)
Pointer to the current number of media of this
media type classification in this archive.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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. Leading and trailing spaces
are not permitted.
Return Values
VS_TypeCapacity_GetFieldreturns:
• 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.
Example
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 ****************************************
*********/
2-448
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
13 #ifdef ANSI_C
14
void
vst_print_typecapacity(VST_TYPECA
PACITY_HANDLEh)
15 #else
16
17
void vst_print_typecapacity(h)
VST_TYPECAPACITY_HANDLE h;
18 #endif
19 {
20
VST_MEDIA_TYPE_NAME
MediaType;
VST_CAPACITY
VST_HIGH_MARK
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
21
22
Capacity;
23
24
25
26
27
28
29
30
31
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;
32
33
34
VS_TypeCapacity_GetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
35
36
37
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
VSID_MANUFACTURER,
ImportManufacturer,
601355 Rev A
API Functions
2-449
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
38
39
40
41
42
43
44
45
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,
46
47
VSID_ENDFIELD);
printf(“******* Type Capacity Handle
*******\n”);
48
printf(“Media type = %s\n”,
MediaType);
49
50
printf(“Capacity = %d\n”, Capacity);
printf(“High Mark Percent = %d\n”,
HighMarkPercent);
51
52
53
54
55
56
57
58
59
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);
2-450
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
60 }
Notes
The migration policy options for VSID_HIGH_MARKare 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:
•
•
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
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)
2-452
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VS_TypeCapacity_SetFieldssets 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.
VS_
TypeCapacity
_SetFields
VST_BOOLEAN VS_TypeCapacity_SetFields
(VST_TYPECAPACITY_HANDLE handle,
“…”,
Synopsis
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_ACTIONvalues are
enumerated in the vs_types.hfile.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_FILL_LEVEL (VST_FILL_LEVEL)
VSID_HIGH_MARK (VST_HIGH_MARK)
Maximum number of media of this media type
classification that can be in this archive.
Current number of media of this media type
classification in this archive.
Percentage of VSID_CAPACITYabove which
the specified migration policy option is
performed or initiated.
VSID_LOW_MARK (VST_LOW_MARK)
Percentage of VSID_CAPACITYbelow 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VS_TypeCapacity_SetFieldsreturns:
• 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.
Example
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
13
VST_BOOLEAN
vst_typecapacity_handle(void)
14 #else
601355 Rev A
API Functions
2-455
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
15
VST_BOOLEAN
vst_typecapacity_handle()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
VST_TYPECAPACITY_HANDLE
VST_MEDIA_TYPE_NAME
MediaType;
h;
21
22
VST_CAPACITY
VST_HIGH_MARK
Capacity;
HighMarkPercent;
VST_LOW_MARK
LowMarkPercent;
VST_FILL_LEVEL
FillLevel;
23
24
25
26
int AssignedBins;
VST_ARCHIVE_ACTION_OPTION
ActionOpt;
27
28
29
30
31
VST_BOOLEAN
AutoCheckinFlag;
VST_BOOLEAN
AutoImportFlag;
VST_BATCH_NAME
ImportBatch;
VST_MANUFACTURER_NAME
ImportManufacturer;
VST_MEDIA_CLASS_NAME
ImportClass;
32
33
34
35
/* create the handle */
h = vS_TypeCapacity_Create();
if (h != (VST_TYPECAPACITY_HANDLE)
NULL)
36
37
38
{
/* get values from user */
printf(“Enter media type name ==>
“);
39
40
41
42
gets(MediaType);
printf(“Enter import class ==> “);
gets(ImportClass);
printf(“Enter import batch ==> “);
2-456
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
43
44
gets(ImportBatch);
printf(“Enter import manufacturer
==> “);
45
46
47
48
gets(ImportManufacturer);
printf(“Enter capacity ==> “);
Capacity = atoi(gets(input));
printf(“Enter high mark percent
==> “);
49
50
51
HighMarkPercent =
atoi(gets(input));
printf(“Enter low mark percent ==>
“);
LowMarkPercent =
atoi(gets(input));
52
53
54
printf(“Enter fill level ==> “);
FillLevel = atoi(gets(input));
printf(“Enter number of assigned
bins ==> “);
55
56
AssignedBins = atoi(gets(input));
printf(“Enter archive action
option ==> “);
57
58
ActionOpt = atoi(gets(input));
printf(“Enter auto import flag ==>
“);
59
60
61
AutoImportFlag =
atoi(gets(input));
printf(“Enter auto checkin flag
==> “);
AutoCheckinFlag =
atoi(gets(input));
62
63
64
/* set the fields */
rc = VS_TypeCapacity_SetFields(h,
VSID_MEDIA_TYPE_NAME,
MediaType,
65
66
67
68
VSID_MEDIA_CLASS_NAME,
ImportClass,
VSID_BATCH_NAME,
ImportBatch,
VSID_MANUFACTURER,
ImportManufacturer,
VSID_CAPACITY,
Capacity,
601355 Rev A
API Functions
2-457
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
69
70
71
72
73
74
75
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)
76
77
78
{
79
80
vst_print_typecapacity(h);
}
81
VS_TypeCapacity_Destroy(h);
82
}
83
return(rc);
84 }
Notes
The migration policy options for VSID_HIGH_MARKare 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-459
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ArchiveQueryqueries for information associated
with a VolServ archive.
VSCMD_
ArchiveQuery
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.
VST_BOOLEAN VSCMD_ArchiveQuery
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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.
2-460
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_ARCHIVE_QUERY_OPTION
(VST_ARCHIVE_QUERY_OPTION)
Specifies the type (or types) of archive
information being requested. Valid
VSID_ARCHIVE_QUERY_OPTIONvalues are
defined in the vs_defs.hfile. 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_LIMITis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor this
ArchiveQuery command request.
USER_FIELDis 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_ArchiveQueryreturns:
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.
2-462
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-463
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_archivequery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_ArchiveQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_archivequery_execute(void)
14 #else
15
VST_BOOLEAN
vst_archivequery_execute()
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
rc =
19
20
21
int
ok;
queryopt;
VST_QUERY_OPTION
VST_ARCHIVE_QUERY_OPTION
arcqueryopt;
22
23
24
25
26
VST_ARCHIVE_NAME
VST_COMMAND_HANDLE
archive;
cmd;
/* get parameters from user */
printf( “*** Archive Query parameters
***\n” );
27
28
printf(“Query all archives? (1) yes,
(0) no: “);
queryopt = (VST_QUERY_OPTION)
atoi(gets(input));
29
30
31
if (queryopt == 0)
{
2-464
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
printf( “\nEnter Archive Name
==>”);
33
34
35
36
37
38
39
gets(archive);
}
else
{
strcpy(archive, VSD_STRING_INIT);
}
/* Initialize the Archive Query
Option */
40
41
arcqueryopt =
VSD_ARCQRY_OPTION_NONE;
printf( “query drive information? (1)
yes, (0) no: “);
42
43
44
45
46
47
ok = atoi(gets(input));
if (ok)
{
/* Add the option to query for */
/* drive information */
arcqueryopt +=
VSD_ARCQRY_OPTION_DRIVE;
}
48
49
50
printf( “query media information? (1)
yes, (0) no: “);
51
52
53
54
ok = atoi(gets(input));
if (ok)
{
/* add the option to query for
media */
55
56
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_MEDIA;
}
57
58
59
printf( “query media class
information? (1) yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
60
61
62
63
{
/* add the option to query media
class */
601355 Rev A
API Functions
2-465
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
64
65
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_CLASS;
66
67
68
}
printf( “query media type
information? (1) yes, (0) no: “);
ok = atoi(gets(input));
if (ok)
69
70
71
72
{
/* add the option to query media
type */
73
74
/* information */
arcqueryopt +=
VSD_ARCQRY_OPTION_TYPE;
}
75
76
77
/* create the command handle */
/* Note that the command handle is
not destroyed in */
/* this routine, but in vst_dispatch
when final */
78
79
80
81
/* status is received. */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
82
83
{
/* Send the command to the
VolServ. */
84
85
86
87
88
/* 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 */
89
90
/* set as default parameters. */
if (queryopt ==
VSE_QUERY_OPTION_ALL)
{
91
2-466
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
92
93
94
95
/* query all archives */
rc = VSCMD_ArchiveQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_ARCHIVE_QRY_OPTION,
arcqueryopt,
VSID_ENDFIELD);
96
97
}
98
99
else
{
100
101
102
103
/* query a specific archive */
rc = VSCMD_ArchiveQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_ARCHIVE_QRY_OPTION,
arcqueryopt,
104
105
VSID_ARCHIVE_NAME, archive,
VSID_ENDFIELD);
106
}
107 }
108 return ( rc );
109}
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_SetFieldsand
VS_Global_GetFieldsfunction 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:
• VSID_ARCHIVE_HANDLE,
• VSID_ARCHIVE_HANDLE_ENTRY,
• VSID_ARCHIVE_HANDLE_TABLE,
• VSID_QUERY_OPTION, VSID_SEQUENCE_NUM,
2-468
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSID_SEQUENCE_TABLE, VSID_STATUS_CODE,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD.
VSCMD_ArchiveQuerydoes 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)
601355 Rev A
API Functions
2-469
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ArchiveQuery_SetDefaultssets the
command-level default parameters for Archive Query
command requests.
VSCMD_
ArchiveQuery
_SetDefaults
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_SetFieldsand
VS_Global_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_ArchiveQuery_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
2-470
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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_OPTIONvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor every
Archive Query command request.
USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_ArchiveQuery_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_archivequery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ArchiveQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_archivequery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_archivequery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
601355 Rev A
API Functions
2-473
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-474
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_ArchiveQuery(l)
601355 Rev A
API Functions
2-475
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ArchiveVarychanges the state of a VolServ
configured archive. Name of the archive and the target state
must be specified.
VSCMD_
ArchiveVary
Upon receipt of a VSCMD_ArchiveVarycommand, 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.
VST_BOOLEAN VSCMD_ArchiveVary
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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_STATEvalues 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_LIMITis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDis 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_ArchiveVaryreturns:
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.
2-478
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-479
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_archivevary_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_ArchiveVary
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_archivevary_execute(void)
14 #else
15
VST_BOOLEAN
vst_archivevary_execute()
16 #endif
17 {
18
19
20
21
22
23
24
VST_BOOLEAN
VST_ARCHIVE_NAME
VST_COMP_STATE
rc = VSE_FALSE;
archive;
state;
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** Archive Vary parameters
***\n” );
25
26
27
printf(“\nEnter Archive “);
gets(archive);
printf(“\nEnter Archive State (1)
ONLINE (2) OFFLINE (3) DIAG: “);
state = (VST_COMP_STATE)
atoi(gets(input));
28
29
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
/* destroyed in this routine, but in
*/
2-480
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
/* vst_dispatch when final status is
received. */
34
35
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
36
37
{
/* Send the command to the
VolServ. */
38
39
40
41
42
/* 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 */
43
44
45
/* default parameters.*/
rc = VSCMD_ArchiveVary(cmd,
VSID_COMP_STATE,
state,
46
VSID_ARCHIVE_NAME,
archive,
47
VSID_ENDFIELD);
48
}
49
return ( rc );
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction 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:
• VSID_ARCHIVE_NAME,
• VSID_COMP_STATE,
• VSID_SEQUENCE_NUMBER,
• VSID_SEQUENCE_TABLE,
• VSID_STATUS_CODE,
2-482
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSID_STATUS_TYPE,
• VSID_USER_FIELD.
VolServ does not generate intermediate status in response to an
Archive Vary request.
VSCMD_ArchiveVarydoes 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)
601355 Rev A
API Functions
2-483
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ArchiveVary_SetDefaultssets the
command-level default parameters for Archive Vary command
requests.
VSCMD_
ArchiveVary_
SetDefaults
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_SetFieldsand
VS_Global_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_ArchiveVary_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
2-484
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor every
Archive Vary command request.
USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_ArchiveVary_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_archivevary_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ArchiveVary API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_archivevary_defaults(void)
15 #else
16
VST_BOOLEAN
vst_archivevary_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
VST_PRIORITY
rc =
20
priority;
601355 Rev A
API Functions
2-487
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
user_field;
timeout;
retries;
wait_flag;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-488
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_ArchiveVary(l)
601355 Rev A
API Functions
2-489
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Auditperforms archive inventory verification of the
specified archive.
VSCMD_Audit
•
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.
VST_BOOLEAN VSCMD_Audit
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
2-490
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-491
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this Audit
request. USER_FIELDis 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_Auditreturns:
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.
2-492
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-493
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_audit_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Audit API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_audit_execute(void)
14 #else
15
VST_BOOLEAN vst_audit_execute()
16 #endif
17 {
18
19
20
21
22
23
VST_BOOLEAN
VST_ARCHIVE_NAME
VST_COMMAND_HANDLE cmd;
rc = VSE_FALSE;
archive;
/* get parameters from user */
printf(“*** Audit parameters ***\n”
);
24
25
26
27
28
printf(“Enter Archive Name ==> “ );
gets(archive);
/* create the command handle */
/* Note that the command handle is
not */
29
30
/* destroyed in this routine, but in
*/
/* vst_dispatch when finalstatus is
received. */
31
32
33
34
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
2-494
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
35
36
37
38
39
/* 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*/
40
41
42
/* default parameters. */
rc = VSCMD_Audit(cmd,
VSID_ARCHIVE_NAME,
archive,
43
VSID_ENDFIELD);
44
}
45
return ( rc );
46 }
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_LIMITplus 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_Auditcan trigger MediaClass callbacks from VolServ.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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 Auditcommand can
be cancelled using the VolServ Cancelcommand.
A pending or executing Auditcommand can be reprioritized
using the VolServ Reprioritizecommand.
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_SetFieldsand
VS_Global_GetFieldsfunction 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:
• VSID_ACTION_CODE,
• VSID_ACTION_CODE_ENTRY,
• VSID_ACTION_CODE_TABLE,
• VSID_COMP_ID,
2-496
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-497
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
•
•
•
•
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)
2-498
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Audit_SetDefaultssets command-level default
parameters for Audit commands.
VSCMD_Audit
_SetDefaults
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_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_Audit_SetDefaults
(
Synopsis
“…”,
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.
601355 Rev A
API Functions
2-499
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
2-500
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_LIMITis not
applicable when the API software executes in
asynchronous mode. The default retry limit is
3.
601355 Rev A
API Functions
2-501
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to be put in USER_FIELDfor Audit
commands. USER_FIELDis 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
VSCMD_Audit_SetDefaultsreturns:
• 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.
2-502
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_audit_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Audit API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_audit_defaults(void)
15 #else
16
VST_BOOLEAN vst_audit_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Audit default parameters
***\n” );
29
30
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
601355 Rev A
API Functions
2-503
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
32
rc = VSCMD_Audit_SetDefaults(
VSID_PRIORITY,
priority,
33
34
35
36
37
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 );
38
39
40 }
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_Audit(l)
2-504
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Cancelstops a pending request from executing or
aborts an executing Audit request.
VSCMD_
Cancel
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.
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.
To issue a valid Cancel request, the client must supply the
request identifier and request type of the request to be canceled.
The VSCMD_Cancelfunction can either take these parameters
separately or retrieve them from a command handle.
VST_BOOLEAN VSCMD_Cancel
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
601355 Rev A
API Functions
2-505
Download from Www.Somanuals.com. All Manuals Search And Download.
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_TYPEvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-506
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue 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_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Cancelreturns:
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.
-
If the object code value is VSE_VOLSERV, the
error occurred in VolServ and the client uses
VST_ERROR_NUMCODEto identify the specific
error.
-
If the object code value is not VSE_VOLSERVand
is not VSE_NONE, the error occurred in the API
and the client uses VST_ERROR_CODEto identify
the specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
2-508
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_cancel_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Cancel API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_cancel_execute(void)
14 #else
15
VST_BOOLEAN vst_cancel_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
21
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_COMMAND_HANDLE
req;
c;
cmd;
601355 Rev A
API Functions
2-509
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
22
23
24
/* get parameters from user */
printf(“*** Cancel parameters ***\n”
);
25
26
printf(“Enter Request ID ==> “ );
req = (VST_REQUEST_ID)
atol(gets(input));
27
28
printf(“Enter Command Request Type
==> “ );
c = (VST_REQUEST_TYPE)
atol(gets(input));
29
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
33
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
34
35
36
37
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
38
39
40
41
42
/* 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 */
43
44
45
/* default parameters. */
rc = VSCMD_Cancel(cmd,
VSID_REQUEST_ID, req,
46
VSID_REQUEST_TYPE, c,
47
48
VSID_ENDFIELD);
}
2-510
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
49
return ( rc );
50 }
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
Cancel request.
VSCMD_Canceldoes 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
601355 Rev A
API Functions
2-511
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-513
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Cancel_SetDefaultssets command-level
default parameters for Cancel commands.
VSCMD_
Cancel_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_Cancel_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
2-514
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_TYPEvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to be put in USER_FIELDfor
Cancel commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Cancel_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_cancel_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Cancel API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_cancel_defaults(void)
15 #else
16 VST_BOOLEAN vst_cancel_defaults()
17 #endif
18 {
19
20
VST_BOOLEAN
VST_PRIORITY
rc = VSE_FALSE;
priority;
601355 Rev A
API Functions
2-517
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
26
27
28
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID
user_field;
timeout;
retries;
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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-518
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Cancel(l)
601355 Rev A
API Functions
2-519
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Checkinchecks media into the VolServ system.
Only media that have been previously checked out can be
checked in.
VSCMD_
Checkin
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.
VST_BOOLEAN VSCMD_Checkin
(VST_COMMAND_HANDLE
handle,
Synopsis
“…”,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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)
(char **)
Number of media to check-in.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-521
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_CheckInreturns:
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.
2-522
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-523
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_checkin_execute
4 *
5 * PURPOSE:
6 * This function sends a checkin command
to the
7 * VolServ software, prompting for all
values needed.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_checkin_execute(void)
15 #else
16 VST_BOOLEAN vst_checkin_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
int
char
rc = VSE_FALSE;
count;
*
medialist[VST_MAX_ITEMS];
22
23
24
25
26
VST_ARCHIVE_NAME
VST_COMMAND_HANDLE cmd;
archive;
/* get parameters from user */
printf(“*** Check-in parameters
***\n” );
27
printf(“\nEnter Archive name (return
for default) “);
2-524
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
28
29
gets( archive);
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
30
31
32
/* create the command handle Note
that the */
/* command handle is not destroyed in
this*/
/* routine, but in vst_dispatch when
final */
33
34
35
36
/* status is received. */
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
37
38
{
/* Send the command to the VolServ
software. */
39
40
41
42
43
/* 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 */
44
45
46
/* default parameters. */
rc = VSCMD_Checkin(cmd,
VSID_ARCHIVE_NAME,
archive,
47
VSID_MEDIA_ID_LIST,
count, medialist,
48
VSID_ENDFIELD);
49
}
50
51
return ( rc );
52 }
601355 Rev A
API Functions
2-525
Download from Www.Somanuals.com. All Manuals Search And Download.
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_Checkincan 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_LIMITplus 1)
multiplied by VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_Checkin_SetDefaults(l)
2-528
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Checkin_SetDefaultssets command-level
default parameters for Checkin commands.
VSCMD_
Checkin_
SetDefaults
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_GetFieldsfunction 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
request itself.
VST_BOOLEAN VSCMD_Checkin_SetDefaults
(
Synopsis
“…”,
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.
601355 Rev A
API Functions
2-529
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(char **)
Number of media to check-in.
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_LIMITis
not applicable when the API software
executes in asynchronous mode.
2-530
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
The total wait time for a command is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
The default time-out value is 120 seconds.
Value to be put in USER_FIELDfor Checkin
commands. USER_FIELDis 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
VSCMD_Checkin_SetDefaultsreturns:
• 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 Functions
2-531
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_checkin_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Checkin API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
**********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_checkin_defaults(void)
15 #else
16 VST_BOOLEAN vst_checkin_defaults()
17 #endif
18 {
19
20
21
22
23
24
25
26
27
VST_BOOLEAN
int
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID
char
rc = VSE_FALSE;
count;
priority;
user_field;
timeout;
retries;
enterprise_id;
archive[VSD_ARCHIVE_NAME_LEN];
28
29
30
/* get parameters from user */
printf(“*** Check-in default
parameters ***\n” );
2-532
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
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,
32
33
34
35
36
priority,
37
38
39
40
41
42
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,
43
VSID_ENDFIELD);
44
45
return ( rc );
46 }
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_Checkin(l)
601355 Rev A
API Functions
2-533
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Checkoutchecks media out of the VolServ system.
Media that are checked out are still known by VolServ, but are
unavailable for client allocation.
VSCMD_
Checkout
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.
VST_BOOLEAN VSCMD_Checkout
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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)
(char **)
Number of media to check-out.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
601355 Rev A
API Functions
2-535
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor this
request. USER_FIELDis 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_Checkoutreturns:
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.
2-536
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-537
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_checkout_execute
4 *
5 * PURPOSE:
6 * This function sends a checkout command
to the
7 * VolServ software, prompting for all
values needed.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_checkout_execute(void)
15 #else
16 VST_BOOLEAN vst_checkout_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
int
char
rc = VSE_FALSE;
count;
*
medialist[VST_MAX_ITEMS];
22
23
24
25
26
VST_COMMENT
VST_COMMAND_HANDLE cmd;
comment;
/* get parameters from user */
printf(“*** Check-out Parameters
***\n” );
27
28
29
printf(“\nEnter Checkout Comment “);
gets( comment);
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
/* destroyed in this routine, but in
*/
2-538
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
/* vst_dispatch when finalstatus is
received. */
34
35
36
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
37
38
{
/* Send the command to the
VolServ */
39
40
41
42
43
44
/* 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 */
45
46
47
48
/* parameters. */
rc = VSCMD_Checkout(cmd,
VSID_COMMENT, comment,
VSID_MEDIA_ID_LIST, count,
medialist,
49
VSID_ENDFIELD);
50
}
51
52
return ( rc );
53 }
601355 Rev A
API Functions
2-539
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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
2-542
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Checkout_SetDefaultssets the command-level
default parameters for Checkout commands.
VSCMD_
Checkout_Set
Defaults
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_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_Checkout_SetDefaults
(
Synopsis
“…”,
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.
601355 Rev A
API Functions
2-543
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(char **)
Number of media to check out with Checkout
commands.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Checkout
commands. USER_FIELDis 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
VSCMD_Checkout_SetDefaultsreturns:
• 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 Functions
2-545
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_checkout_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Checkout API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_checkout_defaults(void)
15 #else
16 VST_BOOLEAN vst_checkout_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
VST_COMMENT
20
21
22
23
24
25
priority;
user_field;
timeout;
retries;
wait_flag;
26
27
28
29
comment;
/* get parameters from user */
printf(“*** Check-out Default
Parameters ***\n” );
2-546
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
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,
31
32
33
34
35
priority,
36
37
38
39
40
41
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,
42
VSID_ENDFIELD);
43
44
return ( rc );
45 }
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_Checkout(l)
601355 Rev A
API Functions
2-547
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ClearEjectreverses the scheduled ejection of one
or more media from an archive.
VSCMD_Clear
Eject
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.
VST_BOOLEAN VSCMD_ClearEject
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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)
(char **)
Number of media to remove from the Eject list.
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
2-549
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
Value to be put in USER_FIELDfor ClearEject
commands. USER_FIELDis 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_ClearEjectreturns:
VSE_TRUE
•
-
Successful execution if the API is operating in
synchronous mode.
-
Good initial status received if the API is operating in
asynchronous mode.
2-550
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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 Functions
2-551
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_cleareject_execute
4 *
5 * PURPOSE:
6 * This function sends an cleareject
command to the
7 * VolServ software, prompting for all
values needed.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_cleareject_execute(void)
15 #else
16 VST_BOOLEAN vst_cleareject_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
int
char
rc = VSE_FALSE;
count;
*
medialist[VST_MAX_ITEMS];
22
23
24
25
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** ClearEject Parameters
***\n” );
26
27
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
/* create the command handle */
2-552
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
28
29
30
/* Note that the command handle is
not */
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
31
32
33
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
34
35
{
/* Send the command to the VolServ
software. */
36
37
38
39
40
/* 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 */
41
42
43
/* default parameters. */
rc = VSCMD_ClearEject(cmd,
VSID_MEDIA_ID_LIST, count,
medialist,
44
VSID_ENDFIELD);
45
}
46
47
return ( rc );
48 }
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 ClearEject request.
601355 Rev A
API Functions
2-553
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
•
Command-specific parameter defaults for ClearEject
commands are set with
VSCMD_ClearEject_SetDefaults. If
2-554
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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,
• 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
•
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)
2-556
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ClearEject_SetDefaultssets command-level
default parameters for ClearEject commands.
VSCMD_Clear
Eject_
Two levels of default parameter settings are used in the API
software— global defaults and command-specific parameter
defaults.
SetDefaults
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_ClearEject_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-557
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(char **)
Number of media to remove from the Eject list
with ClearEject commands.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor ClearEject
commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_ClearEject_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_cleareject_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ClearEject API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_cleareject_defaults(void)
vst_cleareject_defaults()
15 #else
16
VST_BOOLEAN
17 #endif
18 {
2-560
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** ClearEject Default
Parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ClearEject_SetDefaults(
30
31
32
33
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
34
35
36
VSID_TIMEOUT_VALUE,
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
timeout,
retries,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
40
return ( rc );
41 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-561
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_ClearEject(l)
2-562
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Connectassociates 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.
VSCMD_
Connect
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.
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.
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:
•
Round Robin
601355 Rev A
API Functions
2-563
Download from Www.Somanuals.com. All Manuals Search And Download.
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_SCHEDULINGenvironmental
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_SCHEDULINGenvironmental
variable is in the envvar.config configuration file.)
VST_BOOLEAN VSCMD_Connect
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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_HANDLEis not applicable if
VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBERare 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_NUMBERis not applicable
if VSID_CONNECT_HANDLEis 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_NUMBERis not applicable if
VSID_CONNECT_HANDLEis specified.
601355 Rev A
API Functions
2-565
Download from Www.Somanuals.com. All Manuals Search And Download.
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_PROTOCOLis
VSE_PROT_UDP. VSID_PROTOCOLis not
applicable if VSID_CONNECT_HANDLEis
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_NUMBERis not applicable if
VSID_CONNECT_HANDLEis specified.
Return Values
VSCMD_Connectreturns:
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.
601355 Rev A
API Functions
2-567
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connect_execute
4 *
5 * PURPOSE:
2-568
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This executes the VSCMD_Connect API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_connect_execute(void)
14 #else
15 VST_BOOLEAN vst_connect_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ENTERPRISE_ID
TargetEnterpriseID;
VST_SOCKADDR_IN
socketaddress;
21
22
23
24
25
26
27
28
VST_PROGRAM_NUMBER
VST_COMMAND_HANDLE
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
int
prognum;
cmd;
versnum;
procnum;
temp;
/* get parameters from user */
printf(“*** Connect parameters
***\n” );
29
30
printf(“Enter Enterprise ID ==> “ );
TargetEnterpriseID =
(VST_ENTERPRISE_ID)
atoi(gets(input));
31
32
printf(“Enter program number ==>”);
prognum = (VST_PROGRAM_NUMBER)
atol(gets(input));
33
34
printf(“Enter Version Number ==> “ );
versnum = (VST_VERSION_NUMBER)
atol(gets(input));
35
printf(“Enter Procedure Number ==> “
);
601355 Rev A
API Functions
2-569
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
36
37
procnum = (VST_PROCEDURE_NUMBER)
atoi(gets(input));
printf(“Enter Socket sin family ==> “
);
38
39
temp = atoi(gets(input));
socketaddress.sin_family = (short)
temp;
40
printf(“Enter Socket sin port ==> “
);
41
42
temp = atoi(gets(input));
socketaddress.sin_port = (u_short)
temp;
43
printf(“Enter Socket sin address ==>
“ );
44
45
temp = atoi(gets(input));
socketaddress.sin_addr = (u_long)
temp;
46
47
48
/* create the command handle */
/* Note that the command handle is
not */
49
50
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
51
52
53
54
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
55
56
57
58
59
/* 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 */
60
61
/* default parameters. */
rc = VSCMD_Connect(cmd,
2-570
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
62
VSID_TARGET_ENTERPRISE_ID,TargetE
nterpriseID
63
64
65
66
VSID_PROGRAM_NUMBER,
VSID_VERSION_NUMBER,
VSID_PROCEDURE_NUMBER, procnum,
VSID_PROTOCOL,
prognum,
versnum,
VSE_PROT_TCP,
67
VSID_SOCKADDR_IN,
socketaddress,
68
69
VSID_ENDFIELD);
}
70 return ( rc );
71 }
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
Connect command.
The Connect command cannot trigger MediaClass callbacks
from VolServ.
The VSID_CONNECT_HANDLEparameter 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_Disconnectcommand to the VolServ system.
A client may use the VSCMD_ConnectQuerycommand to
determine if an enterprise is already registered and, if so, under
what address.
601355 Rev A
API Functions
2-571
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If a client sends a VSCMD_Connectcommand 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_Connectcommand 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
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)
2-574
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Connect_SetDefaultssets command-level
default parameters for Connect commands.
VSCMD_
Connect_Set
Defaults
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_GetFieldsfunction 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
VST_BOOLEAN VSCMD_Connect_SetDefaults
(
Synopsis
“…”,
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.
601355 Rev A
API Functions
2-575
Download from Www.Somanuals.com. All Manuals Search And Download.
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_HANDLEis not applicable if
VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBERare 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_NUMBERis not applicable
if VSID_CONNECT_HANDLEis 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_NUMBERis not applicable if
VSID_CONNECT_HANDLEis specified.
2-576
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_PROTOCOLis
VSE_PROT_TCP. VSID_PROTOCOLis not
applicable if VSID_CONNECT_HANDLEis
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_LIMITis
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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor Connect
commands. USER_FIELDis 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_NUMBERis not applicable if
VSID_CONNECT_HANDLEis specified.
Return Values
VSCMD_Connect_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connect_defaults
4 *
5 * PURPOSE:
2-578
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This function sets the default
parameters for the
7 * VSCMD_Connect API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_connect_defaults(void)
15 #else
16 VST_BOOLEAN vst_connect_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
601355 Rev A
API Functions
2-579
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
36
37
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
38
39
40 }
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_Connect(l)
2-580
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ConnectQueryreturns a list of all client Internet
addresses currently associated with the specified enterprise
identifier.
VSCMD_
Connect-
Query
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
“…”,
Synopsis
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
2-581
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_ConnectQueryreturns:
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.
601355 Rev A
API Functions
2-583
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
2-584
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connectquery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_ConnectQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_connectquery_execute(void)
14 #else
15
VST_BOOLEAN
vst_connectquery_execute()
16 #endif
17 {
18
VST_BOOLEAN
VST_ENTERPRISE_ID
VST_COMMAND_HANDLE cmd;
rc = VSE_FALSE;
enterprise;
19
20
21
22
23
/* get parameters from user */
printf(“*** Connect Query parameters
***\n” );
24
25
printf(“\nEnter Enterprise ID ==>”);
enterprise = (VST_ENTERPRISE_ID)
atoi(gets(input));
26
27
28
/* create the command handle */
/* Note that the command handle is
not */
29
30
31
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
601355 Rev A
API Functions
2-585
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
33
34
{
/* Send the command to the VolServ
software. */
35
36
37
38
39
/* 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 */
40
41
42
/* default parameters. */
rc = VSCMD_ConnectQuery(cmd,
VSID_QRY_ENTERPRISE_ID,
enterprise,
43
VSID_ENDFIELD);
44
}
45
return ( rc );
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
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
2-586
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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 Querycommand 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
•
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),
2-588
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
•
VS_Initialize(l),
VS_Status_GetFields(l),
VS_Table_GetFields(l),
601355 Rev A
API Functions
2-589
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ConnectQuery_SetDefaultssets
command-level default parameters for Connect Query
commands.
VSCMD_
Connect-
Query_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
Set-Defaults
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_ConnectQuery_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
2-590
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_LIMITis not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-591
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
The total wait time for a command is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE. The default time-out
value is 120 seconds.
Value to be put in USER_FIELDfor Connect
Query commands. USER_FIELDis 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
VSCMD_ConnectQuery_SetDefaultsreturns:
• 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.
2-592
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_connectquery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ConnectQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_connectquery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_connectquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Connect Query default
parameters ***\n” );
601355 Rev A
API Functions
2-593
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_ConnectQuery_SetDefaults(
VSID_PRIORITY,
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
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_ConnectQuery(l)
2-594
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreateArchiveMediaClasscreates an archive
media class association. An archive media class association is
the association of a MediaClass group with a defined archive.
VSCMD_
CreateArchiv
eMediaClass
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:
•
•
•
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
Synopsis
handle,
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-595
Download from Www.Somanuals.com. All Manuals Search And Download.
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_ACTIONvalues are
enumerated in the vs_types.hfile.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_HIGH_MARK (VST_HIGH_MARK)
Percentage of VSID_CAPACITYabove which
the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
VSID_LOW_MARK(VST_LOW_MARK)
Percentage of VSID_CAPACITYbelow which
the specified migration policy option is
performed or terminated. This field is
applicable only if VSID_ARCHIVE_ACTIONis
set to VSE_ARCHIVE_ACTION_NOTIFYor
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-597
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue 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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_CreateArchiveMediaClassreturns:
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.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
601355 Rev A
API Functions
2-599
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
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()
2-600
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
17 #endif
18 {
19
20
21
int
int
i;
count;
rc =
VST_BOOLEAN
VSE_FALSE;
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
VST_PRIORITY
22
23
archive;
24
25
26
27
28
29
capacity;
highmark;
lowmark;
migpri;
VST_ARCHIVE_NAME
targetarchive;
30
31
32
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
VST_COMMAND_HANDLE
33
34
35
36
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
39
40
41
printf(“Enter Media Class Name ==> “
);
42
43
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
44
45
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
46
601355 Rev A
API Functions
2-601
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
47
printf(“Enter High Mark Percentage
==> “ );
48
49
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
50
51
52
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
53
54
{
/* these parameters only need to
be set if */
55
/* the archivemediaclass is being
set up to */
56
57
/* support migration. */
printf(“Enter Target Archive ==> “
);
58
59
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
60
61
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
62
63
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
64
65
66
67
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
68
69
70
71
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
72
73
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
2-602
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
75
76
77
78
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
79
80
81
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
82
83
84
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
VS_Component_SetFields(comphandle
,
86
87
88
89
VSID_COMP_TYPE, CompType,
VSID_COMP_ID, CompID,
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
90
91
}
/* This also only needs to be set
if it is */
92
/* actually being used. It is not
needed */
93
94
/* otherwise. */
VSCMD_CreateArchiveMediaClass_Set
Defaults(
95
VSID_COMPONENT_HANDLE_TABLE,comph
andletable,
96
97
98
99
VSID_ENDFIELD);
}
/* create the command handle */
601355 Rev A
API Functions
2-603
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
100 /* Note that the command handle is
not */
101 /* destroyed in this routine, but in
*/
102 /* vst_dispatch when final status is
received. */
103 cmd = VS_Command_Create();
104 if (cmd != (VST_COMMAND_HANDLE )NULL)
105 {
106
107
108
109
110
111
/* 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 */
112
113
/* default parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
114
115
116
117
118
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
119
VSID_ENDFIELD);
120 }
121
122 return ( rc );
123}
2-604
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CreateArchiveMediaClassdoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_MARKis
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
2-606
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_CreateArchiveMediaClass_SetDefaults(l),
VSCMD_DeleteArchiveMediaClass(l),
VSCMD_ModifyArchiveMediaClass(l)
2-608
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreateArchvieMediaClass_SetDefaults
sets the command-level default parameters for Create Archive
Media Class commands.
VSCMD_
CreateArchiv
eMediaClass_
SetDefaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_CreateArchive
MediaClass_SetDefaults
Synopsis
(
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-609
Download from Www.Somanuals.com. All Manuals Search And Download.
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_ACTIONvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_HIGH_MARK (VST_HIGH_MARK)
Percentage of VSID_CAPACITYabove which
the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
VSID_LOW_MARK (VST_LOW_MARK)
Percentage of VSID_CAPACITYbelow which
the specified migration policy option is
performed or terminated. This field is
applicable only if VSID_ARCHIVE_ACTIONis
set to VSE_ARCHIVE_ACTION_NOTIFYor
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_LIMITis not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-611
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue 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)
VSID_USER_FIELD (VST_USER_FIELD)
The total wait time for a command is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE. The default time-out
value is 120 seconds.
Value to be put in USER_FIELDfor Create
Archive Media Class commands.
USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_CreateArchiveMediaClass_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_BADSIZE- The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
Example
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
601355 Rev A
API Functions
2-613
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16
VST_BOOLEAN
vst_createarchivemediaclass_execu
te()
17 #endif
18 {
19
20
21
int
int
VST_BOOLEAN
i;
count;
rc =
VSE_FALSE;
22
23
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
24
25
26
27
28
29
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
VST_PRIORITY
VST_ARCHIVE_NAME
targetarchive;
capacity;
highmark;
lowmark;
migpri;
30
31
32
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
VST_COMMAND_HANDLE
33
34
35
36
CompID;
cmd;
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Create Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
39
40
41
printf(“Enter Media Class Name ==> “
);
42
43
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
44
capacity = atoi(gets(input));
2-614
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
46
47
48
49
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
50
51
52
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
53
54
{
/* these parameters only need to
be set if */
55
/* the archivemediaclass is being
set up to */
56
57
/* support migration. */
printf(“Enter Target Archive ==> “
);
58
59
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
60
61
migpri = atoi(gets(input));
VSCMD_CreateArchiveMediaClass_Set
Defaults (
62
63
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
64
65
66
67
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
68
69
70
71
count = atoi(gets(input));
if (count > 0)
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
601355 Rev A
API Functions
2-615
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
72
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return(VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
73
74
75
76
77
78
79
80
81
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
82
83
84
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
VS_Component_SetFields(comphandle
,
86
87
88
89
VSID_COMP_TYPE, CompType,
VSID_COMP_ID, CompID,
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
90
91
}
/* This also only needs to be set
if it is */
92
/* actually being used. It is not
needed */
93
94
/* otherwise. */
VSCMD_CreateArchiveMediaClass_Set
Defaults(
95
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
96
97
VSID_ENDFIELD);
}
2-616
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
98
99
/* create the command handle */
100 /* Note that the command handle is
not */
101 /* destroyed in this routine, but in
*/
102 /* vst_dispatch when final status is
received. */
103 cmd = VS_Command_Create();
104 if (cmd != (VST_COMMAND_HANDLE )NULL)
105 {
106
107
108
109
110
111
/* 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 */
112
113
/* default parameters. */
rc =
VSCMD_CreateArchiveMediaClass(cmd
,
114
115
116
117
118
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
VSID_LOW_MARK,
lowmark,
VSID_CAPACITY,
capacity,
119
VSID_ENDFIELD);
120 }
121
122 return ( rc );
123}
601355 Rev A
API Functions
2-617
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CreateArchiveMediaClass(l)
2-618
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreateMediaClass creates a new MediaClass
group.
VSCMD_
CreateMedia-
Class
A MediaClass group establishes common characteristics for the
media it contains.
VST_BOOLEAN VSCMD_CreateMediaClass
(
Synopsis
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.
601355 Rev A
API Functions
2-619
Download from Www.Somanuals.com. All Manuals Search And Download.
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_STATEvalues
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_OPTIONvalues 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_CAPACITYabove which
the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
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_OPTIONis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_NUMBERis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBERis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBERis not
applicable.
601355 Rev A
API Functions
2-621
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol VolServ uses to send
callbacks for this MediaClass group. The
default VSID_PROTOCOLis VSE_PROT_TCP.
VSID_PROTOCOLis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOLis 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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBERis not
applicable.
Return Values
VSCMD_CreateMediaClassreturns:
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.
601355 Rev A
API Functions
2-623
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
2-624
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_createmediaclass_execute
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_CreateMediaClass API call.
7 *
8 * PARAMETERS:
9 * none
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
VSE_FALSE;
rc =
19
20
VST_MEDIA_CLASS_NAME
VST_MEDIA_TYPE_NAME
MediaTypeName;
mediaclass;
21
22
23
24
25
26
27
VST_CAPACITY
VST_CLASS_MOUNT_STATE mountstate;
VST_HIGH_MARK
VST_COMMAND_HANDLE
VST_NOTIFY_COMMENT
VST_CLASS_RPC_OPTION
VST_HOSTNAME
capacity;
highmark;
cmd;
comment;
rpc_option;
rpc_hostname;
28
29
30
31
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
rpc_prognum;
rpc_versnum;
rpc_procnum;
rpc_protocol;
601355 Rev A
API Functions
2-625
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
VST_ENTERPRISE_ID
enterpriseid;
33
34
35
/* get parameters from user */
printf(“*** Create Media Class
parameters ***\n” );
36
printf(“\nEnter Media Class Name
==>”);
37
38
gets( mediaclass);
printf(“\nEnter Media Type Name ==>
“);
39
40
41
42
gets( MediaTypeName);
printf(“\nEnter capacity==>”);
capacity = atoi(gets(input));
printf(“\nEnter class mount state (0)
no, (1) ok: “);
43
44
45
46
mountstate = atoi(gets(input));
printf(“\nEnter high mark ==>”);
highmark = atoi(gets(input));
printf(“\nEnter notify comment
==>”);
47
48
gets(comment);
printf(“\nEnter Option (0) no
callbacks, (1) standard, (2)
Enterprise==>”);
49
50
rpc_option = (VST_CLASS_RPC_OPTION)
atoi(gets(input));
if (rpc_option ==
VSE_CLASS_RPC_NONE)
51
52
{
VSCMD_CreateMediaClass_SetDefault
s(
53
VSID_CLASS_RPC_OPTION,
rpc_option,
54
55
56
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_STANDARD)
57
58
{
printf(“\nEnter RPC Host Name
==>”);
2-626
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
59
60
gets(rpc_hostname);
printf(“\nEnter program number
==>”);
61
rpc_prognum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter version number
==>”);
62
63
rpc_versnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter procedure number
==>”);
64
65
rpc_procnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter Protocol (6) TCP
or (17) UDP ==>”);
rpc_protocol = (VST_PROTOCOL)
atoi(gets(input));
66
67
68
VSCMD_CreateMediaClass_SetDefault
s(
69
70
71
72
73
74
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,
75
76
77
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_ENTERPRISE)
78
79
{
printf(“\nEnter enterprise id
==>”);
601355 Rev A
API Functions
2-627
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
80
81
enterpriseid =
(VST_ENTERPRISE_ID)
atol(gets(input));
VSCMD_CreateMediaClass_SetDefault
s(
82
83
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_TARGET_ENTERPRISE_ID,
enterpriseid,
84
85
86
87
88
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
89
90
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
91
92
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
93
94
{
/* Send the command to the VolServ
software. */
95
96
97
98
99
/* 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 */
100
101
102
/* default parameters. */
rc = VSCMD_CreateMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
103
VSID_MEDIA_TYPE_NAME,
MediaTypeName,
2-628
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
104
105
106
107
VSID_CAPACITY,
capacity,
VSID_CLASS_MOUNT_STATE,
mountstate,
VSID_HIGH_MARK,
highmark,
VSID_NOTIFY_COMMENT,
comment,
VSID_ENDFIELD);
108
109 }
110 return ( rc );
111}
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 Media Class request.
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_LIMITplus 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_MARKhas been reached
or exceeded occur after any Reclassify, Import, or Modify
Media Class command.
601355 Rev A
API Functions
2-629
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSID_CAPACITYis a “hard” limit. VolServ does not permit
the number of media assigned to a MediaClass group to exceed
the VSID_CAPACITYfor that MediaClass group.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction 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:
• VSID_MEDIA_CLASS_NAME,
2-630
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-631
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreateMediaClass_SetDefaultssets the
command-level default parameters for Create Media Class
commands.
VSCMD_
CreateMedia-
Class_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_CreateMediaClass
(
Synopsis
“…”,
VSID_ENDFIELD)
2-632
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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_STATEvalues 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_OPTIONvalues 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
2-633
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_HIGH_MARK (VST_HIGH_MARK)
VSID_HOST_NAME (VST_HOST_NAME)
Percentage of VSID_CAPACITYabove which
the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
Network-assigned name of the computer
where the task that “listens” for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTIONis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PROCEDURE_NUMBER
(VST_PROCEDURE_NUMBER)
RPC procedure number of the client process
to receive callbacks generated for this
MediaClass group.
VSID_PROCEDURE_NUMBERis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBERis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBERis not
applicable.
VSID_PROTOCOL (VST_PROTOCOL)
Internet protocol VolServ uses to send
callbacks for this MediaClass group. The
default VSID_PROTOCOLis VSE_PROT_TCP.
VSID_PROTOCOLis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOLis 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_LIMITis not applicable when
the API software executes in asynchronous
mode.
601355 Rev A
API Functions
2-635
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue 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_FIELDfor Create
Media Class commands. USER_FIELDis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBERis not
applicable.
2-636
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_CreateMediaClass_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_createmediaclass_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_CreateMediaClass API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_createmediaclass_defaults(voi
d)
15 #else
16
VST_BOOLEAN
vst_createmediaclass_defaults()
601355 Rev A
API Functions
2-637
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Create Archive Media
Class default parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
29
30
31
VSCMD_CreateMediaClass_SetDefault
s(
32
33
34
35
36
37
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,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
2-638
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-639
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
2-640
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DriveVaryis issued to execute VolServ Drive Vary
requests and to change the operational availability of a drive.
VSCMD_Drive
Vary
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.
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.
VST_BOOLEAN VSCMD_DriveVary
( VST_COMMAND_HANDLE handle,
"…",
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_IDor drive pool
group given in VSID_DRIVEPOOL_NAME.
Used when varying all drives to the same
state. Valid VSID_COMP_STATEvalues are
enumerated in the vs.types.h file.
VSID_COMP_STATE_LIST (int)
(VST_COMP_STATE *)
Number of states contained in this list.
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)
(VST_DRIVE_ID *)
Number of drives contained in this list used
with VSID_COMP_STATE_LIST.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
The default time-out value is 120 seconds.
601355 Rev A
API Functions
2-643
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_DriveVaryreturns:
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.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
2-644
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivevary_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_DriveVary API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivevary_execute(void)
14 #else
15 VST_BOOLEAN vst_drivevary_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
int
VST_DRIVE_ID
rc = VSE_FALSE;
count;
drivelist[VST_MAX_ITEMS];
21
22
VST_DRIVE_ID
VST_COMP_STATE
temp_drive_id;
temp_state;
601355 Rev A
API Functions
2-645
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
23
VST_COMP_STATE
statelist[VST_MAX_ITEMS];
VST_DRIVE_POOL_NAME poolname;
24
25
26
27
28
29
30
31
int
i;
VST_COMMAND_HANDLE cmd;
int
int
varyopt;
stateopt;
/* get parameters from user */
printf(“*** Drive Vary parameters
***\n” );
32
printf(“0) Vary by drive list , 1)
Vary by drive pool 2) Vary by
drive ID ==> “ );
33
34
35
36
37
38
39
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);
}
40
41
42
43
44
45
46
47
else if (varyopt == 1)
{
/* vary by drive pool */
return(vst_drivevary_pool_execute
());
48
49
50
51
52
53
}
else
{
/* vary a single drive */
printf(“\nEnter Drive ID ==> “);
temp_drive_id =
atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
54
2-646
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
55
VSID_DRIVE_ID,
temp_drive_id,
VSID_ENDFIELD);
56
57
58
59
}
printf(“0) Vary by state list , 1)
Vary single state ==> “ );
stateopt = atoi(gets(input));
if (stateopt == 0)
{
60
61
62
63
/* vary by using a list of
component states */
printf(“\nEnter New States
(1)ONLINE (2)OFFLINE (3) DIAG”);
for (i = 0; i < count; i++)
{
64
65
66
67
printf(“State #%d: “,
count+1);
68
statelist[i] =
atoi(gets(input));
}
69
70
71
72
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE_LIST,
count,statelist,
73
74
75
76
77
VSID_ENDFIELD);
}
else
{
/* vary everyting to a single
state */
78
printf(“\nEnter New State (1)
ONLINE (2) OFFLINE (3) DIAG ==>”);
temp_state = atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE,
79
80
81
temp_state,
82
83
84
85
VSID_ENDFIELD);
}
/* create the command handle */
601355 Rev A
API Functions
2-647
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
86
87
88
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
89
90
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
91
92
{
/* Send the command to the VolServ
software. */
93
94
95
96
97
/* 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 */
98
99
100
/* default parameters. */
rc = VSCMD_DriveVary(cmd,
VSID_ENDFIELD);
101 }
102 return ( rc );
103}
Notes
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_DriveVarydoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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 diagnosticstates
only.
The unavailablestate 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-linecauses
the associated drive to be viewed as unavailable.
The VSID_DRIVE_ID_LISTand
VSID_COMP_STATE_LISTparameters 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_SetDefaultscommand.
It is possible to vary drives to different states with one request.
To do this, use the VSID_DRIVE_ID_LISTand
VSID_COMP_STATE_LISTparameters.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
601355 Rev A
API Functions
2-649
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction 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:
• VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
• VSID_DRIVE_ID,
2-650
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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_DriveVary_SetDefaults(l)
601355 Rev A
API Functions
2-651
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DriveVary_SetDefaultsis the call issued to set
the command default parameters for Drive Vary commands.
VSCMD_Drive
Vary_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
VST_BOOLEAN VSCMD_DriveVary_SetDefaults
(
Synopsis
"…",
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_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_STATEvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
(VST_COMP_STATE *)
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_LISTvalues 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)
(VST_DRIVE_ID *)
Number of drives contained in this list.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in the USER_FIELDfor Drive
Vary commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_DriveVary_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivevary_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_DriveVary API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivevary_execute(void)
14 #else
15 VST_BOOLEAN vst_drivevary_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
int
VST_DRIVE_ID
rc = VSE_FALSE;
count;
drivelist[VST_MAX_ITEMS];
601355 Rev A
API Functions
2-655
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
VST_DRIVE_ID
VST_COMP_STATE
VST_COMP_STATE
temp_drive_id;
temp_state;
statelist[VST_MAX_ITEMS];
24
25
26
27
28
29
30
31
VST_DRIVE_POOL_NAME poolname;
int
i;
VST_COMMAND_HANDLE cmd;
int
int
varyopt;
stateopt;
/* get parameters from user */
printf(“*** Drive Vary parameters
***\n” );
32
printf(“0) Vary by drive list , 1)
Vary by drive pool 2) Vary by
drive ID ==> “ );
33
34
35
36
37
38
39
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);
}
40
41
42
43
44
45
46
47
else if (varyopt == 1)
{
/* vary by drive pool */
return(vst_drivevary_pool_execute
());
48
49
50
51
52
}
else
{
/* vary a single drive */
printf(“\nEnter Drive ID ==> “);
2-656
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
53
temp_drive_id =
atoi(gets(input));
54
55
VSCMD_DriveVary_SetDefaults(
VSID_DRIVE_ID,
temp_drive_id,
56
57
58
59
VSID_ENDFIELD);
}
printf(“0) Vary by state list , 1)
Vary single state ==> “ );
stateopt = atoi(gets(input));
if (stateopt == 0)
{
60
61
62
63
/* vary by using a list of
component states */
printf(“\nEnter New States
(1)ONLINE (2)OFFLINE (3) DIAG”);
for (i = 0; i < count; i++)
{
64
65
66
67
printf(“State #%d: “,
count+1);
68
statelist[i] =
atoi(gets(input));
}
69
70
71
72
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE_LIST,
count,statelist,
73
74
75
76
77
VSID_ENDFIELD);
}
else
{
/* vary everyting to a single
state */
78
printf(“\nEnter New State (1)
ONLINE (2) OFFLINE (3) DIAG ==>”);
temp_state = atoi(gets(input));
VSCMD_DriveVary_SetDefaults(
VSID_COMP_STATE,
79
80
81
temp_state,
82
83
VSID_ENDFIELD);
}
601355 Rev A
API Functions
2-657
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
84
85
86
/* create the command handle */
/* Note that the command handle is
not */
87
88
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
89
90
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
91
92
{
/* Send the command to the VolServ
software. */
93
94
95
96
97
/* 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 */
98
99
100
/* default parameters. */
rc = VSCMD_DriveVary(cmd,
VSID_ENDFIELD);
101 }
102 return ( rc );
103}
Notes
The VSID_DRIVE_ID_LISTand 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_DriveVary(l)
601355 Rev A
API Functions
2-659
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Exportis issued to execute the VolServ Export
request.
VSCMD_
Export
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.
VST_BOOLEAN VSCMD_Export (
VST_COMMAND_HANDLE handle,
"…",
Synopsis
VSID_ENDFIELD )
2-660
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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.
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)
(char **)
Number of media identified in the list.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-661
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Exportreturns:
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.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
601355 Rev A
API Functions
2-663
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_export_execute
4 *
5 * PURPOSE:
6 * This function sends an export command
to the
7 * Volserv, prompting for all values
needed.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_export_execute(void)
15 #else
16
VST_BOOLEAN vst_export_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
int
char
rc = VSE_FALSE;
count;
*
medialist[VST_MAX_ITEMS];
22
VST_COMMENT
comment;
2-664
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
23
24
25
26
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** Export Parameters ***\n”
);
27
28
29
printf(“\nEnter Export Comment “);
gets( comment);
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
33
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
34
35
36
cmd = VS_Command_Create();
/* validate the command handle */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
37
38
{
/* Send the command to the VolServ
software. */
39
40
41
42
43
/* 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 */
44
45
46
47
/* default parameters. */
rc = VSCMD_Export(cmd,
VSID_COMMENT, comment,
VSID_MEDIA_ID_LIST,
count, medialist,
48
49
50
VSID_ENDFIELD);
}
601355 Rev A
API Functions
2-665
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
51
return ( rc );
52 }
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 an
Export request.
VSCMD_Exporttriggers MediaClass callbacks from VolServ.
The VSID_Media_ID_LISTparameter 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction 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.
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:
• 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,
601355 Rev A
API Functions
2-667
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
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)
2-668
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Export_SetDefaultssets command-level
default parameters for the Export command.
VSCMD_
Export_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
VST_BOOLEAN VSCMD_Export_SetDefaults
(
Synopsis
"…",
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_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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Export
commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Export_SetDefaultsreturns:
• VSE_TRUE- Successful execution.
• VSE_FALSE- API failure - An appropriate error code is set
in VSG_Error.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_export_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Export API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_export_defaults(void)
15 #else
16 VST_BOOLEAN vst_export_defaults()
17 #endif
18 {
19
20
21
22
23
24
25
26
27
28
29
VST_BOOLEAN
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG wait_flag;
VST_ENTERPRISE_ID
VST_COMMENT
rc = VSE_FALSE;
priority;
user_field;
timeout;
retries;
enterprise_id;
comment;
/* get parameters from user */
printf(“*** Export default
parameters ***\n” );
601355 Rev A
API Functions
2-671
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
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,
31
32
33
34
35
priority,
36
37
38
39
40
41
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,
42
VSID_ENDFIELD);
43
44
return ( rc );
45 }
Notes
The VSID_MEDIA_ID_LISTparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Export(l)
601355 Rev A
API Functions
2-673
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Importis issued to request execution of VolServ
Import requests.
VSCMD_
Import
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.
VST_BOOLEAN VSCMD_Import (
VST_COMMAND_HANDLE handle,
"…",
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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)
(char **)
Number of media in the list.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Importreturns:
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.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
601355 Rev A
API Functions
2-677
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_import_execute
4 *
5 * PURPOSE:
6 * This function sends a import command
to the
7 * VolServ software, prompting for all
values needed.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_import_execute(void)
15 #else
16
VST_BOOLEAN vst_import_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
int
char
rc = VSE_FALSE;
count;
*
medialist[VST_MAX_ITEMS];
22
VST_ARCHIVE_NAME
archive;
2-678
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
23
24
25
26
27
28
29
VST_MEDIA_CLASS_NAME mediaclass;
VST_BATCH_NAME batch;
VST_MANUFACTURER_NAM manuf;
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** Import parameters ***\n”
);
30
31
32
33
34
35
36
37
38
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);
39
40
/* create the command handle */
/* Note that the command handle is
not */
41
42
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
43
44
cmd = VS_Command_Create();
/* make sure that the command handle
is not */
45
46
/* null. */
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
47
48
{
/* Send the command to the VolServ
software. */
49
50
51
52
/* 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 */
601355 Rev A
API Functions
2-679
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
53
/* retry limit and priority are
set as */
54
55
56
/* default parameters. */
rc = VSCMD_Import(cmd,
VSID_ARCHIVE_NAME,
archive,
57
VSID_MEDIA_CLASS_NAME,
mediaclass,
58
59
60
VSID_BATCH_NAME,
VSID_MANUFACTURER,
VSID_MEDIA_ID_LIST,
batch,
manuf,
count,
medialist,
VSID_ENDFIELD);
61
62
}
63
64
return ( rc );
65 }
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 an
Import request.
VSCMD_Importtriggers MediaClass callbacks from VolServ.
The VSID_MEDIA_ID_LISTparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction calls.
601355 Rev A
API Functions
2-681
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-683
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Import_SetDefaultsis the call issued to set the
command default parameters for Import commands.
VSCMD_
Import_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
VST_BOOLEAN VSCMD_Import_SetDefaults
(
Synopsis
"…",
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_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
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.
2-684
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_BATCH_NAME (VST_BATCH_NAME)
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)
(char **)
Number of media in the list.
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_LIMITis
not applicable when the API software
executes in asynchronous mode.
601355 Rev A
API Functions
2-685
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Import
commands. USER_FIELDis 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
VSCMD_Import_SetDefaultsreturns:
• 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.
2-686
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_import_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Import API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_import_defaults(void)
15 #else
16 VST_BOOLEAN vst_import_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
VST_BATCH_NAME
priority;
user_field;
timeout;
retries;
wait_flag;
26
27
28
29
30
batch;
VST_MANUFACTURER_NAME manuf;
/* get parameters from user */
printf(“*** Import default
parameters ***\n” );
31
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
printf(“\nEnter Batch “);
gets( batch);
32
33
601355 Rev A
API Functions
2-687
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
34
35
36
37
38
39
printf(“\nEnter Manufacturer “);
gets( manuf);
/* set the default parameters */
rc = VSCMD_Import_SetDefaults(
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
40
41
42
VSID_TIMEOUT_VALUE,
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
timeout,
retries,
43
VSID_ENTERPRISE_ID,
enterprise_id,
44
45
46
VSID_BATCH_NAME,
VSID_MANUFACTURER,
VSID_ENDFIELD);
batch,
manuf,
47
48
return ( rc );
49 }
Notes
The VSID_MEDIA_ID_LISTparameter 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
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Import(l)
2-688
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_IntransitQueryis issued to request execution of
VolServ Intransit Query commands.
VSCMD_
Intransit-
Query
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.
VST_BOOLEAN VSCMD_IntransitQuery
( VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_IntransitQueryreturns:
• 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.
601355 Rev A
API Functions
2-691
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
Example
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 ****************************************
*********/
2-692
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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
VSE_FALSE;
VST_COMMAND_HANDLE
rc =
cmd;
19
20
21
22
23
24
printf(“*** Intransit Query ***\n” );
/* create the command handle */
/* Note that the command handle is
not */
25
26
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
27
28
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
29
30
{
/* Send the command to the VolServ
software. */
31
32
33
34
35
36
37
38
/* 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. There are
no */
/* command-specific parameters
for */
/* intransit query. */
601355 Rev A
API Functions
2-693
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
40
rc = VSCMD_IntransitQuery(cmd,
VSID_ENDFIELD);
41
}
42
return ( rc );
43 }
Notes
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_IntransitQuerydoes 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 intransitstate 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFieldsand
VS_Global_GetFieldsfunction 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
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
•
•
•
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)
2-696
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_IntransitQuery_SetDefaultsis issued to set
command-level default parameters for Intransit Query
commands.
VSCMD_
Intransit-
Query_Set-
Defaults
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
VST_BOOLEAN VSCMD_IntransitQuery_SetDefaults (
“…”,
Synopsis
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 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Intransit
Query commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_IntransitQuery_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_intransitquery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_IntransitQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_intransitquery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_intransitquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
601355 Rev A
API Functions
2-699
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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 =
29
30
31
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,
32
33
34
35
36
37
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-700
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_IntransitQuery(l)
601355 Rev A
API Functions
2-701
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Lockis issued to request execution of the VolServ
Lock command.
VSCMD_Lock
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.
VST_BOOLEAN VSCMD_Lock
( VST_COMMAND_HANDLE handle,
"…",
Synopsis
VSID_ENDFIELD )
2-702
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
Name of the client dispatch routine to receive
status for this request.
VSID_DRIVE_COUNT (int)
VSID_DRIVE_EXCL_LIST (int)
(VST_DRIVE_ID *)
Number of drives to lock.
Number of drives in the drive exclusion list.
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)
(VST_DRIVE_ID *)
Number of drives in list.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Lockreturns:
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.
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
601355 Rev A
API Functions
2-705
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_lock_pool_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Lock API call
for drive
7 * pools.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_lock_pool_execute(void)
15 #else
16 VST_BOOLEAN vst_lock_pool_execute()
17 #endif
18 {
19
20
21
VST_BOOLEAN
VSE_FALSE;
VST_DRIVE_ID
rc =
excllist[VST_MAX_ITEMS];
count;
int
2-706
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
22
23
24
25
26
VST_DRIVE_POOL_NAME
int
VST_COMMAND_HANDLE
dp;
drivecount;
cmd;
printf(“\nEnter Drive Pool Name
==>”);
27
28
gets( dp );
printf(“\nEnter drive exclusion
list\n”);
29
30
count =
vst_getdrivelist(excllist,
VST_MAX_ITEMS);
printf(“Enter number of drives to
lock ==> “);
31
32
33
34
drivecount = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
35
36
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
37
38
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
39
40
{
/* Send the command to the VolServ
software. */
41
42
43
44
45
/* 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 */
46
47
48
/* default parameters. */
rc = VSCMD_Lock(cmd,
VSID_DRIVEPOOL_NAME, dp,
601355 Rev A
API Functions
2-707
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
49
50
VSID_DRIVE_EXCL_LIST,
count,excllist,
VSID_DRIVE_COUNT,
drivecount,
VSID_ENDFIELD);
51
52
}
53
return(rc);
54 }
Notes
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_Lockdoes not trigger any MediaClass callbacks from
VolServ.
The VSID_DRIVE_ID_LISTand
VSID_DRIVE_EXCEL_LISTparameters 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
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_SetDefaultsfunction.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
Global defaults are initialized at startup and can be set or
retrieved using VS_Global_SetFieldsand
VS_Global_GetFieldsfunction 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:
•
•
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.
2-710
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-711
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Lock_SetDefaultsis issued to set the
command-level default parameters for the Lock command.
VSCMD_Lock
_SetDefaults
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
VST_BOOLEAN VSCMD_Lock_SetDefaults
(
Synopsis
"…",
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)
VSID_DRIVE_EXCL_LIST (int)
(VST_DRIVE_ID *)
Number of drives to lock.
Number of drives in list.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVE_ID_LIST (int)
(VST_DRIVE_ID *)
Number of drives in list.
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor Lock
commands. USER_FIELDis 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.
Return Values
VSCMD_Lock_SetDefaultsreturns:
• 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.
2-714
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_lock_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Lock API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_lock_defaults(void)
15 #else
16
VST_BOOLEAN vst_lock_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Lock default parameters
***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Lock_SetDefaults(
VSID_PRIORITY,
30
31
32
priority,
601355 Rev A
API Functions
2-715
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
34
35
36
37
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 );
38
39
40 }
Notes
The VSID_DRIVE_ID_LISTand 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
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Lock(l)
2-716
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaClassQueryis issued to request execution of
VolServ Media Class Query commands.
VSCMD_
MediaClass-
Query
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,
“…”,
Synopsis
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
2-717
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTvalues 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_OPTIONvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-718
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_MediaClassQueryreturns:
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 Functions
2-719
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
2-720
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediaclassquery_execute
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_MediaClassQuery API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediaclassquery_execute(void)
14 #else
15
VST_BOOLEAN
vst_mediaclassquery_execute()
16 #endif
17 {
18
19
20
21
22
23
24
25
VST_BOOLEAN rc = VSE_FALSE;
VST_QUERY_OPTION queryopt;
VST_QUERY_LIST_OPTION querylistopt;
VST_MEDIA_CLASS_NAME mediaclass;
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** MediaClass Query
parameters ***\n” );
26
printf(“0) Query by Media Class Name,
1) Query all ==> “ );
27
28
29
30
31
queryopt = atoi(gets(input));
if (queryopt == 0)
{
printf(“\nEnter Media Class Name
==>”);
32
33
gets( mediaclass);
}
601355 Rev A
API Functions
2-721
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
34
printf(“\n0) no media list, 1) Media
List, 2) Media List Details ==>
“);
35
36
37
38
querylistopt = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
39
40
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
41
42
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
43
44
{
/* Send the command to the VolServ
software. */
45
46
47
48
49
/* 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 */
50
51
52
53
54
/* 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,
55
56
57
58
59
VSID_ENDFIELD);
}
2-722
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
60
61
62
63
else
{
/* query all media classes */
rc =
VSCMD_MediaClassQuery(cmd,
VSID_QRY_OPTION,
queryopt,
64
65
VSID_CLASS_QRY_OPTION,
querylistopt,
VSID_ENDFIELD);
}
66
67
68
}
69
return ( rc );
70 }
Notes
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_MediaClassQuerydoes 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_FAILwith 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
601355 Rev A
API Functions
2-723
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction 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:
• VSID_MEDIACLASS_HANDLE,
• VSID_MEDIACLASS_HANDLE_ENTRY,
• VSID_MEDIACLASS_HANDLE_TABLE,
2-724
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-725
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaClassQuery_SetDefaultsis issued to
set the command-level default parameters for the Media Class
Query command.
VSCMD_
MediaClass-
Query_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
VST_BOOLEAN VSCMD_MediaClassQuery_SetDefaults (
“…”,
Synopsis
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_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_OPTvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
VSID_ENTERPRISE_ID
Description
Identifier of the enterprise, if any, to receive
intermediate and final status for Media Class
Query commands.
(VST_ENTERPRISE_ID)
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
601355 Rev A
API Functions
2-727
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor Media
Class Query commands. USER_FIELDis 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
VSCMD_MediaClassQuery_SetDefaultsreturns:
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_mediaclassquery_defaults
4 *
5 * PURPOSE:
2-728
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This function sets the default
parameters for the
7 * VSCMD_MediaClassQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_mediaclassquery_defaults(void
)
15 #else
16
VST_BOOLEAN
vst_mediaclassquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* 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 =
29
30
31
VSCMD_MediaClassQuery_SetDefaults
(
32
33
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
601355 Rev A
API Functions
2-729
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
34
35
36
37
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
VSID_ENDFIELD);
return ( rc );
38
39
40 }
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_MediaClassQuery(l)
2-730
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaQueryis issued to request execution of the
VolServ Media Query command.
VSCMD_
MediaQuery
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,
"…",
Synopsis
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)
(char **)
Number of media in the list.
List of media identifiers to query.
601355 Rev A
API Functions
2-731
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues 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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_MediaQueryreturns:
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.
601355 Rev A
API Functions
2-733
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
Example
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 ****************************************
*********/
2-734
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
12 #ifdef ANSI_C
13 VST_BOOLEAN
vst_mediaquery_execute(void)
14 #else
15 VST_BOOLEAN vst_mediaquery_execute()
16 #endif
17 {
18
19
20
21
VST_BOOLEAN
VST_QUERY_OPTION
int
char
rc = VSE_FALSE;
queryopt;
count;
*
medialist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE cmd;
22
23
24
25
/* get parameters from user */
printf(“*** Media Query parameters
***\n” );
26
printf(“0) Query by media list, 1)
Query all ==> “ );
27
28
29
30
31
queryopt = atoi(gets(input));
if (queryopt == 0)
{
count =
vst_getmedialist(medialist,
VST_MAX_ITEMS);
}
32
33
34
35
/* create the command handle */
/* Note that the command handle is
not */
36
37
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
38
39
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
40
41
{
/* Send the command to the VolServ
software. */
601355 Rev A
API Functions
2-735
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
42
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 */
47
48
49
50
/* default parameters. */
rc = VSCMD_MediaQuery(cmd,
VSID_QRY_OPTION, queryopt,
VSID_MEDIA_ID_LIST, count,
medialist,
51
VSID_ENDFIELD);
52
}
53
return ( rc );
54 }
Notes
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_MediaQuerydoes not trigger any MediaClass
callbacks from VolServ.
The VSID_MEDIA_ID_LISTparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
•
•
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)
2-738
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaQuery_SetDefaultssets the
command-level default parameters for the Media Query
commands.
VSCMD_
MediaQuery_
SetDefaults
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
VST_BOOLEAN VSCMD_MediaQuery_SetDefaults
(
Synopsis
"…",
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)
(char **)
Number of media identified in the list.
List of media identifier to query.
601355 Rev A
API Functions
2-739
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONvalues 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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to be put in USER_FIELDfor Media
Query commands. USER_FIELDis 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.
Return Values
VSCMD_MediaQuery_SetDefaultsreturns:
• 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.
Example
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 *
601355 Rev A
API Functions
2-741
Download from Www.Somanuals.com. All Manuals Search And Download.
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
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Media Query default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_MediaQuery_SetDefaults(
VSID_PRIORITY,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
39
VSID_ENDFIELD);
return ( rc );
2-742
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
40 }
Notes
The VSID_MEDIA_ID_LISTparameter 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)
601355 Rev A
API Functions
2-743
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaTypeQueryis issued to request execution of
the VolServ Media Type Query request.
VSCMD_
MediaType-
Query
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.
VST_BOOLEAN VSCMD_MediaTypeQuery
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MEDIA_TYPE_LIST (int)
If VSE_QUERY_OPTION_NONEwas 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_NONEwas 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_OPTIONvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-745
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_MediaTypeQueryreturns:
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.
2-746
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto 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_CODEto
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.
601355 Rev A
API Functions
2-747
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediatypequery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_MediaTypeQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_mediatypequery_execute(void)
14 #else
15
VST_BOOLEAN
vst_mediatypequery_execute()
16 #endif
17 {
18
19
VST_BOOLEAN
VST_BOOLEAN
rc = VSE_FALSE;
done =
VSE_FALSE;
VST_QUERY_OPTION
int
20
21
22
queryopt;
/count = 0;
*
char
temp_media_type;
char
23
*
mediatypelist[VST_MAX_ITEMS];
VST_COMMAND_HANDLEcmd;
24
25
26
/* get parameters from user */
2-748
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
27
28
printf(“*** Media Type Query
parameters ***\n” );
printf(“0) Query by media type list,
1) Query all ==> “ );
29
30
31
32
33
queryopt = atoi(gets(input));
if (queryopt == 0)
{
count =
vst_getmediatypelist(mediatypelis
t, VST_MAX_ITEMS);
}
34
35
36
37
/* create the command handle */
/* Note that the command handle is
not */
38
39
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
40
41
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
42
43
{
/* Send the command to the VolServ
software. */
44
45
46
47
48
/* 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 */
49
50
51
52
/* default parameters. */
if (queryopt == 0)
{
/* query a list of media types
*/
53
rc = VSCMD_MediaTypeQuery(cmd,
601355 Rev A
API Functions
2-749
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
54
55
VSID_QRY_OPTION,
queryopt,
VSID_MEDIA_TYPE_LIST, count,
mediatypelist,
VSID_ENDFIELD);
56
57
58
59
60
61
62
}
else
{
/* query all media types */
rc = VSCMD_MediaTypeQuery(cmd,
VSID_QRY_OPTION, queryopt,
63
64
VSID_ENDFIELD);
}
65
}
66
67
else
{
68
rc = VSE_FALSE;
69
}
70
return ( rc );
71 }
Notes
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_MediaTypeQuerydoes not trigger any MediaClass
callbacks from VolServ.
The VSID_MEDIA_TYPE_LISTparameter requires that two
arguments be passed instead of one.
2-750
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_SetFieldsand
VS_Global_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
•
•
•
•
•
•
•
•
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)
2-752
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MediaTypeQuery_SetDefaultsis issued to set
the command-level default parameters for Media Type Query
commands.
VSCMD_
MediaType-
Query_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
VST_BOOLEAN VSCMD_MediaTypeQuery_SetDefaults (
“…”,
Synopsis
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-753
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NONEwas specified
for VSID_QUERY_OPTION, indicates the
number of media types specified in the list of
media types.
(char **)
If VSE_QUERY_OPTION_NONEwas 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_OPTIONvalues are
enumerated in the vs_types.h file.
2-754
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Media Type Query commands.
VSID_RETRY_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Media
Type Query commands. USER_FIELDis 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
VSCMD_MediaTypeQuery_SetDefaultsreturns:
• VSE_TRUE- Successful execution.
• VSE_FALSE- API failure - An appropriate error code is set
in VSG_Error.
601355 Rev A
API Functions
2-755
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mediatypequery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_MediaTypeQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_mediatypequery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_mediatypequery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
2-756
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
26
27
28
/* 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 =
29
30
31
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,
32
33
34
35
36
37
38
VSID_ENDFIELD);
39
return ( rc );
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
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
601355 Rev A
API Functions
2-757
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
VSCMD_MediaTypeQuery(l)
2-758
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
A client uses Modify Media requests to create or modify the
attribute values of an existing medium.
VSCMD_
ModifyMedia
VST_BOOLEAN VSCMD_ModifyMedia
(
Synopsis
“…”,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_MEDIA_STAT_VALUE_LIST (int)
(char **)
Media identifier of the medium to update.
Number of user statistics in the list.
An array of user statistics to associate with the
medium.
VSID_MEDIA_STAT_OPTION_LIST (int)
(VST_MEDIA_STAT_OPTION *)
Number of media statistic options in the list.
An array of media statistic options to place on
the list of user statistics. Valid
VSID_MEDIA_STAT_OPTION_LISTvalues
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_OPTIONvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-760
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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:
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 Functions
2-761
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
2-762
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_modifymedia_execute
4 *
5 * PURPOSE:
6 * This function actually tests the
VSCMD_ModifyMedia
7 * API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modifymedia_execute(void)
15 #else
16
VST_BOOLEAN
vst_modifymedia_execute()
17 #endif
18 {
19
20
21
int
int
VST_BOOLEAN
i;
num;
rc =
VSE_FALSE;
22
23
24
25
VST_COMMAND_HANDLE
VST_MEDIA_ID
cmdh;
mediaid;
batch;
VST_BATCH_NAME
VST_MANUFACTURER_NAME
manufacturer;
VST_MODMEDIA_OPTION
VST_COUNT
26
27
modopt;
field[VSD_MAX_MEDIA_STATS];
VST_MEDIA_STAT_OPTION
option[VSD_MAX_MEDIA_STATS];
char
* value[VSD_MAX_MEDIA_STATS];
char
28
29
30
valuearray[VSD_MAX_MEDIA_STATS][V
SD_MEDIA_STAT_VALUE_LEN];
601355 Rev A
API Functions
2-763
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
32
33
/* get parameters from user */
printf(“*** Modify Media Parameters
***\n”);
34
printf ( “Enter the media id to
modify ==> “ );
35
36
gets(mediaid);
printf ( “Enter the batch name
(return for none) ==> “ );
gets(batch);
printf ( “Enter the manufacturer name
==> “ );
37
38
39
40
gets(manufacturer);
printf ( “Enter the modify media
option
(1-Delete/2-Update/3-Replace)==>
“ );
41
42
modopt = (VST_MODMEDIA_OPTION)
atoi(gets(input));
printf ( “Enter the number of user
statistics ==> “ );
43
44
45
num = atoi(gets(input));
/* loop through the number of user
statistics */
46
for ( i = 0 ; i < num && i <
VSD_MAX_MEDIA_STATS ; i++ )
{
47
48
printf ( “Enter field index[%d]
==> “, i );
49
50
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 );
51
52
53
54
option[i] =
(VST_MEDIA_STAT_OPTION)
atoi(gets(input));
2-764
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
55
56
57
}
/* Create the command (assume that
the api is */
58
/* initialized). Note that status is
processed */
59
60
/* in the vst_dispatch routine. */
/* Also, the command handle created
here is */
61
/* destroyed in the dispatch routine.
*/
62
63
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
64
65
{
/* execute the modify media command
*/
66
67
/* common parameters such as
priority, timeout */
/* value, etc, have been set through
the */
68
69
70
71
/* VS_Global_SetFields or */
/* VSCMD_ModifyMedia_SetDefaults. */
rc = VSCMD_ModifyMedia ( cmdh,
VSID_MEDIA_ID,
mediaid,
72
73
74
75
76
77
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,
78
79
80
81
VSID_ENDFIELD );
}
return ( rc );
601355 Rev A
API Functions
2-765
Download from Www.Somanuals.com. All Manuals Search And Download.
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_ModifyMediadoes not trigger any MediaClass
callbacks from VolServ.
The VSID_FIELD_LIST,
VSID_MEDIA_STAT_OPTION_LIST, and
VSID_MEDIA_STAT_VALUE_LISTparameters 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_OPTIONis set to
VSE_MODMEDIA_OPTION_REPLACE, the current medium
statistics are deleted, and the statistics given in the
VSID_MEDIA_STAT_VALUE_LISTare added for the
medium.
If the VSID_MODMEDIA_OPTIONis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive intermediate
and final status for Modify Media 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_SetFieldsand
VS_Global_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
•
•
VS_Global_SetFields(l),
VSCMD_ModifyMedia_SetDefaults(l)
2-768
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyMedia_SetDefaultssets
command-level default parameters for all
VSCMD_ModifyMediacommands.
VSCMD_
ModifyMedia_
SetDefaults
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
(
Synopsis
“…”,
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(VST_COUNT *)
Number of field identifiers in the list.
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)
VSID_MEDIA_STAT_OPTION_LIST (int)
(VST_MEDIA_STAT_OPTION *)
Media identifier of the medium to modify.
Number of items in the list.
An array of media statistic options to place on
the list of user statistics.
VSID_MEDIA_STAT_VALUE_LIST (int)
(char **)
Number of user statistics in the list.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Modify
Media commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_modifymedia_execute
4 *
5 * PURPOSE:
6 * This function actually tests the
VSCMD_ModifyMedia
7 * API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modifymedia_execute(void)
15 #else
16
VST_BOOLEAN
vst_modifymedia_execute()
17 #endif
18 {
19
20
int
int
i;
num;
2-772
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
VST_BOOLEAN
rc =
VSE_FALSE;
22
23
24
25
VST_COMMAND_HANDLE
VST_MEDIA_ID
cmdh;
mediaid;
batch;
VST_BATCH_NAME
VST_MANUFACTURER_NAME
manufacturer;
VST_MODMEDIA_OPTION
VST_COUNT
26
27
modopt;
field[VSD_MAX_MEDIA_STATS];
VST_MEDIA_STAT_OPTION
option[VSD_MAX_MEDIA_STATS];
char
value[VSD_MAX_MEDIA_STATS];
char
28
29
30
valuearray[VSD_MAX_MEDIA_STATS]
[VSD_MEDIA_STAT_VALUE_LEN];
31
32
33
/* get parameters from user */
printf(“*** Modify Media Parameters
***\n”);
34
printf ( “Enter the media id to
modify ==> “ );
35
36
gets(mediaid);
printf ( “Enter the batch name
(return for none) ==> “ );
gets(batch);
printf ( “Enter the manufacturer name
==> “ );
37
38
39
40
gets(manufacturer);
printf ( “Enter the modify media
option
(1-Delete/2-Update/3-Replace)==>
“ );
41
42
modopt = (VST_MODMEDIA_OPTION)
atoi(gets(input));
printf ( “Enter the number of user
statistics ==> “ );
43
44
num = atoi(gets(input));
601355 Rev A
API Functions
2-773
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
45
46
/* loop through the number of user
statistics */
for ( i = 0 ; i < num && i <
VSD_MAX_MEDIA_STATS ; i++ )
{
47
48
printf ( “Enter field index[%d]
==> “, i );
49
50
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 );
51
52
53
54
option[i] =
(VST_MEDIA_STAT_OPTION)
atoi(gets(input));
}
55
56
57
/* Create the command (assume that
the api is */
58
/* initialized). Note that status is
processed */
59
60
/* in the vst_dispatch routine. */
/* Also, the command handle created
here is */
61
/* destroyed in the dispatch routine.
*/
62
63
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
64
65
{
/* execute the modify media command
*/
66
67
/* common parameters such as
priority, timeout */
/* value, etc, have been set through
the */
68
69
/* VS_Global_SetFields or */
/* VSCMD_ModifyMedia_SetDefaults. */
2-774
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
70
71
rc = VSCMD_ModifyMedia ( cmdh,
VSID_MEDIA_ID,
mediaid,
72
73
74
75
76
77
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,
78
VSID_ENDFIELD );
79
}
80
81
return ( rc );
82 }
Notes
The VSID_FIELD_LIST,
VSID_MEDIA_STAT_OPTION_LIST, and
VSID_MEDIA_STAT_VALUE_LISTparameters 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
•
•
VS_Global_SetFields(l),
VSCMD_ModifyMedia(l)
601355 Rev A
API Functions
2-775
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreatePoolcreates 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.
VSCMD_
CreatePool
After receiving a VSCMD_CreatePoolrequest, VolServ
creates a new drive pool and returns status to the client which
indicates the success or failure of the request.
VST_BOOLEAN VSCMD_CreatePool
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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)
(VST_DRIVE_ID *)
Number of drives to include in the new drive
pool.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-777
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_CreatePoolreturns:
•
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.
2-778
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API software
and the client uses VST_ERROR_CODEto 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 Functions
2-779
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_createpool_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_CreatePool API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_createpool_execute(void)
14 #else
15 VST_BOOLEAN vst_createpool_execute()
16 #endif
17 {
18
19
20
21
VST_BOOLEAN
VST_DRIVE_POOL_NAME dp;
int
rc = VSE_FALSE;
count;
VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE cmd;
22
23
24
25
/* get parameters from user */
printf(“*** Create Pool Parameters
***\n” );
26
printf(“\nEnter Drive Pool Name
==>”);
27
28
gets( dp );
count = vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
29
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
/* destroyed in this routine, but in
*/
2-780
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
/* vst_dispatch when final status is
received. */
34
35
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
36
37
{
/* Send the command to the VolServ
software. */
38
39
40
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also
retry limit */
41
42
43
44
45
/* and priority are set as */
/* default parameters. */
rc = VSCMD_CreatePool(cmd,
VSID_DRIVEPOOL_NAME, dp,
VSID_DRIVE_ID_LIST, count,
drivelist,
46
VSID_ENDFIELD);
47
}
48
return ( rc );
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_CreatePooldoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_MODEand
MOVEWAIT_OPTIONattributes control whether or not
Move-Mount processing is allowed for a specific archive.
These attributes are discussed under the
VS_Archive_SetFieldsand
VS_Archive_GetFieldsfunctions.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a Create Pool request submitted through the API interface to the
VolServ system.
2-782
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Two levels of default parameter settings are used in the API
software— global defaults and command-specific defaults.
The VSID_DRIVE_ID_LISTand 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_GetFieldsfunction 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.
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:
•
•
•
•
•
VSID_DRIVE_ID,
VSID_DRIVE_ID_ENTRY,
VSID_DRIVE_ID_TABLE,
VSID_DRIVEPOOL_NAME,
VSID_ERROR_CODE,
601355 Rev A
API Functions
2-783
Download from Www.Somanuals.com. All Manuals Search And Download.
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
• 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)
2-784
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_CreatePool_SetDefaultssets the
command-level default parameters for Create Pool commands.
VSCMD_
CreatePool_
SetDefaults
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_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_CreatePool_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-785
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(VST_DRIVE_ID *)
Number of drives to include in the new drive
pool.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Create Pool commands.
VSID_RETRY_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Create
Pool commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_CreatePool_SetDefaultsreturns:
•
•
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_createpool_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_CreatePool API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_createpool_defaults(void)
15 #else
16
VST_BOOLEAN
vst_createpool_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
2-788
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
The VSID_DRIVE_ID_LISTand 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CreatePool(l)
2-790
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeleteArchiveMediaClassdeletes an existing
archive media class relationship.
VSCMD_
DeleteArchive
MediaClass
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.
VST_BOOLEAN VSCMD_DeleteArchiveMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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.
601355 Rev A
API Functions
2-791
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-792
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue 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_FIELDfor this
request. USER_FIELDis 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_DeleteArchiveMediaClassreturns:
•
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 Functions
2-793
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
2-794
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_deletearchivemediaclass_execu
te
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_DeleteArchiveMediaClass
7 * API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_deletearchivemediaclass_execu
te(void)
15 #else
16
VST_BOOLEAN
vst_deletearchivemediaclass_execu
te()
17 #endif
18 {
19
20
21
22
23
24
25
VST_BOOLEAN
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME mediaclass;
VST_COMMAND_HANDLE cmd;
rc = VSE_FALSE;
archive;
/* get parameters from user */
printf(“*** Delete Archive Media
Class parameters ***\n” );
printf(“Enter Archive Name ==> “ );
gets( archive );
26
27
28
printf(“Enter Media Class Name ==> “
);
29
30
gets( mediaclass );
/* create the command handle */
601355 Rev A
API Functions
2-795
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
31
32
33
/* Note that the command handle is
not */
/* destoyed in this routine, but in
*/
/* vs_dispatch when final status is
received. */
34
35
36
37
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
38
39
40
41
42
43
44
/* 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
,
45
46
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
47
VSID_ENDFIELD);
48
}
49
return ( rc );
50 }
2-796
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_DeleteArchiveMediaClassdoes not trigger
any MediaClass callbacks from VolServ.
If the archive media class contains any media, the
VSCMD_DeleteArchiveMediaClassrequest fails. This
includes media that are currently marked for checkout or export
and have not yet been ejected.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
•
Command-specific parameter defaults for Delete Archive
Media Class commands are set with
VSCMD_DeleteArchiveMediaClass_SetDefaults. If
601355 Rev A
API Functions
2-797
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-799
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeleteArchiveMediaClass_SetDefaults
sets the command-level default parameters for Delete Archive
Media Class commands.
VSCMD_
DeleteArchive
MediaClass_
SetDefaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_DeleteArchiveMedia
Class_SetDefaults
Synopsis
(
“…”,
VSID_ENDFIELD)
2-800
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Delete
Archive Media Class commands.
USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_DeleteArchiveMediaClass_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
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_deletearchivemediaclass_defau
lts
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_DeleteArchiveMediaClass API
call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_deletearchivemediaclass_defau
lts(void)
15 #else
601355 Rev A
API Functions
2-803
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16
VST_BOOLEAN
vst_deleteaarchivemediaclass_defa
ults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* 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 =
29
30
31
VSCMD_DeleteArchiveMediaClass_Set
Defaults(
32
33
34
35
36
37
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,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
2-804
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-805
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeleteMediaClassdeletes an existing
MediaClass group from the VolServ system.
VSCMD_
DeleteMedia
Class
Upon receipt of a VSCMD_DeleteMediaClasscommand,
VolServ removes the MediaClass group and returns status to
the client indicating the success or failure of the request.
VST_BOOLEAN VSCMD_DeleteMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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_LIMITis 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_FLAGvalue is
VSE_TRUE.
601355 Rev A
API Functions
2-807
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor this
request. USER_FIELDis 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_DeleteMediaClassreturns:
•
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.
2-808
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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 Functions
2-809
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_deletemediaclass_execute
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_DeleteMediaClass API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_deletemediaclass_execute(void
)
14 #else
15
VST_BOOLEAN
vst_deletemediaclass_execute()
16 #endif
17 {
18
19
20
VST_MEDIA_CLASS_NAME
VST_COMMAND_HANDLE
VST_BOOLEAN
mediaclass;
cmd;
rc =
VSE_FALSE;
21
22
23
/* get parameters from user */
printf(“*** Delete Media Class
parameters ***\n” );
24
printf(“\nEnter Media Class name to
delete ==>”);
25
26
27
28
gets( mediaclass);
/* create the command handle */
/* Note that the command handle is
not */
29
/* destroyed in this routine, but in
*/
2-810
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
/* vst_dispatch when final status is
received. */
31
32
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
33
34
{
/* Send the command to the VolServ
software. */
35
36
37
38
39
/* 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 */
40
41
42
/* default parameters. */
rc = VSCMD_DeleteMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
43
VSID_ENDFIELD);
44
}
45
return ( rc );
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_DeleteMediaClassdoes not trigger any
MediaClass callbacks from VolServ.
If the specified MediaClass group is associated with any
archive media class relationship, the
VSCMD_DeleteMediaClassrequest fails.
601355 Rev A
API Functions
2-811
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the specified MediaClass group contains any media, the
VSCMD_DeleteMediaClassrequest fails.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
See Also
• 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)
601355 Rev A
API Functions
2-813
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeleteMediaClass_SetDefaultssets the
command-level default parameters for Delete Archive Media
Class commands.
VSCMD_
DeleteMedia
Class_Set
Defaults
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.
VST_BOOLEAN VSCMD_DeleteMediaClass_
SetDefaults
Synopsis
(
“…”,
VSID_ENDFIELD)
2-814
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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 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_LIMITis not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
601355 Rev A
API Functions
2-815
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Delete
Archive Media Class commands.
USER_FIELDis 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
VSCMD_DeleteMediaClass_SetDefaultsreturns:
•
•
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.
2-816
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
VSE_ERR_NULLSTRING - A null value was passed to a
string argument
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_deletemediaclass_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_DeleteMediaClass API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_deletemediaclass_defaults(voi
d)
15 #else
16
VST_BOOLEAN
vst_deletemediaclass_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Create Archive Media
Class default parameters ***\n” );
601355 Rev A
API Functions
2-817
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
30
31
VSCMD_DeleteMediaClass_SetDefault
s(
32
33
34
35
36
37
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,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
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_DeleteMediaClass(l)
2-818
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeletePooldeletes an existing drive pool.
VSCMD_
DeletePool
Upon receipt of a VSCMD_DeletePoolrequest, 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.
VST_BOOLEAN VSCMD_DeletePool
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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.
601355 Rev A
API Functions
2-819
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
2-820
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor this
request. USER_FIELDis 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_DeletePoolreturns:
•
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 Functions
2-821
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
2-822
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_deletepool_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_DeletePool API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_deletepool_execute(void)
14 #else
15 VST_BOOLEAN vst_deletepool_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
21
22
23
VST_DRIVE_POOL_NAME
VST_COMMAND_HANDLE
dp;
cmd;
/* get parameters from user */
printf(“*** Delete Pool Parameters
***\n” );
24
printf(“\nEnter Drive Pool name to
delete ==>”);
25
26
27
28
gets( dp );
/* create the command handle */
/* Note that the command handle is
not */
29
30
31
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
cmd = VS_Command_Create();
601355 Rev A
API Functions
2-823
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
33
34
{
/* Send the command to the VolServ
software. */
35
36
37
38
39
/* 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 */
40
41
42
/* default parameters. */
rc = VSCMD_DeletePool(cmd,
VSID_DRIVEPOOL_NAME, dp,
43
VSID_ENDFIELD);
44
}
45
return ( rc );
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 Pool request.
VSCMD_DeletePooldoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
• 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)
2-826
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DeletePool_SetDefaultssets the
command-level default parameters for Delete Pool commands.
VSCMD_
DeletePool_
SetDefaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_DeletePool_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-827
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Delete
Pool commands. USER_FIELDis 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
VSCMD_DeletePool_SetDefaultsreturns:
•
•
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 Functions
2-829
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_deletepool_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_DeletePool API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_deletepool_defaults(void)
15 #else
16
VST_BOOLEAN
vst_deletepool_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Delete Pool default
parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_DeletePool_SetDefaults(
30
31
2-830
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
33
34
35
36
37
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 );
38
39
40 }
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_DeletePool(l)
601355 Rev A
API Functions
2-831
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Disconnectdisconnects a specified Internet
address from the specified enterprise identifier. This association
of Internet address with an enterprise identifier was made via
the Connect command.
VSCMD_
Disconnect
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_Disconnectrequest, 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.
VST_BOOLEAN VSCMD_Disconnect
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_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_HANDLEis
not applicable if VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBERare 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_NUMBERis not applicable
if VSID_CONNECT_HANDLEis specified.
VSID_PROGRAM_NUMBER
(VST_PROGRAM_NUMBER)
The RPC program number of the client
process to disconnect from VolServ.
VSID_PROGRAM_NUMBERis not applicable if
VSID_CONNECT_HANDLEis 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_PROTOCOLis not applicable if
VSID_CONNECT_HANDLEis specified.
601355 Rev A
API Functions
2-833
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue 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_FIELDfor this
request. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Disconnectreturns:
•
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.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ, and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Functions
2-835
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_disconnect_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Disconnect API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_disconnect_execute(void)
14 #else
15 VST_BOOLEAN vst_disconnect_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
rc =
VSE_FALSE;
VST_ENTERPRISE_ID
TargetEnterpriseID;
VST_SOCKADDR_IN
socketaddress;
2-836
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
26
27
28
VST_PROGRAM_NUMBER
VST_COMMAND_HANDLE
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
int
prognum;
cmd;
versnum;
procnum;
temp;
/* get parameters from user */
printf(“*** Disconnect parameters
***\n” );
29
30
printf(“Enter Enterprise ID ==> “ );
TargetEnterpriseID =
atoi(gets(input));
31
32
33
34
35
printf(“Enter Program Number ==> “ );
prognum = atoi(gets(input));
printf(“Enter Version Number ==> “ );
versnum = atoi(gets(input));
printf(“Enter Procedure Number ==> “
);
36
37
procnum = atoi(gets(input));
printf(“Enter Socket sin family ==> “
);
38
39
temp = atoi(gets(input));
socketaddress.sin_family = (short)
temp;
40
printf(“Enter Socket sin port ==> “
);
41
42
temp = atoi(gets(input));
socketaddress.sin_port = (u_short)
temp;
43
printf(“Enter Socket sin address ==>
“ );
44
45
temp = atoi(gets(input));
socketaddress.sin_addr = (u_long)
temp;
46
47
48
/* create the command handle */
/* Note that the command handle is
not */
49
50
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
601355 Rev A
API Functions
2-837
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
51
52
53
54
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
55
56
57
58
59
/* 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 */
60
61
62
/* default parameters. */
rc = VSCMD_Disconnect(cmd,
VSID_TARGET_ENTERPRISE_ID,
TargetEnterpriseID,
VSID_PROGRAM_NUMBER, prognum,
VSID_VERSION_NUMBER, versnum,
VSID_PROCEDURE_NUMBER,
procnum,
63
64
65
66
VSID_SOCKADDR_IN,
socketaddress,
67
VSID_ENDFIELD);
68
}
69
return ( rc );
70 }
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
Disconnect command.
The Disconnect command cannot trigger MediaClass callbacks
from VolServ.
2-838
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VSID_CONNECT_HANDLEparameter may be used after a
Connect Query command to disconnect an enterprise after the
client has gone down.
A VSCMD_Disconnectrequest 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
•
Command-specific parameter defaults for the Disconnect
command are set with
VSCMD_Disconnect_SetDefaults. If
601355 Rev A
API Functions
2-839
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-841
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Disconnect_SetDefaultssets the
command-level default parameters for Disconnect commands.
VSCMD_
Disconnect_
SetDefaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_Disconnect_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
2-842
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_HANDLEis
not applicable if VSID_PROCEDURE_NUMBER,
VSID_PROGRAM_NUMBER, VSID_PROTOCOL,
and VSID_VERSION_NUMBERare 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_NUMBERis not applicable
if VSID_CONNECT_HANDLEis specified.
601355 Rev A
API Functions
2-843
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMBERis not applicable if
VSID_CONNECT_HANDLEis 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_PROTOCOLis not applicable if
VSID_CONNECT_HANDLEis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FIELDfor
Disconnect commands. USER_FIELDis 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
VSCMD_DeletePool_SetDefaultsreturns:
•
•
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 Functions
2-845
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_disconnect_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Disconnect API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_disconnect_defaults(void)
15 #else
16
VST_BOOLEAN
vst_disconnect_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Disconnect default
parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Disconnect_SetDefaults(
30
31
2-846
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
33
34
35
36
37
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 );
38
39
40 }
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_Connect(l),
• VSCMD_ConnectQuery(l)
601355 Rev A
API Functions
2-847
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
A VSCMD_Dismountrequest informs VolServ that the client
is finished using a drive and the medium mounted in the drive.
VSCMD_
Dismount
Upon receipt of a VSCMD_Dismountrequest 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.
VST_BOOLEAN VSCMD_Dismount
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
2-848
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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 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)
VSID_PRIORITY (VST_PRIORITY)
Identifier of the medium to dismount.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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.
The length of time, in seconds, the drive was
in use.
VSID_USAGE_TIME (VST_USAGE)
2-850
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Dismountreturns:
•
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.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto identify the
specific error.
•
VSE_ERR_BADFIELD - An invalid parameter was
specified.
601355 Rev A
API Functions
2-851
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_dismount_execute
4 *
5 * PURPOSE:
6 * This routine tests the VSCMD_Dismount
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_dismount_execute(
void )
14 #else
15
VST_BOOLEAN vst_dismount_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
VST_MEDIA_ID
VST_DRIVE_ID
VST_LOCK_ID
VST_USAGE
19
20
21
22
media;
drive;
lock;
time;
2-852
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
23
24
25
26
27
VST_COUNT
VST_COMMAND_HANDLE
err;
cmd;
/* get parameters from user */
printf(“*** Dismount parameters
***\n” );
28
29
30
31
32
33
34
35
36
37
38
39
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 */
40
41
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
42
43
44
45
cmd = VS_Command_Create();
if (cmd!= (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
46
47
48
49
50
/* 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 */
51
52
53
/* default parameters. */
rc = VSCMD_Dismount(cmd,
VSID_DRIVE_ID,
drive,
601355 Rev A
API Functions
2-853
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
54
55
56
57
VSID_MEDIA_ID,
VSID_LOCK_ID,
media,
lock,
VSID_USAGE_TIME, time,
VSID_ERROR_COUNT, err,
58
VSID_ENDFIELD);
59
}
60
return ( rc );
61 }
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
Dismount request.
VSCMD_Dismountcan trigger MediaClass callbacks from
VolServ.
VSID_USAGE_TIMEand VSID_ERROR_COUNTare 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a Dismount 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_GetFieldsfunction 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
• 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)
2-856
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Dismount_SetDefaultssets the command-level
default parameters for Dismount commands.
VSCMD_
Dismount_Set
Defaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_Dismount_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-857
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_LOCK_ID (VST_LOCK_ID)
VSID_MEDIA_ID (VST_MEDIA_ID)
Number of read/write errors encountered
while the drive was mounted.
The drive’s lock identifier, required if a drive is
locked.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Dismount
commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Dismount_SetDefaultsreturns:
•
•
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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_dismount_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Dismount API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_dismount_defaults(void)
15 #else
16 VST_BOOLEAN vst_dismount_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
VST_PRIORITY
priority;
2-860
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
user_field;
timeout;
retries;
wait_flag;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
38
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);
39 return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-861
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
• vsapi(l),
• VS_Error_GetFields(l),
• VS_Global_SetFields(l),
• VSCMD_Dismount(l)
2-862
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VSCMD_DrivePoolQueryqueries for information
about one drive pool or about all drive pools known to the
VolServ system.
VSCMD_Drive
PoolQuery
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,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-864
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor this
request. USER_FIELDis 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_DrivePoolQueryreturns:
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 Functions
2-865
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
2-866
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivepoolquery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_DrivePoolQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivepoolquery_execute(void)
14 #else
15
VST_BOOLEAN
vst_drivepoolquery_execute()
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
rc =
19
20
VST_QUERY_OPTION
VST_QUERY_LIST_OPTION
querylistopt;
queryopt;
21
22
23
24
25
26
int
count;
drivepool;
cmd;
VST_DRIVE_POOL_NAME
VST_COMMAND_HANDLE
/* get parameters from user */
printf(“*** DrivePool Query
parameters ***\n” );
27
printf(“0) Query by drive pool Name,
1) Query all ==> “ );
28
29
30
31
32
queryopt = atoi(gets(input));
if (queryopt == 0)
{
printf(“\nEnter drive pool Name
==>”);
601355 Rev A
API Functions
2-867
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
33
34
35
gets( drivepool);
}
printf(“\n1) DriveList , 2) DriveList
Details ==> “ );
36
37
38
39
querylistopt = atoi(gets(input));
/* create the command handle */
/* Note that the command handle is
not */
40
41
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
42
43
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
44
45
{
/* Send the command to the VolServ
software. */
46
47
48
49
50
/* 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 */
51
52
53
54
55
56
/* default parameters. */
if (queryopt == 0)
{
/* query a single drive pool */
rc = VSCMD_DrivePoolQuery(cmd,
VSID_QRY_OPTION,
queryopt,
57
58
VSID_POOL_QRY_OPT,
querylistopt,
VSID_DRIVEPOOL_NAME,
drivepool,
59
60
VSID_ENDFIELD);
}
2-868
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
61
62
63
64
else
{
/* query all drive pools */
rc =
VSCMD_DrivePoolQuery(cmd,
VSID_QRY_OPTION,
queryopt,
VSID_POOL_QRY_OPT,
querylistopt,
VSID_ENDFIELD);
}
65
66
67
68
69
}
70
return ( rc );
71 }
Notes
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
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_CreatePooldoes 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_GetFieldsfunction 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:
•
•
•
•
•
•
•
•
•
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.
2-870
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-871
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DrivePoolQuery_SetDefaultssets the
command-level default parameters for Drive Pool Query
commands.
VSCMD_Drive
PoolQuery_
SetDefaults
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_GetFieldsfunction 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.
VST_BOOLEAN
VSCMD_DrivePoolQuery_SetDefaults (
Synopsis
“…”,
VSID_ENDFIELD)
2-872
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 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_OPTvalues 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to be put in USER_FIELDfor Drive Pool
Query commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_DrivePoolQuery_SetDefaultsreturns:
•
•
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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivepoolquery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_DrivePoolQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_drivepoolquery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_drivepoolquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
601355 Rev A
API Functions
2-875
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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 =
29
30
31
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,
32
33
34
35
36
37
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-876
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
• vsapi(l),
• VS_Error_GetFields(l),
• VS_Global_SetFields(l),
• VSCMD_DrivePoolQuery(l)
601355 Rev A
API Functions
2-877
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DriveQueryqueries for information about one or
more drives known to the VolServ system.
VSCMD_Drive
Query
Upon receipt of a Drive Query command, VolServ obtains the
requested information and returns this information to the client.
VST_BOOLEAN VSCMD_DriveQuery
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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)
VSID_DRIVE_ID_LIST (int)
Identifier of a single drive to query.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
VSID_ENTERPRISE_ID
Description
Identifier of the enterprise, if any, to receive
final status on this request.
(VST_ENTERPRISE_ID)
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
Value to put in USER_FIELDfor this request.
USER_FIELDis 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_DriveQueryreturns:
•
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.
-
If the object code value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODEto identify the specific error.
2-880
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
If the object code value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivequery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_DriveQuery API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_drivequery_execute(void)
14 #else
15 VST_BOOLEAN vst_drivequery_execute()
601355 Rev A
API Functions
2-881
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
16 #endif
17 {
18
19
20
21
22
VST_BOOLEAN
VST_QUERY_OPTION
int
VST_DRIVE_ID
VST_DRIVE_ID
rc = VSE_FALSE;
queryopt;
count;
temp_drive_id;
drivelist[VST_MAX_ITEMS];
VST_COMMAND_HANDLE cmd;
23
24
25
26
/* get parameters from user */
printf(“*** Drive Query parameters
***\n” );
27
printf(“0) Query by drive list, 1)
Query all, 2) Query single
DriveID==> “ );
28
29
30
31
32
queryopt = atoi(gets(input));
if (queryopt == 0)
{
count =
vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
33
34
35
36
}
else if (queryopt == 2)
{
printf(“\nEnter Drive ID to query:
“);
37
temp_drive_id =
atoi(gets(input));
}
38
39
40
41
/* create the command handle */
/* Note that the command handle is
not */
42
43
/* destroyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
44
45
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
2-882
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
46
47
{
/* Send the command to the VolServ
software. */
48
49
50
51
52
/* 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 */
53
54
55
56
57
/* default parameters. */
if(queryopt == 2)
{
rc = VSCMD_DriveQuery(cmd,
VSID_QRY_OPTION,
VSE_QUERY_OPTION_NONE,
VSID_DRIVE_ID,
58
temp_drive_id,
59
60
61
62
63
64
VSID_ENDFIELD);
}
else
{
rc = VSCMD_DriveQuery(cmd,
VSID_QRY_OPTION,
queryopt,
65
VSID_DRIVE_ID_LIST,
count,drivelist,
VSID_ENDFIELD);
}
66
67
68
69
}
return ( rc );
70 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
601355 Rev A
API Functions
2-883
Download from Www.Somanuals.com. All Manuals Search And Download.
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_DriveQuerydoes 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
The VSID_DRIVE_ID_LISTand
VSID_COMP_STATE_LISTparameters require that two
arguments be passed instead of one.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
•
Command-specific parameter defaults for Drive Query
commands are set with
VSCMD_DriveQuery_SetDefaults. If
2-884
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-885
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
• 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)
2-886
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_DriveQuery_SetDefaultssets the
command-level default parameters for Drive Query commands.
VSCMD_Drive
Query_
Two levels of default parameter settings are used in the API
software—global defaults and command-specific defaults.
SetDefaults
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_DriveQuery_SetDefaults
(
Synopsis
“…”,
VSID_ENDFIELD)
601355 Rev A
API Functions
2-887
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
VSID_DRIVE_ID_LIST (int)
Identifier of a single drive to query.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Drive Query commands.
VSID_RETRY_LIMITis 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
Value to put in USER_FIELDfor Drive Query
commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_DriveQuery_SetDefaultsreturns:
•
•
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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_drivequery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_DriveQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_drivequery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_drivequery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
2-890
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
The VSID_DRIVE_ID_LISTand 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyArchiveMediaClassmodifies 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.
VSCMD_
Modify
ArchiveMedia
Class
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.
VST_BOOLEAN VSCMD_ModifyArchiveMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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.
601355 Rev A
API Functions
2-893
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
2-894
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
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)
VSID_LOW_MARK (VST_LOW_MARK)
The percentage of VSID_CAPACITYabove
which the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
The percentage of VSID_CAPACITYbelow
which the specified migration policy option is
performed or terminated. This field is
applicable only if VSID_ARCHIVE_ACTIONis
set to VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
601355 Rev A
API Functions
2-895
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue is
VSE_TRUE.
2-896
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
A value to put in USER_FIELDfor this request.
USER_FIELDis 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_ModifyArchiveMediaClassreturns:
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 Functions
2-897
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
2-898
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
3 * FUNCTION:
vst_modarchivemediaclass_execute
4 *
5 * PURPOSE:
6 * This executes the
VSCMD_ModifyArchiveMediaClass
7 * API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modarchivemediaclass_execute(
void)
15 #else
16
VST_BOOLEAN
vst_modarchivemediaclass_execute(
)
17 #endif
18 {
19
20
21
int
int
VST_BOOLEAN
i;
count;
rc =
VSE_FALSE;
22
23
VST_ARCHIVE_NAME
VST_MEDIA_CLASS_NAME
mediaclass;
archive;
24
25
26
27
28
29
VST_CAPACITY
VST_ARCHIVE_ACTION_OPTION action;
VST_HIGH_MARK
VST_LOW_MARK
capacity;
highmark;
lowmark;
migpri;
VST_PRIORITY
VST_ARCHIVE_NAME
targetarchive;
VST_TABLE_HANDLE
comphandletable;
VST_COMPONENT_HANDLE
comphandle;
30
31
601355 Rev A
API Functions
2-899
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
VST_COMP_TYPE CompType =
VSE_COMPTYPE_COLUMN;
VST_COMPONENT_ID
33
34
35
36
CompID;
cmd;
VST_COMMAND_HANDLE
bzero ( CompID, sizeof (
VST_COMPONENT_ID ) );
37
38
/* get parameters from user */
printf(“*** Modify parameters***\n”
);
39
printf(“*** The archive media class
grouping must exist. ***\n”);
printf(“Enter Archive Name ==> “ );
gets( archive );
printf(“Enter Media Class Name ==> “
);
40
41
42
43
44
gets( mediaclass );
printf(“Enter Capacity Percent ==> “
);
45
46
capacity = atoi(gets(input));
printf(“Enter Archive action option
(0-none/1-mig/2-notify) ==> “ );
action = atoi(gets(input));
printf(“Enter High Mark Percentage
==> “ );
47
48
49
50
highmark = atoi(gets(input));
printf(“Enter Low Mark Percentage ==>
“ );
51
52
53
lowmark = atoi(gets(input));
if ( action == VSE_ARCHIVE_ACTION_MIG
)
54
55
{
printf(“Enter Target Archive ==> “
);
56
57
gets( targetarchive );
printf(“Enter Migration Priority
== > “ );
58
59
migpri = atoi(gets(input));
/* These only need to be set when
migration */
60
/* is used. */
2-900
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
61
VSCMD_ModifyArchiveMediaClass_Set
Defaults (
62
63
VSID_TARGET_ARCHIVE_NAME,
targetarchive,
VSID_MIGRATION_PRIORITY,
migpri,
64
65
66
67
VSID_ENDFIELD );
}
printf(“How many prefered placements
(0 to skip): “);
count = atoi(gets(input));
if (count > 0)
68
69
70
71
{
comphandletable =
VS_Table_Create(VSE_COMPONENT_HAN
DLE, count);
72
if (comphandletable ==
(VST_TABLE_HANDLE) NULL)
{
return (VSE_FALSE);
}
for (i = 0; i < count; i++)
{
printf(“Enter row #%d:”, i +
1);
73
74
75
76
77
78
79
80
81
CompID[0] = (short)
atoi(gets(input));
printf(“Enter column #%d:”, i +
1);
CompID[1] = (short)
atoi(gets(input));
CompID[2] = 0;
82
83
84
CompID[3] = 0;
comphandle =
VS_Component_Create();
85
86
VS_Component_SetFields(comphandle
,
VSID_COMP_TYPE,
CompType,
601355 Rev A
API Functions
2-901
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
87
VSID_COMP_ID,
CompID,
88
89
VSID_ENDFIELD);
VS_Table_AddEntry(comphandletable
,comphandle);
}
90
91
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
92
VSID_COMPONENT_HANDLE_TABLE,
comphandletable,
93
94
95
96
97
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
98
99
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
100 cmd = VS_Command_Create();
101 if (cmd != (VST_COMMAND_HANDLE )NULL)
102 {
103
104
105
106
107
108
/* 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 */
109
110
/* default parameters. */
rc =
VSCMD_ModifyArchiveMediaClass(cmd
,
2-902
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
111
112
113
114
115
VSID_ARCHIVE_NAME,
archive,
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_HIGH_MARK,
highmark,
lowmark,
capacity,
VSID_LOW_MARK,
VSID_CAPACITY,
VSID_ENDFIELD);
116
117 }
118 return ( rc );
119}
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
Modify Archive Media Class.
VSCMD_ModifyArchiveMediaClassdoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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:
•
•
After any Eject, Enter, Reclassify, or Modify Archive
Media Class command executes.
After the MediaClass group or archive media class are
redefined.
2-904
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_MARKis
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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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_GetFieldsfunction calls.
Note
Global defaults for all commands are initialized at startup
and can be set or retrieved using
VS_Global_SetFieldsand VS_Global_GetFields
function calls.
601355 Rev A
API Functions
2-905
Download from Www.Somanuals.com. All Manuals Search And Download.
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:
• 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.
2-906
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
601355 Rev A
API Functions
2-907
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyArchieMediaClass_SetDefaults
sets the command-level default parameters for Modify Archive
Media Class commands.
VSCMD_
Modify
ArchiveMedia
Class_Set
Defaults
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_GetFieldsfunction 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
VST_BOOLEAN VSCMD_ModifyArchiveMediaClass
_SetDefaults
( “…”,
Synopsis
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 used as a command default
2-908
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_ARCHIVE_ACTION
(VST_ARCHIVE_ACTION_MODE)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
The value to put in USER_FIELDfor Modify
Archive Media Class commands.
USER_FIELDis 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.
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
Example
1 /****************************************
*********
2 *
3 * FUNCTION:
vst_modarchivemediaclass_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
601355 Rev A
API Functions
2-911
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
7 * VSCMD_ModifyArchiveMediaClass API
call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modarchivemediaclass_defaults
(void)
15 #else
16
VST_BOOLEAN
vst_modarchivemediaclass_defaults
()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* 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 =
29
30
31
VSCMD_ModifyArchiveMediaClass_Set
Defaults(
32
33
VSID_PRIORITY,
VSID_USER_FIELD,
user_field,
priority,
34
VSID_TIMEOUT_VALUE,
timeout,
2-912
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
35
36
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
retries,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
39
VSID_ENDFIELD);
return ( rc );
40 }
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_ModifyArchiveMediaClass(l)
601355 Rev A
API Functions
2-913
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyMediaClassmodifies the value of one or
more attributes of a MediaClass group. A MediaClass group
establishes common characteristics for the media it contains.
VSCMD_
ModifyMedia
Class
All MediaClass group attributes must be specified on a Modify
Media Class request, whether the value of an attribute is being
modified or not.
VST_BOOLEAN VSCMD_ModifyMediaClass
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Description
VSID_CAPACITY (VST_CAPACITY)
The maximum number of media allowed in
this MediaClass group.
2-914
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_CLASS_MOUNT_STATE
(VST_CLASS_MOUNT_STATE)
Indicates whether this MediaClass group
supports the mount by MediaClass
functionality. Valid
VSID_CLASS_MOUNT_STATEvalues 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_OPTIONvalues 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)
VSID_HOST_NAME (VST_HOST_NAME)
The percentage of VSID_CAPACITYabove
which the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
The network-assigned name of the computer
where the task that listens for MediaClass
callbacks executes. Applicable only if
VSID_CLASS_RPB_OPTIONis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMBERis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBERis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBERis not
applicable.
2-916
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PROTOCOL (VST_PROTOCOL)
The Internet protocol VolServ is to use to send
callbacks for this MediaClass group. The
default VSID_PROTOCOLis VSE_PROT_TCP.
VSID_PROTOCOLis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOLis 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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
A value to put in USER_FIELDfor Modify
Media Class commands. USER_FIELDis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBERis not
applicable.
Return Values
VSCMD_ModifyMediaClassreturns:
• 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.
2-918
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API, and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
601355 Rev A
API Functions
2-919
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
3 * FUNCTION: vst_modmediaclass_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_ModMediaClass
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_modmediaclass_execute(void)
14 #else
15
VST_BOOLEAN
vst_modmediaclass_execute()
16 #endif
17 {
18
VST_BOOLEAN
VSE_FALSE;
rc =
19
20
21
22
23
24
25
26
27
VST_MEDIA_CLASS_NAME
VST_MEDIA_CLASS_NAME
VST_CAPACITY
VST_CLASS_MOUNT_STATE mountstate;
VST_HIGH_MARK
VST_COMMAND_HANDLE
VST_NOTIFY_COMMENT
VST_CLASS_RPC_OPTION
VST_HOSTNAME
mediaclass;
newclass;
capacity;
highmark;
cmd;
comment;
rpc_option;
rpc_hostname;
28
29
30
31
VST_PROGRAM_NUMBER
VST_VERSION_NUMBER
VST_PROCEDURE_NUMBER
VST_PROTOCOL
rpc_prognum;
rpc_versnum;
rpc_procnum;
rpc_protocol;
32
VST_ENTERPRISE_ID
enterpriseid;
33
34
35
/* get parameters from user */
printf(“*** Modify Media Class
parameters ***\n” );
2-920
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
36
printf(“\nEnter Media Class to modify
==>”);
37
38
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: “);
39
40
41
42
43
44
45
46
mountstate = atoi(gets(input));
printf(“\nEnter high mark ==>”);
highmark = atoi(gets(input));
printf(“\nEnter notify comment
==>”);
47
48
gets(comment);
printf(“\nEnter Option (0) no
callbacks, (1) standard, (2)
Enterprise ==>”);
49
50
rpc_option = (VST_CLASS_RPC_OPTION)
atoi(gets(input));
if (rpc_option ==
VSE_CLASS_RPC_NONE)
51
52
{
VSCMD_ModifyMediaClass_SetDefault
s(
53
VSID_CLASS_RPC_OPTION,
rpc_option,
54
55
56
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_STANDARD)
{
57
58
printf(“\nEnter RPC Host Name
==>”);
59
60
gets(rpc_hostname);
printf(“\nEnter program number
==>”);
61
rpc_prognum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
601355 Rev A
API Functions
2-921
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
62
63
printf(“\nEnter version number
==>”);
rpc_versnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter procedure number
==>”);
64
65
rpc_procnum =
(VST_PROGRAM_NUMBER)
atol(gets(input));
printf(“\nEnter Protocol (6) TCP
or (17) UDP ==>”);
rpc_protocol = (VST_PROTOCOL)
atoi(gets(input));
66
67
68
VSCMD_ModifyMediaClass_SetDefault
s(
69
70
VSID_HOST_NAME, rpc_hostname,
VSID_CLASS_RPC_OPTION,
rpc_option,
71
72
73
74
VSID_PROGRAM_NUMBER,
rpc_prognum,
VSID_VERSION_NUMBER,
rpc_versnum,
VSID_PROCEDURE_NUMBER,
rpc_procnum,
VSID_PROTOCOL,
rpc_protocol,
75
76
77
VSID_ENDFIELD);
}
else if (rpc_option ==
VSE_CLASS_RPC_ENTERPRISE)
{
78
79
printf(“\nEnter enterprise id
==>”);
80
81
enterpriseid =
(VST_ENTERPRISE_ID)
atol(gets(input));
VSCMD_ModifyMediaClass_SetDefault
s(
2-922
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
82
83
VSID_CLASS_RPC_OPTION,
rpc_option,
VSID_TARGET_ENTERPRISE_ID,
enterpriseid,
84
85
86
87
88
VSID_ENDFIELD);
}
/* create the command handle */
/* Note that the command handle is
not */
89
90
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
91
92
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
93
94
{
/* Send the command to the VolServ
software. */
95
96
97
98
99
/* 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 */
100
101
102
/* default parameters. */
rc = VSCMD_ModifyMediaClass(cmd,
VSID_MEDIA_CLASS_NAME,
mediaclass,
103
104
105
106
VSID_NEW_MEDIA_CLASS_NAME,
newclass,
VSID_CAPACITY,
capacity,
VSID_CLASS_MOUNT_STATE,
mountstate,
VSID_HIGH_MARK,
highmark,
601355 Rev A
API Functions
2-923
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
107
VSID_NOTIFY_COMMENT,
comment,
VSID_ENDFIELD);
108
109 }
110 return ( rc );
111}
Notes
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_LIMITplus 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_MARKhas been reached
or exceeded occur after any Reclassify, Import, or Modify
Media Class command.
VSID_CAPACITYis a hard limit. VolServ does not permit the
number of media assigned to a MediaClass group to exceed the
VSID_CAPACITYfor that MediaClass group.
If the VSID_ENTERPRISE_IDparameter 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When the API software is operating in asynchronous mode,
client software must call VS_Selectto 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_GetFieldsfunction 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:
• VSID_MEDIA_CLASS_NAME,
• VSID_SEQUENCE_NUM,
• VSID_SEQUENCE_TABLE,
• VSID_STATUS_CODE,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD.
601355 Rev A
API Functions
2-925
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CreateMediaClass(l),
VSCMD_DeleteMediaClass(l),
VSCMD_ModifyMediaClass_SetDefaults(l)
2-926
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyMediaClass_SetDefaultssets the
command-level default parameters for Modify Media Class
commands.
VSCMD_
ModifyMedia
Class_Set
Defaults
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_GetFieldsfunction 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.
VST_BOOLEAN VSCMD_ModifyMediaClass
( “…”,
Synopsis
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 used as a command default
601355 Rev A
API Functions
2-927
Download from Www.Somanuals.com. All Manuals Search And Download.
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_STATEvalues 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_OPTIONvalues 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)
(VST_ENTERPRISE_ID)
The number of enterprise identifiers in the list.
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_CAPACITYabove
which the specified migration policy option is
performed or initiated. This field is applicable
only if VSID_ARCHIVE_ACTIONis set to
VSE_ARCHIVE_ACTION_NOTIFYor
VSE_ARCHIVE_ACTION_MIG.
2-928
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_OPTIONis 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_NUMBERis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROCEDURE_NUMBERis not applicable.
601355 Rev A
API Functions
2-929
Download from Www.Somanuals.com. All Manuals Search And Download.
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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_PROGRAM_NUMBERis not
applicable.
VSID_PROTOCOL (VST_PROTOCOL)
The Internet protocol VolServ is to use to send
callbacks for this MediaClass group. The
default VSID_PROTOCOLis VSE_PROT_TCP.
VSID_PROTOCOLis required if
VSID_CLASS_RPC_OPTIONis set to
VSE_CLASS_RPC_ENTERPRISE. Otherwise,
VSID_PROTOCOLis 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_LIMITis 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_FLAGvalue 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_FIELDfor Modify
Media Class commands. USER_FIELDis 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_OPTIONis
set to VSE_CLASS_RPC_ENTERPRISE.
Otherwise, VSID_VERSION_NUMBERis not
applicable.
Return Values
VSCMD_ModifyMediaClass_SetDefaultsreturns:
• 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 Functions
2-931
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_BADSIZE- The value passed for a string
parameter exceeds the maximum allowable length for that
parameter.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_modmediaclass_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ModMediaClass API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modmediaclass_defaults(void)
15 #else
16
VST_BOOLEAN
vst_modmediaclass_defaults()
17 #endif
18 {
19
20
21
22
23
24
25
26
27
28
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” );
2-932
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc =
30
31
VSCMD_ModifyMediaClass_SetDefault
s(
32
33
34
35
36
37
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,
38
39
VSID_ENDFIELD);
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
601355 Rev A
API Functions
2-933
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_ModifyMediaClass(l)
2-934
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyPoolmodifies 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_ModifyPoolrequest.
VSCMD_
ModifyPool
VST_BOOLEAN VSCMD_ModifyPool
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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_LISTindicates
whether the corresponding entry in
VSID_DRIVE_ID_LISTis added to or
deleted from the specified drive pool. Valid
VSID_MODPOOL_OPTIONvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-936
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor this
request. USER_FIELDis 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_ModifyPoolreturns:
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 Functions
2-937
Download from Www.Somanuals.com. All Manuals Search And Download.
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
2-938
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_modpool_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_ModifyPool API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_modpool_execute(void)
14 #else
15 VST_BOOLEAN vst_modpool_execute()
16 #endif
17 {
18 VST_BOOLEAN
19 VST_DRIVE_POOL_NAME
20 int
rc = VSE_FALSE;
dp;
count;
i;
21 int
22 VST_DRIVE_ID
drivelist[VST_MAX_ITEMS];
23 VST_POOL_DRIVE_OPTION
optionlist[VST_MAX_ITEMS];
24 VST_COMMAND_HANDLE
25
cmd;
26
27
/* get parameters from user */
printf(“*** Modify Pool Parameters
***\n” );
601355 Rev A
API Functions
2-939
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
28
printf(“\nEnter Drive Pool to modify
==>”);
29
30
gets( dp );
count = vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
31
printf(“\nPlease select the action to
take on each drive\n”);
for (i = 0; i < count; i++)
{
32
33
34
printf(“drive %d: (1) add to pool,
(2) delete: “, drivelist[i]);
optionlist[i] =
35
(VST_POOL_DRIVE_OPTION)
atoi(gets(input));
36
37
38
39
}
/* create the command handle */
/* Note that the command handle is
not */
40
41
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
42
43
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
44
45
{
/* Send the command to the VolServ
software. */
46
47
48
49
50
/* 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 */
51
52
53
/* default parameters. */
rc = VSCMD_ModifyPool(cmd,
VSID_DRIVEPOOL_NAME, dp,
2-940
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
54
55
VSID_DRIVE_ID_LIST, count,
drivelist,
VSID_MODPOOL_OPTION_LIST,
count, optionlist,
56
VSID_ENDFIELD);
57
}
58
return ( rc );
59 }
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
Modify Pool request.
VSCMD_ModifyPooldoes 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Whether or not Move-Mount action processing is permitted is
specified at the archive level. The ACTION_MODEand
MOVEWAIT_OPTIONattributes control whether or not
Move-Mount processing is allowed for a specific archive.
These attributes are discussed under the
VS_Archive_SetFieldsand
VS_Archive_GetFieldsfunctions.
The VSID_DRIVE_ID_LISTand
VSID_MODPOOL_OPTION_LISTparameters 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
2-942
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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.
The following fields can be retrieved from the status handle
after a successful Modify Pool request:
• 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.
601355 Rev A
API Functions
2-943
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CreatePool(l),
VSCMD_DeletePool(l),
VSCMD_ModifyPool_SetDefaults(l)
2-944
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_ModifyPool_SetDefaultssets the
command-level default parameters for Modify Pool commands.
VSCMD_
ModifyPool_
SetDefaults
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_GetFieldsfunction 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.
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.
VST_BOOLEAN VSCMD_ModifyPool_SetDefaults
( “…”,
Synopsis
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.
601355 Rev A
API Functions
2-945
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
(VST_POOL_DRIVE_OPTION *)
The number of entries in the modify pool
option list.
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_OPTIONreplaces
VSID_MODPOOL_OPTION_LISTwhen all
drives are to be modified in some manner.
2-946
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_PRIORITY (VST_PRIORITY)
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Modify
Pool commands. USER_FIELDis 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
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_ModifyPool_SetDefaultsreturns:
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_modpool_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_ModifyPool API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_modpool_defaults(void)
15 #else
16 VST_BOOLEAN vst_modpool_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
2-948
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
20
21
22
23
24
25
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;
26
27
28
/* 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,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
The VSID_DRIVE_ID_LISTand
VSID_MODPOOL_OPTION_LISTparameters require that two
arguments be passed instead of one.
•
The first argument passed is the number of drives to be
added to or deleted from the specified drive pool.
601355 Rev A
API Functions
2-949
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
The second argument is the list of identifier of the drives to
be added to or deleted from the specified drive pool.
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_ModifyPool(l)
2-950
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Mountrequests that VolServ mount a medium on a
drive.
VSCMD_
Mount
When issuing a Mount command, the client can specify:
•
•
•
•
A single medium
A list of media
A MediaClass group
and either:
-
-
-
A specific drive
A drive pool
A drive pool with the exclusion of drives
When a MediaClass group is specified, the client has the option
to reclassify the selected medium into a different MediaClass
group by specifying the
VSID_TARGET_MEDIA_CLASS_NAMEparameter. If this
option is specified, VolServ reclassifies the selected medium
before performing any other action on the medium. Using this
option is similar to issuing a Reclassify request for the medium.
The Mount request supports a lock identifier parameter. This
parameter is required if the drive to be used in satisfying the
Mount request is locked. If a Mount request is issued for a
locked drive and does not specify a lock identifier, the Mount
request waits until the requested drive is unlocked.
The client also has the option of specifying how to handle a
mount that requires an inter-archive movement of the medium.
This option indicates whether an inter-archive medium
movement should or should not be attempted and whether to
consider if the source and destination archives are operator
attended or not.
601355 Rev A
API Functions
2-951
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If more than one medium and/or more than one drive is
specified on the Mount request, VolServ applies a selection
algorithm to select a medium/drive pair from the lists of media
and drives.
For manual archives, a Mount notice is sent to the operator
console for action. The operator is then responsible for
confirmation to VolServ when the mount is complete. VolServ
returns status to the client after the operator action is complete.
A Mount request is queued for later processing if:
•
•
•
Specified/selected drive is busy.
Specified/selected medium is busy.
Specified/selected drive is locked and a Lock identifier was
not specified on the Mount request.
When a Mount request is queued for later processing, VolServ
returns intermediate status to the client that indicates the reason
the Mount request was queued.
VST_BOOLEAN VSCMD_Mount
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Mount 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.
2-952
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 for this request.
VSID_CRITERIA_GROUP_HANDLE (int)
The index of a criteria group in the criteria
group table to be used in selecting a medium
to satisfy the Mount request. The valid range
for VSID_CRITERIA_GROUP_HANDLE
(int)is 0 to 3, inclusive.
(VST_CRITERIAGROUP_HANDLE)
VSID_DRIVE_EXCL_LIST (int)
A criteria group in the criteria group table to be
used in selecting a medium to satisfy the
Mount request. There can be 0 to 4 criteria
groups defined for a Mount request.
The number of drives to exclude from the
specified drive pool.
VSID_DRIVE_EXCL_LISTis applicable only
if the client is requesting a mount by drive
pool.
(VST_DRIVE_ID *)
The list of drives to exclude from the specified
drive pool. VSID_DRIVE_EXCL_LISTis
applicable only if the client is requesting a
mount by drive pool.
VSID_DRIVE_ID (VST_DRIVE_ID)
The identifier of the drive to mount.
VSID_DRIVE_IDis applicable only if the
client is specifying a specific drive to be
mounted.
601355 Rev A
API Functions
2-953
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
The name of the drive pool where a drive is
selected to satisfy the Mount request. Valid
drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_DRIVEPOOL_NAMEis applicable only if
the client is requesting a mount by drive pool.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_LOCK_ID (VST_LOCK_ID)
The lock identifier associated with a locked
drive that is specified or selected to honor the
Mount request. A lock identifier is assigned to
a drive with a VSCMD_Lockrequest.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The name of the MediaClass group where a
medium is selected to honor the Mount
request. VSID_MEDIA_CLASS_NAMEis
applicable only if the client is specifying a
mount by MediaClass group.
VSID_MEDIA_ID (VST_MEDIA_ID)
VSID_MEDIA_ID_LIST (int)
The identifier of the medium to be mounted.
VSID_MEDIA_IDis applicable only if the
client is specifying a mount of a specific
medium.
The number of media in the list of media
where the medium to honor the Mount request
is selected. VSID_MEDIA_ID_LIST (int)
is applicable only if the client is specifying a
mount from a media identifier list.
(char **)
The list of media where the medium to honor
the Mount request is selected.
VSID_MEDIA_ID_LIST (int)is applicable
only if the client is specifying a mount from a
media identifier list.
2-954
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
VSID_MOUNT_HANDLE
Description
A handle that contains Mount command
parameters. A client can set mount
parameters in a mount handle with the
VS_Mount_SetFieldsfunction. A mount
handle can be passed in a Mount request
instead of specifying the mount parameters on
the Mount request itself.
(VST_MOUNT_HANDLE)
VSID_MOUNT_OPTION
(VST_MOUNT_OPTION)
A flag that indicates which mount processing
options are in effect for the Mount command.
Valid VSID_MOUNT_OPTIONvalues are listed
in the vs_defs.h file.
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION)
Indicates whether a Mount request should
wait or fail if an inter-archive medium
movement is required to complete the Mount
request and either the source or target archive
is unattended. Valid
VSID_MOVEWAIT_OPTIONvalues 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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-955
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_TARGET_MEDIA_CLASS _NAME)
The name of the MediaClass group where the
mounted medium is reclassified if the
reclassify option is in effect for the Mount
request.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor this
request. USER_FIELDis 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_Mountreturns:
VSE_TRUE
•
-
Successful execution if the API is operating in
synchronous mode
2-956
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
601355 Rev A
API Functions
2-957
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mount_pool_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Mount API call
for drive
7 * pools.
8 *
9 * PARAMETERS:
10 * none
11 *
12 *
13 ****************************************
*********/
14 #ifdef ANSI_C
15
VST_BOOLEAN
vst_mount_pool_execute(void)
16 #else
17 VST_BOOLEAN vst_mount_pool_execute()
18 #endif
19 {
20 VST_BOOLEAN
rc =
VSE_FALSE;
21 int
i;
22 int
23 VST_DRIVE_POOL_NAME
24 VST_DRIVE_ID
entry;
drivepool;
excllist[VST_MAX_ITEMS];
25 int
26 VST_MEDIA_ID
exclcount;
mediaid;
2-958
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
27 VST_LOCK_ID
lockid;
28 VST_CRITERIAGROUP_HANDLE grouph;
29 VST_COMMAND_HANDLE
30
cmdh;
31
32
/* get parameters from user */
printf ( “Enter Drive Pool for mount
==> “ );
33
34
gets(drivepool);
printf(“\n*** Exclusion List
***\n”);
35
36
exclcount =
vst_getdrivelist(excllist,
VST_MAX_ITEMS);
printf ( “Enter Media ID for mounting
==> “ );
37
38
gets(mediaid);
printf ( “Mount by criteria (1) yes
or (2) no ==> “ );
entry = atoi(gets(input));
if ( entry == 1 )
39
40
41
42
{
printf ( “Enter number of criteria
groups ==> “ );
43
44
45
46
entry = atoi(gets(input));
for ( i = 0 ; i < entry ; i++ )
{
grouph =
vst_create_mount_criteria();
if ( grouph !=
47
(VST_CRITERIAGROUP_HANDLE) NULL )
{
/* It is easiest to set
criteria */
48
49
50
51
52
53
54
/* groups in the default
function as */
/* done here. This is
particularly */
/* true if it is desired to
use more */
/* than one criteria group.
*/
VSCMD_Mount_SetDefaults (
601355 Rev A
API Functions
2-959
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
55
VSID_CRITERIA_GROUP_HANDLE, i,
grouph,
56
57
58
59
60
61
62
63
VSID_ENDFIELD );
}
}
}
printf(“Enter lock id ==> “);
lockid = atol(gets(input));
/* create the command (assume that
the api is */
64
65
66
/* initialized) */
cmdh = VS_Command_Create();
if ( cmdh != (VST_COMMAND_HANDLE)
NULL)
67
68
69
{
/* execute the mount command. */
/* if sync, we will wait for the
mount to */
70
71
/* complete if async, we will
leave once */
/* initial status has been
returned */
72
73
rc = VSCMD_Mount ( cmdh,
VSID_DRIVEPOOL_NAME,
drivepool,
74
75
76
VSID_DRIVE_EXCL_LIST,
exclcount, excllist,
VSID_MEDIA_ID,
mediaid,
VSID_LOCK_ID,
lockid,
77
78
VSID_ENDFIELD );
}
79
else
80
{
81
82
rc = VSE_FALSE;
}
83
return ( rc );
84 }
2-960
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Mount request.
VSCMD_Mountdoes not trigger any MediaClass callbacks
from VolServ.
Depending on the number of available drives and pending
Mountrequests, a specific Mount request can take a relatively
long time to satisfy.
A drive that is specified in a Mount request may not be the ideal
drive on which to mount the specified medium. It may take
considerably longer to mount the medium onto the drive than if
a drive pool had been specified.
The VSID_MOVEWAIT_OPTIONoption has no affect on a
Mount request for a medium and drive associated with the same
archive.
If the specified drive is locked, the appropriate lock identifier
must be supplied if that drive is considered in the selection
process.
If a specified or selected drive is locked and the Mount request
does not specify a lock identifier, VolServ returns an
intermediate status message with a “drive locked” indication.
VolServ then waits for the drive to become unlocked to
continue execution of the command.
If the Mount request specifies a MediaClass group or a list of
media and the reclassify option is selected, the reclassify to a
different MediaClass group occurs after a specific medium is
selected to satisfy the Mountrequest. Only the selected
medium is reclassified.
601355 Rev A
API Functions
2-961
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the reclassify option is selected, the receiving MediaClass
group is checked for compatible media type as well as having
adequate capacity for another medium (i.e., fill level less than
capacity). If either condition is not satisfied, the Mount request
fails.
A pending Mount request (awaiting drive or medium) can be
cancelled.
If no drive specified on a Mount request is on-line, the Mount
request fails.
If a medium and/or drive is specified and either the medium or
drive (or both) are presently in-use, the Mount request waits for
resources and returns intermediate status indicating the reason
for the delay.
When specifying a drive pool that contains drives that support
different types of media, only those drives that support the
media type of the media specified in the Mount request are
considered for selection.
If a list of media specified in a Mount request contains media of
more than one type, the request fails.
When a medium/drive pairing requires the medium be moved
within a single archive system (such as cross-aisle or
inter-manipulator unit) the mount may take a while to complete.
The VSID_MOVEWAIT_OPTIONsetting does NOT apply to
intra-archive system movement.
When a Mount request with groups of media and/or drives is
submitted, VolServ attempts to select a drive/medium pair
where the drive and medium are associated with the same
archive. If there are multiple drive/medium pair candidates,
VolServ selects a drive/medium pair from the archive with a
free drive if, possible.
2-962
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If there is no drive/medium pair associated with the same
archive, VolServ then selects a drive/medium pair where the
drive and medium are associated with different archives. If
there are multiple drive/medium pair candidates, VolServ
selects a drive/medium pair from the archive with a free drive,
if possible. If all archives contain the same number of drives
with no drives available, VolServ then selects a drive/medium
pair from the archive with the largest number of media.
When specifying a mount by MediaClass group associated
across more than one archive, no inter-archive medium/drive
pairing is permitted. The medium selected from the MediaClass
group must be in the same archive as the selected drive;
otherwise the Mount request fails.
When a medium is ejected (as a result an Export or Checkout
request), no check is made to determine if a Mount request
exists in the queue for the ejected medium. As a result, the
Mount request remains queued until a drive is freed. At that
time, the Mount request fails because the medium is not
available. In other words, the request queue is not checked for
impact on pending requests each time a resource changes its
availability and after a medium/drive pair is identified. VolServ
does not attempt re-pairing based on changed availability of
resources.
A queued Mount request (awaiting drive or medium) can be
cancelled.
The VSID_CRITERIA_GROUP_HANDLEparameter require that
two arguments be passed instead of one.
•
•
The first argument passed is the number of criteria groups
handles to be used in selecting the medium to be mounted.
The second argument is the list of criteria group handles to
be used in selecting the medium to be mounted.
601355 Rev A
API Functions
2-963
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VSID_DRIVE_EXCL_LISTparameter require that two
arguments be passed instead of one.
•
•
The first argument passed is the number of drives to be
excluded from the specified drive pool.
The second argument is the list of the identifier of the drives
to be excluded from the specified drive pool.
The VSID_MEDIA_ID_LISTparameter requires that two
arguments be passed instead of one.
•
•
The first argument passed is the number of media specified
where the medium to honor the Mount request is selected.
The second argument is the list of media where the medium
to honor the Mount request is selected.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a Mount 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_GetFieldsfunction calls.
2-964
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
Command-specific parameter defaults for Mount
commands are set with VSCMD_Mount_SetDefaults. If
command-specific defaults are set for Mount 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 Mount
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 Mount request:
• VSID_DRIVE_ID,
• 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,
• VSID_WAIT_REASON.
601355 Rev A
API Functions
2-965
Download from Www.Somanuals.com. All Manuals Search And Download.
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_CriteriaGroup_Create(l),
VS_CriteriaGroup_SetFields(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Mount_Create(l),
VS_Mount_Destroy(l)
VS_Mount_GetFields(l),
VS_Mount_SetFields(l),
VS_Status_GetFields(l),
VSCMD_Mount_SetDefaults(l)
2-966
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Mount_SetDefaultssets the command-level
default parameters for Mount commands.
VSCMD_
Mount_Set
Defaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Mount
commands are set with VSCMD_Mount_SetDefaults. If
command-specific defaults are set for Mount 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 Mount
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_Mount_SetDefaults
( “…”,
Synopsis
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.
601355 Rev A
API Functions
2-967
Download from Www.Somanuals.com. All Manuals Search And Download.
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 Mount commands.
VSID_CRITERIA_GROUP_HANDLE (int)
The index of a criteria group in the criteria
group table to use in selecting a medium to
satisfy the Mount request. The valid range for
VSID_CRITERIA_GROUP_HANDLE (int)is
0 to 3, inclusive.
(VST_CRITERIAGROUP_HANDLE)
VSID_DRIVE_EXCL_LIST (int)
A criteria group in the criteria group table to
use in selecting a medium to satisfy the Mount
request. There can be 0 to 4 criteria groups
defined for a Mount request.
The number of drives to exclude from the
specified drive pool.
VSID_DRIVE_EXCL_LISTis applicable only
if the client is requesting a Mount by drive
pool.
(VST_DRIVE_ID *)
The list of drives to exclude from the specified
drive pool. VSID_DRIVE_EXCL_LISTis
applicable only if the client is requesting a
Mount by drive pool.
VSID_DRIVE_ID (VST_DRIVE_ID)
The identifier of the drive to mount.
VSID_DRIVE_IDis applicable only if the
client specifies a specific drive to be mounted.
2-968
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVEPOOL_NAME
(VST_DRIVE_POOL_NAME)
The name of the drive pool where a drive is
selected to satisfy the Mount request. Valid
drive pool names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
VSID_DRIVEPOOL_NAMEis applicable only if
the client is requesting a mount by drive pool.
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on Mount
commands.
VSID_LOCK_ID (VST_LOCK_ID)
The lock identifier associated with a locked
drive that is specified or selected to honor the
Mount request. A lock identifier is assigned to
a drive with a VSCMD_Lockrequest.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The name of the MediaClass group where a
medium is selected to honor the Mount
request. VSID_MEDIA_CLASS_NAMEis
applicable only if the client is specifying a
mount by MediaClass group.
VSID_MEDIA_ID (VST_MEDIA_ID)
VSID_MEDIA_ID_LIST (int)
The identifier of the medium to be mounted.
VSID_MEDIA_IDis applicable only if the
client is specifying a mount of a specific
medium.
The number of media in the list of media
where the medium to honor the Mount request
is selected. VSID_MEDIA_ID_LISTis
applicable only if the client is specifying a
mount from a media identifier list.
(char **)
The list of media where the medium to honor
the Mount request is selected.
VSID_MEDIA_ID_LISTis applicable only if
the client is specifying a mount from a media
identifier list.
601355 Rev A
API Functions
2-969
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MOUNT_HANDLE
(VST_MOUNT_HANDLE)
A handle that contains Mount command
parameters. A client can set mount
parameters in a mount handle with the
VS_Mount_SetFieldsfunction. A mount
handle can be passed in a Mount request
instead of specifying the mount parameters on
the Mount request itself.
VSID_MOUNT_OPTION
(VST_MOUNT_OPTION)
A flag that indicates which mount processing
options are in effect for the Mount command.
Valid VSID_MOUNT_OPTIONvalues are listed
in the vs_defs.h file.
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION)
Indicates whether a Mount request should
wait or fail if an inter-archive medium
movement is required to complete the Mount
request and either the source or target archive
is unattended. Valid
VSID_MOVEWAIT_OPTIONvalues are
enumerated in the vs_types.h file.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Mount
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
Mount commands. VSID_RETRY_LIMITis
not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
2-970
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 Mount 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_TARGET_MEDIA_CLASS_NAME)
The name of the MediaClass group where the
mounted medium is reclassified if the
reclassify option is active for the Mount
request.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Mount
commands. USER_FIELDis 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 Mount
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
VSCMD_Mount_SetDefaultsreturns:
• 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.
601355 Rev A
API Functions
2-971
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_mount_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Mount API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_mount_defaults(void)
15 #else
16
VST_BOOLEAN vst_mount_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Modify Pool default
parameters ***\n” );
2-972
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Mount_SetDefaults(
VSID_PRIORITY,
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
The VSID_CRITERIA_GROUP_HANDLEparameter require that
two arguments be passed instead of one.
•
•
The first argument passed is the number of criteria groups
handles to use in selecting the medium to mount.
The second argument is the list of criteria group handles to
use in selecting the medium to mount.
The VSID_DRIVE_EXCL_LISTparameter require that two
arguments be passed instead of one.
•
•
The first argument passed is the number of drives to exclude
from the specified drive pool.
The second argument is the list of the identifier of the drives
to exclude from the specified drive pool.
The VSID_MEDIA_ID_LISTparameter require that two
arguments be passed instead of one.
601355 Rev A
API Functions
2-973
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
The first argument passed is the number of media specified
where the medium to honor the Mount request is selected.
The second argument is the list of media where the medium
to honor the Mount request is selected.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
•
•
•
•
•
•
•
•
vsapi(l),
VS_CriteriaGroup_Create(l),
VS_CriteriaGroup_Destroy(l),
VS_CriteriaGroup_SetFields(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VS_Mount_Create(l),
VS_Mount_Destroy(l),
VS_Mount_SetFields(l),
VSCMD_Mount(l)
2-974
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Movedirects the movement of media from one
VSCMD_Move
archive to another. Inter-archive media movement requires
operator intervention. An operator must eject media from their
home archives and enter them into the specified target archive.
The eject and enter functionalities are available from the
appropriate archive's console display. The eject and enter
functionalities are not available from the API.
Upon receipt of a Move request, VolServ verifies the specified
media exist, the target archive supports the media type name of
the specified media, and there exists an appropriate archive
media class with the target archive. Only one target archive can
be specified on a move request. The current archive of each
specified medium is commanded to eject the medium. An Eject
request, specifying the target archive, is displayed on the
archive console of each source archive. The operator selects and
manually ejects/removes the media on each eject list. After a
medium is ejected from its home archive, the target archive
displays a corresponding Enter request for that medium. The
operator then manually enters the medium on the Enter list into
the target archive.
When the VSID_MOVE_OPTIONparameter is set to
VSE_MOVE_WAIT, VolServ waits until processing of the
Move command completes before returning status to the client.
The client must monitor the media movement in some other
manner (e.g., MediaClass callbacks) to know when the media
are ejected from the home archives and entered into the target
archive.
When the VSID_MOVE_OPTIONparameter is set to
VSE_MOVE_NOWAIT, VolServ returns a status code to the
client after the specified media are placed on the ejection
candidate list of the home archives.
601355 Rev A
API Functions
2-975
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
When media are ejected from the home archive and entered into
the target archive, VolServ generates MediaClass callbacks, if
any of the moved media are associated with MediaClass groups
that are configured to generate callbacks from VolServ.
The Move command can be used to place homeless media into
an archive. A homeless medium is an intransit medium that has
no pending movement activity.
VST_BOOLEAN VSCMD_Move
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Move 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)
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.
2-976
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MEDIA_ID_LIST (int)
The number of media to move to the target
archive.
(char **)
A list of the identifiers of the media to move to
the target archive.
VSID_MOVE_OPTION
(VST_MOVE_OPTION)
Indicates whether VolServ returns final status
to the client as soon as the Move command
begins execution or after the Move command
completes execution. Valid
VSID_MOVE_OPTIONvalues are enumerated
in the vs_types.h file.
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION)
Indicates whether a Move request waits or
fails if either the source archive or target
archive is unattended. The only valid
VSID_MOVEWAIT_OPTIONvalue is
VSE_MOVEWAIT_ATTENDED. The other
VSID_MOVEWAIT_OPTIONvalues
enumerated in the vs_types.h file have no
effect on VSCMD_Move.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-977
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The name of the archive where the specified
media are to be moved. 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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor this
request. USER_FIELDis 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_Movereturns:
VSE_TRUE
•
-
Successful execution if the API is operating in
synchronous mode
2-978
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
601355 Rev A
API Functions
2-979
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_move_execute
4 *
5 * PURPOSE:
6 * This function sends a move command to
the VolServ.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_move_execute( void )
14 #else
15
VST_BOOLEAN vst_move_execute()
16 #endif
17 {
18
19
VST_BOOLEAN
rc = VSE_FALSE;
done =
VST_BOOLEAN
VSE_FALSE;
int
int
int
20
21
22
23
attended;
wait;
count;
*
char
medialist[VST_MAX_ITEMS];
VST_ARCHIVE_NAME archive;
VST_COMMAND_HANDLE cmd;
24
25
26
27
/* get parameters from user */
2-980
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
28
29
30
31
32
printf(“*** Move parameters ***\n” );
printf(“\nEnter Archive: “);
gets( archive);
/* If the next prompt is answered
yes, the move */
33
34
/* will fail unless both archives are
attended. */
printf(“\nMove only with Attended
Archives (0) no, (1) yes: “);
attended = atoi(gets(input));
35
36
37
/* The wait parameter will cause the
move to */
38
39
40
/* not return final status until the
physical */
/* move is complete, or return
immediately. */
printf(“\nWait for status until Move
complete (0) no, (1) yes: “ );
wait = atoi(gets(input));
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
41
42
43
44
45
/* create the command handle */
/* Note that the command handle is
not */
46
47
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received.*/
48
49
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
50
51
{
/* Send the command to the VolServ
software. */
52
53
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
601355 Rev A
API Functions
2-981
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
54
55
56
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout,
*/
/* value retry limit and priority
are set as */
57
58
59
/* default parameters. */
rc = VSCMD_Move(cmd,
VSID_TARGET_ARCHIVE_NAME,
archive,
60
61
VSID_MEDIA_ID_LIST, count,
medialist,
VSID_MOVEWAIT_OPTION,
(attended == 1 ?
VSE_MOVEWAIT_ATTENDED :
VSE_MOVEWAIT_YES ),
VSID_MOVE_OPTION,
62
(wait == 1 ? VSE_MOVE_WAIT :
VSE_MOVE_NOWAIT ),
VSID_ENDFIELD);
63
64
}
65
return ( rc );
66 }
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 Move
request.
VSCMD_Movetriggers MediaClass callbacks from VolServ.
Operator intervention is required for inter-archive media
movement.
A medium that is allocated to a Move request is not available
for another allocation until the Move completes.
VSCMD_Moverequests movement of media between archives,
not within a single archive.
2-982
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
If the VSID_MOVE_OPTIONis specified as
VSE_MOVE_NOWAIT, the status returned to the client indicates
only the initial validity of the Move request. Actual completion
of the move can be traced only via MediaClass callback
processing, media querying, or operator monitoring.
The VSID_MEDIA_ID_LISTparameter requires that two
arguments be passed instead of one.
•
•
The first argument passed is the number of media to move.
The second argument is the list of identifiers of the media to
move.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a Move 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_GetFieldsfunction calls.
601355 Rev A
API Functions
2-983
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
Command-specific parameter defaults for Move commands
are set with VSCMD_Move_SetDefaults. If
command-specific defaults are set for Move 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 Move
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 Move 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,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-984
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VSCMD_Move_SetDefaults(1),
VS_Status_GetFields(l)
601355 Rev A
API Functions
2-985
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Move_SetDefaultssets the command-level
default parameters for Move commands.
VSCMD_Move
_SetDefaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Move commands
are set with VSCMD_Move_SetDefaults. If
command-specific defaults are set for Move 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 Move
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_Move_SetDefaults
( “…”,
Synopsis
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.
2-986
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 Move commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on Move
commands.
VSID_MEDIA_ID_LIST (int)
The number of media to move to the target
archive.
(char **)
A list of the identifiers of the media to move to
the target archive.
VSID_MOVE_OPTION
(VST_MOVE_OPTION)
Indicates whether VolServ returns final status
to the client as soon as the Move command
begins execution or after the Move command
completes execution. Valid
VSID_MOVE_OPTIONvalues are enumerated
in the vs_types.h file.
VSID_MOVEWAIT_OPTION
(VST_MOVEWAIT_OPTION)
Indicates whether a Move request waits or
fails if either the source or target archive is
unattended. The only valid
VSID_MOVEWAIT_OPTIONvalue is
VSE_MOVEWAIT_ATTENDED. The other
VSID_MOVEWAIT_OPTIONvalues
enumerated in the vs_types.h file have no
effect on VSCMD_Move.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Move
commands. 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-987
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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
Move commands. VSID_RETRY_LIMITis 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 Move 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_ARCHIVE_NAME
(VST_ARCHIVE_NAME)
The name of the archive where the specified
media are moved. 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)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Move
commands. USER_FIELDis 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 Move
commands. Neither the API software nor
VolServ uses USER_FIELD.
2-988
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Move_SetDefaultsreturns:
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_move_defaults
4 *
5 * PURPOSE:
6 * This function sets default parameters
for the move
7 * command.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN vst_move_defaults(void)
15 #else
16
VST_BOOLEAN vst_move_defaults()
17 #endif
18 {
19
20
21
VST_PRIORITY
VST_USER_FIELD
VST_TIME_OUT
priority;
user_field;
timeout;
601355 Rev A
API Functions
2-989
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
22
23
24
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
retries;
wait_flag;
25
26
27
28
29
VST_BOOLEAN
rc;
/* get parameters from user */
printf(“*** Move defaults ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
rc = VSCMD_Move_SetDefaults
( VSID_PRIORITY, priority,
VSID_USER_FIELD,
30
31
32
33
34
35
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
36
VSID_ENDFIELD);
37
return(rc);
38 }
Notes
The VSID_MEDIA_ID_LISTparameter requires that two
arguments be passed instead of one.
•
•
The first argument passed is the number of media to move.
The second argument is the list of identifiers of the media to
move.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-990
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Move(l)
601355 Rev A
API Functions
2-991
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MultiMountmounts one or more media with a
single command. Up to eight mount requests can be specified
on a MultiMount command. The media specified on a
MultiMount command are mounted atomically.
VSCMD_Multi
Mount
VST_BOOLEAN VSCMD_MultiMount
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
ARGUMENTS
• handle= The command handle for the MultiMount
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)
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 on this
request.
2-992
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_MOUNT_HANDLE (int)
The index of this mount handle in a mount
handle table. The index of the first mount
handle for a MultiMount request should be 0.
Enter one VSID_MOUNT_HANDLE(int,
VST_MOUNT_HANDLE)parameter pair for
each medium to be mounted with this
MultiMount request. Up to eight
VSID_MOUNT_HANDLEparameter pairs may
be specified on a single MultiMount command.
(VST_MOUNT_HANDLE)
The mount handle for this individual mount
request. Enter one VSID_MOUNT_HANDLE
(int, VST_MOUNT_HANDLE)parameter
pair for each medium to be mounted with this
MultiMount request. Up to eight
VSID_MOUNT_HANDLEparameter pairs may
be specified on a single MultiMount command.
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_LIMITis not
applicable when the API software executes in
asynchronous mode.
601355 Rev A
API Functions
2-993
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor this
request. USER_FIELDis 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_MultiMountreturns:
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.
2-994
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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 Functions
2-995
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_multimount_execute
4 *
5 * PURPOSE:
6 * This function will test the
VSCMD_Multimount call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_multimount_execute(void)
14 #else
15 VST_BOOLEAN vst_multimount_execute()
16 #endif
17 {
18
19
20
21
22
int
int
i;
num;
rc = VSE_FALSE;
VST_BOOLEAN
VST_COMMAND_HANDLE cmdh;
VST_MOUNT_HANDLE
mounth[VSD_MAX_MOUNT_REQS];
23
24
25
/* get parameters from user */
printf(“*** MultiMount Parameters
***\n”);
26
printf(“Enter the number of mount
requests ==> “ );
27
28
num = atoi(gets(input));
2-996
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
/* loop through the number of mount
request */
30
31
32
33
for ( i = 0 ; i < num ; i++ )
{
/* Create a mount handle. */
/* Each mount handle stores a
single mount */
34
35
/* request. The MultiMount command
accepts */
/* multiple mount requests
andexecutes them */
36
37
/* all as one operation. */
mounth[i] =
vst_create_mount_handle();
38
if ( mounth[i] !=
(VST_MOUNT_HANDLE) NULL )
39
40
{
/* add the mount request to the
t */
41
/* multimount via the command
*/
42
43
44
/* default function */
VSCMD_MultiMount_SetDefaults (
VSID_MOUNT_HANDLE,i,
mounth[i],
45
46
47
48
49
50
51
52
53
54
55
56
57
VSID_ENDFIELD );
}
else
{
rc = VSE_FALSE;
break;
}
}
if ( rc )
{
cmdh = VS_Command_Create();
if (cmdh != (VST_COMMAND_HANDLE)
NULL)
58
59
{
/* execute the multimount
command, note */
601355 Rev A
API Functions
2-997
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
60
61
62
63
/* 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 */
64
65
66
/* status has been returned */
rc = VSCMD_MultiMount ( cmdh,
VSID_ENDFIELD );
67
68
69
70
71
72
73
74
}
else
{
rc = VSE_FALSE;
}
}
/* destroy the mount handles that
contain the */
75
/* individual mount requests. */
76
for ( i = 0 ; i < num ; i++ )
77
{
78
VS_Mount_Destroy ( mounth[i] );
79
}
80
return ( rc );
81 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generates intermediate status in response to a
MultiMount request for the following situations.
•
•
•
A drive is reserved for an individual Mount request.
A medium is mounted for an individual Mount request.
An individual Mount request is waiting on a locked drive.
2-998
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
An individual Mount request is waiting on a busy drive.
An individual Mount request is waiting on a busy media.
Thus, for a successful MultiMount command with two Mount
requests, the client can expect at least four intermediate statuses
(two for the reserve of drives and two for the mount
notification).
VSCMD_MultiMounttriggers MediaClass callbacks from
VolServ.
The VSID_MOUNT_HANDLEparameter require that two
Arguments be passed instead of one.
•
•
The first argument passed is the index of the entry in the
Mount handle table.
The second argument is the mount handle to be stored in the
Mount handle table. The Mount handle table is created and
used internally by the API software and is not visible to the
client.
The MultiMount command does not restrict the Mount request
in its use of mount parameters. All mount parameters are valid
for each individual Mount request.
A MultiMount request is an “all-or-nothing” request. If an
entire MultiMount request cannot be satisfied because of
resource conflicts or limitations, the entire command fails.
Partial mounts can be done if one of the last Mount commands
fails and the previous Mount commands have already
completed. MultiMount does not dismount completed mounts if
one mount fails while another succeeds.
A MultiMount command reserves resources to ensure deadlock
avoidance. After all individual mounts are issued, the resources
are freed.
601355 Rev A
API Functions
2-999
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
A MultiMount command should not be used to batch multiple
non-related Mount requests into a single command. The
overhead of checking for resource contention, the presence of
deadlock, and reserving drives is significant. It is recommended
that individual Mount requests be issued for unrelated Mount
requests.
Only one MultiMount request is processed at a time. If a
MultiMount request is received by VolServ and there is already
an active MultiMount request, the new request is queued until
the active command completes reserving resources.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a MultiMount 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_GetFieldsfunction calls.
•
Command-specific parameter defaults for MultiMount
commands are set with
VSCMD_MultiMount_SetDefaults. If
2-1000
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
command-specific defaults are set for MultiMount
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 MultiMount
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 MultiMount request:
• VSID_DRIVE_ID,
• VSID_DRIVE_ID_ENTRY,
• VSID_DRIVE_ID_TABLE,
• VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
• VSID_FIELD,
• VSID_MEDIA_ID,
• VSID_SEQUENCE_NUM,
• VSID_SEQUENCE_TABLE,
• VSID_STATUS_CODE,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD,
• VSID_WAIT_REASON.
601355 Rev A
API Functions
2-1001
Download from Www.Somanuals.com. All Manuals Search And Download.
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),
VSID_Mount_Create(l),
VS_Mount_SetFields(l),
VS_Status_GetFields(l),
VSCMD_MultiMount_SetDefaults(l)
2-1002
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_MultiMount_SetDefaultssets the
command-level default parameters for MultiMount commands.
VSCMD_
MultiMount_
SetDefaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for MultiMount
commands are set with
VSCMD_MultiMount_SetDefaults. If
command-specific defaults are set for MultiMount
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 MultiMount
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_MultiMount_SetDefaults
( “…”,
Synopsis
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.
601355 Rev A
API Functions
2-1003
Download from Www.Somanuals.com. All Manuals Search And Download.
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 MultiMount commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
MultiMount commands.
VSID_MOUNT_HANDLE (int)
The index of this mount handle in a mount
handle table. The index of the first mount
handle for a MultiMount request should be 0.
Enter one VSID_MOUNT_HANDLE (int,
VST_MOUNT_HANDLE)parameter pair for
each medium to be mounted with a
MultiMount request. Up to eight
VSID_MOUNT_HANDLEparameter pairs may
be specified on a single MultiMount command.
(VST_MOUNT_HANDLE)
The mount handle for this individual Mount
request. Enter one VSID_MOUNT_HANDLE
(int, VST_MOUNT_HANDLE) parameter
pair for each medium to be mounted with a
MultiMount request. Up to eight
VSID_MOUNT_HANDLEparameter pairs may
be specified on a single MultiMount command.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for
MultiMount commands. Assignable priority
values are restricted to the range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
2-1004
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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
MultiMount 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 MultiMount 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor
MultiMount commands. USER_FIELDis 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 MultiMount commands.
Neither the API software nor VolServ uses
USER_FIELD.
601355 Rev A
API Functions
2-1005
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_MultiMount_SetDefaultsreturns:
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_multimount_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Multimount API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_multimount_defaults(void)
15 #else
16
VST_BOOLEAN
vst_multimount_defaults()
17 #endif
18 {
2-1006
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Multimount default
parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_MultiMount_SetDefaults(
30
31
32
33
VSID_PRIORITY,
priority,
VSID_USER_FIELD,
user_field,
34
35
36
VSID_TIMEOUT_VALUE,
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
timeout,
retries,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
40
return ( rc );
41 }
Notes
The VSID_MOUNT_HANDLEparameter requires that two
arguments be passed instead of one.
•
The first argument passed is the index of the entry in the
mount handle table.
601355 Rev A
API Functions
2-1007
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
The second argument is the mount handle to be stored in the
mount handle table. The mount handle table is created and
used internally by the API software and is not visible to the
client.
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_MultiMount(l)
2-1008
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Pingchecks the availability of VolServ. If VolServ
responds to a VSCMD_Pingrequest, it can be assumed by the
client that the VolServ is available and functioning.
VSCMD_Ping
The client is not required to issue a VSCMD_Pingrequest
before sending other requests to the VolServ system.
Upon receiving a VSCMD_Ping request, VolServ
immediately returns a VolServ process identifier number. No
other processing is executed for a VSCMD_Pingcommand.
VST_BOOLEAN VSCMD_Ping
(VST_COMMAND_HANDLE handle)
Synopsis
Arguments
• handle= The command handle for this Ping request.
VSCMD_Pingreturns:
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.
601355 Rev A
API Functions
2-1009
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_NOTINITIALIZED- The VolServ API is not
initialized.
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_ping
4 *
5 * PURPOSE:
6 * This function tests the VSCMD_Ping API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
2-1010
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_ping( void )
14 #else
15
VST_BOOLEAN vst_ping()
16 #endif
17 {
18
19
20
21
22
23
24
25
VST_BOOLEAN
VST_COMMAND_HANDLE cmd;
rc = VSE_FALSE;
printf(“*** Pinging VolServ ***\n” );
/* create the command handle */
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
26
27
{
/* Send the command to the VolServ
software. */
28
29
/* This will try to “ping” the
VolServ */
/* software at the host name and
program */
30
31
32
33
34
35
/* number set in VS_Initialize */
rc = VSCMD_Ping(cmd);
vst_print_command(cmd);
if (rc)
{
printf(“The VolServ software
is active.\n”);
36
37
38
39
}
else
{
printf(“The VolServ software
is down.\n”);
40
}
41
}
42
43
vst_print_error(VSG_Error);
return ( rc );
44 }
601355 Rev A
API Functions
2-1011
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ generates no intermediate or final status in response to
a Ping request.
VSCMD_Pingtriggers no 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_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
The following fields can be retrieved from the status handle
after a successful Ping request:
• VSID_PID,
• VSID_SEQUENCE_NUM,
• VSID_SEQUENCE_TABLE,
• VSID_STATUS_CODE,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD.
See Also
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l)
2-1012
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_QueryMount determines which drives can be used
in a subsequent Mount command for the specified medium. A
Query Mount request returns the drives in the order of
preference, based upon availability, proximity to the medium,
usage time, and usage count.
VSCMD_
QueryMount
Upon receipt of a Query Mount request, VolServ determines
which archive contains the specified medium.
If the specified medium is not in an archive, a null list of drives
is returned to the client.
If the medium is in an archive, VolServ determines which
drives in that archive are suitable for mounting the specified
medium. The list of suitable drives is returned to the client in
the Query Mount status.
VST_BOOLEAN VSCMD_QueryMount
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for this Query Mount
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-1013
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
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 on this
request.
VSID_MEDIA_ID (VST_MEDIA_ID)
VSID_PRIORITY (VST_PRIORITY)
The identifier of the medium for which a list of
compatible drives is being requested.
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_LIMITis 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 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_FLAGvalue is
VSE_TRUE.
2-1014
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_FIELDfor this
request. USER_FIELDis 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_QueryMountreturns:
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’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 Functions
2-1015
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_querymount_execute
4 *
5 * PURPOSE:
2-1016
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This executes the VSCMD_QueryMount API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_querymount_execute(void)
14 #else
15 VST_BOOLEAN vst_querymount_execute()
16 #endif
17 {
18
VST_BOOLEAN
rc =
VSE_FALSE;
19
20
21
22
23
VST_MEDIA_ID
VST_COMMAND_HANDLE
mediaid;
cmd;
/* get parameters from user */
printf(“*** QueryMount parameters
***\n” );
24
25
26
27
28
29
printf(“\nEnter media ID: “);
gets( mediaid);
/* create the command handle */
/* Note that the command handle is
not */
30
31
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
32
33
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
34
35
{
/* Send the command to the VolServ
software. */
36
/* Note that status is not
processed here. */
601355 Rev A
API Functions
2-1017
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
37
38
39
40
/* 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 */
41
42
43
/* default parameters. */
rc = VSCMD_QueryMount(cmd,
VSID_MEDIA_ID, mediaid,
VSID_ENDFIELD);
44
45
}
46
return ( rc );
47 }
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 Query
Mount request for the following situations.
VSCMD_QueryMountdoes not trigger any MediaClass
callbacks from VolServ.
The drives identified in the status returned to the client are
known to be suitable for mounting the specified medium.
However, they may not be available for mounting.
Drives that are not in the on-line state are not considered
suitable for mounting and are, therefore, not returned in the
Query Mount status.
If a Query Mount request specifies a medium that is currently
mounted, the Query Mount request fails with the error
VSE_VOLERR_MEDIA_MOUNTED. However, the status still
includes a list of drives suitable for the specified medium.
2-1018
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The ordering of the drives in the list returned to the client is
based on the medium’s current physical location. Drives that
are not mounted are listed before drives that are mounted.
Consequently, for a mounted medium, the drive on which the
medium is currently mounted may not be the first drive in the
returned list.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
If the VSID_ENTERPRISE_IDparameter 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_Selectto receive final status on
a Query Mount 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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Query Mount
commands are set with
VSCMD_QueryMount_SetDefaults. If
601355 Rev A
API Functions
2-1019
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
command-specific defaults are set for Query Mount
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 Query Mount
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 Query Mount request:
• VSID_DRIVE_ID,
• VSID_DRIVE_ID_ENTRY,
• VSID_DRIVE_ID_TABLE,
• VSID_SEQUENCE_NUM,
• VSID_SEQUENCE_TABLE,
• VSID_STATUS_CODE,
• VSID_STATUS_TYPE,
• VSID_USER_FIELD,
• VSID_WAIT_REASON.
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
See Also
•
•
vsapi(l),
VS_Command_Create(l),
2-1020
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
•
•
•
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_QueryMount_SetDefaults(l)
601355 Rev A
API Functions
2-1021
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_QueryMount_SetDefaultssets the
command-level default parameters for Query Mount
commands.
VSCMD_
QueryMount_
SetDefaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Query Mount
commands are set with
VSCMD_QueryMount_SetDefaults. If
command-specific defaults are set for Query Mount
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 Query Mount
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_QueryMount_SetDefaults
( “…”,
Synopsis
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
2-1022
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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 on Query Mount commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on Query
Mount commands.
VSID_MEDIA_ID (VST_MEDIA_ID)
VSID_PRIORITY (VST_PRIORITY)
The identifier of the medium for which a list of
compatible drives is being requested.
The requested execution priority for Query
Mount 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
Query Mount commands.
VSID_RETRY_LIMITis not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
601355 Rev A
API Functions
2-1023
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 Query Mount 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Query
Mount commands. USER_FIELDis 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 Query Mount
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
VSCMD_QueryMount_SetDefaultsreturns:
• 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.
2-1024
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_querymount_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_QueryMount API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_querymount_defaults(void)
15 #else
16
VST_BOOLEAN
vst_querymount_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Query Mount default
parameters ***\n” );
601355 Rev A
API Functions
2-1025
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_QueryMount_SetDefaults(
VSID_PRIORITY,
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
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_QueryMount(l)
2-1026
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Reclassifychanges the MediaClass group with
which the specified media are associated.
VSCMD_
Reclassify
Upon receipt of a VSCMD_Reclassify request, VolServ
verifies that each specified media identifier references a media
of the type supported by the target MediaClass group.
If all specified media are of the appropriate media type,
VolServ verifies that the target MediaClass group is not already
filled to capacity.
If the target MediaClass group is already filled to capacity, a
VSCMD_Reclassifyrequest fails and a failure return code is
returned to the client.
If the target MediaClass group is not already filled to capacity,
only the media it takes to reach the capacity are reclassified.
Any remaining media specified in a VSCMD_Reclassify
request are not reclassified, and a failure indicator is returned to
the client.
VST_BOOLEAN VSCMD_Reclassify
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Reclassify 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.
601355 Rev A
API Functions
2-1027
Download from Www.Somanuals.com. All Manuals Search And Download.
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 for this request.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_MEDIA_CLASS_LIST (int)
The list of MediaClass groups with which the
specified media are currently associated.
Used with the media to be reclassified reside
in different MediaClass groups.
(char **)
A list of the MediaClass groups with which the
specified media are currently associated.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The MediaClass name with which all the
specified media are currently associated if all
of the specified media are associated with the
same MediaClass group.
VSID_MEDIA_ID_LIST (int)
(char **)
The identifier of the number of media to
reclassify.
A list of the identifiers of the media to
reclassify.
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.
2-1028
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_LIMITis 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 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The name of the target MediaClass group with
which the specified media are to be
associated.
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_FIELDfor this
request. USER_FIELDis 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-1029
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Reclassifyreturns:
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
2-1030
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_reclassify_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Reclassify API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_reclassify_execute(void)
14 #else
15 VST_BOOLEAN vst_reclassify_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
rc =
done =
i;
VSE_FALSE;
VST_BOOLEAN
VSE_FALSE;
int
601355 Rev A
API Functions
2-1031
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
int
VST_BOOLEAN
count;
single_class
= VSE_TRUE;
23
24
25
26
VST_MEDIA_CLASS_NAME
old_media_class;
VST_MEDIA_CLASS_NAME
target_media_class;
char
*
medialist[VST_MAX_ITEMS];
char
*
mediaclasslist
[VST_MAX_ITEMS];
27
28
29
30
VST_COMMAND_HANDLE
cmd;
/* get parameters from user */
printf(“*** Reclassify parameters
***\n” );
31
32
count = vst_getmedialist(medialist,
VST_MAX_ITEMS);
printf(“\nEnter Target media class:
“);
33
34
gets( target_media_class);
printf(“\n Are media in same class
(1) yes, (0) no? “);
35
single_class = (VST_BOOLEAN)
atoi(gets(input));
36
37
38
39
40
41
42
43
if (single_class)
{
printf(“\n Enter media class: “);
gets( old_media_class);
}
else
{
count =
vst_getmediaclasslist(mediaclassl
ist, VST_MAX_ITEMS);
}
44
45
46
47
/* create the command handle */
/* Note that the command handle is
not */
2-1032
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
48
49
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
50
51
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
52
53
{
/* Send the command to the VolServ
software. */
54
55
56
57
58
/* 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 */
59
60
61
62
/* default parameters. */
if ( single_class )
{
/* all media are in the same
source class */
63
64
rc = VSCMD_Reclassify(cmd,
VSID_MEDIA_CLASS_NAME,
old_media_class,
65
66
VSID_TARGET_MEDIA_CLASS_NAME,
target_media_class,
VSID_MEDIA_ID_LIST, count,
medialist,
67
68
69
70
71
VSID_ENDFIELD);
}
else
{
/* The media are in different
mediaclass */
72
73
/* groups*/
rc = VSCMD_Reclassify(cmd,
601355 Rev A
API Functions
2-1033
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
74
75
76
VSID_MEDIA_CLASS_LIST,
mediaclasslist,
count,
VSID_TARGET_MEDIA_CLASS_NAME,
target_media_class,
VSID_MEDIA_ID_LIST, count,
medialist,
77
VSID_ENDFIELD);
78
}
79
}
80
return ( rc );
81 }
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
Reclassify request.
There are two ways to specify the MediaClass groups with
which the specified media are currently associated.
•
If all of the specified media are associated with the same
MediaClass group, use the VSID_MEDIA_CLASS_NAME
parameter.
•
If the specified media are associated with more than one
MediaClass group, use the VSID_MEDIA_CLASS_LIST
parameter. The VSID_MEDIA_CLASS_LISTmust
contain an entry for each medium specified in
VSID_MEDIA_ID_LIST(the lists must contain the same
number of entries.) Also, the entries in these lists are
positional. For example, the first specified medium must be
associated with the first specified MediaClass group; the
second specified medium must be associated with the
2-1034
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
th
second specified MediaClass group; and the n specified
th
medium must be associated with the n specified
MediaClass group.
Pending Mount requests are not affected by the reclassification
of media.
If a medium to be reclassified is in an archive, the target
MediaClass group with which the medium is associated must be
associated with that archive.
If the capacity of the target MediaClass group would be
exceeded by the reclassification, only as many media as
necessary to reach capacity are reclassified. The Reclassify
request for any remaining media fails.
The capacity of an archive media class is a soft limit. If the
capacity of an archive media class is exceeded, the entire
Reclassify request is processed unless the capacity of the
associated MediaClass group is also reached. When the
capacity of an archive media class is reached, applicable High
Mark threshold processing is initiated.
If the target MediaClass group is not associated with any
archive, the Reclassify request fails.
An attempt to reclassify a medium into the MediaClass group
with which it is already associated returns an error.
If reclassifying a medium places the medium in a MediaClass
group that does not have the medium’s present location as a
preferred location, the medium is not moved simply to place it
into a preferred location. If the medium is mounted and then
dismounted, or ejected and then entered, an attempt is made to
place the medium in a preferred location as defined by the
target MediaClass group.
A medium that does not reside in an archive can be reclassified.
601355 Rev A
API Functions
2-1035
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VSID_MEDIA_CLASS_LISTparameter require that two
Arguments be passed instead of one.
•
•
The first argument passed is the number of MediaClass
groups contained in the list of MediaClass identifiers.
The second argument is the list of MediaClass groups with
which the specified media are currently associated.
The VSID_MEDIA_ID_LISTparameter require that two
arguments be passed instead of one.
•
The first argument passed is the number of media to
reclassify.
•
The second argument is the list of media to reclassify.
If the VSID_ENTERPRISE_IDparameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Selectto receive final status on
a Reclassify 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_GetFieldsfunction calls.
2-1036
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
Command-specific parameter defaults for Reclassify
commands are set with
VSCMD_Reclassify_SetDefaults. If
command-specific defaults are set for Reclassify
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 Reclassify
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 Reclassify 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,
• VSID_STATUS_TYPE,
601355 Rev A
API Functions
2-1037
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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_Error_GetFields(l),
VS_Initialize(l),
VSCMD_Reclassify_SetDefaults(l)
2-1038
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Reclassify_SetDefaultssets the
command-level default parameters for Reclassify commands.
VSCMD_
Reclassify_
SetDefaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Reclassify
commands are set with
VSCMD_Reclassify_SetDefaults. If
command-specific defaults are set for Reclassify
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 Reclassify
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_Reclassify_SetDefaults
( “…”,
Synopsis
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.
601355 Rev A
API Functions
2-1039
Download from Www.Somanuals.com. All Manuals Search And Download.
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 Reclassify commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
Reclassify commands.
VSID_MEDIA_CLASS_LIST (int)
The number of MediaClass groups with which
the specified media are currently associated.
Used with the media to be reclassified reside
in different archives.
(char **)
A list of the MediaClass groups with which the
specified media are currently associated.
VSID_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The MediaClass group with which all the
specified media are currently associated if all
of the specified media are associated with the
same MediaClass group.
VSID_MEDIA_ID_LIST (int)
(char **)
The number of media to reclassify.
A list of the identifiers of the media to
reclassify.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Reclassify
commands. Assignable priority values are
restricted to the range from 1 (highest) to 32
(lowest) inclusive. The default priority value is
15.
2-1040
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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
Reclassify 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 Reclassify 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_FLAGvalue is
VSE_TRUE.
VSID_TARGET_MEDIA_CLASS_NAME
(VST_MEDIA_CLASS_NAME)
The name of the target MediaClass group with
which the specified media are to be
associated.
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_FIELDfor
Reclassify commands. USER_FIELDis 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 Reclassify commands.
Neither the API software nor VolServ uses
USER_FIELD.
Return Values
VSCMD_Reclassify_SetDefaultsreturns:
601355 Rev A
API Functions
2-1041
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_Reclassify_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Reclassify API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_reclassify_defaults(void)
15 #else
16
VST_BOOLEAN
vst_reclassify_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
VST_PRIORITY
rc =
20
priority;
2-1042
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
21
22
23
24
25
VST_USER_FIELD
VST_TIME_OUT
VST_RETRY_LIMIT
VST_STATUS_WAIT_FLAG
VST_ENTERPRISE_ID
enterprise_id;
user_field;
timeout;
retries;
wait_flag;
26
27
28
/* get parameters from user */
printf(“*** Reclassify default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Reclassify_SetDefaults(
VSID_PRIORITY,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
40
return ( rc );
41 }
Notes
The VSID_MEDIA_CLASS_LISTparameter require that two
arguments be passed instead of one.
•
•
The first argument passed is the number of MediaClass
groups contained in the list of MediaClass identifiers.
The second argument is the list of MediaClass groups with
which the specified media are currently associated.
601355 Rev A
API Functions
2-1043
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The VSID_MEDIA_ID_LISTparameter require that two
arguments be passed instead of one.
•
•
The first argument passed is the number of media to
reclassify.
The second argument is the list of media to reclassify.
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_Reclassify(l)
2-1044
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Reprioritizechanges the execution priority of a
request.
VSCMD_
Reprioritize
The client must supply the request identifier and request type of
the request to be reprioritized when issuing a
VSCMD_Reprioritizerequest.
The request identifier and request type of the request to
reprioritize can be specified on the VSCMD_Reprioritize
request or can be within a command handle that is specified on
the VSCMD_Reprioritizerequest.
Upon receipt of a VSCMD_Reprioritizerequest, VolServ
changes the priority of the specified pending request to the new
priority. VolServ then reorders its command queue to reflect the
request’s new priority.
VST_BOOLEAN VSCMD_Reprioritize
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Reprioritize
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-1045
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameters
Parameter Type
Description
VSID_CLIENT_DISPATCH
(VST_CLIENT_DISPATCH)
The name of the client dispatch routine to
receive status on Reclassify commands.
VSID_COMMAND_HANDLE
(VST_COMMAND_HANDLE)
The command handle of the request to
reprioritize. If VSID_REQUEST_IDand
VSID_REQUEST_TYPEare specified,
VSID_COMMAND_HANDLEis not applicable.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_NEW_PRIORITY (VST_PRIORITY)
The new execution priority to be assigned to
the specified request. Assignable priority
values are restricted to a range from 1
(highest) to 32 (lowest) inclusive.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for this
Reprioritize request. Assignable priority
values are restricted to the range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_REQUEST_ID (VST_REQUEST_ID)
The identifier of the request to reprioritize. If
VSID_COMMAND_HANDLEis specified,
VSID_REQUEST_IDis not applicable.
VSID_REQUEST_TYPE
(VST_REQUEST_ID)
The request type of the request to reprioritize.
Valid values for this field are enumerated in
the vs_types.h file. VSID_COMMAND_HANDLE
is specified, VSID_REQUEST_TYPEis 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
this request. VSID_RETRY_LIMITis not
applicable when the API software executes in
asynchronous mode.
2-1046
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor this
request. USER_FIELDis 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-1047
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Reprioritizereturns:
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’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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto identify the
specific error.
• VSE_ERR_BADFIELD- An invalid parameter was
specified.
2-1048
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_reprioritize_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_Reprioritize
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_reprioritize_execute(void)
14 #else
15
VST_BOOLEAN
vst_reprioritize_execute()
16 #endif
17 {
18
VST_BOOLEAN
VST_REQUEST_ID
VST_REQUEST_TYPE
VST_PRIORITY
rc = VSE_FALSE;
req;
c;
19
20
21
p;
601355 Rev A
API Functions
2-1049
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
22
23
24
25
VST_COMMAND_HANDLE cmd;
/* get parameters from user */
printf(“*** Reprioritize parameters
***\n” );
26
27
printf(“Enter Request ID ==> “ );
req = (VST_REQUEST_ID)
atol(gets(input));
28
29
printf(“Enter Command Request Type
==> “ );
c = (VST_REQUEST_TYPE)
atol(gets(input));
30
31
printf(“Enter New Priority ==> “ );
p = (VST_PRIORITY)
atoi(gets(input));
32
33
/* create the command handle */
/* Note that the command handle is
not */
34
35
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
36
37
38
39
cmd = VS_Command_Create();
if (cmd != (VST_COMMAND_HANDLE )NULL)
{
/* Send the command to the VolServ
software. */
40
41
42
43
44
/* 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 */
45
46
47
/* default parameters. */
rc = VSCMD_Reprioritize(cmd,
VSID_REQUEST_ID, req,
2-1050
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
48
49
50
VSID_REQUEST_TYPE, c,
VSID_NEW_PRIORITY, p,
VSID_ENDFIELD);
51
}
52
return ( rc );
53 }
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
Reprioritize request for the following situations.
VSCMD_Reprioritizedoes not trigger any MediaClass
callbacks from VolServ.
To ensure timely processing, a VSCMD_Reprioritize
request is assigned execution priority 0 (zero) by VolServ.
A VSCMD_Reprioritizerequest cannot be cancelled.
The new priority specified in a VSCMD_Reprioritize
request may be higher or lower than the current priority of the
specified request.
If the request specified in a VSCMD_Reprioritizerequest
is already processing when the VSCMD_Reprioritize
request is received, VolServ still processes the
VSCMD_Reprioritizerequest. If all work on the specified
request has completed, the VSCMD_Reprioritizerequest
functions as a noop. However, if there is additional processing
to perform to complete the specified request, VolServ
reprioritizes the remaining processing.
601355 Rev A
API Functions
2-1051
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Any client can reprioritize any command as long as the request
identifier and request type are known.
If the VSID_ENTERPRISE_IDparameter is set to any value
other than zero, the intermediate and final status for this request
is returned to the enterprise registered with VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Selectto receive final status on
a Reprioritize 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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Reprioritize
commands are set with
VSCMD_Reprioritize_SetDefaults. If
command-specific defaults are set for Reprioritize
commands, they override the global defaults for all
commands.
2-1052
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Tip
To override a default (global or command-specific)
parameter value for a specific instance of a Reprioritize
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 Reprioritize 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.
See Also
•
•
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_Reprioritize_SetDefaults(l)
601355 Rev A
API Functions
2-1053
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Reprioritize_SetDefaultssets the
command-level default parameters for Reprioritize commands.
VSCMD_
Reprioritize_
SetDefaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Reprioritize
commands are set with
VSCMD_Reprioritize_SetDefaults. If
command-specific defaults are set for Reprioritize
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 Reprioritize
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_Reprioritize_SetDefaults
( “…”,
Synopsis
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.
2-1054
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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 Reprioritize commands.
VSID_COMMAND_HANDLE
(VST_COMMAND_HANDLE)
The command handle of the request to
reprioritize. If VSID_REQUEST_IDand
VSID_REQUEST_TYPEare specified,
VSID_COMMAND_HANDLEis not applicable.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
Reprioritize commands.
VSID_NEW_PRIORITY (VST_PRIORITY)
The new execution priority to be assigned to
the specified request. Assignable priority
values are restricted to a range from 1
(highest) to 32 (lowest) inclusive.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for
Reprioritize commands. Assignable priority
values are restricted to the range from 1
(highest) to 32 (lowest) inclusive. The default
priority value is 15.
VSID_REQUEST_ID (VST_REQUEST_ID)
The identifier of the request to reprioritize. If
VSID_COMMAND_HANDLEis specified,
VSID_REQUEST_IDis not applicable.
VSID_REQUEST_TYPE
(VST_REQUEST_ID)
The request type of the request to reprioritize.
Valid values for this field are enumerated in
the vs_types.h file. VSID_COMMAND_HANDLE
is specified, VSID_REQUEST_TYPEis not
applicable.
601355 Rev A
API Functions
2-1055
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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
Reprioritize 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 Reprioritize 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor
Reprioritize commands. USER_FIELDis 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 Reprioritize commands.
Neither the API software nor VolServ uses
USER_FIELD.
2-1056
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Return Values
VSCMD_Reprioritize_SetDefaultsreturns:
• 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
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_reprioritize_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Reprioritize API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_reprioritize_defaults(void)
15 #else
16
VST_BOOLEAN
vst_reprioritize_defaults()
17 #endif
18 {
601355 Rev A
API Functions
2-1057
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Reprioritize default
parameters ***\n” );
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
/* set the default parameters */
rc = VSCMD_Reprioritize_SetDefaults(
VSID_PRIORITY,
29
30
31
32
priority,
33
34
35
36
37
VSID_USER_FIELD,
user_field,
VSID_TIMEOUT_VALUE,
timeout,
VSID_RETRY_LIMIT,
retries,
VSID_STATUS_WAIT_FLAG,
wait_flag,
VSID_ENTERPRISE_ID,
enterprise_id,
38
VSID_ENDFIELD);
39
return ( rc );
40 }
Notes
Note
If the argument list does not end with VSID_ENDFIELD,
unpredictable results occur.
2-1058
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
See Also
•
•
•
•
vsapi(l),
VS_Error_GetFields(l),
VS_Global_SetFields(l),
VSCMD_Reprioritize(l)
601355 Rev A
API Functions
2-1059
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_RequestQueryrequests information about an
outstanding VolServ request. To execute a valid Request Query
command, the client must provide the VolServ-assigned request
identifier of the request for which information is needed.
VSCMD_
Request-
Query
VST_BOOLEAN VSCMD_RequestQuery
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Request 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)
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 on this
request.
2-1060
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
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_REQUEST_ID (VST_REQUEST_ID)
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The VolServ-assigned identifier of the request
to be queried. A valid request identifier must
be specified in the YYYY:DD:MM format
where YYYY represents the year, DD
represents the day, and MM is the month.
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_LIMITis 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 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_FLAGvalue 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.
601355 Rev A
API Functions
2-1061
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_USER_FIELD (VST_USER_FIELD)
The value to put in USER_FIELDfor this
request. USER_FIELDis 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_RequestQueryreturns:
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’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-1062
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
-
-
If the object code’s value is VSE_VOLSERV, the error
occurred in VolServ and the client uses
VST_ERROR_NUMCODEto identify the specific error.
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_requestquery_execute
4 *
5 * PURPOSE:
6 * This executes the VSCMD_RequestQuery
API call.
7 *
8 * PARAMETERS:
9 * none
10 *
601355 Rev A
API Functions
2-1063
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN
vst_requestquery_execute(void)
14 #else
15
VST_BOOLEAN
vst_requestquery_execute()
16 #endif
17 {
18
VST_BOOLEAN
VST_REQUEST_ID
VST_COMMAND_HANDLE cmd;
rc = VSE_FALSE;
requestid;
19
20
21
22
23
/* get parameters from user */
printf(“*** Request Query parameters
***\n” );
24
25
printf(“Request ID to query: “);
requestid = (VST_REQUEST_ID)
atoi(gets(input));
26
27
28
/* create the command handle */
/* Note that the command handle is
not */
29
30
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
31
32
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
33
34
{
/* Send the command to the VolServ
software. */
35
36
37
38
/* Note that status is not
processed here. */
/* Instead, it is processed in the
*/
/* vst_dispatch routine. Also,
note that */
/* default values such as timeout
*/
2-1064
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
39
/* value retry limit and priority
are set as */
40
41
42
/* default parameters. */
rc = VSCMD_RequestQuery(cmd,
VSID_REQUEST_ID, requestid,
VSID_ENDFIELD);
43
44
}
45
return ( rc );
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
Request Query request.
VSCMD_RequestQuerydoes not trigger any MediaClass
callbacks from VolServ.
The request identifier as shown in syslogs and vsadm is not in
the correct format for a VSCMD_RequestQueryrequest. The
request identifier obtained from these sources has the format:
93:123:45678. A request identifier in this format must be
converted to the ydddnnnnn format before being used as a
parameter on a VSCMD_RequestQueryrequest. The request
identifier 93:123:45678, converted to the appropriate format, is
312345678.
The client must specify the identifier of the request to query.
After a request completes processing, there is a relatively short
period of time that the request shows a state of complete.
Afterwards, all knowledge of the request is removed from the
VolServ system and a subsequent VSCMD_RequestQuery
request for that request fails.
601355 Rev A
API Functions
2-1065
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Only one request can be queried per VSCMD_RequestQuery
request.
If the VSID_ENTERPRISE_IDparameter is set to any value
other than zero, the final status for this request is returned to the
enterprise registered with VolServ.
The total length of time the API software waits for a command
status in synchronous mode from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Selectto receive final status on
a Request 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.
•
Global defaults for all commands are initialized at startup
and can be set or retrieved using VS_Global_SetFields
and VS_Global_GetFieldsfunction calls.
•
Command-specific parameter defaults for Request Query
commands are set with
VSCMD_RequestQuery_SetDefaults. If
command-specific defaults are set for Request 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 Request Query
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
2-1066
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
The following fields can be retrieved from the status handle
after a successful Request Query request:
• VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
• VSID_REQUEST_HANDLE,
• 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_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_RequestQuery_SetDefaults(l)
601355 Rev A
API Functions
2-1067
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_RequestQuery_SetDefaultssets the
command-level default parameters for Request Query
commands.
VSCMD_
Request
Query_Set
Defaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Request Query
commands are set with
VSCMD_RequestQuery_SetDefaults. If
command-specific defaults are set for Request 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 Request Query
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_RequestQuery_SetDefaults
( “…”,
Synopsis
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
2-1068
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
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 on Request Query commands.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
Request Query commands.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Request
Query commands. Assignable priority values
are restricted to the range from 1 (highest) to
32 (lowest) inclusive. The default priority value
is 15.
VSID_REQUEST_ID (VST_REQUEST_ID)
VSID_RETRY_LIMIT (VST_RETRY_LIMIT)
The VolServ-assigned identifier of the request
to be queried. A valid request identifier must
be specified in theYYYY:DD:MM format where
YYYY represents the year, DD represents the
day, and MM is the month.
The number of times the API software retries
for command status from VolServ before
returning a time-out to the client software for
Request Query commands.
VSID_RETRY_LIMITis not applicable when
the API software executes in asynchronous
mode. The default retry limit is 3.
601355 Rev A
API Functions
2-1069
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 Request 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Request
Query commands. USER_FIELDis 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 Request Query
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
VSCMD_RequestQuery_SetDefaultsreturns:
• 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.
2-1070
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_requestquery_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_RequestQuery API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_requestquery_defaults(void)
15 #else
16
VST_BOOLEAN
vst_requestquery_defaults()
17 #endif
18 {
19
VST_BOOLEAN
VSE_FALSE;
rc =
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Modify Pool default
parameters ***\n” );
601355 Rev A
API Functions
2-1071
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
30
31
32
33
/* set the default parameters */
rc = VSCMD_RequestQuery_SetDefaults(
VSID_PRIORITY,
VSID_USER_FIELD,
user_field,
priority,
34
35
36
VSID_TIMEOUT_VALUE,
VSID_RETRY_LIMIT,
VSID_STATUS_WAIT_FLAG,
wait_flag,
timeout,
retries,
37
VSID_ENTERPRISE_ID,
enterprise_id,
38
39
VSID_ENDFIELD);
return ( rc );
40 }
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_RequestQuery(l)
2-1072
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Unlockreleases exclusive use of a drive or a set of
drives. The drive to be unlocked and the assigned lock identifier
for the drive must be specified.
VSCMD_
Unlock
A set of drives locked with a single VSCMD_Lockrequest can
be unlocked with multiple VSCMD_Unlockcommands.
A VSCMD_Unlockrequest can specify a subset of the drives
locked for the issuing client. VolServ unlocks only those drives
specified in the VSCMD_Unlockrequest.
VST_BOOLEAN VSCMD_Unlock
(VST_COMMAND_HANDLE handle,
“…”,
Synopsis
VSID_ENDFIELD)
Arguments
• handle= The command handle for the Unlock 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)
The name of the client dispatch routine to
receive status for this request.
601355 Rev A
API Functions
2-1073
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
VSID_DRIVE_ID (int)
(VST_DRIVE_ID *)
The number of drives to unlock.
A pointer to the list of identifiers of the drives
to unlock.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on this
request.
VSID_LOCK_ID (VST_LOCK_ID)
The lock identifier assigned to the drives to
unlock. A lock identifier is assigned to a drive
when the drive is locked with the
VSCMD_Lockcommand.
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_LIMITis 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 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_FLAGvalue is
VSE_TRUE.
2-1074
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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_FIELDfor this
request. USER_FIELDis 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_Unlockreturns:
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’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 Functions
2-1075
Download from Www.Somanuals.com. All Manuals Search And Download.
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_NUMCODEto identify the specific error.
-
If the object code’s value is not VSE_VOLSERVand is
not VSE_NONE, the error occurred in the API and the
client uses VST_ERROR_CODEto 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.
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_unlock_execute
4 *
5 * PURPOSE:
2-1076
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
6 * This executes the VSCMD_Unlock API
call.
7 *
8 * PARAMETERS:
9 * none
10 *
11 ****************************************
*********/
12 #ifdef ANSI_C
13
VST_BOOLEAN vst_unlock_execute(void)
14 #else
15
VST_BOOLEAN vst_unlock_execute()
16 #endif
17 {
18
19
20
VST_BOOLEAN
int
VST_DRIVE_ID
rc = VSE_FALSE;
count;
drivelist[VST_MAX_ITEMS];
21
22
23
24
25
VST_LOCK_ID
VST_COMMAND_HANDLE cmd;
lockid;
/* get parameters from user */
printf(“*** Unlock Parameters ***\n”
);
26
count = vst_getdrivelist(drivelist,
VST_MAX_ITEMS);
27
28
printf(“\nEnter Lock ID ==>”);
lockid = (VST_LOCK_ID)
atoi(gets(input));
29
30
31
/* create the command handle */
/* Note that the command handle is
not */
32
33
/* destoyed in this routine, but in
*/
/* vst_dispatch when final status is
received. */
34
35
cmd = VS_Command_Create();
if ( cmd != (VST_COMMAND_HANDLE)
NULL)
{
36
601355 Rev A
API Functions
2-1077
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
37
38
39
40
41
42
/* 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 */
43
44
45
/* default parameters. */
rc = VSCMD_Unlock(cmd,
VSID_DRIVE_ID_LIST,
count,drivelist,
46
VSID_LOCK_ID,
lockid,
47
VSID_ENDFIELD);
48
}
49
return ( rc );
50 }
Notes
The API must be initialized with a call to VS_Initialize
before this function can be executed.
VolServ can generate intermediate status in response ton
Unlock request.
VSCMD_Unlockdoes not trigger MediaClass callbacks from
VolServ.
Drives specified on a VSCMD_Unlockrequest that are either
not locked or that have a lock identifier different from the one
specified on the VSCMD_Unlockrequest return a failure
status.
The VSID_DRIVE_IDparameter requires that two arguments
be passed instead of one.
2-1078
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
•
•
The first argument passed is the number of drives to unlock.
The second argument is the list of identifiers of the drives to
unlock.
The total length of time the API software waits for a command
status, in synchronous mode, from VolServ is
(VSID_RETRY_LIMITplus 1) multiplied by
VSID_TIMEOUT_VALUE.
When the API software is operating in asynchronous mode,
client software must call VS_Selectto receive intermediate
and final status on an Unlock 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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Unlock
commands are set with VSCMD_Unlock_SetDefaults. If
command-specific defaults are set for Unlock 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 Unlock
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 Unlock request:
• VSID_DRIVE_ID,
601355 Rev A
API Functions
2-1079
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSID_DRIVE_ID_ENTRY,
• VSID_DRIVE_ID_TABLE,
• VSID_ERROR_CODE,
• VSID_ERROR_CODE_ENTRY,
• VSID_ERROR_CODE_TABLE,
• VSID_LOCK_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
•
•
•
•
•
•
•
•
vsapi(l),
VS_Command_Create(l),
VS_Command_Destroy(l),
VS_Error_GetFields(l),
VS_Initialize(l),
VS_Status_GetFields(l),
VSCMD_Lock(l),
VSCMD_Unlock_SetDefaults(l)
2-1080
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
VSCMD_Unlock_SetDefaultssets the command-level
default parameters for Unlock commands.
VSCMD_
Unlock_Set
Defaults
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_GetFieldsfunction calls.
•
Command-specific parameter defaults for Unlock
commands are set with VSCMD_Unlock_SetDefaults. If
command-specific defaults are set for Unlock 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 Unlock
command, the parameter identifier and the value to be
used for the parameter can be submitted on the specific
request itself.
VST_BOOLEAN VSCMD_Unlock_SetDefaults
( “…”,
Synopsis
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.
601355 Rev A
API Functions
2-1081
Download from Www.Somanuals.com. All Manuals Search And Download.
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 Unlock commands.
VSID_DRIVE_ID (int)
(VST_DRIVE_ID *)
The number of drives to unlock.
A pointer to the list of identifiers of the drives
to unlock.
VSID_ENTERPRISE_ID
(VST_ENTERPRISE_ID)
The identifier of the enterprise, if any, to
receive intermediate and final status on
Unlock commands.
VSID_LOCK_ID (VST_LOCK_ID)
The lock identifier assigned to the drives to
unlock. A lock identifier is assigned to a drive
when the drive is locked with the
VSCMD_Lockcommand.
VSID_PRIORITY (VST_PRIORITY)
The requested execution priority for Unlock
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
Unlock commands. VSID_RETRY_LIMITis
not applicable when the API software
executes in asynchronous mode. The default
retry limit is 3.
2-1082
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Parameter Type
Description
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 Unlock 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_FLAGvalue is
VSE_TRUE.
VSID_TIMEOUT_VALUE (VST_TIME_OUT)
VSID_USER_FIELD (VST_USER_FIELD)
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.
The value to put in USER_FIELDfor Unlock
commands. USER_FIELDis 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 Unlock
commands. Neither the API software nor
VolServ uses USER_FIELD.
Return Values
VSCMD_Unlock_SetDefaultsreturns:
• 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 Functions
2-1083
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
• VSE_ERR_NULLSTRING- A null value was passed to a
string argument
Example
1 /****************************************
*********
2 *
3 * FUNCTION: vst_unlock_defaults
4 *
5 * PURPOSE:
6 * This function sets the default
parameters for the
7 * VSCMD_Unlock API call.
8 *
9 * PARAMETERS:
10 * none
11 *
12 ****************************************
*********/
13 #ifdef ANSI_C
14
VST_BOOLEAN
vst_unlock_defaults(void)
15 #else
16 VST_BOOLEAN vst_unlock_defaults()
17 #endif
18 {
19
VST_BOOLEAN
rc =
VSE_FALSE;
20
21
22
23
24
25
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;
26
27
28
/* get parameters from user */
printf(“*** Unlock default
parameters ***\n” );
29
vst_promptforglobals(&priority,
user_field, &timeout, &retries,
&wait_flag, &enterprise_id);
2-1084
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
30
31
32
/* set the default parameters */
rc = VSCMD_Unlock_SetDefaults(
VSID_PRIORITY,
priority,
33
34
35
36
37
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 );
38
39
40 }
Notes
The VSID_DRIVE_IDparameter requires that two arguments
be passed instead of one.
•
•
The first argument passed is the number of drives to unlock.
The second argument is the list of identifiers of the drives to
unlock.
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_Unlock(l)
601355 Rev A
API Functions
2-1085
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
2-1086
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
601355 Rev A
API Functions
2-1087
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
2-1088
API Functions
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
A
Valid Status
Fields
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Roadmap
Refer To
Chapter
Topic
Naming conventions.
Global parameters.
Error handling.
1
API functions.
Valid staus fields.
Error codes.
2
A
B
C
Mount example.
A-2
Valid Status Fields
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-1
VSID_ACTION_CODE through VSID_COMPONENT_HANDLE_ENTRY
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
ACTION_
CODE
ACTION_
ACTION_
ARCHIVE_ ARCHIVE_ ARCHIVE_ ARCHIVE_ COMPONENT COMPONENT
CODE_ENTRY CODE_TABLE HANDLE
HANDLE_
ENTRY
HANDLE_
TABLE
NAME
_HANDLE
_HANDLE_
ENTRY
VSCMD_Archive-
Query
X
X
X
VSCMD_Archive-
Vary
X
VSCMD_Audit
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
VSCMD_Connect-
Query
VSCMD_Create-
Archive MediaClass
X
X
X
X
VSCMD_Create-
MediaClass
VSCMD_CreatePool
VSCMD_Delete-
Archive MediaClass
VSCMD_Delete-
MediaClass
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
VSCMD_DrivePool
Query
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
VSCMD_Import
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
ACTION_
CODE
ACTION_
ACTION_
ARCHIVE_ ARCHIVE_ ARCHIVE_ ARCHIVE_ COMPONENT COMPONENT
CODE_ENTRY CODE_TABLE HANDLE
HANDLE_
ENTRY
HANDLE_
TABLE
NAME
_HANDLE
_HANDLE_
ENTRY
VSCMD_Intransit-
Query
VSCMD_Lock
VSCMD_MediaClass
Query
VSCMD_Media-
Query
VSCMD_MediaType
Query
VSCMD_Modify-
ArchiveMediaClass
X
X
X
VSCMD_Modify-
Media
VSCMD_Modify-
MediaClass
VSCMD_ModifyPool
VSCMD_Mount
VSCMD_Move
VSCMD_MultiMount
VSCMD_Ping
VSCMD_Query-
Mount
VSCMD_Reclassify
VSCMD_Reprioritize
VSCMD_Request-
Query
VSCMD_Unlock
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-2
VSID_COMPONENT_HANDLE_TABLE through VSID_DRIVE_HANDLE
VSID_
COMPONENT COMP_
_HANDLE_
TABLE
VSID_
VSID_COMP VSID_COM VSID_
VSID_
VSID_
VSID_
VSID_DRIVE_
HANDLE
_ID_ENTRY
P_ID_
TABLE
COMP_STATE CONNECT CONNECT_ CONNECT_
ID
_HANDLE
HANDLE_
ENTRY
HANDLE_
TABLE
VSCMD_Archive-
Query
VSCMD_Archive-
Vary
X
VSCMD_Audit
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
VSCMD_Connect-
Query
X
X
X
VSCMD_Create-
Archive MediaClass
X
VSCMD_Create-
MediaClass
VSCMD_CreatePool
VSCMD_Delete-
Archive MediaClass
VSCMD_Delete-
MediaClass
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
VSCMD_DrivePool
Query
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
X
VSCMD_Import
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_
COMPONENT COMP_
_HANDLE_
TABLE
VSID_
VSID_COMP VSID_COM VSID_
VSID_
VSID_
VSID_
VSID_DRIVE_
HANDLE
_ID_ENTRY
P_ID_
TABLE
COMP_STATE CONNECT CONNECT_ CONNECT_
ID
_HANDLE
HANDLE_
ENTRY
HANDLE_
TABLE
VSCMD_Intransit-
Query
VSCMD_Lock
VSCMD_MediaClass
Query
VSCMD_Media-
Query
VSCMD_MediaType
Query
VSCMD_Modify-
Archive MediaClass
X
VSCMD_Modify-
Media
VSCMD_Modify-
MediaClass
VSCMD_ModifyPool
VSCMD_Mount
VSCMD_Move
VSCMD_MultiMount
VSCMD_Ping
VSCMD_Query-
Mount
VSCMD_Reclassify
VSCMD_Reprioritize
VSCMD_Request-
Query
VSCMD_Unlock
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-3
VSID_DRIVE_HANDLE_ENTRY through DSID_DRIVEPOOL_NAME
VSID_DRIVE_ VSID_DRIVE_ VSID_
VSID_
DRIVE_ID_ DRIVE_ID_
ENTRY TABLE
VSID_
VSID_
VSID_
VSID_
VSID_
HANDLE_
ENTRY
HANDLE_
TABLE
DRIVE_
ID
DRIVEPOOL_ DRIVEPOOL DRIVEPOOL_ DRIVE
HANDLE
_HANDLE_
ENTRY
HANDLE_
TABLE
POOL_
NAME
VSCMD_Archive-
Query
VSCMD_Archive-
Vary
VSCMD_Audit
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
VSCMD_Connect-
Query
VSCMD_Create-
Archive MediaClass
VSCMD_Create-
MediaClass
VSCMD_CreatePool
X
X
X
X
X
VSCMD_Delete-
Archive MediaClass
VSCMD_Delete-
MediaClass
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
X
X
X
X
X
X
VSCMD_DrivePool
Query
X
X
X
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
X
X
VSCMD_Import
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_DRIVE_ VSID_DRIVE_ VSID_
VSID_
DRIVE_ID_ DRIVE_ID_
ENTRY TABLE
VSID_
VSID_
VSID_
VSID_
VSID_
HANDLE_
ENTRY
HANDLE_
TABLE
DRIVE_
ID
DRIVEPOOL_ DRIVEPOOL DRIVEPOOL_ DRIVE
HANDLE
_HANDLE_
ENTRY
HANDLE_
TABLE
POOL_
NAME
VSCMD_Intransit-
Query
VSCMD_Lock
X
X
X
VSCMD_MediaClass
Query
VSCMD_Media-
Query
VSCMD_MediaType
Query
VSCMD_Modify-
Archive MediaClass
VSCMD_Modify-
Media
VSCMD_Modify-
MediaClass
VSCMD_ModifyPool
VSCMD_Mount
VSCMD_Move
X
X
X
X
X
X
X
VSCMD_MultiMount
VSCMD_Ping
X
X
X
X
X
X
VSCMD_Query-
Mount
VSCMD_Reclassify
VSCMD_Reprioritize
VSCMD_Request-
Query
VSCMD_Unlock
X
X
X
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-4
VSID_ERROR_CODE through VSID_MEDIA_HANDLE
VSID_
VSID_
VSID_
VSID_FIELD VSID_FIELD_ VSID_FIELD_ VSID_
VSID_MEDIA_ VSID_MEDIA
ERROR_
CODE
ERROR_
CODE_ENTRY CODE_
TABLE
ERROR_
ENTRY
TABLE
LOCK_ID CLASS_NAME _HANDLE
VSCMD_Archive-
Query
VSCMD_Archive-
Vary
VSCMD_Audit
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
X
X
X
X
X
X
X
X
X
VSCMD_Connect-
Query
X
X
X
X
X
X
VSCMD_Create-
Archive MediaClass
X
X
VSCMD_Create-
MediaClass
VSCMD_CreatePool
X
X
X
VSCMD_Delete-
Archive MediaClass
X
X
VSCMD_Delete-
MediaClass
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
X
VSCMD_DrivePool
Query
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_Import
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_
VSID_
VSID_
VSID_FIELD VSID_FIELD_ VSID_FIELD_ VSID_
VSID_MEDIA_ VSID_MEDIA
ERROR_
CODE
ERROR_
CODE_ENTRY CODE_
TABLE
ERROR_
ENTRY
TABLE
LOCK_ID CLASS_NAME _HANDLE
VSCMD_Intransit-
Query
VSCMD_Lock
X
VSCMD_MediaClass
Query
VSCMD_Media-
Query
X
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_MediaType
Query
VSCMD_Modify-
Archive MediaClass
X
X
VSCMD_Modify-
Media
X
X
X
VSCMD_Modify-
MediaClass
VSCMD_ModifyPool
VSCMD_Mount
VSCMD_Move
X
X
X
X
X
X
X
X
X
VSCMD_MultiMount
VSCMD_Ping
VSCMD_Query-
Mount
VSCMD_Reclassify
VSCMD_Reprioritize
X
X
X
VSCMD_Request-
Query
X
X
X
X
X
X
VSCMD_Unlock
X
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-5
VSID_MEDIA_HANDLE through VSID_MEDIATYPE_HANDLE
VSID_MEDIA VSID_MEDIA VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
_HANDLE_
ENTRY
_HANDLE_
TABLE
MEDIA_ID MEDIA_ID MEDIA_ID MEDIACLASS_ MEDIACLASS MEDIACLASS MEDIATYPE_
_ENTRY
_TABLE
HANDLE
_HANDLE_
ENTRY
_HANDLE_
TABLE
HANDLE
VSCMD_Archive-
Query
VSCMD_Archive-
Vary
VSCMD_Audit
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
X
X
X
X
X
X
X
X
X
VSCMD_Clear-
Eject
VSCMD_Connect
VSCMD_Connect
Query
VSCMD_Create-
Archive
MediaClass
VSCMD_Create-
MediaClass
VSCMD_Create-
Pool
VSCMD_Delete-
Archive
MediaClass
VSCMD_Delete-
MediaClass
VSCMD_Delete-
Pool
VSCMD_
Disconnect
VSCMD_Dismount
X
X
X
VSCMD_Drive-
Pool Query
VSCMD_Drive-
Query
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_MEDIA VSID_MEDIA VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
VSID_
_HANDLE_
ENTRY
_HANDLE_
TABLE
MEDIA_ID MEDIA_ID MEDIA_ID MEDIACLASS_ MEDIACLASS MEDIACLASS MEDIATYPE_
_ENTRY
_TABLE
HANDLE
_HANDLE_
ENTRY
_HANDLE_
TABLE
HANDLE
VSCMD_Drive-
Vary
VSCMD_Export
VSCMD_Import
X
X
X
X
X
X
X
X
X
VSCMD_Intransit
Query
VSCMD_Lock
VSCMD_Media-
Class Query
X
X
X
VSCMD_Media-
Query
X
X
VSCMD_Media-
Type Query
X
VSCMD_Modify-
Archive
MediaClass
VSCMD_ModifyM
edia
X
X
X
VSCMD_Modify-
MediaClass
VSCMD_Modify-
Pool
VSCMD_Mount
VSCMD_Move
X
X
X
X
X
X
X
X
X
VSCMD_Multi-
Mount
VSCMD_Ping
VSCMD_Query-
Mount
VSCMD_Reclassi-
fy
X
X
X
VSCMD_Re-
prioritize
VSCMD_Request
Query
VSCMD_Unlock
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-6
VSID_STATUS_CODE through VSID_WAIT_REASON
VSID_STATUS_
CODE
VSID_STATUS_
TYPE
VSID_TARGET_
ENTERPRISE_ID
VSID_USER_
FIELD
VSID_WAIT_
REASON
VSCMD_ArchiveQuery
VSCMD_ArchiveVary
VSCMD_Audit
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
X
VSCMD_ConnectQuery
VSCMD_CreateArchiveMediaClass
VSCMD_CreateMediaClass
VSCMD_CreatePool
VSCMD_DeleteArchiveMediaClass
VSCMD_DeleteMediaClass
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
X
VSCMD_DrivePoolQuery
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
VSCMD_Import
VSCMD_IntransitQuery
VSCMD_Lock
X
VSCMD_MediaClassQuery
VSCMD_MediaQuery
VSCMD_MediaTypeQuery
VSCMD_ModifyArchiveMediaClass
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_STATUS_
CODE
VSID_STATUS_
TYPE
VSID_TARGET_
ENTERPRISE_ID
VSID_USER_
FIELD
VSID_WAIT_
REASON
VSCMD_ModifyMedia
VSCMD_ModifyMediaClass
VSCMD_ModifyPool
VSCMD_Mount
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_Move
VSCMD_MultiMount
VSCMD_Ping
VSCMD_QueryMount
VSCMD_Reclassify
VSCMD_Reprioritize
VSCMD_RequestQuery
VSCMD_Unlock
Download from Www.Somanuals.com. All Manuals Search And Download.
Table A-7
VSID_MEDIATYPE_HANDLE_ENTRY through VSID_SEQUENCE_TABLE
VSID_
VSID_
VSID_
VSID_QUERY_ VSID_
VSID_
VSID_
VSID_
VSID_
MEDIATYPE_ MEDIATYPE_ PID
ENTERPRISE_ QUERY_
REQUEST_ REQUEST_ SEQUENCE SEQUENCE
HANDLE_
ENTRY
HANDLE_
TABLE
ID
OPTION
HANDLE
ID
_NUM
_TABLE
VSCMD_Archive-
Query
X
X
X
X
VSCMD_Archive-
Vary
X
VSCMD_Audit
X
X
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_Cancel
VSCMD_Checkin
VSCMD_Checkout
VSCMD_ClearEject
VSCMD_Connect
X
VSCMD_Connect-
Query
X
VSCMD_Create-
ArchiveMediaClass
X
X
X
X
VSCMD_Create-
MediaClass
VSCMD_CreatePool
X
X
X
X
VSCMD_Delete-
ArchiveMediaClass
VSCMD_Delete-
MediaClass
X
X
VSCMD_DeletePool
VSCMD_Disconnect
VSCMD_Dismount
X
X
X
X
X
X
X
X
VSCMD_DrivePool
Query
X
VSCMD_DriveQuery
VSCMD_DriveVary
VSCMD_Export
X
X
X
X
X
X
X
X
VSCMD_Import
Download from Www.Somanuals.com. All Manuals Search And Download.
VSID_
VSID_
VSID_
VSID_QUERY_ VSID_
VSID_
VSID_
VSID_
VSID_
MEDIATYPE_ MEDIATYPE_ PID
ENTERPRISE_ QUERY_
REQUEST_ REQUEST_ SEQUENCE SEQUENCE
HANDLE_
ENTRY
HANDLE_
TABLE
ID
OPTION
HANDLE
ID
_NUM
_TABLE
X
VSCMD_Intransit-
Query
X
VSCMD_Lock
X
X
X
X
VSCMD_MediaClass
Query
X
VSCMD_Media-
Query
X
X
X
X
X
X
X
X
X
X
VSCMD_MediaType
Query
X
X
VSCMD_Modify-
ArchiveMediaClass
VSCMD_Modify-
Media
VSCMD_Modify-
MediaClass
VSCMD_ModifyPool
VSCMD_Mount
VSCMD_Move
X
X
X
X
X
X
X
X
X
X
X
X
VSCMD_MultiMount
VSCMD_Ping
X
VSCMD_Query-
Mount
VSCMD_Reclassify
VSCMD_Reprioritize
X
X
X
X
X
X
X
VSCMD_Request-
Query
X
VSCMD_Unlock
X
X
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
601355 Rev A
Valid Status Fields
A-17
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
A-18
Valid Status Fields
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
B
Error Codes
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Roadmap
Refer To
Chapter
Topic
Naming conventions.
Global parameters.
Error handling.
1
API functions.
Valid staus fields.
Error codes.
2
A
B
C
Mount example.
Note
Some errors are specific to VSADM functionality, thus they are
not marked as being returned for a Client Command.
B-2
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Error Codes
Code
Definition
Description
0
1
VSE_VOLERR_NONE
VSE_VOLERR_AUTH
No error.
Authorization error.
Client is not authorized to send
commands.
2
VSE_VOLERR_VERS
Version error.
Software versions are incompatible.
3
4
5
VSE_VOLERR_PROC
VSE_VOLERR_DB
Procedure error.
Database error.
VSE_VOLERR_SWCOMM
Software communication error.
VolServ cannot communicate with one
of its tasks or with an archive.
6
VSE_VOLERR_SYSTEM
System error.
Internal system object cannot be found
in memory lists. (VolServ may need to
be cycled.)
7
8
VSE_VOLERR_NOTEMPTY
VSE_VOLERR_NOTFOUND
Item not empty.
Item not found.
Query could not find a match for the
given criteria.
9
VSE_VOLERR_EXIST
Item already exists.
Invalid item.
10
11
12
13
VSE_VOLERR_INVAL
VSE_VOLERR_BUSY
Device is busy.
Overflow.
VSE_VOLERR_OVERFLOW
VSE_VOLERR_INVALID_ARCHIVE
Invalid archive.
Specified archive does not exist or
could not be found.
Medium is found, but it is not in the
correct archive.
601355 Rev A
Error Codes
B-3
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
14
VSE_VOLERR_INVALID_BATCH
Invalid batch.
Specified batch could not be found or
does not exist.
15
16
17
18
VSE_VOLERR_INVALID_CLASS
VSE_VOLERR_INVALID_OPT
VSE_VOLERR_EMPTY_LIST
VSE_VOLERR_BAD_LIST
Invalid class.
Specified MediaClass name could not
be found or does not exist.
Invalid option specified.
An invalid drive pool option (add/delete)
was specified.
No list specified.
No archive/drive/medium list was
specified for command requiring list.
Error retrieving list items.
Query failed to return a valid
archive/drive/medium list.
19
20
21
22
VSE_VOLERR_DRIVE_ASSOCIATED Drive still associated with archive.
VSE_VOLERR_IMPORT
Medium failed import.
Medium failed checkin.
VSE_VOLERR_CHECKIN
VSE_VOLERR_INVALID_COMMAND
Invalid command.
Command to cancel/reprioritize was not
a valid command type.
23
24
VSE_VOLERR_DRIVE_IN_POOL
VSE_VOLERR_LIST
Drive still member of drive pool group.
Error in list - check individual error
codes on item in list.
At least one of the items in the list
returned an error (i.e., reclassify may be
successful for one medium but not
another).
25
26
VSE_VOLERR_EMPTY_POOL
Drive pool empty.
VSE_VOLERR_DRIVE_NOT_ASSOCI Drive not associated with an archive.
ATED
B-4
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
27
VSE_VOLERR_INVAL_STATE
Invalid action or location state for
operation.
The medium is not in the correct state
for the specified operation (a medium
mount may fail because the medium is
marked for export).
The archive is not in the correct state to
be started/stopped.
28
29
VSE_VOLERR_INVALID_DRIVE
Invalid drive specified.
Specified drive could not be found or is
out of valid drive ID range.
No drive in the drive list or drive pool is
suitable to satisfy the request.
VSE_VOLERR_INVALID_MEDIA
VSE_VOLERR_INVALID_POOL
Invalid media specified.
A medium specified for dismount does
not match the medium actually
mounted on the specified drive.
30
31
Invalid pool specified.
Specified drive pool could not be found.
VSE_VOLERR_ARCHIVE_MANAGER Archive manager general error.
Components in the archive are
unavailable, so requests cannot be
processed.
Archive or archive components cannot
be initialized.
Cannot find component to complete
request.
See logs for more information.
32
33
34
VSE_VOLERR_MEM_ALLOC
Memory allocation error.
Out of memory.
VSE_VOLERR_INVALID_
ATTRIBUTES
Invalid parameters specified.
VSE_VOLERR_OPERATOR_FAIL
Operator failed command.
601355 Rev A
Error Codes
B-5
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
35
VSE_VOLERR_MEDIUM_IN_
ARCHIVE
Medium already exists in an archive.
Medium was found in a different
archive, and thus may not be entered
into this archive.
36
37
VSE_VOLERR_UNKNOWN_MEDIUM Unknown medium.
Medium is not known to VolServ
software (i.e., it has not been imported).
VSE_VOLERR_MUST_CHECKIN_
MEDIUM
Medium must be checked in.
38
39
VSE_VOLERR_PORT_IN_USE
Specified port is in use.
VSE_VOLERR_MEDIUM_TO_BE_
CHECKED_OUT
Medium is to be checked out.
40
VSE_VOLERR_MEDIUM_NOT_TO_
BE_ENTERED
Medium not scheduled to be entered.
Some other action is to be taken on the
medium; it may be destined for
checkout.
41
42
VSE_VOLERR_ARCHMEDIA_
NOTFOUND
Medium not found in archive.
Cannot find the medium in the specified
archive.
VSE_VOLERR_MEDIUM_DUPLICATE Duplicate medium.
Two media with the same Media ID
were found in the archive.
43
44
VSE_VOLERR_MEDIUM_MOUNTED
Medium mounted.
VSE_VOLERR_MEDIUM_NOT_
MOUNTED
Medium not mounted.
45
46
VSE_VOLERR_MEDIUM_MARKED_
EJECT
Medium already marked for ejection.
Medium not marked for ejection.
VSE_VOLERR_MEDIUM_NOT_
MARKED_EJECT
B-6
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
47
VSE_VOLERR_MEDIA_NOT_
AVAILABLE
Media not available for use.
The medium is currently in an
unavailable component (i.e., it may be
in a CLM that has been taken off-line).
The robots that can access the medium
are off-line.
48
49
50
51
52
53
54
55
VSE_VOLERR_MEDIUM_NOT_IN_
SPECIFIED_CLASS
Medium not in specified MediaClass
group.
VSE_VOLERR_ARCHIVE_CLASS_
NOT_FOUND
Archive not associated with MediaClass
group.
VSE_VOLERR_ARCHIVE_CLASS_
EXISTS
Archive already associated with
MediaClass group.
VSE_VOLERR_ARCHIVE_CLASS_IS_ MediaClass group is the auto-import
IMPORT_DEFAULT
default for archive.
VSE_VOLERR_ARCHIVE_CLASS_
PLACEMENT_NOT_SUPPORTED
MediaClass group placement not
supported for this archive type.
VSE_VOLERR_INVALID_LOCATION
Invalid archive media class placement
location.
VSE_VOLERR_ARCHIVE_
MEDIATYPE_NOTFOUND
Archive does not support media type.
VSE_VOLERR_ARCHIVE_FULL
Archive has reached capacity for media
type.
There is no more room in the archive for
this media type.
56
57
58
59
VSE_VOLERR_INVALID_LOCKID
VSE_VOLERR_DRIVE_LOCKED
Invalid lock ID.
Drive currently locked.
VSE_VOLERR_DRIVE_NOT_LOCKED Drive not locked.
VSE_VOLERR_DRIVE_NOT_
AVAILABLE
Drive not available for use.
60
VSE_VOLERR_DRIVE_ALREADY_
ASSOCIATED
Drive already associated.
601355 Rev A
Error Codes
B-7
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
61
VSE_VOLERR_DRIVE_ASSOCIATED Drive associated with another archive.
_WITH_ANOTHER_ARCHIVE
62
63
VSE_VOLERR_ARCHIVE_HW
Archive hardware error.
VSE_VOLERR_CMD_NOT_
CANCELLABLE
Command not in state to cancel.
64
65
VSE_VOLERR_CMD_CANCELLED
VSE_VOLERR_CMD_NOTFOUND
Command has been cancelled.
Command not found. Unable to cancel
or reprioritize.
66
67
68
VSE_VOLERR_AUDIT_FAIL
Audit failed.
VSE_VOLERR_NEW_MEDIUM
New medium - imported.
Unreadable medium label.
VSE_VOLERR_UNREADABLE_
LABEL
69
70
VSE_VOLERR_WRONG_BIN
Medium in wrong bin.
VSE_VOLERR_COMP_NOT_
SUPPORTED
Component not supported.
71
72
73
VSE_VOLERR_COMP_INVALID
Invalid component.
VSE_VOLERR_COMPSTATE_INVALID Invalid component state.
VSE_VOLERR_COMP_NOT_
AVAILABLE
Component not available.
74
75
76
VSE_VOLERR_COMP_NOTFOUND
Component not found.
VSE_VOLERR_COMPTYPE_INVALID Invalid component type.
VSE_VOLERR_COMP_DOES_NOT_
SUPPORT_MEDIATYPE
Component does not support media
type.
77
78
79
80
81
VSE_VOLERR_RECLASSIFY
VSE_VOLERR_ROBOT_OFFLINE
VSE_VOLERR_DRIVE_MOUNTED
VSE_VOLERR_PORT_EMPTY
Reclassify error.
Robot off-line.
Drive is mounted.
Port is empty.
Drive is not mounted.
VSE_VOLERR_DRIVE_NOT_
MOUNTED
B-8
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
82
VSE_VOLERR_ARCHIVE_CLASSES_ MediaClass group associated with
STILL_EXIST
archives.
83
84
VSE_VOLERR_MOUNT_
RECLASSIFY_NOT_SUPPORTED
Reclassify only supported for mount by
MediaClass group.
VSE_VOLERR_ARCHIVE_NOT_
ONLINE
Archive not on-line.
85
86
VSE_VOLERR_MEDIA_NOT_IN_LIST Media is not on list.
VSE_VOLERR_MEDIA_ALREADY_IN Media is already on list.
_LIST
87
88
VSE_VOLERR_MEDIA_NOT_
PROCESSED
Media was not processed.
Processing, as specified by the request,
was not completed for this medium.
VSE_VOLERR_MEDIA_ASSIGNED
Media assigned.
The specified medium is assigned to be
mounted (Query Mount).
VolServ tried to assign a medium that
was already assigned. If this is the
case, there is a VolServ software error
(Mount).
89
90
91
VSE_VOLERR_MEDIA_NOT_
ASSIGNED
Media is not assigned.
VSE_VOLERR_INVALID_
MANUFACTURER_NAME
Invalid manufacturer name.
VSE_VOLERR_INVALID_REQUEST_ Invalid request ID.
ID
Specified request ID was not a positive
non-zero number.
92
93
VSE_VOLERR_INVALID_PRIORITY
Invalid priority. The range of valid
priorities is 1 to 32, inclusive.
VSE_VOLERR_INVALID_DRIVE_
TYPE
Invalid drive type.
The specified drive type is invalid
(creation of a drive).
601355 Rev A
Error Codes
B-9
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
Invalid media type.
The specified media type was not a
valid system or user-defined media
type.
94
VSE_VOLERR_INVALID_MEDIA_
TYPE
95
96
VSE_VOLERR_INVALID_DRIVE_
SELECT
Invalid drive select option.
A drive select option other than by drive
ID, drive list, or drive pool was specified.
Note: Selecting by list is not valid for a
mount command.
VSE_VOLERR_INVALID_MEDIA_
SELECT
Invalid media select option.
A media select option other than by
media ID, media list, or MediaClass
group was specified.
97
98
VSE_VOLERR_INVALID_CLASS_
MOUNT_STATE
Invalid class mount state.
The MediaClass group is not defined as
mountable by class.
VSE_VOLERR_INVALID_ARCHIVE_
MODE
Invalid archive mode
The specified archive mode is not in the
range of allowable modes
(attended/unattended).
99
VSE_VOLERR_CLM_ASSOCIATED
Component already associated.
The specified component is already
associated with a drive.
100
VSE_VOLERR_EJECTION_CLEARED Medium ejection cleared.
A medium marked for ejection (on the
Eject list) was unmarked (removed from
the Eject list).
101
102
VSE_VOLERR_MANUAL_EJECT
Medium manually ejected.
The specified medium was manually
ejected while processing this request.
VSE_VOLERR_INVALID_ARCHIVE_
ACTION_OPTION
Invalid archive action.
The specified archive action option is
not within the allowed range (none,
migrate, notify).
B-10
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
103
VSE_VOLERR_INVALID_MIGRATION Invalid migration priority.
_PRIORITY
104
105
106
107
VSE_VOLERR_INVALID_HIGH_MARK Invalid high mark.
VSE_VOLERR_INVALID_LOW_MARK Invalid low mark.
VSE_VOLERR_INVALID_CAPACITY
Invalid capacity.
VSE_VOLERR_INVALID_TARGET_
ARCHIVE
Invalid target archive.
Migration was specified as the archive
action option, but an unknown or invalid
migration archive was specified.
108
VSE_VOLERR_COMP_OVERLAP
Component overlaps with another in the
list.
A component specified for preferred
placement overlaps with another
already in the list (i.e., if row 1,0,0,0 was
specified, as was column 1,2,0,0, then
the column would return this error as it
is redundant).
109
110
VSE_VOLERR_DRIVE_NOT_ONLINE Drive not on-line.
VSE_VOLERR_MOUNT_CROSSES_
ARCHIVES
Mount crosses archives.
The mount requires a medium be
moved between archives, but the
move-wait option specifies no wait.
111
VSE_VOLERR_CLASS_NOT_
MOUNTABLE
Class mount state not set to mount.
The specified MediaClass group is not
defined for mounting by class.
112
113
114
115
VSE_VOLERR_CLASS_CANNOT_
STATISFY_MOUNT
No media in class or no drives to satisfy
mount.
VSE_VOLERR_NO_MEDIA_FOUND_ No media available in class to satisfy
IN_CLASS_FOR_MOUNT mount.
VSE_VOLERR_NO_DRIVES_FOUND No drives available to satisfy Mount.
_FOR_MOUNT
VSE_VOLERR_NO_DRIVES_
AVAILABLE_IN_POOL
No drives available in drive pool to
satisfy Mount.
601355 Rev A
Error Codes
B-11
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
116
VSE_VOLERR_INCONSISTENCY
Software or database inconsistency.
Database inconsistency was
encountered.
117
118
VSE_VOLERR_MEDIA_STILL_IN_
CLASS
Media still in class.
MediaClass group cannot be deleted,
unless there are no media in the class.
VSE_VOLERR_DRIVE_ARCHIVE_
INCOMPATIBLE_MEDIA_TYPES
Drive and archive are of incompatible
media types.
The drive to be associated does not
match any media types that the archive
supports.
119
120
121
VSE_VOLERR_INVALID_MEDIA_
SYNTAX
Invalid media syntax.
VSE_VOLERR_INVALID_DRIVE_
SYNTAX
Invalid drive syntax.
VSE_VOLERR_CLASS_STILL_
TARGET_CLASS_FOR_MIGRATION
Class still specified as target for
migration.
The specified archive MediaClass
group association cannot be deleted
because this archive and MediaClass
group are the migration target for
another archive media class
association.
122
VSE_VOLERR_NOT_ENOUGH_
AVAILABLE_DRIVES_IN_POOL
Not enough available drives in pool.
There are not enough available drives
in the pool to satisfy the request.
123
124
125
126
VSE_VOLERR_INVALID_RPC_
OPTION
Invalid RPC option.
VSE_VOLERR_INVALID_RPC_HOST Invalid RPC hostname.
NAME
VSE_VOLERR_INVALID_RPC_
PROGRAM_NUMBER
Invalid RPC program number.
VSE_VOLERR_INVALID_RPC_
VERSION
Invalid RPC version.
B-12
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
127
VSE_VOLERR_INVALID_RPC_PROC Invalid RPC procedure number.
_NUMBER
128
129
VSE_VOLERR_INVALID_RPC_
PROTOCOL
Invalid RPC protocol.
VSE_VOLERR_LOCK_CROSSES_
ARCHIVES
Lock crosses archives.
Only drives in the same archive can be
locked with a single lock command.
130
131
VSE_VOLERR_SOFTWARE_NOT_
READY
Software not ready.
VolServ is not ready to process
requests. It is still initializing.
VSE_VOLERR_NOT_ACCEPTING_
COMMANDS
VolServ not accepting commands.
VolServ is in single-user mode (i.e., it is
not accepting commands through the
client interface).
132
133
VSE_VOLERR_COMMAND_NOT_
ALLOWED
Command not allowed.
The specified command is not allowed
over this interface. The system
administrator controls which commands
are allowed over each interface.
VSE_VOLERR_INVALID_LOCK_
COUNT
Invalid lock count.
Drive lock count is not a positive
non-zero number.
134
135
VSE_VOLERR_NO_AVAILABLE_BINS No available bins.
VSE_VOLERR_INVALID_MODE
Invalid mode.
The specified mode is out of range.
136
137
VSE_VOLERR_COMMAND_IN_
UNKNOWN_STATE
Command terminated in unknown state.
VSE_VOLERR_MANUFACTURER_
MISSING
Manufacturer not specified.
A batch identifier was specified without
the manufacturer name (none or both
are required).
601355 Rev A
Error Codes
B-13
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
Batch not specified.
138
VSE_VOLERR_BATCH_ MISSING
A manufacturer name was specified
with the batch identifier (none or both
are required).
139
140
VSE_VOLERR_CLASS_DOES_NOT_ Class does not support media type.
SUPPORT_MEDIA_TYPE
VSE_VOLERR_INVALID_MOVEWAIT_ Invalid move-wait option.
OPTION
The move-wait option was not in the
range of accepted values (no, yes,
attended).
141
142
VSE_VOLERR_ARCHIVE_
UNATTENDED
Current archive mode is unattended.
The request cannot be completed
because the source archive was
unattended.
VSE_VOLERR_TARGET_ARCHIVE_
UNATTENDED
Target archive mode is unattended.
The request cannot be completed
because the destination archive was
unattended.
143
144
145
VSE_VOLERR_DELETING_MEDIA_
FROM_CLASS
Error deleting medium from class.
VSE_VOLERR_ADDING_MEDIA_TO_ Error adding medium to class.
CLASS
VSE_VOLERR_MEDIA_ALREADY_IN Medium already in class.
_CLASS
Reclassify failed because medium
already exists in MediaClass group.
146
147
VSE_VOLERR_INVALID_CURRENT_ Invalid current class.
CLASS
Reclassify failed because medium does
not exist in specified current class.
VSE_VOLERR_INVALID_TARGET_
CLASS
Invalid target class.
Reclassify failed because target class is
not a valid class for this medium.
B-14
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
Media still in archive.
148
VSE_VOLERR_MEDIA_STILL_IN_
ARCHIVE
If environment variables are set
appropriately, then archive that still has
media in it cannot be deleted.
149
150
VSE_VOLERR_MIXED_MEDIA_
TYPES_IN_LIST
Media list with mixed media types.
Mount failed because the specified
media contained media of differing
media types.
VSE_VOLERR_FILLLEVEL_
EXCEEDS_NEW_CAPACITY
Current fill level exceeds desired
capacity.
The modify class failed because the
current fill level is above the requested
capacity.
151
152
153
VSE_VOLERR_MAX_MEDIATYPES_
DEFINED
Maximum number of media types
defined.
VSE_VOLERR_ARCHMEDIA_MOVE_ Archive media move failed (not
FAILED
currently returned).
VSE_VOLERR_CLASS_CAPACITY_
INCONSISTENCY
Archive media class inconsistency (not
currently returned).
154
155
VSE_VOLERR_MEDIA_CLASS_FULL MediaClass group is full.
VSE_VOLERR_BIN_EMPTY
Bin empty.
Medium movement failed because the
medium was not in the bin.
156
VSE_VOLERR_BIN_NOT_EMPTY
Bin not empty.
Medium movement failed because a
medium already exists in the
destination bin (several retries with a
new bin will be tried before failing).
157
158
VSE_VOLERR_DRIVE_MEDIA_
ASSIGNED
Drive has media assigned.
Mount failed because the drive already
had a medium assigned to it.
VSE_VOLERR_CLIENT_
CONNECTED
Client connected.
601355 Rev A
Error Codes
B-15
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
159
VSE_VOLERR_UNABLE_TO_
CONNECT_CLIENT
Unable to connect to client.
160
161
VSE_VOLERR_INVALID_
ENTERPRISE_ID
Invalid enterprise ID.
VSE_VOLERR_UNKNOWN_
ENTERPRISE_ID
Unknown enterprise ID.
162
163
VSE_VOLERR_UNKNOWN_CLIENT
Unknown client.
VSE_VOLERR_UNABLE_TO_
DISCONNECT_CLIENT
Unable to disconnect from client.
164
165
166
VSE_VOLERR_ENTER_WRONG_
ARCHIVE
Medium to be entered in another
archive.
VSE_VOLERR_CHECKEDIN_
MEDIUM
Medium checked in.
VSE_VOLERR_MEDIUM_ID_
MISMATCH
Medium ID specified does not match
bar code.
Medium movement failed because the
wrong medium was in the bin.
167
168
VSE_VOLERR_COMP_
INCONSISTENT_MAPPINGS
Inconsistency in column mappings.
During configuration or reconfiguration,
there was an inconsistency in the
column mappings.
VSE_VOLERR_EU_HAS_
ASSOCIATED_MEDIA
CLM or CLU with associated media -
manual eject.
This is the result of a Mount failing
because the CLM could not move the
medium to the recorder, and error
recovery processing could not correct
the problem.
169
VSE_VOLERR_ARCHIVE_MANAGER Archive manager terminating - request
_TERMINATING
cancelled.
The archive is in the process of shutting
down; therefore, the request has been
cancelled.
B-16
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
170
VSE_VOLERR_MEDIA_NOT_
EJECTED_FROM_DRIVE
Medium not ejected from drive.
Dismount failed because the medium
was not ejected from the drive.
171
VSE_VOLERR_MEDIA_ALREADY_IN Medium already exists in target archive.
_TARGET_ARCHIVE
Move failed because medium already
resides in the destination archive.
172
173
174
175
176
177
178
179
VSE_VOLERR_MEDIUM_NOT_
MOUNTED_ON_DRIVE
Medium is not mounted on specified
drive.
VSE_VOLERR_PORT_NO_
AVAILABLE_BINS
No available port bins.
VSE_VOLERR_PORT_COUNT_TOO_ Port count too large.
LARGE
VSE_VOLERR_INVALID_MEDIA_
STAT_VALUE
Invalid media statistic value for
user-defined media statistics.
VSE_VOLERR_INVALID_MOUNT_
CRITERIA
Invalid mount criteria.
VSE_VOLERR_NO_MEDIA_
SELECTED_BY_CRITERIA
No media found that meet user criteria.
Media on console list.
VSE_VOLERR_INCONSISTENT_
MEDIA_ON_LIST
VSE_VOLERR_CANNOT_
REPRIORITIZE_CMD
Command not in state to reprioritize.
180
181
182
VSE_VOLERR_INVALID_DRIVE_LIST Invalid Drive list.
VSE_VOLERR_MEDIUM_IN_PORT
Medium in port.
VSE_VOLERR_PROTOCOL_NOT_
SUPPORTED
Protocol not supported at this time.
183
VSE_VOLERR_MEDIUM_NOT_
REMOVED_FROM_ARCHIVE
Medium not physically removed from
archive.
Manual eject was requested, but
medium was not physically removed
(only the STK ACS product family
archives verify that medium was
physically removed).
601355 Rev A
Error Codes
B-17
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
184
VSE_VOLERR_ARCHIVE_
PHYSICALLY_FULL
Archive is physically full.
185
186
187
188
VSE_VOLERR_INVALID_SOCKET_
INFORMATION
Invalid socket information.
VSE_VOLERR_ROBOT_ACCESSOR_ Accessor contains a medium.
FULL
VSE_VOLERR_AUDIT_IN_
PROGRESS
Shelf cannot be varied during an audit.
VSE_VOLERR_PORT_NOT_
AVAILABLE
Port is not available.
189
190
ERR_HARDWARE_NOT_READY
ERR_MAC_OFFLINE
Hardware not ready.
Manipulator Accessor Component
(MAC) is offline or unavailable.
191
192
193
194
195
196
ERR_MAC_NOTFOUND
ERR_PTBIN_OFFLINE
ERR_PTBIN_NOTFOUND
ERR_ROW_NOTFOUND
ERR_CLU_INVALID
MAC not found.
Pass-through bin offline or unavailable.
Pass-through bin not found.
Row not found.
Port not accessible or offline.
Physical hardware component offline.
ERR_HARDWARE_COMPONENT_
OFFLINE
197
198
199
ERR_MEDIUM_CHECKED_OUT
ERR_MEDIUM_INTRANSIT
Medium checked out.
Medium intransit.
ERR_ARCHIVE_MOVEMENT_
PENDING_FOR_MEDIUM
Archive movement pending for medium.
200
201
202
203
ERR_LICENSE_STRING_MISSING
ERR_LICENSE_LIMIT_REACHED
ERR_INVALID_LICENSE_STRING
ERR_EJECT_IN_PROGRESS
License string missing.
License limit reached.
Invalid license string.
Eject currently in progress for medium.
B-18
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Code
Definition
Description
Timeout waiting on hardware status.
204
ERR_TIMEOUT_WAITING_ON_
HARDWARE_STATUS
205
206
ERR_HARDWARE_COMMUNICATION Hardware communication error.
ERR_ARCHIVE_TYPE_NOT_
SUPPORTED
Archive type is not supported.
207
ERR_DISMOUNT_ALREADY_
QUEUED
Medium dismount is already queued.
601355 Rev A
Error Codes
B-19
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
B-20
Error Codes
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
C
Mount
Example
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Roadmap
Refer To
Chapter
Topic
Naming conventions.
Global parameters.
Error handling.
1
API functions.
Valid staus fields.
Error codes.
2
A
B
C
Mount example.
C-2
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
Mount by MediaClass Group & Drive Pool:
Example
1 #include <stdio.h>
2 #include <vs_client.h>
3
4 /* include the VolServ API header file*/
5
6 /* define the volserv host computer */
7 #define VOLSERV_HOST
8
"vshost"
9 /* forward declare the dispatch routine
*/
10 void dispatch ( VST_COMMAND_HANDLE );
11
12 void print_error ( VST_ERROR_HANDLE );
13
14 main ( int argc, char *argv[] )
15 {
16
17
18
int
exitcode = 0;
/* the name of the MediaClass group
from */
19
/* which to select the medium to
mount */
20
21
22
VST_MEDIA_CLASS_NAME mediaclass;
/* the name of the DrivePool group
from */
23
/*whichtoselectthedrivetomount
*/
24
25
26
VST_DRIVE_POOL_NAME drivepool;
/* the identifier of the medium that
was mounted */
27
28
29
VST_MEDIA_ID
mediaid;
/* the identifier of the drive that
was mounted */
30
31
VST_DRIVE_ID
driveid;
601355 Rev A
Mount Example
C-3
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
32
/* the command handle for the Mount
request */
33
34
35
VST_COMMAND_HANDLE cmdh;
/* the status handle for the Mount
request */
36
37
38
VST_STATUS_HANDLE
stath;
/* the error handle for the Mount
request */
39
40
41
VST_ERROR_HANDLE
errh;
/* the error object code for the
Mount request */
42
43
44
VST_ERROR_OBJCODE errobj;
/* the numeric error code for the
Mount request */
45
46
47
VST_ERROR_NUMCODE errnum;
/* check for the proper number of
arguments */
48
49
50
if ( argc != 3 )
{
printf ("usage: mount
<mediaclass> <drivepool>\n");
51
52
53
54
exit ( 1 );
}
/*copytheMediaClassnameandthe
drivepoolname*/
55
56
57
58
59
strcpy ( mediaclass, argv[1] );
strcpy ( drivepool, argv[2] );
/* initilize the VolServ API */
if ( VS_Initialize ( VOLSERV_HOST, 0,
10 ) )
{
60
61
62
/* create a command handle to hold
the ping */
63
/* and mount request */
C-4
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
64
if ( (cmdh = VS_Command_Create ())
!=
(VST_COMMAND_HANDLE) NULL )
65
66
{
/* check to see if VolServ s/w is
available */
67
68
69
if ( ! VSCMD_Ping ( cmdh ) )
{
printf ( "VolServ system is
not available\n"
);
exit ( 1 );
}
70
71
72
73
/*******************************
********/
74
75
76
77
78
79
80
81
82
83
84
/*SendtheMountrequest.
*/
/* The default API mode is
synchronous.
/* Therefore, wait for status
until the */
/* command is complete or until
*/
it
*/
/*times-outwaitingforstatus.
*/
/* Set the timeout for three
minutes and */
/* the retry to two so that the
total time */
/*towaitisnineminutes.
*/
/* Also,register a dispatch
routine to */
/* catch mount intermediate
status.
*/
/*******************************
********/
85
if ( VSCMD_Mount ( cmdh,
601355 Rev A
Mount Example
C-5
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
86
87
88
89
90
VSID_MEDIA_CLASS_NAME,
mediaclass,
VSID_DRIVEPOOL_NAME,
drivepool,
VSID_TIMEOUT_VALUE,
VSID_RETRY_LIMIT,
VSID_CLIENT_DISPATCH,
VSID_ENDFIELD ) )
180,
2,
dispatch,
{
91
92
93
/*Mountwassuccessful.
/*Getthestatushandle
VS_Command_GetFields (
*/
94
95
96
97
*/
cmdh,
VSID_STATUS_HANDLE,&stath,
VSID_ENDFIELD
);
98
99
/* Get identifiers of medium
and drive */
100
/* that were mounted from
status handle */
101
102
VS_Status_GetFields ( stath,
VSID_MEDIA_ID,mediaid,
VSID_DRIVE_ID,&driveid,
VSID_ENDFIELD );
103
104
105
106
/* Output user message
showing */
107
108
/* identifiers of mounted
medium and */
/* drive. */
C-6
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
109
printf ( "Media [%s] mounted
on drive
[%d]\n",
mediaid, driveid );
110
111
112
113
}
else
{
/*******************************
*****/
114
115
116
117
/*Mountwasnotsuccessful.
*/
/* Get error handle from
command to */
/* determine where error
occurred */
/*******************************
*****/
118
119
120
VS_Command_GetFields (
cmdh,
VSID_ERROR_HANDLE,&errh,
VSID_ENDFIELD );
121
122
/*******************************
*****/
123
124
125
126
127
128
/* Get error object and
numeric code
/* from error handle.
*/
*/
/* The error object code
tells where
/* the error occurred.
*/
*/
/* The error numeric code
tells what
*/
/* error occurred.
*/
601355 Rev A
Mount Example
C-7
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
129
/*******************************
******/
130
131
VS_Error_GetFields ( errh,
VSID_ERROR_NUMBER,
&errnum,
132
VSID_ERROR_OBJECT,
&errobj,
133
134
135
VSID_ENDFIELD );
/*******************************
*****/
136
137
138
139
/* if command's error
number states */
/* no error, error is stored
in the */
/* global error code.
*/
/*******************************
*****/
140
if ( errnum != VSE_ERR_NONE
)
141
142
143
{
/*******************************
**/
144
145
146
147
148
/* check to see if error
was a
*/
/* VolServ error. if yes,
*/
print a
/* message to the user
stating the
*/
/* error condition.
*/
/*******************************
**/
149
if ( errobj ==
VSE_VOLSERV )
C-8
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
150
151
152
153
154
{
switch ( errnum )
{
case
VSE_VOLERR_INVALID_CLASS:
printf (
155
"Invalid media
class[%s]\n",
mediaclass);
break;
156
157
case
VSE_VOLERR_INVALID_POOL:
printf (
158
"Invalid drive
pool[%s]\n"
drivepool );
159
160
break;
case
VSE_VOLERR_NO_DRIVES_AVAILABLE_I
N_POOL:
161
printf ( "No
drives
available in
drive pool
[%s]\n",
drivepool );
break;
162
163
case
VSE_VOLERR_CLASS_NOT_MOUNTABLE:
printf ( "Media
class [%s]
does not allow
mounts\n",
mediaclass );
break;
164
165
166
case
VSE_VOLERR_NO_MEDIA_FOUND_IN_CLA
SS_FOR_MOUNT:
601355 Rev A
Mount Example
C-9
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
167
printf ( "Media
has no media
class [%s]
available for
mounting\n",mediaclass );
break;
168
169
170
default:
printf (
"VolServ error
encountered\n"
break;
);
171
172
173
174
175
}
}
/*******************************
**/
176
177
/* print the error code
for the user */
/*******************************
**/
178
179
180
181
182
print_error ( errh );
}
else
{
/*******************************
**/
183
184
185
/* print the error code
from the
handle
*/
/* VolServ global error
*/
/*******************************
**/
186
print_error ( VSG_Error
);
}
187
188
C-10
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
189
190
191
192
193
194
exitcode = 1;
}
}
else
{
/*******************************
*********/
195
196
197
/* print the error code from
the
*/
*/
/* VolServ global error handle
/*******************************
*********/
198
print_error ( VSG_Error );
199
200
exitcode = 1;
}
201 }
202 else
203 {
204
/*******************************
*********/
205
206
207
/* print the error code from the
*/
/* VolServ global error handle
*/
/*******************************
*********/
208
209
print_error ( VSG_Error );
exitcode = 1;
210 }
211
212 exit ( exitcode );
213}
214
215/*************************************
***********/
216/* The dispatch routine registered with
the mount*/
601355 Rev A
Mount Example
C-11
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
217/* command. This routine is called by
the API
*/
218/* whenever status (final or
intermediate) is
*/
219/* received for the Mount request. For
this
*/
220/* example, we are interested in
intermediate
*/
221/* status. if we receive final status,
we ignore */
222/* it and let the main routine print out
the
*/
223/* media/drive used.
*/
224/*************************************
***********/
225void
226dispatch ( VST_COMMAND_HANDLE cmdh )
227{
228 VST_STATUS_HANDLE stath;
229 VST_STATUS_TYPE stattype;
230 VST_WAIT_REASON wait;
231
232
/*******************************
**************/
233 /* Get status handle from Mount
request
*/
234
/*******************************
**************/
235 VS_Command_GetFields ( cmdh,
236
VSID_STATUS_HANDLE,&stath,
237
238
VSID_ENDFIELD
);
C-12
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
239
/*******************************
**************/
240 /* Get status type (intermediate or
final) */
241 /* and wait reason (if any exists).
*/
242
/*******************************
**************/
243 VS_Status_GetFields ( stath,
244
VSID_STATUS_TYPE,
VSID_WAIT_REASON,
VSID_ENDFIELD );
&stattype,
&wait,
245
246
247
248
/*******************************
**************/
249 /* If intermediate status, print
message to */
250 /*user.Iffinalstatus,ignoreit.
*/
251
/*******************************
**************/
252 if ( stattype ==
VSE_STATUSTYPE_INTERMEDIATE )
253 {
254
/* print message depending upon
wait reason */
255
256
257
258
switch ( wait )
{
case VSE_WAIT_LOCKED_DRIVE:
printf ( "Mount waiting on
locked drive\n" );
break;
case VSE_WAIT_BUSY_DRIVE:
printf ( "Mount waiting on
busy drive\n");
259
260
261
262
break;
601355 Rev A
Mount Example
C-13
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
263
264
case VSE_WAIT_BUSY_MEDIUM:
printf ( "Mount waiting on
busy medium\n" );
break;
265
266
267
default:
printf ( "Unknown wait
reason [%d]
received\n",wait );
break;
268
269
}
270 }
271}
272
273/* print error code from given error
handle */
274void
275print_error ( VST_ERROR_HANDLE errh )
276{
277 VST_ERROR_CODE errcode;
278
279 VS_Error_GetFields ( errh,
280
VSID_ERROR_CODE,
VSID_ENDFIELD );
errcode,
281
282
283 printf ( "Error code [%s] returned
from API\n", errcode );
284}
C-14
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
601355 Rev A
Mount Example
C-15
Download from Www.Somanuals.com. All Manuals Search And Download.
API Guide
NOTES
C-16
Mount Example
601355 Rev A
Download from Www.Somanuals.com. All Manuals Search And Download.
|
