AS/400e IBM

System API Reference

Version 4

SC41-5801-03
AS/400e IBM
System API Reference
Version 4

SC41-5801-03
 Note

Before using this information and the product it supports, be sure to read the information in Appendix D, “Notices” on page D-1.

Fourth Edition (May 1999)

This edition applies to Version 4 Release 4 Modification 0, of IBM Operating System/400 (Program 5769-SS1) and to all subsequent releases
and modifications until otherwise indicated in new editions. This edition applies only to reduced instruction set computer (RISC) systems.

This edition replaces SC41-5801-02.

 Copyright International Business Machines Corporation 1998, 1999. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 Contents
About System API Reference (SC41-5801) . . . . xxvii Installing Operations Navigator . . . . . . . . . . xxviii
Who Should Read This Book . . . . . . . . . . . . . xxvii Prerequisite and Related Information . . . . . . . . . xxviii
Conventions and Terminology Used in This Book . . xxvii How to send your comments . . . . . . . . . . . . . xxviii
OS/400 Terms and Special Values . . . . . . . . xxvii
AS/400 Operations Navigator . . . . . . . . . . . . xxvii Summary of Changes to System API Reference . . xxxi

Part 1. Introduction to the OS/400 Callable APIs

Chapter 1. Application Programming Language Selection Considerations . . . . . . . . . . 2-1
Interfaces—Introduction . . . . . . . . . . . . . . . 1-1 Data Types and Parameter Coding . . . . . . . . . . 2-2
Compatibility with Future Releases . . . . . . . . . . . 1-1 User Space Format for List APIs . . . . . . . . . . . . 2-4
Summary of OS/400 APIs . . . . . . . . . . . . . . . 1-1 API Error Reporting . . . . . . . . . . . . . . . . . . . 2-6
Format of Open List Information . . . . . . . . . . . . 2-7
Chapter 2. Programming Tips for Using OS/400 Path Name Format . . . . . . . . . . . . . . . . . . . 2-8
APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Part 2. Backup and Recovery APIs

Chapter 3. Backup and Recovery APIs . . . . . . . 3-1 Retrieve Backup Detail (QEZRTBKD) API . . . . . . 3-37
Backup and Recovery APIs—Introduction . . . . . . . 3-1 Retrieve Backup History (QEZRTBKH) API . . . . . 3-38
Backup and Recovery Exit Programs—Introduction . . 3-1 Retrieve Backup Options (QEZRTBKO) API . . . . . 3-43
Change Backup Schedule (QEZCHBKS) API . . . . . 3-2 Retrieve Backup Schedule (QEZRTBKS) API . . . . 3-46
Change Job Media Library Attributes (QTACJMA) API 3-5 Retrieve Device Capabilities (QTARDCAP) API . . . 3-48
Change Object Backup List (QEZCHBKL) API . . . . . 3-7 Retrieve Device Information (QTARDINF) API . . . . 3-55
| Create Media Definition (QSRCRTMD, Retrieve Job Media Library Attributes (QTARJMA) API 3-56
| QsrCreateMediaDefinition) API . . . . . . . . . . . . 3-9 | Retrieve Media Definition (QSRRTVMD,
| Delete Media Definition (QSRDLTMD, | QsrRetrieveMediaDefinition) API . . . . . . . . . . 3-58
| QsrDeleteMediaDefinition) API . . . . . . . . . . . 3-12 Save Object (QsrSave) API . . . . . . . . . . . . . 3-61
Dump Device (QTADMPDV) API . . . . . . . . . . . 3-12 Save Object List (QSRSAVO) API . . . . . . . . . . 3-71
Free Object (QTAFROBJ) API . . . . . . . . . . . . 3-14 Save to Application (QaneSava) API . . . . . . . . . 3-80
List Save File (QSRLSAVF) API . . . . . . . . . . . 3-15 Restore from Application Exit Program . . . . . . . . 3-83
Open List of Objects to be Backed Up (QEZOLBKL) Save Storage Free Exit Program . . . . . . . . . . . 3-85
API . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 Save to Application Exit Program . . . . . . . . . . 3-85
Qp0lSaveStgFree()—Save Storage Free . . . . . . . 3-22 Storage Extension Exit Program . . . . . . . . . . . 3-87
Restore from Application (QaneRsta) API . . . . . . 3-26 Tape Management Exit Program . . . . . . . . . . . 3-89
Restore Object (QsrRestore) API . . . . . . . . . . 3-29

Part 3. Client Management Support APIs

| Chapter 4. Client Management Support APIs . . . 4-1

Part 4. Cluster APIs

| Chapter 5. Cluster APIs . . . . . . . . . . . . . . . 5-1 | Cluster Node Status . . . . . . . . . . . . . . . . . . 6-1
| Cluster APIs—Introduction . . . . . . . . . . . . . . . 5-1 | Cluster Control APIs . . . . . . . . . . . . . . . . . . 6-1
| Cluster Resource Services Characteristics . . . . . . . 5-1 | Add Cluster Node Entry (QcstAddClusterNodeEntry) API 6-1
| Cluster Resource Services Job Structure . . . . . . . 5-1 | Change Cluster Node Entry
| Cluster APIs Use of User Queues . . . . . . . . . . . 5-2 | (QcstChangeClusterNodeEntry) API . . . . . . . . . 6-4
| Using Results Information . . . . . . . . . . . . . . . 5-3 | Create Cluster (QcstCreateCluster) API . . . . . . . . 6-6
| Delete Cluster (QcstDeleteCluster) API . . . . . . . . 6-9
| Chapter 6. Cluster Control APIs . . . . . . . . . . . 6-1 | End Cluster Node (QcstEndClusterNode) API . . . . 6-10
| Cluster Control APIs—Introduction . . . . . . . . . . . 6-1 | List Cluster Information (QcstListClusterInfo) API . . 6-12
| Network Attributes . . . . . . . . . . . . . . . . . . . 6-1

 Copyright IBM Corp. 1998, 1999 iii

| Remove Cluster Node Entry | End Cluster Resource Group
| (QcstRemoveClusterNodeEntry) API . . . . . . . . 6-14 | (QcstEndClusterResourceGroup) API . . . . . . . 7-20
| Start Cluster Node (QcstStartClusterNode) API . . . 6-16 | Initiate Switch Over (QcstInitiateSwitchOver) API . . 7-22
| List Cluster Resource Groups
| Chapter 7. Cluster Resource Group APIs . . . . . 7-1 | (QcstListClusterResourceGroups) API . . . . . . . 7-25
| Cluster Resource Group APIs—Introduction . . . . . . 7-1 | List Cluster Resource Group Information
| Add Node To Recovery Domain | (QcstListClusterResourceGroupIn) API . . . . . . . 7-27
| (QcstAddNodeToRcvyDomain) API . . . . . . . . . . 7-5 | Remove Node From Recovery Domain
| Change Cluster Resource Group | (QcstRemoveNodeFromRcvyDomain) API . . . . . 7-31
| (QcstChangeClusterResourceGroup) API . . . . . . 7-8 | Start Cluster Resource Group
| Create Cluster Resource Group | (QcstStartClusterResourceGroup) API . . . . . . . 7-33
| (QcstCreateClusterResourceGroup) API . . . . . . 7-13
| Delete Cluster Resource Group | Chapter 8. Cluster Resource Group Exit Program . 8-1
| (QcstDeleteClusterResourceGroup) API . . . . . . 7-18 | Cluster Resource Group Exit Program—Introduction . 8-1
| Cluster Resource Group Exit Program . . . . . . . . . 8-1

Part 5. Communications APIs

Chapter 9. User-Defined Send Data (QOLSEND) API . . . . . . . . . . . . . 12-27
Communications—Introduction . . . . . . . . . . . 9-1 Set Filter (QOLSETF) API . . . . . . . . . . . . . . 12-43
Overview . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Set Timer (QOLTIMER) API . . . . . . . . . . . . . 12-49
Terminology . . . . . . . . . . . . . . . . . . . . . . . 9-2
Relationship to Communications Standards . . . . . . 9-2 Chapter 13. Debugging of User-Defined
Local Area Network (LAN) Considerations . . . . . . . 9-4 Communications Applications . . . . . . . . . . 13-1
X.25 Considerations . . . . . . . . . . . . . . . . . . 9-5 System Services and Tools . . . . . . . . . . . . . 13-1
Error Codes . . . . . . . . . . . . . . . . . . . . . . 13-9
Chapter 10. Programming Design Considerations 10-1 Common Errors and Messages . . . . . . . . . . . 13-11
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Application Program Feedback . . . . . . . . . . . . 10-2 Chapter 14. Data Stream Translation APIs . . . . 14-1
Programming Languages . . . . . . . . . . . . . . . 10-3 Data Stream Translation APIs—Introduction . . . . . 14-1
Starting and Ending Communications . . . . . . . . 10-3 Using the Data Stream Translation APIs . . . . . . . 14-1
Programming Considerations for LAN Applications . 10-18 End Data Stream Translation Session (QD0ENDTS)
Programming Considerations for X.25 Applications . 10-20 API . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Queue Considerations . . . . . . . . . . . . . . . . 10-25 Start Data Stream Translation Session (QD0STRTS)
User Space Considerations . . . . . . . . . . . . . 10-26 API . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Return Codes and Reason Codes . . . . . . . . . . 10-27 Translate Data Stream (QD0TRNDS) API . . . . . . 14-3
Messages . . . . . . . . . . . . . . . . . . . . . . . 10-27
Chapter 15. OptiConnect APIs . . . . . . . . . . . 15-1
Chapter 11. Configuration and Queue Entries . . 11-1 OptiConnect APIs—Introduction . . . . . . . . . . . 15-1
Configuring User-Defined Communications Support . 11-1 Close Path (QzdmClosePath) API . . . . . . . . . . 15-1
Queue Entries . . . . . . . . . . . . . . . . . . . . 11-1 Close Stream (QzdmCloseStream) API . . . . . . . 15-2
Open Path (QzdmOpenPath) API . . . . . . . . . . 15-3
Chapter 12. User-Defined Communications Open Stream (QzdmOpenStream) API . . . . . . . . 15-5
Support APIs . . . . . . . . . . . . . . . . . . . . 12-1 Receive Control (QzdmReceiveControl) API . . . . . 15-6
User-Defined Communications Support Receive Request (QzdmReceiveRequest) API . . . . 15-7
APIs—Introduction . . . . . . . . . . . . . . . . . 12-1 Receive Response (QzdmReceiveResponse) API . . 15-9
Disable Link (QOLDLINK) API . . . . . . . . . . . . 12-1 Send Request (QzdmSendRequest) API . . . . . . . 15-11
Enable Link (QOLELINK) API . . . . . . . . . . . . 12-2 Send Response (QzdmSendResponse) API . . . . . 15-13
Query Line Description (QOLQLIND) API . . . . . . 12-5 Wait Message (QzdmWaitMessage) API . . . . . . . 15-14
Receive Data (QOLRECV) API . . . . . . . . . . . . 12-14

Part 6. Configuration APIs

Chapter 16. Configuration APIs . . . . . . . . . . 16-1 Retrieve Controller Description (QDCRCTLD) API . . 16-11
Configuration APIs—Introduction . . . . . . . . . . . 16-1 Retrieve Device Description (QDCRDEVD) API . . . 16-29
Change Configuration Description (QDCCCFGD) API 16-1 Retrieve Line Description (QDCRLIND) API . . . . . 16-45
List Configuration Descriptions (QDCLCFGD) API . . 16-2 Retrieve Network Server Description (QDCRNWSD)
Retrieve Configuration Status (QDCRCFGS) API . . 16-8 API . . . . . . . . . . . . . . . . . . . . . . . . . 16-69

iv AS/400 System API Reference V4R4

Part 7. Debugger APIs
Chapter 17. Debugger APIs . . . . . . . . . . . . 17-1 Retrieve Debug Attribute (QteRetrieveDebugAttribute)
Debugger APIs—Introduction . . . . . . . . . . . . . 17-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 17-23
Source Debugger APIs—Introduction . . . . . . . . 17-1 Retrieve Debugged Threads
Source Debugger APIs and Exit (QteRetrieveDebuggedThreads) API . . . . . . . . 17-24
Programs—Introduction . . . . . . . . . . . . . . . 17-2 Retrieve Module Views (QteRetrieveModuleViews)
Create View APIs—Introduction . . . . . . . . . . . 17-3 API . . . . . . . . . . . . . . . . . . . . . . . . . 17-27
Add Breakpoint (QteAddBreakpoint) API . . . . . . . 17-4 Retrieve Program Variable (QTERTVPV) API . . . . 17-30
Add View Description (QteAddViewDescription) API . 17-4 Retrieve Statement View (QteRetrieveStatementView)
Add View File (QteAddViewFile) API . . . . . . . . . 17-6 API . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
Add View Map (QteAddViewMap) API . . . . . . . . 17-8 Retrieve Stopped Position
Add View Text (QteAddViewText) API . . . . . . . . 17-10 (QteRetrieveStoppedPosition) API . . . . . . . . . 17-38
Change Current Thread (QteChangeCurrentThread) Retrieve View File (QteRetrieveViewFile) API . . . . 17-39
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-12 Retrieve View Line Information
Change Thread Status (QteChangeThreadStatus) API 17-13 (QteRetrieveViewLineInformation) API . . . . . . . 17-42
Dump Module Variables (QteDumpModuleVariables) Retrieve View Text (QteRetrieveViewText) API . . . 17-43
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-13 Set Debug Attribute (QteSetDebugAttribute) API . . 17-45
End Source Debug (QteEndSourceDebug) API . . . 17-18 Start Source Debug (QteStartSourceDebug) API . . 17-46
End View Creation (QteEndViewCreation) API . . . 17-18 Start View Creation (QteStartViewCreation) API . . . 17-47
Map View Position (QteMapViewPosition) API . . . . 17-18 Step (QteStep) API . . . . . . . . . . . . . . . . . . 17-49
Register Debug View (QteRegisterDebugView) API . 17-20 Stop Debugged Job (QteStopDebuggedJob) API . . 17-49
Remove All Breakpoints (QteRemoveAllBreakpoints) Submit Debug Command
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-22 (QteSubmitDebugCommand) API . . . . . . . . . . 17-50
Remove Breakpoint (QteRemoveBreakpoint) API . . 17-22 Debug Session Handler Exit Program . . . . . . . . 17-64
Remove Debug View (QteRemoveDebugView) API . 17-23 Program-Stop Handler Exit Program . . . . . . . . . 17-65

Part 8. Directory Services APIs

Chapter 18. Directory Services APIs . . . . . . . 18-1 ldap_first_attribute()—Retrieve First Attribute in an
Lightweight Directory Access Protocol (LDAP) Client Entry . . . . . . . . . . . . . . . . . . . . . . . . . 18-12
APIs—Introduction . . . . . . . . . . . . . . . . . 18-1 ldap_first_entry()—Retrieve First LDAP Entry . . . . 18-13
ldap_abandon()—Abandon an LDAP Operation in ldap_free_urldesc()—Free an LDAP URL Description 18-14
Progress . . . . . . . . . . . . . . . . . . . . . . . 18-3 ldap_get_dn()—Retrieve the Distinguished Name of
ldap_add()—Perform an LDAP Add Operation . . . . 18-3 an Entry . . . . . . . . . . . . . . . . . . . . . . . 18-14
ldap_add_s()—Perform an LDAP Add Operation ldap_get_errno()—Retrieve Error Information . . . . 18-15
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-4 ldap_get_option()—Retrieve LDAP Options . . . . . 18-15
ldap_bind()—Perform an LDAP Bind Request . . . . 18-5 ldap_get_values()—Retrieve a Set of Attribute Values
ldap_bind_s()—Perform an LDAP Bind Request from an Entry . . . . . . . . . . . . . . . . . . . . 18-17
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-6 ldap_get_values_len()—Retrieve a Set of Binary
ldap_compare()—Perform an LDAP Compare Attribute Values . . . . . . . . . . . . . . . . . . . 18-17
Operation . . . . . . . . . . . . . . . . . . . . . . 18-6 ldap_init()—Perform an LDAP Initialization Operation 18-18
ldap_compare_s()—Perform a Synchronous LDAP ldap_is_ldap_url()—Verify LDAP URL . . . . . . . . 18-19
Compare Operation . . . . . . . . . . . . . . . . . 18-7 ldap_memfree()—Free Memory Allocated by LDAP
ldap_count_attributes()—Retrieve Count of Attributes API . . . . . . . . . . . . . . . . . . . . . . . . . 18-20
for an LDAP Entry . . . . . . . . . . . . . . . . . . 18-8 ldap_modify()—Perform an LDAP Modify Entry
ldap_count_entries()—Retrieve Count of LDAP Entries 18-8 Request . . . . . . . . . . . . . . . . . . . . . . . 18-20
ldap_count_values()—Retrieve Count of Attribute ldap_modify_s()—Perform an LDAP Modify Entry
Values . . . . . . . . . . . . . . . . . . . . . . . . 18-9 Request (Synchronous) . . . . . . . . . . . . . . . 18-21
ldap_count_values_len()—Retrieve Count of Binary ldap_modrdn()—Perform an LDAP Modify RDN
Attribute Values . . . . . . . . . . . . . . . . . . . 18-9 Request . . . . . . . . . . . . . . . . . . . . . . . 18-22
ldap_delete()—Perform an LDAP Delete Operation . 18-10 ldap_modrdn_s()—Perform an LDAP Modify RDN
ldap_delete_s()—Perform an LDAP Delete Operation Request (Synchronous) . . . . . . . . . . . . . . . 18-23
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-10 ldap_mods_free()—Free LDAP Modify Storage . . . 18-24
ldap_err2string()—Retrieve LDAP Error Message ldap_msgfree()—Free LDAP Result Message . . . . 18-24
String . . . . . . . . . . . . . . . . . . . . . . . . 18-11 ldap_next_attribute()—Retrieve Next Attribute in an
ldap_explode_dn()—Break a Distinguished Name into Entry . . . . . . . . . . . . . . . . . . . . . . . . . 18-25
Its Components . . . . . . . . . . . . . . . . . . . 18-11 ldap_next_entry()—Retrieve Next LDAP Entry . . . . 18-26

Contents v
ldap_open()—Perform an LDAP Open Operation . . 18-26 ldap_url_search_s()—Perform an LDAP URL Search
ldap_perror()—Print LDAP Error Information . . . . . 18-27 Operation (Synchronous) . . . . . . . . . . . . . . 18-42
ldap_result()—Retrieve Result of an Asynchronous ldap_url_search_st()—Perform an LDAP URL Search
LDAP Operation . . . . . . . . . . . . . . . . . . . 18-27 Operation (Timed Synchronous) . . . . . . . . . . 18-43
ldap_result2error()—Retrieve LDAP Error Information 18-29 ldap_value_free()—Free Memory Allocated by
ldap_search()—Perform an LDAP Search Operation 18-29 ldap_get_values() . . . . . . . . . . . . . . . . . . 18-44
ldap_search_s()—Perform an LDAP Search Operation ldap_value_free_len()—Free Memory Allocated by
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-30 ldap_get_values_len() . . . . . . . . . . . . . . . . 18-45
ldap_search_st()—Perform an LDAP Search LDAP Client API Error Conditions . . . . . . . . . . 18-45
Operation (Timed Synchronous) . . . . . . . . . . 18-31
ldap_set_option()—Set LDAP Options . . . . . . . . 18-32 Chapter 19. Directory Services Configuration APIs 19-1
ldap_set_rebind_proc()—Set Rebind Procedure . . . 18-34 Directory Services Configuration APIs—Introduction . 19-1
ldap_simple_bind()—Perform a Simple LDAP Bind Change Directory Server Attributes (QgldChgDirSvrA)
Request . . . . . . . . . . . . . . . . . . . . . . . 18-34 API . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
ldap_simple_bind_s()—Perform a Simple LDAP Bind Configure Directory Server (QgldCfgDirSvr) API . . . 19-7
Request (Synchronous) . . . . . . . . . . . . . . . 18-35 Export LDIF File (QgldExportLdif) API . . . . . . . . 19-9
ldap_ssl_start()—Start a Secure LDAP Connection . 18-36 Import LDIF File (QgldImportLdif) API . . . . . . . . 19-10
ldap_unbind()—Perform an LDAP Unbind Request . 18-39 List Directory Server Attributes (QgldLstDirSvrA) API 19-12
ldap_unbind_s()—Perform an LDAP Unbind Request | Publish Directory Object (QgldPubDirObj) API . . . . 19-14
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-40 Retrieve Directory Server Attributes (QgldRtvDirSvrA)
ldap_url_parse()—Parse an LDAP URL . . . . . . . 18-40 API . . . . . . . . . . . . . . . . . . . . . . . . . 19-17
ldap_url_search()—Perform an LDAP URL Search Synchronize System Distribution Directory to LDAP
Operation . . . . . . . . . . . . . . . . . . . . . . 18-41 (QGLDSSDD) API . . . . . . . . . . . . . . . . . . 19-20

Part 9. Dynamic Screen Manager APIs

Chapter 20. Dynamic Screen Manager Retrieve Low-Level Environment Window Mode
APIs—Introduction . . . . . . . . . . . . . . . . . 20-1 (QsnRtvEnvWinMod) API . . . . . . . . . . . . . . 22-17
Dynamic Screen Manager APIs—Introduction . . . . 20-1 Retrieve Screen Dimensions (QsnRtvScrDim) API . 22-18
Data Structures for DSM APIs . . . . . . . . . . . . 20-1 Roll Down (QsnRollDown) API . . . . . . . . . . . . 22-19
Omitting Parameters with Associated Lengths . . . . 20-1 Roll Up (QsnRollUp) API . . . . . . . . . . . . . . . 22-20
Save Screen (QsnSavScr) API . . . . . . . . . . . . 22-21
Chapter 21. Low-Level Screen I/O Services APIs 21-1 Set Low-Level Environment Window Mode
Low-Level Screen I/O Services APIs—Introduction . 21-1 (QsnSetEnvWinMod) API . . . . . . . . . . . . . . 22-22
DSM Error Handling . . . . . . . . . . . . . . . . . 21-1
Device Support . . . . . . . . . . . . . . . . . . . . 21-1 Chapter 23. Buffer Manipulation and Query APIs 23-1
Operating Environments . . . . . . . . . . . . . . . 21-1 Buffer Manipulation and Query APIs—Introduction . 23-1
Direct and Indirect Operations . . . . . . . . . . . . 21-1 Clear Buffer (QsnClrBuf) API . . . . . . . . . . . . . 23-1
DBCS Considerations . . . . . . . . . . . . . . . . 21-1 Copy Buffer (QsnCpyBuf) API . . . . . . . . . . . . 23-2
5250 Data Stream Details . . . . . . . . . . . . . . 21-2 Create Command Buffer (QsnCrtCmdBuf) API . . . 23-3
Create Input Buffer (QsnCrtInpBuf) API . . . . . . . 23-4
Chapter 22. Screen Manipulation and Query APIs 22-1 Delete Buffer (QsnDltBuf) API . . . . . . . . . . . . 23-5
Screen Manipulation and Query APIs—Introduction . 22-1 Put Command Buffer (QsnPutBuf) API . . . . . . . . 23-5
Change Low-Level Environment (QsnChgEnv) API . 22-1 Put Command Buffer and Perform Get (QsnPutGetBuf)
Clear Field Table (QsnClrFldTbl) API . . . . . . . . 22-2 API . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Clear Screen (QsnClrScr) API . . . . . . . . . . . . 22-3 Retrieve AID Code on Read (QsnRtvReadAID) API . 23-7
Create Low-Level Environment (QsnCrtEnv) API . . 22-4 Retrieve Available Data (QsnRtvAvailData) API . . . 23-8
Delete Low-Level Environment (QsnDltEnv) API . . . 22-7 Retrieve Buffer Data Length (QsnRtvBufLen) API . . 23-8
Initialize Low-Level Environment Description Retrieve Buffer Size (QsnRtvBufSiz) API . . . . . . 23-9
(QsnInzEnvD) API . . . . . . . . . . . . . . . . . . 22-8 Retrieve Cursor Address on Read (QsnRtvReadAdr)
Query Color Support (QsnQryColorSup) API . . . . 22-9 API . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Query Display Mode Support (QsnQryModSup) API . 22-9 Retrieve Field Information (QsnRtvFldInf) API . . . . 23-11
Query 5250 (QsnQry5250) API . . . . . . . . . . . . 22-10 Retrieve Length of Data in Input Buffer
Restore Screen (QsnRstScr) API . . . . . . . . . . 22-14 (QsnRtvDtaLen) API . . . . . . . . . . . . . . . . 23-12
Retrieve Display Mode (QsnRtvMod) API . . . . . . 22-15 Retrieve Length of Field Data in Buffer
Retrieve Low-Level Environment Description (QsnRtvFldDtaLen) API . . . . . . . . . . . . . . . 23-13
(QsnRtvEnvD) API . . . . . . . . . . . . . . . . . 22-15 Retrieve Number of Bytes Read from Screen
Retrieve Low-Level Environment User Data (QsnRtvReadLen) API . . . . . . . . . . . . . . . 23-13
(QsnRtvEnvDta) API . . . . . . . . . . . . . . . . 22-16 Retrieve Number of Fields Read (QsnRtvFldCnt) API 23-14

vi AS/400 System API Reference V4R4

Retrieve Pointer to Data in Input Buffer (QsnRtvDta) Window I/O APIs—Introduction . . . . . . . . . . . . 28-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 23-15 Clear Window (QsnClrWin) API . . . . . . . . . . . 28-1
Retrieve Pointer to Field Data (QsnRtvFldDta) API . 23-16 Clear Window Message (QsnClrWinMsg) API . . . . 28-1
Retrieve Read Information (QsnRtvReadInf) API . . 23-17 Display Window (QsnDspWin) API . . . . . . . . . . 28-2
Put Window Message (QsnPutWinMsg) API . . . . . 28-3
Chapter 24. Screen Input APIs . . . . . . . . . . 24-1
Screen Input APIs—Introduction . . . . . . . . . . . 24-1 Chapter 29. Window Manager Services APIs . . . 29-1
Read Command Processing . . . . . . . . . . . . . 24-1 Window Manager Services APIs—Introduction . . . 29-1
Get AID (QsnGetAID) API . . . . . . . . . . . . . . 24-1 End a Window (QsnEndWin) API . . . . . . . . . . 29-1
Get Cursor Address (QsnGetCsrAdr) API . . . . . . 24-2 Retrieve Current Window (QsnRtvCurWin) API . . . 29-2
Get Cursor Address with AID (QsnGetCsrAdrAID) API 24-3 Set Current Window (QsnSetCurWin) API . . . . . . 29-2
Put Input Command (QsnPutInpCmd) API . . . . . . 24-4 Start a Window (QsnStrWin) API . . . . . . . . . . . 29-3
Read Immediate (QsnReadImm) API . . . . . . . . 24-5 Performance Considerations . . . . . . . . . . . . . 29-4
Read Input Fields (QsnReadInp) API . . . . . . . . 24-6 Creating/Manipulating Windows Example . . . . . . 29-4
Read from Invited Device (QsnReadInvited) API . . 24-8
Read Modified Alternate (QsnReadMDTAlt) API . . . 24-9 Chapter 30. Introduction to the Session Services
Read Modified Fields (QsnReadMDT) API . . . . . . 24-10 APIs . . . . . . . . . . . . . . . . . . . . . . . . . 30-1
Read Modified Immediate Alternate Session Services APIs—Introduction . . . . . . . . . 30-1
(QsnReadMDTImmAlt) API . . . . . . . . . . . . . 24-12 Session Details . . . . . . . . . . . . . . . . . . . . 30-1
Read Screen (QsnReadScr) API . . . . . . . . . . . 24-13 Command Key Action Routines . . . . . . . . . . . 30-1
Active Position . . . . . . . . . . . . . . . . . . . . 30-2
Chapter 25. Screen Output APIs . . . . . . . . . 25-1 EBCDIC Display Control Characters . . . . . . . . . 30-3
Screen Output APIs—Introduction . . . . . . . . . . 25-1 DBCS Considerations . . . . . . . . . . . . . . . . 30-3
Delete Field ID Definition (QsnDltFldId) API . . . . . 25-1
Generate a Beep (QsnBeep) API . . . . . . . . . . 25-2 Chapter 31. Session Manipulation and Query APIs 31-1
Insert Cursor (QsnInsCsr) API . . . . . . . . . . . . 25-2 Session Manipulation and Query APIs—Introduction 31-1
Pad between Two Screen Addresses (QsnWrtPadAdr) Change Session (QsnChgSsn) API . . . . . . . . . 31-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 25-4 Clear Scroller (QsnClrScl) API . . . . . . . . . . . . 31-2
Pad for N Positions (QsnWrtPad) API . . . . . . . . 25-5 Create a Session (QsnCrtSsn) API . . . . . . . . . . 31-2
Put Output Command (QsnPutOutCmd) API . . . . . 25-7 Display Scroller Bottom (QsnDspSclB) API . . . . . 31-8
Set Cursor Address (QsnSetCsrAdr) API . . . . . . 25-8 Display Scroller Top (QsnDspSclT) API . . . . . . . 31-9
Set Error State (QsnSetErr) API . . . . . . . . . . . 25-9 Initialize Session Description (QsnInzSsnD) API . . . 31-9
Set Field (QsnSetFld) API . . . . . . . . . . . . . . 25-11 Query If Scroller in Line Wrap Mode (QsnQrySclWrp)
Set Output Address (QsnSetOutAdr) API . . . . . . 25-17 API . . . . . . . . . . . . . . . . . . . . . . . . . 31-10
Write Data (QsnWrtDta) API . . . . . . . . . . . . . 25-18 Retrieve Number of Columns to Shift Scroller
Write Structured Field Major (QsnWrtSFMaj) API . . 25-21 (QsnRtvSclNumShf) API . . . . . . . . . . . . . . 31-11
Write Structured Field Minor (QsnWrtSFMin) API . . 25-22 Retrieve Number of Rows to Roll Scroller
Write to Display (QsnWTD) API . . . . . . . . . . . 25-23 (QsnRtvSclNumRoll) API . . . . . . . . . . . . . . 31-11
Write Transparent Data (QsnWrtTDta) API . . . . . 25-25 Retrieve Session Data (QsnRtvSsnDta) API . . . . . 31-12
Low-Level Services Examples . . . . . . . . . . . . 25-26 Retrieve Session Description (QsnRtvSsnD) API . . 31-13
Performance Considerations . . . . . . . . . . . . . 25-29 Roll Scroller Down (QsnRollSclDown) API . . . . . . 31-14
Limitations and Restrictions . . . . . . . . . . . . . 25-30 Roll Scroller Up (QsnRollSclUp) API . . . . . . . . . 31-14
Shift Scroller Left (QsnShfSclL) API . . . . . . . . . 31-15
Chapter 26. Introduction to the Window Services Shift Scroller Right (QsnShfSclR) API . . . . . . . . 31-16
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 26-1 Toggle Line Wrap/Truncate Mode (QsnTglSclWrp)
API . . . . . . . . . . . . . . . . . . . . . . . . . 31-16
Chapter 27. Window Manipulation and Query APIs 27-1
Window Manipulation and Query APIs—Introduction 27-1 Chapter 32. Session I/O APIs . . . . . . . . . . . 32-1
Change Window (QsnChgWin) API . . . . . . . . . 27-1 Session I/O APIs—Introduction . . . . . . . . . . . . 32-1
Create a Window (QsnCrtWin) API . . . . . . . . . . 27-2 Backspace on Scroller Line (QsnSclBS) API . . . . . 32-1
Initialize Window Description (QsnInzWinD) API . . . 27-8 Go to Next Tab Position in Scroller Line (QsnSclTab)
Move Window (QsnMovWin) API . . . . . . . . . . . 27-9 API . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Move Window by User (QsnMovWinUsr) API . . . . 27-9 Go to Start of Current Scroller Line (QsnSclCR) API 32-2
Resize Window (QsnRszWin) API . . . . . . . . . . 27-10 Go to Start of Next Scroller Line (QsnSclNL) API . . 32-3
Resize Window by User (QsnRszWinUsr) API . . . . 27-11 Print Scroller Data (QsnPrtScl) API . . . . . . . . . 32-3
Retrieve Window Data (QsnRtvWinDta) API . . . . . 27-12 Read Data from Session (QsnReadSsnDta) API . . 32-4
Retrieve Window Description (QsnRtvWinD) API . . 27-12 Retrieve Session Line to Input Line (QsnRtvSsnLin)
Set Window Services Attributes (QsnSetWinAtr) API 27-13 API . . . . . . . . . . . . . . . . . . . . . . . . . 32-5
Start New Scroller Line at Current Position (QsnSclLF)
Chapter 28. Window I/O APIs . . . . . . . . . . . 28-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 32-6

Contents vii
 Start New Scroller Page (QsnSclFF) API . . . . . . 32-6 Performance Considerations . . . . . . . . . . . . . 32-8
Write Characters to Scroller (QsnWrtSclChr) API . . 32-7 Create Session and Read Data—Example . . . . . . 32-9
Write Line to Scroller (QsnWrtSclLin) API . . . . . . 32-8

Part 10. Edit Function APIs

Chapter 33. Edit Function APIs . . . . . . . . . . 33-1 Convert Edit Word (QECCVTEW) API . . . . . . . . 33-2
Edit Function APIs—Introduction . . . . . . . . . . . 33-1 Edit (QECEDT) API . . . . . . . . . . . . . . . . . . 33-4
Convert Edit Code (QECCVTEC) API . . . . . . . . 33-1

Part 11. File APIs

Chapter 34. File APIs . . . . . . . . . . . . . . . . 34-1 List Record Formats (QUSLRCD) API . . . . . . . . 34-27
File APIs—Introduction . . . . . . . . . . . . . . . . 34-1 | Process Command (QxdaProcessCommandEDRS)
File Exit Program—Introduction . . . . . . . . . . . 34-2 | API . . . . . . . . . . . . . . . . . . . . . . . . . 34-29
| Block EDRS Access (QxdaBlockEDRS) API . . . . . 34-2 Process Extended Dynamic SQL (QSQPRCED) API 34-30
| Call Program (QxdaCallProgramEDRS) API . . . . . 34-3 | Process Immediate SQL Statement
| Check EDRS Block Status (QxdaCheckEDRSBlock) | (QxdaProcessImmediateEDRS) API . . . . . . . . 34-37
| API . . . . . . . . . . . . . . . . . . . . . . . . . 34-4 | Process Remote Extended Dynamic SQL
Clear SQL Database Monitor Statistics (QQQCSDBM) | (QxdaProcessExtDynEDRS) API . . . . . . . . . . 34-38
API . . . . . . . . . . . . . . . . . . . . . . . . . 34-6 Query (QQQQRY) API . . . . . . . . . . . . . . . . 34-40
| Commit EDRS Server (QxdaCommitEDRS) API . . . 34-6 Query SQL Database Monitor (QQQQSDBM) API . . 34-71
| Connect to EDRS Server (QxdaConnectEDRS) API . 34-7 Retrieve Database File Description (QDBRTVFD) API 34-72
Create Database Hash (QCreateDatabaseHash) API 34-10 Retrieve Display File Description (QDFRTVFD) API 34-117
| Disconnect from EDRS Server Retrieve File Override Information (QDMRTVFO) API 34-182
| (QxdaDisconnectEDRS) API . . . . . . . . . . . . 34-11 Retrieve Member Description (QUSRMBRD) API . 34-183
Dump SQL Database Monitor (QQQDSDBM) API . . 34-11 Retrieve Short Name (QDBRTVSN) API . . . . . . 34-193
End SQL Database Monitor (QQQESDBM) API . . . 34-13 | Roll Back EDRS Server (QxdaRollbackEDRS) API 34-194
| Find EDRS Job (QxdaFindEDRSJob) API . . . . . . 34-13 Run Database Hash (QDBRUNHA) API . . . . . . 34-195
List Database File Members (QUSLMBR) API . . . . 34-15 Start SQL Database Monitor (QQQSSDBM) API . 34-195
List Database Relations (QDBLDBR) API . . . . . . 34-18 Syntax Check SQL Statement (QSQCHKS) API . . 34-197
List Fields (QUSLFLD) API . . . . . . . . . . . . . . 34-21 SQL Client Integration Exit Program . . . . . . . . 34-201

Part 12. Hardware Resource APIs

| Chapter 35. Hardware Resource APIs . . . . . . 35-1

Part 13. Hierarchical File System APIs

| Chapter 36. Hierarchical File System APIs . . . . 36-1

Part 14. High-Level Language APIs

Chapter 37. Application Development Manager/400 COBOL/400 APIs—Introduction . . . . . . . . . . . 38-1
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 37-1 Change COBOL Main Program (QLRCHGCM) API . 38-1
Application Development Manager APIs—Introduction 37-1 Dump COBOL (QlnDumpCobol) API . . . . . . . . . 38-2
Get Space Status (QLYGETS) API . . . . . . . . . . 37-2 Retrieve COBOL Error Handler
Read Build Information (QLYRDBI) API . . . . . . . 37-3 (QlnRtvCobolErrorHandler) API . . . . . . . . . . . 38-3
Set Space Status (QLYSETS) API . . . . . . . . . . 37-4 Retrieve COBOL Error Handler (QLRRTVCE) API . 38-3
Write Build Information (QLYWRTBI) API . . . . . . 37-4 Set COBOL Error Handler (QlnSetCobolErrorHandler)
Record Types . . . . . . . . . . . . . . . . . . . . . 37-5 API . . . . . . . . . . . . . . . . . . . . . . . . . 38-4
Examples of Records Written . . . . . . . . . . . . 37-17 Set COBOL Error Handler (QLRSETCE) API . . . . 38-5
ILE COBOL Error-Handling Exit Procedure . . . . . 38-6
Chapter 38. COBOL/400 APIs . . . . . . . . . . . 38-1 OPM COBOL Error-Handling Exit Program . . . . . 38-7

viii AS/400 System API Reference V4R4

Part 15. Integrated Language Environment (ILE) CEE APIs
Chapter 39. Descriptions of the ILE CEE APIs . . 39-1 Get Current Greenwich Mean Time (CEEGMT) API . 42-13
ILE CEE APIs—Introduction . . . . . . . . . . . . . 39-1 Get Current Local Time (CEELOCT) API . . . . . . 42-13
ILE CEE API Calling Conventions . . . . . . . . . . 39-1 Get Offset from Universal Time Coordinated to Local
Naming Conventions of the ILE CEE APIs . . . . . . 39-2 Time (CEEUTCO) API . . . . . . . . . . . . . . . 42-13
Data Type Definitions of ILE CEE APIs . . . . . . . 39-2 Get Universal Time Coordinated (CEEUTC) API . . 42-14
Omitting Parameters in ILE CEE APIs . . . . . . . . 39-4 Query Century (CEEQCEN) API . . . . . . . . . . . 42-15
Return Default Date and Time Strings for Country
Chapter 40. Activation Group and Control Flow (CEEFMDT) API . . . . . . . . . . . . . . . . . . 42-15
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 40-1 Return Default Date String for Country (CEEFMDA)
Activation Group and Control Flow APIs—Introduction 40-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 42-17
Abnormal End (CEE4ABN) API . . . . . . . . . . . 40-1 Return Default Time String for Country (CEEFMTM)
Find a Control Boundary (CEE4FCB) API . . . . . . 40-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 42-17
Register Activation Group Exit Procedure (CEE4RAGE) Set Century (CEESCEN) API . . . . . . . . . . . . 42-18
API . . . . . . . . . . . . . . . . . . . . . . . . . 40-2
Register Call Stack Entry Termination User Exit Chapter 43. Math APIs . . . . . . . . . . . . . . . 43-1
Procedure (CEERTX) API . . . . . . . . . . . . . 40-3 Math APIs—Introduction . . . . . . . . . . . . . . . 43-1
Normal End (CEETREC) API . . . . . . . . . . . . . 40-4 Data Types and Limits . . . . . . . . . . . . . . . . 43-1
Unregister Call Stack Entry Termination User Exit Calling Math Bindable APIs . . . . . . . . . . . . . 43-2
Procedure (CEEUTX) API . . . . . . . . . . . . . 40-4 Math Bindable APIs Are Procedures . . . . . . . . . 43-3
ILE Math Bindable API Descriptions . . . . . . . . . 43-3
Chapter 41. Condition Management APIs . . . . 41-1 Message Descriptions . . . . . . . . . . . . . . . . 43-8
Condition Management APIs—Introduction . . . . . 41-1 Basic Random Number Generation (CEERAN0) API 43-9
How Conditions Are Represented . . . . . . . . . . 41-1 Convert 64-Bit Integer to Character String
Condition Token Layout . . . . . . . . . . . . . . . 41-1 (CEE4JNTS) API . . . . . . . . . . . . . . . . . . 43-10
Condition Token Testing . . . . . . . . . . . . . . . 41-2 Convert Character String to 64-Bit Integer
Construct a Condition Token (CEENCOD) API . . . 41-3 (CEE4JSTN) API . . . . . . . . . . . . . . . . . . 43-10
Decompose a Condition Token (CEEDCOD) API . . 41-3
Handle a Condition (CEE4HC) API . . . . . . . . . . 41-4 Chapter 44. Message Services APIs . . . . . . . 44-1
Move the Resume Cursor to a Return Point Message Services APIs—Introduction . . . . . . . . 44-1
(CEEMRCR) API . . . . . . . . . . . . . . . . . . 41-5 Dispatch a Message (CEEMOUT) API . . . . . . . . 44-1
Register a User-Written Condition Handler (CEEHDLR) Get a Message (CEEMGET) API . . . . . . . . . . 44-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 41-6 Get, Format, and Dispatch a Message (CEEMSG) API 44-2
Retrieve ILE Version and Platform ID (CEEGPID) API 41-7
Return the Relative Invocation Number (CEE4RIN) API 41-8 Chapter 45. Program or Procedure Call APIs . . 45-1
Signal a Condition (CEESGL) API . . . . . . . . . . 41-8 Program or Procedure Call APIs—Introduction . . . 45-1
Unregister a User-Written Condition Handler Get String Information (CEEGSI) API . . . . . . . . 45-1
(CEEHDLU) API . . . . . . . . . . . . . . . . . . . 41-9 Retrieve Operational Descriptor Information (CEEDOD)
API . . . . . . . . . . . . . . . . . . . . . . . . . 45-2
Chapter 42. Date and Time APIs . . . . . . . . . 42-1 Test for Omitted Argument (CEETSTA) API . . . . . 45-3
Date and Time APIs—Introduction . . . . . . . . . . 42-1
Date and Time Notation and Limits . . . . . . . . . 42-1 Chapter 46. Storage Management APIs . . . . . . 46-1
Calculate Day of Week from Lilian Date (CEEDYWK) Storage Management APIs—Introduction . . . . . . 46-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 42-1 Allocation Strategy Type (CEE4ALC) . . . . . . . . 46-1
Convert Date to Lilian Format (CEEDAYS) API . . . 42-2 Create Heap (CEECRHP) API . . . . . . . . . . . . 46-3
Convert Integers to Seconds (CEEISEC) API . . . . 42-6 Define Heap Allocation Strategy (CEE4DAS) API . . 46-4
Convert Lilian Date to Character Format (CEEDATE) Discard Heap (CEEDSHP) API . . . . . . . . . . . . 46-5
API . . . . . . . . . . . . . . . . . . . . . . . . . 42-7 Free Storage (CEEFRST) API . . . . . . . . . . . . 46-5
Convert Seconds to Character Timestamp (CEEDATM) Get Heap Storage (CEEGTST) API . . . . . . . . . 46-6
API . . . . . . . . . . . . . . . . . . . . . . . . . 42-8 Mark Heap (CEEMKHP) API . . . . . . . . . . . . . 46-6
Convert Seconds to Integers (CEESECI) API . . . . 42-10 Reallocate Storage (CEECZST) API . . . . . . . . . 46-7
Convert Timestamp to Number of Seconds Release Heap (CEERLHP) API . . . . . . . . . . . 46-7
(CEESECS) API . . . . . . . . . . . . . . . . . . . 42-11

Part 16. Journal and Commit APIs

Chapter 47. Journal and Commit APIs . . . . . . 47-1 Journal and Commit APIs—Introduction . . . . . . . 47-1

Contents ix
 Journal and Commit Exit Programs—Introduction . . 47-1 Remove Remote Journal (QjoRemoveRemoteJournal)
Journaling . . . . . . . . . . . . . . . . . . . . . . . 47-2 API . . . . . . . . . . . . . . . . . . . . . . . . . 47-23
Commitment Control . . . . . . . . . . . . . . . . . 47-3 Retrieve Commitment Information (QTNRCMTI) API 47-24
Add Commitment Resource (QTNADDCR) API . . . 47-5 | Retrieve Journal Entries (QjoRetrieveJournalEntries)
Add Remote Journal (QjoAddRemoteJournal) API . . 47-10 | API . . . . . . . . . . . . . . . . . . . . . . . . . 47-27
Change Commitment Options (QTNCHGCO) API . . 47-13 Retrieve Journal Identifier Information (QJORJIDI) API 47-39
Change Journal State (QjoChangeJournalState) API 47-16 Retrieve Journal Information
| Delete Pointer Handle (QjoDeletePointerHandle) API 47-21 (QjoRetrieveJournalInformation) API . . . . . . . . 47-41
Materialize Journal Port Attributes Retrieve Journal Receiver Information
(QusMaterializeJournalPortAttr) API . . . . . . . . 47-21 (QjoRtvJrnReceiverInformation) API . . . . . . . . 47-49
Materialize Journal Space Attributes Rollback Required (QTNRBRQD) API . . . . . . . . 47-54
(QusMaterializeJournalSpaceAttr) API . . . . . . . 47-22 Send Journal Entry (QJOSJRNE) API . . . . . . . . 47-54
Remove Commitment Resource (QTNRMVCR) API . 47-22 Commitment Control Exit Program . . . . . . . . . . 47-57
Delete Journal Receiver Exit Program . . . . . . . . 47-61

Part 17. Message Handling APIs

Chapter 48. Message Handling APIs . . . . . . . 48-1 Remove Program Messages (QMHRMVPM) API . . 48-74
Message Handling APIs—Introduction . . . . . . . . 48-1 Resend Escape Message (QMHRSNEM) API . . . . 48-77
Message Handling Exit Programs—Introduction . . . 48-2 Retrieve Message (QMHRTVM) API . . . . . . . . . 48-81
Terms and Concepts . . . . . . . . . . . . . . . . . 48-2 Retrieve Message File Attributes (QMHRMFAT) API 48-87
Change Exception Message (QMHCHGEM) API . . 48-4 Retrieve Nonprogram Message Queue Attributes
Control Job Log Output (QMHCTLJL) API . . . . . . 48-6 (QMHRMQAT) API . . . . . . . . . . . . . . . . . 48-88
List Job Log Messages (QMHLJOBL) API . . . . . . 48-11 Retrieve Request Message (QMHRTVRQ) API . . . 48-91
List Nonprogram Messages (QMHLSTM) API . . . . 48-22 Send Break Message (QMHSNDBM) API . . . . . . 48-93
Move Program Messages (QMHMOVPM) API . . . . 48-32 Send Nonprogram Message (QMHSNDM) API . . . 48-95
Open List of Job Log Messages (QGYOLJBL) API . 48-37 Send Program Message (QMHSNDPM) API . . . . . 48-98
Open List of Messages (QGYOLMSG) API . . . . . 48-44 Send Reply Message (QMHSNDRM) API . . . . . 48-105
Promote Message (QMHPRMM) API . . . . . . . . 48-53 Send Scope Message (QMHSNDSM) API . . . . . 48-107
Receive Nonprogram Message (QMHRCVM) API . . 48-55 Break Handling Exit Program . . . . . . . . . . . . 48-108
Receive Program Message (QMHRCVPM) API . . . 48-62 Default Handling Exit Program . . . . . . . . . . . 48-108
Remove Nonprogram Messages (QMHRMVM) API . 48-73

Part 18. National Language Support APIs

Chapter 49. National Language Support APIs . . 49-1 Validate Language ID (QLGVLID) API . . . . . . . . 49-49
National Language Support APIs—Introduction . . . 49-1
Convert Case (QLGCNVCS, QlgConvertCase) API . 49-1 Chapter 50. National Language Data Conversion
Convert Sort Sequence Table (QLGCNVSS) API . . 49-3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . 50-1
QlgCvtTextDescToDesc()—Convert Text Descriptor Data Conversion APIs—Introduction . . . . . . . . . 50-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 49-4 Convert Data (QDCXLATE) API . . . . . . . . . . . 50-1
QtqValidateCCSID()—Validate CCSID API . . . . . 49-6 iconv()—Code Conversion API . . . . . . . . . . . . 50-3
| Retrieve CCSID Data (QLGRTVCD) . . . . . . . . . 49-7 iconv_close()—Code Conversion Deallocation API . 50-5
Retrieve Language IDs (QLGRTVLI) API . . . . . . 49-8 iconv_open()—Code Conversion Allocation API . . . 50-6
Retrieve Language Information (QLGRLNGI) API . . 49-9 QtqIconvOpen()—Code Conversion Allocation API . 50-8
Retrieve Locale Information (QLGRTVLC,
QlgRetrieveLocaleInformation) API . . . . . . . . . 49-11 Chapter 51. Character Data Representation
Retrieve Sort Sequence Table (QLGRTVSS) API . . 49-29 Architecture (CDRA) APIs . . . . . . . . . . . . . 51-1
Scan String for Mixed Data (QLGSCNMX) API . . . 49-32 Character Data Representation Architecture (CDRA)
Sort (QLGSORT) API . . . . . . . . . . . . . . . . . 49-32 APIs—Introduction . . . . . . . . . . . . . . . . . 51-1
Sort Input/Output (QLGSRTIO) API . . . . . . . . . 49-42 Convert a Graphic Character String (CDRCVRT) API 51-1
Truncate Character Data (QLGTRDTA) API . . . . . 49-46 Get CCSID for Normalization (CDRGCCN) API . . . 51-4
UniNextCompChar()—Advance to Next Composite Get Control Function Definition (CDRGCTL) API . . 51-5
Character Sequence API . . . . . . . . . . . . . . 49-47 Get Encoding Scheme, Character Set, and Code Page
UniQueryCompChar()—Number of Composite Elements (CDRGESP) API . . . . . . . . . . . . . 51-7
Character Sequences API . . . . . . . . . . . . . 49-48 Get Related Default CCSID (CDRGRDC) API . . . . 51-8
UniQueryCompCharLen()—Composite Character Get Short Form (CCSID) from Specified ES and (CS,
Sequence Code Element Count API . . . . . . . . 49-49 CP) Pair (CDRSCSP) API . . . . . . . . . . . . . 51-9

x AS/400 System API Reference V4R4

 Get Short Form with Maximal CS for Specified ES Get Short Form with Maximal CS for Specified ES
and CP (CDRSMXC) API . . . . . . . . . . . . . . 51-10 and CP (QTQSMXC2) API . . . . . . . . . . . . . 51-12
Resolve Client Server CCSID (QTQRCSC) API . . . 51-13

Part 19. Network Management APIs

Chapter 52. Network Management APIs . . . . . 52-1 Register Application (QNMREGAP) API . . . . . . . 52-19
Network Management APIs—Introduction . . . . . . 52-1 Register APPN Topology Information (QNMRGTI) API 52-20
Network Management APIs—Overview . . . . . . . 52-1 Register Filter Notifications (QNMRGFN) API . . . . 52-28
Add Activity (QFVADDA) API . . . . . . . . . . . . . 52-5 Remove Activity (QFVRMVA) API . . . . . . . . . . 52-30
Change Mode Name (QNMCHGMN) API . . . . . . 52-8 Retrieve Alert (QALRTVA) API . . . . . . . . . . . . 52-31
Deregister Application (QNMDRGAP) API . . . . . . 52-9 Retrieve Change Request Description (QFVRTVCD)
Deregister APPN Topology Information (QNMDRGTI) API . . . . . . . . . . . . . . . . . . . . . . . . . 52-33
API . . . . . . . . . . . . . . . . . . . . . . . . . 52-9 Retrieve Mode Name (QNMRTVMN) API . . . . . . 52-36
Deregister Filter Notifications (QNMDRGFN) API . . 52-10 Retrieve Registered Filters (QNMRRGF) API . . . . 52-37
End Application (QNMENDAP) API . . . . . . . . . 52-10 Send Alert (QALSNDA) API . . . . . . . . . . . . . 52-38
Generate Alert (QALGENA) API . . . . . . . . . . . 52-11 Send Error (QNMSNDER) API . . . . . . . . . . . . 52-38
List Activities (QFVLSTA) API . . . . . . . . . . . . 52-12 Send Reply (QNMSNDRP) API . . . . . . . . . . . 52-39
List Node List Entries (QFVLSTNL) API . . . . . . . 52-15 Send Request (QNMSNDRQ) API . . . . . . . . . . 52-40
Receive Data (QNMRCVDT) API . . . . . . . . . . 52-17 Start Application (QNMSTRAP) API . . . . . . . . . 52-42
Receive Operation Completion (QNMRCVOC) API . 52-18

Part 20. Object APIs

| Chapter 53. Object APIs . . . . . . . . . . . . . . 53-1

Part 21. Office APIs

Chapter 54. Office APIs . . . . . . . . . . . . . . 54-1 Add Mail Server Framework Configuration
Office APIs—Introduction . . . . . . . . . . . . . . . 54-1 (QzmfAddMailCfg) API . . . . . . . . . . . . . . . 56-2
Add Department (QOKADDDP) API . . . . . . . . . 54-1 Change Mail Message (QzmfChgMailMsg) API . . . 56-3
Aid Spelling (QTWAIDSP) API . . . . . . . . . . . . 54-2 Complete Creation Sequence (QzmfCrtCmpMailMsg)
Change Department (QOKCHGDP) API . . . . . . . 54-4 API . . . . . . . . . . . . . . . . . . . . . . . . . 56-9
Change Office Program (QOGCHGOE) API . . . . . 54-5 Create Mail Message (QzmfCrtMailMsg) API . . . . 56-10
Check Spelling (QTWCHKSP) API . . . . . . . . . . 54-6 List Mail Server Framework Configuration
Control Office Services (QOCCTLOF) API . . . . . . 54-9 (QzmfLstMailCfg) API . . . . . . . . . . . . . . . . 56-16
Display Directory Panels (QOKDSPDP) API . . . . . 54-9 Query Mail Message Identifier (QzmfQryMailMsgId)
Display Directory X.400 Panels (QOKDSPX4) API . 54-11 API . . . . . . . . . . . . . . . . . . . . . . . . . 56-18
Remove Department (QOKRMVDP) API . . . . . . . 54-12 Remove Mail Server Framework Configuration
Retrieve Office Programs (QOGRTVOE) API . . . . 54-12 (QzmfRmvMailCfg) API . . . . . . . . . . . . . . . 56-18
Search System Directory (QOKSCHD) API . . . . . 54-14 Remove Reserved Mail Message Identifier
Word Separator Tables . . . . . . . . . . . . . . . . 54-26 (QzmfRmvRsvMailMsgId) API . . . . . . . . . . . 56-19
Reserve Mail Message Identifier (QzmfRsvMailMsgId)
Chapter 55. Office Exit Programs . . . . . . . . . 55-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 56-20
Office Exit Programs—Introduction . . . . . . . . . . 55-1 Retrieve Mail Message (QzmfRtvMailMsg) API . . . 56-21
Directory Maintenance Exit Program . . . . . . . . . 55-1 Snap-In Call Exit Program . . . . . . . . . . . . . . 56-27
Directory Search Exit Program . . . . . . . . . . . . 55-8 Track Mail Message Changes Exit Program . . . . . 56-34
Directory Supplier Exit Program . . . . . . . . . . . 55-9 Validate Data Field Exit Program . . . . . . . . . . . 56-35
Document Conversion Exit Program . . . . . . . . . 55-16
Document Handling Exit Program . . . . . . . . . . 55-17 Chapter 57. SNADS File Server Object APIs . . . 57-1
User Application Administration Exit Program . . . . 55-29 SNADS File Server Object APIs—Introduction . . . . 57-1
File Server Operations—Overview . . . . . . . . . . 57-1
Chapter 56. AnyMail/400 Mail Server Framework Assign SNADS File Server Object Access ID
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 56-1 (QZDASNID) API . . . . . . . . . . . . . . . . . . 57-2
Mail Server Framework APIs—Introduction . . . . . 56-1 Create SNADS File Server Object (QZDCRFSO) API 57-3
Mail Server Framework Exit Programs—Introduction 56-1 List SNADS File Server Object Access IDs
(QZDLSTID) API . . . . . . . . . . . . . . . . . . 57-4

Contents xi
 Read SNADS File Server Object (QZDRDFSO) API . 57-5 Revoke SNADS File Server Object Access ID
Retrieve SNADS File Server Object Access ID (QZDRVKID) API . . . . . . . . . . . . . . . . . . 57-9
(QZDRTVID) API . . . . . . . . . . . . . . . . . . 57-8 Write to SNADS File Server Object (QZDWTFSO) API 57-9

Part 22. Operational Assistant APIs

Chapter 58. Operational Assistant APIs . . . . . 58-1 Work with Messages (QEZMSG) API . . . . . . . . 58-8
Operational Assistant APIs—Introduction . . . . . . 58-1 Work with Printer Output (QEZOUTPT) API . . . . . 58-9
List Signed-On Users (QEZLSGNU) API . . . . . . . 58-1
Operational Assistant Attention-Key-Handling (group Chapter 59. Operational Assistant Exit Programs 59-1
jobs) (QEZMAIN) API . . . . . . . . . . . . . . . . 58-4 Operational Assistant Exit Programs—Introduction . 59-1
Operational Assistant Attention-Key-Handling Exit Program for Tailoring Automatic Cleanup . . . . 59-1
(nongroup jobs) (QEZAST) API . . . . . . . . . . . 58-4 Exit Program for Tailoring Operational Assistant
Save Information (QEZSAVIN) API . . . . . . . . . . 58-4 Backup . . . . . . . . . . . . . . . . . . . . . . . 59-1
Send Message (QEZSNDMG) API . . . . . . . . . . 58-5 Exit Program for Tailoring Power Off . . . . . . . . . 59-2
Work with Jobs (QEZBCHJB) API . . . . . . . . . . 58-8

Part 23. Performance Collector APIs

Chapter 60. Performance Collector APIs . . . . . 60-1 List Performance Data (QPMLPFRD) API . . . . . . 60-1
Performance Collector APIs—Introduction . . . . . . 60-1 Work with Collector (QPMWKCOL) API . . . . . . . 60-22
Performance Collector Exit Program—Introduction . 60-1 Performance Monitor Exit Program . . . . . . . . . . 60-24

Part 24. Print APIs

Chapter 61. Print APIs . . . . . . . . . . . . . . . 61-1 Print Exit Programs—Introduction . . . . . . . . . . 62-1
Print APIs—Introduction . . . . . . . . . . . . . . . 61-1 Exit Program for a Customized Separator Page . . . 62-1
Spool and Print Tools in Library QUSRTOOL . . . . 61-2 Print Driver Exit Program . . . . . . . . . . . . . . . 62-4
Build Open Time Commands (QSPBOPNC) API . . 61-2 Writer Transform Exit Program . . . . . . . . . . . . 62-8
Build Separator Pages (QSPBSEPP) API . . . . . . 61-3
Change Output Queue (QSPCHGOQ) API . . . . . 61-5 Chapter 63. Spooled File APIs . . . . . . . . . . . 63-1
Convert Image (QIMGCVTI, QimgCvtImg) API . . . 61-7 Spooled File APIs—Introduction . . . . . . . . . . . 63-1
Extract Writer Status (QSPEXTWI) API . . . . . . . 61-22 Close Spooled File (QSPCLOSP) API . . . . . . . . 63-1
Host Print Transform (QWPZHPTR, Copy AFPDS Resource (QGSCPYRS) API . . . . . 63-2
QwpzHostPrintTransform) API . . . . . . . . . . . 61-24 Create Spooled File (QSPCRTSP) API . . . . . . . 63-5
Open List of Printers (QGYRPRTL) API . . . . . . . 61-34 Get Spooled File Data (QSPGETSP) API . . . . . . 63-29
Retrieve Output Queue Information (QSPROUTQ) API 61-36 List Spooled File AFPDS Resources (QGSLRSC) API 63-37
Retrieve Printer Attributes (QGYRPRTA) API . . . . 61-44 List Spooled Files (QUSLSPL) API . . . . . . . . . . 63-41
Retrieve Writer Information (QSPRWTRI) API . . . . 61-48 Move Spooled File (QSPMOVSP) API . . . . . . . . 63-47
Send Writer Message (QSPSNDWM) API . . . . . . 61-52 Open List of Spooled Files (QGYOLSPL) API . . . . 63-53
Set Writer Status (QSPSETWI) API . . . . . . . . . 61-54 Open Spooled File (QSPOPNSP) API . . . . . . . . 63-59
Transform AFP to ASCII (QWPZTAFP) API . . . . . 61-57 Put Spooled File Data (QSPPUTSP) API . . . . . . 63-61
Retrieve Spooled File Attributes (QUSRSPLA) API . 63-63
Chapter 62. Print Exit Programs . . . . . . . . . . 62-1

Part 25. Problem Management APIs

| Chapter 64. Problem Management APIs . . . . . 64-1

Part 26. Program and CL Command APIs

Chapter 65. Program and CL Command APIs . . 65-1 Add Associated Space Entry
Program and CL Command APIs–Introduction . . . . 65-1 (QbnAddAssociatedSpaceEntry) API . . . . . . . . 65-3
Activate Bound Program (QleActBndPgm) API . . . 65-2 Add Bindtime Exit (QbnAddBindtimeExit) API . . . . 65-4

xii AS/400 System API Reference V4R4

 Add Extended Attribute Data List Service Program Information (QBNLSPGM) API 65-43
(QbnAddExtendedAttributeData) API . . . . . . . . 65-5 Process Commands (QCAPCMD) API . . . . . . . . 65-53
Add Preprocessor Level Data Retrieve Associated Space
(QbnAddPreProcessorLevelData) API . . . . . . . 65-5 (QbnRetrieveAssociatedSpace) API . . . . . . . . 65-56
| Call Service Program Procedure (QZRUCLSP) API . 65-6 Retrieve Command Information (QCDRCMDI) API . 65-57
Check Command Syntax (QCMDCHK) API . . . . . 65-8 Retrieve Module Information (QBNRMODI) API . . . 65-62
Create Program (QPRCRTPG) API . . . . . . . . . 65-9 Retrieve Program Associated Space (QCLRPGAS)
Program Attributes . . . . . . . . . . . . . . . . . . 65-15 API . . . . . . . . . . . . . . . . . . . . . . . . . 65-73
Program Syntax . . . . . . . . . . . . . . . . . . . 65-15 Retrieve Program Information (QCLRPGMI) API . . 65-75
Coding Techniques . . . . . . . . . . . . . . . . . . 65-24 Retrieve Service Program Information (QBNRSPGM)
End Preprocessor (QbnEndPreProcessor) API . . . 65-27 API . . . . . . . . . . . . . . . . . . . . . . . . . 65-86
Execute Command (QCMDEXC) API . . . . . . . . 65-29 Scan for String Pattern (QCLSCAN) API . . . . . . . 65-91
Get Export (QleGetExp) API . . . . . . . . . . . . . 65-30 Start Preprocessor (QbnStartPreProcessor) API . . . 65-92
List ILE Program Information (QBNLPGMI) API . . . 65-31 Store Program Associated Space (QCLSPGAS) API 65-93
List Module Information (QBNLMODI) API . . . . . . 65-39

Part 27. Registration Facility APIs

| Chapter 66. Registration Facility APIs . . . . . . 66-1

Part 28. Remote Procedure Call APIs

| Chapter 67. Remote Procedure Call APIs . . . . 67-1

Part 29. Security APIs

Chapter 68. Security APIs . . . . . . . . . . . . . 68-1 Retrieve Users Authorized to an Object (QSYRTVUA)
Security APIs—Introduction . . . . . . . . . . . . . 68-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 68-49
Change Dedicated Service Tools Profiles Set Encrypted User Password (QSYSUPWD) API . . 68-52
(QSYCHGDS) API . . . . . . . . . . . . . . . . . 68-2 Set Job User Identity (QWTSJUID) API . . . . . . . 68-53
Change Previous Sign-On Date (QSYCHGPR) API . 68-2 Set Profile (QWTSETP) API . . . . . . . . . . . . . 68-54
Change User Password (QSYCHGPW) API . . . . . 68-3
Change User Profile UID or GID (QSYCHGID) API . 68-4 Chapter 69. Security Exit Programs . . . . . . . . 69-1
Check User Authority to an Object (QSYCUSRA) API 68-5 Security Exit Programs—Introduction . . . . . . . . 69-1
Check User Special Authorities (QSYCUSRS) API . 68-7 Change User Profile Exit Program . . . . . . . . . . 69-1
Convert Authority Values to MI Value (QSYCVTA) API 68-8 Create User Profile Exit Program . . . . . . . . . . 69-1
Get Profile Handle (QSYGETPH) API . . . . . . . . 68-9 Delete User Profile Exit Program . . . . . . . . . . . 69-2
List Authorized Users (QSYLAUTU) API . . . . . . . 68-10 Restore User Profile Exit Program . . . . . . . . . . 69-3
List Objects Secured by Authorization List
(QSYLATLO) API . . . . . . . . . . . . . . . . . . 68-12 Chapter 70. Digital Certificate Management APIs 70-1
List Objects That Adopt Owner Authority (QSYLOBJP) | Digital Certificate Management APIs and Exit
API . . . . . . . . . . . . . . . . . . . . . . . . . 68-16 | Programs—Introduction . . . . . . . . . . . . . . . 70-1
List Objects User Is Authorized to, Owns, or Is Add User Certificate (QSYADDUC,
Primary Group of (QSYLOBJA) API . . . . . . . . 68-18 QsyAddUserCertificate) API . . . . . . . . . . . . 70-1
List Users Authorized to Object (QSYLUSRA) API . 68-23 Add Validation List Certificate (QSYADDVC,
Open List of Authorized Users (QGYOLAUS) API . . 68-25 QsyAddVldlCertificate) API . . . . . . . . . . . . . 70-2
QwtClearJuid()—Clear Job User Identity . . . . . . . 68-28 Check Validation List Certificate
QwtSetJuid()—Set Job User Identity . . . . . . . . . 68-28 (QSYCHKVC,QsyCheckVldlCertificate) API . . . . 70-3
Release Profile Handle (QSYRLSPH) API . . . . . . 68-29 | Deregister Application for Certificate Use (QSYDRGAP,
| Remove Profile Tokens (QSYRMVPT) API . . . . . 68-29 | QsyDeregisterAppForCertUse) API . . . . . . . . . 70-4
Retrieve Authorized Users (QSYRAUTU) API . . . . 68-30 Find Certificate User
Retrieve Encrypted User Password (QSYRUPWD) (QSYFNDCU,QsyFindCertificateUser) API . . . . . 70-5
API . . . . . . . . . . . . . . . . . . . . . . . . . 68-33 List User Certificates (QSYLSTUC,
Retrieve Objects Secured by Authorization List QsyListUserCertificates) API . . . . . . . . . . . . 70-5
(QGYRATLO) API . . . . . . . . . . . . . . . . . . 68-34 List Validation List Certificates
Retrieve User Authority to Object (QSYRUSRA) API 68-38 (QSYLSTVC,QsyListVldlCertificates) API . . . . . . 70-11
Retrieve User Information (QSYRUSRI) API . . . . . 68-41 Open List of User Certificates (QSYOLUC) API . . . 70-13

Contents xiii
 Parse Certificate (QSYPARSC, QsyParseCertificate) Change Function Usage Information (QSYCHFUI,
API . . . . . . . . . . . . . . . . . . . . . . . . . 70-18 QsyChangeFunctionUsageInfo) API . . . . . . . . 72-1
| Register Application for Certificate Use (QSYRGAP, Check User Function Usage (QSYCKUFU,
| QsyRegisterAppForCertUse) API . . . . . . . . . . 70-18 QsyCheckUserFunctionUsage) API . . . . . . . . . 72-2
Remove User Certificate (QSYRMVUC, Deregister Function (QSYDRGFN,
QsyRemoveUserCertificate) API . . . . . . . . . . 70-21 QsyDeregisterFunction) API . . . . . . . . . . . . 72-3
Remove Validation List Certificate (QSYRMVVC, Register Function (QSYRGFN, QsyRegisterFunction)
QsyRemoveVldlCertificate) API . . . . . . . . . . . 70-22 API . . . . . . . . . . . . . . . . . . . . . . . . . 72-4
| Deregister Application for Certificate Use Exit Retrieve Function Information (QSYRTVFI,
| Program . . . . . . . . . . . . . . . . . . . . . . . 70-23 QsyRetrieveFunctionInformation) API . . . . . . . . 72-7
| Update Certificate Usage Exit Program . . . . . . . 70-24 Retrieve Function Usage Information (QSYRTFUI,
QsyRetrieveFunctionUsageInfo) API . . . . . . . . 72-11
Chapter 71. Network Security APIs . . . . . . . . 71-1 Retrieve User Function Information (QSYRTUFI,
Network Security APIs—Introduction . . . . . . . . . 71-1 QsyRetrieveUserFunctionInfo) API . . . . . . . . . 72-13
Add NetWare Authentication Entry (QfpzAddNtwAutE)
API . . . . . . . . . . . . . . . . . . . . . . . . . 71-1 Chapter 73. Validation List APIs . . . . . . . . . . 73-1
Add Server Authentication Entry (QsyAddServerEntry) Validation List APIs—Introduction . . . . . . . . . . 73-1
API . . . . . . . . . . . . . . . . . . . . . . . . . 71-4 Add Validation List Entry (QSYADVLE) API . . . . . 73-1
Change NetWare Authentication Entry Change Validation List Entry (QSYCHVLE) API . . . 73-3
(QfpzChgNtwAutE) API . . . . . . . . . . . . . . . 71-4 Find Validation List Entry (QSYFDVLE) API . . . . . 73-6
Change Server Authentication Entry Open List of Validation List Entries (QSYOLVLE) API 73-8
(QsyChangeServerEntry) API . . . . . . . . . . . . 71-7 QsyAddValidationLstEntry()—Add Validation List Entry
End NetWare Connection (QfpzEndNtwCnn) API . . 71-8 API . . . . . . . . . . . . . . . . . . . . . . . . . 73-11
List NetWare Authentication Entries (QfpzListNtwAutE) QsyChangeValidationLstEntry()—Change Validation
API . . . . . . . . . . . . . . . . . . . . . . . . . 71-9 List Entry API . . . . . . . . . . . . . . . . . . . . 73-13
Remove NetWare Authentication Entry QsyFindFirstValidationLstEntry()—Find First Validation
(QfpzRmvNtwAutE) API . . . . . . . . . . . . . . . 71-12 List Entry API . . . . . . . . . . . . . . . . . . . . 73-16
Remove Server Authentication Entry QsyFindNextValidationLstEntry()—Find Next
(QsyRemoveServerEntry) API . . . . . . . . . . . 71-13 Validation List Entry API . . . . . . . . . . . . . . 73-18
Retrieve Server Authentication Entries (QSYRTVSE, QsyFindValidationLstEntry()—Find Validation List
QsyRetrieveServerEntries) API . . . . . . . . . . . 71-14 Entry API . . . . . . . . . . . . . . . . . . . . . . 73-20
Start NetWare Connection (QfpzStrNtwCnn) API . . 71-16 QsyFindValidationLstEntryAttrs()—Find Validation List
Verify NetWare Authentication Entry Entry Attributes API . . . . . . . . . . . . . . . . . 73-22
(QfpzVfyNtwAutE) API . . . . . . . . . . . . . . . 71-19 QsyRemoveValidationLstEntry()—Remove Validation
List Entry API . . . . . . . . . . . . . . . . . . . . 73-25
Chapter 72. User Function Registration APIs . . 72-1 QsyVerifyValidationLstEntry()—Verify Validation List
User Function Registration APIs—Introduction . . . . 72-1 Entry API . . . . . . . . . . . . . . . . . . . . . . 73-26
Remove Validation List Entry (QSYRMVLE) API . . 73-27

Part 30. Server Support APIs

| Chapter 74. Server Support APIs . . . . . . . . . 74-1

Part 31. Software Product APIs

| Chapter 75. Software Product APIs . . . . . . . . 75-1

Part 32. UNIX-Type APIs

Chapter 76. Environment Variable APIs . . . . . 76-1 | Qp0zGetAllSysEnv()—Get All System-Level
Environment Variable APIs—Introduction . . . . . . 76-1 | Environment Variables . . . . . . . . . . . . . . . 76-6
getenv()—Get Value of Environment Variable . . . . 76-1 Qp0zGetEnv()—Get Value of Environment Variable
putenv()—Change or Add Environment Variable . . . 76-2 (Extended) . . . . . . . . . . . . . . . . . . . . . 76-8
Qp0zDltEnv()—Delete an Environment Variable . . . 76-4 | Qp0zGetSysEnv()—Get Value of System-Level
| Qp0zDltSysEnv()—Delete a System-Level Environment | Environment Variable . . . . . . . . . . . . . . . . 76-9
| Variable . . . . . . . . . . . . . . . . . . . . . . . 76-5 Qp0zInitEnv()—Initialize Environment for Variables . 76-10

xiv AS/400 System API Reference V4R4

 Qp0zPutEnv()—Change or Add Environment Variable | lseek64()—Set File Read/Write Offset (Large File
(Extended) . . . . . . . . . . . . . . . . . . . . . 76-10 | Enabled) . . . . . . . . . . . . . . . . . . . . . . . 77-82
| Qp0zPutSysEnv()—Change or Add a System-Level lstat()—Get File or Link Information . . . . . . . . . 77-82
| Environment Variable . . . . . . . . . . . . . . . . 76-12 | lstat64()—Get File or Link Information (Large File
| Enabled) . . . . . . . . . . . . . . . . . . . . . . . 77-86
Chapter 77. Integrated File System APIs . . . . . 77-1 mkdir()—Make Directory . . . . . . . . . . . . . . . 77-87
Integrated File System APIs—Introduction . . . . . . 77-1 open()—Open File . . . . . . . . . . . . . . . . . . 77-91
Integrated File System Exit Program—Introduction . 77-2 | open64()—Open File (Large File Enabled) . . . . . 77-100
access()—Determine File Accessibility . . . . . . . . 77-2 opendir()—Open Directory . . . . . . . . . . . . . 77-100
chdir()—Change Current Directory . . . . . . . . . . 77-6 pathconf()—Get Configurable Path Name Variables 77-103
chmod()—Change File Authorizations . . . . . . . . 77-8 Perform File System Operation (QP0LFLOP) API . 77-107
chown()—Change Owner and Group of File . . . . . 77-11 Qp0lCvtPathToQSYSObjName()— Resolve
close()—Close File or Socket Descriptor . . . . . . . 77-15 Integrated File System Path Name into QSYS
closedir()—Close Directory . . . . . . . . . . . . . . 77-17 Object Name . . . . . . . . . . . . . . . . . . . 77-110
creat()—Create or Rewrite File . . . . . . . . . . . . 77-19 Qp0lGetAttr()—Get Attributes . . . . . . . . . . . 77-113
| creat64()—Create or Rewrite a File (Large File Qp0lGetPathFromFileID()—Get Path Name of Object
| Enabled) . . . . . . . . . . . . . . . . . . . . . . . 77-24 from Its File ID . . . . . . . . . . . . . . . . . . 77-123
DosSetFileLocks()—Lock and Unlock a Byte Range of | Qp0lOpen()—Open File . . . . . . . . . . . . . . 77-125
an Open File . . . . . . . . . . . . . . . . . . . . 77-24 Qp0lProcessSubtree()—Process a Path Name . . 77-126
| DosSetFileLocks64()—Lock and Unlock a Byte Range Qp0lRenameKeep()—Rename File or Directory,
| of an Open File (Large File Enabled) . . . . . . . . 77-27 Keep “new” If It Exists . . . . . . . . . . . . . . 77-135
DosSetRelMaxFH()—Change Maximum Number of Qp0lRenameUnlink()—Rename File or Directory,
File Descriptors . . . . . . . . . . . . . . . . . . . 77-27 Unlink “new” If It Exists . . . . . . . . . . . . . . 77-140
dup()—Duplicate Open File Descriptor . . . . . . . . 77-29 | Qp0lSetAttr()—Set Attributes . . . . . . . . . . . . 77-144
dup2()—Duplicate Open File Descriptor to Another | Qp0lUnlink()—Remove Link to File . . . . . . . . . 77-151
Descriptor . . . . . . . . . . . . . . . . . . . . . . 77-30 read()—Read from Descriptor . . . . . . . . . . . 77-151
fchmod()—Change File Authorizations by Descriptor 77-32 readdir()—Read Directory Entry . . . . . . . . . . 77-155
fchown()—Change Owner and Group of File by readdir_r()—Read Directory Entry . . . . . . . . . 77-158
Descriptor . . . . . . . . . . . . . . . . . . . . . . 77-35 readlink()—Read Value of Symbolic Link . . . . . 77-161
fcntl()—Perform File Control Command . . . . . . . 77-39 readv()—Read from Descriptor Using Multiple
fpathconf()—Get Configurable Path Name Variables Buffers . . . . . . . . . . . . . . . . . . . . . . . 77-164
by Descriptor . . . . . . . . . . . . . . . . . . . . 77-45 rename()—Rename File or Directory . . . . . . . . 77-167
fstat()—Get File Information by Descriptor . . . . . . 77-48 Retrieve Network File System Export Entries
| fstat64()—Get File Information by Descriptor (Large (QZNFRTVE) API . . . . . . . . . . . . . . . . . 77-168
| File Enabled) . . . . . . . . . . . . . . . . . . . . 77-51 rewinddir()—Reset Directory Stream to Beginning . 77-171
fstatvfs()—Get File System Information by Descriptor 77-51 rmdir()—Remove Directory . . . . . . . . . . . . . 77-172
| fstatvfs64()—Get File System Information by stat()—Get File Information . . . . . . . . . . . . . 77-176
| Descriptor (64-Bit Enabled) . . . . . . . . . . . . . 77-55 | stat64()—Get File Information (Large File Enabled) 77-180
fsync()—Synchronize Changes to File . . . . . . . . 77-55 statvfs()—Get File System Information . . . . . . . 77-181
ftruncate()—Truncate File . . . . . . . . . . . . . . 77-57 | statvfs64()—Get File System Information (64-Bit
| ftruncate64()—Truncate File (Large File Enabled) . . 77-59 | Enabled) . . . . . . . . . . . . . . . . . . . . . . 77-185
getcwd()—Get Current Directory . . . . . . . . . . . 77-60 symlink()—Make Symbolic Link . . . . . . . . . . 77-187
getegid()—Get Effective Group ID . . . . . . . . . . 77-63 sysconf()—Get System Configuration Variables . . 77-190
geteuid()—Get Effective User ID . . . . . . . . . . . 77-63 umask()—Set Authorization Mask for Job . . . . . 77-191
getgid()—Get Real Group ID . . . . . . . . . . . . . 77-64 unlink()—Remove Link to File . . . . . . . . . . . 77-192
getgrgid()—Get Group Information Using Group ID . 77-65 utime()—Set File Access and Modification Times . 77-195
| getgrgid_r()—Get Group Information Using Group ID 77-65 write()—Write to Descriptor . . . . . . . . . . . . . 77-198
getgrnam()—Get Group Information Using Group writev()—Write to Descriptor Using Multiple Buffers 77-203
Name . . . . . . . . . . . . . . . . . . . . . . . . 77-67 Integrated File System APIs—Time Stamp Updates 77-206
| getgrnam_r()—Get Group Information Using Group Process a Path Name Exit Program . . . . . . . . 77-207
| Name . . . . . . . . . . . . . . . . . . . . . . . . 77-67
getgroups()—Get Group IDs . . . . . . . . . . . . . 77-68 Chapter 78. Interprocess Communication APIs . 78-1
getpwnam()—Get User Information for User Name . 77-69 Interprocess Communication APIs—Introduction . . . 78-1
| getpwnam_r()—Get User Information for User Name 77-70 Identifier Based Services . . . . . . . . . . . . . . . 78-1
getpwuid()—Get User Information for User ID . . . . 77-72 | Pointer Based Services . . . . . . . . . . . . . . . . 78-5
| getpwuid_r()—Get User Information for User ID . . . 77-72 Interprocess Communication APIs—Summary . . . . 78-6
getuid()—Get Real User ID . . . . . . . . . . . . . . 77-74 Delete Interprocess Communication Objects
ioctl()—Perform File I/O Control Request . . . . . . 77-74 (QP0ZDIPC) API . . . . . . . . . . . . . . . . . . 78-7
link()—Create Link to File . . . . . . . . . . . . . . 77-76 ftok()—Generate IPC Key from File Name . . . . . . 78-8
lseek()—Set File Read/Write Offset . . . . . . . . . 77-80 msgctl()–Perform Message Control Operations . . . 78-10

Contents xv
 msgget()–Get Message Queue . . . . . . . . . . . . 78-12 sigfillset()—Initialize and Fill Signal Set . . . . . . . 80-23
msgrcv()–Receive Message Operation . . . . . . . . 78-14 sigismember()—Test for Signal in Signal Set . . . . 80-24
msgsnd()–Send Message Operation . . . . . . . . . 78-16 siglongjmp()—Perform Nonlocal Goto with Signal
Open List of Interprocess Communication Objects Handling . . . . . . . . . . . . . . . . . . . . . . . 80-25
(QP0ZOLIP) API . . . . . . . . . . . . . . . . . . 78-18 sigpending()—Examine Pending Signals . . . . . . . 80-27
Open List of Semaphores (QP0ZOLSM) API . . . . 78-24 sigprocmask()—Examine and Change Blocked
Retrieve an Interprocess Communication Object Signals . . . . . . . . . . . . . . . . . . . . . . . 80-28
(QP0ZRIPC) API . . . . . . . . . . . . . . . . . . 78-26 sigsetjmp()—Set Jump Point for Nonlocal Goto . . . 80-30
| sem_close()–Close Named Semaphore . . . . . . . 78-31 sigsuspend()—Wait for Signal . . . . . . . . . . . . 80-31
| sem_destroy()–Destroy Unnamed Semaphore . . . . 78-32 sigtimedwait()—Synchronously Accept a Signal for
| sem_getvalue()–Get Semaphore Value . . . . . . . 78-33 Interval of Time . . . . . . . . . . . . . . . . . . . 80-33
| sem_init()–Initialize Unnamed Semaphore . . . . . . 78-34 sigwait()—Synchronously Accept a Signal . . . . . . 80-35
| sem_init_np()–Initialize Unnamed Semaphore with sigwaitinfo()—Synchronously Accept a Signal and
| Maximum Value . . . . . . . . . . . . . . . . . . . 78-35 Signal Data . . . . . . . . . . . . . . . . . . . . . 80-36
| sem_open()–Open Named Semaphore . . . . . . . 78-36 sleep()—Suspend Processing for Interval of Time . . 80-38
| sem_open_np()–Open Named Semaphore with usleep()—Suspend Processing for Interval of Time . 80-39
| Maximum Value . . . . . . . . . . . . . . . . . . . 78-38
| sem_post()–Post to Semaphore . . . . . . . . . . . 78-40 Chapter 81. Simple Network Management Protocol
| sem_post_np()–Post Value to Semaphore . . . . . . 78-41 (SNMP) Subagent APIs . . . . . . . . . . . . . . 81-1
| sem_trywait()–Try to Decrement Semaphore . . . . 78-42 Simple Network Management Protocol (SNMP)
| sem_unlink()–Unlink Named Semaphore . . . . . . . 78-43 APIs—Introduction . . . . . . . . . . . . . . . . . 81-1
| sem_wait()–Wait for Semaphore . . . . . . . . . . . 78-44 SNMP Subagent APIs—Introduction . . . . . . . . . 81-1
| sem_wait_np()–Wait for Semaphore with Timeout . . 78-45 connectSNMP()—Establish Connection with SNMP
semctl()–Perform Semaphore Control Operations . . 78-46 Agent . . . . . . . . . . . . . . . . . . . . . . . . 81-3
semget()–Get Semaphore Set with Key . . . . . . . 78-49 debugDPI()—Set DPI Packet Trace . . . . . . . . . 81-4
semop()–Perform Semaphore Operations on disconnectSNMP()—End Connection with SNMP Agent 81-5
Semaphore Set . . . . . . . . . . . . . . . . . . . 78-51 DPI_PACKET_LEN()—Get Length of DPI Packet . . 81-6
shmat()–Attach Shared Memory Segment to Current fDPIparse()—Free Storage from DPI Packet Parse . 81-7
Process . . . . . . . . . . . . . . . . . . . . . . . 78-53 fDPIset()—Free Storage from DPI Set Packet . . . . 81-7
shmctl()–Perform Shared Memory Control Operations 78-54 mkDPIAreYouThere()—Make a DPI AreYouThere
shmdt()–Detach Shared Memory Segment from Packet . . . . . . . . . . . . . . . . . . . . . . . . 81-8
Calling Process . . . . . . . . . . . . . . . . . . . 78-56 mkDPIclose()—Make a DPI Close Packet . . . . . . 81-8
shmget()–Get ID of Shared Memory Segment with mkDPIopen()—Make a DPI Open Packet . . . . . . 81-9
Key . . . . . . . . . . . . . . . . . . . . . . . . . 78-57 mkDPIregister()—Make a DPI Register Packet . . . 81-10
mkDPIresponse()—Make a DPI Response Packet . 81-12
Chapter 79. Problem Determination APIs . . . . . 79-1 mkDPIset()—Make a DPI Set Packet . . . . . . . . 81-13
Problem Determination APIs—Introduction . . . . . . 79-1 mkDPItrap()—Make a DPI Trap Packet . . . . . . . 81-14
Qp0zDump()—Dump Formatted Storage Trace Data 79-1 mkDPIunregister()—Make a DPI Unregister Packet . 81-15
Qp0zDumpStack()—Dump Formatted Stack Trace Data 79-3 pDPIpacket()—Parse a DPI Packet . . . . . . . . . 81-16
Qp0zDumpTargetStack()—Dump Formatted Stack receiveDPIpacket()—Receive a DPI Packet from the
Trace Data of the Target Thread . . . . . . . . . . 79-5 SNMP Agent . . . . . . . . . . . . . . . . . . . . 81-16
Qp0zLprintf()—Print Formatted Job Log Data . . . . 79-7 sendDPIpacket()—Send a DPI Packet to the SNMP
Qp0zUprintf()—Print Formatted User Trace Data . . 79-9 Agent . . . . . . . . . . . . . . . . . . . . . . . . 81-17
waitDPIpacket()—Wait for a DPI Packet . . . . . . . 81-18
Chapter 80. Signal APIs . . . . . . . . . . . . . . 80-1
Signal Concepts . . . . . . . . . . . . . . . . . . . 80-1 Chapter 82. Simple Network Management Protocol
OS/400 Signal Management . . . . . . . . . . . . . 80-1 (SNMP) Manager APIs . . . . . . . . . . . . . . . 82-1
Differences from Signals on UNIX Systems . . . . . 80-3 Simple Network Management Protocol (SNMP)
Signal APIs—Summary . . . . . . . . . . . . . . . . 80-4 Manager APIs—Introduction . . . . . . . . . . . . 82-1
alarm()—Set Schedule for Alarm Signal . . . . . . . 80-4 snmpGet()—Retrieve MIB Objects . . . . . . . . . . 82-1
getitimer()—Get Value for Interval Timer . . . . . . . 80-5 snmpGetnext()—Retrieve Next MIB Object . . . . . 82-3
kill()—Send Signal to Process or Group of Processes 80-7 snmpSet()—Set MIB Objects . . . . . . . . . . . . . 82-6
pause()—Suspend Process Until Signal Received . . 80-9 SNMP Trap Support . . . . . . . . . . . . . . . . . 82-8
Qp0sDisableSignals()—Disable Process for Signals . 80-10 Using SNMP Manager APIs—Example . . . . . . . 82-10
Qp0sEnableSignals()—Enable Process for Signals . 80-12
setitimer()—Set Value for Interval Timer . . . . . . . 80-13 Chapter 83. Sockets APIs . . . . . . . . . . . . . 83-1
sigaction()—Examine and Change Signal Action . . 80-15 Sockets APIs—Introduction . . . . . . . . . . . . . . 83-1
sigaddset()—Add Signal to Signal Set . . . . . . . . 80-20 Sockets System Functions—Summary . . . . . . . . 83-1
sigdelset()—Delete Signal from Signal Set . . . . . . 80-21 accept()—Wait for Connection Request and Make
sigemptyset()—Initialize and Empty Signal Set . . . 80-22 Connection . . . . . . . . . . . . . . . . . . . . . 83-1

xvi AS/400 System API Reference V4R4

 accept_and_recv()—Wait for Connection Request and gethostbyaddr_r()—Get Host Information for IP
Receive the First Message That Was Sent . . . . . 83-3 Address . . . . . . . . . . . . . . . . . . . . . . . 83-94
bind()—Set Local Address for Socket . . . . . . . . 83-6 gethostbyname()—Get Host Information for Host
close()—Close File or Socket Descriptor . . . . . . . 83-8 Name . . . . . . . . . . . . . . . . . . . . . . . . 83-96
connect()—Establish Connection or Destination gethostbyname_r()—Get Host Information for Host
Address . . . . . . . . . . . . . . . . . . . . . . . 83-11 Name . . . . . . . . . . . . . . . . . . . . . . . . 83-97
fcntl()—Retrieve or Change Descriptor Attributes . . 83-15 gethostent()—Get Next Entry from Host Database . 83-99
fstat()—Retrieve Status Information about a Descriptor 83-16 gethostent_r()—Get Next Entry from Host Database 83-100
getdomainname()—Retrieve Domain Name . . . . . 83-18 _getlong()—Get Long Byte Quantities . . . . . . . 83-101
gethostid()—Retrieve Host ID Address . . . . . . . . 83-19 getnetbyaddr()—Get Network Information for IP
gethostname()—Retrieve Host Name . . . . . . . . 83-19 Address . . . . . . . . . . . . . . . . . . . . . . 83-101
getpeername()—Retrieve Destination Address of getnetbyaddr_r()—Get Network Information for IP
Socket . . . . . . . . . . . . . . . . . . . . . . . . 83-20 Address . . . . . . . . . . . . . . . . . . . . . . 83-102
getsockname()—Retrieve Local Address of Socket . 83-21 getnetbyname()—Get Network Information for
getsockopt()—Retrieve Information about Socket Domain Name . . . . . . . . . . . . . . . . . . . 83-103
Options . . . . . . . . . . . . . . . . . . . . . . . 83-22 getnetbyname_r()—Get Network Information for
givedescriptor()—Pass Descriptor Access to Another Domain Name . . . . . . . . . . . . . . . . . . . 83-103
Job . . . . . . . . . . . . . . . . . . . . . . . . . 83-29 getnetent()—Get Next Entry from Network Database 83-104
ioctl()—Change Descriptor Attributes . . . . . . . . . 83-30 getnetent_r()—Get Next Entry from Network
listen()—Invite Incoming Connections Requests . . . 83-36 Database . . . . . . . . . . . . . . . . . . . . . 83-105
Rbind()—Set Remote Address for Socket . . . . . . 83-38 getprotobyname()—Get Protocol Information for
read()—Read from Descriptor . . . . . . . . . . . . 83-39 Protocol Name . . . . . . . . . . . . . . . . . . 83-106
readv()—Read from Descriptor Using Multiple Buffers 83-43 getprotobyname_r()—Get Protocol Information for
recv()—Receive Data . . . . . . . . . . . . . . . . . 83-46 Protocol Name . . . . . . . . . . . . . . . . . . 83-107
recvfrom()—Receive Data . . . . . . . . . . . . . . 83-48 getprotobynumber()—Get Protocol Information for
recvmsg()—Receive Data or Descriptors or Both . . 83-50 Protocol Number . . . . . . . . . . . . . . . . . 83-107
select()—Wait for Events on Multiple Sockets . . . . 83-53 getprotobynumber_r()—Get Protocol Information for
send()—Send Data . . . . . . . . . . . . . . . . . . 83-54 Protocol Number . . . . . . . . . . . . . . . . . 83-108
send_file()—Send a File over a Socket Connection . 83-56 getprotoent()—Get Next Entry from Protocol
| send_file64()—Send a File over a Socket Connection 83-59 Database . . . . . . . . . . . . . . . . . . . . . 83-109
sendmsg()—Send Data or Descriptors or Both . . . 83-60 getprotoent_r()—Get Next Entry from Protocol
sendto()—Send Data . . . . . . . . . . . . . . . . . 83-63 Database . . . . . . . . . . . . . . . . . . . . . 83-110
setdomainname()—Set Domain Name . . . . . . . . 83-65 getservbyname()—Get Port Number for Service
sethostid()—Set Host ID Address . . . . . . . . . . 83-66 Name . . . . . . . . . . . . . . . . . . . . . . . 83-111
sethostname()—Set Host Name . . . . . . . . . . . 83-66 getservbyname_r()—Get Port Number for Service
setsockopt()—Set Socket Options . . . . . . . . . . 83-67 Name . . . . . . . . . . . . . . . . . . . . . . . 83-111
shutdown()—End Receiving and/or Sending of Data getservbyport()—Get Service Name for Port Number 83-112
on Socket . . . . . . . . . . . . . . . . . . . . . . 83-74 getservbyport_r()—Get Service Name for Port
socket()—Create Socket . . . . . . . . . . . . . . . 83-74 Number . . . . . . . . . . . . . . . . . . . . . . 83-113
socketpair()—Create a Pair of Sockets . . . . . . . . 83-76 getservent()—Get Next Entry from Service Database 83-114
takedescriptor()—Receive Socket Access from getservent_r()—Get Next Entry from Service
Another Job . . . . . . . . . . . . . . . . . . . . . 83-77 Database . . . . . . . . . . . . . . . . . . . . . 83-115
write()—Write to Descriptor . . . . . . . . . . . . . . 83-78 _getshort()—Get Short Byte Quantities . . . . . . 83-116
writev()—Write to Descriptor Using Multiple Buffers . 83-82 htonl()—Convert Long Integer to Network Byte Order 83-116
Sockets Network Functions (Routines)—Summary . 83-85 htons()—Convert Short Integer to Network Byte
dn_comp()—Compress Domain Name . . . . . . . . 83-87 Order . . . . . . . . . . . . . . . . . . . . . . . 83-116
dn_expand()—Expand Domain Name . . . . . . . . 83-87 inet_addr()—Translate Full Address to 32-bit IP
dn_find()—Search for Compressed Domain Name . 83-88 Address . . . . . . . . . . . . . . . . . . . . . . 83-117
dn_skipname()—Skip over Compressed Domain inet_lnaof()—Separate Local Portion of IP Address 83-118
Name . . . . . . . . . . . . . . . . . . . . . . . . 83-89 inet_makeaddr()—Combine Network Portion and
endhostent()—Close Host Database . . . . . . . . . 83-89 Host Portion to Make IP Address . . . . . . . . . 83-118
endhostent_r()—Close Host Database . . . . . . . . 83-90 inet_netof()—Separate Network Portion of IP
endnetent()—Close Network Database . . . . . . . . 83-90 Address . . . . . . . . . . . . . . . . . . . . . . 83-118
endnetent_r()—Close Network Database . . . . . . 83-91 inet_network()—Translate Network Portion of
endprotoent()—Close Protocol Database . . . . . . 83-91 Address to 32-bit IP Address . . . . . . . . . . . 83-119
endprotoent_r()—Close Protocol Database . . . . . 83-91 inet_ntoa()—Translate IP Address to Dotted Decimal
endservent()—Close Service Database . . . . . . . 83-92 Format . . . . . . . . . . . . . . . . . . . . . . . 83-119
endservent_r()—Close Service Database . . . . . . 83-92 inet_ntoa_r()—Translate IP Address to Dotted
gethostbyaddr()—Get Host Information for IP Address 83-93 Decimal Format . . . . . . . . . . . . . . . . . . 83-119

Contents xvii
 ns_addr()—Translate Network Services Address to getpid()—Get Process ID . . . . . . . . . . . . . . . 86-3
12-byte Address . . . . . . . . . . . . . . . . . . 83-120 getppid()—Get Process ID of Parent Process . . . . 86-3
ns_ntoa()—Translate Network Services Address pipe()—Create Interprocess Channel . . . . . . . . . 86-4
from 12-byte Address . . . . . . . . . . . . . . . 83-121 Qp0wChkChld()—Check Status for Child Processes 86-5
ns_ntoa_r() — Translate Network Services Address Qp0wChkPgrp()—Check Status for Process Group . 86-6
from 12-byte Address . . . . . . . . . . . . . . . 83-121 Qp0wChkPid()—Check Status for Process ID . . . . 86-8
ntohl()—Convert Long Integer to Host Byte Order . 83-122 Qp0wGetJobID()—Get Qualified Job Name and ID for
ntohs()—Convert Short Integer to Host Byte Order 83-122 Process ID . . . . . . . . . . . . . . . . . . . . . 86-9
_putlong()—Put Long Byte Quantities . . . . . . . 83-123 Qp0wGetPgrp()—Get Process Group ID . . . . . . . 86-10
_putshort()—Put Short Byte Quantities . . . . . . . 83-123 Qp0wGetPid()—Get Process ID . . . . . . . . . . . 86-11
res_close()—Close Socket and Reset _res Structure 83-124 Qp0wGetPidNoInit()—Get Process ID without
res_init()—Initialize _res Structure . . . . . . . . . 83-124 Initializing for Signals . . . . . . . . . . . . . . . . 86-11
res_mkquery()—Place Domain Query in Buffer . . 83-125 Qp0wGetPPid()—Get Process ID of Parent Process 86-12
res_query()—Send Domain Query . . . . . . . . . 83-126 Qp0zEndTerminal()—End a Generic Terminal . . . . 86-12
res_search()—Search for Domain Name . . . . . . 83-127 Qp0zGetTerminalPid()—Get Process ID for a Generic
res_send()—Send Buffered Domain Query . . . . 83-128 Terminal . . . . . . . . . . . . . . . . . . . . . . . 86-13
res_xlate()—Translate DNS Packets . . . . . . . . 83-129 Qp0zIsATerminal()—Determine Whether Descriptor Is
sethostent()—Open Host Database . . . . . . . . 83-130 Connected to a Generic Terminal . . . . . . . . . . 86-14
sethostent_r()—Open Host Database . . . . . . . 83-131 Qp0zRunTerminal()—Run a Generic Terminal . . . . 86-14
setnetent()—Open Network Database . . . . . . . 83-132 Qp0zStartTerminal()—Start a Generic Terminal . . . 86-16
setnetent_r()—Open Network Database . . . . . . 83-132 Qp0zSystem()—Run a CL Command . . . . . . . . 86-18
setprotoent()—Open Protocol Database . . . . . . 83-133 setpgid()—Set Process Group ID for Job Control . . 86-19
setprotoent_r()—Open Protocol Database . . . . . 83-133 spawn()—Spawn Process . . . . . . . . . . . . . . 86-19
setservent()—Open Service Database . . . . . . . 83-134 spawnp()—Spawn Process with Path . . . . . . . . 86-26
setservent_r()—Open Service Database . . . . . . 83-134 wait()—Wait for Child Process to End . . . . . . . . 86-33
Debugging IP over SNA Configurations . . . . . . 83-135 waitpid()—Wait for Specific Child Process . . . . . . 86-35
About Shell Scripts . . . . . . . . . . . . . . . . . . 86-36
Chapter 84. Secure Sockets Layer (SSL) APIs . . 84-1
Secure Sockets Layer (SSL) APIs—Introduction . . . 84-1 Chapter 87. XA APIs . . . . . . . . . . . . . . . . 87-1
SSL_Create()—Enable SSL Support for the Specified XA APIs—Introduction . . . . . . . . . . . . . . . . 87-1
Socket Descriptor . . . . . . . . . . . . . . . . . . 84-2 Restrictions . . . . . . . . . . . . . . . . . . . . . . 87-2
SSL_Destroy()—End SSL Support for the Specified db2xa_close()—Close an XA Resource Manager . . 87-2
SSL Session . . . . . . . . . . . . . . . . . . . . 84-3 db2xa_commit()—Commit an XA Transaction Branch 87-3
SSL_Handshake()—Initiate the SSL Handshake db2xa_complete()—Test Completion of Asynchronous
Protocol . . . . . . . . . . . . . . . . . . . . . . . 84-5 XA Request . . . . . . . . . . . . . . . . . . . . . 87-5
SSL_Init()—Initialize the Current Job for SSL . . . . 84-7 db2xa_end()—End Work on an XA Transaction Branch 87-5
| SSL_Init_Application()—Initialize the Current Job for db2xa_forget()—Forget an XA Transaction Branch . 87-7
| SSL Processing Based on the Application Identifier 84-9 db2xa_open()—Open an XA Resource Manager . . 87-8
SSL_Read()—Receive Data from an SSL-Enabled db2xa_prepare()—Prepare to Commit an XA
Socket Descriptor . . . . . . . . . . . . . . . . . . 84-11 Transaction Branch . . . . . . . . . . . . . . . . . 87-10
SSL_Write()—Write Data to an SSL-Enabled Socket db2xa_recover()—Recover XA Transactions . . . . . 87-11
Descriptor . . . . . . . . . . . . . . . . . . . . . . 84-13 db2xa_rollback()—Roll Back an XA Transaction . . . 87-12
db2xa_start()—Start an XA Transaction . . . . . . . 87-13
Chapter 85. Software Clock APIs . . . . . . . . . 85-1 ax_reg()—Exit Program to Dynamically Register an
Software Clock APIs—Introduction . . . . . . . . . . 85-1 XA Resource Manager . . . . . . . . . . . . . . . 87-14
adjtime()–Adjust Software Clock . . . . . . . . . . . 85-1 ax_unreg()—Exit Program to Dynamically Unregister
gettimeofday()–Get Current Software Clock Time . . 85-2 an XA Resource Manager . . . . . . . . . . . . . 87-15
settimeofday()–Set Current Software Clock Time . . 85-3
Chapter 88. Header Files for UNIX-Type Functions 88-1
Chapter 86. Process-Related APIs . . . . . . . . 86-1
Process-Related APIs—Introduction . . . . . . . . . 86-1 | Chapter 89. Errno Values for UNIX-Type Functions 89-1
getopt()—Get Flag Letters from Argument Vector . . 86-1 | Errno Values for UNIX-Type Functions—Introduction 89-1
getpgrp()—Get Process Group ID . . . . . . . . . . 86-2

Part 33. User Interface APIs

| Chapter 90. User Interface APIs . . . . . . . . . . 90-1

xviii AS/400 System API Reference V4R4

 Part 34. Virtual Terminal APIs
Chapter 91. Virtual Terminal APIs—Overview . . 91-1 Chapter 92. Virtual Terminal APIs . . . . . . . . . 92-1
Distributed 5250 Emulation Model . . . . . . . . . . 91-1 Virtual Terminal APIs—Introduction . . . . . . . . . 92-1
AS/400 Job Information . . . . . . . . . . . . . . . . 91-1 Close Virtual Terminal Path (QTVCLOVT) API . . . 92-1
AS/400 Subsystem Information . . . . . . . . . . . . 91-2 Open Virtual Terminal Path (QTVOPNVT) API . . . 92-1
Work Station Types . . . . . . . . . . . . . . . . . . 91-2 Read from Virtual Terminal (QTVRDVT) API . . . . 92-5
Data Queues . . . . . . . . . . . . . . . . . . . . . 91-2 Send Request for OS/400 Function (QTVSNDRQ) API 92-7
Preparing to Use the Virtual Terminal APIs . . . . . 91-3 Write to Virtual Terminal (QTVWRTVT) API . . . . . 92-8
Creating Your Own Virtual Controllers and Devices . 91-4
Developing Client and Server Programs . . . . . . . 91-4 Chapter 93. Virtual Terminal Run-Time—Example 93-1

Part 35. Work Management APIs

Chapter 94. Work Management APIs . . . . . . . 94-1 Retrieve Current Attributes (QWCRTVCA) API . . . 94-71
Work Management APIs—Introduction . . . . . . . . 94-1 Retrieve Data Area (QWCRDTAA) API . . . . . . . 94-79
Change Current Job (QWCCCJOB) API . . . . . . . 94-2 Retrieve IPL Attributes (QWCRIPLA) API . . . . . . 94-80
Change Job (QWTCHGJB) API . . . . . . . . . . . 94-3 Retrieve Job Description Information (QWDRJOBD)
Change Pool Attributes (QUSCHGPA) API . . . . . 94-16 API . . . . . . . . . . . . . . . . . . . . . . . . . 94-82
Change Pool Tuning Information (QWCCHGTN) API 94-19 Retrieve Job Information (QUSRJOBI) API . . . . . 94-86
Change Subsystem Entry (QWDCSBSE) API . . . . 94-22 Retrieve Job Queue Information (QSPRJOBQ) API 94-105
Control Trace (QWTCTLTR) API . . . . . . . . . . . 94-25 Retrieve Job Status (QWCRJBST) API . . . . . . 94-107
Create Job Structures (QWTCTJBS) API . . . . . . 94-26 Retrieve Network Attributes (QWCRNETA) API . . 94-108
| Delete Job Structures (QWTDTJBS) API . . . . . . 94-27 Retrieve Profile Exit Programs (QWTRTVPX) API . 94-114
Dump Flight Recorder (QWTDMPFR) API . . . . . . 94-27 Retrieve Subsystem Information (QWDRSBSD) API 94-115
Dump Lock Flight Recorder (QWTDMPLF) API . . . 94-27 Retrieve System Status (QWCRSSTS) API . . . . 94-117
List Active Subsystems (QWCLASBS) API . . . . . 94-28 Retrieve System Values (QWCRSVAL) API . . . . 94-121
List Job (QUSLJOB) API . . . . . . . . . . . . . . . 94-29 Set Lock Flight Recorder (QWTSETLF) API . . . . 94-134
List Job Schedule Entries (QWCLSCDE) API . . . . 94-34 Set Profile Exit Programs (QWTSETPX) API . . . 94-134
List Object Locks (QWCLOBJL) API . . . . . . . . . 94-39 Set Trace (QWTSETTR) API . . . . . . . . . . . . 94-135
List Subsystem Entries (QWDLSBSE) API . . . . . . 94-42
List Subsystem Job Queues (QWDLSJBQ) API . . . 94-48 Chapter 95. Work Management Exit Programs . . 95-1
Move Job (QSPMOVJB) API . . . . . . . . . . . . . 94-49 Work Management Exit Program—Introduction . . . 95-1
Open List of Activation Attributes (QWVOLACT) API 94-53 Auxiliary Storage Lower Limit Exit Program . . . . . 95-1
Open List of Activation Group Attributes Exit Program for Trace Job . . . . . . . . . . . . . . 95-1
(QWVOLAGP) API . . . . . . . . . . . . . . . . . 94-55 Job Notification Exit Point . . . . . . . . . . . . . . 95-5
| Open List of ASPs (QYASPOL) API . . . . . . . . . 94-57 Power Down System Exit Program . . . . . . . . . . 95-7
Open List of Jobs (QGYOLJOB) API . . . . . . . . . 94-63 Preattention Program Exit Program . . . . . . . . . 95-7
Retrieve Class Information (QWCRCLSI) API . . . . 94-69 Presystem Request Program Exit Program . . . . . 95-7

Part 36. Work Station Support APIs

| Chapter 96. Work Station Support APIs . . . . . 96-1

Part 37. Miscellaneous APIs

| Chapter 97. Miscellaneous APIs . . . . . . . . . . 97-1

Part 38. Reference Information

Appendix A. Examples . . . . . . . . . . . . . . . . A-1 Creating Your Own Telephone Directory . . . . . . . A-10
Examples—Introduction . . . . . . . . . . . . . . . . A-1 Creating and Manipulating a User Index . . . . . . . A-12
Deleting Old Spooled Files . . . . . . . . . . . . . . . A-1 Creating a Batch Machine . . . . . . . . . . . . . . A-13
Changing an Active Job . . . . . . . . . . . . . . . . A-6 Defining Queries . . . . . . . . . . . . . . . . . . . A-15
Changing a Job Schedule Entry . . . . . . . . . . . . A-9 Generating and Sending an Alert . . . . . . . . . . A-24

Contents xix
 Diagnostic Reporting . . . . . . . . . . . . . . . . . A-24 Creating a Program Temporary Fix Exit Program . . A-84
Listing Directories . . . . . . . . . . . . . . . . . . . A-27
Listing Subdirectories . . . . . . . . . . . . . . . . . A-30 Appendix B. Authority for Call Level Interfaces . . B-1
| Saving to Multiple Devices . . . . . . . . . . . . . . A-32
Scanning String Patterns . . . . . . . . . . . . . . . A-32 Appendix C. Application Programming Interfaces
Using COBOL Program to Call APIs . . . . . . . . . A-34 by Release . . . . . . . . . . . . . . . . . . . . . . C-1
Using the User-Defined Communications Programs for OS/400 APIs by Release . . . . . . . . . . . . . . . . C-1
File Transfer . . . . . . . . . . . . . . . . . . . . . A-35 APIs Described in Other Manuals . . . . . . . . . . C-38
| Using the Control Device (QTACTLDV) API . . . . . A-49
Using a Data Queue . . . . . . . . . . . . . . . . . A-50 Appendix D. Notices . . . . . . . . . . . . . . . . . D-1
Using Environment Variables . . . . . . . . . . . . . A-52 Programming Interface Information . . . . . . . . . . . D-2
| Saving and Restoring System-Level Environment Trademarks . . . . . . . . . . . . . . . . . . . . . . . D-2
| Variables . . . . . . . . . . . . . . . . . . . . . . A-53
Using the Generic Terminal APIs . . . . . . . . . . A-55 Bibliography . . . . . . . . . . . . . . . . . . . . . . X-1
Using Profile Handles . . . . . . . . . . . . . . . . . A-56 General-Purpose Books . . . . . . . . . . . . . . . . X-1
Using Registration Facility APIs . . . . . . . . . . . A-57 OS/400 API Books . . . . . . . . . . . . . . . . . . . X-2
Using Semaphores and Shared Memory . . . . . . . A-58 Programming Language Books . . . . . . . . . . . . . X-2
Using SNA/Management Services Transport APIs . . A-60 Communications Books . . . . . . . . . . . . . . . . . X-3
Using Source Debugger APIs . . . . . . . . . . . . A-65 CDRA Book . . . . . . . . . . . . . . . . . . . . . . . X-4
Using the Spawn Process and Wait for Child Process DLS File System Books . . . . . . . . . . . . . . . . X-4
APIs . . . . . . . . . . . . . . . . . . . . . . . . . A-79
Working with Stream Files . . . . . . . . . . . . . . A-83 Index . . . . . . . . . . . . . . . . . . . . . . . . . . X-5
Using the Operational Assistant Exit Program for
Operational Assistant Backup . . . . . . . . . . . . A-84

xx AS/400 System API Reference V4R4

 Figures
0-1. AS/400 Operations Navigator Display . . . xxviii 11-6. Timer-Expired Entry . . . . . . . . . . . . 11-3
2-1. Language Selection Considerations — Data 12-1. Return and Reason Codes for the
Types . . . . . . . . . . . . . . . . . . . . . 2-1 QOLDLINK API . . . . . . . . . . . . . . 12-1
2-2. Language Selection Considerations — Call 12-2. Return and Reason Codes for the
Conventions . . . . . . . . . . . . . . . . . 2-1 QOLELINK API . . . . . . . . . . . . . . . 12-4
2-3. Include Files Shipped with the QSYSINC 12-3. User Buffer Format . . . . . . . . . . . . . 12-6
Library . . . . . . . . . . . . . . . . . . . . 2-2 12-4. General Query Data . . . . . . . . . . . . 12-7
3-1. User Function Pointer . . . . . . . . . . . 3-23 12-5. LAN Specific Data–Format 01 . . . . . . . 12-7
3-2. Authorization Required for 12-6. LAN Specific Data–Format 02 . . . . . . . 12-8
Qp0lSaveStgFree() API . . . . . . . . . . 3-24 12-7. X.25 Specific Data–Format 01 . . . . . . . 12-9
3-3. Path Name Pointers . . . . . . . . . . . . 3-85 12-8. X.25 Specific Data–Format 02 . . . . . . . 12-10
| 7-1. Nodes role example . . . . . . . . . . . . . 7-2 12-9. Return and Reason Codes for the
| 7-2. Summary of cluster resource group statuses QOLQLIND API . . . . . . . . . . . . . . 12-13
| for each Cluster Resource Group Manager 12-10. Diagnostic Data Parameter . . . . . . . . 12-15
| API . . . . . . . . . . . . . . . . . . . . . . 7-3 12-11. Format of the General LAN Information . . 12-17
| 8-1. Reasons an Exit Program Is Called . . . . . 8-5 12-12. Ethernet 802.3, Wireless, and . . . . . . . 12-17
9-1. User-Defined Communications Support . . . 9-1 12-13. Token-Ring Frames with Routing
9-2. AS/400 APPC versus ISO Model . . . . . . 9-3 Information . . . . . . . . . . . . . . . . . 12-18
9-3. AS/400 User-Defined versus ISO Model . . 9-3 12-14. Ethernet Version 2 Frames . . . . . . . . 12-18
9-4. Comparison between User-Defined 12-15. Format of an Element in the Input Buffer
Communications and APPC Communications 9-4 Descriptor . . . . . . . . . . . . . . . . . 12-18
10-1. Overview of API Relationships . . . . . . . 10-2 12-16. X.25 SVC and PVC Input Operations . . . 12-18
10-2. Application Programming Interface to Job 12-17. Format of an Element in the Input Buffer
Structure . . . . . . . . . . . . . . . . . . 10-2 Descriptor . . . . . . . . . . . . . . . . . 12-19
10-3. Example 1: Normal Connection 12-18. Format of Data for X'B001' Operation
Establishment . . . . . . . . . . . . . . . 10-4 (Completion of SVC Call) . . . . . . . . . 12-20
10-4. Example 2: Connection Request Cleared by 12-19. Format of Data for X'B001' Operation
Network/Remote System . . . . . . . . . . 10-5 (Completion of Open PVC) . . . . . . . . 12-20
10-5. Example 3: Request to Clear Connection 12-20. Format of Data for X'B101' Operation . . . 12-21
with Outstanding Call (Unsuccessful) . . . 10-6 12-21. Format of Data for X'B201' Operation . . . 12-22
10-6. Unsuccessful Attempt to Clear Outstanding 12-22. Format of Data for X'B301' Operation . . . 12-23
(Successful) Call . . . . . . . . . . . . . . 10-7 12-23. Return and Reason Codes Indicating No
10-7. Example 5: Successful Attempt to Clear Data Received . . . . . . . . . . . . . . . 12-23
Outstanding (Successful) Call . . . . . . . 10-9 12-24. Return and Reason Codes for LAN
10-8. Example 6: Successful Attempt to Clear Operation X'0001'. . . . . . . . . . . . . . 12-24
Outstanding (Unsuccessful) Call . . . . . . 10-10 12-25. Return and Reason Codes Indicating No
10-9. Example 7: Unsuccessful Attempt to Clear Data Received . . . . . . . . . . . . . . . 12-24
Outstanding (Unsuccessful) Call . . . . . . 10-12 12-26. Return and Reason Codes for X.25
10-10. Example 1: Normal Connection Operation X'0001' . . . . . . . . . . . . . 12-25
Establishment . . . . . . . . . . . . . . . 10-13 12-27. Return and Reason Codes for X.25
10-11. Example 2: Send Call Accept Not Valid . 10-14 Operation X'B001' . . . . . . . . . . . . . 12-25
10-12. Example 3: Send Clear for Incoming Call . 10-15 12-28. Return and Reason Codes for X.25
10-13. Example 4: Send Clear for Incoming Call . 10-16 Operation X'B101' . . . . . . . . . . . . . 12-25
10-14. Example 1: Close Connection Request Is 12-29. Return and Reason Codes for X.25
Not Valid . . . . . . . . . . . . . . . . . . 10-17 Operation X'B111' . . . . . . . . . . . . . 12-26
10-15. Example 2: Close Connection Request Is 12-30. Return and Reason Codes for X.25
Valid . . . . . . . . . . . . . . . . . . . . 10-18 Operation X'B201' . . . . . . . . . . . . . 12-26
10-16. Using the Data Queue . . . . . . . . . . . 10-25 12-31. Return and Reason Codes for X.25
10-17. Application Disables the Link . . . . . . . 10-25 Operation X'B301' . . . . . . . . . . . . . 12-26
10-18. User Spaces . . . . . . . . . . . . . . . . 10-26 12-32. Return and Reason Codes for X.25
10-19. Input/Output Operations . . . . . . . . . . 10-26 Operation X'B311' . . . . . . . . . . . . . 12-27
11-1. Queue Entry General Format . . . . . . . 11-2 12-33. Return and Reason Codes for X.25
11-2. Enable-Complete Entry . . . . . . . . . . 11-2 Operation X'BF01' . . . . . . . . . . . . . 12-27
11-3. Disable-Complete Entry . . . . . . . . . . 11-2 12-34. Diagnostic Data Parameter . . . . . . . . 12-29
11-4. Permanent-Link-Failure Entry . . . . . . . 11-3 12-35. Format of the General LAN Information . . 12-30
11-5. Incoming-Data Entry . . . . . . . . . . . . 11-3

Contents xxi
12-36. Format of an Element in the Output Buffer 14-1. Translations for Output Operations . . . . 14-1
Descriptor . . . . . . . . . . . . . . . . . 12-31 14-2. Translations for Input Operations . . . . . 14-1
12-37. X.25 SVC and PVC Output Operations . . 12-31 14-3. Valid Parameter Combinations . . . . . . . 14-4
12-38. Format of an Element in the Output Buffer 17-1. Receiver Variable Header Section . . . . . 17-15
Descriptor . . . . . . . . . . . . . . . . . 12-32 17-2. Module Variable Header Section . . . . . 17-15
12-39. Format of Data for X'B000' Operation 17-3. Scalar Variable Section . . . . . . . . . . 17-15
(Initiate an SVC Call) . . . . . . . . . . . 12-33 17-4. Array Definition Variable Section . . . . . 17-16
12-40. Format of Data for X'B000' Operation (Open 17-5. Block Definition Variable Section . . . . . 17-16
a PVC Connection) . . . . . . . . . . . . 12-35 17-6. Receiver Variable Structure . . . . . . . . 17-50
12-41. Format of Data for X'B100' Operation . . . 12-37 17-7. Variations in Receiver Variable Structure . 17-51
12-42. Format of Data for X'B400' Operation . . . 12-37 17-8. Program for Break Example . . . . . . . . 17-56
12-43. Return and Reason Codes for LAN 17-9. Program for Scalar Evaluate Example . . . 17-56
Operation X'0000' . . . . . . . . . . . . . 12-40 17-10. RPG Programming Language Example,
12-44. Return and Reason Codes Valid for All X.25 Evaluate . . . . . . . . . . . . . . . . . . 17-57
Operations . . . . . . . . . . . . . . . . . 12-41 17-11. Program for Structure Evaluate Example . 17-57
12-45. Return and Reason Codes for X.25 17-12. Program for Step Example . . . . . . . . . 17-58
Operation X'0000' . . . . . . . . . . . . . 12-41 17-13. RPG Programming Language Example,
12-46. Return and Reason Codes for X.25 Evaluate . . . . . . . . . . . . . . . . . . 17-58
Operation X'B000' . . . . . . . . . . . . . 12-42 17-14. Program for Scalar Evaluate Example . . . 17-58
12-47. Return and Reason Codes for X.25 17-15. Presentation Formats . . . . . . . . . . . 17-62
Operation X'B100' . . . . . . . . . . . . . 12-42 18-1. LDAP Client Functions . . . . . . . . . . . 18-1
12-48. Return and Reason Codes for X.25 18-2. Authorization Required for ldap_ssl_start() 18-37
Operation X'B110' . . . . . . . . . . . . . 12-43 19-1. System Distribution Directory Fields Mapped
12-49. Return and Reason Codes for X.25 to LDAP Attributes . . . . . . . . . . . . . 19-22
Operation X'B400' . . . . . . . . . . . . . 12-43 21-1. AID Codes . . . . . . . . . . . . . . . . . 21-2
12-50. Return and Reason Codes for X.25 21-2. Control Character Byte 1 . . . . . . . . . . 21-2
Operation X'BF00' . . . . . . . . . . . . . 12-43 21-3. Control Character Byte 2 . . . . . . . . . . 21-3
12-51. Filter Header Data . . . . . . . . . . . . . 12-45 21-4. Screen Attributes for Non-Color Displays . 21-3
12-52. Filter Types X'00' and X'01' . . . . . . . . 12-45 21-5. Screen Attributes for Color Displays . . . . 21-4
12-53. Filter Types X'02', X'03', and X'04' . . . . . 12-46 22-1. Window Area . . . . . . . . . . . . . . . . 22-23
12-54. Filter Type X'08' . . . . . . . . . . . . . . 12-47 25-1. Field Format Words . . . . . . . . . . . . 25-14
12-55. Return and Reason Codes for the 25-2. Field Control Words . . . . . . . . . . . . 25-17
QOLSETF API . . . . . . . . . . . . . . . 12-48 25-3. Program to Roll Text on Screen . . . . . . 25-27
12-56. Return and Reason Codes for the 25-4. Screen Output from Roll Text Program . . 25-27
QOLTIMER API . . . . . . . . . . . . . . 12-51 25-5. Program Using the Query 5250
13-1. User Space to Set a Filter to Route Incoming (QsnQry5250) API . . . . . . . . . . . . . 25-27
X.25 Calls . . . . . . . . . . . . . . . . . 13-2 25-6. Screen Output from QsnQry5250 API
13-2. User Space to Send an SVC Call . . . . . 13-3 Program . . . . . . . . . . . . . . . . . . 25-27
13-3. User Space Containing an Incoming X.25 25-7. Program Using Read Modified Fields
Call . . . . . . . . . . . . . . . . . . . . . 13-4 (QsnReadMDT) API . . . . . . . . . . . . 25-28
13-4. User Space to Accept an Incoming X.25 Call 13-5 25-8. Display Screen before Input Operation . . 25-28
13-5. User Space (Buffer) to Send Three Data 25-9. Display Screen after Input Operation . . . 25-28
Units . . . . . . . . . . . . . . . . . . . . 13-6 25-10. Program Using Read QsnWrtSFMaj and
13-6. User Space (Descriptor Element) to Describe QsnWrtSFMin APIs . . . . . . . . . . . . 25-29
the Three Data Units . . . . . . . . . . . . 13-6 26-1. DSM Window Layout . . . . . . . . . . . . 26-2
13-7. User Space (Buffer) Containing the Three 26-2. DSM Window with No Border . . . . . . . 26-2
Data Units . . . . . . . . . . . . . . . . . 13-7 26-3. DSM Window with No Border Attributes . . 26-2
13-8. User Space (Descriptor Element) Describing 26-4. DSM Window with No Leading Window
the Three Data Units . . . . . . . . . . . . 13-8 Attribute . . . . . . . . . . . . . . . . . . 26-2
13-9. User Space to Send an SVC Clear . . . . 13-8 29-1. Creating and Manipulating Windows . . . . 29-4
13-10. Error Codes Received While Sending Data 29-2. Display Screen . . . . . . . . . . . . . . . 29-5
over LAN . . . . . . . . . . . . . . . . . . 13-9 30-1. Session Attributes . . . . . . . . . . . . . 30-1
13-11. Error Codes Reported on X'B001', X'B301', 30-2. EBCDIC Display Control Characters . . . . 30-3
and X'B400' Operations . . . . . . . . . . 13-9 32-1. Program for Creating a Session and Reading
13-12. Error Codes Reported on the X'B101' Data . . . . . . . . . . . . . . . . . . . . 32-9
Operation . . . . . . . . . . . . . . . . . . 13-10 32-2. Screen Output from Create Session
13-13. Error Codes Reported on the X'BF01' Program . . . . . . . . . . . . . . . . . . 32-10
Operation . . . . . . . . . . . . . . . . . . 13-11 | 34-1. QDBQH_T Format . . . . . . . . . . . . . 34-42
13-14. Error Codes Resulting from a X'0000' 34-2. Qdb_Qddfmt_t Format . . . . . . . . . . . 34-66
Operation . . . . . . . . . . . . . . . . . . 13-11 | 34-3. FILD0100 Format . . . . . . . . . . . . . 34-75

xxii AS/400 System API Reference V4R4

| 34-4. FILD0200 Format . . . . . . . . . . . . . 34-95 | 47-4. This journal entry's header . . . . . . . . . 47-34
34-5. FILD0300 Format . . . . . . . . . . . . 34-116 | 47-5. This journal entry's null value indicators if
34-6. DSPF0100 Format . . . . . . . . . . . . 34-119 | Null Value Indicators (*VARLEN) specified 47-35
34-7. File Header Section . . . . . . . . . . . 34-121 | 47-6. This journal entry's null value indicators if
34-8. Record Header Section . . . . . . . . . 34-124 | Null Value Indicators (field length) specified 47-35
34-9. Field Header Section . . . . . . . . . . . 34-133 | 47-7. This journal entry's entry specific data . . . 47-35
34-10. Where-Used Section . . . . . . . . . . . 34-178 47-8. Logical Unit of Work Identifier Format . . . 47-59
34-11. Keyword Types . . . . . . . . . . . . . . 34-180 48-1. NOTIFY Message Results . . . . . . . . 48-104
34-12. Find Member Example . . . . . . . . . . 34-185 49-1. Sample Information from the API for CCSID
34-13. MBRD0100 Format . . . . . . . . . . . 34-185 00037 . . . . . . . . . . . . . . . . . . . 49-6
34-14. MBRD0200 Format . . . . . . . . . . . 34-186 49-2. Sample Information from the API for CCSID
34-15. MBRD0300 Format . . . . . . . . . . . 34-186 00932 . . . . . . . . . . . . . . . . . . . 49-6
34-16. Relationship between Input Format Name 49-3. Sample Information from the API for CCSID
and Input Format . . . . . . . . . . . . . 34-202 00437 . . . . . . . . . . . . . . . . . . . 49-6
34-17. Relationship between Input Format Name 49-4. Sample Information from the API for CCSID
and Output Format . . . . . . . . . . . . 34-205 01252 . . . . . . . . . . . . . . . . . . . 49-6
37-1. Compilers and preprocessors that can be 52-1. Applications Using SNA/Management
used with the Application Development Services Transport APIs . . . . . . . . . . 52-4
Manager/400 feature . . . . . . . . . . . . 37-1 52-2. Data Types Handled by SNA/Management
37-2. Overall Application Development Services Transport APIs . . . . . . . . . . 52-4
Manager/400 API Usage . . . . . . . . . . 37-2 52-3. Format CRQD0100 . . . . . . . . . . . . 52-33
37-3. API Space Status . . . . . . . . . . . . . 37-2 52-4. Format CRQD0200 . . . . . . . . . . . . 52-34
37-4. Record Types and Processors (Part 1) . . 37-5 54-1. Always Delimiters . . . . . . . . . . . . . 54-26
37-5. Record Types and Processors (Part 2) . . 37-6 54-2. Never Delimiters . . . . . . . . . . . . . . 54-26
37-6. Record Types and Processors (Part 3) . . 37-6 54-3. Sometimes Delimiters . . . . . . . . . . . 54-26
39-1. Data Type Definitions across ILE Languages 39-2 54-4. Simple Token Table for Code Page 500 . 54-27
40-1. Common Reason Codes for Ending 54-5. Simple Token Table for Code Page 875
Activation Groups and Call Stack Entries. . 40-3 Greek Support . . . . . . . . . . . . . . . 54-27
41-1. ILE Condition Token Layout . . . . . . . . 41-1 54-6. Simple Token Table for Code Page 1026
41-2. Default Responses to Unhandled Exceptions 41-2 Turkish Support . . . . . . . . . . . . . . 54-27
41-3. Mapping OS/400 *ESCAPE Message 55-1. APIs Used to Register User Exit
Severities to ILE Condition Severities . . . 41-2 Applications . . . . . . . . . . . . . . . . 55-17
41-4. Mapping OS/400 *STATUS and *NOTIFY 55-2. Document Handling Function Requests . . 55-19
Message Severities to ILE Condition 56-1. Example of a Message Descriptor for the
Severities . . . . . . . . . . . . . . . . . . 41-2 Create Mail Message (QzmfCrtMailMsg) or
42-1. Picture Characters Used in Picture Strings 42-4 Change Mail Message (QzmfChgMailMsg)
42-2. Examples of Picture Strings Recognized by API . . . . . . . . . . . . . . . . . . . . . 56-2
ILE Date and Time APIs . . . . . . . . . . 42-5 56-2. Message Descriptor Attribute Array Entry . 56-21
42-3. Japanese Eras Used by ILE Date and Time 56-3. Format of Common Header . . . . . . . . 56-22
APIs When <JJJJ> Specified . . . . . . . 42-5 58-1. Send a Message Display . . . . . . . . . 58-6
42-4. Republic of China Eras Used by ILE Date 61-1. Standard Paper and Envelope Dimensions 61-16
and Time APIs When <CCCC> or 61-2. Parameters for Multipage Output . . . . . 61-19
<CCCCCCCC> Specified . . . . . . . . . 42-6 61-3. Data Stream Type . . . . . . . . . . . . . 61-58
42-5. Sample Output of the CEEDATE API . . . 42-8 62-1. Structure of the Option Specific Input
42-6. Sample Output of the CEEDATM API . . . 42-10 Information Parameter . . . . . . . . . . . 62-5
42-7. Country Codes . . . . . . . . . . . . . . . 42-16 62-2. Fields Defined for the Option Specific Input
43-1. Precise Limit Values of Integer Data Types 43-1 Information Parameter . . . . . . . . . . . 62-6
43-2. Approximate Limit Values of Real Data Types 43-2 62-3. Structure of the Option Specific Output
43-3. Floating-point Special Values . . . . . . . 43-2 Information Parameter . . . . . . . . . . . 62-7
43-4. Approximate Limit Values of Complex Data 62-4. Fields Defined for the Option Specific Output
Types . . . . . . . . . . . . . . . . . . . . 43-2 Information Parameter . . . . . . . . . . . 62-8
43-5. Math API Descriptions . . . . . . . . . . . 43-4 62-5. Parameters Used by the Printer Writer or
43-6. Messages Generated by Math Bindable APIs 43-8 Transform Exit Program . . . . . . . . . . 62-11
46-1. CEE4ALC Definition for ILE C . . . . . . . 46-1 62-6. Fields Used by the Option Specific Input
46-2. CEE4ALC Definition for ILE COBOL . . . 46-2 Information Parameter . . . . . . . . . . . 62-12
46-3. CEE4ALC Definition for ILE RPG . . . . . 46-2 62-7. Fields Used by the Option Specific Output
47-1. Example Using Selective Commitment Information Parameter . . . . . . . . . . . 62-15
Control APIs . . . . . . . . . . . . . . . . 47-4 63-1. Format CPYR0100 . . . . . . . . . . . . . 63-3
47-2. Logical Unit of Work Identifier Format . . . 47-26 63-2. SPLA0200 Format Field Names and
| 47-3. Header . . . . . . . . . . . . . . . . . . . 47-34 Descriptions . . . . . . . . . . . . . . . . 63-6

Figures xxiii
 63-3. Formats SPFR0100 and SPFR0200 . . . . 63-31 77-35. Checkout Format . . . . . . . . . . . . . 77-114
63-4. Format SPFR0300 . . . . . . . . . . . . . 63-32 77-36. General Authority Format . . . . . . . . 77-115
63-5. Spooled File Identifying Fields . . . . . . . 63-52 77-37. Data and Object Authority Format . . . . 77-115
76-1. Environment Variable Functions . . . . . . 76-1 | 77-38. Qp0l_Usage_t . . . . . . . . . . . . . . 77-117
77-1. Integrated File System Functions . . . . . 77-1 | 77-39. Qp0l_Journal_Info_t . . . . . . . . . . . 77-118
77-2. Other Functions that Operate on Files . . . 77-2 77-40. Buffer Pointer . . . . . . . . . . . . . . 77-119
77-3. Authorization Required for access() . . . . 77-3 77-41. Authorization Required for . . . . . . . 77-119
77-4. Authorization Required for chdir() . . . . . 77-6 77-42. Authorization Required for
77-5. Authorization Required for chmod() Qp0lGetPathFromFileID() . . . . . . . . 77-124
(excluding QDLS) . . . . . . . . . . . . . 77-9 77-43. Object Types Array Pointer . . . . . . . 77-127
77-6. Authorization Required for chmod() in the 77-44. IN_EXclusion Pointer. This points to a list
QDLS File System . . . . . . . . . . . . . 77-9 of path names to either include or exclude
77-7. Authorization Required for chown() from a search. . . . . . . . . . . . . . . 77-127
(excluding QSYS.LIB and QDLS) . . . . . 77-12 77-45. User Function Pointer. This points to the
77-8. Authorization Required for chown() in the user exit program. The exit program can
QSYS.LIB File System . . . . . . . . . . . 77-12 be a procedure or a program. . . . . . . 77-128
77-9. Authorization Required for chown() in the 77-46. Authorization Required for . . . . . . . 77-129
QDLS File System . . . . . . . . . . . . . 77-12 | 77-47. Directory Structure A . . . . . . . . . . . 77-132
| 77-10. Authorization Required for chown() in the | 77-48. Directory Structure B . . . . . . . . . . . 77-132
| QOPT File System . . . . . . . . . . . . . 77-12 77-49. Scenario 1 API Input . . . . . . . . . . . 77-133
77-11. Authorization Required for creat() (excluding 77-50. Results of a call . . . . . . . . . . . . . 77-133
QSYS.LIB and QDLS) . . . . . . . . . . . 77-20 77-51. Scenario 2 API Input . . . . . . . . . . . 77-133
77-12. Authorization Required for creat() in the 77-52. Results of a call . . . . . . . . . . . . . 77-133
QSYS.LIB File System . . . . . . . . . . . 77-20 77-53. Scenario 3 API Input . . . . . . . . . . . 77-134
77-13. Authorization Required for creat() in the 77-54. Results of a call . . . . . . . . . . . . . 77-134
QDLS File System . . . . . . . . . . . . . 77-20 77-55. Scenario 4 API Input . . . . . . . . . . . 77-134
77-14. Authorization Required for fchmod() 77-56. Results of a call . . . . . . . . . . . . . 77-134
(excluding QDLS) . . . . . . . . . . . . . 77-32 77-57. Authorization Required for
77-15. Authorization Required for fchmod() in the Qp0lRenameKeep() (excluding QSYS.LIB,
QDLS File System . . . . . . . . . . . . . 77-33 QDLS, and QOPT) . . . . . . . . . . . . 77-136
77-16. Authorization Required for fchown() 77-58. Authorization Required for
(excluding QSYS.LIB and QDLS) . . . . . 77-36 Qp0lRenameKeep() in the QSYS.LIB File
77-17. Authorization Required for fchown() in the System . . . . . . . . . . . . . . . . . . 77-136
QSYS.LIB File System . . . . . . . . . . . 77-36 77-59. Authorization Required for
77-18. Authorization Required for fchown() in the Qp0lRenameKeep() in the QDLS File
QDLS File System . . . . . . . . . . . . . 77-36 System . . . . . . . . . . . . . . . . . . 77-136
| 77-19. Authorization Required for fchown() in the | 77-60. Authorization Required for
| QOPT File System . . . . . . . . . . . . . 77-36 | Qp0lRenameKeep() in the QOPT File
77-20. Authorization Required for fstatvfs() . . . . 77-52 | System . . . . . . . . . . . . . . . . . . 77-137
77-21. Authorization Required for getcwd() . . . . 77-60 77-61. Authorization Required for
77-22. Authorization Required for link() . . . . . . 77-77 Qp0lRenameUnlink() (excluding QSYS.LIB,
77-23. Authorization Required for lstat() . . . . . 77-83 QDLS, and QOPT) . . . . . . . . . . . . 77-141
77-24. Authorization Required for mkdir() 77-62. Authorization Required for
(excluding QSYS.LIB and QDLS) . . . . . 77-87 Qp0lRenameUnlink() in the QSYS.LIB File
77-25. Authorization Required for mkdir() in the System . . . . . . . . . . . . . . . . . . 77-141
QSYS.LIB File System . . . . . . . . . . . 77-87 77-63. Authorization Required for
77-26. Authorization Required for mkdir() in the Qp0lRenameUnlink() in the QDLS File
QDLS File System . . . . . . . . . . . . . 77-87 System . . . . . . . . . . . . . . . . . . 77-141
77-27. File Sharing Conflicts . . . . . . . . . . . 77-93 77-64. Authorization Required for
77-28. Authorization Required for open() (excluding Qp0lRenameUnlink() in the QOPT File
QSYS.LIB and QDLS) . . . . . . . . . . . 77-94 System . . . . . . . . . . . . . . . . . . 77-141
77-29. Authorization Required for open() in the | 77-65. Buffer Pointer . . . . . . . . . . . . . . 77-145
QSYS.LIB File System . . . . . . . . . . . 77-94 | 77-66. Authorization Required for Qp0lSetAttr()
77-30. Authorization Required for open() in the | (excluding QSYS.LIB) . . . . . . . . . . 77-146
QDLS File System . . . . . . . . . . . . . 77-95 | 77-67. Authorization Required for Qp0lSetAttr()
77-31. Authorization Required for opendir() . . . 77-100 | (QSYS.LIB) . . . . . . . . . . . . . . . . 77-146
77-32. Authorization Required for pathconf() . . 77-105 77-68. Authorization Required for readlink() . . 77-162
77-33. Authorization Required for the 77-69. Authorization Required for rmdir()
Qp0lCvtPathToQSYSObjName() API . . 77-110 (excluding QSYS.LIB and QDLS) . . . . 77-173
77-34. Attribute array pointer . . . . . . . . . . 77-114

xxiv AS/400 System API Reference V4R4

 77-69. Authorization Required for rmdir() 83-4. Socket Options That Apply to the TCP
(excluding QSYS.LIB and QDLS) . . . . 77-173 Layer (IPPROTO_TCP) . . . . . . . . . . 83-24
77-70. Authorization Required for rmdir() in the 83-5. Socket Options That Apply to the IPX or
QSYS.LIB File System . . . . . . . . . . 77-173 SPX Layer (NNSPROTO_IPX or
77-71. Authorization Required for rmdir() in the NNSPROTO_SPX) . . . . . . . . . . . . . 83-24
QDLS File System . . . . . . . . . . . . 77-173 83-6. Socket Options That Apply to the SPX
| 77-72. Authorization Required for rmdir() in the Layer Only (NNSPROTO_SPX) . . . . . . 83-25
| QOPT File System . . . . . . . . . . . . 77-173 83-7. Socket Options That Apply to the Socket
77-73. Authorization Required for stat() . . . . . 77-177 Layer (SOL_SOCKET) . . . . . . . . . . . 83-25
77-74. Authorization Required for statvfs() . . . 77-183 83-8. ioctl() Requests Supported by Sockets . . 83-30
77-75. Authorization Required for symlink() . . . 77-187 83-9. ipxrt_entry Structure . . . . . . . . . . . . 83-33
77-76. Authorization Required for unlink() 83-10. timeval Structure . . . . . . . . . . . . . . 83-33
(excluding QSYS.LIB, QDLS and QOPT) 77-192 83-11. ipxsrv_conf Structure . . . . . . . . . . . . 83-33
77-77. Authorization Required for unlink() in the 83-12. ipxsrv_entry Structure . . . . . . . . . . . 83-34
QSYS.LIB File System . . . . . . . . . . 77-193 83-13. Socket Options That Apply to the IP Layer
77-78. Authorization Required for unlink() in the (IPPROTO_IP) . . . . . . . . . . . . . . . 83-68
QDLS File System . . . . . . . . . . . . 77-193 83-14. Socket Options That Apply to the TCP
| 77-79. Authorization Required for unlink() in the Layer (IPPROTO_TCP) . . . . . . . . . . 83-69
| QOPT File System . . . . . . . . . . . . 77-193 83-15. Socket Options That Apply to the IPX or
77-80. Authorization Required for utime() SPX Layer (NNSPROTO_IPX or
(excluding QDLS) . . . . . . . . . . . . 77-196 NNSPROTO_SPX) . . . . . . . . . . . . . 83-69
77-81. Authorization Required for utime() in the 83-16. Socket Options That Apply to the SPX
QDLS File System . . . . . . . . . . . . 77-196 Layer Only (NNSPROTO_SPX) . . . . . . 83-70
77-82. Time Stamp Updates for Integrated File 83-17. Socket Options That Apply to the Socket
System APIs . . . . . . . . . . . . . . . 77-206 Layer (SOL_SOCKET) . . . . . . . . . . . 83-70
78-1. Interprocess Communication Functions . . 78-6 83-18. Supported Combinations of Types and
78-2. Authorization Required for ftok() (excluding Protocols for AF_NS . . . . . . . . . . . . 83-76
QOPT) . . . . . . . . . . . . . . . . . . . 78-8 83-19. Supported Combinations of Types and
78-3. Authorization Required for ftok() in the QOPT Protocols for AF_INET . . . . . . . . . . . 83-76
File System . . . . . . . . . . . . . . . . . 78-8 83-20. Socket Network Functions . . . . . . . . . 83-85
78-4. Authorization Required for msgctl() . . . . 78-11 83-21. Common IP over SNA Configuration Errors 83-135
78-5. Authorization Required for msgget() . . . . 78-12 84-1. Secure Sockets Layer Functions . . . . . 84-2
78-6. Authorization Required for msgrcv() . . . . 78-14 85-1. Software Clock Functions . . . . . . . . . 85-1
78-7. Authorization Required for msgsnd() . . . 78-16 86-1. Process-Related Functions . . . . . . . . 86-1
| 78-8. Authorization Required for sem_open() . . 78-37 86-2. Authorization Required for
| 78-9. Authorization Required for sem_open_np() 78-39 Qp0zStartTerminal() . . . . . . . . . . . . 86-17
| 78-10. Authorization Required for sem_unlink() . . 78-43 86-3. Authorization Required for spawn() . . . . 86-21
78-11. Authorization Required for semctl() . . . . 78-48 86-4. Arguments to Shell Interpreter . . . . . . . 86-24
78-12. Authorization Required for semget() . . . . 78-50 86-5. Authorization Required for spawnp() . . . . 86-28
78-13. Authorization Required for semop() . . . . 78-51 86-6. Arguments to Shell Interpreter . . . . . . . 86-31
78-14. Authorization Required for shmat() . . . . 78-53 87-1. XA Functions . . . . . . . . . . . . . . . . 87-1
78-15. Authorization Required for shmctl() . . . . 78-55 87-2. XA Exit Functions . . . . . . . . . . . . . 87-1
78-16. Authorization Required for shmdt() . . . . 78-57 87-3. Example Using XA APIs . . . . . . . . . . 87-2
78-17. Authorization Required for shmget() . . . . 78-58 87-4. xainfo String Keywords and Values . . . . 87-9
79-1. Problem Determination Functions . . . . . 79-1 88-1. Where to Find Header Files . . . . . . . . 88-1
80-1. Signal Functions . . . . . . . . . . . . . . 80-4 | 89-1. Errno Values . . . . . . . . . . . . . . . . 89-1
80-2. Control Signals . . . . . . . . . . . . . . . 80-17 91-1. Example Virtual Terminal Client/Server Model 91-1
81-1. SNMP Subagent Functions . . . . . . . . 81-1 91-2. Format for OS/400 Data Queue Entries . . 91-2
81-2. DPI API Call Sequences—Example . . . . 81-2 92-1. Work Station Types and Models . . . . . . 92-4
82-1. SNMP Manager Functions . . . . . . . . . 82-1 92-2. Read Operation Codes . . . . . . . . . . 92-6
82-2. SNMP Trap Support . . . . . . . . . . . . 82-9 92-3. Write Operation Codes . . . . . . . . . . . 92-9
82-3. Work with Registration Information 94-1. Attribute Scope and Thread Safety . . . . 94-14
(WRKREGINF) Display . . . . . . . . . . 82-9 94-2. WRKACTJOB and QUSRJOBI API
82-4. Work with Exit Programs Display . . . . . 82-9 Comparison . . . . . . . . . . . . . . . 94-102
82-5. Add Exit Program - Display 1 of 2 . . . . . 82-9 94-3. Attribute Scope and Thread Safety . . . 94-103
82-6. Add Exit Program - Display 2 of 2 . . . . . 82-10 B-1. Public Authority for Call-Level Interfaces . . B-1
83-1. fcntl() Commands Supported by Sockets . 83-15 C-1. APIs by Release from V3R6 through V4R4 . C-1
83-2. Commands Used by the ... Parameter . . 83-15 C-2. APIs by Release from V1R3 through V3R1 C-20
83-3. Socket Options That Apply to the IP Layer C-3. Exit Programs by Release . . . . . . . . . C-36
(IPPROTO_IP) . . . . . . . . . . . . . . . 83-23

Figures xxv
xxvi AS/400 System API Reference V4R4
About System API Reference (SC41-5801)
This book describes the OS/400 application programming Program (*PGM). A sequence of instructions that a com-
interfaces (APIs). Some APIs provide the same functions as puter can interpret and run. A program can contain one or
control language (CL) commands and output file support. more modules.
Some APIs provide functions that CL commands do not.
Most APIs work more quickly and use less system overhead Service program (*SRVPGM). An object that packages
than the CL commands. externally supported callable routines into a separate object.

The System API Reference manual is broken into softcopy User index (*USRIDX). An object that provides a specific
“booklets,” which are usually referred to as books. Each of order for byte data according to the value of the data.
these books corresponds to a specific “part” in the printed
User queue (*USRQ). An object consisting of a list of mes-
manual. For example, System API Reference: Message
sages that communicate information to other application pro-
Handling APIs is a separate book in the softcopy version and
grams. Only programming languages that can use machine
is simply a part in the printed version. The System API Ref-
interface (MI) instructions can access *USRQ objects.
erence is the title of the printed version but is the introductory
book for the softcopy version. User space (*USRSPC). An object consisting of a collection
of bytes used for storing any user-defined information.

Who Should Read This Book These special values refer to OS/400 libraries and can often
be used in API calls in place of specific library names:
This book is intended for experienced application program-
mers who are developing system-level and other OS/400 *ALL. All libraries, including QSYS, that the user owns or to
applications. It provides reference information only; it is which the user has read authority.
neither an introduction to the OS/400 licensed program nor a
guide to writing OS/400 applications. *ALLUSR. All user-defined libraries to which the user has
read authority. *ALLUSR includes libraries that have names
starting with the letter Q and that also contain user data:
QDSNX, QGPL, QGPL38, QRCL, QPRFDATA, QS36F,
Conventions and Terminology Used in QUSER38, QUSRSYS, and QUSRVxRxMx. *ALLUSR
This Book excludes System/36 libraries that have names starting with
the symbol # and that do not contain user data: #CGULIB,
The descriptions of the APIs are organized in the parts (or
#COBLIB, #DFULIB, #DSULIB, #RPGLIB, #SDALIB, and
booklets) in alphabetical order as follows:
#SEULIB. For more information about QUSRVxRxMx
Ÿ By the spelled-out name for the original program model libraries or the *ALLUSR special value, see the topic about
(OPM), the Integrated Language Environment (ILE), and saving libraries in the Backup and Recovery book.
the ILE CEE APIs
*CURLIB. The job's current library. If no current library is
Ÿ By the function name for the UNIX-type APIs
specified for the job, the QGPL library is used.

OS/400 Terms and Special Values *LIBL. The user and system portions of the job's library list.

Before using the OS/400 APIs, you should be familiar with *USRLIBL. The user portion of the job's library list.
several terms and special values (not all APIs use every
concept). These terms refer to OS/400 objects, and the
system-recognized identifiers are shown in parentheses: AS/400 Operations Navigator
Binding directory (*BNDDIR) An AS/400 object that con- AS/400 Operations Navigator is a powerful graphical inter-
tains a list of names of modules and service programs. face for Windows clients. With AS/400 Operations Navigator,
you can manage and administer your AS/400 systems from
Data queue (*DTAQ). An object that is used to communi- your Windows desktop.
cate and store data used by several programs in a job or
between jobs. You can use Operations Navigator to manage communica-
tions, printing, database, security, and other system oper-
Module (*MODULE). An AS/400 object that is made up of ations. Operations Navigator includes Management Central
the output of the compiler. for managing multiple AS/400 systems centrally.

Figure 0-1 on page xxviii shows an example of the Oper-

ations Navigator display.

 Copyright IBM Corp. 1998, 1999 xxvii

 Prerequisite and Related Information
Before using the APIs described in this book, you should be
familiar with the concepts discussed in the CL Programming
book, SC41-5721. You should also be familiar with the con-
ceptual and guidance information provided for OS/400 API
users in the System API Programming book, SC41-5800.
You may need to refer to other IBM books for more specific
information about a particular topic.

Use the AS/400 Information Center as a starting point for

looking up AS/400 technical information. You can access the
Information Center from the AS/400e Information Center
CD-ROM (English version: SK3T-2027) or from one of these
Web sites:
http://www.as4ðð.ibm.com/infocenter
Figure 0-1. AS/400 Operations Navigator Display http://publib.boulder.ibm.com/pubs/html/as4ðð/infocenter.htm
This new interface has been designed to make you more The AS/400 Information Center contains important topics
productive and is the only user interface to new, advanced such as logical partitioning, clustering, Java, TCP/IP, Web
features of OS/400. Therefore, IBM recommends that you serving, and secured networks. It also contains Internet links
use AS/400 Operations Navigator, which has online help to to Web sites such as the AS/400 Online Library and the
guide you. While this interface is being developed, you may AS/400 Technical Studio. Included in the Information Center
still need to use a traditional emulator such as PC5250 to do is a link that describes at a high level the differences in infor-
some of your tasks. mation between the Information Center and the Online
Library.
Installing Operations Navigator For a list of related publications, see the “Bibliography” on
To use AS/400 Operations Navigator, you must have Client page X-1.
Access installed on your Windows PC. For help in con-
necting your Windows PC to your AS/400 system, consult
Client Access Express for Windows - Setup, SC41-5507. How to send your comments
AS/400 Operations Navigator is a separately installable com- Your feedback is important in helping to provide the most
ponent of Client Access that contains many accurate and high-quality information. If you have any com-
subcompoonents. If you are installing for the first time and ments about this book or any other AS/400 documentation,
you use the Typical installation option, the following options fill out the readers' comment form at the back of this book.
are installed by default: Ÿ If you prefer to send comments by mail, use the readers'
Ÿ Operations Navigator base support comment form with the address that is printed on the
back. If you are mailing a readers' comment form from a
Ÿ Basic operations (messages, printer output, and printers)
country other than the United States, you can give the
To select the subcomponents that you want to install, select form to the local IBM branch office or IBM representative
the Custom installation option. (After Operations Navigator for postage-paid mailing.
has been installed, you can add subcomponents by using Ÿ If you prefer to send comments by FAX, use either of
Client Access Selective Setup.) the following numbers:
1. Display the list of currently installed subcomponents in United States and Canada: 1-800-937-3430
the Component Selection window of Custom installa- Other countries: 1-507-253-5192
tion or Selective Setup.
Ÿ If you prefer to send comments electronically, use one of
2. Select AS/400 Operations Navigator. these e-mail addresses:
3. Select any additional subcomponents that you want to – Comments on books:
install and continue with Custom installation or Selective
[email protected]
Setup.
IBMMAIL, to IBMMAIL(USIB56RZ)
After you install Client Access, double-click the AS/400 – Comments on the AS/400 Information Center:
Operations Navigator icon on your desktop to access Oper-
[email protected]
ations Navigator and create an AS/400 connection.
Be sure to include the following:

xxviii AS/400 System API Reference V4R4

Ÿ The name of the book. Ÿ The page number or topic to which your comment
applies.
Ÿ The publication number of the book.

About System API Reference (SC41-5801) xxix

xxx AS/400 System API Reference V4R4
 Summary of Changes to System API Reference
| The following changes have been made to this book since | – Client Management Support APIs
| Version 4 Release 3 of the OS/400 licensed program. | – Hardware Resource APIs
| – Hierarchical File System APIs
| Ÿ Major new groups of APIs have been added as follows:
| – Object APIs
| – Cluster APIs part | – Problem Management APIs
| – EDRS APIs in the File part | – Registration Facility APIs
| – Management Central APIs (located in the Informa- | – Remote Procedure Call APIs
| tion Center) | – Server Support APIs
| – System-level environment variable APIs were added | – Software Product APIs
| to the Environment Variable APIs chapter in the | – User Interface APIs
| UNIX part | – Work Station Support APIs
| – 64-bit APIs were added to the Integrated File | – Miscellaneous APIs
| System APIs chapter of the UNIX part
| Pthread APIs are included with the other OS/400 APIs in
| – Posix semaphore APIs were added to the Interpro-
| the Information Center.
| cess Communication APIs chapter of the UNIX part
| Ÿ Throughout this book, APIs and exit programs have
| The AS/400 Information Center is located at the fol-
| been added and enhanced.
| lowing URL:
| http://publib.boulder.ibm.com/html/as4ðð/infocenter.html Integrated Netfinity Server for AS/400 is the new name for
file server I/O processor and FSIOP.
| Ÿ A new chapter listing the various values for errno was
| added to the UNIX part. A vertical line (|) to the left of the text indicates a change or
| Ÿ The System API Reference book is moving to the Infor- addition.
| mation Center in stages. The following parts have
| moved to the Information Center as of this release:

 Copyright IBM Corp. 1998, 1999 xxxi

xxxii AS/400 System API Reference V4R4
 Introduction

Part 1. Introduction to the OS/400 Callable APIs

Chapter 1. Application Programming Omitted Parameters . . . . . . . . . . . . . . . . . 2-4

Interfaces—Introduction . . . . . . . . . . . . . . . 1-1 User Space Format for List APIs . . . . . . . . . . . . 2-4
Compatibility with Future Releases . . . . . . . . . . . 1-1 General Data Structure . . . . . . . . . . . . . . . 2-4
Summary of OS/400 APIs . . . . . . . . . . . . . . . 1-1 Common Data Structure Formats . . . . . . . . . . 2-4
APIs Described in This Book . . . . . . . . . . . . 1-1 Generic Header Format 0100 . . . . . . . . . . 2-4
Generic Header Format 0300 . . . . . . . . . . 2-4
Chapter 2. Programming Tips for Using OS/400 Field Descriptions . . . . . . . . . . . . . . . . 2-5
APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 List Sections . . . . . . . . . . . . . . . . . . . . . 2-5
Language Selection Considerations . . . . . . . . . . 2-1 Partial List Considerations . . . . . . . . . . . . . . 2-6
Data Types and Parameter Coding . . . . . . . . . . 2-2 API Error Reporting . . . . . . . . . . . . . . . . . . . 2-6
Data Structures and the QSYSINC Library . . . . . 2-2 Error Code Parameter . . . . . . . . . . . . . . . . 2-6
Character Data . . . . . . . . . . . . . . . . . . . 2-3 Format ERRC0100 . . . . . . . . . . . . . . . . 2-6
Binary Data . . . . . . . . . . . . . . . . . . . . . 2-3 Format ERRC0200 . . . . . . . . . . . . . . . . 2-6
Passing Parameters . . . . . . . . . . . . . . . . . 2-3 Field Descriptions . . . . . . . . . . . . . . . . 2-7
Input and Output Parameters . . . . . . . . . . . . 2-3 Format of Open List Information . . . . . . . . . . . . 2-7
Offset Values and Lengths . . . . . . . . . . . . . 2-3 Field Descriptions . . . . . . . . . . . . . . . . . . 2-7
Offset versus Displacement Considerations for Path Name Format . . . . . . . . . . . . . . . . . . . 2-8
Structures . . . . . . . . . . . . . . . . . . . . . 2-3 Field Descriptions . . . . . . . . . . . . . . . . . . 2-8
Optional Parameters . . . . . . . . . . . . . . . . . 2-4

 Copyright IBM Corp. 1998, 1999

Introduction

AS/400 System API Reference V4R4

 Introduction

Chapter 1. Application Programming Interfaces—Introduction

The OS/400 application programming interfaces (APIs) are APIs Described in This Book
for highly experienced programmers who create system
applications. For example, programmers can use the APIs to This book presents the APIs in major functional categories,
create machine interface (MI) programs and applications for such as objects and work management, which correspond to
deleting outdated objects. However, you can also use some the parts of this book.
APIs for unique requirements.
For a complete list of APIs in each part, see the table of con-
The APIs are directly callable from high-level language pro- tents at the beginning of this book or the partial table of con-
grams. They allow you to: tents at the beginning of each part. To find a specific API,
either search the softcopy bookshelf or see the printed
Ÿ Provide better performance when getting system infor-
book's index.
mation or when using system functions than is provided
by control language (CL) commands or output file In brief, the major parts of the book and their contents are as
support. follows:
Ÿ Use system information and functions that are not avail-
able through CL commands. Part 1, “Introduction to the OS/400 Callable APIs.” This
introduction provides an overview of the APIs. It also
Ÿ Use calls from high-level languages to these interfaces. describes standard API parameters and formats, and dis-
cusses considerations in using the APIs in your programs.

Compatibility with Future Releases Part 2, “Backup and Recovery APIs.” These APIs list the
contents of a save file and save a list of objects. This part
In future releases, IBM intends that one of the following will also contains exit programs for storage extension and tape
be true: management.
Ÿ If additional input or output parameters are provided for
| Part 3, “Client Management Support APIs.” This part has
any of the APIs, the new parameters will be placed after
| moved to the AS/400 Information Center.
the current parameters and will be optional parameters.
The existing APIs will continue to work without any These APIs allow you to add and remove clients to and from
changes. the AS/400, update client information, and refresh client infor-
Ÿ If an additional data structure is provided, a new format mation on the AS/400 with the information stored at the
(layout of that data structure) will be created. client. The exit programs notify you when these API func-
tions have been completed. A Lotus Notes exit program pro-
Ÿ New information may be added to the end of an existing
vides the capability of processing an SQL table of all
format.
changes that occurred in the Notes database that is being
It is IBM's intention that the APIs will continue to work as shadowed from DB2 UDB for AS/400.
they originally worked and any existing applications that use
| Part 4, “Cluster APIs.” These APIs define an AS/400
the APIs will continue to work without changes. However,
| cluster of one or more systems, called nodes, manage the
significant architectural changes may necessitate incompat-
| membership and status of nodes in the cluster, specify the
ible changes.
| location of replicated objects, data, and applications within
To ensure better compatibility with future releases, you | the cluster, and provide for automatic recovery from failures
should retrieve and use all of the following when you work | within the cluster.
with user spaces generated by list APIs:
Part 5, “Communications APIs.” This part provides the
Ÿ Offset values to the list data section information needed to write user-defined communications
Ÿ Size of the list data section applications, programming examples, and debugging infor-
mation. This part includes the data stream translation APIs,
Ÿ Number of list entries which allow a user-written application program that creates
Ÿ Size of each entry 3270 data streams to run on an AS/400 system using 5250
data streams. This part also includes the OptiConnect APIs,
which can be used to move user data between two or more
Summary of OS/400 APIs AS/400 systems that are connected by an OptiConnect fiber-
optic bus.
Most OS/400 APIs are described in this book. However, a
few special-purpose APIs are described in other books; for
example, the REXX APIs. The following section outlines the
APIs described in this book.

 Copyright IBM Corp. 1998, 1999 1-1

 Introduction

Part 6, “Configuration APIs.” These APIs get information These APIs create, manipulate, and delete user spaces, user
about the configuration status of the system and about indi- indexes, and user queues. They send, receive, and clear
vidual configuration descriptions. entries on a data queue and retrieve data queue information.
They also change, list, rename, and retrieve information
Part 7, “Debugger APIs.” These APIs can be used to write about AS/400 objects.
debuggers for the AS/400 system.
Part 21, “Office APIs.” These APIs work with system distri-
Part 8, “Directory Services APIs.” The Lightweight Direc- bution directory data and with document handling. This part
tory Access Protocol (LDAP) client APIs can be used to also includes the OfficeVision exit programs, the AnyMail/400
access LDAP-enabled directories in a network. This part also Mail Server Framework APIs, and the SNADS File Server
includes administrative and configuration APIs for the OS/400 Object APIs.
Directory Services feature.
Part 22, “Operational Assistant APIs.” These APIs provide
Part 9, “Dynamic Screen Manager APIs.” These APIs access to the Operational Assistant functions.
provide the screen I/O interfaces for Integrated Language
Environment (ILE) high-level languages. Part 23, “Performance Collector APIs.” These APIs
describe the performance collector APIs and the performance
Part 10, “Edit Function APIs.” These APIs create and use monitor exit program.
edit masks.
Part 24, “Print APIs.” These APIs retrieve information and
Part 11, “File APIs.” These APIs retrieve information about manipulate spooled files.
files.
| Part 25, “Problem Management APIs.” This part has
| Part 12, “Hardware Resource APIs.” This part has moved | moved to the AS/400 Information Center.
| to the AS/400 Information Center.
These APIs offer you the ability to write problem manage-
These APIs allow you to work with hardware resources such ment solutions, improve serviceability, and manage your own
as searching resource entry information, retrieving resource applications.
information, and changing resource entry information.
Part 26, “Program and CL Command APIs.” These APIs
| Part 13, “Hierarchical File System APIs.” This part has create programs, retrieve program information, list and
| moved to the AS/400 Information Center. retrieve module information, activate bound programs,
resolve pointers to exports, and retrieve command informa-
These APIs let you work with directories and files in hierar- tion.
chical file systems (HFSs). This part also includes the HFS
exit programs. | Part 27, “Registration Facility APIs.” This part has moved
| to the AS/400 Information Center.
Part 14, “High-Level Language APIs.” These APIs com-
municate with compilers, and the DB2 for AS/400 SQL and These APIs provide the capability (1) to register and dereg-
COBOL/400 languages. ister exit points with the registration facility, (2) to add and
remove exit programs to and from the registration facility
Part 15, “Integrated Language Environment (ILE) CEE repository, (3) to retrieve exit point and exit program informa-
APIs.” These APIs contain the CEE and CEE4 Integrated tion, and (4) to designate the order in which exit programs
Language Environment (ILE) bindable APIs. are called.
Part 16, “Journal and Commit APIs.” This part contains | Part 28, “Remote Procedure Call APIs.” This part has
the journal and commitment control APIs, which allow you to | moved to the AS/400 Information Center.
add and remove your own commitment resources.
These APIs enable distributed applications to communicate
Part 17, “Message Handling APIs.” These APIs allow with each other by using the SUN RPC protocol. On the
applications to work with AS/400 messages. AS/400, these APIs can be used to easily separate and dis-
tribute client applications from the server.
Part 18, “National Language Support APIs.” These APIs
work with the national language support (NLS) functions, Part 29, “Security APIs.” These APIs manage system-level
such as sort and code conversion. The CDRA APIs are jobs, allowing your programs to run under different user pro-
included also. files without compromising system security. APIs are pro-
vided to retrieve security information. This part includes the
Part 19, “Network Management APIs.” These APIs handle
NetWare Authentication Entry APIs, which provide a means
alertable messages, work with problem logs, and use the
to automatically log you on to a server when you request a
SNA/Management Services Transport.
NetWare function (for example, file or print). The digital cer-
| Part 20, “Object APIs.” This part has moved to the AS/400
| Information Center.

1-2 AS/400 System API Reference V4R4

 Introduction

tificate management APIs, user function registration APIs, and to build screens. This part also includes the user inter-
and validation list APIs are also contained in this part. face manager exit programs.

| Part 30, “Server Support APIs.” This part has moved to Part 34, “Virtual Terminal APIs.” These APIs provide infor-
| the AS/400 Information Center. mation needed to use the virtual terminal (VT) APIs, which
allow an AS/400 application program to interact with an
These APIs allow personal computers to access file and print AS/400 system that is performing work station input/output
resources on the AS/400 by using the networking support (I/O).
provided with their operating systems. This part also
includes the AS/400 Dynamic Host Configuration Protocol Part 35, “Work Management APIs.” These APIs perform
(DHCP) server exit programs. The user-supplied exit pro- functions that are used in a wide variety of applications.
grams can provide validation of incoming client requests and These APIs retrieve and manipulate:
notification when IP addresses are assigned or released.
Jobs
| Part 31, “Software Product APIs.” This part has moved to Subsystem storage pools
| the AS/400 Information Center.
Subsystem job queues
These APIs work with software products and program tempo- Data areas
rary fixes (PTFs) on your system.
Network attributes
Part 32, “UNIX-Type APIs.” This part contains the following System status
groups of APIs:
System values
Environment variable
Flight recorder
Integrated file system
| Part 36, “Work Station Support APIs.” This part has
Interprocess communication
| moved to the AS/400 Information Center.
Problem determination
These APIs allow you to use the type-ahead and attention
Signal
key buffering functions in your applications.
SNMP subagent
| Part 37, “Miscellaneous APIs.” This part has moved to the
SNMP manager
| AS/400 Information Center.
Sockets
These APIs remove bookmarks from a course, convert date
Secure Sockets Layer (SSL)
and time, start pass-through, and retrieve data on a target
Process related system. This part also includes APIs that process open lists.
These APIs allow you to get list entries. to find entry
XA APIs for DB2/400
numbers in lists and in message lists, to find field numbers in
| Part 33, “User Interface APIs.” This part has moved to the lists, to retrieve server job information, and to close lists.
| AS/400 Information Center.
Part 38, “Reference Information.” This part includes
These APIs handle various aspects of the user interface, several appendixes that contain programming examples, a
allowing your applications to display help, display a chart of APIs and the public authority for each, and a chart of
command line window, convert date and time formats, control OS/400 APIs by release. This part also includes a bibli-
keyboard buffering, display screens and pop-up windows, ography of related books and the index.

Chapter 1. Application Programming Interfaces—Introduction 1-3

Introduction

1-4 AS/400 System API Reference V4R4

 Language Selection Considerations

Chapter 2. Programming Tips for Using OS/400 APIs

This chapter explains how to use the APIs included in this
book. The chapter covers these topics:
Language Selection Considerations
Ÿ Language selection considerations You can use APIs with all the languages available on AS/400
Ÿ Data types and parameter coding business computing systems, except for the ILE APIs. ILE
APIs that are implemented as service programs (*SRVPGM)
Ÿ User space format for list APIs can be accessed only by ILE languages. In some cases, a
Ÿ API error reporting program (*PGM) interface is provided so that non-ILE lan-
guages can access the function.
Ÿ Open list information structure
Ÿ Path name structure Some APIs also require that particular data types and partic-
ular parameter passing conventions be used. Figure 2-1
shows the languages available on the AS/400 system and
the data types that they provide.

Figure 2-1. Language Selection Considerations — Data Types

Excep-
Float- tion
Poin- Binary Binary Char- Zoned Packed ing Struc- Single Han-
Language1 ters 2 4 acter Decimal Decimal Point tures Array dling
BASIC (PRPQ 5799-FPK) X X X X2 X2 X X X
ILE C X X X X X9 X X X X
VisualAge C++ for OS/400 X X X X X10 X X X X
CL X3 X3 X X X4 X4 X
ILE CL X5 X3 X3 X X X4 X4 X
COBOL X X X X X X X X X6
ILE COBOL X X X X X X X X X6
MI X X X X X X X X X X
Pascal (PRPQ 5799-FRJ) X X X X X7 X7 X X X X
PL/I (PRPQ 5799-FPJ) X X X X X X X X X X
REXX X X4 X4 X
RPG X X X X X X X X8
ILE RPG X X X X X X X X X X8
Notes:
1 You cannot develop Cross System Product (CSP) programs on an AS/400 system. However, you can develop CSP programs on a
System/370 system and run them on your AS/400 system.
2 Refer to the CNVRT$ intrinsic function.
3 There is no direct support, but the %BIN function exists on the Change Variable (CHGVAR) CL command to convert to and from binary.
4 There is no direct support, but you can use the substring capability to simulate structures and arrays.
5 There is no direct support, but pointers passed to a CL program are preserved.
6 COBOL and ILE COBOL programs cannot monitor for specific messages, but these programs can define an error handler to run when a
program ends because of an error.
7 There is no direct support, but you can use extended program model (EPM) conversion routines to convert to and from zoned and packed
decimal.
8 RPG programs cannot monitor for specific messages, but these programs turn on an error indicator when a called program ends with an error.
These programs can define an error handler to run when a program ends because of an error.
9 Packed decimal is implemented in ILE C with the decimal() data type.
10 Packed decimal is implemented in VisualAge C++ for OS/400 with the Binary Coded Decimal (BCD) class. The BCD class is the C++ imple-
mentation of the C-language's decimal(). The BCD object can be used in API calls because it is binary compatible with the decimal() data type.

Figure 2-2 shows the languages available on the AS/400 Figure 2-2 (Page 1 of 2). Language Selection Considerations
system and the parameter support that they provide. For — Call Conventions
more information, see the reference manual for the specific Function Pass
programming language that you plan to use. Return Pass by by
Language1 Values2 Reference Value
BASIC X
ILE C X X X
VisualAge C++ for OS/400 X X X

 Copyright IBM Corp. 1998, 1999 2-1

Data Types and Parameter Coding

Figure 2-2 (Page 2 of 2). Language Selection Considerations Figure 2-3. Include Files Shipped with the QSYSINC Library
— Call Conventions
Oper- Lan- File Name Member Name
Function Pass ating guage (Header File)
Return Pass by by Envi-
Language1 Values2 Reference Value
ronment
CL X
OPM ILE C1 H OPM API program
ILE CL X APIs name
COBOL X 3
RPG QRPGSRC OPM API program
ILE COBOL X X X name or OPM API
MI X X program name with
Pascal X
the letter E
replacing the letter
PL/I X Q for members con-
REXX X taining array defi-
RPG X nitions
ILE RPG X X X ILE QRPGLESRC OPM API program
Notes:
RPG name
1 You cannot develop Cross System Product (CSP) pro- COBOL QLBLSRC OPM API name
grams on an AS/400 system. However, you can develop
ILE QCBLLESRC OPM API program
CSP programs on a System/370 and run them on your
AS/400 system. COBOL name
2 Return values are used by the UNIX-type APIs and the ILE ILE C H Service program
Dynamic Screen Manager (DSM) APIs.
3 APIs name or API
COBOL provides a by-content phrase, but it does not have
the same semantics as ILE C pass-by-value. program name2
ILE QRPGLESRC Service program
RPG name or API
program name2
Data Types and Parameter Coding
ILE QCBLLESRC Service program
COBOL name or API
The following sections describe a variety of API coding con-
program name2
siderations, covering these topics:
UNIX ILE C ARPA Industry defined
Ÿ Data structures and the QSYSINC library type
ILE C H Industry defined
Ÿ Character and binary data
ILE C NET Industry defined
Ÿ Passing parameters
ILE C NETINET Industry defined
Ÿ Input and output parameters ILE C NETNS Industry defined
Ÿ Offset values and lengths ILE C SYS Industry defined
Ÿ Displacement versus offset considerations for structures Notes:
Ÿ Optional parameters 1 CEE ILE APIs are included in this part of the
table.
Ÿ Omitted parameters 2 The API can be either bindable when you use the
service program name or callable when you use
the API program name.
Data Structures and the QSYSINC Library
The QSYSINC (system include) library provides all source Besides the includes for specific APIs, other includes existing
includes shipped with the AS/400 system for OS/400 APIs. in the QSYSINC library follow:
This optionally installed library is fully supported, which QLIEPT and QUSEPT
means you can write APARs if you find errors in the Allow C-language application programs to call
includes. OPM APIs directly through the system entry
point table
You can install this library by using the GO LICPGM func-
QUSGEN Defines the generic header for list APIs
tions of OS/400. Select the Install Licensed Programs option
QUSEC Contains the structures for the error code
on the Work with Licensed Programs display and the OS/400
parameter
Openness Includes option on the Install Licensed Programs
Qxx Provides common structures that are used by
display.
multiple APIs (where the xx is the component
The naming conventions for the includes are the same as identifier, for example, QMH, QSY, and so
either the OPM API or the ILE service program name. If forth)
both exist, the include has both names.

2-2 AS/400 System API Reference V4R4

 Data Types and Parameter Coding

The include files that are shipped with the system define only ILE C) to ensure that these conventions are followed. Refer
the fixed portions of the formats. You must define the to the appropriate language documentation for instructions.
varying-length fields. The QSYSINC include files are read- The parameter passing convention of pass-by-reference can
only files. If you use a structure that contains one or more be used in all programming languages. Some of the
varying-length fields, you need to copy the include file to your UNIX-type APIs require pass-by-value parameter passing.
library and edit your copy. Uncomment the varying-length VisualAge C++ for OS/400 also supports pass-by-value
fields in your copy of the include file, and specify the actual parameter passing.
lengths you want.

Exit programs only have an include if the exit program con- Input and Output Parameters
tains a structure. The QSYSINC member name of these
API parameters can be used for input or output. Some
includes is provided in the parameter box for the applicable
parameters contain both input and output fields; these are
exit programs.
identified as input/output (I/O) parameters in the API param-
For development of client-based applications, integrated-file- eter tables.
system symbolic links to QSYSINC openness includes are
Input parameters and fields are not changed by the API.
also provided in the /QIBM/include path.
They have the same value on the return from the API call as
they do before the API call. In contrast, output parameters
Character Data and fields are changed. Any information that an API caller
(either an application program or an interactive entry on the
In the API parameter tables in this book, CHAR(*) represents display) places in an output parameter or output field before
character data that has: the call will be lost on the return from the call.
Ÿ A type that is not known, such as character, binary, and
so on Offset Values and Lengths
Ÿ A length that might not be known or is based on another
value (for example, a length you specify) When you are using an API that generates a list into a user
space, you should use the offset values and lengths returned
by the API in the generic user space header to step through
Binary Data the list instead of specifying what the current version of the
API returns. This is because:
In the API parameter tables in this book, BINARY(2) and
BINARY(4) represent numeric data. These parameters must Ÿ The offset values to the different sections of the user
be signed, 2- or 4-byte numeric values with a precision of 15 space may change in future releases.
(halfword) or 31 (fullword) bits and one high-order bit for the Ÿ The length of the entries in the list data section of the
sign. Numeric parameters that must be unsigned 4-byte user space may change in future releases.
numeric values are explicitly defined as
BINARY(4) UNSIGNED. As long as your HLL application program uses the offset
values and lengths returned in the generic header of the user
When you develop applications that use binary values, be space, your program will run in future releases of the OS/400
aware that some high-level languages allow the definition of licensed program.
binary variables by using precision and not length. For
Note: While your application program should use the length
example, an RPG definition of binary length 4 specifies a
returned in the generic header to address subsequent list
precision of 4 digits, which can be stored in a 2-byte binary
entries, your application program should only retrieve as
field. For API BINARY(4) fields, RPG developers should use
many bytes as the application program has allocated storage
one of the following:
for.
Ÿ Positional notation
Ÿ A length of 5 to 9 in order to allocate a 4-byte binary Offset versus Displacement
field
Considerations for Structures
Ÿ A length of 10 in order to allocate a 4-byte integer field
You will find the terms offset and or displacement in some of
the AS/400 APIs. For example, the Retrieve Data Queue
Passing Parameters Message (QMHRDQM) API uses offset; the List Objects
(QUSLOBJ) API uses displacement.
When you call an API, the protocol for passing parameters is
to typically pass a space pointer that points to the information An offset is the distance from the beginning of an object
being passed. (This is also referred to as pass-by- (user spaces and receiver variables) to the beginning of a
reference.) This is the convention used by the control lan- particular field. However, a displacement is the distance
guage (CL), RPG, and COBOL compilers. Care must be from the beginning of a specific record, block, or structure to
used in those languages that support pass-by-value (such as the beginning of a particular field.

Chapter 2. Programming Tips for Using OS/400 APIs 2-3

User Space Format for List APIs

Optional Parameters All offset values are from the beginning of the user space.
The offset values for the Dump Object (DMPOBJ) and Dump
Some of the APIs have optional parameters; the optional System Object (DMPSYSOBJ) commands also start at the
parameters form a group. You must either include or beginning of the user space. To get the correct starting posi-
exclude the entire group. You cannot use just one of these tion for the Change User Space (QUSCHGUS) and Retrieve
parameters by itself. In addition, you must include all pre- User Space (QUSRTVUS) APIs, add one to the offset value.
ceding parameters.

You may call the API in two ways: either with the optional Common Data Structure Formats
parameters or without the optional parameters. The following tables show the generic user space layout.
Format 0100 shows the format for an original program model
(OPM) layout. Format 0300 shows the format for an Inte-
Omitted Parameters grated Language Environment (ILE) model layout. The fields
are described in detail after the table.
The Integrated Language Environment (ILE) APIs may have
parameters that can be omitted. When these parameters are Generic Header Format 0100
omitted, you must pass a null pointer.
Offset
Dec Hex Type Field
User Space Format for List APIs
0 0 CHAR(64) User area
To provide a consistent design and use of the user space 64 40 BINARY(4) Size of generic header
(*USRSPC) objects, the OS/400 list APIs use a common
68 44 CHAR(4) Structure's release and level
data structure. The list APIs are those APIs that generate a
list unique to that API. This includes any list API that has a 72 48 CHAR(8) Format name
user space parameter, such as the List Spooled Files and 80 50 CHAR(10) API used
List Objects APIs.
90 5A CHAR(13) Date and time created
103 67 CHAR(1) Information status
General Data Structure
104 68 BINARY(4) Size of user space used
The list APIs use the following general data structure: 108 6C BINARY(4) Offset to input parameter
section
Header
┌────────────────────────────────────┐ ┌─────────────────────────┐ 112 70 BINARY(4) Size of input parameter
+ðð│ │ │ │
│ 64─Byte User Area │ │ │ section
│ │ │ │
├────────────────────────────────────┤ ┌───5│ Input Parameter Section │ 116 74 BINARY(4) Offset to header section
+4ð│ Size of Generic Header │ │ │ │
├────────────────────────────────────┤ │ ' '
│ │ │ ' '
120 78 BINARY(4) Size of header section
│ Generic Header │ │ ├─────────────────────────┤
│ │ │ │ │ 124 7C BINARY(4) Offset to list data section
│ │ │
+6C│ Offset to Input Parameter Section ─┼────┘ 128 80 BINARY(4) Size of list data section
│ │ │ │
+7ð│ Input Parameter Section Size │ ├─────────────────────────┤
│ │ │ │
132 84 BINARY(4) Number of list entries
+74│ Offset to Header Section───────────┼────────5│ Header Section │
│ │ │ │ 136 88 BINARY(4) Size of each entry
+78│ Header Section Size │ │ │
│ │ │ │ 140 8C BINARY(4) CCSID of data in the list
+7C│ Offset to List Data Section────────┼────┐ │ │
│ │ │ │ │ entries
+8ð│ List Data Section Size │ │ │ │
│ │ │ ' ' 144 90 CHAR(2) Country ID
+84│ Number of List Entries │ │ ' '
│ │ │ │ │ 146 92 CHAR(3) Language ID
+88│ Size of Each Entry │ │ ├─────────────────────────┤
│ │ │ │ │
+8C│ CCSID of data in the user space │ │ 149 95 CHAR(1) Subsetted list indicator
│ │ │
+9ð│ Country ID │ │ │ │ 150 96 CHAR(42) Reserved
│ │ │ │ List Data Section │
+93│ Language ID │ │ │─────────────────────────┤
│ │ └───5│ Entry 1 │
+95│ Subsetted list indicator │ │─────────────────────────┤ Generic Header Format 0300
│ │ │ Entry 2 │
+Cð│ API entry point name │ │─────────────────────────┤
│ │ │ Entry 3 │
│ │ │ │ Offset
└────────────────────────────────────┘ ' '
' ' Dec Hex Type Field
│ │
│─────────────────────────┤ 0 0 Everything from the 0100
│ Last Entry │
│─────────────────────────┤ format
│ │
192 C0 CHAR(256) API entry point name

2-4 AS/400 System API Reference V4R4

 User Space Format for List APIs

Size of generic header. The size of the generic header, in

Offset
bytes. This does not include the size of the user area; refer
Dec Hex Type Field to “General Data Structure” on page 2-4 for a diagram
448 1C0 CHAR(128) Reserved showing the user area.

Size of header section. The size of the header section, in

Field Descriptions: This topic describes the fields bytes.
returned in further detail.
Size of input parameter section. The size of the input
API entry point name. The name of the ILE bindable API
parameter section, in bytes.
entry point that generated the list.
Size of list data section. The size of the list data section,
API used. For format 0100, this is the name of the original
in bytes. For formats that return variable length records, this
program model (OPM) API that generated the list. For
is zero.
format 0300, this is a reserved field. See the API entry point
name field for the API used. Size of user space used. The combined size of the user
area, generic header, input parameter section, header
CCSID of the data in the list entries. The coded character
section, and list data section, in bytes. This determines what
set ID for data in the list entries.
is changed in the user space.
Country ID. The country identifier of the data written to the
Structure's release and level. The release and level of the
user space.
structure. The value of this field is 0100. List APIs put this
Date and time created. The date and time when the list value into the user space.
was created. The 13 characters are:
Subsetted list indicator. A flag that indicates if the data
1 Century, where 0 indicates years 19xx and 1 selected from the list API can be stored in that format.
indicates years 20xx.
0 List is not subsetted; all of the information can
2-7 The date, in YYMMDD (year, month, day)
be stored in the format.
format.
1 List is subsetted. For example, integrated file
8-13 The time of day, in HHMMSS (hours, minutes,
system names may be longer than the avail-
seconds) format.
able area in the format. See the API specific
Format name. The name of the format for the list data documentation for detail.
section.
User area. An area within the user space that is provided
Information status. Whether or not the information is com- for the caller to use to communicate system programmer-
plete and accurate. Possible values are: related information between applications that use the user
space.
C Complete and accurate.
I Incomplete. The information you received is
not accurate or complete. List Sections
P Partial but accurate. The information you
received is accurate, but the API had more Each list API provides the following sections:
information to return than the user space
could hold. See “Partial List Considerations” List Section Contents
on page 2-6 for more information about partial Input parameter An exact copy of the parameters coded
lists. section in the call to the API. In general, this
section contains all the parameters
Language ID. The language identifier of the data written to available.
the user space. Header section Parameter feedback and global informa-
tion about each object. Some APIs do
Number of list entries. The number of fixed-length entries not use this section; in those cases, the
in the list data section. value of the size-of-header-section field
is zero.
Offset to (all) section. The byte offset from the beginning
List data section The generated list data. All entries in
of the user space to the start of the section. the list section are the same length.

Reserved. An ignored field.

When you retrieve list entry information from a user space,
Size of each entry. The size of each list data section entry, you should use the entry size designated in your application.
in bytes. All entries are the same size. For formats that To get the next entry, use the entry size returned in the
return variable length records, this is zero. generic header. The size of each entry may be padded at
the end. If you do not use the entry size, the result may not

Chapter 2. Programming Tips for Using OS/400 APIs 2-5

API Error Reporting

be valid. For examples of how to process lists, see Error Code Parameter
Appendix A, “Examples.”
Most OS/400 APIs include an error code parameter to return
error codes and exception data to the application. The error
Partial List Considerations code parameter is a variable-length structure that contains
Some APIs may be able to return more information to the the information associated with an error condition. The error
application than fits in a receiver variable or a user space. code parameter can be one of two variable-length structures,
The information returned is correct, but not complete. format ERRC0100 or format ERRC0200.

If the list information is not complete, the first item and pos- In format ERRC0100, one field in that structure is an INPUT
sibly the second item occur: field; it controls whether an exception is returned to the appli-
cation or the error code structure is filled in with the excep-
Ÿ A P is returned in the information status field of the tion information. When the bytes provided field is greater
generic user space layout; refer to “General Data than or equal to 8, the rest of the error code structure is filled
Structure” on page 2-4. in with the OUTPUT exception information associated with
Ÿ The API supports a continuation handle. the error. When the bytes provided INPUT field is zero, all
other fields are ignored and an exception is returned.
If an indicator of a partial list is returned, the application
should call the API again with the continuation handle in the Format ERRC0200 must be used if the API caller wants con-
list header section of the API and specify that the list begin vertible character (CCHAR) support. Format ERRC0200
with the next entry to be returned. contains two INPUT fields. The first field, called the key
Note: If this is the first time the API is attempting to return field, must contain a -1 to use CCHAR support. When the
information, the continuation handle must be set to blanks. If bytes provided field is greater than or equal to 12, the rest of
the API does not support a continuation handle, you need to the error code structure is filled in with the OUTPUT excep-
call the API again and use more restrictive values for the tion information associated with the error. When the bytes
parameters. provided INPUT field is zero, all other fields are ignored and
an exception is returned.
For information about how list APIs make use of user
spaces, see “User Spaces” in the book System API Program- For some APIs, the error code parameter is optional. If you
ming. For information about how retrieve APIs make use of do not code the optional error code parameter, the API
receiver variables and to determine whether the returned returns diagnostic and escape messages. If you do code the
information is complete, see “Receiver Variables” in the book optional error code parameter, the API returns only escape
System API Programming. messages or error codes; it never returns diagnostic mes-
sages.

The structure of the error code parameter is as follows. The

API Error Reporting fields are described in detail after the tables.
The following sections discuss an API error code parameter, Note: The error code structures for both formats are pro-
which is common to all of the system APIs, give examples vided in the QUSEC include file in the QSYSINC library.
for its use, and explain how to use the job log to diagnose Includes exist in the following source physical files:
API errors. QRPGSRC, QRPGLESRC, QLBLSRC, QCBLLESRC, and H.

Notes: Format ERRC0100

1. The ILE CEE APIs use feedback codes and conditions.
See “OS/400 Messages and the ILE CEE API Feedback Offset
Code” on page 39-5 for information about how feedback Dec Hex Use Type Field
codes are used with the ILE CEE APIs.
0 0 INPUT BINARY(4) Bytes provided
2. The UNIX-type APIs in Part 32, “UNIX-Type APIs” on 4 4 OUTPUT BINARY(4) Bytes available
page 75-3 and in Chapter 50, “National Language Data
Conversion APIs” on page 50-1 use errno to report error 8 8 OUTPUT CHAR(7) Exception ID
conditions. 15 F OUTPUT CHAR(1) Reserved
16 10 OUTPUT CHAR(*) Exception data

Format ERRC0200

Offset
Dec Hex Use Type Field
0 0 INPUT BINARY(4) Key

2-6 AS/400 System API Reference V4R4

 Open List Format

Exception ID. The identifier for the message for the error
Offset
condition.
Dec Hex Use Type Field
4 4 INPUT BINARY(4) Bytes provided Key. The key value that enables the message handler error
function if CCHAR support is used. This value should be -1
8 8 OUTPUT BINARY(4) Bytes available
if CCHAR support is expected.
12 C OUTPUT CHAR(7) Exception ID
19 13 OUTPUT CHAR(1) Reserved
Length of the exception data. The length, in bytes, of the
exception data returned in the error code.
20 14 OUTPUT BINARY(4) CCSID of the
CCHAR data Offset to the exception data. The offset from the beginning
24 18 OUTPUT BINARY(4) Offset to the of the error code structure to the exception data in the error
exception data code structure.
28 1C OUTPUT BINARY(4) Length of the
exception data Reserved. A 1-byte reserved field.

OUTPUT CHAR(*) Exception data

Format of Open List Information

Field Descriptions: This topic describes the fields
returned in further detail. The format of the open list information is common across
many of the open list APIs. The open list APIs return data
Bytes available. The length of the error information avail- for use by the process open list APIs. The process open list
able to the API to return, in bytes. If this is 0, no error was APIs are located in the Miscellaneous part whereas the open
detected and none of the fields that follow this field in the list APIs can be found in the applicable sections. For
structure are changed. example, the Open List of Messages (QGYOLMSG) API is
located in the Messages part.
Bytes provided. The number of bytes that the calling appli-
cation provides for the error code. If the API caller is using The following shows the format of the list information param-
format ERRC0100, the bytes provided must be 0, 8, or more eter in the open list APIs. For a detailed description of each
than 8. If more than 32 783 bytes (32KB for exception data field, see the “Field Descriptions.”
plus 16 bytes for other fields) are specified, it is not an error,
but only 32 767 bytes (32KB) can be returned in the excep-
Offset
tion data.
Dec Hex Type Field
If the API caller is using format ERRC0200, the bytes pro- 0 0 BINARY(4) Total records
vided must be 0, 12, or more than 12. If more than 32 799
4 4 BINARY(4) Records returned
bytes (32KB for exception data plus 32 bytes for other fields)
are specified, it is not an error, but only 32 767 bytes (32KB) 8 8 CHAR(4) Request handle
can be returned in the exception data. 12 C BINARY(4) Record length
0 If an error occurs, an exception is returned to 16 10 CHAR(1) Information complete indi-
the application to indicate that the requested cator
function failed. 17 11 CHAR(13) Date and time created
≥8 If an error occurs, the space is filled in with
30 1E CHAR(1) List status indicator
the exception information. No exception is
returned. This only occurs if format 31 1F CHAR(1) Reserved
ERRC0100 is used. 32 20 BINARY(4) Length of information
≥12 If an error occurs, the space is filled in with returned
the exception information. No exception is 36 24 BINARY(4) First record in receiver vari-
returned. This only occurs if format able
ERRC0200 is used.
40 28 CHAR(40) Reserved
CCSID of the CCHAR data. The coded character set identi-
fier (CCSID) of the convertible character (CCHAR) portion of
the exception data. The default is 0. Field Descriptions
0 The default job CCSID. Date and time created. The date and time when the list
CCSID A valid CCSID number. The valid CCSID was created. The 13 characters are:
range is 1 through 65535, but not 65534.
1 Century, where 0 indicates years 19xx and 1
Exception data. A variable-length character field that con- indicates years 20xx.
tains the insert data associated with the exception ID. 2-7 The date, in YYMMDD (year, month, day)
format.

Chapter 2. Programming Tips for Using OS/400 APIs 2-7

Path Name Format

8-13 The time of day, in HHMMSS (hours, minutes, Total records. The total number of records available in the
seconds) format. list.

First record in receiver variable. The number of the first

record returned in the receiver variable.
Path Name Format
Information complete indicator. Whether all requested
The path name format is common across application pro-
information has been supplied. Possible values follow:
gramming interfaces that work with objects that are sup-
C Complete and accurate information. All of the ported across file systems. These APIs require a path name
requested records have been returned in the to identify the object that the API will work with.
receiver variable.
I Incomplete information. An interruption The format of the path name is as follows. For a detailed
causes the receiver variable to contain incom- description of each field, see “Field Descriptions.”
plete information.
P Partial and accurate information. Partial infor- Offset
mation is returned when the receiver variable Dec Hex Use Type Field
is full and not all of the records requested are
0 0 INPUT BINARY(4) CCSID
returned.
4 4 INPUT CHAR(2) Country ID
Length of information returned. The size, in bytes, of the
6 6 INPUT CHAR(3) Language ID
information that is returned in the receiver variable.
9 9 INPUT CHAR(3) Reserved
List status indicator. The status of building the list. 12 C INPUT BINARY(4) Path type indicator

Possible values follow: 16 10 INPUT BINARY(4) Length of path

name
0 The building of the list is pending.
20 14 INPUT CHAR(2) Path name delim-
1 The list is in the process of being built.
iter character
2 The list has been completely built.
3 An error occurred when building the list. The 22 16 INPUT CHAR(10) Reserved
next call to the Get List Entries (QGYGTLE) 32 26 INPUT CHAR(*) Path name
API will cause the error to be signaled to the
caller of the QGYGTLE API.
4 The list is primed and ready to be built. The Field Descriptions
list will be built asynchronously by a server
job, but the server job has not necessarily The following section describes the path name format fields
started building the list yet. in further detail.

Record length. The length of each record of information CCSID. The CCSID (coded character set ID) the path name
returned. For variable length records, this value is set to is in. The possible values follow:
zero. For variable length records, you can obtain the length 0 Use the current job default CCSID.
of individual records from the records themselves. 1–65533 A valid CCSID in this range.
Records returned. The number of records that are returned Country ID. The country ID for the path name. The pos-
in the receiver variable. This number is the smallest of the sible values follow:
following values:
X'0000' Use the current job country ID.
Ÿ The number of records that will fit into the receiver vari- Country ID A valid country ID.
able.
Ÿ The number of records in the list. Language ID. The language ID for the path name. The
Ÿ The number of records that are requested. possible values follow:

Request handle. The handle of the request that can be X'000000' Use the current job language ID.
used for subsequent requests of information from the list. Language ID A valid language ID.
The handle is valid until the Close List (QGYCLST) API is
Length of path name. The length of the path name in
called to close the list, or until the job ends.
bytes.
Note: This field should be treated as a hexadecimal field. It
should not be converted from one CCSID to another, for Path name. Depending on the path type indicator field, this
example, EBCDIC to ASCII, because doing so could result in field contains either a pointer to a character string that con-
an unusable value. tains the path name, or a character string that contains the
path name.
Reserved. An ignored field.

2-8 AS/400 System API Reference V4R4

 Path Name Format

The path name must be an absolute path name or a relative Path type indicator. Whether the path name contains a
path name. An absolute path name is a path name that pointer or is a character string and whether the path name
starts with the path name delimiter, usually the slash (/) char- delimiter character is 1 or 2 characters long. The possible
acter. A relative path name is a path name that does not values follow:
start with the path name delimiter. When a relative name is
0 The path name is a character string, and the
specified, the API assumes that this path name starts at the
path name delimiter character is 1 character
current directory of the process that the API is running in.
long.
The dot and dot dot (. ..) directories are valid in the path
1 The path name is a pointer, and the path
name delimiter character is 1 character long.
name. The home directory, generally represented by using
the tilde character in the first character position of the path
2 The path name is a character string, and the
path name delimiter character is 2 characters
name, is not supported.
long.
Path name delimiter character. The delimiter character 3 The path name is a pointer, and the path
used between the element names in the path name. This is name delimiter character is 2 characters long.
in the same CCSID as the path name. The most common
Reserved. A reserved field that must be set to hexadecimal
delimiter is the slash (/) character. If the delimiter is 1 char-
zeros.
acter, the first character of the 2-character field is used.

Chapter 2. Programming Tips for Using OS/400 APIs 2-9

Path Name Format

2-10 AS/400 System API Reference V4R4

 Backup and Recovery

Part 2. Backup and Recovery APIs

Chapter 3. Backup and Recovery APIs . . . . . . . 3-1 Required Parameter Group . . . . . . . . . . . . 3-16
Backup and Recovery APIs—Introduction . . . . . . . 3-1 Format of the Generated List . . . . . . . . . . . 3-16
Backup and Recovery Exit Programs—Introduction . . 3-1 Input Parameter Section . . . . . . . . . . . . 3-16
Change Backup Schedule (QEZCHBKS) API . . . . . 3-2 Header Section . . . . . . . . . . . . . . . . . 3-17
Authorities and Locks . . . . . . . . . . . . . . . . 3-2 SAVF0100 Format . . . . . . . . . . . . . . . 3-17
Required Parameter Group . . . . . . . . . . . . . 3-2 SAVF0200 Format . . . . . . . . . . . . . . . 3-17
CBKS0100 Format . . . . . . . . . . . . . . . . . 3-2 SAVF0300 Format . . . . . . . . . . . . . . . 3-17
Field Descriptions . . . . . . . . . . . . . . . . . . 3-2 Field Descriptions . . . . . . . . . . . . . . . 3-17
Error Messages . . . . . . . . . . . . . . . . . . . 3-4 Error Messages . . . . . . . . . . . . . . . . . . 3-19
Change Job Media Library Attributes (QTACJMA) API 3-5 Open List of Objects to be Backed Up (QEZOLBKL)
Authorities and Locks . . . . . . . . . . . . . . . . 3-5 API . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Required Parameter Group . . . . . . . . . . . . . 3-5 Authorities and Locks . . . . . . . . . . . . . . . 3-20
CJMA0100 Format . . . . . . . . . . . . . . . . . 3-5 Required Parameter Group . . . . . . . . . . . . 3-20
Field Descriptions . . . . . . . . . . . . . . . . . . 3-6 Format of Receiver Variable . . . . . . . . . . . 3-20
Error Messages . . . . . . . . . . . . . . . . . . . 3-6 OBKL0100 Format . . . . . . . . . . . . . . . 3-20
Change Object Backup List (QEZCHBKL) API . . . . . 3-7 OBKL0200 Format . . . . . . . . . . . . . . . 3-21
Authorities and Locks . . . . . . . . . . . . . . . . 3-7 OBKL0600 Format . . . . . . . . . . . . . . . 3-21
Required Parameter Group . . . . . . . . . . . . . 3-7 Field Descriptions . . . . . . . . . . . . . . . . . 3-21
Format for Variable Length Records . . . . . . . . 3-7 Format of List Information . . . . . . . . . . . . . 3-21
Field Descriptions . . . . . . . . . . . . . . . . . . 3-7 Field Descriptions . . . . . . . . . . . . . . . . . 3-21
Valid Keys . . . . . . . . . . . . . . . . . . . . . . 3-8 Error Messages . . . . . . . . . . . . . . . . . . 3-22
Field Descriptions . . . . . . . . . . . . . . . . . . 3-8 Qp0lSaveStgFree()—Save Storage Free . . . . . . . 3-22
Folder Key Format . . . . . . . . . . . . . . . . . . 3-8 Parameters . . . . . . . . . . . . . . . . . . . . 3-23
Field Descriptions . . . . . . . . . . . . . . . . . . 3-8 Authorities . . . . . . . . . . . . . . . . . . . . . 3-24
Library Key Format . . . . . . . . . . . . . . . . . 3-8 Return Value . . . . . . . . . . . . . . . . . . . 3-24
Field Descriptions . . . . . . . . . . . . . . . . . . 3-8 Error Conditions . . . . . . . . . . . . . . . . . . 3-24
Error Messages . . . . . . . . . . . . . . . . . . . 3-8 Error Messages . . . . . . . . . . . . . . . . . . 3-26
| Create Media Definition (QSRCRTMD, Usage Notes . . . . . . . . . . . . . . . . . . . . 3-26
| QsrCreateMediaDefinition) API . . . . . . . . . . . . 3-9 Related Information . . . . . . . . . . . . . . . . 3-26
| Authorities and Locks . . . . . . . . . . . . . . . . 3-9 Example . . . . . . . . . . . . . . . . . . . . . . 3-26
| Required Parameter Group . . . . . . . . . . . . . 3-9 Restore from Application (QaneRsta) API . . . . . . 3-26
| Input Data Format . . . . . . . . . . . . . . . . . 3-10 Restrictions . . . . . . . . . . . . . . . . . . . . 3-26
| Field Descriptions for Input Data . . . . . . . . . 3-10 Authorities and Locks . . . . . . . . . . . . . . . 3-27
| Device Definition Format . . . . . . . . . . . . . 3-10 Required Parameter Group . . . . . . . . . . . . 3-27
| Field Descriptions for Device Definition . . . . . . 3-11 SVRS0100 Format . . . . . . . . . . . . . . . . 3-27
| Media File Definition Format . . . . . . . . . . . 3-11 Field Descriptions . . . . . . . . . . . . . . . 3-27
| Field Descriptions for Media File Definition . . . . 3-11 SRST0100 Format . . . . . . . . . . . . . . . . . 3-28
| Error Messages . . . . . . . . . . . . . . . . . . 3-11 Field Descriptions . . . . . . . . . . . . . . . 3-28
| Delete Media Definition (QSRDLTMD, Error Messages . . . . . . . . . . . . . . . . . . 3-29
| QsrDeleteMediaDefinition) API . . . . . . . . . . . 3-12 Restore Object (QsrRestore) API . . . . . . . . . . 3-29
| Authorities and Locks . . . . . . . . . . . . . . . 3-12 Authorities and Locks . . . . . . . . . . . . . . . 3-29
| Required Parameter Group . . . . . . . . . . . . 3-12 Required Parameter Group . . . . . . . . . . . . 3-29
| Error Messages . . . . . . . . . . . . . . . . . . 3-12 User Space Format . . . . . . . . . . . . . . . . 3-30
Dump Device (QTADMPDV) API . . . . . . . . . . . 3-12 Field Descriptions . . . . . . . . . . . . . . . . . 3-30
Required Parameter . . . . . . . . . . . . . . . . 3-13 Valid Keys . . . . . . . . . . . . . . . . . . . . . 3-30
Optional Parameter Group . . . . . . . . . . . . 3-13 Field Descriptions . . . . . . . . . . . . . . . . . 3-31
Examples . . . . . . . . . . . . . . . . . . . . . 3-14 Dependencies between Keys . . . . . . . . . . . 3-36
Error Messages . . . . . . . . . . . . . . . . . . 3-14 Relationship to RST Command . . . . . . . . . . 3-37
Free Object (QTAFROBJ) API . . . . . . . . . . . . 3-14 Error Messages . . . . . . . . . . . . . . . . . . 3-37
Authorities and Locks . . . . . . . . . . . . . . . 3-14 Retrieve Backup Detail (QEZRTBKD) API . . . . . . 3-37
Required Parameter Group . . . . . . . . . . . . 3-14 Authorities and Locks . . . . . . . . . . . . . . . 3-37
TAFO0100 Format . . . . . . . . . . . . . . . . . 3-14 Required Parameter Group . . . . . . . . . . . . 3-37
Field Descriptions . . . . . . . . . . . . . . . . . 3-15 RBKD0100 Format . . . . . . . . . . . . . . . . 3-38
Error Messages . . . . . . . . . . . . . . . . . . 3-15 Field Descriptions . . . . . . . . . . . . . . . . . 3-38
List Save File (QSRLSAVF) API . . . . . . . . . . . 3-15 Error Messages . . . . . . . . . . . . . . . . . . 3-38
Authorities and Locks . . . . . . . . . . . . . . . 3-15 Retrieve Backup History (QEZRTBKH) API . . . . . 3-38

 Copyright IBM Corp. 1998, 1999

 Backup and Recovery

Authorities and Locks . . . . . . . . . . . . . . . 3-39 Authorities and Locks . . . . . . . . . . . . . . . 3-71

Required Parameter Group . . . . . . . . . . . . 3-39 Required Parameter Group . . . . . . . . . . . . 3-71
RBKH0100 Format . . . . . . . . . . . . . . . . 3-39 User Space Format . . . . . . . . . . . . . . . . 3-72
RBKH0200 Format . . . . . . . . . . . . . . . . 3-40 Field Descriptions . . . . . . . . . . . . . . . . . 3-72
Field Descriptions . . . . . . . . . . . . . . . . . 3-40 Valid Keys . . . . . . . . . . . . . . . . . . . . . 3-72
Error Messages . . . . . . . . . . . . . . . . . . 3-43 Field Descriptions . . . . . . . . . . . . . . . . . 3-73
Retrieve Backup Options (QEZRTBKO) API . . . . . 3-43 Device Key Format . . . . . . . . . . . . . . . . 3-76
Authorities and Locks . . . . . . . . . . . . . . . 3-43 Field Descriptions . . . . . . . . . . . . . . . . . 3-76
Required Parameter Group . . . . . . . . . . . . 3-43 File Member Format . . . . . . . . . . . . . . . . 3-77
RBOH0100 Format . . . . . . . . . . . . . . . . 3-44 Field Descriptions . . . . . . . . . . . . . . . . . 3-77
RBKO0100 Format . . . . . . . . . . . . . . . . 3-44 Library Key Format . . . . . . . . . . . . . . . . 3-77
RBKO0200 Format . . . . . . . . . . . . . . . . 3-44 Field Descriptions . . . . . . . . . . . . . . . . . 3-77
Field Descriptions . . . . . . . . . . . . . . . . . 3-44 Object Information Format . . . . . . . . . . . . . 3-77
Error Messages . . . . . . . . . . . . . . . . . . 3-46 Field Descriptions . . . . . . . . . . . . . . . . . 3-77
Retrieve Backup Schedule (QEZRTBKS) API . . . . 3-46 Omit Object Information Format . . . . . . . . . . 3-78
Authorities and Locks . . . . . . . . . . . . . . . 3-46 Field Descriptions . . . . . . . . . . . . . . . . . 3-78
Required Parameter Group . . . . . . . . . . . . 3-46 Output Member Format . . . . . . . . . . . . . . 3-78
RBKS0100 Format . . . . . . . . . . . . . . . 3-47 Field Descriptions . . . . . . . . . . . . . . . . . 3-78
Field Descriptions . . . . . . . . . . . . . . . . . 3-47 Volume Identifier Format . . . . . . . . . . . . . 3-78
Error Messages . . . . . . . . . . . . . . . . . . 3-48 Field Descriptions . . . . . . . . . . . . . . . . . 3-78
Retrieve Device Capabilities (QTARDCAP) API . . . 3-48 Dependencies between Keys . . . . . . . . . . . 3-78
Authorities and Locks . . . . . . . . . . . . . . . 3-49 Relationship to SAVOBJ Command . . . . . . . . 3-79
Required Parameter Group . . . . . . . . . . . . 3-49 Error Messages . . . . . . . . . . . . . . . . . . 3-79
TAPE0100 Format . . . . . . . . . . . . . . . . . 3-49 Save to Application (QaneSava) API . . . . . . . . . 3-80
Field Descriptions . . . . . . . . . . . . . . . . . 3-51 Restrictions . . . . . . . . . . . . . . . . . . . . 3-80
Error Messages . . . . . . . . . . . . . . . . . . 3-55 Authorities and Locks . . . . . . . . . . . . . . . 3-80
Retrieve Device Information (QTARDINF) API . . . . 3-55 Required Parameter Group . . . . . . . . . . . . 3-80
Authorities and Locks . . . . . . . . . . . . . . . 3-56 SVRS0100 Format . . . . . . . . . . . . . . . . 3-81
Required Parameter Group . . . . . . . . . . . . 3-56 Field Descriptions . . . . . . . . . . . . . . . . . 3-81
TADS0100 Format . . . . . . . . . . . . . . . . . 3-56 SRST0100 Format . . . . . . . . . . . . . . . . . 3-82
Field Descriptions . . . . . . . . . . . . . . . . . 3-56 Field Descriptions . . . . . . . . . . . . . . . . . 3-82
Error Messages . . . . . . . . . . . . . . . . . . 3-56 Error Messages . . . . . . . . . . . . . . . . . . 3-83
Retrieve Job Media Library Attributes (QTARJMA) API 3-56 Restore from Application Exit Program . . . . . . . . 3-83
Authorities and Locks . . . . . . . . . . . . . . . 3-57 Restrictions . . . . . . . . . . . . . . . . . . . . 3-83
Required Parameter Group . . . . . . . . . . . . 3-57 Authorities and Locks . . . . . . . . . . . . . . . 3-83
RJMA0100 Format . . . . . . . . . . . . . . . . 3-57 Required Parameter Group . . . . . . . . . . . . 3-83
Field Descriptions . . . . . . . . . . . . . . . . . 3-58 Coding Guidelines . . . . . . . . . . . . . . . . . 3-84
Error Messages . . . . . . . . . . . . . . . . . . 3-58 Save Storage Free Exit Program . . . . . . . . . . . 3-85
| Retrieve Media Definition (QSRRTVMD, Required Parameter Group . . . . . . . . . . . . 3-85
| QsrRetrieveMediaDefinition) API . . . . . . . . . . 3-58 Save to Application Exit Program . . . . . . . . . . 3-85
| Authorities and Locks . . . . . . . . . . . . . . . 3-59 Restrictions . . . . . . . . . . . . . . . . . . . . 3-86
| Required Parameter Group . . . . . . . . . . . . 3-59 Authorities and Locks . . . . . . . . . . . . . . . 3-86
| Format of Receiver Variable . . . . . . . . . . . 3-59 Required Parameter Group . . . . . . . . . . . . 3-86
| Field Descriptions for Receiver Variable . . . . . 3-59 Coding Guidelines . . . . . . . . . . . . . . . . . 3-87
| Device Definition Format . . . . . . . . . . . . . 3-60 Storage Extension Exit Program . . . . . . . . . . . 3-87
| Field Descriptions for Device Definition . . . . . . 3-60 Exit Point Format EX400200 . . . . . . . . . . 3-87
| Media File Definition Format . . . . . . . . . . . 3-60 Exit Point Format EX400300 . . . . . . . . . . 3-87
| Field Descriptions for Media File Definition . . . . 3-60 Required Parameter Group . . . . . . . . . . . . 3-87
| Error Messages . . . . . . . . . . . . . . . . . . 3-61 Format of Object Description Information
Save Object (QsrSave) API . . . . . . . . . . . . . 3-61 (EX400200,EX400300) . . . . . . . . . . . . . 3-88
Authorities and Locks . . . . . . . . . . . . . . . 3-61 Field Descriptions . . . . . . . . . . . . . . . . . 3-88
Required Parameter Group . . . . . . . . . . . . 3-61 Format of Control Value Information . . . . . . . 3-89
User Space Format . . . . . . . . . . . . . . . . 3-61 Control Value Field Descriptions . . . . . . . . . 3-89
Field Descriptions . . . . . . . . . . . . . . . . . 3-62 Error Messages . . . . . . . . . . . . . . . . . . 3-89
Valid Keys . . . . . . . . . . . . . . . . . . . . . 3-62 Tape Management Exit Program . . . . . . . . . . . 3-89
Field Descriptions . . . . . . . . . . . . . . . . . 3-62 Required Parameter Group . . . . . . . . . . . . 3-89
Dependencies between Keys . . . . . . . . . . . 3-70 Format of Exit Description Information . . . . . . 3-90
Relationship to SAV Command . . . . . . . . . . 3-70 Field Descriptions . . . . . . . . . . . . . . . . . 3-90
Error Messages . . . . . . . . . . . . . . . . . . 3-70 Examples of Exit Calls . . . . . . . . . . . . . . 3-91
Save Object List (QSRSAVO) API . . . . . . . . . . 3-71 Format of Label Information . . . . . . . . . . . . 3-91

AS/400 System API Reference V4R4

 Backup and Recovery

Field Descriptions . . . . . . . . . . . . . . . . . 3-92 Format of Control Value Information . . . . . . . 3-96

Format of Operational Information . . . . . . . . 3-92 Field Descriptions . . . . . . . . . . . . . . . . . 3-96
Field Descriptions . . . . . . . . . . . . . . . . . 3-93 Error Messages . . . . . . . . . . . . . . . . . . 3-100

Part 2. Backup and Recovery APIs

Backup and Recovery

AS/400 System API Reference V4R4

 Backup and Recovery Exit Programs—Introduction

Chapter 3. Backup and Recovery APIs

Retrieve Backup Schedule
Backup and Recovery APIs—Introduction (QEZRTBKS) returns information about when
the Operational Assistant backups are sched-
This chapter contains information about the following APIs:
uled to be run.
Change Backup Schedule Retrieve Device Capabilities
(QEZCHBKS) allows the user to change the (QTARDCAP) retrieves information that is
Operational Assistant backup schedules. associated with a specified tape device
Change Job Media Library Attributes description or tape resource name.
(QTACJMA) API changes the specified job's Retrieve Device Information
settings for the media library attributes. (QTARDINF) retrieves information that is
Change Object Backup List associated with a specified device description.
(QEZCHBKL) changes the backup type for a Retrieve Job Media Library Attributes
list of objects that are specified by the user. (QTARJMA) retrieves the specified job's
| Create Media Definition current settings for the media library attributes.
| (QSRCRTMD, QsrCreateMediaDefinition) | Retrieve Media Definition
| creates a media definition specified by the | (QSRRTVMD, QsrRetrieveMediaDefinition)
| user. | retrieves a media definition specified by the
| (Delete Media Definition | user.
| (QSRDLTMD, QsrDeleteMediaDefinition) Save Object (QsrSave) saves a copy of one or more
| deletes a media definition specified by the objects that can be used in the integrated file
| user. system.
Dump Device (QTADMPDV) collects information for your Save Object List
IBM service representative for use imme- (QSRSAVO) saves a list of objects specified
diately after a suspected device and/or tape by the user.
management system failure. Save to Application
Free Object (QTAFROBJ) "suspends" a document object (QaneSava) enables an application to receive
specified by the caller of the API. the save records that are generated by a
List Save File save-to-save-file operation.
(QSRLSAVF) lists the contents of a save file.
Open List of Objects to be Backed Up For information about planning a backup and recovery
(QEZOLBKL) retrieves an open list of the strategy, see the Backup and Recovery book. For informa-
objects that are to be backed up. tion about save and restore procedures, see the Backup and
Qp0lSaveStgFree()—Save Storage Free Recovery book.
calls a user-supplied exit program to save an
*STMF AS/400 object type and, upon suc- The APIs in this chapter are presented in alphabetical order
cessful completion of the exit program, frees followed by the exit programs.
the storage for the object and marks the
object as storage freed.
Restore from Application Backup and Recovery Exit
(QaneRsta) enables an application to provide Programs—Introduction
the restore records that are required for a
restore-from-save-file operation. This chapter contains information about the following exit
Restore Object programs, which must be provided by the user:
(QsrRestore) restores a copy of one or more
Save Storage Free exit program
objects that can be used in the integrated file
is called by the Qp0lSaveStgFree() API to
system.
save an *STMF AS/400 object type.
Retrieve Backup Detail
Restore from Application exit program
(QEZRTBKD) retrieves more detailed informa-
enables an application program to provide the
tion about the library or folder that is to be
restore records that are required for a restore-
backed up.
from-save-file operation using the “Restore
Retrieve Backup History
from Application (QaneRsta) API” on
(QEZRTBKH) retrieves information about the
page 3-26.
backup status and history into a single vari-
Save to Application exit program
able in the calling program.
enables an application program to receive the
Retrieve Backup Options
save records that are generated by a save-to-
(QEZRTBKO) returns the backup options for
the requested backup type.

 Copyright IBM Corp. 1998, 1999 3-1

Change Backup Schedule (QEZCHBKS) API

save-file operation using the “Save to Applica- CBKS0100 Format

tion (QaneSava) API” on page 3-80.
Storage Extension Exit Program Offset
provides the capability to use storage exten-
sion. Dec Hex Type Field
Tape Management Exit Program 0 0 BINARY(4) Hours before backup to
provides the function to monitor and control send load-tape message
the use of volumes and devices used by the 4 4 BINARY(4) Occurrence of week in
operating system for most tape operations. month to run backup
8 8 CHAR(1) Run backup using this
schedule
Change Backup Schedule (QEZCHBKS) 9 9 CHAR(1) Sunday backup
API 10 A CHAR(6) Sunday backup time
Parameters 16 10 CHAR(1) Monday backup
17 11 CHAR(6) Monday backup time
Required Parameter Group:
23 17 CHAR(1) Tuesday backup
1 Input structure Input Char(*) 24 18 CHAR(6) Tuesday backup time
2 Length of input structure Input Binary(4)
3 Format name Input Char(8) 30 1D CHAR(1) Wednesday backup
4 Error Code I/O Char(*) 31 1F CHAR(6) Wednesday backup time
37 22 CHAR(1) Thursday backup

The Change Backup Schedule (QEZCHBKS) API allows the 38 23 CHAR(6) Thursday backup time
user to change the Operational Assistant backup schedules. 44 2C CHAR(1) Friday backup
45 2D CHAR(6) Friday backup time
Authorities and Locks 51 33 CHAR(1) Saturday backup
Special Authority *JOBCTL and *SAVSYS 52 34 CHAR(6) Saturday backup time
User Index Authority *CHANGE
User Index Lock *EXCL
Field Descriptions
Required Parameter Group
Friday backup. The backup type to be performed on
Input structure
Friday. Possible values follow:
INPUT; CHAR(*)
The variable that contains the backup schedule changes. 1 *DAILY
The layout of this parameter is defined by the format 2 *WEEKLY
name parameter. 3 *MONTHLY
4 *WEEKMONTH. The weekly backup options are
Length of input structure used to run the backup every week except for
INPUT; BINARY(4) the week that the monthly backup is to occur.
Length of the change request structure. A minimum The monthly backup week is determined by the
length of 58 is required for the CBKS0100 format. value that the user specifies for the Occurrence
Format name of week in month to run backup field.
INPUT; CHAR(8) 9 *SAME. No change is made to the current
The format of the input structure data. Format backup schedule for the specified day of the
CBKS0100 contains the information regarding changes week.
to the Operational Assistant backup schedule. For more blank No backup is scheduled for the specified day of
information, see “CBKS0100 Format.” the week.

Error code Friday backup time. The time that the backup should occur
I/O; CHAR(*) on Friday. Possible values follow:
The structure in which to return error information. For HHMMSS The time that the backup operation should occur
the format of the structure, see “Error Code Parameter” for the specified day of the week. A 24-hour
on page 2-6. format is used.
blank No backup operations are scheduled to be per-
formed for the specified day of the week.

3-2 AS/400 System API Reference V4R4

 Change Backup Schedule (QEZCHBKS) API

*SAME No change should be made to the current Run backup using this schedule. Whether the backup
backup operations that are scheduled for the schedule should be used to run backups. Possible values
specified day of the week. follow:

Hours before backup to send load-tape message. The

0 No. Save all the schedule values, but do not run
the backups.
number of hours prior to a backup for a system-operator
load-tape-message reminder to be sent. The possible values
1 Yes. Allow backups to run according to this
schedule.
follow:
blank *SAME. Use the existing Run backup using this
0 *NOMSG. No message is sent. schedule value.
1-24 The number of hours prior to backup to send the
message. Saturday backup. The backup type to be performed on
-1 *SAME. No change is made to the scheduled Saturday. Possible values follow:
hours before backup to send the load-tape
1 *DAILY
message.
2 *WEEKLY
Monday backup. The backup type to be performed on
3 *MONTHLY
Monday. Possible values follow:
4 *WEEKMONTH. The weekly backup options that
are used to run the backup every week except
1 *DAILY for the week that the monthly backup is to occur.
2 *WEEKLY The monthly backup week is determined by the
3 *MONTHLY value that the user specifies for the Occurrence
4 *WEEKMONTH. The weekly backup options are of week in month to run monthly backup field.
used to run the backup every week except for 9 *SAME. No change is made to the current
the week that the monthly backup is to occur. backup schedule for the specified day of the
The monthly backup week is determined by the week.
value that the user specifies for the Occurrence blank No backup is scheduled for the specified day of
of week in month to run backup field. the week.
9 *SAME. No change is made to the current
backup schedule for the specified day of the Saturday backup time. The time the backup should occur
week. on Saturday. Possible values follow:
blank No backup is scheduled for the specified day of
HHMMSS The time that the backup operation should occur
the week.
for the specified day of the week. A 24-hour
format is used.
Monday backup time. The time that the backup should
occur on Monday. Possible values follow:
blank No backup operations are scheduled to be per-
formed for the specified day of the week.
HHMMSS The time that the backup operation should occur *SAME No change should be made to the current
for the specified day of the week. A 24-hour backup operations that are scheduled for the
format is used. specified day of the week.
blank No backup operations are scheduled to be per-
formed for the specified day of the week. Sunday backup. The backup type to be performed on
*SAME No change should be made to the current Sunday. Possible values follow:
backup operations that are scheduled for the
1 *DAILY
specified day of the week.
2 *WEEKLY
Occurrence of week in month to run backup. The week
3 *MONTHLY
of the month that you want the backup to occur when the
4 *WEEKMONTH. The weekly backup options are
used to run the backup every week except for
backup type is *MONTHLY or *WEEKMONTH. Possible
the week that the monthly backup is to occur.
values follow:
The monthly backup week is determined by the
-1 *SAME. No changes are made to this value. value that the user specifies for the Occurrence
0 No monthly backups are scheduled. (If there are of week in month to run backup field.
no days specified with *MONTHLY or 9 *SAME. No change is made to the current
*WEEKMONTH, this value is not used and is backup schedule for the specified day of the
ignored.) week.
1-4 The corresponding week of the month during blank No backup is scheduled for this day of the week.
which the monthly backup occurs.
5 *LAST. The monthly backup should be run on Sunday backup time. The time that the backup should
the last week for any given month. occur on Sunday. Possible values follow:

Chapter 3. Backup and Recovery APIs 3-3

Change Backup Schedule (QEZCHBKS) API

HHMMSS The time that the backup operation should occur blank No backup operations are scheduled to be per-
for the specified day of the week. A 24-hour formed for the specified day of the week.
format is used. *SAME No change should be made to the current
blank No backup operations are scheduled to be per- backup operations that are scheduled for the
formed for the specified day of the week. specified day of the week.
*SAME No change should be made to the current
backup operations that are scheduled for the Wednesday backup. The backup type to be performed on
specified day of the week. Wednesday. Possible values follow:
1 *DAILY
Thursday backup. The backup type to be performed on
2 *WEEKLY
Thursday. Possible values follow:
3 *MONTHLY
1 *DAILY 4 *WEEKMONTH. The weekly backup options are
2 *WEEKLY used to run the backup every week except for
3 *MONTHLY the week that the monthly backup is to occur.
4 *WEEKMONTH. The weekly backup options are The monthly backup week is determined by the
used to run the backup every week except for value that the user specifies for the Occurrence
the week that the monthly backup is to occur. of week in month to run backup field.
The monthly backup week is determined by the 9 *SAME. No change is made to the current
value that the user specifies for the Occurrence backup schedule for the specified day of the
of week in month to run backup field. week.
9 *SAME. No change is made to the current blank No backup is scheduled for the specified day of
backup schedule for the specified day of the the week.
week.
blank No backup is scheduled for the specified day of Wednesday backup time. The time the backup should
the week. occur on Wednesday. Possible values follow:
HHMMSS The time that the backup operation should
Thursday backup time. The time the backup should occur
occur for the specified day of the week. A
on Thursday. Possible values follow:
24-hour format is used.
HHMMSS The time that the backup operation should occur blank No backup operations are scheduled to be
for the specified day of the week. A 24-hour performed for the specified day of the week.
format is used. *SAME No change should be made to the current
blank No backup operations are scheduled to be per- backup operations that are scheduled for
formed for the specified day of the week. the specified day of the week.
*SAME No change should be made to the current
backup operations that are scheduled for the
specified day of the week. Error Messages
Tuesday backup. The backup type to be performed on CPF1061 E Time not valid.
Tuesday. Possible values follow: CPF1099 E Subsystem not started because system ending.
CPF1629 E Not authorized to job schedule &1.
1 *DAILY
CPF1637 E Job schedule &1 in library &2 in use.
2 *WEEKLY
CPF1EC0 E
3 *MONTHLY
Job schedule in use by another user.
4 *WEEKMONTH. The weekly backup options are
CPF1EC3 E
used to run the backup every week except for
Not authorized to Backup Schedule.
the week that the monthly backup is to occur.
CPF1EC4 E
The monthly backup week is determined by the
Cannot display Backup Schedule.
value that the user specifies for the Occurrence
CPF1EC5 E
of week in month to run backup field.
Backup option &1 is not valid.
9 *SAME. No change is made to the current
CPF1EC6 E
backup schedule for the specified day of the
Value &1 for run backup not valid.
week.
CPF1EC8 E
blank No backup is scheduled for the specified day of
Value &1 for hours before backup not valid.
the week.
CPF1EC9 E
Tuesday backup time. The time that the backup should Value &1 for occurrence of week not valid.
occur on Tuesday. Possible values follow: CPF1E99 E Unexpected error occurred.
CPF24B4 E Severe error while addressing parameter list.
HHMMSS The time the backup operation should occur for CPF3C17 E
the specified day of the week. A 24-hour format Error occurred with input data parameter.
is used.

3-4 AS/400 System API Reference V4R4

 Change Job Media Library Attributes (QTACJMA) API

CPF3C21 E butes will be replaced or only specified entries will be

Format name &1 is not valid. changed by this specification.
CPF3C90 E
Length of media library attributes description
Literal value cannot be changed.
INPUT; BINARY(4)
CPF3CF1 E
Error code parameter not valid. The length of the media library attributes description, in
CPF8122 E &8 damage on library &4. bytes.
CPF9802 E Not authorized to object &2 in &3.
Format name
CPF9803 E Cannot allocate object &2 in library &3.
INPUT; CHAR(8)
CPF9807 E One or more libraries in library list deleted.
CPF9808 E Cannot allocate one or more libraries on library The format name CJMA0100 is the only valid format
list. name used by this API. For more information, see
CPF9810 E Library &1 not found. “CJMA0100 Format.”
CPF9820 E Not authorized to use library &1.
Qualified job name
CPF9830 E Cannot assign library &1.
INPUT; CHAR(26)
CPF9838 E User profile storage limit exceeded.
CPF9872 E Program or service program &1 in library &2 The name of the job for which information is to be
ended. Reason code &3. changed. The qualified job name has three parts:
CPF9999 E Function check. &1 unmonitored by &2 at state-
ment &5, instruction &3.
Job name CHAR(10). A specific job name or the
following special value:
* The job that this program
is running in. The rest of
Change Job Media Library Attributes the qualified job name
(QTACJMA) API parameter must be blank.
*INT The internal job identifier
locates the job. The user
Required Parameter Group: name and job number
must be blank.
1 Media library attributes Input Char(*)
User name CHAR(10). A specific user profile name,
description
2 Length of media library Input Binary(4)
or blanks when the job name is a special
attributes description value or *INT.
3 Format name Input Char(8) Job number CHAR(6). A specific job number, or
4 Qualified job name Input Char(26) blanks when the job name specified is a
5 Internal job identifier Input Char(16) special value or *INT.
6 Error code I/O Char(*)
Internal job identifier
Threadsafe: Yes INPUT; CHAR(16)
The internal identifier for the job. The List Job
The Change Job Media Library Attributes (QTACJMA) API (QUSLJOB) API creates this identifier. If you do not
changes the specified job's settings for the media library attri- specify *INT for the job name parameter, this parameter
butes. More information about using this API is in the Auto- must contain blanks. With this parameter, the system
mated Tape Library Planning and Management book. can locate the job more quickly than with a job name.

Error code
Authorities and Locks I/O; CHAR(*)

Job Authority *JOBCTL, if the job for which information is The structure in which to return error information. For
changed has a different user profile from that the format of the structure, see “Error Code Parameter”
of the job that calls the QTACJMA API. on page 2-6.
*JOBCTL special authority is required when
changing or replacing the resource allocation CJMA0100 Format
priority.
The following table lists the fields for the media library attri-
butes description in the CJMA0100 format. For more infor-
Required Parameter Group mation about each field, see “Field Descriptions” on
Media library attributes description page 3-6.
INPUT; CHAR(*)
The media library attributes. Either the entire list of attri-

Chapter 3. Backup and Recovery APIs 3-5

Change Job Media Library Attributes (QTACJMA) API

Ÿ Value of -1 implies *SAME. The resource allocation pri-

Offset
ority will remain the same. This value is only allowed for
Dec Hex Type Field the *CHANGE option.
0 0 CHAR(10) Option
Ÿ Value of -2 implies *DEV. The priority specified in the
10 A CHAR(2) Reserved device description will be used when the job requests a
12 C BINARY(4) Number of device entries tape resource.
Offsets vary. CHAR(10) Media library device Ÿ Value of -31 implies *JOB. The specified job's run-time
These fields priority will be used for the resource allocation priority
CHAR(6) Reserved
repeat in the when the job requests a tape resource.
order listed, BINARY(4) Resource allocation pri-
for each ority Wait time for end of volume mount. The maximum
media library amount of time, in minutes, a request will wait for the allo-
BINARY(4) Wait time for initial mount
device that is cation of a tape resource to mount the next volume after the
to have attri- BINARY(4) Wait time for end of
volume mount end of volume is reached. Valid values range from 1 through
butes defined.
600.
CHAR(4) Reserved
Exceptions:
Ÿ Value of -1 implies *SAME. The wait time for the end of
Field Descriptions
volume mount will remain the same. This value is only
Media library device. The name of the media library device allowed for the *CHANGE option.
that the attributes apply to. The special values supported Ÿ Value of -2 implies *DEV. The end of volume mount
are: wait time specified in the device description will be used.
*ALL The attributes apply to all media libraries. The Ÿ Value of -8 implies *NOMAX. The specified job will wait
value *ALL is only allowed when changing the until a resource becomes available.
attributes and must be the first and only
Ÿ Value of -31 implies *JOB. The specified job's default
device entry.
wait time will be used to calculate the wait time. The
*DEFAULT The attributes apply to all media libraries that
time is calculated by rounding the default wait time, in
do not have specific attributes defined for the
seconds, to the next highest minute.
specified job. The *DEFAULT device is only
allowed when replacing the attribute list and Ÿ Value of -32 implies *IMMED. The specified job will not
must be specified as the first device entry. wait for a resource to become available.

Number of device entries. The number of entries in the Wait time for initial mount. The maximum amount of time,
device list changed for this format. There must be at least in minutes, a request will wait for the allocation of a tape
one entry defined. The maximum number of device entries resource to mount the first volume. Valid values range from
allowed is 1000. 1 through 600.

Option. An option specifying the action to take. Special Exceptions:

values are: Ÿ Value of -1 implies *SAME. The wait time for the initial
*CHANGE The media library attributes are changed by mount will remain the same. This value is only allowed
using the device entries specified in the media for the *CHANGE option.
library attributes description. If an entry Ÿ Value of -2 implies *DEV. The initial mount wait time
already exists for a specified device, that entry specified in the device description will be used.
will be replaced. If no entry exists for a speci-
fied device, an entry will be created. Ÿ Value of -8 implies *NOMAX. The specified job will wait
*REPLACE The entire list of media library attributes are until a resource becomes available.
replaced by the device entries specified in the Ÿ Value of -31 implies *JOB. The specified job's default
media library attributes description. The first wait time will be used to calculate the wait time. The
entry must be for the *DEFAULT device. time is calculated by rounding the default wait time, in
seconds, to the next highest minute.
Reserved. This field must be set to hexadecimal zeros.
Ÿ Value of -32 implies *IMMED. The specified job will not
Resource allocation priority. The priority the specified job wait for a resource to become available.
will be given when the job requests a tape resource within a
media library device. Valid values range from 1 (highest)
through 99 (lowest).
Error Messages
CPF1343 E Job &3/&2/&1 not valid job type for function.
Exceptions: CPF136A E Job &3/&2/&1 not active.
CPF24B4 E Severe error while addressing parameter list.

3-6 AS/400 System API Reference V4R4

 Change Object Backup List (QEZCHBKL) API

CPF3C1D E Input structure

Length specified in parameter &1 not valid. INPUT; CHAR(*)
CPF3C21 E This structure includes the keys and data that are
Format name &1 is not valid. needed to make the necessary changes to the backup
CPF3C39 E definitions.
Value for reserved field not valid.
Input structure length
CPF3C51 E
INPUT; BINARY(4)
Internal job identifier not valid.
The length of the input structure. A minimum length of
CPF3C52 E
16 is required.
Internal job identifier no longer valid.
CPF3C53 E Error code
Job &3/&2/&1 not found. I/O; CHAR(*)
CPF3C54 E
The structure in which to return error information. For
Job &3/&2/&1 currently not available.
the format of the structure, see “Error Code Parameter”
CPF3C55 E
on page 2-6.
Job &3/&2/&1 does not exist.
CPF3C58 E
Job name specified is not valid. Format for Variable Length Records
CPF3C59 E
Internal identifier is not blanks and job name is Offset
not *INT.
Dec Hex Type Field
CPF3C90 E
Literal value cannot be changed. 0 0 BINARY(4) Number of variable length
CPF3CF1 E records
Error code parameter not valid. These fields BINARY(4) Length of variable length
CPF6708 E Command ended due to error. repeat for record
CPF67B1 E Option value &1 not valid. each variable
BINARY(4) Key
CPF67B2 E Number of devices entries &1 not valid. length record
BINARY(4) Length of data
CPF67B3 E Media library device &1 not valid.
CPF67B4 E Value &1 in field &2 not valid. CHAR(*) Data
CPF67B5 E &3/&2/&1 not authorized to change attribute.
CPF67B6 E &3/&2/&1 not authorized to do requested opera- If the length of the data is longer than the key field’s data
tion. length, the data is truncated at the right. No message is
CPF9872 E Program or service program &1 in library &2 issued.
ended. Reason code &3.
If the length of the data is smaller than the key field’s data
length, the data is padded with blanks at the right. No
Change Object Backup List (QEZCHBKL) message is issued.
API It is not an error to specify a key more than once. If dupli-
cate keys are specified, the last specified value for that key
Parameters
is used.
Required Parameter Group:
Each variable length record must be 4-byte aligned. If not,
1 Input structure Input Char(*) unpredictable results may occur.
2 Input structure length Input Binary(4)
3 Error code I/O Char(*)
Field Descriptions

The Change Object Backup List (QEZCHBKL) API changes Number of variable length records. The number of
the backup type for a list of objects that are specified by the records. Only specific attributes can be changed. Refer to
user. “Valid Keys” on page 3-8 for more information.

Length of variable length record. The length of each

Authorities and Locks record. Only specific attributes can be changed. Refer to
User Index Authority *CHANGE “Valid Keys” on page 3-8 for more information.
User Index Lock *SHRRD
Key. The key specifies either the library or folder attribute.
For the list of valid keys, see “Valid Keys” on page 3-8.
Required Parameter Group

Chapter 3. Backup and Recovery APIs 3-7

Change Object Backup List (QEZCHBKL) API

Length of data. The length of the data that is used to 3 Back up monthly. Back up folder objects during the
specify the value for the given parameter. monthly backup.
4 No backup. Folder objects are not backed up at all.
Data. The data that is used to specify the value for the
given key.
Library Key Format
Valid Keys
Offset
The following table lists the valid keys for the key field area
Dec Hex Type Field
of the variable length record. For detailed descriptions of the
keys, see “Field Descriptions.” BINARY(4) Number in array
CHAR(1) Backup type
Key Type Field
Note: This field repeats for each library name.
1 CHAR(*) Library
CHAR(10) Library name
2 CHAR(*) Folder

Field Descriptions
Field Descriptions
Library name. The library name of the object to be
Folder. The backup type selected and the list of folder changed for the backup type that you specified.
objects to have their backup type changed. For the format of
this field, see “Folder Key Format.” Number in array. The number of library names of objects
to have their backup type changed. The value must be 1 or
Library. The backup type selected and the list of library greater.
objects to have their backup type changed. For the format of
this field, see “Library Key Format.” Backup type. Backup type that you selected for the library
objects. The possible values follow:

Folder Key Format 1 Back up daily. Back up library objects during the daily
backup. Backing up daily means that the library
Offset
objects are also saved on the weekly and monthly
backups.
Dec Hex Type Field 2 Back up weekly. Backup library objects during the
BINARY(4) Number in array weekly backup. Backing up weekly means that the
CHAR(1) Backup type library objects are also saved on the monthly backups.
3 Back up monthly. Back up library objects during the
Note: This field repeats for each folder name.
monthly backup.
CHAR(12) Folder name 4 No backup. Library objects are not backed up at all.

Field Descriptions Error Messages

CPF1E65 E Library backup list in use.
Folder name. The folder name of the object to be changed CPF1E6B E
for the backup type that you specified. Folder backup list in use.
CPF1EC5 E
Number in array. The number of folder names of objects to
Backup option &1 is not valid.
have their backup type changed. The value must be 1 or
CPF1EEA E
greater.
Not authorized to library backup list.
Backup type. The backup type that you selected for the CPF1EEB E
folder objects. The possible values follow: Not authorized to folder backup list.
CPF1E99 E Unexpected error occurred.
1 Back up daily. Back up folder objects during the daily CPF24B4 E Severe error while addressing parameter list.
backup. Backing up daily means that the folder CPF3C17 E
objects are also saved on the weekly and monthly Error occurred with input data parameter.
backups. CPF3C81 E
2 Back up weekly. Back up folder objects during the Value for key &1 not valid.
weekly backup. Backing up weekly means that the CPF3C90 E
folder objects are also saved on the monthly backups. Literal value cannot be changed.

3-8 AS/400 System API Reference V4R4

 Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API

CPF3CF1 E | user. Care should be taken when using this special

Error code parameter not valid. | value to avoid unexpected results.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.
| *CURLIB The job’s current library is used to locate
| the media definition. If no library is speci-
CPF9999 E Function check. &1 unmonitored by &2 at state-
| fied as the current library for the job, the
ment &5, instruction &3.
| QGPL library is used.

| Input data
| Create Media Definition (QSRCRTMD, | INPUT; CHAR(*)
| QsrCreateMediaDefinition) API | The variable that is to hold all the information defining
| the use of multiple tape files for a save or restore opera-
| tion. See “Input Data Format” on page 3-10 for the
| Required Parameter Group: | format of the input data.

| Length of data
| 1 Qualified media defi- Input Char(20)
| nition name | INPUT; BINARY(4)
| 2 Input data Input Char(*) | The length of the data in the input data parameter. The
| 3 Length of data Input Binary(4) | length of data parameter may be specified up to the size
| 4 Format name Input Char(8) | of the input data variable specified in the user program.
| 5 Public authority Input Char(10) | If the length of data parameter specified is larger than
| 6 Text description Input Char(50) | the allocated size of the input data variable specified in
| 7 Replace Input Char(1)
| the user program, the results are not predictable. The
| 8 Error code I/O Char(*)
| minimum length is 72 bytes.
| Service Program: QSRLIB01 | Format name
| INPUT; CHAR(8)
| Threadsafe: No
| The name of the format for input data. The valid value
| is:
| The Create Media Definition (OPM, QSRCRTMD; ILE,
| TAPE0100 Tape devices and media
| QsrCreateMediaDefinition) API creates a media definition
| specified by the user. A media definition defines the | Public authority
| devices and media to be used in parallel by a save or restore | INPUT; CHAR(10)
| operation. For more information about using a media defi-
| The authority you give to users who do not have specific
| nition, see the Backup and Recovery book.
| private or group authority to the media definition. Once
| the media definition has been created, its public
| Authorities and Locks | authority stays the same when it is moved to another
| library or restored from backup media.
| Media Definition Authority
| *OBJMGMT, *OBJEXIST, and *READ. These | If the replace parameter is used and an existing media
| authorities are required only if an existing | definition is replaced, this parameter is ignored. All
| media definition is to be replaced. | authorities are transferred from the replaced media defi-
| Library Authority | nition to the new one.
| *EXECUTE, *ADD and *READ | The valid values for this parameter are:
| Media Definition Lock
| *EXCL | *ALL The user can perform all authorized oper-
| Library Lock *SHRUPD | ations on the media definition.
| Authorization list name
| The media definition is secured by the
| Required Parameter Group | specified authorization list, and its public
| Qualified media definition name | authority is set to *AUTL. The specified
| INPUT; CHAR(20) | authorization list must exist on the system
| The media definition to be created. The first 10 charac- | when this API is issued. If the list does
| ters contain the media definition name. The second 10 | not exist, the create process fails, and an
| characters contain the name of the library in which the | error message is returned to the applica-
| media definition is located. | tion.
| *CHANGE The user has read, add, update, and
| You can use the following special value for the library | delete authority for the media definition
| name. It should be noted, however, that the library | and can read the object description.
| name that is actually used is not passed back to the | *EXCLUDE The user cannot access the media defi-
| nition in any way.

Chapter 3. Backup and Recovery APIs 3-9

 Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API

| *LIBCRTAUT The public authority for the media defi-

| Offset
| nition is taken from the CRTAUT value for
| the target library when the object is | Dec Hex Type Field
| created. If the CRTAUT value for the | 12 C BINARY(4) Minimum parallel device
| library changes later, that change does | resources
| not affect media definitions already | 16 10 BINARY(4) Offset to first device defi-
| created. If the CRTAUT value contains | nition
| an authorization list name and that
| 20 14 BINARY(4) Number of device definitions
| authorization list secures an object, do
| not delete the list. If you do, the next | CHAR(*) Device definitions
| time you call this API with the
| *LIBCRTAUT parameter, it will fail.
| *USE The user can read the object description | Field Descriptions for Input Data
| and contents, but cannot change the
| Device definitions. A description of the devices to be used.
| media definition.
| See “Device Definition Format” for the format of a device
| Text description | definition.
| INPUT; CHAR(50)
| Maximum parallel device resources. The maximum
| A brief description of the media definition. | number of device resources to use in parallel. The possible
| Replace | values are 0 through 32. If 0 is specified, the value assumed
| INPUT; CHAR(1) | is the total number of media file definitions specified in all of
| the device definitions.
| Whether you want to replace an existing media defi-
| nition. | Minimum parallel device resources. The minimum number
| Valid values for this parameter are: | of device resources to use in parallel. A save or restore
| operation will end if fewer resources are available. A restore
| 0 Do not replace an existing media defi- | operation will also end if any of the devices specified have
| nition of the same name and library. | no resources available. The possible values are 0 through
| 1 Replace an existing media definition of | 32. If 0 is specified, the value assumed is the number of
| the same name and library. The replaced | device definitions specified.
| media definition is moved to the
| QRPLOBJ library, which is cleared at | Number of device definitions. The number of device defi-
| system IPL. For details about authorities, | nitions for the media definition. The possible values are 1
| ownership, and renaming, see the dis- | through 32.
| cussion of the REPLACE parameter in
| Appendix A of the CL Reference | Offset to first device definition. The offset from the begin-
| (Abridged) book. | ning of the input data to the first device definition for the
| media definition. This value must be a multiple of 4.
| Error code
| I/O; CHAR(*) | Reserved. An ignored field. The value must be 0.
| The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter” | Device Definition Format
| on page 2-6.
| Offset
| Input Data Format | Dec Hex Type Field
| 0 0 BINARY(4) Offset to next device defi-
| The following defines the format for the input data. For | nition
| detailed descriptions of the fields, see “Field Descriptions for
| Input Data.” | 4 4 CHAR(10) Device name
| 14 E CHAR(2) Reserved
| Offset | 16 10 BINARY(4) Offset to first media file defi-
| Dec Hex Type Field | nition

| 0 0 BINARY(4) Reserved | 20 14 BINARY(4) Number of media file defi-

| nitions
| 4 4 BINARY(4) Reserved
| CHAR(*) Media file definitions
| 8 8 BINARY(4) Maximum parallel device
| resources

3-10 AS/400 System API Reference V4R4

 Create Media Definition (QSRCRTMD, QsrCreateMediaDefinition) API

| Field Descriptions for Device Definition | Offset to next media file definition. The offset from the
| beginning of the input data to the next media file definition for
| Device name. The name of a tape device description or | the device. This value must be a multiple of 4.
| tape media library device description.
| Offset to volume identifier array. The offset from the
| Media file definitions. A description of the media files to be | beginning of the input data to the first volume identifier for
| used on this device. See “Media File Definition Format” on | the tape file. This value must be a multiple of 4.
| page 3-11 for the format of a media file definition.
| Sequence number. The tape file sequence number for the
| Number of media file definitions. The number of media | media file.
| file definitions for the device. The possible values are 1
| through 32. | The possible values are:
| 0 A save operation begins after the last
| Offset to first media file definition. The offset from the | sequence number on the starting volume. A
| beginning of the input data to the first media file definition for | restore operation searches the starting volume
| the device. This value must be a multiple of 4. | for a media file containing any of the objects
| to restore.
| Offset to next device definition. The offset from the begin-
| 1-16777215 The sequence number of the tape file.
| ning of the input data to the next device definition for the
| media definition. This value must be a multiple of 4. | Starting volume array element. The element in the volume
| identifier array containing the volume on which the save or
| Reserved. An ignored field. The value must be
| restore operation should begin. The possible values are 0
| hexadecimal zeros.
| through the number of volume identifiers specified. If the
| number of volume identifiers is 0, this value must be 0. If the
| Media File Definition Format | number of volume identifiers is greater than 0, this value
| must be greater than 0.
| Offset
| Volume identifier array. An array of volume identifiers. The
| Dec Hex Type Field | save or restore operation will use the volumes in the order
| 0 0 BINARY(4) Offset to next media file | specified, beginning with the starting volume array element.
| definition | If additional volumes are needed after the last array element
| 4 4 BINARY(4) Sequence number | is used, the save or restore operation will call the Tape Man-
| agement exit program or prompt the user to provide each
| 8 8 BINARY(4) Offset to volume identifier
| array
| additional volume. The possible value for a volume identifier
| is:
| 12 C BINARY(4) Number of volume identi-
| fiers | Volume identifier
| The identifier of a volume.
| 16 10 BINARY(4) Length of volume identifier
| 20 14 BINARY(4) Starting volume array
| element | Error Messages
| CHAR(*) Volume identifier array | CPF24B4 E Severe error while addressing parameter list.
| CPF386F E Value in input data parameter not valid.
| CPF3C17 E
| Field Descriptions for Media File Definition | Error occurred with input data parameter.
| CPF3C1D E
| Length of volume identifier. The number of bytes in each | Length specified in parameter &1 not valid.
| volume identifier. The possible values are 0 through 6. If 0 | CPF3C21 E
| is specified, the number of volume identifiers specified must | Format name &1 is not valid.
| be 0. | CPF3C29 E
| Object name &1 is not valid.
| Number of volume identifiers. The number of volume
| CPF3C3C E
| identifiers used for the tape file. The possible values are 0
| Value for parameter &1 not valid.
| through 75. If 0 is specified, the volume currently placed in
| CPF3C90 E
| the device is used. If 0 is specified for a tape media library
| Literal value cannot be changed.
| device, volume identifiers must be supplied by using the
| CPF3CF1 E
| Tape Management exit program during the save or restore
| Error code parameter not valid.
| operation.
| CPF9800 E All CPF98xx messages could be signaled. xx is
| from 01 to FF.
| CPF9999 E Function check. &1 unmonitored by &2 at state-
| ment &5, instruction &3.

Chapter 3. Backup and Recovery APIs 3-11

 Dump Device (QTADMPDV) API

| *CURLIB The job’s current library is used to locate

| Delete Media Definition (QSRDLTMD, | the media definition. If no library is speci-
| QsrDeleteMediaDefinition) API | fied as the current library for the job, the
| QGPL library is used.
| *LIBL The library list is used to locate the media
| Required Parameter Group: | definition.
| *USRLIBL The user portion of the job’s library list is
| 1 Qualified media defi- Input Char(20) | used to locate the media definition.
| nition name | *ALL All libraries in the system, including
| 2 Error code I/O Char(*) | QSYS, are searched.
| *ALLUSR All user-defined libraries, plus libraries
| Service Program: QSRLIB01
| containing user data and having names
| Threadsafe: No | starting with Q. All libraries with names
| that do not begin with the letter Q are
| searched except for the following:
| The Delete Media Definition (OPM, QSRDLTMD; ILE, | #CGULIB #RPGLIB
| QsrDeleteMediaDefinition) API deletes a media definition | #COBLIB #SDALIB
| specified by the user. A media definition defines the | #DFULIB #SEULIB
| devices and media to be used in parallel by a save or restore | #DSULIB
| operation. For more information about using a media defi-
| Although the following Qxxx libraries are
| nition, see the Backup and Recovery book.
| provided by IBM, they typically contain
| user data that changes frequently. There-
| Authorities and Locks | fore, these libraries are considered user
| libraries and are also searched:
| Media Definition Authority
| *OBJEXIST | QDSNX QUSRADSM
| Library Authority | QGPL QUSRBRM
| *EXECUTE | QGPL38 QUSRIJS
| QMQMDATA QUSRINFSKR
| Media Definition Lock
| QMQMPROC QUSRNOTES
| *EXCL
| QPFRDATA QUSRPYMSVR
| Library Lock *SHRUPD | QRCL QUSRRDARS
| QS36F QUSRSYS
| Required Parameter Group | QUSER38 QUSRVxRxMx

| Qualified media definition name | Error code

| INPUT; CHAR(20) | I/O; CHAR(*)
| The media definition to be deleted. The first 10 charac-
| The structure in which to return error information. For
| ters contain the media definition name. The second 10
| the format of the structure, see “Error Code Parameter”
| characters contain the name of the library in which the
| on page 2-6.
| media definition is located.
| The media definition name can be either a specific name
| or a generic name, which is a string of one or more
| Error Messages
| characters followed by an asterisk (*). If you specify a | CPF24B4 E Severe error while addressing parameter list.
| generic name, this API deletes all media definitions that | CPF3C90 E
| have names beginning with the string for which the user | Literal value cannot be changed.
| has authority. | CPF3CF1 E
| Error code parameter not valid.
| You can use the following special values for the library
| CPF9800 E All CPF98xx messages could be signaled. xx is
| name. It should be noted, however, that the library
| from 01 to FF.
| name that is actually used is not passed back to the
| CPF9999 E Function check. &1 unmonitored by &2 at state-
| user. Care should be taken when using these special
| ment &5, instruction &3.
| values to avoid unexpected results.

Dump Device (QTADMPDV) API

3-12 AS/400 System API Reference V4R4

 Dump Device (QTADMPDV) API

Ÿ A Work with Configuration Status (WRKCFGSTS) listing.

Required Parameter: Ÿ Licensed Internal Code logs from the last 24 hours.

1 Device name Input Char(10) Ÿ Error logs that are associated with the device resource
(and each resource within a media library device).
Optional Parameter Group: Ÿ Associated internal system objects.
2 Type of information Input Char(10) Ÿ Media and Storage Extensions (MSE) flight recorder.
3 Problem identifier Input Char(10)
4 Error code I/O Char(*) This flight recorder traces the structures that are passed
to a tape management system registered with the regis-
Threadsafe: No tration facility and traces the response from the regis-
tered program. This flight recorder can be helpful in
developing and maintaining a tape management product.
The Dump Device (QTADMPDV) API collects information for MSE is an optional feature of OS/400.
your IBM service representative. This API should be used
immediately after a suspected device and/or tape manage- Note that this API will generate multiple spooled files and
ment system failure. If the API is not used immediately, other may get large depending upon the job logs that are being
device operations may cause the flight recorders to wrap, printed and the size of the other device information. Submit-
which could result in lost information. A problem identifier will ting the call to batch may be used if system performance is a
be created and an APAR library will be generated similar to concern. That is, if the API is called from the system console
the Save APAR Data (SAVAPARDTA) command. To save at high priority, it may degrade performance on other critical
the APAR library, use Work with Problem (WRKPRB) processing. Since many and potentially large spooled files
command. Choose the option to work with the problem and may be generated, ensure that there is enough system
then the option to save the APAR library. If an existing storage available to handle the request.
problem identifier is passed to this API, then the spooled files
generated will be logged against that problem identifier and
no new problem identifier will be generated.
Required Parameter
Device name
The Dump Device API currently supports the following device INPUT; CHAR(10)
types:
The name of the device for which debugging information
Ÿ Tape (TAP) devices is being dumped.
Ÿ Tape media library (TAPMLB) devices
Ÿ Optical (OPT) devices Optional Parameter Group
Ÿ Optical media library (OPTMLB) devices Type of information
Ÿ Diskette (DKT) devices INPUT; CHAR(10)
Note: The information provided in and the number of The type of information to be dumped. Valid values are:
spooled files may change at anytime. The information pro-
*ALL All information needed by IBM will be
vided is intended for problem determination.
dumped to spooled files.
The Dump Device (QTADMPDV) API dumps the following *MSE Media and Storage Extension (MSE) flight
information into spooled files: recorder will be dumped.

Ÿ The contents of the device flight recorder for the device Problem identifier
specified in the parameter that is passed to the program. INPUT; CHAR(10)
This includes OS/400 flight recorders. The problem identifier of the problem being analyzed.
Ÿ QSYSARB job log. Problems with different system origins can have the
same identifier. The possible values are:
Ÿ QSYSOPR message queue.
Ÿ Job logs of the active jobs that have used the device as *NEW A problem identifier will be created.
indicated in the flight recorder data. problem-identifier
The 10-character problem identifier of the
Ÿ The history log (QHST). problem being selected.
Ÿ Device description of the device.
Error code
Ÿ Communication information that is associated with the I/O; CHAR(*)
media library device. This includes the line, controller,
The structure in which to return error information. For
and device descriptions.
the format of the structure, see “Error Code Parameter”
Ÿ The job log of the job that is processing this API.

Chapter 3. Backup and Recovery APIs 3-13

Free Object (QTAFROBJ) API

on page 2-6. If this parameter is omitted, diagnostic Notes:

and escape messages are issued to the application.
1. To use this API, you need the Media and Storage Exten-
sions feature of the OS/400.
Examples 2. For a document of type *DOC, the caller must be
enrolled in the system distribution directory to use this
The following are examples of calls to the API from
API.
command entry:
Ÿ CALL QTADMPDV TAP01
Authorities and Locks
The dump device will dump information about TAP01
and assigns it to a created problem identifier.
Object Authority
*CHANGE
Ÿ CALL QTADMPDV TAPMLB01 *OBJEXIST
The dump device will dump information about Directory Authority
TAPMLB01 and assigns it to a created problem identi- *X
fier.
Ÿ CALL QTADMPDV (TAP01 *ALL 9628851615 Required Parameter Group
x'00000000')
Request variable
The dump device will dump information about TAP01 INPUT; CHAR(*)
and assign it to an existing problem identifier.
The request variable that identifies the object to be sus-
pended.
Error Messages
Length of request variable
CPF3C90 E INPUT; BINARY(4)
Literal value cannot be changed.
The length of the request variable provided. Valid
CPF6709 E Parameter &3 not correct.
values range from 48 through 32048.
CPF6721 E Device &1 not a tape device.
CPF673F E Device &1 does not support &2. Format name
CPF9814 E Device &1 not found. INPUT; CHAR(8)
CPF9825 E Not authorized to device &1.
The format of the object information being passed to the
CPF9872 E Program or service program &1 in library &2
QTAFROBJ API. The TAFO0100 format must be used
ended. Reason code &3.
for this API. See “TAFO0100 Format” to view the object
information required to perform this API.

Free Object (QTAFROBJ) API Error code

I/O; CHAR(*)
The structure in which to return error information. For
Required Parameter Group: the format of the structure, see “Error Code Parameter”
on page 2-6.
1 Request variable Input Char(*)
2 Length of request variable Input Binary(4)
3 Format name Input Char(8)
4 Error code I/O Char(*)
TAFO0100 Format
The following table shows the object information that is
Threadsafe: No
required for the TAFO0100 format. For more details about
the fields in the following table, see “Field Descriptions” on
The Free Object (QTAFROBJ) API will "suspend" a docu- page 3-15.
ment object specified by the caller of the API. A call to this
API forces the system storage that is occupied by the data Offset
portion of the specified object to be freed. Only the data Dec Hex Type Field
portion of the objects is freed, not the descriptions of the
0 0 CHAR(10) Object name
object. This function is similar to the save with storage freed
option, STG(*FREE), on the Save Document Library Object 10 A CHAR(10) Object library
(SAVDLO) command. 20 14 CHAR(10) Reserved

The caller of this API is required to verify that the specified 30 1E CHAR(10) Object type
object has not been changed since it was last saved. 40 28 BINARY(4) Offset to path name struc-
ture

3-14 AS/400 System API Reference V4R4

 List Save File (QSRLSAVF) API

CPF3C39 E
Offset
Value for reserved field not valid.
Dec Hex Type Field CPF3C4B E
44 2C BINARY(4) Length of path name struc- Value not valid for field &1.
ture CPF3C4C E
CHAR(*) Path name structure Value not valid for field &1.
CPF3C90 E
Literal value cannot be changed.
Field Descriptions CPF3CF1 E
Error code parameter not valid.
Length of the path name structure. The length, in bytes, CPF6708 E Command ended due to error.
of the path name structure. This field must be set to zero if CPF67C2 E
the object does not have a path name structure passed. Path name structure field &7 not valid.
Valid values are 0 and 48 through 32048. CPF67C4 E
Object &1 type &2 in library &3 not freed.
Object library. The library name of the object to be freed. Object in use.
The special value is: CPF67C5 E
*PATH The path name structure contains the object Object &1 type &2 in library &3 not freed.
information. CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
Object name. The name of the object to be freed by the CPF9872 E Program or service program &1 in library &2
API. The special value is: ended. Reason code &3.
*PATH The path name structure contains the object
information.
List Save File (QSRLSAVF) API
Object type. The type of object specified to be freed by the
API. Possible values follow:
*DOC The object to be suspended is a document. Required Parameter Group:
*PATH The path name structure will contain the object
1 Qualified user space name Input Char(20)
information. 2 Format name Input Char(8)
3 Qualified save file name Input Char(20)
Offset to path name structure. The offset from the start of 4 Object name filter Input Char(10)
the structure, in bytes, to a path name structure that contains 5 Object type filter Input Char(10)
object path name and translation information. This field must 6 Continuation handle Input Char(36)
be set to zero if the object does not have a path name struc- 7 Error code I/O Char(*)
ture. Valid values are 0 and 48 through 32048.
Threadsafe: No
Path name structure. The path name structure and trans-
lation information for the suspended object. The path name
structure contains information such as CCSID, country, and The List Save File (QSRLSAVF) API lists the contents of a
language. For more information on this structure, see “Path save file.1 The generated list replaces any data that already
Name Format” on page 2-8. The path name must be in the exists in the user space; it does not add the new list to an
library file system format, for example, existing one. The generated list is not sorted.
/QSYS.LIB/QDOC.LIB/DOC1.DOC
Authorities and Locks
Reserved. An ignored field. This field must be set to
blanks. Save File Library Authority
*USE
Save File Authority
Error Messages *USE
CPF24B4 E Severe error while addressing parameter list. Save File Lock
CPF3C1D E *EXCLRD
Length specified in parameter &1 not valid. User Space Authority
CPF3C21 E *CHANGE
Format name &1 is not valid.

1 A save file is a file allocated in auxiliary storage that can be used to store saved data on disk (without requiring diskettes or tapes), to do
I/O operations from a high-level language program, or to receive objects sent through the network.

Chapter 3. Backup and Recovery APIs 3-15

List Save File (QSRLSAVF) API

User Space Library Authority can determine if a previous call resulted in partially com-
*USE plete information by checking the information status field
User Space Lock in the generic user space header following the API call.
*EXCLRD For information about the generic header, see “User
Space Format for List APIs” on page 2-4.
Required Parameter Group If the API is not attempting to continue from a previous
call, this parameter must be set to blanks. Otherwise, a
Qualified user space name valid continuation value must be supplied. The value
INPUT; CHAR(20) may be obtained from the continuation handle returned
The user space that is to receive the created list. The field in the header section. See “Format of the Gener-
first 10 characters contain the user space name, and the ated List” for information about the header section.
second 10 characters contain the name of the library
Error code
where the user space is located. You can use these
I/O; CHAR(*)
special values for the library name:
The structure in which to return error information. For
*CURLIB The job’s current library the format of the structure, see “Error Code Parameter”
*LIBL The library list on page 2-6.
Format name
INPUT; CHAR(8) Format of the Generated List
The content and format of the information returned for
The save file list consists of:
the save file. The possible format names are:
Ÿ A user area
SAVF0100 Library level
SAVF0200 Object level Ÿ A generic header
SAVF0300 Member level Ÿ An input parameter section
For more information, see the specified formats in the Ÿ A header section
“Format of the Generated List.”
Ÿ A list data section (containing one of the following) :
Qualified save file name – SAVF0100 format
INPUT; CHAR(20)
– SAVF0200 format
The save file about which to list information, and the
library in which the save file is located. The first 10 – SAVF0300 format
characters contain the save file name, and the second
For details about the user area and generic header, see
10 characters contain the library name. You can use
“User Space Format for List APIs” on page 2-4. For details
these special values for the library name:
about the remaining items, see the following sections. For
*CURLIB The job’s current library detailed descriptions of the fields in the list returned, see
*LIBL The library list “Field Descriptions” on page 3-17.

Object name filter When you retrieve list entry information from a user space,
INPUT; CHAR(10) you must use the entry size returned in the generic header.
The name of the objects to search for. This name may The size of each entry may be padded at the end. If you do
be a simple name, a generic name, or the special value not use the entry size, the result may not be valid. For
*ALL. If the name is not a valid name, an empty list will examples of how to process lists, see the DLTOLDSPLF
be returned. This field must be *ALL for the SAVF0100 example programs in Appendix A, “Examples.”
format.
Input Parameter Section
Object type filter
INPUT; CHAR(10) Offset
The type of objects to search for. You may either enter Dec Hex Type Field
a specific type or the special value *ALL. For a com- 0 0 CHAR(10) User space name specified
plete list of the available object types, see the CL Refer-
10 A CHAR(10) User space library name
ence (Abridged) manual. This field must be *ALL for the
specified
SAVF0100 format and the SAVF0300 format.
20 14 CHAR(8) Format name
Continuation handle
28 1C CHAR(10) Save file name specified
INPUT; CHAR(36)
38 26 CHAR(10) Save file library name speci-
The handle used to continue from a previous call to this fied
API that resulted in partially complete information. You

3-16 AS/400 System API Reference V4R4

 List Save File (QSRLSAVF) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
48 30 CHAR(10) Object name filter specified 60 3C CHAR(1) Data saved
58 3A CHAR(10) Object type filter specified 61 3D CHAR(10) Object owner
68 44 CHAR(36) Continuation handle speci- 71 47 CHAR(20) Document library object
fied (DLO) name
91 5B CHAR(63) Folder
Header Section 154 9A CHAR(50) Text description

Offset
SAVF0300 Format
Dec Hex Type Field
0 0 CHAR(10) User space name used Offset
10 A CHAR(10) User space library name Dec Hex Type Field
used
0 0 CHAR(10) File name
20 14 CHAR(10) Save file name used
10 A CHAR(10) Library saved
30 1E CHAR(10) Save file library name used
20 14 CHAR(10) Member name
40 28 CHAR(36) Continuation handle
30 1E CHAR(10) Extended object attribute
returned
40 28 CHAR(8) Save date and time

SAVF0100 Format 48 30 BINARY(4) Members saved

Offset Field Descriptions:

Dec Hex Type Field
Access paths. The number of logical file access paths that
0 0 CHAR(10) Library saved were saved for the library.
10 A CHAR(10) Save command
Auxiliary storage pool. The auxiliary storage pool (ASP) of
20 14 CHAR(8) Save date and time
the object when it was saved. For the SAVF0100 format,
28 1C BINARY(4) Auxiliary storage pool this is the ASP of the library. For the SAVF0200 format, this
32 20 BINARY(4) Records is the ASP of the object. The possible values are:
36 24 BINARY(4) Objects saved 1 System ASP
2 - 16 User ASPs
40 28 BINARY(4) Access paths
44 2C CHAR(10) Save active Continuation handle returned. A continuation point for the
54 36 CHAR(6) Release level API.
60 3C CHAR(1) Data compressed This value is set based on the contents of the information
61 3D CHAR(8) System serial number status variable in the generic header for the user space. The
69 45 CHAR(3) Reserved following situations can occur:
Ÿ Information status–C. The information returned in the
SAVF0200 Format user space is valid and complete. No continuation is
necessary and the continuation handle is set to blanks.
Offset Ÿ Information status–P. The information returned in the
Dec Hex Type Field user space is valid but incomplete. The user may call
the API again, continuing where the last call ended. The
0 0 CHAR(10) Object name
continuation handle contains a value that may be sup-
10 A CHAR(10) Library saved plied as an input parameter in later calls.
20 14 CHAR(10) Object type Ÿ Information status–I. The information returned in the
30 1E CHAR(10) Extended object attribute user space is not valid or complete. The contents of the
continuation handle are unpredictable.
40 28 CHAR(8) Save date and time
48 30 BINARY(4) Object size Continuation handle specified. The handle used to con-
52 34 BINARY(4) Object size multiplier tinue from a previous call to this API that resulted in partially
complete information.
56 38 BINARY(4) Auxiliary storage pool

Chapter 3. Backup and Recovery APIs 3-17

List Save File (QSRLSAVF) API

Data compressed. Whether the data was stored in com- Object size multiplier. The value to multiply the object size
pressed format. The possible values are: by to get the true size. The value is 1 if the object is smaller
than or equal to 999 999 999 bytes, 1024 if it is larger than
0 The data is not compressed.
999 999 999 but smaller than or equal to 4 294 967 295, and
1 The data is compressed.
4096 if larger than 4 294 967 295.
Data saved. Whether the data for this object was saved
Object type. The type of object. For a list of object types,
with the object. The possible values are:
see the CL Reference (Abridged) book.
0 The data was not saved. The object’s storage
was freed by a previous save command Object type filter specified. The type of objects to search
before this save operation. for. Only object types that match the filter are listed.
1 The data was saved. The object’s storage
was not freed by a previous save command Records. The number of records used to contain the saved
before this save operation. information in the save file.

Document library object (DLO) name. The name of the Release level. The earliest release level of the operating
document, folder, or mail object that was saved. If the object system on which the objects can be restored.
is a document or folder, the first 12 characters will contain
Reserved. An ignored field.
the DLO name. If the object is a mail object, the full 20 char-
acters will be used for the mail object name. If the save file
Save active. Whether objects in the library are allowed to
does not contain DLO information, this field will be blank.
be updated while they are being saved. The possible values
are:
Extended object attribute. Extended information about the
object type. If there is not an extended object attribute for *LIB Objects in the library are saved while in use
the object, this field will be blank. by another job. All of the objects in the library
reached a checkpoint together and were
File name. The name of the file that was saved. saved in a consistent state in relationship to
each other. All objects in the library are
Folder. The name of the folder that was saved. The folder
saved at the same time.
name is a fully qualified name. If the object is not a *FLR or
*NO Objects in the library are not saved while in
*DOC object, this field will be blank. For *DOC and *FLR
use by another job.
objects, this field will be set to the qualified name of the
*SYNCLIB Objects in the library are saved while in use
folder or to *NONE.
by another job. All of the objects and all of
the libraries in the save operation reached a
Format name. The format of the returned output.
checkpoint together. The objects and the
Library saved. The name of the library from which the libraries were saved in a consistent state in
objects are saved. relationship to each other.
*SYSDFN Objects in the library are saved while in use
Member name. The name of the file member that is saved. by another job. Objects in the library may
The member names are not in sorted order. have reached a checkpoint at different times
and may not be in a consistent state in
Members saved. The number of members saved for the relationship to each other.
file. *YES Document library objects are saved while in
use by another job. This value is valid only if
Object name. The name of the object saved. If the object
the SAVDLO command is used for the save
is a DLO object, this field will contain the system name of the
operation.
object.
Save command. The save command that is used when the
Object name filter specified. The name of the objects to
save operation is performed. The possible values are:
search for. Only objects with names that match the filter are
listed. QSYS Contents of the save file are created by the
operating system by using a function other
Object owner. The name of the object owner’s user profile. than the CL commands.
SAVCFG Saves configuration information.
Objects saved. The number of objects that are saved for SAVCHGOBJ
this library. Saves objects that changed since the date
and time specified on the referenced date
Object size. The size of the object in units of the size multi-
parameter.
plier. The true object size is equal to or smaller than the
SAVDLO Saves documents or folders located in library
object size multiplied by the object size multiplier.
QDOC.
SAVLIB Saves a copy of a library.

3-18 AS/400 System API Reference V4R4

 Open List of Objects to be Backed Up (QEZOLBKL) API

SAVLICPGM CPF4500 D All CPF45xx messages could be

Saves licensed programs. returned. xx is from 01 to FF.
SAVOBJ Saves an object or group of objects from the CPF4600 D All CPF46xx messages could be
same library. returned. xx is from 01 to FF.
SAVSECDTA CPF5100 E All CPF51xx messages could be
Saves objects required for the security func- returned. xx is from 01 to FF.
tion. CPF5200 E All CPF52xx messages could be
returned. xx is from 01 to FF.
Save date and time. The time at which the objects were CPF5300 E All CPF53xx messages could be
saved in system time-stamp format. returned. xx is from 01 to FF.
CPF3743 E File cannot be restored, displayed, or listed.
Save file library name specified. The name of the save file
CPF3782 E File &1 in &2 not a save file.
library as specified in the call to the API.
CPF3793 E Machine storage limit reached.
CPF381F E Save file &1 cannot be processed by API
Save file library name used. The name of the save file
QSRLSAVF.
library used to produce the listing.
CPF3812 E Save file &1 in &2 in use.
Save file name specified. The name of the save file as CPF3C21 E
specified in the call to the API. Format name &1 is not valid.
CPF3CF1 E
Save file name used. The name of the save file used to Error code parameter not valid.
produce the listing. CPF3C90 E
Literal value cannot be changed.
System serial number. The serial number of the system on CPF8100 E All CPF81xx messages could be returned. xx is
which the save was performed. If the save media is from a from 01 to FF.
System/38, the system serial number will be blank. CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
Text description. The text description of the object. If the
CPF9803 E Cannot allocate object &2 in library &3.
object is a DLO object, the following pertains:
CPF9806 E Cannot perform function for object &2 in library
Ÿ Characters 1 through 44 contain the text description. &3.
CPF9807 E One or more libraries in library list deleted.
Ÿ The last 6 characters are padded with blanks.
CPF9808 E Cannot allocate one or more libraries on library
User space library name specified. The name of the list.
library containing the user space as specified in the call to CPF9809 E Library &1 cannot be accessed.
the API. CPF9810 E Library &1 not found.
CPF9812 E File &1 in library &2 not found.
User space library name used. The name of the library CPF9820 E Not authorized to use library &1.
used to produce the listing. CPF9822 E Not authorized to file &1 in library &2.
CPF9830 E Cannot assign library &1.
User space name specified. The name of the user space CPF9838 E User profile storage limit exceeded.
as specified in the call to the API. CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.
User space name used. The name of the user space used
to produce the listing.

Open List of Objects to be Backed Up

Error Messages (QEZOLBKL) API
CPF22FD E
Continuation handle not valid for API &1.
CPF24B4 E Severe error while addressing parameter list. Required Parameter Group:
CPF3704 E Request ended; data management error
1 Receiver variable Output Char(*)
occurred.
2 Length of receiver variable Input Binary(4)
CPD3723 D
3 List information Output Char(80)
System may be too busy for save 4 Number of records to return Input Binary(4)
or restore operation. 5 Format name Input Char(8)
CPF4100 E All CPF41xx messages could be 6 Object type Input Char(10)
returned. xx is from 01 to FF. 7 Type of backup to select Input Char(10)
CPF4200 E All CPF42xx messages could be 8 Error Code I/O Char(*)
returned. xx is from 01 to FF.
CPF4300 E All CPF43xx messages could be Threadsafe: No
returned. xx is from 01 to FF.

Chapter 3. Backup and Recovery APIs 3-19

Open List of Objects to be Backed Up (QEZOLBKL) API

The Open List of Objects to be Backed Up (QEZOLBKL) API OBKL0600 Complete information format. The object
retrieves an open list of the objects that are to be backed up. type parameter may be *FLR or *LIB. For
more information, see “OBKL0600
For more information, see the "Process Open List APIs" in Format” on page 3-21.
the Information Center.
Object type
INPUT; CHAR(10)
Authorities and Locks
The type of the objects to be returned in the list. One of
User Index Authority the following object types may be used:
*USE
User Index Lock *FLR The folder information is returned. The
*SHRRD format name may be OBKL0200 or
OBKL0600.
*LIB The library information is returned. The
Required Parameter Group format name may be OBKL0100 or
Receiver variable OBKL0600.
OUTPUT; CHAR(*) Type of backup to select
The receiver variable that receives the information INPUT; CHAR(10)
requested. You can specify the size of the area to be The backup type of the objects that you request. Allow-
smaller than the format requested as long as you specify able backup types follow:
the length parameter correctly. As a result, the API
returns only the data that the area can hold. *DAILY Return information for objects that are
backed up *DAILY.
Length of receiver variable *WEEKLY Return information for objects that are
INPUT; BINARY(4) backed up *WEEKLY.
The length of the receiver variable provided. The length *MONTHLY Return information for objects that are
of receiver variable parameter may be specified up to backed up *MONTHLY.
the size of the receiver variable specified in the user *ALL Return information for objects that are
program. If the length of receiver variable parameter backed up *DAILY, *WEEKLY, or
specified is larger than the allocated size of the receiver *MONTHLY.
variable specified in the user program, the results are
Error code
not predictable.
I/O; CHAR(*)
List information The structure in which to return error information. For
OUTPUT; CHAR(80) the format of the structure, see “Error Code Parameter”
Information about the list that is created by this program. on page 2-6.
For a description of the layout of this parameter, see
“Format of List Information” on page 3-21.
Format of Receiver Variable
Number of records to return
INPUT; BINARY(4) The following tables describe the order and format of the
data that is returned in the receiver variable.
The number of records in the list to put into the receiver
variable. The value must be 0 or greater. OBKL0100 Format: The OBKL0100 format includes the
basic information for a library object entry. The following
Format name
table shows how this information is organized. For detailed
INPUT; CHAR(8)
descriptions of the fields in the list, see “Field Descriptions”
The name of the format to be used to return the on page 3-21.
requested information.
One of the following format names may be used: Offset
Dec Hex Type Field
OBKL0100 Library basic information format. The
object type parameter must be *LIB. For 0 0 CHAR(10) Backup option
more information, see “OBKL0100 10 A CHAR(10) Library name
Format.”
20 14 CHAR(2) Reserved
OBKL0200 Folder basic information format. The
object type parameter must be *FLR. For
more information, see “OBKL0200
Format” on page 3-21.

3-20 AS/400 System API Reference V4R4

 Open List of Objects to be Backed Up (QEZOLBKL) API

OBKL0200 Format: The OBKL0200 format includes the Last backup time. The time that the object was last backed
basic information for a folder object entry. The following up. The format of this field is in the HHMMSS as follows:
table shows how this information is organized. For detailed HH Hour
descriptions of the fields in the list, see “Field Descriptions” MM Minute
on page 3-21. SS Second

Offset Library name. The library name of the object to be backed

Dec Hex Type Field up.

0 0 CHAR(10) Backup option Object description text. The text that describes the object.
10 A CHAR(12) Folder name
Reserved. An ignored field.

OBKL0600 Format: The OBKL0600 format includes the

complete information for a library or folder object entry. The Format of List Information
following table shows how this information is organized. For
detailed descriptions of the fields in the list, see “Field Offset
Descriptions.” Dec Hex Type Field
0 0 BINARY(4) Total records
Offset
4 4 BINARY(4) Records returned
Dec Hex Type Field
8 8 CHAR(4) Request handle
0 0 Returns everything from
format OBKL0100 or 12 C BINARY(4) Record length
OBKL0200
16 10 CHAR(1) Information complete indi-
22 16 CHAR(7) Last backup date cator
29 1D CHAR(6) Last backup time 17 11 CHAR(13) Date and time created
35 23 CHAR(50) Object description text 30 1E CHAR(1) List status indicator
85 55 CHAR(1) Changed since last backup 31 1F CHAR(1) Reserved
86 56 CHAR(21) Reserved 32 20 BINARY(4) Length of information
returned
36 24 BINARY(4) First record in buffer
Field Descriptions 40 28 BINARY(4) Authority reason code
Backup option. The backup option defined for the object. 44 2C CHAR(36) Reserved
The possible values follow:
*DAILY Daily backup option.
*WEEKLY Weekly backup option.
Field Descriptions
*MONTHLY Monthly backup option. Authority reason code. Whether all information that you
requested has been supplied due to the user's authority.
Changed since last backup. Whether the object has
The list of folders or libraries may not be the complete list of
changed since the last backup. The possible values follow:
objects on the system if the user does not have the required
0 No change has been made since the last authority to list the object. A user with *SAVSYS or
backup. *ALLOBJ authority is able to get a complete list. Without this
1 A change has been made since the last authority, the list may not be complete.
backup.
0000 The list is complete.
Folder name. The folder name of the object to be backed 0001 The list may be partial due to authorization.
up.
Date and time created. The date and time that the list was
Last backup date. The date that the object was last backed created. The 13 characters follow:
up. The format of this field is in the CYYMMDD as follows: 1 Century, where 0 indicates years 19xx and 1
C Century, where 0 indicates years 19xx and 1 indicates years 20xx.
indicates years 20xx. 2-7 The date, in YYMMDD (year, month, and day)
YY Year format.
MM Month 8-13 The time of day, in HHMMSS (hours, minutes,
DD Day and seconds) format.

Chapter 3. Backup and Recovery APIs 3-21

Qp0lSaveStgFree

First record in buffer. The number of the first record in the Error Messages
receiver variable.
CPF1E65 E Library backup list in use.
Information complete indicator. Whether all information CPF1E67 D
that was requested has been supplied. Backup options and library backup list
damaged.
I Incomplete information. An interruption
CPF1E6B E
causes the list to contain incomplete informa-
Folder backup list in use.
tion about a buffer or buffers.
CPF1E6D D
P Partial and accurate information. Partial infor-
Folder backup list damaged; new one created.
mation is returned when the maximum space
CPF1EC5 E
is used and not all of the buffers that were
Backup option &1 is not valid.
requested are read.
CPF1EE4 E
C Complete and accurate information. All the
Not authorized to run backup.
buffers that were requested are read and
CPF1EEA E
returned.
Not authorized to library backup list.
Length of information returned. The size, in bytes, of the CPF1EEB E
information that is returned in the receiver variable. Not authorized to folder backup list.
CPF1E99 E Unexpected error occurred.
List status indicator. The status of building the list. CPF24B4 E Severe error while addressing parameter list.
CPF3C19 E
0 Building the list is pending.
Error occurred with receiver variable specified.
1 The list is in the process of being built.
CPF3C21 E
2 The list has been completely built.
Format name &1 is not valid.
3 An error occurred when the system built the
CPF3C31 E
list. The next call to the Get List Entries
Object type &1 is not valid.
(QGYGTLE) API causes the error to be sig-
CPF3C90 E
naled to the caller of QGYGTLE.
Literal value cannot be changed.
Record length. The length of each record of information CPF3CF1 E
returned. For variable length records, this value is set to 0. Error code parameter not valid.
For variable length records, you can obtain the length of indi- CPF8148 E Object &4 type &3 in &9 damaged.
vidual records from the records themselves. CPF8A77 E Folder &1 not found.
CPF8A78 E Folder &1 in use.
Records returned. The number of records that are returned CPF8A79 E Folder &1 is logically damaged.
in the receiver variable. This is the smallest of the following CPF8A80 E Document &2 in use in folder &1.
values: CPF9012 E Start of document interchange session not suc-
cessful for &1.
Ÿ The number of records that fit into the receiver variable.
CPF9032 E Document interchange session not started.
Ÿ The number of records in the list. CPF9076 E Internal system error processing documents or
Ÿ The number of records that was requested. folders.
CPF9095 E Folder &1 is damaged.
Request handle. The handle of the request that can be CPF909A E Document &2 in folder &1 is damaged.
used for subsequent requests of information from the list. CPF9810 E Library &1 not found.
The handle is valid until the Close List (QGYCLST) API is CPF9872 E Program or service program &1 in library &2
called to close the list or until the job ends. ended. Reason code &3.
CPF9830 E Cannot assign library &1.
Note: This field should be treated as a hexadecimal field. It
CPF9838 E User profile storage limit exceeded.
should not be converted from one CCSID to another, for
CPF9999 E Function check. &1 unmonitored by &2 at state-
example, EBCDIC to ASCII, because doing so could result in
ment &5, instruction &3.
an unusable value.

Reserved. A reserved field. This field must be set to

hexadecimal or binary zero. Qp0lSaveStgFree()—Save Storage Free
Total records. The total number of records available in the
list.

3-22 AS/400 System API Reference V4R4

 Qp0lSaveStgFree

object in a remote file system, Qp0lSaveStgFree()

Syntax returns ENOTSUP to the calling program.

#include <Qpðlstdi.h> UserFunction_ptr

(Input) A pointer to a structure that contains information
int QpðlSaveStgFree( about the user exit program that the caller wants
Qlg_Path_Name_T \Path_Name, Qp0lSaveStgFree() to call to save a *STMF object.
Qpðl_StgFree_Function_t \UserFunction_ptr, This user exit program can be either a procedure or a
void \Function_CtlBlk_ptr); program. If this pointer is NULL, Qp0lSaveStgFree()
does not call an exit program to save the object but
Threadsafe: Conditional; see Usage Notes. does free the object's storage and marks it as storage
freed.

Figure 3-1. User Function Pointer

The Qp0lSaveStgFree() function calls a user-supplied exit
Offset
program to save AS/400 objects of type *STMF and, upon
successful completion of the exit program, frees the storage Dec Hex Type Field
for the object and marks the object as storage freed. The 0 0 BINARY(4) Function type flag
*STMF object and its attributes remain on the system, but 14 E CHAR(10) Program library
the storage occupied by the *STMF object's data is deleted.
The *STMF object cannot be used until it is restored to the 4 4 CHAR(10) Program name
system. This is accomplished by either of the following: 24 18 CHAR(1) Multithreaded job action
Ÿ Restoring the object using the RST command. 25 19 CHAR(7) Reserved
Ÿ Requesting an operation on the object, requiring one of 32 20 PP(*) Procedure pointer to exit
the following, which will dynamically retrieve (restore) the procedure
*STMF object:
– Accessing the object's data (open(), creat(), MOV, Function type flag
CPY, CPYFRMSTMF, or CPYTOSTMF). A flag that indicates whether the Save Storage
– Adding a new name to the object (RNM, ADDLNK, Free exit program called by Qp0lSaveStgFree()
link(), rename(), Qp0lRenameKeep(), or is a procedure or a program. If the exit program
Qp0lRenameUnlink()). is a procedure, this flag is set to 0, and the proce-
– Checking out the object (CHKOUT). dure pointer to exit procedure field points to the
procedure called by Qp0lSaveStgFree(). If the
The restore operation is done by calling a user-provided exit
exit program is a program, this flag is set to 1 and
program registered against the Storage Extension exit point
a program name and program library are pro-
QIBM_QTA_STOR_EX400. A description of this exit
vided, respectively, in the program name and
program is located in the Backup and Recovery part of this
program library fields. Valid values follow:
manual.
0 QP0L_USER_FUNCTION_PTR: A user
Qp0lSaveStgFree() returns EOFFLINE for an object that is procedure is called.
already storage freed or returns EBUSY for an object that is 1 QP0L_USER_FUNCTION_PGM: A user
checked out. program is called.
Multithreaded job action
The user exit program can be either a procedure or a (Input) A CHAR(1) value that indicates the action
program. to take in a multithreaded job. The default value
is QP0L_MLTTHDACN_SYSVAL. For release
compatibility and for processing this parameter
Parameters against the QMLTTHDACN system value, x'00,
Path_Name x'01', x'02', & x'03' are treated as x'F0', x'F1',
(Input) A pointer to a path name whose last component x'F2', and x'F3'.
is the object that is saved and whose storage is freed. x'00'
This path name is in the Qlg_Path_Name_T format. For QP0L_MLTTHDACN_SYSVAL: The API
more information on this structure, see “Path Name evaluates the QMLTTHDACN system value
Format” on page 2-8. to determine the action to take in a multi-
threaded job. Valid QMLTTHDACN system
If the last component of the path name supplied on the values follow:
call to Qp0lSaveStgFree() is a symbolic link, then '1' Call the exit program. Do not send an
Qp0lSaveStgFree() resolves and follows the link to its informational message.
target and performs its normal Qp0lSaveStgFree() func- '2' Call the exit program and send infor-
tions on that target. If the symbolic link refers to an mational message CPI3C80.

Chapter 3. Backup and Recovery APIs 3-23

Qp0lSaveStgFree

'3' The exit program is not called when

Figure 3-2. Authorization Required for Qp0lSaveStgFree() API
the API determines that it is running in
a multithreaded job. ENOTSAFE is Authority
Object Referred to Required errno
returned.
x'01' Each directory, preceding the last *RX EACCES
QP0L_MLTTHDACN_NOMSG: Call the exit component, in a path name
program. Do not send an informational Object *ALLOBJ EACCES
message. or
x'02' *SAVSYS
QP0L_MLTTHDACN_MSG: Call the exit Any called program pointed to by the *X EACCES
program and send informational message UserFunction_ptr parameter
CPI3C80.
Any library containing the called *X EACCES
x'03' program pointed to by the
QP0L_MLTTHDACN_NO: The exit program UserFunction_ptr parameter
is not called when the API determines that it
is running in a multithreaded job.
ENOTSAFE is returned. Return Value
Procedure pointer to exit procedure
0 Qp0lSaveStgFree() was successful.
If the function type flag is 0, which indicates that a
−1 Qp0lSaveStgFree() was not successful. The
procedure is called instead of a program, this field
errno global variable is set to indicate the
contains a procedure pointer to the procedure that
error.
Qp0lSaveStgFree() calls. This field must be
NULL if the function type flag is 1.
Program library Error Conditions
If the function type flag is 1, indicating a program
is called, this field contains the library in which the If Qp0lSaveStgFree() is not successful, the errno indicates
program being called (identified by the program one of the following errors:
name field) is located. This field must be blank if [EACCES] Permission denied.
the function type flag is 0.
Program name An attempt was made to access an object in a
If the function type flag is 1, indicating a program way forbidden by its object access permis-
is called, this field contains the name of the sions.
program that is called. The program should be The thread does not have access to the speci-
located in the library identified by the program fied file, directory, component, or path.
library field. This field must be blank if the func-
If you are accessing a remote file through the
tion type flag is 0.
Network File System, update operations to file
Reserved
permissions at the server are not reflected at
A reserved field. This field must be set to binary
the client until updates to data that is stored
zero.
locally by the Network File System take place.
Function_CtlBlk_ptr (Several options on the Add Mounted File
(Input) A pointer to any data that the caller of System (ADDMFS) command determine the
Qp0lSaveStgFree() wants to have passed to the user- time between refresh operations of local data.)
defined Save Storage Free exit program that Access to a remote file may also fail due to
Qp0lSaveStgFree() calls to save an *STMF object. different mappings of user IDs (UID) or group
Qp0lSaveStgFree() does not process the data that is IDs (GID) on the local and remote systems.
referred to by this pointer. The API passes this pointer [EAGAIN] Operation would have caused the process to
as a parameter to the user-defined Save Storage Free be suspended.
exit program that was specified on its call. This is a [EBADNAME]
means for the caller of Qp0lSaveStgFree() to pass infor- The object name specified is not correct.
mation to and from the Save Storage Free exit program.
[EBUSY] Resource busy.
An attempt was made to use a system
Authorities
resource that is not available at this time.
[EDAMAGE] A damaged object was encountered.
A referenced object is damaged. The object
cannot be used.

3-24 AS/400 System API Reference V4R4

 Qp0lSaveStgFree

[EFAULT] The address used for an argument is not The entire system has too many other file
correct. descriptors already open.
In attempting to use an argument in a call, the
[ENOENT] No such path or directory.
system detected an address that is not valid. The directory or a component of the path
name specified does not exist.
While attempting to access a parameter
passed to this function, the system detected A named file or directory does not exist or is
an address that is not valid. an empty string.
[EINVAL] The value specified for the argument is not [ENOMEM] Storage allocation request failed.
correct.
A function needed to allocate storage, but no
A function was passed incorrect argument storage is available.
values, or an operation was attempted on an
There is not enough memory to perform the
object and the operation specified is not sup-
requested function.
ported for that type of object.
[ENOTDIR] Not a directory.
An argument value is not valid, out of range,
A component of the specified path name
or NULL.
existed, but it was not a directory when a
[EIO] Input/output error.
directory was expected.
A physical I/O error occurred.
Some component of the path name is not a
A referenced object may be damaged. directory, or is an empty string.
[EISDIR] Specified target is a directory. [ENOSPC] No space available.
The path specified named a directory where a The requested operations required additional
file or object name was expected. space on the device and there is no space
left. This could also be caused by exceeding
The path name given is a directory.
the user profile storage limit when creating or
[ELOOP] A loop exists in the symbolic links.
transferring ownership of an object.
This error is issued if the number of symbolic
Insufficient space remains to hold the intended
links encountered is more than
file, directory, or link.
POSIX_SYMLOOP (defined in the limits.h
header file). Symbolic links are encountered
[ENOSYSRSC]
System resources not available to complete
during resolution of the directory or path
request.
name.
[EMFILE] Too many open files for this process.
[ENOTSAFE] Function is not allowed in a job that is running
with multiple threads.
An attempt was made to open more files than
allowed by the value of OPEN_MAX. The
[ENOTSUP] Operation not supported.
value of OPEN_MAX can be retrieved using The operation, though supported in general, is
the sysconf() function. not supported for the requested object or the
requested arguments.
The process has more than OPEN_MAX
descriptors already open (see the sysconf() [EOFFLINE] Object is suspended.
function).
You have attempted to use an object that has
[ENAMETOOLONG] had its data saved and the storage associated
A path name is too long.
with it freed. An attempt to retrieve the
A path name is longer than PATH_MAX char- object's data failed. The object's data cannot
acters or some component of the name is be used until it is successfully restored. The
longer than NAME_MAX characters while object's data was saved and freed either by
_POSIX_NO_TRUNC is in effect. For sym- saving the object with the STG(*FREE)
bolic links, the length of the name string sub- parameter, or by calling an API.
stituted for a symbolic link exceeds
[EUNKNOWN]
PATH_MAX. The PATH_MAX and
Unknown system state.
NAME_MAX values can be determined using
the pathconf() function. The operation failed because of an unknown
system state. See any messages in the job
[ENFILE] Too many open files in the system.
log and correct any errors that are indicated,
A system limit has been reached for the then retry the operation.
number of files that are allowed to be concur-
rently open in the system.

Chapter 3. Backup and Recovery APIs 3-25

Restore from Application (QaneRsta) API

Error Messages
Required Parameter Group:
The following messages may be sent from this function:
1 Qualified user space Input Char(20)
CPI3C80 I An exit program has been called for which the
name
threadsafety status was not known. 2 User space format Input Char(8)
CPFA0D4 E name
File system error occurred. 3 Status format name Input Char(8)
CPE3418 E Possible APAR condition or hardware failure. 4 Status information Output Char(*)
CPF3CF2 E 5 Length of status infor- Input Binary(4)
Error(s) occurred during running of &1 API. mation
CPF9872 E Program or service program &1 in library &2 6 Error code I/O Char(*)
ended. Reason code &3.
Service Program: QANESERV

Usage Notes Threadsafe: No

Ÿ This function will fail with error code [ENOTSAFE] when

both of the following conditions occur: The Restore from Application (QaneRsta) API enables an
application to provide the restore records that are required
– There are secondary threads active in the job.
for a restore-from-save-file operation. The application
– The object this function is operating on resides in a defines the restore operation by specifying the type of restore
file system that is not threadsafe. Only the following command, and by providing the restore command parame-
file systems are threadsafe for this function: ters. The API calls an exit program to retrieve the restore
- Root records from the application instead of from the save file.

- QOpenSys To use the API, the application must provide the following:
- User-defined Ÿ A user space that contains the required input parameter
- QNTC group

- QSYS.LIB Ÿ An exit program

- QOPT When processing the restore command, the API does the fol-
- QLANSrv lowing:

Ÿ If the Save Storage Free exit program calls the SAV Ÿ Calls the exit program to indicate the start of the transfer
command or the QsrSave function or any other function sequence
that is not threadsafe, and there are secondary threads Ÿ Submits the restore command for processing
active in the job, Qp0lSaveStgFree() may fail as a
Ÿ Calls the exit program repeatedly to transfer the restore
result.
records
Ÿ If the Save Storage Free exit program is not threadsafe
Ÿ Calls the exit program to signal the end of the restore
or uses a function that is not threadsafe, then
operation
Qp0lSaveStgFree() is not threadsafe.
Ÿ May call the exit program to force an abnormal end to
the restore operation
Related Information
Ÿ The <Qp0lstdi.h> file The program that calls the API is suspended while the
restore operation is being processed.

Example
Restrictions
See Qp0lGetAttr() description for a code example that
shows a call to Qp0lSaveStgFree() by using a procedure as QTEMP should not be specified for the library name on the
the exit program. This API also shows an example of a call OUTFILE parameter because the restore command is sub-
to Qp0lGetAttr(). mitted by a prestart job running in the QSYSWRK subsystem
and not in the job that called the API. Locks should not be
applied to restore objects that would conflict with locks
applied by the restore operation running in the prestart job.
Restore from Application (QaneRsta) API
Objects can only be restored by this API if the objects were
saved using the “Save to Application (QaneSava) API” on
page 3-80, and only if the objects were saved from the
current or an earlier release of the operating system.

3-26 AS/400 System API Reference V4R4

 Restore from Application (QaneRsta) API

The application must provide the restore records in the order Status information
presented, without modification, for the objects to be suc- OUTPUT; CHAR(*)
cessfully restored.
The status information returned on the API call.

Length of status information

Authorities and Locks INPUT; BINARY(4)
Exit Program Library Authority
The length of the status information returned on the API
*EXECUTE
call. The minimum length is 8 bytes.
Exit Program Authority
*EXECUTE Error code
User Space Lock I/O; CHAR(*)
*SHRNUP
The structure in which to return error information. For
User Space Library Authority
the format of the structure, see “Error Code Parameter”
*USE
on page 2-6.
User Space Authority
*USE
Restore Command Library Authority SVRS0100 Format
*EXECUTE
Restore Command Authorities This format defines the input parameter group for the API.
See the restore command
Restored Object Locks Offset
See the Backup and Recovery book Dec Hex Type Field
Restored Object Authorities
0 0 Binary(4) Length of structure
See “Appendix D ”in the Security – Reference
book 4 4 Binary(4) Offset to restore command
parameters
8 8 Binary(4) Length of restore command
Required Parameter Group parameters
Qualified user space name 12 C Binary(4) Offset to application data
INPUT; CHAR(20) 16 10 Binary(4) Length of application data
The user space that contains all the control information 20 14 Binary(4) Restore command type
for the restore operation. The first 10 characters contain
24 18 Char(10) Exit program name
the user space name. The second 10 characters contain
the name of the library where the user space is located. 34 22 Char(10) Exit program library

You can use the following special values for the library | 44 2C Char(8) Target release
name: Char(*) Restore command parame-
ters
*CURLIB The job's current library is used to locate
the user space. If no library is specified Char(*) Application data
as the current library for the job, the
QGPL library is used. Field Descriptions:
*LIBL The library list is used to locate the user
space. Application data. Information that the application wants
passed to the exit program. The content of this information
The actual library that is used is returned in the status is defined by the application. This field could contain infor-
information. the user space. mation specific to the object being saved (such as the object
name, size, and so forth), or it could contain the qualified
User space format name
name of another object that contains this information.
INPUT; CHAR(8)
The format name for the input parameters that are con- Exit program library. The name of the library that contains
tained in the user space. For the format of the structure, the exit program called by the API. the exit program.
see “SVRS0100 Format.”
Exit program name. The name of the exit program that is
Status format name called by the API. See “Restore from Application Exit
INPUT; CHAR(8) Program” on page 3-83 for additional details.
The format name for the status information returned on
Length of application data. The length of the application
the API call. For the format of the structure, see
data. This value is passed to the exit program. This value
“SRST0100 Format” on page 3-28.
must be set to zero if there is no application data.

Chapter 3. Backup and Recovery APIs 3-27

Restore from Application (QaneRsta) API

Length of restore command parameters. The length of These additional restrictions apply to the command parame-
the restore command parameters. The maximum allowable ters when you use the Restore Object (QsrRestore) API.
length is 5900 bytes for restore commands.
Ÿ The keys specified must be consistent with restore from
Length of structure. The length of this structure, from the save file operations.
start of the input parameters to the last byte of the applica- Ÿ The DEV key must not be used. These key is provided
tion data. by this API.

Offset to application data. The byte offset from the begin- Ÿ The starting offset for the keys is always 0 and not the
ning of the user space to the start of the application data. offset of the restore command parameters.
This value must be set to zero if there is no application data. Ÿ All integer values within the keys must be aligned on
4-byte boundaries.
Offset to restore command parameters. The byte offset
from the beginning of the user space to the start of the Ÿ All pointers within the keys must be aligned on 16-byte
restore command parameters. boundaries.

Restore command parameters. A character string that Restore command type. The type of restore command that
contains the restore command parameters or restore keys. is to be processed.
These parameters are validated when the API submits the 1 Restore (RST) command
command for processing. Refer to the restore commands in 2 Restore Object (RSTOBJ) command
the CL Reference (Abridged) book for detailed information 3 Restore Document Library Object (RSTDLO)
about valid parameters when you restore objects from save command
files. Refer to “Restore Object (QsrRestore) API” on 4 Restore Library (RSTLIB) command
page 3-29 for detailed information about valid keys when you 5 Restore Object (QsrRestore) API
restore objects from save files.
| Target release.
These additional restrictions apply to the restore command
parameters when you use this API: | An ignored field. Must be set to blanks.

Ÿ The parameters must be consistent with the restore

command type. SRST0100 Format
Ÿ The parameters must not include the restore command This format defines the status information that is returned on
name. the API call.
Ÿ The parameters must be separated by at least one blank
character. Offset
Ÿ The DEV and SAVF parameters must not be used. Dec Hex Type Field
These parameters are provided by the API. 0 0 Binary(4) Bytes returned
Ÿ Only single library names can be used with the SAVLIB 4 4 Binary(4) Bytes available
or RSTLIB parameter.
8 8 Binary(4) Transfer time
The following examples illustrate the restore command 12 C Binary(4) Transfer block size
parameters that are required for typical restore scenarios: 16 10 Binary(4) Transfer block multiplier
Ÿ Example 1: Restore command type 1 (RST) 20 14 Binary(4) Last block size
OBJ('/\') ('/QSYS.LIB' \OMIT) 24 18 Char(10) User space library used
('/QDLS.LIB' \OMIT)
These parameters restore all objects that are not in Field Descriptions:
libraries and that are not document library objects.
Ÿ Example 2: Restore command type 2 (RSTOBJ) Bytes returned. The number of status information bytes
returned. If the value specified in the length of status infor-
OBJ(FILE\) SAVLIB(MYLIB) OBJTYPE(\FILE) mation parameter is larger than the specified status informa-
SAVDATE(122297) RSTLIB(TMPLIB) tion structure, this value is set to the last byte of the returned
These parameters restore all files with names that start information.
with the characters FILE* to library TMPLIB that were
saved from the library named MYLIB on 22 December Bytes available. The number of status information bytes
1997. available for the specified status information format.

Ÿ Example 3: Restore command type 4 (RSTLIB) Transfer block size. The number of bytes in the blocks
SAVLIB(JOE) transferred by the exit program.
These parameters restore the library named JOE.

3-28 AS/400 System API Reference V4R4

 Restore Object (QsrRestore) API

Transfer block multiplier. The number of blocks success- CPFB8C9 E

fully transferred by the exit program. Command exception occurred using &1 API.
CPFB8CF E
Last block size. The number of bytes in the last block Unexpected condition with &1 API. Reason &6.
transferred by the exit program.

The true transfer size of the operation is equal to the transfer

block size multiplied by the transfer block multiplier plus the Restore Object (QsrRestore) API
last block size.

Transfer time. The elapsed time, in seconds, that begins Required Parameter Group:
when the application calls the API, and ends when the API
1 Qualified user space Input Char(20)
returns to the caller.
name
2 Error code I/O Char(*)
User space library used. The name of the user space
library that is used in the API call.
Service Program: QSRLIB01

Error Messages Threadsafe: No

CPF3700 E All CPF37xx messages could be signalled. xx

is from 01 to FF, excluding tape and diskette The Restore Object (QsrRestore) API restores a copy of one
errors since the operation is a restore from a or more objects that can be used in the integrated file
save file. system.
CPF3800 E All CPF38xx messages could be signalled. xx
is from 01 to FF, excluding tape and diskette For detailed restrictions on using this API to restore objects
errors since the operation is a restore from a | in libraries or to restore document library objects, see the
save file. Backup and Recovery book.
CPF2115 E Object &1 in &2 type *&3 damaged.
CPF3C1E E Authorities and Locks
Required parameter &1 omitted.
CPF3C21 E User Space
Format name &1 is not valid.
User Space Authority
CPF3CF1 E
*USE
Error code parameter not valid.
User Space Library Authority
CPF8100 E All CPF81xx messages could be returned. xx is
| *EXECUTE
from 01 to FF.
User Space Lock
CPF9800 E All CPF98xx messages could be signaled. xx is
*EXCLRD
from 01 to FF.
CPF9999 E Function check. &1 unmonitored by &2 at state- Objects to Be Restored, Devices, and Output
ment &5, instruction &3.
CPFB8C0 E Locking See the Backup and Recovery book for
Status information length for &1 API is not valid. information on object locking for the
CPFB8C1 E Restore Object (RST) command.
Unsupported value for &1 API. Authority In the Security – Reference book, see the
CPFB8C2 E appendix about authorities required for the
Offset value for &1 API not valid. Reason &6. Restore Object (RST) command.
CPFB8C3 E
Length value for &1 API not valid. Reason &6. Required Parameter Group
CPFB8C4 E
Unexpected condition with exit program for &1 Qualified user space name
API. Reason &6. INPUT; CHAR(20)
CPFB8C5 E The user space that is to hold all the information for the
Parameter &2 specified more than once for API restore operation. The first 10 characters contain the
&1. user space name. The second 10 characters contain
CPIB8C6 I Trace data generated for API &1. the name of the library where the user space is located.
CPFB8C7 E See “User Space Format” on page 3-30 for the format of
Unsupported value for &1 API. the information in the user space.
CPFB8C8 E You can use the following special values for the library
Command syntax error detected by &1 API. name. However, it should be noted that the library
name that is actually used is not passed back to the

Chapter 3. Backup and Recovery APIs 3-29

 Restore Object (QsrRestore) API

user. Care should be taken when you use these special Field Descriptions
values to avoid unexpected results.
Data. The data used to specify the value for the given key.
*CURLIB The job’s current library is used to locate
the user space. If no library is specified Key. The parameter of the Restore Object (RST) command
as the current library for the job, the to specify. See “Valid Keys” for the list of valid keys.
QGPL library is used.
*LIBL The library list is used to locate the user Offset to first record. The offset from the beginning of the
space. user space to the first variable length record.
Error code Offset to next record. The offset from the beginning of the
I/O; CHAR(*) user space to the next variable length record.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Number of variable length records. The number of vari-
on page 2-6. | able length records that are passed in the user space. The
| valid range is from 2 through 16.

User Space Format Reserved. This field should contain blanks.

The following defines the format for the information in the

user space. For detailed descriptions of the fields in the user Valid Keys
space format, see “Field Descriptions.”
The following table lists the valid keys for the key field area
of the variable length record. For detailed descriptions of
Offset
the keys, see the “Field Descriptions” on page 3-31.
Dec Hex Type Field
Some messages for this API refer to parameters and values
0 0 BINARY(4) Number of variable length
records of the Restore Object (RST) command. This table can also
be used to locate the key names that correspond to the RST
4 4 BINARY(4) Offset to first record
command parameters. The field descriptions contain, in
8 8 CHAR(8) Reserved addition to detailed descriptions, the corresponding param-
Note: These fields repeat for each variable length record. eter values.
BINARY(4) Key The object path name key and the device path name key are
BINARY(4) Offset to next record required keys. The other keys are optional.
CHAR(8) Reserved
Key Type Field RST Command
CHAR(*) Data Parameter
1 CHAR(*) Device path DEV
If the length of the data is longer than the key identifier's data name
length, the data will be truncated at the right. No message
2 CHAR(*) Object path OBJ
will be issued.
name
If the specified data length is shorter than the key field's 3 CHAR(1) Directory SUBTREE
defined data length, an error message is returned for binary subtree
fields. If the field is a character field, the data is padded with 4 CHAR(1) System SYSTEM
blanks and an error message will not be returned.
5 CHAR(7) Save date SAVDATE
Note: This does not apply to keys that allow a list of values
6 CHAR(8) Save time SAVTIME
to be specified. In these cases, the amount of data read is
based on the specified number of entries in the list. 7 CHAR(1) Option OPTION
8 CHAR(*) Allow object ALWOBJDIF
If keys are duplicated in the user space, only the last value differences
| for a given key is used for the restore operation.
9 CHAR(2) Force object FRCOBJCVN
conversion
Each variable length record must be 4-byte aligned. If not,
unpredictable results may occur. 10 CHAR(*) Volume identi- VOL
fier
11 CHAR(*) Label LABEL
12 BINARY(4) Sequence SEQNBR
number

3-30 AS/400 System API Reference V4R4

 Restore Object (QsrRestore) API

object is not linked to its

Key Type Field RST Command
Parameter authorization list.
1 All differences are allowed
13 CHAR(1) End of tape ENDOPT
between the saved object and
option
the restored object. If 1 is
14 CHAR(*) Optical file OPTFILE specified for the allow object
15 CHAR(*) Output OUTPUT, INFTYPE difference field, 1 must be
specified for the number in
16 CHAR(*) Object ID OBJID
array field. (*ALL)
If the owner is different, the
Field Descriptions object is restored with the
owner of the object on the
The values shown in parentheses are the corresponding system to which it is restored.
values for the RST command parameters.
If the system is different for an
Allow object differences. Whether differences are allowed object with an authorization list,
between the saved object and the restored object. The differ- the object is restored and
ences include: linked to its authorization list.
2 The system of an object with
Offset an authorization list can be dif-
ferent. (*AUTL)
Dec Hex Type Field
If the system is different for an
BINARY(4) Number in array
object with an authorization list,
Note: This field repeats for each allow object difference value. the object is restored and
CHAR(1) Allow object difference linked to its authorization list.
3 The object owner can be dif-
Number in array. ferent. (*OWNER)
The number of allow object difference values. If the owner is different, the
The possible values are: object is restored with the
1-2 The number of allow object dif- owner of the object on the
ference values. system to which it is restored.
Allow object difference
Device path name. The path name of the device from
Whether differences are allowed between the
which the objects are restored.
saved object and the restored object. The dif-
ferences include:
Offset
Ownership: The owner of an object on
Dec Hex Type Field
the system is different than the owner of
an object from the save operation. BINARY(4) Number in array

Authorization list linkage: The system on BINARY(4) Offset to first device path
name
which an object with an authorization list
is being restored is different from the Note: These fields repeat for each device name.
system on which it was saved. BINARY(4) Offset to next device path
name
The default is 0.
CHAR(12) Reserved
The possible values are:
0 No differences are allowed CHAR(*) Device path name
between the saved object and
the restored object. If 0 is spec- Device path name.
ified for the allow object differ- The path name of the device used for the
ence field, 1 must be specified restore operation. The path name should be
for the number in array field. specified in the Qlg_Path_Name_T format. If
(*NONE) a pointer is specified in the path name format,
If the owner is different, the it must be 16-byte aligned. If not, unpredict-
object is not restored. able results may occur. For more information
on this structure, see “Path Name Format” on
If the system is different for an page 2-8.
object with an authorization list,
the object is restored, but the The possible values are:

Chapter 3. Backup and Recovery APIs 3-31

Restore Object (QsrRestore) API

device-path-name objects in the subdirectories are not included.

The path name of the diskette (*DIR)
device, media library device, 3 Only the objects that exactly match the object
optical device, save file, or tape name pattern are included. If the object name
device used to restore the pattern specifies a directory, objects in the
objects. If a diskette device, directory are not included. (*OBJ)
media library device, optical
device, or save file path name End of tape option. The operation that is automatically per-
is specified, it must be the only formed on the tape volume after the operation ends. If more
element in the array. than one volume is included, this key applies only to the last
Number in array. tape volume used; all other tape volumes are rewound and
The number of devices used during the unloaded when the end of the tape is reached. The default
restore operation. is 0.

The possible values are: The possible values are:

1-4 The number of devices used
during the restore operation.
0 The tape is automatically rewound, but not
unloaded, after the operation ends.
Offset to first device path name
(*REWIND)
The offset from the beginning of the user
space to the first device path name in the list.
1 The tape does not rewind or unload after the
operation ends. It remains at the current posi-
The possible values are: tion on the tape drive. (*LEAVE)
n The offset from the beginning 2 The tape is automatically rewound and
of the user space to the first unloaded after the operation ends.
device path name in the list. (*UNLOAD)
Offset to next device path name
The offset from the beginning of the user Force object conversion. Whether to convert user objects
space to the next device path name in the list. to the format required for use in the current version of the
operating system.
The possible values are:
n The offset from the beginning Note: If an object needs to be converted, but is not con-
of the user space to the next verted during the restore operation, the object is automat-
device path name in the list. If ically converted the first time it is used.
the current device path name is
the last device path name in Offset
the array, this value should be
Dec Hex Type Field
0.
Reserved Reserved. CHAR(1) Force conversion
CHAR(1) Objects to convert
The possible value is:
blanks This field should contain
blanks. Force conversion.
Whether objects should be converted on the
Directory subtree. Whether the directory subtrees are restore operation. The default is 2.
included in the restore operation. The default is 1.
The possible values are:
The possible values are: 0 The objects are not converted
during the restore operation.
0 No subtrees are included in the restore opera- (*NO)
tion. If a directory matches the object name 1 The objects are converted
pattern specified, the objects in the directory during the restore operation.
are included. If the directory has subdirecto- (*YES)
ries, neither the subdirectories nor the objects
in the subdirectories are included. (*NONE) Note: This value increases
1 The entire subtree of each directory that the time of the restore opera-
matches the object name pattern is included. tion, but avoids the need to
The subtree includes all subdirectories and convert the objects when they
the objects within those subdirectories. (*ALL) are first used.
2 The objects in the first level of each directory 2 The objects are converted
that matches the object name pattern are based on the value of the
included. The subdirectories of each QFRCCVNRST system value.
matching directory are included, but the (*SYSVAL)

3-32 AS/400 System API Reference V4R4

 Restore Object (QsrRestore) API

Note: If this value is specified file-identifier The identifier (maximum of 17 characters) of

and the system value the tape or diskette file used for the restore
QFRCCVNRST has a value of operation.
1, the restore operation pro-
ceeds as if 1 were specified for Object path name. The path name of the object to restore.
the force conversion field and 2 You can specify a pattern for this path name.
were specified for the objects
to convert field. Offset

If QFRCCVNRST has a value Dec Hex Type Field

of 0, the restore operation pro- BINARY(4) Number in array
ceeds as if 0 were specified for
BINARY(4) Offset to first object path
the force conversion field. name
Objects to convert.
Note: These fields repeat for each object path name.
Which objects should be converted on the
restore operation. The default is 2. BINARY(4) Offset to next object

The possible values are: BINARY(4) Offset to new object path

1 All objects are converted name
regardless of their current CHAR(1) Option
format. Even if the objects are CHAR(7) Reserved
in the current format, they are
CHAR(*) Object path name
converted again. However, if
the objects are not observable, CHAR(*) New path name
the objects are not restored.
(*ALL) New path name.
2 The objects are converted only The new path name of the object. The path
if they require conversion to be name should be specified in the
used by the current operating Qlg_Path_Name_T format. If a pointer is
system. If the objects are not specified in the path name format, it must be
observable, the objects are 16-byte aligned. If not, unpredictable results
restored but not converted. may occur. For more information on this
(*RQD) structure, see “Path Name Format” on
page 2-8.
Object ID. Whether the object ID of the restored object will
be the object ID of the object from the save media, the object The possible values are:
ID of the object that exists on the system prior to the restore, path-name The path name with which to
or a new object ID generated by the system if the object restore the object. If a pattern
does not exist on the system prior to the restore. The default is specified for the object path
is 0. name field, the new path name
must be an existing directory in
The possible values are: which to restore any objects
that match the pattern. If an
0 The restored object will have the object ID it
object name is specified in the
had when it was saved. (*SAVED)
object path name field, each
1 The restored object may have a new object ID
component in the new path
generated by the system. If the object is
name must exist with the
being restored as a new object, a new object
exception of the last compo-
ID will be given to the restored object. If an
nent. If the object described in
object with the same name as the object from
the last component does not
the media already exists on the system, the
exist, it will be restored as new.
object ID of the restored object will be the
Number in array.
same as the object ID of the object on the
The number of object path names to be
system before the restore. (*SYS)
restored.
Label. The file identifier of the media to be used for the The possible values are:
restore operation. The default is *SEARCH. 1-300 The number of object path
names to be restored.
The possible values are as follows: Object path name.
*SEARCH The file label for which to search is deter- The path names of the objects saved on the
mined by the system. media. Directory abbreviations (for example,
the current directory) are expanded with their

Chapter 3. Backup and Recovery APIs 3-33

Restore Object (QsrRestore) API

current values, not with the values they had at The possible values are:
the time of the save operation. The path 0 The objects that match the
name should be specified in the object name pattern are not
Qlg_Path_Name_T format. If a pointer is restored. This value overrides
specified in the path name format, it must be the objects that are included
16-byte aligned. If not, unpredictable results with option 1 and is intended to
may occur. For more information on this be used to omit a subset of a
structure, see “Path Name Format” on previously selected pattern.
page 2-8. (*OMIT)
The possible value is:
1 The objects that match the
object name pattern are
path-name The path name or pattern that
restored, unless overridden by
can match many names. If 0 is
an omit specification.
specified for the new name
(*INCLUDE)
option, each component in the
path name must exist with the
Reserved Reserved.
exception of the last compo- The possible value is:
nent. The name in the last blanks This field should contain
component is restored as new blanks.
if it does not exist.
Offset to first object path name. Optical file. The path name of the optical file that is used
The offset from the beginning of the user for the restore operation. The path name should be specified
space to the first object path name. in the Qlg_Path_Name_T format. If a pointer is specified in
the path name format, it must be 16-byte aligned. If not,
The possible value is:
unpredictable results may occur. For more information on
n The offset from the beginning
this structure, see “Path Name Format” on page 2-8.
of the user space to the first
object path name. Note: This key is required when using an optical device.
Offset to new object path name.
The possible value follows:
The offset from the beginning of the user
space to the new object path name. Optical file The path name of the optical file that is used
for the restore operation, beginning with the
The possible values are:
root directory of the volume.
0 There is not a new object path
name. The object will be When using a CD-ROM device, the extension
restored to the same name with separator, the version separator, and the
which it was saved. version number must be included at the end
n The offset from the beginning of the path name. For example, a file named
of the user space to the new 'myfile' that is in the root directory of the
object path name. volume, and that has no extension and only a
Offset to next object. single version, is specified as '/myfile.;1'.
The offset from the beginning of the user
space to the next object in the list. Option. Whether to restore objects that already exist on the
system or to restore objects that do not already exist on the
The possible value is:
system. The default is 0.
n The offset from the beginning
of the user space to the next The possible values are:
object in the list. If the current
object is the last object in the
0 All of the specified objects are restored,
whether or not they already exist on the
array, this value should be 0.
system. (*ALL)
Option. Whether names that match the pattern should
be included or omitted from the restore opera-
1 Objects are restored only if they do not
already exist on the system. (*NEW)
tion. Note that in determining whether the
name matches a pattern, relative name pat-
2 Objects are restored only if they already exist
on the system. (*OLD)
terns are always treated as relative to the
current working directory.
Output. Whether a list of information about the restored
Note: The subtree key specifies whether the objects is created. The information can be directed to a
subtrees are included or omitted. spooled file, a stream file, or a user space.

3-34 AS/400 System API Reference V4R4

 Restore Object (QsrRestore) API

Save date. The date the objects were saved. If the most
Offset
recently saved version is the one being restored, or if mul-
Dec Hex Type Field tiple saved versions reside on the media, specify the date
CHAR(1) Option that identifies which version of the objects to restore. If this
CHAR(1) Type of output information key is not specified, the restored version of the objects is the
first version found.
CHAR(14) Reserved
CHAR(*) Output path name The possible values are:
date The date the objects were saved, in the
Option. Whether a list of information about the format CYYMMDD:
restored objects is created. The default is 0. C Century, where 0 indicates
The possible values are: years 19xx and 1 indicates
0 No output is created. (*NONE) years 20xx.
1 The output is printed with the YY Year
job’s spooled output. (*PRINT) MM Month
2 The output is directed to an DD Day
existing stream file or user
Save time. The time the objects were saved. If this key is
space specified by the output
not specified, the version of the objects to be restored is the
path name.
first version on the volume.
Output path name.
The path name should be specified in the Note:
Qlg_Path_Name_T format. If a pointer is 1. This key is valid only if the save date key is specified.
specified in the path name format, it must be 2. This key is ignored when the sequence number key is
16-byte aligned. If not, unpredictable results specified.
may occur. For more information on this
structure, see “Path Name Format” on The possible values are:
page 2-8.
time The time the objects were saved in the format
The possible value is: HHMMSS:
path-name The path name of the existing HH Hour
stream file or user space to MM Minute
which the output of the SS Second
command is directed.
Reserved Reserved. Sequence number. The tape file sequence number to be
used. The default is -1.
The possible value is:
blanks This field should contain The possible values are:
blanks.
Type of output information. -1 The tape volume is searched for the next file
The type of information that should be that contains any of the specified objects.
directed to the spooled file, stream file, or user (*SEARCH)
space specified for the output key. 1-16777215 The sequence number of the file.

The possible values are: System. Whether to process objects that exist on the local
0 The file will contain information system or remote systems. The default is 0.
about the command, and an
entry for each directory. The possible values are:
(*SUMMARY) 0 Only local objects are processed. (*LCL)
1 The file will contain information 1 Only remote objects are processed. (*RMT)
about the command, an entry 2 Both local and remote objects are processed.
for each directory, and an entry (*ALL)
for each object that was not
successfully restored. (*ERR) Volume identifier. The volume identifiers of the volumes, or
2 The file will contain information the cartridge identifier of a tape in a tape media library
about the command, an entry device, from which data is to be restored. The volumes must
for each directory, an entry for be placed in the device in the order specified on this key.
each object that was success- After all specified volumes are filled, the restore operation
fully restored, and an entry for continues on whatever volumes are mounted on the device.
each object that was not suc-
cessfully restored. (*ALL)

Chapter 3. Backup and Recovery APIs 3-35

Restore Object (QsrRestore) API

n The offset from the beginning

Offset
of the user space to the first
Dec Hex Type Field volume identifier in the list.
BINARY(4) Number in array Offset to next volume identifier
BINARY(4) Length of each volume The offset from the beginning of the user
identifier space to the next object volume identifier in
the list.
BINARY(4) Offset to first volume identi-
fier The possible value is:
Note: These fields repeat for each volume identifier n The offset from the beginning
of the user space to the next
BINARY(4) Offset to next volume identi-
volume identifier in the list. If
fier
the current volume identifier is
CHAR(*) Volume identifier the last volume identifier in the
array, this value should be 0.
Length of each volume identifier. Volume identifier.
The character length of each of the volume The volume identifiers of one or more volumes
identifiers. to be used.
The possible value follows: The possible value is:
n The size of a single volume Volume identifier
identifier. The maximum size The volume identifiers of one or
of a tape or diskette volume more volumes to be used.
identifier is 6 characters. The
maximum size of an optical
volume identifier is 32 charac- Dependencies between Keys
ters. If a volume identifier
larger than the maximum size The following two tables list the dependencies between the
is entered for this key, it is trun- different keys. If the dependency pertains only to a certain
cated to the maximum size. value, then that value is also shown (key = n, where n is the
Number in array. value). Otherwise, if the dependency is true for all values of
The number of volume identifiers that are the key, then only the name of the key is given.
used during the restore operation. The default
The following table lists the conditions where specifying a
is 0.
certain key forces the use of another key.
The possible values are:
0 The volume currently placed in If you specify... ...must be specified
the device is used. If 0 is
Device = optical device Volume identifier
specified for a tape media
Optical file
library device, volume identi-
fiers must be supplied by using
the Tape Management exit The following table lists the conditions where specifying a
program during the save or certain key excludes the user from using another key or a
restore operation. If 0 is speci- particular value of that key.
fied, the length of each volume
identifier value is ignored. If you specify... ...cannot be specified
(*MOUNTED) Device = diskette device End of tape option
Optical file
Note: This value cannot be
Sequence number
specified for an optical media
library device. Device = optical device End of tape option
Label
1-75 The number of volume identi-
Sequence number
fiers used during the restore
operation. Device = save file End of tape option
Offset to first volume identifier Label
Optical file
The offset from the beginning of the user
Sequence number
space to the first volume identifier in the list. Volume identifier
The possible value is: Device = tape device Optical file

3-36 AS/400 System API Reference V4R4

 Retrieve Backup Detail (QEZRTBKD) API

Relationship to RST Command Parameters

Due to the relationship between the QsrRestore API and the Required Parameter Group:
RST command, the following situations should be noted:
1 Receiver variable Output Char(*)
Ÿ Message text: Several messages produced by this API 2 Length of receiver variable Input Binary(4)
refer to parameters or values of the RST command (for 3 Object name Input Char(*)
example, *SEARCH). To determine which key a given 4 Object name length Input Binary(4)
parameter corresponds to, see “Valid Keys” on 5 Format name Input Char(8)
6 Object type Input Char(10)
page 3-30. To determine which key value a given
7 Error Code I/O Char(*)
parameter value corresponds to, see “Field Descriptions”
on page 3-31.
Ÿ Command type: The command type listed for the API The Retrieve Backup Detail (QEZRTBKD) API retrieves more
on headings of displays and print files is QsrRestore for detailed information about the library or folder that is to be
integrated file system objects. If QsrRestore is used to backed up.
restore objects in libraries or document library objects
(DLOs), the generated output indicates that the corre-
sponding library or DLO command generated the media. Authorities and Locks
Backup Object *USE
Error Messages
CPF0001 E Error found on &1 command. Required Parameter Group
CPF24B4 E Severe error while addressing parameter list. Receiver variable
CPF3700 E All CPF37xx messages could be signalled. xx OUTPUT; CHAR(*)
is from 01 to FF. The receiver variable that receives the information
CPF3800 E All CPF38xx messages could be signalled. xx requested. You can specify the size of the area to be
is from 01 to FF. smaller than the format requested as long as you specify
CPF3C31 E the length parameter correctly. As a result, the API
Object type &1 is not valid. returns only the data that the area can hold.
CPF3C4D E
Length &1 for key &2 not valid. Length of receiver variable
CPF3C81 E INPUT; BINARY(4)
Value for key &1 not valid. The length of the receiver variable provided. The length
CPF3C82 E of receiver variable parameter may be specified up to
Key &1 not valid for API &2. the size of the receiver variable specified in the user
CPF3C83 E program. If the length of receiver variable parameter
Key &1 not allowed with value specified for key specified is larger than the allocated size of the receiver
&2. variable specified in the user program, the results are
CPF3C84 E not predictable. The minimum length is 8 bytes.
Key &1 required with value specified for key &2.
Object name
CPF3C85 E
INPUT; CHAR(*)
Value for key &1 not allowed with value for key
The name of the object to retrieve backup detail informa-
&2.
tion about. The length of this field is based on the
CPF3C86 E
Object type parameter and the Object name length
Required key &1 not specified.
parameter. Specify either a 10-character library name or
CPF3C87 E
specify a 12-character folder name.
Key &1 allows one value with special value.
CPF3C90 E Object name length
Literal value cannot be changed. INPUT; BINARY(4)
CPF3CF1 E The length of the name of the object to retrieve backup
Error code parameter not valid. detail information about.
CPF5729 E Not able to allocate object &1.
Allowable object name lengths follow:
CPF9800 E All CPF98xx messages could be signaled. xx is
from 01 to FF. 10 The 10-character library name when the Object
CPF9999 E Function check. &1 unmonitored by &2 at state- type parameter is *LIB.
ment &5, instruction &3. 12 The 12-character folder name when the Object
type parameter is *FLR.

Retrieve Backup Detail (QEZRTBKD) API

Chapter 3. Backup and Recovery APIs 3-37

Retrieve Backup History (QEZRTBKH) API

Format name HH Hour

INPUT; CHAR(8) MM Minute
The name of the format to be used to return information SS Second
to caller. The following format may be used:
Object description text. The text that describes the object.
RBKD0100 Backup detail information. For more
information, see “RBKD0100 Format.”
Error Messages
Object type
CPF1EC7 E
INPUT; CHAR(10)
The length &1 is not valid when the specified
The type of object for which you are requesting informa-
type is &2.
tion. Allowable object types follow:
CPF24B4 E Severe error while addressing parameter list.
*FLR Folder CPF3C19 E
*LIB Library Error occurred with receiver variable specified.
CPF3C21 E
Error code Format name &1 is not valid.
I/O; CHAR(*) CPF3C31 E
The structure in which to return error information. For Object type &1 is not valid.
the format of the structure, see “Error Code Parameter” CPF3C24 E
on page 2-6. Length of the receiver variable is not valid.
CPF3C90 E
Literal value cannot be changed.
RBKD0100 Format CPF3CF1 E
Error code parameter not valid.
Offset CPF8148 E Object &4 type &3 in &9 damaged.
Dec Hex Type Field CPF8A75 E Not authorized to access folder &1.
0 0 BINARY(4) Bytes available CPF8A77 E Folder &1 not found.
CPF8A78 E Folder &1 in use.
4 4 BINARY(4) Bytes returned
CPF8A79 E Folder &1 is logically damaged.
8 8 CHAR(7) Last saved date CPF8A80 E Document &2 in use in folder &1.
15 F CHAR(6) Last saved time CPF9012 E Start of document interchange session not suc-
cessful for &1.
21 15 CHAR(50) Object description text
CPF9032 E Document interchange session not started.
71 47 CHAR(1) Changed since last backup CPF9076 E Internal system error processing documents or
folders.
CPF9095 E Folder &1 is damaged.
Field Descriptions CPF909A E Document &2 in folder &1 is damaged.
CPF9810 E Library &1 not found.
Bytes available. The number of bytes of data available to CPF9820 E Not authorized to use library &1.
be returned. All available data is returned if enough space is CPF9830 E Cannot assign library &1.
provided. CPF9838 E User profile storage limit exceeded.
CPF9872 E Program or service program &1 in library &2
Bytes returned. The number of bytes of data returned.
ended. Reason code &3.
Changed since last backup. Whether the object changed CPF9999 E Function check. &1 unmonitored by &2 at state-
since the last backup. Possible values follow: ment &5, instruction &3.

0 No change has been made since the last backup.

1 Change has been made since the last backup.
Retrieve Backup History (QEZRTBKH) API
Last saved date. The date that the object was last saved to
media. The format of this field is in the CYYMMDD as
follows: Required Parameter Group:
C Century, where 0 indicates years 19xx and 1 1 Receiver variable Output Char(*)
indicates years 20xx. 2 Length of receiver variable Input Binary(4)
YY Year 3 Format name Input Char(8)
MM Month 4 Error code I/O Char(*)
DD Day
Threadsafe: No
Last saved time. The time that the object was last saved to
media. The format of this field is in the HHMMSS as follows:

3-38 AS/400 System API Reference V4R4

 Retrieve Backup History (QEZRTBKH) API

The Retrieve Backup History (QEZRTBKH) API retrieves

Offset
information about the backup status and history into a single
variable in the calling program. The amount of information Dec Hex Type Field
that is returned depends on the size of the variable. The 0 0 BINARY(4) Bytes returned
information that this API returns is the same information that 4 4 BINARY(4) Bytes available
the Display Backup Status (DSPBCKSTS) command returns.
8 8 CHAR(7) Last date all user libraries
backed up
Authorities and Locks 15 F CHAR(6) Last backup time of all user
User Index Authority libraries
*USE 21 15 CHAR(4) Tape set for all user
User Index Lock libraries
*SHRRD 25 19 CHAR(7) Last date all user libraries
backed up (changes only)

Required Parameter Group 32 20 CHAR(6) Last backup time of all user

libraries (changes only)
Receiver variable
38 26 CHAR(4) Tape set for all user
OUTPUT; CHAR(*) libraries (changes only)
The receiver variable that receives the information 42 2A CHAR(7) Last date libraries on list
requested. You can specify the size of the area to be backed up
smaller than the format requested as long as you specify
49 31 CHAR(6) Last backup time of libraries
the length parameter correctly. As a result, the API on list
returns only the data that the area can hold.
55 37 CHAR(4) Tape set for libraries on list
Length of receiver variable 59 3B CHAR(7) Last date libraries on list
INPUT; BINARY(4) backed up (changes only)
The length of the receiver variable provided. The length 66 42 CHAR(6) Last backup time of libraries
of receiver variable parameter may be specified up to on list (changes only)
the size of the receiver variable specified in the user 72 48 CHAR(4) Tape set for libraries on list
program. If the length of receiver variable parameter (changes only)
specified is larger than the allocated size of the receiver
76 4C CHAR(7) Last date all folders backed
variable specified in the user program, the results are
up
not predictable. The minimum length is 8 bytes.
83 53 CHAR(6) Last backup time of all
Format name folders
INPUT; CHAR(8) 89 59 CHAR(4) Tape set for folders
The format of the command information to be returned. 93 5D CHAR(7) Last date all folders backed
One of the following format names may be used: up (changes only)

RBKH0100 Basic backup status and history. For 100 64 CHAR(6) Last backup time of all
more information, see “RBKH0100 folders (changes only)
Format.” 106 6A CHAR(4) Tape set for folders
RBKH0200 Detailed backup status and information. (changes only)
For more information, see “RBKH0200 110 6E CHAR(7) Last date folders on list
Format” on page 3-40. backed up

Error code 117 75 CHAR(6) Last backup time of folders

I/O; CHAR(*) on list
123 7B CHAR(4) Tape set for folders on list
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” 127 7F CHAR(7) Last date security data
on page 2-6. backed up
134 86 CHAR(6) Last backup time of security
data
RBKH0100 Format
140 8C CHAR(4) Tape set for security data
The following table describes the information that is returned 144 90 CHAR(7) Last date configuration data
in the receiver variable for the RBKH0100 format. For backed up
detailed descriptions of the fields, see “Field Descriptions” on 151 97 CHAR(6) Last backup time of
page 3-40. configuration

Chapter 3. Backup and Recovery APIs 3-39

Retrieve Backup History (QEZRTBKH) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
157 9D CHAR(4) Tape set for configuration CHAR(1) Folders saved
data
CHAR(1) User directories saved
161 A1 CHAR(7) Last date calendars backed
CHAR(1) Security data saved
up
CHAR(1) Configuration saved
168 A8 CHAR(6) Last backup time of calen-
dars CHAR(1) Calendars saved
174 AE CHAR(4) Tape set for calendars CHAR(1) Mail saved
178 B2 CHAR(7) Last date mail backed up
185 B9 CHAR(6) Last backup time of mail Field Descriptions
191 BF CHAR(4) Tape set for mail
Some of the fields use a date format (CYYMMDD) as
195 C3 CHAR(7) Last date all user directories
backed up
follows:

202 CA CHAR(6) Last backup time of all user C Century, where 0 indicates years 19xx and 1
directories indicates years 20xx.
YY Year
208 D0 CHAR(4) Tape set for all user directo-
ries backed up MM Month
DD Day
212 D4 CHAR(7) Last date all user directories
backed up (changes only) Some of the fields use a time format (HHMMSS), where:
219 DB CHAR(6) Last backup time of all user HH Hour
directories (changes only)
MM Minute
225 E1 CHAR(4) Tape set for all user directo- SS Second
ries backed up (changes
only) For more information on the following fields, refer to the doc-
229 E5 CHAR(21) Reserved umentation for the Display Backup Status (DSPBCKSTS)
command in the CL Reference (Abridged) manual.

RBKH0200 Format Backup date. The completion date of the backup. This date
is in the format CYYMMDD.
The following table describes the information that is returned
in the receiver variable for the RBKH0200 format. For Backup time. The completion time of the backup. This time
detailed descriptions of the fields, see “Field Descriptions.” is in the format HHMMSS.

Backup options. The backup option that were used. The

Offset
possible values are:
Dec Hex Type Field
*DAILY
0 0 Returns everything from
format RBKH0100 *WEEKLY

250 FA BINARY(4) Number of backup date *MONTHLY

entries
Bytes available. The number of bytes of data available to
254 FE BINARY(4) Length of a backup date
be returned. All available data is returned if enough space is
entry
provided.
Note: Format of a backup date entry. The backup date entry
fields repeat, in the order listed, by the number of backup date Bytes returned. The number of bytes of data returned.
entries. The decimal and hexadecimal offsets to the following
fields depend on the number of backup date entries and the Calendars saved. Whether OfficeVision calendars were
length of a backup date entry. saved during the backup.
CHAR(7) Backup date 0 No OfficeVision calendars were saved during
CHAR(6) Backup time the backup.
CHAR(10) Backup options 1 All OfficeVision calendars were saved during
the backup.
CHAR(4) Tape set
CHAR(1) Changes only Changes only. Whether the backup saved only the changes
to libraries, directories, and folders.
CHAR(1) User libraries saved

3-40 AS/400 System API Reference V4R4

 Retrieve Backup History (QEZRTBKH) API

0 All objects in the libraries, folders, and directo- Last backup time of configuration. The completion time of
ries were saved during the backup. the most recent backup of the system configuration. This
1 Only changes made to the libraries, folders, uses the 24-hour clock and is in the format HHMMSS.
and directories since the last backup were
saved during the backup. Last backup time of folders on list. The completion time
of the most recent backup of all the objects in all the folders
Configuration saved. Whether the system configuration on the folder backup list. This time uses the 24-hour clock
was saved. and is in the format HHMMSS.
0 The system configuration was not saved Last backup time of libraries on list. The completion time
during the backup. of the most recent backup of all the objects in all the libraries
1 The system configuration was saved during on the library backup list. This time uses the 24-hour clock
the backup. and is in the format HHMMSS.
Folders saved. Which folders were saved during the Last backup time of libraries on list (changes only). The
backup. The possible values follow: completion time of the most recent backup of all the objects
1 Only folders that were selected from the folder in all the libraries on the library backup list that changed
backup list were saved. since the previous backup. This time uses the 24-hour clock
2 All folders were saved. and is in the format HHMMSS.
3 No folders were saved.
Last backup time of security data. The completion time of
Last backup time of calendars. The completion time of the the most recent backup of all the system security data. This
most recent backup of all the calendars for OfficeVision. This uses the 24-hour clock and is in the format HHMMSS.
time uses the 24-hour clock and is in the format HHMMSS.
Last date all folders backed up. The completion date for
Last backup time of mail. The completion time of the most the most recent backup of all the objects in all the root
recent backup of all the mail for OfficeVision. This time uses folders on the system. This date is in the format CYYMMDD.
the 24-hour clock and is in the format HHMMSS.
Last date all folders backed up (changes only). The com-
Last backup time of all folders. The completion time of the pletion date for the most recent backup of all the objects in
most recent backup of all the objects in all the root folders. all the folders that changed since the previous backup. This
This time uses the 24-hour clock and is in the format date is in the format CYYMMDD.
HHMMSS.
Last date all user directories backed up (changes only).
Last backup time of all folders (changes only). The com- The completion date for the most recent backup of all the
pletion time of the most recent backup of all the objects in all objects in all the user directories that changed since the pre-
the root folders that changed since the previous backup. vious backup. This date is in the format CYYMMDD.
This time uses the 24-hour clock and is in the format
HHMMSS. Last date all user directories backed up. The completion
date for the most recent backup of all the objects in all the
Last backup time of all user directories. The completion user directories on the system. This date is in the format
time of the most recent backup of all the objects in all the CYYMMDD.
user directories on the system. This time uses the 24-hour
clock and is in the format HHMMSS. Last date all user libraries backed up. The completion
date for the most recent backup of all the objects in all the
Last backup time of all user directories (changes only). user libraries on the system. This date is in the format
The completion time of the most recent backup of all the CYYMMDD.
objects in all the user directories that changed since the pre-
vious backup. This time uses the 24-hour clock and is in the Last date all user libraries backed up (changes only).
format HHMMSS. The completion date for the most recent backup of all the
objects in all the user libraries that changed since the pre-
Last backup time of all user libraries. The completion vious backup. This date is in the format CYYMMDD.
time of the most recent backup of all the objects in all the
user libraries on the system. This time uses the 24-hour Last date calendars backed up. The completion date for
clock and is in the format HHMMSS. the most recent backup of all the OfficeVision calendars on
the system. This date is in the format CYYMMDD.
Last backup time of all user libraries (changes only).
The completion time of the most recent backup of all the Last date configuration data backed up. The last backup
objects in all the user libraries that changed since the pre- date for the most recent backup of the system configuration.
vious backup. This time uses the 24-hour clock and is in the
Last date folders on list backed up. The completion date
format HHMMSS.
for the most recent backup of all the objects in all the folders

Chapter 3. Backup and Recovery APIs 3-41

Retrieve Backup History (QEZRTBKH) API

in the folder backup list. This date is in the format the objects in all the user libraries on the system. The pos-
CYYMMDD. sible value follows:

Last date libraries on list backed up. The completion date

*ANY The option that the system used for the
backup did not specify a tape set name.
for the most recent backup of all the objects in all the
libraries in the library backup list. This date is in the format
Tape set for all user libraries (changes only). The name
CYYMMDD.
of the last tape set that the system used for the most recent
backup of all the objects in all the user libraries that changed
Last date libraries on list backed up (changes only). The
since the previous backup. The possible value follows:
completion date for the most recent backup of all the objects
in all the libraries in the library backup list that changed since *ANY The option that the system used for the
the previous backup. This date is in the format CYYMMDD. backup did not specify a tape set name.

Last date mail backed up. The completion date for the Tape set for calendars. The name of the last tape set that
most recent backup of all the OfficeVision mail on the the system used for the most recent backup of all the calen-
system. This date is in the format CYYMMDD. dars for OfficeVision. The possible value follows:

Last date security data backed up. The last backup date
*ANY The option that the system used for the
backup did not specify a tape set name.
for the most recent backup of system security data.
Tape set for configuration. The name of the last tape set
Length of a backup date entry. The length of one backup
that the system used for the most recent backup of the
date entry.
system configuration. The possible value follows:
Mail saved. Whether mail was saved during the backup. *ANY The option that the system used for the
0 OfficeVision mail was not saved during the backup did not specify a tape set name.
backup.
Tape set for folders. The name of the last tape set that t
1 OfficeVision mail was saved during the
he system used for the most recent backup of all the objects
backup.
in all the root folders on the system. The possible value
Number of backup date entries. The number of backup follows:
date e ntries that are contained in format RBKH0200. *ANY The option that the system used for the
backup did not specify a tape set name.
Reserved. This space is reserved for future use.
Tape set for folders (changes only). The name of the last
Security data saved. Whether the security data was saved.
tape set that the system used for the most recent backup of
0 Security data was not saved during the all the new and changed documents from all the new and
backup. changed root folders since the previous backup. The pos-
1 Security data was saved during the backup. sible value follows:

Tape set. The name of the last tape set that the system
*ANY The option that the system used for the
backup did not specify a tape set name.
used to complete the backup of the information described in
this backup date entry.
Tape set for folders on list. The name of the last tape se t
that the system used for the most recent backup of all the
Tape set for all user directories backed up. The name of
folders that were selected for backup from the folder backup
the last tape set that the system used for the most recent
list. The possible value follows:
backup of all the objects in all the user directories on the
system. The possible value follows: *ANY The option that the system used for the
backup did not specify a tape set name.
*ANY The option that the system used for the
backup did not specify a tape set name.
Tape set for libraries on list. The name of the last tape set
that the system used for the most recent backup of all the
Tape set for all user directories backed up (changes
libraries on the library backup list. The possible value
only). The name of the last tape set that the system used
follows:
for the most recent backup of all the objects in all the user
directories that changed since the previous backup. The *ANY The option that the system used for the
possible value follows: backup did not specify a tape set name.
*ANY The option that the system used for the
Tape set for libraries on list (changes only). The name of
backup did not specify a tape set name.
the last tape set that the system used for the most recent
backup of all the objects in the libraries on the library backup
Tape set for all user libraries. The name of the last tape
list that changed since the previous backup. The possible
set that the system used for the most recent backup of all
value follows:

3-42 AS/400 System API Reference V4R4

 Retrieve Backup Options (QEZRTBKO) API

*ANY The option that the system used for the The Retrieve Backup Options (QEZRTBKO) API returns in a
backup did not specify a tape set name. receiver variable the backup options for the requested
backup type. If you request all options, the receiver variable
Tape set for mail. The name of the last tape set that the contains the header, which is followed by three RBKO0100
system used for the most recent backup of all the mail for formats, one for each backup type.
OfficeVision. The possible value follows:
*ANY The option that the system used for the Authorities and Locks
backup did not specify a tape set name.
User Index Authority
Tape set for security data. The name of the last tape set *USE
that the system used for the most recent backup of the User Index Lock
system security data. The possible value follows: *SHRRD
*ANY The option that the system used for the
backup did not specify a tape set name. Required Parameter Group
User directories saved. The directories that were saved Receiver variable
during the backup. The possible values follow: OUTPUT; CHAR(*)
2 All user directories were saved. The receiver variable that receives the information
3 No user directories were saved. requested. You can specify the size of the area to be
smaller than the format requested as long as you specify
User libraries saved. The libraries that were saved during the length parameter correctly. As a result, the API
the backup. The possible values follow: returns only the data that the area can hold.
1 Only user libraries that were selected from the Length of receiver variable
library backup list were saved. INPUT; BINARY(4)
2 All user libraries were saved.
3 No user libraries were saved. The length of the receiver variable provided. The length
of receiver variable parameter may be specified up to
the size of the receiver variable specified in the user
Error Messages program. If the length of receiver variable parameter
CPF1E00 E All CPF1Exx messages could be returned. xx specified is larger than the allocated size of the receiver
is from 01 to FF. variable specified in the user program, the results are
CPF24B4 E Severe error while addressing parameter list. not predictable. The minimum length is 8 bytes.
CPF3CF1 E Format name
Error code parameter not valid. INPUT; CHAR(8)
CPF3C19 E
Error occurred with receiver variable specified. The format of the backup option descriptions to be
CPF3C21 E returned. The valid format names are RBKO0100 and
Format name &1 is not valid. RBKO0200.
CPF3C24 E RBKO0100 This format returns information about
Length of the receiver variable is not valid. what the user has selected to be saved
CPF3C90 E on the next backup for that type (*DAILY,
Literal value cannot be changed. *WEEKLY, or *MONTHLY).
CPF9872 E Program or service program &1 in library &2 RBKO0200 This format returns information on the last
ended. Reason code &3. backup date and time, and when the next
backup date and time for that backup
option are scheduled to occur.
Retrieve Backup Options (QEZRTBKO) API
Backup option
INPUT; CHAR(10)
Required Parameter Group: The backup options to retrieve. Possible values follow:

1 Receiver variable Output Char(*) *DAILY Daily backup options.

2 Length of receiver variable Input Binary(4) *WEEKLY Weekly backup options.
3 Format name Input Char(8) *MONTHLY Monthly backup options.
4 Backup option Input Char(10) *ALL The backup options for all types of
5 Error Code I/O Char(*)
backup (*DAILY, *WEEKLY, and
*MONTHLY).
Threadsafe: No

Chapter 3. Backup and Recovery APIs 3-43

Retrieve Backup Options (QEZRTBKO) API

Error code
Offset
I/O; CHAR(*)
Dec Hex Type Field
The structure in which to return error information. For
55 37 CHAR(1) Reserved
the format of the structure, see “Error Code Parameter”
on page 2-6. 56 38 BINARY(4) Offset to additional infor-
mation
The offsets to ARRAY OF Backup devices
RBOH0100 Format these fields CHAR(10)
depend on the
ARRAY OF Tape sets to rotate
Offset number of
CHAR(4)
Dec Hex Type Field backup
devices and
0 0 BINARY(4) Bytes returned the number of
4 4 BINARY(4) Bytes available tape sets to
rotate.
8 8 BINARY(4) Offset to daily options
12 C BINARY(4) Offset to weekly options
16 10 BINARY(4) Offset to monthly options RBKO0200 Format
Offset
RBKO0100 Format Dec Hex Type Field
Note: The following is accessed by using the offsets that 0 0 CHAR(*) All data in format
are provided in format RBOH0100. RBKO0100
The offsets to CHAR(7) Last backup date
Offset these fields
CHAR(6) Last backup time
depend on the
Dec Hex Type Field
number of CHAR(7) Next backup date
0 0 BINARY(4) Offset to list of backup backup
CHAR(6) Next backup time
device names devices and
4 4 BINARY(4) Number of backup the number of
devices tape sets to
rotate.
8 8 BINARY(4) Offset to list of tape sets
to rotate
12 C BINARY(4) Number of tape sets to Field Descriptions
rotate
16 10 CHAR(4) Last tape set used Back up configuration data. Whether to save the system
configuration data. Possible values follow:
20 14 CHAR(4) Next tape set to be used
0 Do not save configuration data.
24 18 CHAR(1) Erase tape before backup
1 Save configuration data.
25 19 CHAR(1) Back up user libraries
26 1A CHAR(1) Back up folders
Backup devices. The tape devices that are used for a
backup.
27 1B CHAR(1) Back up user directories
28 1C CHAR(1) Back up security data Back up folders. Which root folders are backed up. Pos-
sible values follow:
29 1D CHAR(1) Back up configuration
data 1 The root folders that are selected for backup
30 1E CHAR(1) Back up OfficeVision mail in the folder backup list are backed up.
2 All root folders are backed up.
31 1F CHAR(1) Back up OfficeVision cal-
3 No root folders are backed up.
endars
32 20 CHAR(1) Submit as batch job Back up OfficeVision calendars. Whether to save
33 21 CHAR(1) Save changed objects OfficeVision calendar data. OfficeVision calendars are also
only saved when QUSRSYS is saved. Possible values follow:
34 22 CHAR(1) Print detailed report 0 Calendars are not saved when the backup is
35 23 CHAR(10) User exit program name
run.
1 Calendars are saved when the backup is run.
45 2D CHAR(10) User exit program library 9 Calendars are not saved when the backup is
name
run because the OfficeVision calendar function
is not available.

3-44 AS/400 System API Reference V4R4

 Retrieve Backup Options (QEZRTBKO) API

Back up OfficeVision mail. Whether to save OfficeVision 2 All user libraries are saved when the backup
mail. The backup ignores this option if FLR(*ALL) is speci- is run.
fied. 3 No user libraries are saved when the backup
is run.
0 Mail is not saved when the backup is run.
1 Mail is saved when the backup is run.
Back up user directories. Whether to save all user directo-
9 Mail is not saved when the backup is run
ries. This does not include any IBM-supplied directories that
because the OfficeVision mail function is not
contain user data. Some directories that are not saved
available.
include QOPT, QFileSvr.400, QSYS.LIB, and QDLS (QDLS
data is saved under the option to save folders). Possible
Back up security data. Whether to save the system secu-
values follow:
rity data. Possible values follow:
0 Security data is not saved when the backup is
2 All user directories are saved when the
backup is run.
run.
1 Security data is saved when the backup is
3 Do not back up any user directories.
run.
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is
Back up user libraries. Which user libraries are saved
provided.
when a backup is run. All libraries with names that do not
begin with the letter Q are backed up except for the fol-
Bytes returned. The number of bytes of data returned.
lowing:
#CGULIB Erase tape before backup. Whether to clear the tape and
start the save operation at sequence number 1. Possible
#COBLIB
values follow:
#DFULIB
0 The save operation continues at the next
#DSULIB available sequence number.
#RPGLIB
1 The tape is cleared, and the save operation
starts at sequence number 1.
#SDALIB
Last backup date. The completion date of the last Opera-
#SEULIB
tional Assistant backup in CYYMMDD format.
Although IBM provides the following Qxxx libraries, the
Last backup time. The completion time of the last Opera-
libraries typically contain user data that changes frequently.
tional Assistant backup in HHMMSS format.
Therefore, these libraries are considered user libraries and
are also backed up: Last tape set used. The tape set that was used to com-
QDSNX plete the last Operational Assistant backup.
QGPL Next backup date. The next date that an Operational
QGPL38 Assistant backup is run in CYYMMDD format.
QPFRDATA Next backup time. The time of the next scheduled backup.
QRCL This time is in the format HHMMSS and uses the 24-hour
clock.
QS36F
QUSER38 Next tape set to be used. The tape set that is used to start
the next backup.
QUSRINFSKR
QUSRSYS Number of backup devices. The number of backup
devices that are defined as available for use in an Opera-
QUSRVxRxMx
tional Assistant backup.
The user can create a different library name, of the form
QUSRVxRxMx, for each release that IBM supports. Number of tape sets to rotate. The number of tape sets
VxRxMx is the version, release, and modification level of that are defined to be used in a backup.
the library.
Offset to additional information. The offset from the start
Possible values follow: of format RBOH0100 to the last backup date field.
1 The objects in the libraries that are selected
Offset to daily options. The offset from the start of the
for backup from the library backup list are
RBOH0100 structure to the backup options.
backed up.

Chapter 3. Backup and Recovery APIs 3-45

Retrieve Backup Schedule (QEZRTBKS) API

Offset to list of backup device names. The offset from the CPF3C21 E
start of the RBOH0100 structure to the list of device names. Format name &1 is not valid.
This list is defined by the user to be used during an Opera- CPF3C24 E
tional Assistant backup. Length of the receiver variable is not valid.
CPF3C90 E
Offset to list of tape sets to rotate. The offset from the Literal value cannot be changed.
start of the RBOH0100 structure to the list of tape sets to be CPF3CF1 E
used in an Operational Assistant backup. Error code parameter not valid.
CPF9820 E Not authorized to use library &1.
Offset to monthly options. The offset from the start of the
CPF9872 E Program or service program &1 in library &2
RBOH0100 structure to the monthly backup options.
ended. Reason code &3.
Offset to weekly options. The offset from the start of the
RBOH0100 structure to the weekly backup options.
Retrieve Backup Schedule (QEZRTBKS)
Print detailed reports. Whether each save command that API
supports OUTPUT(*PRINT) generates a detailed list of the
objects that were saved in addition to a summary report.
Possible values follow: Required Parameter Group:
0 Only a summary report is generated from the
1 Receiver variable Output Char(*)
backup. A detailed report is not generated.
2 Length of receiver variable Input Binary(4)
1 A detailed list of saved objects is printed. A 3 Format name Input Char(8)
summary report is always printed. 4 Error Code I/O Char(*)

Reserved. This field is ignored. Threadsafe: No

Save changed objects only. Whether to save only
changed objects in the libraries, folders, and directories being The Retrieve Backup Schedule (QEZRTBKS) API returns in
backed up. Possible values follow: a receiver variable information about when the Operational
0 All of the objects in the requested libraries, Assistant backups are scheduled to be run.
folders, and directories are backed up.
1 Only objects that were changed since the last Authorities and Locks
backup are saved.
User Index Authority
Submit as batch job. Whether the backup is scheduled to *USE
be submitted as a batch job. Possible values follow: Job Schedule Entry Authority
*USE
0 The backup is run interactively.
User Index Lock
1 The backup is submitted as a batch job.
*SHRRD
Tape sets to rotate. The name of the one or more tape Job Schedule Lock
sets to be used for backup rotation. *SHRRD

User exit program library name. The name of the library

that contains the user exit program.
Required Parameter Group
blank No exit program is defined so no library name Receiver variable
is required. OUTPUT; CHAR(*)
*LIBL The library list is searched to find the exit The receiver variable that receives the information
program. requested. You can specify the size of the area to be
smaller than the format requested as long as you specify
User exit program name. This exit program is run before the length parameter correctly. As a result, the API
and after a backup is run to allow users to customize their returns only the data that the area can hold.
backups.
Length of receiver variable
*NONE No exit program is run.
Input; BINARY(4)
The length of the receiver variable provided. The length
Error Messages of receiver variable parameter may be specified up to
CPF1EC5 E the size of the receiver variable specified in the user
Backup option &1 is not valid. program. If the length of receiver variable parameter
CPF24B4 E Severe error while addressing parameter list. specified is larger than the allocated size of the receiver

3-46 AS/400 System API Reference V4R4

 Retrieve Backup Schedule (QEZRTBKS) API

variable specified in the user program, the results are Bytes available. The number of bytes of data available to
not predictable. The minimum length is 8 bytes. be returned. All available data is returned if enough space is
provided.
Format name
INPUT; CHAR(8) Bytes returned. The number of bytes of data returned.
The name of the format in which to return the backup
Friday backup. The type of backup that is run on Friday.
schedule. The following format name may be used:
Possible values follow:
RBKS0100 Basic schedule information. For more
blank No backup is scheduled for this day of the
information, see “RBKS0100 Format.”
week.
Error code 1 A daily backup is run on this day.
I/O; CHAR(*) 2 A weekly backup is run on this day.
3 A monthly backup is run on this day.
The structure in which to return error information. For
4 A *WEEKMONTH backup is run on this day. A
the format of the structure, see “Error Code Parameter”
weekly backup is run on this day of the week
on page 2-6.
every week except on the week that a monthly
backup is run. In that case, the monthly
RBKS0100 Format
backup is run.

Offset Friday backup time. Using the 24-hour clock, the time that
Dec Hex Type Field the backup takes place (in format HHMMSS).
0 0 BINARY(4) Bytes returned
Hours before backup to send tape message. If you
4 4 BINARY(4) Bytes available choose, you may have the system send a reminder to the
8 8 BINARY(4) Hours before backup to system operator to load the tape before a backup starts.
send tape message Specify the number of hours before the backup that you
would like this message to be sent. Possible values follow:
12 C BINARY(4) Occurrence in month to run
backup 0 No message is sent to the system operator
16 10 CHAR(1) Run backup using this before the backup.
schedule 1-24 The number of hours prior to backup to send
the message.
17 11 CHAR(1) Sunday backup
18 12 CHAR(6) Sunday backup time Monday backup. The type of backup that is run on
24 18 CHAR(1) Monday backup Monday. Possible values follow:
25 19 CHAR(6) Monday backup time blank No backup is scheduled for this day of the
week.
31 1F CHAR(1) Tuesday backup
1 A daily backup is run on this day.
32 20 CHAR(6) Tuesday backup time 2 A weekly backup is run on this day.
38 26 CHAR(1) Wednesday backup 3 A monthly backup is run on this day.
39 27 CHAR(6) Wednesday backup time
4 A *WEEKMONTH backup is run on this day.
A weekly backup is run on this day of the
45 2D CHAR(1) Thursday backup week every week except on the week that a
46 2E CHAR(6) Thursday backup time monthly backup is run. In that case, the
52 34 CHAR(1) Friday backup monthly backup is run.
53 35 CHAR(6) Friday backup time Monday backup time. Using the 24-hour clock, the time
59 3B CHAR(1) Saturday backup that the backup takes place (in format HHMMSS).
60 3C CHAR(6) Saturday backup time
Occurrence in month to run backup. The week of the
month that you want the backup to occur when the backup
type is either *MONTHLY or *WEEKMONTH. Possible
Field Descriptions values follow:
Some of the fields use a time format (HHMMSS), where: 0 No monthly backup is scheduled to run.
HH Hour 1–4 A value 1 through 4 corresponds to the week
MM Minute of the month that the monthly backup is run.
SS Second 5 The monthly backup is run on the last week of
the month.

Run backup using this schedule. Whether you want to

use the backup schedule. Possible values follow:

Chapter 3. Backup and Recovery APIs 3-47

Retrieve Device Capabilities (QTARDCAP) API

0 A schedule has been created, but it is not blank No backup is scheduled for this day of the
being used at this time. week.
1 Backups are run according to the schedule. 1 A daily backup is run on this day.
2 A weekly backup is run on this day.
Saturday backup. The type of backup that is to run on Sat- 3 A monthly backup is run on this day.
urday. Possible values follow: 4 A *WEEKMONTH backup is run on this day.
blank No backup is scheduled for this day of the A weekly backup is run on this day of the
week. week every week except on the week that a
1 A daily backup is run on this day. monthly backup is run. In that case, the
2 A weekly backup is run on this day. monthly backup is run.
3 A monthly backup is run on this day.
Tuesday backup time. Using the 24-hour clock, the time
4 A *WEEKMONTH backup is run on this day.
that the backup takes place (in format HHMMSS).
A weekly backup is run on this day of the
week every week except on the week that a
Wednesday backup. The type of backup that is run on
monthly backup is run. In that case, the
Wednesday. Possible values follow:
monthly backup is run.
blank No backup is scheduled for this day of the
Saturday backup time. Using the 24-hour clock, the time week.
that the backup takes place (in HHMMSS). 1 A daily backup is run on this day.
2 A weekly backup is run on this day.
Sunday backup. The type of backup that is to be run on 3 A monthly backup is run on this day.
Sunday. Possible values follow: 4 A *WEEKMONTH backup is run on this day. A
blank No backup is scheduled for this day of the weekly backup is run on this day of the week
week. every week except on the week that a monthly
1 A daily backup is run on this day. backup is run. In that case, the monthly
2 A weekly backup is run on this day. backup is run.
3 A monthly backup is run on this day.
Wednesday backup time. Using the 24-hour clock, the time
4 A *WEEKMONTH backup is run on this day. A
that the backup takes place (in format HHMMSS).
weekly backup is run on this day of the week
every week except on the week that a monthly
backup is run. In that case, the monthly Error Messages
backup is run.
CPF1629 E Not authorized to job schedule &1.
Sunday backup time. Using the 24-hour clock, the time CPF1632 E Job schedule entry &3 number &4 damaged.
that the backup takes place (in format HHMMSS). CPF1637 E Job schedule &1 in library &2 in use.
CPF1640 E Job schedule &1 in library &2 does not exist.
Thursday backup. The type of backup that is run on CPF1641 E Job schedule &1 in library &2 damaged.
Thursday. Possible values follow: CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
blank No backup is scheduled for this day of the
Error code parameter not valid.
week.
CPF3C21 E
1 A daily backup is run on this day.
Format name &1 is not valid.
2 A weekly backup is run on this day.
CPF3C90 E
3 A monthly backup is run on this day.
Literal value cannot be changed.
4 A *WEEKMONTH backup is run on this day. A
CPF812C E
weekly backup is run on this day of the week
Job schedule &4 in &9 damaged.
every week except on the week that a monthly
CPF9802 E Not authorized to object &2 in &3.
backup is run. In that case, the monthly
CPF9803 E Cannot allocate object &2 in library &3.
backup is run.
CPF9820 E Not authorized to use library &1.
Thursday backup time. Using the 24-hour clock, the time CPF9872 E Program or service program &1 in library &2
that the backup takes place (in format HHMMSS). ended. Reason code &3.

Tuesday backup. The type of backup that is run on

Tuesday. Possible values follow: Retrieve Device Capabilities (QTARDCAP)
API

3-48 AS/400 System API Reference V4R4

 Retrieve Device Capabilities (QTARDCAP) API

Device description or resource name

Required Parameter Group: INPUT; CHAR(10)
The name of the device description or resource for
1 Receiver variable Output Char(*) which the data is returned.
2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8) Device description or resource indicator
4 Device description or Input Char(10) INPUT; CHAR(10)
resource name
5 Device description or Input Char(10) Whether the name specified is a device description or a
resource indicator resource name. The possible values follow:
6 Resources to list Input Char(1)
7 Error code I/O Char(*) *DEVD The name specified is a device descrip-
tion.
Threadsafe: No *RSRC The name specified is a resource name.

Resources to list
The Retrieve Device Capabilities (QTARDCAP) API retrieves INPUT; CHAR(1)
information that is associated with a specified tape device Which media library device resources are listed if the
description or tape resource name. The resource that is device description indicator in the device description or
specified or associated with the specified device description resource indicator parameter is *DEVD. This parameter
must currently exist on the system. is blank if the device requested is not a media library
device description. If a media library device description
The QTARDCAP API currently supports the following device
is specified, the possible values are as follows:
types:
Ÿ Tape (TAP) devices 1 All resources are listed (*ALL).
2 Allocated resources are listed (*ALLO-
Ÿ Tape media library (TAPMLB) devices CATED).
3 Unprotected resources are listed
Authorities and Locks (*UNPROTECTED).
4 Deallocated resources are listed (*DEAL-
Device Description Authority LOCATED).
*READ 5 Both allocated and unprotected resources
are listed (*AVAILABLE).
Required Parameter Group blank The requested input device or resource is
not a media library device, not a device
Receiver variable description, or the information is not
OUTPUT; CHAR(*) requested.
The receiver variable that receives the information Error code
requested. You can specify the size of the area to be I/O; CHAR(*)
smaller than the format requested as long as you specify
the length parameter correctly. As a result, the API The structure in which to return error information. For
returns only the data that the area can hold. the format of the structure, see “Error Code Parameter”
on page 2-6.
Length of receiver variable
INPUT; BINARY(4)
TAPE0100 Format
The length of the receiver variable provided. The length
of receiver variable parameter may be specified up to The following table shows the information that is returned for
the size of the receiver variable specified in the user the TAPE0100 format. For more details about the fields in
program. If the length of receiver variable parameter the following table, see “Field Descriptions” on page 3-51.
specified is larger than the allocated size of the receiver
variable specified in the user program, the results are Offset
not predictable. The minimum length is 8 bytes.
Dec Hex Type Field
Format name 0 0 BINARY(4) Bytes returned
INPUT; CHAR(8)
4 4 BINARY(4) Bytes available
The content and format of the information being
8 8 CHAR(10) Device description or
returned. The TAPE0100 format must be used for the resource name
tape device capabilities information. See “TAPE0100
Format” to view the information returned for this format. 18 12 CHAR(10) Device description or
resource indicator

Chapter 3. Backup and Recovery APIs 3-49

Retrieve Device Capabilities (QTARDCAP) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
28 1C CHAR(10) Device resource name 103 67 CHAR(2) Bit mapping of the highest
supported density
38 26 CHAR(3) Reserved
105 69 CHAR(1) Reserved
41 29 CHAR(1) Device relationship to media
library device 106 6A CHAR(2) Bit mapping of all supported
character densities
42 2A CHAR(1) Type of media library device
108 6C BINARY(4) Offset to supported char-
43 2B CHAR(1) Intelligent tape device
acter densities
44 2C CHAR(4) Device type
112 70 BINARY(4) Number of supported char-
48 30 CHAR(4) Device model acter densities
52 34 BINARY(4) Maximum block size 116 74 BINARY(4) Offset to resource list
56 38 CHAR(1) Logical-block-ID capability 120 78 BINARY(4) Number of resources in
resource list
57 39 CHAR(1) Assign capability
124 7C BINARY(4) Offset to resource status list
58 3A CHAR(1) Overwrite capability
128 80 BINARY(4) Number of resource status
59 3B CHAR(1) Read-backward capability
list entries
60 3C CHAR(1) Cartridge-checking capa-
132 84 CHAR(1) Reserved
bility
61 3D CHAR(1) Device class
| 133 85 CHAR(1) QTACTLDV API supported
134 86 CHAR(1) Media library device with
62 3E CHAR(1) Hardware data compression
door
capability
135 87 CHAR(5) Reserved
63 3F CHAR(1) Label compaction supported
140 8C BINARY(4) Offset to density capability
64 40 BINARY(4) Offset to supported write
entries
densities
144 90 BINARY(4) Number of density capability
68 44 BINARY(4) Number of supported write
entries
densities
148 94 BINARY(4) Length of density capability
72 48 BINARY(4) Offset to supported read
entries
densities
152 98 BINARY(4) Offset to system feature
76 4C BINARY(4) Number of supported read
codes
densities
156 9C BINARY(4) Length of system feature
80 50 BINARY(4) Offset to supported
codes
improved-data-recording-
capability (IDRC) densities 160 A0 BINARY(4) Acceptable read error
thresholds
84 54 BINARY(4) Number of supported
improved-data-recording- 164 A4 BINARY(4) Acceptable write error
capability (IDRC) densities thresholds
88 58 BINARY(4) Optimum block size 168 A8 BINARY(4) Instantaneous performance
92 5C CHAR(1) Space to end of data | 172 AC BINARY(4) Offset to slot and station
93 5D CHAR(1) Space backward allowed
| information
176 B0 BINARY4) Offset to device text
94 5E CHAR(1) Media library device with
bar-code scanner 180 B4 BINARY4) Length of device text
95 5F CHAR(1) Improved-data-recording- 184 B8 ARRAY(*) of Supported improved-data-
capability (IDRC) supported CHAR(10) recording-capability (IDRC)
densities
96 60 CHAR(1) Automatic cartridge mech-
anism supported ARRAY(*) of Supported write densities
CHAR(10)
97 61 CHAR(2) Bit mapping of all supported
improved-data-recording- ARRAY(*) of Supported read densities
capability (IDRC) densities CHAR(10)
99 63 CHAR(2) Bit mapping of all supported ARRAY(*) of Supported character densi-
write densities CHAR(10) ties
101 65 CHAR(2) Bit mapping of all supported ARRAY(*) of Resource list
read densities CHAR(10)

3-50 AS/400 System API Reference V4R4

 Retrieve Device Capabilities (QTARDCAP) API

The following are the supported OS/400 densities and their

Offset
corresponding bit-map representations for each device class.
Dec Hex Type Field Note that intelligent tape devices do not follow these OS/400
ARRAY(*) of Resource status list bit-map representations but are defined in the device specifi-
CHAR(15) cations. Values for the device class of 1/4-inch cartridge
ARRAY(*) of Density capability entries technology follow:
CHAR(*) Hexadecimal
CHAR(*) System feature codes Bit Map Density or Format
CHAR(*) Device text '4000'x *QIC24 (8000 bpi)
'2000'x *QIC120 (10000 bpi)
| CHAR(*) Slot and station information
'0800'x *QIC525 (16000 bpi)
'0400'x *QIC1000
'0200'x *QIC2GB
Field Descriptions '0100'x *QIC3040
'0080'x *QIC5010
Acceptable read error thresholds The average minimum
number of kilobytes (1KB = 1000 bytes) read between recov- Values for the device class of 1/2-inch cartridge technology
ered read errors for the media to be considered acceptable. follow:
This information is to determine the reliability of a volume Hexadecimal
based on the number of errors that the device is reporting Bit Map Density or Format
against that tape volume. This field is zero for devices that '8000'x *FMT3480 (38000 bpi)
do not report this information. '4000'x *FMT3490E
'2000'x *FMT3590
Acceptable write error thresholds The average minimum
'0800'x *FMT3570
number of kilobytes (1KB = 1000 bytes) written between
'0400'x *FMT3570E
recovered write errors for the media to be considered accept-
able. This information is to determine the reliability of a Values for the device class of 1/2-inch reel technology follow:
volume based on the number of errors that the device is Hexadecimal
reporting against that tape volume. This field is zero for Bit Map Density or Format
devices that do not report this information. '8000'x 1600 bpi
'4000'x 3200 bpi
Automatic cartridge mechanism supported. Whether the
'2000'x 6250 bpi
device has an automatic cartridge mechanism (loader or
facility) known as an ACL (that is, 3490 type stand alone Values for the device class of 8-mm cartridge technology
devices typically have an ACL) or an ACF (that is, 3590 B11 follow:
devices have an ACF). Possible values follow: Hexadecimal
0 The device does not have an automatic car- Bit Map Density or Format
tridge mechanism. '8000'x *FMT2GB
1 The device does have an automatic cartridge '4000'x *FMT5GB
mechanism. '2000'x *FMT7GB
blank This field is not valid for a media library
device. Bit mapping of highest supported output density. A bit-
mapped encoding of the highest supported output density on
Assign capability. Whether the specified device or the device. This field is not available for a media library
resource has the capability to assign (reserve) a device to device. The definition of example bit maps can be found in
the system. This concept ensures that no other system can the bit mapping of all supported character densities field.
use the device because the system could not be successfully
assigned (reserved) from the device. This feature fully Bit mapping of all supported improved-data-recording-
enables devices that can be shared. Possible values follow: capability (IDRC) densities. A bit-mapped encoding of den-
sities that correspond to the supported IDRC densities. This
0 The system cannot assign the device. field is not available for a media library device. The definition
1 The system can assign the device. of example bit maps can be found in the bit mapping of all
blank This is not an available value for a media supported character densities field.
library device.
Bit mapping of all supported read densities. A bit-
Bit mapping of all supported character densities. A bit- mapped encoding of densities that correspond to the sup-
mapped encoding of densities that correspond to the sup- ported read densities. This field is not available for a media
ported character densities. This field is not available for a library device. The definition of example bit maps can be
media library device. Bit mappings are defined on the device found in the bit mapping of all supported character densities
level and may not match the following examples. field.

Chapter 3. Backup and Recovery APIs 3-51

Retrieve Device Capabilities (QTARDCAP) API

Bit mapping of all supported write densities. A bit- *RSRC The name specified is a device resource
mapped encoding of densities that correspond to the sup- name.
ported write densities. This field is not available for a media
library device. The definition of example bit maps can be Device description or resource name. The device descrip-
found in the bit mapping of all supported character densities tion or resource name of the device.
field.
Device relationship to media library device. The relation-
Bytes available. The number of bytes of data available to ship of the device or resource to the media library device.
be returned. All available data is returned if enough space is Possible values follow:
provided. 0 The device is not a media library resource.
1 The device is a tape resource in a media
Bytes returned. The number of bytes of data returned.
library resource.
Cartridge-checking capability. Whether the device com-
2 The device is a media library resource.
municates valid cartridge densities or formats. This capa-
Device model. The device model number.
bility allows OS/400 to verify cartridge density or formats.
Devices that do not support this capability cannot send intelli- Device resource name. The resource name if the device
gent messages about the cartridge. When the device is information is for a device description.
unable to write to the cartridge, a generic error message
usually results. It could be as simple as a cartridge not sup- Device text. The specific text that is reported by the device.
ported by the device. Possible values follow:
Device type. The device type number.
0 No device or resource that is requested has
special cartridge-density checking capabilities. Hardware data compression capability. Whether hard-
1 The device requested has special cartridge- ware data compression (HDC) is supported. This field corre-
density checking capabilities. sponds to the data compression (DTACPR) parameter on
blank This is not an available value for a media save commands. Possible values follow:
library device.
0 No device or resource that is requested has
Device class. The class of the device. Possible values hardware data compression capabilities.
follow: 1 The device that is requested has hardware
data compression capabilities.
1 1/2-inch reel technology
blank This is not an available value for a media
2 1/2-inch cartridge technology
library device.
3 1/4-inch cartridge technology
4 8-mm technology Improved-data-recording-capability (IDRC) supported.
blank None of the above technologies or media Whether the device supports IDRC (or compaction) at any
library device density. If IDRC is supported, see the supported IDRC den-
sities field. Possible values follow:
Density capability entries. The list of density capabilities
based on density, format, or both. Each entry consists of the 0 No device or resource that is requested has
following format and has a length that is specified in the IDRC capabilities.
length of density capability entry field. 1 The device that is requested has IDRC capa-
bilities.
CHAR(10) Density or format
blank This is not an available value for a media
CHAR(2) Bit map representation of density
library device.
BINARY(4) Instantaneous performance in megabytes per
second for this density or format. One MB per Instantaneous performance. The highest instantaneous
second is returned for each field if the perfor- performance that is reported by the device. This value can
mance number is not reported by the device. be obtained from the density capability entries list on a
BINARY(4) Maximum block size for this density or format. density, format, or both. This value is the highest perfor-
BINARY(4) Optimum block size for this density or format. mance number that is specified in the density capability
This format is repeated once for each density or format that entries list. The value is in megabytes per second. If the
is supported by the device. The number of entries in the device does not report this value, a value of 1 MB per
array is specified in the number of density capability entries second will be used. This is not an available value for a
field. This field is not available for a media library device. media library device and is set to zero for media library
devices.
Device description or resource indicator. Whether the
information is retrieved for a device description or a device Intelligent tape device. Whether this resource or device is
resource name. This field is left-justified. Possible values an intelligent tape device. Possible values follow:
follow: 0 The device is not an intelligent tape device.
*DEVD The name specified is a device description. 1 The device is an intelligent tape device.

3-52 AS/400 System API Reference V4R4

 Retrieve Device Capabilities (QTARDCAP) API

Label compaction supported. Whether the device volumes Media library device with door. Whether the media library
are written with compacted labels. Possible values follow: device has a door that can be opened. Possible values
follow:
0 The device does not generate labels with
compaction. 0 The device does not have a door.
1 The device generates labels with compaction 1 The device has a door.
if compaction is requested. blank This field is only valid for a media library
device.
Length of density capability entry. The length, in bytes, of
each entry in the density capability entries list. This field Number of density capability entries. The number of
should be used in stepping through the array of density density capability entries in the density capability entries list.
capability entries. Additional fields for each density or format This field is not available for a media library device and is set
in the density capability entries list may be added at any to zero when the input device is a media library device.
time.
Number of resources in resource list. The number of
Length of device text. The length, in bytes, of text that is resources that are listed in the resource list. This number is
reported by the device. If the device does not report specific set to zero when the input device is not a media library
text about the device, zero is returned. device description (*DEVD).

Length of system feature codes. The length, in bytes, of Number of resource status list entries. The number of
the system feature codes entry. This field should be used in resource status entries for the resource status list. This
determining the system feature codes (type and model) of number is set to zero when the input device is not a media
the device. If the device does not report this information, zero library device description (*DEVD).
is returned.
Number of supported improved-data-recording-capability
Logical-block-ID capability. Whether the device allows fast (IDRC) densities. The number of supported IDRC (or com-
access capabilities. This allows logical-block-identifier paction) densities that are specified in the supported IDRC
support through a tape management system that is regis- densities field. This field is not available for a media library
tered with the registration facility and used in combination device and is set to zero when the input device is a media
with the Media and Storage Extensions feature of OS/400. library device.
Possible values follow:
Number of supported character densities. The number of
0 No device or resource that is requested has
supported character densities that are specified in the sup-
fast access by logical-block-identifier capabili-
ported character densities field. This field is not available for
ties.
a media library device and is set to zero when the input
1 The device that is requested has fast access
device is a media library device.
by logical-block-identifier capabilities.
blank This is not an available value for a media Number of supported read densities. The number of sup-
library device. ported read densities that are specified in the supported read
densities field. This field is not available for a media library
Maximum block size. The highest maximum block size that
device and is set to zero when the input device is a media
is supported by the device. If you use the maximum block
library device.
size, tapes may be created that are not compatible with other
device types. A tape that is created with a maximum block Number of supported write densities. The number of sup-
size can only be duplicated with the Duplicate Tape ported write densities that are specified in the supported
(DUPTAP) command to devices that support the same block write densities field. This field is not available for a media
size. This field is not available for a media library device and library device and is set to zero when the input device is a
is set to zero for media library devices. media library device.

The maximum block size that a device supports may vary Offset to density capability entries. The offset, in bytes, to
with density. Use the Density capability entries to determine the density capability entries list.
the maximum block size for a specific density.
Offset to device text. The offset, in bytes, to the text that is
Media library device with bar-code scanner. Whether the reported by the device.
device has a bar-code scanner, which is for a media library
device. Possible values follow: Offset to resource list. The offset, in bytes, to the resource
list.
0 The device has no bar-code scanner.
1 The device has a bar-code scanner. Offset to resource status list. The offset, in bytes, to the
blank This field is only valid for a media library resource status list field.
device.
| Offset to slot and station information. The offset, in
| bytes, to the slot and station information field.

Chapter 3. Backup and Recovery APIs 3-53

 Retrieve Device Capabilities (QTARDCAP) API

Offset to supported character densities. The offset, in blank This is not an available value for a media
bytes, to the supported character densities field. library device.

Offset to supported improved-data-recording-capabilities Reserved. An ignored field.

(IDRC) densities. The offset, in bytes, to the supported
improved-data-recording-capabilities (IDRC) densities field. Resource list. The list of tape resources in the media
library device.
Offset to supported read densities. The offset, in bytes, to
Note: The data is an array of 10-byte entries. Each entry
the supported read densities field.
consists of a 10-byte density that is left-justified and padded
with blanks. The number of entries in the array is specified
Offset to supported write densities. The offset, in bytes,
in the number of resources in resource list field. The
to the supported write densities field.
resource list is not valid when the input device is not a media
Offset to system feature codes. The offset, in bytes, to the library device description (*DEVD).
system feature codes (types and models) of the device.
Resource status list. The list of statuses that correspond to
Optimum block size. The highest optimum block size sup- resources in the resource list.
ported by the device. Note: The data is an array of 15-byte entries. Each entry
| consists of a 15-byte status that is left-justified and padded
When USEOPTBLK(*YES) is specified as a parameter for a
with blanks. The number of entries in the array is specified
save operation, performance may be improved. The
in the number of resource status list entries field. The
USEOPTBLK(*YES) parameter may cause tapes to be
resource status list is not valid when the input device is not a
created that are not compatible with other device types. That
media library device description (*DEVD). Possible values
is, a tape that is created with an optimum block size can only
follow:
be duplicated with the Duplicate Tape (DUPTAP) command
to devices that support the same block size. This field is not *ALLOCATED
available for a media library device and is set to zero for The tape resource is allocated to the media
media library devices. library device. The system has assigned the
device.
The optimum block size that a device supports may vary with *UNPROTECTED
density. Use the Density capability entries to determine the The tape resource is considered unprotected
optimum block size for a specific density. to the media library device. It is available to
the media library device, but the system has
Overwrite capability. Whether the device or resource that not assigned the device. The system
is specified has overwriting capabilities. This capability refers attempts to assign the resource when the
to being able to write a data file over an existing data file resource is used.
sequence on a tape volume. Some technologies only allow *DEALLOCATED
appending data to the end of tape or writing files to the The tape resource is deallocated to the media
beginning of tape. Possible values follow: library device. The resource is not available
0 No device or resource that is requested has to the media library device, and the system
overwrite capabilities. has not assigned the device.
1 The device that is requested has overwrite
| Slot and station information. This information is available
capabilities.
| only for a media library device. The information is returned in
blank This is not an available value for a media
| the following format:
library device.
| BINARY(4) Total number of storage slots
| QTACTLDV API supported. Whether the QTACTLDV API | BINARY(4) Total number of import/export stations
| is supported for the device or resource that is specified.
| Possible values follow: | The above numbers are set to zero when the input device is
| not a media library device description (*DEVD) or when the
| 0 QTACTLDV API is not supported.
| information is not available.
| 1 QTACTLDV API is supported.
| For a media library device that requires a communication
Read-backward capability. Whether the device or resource
| interface, the slot and station information is available only
that is specified has read-backward capabilities. Possible
| after the media library device description has been varied on.
values follow:
0 No device or resource that is requested has Space backward allowed. Whether the device supports
read-backward capabilities. spacing backward or requires rewinding the device and
1 The device that is requested has read- respacing to the correct file. Possible values follow:
backward capabilities.
0 No device or resource that is requested has
space-backward capabilities.

3-54 AS/400 System API Reference V4R4

 Retrieve Device Information (QTARDINF) API

1 The device that is requested has space- Supported read densities. The list of valid read densities
backward capabilities. that are supported by this device.
blank This is not an available value for a media
Note: The data is an array of 10-byte entries. Each entry
library device.
consists of a 10-byte density that is left-justified and padded
with blanks. The number of entries in the array is specified
Space to end of data. The function that allows quick
in the number of supported read densities field. This field is
access to the end of the logical tape when a command spec-
not available for a media library device.
ifies SEQNBR(*END), such as the Save Library (SAVLIB)
command. This function allows a significant improvement on
Supported write densities. The list of valid write densities
performance when the tape is positioned at the beginning of
that are supported by this device.
the tape and needs to be positioned a long way into the
tape. If the device does not support this function, OS/400 Note: The data is an array of 10-byte entries. Each entry
spaces by the file marks until the end of data is reached. consists of a 10-byte density that is left-justified and padded
Possible values follow: with blanks. The number of entries in the array is specified
in the number of supported write densities field. This field is
0 No device or resource that is requested has
not available for a media library device.
space to end of data capabilities.
1 The device that is requested has space to end Type of media library device. The media library tech-
of data capabilities. nology. Possible values follow:
blank This is not an available value for a media
library device.
0 The device is not a media library device.
1 Library commands are communicated to the
Supported improved-data-recording-capability (IDRC) library robotic device.
densities. The list of densities that support IDRC (or com- 2 Library commands are communicated to a
paction) on this device. communications line.
3 Library commands are communicated to the
Note: The data is an array of 10-byte entries. Each entry
library robotic device and the device.
consists of a 10-byte density that is left-justified and padded
with blanks. The number of entries in the array is specified in
the number of supported improved-data-recording-capability Error Messages
(IDRC) densities field. This field is not available for a media CPF3C90 E
library device. Literal value cannot be changed.
CPF6707 E Format name &1 not valid.
System feature codes. The system feature codes (type and
CPF6708 E Command ended due to error.
model) that the device reports. The first 4 bytes of the
CPF6709 E Parameter &3 not correct.
system feature codes field displays which feature codes are
CPF6710 E Specified length not correct.
available or reported by the device. The 32 bits of the 4
CPF6721 E Device &1 not a tape device.
bytes are defined as follows:
CPF672F E Resource &1 not found.
Bit 0 AS/400 default feature code provided CPF673F E Device &1 does not support &2.
Bit 1-31 Not used CPF9814 E Device &1 not found.
CPF9825 E Not authorized to device &1.
Each bit that is identified in the 32 bits as defined above is CPF9872 E Program or service program &1 in library &2
represented with 4 bytes of device type and model in ended. Reason code &3.
hexadecimal representation. These 4 bytes are repeated for
each bit that is turned on in the first 4 bytes of the system
feature codes field. The length of this field determines how
much information is returned from the device and is con-
Retrieve Device Information (QTARDINF)
tained in the length of system feature codes. The length of API
this field includes the first 4 bytes of bit definitions. That is, if
only bit 0 is on, then the length of the field is 8 bytes, which
includes the 4 bytes of bit definition and the 4 bytes of the Required Parameter Group:
one system feature code.
1 Receiver variable Output Char(*)
Supported character densities. The list of densities that 2 Length of receiver variable Input Binary(4)
3 Device Input Char(10)
are supported on this device.
4 Format name Input Char(8)
Note: The data is an array of 10-byte entries. Each entry 5 Error code I/O Char(*)
consists of a 10-byte density that is left-justified and padded
with blanks. The number of entries in the array is specified Threadsafe: No
in the number of supported character densities field. This
field is not available for a media library device.

Chapter 3. Backup and Recovery APIs 3-55

Retrieve Job Media Library Attributes (QTARJMA) API

The Retrieve Device Information (QTARDINF) API retrieves TADS0100 Format

information that is associated with a specified device descrip-
tion. The following table shows the information that is returned for
the TADS0100 format. For more details about the fields in
The QTARDINF API currently supports the following device the following table, see “Field Descriptions.”
types:
Ÿ Tape (TAP) devices Offset
Ÿ Tape media library (TAPMLB) devices Dec Hex Type Field

Specifically, it retrieves information about the current status 0 0 BINARY(4) Bytes returned
and mode of the specified device. The device must be 4 4 BINARY(4) Bytes available
varied on at run time of the API.
8 8 BINARY(4) Number of active jobs

Authorities and Locks

Field Descriptions
Device Description Authority
*READ Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is
Required Parameter Group provided.

Receiver variable Bytes returned. The number of bytes of data returned.

OUTPUT; CHAR(*)
The receiver variable that receives the information Number of active jobs. The number of active jobs for the
requested. You can specify the size of the area to be device. For stand-alone devices the value returned will be
smaller than the format requested as long as you specify zero or one depending on whether it is in use at the current
the length parameter correctly. As a result, the API time. Note that since stand-alone tape devices require an
returns only the data that the area can hold. exclusive lock through system functions, the device will only
allow one user at a time. For media library devices, multiple
Length of receiver variable users can access the tape media library at the same time
INPUT; BINARY(4) through shared locks; therefore, any number of jobs may be
The length of the receiver variable provided. The length active at the same time. This field is designed to allow users
of receiver variable parameter may be specified up to to better utilize one resource tape media library such as the
the size of the receiver variable specified in the user 3570 tape media library device.
program. If the length of receiver variable parameter
specified is larger than the allocated size of the receiver
variable specified in the user program, the results are Error Messages
not predictable. The minimum length is 8 bytes. CPF3C90 E
Literal value cannot be changed.
Device
CPF6707 E Format name &1 not valid.
INPUT; CHAR(10)
CPF6708 E Command ended due to error.
The name of the device description for which the data is
CPF6709 E Parameter &3 not correct.
to be returned.
CPF6710 E Specified length not correct.
Format name CPF6721 E Device &1 not a tape device.
INPUT; CHAR(8) CPF672F E Resource &1 not found.
The content and format of the information being CPF673A E Device &3 not varied on.
returned. The TADS0100 format must be used for the CPF673F E Device &1 does not support &2.
retrieve device information. See “TADS0100 Format” to CPF9814 E Device &1 not found.
view the information returned for this format. CPF9825 E Not authorized to device &1.
CPF9872 E Program or service program &1 in library &2
Error code ended. Reason code &3.
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Retrieve Job Media Library Attributes
on page 2-6. (QTARJMA) API

3-56 AS/400 System API Reference V4R4

 Retrieve Job Media Library Attributes (QTARJMA) API

* The job that this program

Required Parameter Group: is running in. The rest of
the qualified job name
1 Receiver variable Output Char(*) parameter must be blank.
2 Length of receiver variable Input Binary(4) *INT The internal job identifier
3 Format name Input Char(8) locates the job. The user
4 Qualified job name Input Char(26) name and job number
5 Internal job identifier Input Char(16)
must be blank.
6 Error code I/O Char(*)
User name CHAR(10). A specific user profile name,
Threadsafe: Yes or blanks when the job name is a special
value or *INT.
Job number CHAR(6). A specific job number, or
The Retrieve Job Media Library Attributes (QTARJMA) API blanks when the job name specified is a
retrieves the specified job's current settings for the media special value or *INT.
library attributes. More information about using this API is in
the Automated Tape Library Planning and Management Internal job identifier
book. INPUT; CHAR(16)
The internal identifier for the job. The List Job
(QUSLJOB) API creates this identifier. If you do not
Authorities and Locks specify *INT for the job name parameter, this parameter
Job Authority *JOBCTL, if the job for which information is must contain blanks. With this parameter, the system
retrieved has a different user profile from that can locate the job more quickly than with a job name.
of the job that calls the QTARJMA API.
Error code
I/O; CHAR(*)
Required Parameter Group The structure in which to return error information. For
Receiver variable the format of the structure, see “Error Code Parameter”
OUTPUT; CHAR(*) on page 2-6.
The variable that is to receive the information requested.
You can specify the size of an area smaller than the RJMA0100 Format
format requested as long as you specify the receiver
length parameter correctly. As a result, the API returns The following table lists the fields for the receiver variable in
only the data the area can hold. the RJMA0100 format. For more information about each
field, see “Field Descriptions” on page 3-58.
Length of receiver variable
INPUT; BINARY(4) Offset
The length of the receiver variable. The length must be Dec Hex Type Field
at least 8 bytes. If the variable is not long enough to
0 0 BINARY(4) Bytes returned
hold the information, the data is truncated. If the length
is larger than the size of the receiver variable, the results 4 4 BINARY(4) Bytes available
are not predictable. 8 8 BINARY(4) Offset to list of device
entries
Format name
INPUT; CHAR(8) 12 C BINARY(4) Number of device entries

The format name RJMA0100 is the only valid format 16 10 BINARY(4) Length of a device entry
name used by this API. For more information, see 20 14 CHAR(12) Reserved
“RJMA0100 Format.” Offsets vary. CHAR(10) Media library device
These fields
Qualified job name CHAR(6) Reserved
repeat in the
INPUT; CHAR(26) order listed, BINARY(4) Resource allocation pri-
The name of the job for which information is to be for each ority
returned. The qualified job name has three parts: media library
BINARY(4) Wait time for initial mount
device that
Job name CHAR(10). A specific job name or the has attributes BINARY(4) Wait time for end of
following special value: defined. volume mount
CHAR(4) Reserved

Chapter 3. Backup and Recovery APIs 3-57

Retrieve Media Definition (QSRRTVMD, QsrRetrieveMediaDefinition) API

Field Descriptions Wait time for initial mount. The maximum amount of time,
in minutes, a request will wait for the allocation of a tape
Bytes available. The number of bytes of data available to resource to mount the first volume.
be returned. All available data is returned if enough space is
provided. Exceptions:
Ÿ Value of -2 implies *DEV. The initial mount wait time
Bytes returned. The number of bytes of data returned. specified in the device description will be used.
Length of a device entry. The length, in bytes, of a device Ÿ Value of -8 implies *NOMAX. The specified job will wait
entry. A value of zero is returned if the list is empty. until a resource becomes available.
Ÿ Value of -31 implies *JOB. The specified job's default
Media library device. The name of the media library device
wait time will be used to calculate the wait time. The
that the attributes apply to. The special value supported is:
time is calculated by rounding the default wait time, in
*DEFAULT The attributes apply to all media libraries that seconds, to the next highest minute.
do not have attributes defined.
Ÿ Value of -32 implies *IMMED. The specified job will not
Number of device entries. The number of entries in the wait for a resource to become available.
device list returned for this format. A value of zero is
returned if the list is empty. Error Messages
Offset to the list of device entries. The offset, in bytes, to CPF1343 E Job &3/&2/&1 not valid job type for function.
the list of device entries returned with this format. A value of CPF136A E Job &3/&2/&1 not active.
zero is returned if the list is empty. CPF24B4 E Severe error while addressing parameter list.
CPF3C19 E
Reserved. All reserved fields will contain hexadecimal Error occurred with receiver variable specified.
zeros. CPF3C21 E
Format name &1 is not valid.
Resource allocation priority. The priority that the specified CPF3C24 E
job will be given when the job requests a tape resource Length of the receiver variable is not valid.
within a media library device. CPF3C51 E
Internal job identifier not valid.
Exceptions:
CPF3C52 E
Ÿ Value of -2 implies *DEV. The priority specified in the Internal job identifier no longer valid.
device description will be used when the job requests a CPF3C53 E
tape resource. Job &3/&2/&1 not found.
Ÿ Value of -31 implies *JOB. The specified job's run-time CPF3C54 E
priority will be used for the resource allocation priority Job &3/&2/&1 currently not available.
when the job requests a tape resource. CPF3C55 E
Job &3/&2/&1 does not exist.
Wait time for end of volume mount. The maximum CPF3C58 E
amount of time, in minutes, a request will wait for the allo- Job name specified is not valid.
cation of a tape resource to mount the next volume after the CPF3C59 E
end of volume is reached. Internal identifier is not blanks and job name is
not *INT.
Exceptions: CPF3C90 E
Ÿ Value of -2 implies *DEV. The end of volume mount Literal value cannot be changed.
wait time specified in the device description will be used. CPF3CF1 E
Error code parameter not valid.
Ÿ Value of -8 implies *NOMAX. The specified job will wait CPF6708 E Command ended due to error.
until a resource becomes available. CPF67B6 E &3/&2/&1 not authorized to do requested opera-
Ÿ Value of -31 implies *JOB. The specified job's default tion.
wait time will be used to calculate the wait time. The CPF9872 E Program or service program &1 in library &2
time is calculated by rounding the default wait time, in ended. Reason code &3.
seconds, to the next highest minute.
Ÿ Value of -32 implies *IMMED. The specified job will not
wait for a resource to become available. | Retrieve Media Definition (QSRRTVMD,
| QsrRetrieveMediaDefinition) API

3-58 AS/400 System API Reference V4R4

 Retrieve Media Definition (QSRRTVMD, QsrRetrieveMediaDefinition) API

| Length of receiver variable

| Required Parameter Group: | INPUT; BINARY(4)
| The length of the receiver variable provided. The length
| 1 Qualified media defi- Input Char(20) | of receiver variable parameter may be specified up to
| nition name | the size of the receiver variable specified in the user
| 2 Receiver variable Output Char(*) | program. If the length of receiver variable parameter
| 3 Length of receiver vari- Input Binary(4) | specified is larger than the allocated size of the receiver
| able
| variable specified in the user program, the results are
| 4 Format name Input Char(8)
| not predictable. The minimum length is 8 bytes.
| 5 Error code I/O Char(*)
| Format name
| Service Program: QSRLIB01 | INPUT; CHAR(8)
| The name of the format for the receiver variable. The
| Threadsafe: No
| valid value is:

| TAPE0100 Tape devices and media

| The Retrieve Media Definition (OPM, QSRRTVMD; ILE,
| QsrRetrieveMediaDefinition) API retrieves a media definition | Error code
| specified by the user. A media definition defines the | I/O; CHAR(*)
| devices and media to be used in parallel by a save or restore
| The structure in which to return error information. For
| operation. For more information about using a media defi-
| the format of the structure, see “Error Code Parameter”
| nition, see the Backup and Recovery book.
| on page 2-6.

| Authorities and Locks | Format of Receiver Variable

| Media Definition Authority
| *USE | The following defines the format for the receiver variable.
| Library Authority | For detailed descriptions of the fields, see “Field Descriptions
| *EXECUTE | for Receiver Variable.”
| Media Definition Lock
| *SHRNUP | Offset
| Dec Hex Type Field
| Required Parameter Group | 0 0 BINARY(4) Bytes returned

| Qualified media definition name | 4 4 BINARY(4) Bytes available

| INPUT; CHAR(20) | 8 8 BINARY(4) Maximum parallel device
| The media definition to be retrieved. The first 10 char- | resources
| acters contain the media definition name. The second | 12 C BINARY(4) Minimum parallel device
| 10 characters contain the name of the library in which | resources
| the media definition is located.
| 16 10 BINARY(4) Offset to first device defi-
| You can use the following special values for the library | nition
| name. It should be noted, however, that the library | 20 14 BINARY(4) Number of device definitions
| name that is actually used is not passed back to the
| CHAR(*) Device definitions
| user. Care should be taken when using these special
| values to avoid unexpected results.

| *CURLIB The job’s current library is used to locate | Field Descriptions for Receiver Variable
| the media definition. If no library is speci-
| fied as the current library for the job, the | Bytes available. The number of bytes available to be
| QGPL library is used. | returned. All available data is returned if enough space is
| *LIBL The library list is used to locate the media | provided.
| definition.
| Bytes returned. The number of bytes of data returned. If
| Receiver variable | this is less than the bytes available, the information returned
| OUTPUT; CHAR(*) | is not complete.
| The variable that is to hold all the information defining
| the use of multiple tape files for a save or restore opera- | Device definitions. A description of the devices to be used.
| tion. See “Format of Receiver Variable” for the format of | See “Device Definition Format” on page 3-60 for the format
| the information. | of a device definition.

| Maximum parallel device resources. The maximum

| number of device resources to use in parallel. The possible

Chapter 3. Backup and Recovery APIs 3-59

 Retrieve Media Definition (QSRRTVMD, QsrRetrieveMediaDefinition) API

| values are 0 through 32. If 0 is specified, the value assumed

| Offset
| is the total number of media file definitions specified in all of
| the device definitions. | Dec Hex Type Field
| 0 0 BINARY(4) Offset to next media file
| Minimum parallel device resources. The minimum number | definition
| of device resources to use in parallel. A save or restore
| 4 4 BINARY(4) Sequence number
| operation will end if fewer resources are available. A restore
| operation will also end if any of the devices specified have | 8 8 BINARY(4) Offset to volume identifier
| no resources available. The possible values are 0 through | array
| 32. If 0 is specified, the value assumed is the number of | 12 C BINARY(4) Number of volume identi-
| device definitions specified. | fiers
| 16 10 BINARY(4) Length of volume identifier
| Number of device definitions. The number of device defi-
| nitions for the media definition. The possible values are 1 | 20 14 BINARY(4) Starting volume array
| element
| through 32.
| CHAR(*) Volume identifier array
| Offset to first device definition. The offset from the begin-
| ning of the receiver variable to the first device definition for
| the media definition. | Field Descriptions for Media File Definition
| Length of volume identifier. The number of bytes in each
| Device Definition Format | volume identifier.

| Offset | Number of volume identifiers. The number of volume

| Dec Hex Type Field
| identifiers used for the tape file. The possible values are 0
| through 75. If 0 is specified, the volume currently placed in
| 0 0 BINARY(4) Offset to next device defi- | the device is used. If 0 is specified for a tape media library
| nition
| device, volume identifiers must be supplied by using the
| 4 4 CHAR(10) Device name | Tape Management exit program during the save or restore
| 14 E CHAR(2) Reserved | operation.
| 16 10 BINARY(4) Offset to first media file defi- | Offset to next media file definition. The offset from the
| nition
| beginning of the receiver variable to the next media file defi-
| 20 14 BINARY(4) Number of media file defi- | nition for the device.
| nitions
| CHAR(*) Media file definitions | Offset to volume identifier array. The offset from the
| beginning of the receiver variable to the first volume identifier
| for the media file.
| Field Descriptions for Device Definition | Sequence number. The tape file sequence number for a
| Device name. The name of a tape device description or | tape media file.
| tape media library device description.
| The possible values are:
| Media file definitions. A description of the media files to be | 0 A save operation begins after the last
| used on this device. See “Media File Definition Format” for | sequence number on the starting volume. A
| the format of a media file definition. | restore operation searches the starting volume
| for a media file containing any of the objects
| Number of media file definitions. The number of media | to restore.
| file definitions for the device. | 1-16777215 The sequence number of the tape file.
| Offset to first media file definition. The offset from the | Starting volume array element. The element in the volume
| beginning of the receiver variable to the first media file defi- | identifier array containing the volume on which the save or
| nition for the device. | restore operation should begin. The possible values are 0
| through the number of volume identifiers.
| Offset to next device definition. The offset from the begin-
| ning of the receiver variable to the next device definition for | Volume identifier array. An array of volume identifiers. The
| the media definition. | save or restore operation will use the volumes in the order
| specified, beginning with the starting volume array element.
| Reserved. An ignored field.
| If additional volumes are needed after the last array element
| is used, the save or restore operation will call the Tape Man-
| Media File Definition Format | agement exit program or prompt the user to provide each

3-60 AS/400 System API Reference V4R4

 Save Object (QsrSave) API

| additional volume. The possible value for a volume identifier Locking See the Backup and Recovery book for
| is: information on object locking for the Save
Object (SAV) command.
| Volume identifier
| The identifier of a volume.
Authority In the Security – Reference book, see the
appendix about authorities required for the
Save Object (SAV) command.
| Error Messages
| CPF24B4 E Severe error while addressing parameter list. Required Parameter Group
| CPF3C19 E
| Error occurred with receiver variable specified. Qualified user space name
| CPF3C21 E INPUT; CHAR(20)
| Format name &1 is not valid. The user space that is to hold all the information for the
| CPF3C24 E save operation. The first 10 characters contain the user
| Length of the receiver variable is not valid. space name. The second 10 characters contain the
| CPF3C3C E name of the library where the user space is located.
| Value for parameter &1 not valid. See “User Space Format” for the format of the informa-
| CPF3C90 E tion in the user space.
| Literal value cannot be changed. You can use the following special values for the library
| CPF3CF1 E name. However, it should be noted that the library
| Error code parameter not valid. name that is actually used is not passed back to the
| CPF9800 E All CPF98xx messages could be signaled. xx is user. Care should be taken when you use these special
| from 01 to FF. values to avoid unexpected results.
| CPF9999 E Function check. &1 unmonitored by &2 at state-
| ment &5, instruction &3. *CURLIB The job’s current library is used to locate
the user space. If no library is specified
as the current library for the job, the
QGPL library is used.
Save Object (QsrSave) API
*LIBL The library list is used to locate the user
space.
Required Parameter Group: Error code
I/O; CHAR(*)
1 Qualified user space Input Char(20)
name The structure in which to return error information. For
2 Error code I/O Char(*) the format of the structure, see “Error Code Parameter”
on page 2-6.
Service Program: QSRLIB01

Threadsafe: No User Space Format

The following defines the format for the information in the
The Save Object (QsrSave) API saves a copy of one or user space. For detailed descriptions of the fields in the user
more objects that can be used in the integrated file system. space format, see “Field Descriptions” on page 3-62.

For detailed restrictions on using this API to save objects in

Offset
libraries or to save document library objects, see the Backup
and Recovery book. Dec Hex Type Field
0 0 BINARY(4) Number of variable length
records
Authorities and Locks
4 4 BINARY(4) Offset to first record
User Space 8 8 CHAR(8) Reserved
User Space Authority Note: These fields repeat for each variable length record.
*USE BINARY(4) Key
User Space Library Authority
| *EXECUTE BINARY(4) Offset to next record
User Space Lock CHAR(8) Reserved
*EXCLRD CHAR(*) Data

Objects to Be Saved, Devices, Save While Active, Save-

While-Active Message Queue, and Output

Chapter 3. Backup and Recovery APIs 3-61

 Save Object (QsrSave) API

If the length of the data is longer than the key identifier's data
Key Type Field SAV Command
length, the data will be truncated at the right. No message Parameter
will be issued.
3 CHAR(1) Directory SUBTREE
If the specified data length is shorter than the key field's subtree
defined data length, an error message is returned for binary 4 CHAR(1) System SYSTEM
fields. If the field is a character field, the data is padded with 5 CHAR(40) Change period CHGPERIOD
blanks and an error message will not be returned.
6 CHAR(1) Object precheck PRECHK
Note: This does not apply to keys that allow a list of values
7 CHAR(10) Target release TGTRLS
to be specified. In these cases, the amount of data read is
based on the specified number of entries in the list. 8 CHAR(*) Update history UPDHST
9 CHAR(*) Volume identi- VOL
If keys are duplicated in the user space, only the last value fier
for a given key is used for the save operation.
10 CHAR(*) Label LABEL
Each variable length record must be 4-byte aligned. If not, 11 BINARY(4) Sequence SEQNBR
unpredictable results may occur. number
12 CHAR(7) Expiration date EXPDATE
Field Descriptions 13 CHAR(1) End of tape ENDOPT
option
Data. The data used to specify the value for the given key. 14 CHAR(1) Clear CLEAR

Key. The parameter of the Save Object (SAV) command to 15 CHAR(1) Data com- DTACPR
specify. See “Valid Keys” for the list of valid keys. pression
16 CHAR(1) Data com- COMPACT
Offset to first record. The offset from the beginning of the paction
user space to the first variable length record.
17 CHAR(*) Optical file OPTFILE
Offset to next record. The offset from the beginning of the 18 CHAR(1) Save while SAVACT
user space to the next variable length record. active
19 CHAR(*) Save-while- SAVACTMSGQ
Number of variable length records. The number of vari- active message
| able length records that are passed in the user space. The queue
| valid range is from 2 through 22.
20 CHAR(*) Output OUTPUT, INFTYPE
Reserved. An ignored field. 21 CHAR(1) Use optimum USEOPTBLK
block size
| 22 CHAR(1) Save-while- SAVACTOPT
Valid Keys | active option
The following table lists the valid keys for the key field area
of the variable length record. For detailed descriptions of
the keys, see the “Field Descriptions.” Field Descriptions

Some messages for this API refer to parameters and values The values shown in parentheses are the corresponding
of the Save Object (SAV) command. This table can also be values for the SAV command parameters.
used to locate the key names that correspond to the SAV
Change period. A date and time range. Objects that
command parameters. The field descriptions contain, in
changed within the range are saved.
addition to detailed descriptions, the corresponding param-
eter values. If this key is not specified, the default of *ALL will be used for
the start date and time and the end date and time.
The object path name key and the device path name key are
required keys. The other keys are optional.
Offset

Key Type Field SAV Command Dec Hex Type Field

Parameter CHAR(10) Start date
1 CHAR(*) Device path DEV CHAR(10) Start time
name
CHAR(10) End date
2 CHAR(*) Object path OBJ
name CHAR(10) End time

3-62 AS/400 System API Reference V4R4

 Save Object (QsrSave) API

End date. The date before which objects that have start-date The date after which objects
changed are saved. that have changed are saved in
the format CYYMMDD:
The possible values are:
*ALL No ending date is specified. All
C Century, where
0 indicates years
objects changed since the
19xx and 1 indi-
starting date are saved.
cates years
end-date The date before which objects
20xx.
that have changed are saved in
the format CYYMMDD:
YY Year
C Century, where
MM Month
0 indicates years
DD Day
19xx and 1 indi-
Start time. The time on the start date after which objects
that have changed are saved.
cates years
20xx. The possible values are:
YY Year *ALL All times of day are included in
MM Month the range.
DD Day start-time The time on the start date after
End time. The time on the end date before which objects which objects that have
that have changed are saved. changed are saved in the
format HHMMSS:
The possible values are:
*ALL All times of day are included in
HH Hour
the range.
MM Minute
end-time The time on the end date
SS Second
before which objects that have Note: An explicit time is valid
changed are saved in the only if the starting date is an
format HHMMSS: explicit date.
HH Hour
MM Minute Clear. Whether tapes, diskettes, optical volumes, or save
SS Second files that contain active data and are encountered during the
save operation are automatically cleared. An uncleared tape,
Note: An explicit time is valid
diskette, or optical volume is one that contains a file with an
only if the ending date is an
expiration date later than the date of the save operation
explicit date.
(including files protected permanently with a permanent expi-
Start date. The date after which objects that have
ration date). The default is 0.
changed are saved.
The possible values are: Notes:
*ALL No starting date is specified. a. This key does not control initializing tapes or
All objects changed prior to the diskettes used to perform the save operation.
ending date are saved. Before the save is issued, tapes should be initialized
*LASTSAVE Objects are saved that have to a standard label format and diskettes should be
changed since the last time initialized to a save and restore format.
they were saved with update
Ÿ You can use the Initialize Tape (INZTAP)
history.
command and specify a value on the NEWVOL
Notes: parameter to initialize a tape to a standard label
1. If this value is specified, format.
the value *ALL must be Ÿ You can use the Initialize Diskette (INZDKT)
specified on all other ele- command and specify FMT(*SAVRST) to ini-
ments of this key. tialize a diskette to a save and restore format.
2. For file systems that are If a tape or diskette volume that is not initialized is
accessed through the encountered during the save operation, an inquiry
network server, the PC message will be sent and an operator can initialize
archive attribute is used. the tape or diskette volume.
For other file systems, the
b. This key does control initializing optical volumes.
AS/400 archive attribute is
By clearing an optical volume, you initialize it. If an
used.
optical volume is cleared, the optical file specified
on the optical file key must be in the root directory
of the volume.

Chapter 3. Backup and Recovery APIs 3-63

Save Object (QsrSave) API

The possible values are: key, both device data compaction and device
data compression are performed if supported
0 None of the media volumes or save files
on the device.
encountered during the save operation are
automatically cleared. (*NONE)
Data compression. Whether data compression is per-
Ÿ If an uncleared tape, diskette, or optical formed. The default is 2.
volume is encountered, an inquiry
message is sent to the operator. The The possible values are:
operator can clear the volume, place 0 No data compression is performed. (*NO)
another volume in the tape or diskette 1 If the save operation is to tape and the target
unit, or end the save operation. device has the hardware compression feature,
Ÿ If a save file that contains data is encoun- hardware compression is done. If the feature
tered, an inquiry message is sent to the is not present, or if the save data is written to
work station message queue for an inter- diskette or save file, software data com-
active job, or to the operator for a batch pression is done. If the save operation is
job. The choice is to clear the save file or being done while other jobs on the system are
to end the save operation. active and software data compression is used,
the overall system performance may be
1 All uncleared tapes, diskettes, optical
affected. (*YES)
volumes, or save files encountered during the
save operation are cleared automatically. Note: If 1 is specified for the data com-
(*ALL) pression key and 1 is specified for the data
compaction key, both device data compaction
If tapes are used and a sequence number is
and device data compression are performed if
specified for the sequence number key, the
supported on the device.
first tape is cleared beginning at that
2 If the tape device has the hardware com-
sequence number. All tapes following the first
pression feature installed, processing pro-
tape are completely cleared. To clear the
ceeds as if 1 were specified for the data
entire first tape, 1 must be specified for the
compression key. If the compression feature
sequence number key.
is not installed or if save data is written to a
2 All of the tapes, diskettes, or optical volumes
diskette or save file, processing proceeds as if
that are found after the first volume, and that
0 were specified for the data compression
are not already cleared, are cleared. If the
key. (*DEV)
operation cannot proceed because the first
volume is not cleared, an inquiry message is Note: If 2 is specified for the data com-
sent to the operator. The operator can either pression key and 1 is specified for the data
end the save operation or can specify that the compaction key, only device data compaction
currently selected volume be cleared so the is performed if compaction is supported on the
operation can continue. (*AFTER) device. Otherwise, data compression is per-
formed if supported on the device.
Note: This value is not valid for save files.
Device path name. The path name of the device to which
Data compaction. Whether device data compaction is per-
the objects are saved.
formed. The default is 1.

The possible values are: Offset

Dec Hex Type Field
0 Device data compaction is not performed.
(*NO) BINARY(4) Number in array
1 Device data compaction is performed if the BINARY(4) Offset to first device path
data is saved to tape and all tape devices name
specified for the device key support the com-
Note: These fields repeat for each device path name
paction feature. (*DEV)
BINARY(4) Offset to next device path
Note: If 1 is specified for the data com- name
paction key and 2 is specified for the data
CHAR(12) Reserved
compression key, only device data compaction
is performed if compaction is supported on the CHAR(*) Device path name
device. Otherwise, data compression is per-
formed if supported on the device. Device path name.
If 1 is specified for the data compaction key The path name of the device to which the
and 1 is specified for the data compression objects are saved. The path name should be
specified in the Qlg_Path_Name_T format. If

3-64 AS/400 System API Reference V4R4

 Save Object (QsrSave) API

a pointer is specified in the path name format, 1 The entire subtree of each directory that
it must be 16-byte aligned. If not, unpredict- matches the object name pattern is included.
able results may occur. For more information The subtree includes all subdirectories and
on this structure, see “Path Name Format” on the objects within those subdirectories. (*ALL)
page 2-8. 2 The objects in the first level of each directory
that matches the object name pattern are
The possible values are:
included. The subdirectories of each
device-path-name
matching directory are included, but the
The path name of the diskette
objects in the subdirectories are not included.
device, media library device,
(*DIR)
optical device, save file, or tape
device used to save the
3 Only the objects that exactly match the object
name pattern are included. If the object name
objects. If a diskette device,
pattern specifies a directory, objects in the
media library device, optical
directory are not included. (*OBJ)
device, or save file path name
is specified, it must be the only
End of tape option. The operation that is automatically per-
element in the array.
formed on the tape volume after the operation ends. If more
Number in array. than one volume is included, this key applies only to the last
The number of devices used during the save
tape volume used; all other tape volumes are rewound and
operation.
unloaded when the end of the tape is reached. The default
The possible values are: is 0.
1-4 The number of devices used
during the save operation. The possible values are:
Offset to first device path name. 0 The tape is automatically rewound, but not
The offset from the beginning of the user unloaded, after the operation ends.
space to the first device path name in the list. (*REWIND)
The possible values are: 1 The tape does not rewind or unload after the
n The offset from the beginning operation ends. It remains at the current posi-
of the user space to the first tion on the tape drive. (*LEAVE)
device path name in the list. 2 The tape is automatically rewound and
Offset to next device path name. unloaded after the operation ends.
The offset from the beginning of the user (*UNLOAD)
space to the next device path name in the list.
Expiration date. The media in the device cannot be over-
The possible values are: written until the expiration date. The expiration date must be
n The offset from the beginning later than or equal to the current date. The default is
of the user space to the next 0999999.
device path name in the list. If
the current device path name is The possible values are:
the last device path name in
0999999 The media in the device is protected perma-
the array, this value should be
nently. (*PERM)
0.
date The date when protection for the media ends
Reserved Reserved.
in the format CYYMMDD:
The possible value is: C Century, where 0 indicates
blanks This field should contain years 19xx and 1 indicates
blanks. years 20xx.
YY Year
Directory subtree. Whether the directory subtrees are MM Month
included in the save operation. The default is 1. DD Day

The possible values are: Label. The file identifier of the media to be used for the
0 No subtrees are included in the save opera- save operation. The default is *GEN.
tion. If a directory matches the object name
The possible values are as follows:
pattern specified, the objects in the directory
are included. If the directory has subdirecto- *GEN The system generates the label.
ries, neither the subdirectories nor the objects
Ÿ For objects in libraries, this is the equiv-
in the subdirectories are included. (*NONE)
alent of LABEL(*LIB) on the Save Object
(SAVOBJ) and the Save Library (SAVLIB)
commands.

Chapter 3. Backup and Recovery APIs 3-65

Save Object (QsrSave) API

Ÿ For document library objects, this is the object-path-name

equivalent of LABEL(*GEN) on the Save The object path name or
Document Library Object (SAVDLO) com- pattern that can match many
mands. names.
Ÿ For objects in other file systems, the label
Offset to first object path name
The offset from the beginning of the user
is SAVyyyymmdd for a tape and
space to the first object path name in the list.
SAVyyyymmdd.Qnnn for a diskette,
where yyyymmdd.Qnnn is: The possible values are:
yyyy Year
n The offset from the beginning
of the user space to the first
mm Month
object path name in the list.
dd Day
nnn Unique file sequence
Offset to next object path name
The offset from the beginning of the user
number.
space to the next object path name in the list.
and yyyymmdd is:
The possible values are:
yyyy Year n The offset from the beginning
mm Month of the user space to the next
dd Day object path name in the list. If
file-identifier The identifier (maximum of 17 characters) of the current object path name is
the tape or diskette file used for the save the last object path name in the
operation. array, this value should be 0.
Option. Whether names that match the pattern should
Object path name. The path name of the object to save. be included or omitted from the save opera-
You can specify a pattern for this path name. tion. When determining whether the name
matches a pattern, name patterns are always
Offset treated as relative to the current working
directory.
Dec Hex Type Field
BINARY(4) Number in array Note: The subtree key specifies whether the
subtrees are included or omitted.
BINARY(4) Offset to first object path
name The possible values are:
0 The objects that match the
Note: These fields repeat for each object path name
object name pattern are not
BINARY(4) Offset to next object path saved. This value overrides
name
objects that are included with
CHAR(4) Reserved option 1 and is intended to be
CHAR(1) Option used to omit a subset of a pre-
viously selected pattern.
CHAR(7) Reserved
(*OMIT)
CHAR(*) Object path name 1 The objects that match the
object name pattern are saved,
Number in array. unless overridden by an omit
The number of object path names to be specification. (*INCLUDE)
saved. Reserved Reserved.
The possible values are: The possible value is:
1-300 The number of object path 0 This field should always be 0.
names to be saved.
Object path name. Object precheck. Whether the save operation ends if any
The path name of the object to save. You of the selected objects cannot be saved. The default is 0.
can specify a pattern for this path name. The
The possible values are:
path name should be specified in the
Qlg_Path_Name_T format. If a pointer is 0 The save operation does not end. Objects
specified in the path name format, it must be that can be saved are saved. (*NO)
16-byte aligned. If not, unpredictable results 1 The save operation ends. Nothing is saved
may occur. For more information on this unless all of the selected objects can be
structure, see “Path Name Format” on saved. (*YES)
page 2-8.
Optical file. The path name of the optical file that is used
The possible values are: for the save operation. The path name should be specified

3-66 AS/400 System API Reference V4R4

 Save Object (QsrSave) API

in the Qlg_Path_Name_T format. If a pointer is specified in blanks This field should contain
the path name format, it must be 16-byte aligned. If not, blanks.
unpredictable results may occur. For more information on Type of output information.
this structure, see “Path Name Format” on page 2-8. The type of information that is directed to the
spooled file, stream file, or user space speci-
Note: This key is required when using an optical device.
fied for the output key.
The possible value follows: The possible values are:
Optical file The path name of the optical file that is used 0 The file contains information
for the save operation, beginning with the root about the command, and an
directory of the volume. entry for each directory.
(*SUMMARY)
When using a CD-ROM device, the extension
1 The file contains information
separator, the version separator, and the
about the command, an entry
version number must be included at the end
for each directory, and an entry
of the path name. For example, a file named
for each object that was not
'myfile' that is in the root directory of the
successfully saved. (*ERR)
volume, and that has no extension and only a
2 The file contains information
single version, is specified as '/myfile.;1'.
about the command, an entry
for each directory, an entry for
Output. Whether a list of information about the saved
each object that was success-
objects is created. The information can be directed to a
fully saved, and an entry for
spooled file, a stream file, or a user space.
each object that was not suc-
cessfully saved. (*ALL)
Offset
Dec Hex Type Field Save while active. Whether an object can be updated while
CHAR(1) Option it is being saved. The default is 0.

CHAR(1) Type of output information The possible values are:

CHAR(14) Reserved 0 The objects that are in use are not saved.
CHAR(*) Output path name Objects cannot be updated while they are
being saved. (*NO)
Option. Whether a list of information about the saved 1 Objects can be saved and used at the same
objects is created. The default is 0. time. The object checkpoints can occur at dif-
ferent times. (*YES)
The possible values are: 2 Objects can be saved and used at the same
0 No output is created. (*NONE) time. All of the object checkpoints occur at
1 The output is printed with the the same time. (*SYNC)
job’s spooled output. (*PRINT)
2 The output is directed to an | Save-while-active option. The options that should be used
existing stream file or user | with the save-while-active key.
space specified by the output
path name. | The possible values are:
Output path name. | 0 No special save-while-active options will be
The path name of the existing stream file or | used. (*NONE)
user space to which the output of the API is | 1 When 1 or 2 is specified for the save-while-
directed. The path name should be specified | active key, objects will be enabled to be saved
in the Qlg_Path_Name_T format. If a pointer | when they are being updated if the corre-
is specified in the path name format, it must | sponding system attribute for the object is set.
be 16-byte aligned. If not, unpredictable
results may occur. For more information on | This option should be used only by applica-
this structure, see “Path Name Format” on | tions to save objects that are associated with
page 2-8. | the application and that have additional
| backup and recovery considerations. See the
The possible values are: | Backup and Recovery book for additional
path-name The path name of the existing | information.
stream file or user space to
which the output of the API is Save-while-active message queue. The path name of the
directed. message queue that the save operation uses to notify the
Reserved Reserved. user that save-while-active checkpoint processing is com-
The possible value is: plete.

Chapter 3. Backup and Recovery APIs 3-67

Save Object (QsrSave) API

0 Only local objects are processed. (*LCL)

Offset
1 Only remote objects are processed. (*RMT)
Dec Hex Type Field 2 Both local and remote objects are processed.
CHAR(1) Option (*ALL)
CHAR(15) Reserved
Target release. The release level of the operating system
CHAR(*) Save-while-active message- on which you intend to use the object being saved. The
queue path name default is *CURRENT.

Option. Whether a message should be used to notify The possible values are:
the user that save-while-active checkpoint pro- *CURRENT The object is to be restored to, and used on,
cessing is complete. The default is 0. the release of the operating system that is
The possible values are: currently running on your system. The object
0 No notification message is can also be restored to a system with any
sent. (*NONE) subsequent release of the operating system.
1 The notification message is *PRV The object is to be restored to the previous
sent to the work station release with modification level 0 of the oper-
message queue. (*WRKSTN) ating system. The object can also be restored
2 The notification message is to a system with any subsequent release of
sent to the specified save- the operating system installed.
while-active message-queue target-release
path name. The release in the format VxRxMx. The
Reserved Reserved. object can be restored to a system with the
specified release or with any subsequent
The possible value is:
release of the operating system.
blanks This field should contain
blanks. When you specify the target-release value, the
Save-while-active message-queue path name. format VxRxMx is used to specify the release,
The path name of the message queue that will where Vx is the version, Rx is the release,
be used to notify the user that save-while- and Mx is the modification level. For example,
active checkpoint processing is complete. V4R3M0 is Version 4, Release 3, Modification
The path name should be specified in the Level 0.
Qlg_Path_Name_T format. If a pointer is Valid values depend on the current version,
specified in the path name format, it must be release, and modification level, and they
16-byte aligned. If not, unpredictable results change with each new release. See the valid
may occur. For more information on this values for TGTRLS parameter table in the
structure, see “Path Name Format” on Backup and Recovery book for a complete list
page 2-8. of valid values.
The possible value is:
Save-while-active message-queue path name Update history. Whether to update the save history on
The path name of the message objects saved with this save operation. The save history is
queue. used when *LASTSAVE is specified for the start time value
of the change period key on a subsequent save operation.
Sequence number. The tape file sequence number to be
used. The default is -1. The possible values include:

The possible values are: Offset

-1 The system saves the object starting after the Dec Hex Type Field
last sequence number on the first tape. If the BINARY(4) Number in array
first tape is full, an error message is issued
Note: This field repeats for each update history value.
and the operation ends. (*END)
1-16777215 The sequence number of the file. Any CHAR(1) Update history
existing files on the tape at or beyond this
sequence number are overwritten. Number in array.
The number of update history values.
System. Whether to process objects that exist on the local
The possible values are:
system or remote systems. The default is 0.
1-2 The number of update history
The possible values are: values.

3-68 AS/400 System API Reference V4R4

 Save Object (QsrSave) API

Update history
Offset
Whether to update the save history on objects
saved with this save operation. The save Dec Hex Type Field
history is used when *LASTSAVE is specified BINARY(4) Number in array
for the start time value of the change period BINARY(4) Length of each volume
key on a subsequent save operation. The identifier
default is 0.
BINARY(4) Offset to first volume identi-
The possible values include: fier
0 The save history is not Note: These fields repeat for each volume identifier
updated. (*NO)
BINARY(4) Offset to next volume identi-
1 The save history is updated.
fier
For file systems that are
accessed through the network CHAR(*) Volume identifier
server, the PC archive attribute
is set to No. For other file Length of each volume identifier.
systems, the AS/400 archive The character length of each of the volume
attribute is set to No. (*YES) identifiers.
2 The system save history is The possible value follows:
updated. The AS/400 archive n The size of a single volume
attribute is set to No. (*PC) identifier. The maximum size
3 The PC save history is of a tape or diskette volume
updated. The PC archive attri- identifier is 6 characters. The
bute is set to No. (*SYS) maximum size of an optical
volume identifier is 32 charac-
Use optimum block size. Whether the optimum block size ters. If a volume identifier
is used for the save operation. The default is 1. larger than the maximum size
is entered for this key, it is trun-
The possible values are:
cated to the maximum size.
0 The optimum block size supported by the Number in array.
device is not used. Save uses the default The number of volume identifiers that are
block size supported by all device types. The used during the save operation. The default
tape volume can be duplicated to any media is 0.
format by using the Duplicate Tape (DUPTAP)
The possible values are:
command. (*NO)
0 The volume currently placed in
1 The optimum block size supported by all
the device is used. If 0 is
devices is used. If the optimum block size is
specified for a tape media
used, the following can occur:
library device, volume identi-
Ÿ Performance may improve. fiers must be supplied by using
Ÿ The tape file that is created is only com- the Tape Management exit
patible with a device that supports the program during the save or
block size used. Commands such as restore operation. If 0 is speci-
Duplicate Tape (DUPTAP) do not dupli- fied, the length of each volume
cate files unless the files are being dupli- identifier value is ignored.
cated to a device that supports the same (*MOUNTED)
block size that was used. Note: This value cannot be
Ÿ The value for the data compression key is specified for an optical media
ignored. library device.
1-75 The number of volume identi-
If the target release key that is specified is fiers used during the save
earlier than V3R7M0, then the block size sup- operation.
ported by all device types is used. (*YES) Offset to first volume identifier.
The offset from the beginning of the user
Volume identifier. The volume identifiers of the volumes, or
space to the first volume identifier in the list.
the cartridge identifier of a tape in a tape media library
device, on which data is saved. The volumes must be placed The possible value is:
in the device in the order specified on this key. After all n The offset from the beginning
specified volumes are filled, the save operation continues on of the user space to the first
whatever volumes are mounted on the device. volume identifier in the list.

Chapter 3. Backup and Recovery APIs 3-69

Save Object (QsrSave) API

Offset to next volume identifier.

If you specify... ...cannot be specified
The offset from the beginning of the user
space to the next object volume identifier in Save while active = 0 Save-while-active message
queue
the list.
| Save-while-active option
The possible value is:
Use optimum block size = 1 Target release = release
n The offset from the beginning earlier than Version 3
of the user space to the next Release 7 Modification 0
volume identifier in the list. If
the current volume identifier is
the last volume identifier in the Relationship to SAV Command
array, this value should be 0.
Volume identifier. Due to the relationship between the QsrSave API and the
The volume identifiers of one or more volumes SAV command, the following situations should be noted:
to be used. Ÿ Message text: Several messages produced by this API
The possible value is: refer to parameters or values of the SAV command (for
Volume identifier example, *AFTER). To determine which key a given
The volume identifiers of one or parameter corresponds to, see “Valid Keys” on
more volumes to be used. page 3-62. To determine which key value a given
parameter value corresponds to, see “Field Descriptions”
on page 3-62.
Dependencies between Keys
Ÿ Command type: The command type listed for the API
The following two tables list the dependencies between the on headings of displays and print files is QsrSave for
different keys. If the dependency pertains only to a certain integrated file system objects. If QsrSave is used to
value, then that value is also shown (key = n, where n is the save objects in libraries or document library objects
value). Otherwise, if the dependency is true for all values of (DLOs), the generated output indicates that the corre-
the key, then only the name of the key is given. sponding library or document library objects (DLO)
command generated the media.
The following table lists the conditions where specifying a
certain key forces the use of another key.
Error Messages
If you specify... ...must be specified CPF0001 E Error found on &1 command.
Device = optical device Volume identifier CPF24B4 E Severe error while addressing parameter list.
Optical file CPF3700 E All CPF37xx messages could be signalled. xx
is from 01 to FF.
The following table lists the conditions where specifying a CPF3800 E All CPF38xx messages could be signalled. xx
certain key excludes the user from using another key or a is from 01 to FF.
particular value of that key. CPF3C31 E
Object type &1 is not valid.
CPF3C4D E
If you specify... ...cannot be specified
Length &1 for key &2 not valid.
Device = diskette device End of tape option CPF3C81 E
Optical file
Value for key &1 not valid.
Sequence number
CPF3C82 E
Device = optical device End option Key &1 not valid for API &2.
Label CPF3C83 E
Sequence number
Key &1 not allowed with value specified for key
Target release = release
earlier than Version 3
&2.
Release 6 Modification 0 CPF3C84 E
Use optimum block size Key &1 required with value specified for key &2.
CPF3C85 E
Device = save file Clear = 2
End of tape option Value for key &1 not allowed with value for key
Expiration date &2.
Label CPF3C86 E
Optical file Required key &1 not specified.
Sequence number CPF3C87 E
Use optimum block size Key &1 allows one value with special value.
Volume identifier CPF3C90 E
Device = tape device Optical file Literal value cannot be changed.

3-70 AS/400 System API Reference V4R4

 Save Object List (QSRSAVO) API

CPF3CF1 E Tape, Optical, or Diskette Lock

Error code parameter not valid. *EXCL
CPF5729 E Not able to allocate object &1. Media Library Device Lock
CPF9800 E All CPF98xx messages could be signaled. xx is *SHRUPD
from 01 to FF. | Media Definition Authority
CPF9999 E Function check. &1 unmonitored by &2 at state- | *USE
ment &5, instruction &3. | Media Definition Library Authority
| *EXECUTE
| Media Definition Lock
Save Object List (QSRSAVO) API | *EXCLRD
Note: If the save file will be cleared, *OBJMGT authority is
also required.
Required Parameter Group:
Save While Active
1 Qualified user space Input Char(20)
name Message Queue Authority
2 Error code I/O Char(*) *OBJOPR and *ADD
Message Queue Library Authority
Threadsafe: No *EXECUTE

Output Files
The Save Object List (QSRSAVO) API saves a list of objects
Output File Lock
specified by the user. The list of objects, as well as any addi-
*SHRRD
tional information needed for the save operation, is gener-
ated by the user into a user space. If the output file does not exist:
Output File Library Authority
Authorities and Locks *READ and *ADD

The following authorities are needed if the user does not If the output file exists and a new member will be added:
have *SAVSYS or *ALLOBJ special authority.
Output File Authority
User Space *OBJMGT, *OBJOPR, and *ADD
Output File Library Authority
User Space Authority *EXECUTE and *ADD
*USE
User Space Library Authority If the output file exists and an existing member will be
*USE appended:
User Space Lock
Output File Authority
*SHRNUP
*OBJMGT and *ADD
Objects to Be Saved Output File Library Authority
*EXECUTE
Object Authority
*OBJEXIST If the output file exists and an existing member will be
Library Authority replaced:
*EXECUTE
Output File Authority
Object Lock *SHRNUP
*OBJMGT, *OBJOPR, *ADD, and *DLT
Library Lock *SHRUPD
Output File Library Authority
Note: Lower levels of locking may be used for objects in *EXECUTE
certain cases. See the Backup and Recovery book
for more information on these special cases.
Required Parameter Group
Devices
Qualified user space name
Save File Authority INPUT; CHAR(20)
*USE and *ADD The user space that is to hold all the information for the
Save File Library Authority save operation. The first 10 characters contain the user
*EXECUTE space name. The second 10 characters contain the
Save File Lock name of the library where the user space is located.
*EXCLRD See “User Space Format” on page 3-72 for the format of
Tape, Optical, or Diskette Authority the information in the user space.
*USE

Chapter 3. Backup and Recovery APIs 3-71

Save Object List (QSRSAVO) API

You can use the following special values for the library Field Descriptions
name. However, it should be noted that the library
name that is actually used is not passed back to the Data. The data used to specify the value for the given key.
user. Care should be taken when using these special
values to avoid unexpected results. Key. The parameter of the Save Object (SAVOBJ)
command to specify. See “Valid Keys” for the list of valid
*CURLIB The job’s current library is used to locate keys.
the user space. If no library is specified
as the current library for the job, the Length of data. The length of the data used to specify the
QGPL library is used. value for the given parameter.
*LIBL The library list is used to locate the user
space. Length of variable length record. The length of the vari-
able length record.
Error code
I/O; CHAR(*) Number of variable length records. The number of vari-
The structure in which to return error information. For | able length records that are passed in the user space. The
the format of the structure, see “Error Code Parameter” | valid range is from 2 through 31.
on page 2-6.
Valid Keys
User Space Format The following table lists the valid keys for the key field area
The following defines the format for the information in the of the variable length record. For detailed descriptions of
user space. For detailed descriptions of the fields in the user the keys, see the “Field Descriptions” on page 3-73.
space format, see “Field Descriptions.”
Some messages for this API refer to parameters and values
of the Save Object (SAVOBJ) command. This table can also
Offset
be used to locate the key names that correspond to the
Dec Hex Type Field SAVOBJ command parameters. The field descriptions
0 0 BINARY(4) Number of variable length contain, in addition to detailed descriptions, the corre-
records sponding parameter values.
Note: These fields repeat for each variable length record.
The library key and the device key are required keys. The
BINARY(4) Length of variable length other keys are optional.
record
BINARY(4) Key Key Type Field SAVOBJ
Command
BINARY(4) Length of data
Parameter
CHAR(*) Data
1 CHAR(*) Object information OBJ, OBJTYPE
2 CHAR(*) Library LIB
If you specify a data length that is longer than the key field’s
defined data length, the data is truncated at the right. No 3 CHAR(*) Device DEV
error message is returned. 4 CHAR(20) Save file SAVF

If you specify a data length that is shorter than the key field’s 5 CHAR(1) Update history UPDHST
defined data length, an error message is returned for binary 6 CHAR(*) Volume identifier VOL
fields. If the field is a character field, the data is padded with 7 BINARY(4) Sequence number SEQNBR
blanks.
8 CHAR(*) Label LABEL
Note: This does not apply to keys that allow a list of values
9 CHAR(7) Expiration date EXPDATE
to be specified. In these cases, the amount of data
read is based on the specified number of entries in 10 CHAR(1) End of tape option ENDOPT
the list. 11 CHAR(10) Target release TGTRLS
12 CHAR(1) Clear CLEAR
If keys are duplicated in the user space, only the last value
for a given key is used for the save operation. 13 CHAR(1) Object precheck PRECHK
14 CHAR(1) Save while active SAVACT
15 BINARY(4) Save while active SAVACTWAIT
wait time
16 CHAR(20) Save while active SAVACTMSGQ
message queue

3-72 AS/400 System API Reference V4R4

 Save Object List (QSRSAVO) API

1 Device data compaction is performed if the

Key Type Field SAVOBJ
Command data is saved to tape and all tape devices
Parameter specified support the compaction feature.
(*DEV)
17 CHAR(*) File member FILEMBR
18 CHAR(1) Save access paths ACCPTH Data compression. Whether data compression is used.
19 CHAR(1) Save file data SAVFDTA The default is 2.

20 CHAR(1) Storage STG The possible values are:

21 CHAR(1) Data compression DTACPR 0 No data compression is performed. (*NO)
22 CHAR(1) Data compaction COMPACT 1 If the save operation is to tape and the target
23 CHAR(1) Output OUTPUT device supports compression, hardware com-
pression is performed. If compression is not
24 CHAR(20) Qualified output OUTFILE supported on the device, or if the save data is
file
written to a save file or diskette, software
25 CHAR(11) Output member OUTMBR compression is performed. (*YES)
26 CHAR(1) Type of output INFTYPE 2 If the save operation is to tape and the target
information device supports compression, hardware com-
27 CHAR(*) Optical file OPTFILE pression is performed. Otherwise, no data
compression is performed. (*DEV)
28 CHAR(1) Use optimum USEOPTBLK
block size Device. The names of the devices used for the save opera-
29 CHAR(*) Omit library OMITLIB tion. The device must already be known on the system by a
30 CHAR(*) Omit object infor- OMITOBJ device description. For the format of this field, see “Device
mation Key Format” on page 3-76.
| 31 CHAR(20) Media definition MEDDFN End of tape option. When tape is used, the positioning
operation that is automatically done on the tape volume after
the save operation ends. If more than one volume is
Field Descriptions included, this key applies only to the last volume used. All
other volumes are rewound and unloaded when the end of
The values shown in parentheses are the corresponding
tape is reached. The default is 0.
values for the SAVOBJ command parameters.
The possible values are:
Clear. Whether an uncleared save file, or uncleared tape
volumes, diskette volumes, or optical volumes encountered 0 The tape is automatically rewound, but not
during the save operation are automatically cleared. The unloaded, after the operation ends.
default is 0. (*REWIND)
1 The tape does not rewind or unload after the
The possible values are: operation ends. It remains at the current posi-
0 None of the uncleared tape volumes, diskette tion on the tape drive. (*LEAVE)
volumes, optical volumes, or save files 2 The tape is automatically rewound and
encountered are automatically cleared. unloaded after the operation ends.
(*NONE) (*UNLOAD)
1 All of the uncleared tape volumes, diskette
Expiration date. The expiration date of the tape file,
volumes, optical volumes, or save files
diskette file, or optical file created by the save operation. If a
encountered are automatically cleared. (*ALL)
date is specified, the file is protected and cannot be over-
2 All of the uncleared tape volumes, diskette
written until the specified expiration date. The default is
volumes, or optical volumes after the initial
0999999.
tape, diskette, or optical volume are automat-
ically cleared. (*AFTER) The possible values are:
Data compaction. Whether data compaction is used. The 0999999 The file is protected permanently. (*PERM)
default is 1. Expiration date
The date when protection for the file ends,
The possible values are: specified in the format CYYMMDD:
0 Device data compaction is not performed. C Century, where 0 indicates
(*NO) years 19xx and 1 indicates
years 20xx.
YY Year
MM Month

Chapter 3. Backup and Recovery APIs 3-73

 Save Object List (QSRSAVO) API

DD Day Ÿ The objects were not previously found to be damaged

Ÿ The objects are not locked by another job
File member. A list of the database files and their members
that are to be saved. Each database file specified here must Ÿ The requester of the save operation has authority to
also be specified in the list of objects to be saved. If this key save the objects
is not specified, the default of *ALL will be used for both the
The default is 0.
file name and the member name. For the format of this field,
see “File Member Format” on page 3-77. The possible values are:

Label. The name that identifies the data file on the tape or 0 The save operation for a library continues,
diskette. Although the label key is defined as CHAR(*), the saving only those objects that can be saved.
maximum length of a label is currently 17. If the length of (*NO)
data field is specified as more than 17, the label is truncated 1 If one or more objects cannot be saved after
such that only the first 17 characters are used. The default the specified objects are checked, the save
is *LIB. operation for a library ends before any data is
written. (*YES)
The possible values are as follows:
Omit libraries. A list of the libraries to be omitted from the
*LIB The file label is created by the system using
save operation. The default is *NONE. For the format of this
the name of the library specified for the library
field, see “Library Key Format” on page 3-77.
key.
Data file identifier Omit object information. A list of the name and type of the
The data file identifier of the data file used. objects and library to be omitted from the save operation. If
This option is valid only for a single-library *ALL is specified for the object name and object type, the list
save operation. cannot contain other entries. The default for both the object
name and the object type is *ALL. For the format of this
Library. A list of libraries that contain the objects that are
field, see “Omit Object Information Format” on page 3-78.
saved. If more than one library is specified, *ALL must be
the only object name specified (object information key) and Optical file. The name that identifies the file on the optical
the device cannot be *SAVF. For the format of this field, see volume. Although the optical file is defined as CHAR(*), the
“Library Key Format” on page 3-77. maximum length of an optical file name is currently 256 char-
acters. If the length of data field is specified as more than
| Media definition. The name and library of the media defi-
256 characters, the name is truncated such that only the first
| nition that identifies the devices and media used to contain
256 characters are used. The possible value is as follows:
| the saved data. For information about creating and using a
| media definition, see the Backup and Recovery book and the Optical file path name
| Create Media Definition (QSRCRTMD, The path name (starting with a /) of the file on
| QsrCreateMediaDefinition) API. The first 10 characters the optical volume.
| contain the media definition name, and the second 10 char-
Output. Whether a list of information about the saved
| acters contain the library in which the media definition is
objects is created. The default is 0.
| located.
The possible values are:
| You can use these special values for the library name:
| *CURLIB The job’s current library is used to locate the
0 No output listing is created. (*NONE)
| media definition. If no library is specified as
1 The output is printed with the job’s spooled
output. (*PRINT)
| the current library for the job, the QGPL library
| is used.
2 The output is directed to the database file
specified with the output file key. (*OUTFILE)
| *LIBL The library list.
Output member. The name of the database file member
Object information. A list of the name and type of the
used to save the object information. This field also deter-
objects to be saved. If *ALL is specified for the object name
mines whether to replace or add the data if the member
and object type, the list cannot contain other entries. The
already exists. The defaults are *FIRST for the output
default for both the object name and the object type is *ALL.
member name field and 0 for the option field. For the format
For the format of this field, see “Object Information Format”
of this field, see “Output Member Format” on page 3-78.
on page 3-77.
Qualified output file. The qualified name of the database
Object precheck. Whether the save operation for a library
file to which the information about the objects is directed.
should end if all objects specified by the API do not satisfy all
This key is required only if the output key is set to 2. The
the following conditions:
first 10 characters contain the output file name. The second
Ÿ The objects exist 10 characters contain the output file library. The possible
values for output file library are:

3-74 AS/400 System API Reference V4R4

 Save Object List (QSRSAVO) API

*CURLIB The job’s current library is used to locate the 3 Objects in a library can be saved while they
output file. If no library is specified as the are in use by another job. All the objects and
current library for the job, the QGPL library is all the libraries in the save operation reach a
used. checkpoint together. They are saved in a
*LIBL The library list is used to locate the output file. consistent state in relationship to each other.
Library name The name of the library where the output file (*SYNCLIB)
is located.
Save while active message queue. The name and library
Save access paths. Whether the logical file access paths of the message queue that is used to notify the user that the
that are dependent on the physical files being saved are also checkpoint processing for a library is complete. The first 10
saved. The default is 0. characters contain the message queue name. The second
10 characters contain the name of the library where the
The possible values are: message queue is located. If *NONE or *WRKSTN is speci-
0 The logical file access paths are not saved. fied for the message queue name, blanks must be specified
(*NO) for the message queue library. The defaults are *NONE for
1 The specified physical files and all eligible the message queue name and blanks for the library.
logical file access paths over them are saved.
The possible values for the message queue name are:
(*YES)
*NONE No notification message is sent.
Save file. The name and library of the save file that is used *WRKSTN The notification message is sent to the work
to contain the saved data. The first 10 characters contain the station message queue. This is not valid in
save file name, and the second 10 characters contain the batch mode.
library where the save file is located. Message queue name
The name of the message queue.
You can use these special values for the library name:
*CURLIB The job’s current library is used to locate the The possible values for the message queue library are:
save file. If no library is specified as the *CURLIB The job’s current library is used to locate the
current library for the job, the QGPL library is message queue. If no library is specified as
used. the current library for the job, the QGPL library
*LIBL The library list. is used.
*LIBL The library list is used to locate the message
Save file data. For save file objects, whether only the
queue.
description of a save file, or both the description and the con-
Library name The name of the library where the message
tents of a save file are saved. The default is 1.
queue is located.
The possible values are:
Save while active wait time. If an object is not available,
0 Only the description of a save file is saved. the amount of time to wait for a commit boundary or a lock
(*NO) on the object before continuing the save operation. The
1 The description and contents of a save file are default is 120.
saved. (*YES)
The possible values are:
Note: For System/38 environments, the default value of 1 is
not valid; therefore, this key must be explicitly set to a -1 No maximum wait time exists.
value of 0. 0-99999 The time (in seconds) to wait.

Save while active. Whether an object can be updated while Sequence number. The sequence number to use for the
it is being saved. The default is 0. save operation when tape is used. The default is -1.

The possible values are: The possible values are:

0 Objects that are in use are not saved. (*NO) -1 The save operation begins after the last
1 Objects in a library can be saved while they sequence number on the tape volume.
are in use by another job. Objects in a library 1-16777215 The sequence number of the file to be used
may reach checkpoints at different times and for the save operation.
may not be in a consistent state in relationship
Storage. Whether the system storage that is occupied by
to each other. (*SYSDFN)
the data portion of the following objects in the library being
2 Objects in a library can be saved while they
saved is freed:
are in use by another job. All the objects in a
library reach a checkpoint together. They are Ÿ Files
saved in a consistent state in relationship to
Ÿ Modules
each other. (*LIB)

Chapter 3. Backup and Recovery APIs 3-75

Save Object List (QSRSAVO) API

Ÿ Programs Use optimum block size. Whether the tape device's

optimum block size should be used. The default is 0.
Ÿ Service programs
Ÿ Structured Query Language (SQL) packages The possible values are:
Ÿ Journal receivers 0 The tape device's optimum block size is not
used. A block size that is compatible with all
The default is 0.
OS/400 releases and tape devices is used.
The possible values are: (*NO)
1 The tape device's optimum block size is used.
0 The storage occupied by the data portion of
The system may create a tape that is only
the objects is not freed. (*KEEP)
compatible with a tape device that supports
1 The storage occupied by the data portion of
the same block size. Performance will likely
the objects is freed. The storage is freed only
but not necessarily improve. Commands such
after all the objects in the library are saved
as Duplicate Tape (DUPTAP) do not duplicate
successfully. (*FREE)
the tape unless it is being duplicated to a tape
device that supports the same block size.
Target release. The release of the operating system on
(*YES) Data compression is ignored when
which the objects will be restored and used. The object
optimum block size is used. Optimum block
types specified (in the object information field) must exist on
size is ignored when the target release value
the specified release. The default is *CURRENT.
specified is before V3R7M0.
The possible values are:
Volume identifier. The volume identifiers of the tape
*CURRENT The objects are restored to, and used on, the volumes, diskette volumes, or optical volumes on which the
release of the operating system currently object data is to be saved. All volume identifiers must be
running on the system. entered in the order in which you want them saved. The
*PRV The objects are to be restored on the previous default is *MOUNTED. For the format of this field, see
release that has modification level 0 of the “Volume Identifier Format” on page 3-78.
operating system.
Release level The release level in the format VxRxMx,
where x is the number of the version, release, Device Key Format
and modification level.
Offset
Type of output information. The type of information that is Dec Hex Type Field
printed or directed to the output database file. The default is
0. BINARY(4) Number in array
Note: This field repeats for each device name.
The possible values are:
CHAR(10) Device name
0 The list contains an entry for each object
requested to be saved. (*OBJ)
1 The list contains an entry for each library Field Descriptions
requested to be saved. (*LIB)
2 The list contains an entry for each object or, Device name. The name of the device used for the save
for database files, each member requested to operation. The possible values for each element of the array
be saved. (*MBR) are:
3 The list contains an entry for each library that *SAVF The save operation is done using the save file
is requested to be saved and an entry for specified by the save file key. If specified, it
each object or, for database files, each must be the only element in the array.
member that failed to be saved. (*ERR) | *MEDDFN The save operation is done by using the
| devices and media that are identified in the
Update history. Whether the save history information of
| media definition, which is specified by the
each object is changed to the date, time, and location of this
| media definition key. If specified, it must be
save operation. The default is 1.
| the only element in the array.
The possible values are: Diskette device name
The name of the diskette device used for the
0 The save history information of each object save operation. If specified, it must be the
saved is not updated. (*NO) only element in the array.
1 The last save date, time, and location is
updated in each object saved. (*YES)

3-76 AS/400 System API Reference V4R4

 Save Object List (QSRSAVO) API

Media library device name Number of members. The number of member names for
The name of the media library device used for the given file name. Possible values are 1 through 50.
the save operation. If specified, it must be the
only element in the array. Reserved. An ignored field.
Optical device name
The name of the optical device used for the Library Key Format
save operation. If specified, it must be the
only element in the array.
Offset
Tape device name
The name of the tape device used for the Dec Hex Type Field
save operation. A maximum of four tape BINARY(4) Number in array
devices may be used. They must be specified
Note: This field repeats for each library name.
in the order in which they should be used.
CHAR(10) Library name
Number in array. The number of devices to be used during
the save operation. The possible values are 1 through 4.
Field Descriptions
File Member Format Library name. The name of the library containing the
objects. The possible value is:
Offset
Library name Either a simple or generic library name
Dec Hex Type Field
BINARY(4) Number in array
Number in array. The number of libraries used during the
save operation. The possible values are 1 through 300.
Note: These fields repeat for each file.
CHAR(10) File name
Object Information Format
CHAR(2) Reserved
BINARY(4) Number of members Offset
Note: This field repeats for each member associated with the Dec Hex Type Field
given file.
BINARY(4) Number in array
CHAR(10) Member
Note: These fields repeat for each object name.
CHAR(10) Object name
Field Descriptions CHAR(10) Object type

File name. The name of the file being saved. The possible
values are: Field Descriptions
*ALL The list of member names that follow this
value applies to all files indicated in the list of Number in array. The number of objects that are specified
objects to save. If *ALL is specified for the file for this key. There is no limit for the number in array field.
name, it must be the only file name in the list. However, the total amount of information in the user space
Database file name cannot exceed 16MB.
The name of the database file from which the
Object name. The name of the object that is to be saved.
listed members are saved.
The possible values are:
Member. The name of the member to save. The possible *ALL All the objects in the specified libraries,
values are: depending on the values specified for object
*ALL All members are saved from the specified file. type
If *ALL is specified for member name, it must Object name Either a simple name or a generic name
be the only member name for that file.
Object type. The type of the object that is to be saved. The
*NONE No members are saved from the specified file.
possible values are:
Only the file description is saved.
Member name *ALL All objects with the specified object name,
The name of the member to save. It may be regardless of type
either a simple name or a generic name. Object type A valid type on the current release of the
system
Number in array. The number of file and member struc-
tures used during the save operation. The possible values
are 1 through 50.

Chapter 3. Backup and Recovery APIs 3-77

Save Object List (QSRSAVO) API

Omit Object Information Format Output member name. The name of the file member that
receives the output. The possible values are:
Offset *FIRST The first member in the file is used and
receives the output.
Dec Hex Type Field
Member name
BINARY(4) Number in array If the member does not exist, the system
Note: These fields repeat for each object name. creates it.
CHAR(10) Object name
CHAR(10) Library name Volume Identifier Format
CHAR(10) Object type
Offset
Dec Hex Type Field
Field Descriptions BINARY(4) Number in array

Library name. The name of the library that is to be omitted. Note: These fields repeat for each volume identifier.
The possible values are: BINARY(4) Length of volume identifier
*ALL All the libraries, depending on the values CHAR(*) Volume identifier
specified for object and object type
Library name Either a simple name or a generic name
Field Descriptions
Number in array. The number of values that are specified
for this key. The possible values are 1 through 300. Length of volume identifier. The character length of the
identifier of the volume. The possible values are:
Object name. The name of the object that is to be omitted.
The possible values are: n The size of a single volume identifier. The
maximum size of a tape or diskette volume
*ALL All the objects in the specified libraries, identifier is 6 characters. The maximum size
depending on the values specified for object of an optical volume identifier is 32 characters.
type If a volume identifier larger than the maximum
Object name Either a simple name or a generic name size is entered for this key, it is truncated to
the maximum size. If the volume identifier is
Object type. The type of the object that is to be omitted.
*MOUNTED, this value must be 8.
The possible values are:
*ALL All objects with the specified object name, Number in array. The number of volume identifiers used
regardless of type during the save operation. The possible values are 1
Object type A valid type on the current release of the through 75.
system
Volume identifier. The identifier of a volume. The possible
values are:
Output Member Format *MOUNTED The volume currently placed in the device is
used. If *MOUNTED is specified, it must be
Offset the only value specified. This value cannot be
Dec Hex Type Field specified for an optical media library device.
CHAR(10) Output member name *MOUNTED cannot be specified for a tape
media library device unless a category is set
CHAR(1) Option
with the Set Tape Category (SETTAPCGY)
command.
Volume identifier
Field Descriptions The identifier of a volume.
Option. An indicator of whether to add to or replace the
existing member. The possible values are: Dependencies between Keys
0 The existing records in the specified database
The following two tables list the dependencies between the
file member are replaced by the new records.
different keys. If the dependency holds only for a certain
(*REPLACE)
value, then that value is also shown (key = n, where n is the
1 The new records are added to the existing
value). Otherwise, if the dependency is true for all values of
information in the database file member.
the key, then only the name of the key is given.
(*ADD)

3-78 AS/400 System API Reference V4R4

 Save Object List (QSRSAVO) API

The following table lists the conditions where specifying a

If you specify... ...cannot be specified
certain key forces the use of another key.
Optical file Label
Use optimum block size
If you specify... ...must be specified
Target release = release earlier
Multiple library names or Object name = *ALL than Version 3 Release 7
generic library
Device = tape device Volume identifier 1
Sequence number 1 Relationship to SAVOBJ Command
Label 1
Expiration date 1 Due to the relationship between the QSRSAVO API and the
End of tape option 1 SAVOBJ command, the following situations should be noted:
Device = diskette device Volume identifier 1 Ÿ Message text: Several messages produced by this API
Label 1 refer to parameters or values of the SAVOBJ command
Expiration date 1
(for example, *AFTER). To determine which key a given
Device = optical device Volume identifier parameter corresponds to, see “Valid Keys” on
Optical file page 3-72. To determine which key value a given
Expiration date 1 parameter value corresponds to, see “Field Descriptions”
| Device = media definition Media definition on page 3-73.
Output = 1 Type of output information 1 Ÿ Command type: The command type listed for the API
Output = 2 Output file on headings of displays and print files is SAVOBJ, not
Output member 1 QSRSAVO.
Type of output information 1
Save while active = 1, 2, Save while active wait time 1 Error Messages
or 3 Save while active message
queue 1 CPF24B4 E Severe error while addressing parameter list.
CPF3700 E All CPF37xx messages could be signalled. xx
Storage = 1 Save while active = 0 1
is from 01 to FF.
Notes: CPF3800 E All CPF38xx messages could be signalled. xx
1. This key does not have to be explicitly specified. The is from 01 to FF.
default may be taken to satisfy this dependency. CPF3C31 E
Object type &1 is not valid.
The following table lists the conditions where specifying a CPF3C4D E
certain key excludes the user from using another key, or a Length &1 for key &2 not valid.
particular value of that key. CPF3C81 E
Value for key &1 not valid.
If you specify... ...cannot be specified CPF3C82 E
Key &1 not valid for API &2.
Save file Volume identifier
Sequence number
CPF3C83 E
Label Key &1 not allowed with value specified for key
Expiration date &2.
End of tape option CPF3C84 E
Clear = 2 Key &1 required with value specified for key &2.
Optical file CPF3C85 E
Use optimum block size Value for key &1 not allowed with value for key
| Media definition
&2.
| Media definition Volume identifier CPF3C86 E
| Sequence number Required key &1 not specified.
| Optical file CPF3C87 E
| Target release = release earlier
Key &1 allows one value with special value.
| than Version 4 Release 4
CPF3C90 E
| Tape, diskette, optical, Save file Literal value cannot be changed.
| or media definition CPF3CF1 E
| for the device
Error code parameter not valid.
Save while active = 0 Save while active wait time CPF5729 E Not able to allocate object &1.
Save while active message queue CPF9800 E All CPF98xx messages could be signaled. xx is
Output = 0 Output file from 01 to FF.
Output member CPF9999 E Function check. &1 unmonitored by &2 at state-
Type of output information ment &5, instruction &3.

Chapter 3. Backup and Recovery APIs 3-79

Save to Application (QaneSava) API

Objects saved by this API can only be restored using the

Save to Application (QaneSava) API “Restore from Application (QaneRsta) API” on page 3-26,
and only if restored to a current or a later release of the
operating system from which these were saved.
Required Parameter Group:
The application must store the save records in the order pre-
1 Qualified user space Input Char(20) sented, without modification, for the objects to be success-
name fully restored.
2 User space format Input Char(8)
name
3 Status format name Input Char(8) Authorities and Locks
4 Status information Output Char(*)
5 Length of status infor- Input Binary(4)
Exit Program Library Authority
mation *EXECUTE
6 Error code I/O Char(*) Exit Program Authority
*EXECUTE
Service Program: QANESERV User Space Lock
*SHRNUP
Threadsafe: No User Space Library Authority
*USE
User Space Authority
The Save to Application (QaneSava) API enables an applica-
*USE
tion to receive the save records that are generated by a
Save Command Library Authority
save-to-save-file operation. The application defines the save
*EXECUTE
operation by specifying the type of save command, and by
Save Command Authorities
providing the save command parameters. The API calls an
See the save command
exit program to transfer the save records to the application
Saved Object Locks
instead of to the save file.
See the Backup and Recovery book
To use the API, the application must provide the following: Saved Object Authorities
See “Appendix D ”in the Security – Reference
Ÿ A user space that contains the required input parameter book
group
Ÿ An exit program
Required Parameter Group
When processing the save command, the API does the fol- Qualified user space name
lowing: INPUT; CHAR(20)
Ÿ Calls the exit program to indicate the start of the transfer The user space that contains all the control information
sequence for the save operation. The first 10 characters contain
Ÿ Submits the save command for processing the user space name. The second 10 characters contain
the name of the library where the user space is located.
Ÿ Calls the exit program repeatedly to transfer the save
records You can use the following special values for the library
name:
Ÿ Calls the exit program to signal the end of the save
operation *CURLIB The job's current library is used to locate
Ÿ May call the exit program to force an abnormal end to the user space. If no library is specified
the save operation as the current library for the job, the
QGPL library is used.
The program that calls the API is suspended while the save *LIBL The library list is used to locate the user
operation is being processed. space.

The actual library that is used is returned in the status

Restrictions information. the user space.

QTEMP should not be specified for the library name on the User space format name
OUTFILE or SAVACTMSGQ parameter because the save INPUT; CHAR(8)
command is submitted by a prestart job running in the The format name for the input parameters that are con-
QSYSWRK subsystem and not in the job that called the API. tained in the user space. For the format of the structure,
Locks should not be applied to save objects that would con- see “SVRS0100 Format” on page 3-81.
flict with locks applied by the save operation running in the
prestart job.

3-80 AS/400 System API Reference V4R4

 Save to Application (QaneSava) API

Status format name Exit program name. The name of the exit program that is
INPUT; CHAR(8) called by the API. See “Save to Application Exit Program”
on page 3-85 for additional details.
The format name for the status information returned on
the API call. For the format of the structure, see
Length of application data. The length of the application
“SRST0100 Format” on page 3-82.
data. This value is passed to the exit program. This value
Status information must be set to zero if there is no application data.
OUTPUT; CHAR(*)
Length of save command parameters. The length of the
The status information returned on the API call. save command parameters. The maximum allowable length
is 5900 bytes for save commands.
Length of status information
INPUT; BINARY(4)
Length of structure. The length of this structure, from the
The length of the status information returned on the API start of the input parameters to the last byte of the applica-
call. The minimum length is 8 bytes. tion data.

Error code Offset to application data. The byte offset from the begin-
I/O; CHAR(*) ning of the user space to the start of the application data.
The structure in which to return error information. For This value must be set to zero if there is no application data.
the format of the structure, see “Error Code Parameter”
Offset to save command parameters. The byte offset from
on page 2-6.
the beginning of the user space to the start of the save
command parameters.
SVRS0100 Format
Save command parameters. A character string that con-
This format defines the input parameter group for the API. tains the save command parameters or save keys. These
parameters are validated when the API submits the
Offset command for processing. Refer to the save commands in
the CL Reference (Abridged) book for detailed information
Dec Hex Type Field
about valid parameters when you save objects to save files.
0 0 Binary(4) Length of structure Refer to “Save Object (QsrSave) API” on page 3-61 for
4 4 Binary(4) Offset to save command detailed information about valid keys when you save objects
parameters to save files.
8 8 Binary(4) Length of save command
parameters These additional restrictions apply to the save command
parameters when you use this API:
12 C Binary(4) Offset to application data
Ÿ The parameters specified must be consistent with the
16 10 Binary(4) Length of application data
save command type.
20 14 Binary(4) Save command type
Ÿ The parameters must not include the save command
24 18 Char(10) Exit program name name.
34 22 Char(10) Exit program library
Ÿ The parameters must be separated by at least one blank
| 44 2C Char(8) Target release character.
Char(*) Save command parameters Ÿ Only a single library name can be used with the LIB
Char(*) Application data parameter.
Ÿ The CLEAR, DEV, SAVF and TGTRLS parameters must
not be used. These parameters are provided by the
Field Descriptions API.
Application data. Information that the application wants Ÿ The DTACPR data compression and COMPACT data
passed to the exit program. The content of this information compaction parameters must not be used. These param-
is defined by the application. This field could contain infor- eters are not supported by the API.
mation specific to the object being saved (such as the object
name, size, and so forth), or it could contain the qualified The following examples illustrate the save command parame-
name of another object that contains this information. ters that are required for typical save scenarios:
Ÿ Example 1: Save command type 1 (SAV)
Exit program library. The name of the library that contains
OBJ('/\') ('/QSYS.LIB' \OMIT)
the exit program called by the API. the exit program.