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.
('/QDLS.LIB' \OMIT)
These parameters save all objects that are not in
libraries and that are not document library objects.

Chapter 3. Backup and Recovery APIs 3-81

 Save to Application (QaneSava) API

Ÿ Example 2: Save command type 2 (SAVOBJ) | specified release or with any subsequent
OBJ(FILE\) LIB(MYLIB) OBJTYPE(\FILE) | release of the operating system.

These parameters save all files with names that start | When you specify the target-release value, the
with the characters FILE* in the library named MYLIB. | format VxRxMx is used to specify the release,
| where Vx is the version, Rx is the release,
Ÿ Example 3: Save command type 4 (SAVLIB) | and Mx is the modification level. For example,
LIB(JOE) | V4R4M0 is Version 4, Release 4, Modification
| Level 0.
These parameters save the library named JOE.
| A VxRxMx value prior to V4R3M0 is not valid
These additional restrictions apply to the command parame- | since this API is not supported prior to Version
ters when you use the Save Object (QsrSave) API. | 4, Release 3, Modification Level 0.
Ÿ The keys specified must be consistent with save to save | Valid VxRxM0 values after Version 4, Release
file operations. | 3, Modification Level 0 depend on the current
Ÿ The CLEAR, DEV, SAVF and TGTRLS keys must not be | version, release, and modification level, and
used. These keys are provided by this API. | on the save operation being performed. See
| the valid values for the TGTRLS parameter
Ÿ The DTACPR data compression and COMPACT data | table in the Backup and Recovery book for a
compaction keys must not be used. These keys are not | complete list of valid values.
supported by this API.
Ÿ The starting offset for the keys is always 0 and not the
offset of the save command parameters.
SRST0100 Format
Ÿ All offset and integer values within the keys must be This format defines the status information that is returned on
aligned on 4-byte boundaries. the API call.
Ÿ All pointers within the keys must be aligned on 16-byte
boundaries. Offset
Dec Hex Type Field
Save command type. The type of save command that is to
0 0 Binary(4) Bytes returned
be processed.
4 4 Binary(4) Bytes available
1 Save (SAV) command
2 Save Object (SAVOBJ) command 8 8 Binary(4) Transfer time
3 Save Document Library Object (SAVDLO) 12 C Binary(4) Transfer block size
command 16 10 Binary(4) Transfer block multiplier
4 Save Library (SAVLIB) command
20 14 Binary(4) Last block size
5 Save Changed Object (SAVCHGOBJ)
command 24 18 Char(10) User space library used
6 Save Object (QsrSave) API

| Target release. The release level of the operating system Field Descriptions
| on which you intend to use the object being saved. The
| default is *CURRENT. Bytes returned. The number of status information bytes
returned. If the value specified in the length of status infor-
| The possible values are: mation parameter is larger than the specified status informa-
| blanks The default value is used. tion structure, this value is set to the last byte of the returned
| *CURRENT The object is to be restored to and used on information.
| the release of the operating system that is
Bytes available. The number of status information bytes
| currently running on your system. The object
available for the specified status information format.
| also can be restored to a system with any
| subsequent release of the operating system. Transfer block size. The number of bytes in the blocks
| *PRV The object is to be restored to the previous transferred by the exit program.
| release with modification level 0 of the oper-
| ating system. The object also can be restored Transfer block multiplier. The number of blocks success-
| to a system with any subsequent release of fully transferred by the exit program.
| the operating system installed.
| target-release Last block size. The number of bytes in the last block
| The release in the format VxRxMx. The transferred by the exit program.
| object can be restored to a system with the

3-82 AS/400 System API Reference V4R4

 Restore from Application 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 from Application Exit Program
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
returns to the caller. 1 Operation type Input Binary(4)
2 Operation status Output Binary(4)
User space library used. The name of the user space 3 Restore data Output Char(*)
4 Length of restore data Output Binary(4)
library that is used in the API call.
5 Restore bytes written Input Binary(4)
6 Qualified user space Input Char(20)
name
Error Messages 7 User space format Input Char(8)
CPF3700 E All CPF37xx messages could be signalled. xx name
is from 01 to FF, excluding tape and diskette
errors since the operation is a save to a save
file. The Restore from Application exit program enables an appli-
CPF3800 E All CPF38xx messages could be signalled. xx cation program to provide the restore records that are
is from 01 to FF, excluding tape and diskette required for a restore-from-save-file operation using the
errors since the operation is a save to a save “Restore from Application (QaneRsta) API” on page 3-26.
file.
CPF2115 E Object &1 in &2 type *&3 damaged. The API calls the exit program once to start the transfer
CPF3C1E E sequence, multiple times to transfer each block of restore
Required parameter &1 omitted. records, and once to end the transfer sequence.
CPF3C21 E
Format name &1 is not valid. The API passes to the exit program the operation type, the
CPF3CF1 E number of restore record bytes required, the qualified name
Error code parameter not valid. of the user space and the format name of the user space.
CPF8100 E All CPF81xx messages could be returned. xx is
The exit program must return the restore data, the number of
from 01 to FF.
the restore record bytes retrieved, and status on the success
CPF9800 E All CPF98xx messages could be signaled. xx is
or failure of the requested operation.
from 01 to FF.
CPF9999 E Function check. &1 unmonitored by &2 at state- At any time following the initial call, the API could call the exit
ment &5, instruction &3. program that requires an abnormal end to the transfer
CPFB8C0 E sequence.
Status information length for &1 API is not valid.
CPFB8C1 E
Unsupported value for &1 API. Restrictions
CPFB8C2 E
Offset value for &1 API not valid. Reason &6. The exit program must provide the restore records in the
CPFB8C3 E order the records were saved, without modification, for the
Length value for &1 API not valid. Reason &6. objects to be successfully restored.
CPFB8C4 E
Unexpected condition with exit program for &1 Authorities and Locks
API. Reason &6.
CPFB8C5 E See “Restore from Application (QaneRsta) API” on
Parameter &2 specified more than once for API page 3-26.
&1.
CPIB8C6 I Trace data generated for API &1.
CPFB8C7 E Required Parameter Group
Unsupported value for &1 API. Operation type
CPFB8C8 E INPUT; BINARY(4)
Command syntax error detected by &1 API.
CPFB8C9 E The type of operation that the exit program is required to
Command exception occurred using &1 API. run.
CPFB8CF E 1 Start
Unexpected condition with &1 API. Reason &6.
The exit program must use this operation
type to prepare for the restore records
transfer.

Chapter 3. Backup and Recovery APIs 3-83

Restore from Application Exit Program

2 Transfer (good)., when the last byte of the restore

records has been retrieved. This indicates
The exit program must use this operation
successful completion of operation type 2
type to transfer (retrieve, write, and so
(transfer).
forth) a block of restore records.
3 End Restore data
The exit program must use this operation OUTPUT; CHAR(*)
type to end the restore records transfer. A block of restore records. This parameter is returned
4 Abnormal end only on operation type 2 (transfer).
The exit program must use this operation
Length of restore data
type to prematurely end the restore
OUTPUT; BINARY(4)
records transfer.
For operation types 1 (start), 3 (end), and 4 (abnormal
Normal-operation-type order is 1 (start), 2 (transfer), 2 end), this value is zero.
(transfer), ..., 2 (transfer), 3 (end).
For operation type 2 (transfer), this is the length of
Operation type 1 (start) is issued only once at the begin- restore data being requested.
ning of the restore operation before any restore records
are transferred. Restore bytes written
INPUT; BINARY(4)
Operation type 2 (transfer) is issued multiple times
during the restore operation as each block of restore For operation types 1 (start), 3 (end), and 4 (abnormal
records is required. The exit program must provide as end), this value must be set to zero.
many restore record bytes as requested, with the excep- For operation type 2 (transfer), this value must be set to
tion of the last block, which may not be of sufficient the actual number of restore record bytes returned. This
length. value must never exceed the bytes required.
Operation type 3 (end) is issued only once at the end of
Qualified user space name
the restore operation after all restore records are trans-
INPUT; CHAR(20)
ferred. The exit program must be able to handle the
condition where this operation type is issued before all The qualified user space name that is specified by the
restore records are transferred. The exit program must application on the call to the Restore from Application
handle this operation sequence as a normal condition (QaneRsta) API. The first 10 characters contain the
and end the transfer sequence normally. user space name. The second 10 characters contain the
name of the library where the user space is located.
Operation type 4 (abnormal end) is issued only once fol-
lowing operation types 1 (start) or 2 (transfer), under User space format name
abnormal conditions to prematurely end restore records INPUT; CHAR(8)
transfer. These conditions are:
The user space format name that is specified by the
Ÿ The API detects an error with the system restore application on the call to the Restore from Application
operation. API. For the format of the structure, see “SVRS0100
Format” on page 3-27. The exit program uses the
Ÿ The exit program returns an operation status of 1
length of application data field to determine if the struc-
(error).
ture contains application data, and the offset to applica-
Operation status tion data field to locate this information.
OUTPUT; BINARY(4)
The ending status of the requested operation. Coding Guidelines
0 Good Applications should consider the following when coding the
The exit program must return this status exit program:
value to indicate successful completion of Ÿ The program should only return an exception for the
the operation. requested operation if there has been a failure in the
1 Error operation. If the program signals an escape message to
The exit program must return this status the API, the system assumes there is a failure. A diag-
value to indicate unsuccessful completion nostic message is returned to the calling program.
of the operation. Ÿ The program must clean up any locks that it acquires.
2 Complete
Ÿ The program must handle all potential error conditions
The exit program must use this status associated with its own operations (be fault tolerant).
value instead of a status value of 0
Ÿ The program must avoid infinite looping conditions.

3-84 AS/400 System API Reference V4R4

 Save to Application Exit Program

Number of path names.

Save Storage Free Exit Program The total number of path names that
Qp0lSaveStgFree() found for the object
identified by the caller of
Required Parameter Group: Qp0lSaveStgFree().
Reserved. A reserved field. This field must be set to
1 Path name pointers Input CHAR(*) binary zero.
2 Return code pointer Output BINARY(4)
3 Return value pointer Output BINARY(4) Return code pointer
4 Function control block Input CHAR(*) OUTPUT; BINARY(4)
pointer
A pointer to an indicator that is returned to indicate
whether the exit program was successful or whether it
failed. Valid values follow:
The Save Storage Free exit program is a user-specified
program that is called by Qp0lSaveStgFree() to save an 0 The Save Storage Free exit program was suc-
AS/400 object of type *STMF. This exit program can be cessful.
either a procedure or program. −1 The Save Storage Free exit program was not suc-
cessful. The Return value pointer is set to indicate
When the Save Storage Free exit program is given control, it the error.
should save the object so it can be dynamically retrieved at a
later time. The *STMF object is locked when the exit Return value pointer
program is called to prevent changes to it until the storage OUTPUT; BINARY(4)
free operation is complete. If the Save Storage Free exit A pointer to a valid errno that is returned from the exit
program ends unsuccessfully, it must return a valid errno in program to identify the reason it was not successful.
the storage pointed to by the return value pointer.
Qp0lSaveStgFree() then passes this errno to its caller with a Function control block pointer
minus one return code. INPUT; CHAR(*)
A pointer to the data that is passed to
Storage referred to by the path name pointers or the return
Qp0lSaveStgFree() on its call. Qp0lSaveStgFree()
code pointer when the Save Storage Free exit program is
does not process the data that is referred to by this
called are destroyed or reused when Qp0lSaveStgFree()
pointer, but passes this pointer as a parameter when it
regains control.
calls the exit program.

Required Parameter Group

Path names pointers
Save to Application Exit Program
INPUT; CHAR(*)
All of the path names to the *STMF object being storage Required Parameter Group
freed. There is one path name for each link to the
object. These path names are in the Qlg_Path_Name_T 1 Operation type Input Binary(4)
format and are in the UCS-2 CCSID. For information 2 Operation status Output Binary(4)
about UCS-2, see the International Application Develop- 3 Save data Input Char(*)
ment book. 4 Length of save data Input Binary(4)
5 Save bytes read Output Binary(4)
6 Qualified user space Input Char(20)
Figure 3-3. Path Name Pointers name
Offset 7 User space format Input Char(8)
name
Dec Hex Type Field
0 0 BINARY(4) Number of path names
4 4 CHAR(12) Reserved The Save to Application exit program enables an application
program to receive the save records that are generated by a
16 10 ARRAY(*) Array of path name pointers
save-to-save-file operation using the “Save to Application
(QaneSava) API” on page 3-80.
Array of path name pointers.
Pointers to each path name that The API calls the exit program once to start the transfer
Qp0lSaveStgFree() found for the object sequence, multiple times to transfer each block of save
identified by the path name on the call to records, and once to end the transfer sequence.
Qp0lSaveStgFree(). Each path name is
in the Qlg_Path_Name_T format.

Chapter 3. Backup and Recovery APIs 3-85

Save to Application Exit Program

The API passes to the exit program the operation type, the Operation type 4 (abnormal end) is issued only once fol-
save data, the length of the save data, the qualified name of lowing operation types 1 (start) or 2 (transfer), under
the user space and the format name of the user space. abnormal conditions to prematurely end save records
transfer. These conditions are:
The exit program must return the number of save bytes read,
and status on the success or failure of the requested opera- Ÿ The API detects an error with the system save oper-
tion. ation.
Ÿ The exit program returns an operation status of 1
At any time following the initial call, the API could call the exit
(error).
program that requires an abnormal end to the transfer
sequence. Operation status
OUTPUT; BINARY(4)
Restrictions The ending status of the requested operation.

The exit program must read and store the save records in 0 Good
the order presented, without modification, for the objects to The exit program must return this status
be successfully restored. value to indicate successful completion of
the operation.
1 Error
Authorities and Locks
The exit program must return this status
See “Save to Application (QaneSava) API” on page 3-80. value to indicate unsuccessful completion
of the operation.
Required Parameter Group Save data
INPUT; CHAR(*)
Operation type
INPUT; BINARY(4) A block of save records. This parameter is passed only
on operation type 2 (transfer).
The type of operation that the exit program is required to
run. Length of save data
INPUT; BINARY(4)
1 Start
For operation types 1 (start), 3 (end), and 4 (abnormal
The exit program must use this operation
end), this value is zero.
type to prepare for the save records
transfer. For operation type 2 (transfer), this is the length of the
2 Transfer block of save records. The value for this parameter is
currently 262 208 bytes for all but the last operation,
The exit program must use this operation
which may be less.
type to transfer (copy, store, and so forth)
a block of save records. Save bytes read
3 End OUTPUT; BINARY(4)
The exit program must use this operation For operation types 1 (start), 3 (end), and 4 (abnormal
type to end the save records transfer. end), this value must be set to zero.
4 Abnormal end
For operation type 2 (transfer), the exit program must
The exit program must use this operation return a value that indicates the number of save record
type to prematurely end the save records bytes successfully read. The API abnormally ends the
transfer. transfer sequence if the returned value does not equal
the length of save data.
Normal-operation-type order is 1 (start), 2 (transfer), 2
(transfer), ..., 2 (transfer), 3 (end). Qualified user space name
Operation type 1 (start) is issued only once at the begin- INPUT; CHAR(20)
ning of the save operation before any save records are The qualified user space name specified by the applica-
transferred. tion on the call to the Save to Application (QaneSava)
Operation type 2 (transfer) is issued multiple times API. The first 10 characters contain the user space
during the save operation as each block of save records name. The second 10 characters contain the name of
becomes available. The exit program must read the the library where the user space is located.
entire block of save records. User space format name
Operation type 3 (end) is issued only once at the end of INPUT; CHAR(8)
the save operation after all save records are transferred. The user space format name that is specified by the

3-86 AS/400 System API Reference V4R4

 Storage Extension Exit Program

application on the call to the Save to Application API. Storage extension refers to those objects (and the CL com-
For the format of the structure, see “SVRS0100 Format” mands that refer to those objects) saved from disk using the
on page 3-81. The exit program uses the length of *FREE option on the storage parameter. These saved
application data field to determine if the structure con- objects free disk space by storing a copy of the entire object
tains application data, and the offset to application data and keeping only the object headers on disk. Currently, only
field to locate this information. file, document, and stream objects are supported.

Exit Point Format EX400200: Objects may be sched-

Coding Guidelines uled to be saved from disk when they are not referred to for
a specified amount of time. When the objects are saved, the
Applications should consider the following when coding the
object data is saved and the object headers remain on disk.
exit program:
When this object is referred to, the operating system calls the
Ÿ The program should only return an exception for the exit program for object restoration through the registration
requested operation if there has been a failure in the facility. (For information about registering an exit point with
operation. If the program signals an escape message to the registration facility and adding an exit program to an exit
the API, the system assumes there is a failure. A diag- point, see Chapter 66, “Registration Facility APIs.” The exit
nostic message is returned to the calling program. point format EX400200 only supports one exit program.)
Ÿ The program must clean up any locks that it acquires.
When the user exit program is given control, it verifies that
Ÿ The program must handle all potential error conditions the object was saved. If the exit program has the object
associated with its own operations (be fault tolerant). saved and wants to restore it, the exit program restores the
Ÿ The program must prevent infinite looping conditions. object data and returns a control value to the OS/400 oper-
ating system indicating that the object was restored through
the control value information. If the exit program does not
have the object saved, it returns a control value to OS/400
Storage Extension Exit Program indicating that the object was not restored through the control
value information.

Required Parameter Group: Exit Point Format EX400300: When an object is deter-
mined to be saved using *FREE, each program that is regis-
1 Object description informa- Input Char(*)
tion tered against exit point format name EX400300 will be called
2 Control value information Output Char(*) (as long as no programs are registered against EX400200)
with an indicator that it is asking for a date/time stamp of the
QSYSINC Member Name: ETASTGEX most recent version of the object that the exit program has.
Exit Point Name: QIBM_QTA_STOR_EX400
Exit Point Format Name: EX400200, EX400300 After all programs are called, the exit program that specified
the most recent date/time stamp will be called again with the
indicator to restore the object.
The Storage Extension exit program provides the capability
of restoring the entire object using a storage extension, that After the user exit program is given control and restores the
is, restoring objects that were saved using *FREE, or freed object that was suspended, it should return the control value
through an application programming interface. (*DOC and to the OS/400 operating system indicating that the object
*STMF files are freed through an API, not through save using was restored through the control value information.
*FREE.)
Note: To use this exit program, you need the Media and Required Parameter Group
Storage Extension feature of the OS/400.
Object description information
If there is any program registered against exit point format INPUT; CHAR(*)
name EX400200 of this exit point, then any programs regis- Information about the object that the exit program will
tered against exit point format name EX400300 will not be attempt to restore from storage extension. For details,
called. Therefore, if you are installing your application and see “Format of Object Description Information
you are registering it against exit point format EX400300, (EX400200,EX400300)” on page 3-88.
verify that no programs are registered against exit point
format name EX400200. If there are any, notify the user that Control value information
it needs to be disabled before the application will work. Do OUTPUT; CHAR(*)
not simply deregister programs from exit point format name Information about whether the exit program restored the
EX400200 when installing your application because it may object requested or did not have the object stored in
impact other applications. storage extension. For details, see “Format of Control
Value Information” on page 3-89.

Chapter 3. Backup and Recovery APIs 3-87

Storage Extension Exit Program

Format of Object Description Information Length of control value information. The length, in bytes,
of the control value information.
(EX400200,EX400300)
Length of the path name structure. The length, in bytes,
The following table shows the format of the object description
of the path name structure. This field will be set to zero if
information. For a description of the fields in this format, see
the object does not have a path name structure passed.
“Field Descriptions” on page 3-88.
Length of object description information. The length, in
Offset bytes, of the object description information.
Dec Hex Type Field
Member name. The member within the file that caused the
0 0 BINARY(4) Length of object description
exception.
information
4 4 BINARY(4) Length of control value Object library name. The library name of the object being
information referred to. The special value is:
8 8 CHAR(10) Object name *PATH The path name structure will contain the
18 12 CHAR(10) Object library name object information.
28 1C CHAR(10) Object type
Object name. The name of the object that is being referred
38 26 CHAR(10) Member name to and that causes an exception. The user exit program
48 30 CHAR(10) Job name checks if it has this object saved to storage extension. The
special value is:
58 3A CHAR(10) User name
68 44 CHAR(6) Job number
*PATH The path name structure will contain the
object information.
74 4A CHAR(2) Reserved
76 4C BINARY(4) Offset to path name struc- Object type. The standard object types known to the
ture system. Currently, only the following object types are sup-
ported:
80 50 BINARY(4) Length of path name struc-
ture *FILE File object (object name and library fields will
84 54 CHAR(10) Request type contain object name information).
*DOC Document object (path name structure will
94 5E CHAR(13) Date/time stamp
contain object name information).
CHAR(*) Path name structure *STMF Stream file object (path name structure will
contain object name information).

Field Descriptions Offset to path name structure. The offset, in bytes, to the
path name structure that is passed containing object
Date/time stamp. The most recent date/time stamp that the pathname and translation information. This field will be set
other exit programs have specified as their most recent copy to zero if the object does not have an path name structure.
of the suspended object. If this is the first exit program being
called, or no other exit program has a copy of the suspended Path name structure. The path name structure and trans-
object to be restored, then this field will be set to blanks. lation information for the suspended object. The path name
This field will be blanks when passed for exit format structure contains information such as CCSID, country, and
EX400200. This field will be of the following language. For more information on this structure, see “Path
CYYMMDDHHMMSS format: Name Format” on page 2-8.

Ÿ C Request type. The type of request to the exit program from

the operating system. This field will always be *RESTORE
Century, where 0 indicates years 19xx and 1 indicates
for exit format EX400200. Possible values are:
years 20xx.
*RESTORE The exit program is getting called to restore
Ÿ YYMMDD
the object.
The date (year, month, day format) *DATETIME The exit program is getting called to return the
Ÿ HHMMSS latest date/time stamp of the most recent save
operation of the suspended object. Note that
The time (hours, minutes, seconds format) OS/400 does not restrict the called exit
program from actually restoring the object
Job name. The job name.
when called for a date/time stamp, but it will
Job number. The job number associated with the job name only be a degradation in performance due to
and user identifier. an extra restore of the object.

3-88 AS/400 System API Reference V4R4

 Tape Management Exit Program

Reserved. An unused field. CPD6704 D

Error detected using program &1 in &2.
User name. The user identifier of the caller. CPD6705 D
Incorrect user exit control value specified.
Format of Control Value Information
The following table shows the format of the control value Tape Management Exit Program
information. For a description of the fields in this format, see
“Control Value Field Descriptions.”
Required Parameter Group:
Offset
1 Exit description information Input Char(*)
Dec Hex Type Field 2 Label information Input Char(*)
0 0 CHAR(1) Object restoration informa- 3 Operational information Input Char(*)
tion 4 Control value information Output Char(*)
1 1 CHAR(13) Date/time stamp
QSYSINC Member Name: ETATAPMG
Exit Point Name: QIBM_QTA_TAPE_TMS
Exit Point Format Name: TMS00200
Control Value Field Descriptions
Threadsafe: No
Date/time stamp. This field should be set by the exit
program when the request type specified in the “Format of
Object Description Information (EX400200,EX400300)” on The Tape Management exit program allows a tape manage-
page 3-88 is *DATETIME. This field is used by the operating ment system to monitor and control the use of volumes and
system to determine which registered exit program will be devices used by the operating system for most tape oper-
called again to restore the object. The field is only used ations. The exit program is given control at certain points
when programs registered under exit point format EX400300 during tape and library processing.
are called. The determination is based on which exit
Note: To use this exit program, you need the Media and
program indicates the most recent copy of the suspended
Storage Extension feature of the OS/400.
object. This field will be of the following
CYYMMDDHHMMSS format: The exit program is not given control when:
C Century, where 0 indicates years 19xx and 1 Ÿ The system is being installed
indicates years 20xx.
YYMMDD The date (year, month, day format) Ÿ The tape job is a dedicated service tools (DST) tape job
HHMMSS The time (hours, minutes, seconds format) Ÿ The job is ending

Object restoration information. Whether or not the object The OS/400 operating system handles the setup, calling, and
was successfully restored or whether the exception should response processing of the user exit program as specified
be resignaled. If this field contains a value that is not valid, through the registration facility. (For information about regis-
the value is ignored and message CPD6705 is issued. The tering an exit point with the registration facility and adding an
default for this field is 0. Valid values are: exit program to an exit point, see Chapter 66, “Registration
0 The object has not been restored or was not Facility APIs.” This exit point only supports one exit
asked to be restored through the request type program.)
field.
Note: This field should always be left by the Required Parameter Group
exit program as 0 when the request type
Exit description information
specified in the “Format of Object Description
INPUT; CHAR(*)
Information (EX400200,EX400300)” on
page 3-88 is *DATETIME. A description of the exit point. For a description of the
1 The object has been restored. format, see “Format of Exit Description Information” on
page 3-90.
Note: If the user exit program specifies a 1
for this field and it did not attempt to (or suc- Label information
cessfully) restore the entire object, message INPUT; CHAR(*)
CPD6704 is signaled.
The current volume label and the last header label or
trailer label that was written or read. For a description of
Error Messages the format, see “Format of Label Information” on
page 3-91.

Chapter 3. Backup and Recovery APIs 3-89

Tape Management Exit Program

Operational information 4 Mismatch

INPUT; CHAR(*)
This exit type occurs whenever a mismatch is
Information about the tape operation at the time the exit found between a cartridge identifier and the
program is called. For a description of the format, see volume identifier on the tape cartridge.
“Format of Operational Information” on page 3-92. 5 Mount failure

Control value information This exit type occurs when a cartridge failed
OUTPUT; CHAR(*) to be mounted. It gives the tape management
program an opportunity to choose a different
Information to control the tape operation being per-
cartridge.
formed. This format is set by OS/400 and may be
6 Unload exit
changed by the exit programs to control tape processing.
For a description of the format, see “Format of Control This exit type occurs after taking the option
Value Information” on page 3-96. reject and unload. It gives the tape manage-
ment program an opportunity to choose the
next cartridge to be mounted.
Format of Exit Description Information 7 Mount category exit
The following table shows the format of the exit description This exit type occurs before a category is
information. For a description of each field, see “Field mounted through the use of the Set Tape Cat-
Descriptions.” egory (SETTAPCGY) command with
*MOUNTED specified for the option param-
Offset eter. This exit type allows the tape manage-
ment program the opportunity to reject the
Dec Hex Type Field
SETTAPCGY command.
0 0 BINARY(4) Length of exit description 8 Demount category exit
information
This exit type occurs before a category is
4 4 CHAR(1) Tape position exit type demounted through the use of the Set Tape
5 4 CHAR(1) Tape library device exit type Category (SETTAPCGY) command with
*DEMOUNTED specified for the option param-
eter. This exit type allows the tape manage-
Field Descriptions ment program the opportunity to reject the
SETTAPCGY command.
Length of exit description information. The length, in 9 Inventory success exit
bytes, of the exit description information.
This exit type occurs after a successful inven-
Tape library device exit type. An identifier that indicates to tory has been received from the tape library
the exit program the type of library processing occurring in device.
the tape library device. The values are:
Tape position exit type. An identifier that indicates to the
0 Ignore exit program a reference to or the position of the tape. The
Use the value specified in the tape position values are:
exit type field. 0 Ignore
1 Addition
Use the value specified in the tape library
This exit type occurs immediately after the device exit type field.
cartridge identifier is added to a tape library 1 Start of file (SOF)
device using the Add Tape Cartridge
This exit type occurs late in the open tape file
(ADDTAPCTG) command.
processing but before any steps related to
2 Removal
mounting the first tape volume. This exit type
This exit type occurs immediately before the provides information concerning the open pro-
cartridge identifier is removed from a tape cessing and allows the exit program to select
library device using the Remove Tape Car- the first tape volume that will be read from or
tridge (RMVTAPCTG) command. written to.
3 Category 2 Start of volume (SOV)
This exit type occurs immediately before the This exit type occurs immediately after the
cartridge identifier has its category changed volume label is read unless an initialize opera-
from one category to another using the tion is being done. The purpose is to enable
Change Tape Cartridge (CHGTAPCTG) acceptance or rejection of a tape volume and
command. to allow the exit program to record the volume
actually used. This exit type occurs once for

3-90 AS/400 System API Reference V4R4

 Tape Management Exit Program

each volume processed. When an initialize agement systems the ability to choose values
operation is being done, this exit type occurs that need to be known before any operation is
before the volume label is written. The performed on the tape device. It is only
current volume identifier (if known) is the enabled as an exit type when options can be
volume identifier before the initialize operation changed.
and the next volume identifier is the new
volume identifier.
3 Start of file section (SOS)
Examples of Exit Calls
This exit type occurs immediately after the This example shows the sequence and the tape position exit
HDR2 file header label is read on input or types that result from saving a library object (SAVLIB
immediately before the HDR2 label is written command) to one tape:
on output. Its purpose is to enable acceptance Ÿ Command (CMD)
or rejection of a tape that was previously
accepted at start-of-volume exit type. This Ÿ Start of file (SOF)
exit type occurs once for each file processed. Ÿ Start of volume (SOV)
4 End of file section (EOS)
Ÿ Start of file section (SOS)
This exit type occurs immediately after the
After this exit type, the data file is written.
EOV2 end-of-volume label is read on input or
immediately after the EOV2 label is written on Ÿ End of file (EOF)
output. This exit type allows the exit program Ÿ End position
to select the next tape volume to be read from
or written to. This exit type occurs once for This example shows the sequence and the tape position exit
each volume processed except for the last types that result from saving one library object to two tapes:
volume. (This exit type does not occur for
Ÿ Start of command (CMD)
single volume processes.)
5 End of file (EOF) Ÿ Start of file (SOF)
This exit type occurs immediately after the Ÿ Start of volume (SOV)
EOF2 end-of-file label has been read on input Ÿ Start of file section (SOS)
or immediately after the EOF2 label is written
on output. Its purpose is to inform the exit After this exit type, the first part of the data file is written.
program that tape processing is complete. Ÿ End of file section (EOS)
6 Message
After this exit type, a new tape volume is requested.
This exit type occurs immediately before a
Ÿ Start of volume (SOV)
message is sent by the tape manager. The
exit type informs the exit program that a Ÿ Start of file section (SOS)
message will be sent. If the message is an After this exit type, the next part of the data file is written
inquiry message, the valid responses to the second tape.
accepted by the message handler may be the
same as those that the OS/400 program Ÿ End of file (EOF)
accepts from the tape management system. Ÿ End position
7 End position
This exit type occurs immediately before an Format of Label Information
end positioning occurs. End positioning refers
to whether the tape is rewound, unloaded, or The following table shows the format of the label information.
left in leave processing. (Leave processing For a description of each field, see “Field Descriptions” on
refers to the use of ENDOPT(*LEAVE) on a page 3-92.
tape command.) The exit type is driven by
the End Option (ENDOPT) parameter on all Offset
tape commands. These values could be
Dec Hex Type Field
ENDOPT(*LEAVE), ENDOPT(*REWIND), or
ENDOPT(*UNLOAD). User-specified values 0 0 BINARY(4) Length of label information
cannot be overridden in error scenarios 4 4 CHAR(80) Current volume label
because tape volumes are always rewound in
84 54 CHAR(80) Last processed HDR1 or
error situations. TRL1 label
8 Command exit
164 A4 CHAR(80) Last processed HDR2 or
This exit type occurs before the start-of-file TRL2 label
exit type and is designed to allow tape man-

Chapter 3. Backup and Recovery APIs 3-91

Tape Management Exit Program

Field Descriptions Offset

Dec Hex Type Field
Current volume label. The volume label currently being
processed. If the tape position exit type is SOF or if the tape 162 A2 CHAR(1) Mismatch status
library device exit type is addition, removal, category, or mis- 163 A3 CHAR(10) Library device name
match, this field contains blanks. This field also contains
173 AD CHAR(1) Library device status
blanks if a nonlabeled tape is being processed.
174 AE CHAR(1) Library device mode
Last processed HDR1 or TRL1 label. The HDR1 file 175 AF CHAR(1) System restricted state
header label or TRL1 trailer label that was last encountered. status
If the tape position exit type is SOF or SOV or if the tape
176 B0 CHAR(1) Tape volume write pro-
library device exit type is addition, removal, category, or mis-
tection status
match, this field contains blanks. This field also contains
blanks if a nonlabeled tape is being processed. 177 B1 CHAR(7) Message identifier
184 B8 CHAR(10) Message type
Last processed HDR2 or TRL2 label. The HDR2 file
194 C2 CHAR(10) Message queue or program
header label or TRL2 trailer label that was last encountered.
name
If the tape position exit type is SOF or SOV or if the tape
library device exit type is addition, removal, category, or mis- 204 CC CHAR(10) Message queue or program
match, this field contains blanks. This field also contains library name
blanks if a nonlabeled tape is being processed. 214 D6 CHAR(4) Message destination
218 DA CHAR(1) Volume list status
Length of label information. The length, in bytes, of the
label information. 219 DB BINARY(4) Offset of replacement text
223 DF BINARY(4) Length of replacement text

Format of Operational Information 227 E3 CHAR(1) Generated cartridge ID

status

Offset 228 E4 CHAR(1) Sequence number change

allowed
Dec Hex Type Field
229 E5 CHAR(1) End position
0 0 BINARY(4) Length of operation informa-
tion 230 E6 CHAR(10) File sequence number

4 4 BINARY(4) Length of control value 240 F0 CHAR(10) Aggregate volume

information sequence number

8 8 CHAR(1) Tape operation 250 FA CHAR(10) Media library tape resource

name
9 9 CHAR(17) Data file label
260 104 CHAR(4) Media library tape resource
26 1A CHAR(10) Tape device file name type
36 24 CHAR(10) Tape device file library 264 108 CHAR(4) Media library tape resource
name model
46 2E CHAR(10) Current device name 268 10C CHAR(1) Generated cartridge identi-
56 38 CHAR(6) Current volume identifier fier
62 3E CHAR(10) Next device name 269 10D CHAR(10) Session identifier
72 48 CHAR(6) Next volume identifier 279 117 CHAR(150) Cartridge densities
78 4E CHAR(4) Current device type 429 1AD CHAR(26) Qualified job name
82 52 CHAR(10) Current tape density 455 1C7 CHAR(4) Reserved
92 5C CHAR(1) Data check on write 459 1CB CHAR(1) Type of close operation
93 5D CHAR(10) Next tape density 460 1CC CHAR(10) Command name
103 67 CHAR(1) Tape device ready status 470 1D6 CHAR(1) Message recoverable flag
104 68 CHAR(1) Tape volume initialize status 471 1D7 CHAR(1) Output extend processing
105 69 CHAR(1) Initialize new volume label * * CHAR(*) Message replacement text
(The offset to this field is
106 6A CHAR(32) Logical block identifier
stored in the Offset of
138 8A CHAR(6) Cartridge identifier replacement text field)
144 90 CHAR(10) Category name
154 9A CHAR(8) Category system name

3-92 AS/400 System API Reference V4R4

 Tape Management Exit Program

Field Descriptions Data check on write. Whether a permanent write data

check occurred. Valid values are:
Aggregate volume sequence number. The aggregate 0 A permanent write data check has not
volume sequence number from the label information. The occurred.
numeric value is right-justified with leading zeros or blanks. 1 A permanent write data check occurred and
end-of-volume labels are being written before
Cartridge densities. The densities that are supported by
the end of tape.
the cartridge. Up to 15 densities or formats are supported by
the cartridge. Each density or format is 10 characters in Data file label. The tape data file being processed. This
length. For example, if only one density exists, the first 10 field is blank if the tape library device exit type field is addi-
bytes of this field are the character representation of the tion, removal, or category.
density or format and the last 140 bytes are blanks. This field
is set at the start-of-volume exit type and is blank at all other End position. The type of end position that is occurring for
exit types. This field is blank for devices or cartridges that do this close operation. This exit type is designed for applica-
not support special cartridge-checking capabilities. tions that track the end positioning of cartridges. It becomes
important for media library devices where *LEAVE ties up a
Cartridge identifier. The cartridge identifier of the tape car- device for that cartridge being left in leave processing. This
tridge. If the tape library device has a scanner, the cartridge field is blank at all exit points other than the end position exit
identifier is the external bar-code identifier. If the tape library type. Valid values follow:
device does not have a scanner, the cartridge identifier is the
logical volume identifier. This field is blank if the device is 0 *REWIND
not in a tape library device or when the tape position exit 1 *UNLOAD
type field is SOF. 2 *LEAVE

Category name. The category name that the cartridge iden- File sequence number. The file sequence number from the
tifier is being changed to. This field is blank if the tape label information.
library device exit type field is not addition or category.
Generated cartridge identifier. Whether the cartridge iden-
Category system name. The category system name that is tifier is generated. Generated identifiers include BLKxxx
the primary owner of the category name. This field is blank (where xxx are the characters 0-9) for blank or new tapes,
when the category is *INSERT, *EJECT, or *SHARE400. IMPxxx for tapes in the convenience (import) station, NLTxxx
for nonstandard labeled tapes, CLNxxx for cleaning tapes,
Command name. The name of the command being run. If and ERRxxx for tape cartridges in error. This field is blank
this field is blanks, then the command does not support when no cartridge identifier is passed in the operational infor-
passing the command name to the Media and Storage mation format in the cartridge identifier field. Valid values
Extension structures at this exit point. Check Tape follow:
(CHKTAP), Duplicate Tape (DUPTAP), and Initialize Tape 0 The cartridge identifier is not generated.
(INZTAP) commands pass the command name for all exit 1 The cartridge identifier is generated.
types.
Generated cartridge ID status. Whether the media library
Current device name. The name of the tape device being device has a bar-code reader. If the media library device
used at the time the exit point is reached. This field is blank does not have a bar-code reader, then the field indicates if
if the tape library device exit type field is addition, removal, or the cartridge identifiers are generated by the system or if the
category. logical volume identifiers are used as the cartridge identifiers.
This field is blank at all exit types except inventory success
Current device type. The device type of the current tape
exit. Valid values follow:
device. This field is blank if the tape library device exit type
field is addition, removal, or category. 0 The media library device has a bar-code
reader.
Current tape density. The density of the tape reel or car- 1 The media library device does not have a bar-
tridge on the current tape device. This field is blank if the code reader, and the logical volume identifiers
tape library device exit type field is addition, removal, or cate- will be used as the cartridge identifiers (that is,
gory. the device description has *VOLID specified
for the GENCTGID parameter).
Current volume identifier. The name of the expected 2 The media library device does not have a bar-
volume to be used during the tape operation, not necessarily code reader, and the system will generate the
the loaded volume. OS/400 issues an inquiry message when cartridge identifiers (that is, the device
the expected volume is different from the loaded volume. description has *SYSGEN for the GENCTGID
This field is blank if the tape library device exit type field is parameter).
addition, removal, or category.

Chapter 3. Backup and Recovery APIs 3-93

Tape Management Exit Program

Initialize new volume label. Whether a new volume label Message queue or program name. The name of the
initializes immediately. This field is blank if the tape position message queue or program to which the message will be
exit type field is not SOV. Valid values are: sent.
0 An SOV tape position exit type after the
Message queue or program library name. The name of
volume label on tape is read
the library in which the message queue or program will
1 An SOV tape position exit type before the new
reside.
volume label is written
Message recoverable flag. Indicates if the message is
Length of control value information. The length, bytes, of
recoverable. This field is valid only for the message exit. It
the control value information.
is blank for all other exit types. Valid values are as follows:
Length of operational information. The length, in bytes, of 0 The message is not recoverable.
the operational information. 1 The message is recoverable.

Length of replacement text. The length, in bytes, of the Message replacement text. The replacement text for the
replacement text for the message exit type. message identifier on the message exit type. The offset to
this field and the length of this field are also contained in the
Library device mode. Whether the library device is in operational information format.
library mode. Valid values are as follows:
Message type. The type of message that will be signalled.
0 The library device is not in library mode.
Valid values are as follows:
1 The library device is in library mode.
ESCP Escape message
Library device name. The name of the tape library device INQ Inquiry message
being used at the time the exit point is reached. This field is
blank if a tape library device is not being used. Mismatch status. Whether a mismatch occurred when
using the Add Tape Cartridge (ADDTAPCTG) command.
Library device status. Whether the device is in a library This field is blank if the tape library device exit type is not
device. Valid values are as follows: mismatch or if the device is not in a tape library device.
0 The tape device is not in a library device. Valid values are:
1 The tape device is in a library device. 0 A mismatch did not occur when using the
command.
Logical block identifier. The current tape position. This
1 A mismatch occurred when using the
refers to the logical position of the data buffer rather than the
command.
physical position of the media. This field is passed as part of
the SOS tape position exit type for tapes that support posi- Next device name. The next device name in the list of
tioning by logical block identifier on standard labeled (*SL) devices. If only one device has been specified, the current
tapes opened for output. This field is zero at all other exit and next device names are the same. This field is blank if
types. the tape library device exit type is addition, removal, or cate-
gory.
Media library tape resource name. For a media library
device, the resource name of the tape device being used. If Next tape density. The new density when a reel or car-
no device is allocated to the process for use, the field is tridge is initialized. This field is blank if the tape library
blank. device exit type is addition, removal, or category.

Media library tape resource model. The model number of Next volume identifier. The next volume label in the list of
the tape resource name. labels. Blanks indicate that the volume identifier list is used
up. This field is blank if the tape library device exit type is
Media library tape resource type. The type number of the
addition, removal, or category.
tape resource name.
Offset of replacement text. The offset, in bytes, of the
Message destination. The destination of the message to be
replacement text for the message exit type.
signalled by the operating system in relation to the program
name specified in the message queue or program name Output extend processing. Indicates when a tape file is
field. Valid values are as follows: opened for output with extend processing. This flag will only
PREV The message is sent to the program previous be set when a tape file is opened for output. Valid values
to the one specified. are:
SAME The message is sent to the program specified. blank The file is opened for input.
0 The file is opened for output.
Message identifier. The identifier of the message that is
1 The file is opened for output with extend pro-
signalled.
cessing.

3-94 AS/400 System API Reference V4R4

 Tape Management Exit Program

Qualified job name. The qualified job name that forced the Tape device file library name. The name of the library that
tape function and exit types. contains the tape device file. This field is blank if the tape
library device exit type is addition, removal, or category.
Reserved. An ignored field.
Tape device file name. The name of the tape device file for
Session identifier. An identifier to the tape management this tape device. This field is blank if the tape library device
system of the session identifier that is associated with this exit type is addition, removal, or category.
request. Each session in a media library device has its own
unique session identifier. An exception is a mounted category Tape device ready status. Whether the tape device is
request, which has a session identifier assigned from the ready. Valid values are:
SETTAPCGY OPTION(*MOUNTED) to SETTAPCGY
0 The tape device is not ready
OPTION(*DEMOUNTED); this session identifier is used for
1 The tape device is ready
each command that specifies VOL(*MOUNTED) while a cate-
gory is mounted. This field is set to blanks for stand alone Tape operation. An indicator of how the tape file was
devices. opened. Valid values are:

| Sequence number change allowed. Whether the tape 0 The tape file is open for input.
| management system is allowed to change the user-specified 1 The tape file is open for output.
| sequence number. Valid values follow: 2 No tape file is open.

blank No change to the user-specified sequence Tape volume initialize status. The identifier that deter-
number value is allowed. mines the type of checking for active files during the initialize
0 No change to the user-specified sequence operation. This field is blank when it is not an initialize oper-
number value is allowed because of the tape ation. Valid values are:
positioning or tape file status (that is, end of
volume).
0 Initialize operation and check for active file is
*NO.
1 A change to the user-specified sequence
number is allowed. Valid sequence numbers
1 Initialize operation and check for active files is
*YES.
include 1, *END, or one greater than the last
| sequence number on the tape. This value is
2 Initialize operation and check for active files is
*FIRST.
| valid only for output operations.
2 A change to the user-specified sequence
Tape volume write protection status. Whether the tape
number is allowed.
volume in use is write-protected. Valid values are as follows:
| For output operations, the valid new sequence
0 The tape volume is not write-protected.
| number values include 1, any existing
1 The tape volume is write-protected.
| sequence number, *END, or one greater than
| the last sequence number on the tape. Type of close operation. The type of close operation. If the
| For input operations, the valid new sequence exit type is not an end-of-file exit type, the field is blank.
| number values include any existing sequence Valid values follow:
| number. blank Not an end-of-file exit type
1 Temporary close (save or restore operation
| When a change is allowed, the user-specified sequence
closes between files)
| number is placed in both the sequence number and large
2 Permanent close (operation has completed)
| sequence number fields of the control value information.
3 Normal termination (operation is being ended
| Either the sequence number or large sequence number fields
normally)
| of the control value information may be changed to a new
4 Abnormal termination (operation is being
| value by the tape management system.
ended abnormally)
| Note: For user-specified sequence numbers greater than
| 999 999, the value will appear only in the large sequence Volume list status. Whether *MOUNTED is specified for
| number field. the volume (VOL) parameter. This field is set at SOF and
SOV. This field allows tape management to control the mon-
| Note: The tape management system is not allowed to itoring of the Set Tape Category (SETTAPCGY) command
| change the user-specified sequence number for input oper- for occurrences of *MOUNTED specified for the VOL param-
| ations for the CHKTAP, DMPTAP, DSPTAP, and DUPTAP eter. This field is blank if the tape processing exit type is not
| commands. start of file (SOF) and not start of volume (SOV). Valid
values are as follows:
System restricted state status. Whether the system is in
restricted state. Valid values are as follows: 0 VOL(*MOUNTED) is not specified.
0 The system is not in a restricted state.
1 VOL(*MOUNTED) is specified.
1 The system is in a restricted state.

Chapter 3. Backup and Recovery APIs 3-95

Tape Management Exit Program

Format of Control Value Information to no longer be recognized by the device. This field can only
be changed at the start-of-file exit type. At all other exit
types, the default value is blank. Valid values follow:
Offset
0 Disallow system cartridge searching
Dec Hex Type Field
1 Allow system cartridge searching
0 0 CHAR(1) Volume acceptance
1 1 CHAR(6) Volume to be used Allow category change. Whether to allow a change of cat-
egory for the cartridge identifier. You can change this value
7 7 CHAR(6) File expiration date
when the tape library device exit type field is category. The
13 D CHAR(1) Character code conversion default is 1 when the tape library device exit type is category.
14 E CHAR(1) Allow ignore response Valid values are:
15 F CHAR(1) Issue active file messages 0 The category for the cartridge identifier cannot
be changed.
16 10 CHAR(1) Issue mount next tape
message 1 The category for the cartridge identifier can be
changed.
17 11 CHAR(32) Logical block identifier
49 31 CHAR(1) Allow category change Allow demount category. Whether to allow a demount cat-
egory. You can change this value when the tape library
50 32 CHAR(1) Allow removal
device exit type field is demount category. The default is 1
51 33 CHAR(1) Mismatch acceptance when the tape library device exit type is demount category.
52 34 CHAR(1) Automatic ADDTAPCTG Valid values are as follows:
53 35 CHAR(1) Message response 0 Disallow the demount category operation.
54 36 CHAR(1) Allow mount category 1 Allow the demount category operation.
55 37 CHAR(1) Allow demount category Allow ignore response. Whether to allow an ignore
56 38 CHAR(6) Sequence number response to a mount message. If the field contains a value
62 3E CHAR(10) Category name
that is not valid, it is ignored and message CPF4067 is
issued. You can change the value when the tape position
72 48 CHAR(8) Category system name exit type field is SOV. The default is 0 when the tape posi-
80 50 CHAR(10) Large sequence number tion exit type is SOV. Valid values are:
90 5A CHAR(1) Allow logical block identifier 0 An ignore response is allowed from the mount
support next tape messages. The ignore response is
91 5B CHAR(1) Allow cartridge search permitted as normal on the mount next tape
92 5C CHAR(1) End position
messages.
1 An ignore response is not allowed from the
93 5D CHAR(10) Density or format mount next tape messages.
103 67 CHAR(1) Use optimum block size
Allow logical block identifier support. Whether to allow
logical block identifier support for this device. If a tape man-
Field Descriptions agement system responds at the start-of-file exit type, this
value allows devices that do not support logical block identi-
All of these control values have a default at the exit types in fiers to work with OS/400 code. Devices that are emulating
which the exit program can change them. At exit types that OS/400 supported devices may not support logical block
values cannot be changed, the values are set to blanks. identifiers but still report because of emulation that the device
does support it. Valid values follow:
Allow cartridge search. Whether to allow cartridge
searching for non-bar-code media library devices when the 0 Disallow logical block identifier support.
cartridge that is specified in the VOL parameter of a 1 Allow logical block identifier support.
command is not found. If the system is allowed to use car-
Allow mount category. Whether to allow a mount category.
tridge searching, the system loads tapes and searches for a
You can change this value when the tape library device exit
logical volume identifier to match the requested volume. The
type field is mount category. The default is 1 when the tape
cartridges that the system loads and searches are the car-
library device exit type is mount category. Valid values are
tridges with generated identifiers and unknown logical volume
as follows:
identifiers. Cartridges with generated identifiers such as
NLTxxx (nonlabeled), BLKxxx (blank), or ERRxxx (error) are 0 Disallow the mount category operation.
not used in cartridge searching by the system. 1 Allow the mount category operation.

If cartridge searching is allowed, the system may load and Allow removal. Whether to allow the removal of the car-
unload the convenience station tape, which causes the tape tridge identifier. You can change the value when the tape

3-96 AS/400 System API Reference V4R4

 Tape Management Exit Program

library device exit type field is removal. The default is 1 Character code conversion. Whether to convert character
when the tape library device exit type is removal. Valid code from ASCII to EBCDIC for data written on the tape. If
values are: the field contains a value that is not valid, it is ignored and
message CPF4067 is issued. You can change this value
0 The cartridge identifier cannot be removed
when the tape position exit type field is SOF and the tape
from the tape library device.
operation field is 1. The default is 0 when the tape position
1 The cartridge identifier can be removed from
exit type is SOF and the tape operation field is 1.
the tape library device.
0 Convert ASCII data to EBCDIC data when
Automatic ADDTAPCTG. Whether to allow the tape man- processing the data file
agement system the ability to automatically add the cartridge 1 Retain ASCII data
to a usable category when the exit type field is mount failure
and the cartridge is currently in the *INSERT category. (For Density or format. This field allows the tape management
more information about usable categories, see the Add Tape system to change the density or format of the tape volume.
Cartridge (ADDTAPCTG) command in the CL Reference When the initialize new volume label (operational information
(Abridged) book.) You can change this value when the tape format) is set to 1, which indicates that the new tape volume
library device exit type field is mount failure. The default is 0 is written immediately, the user-specified density at the start-
when the tape library device exit type is mount failure. Valid of-volume exit type is used. The field must be set to one of
values are: the valid cartridge densities that are listed in the operational
information format. The field is blank when it cannot be
0 The cartridge identifier is not added to a
changed.
usable category.
1 The cartridge identifier is added to the
End position. This field allows the tape management
*NOSHARE category, and the tape processing
system to change the end positioning that was specified by
continues.
the user. The value can be changed at the end positioning
2 The cartridge identifier is added to the
exit type. This field is blank when the value cannot be
*SHARE400 category, and the tape pro-
changed. The default for this field is the value specified for
cessing continues.
end positioning in the operational information format and can
3 The cartridge identifier is added to the *IPL
be changed to any of the following:
category, and the tape processing continues.
4 The cartridge identifier is added to the *NL 0 Rewind the tape volume.
category, and the tape processing continues. 1 Unload the tape volume.
5 The cartridge identifier is added to the *CNV 2 Do not position tape (*LEAVE).
category, and the tape processing continues. 3 Unload and eject (remove) the tape volume.
6 The cartridge identifier is added to the cate-
File expiration date. The expiration date of the file being
gory name and to the category system name
written in the header label to control data file expiration.
fields that are specified in the control value
information format.
This field uses the Julian format with a leading century digit.
It is of the form CYYDDD, where C represents the thousands
Category name. If a valid category name and category
and hundreds of the year value (19 is blank, 20 is 0, and 21
system name are specified, the cartridge is changed to that
is 1), YY represents the year (00–99), and DDD represents
category. This automatic Change Tape Cartridge
the day of the year (001–366). For example, 1 February
(CHGTAPCTG) command does not force a change exit type
1972 is represented as ' 72032' and 1 February 2072 is
and can only be specified for media library devices and at
represented as '072032'.
the start-of-volume exit type. If you specify option 6 for the
automatic tape cartridge field at the mount failure exit type,
The value *PERM indicates that the tape file is a permanent
this field is also allowed. The field is set to blanks at all
tape file. This special value must be in uppercase and left-
other exits types. You cannot change to the system-supplied
justified. Blanks indicate that the default expiration date
categories *CNV and *SYSGEN.
should be used.
Category system name. If you specify a valid category
You can change this value at SOF or SOV tape position exit
name and category system name, the cartridge is changed to
type when the tape operation field is 1 and the initialize new
that category. This automatic Change Tape Cartridge
volume label field is 0. (These fields are in the operational
(CHGTAPCTG) command does not force a change exit type
information format.) The default for this field is the file expi-
and can only be specified for media library devices and at
ration date that the user requested.
the start-of-volume exit type. If you specify option 6 for the
automatic tape cartridge field at the mount failure exit type, If the field is changed to contain a date that is not valid, it is
this field is also allowed. The field is set to blanks at all ignored and message CPF4063 is issued.
other exit types. You cannot change to the system-supplied
categories *CNV and *SYSGEN. Issue active file messages. Whether OS/400 should issue
active file messages. If the field contains a value that is not

Chapter 3. Backup and Recovery APIs 3-97

 Tape Management Exit Program

valid, it is ignored and message CPF4067 is issued. You sequence number field, but allows for a greater range of
can change the value when the tape position exit type field is sequence numbers.
SOV. The default is 0 when the tape position exit type is
SOV. Valid values are: Logical block identifier. The tape position to locate. This
field is checked after the SOV tape position exit type is
0 Issue active file messages
reached. If the logical block identifier is changed by the user
1 Do not issue active file messages
at a tape position exit type other than SOV, or is changed to
Issue mount next tape message. Whether OS/400 should an incorrect value, the logical block identifier is referred to as
issue mount next tape messages. If the field contains a an incorrect logical block identifier in message CPD4076.
value that is not valid, it is ignored and message CPF4067 is The logical block identifier is an incorrect value for any of the
issued. You can change this value when the tape position following:
exit type field is EOS. The default is 0 when the tape posi- Ÿ The tape is the wrong format
tion exit type is EOS.
Ÿ The tape is not a standard label (*SL) tape
0 Mount next tape messages are issued.
Ÿ The tape is not opened for input
1 Mount next tape messages are not issued.
Ÿ The tape is opened for bypass label processing (*BLP)
Large sequence number. The sequence number being
Ÿ The tape is opened for a read-backward operation
used. At the start-of-volume exit type, this field contains the
user-specified sequence number. This field is blank for all Ÿ The device does not support positioning by logical block
| other exit types. The field can be changed for both input and identifier
| output operations when the sequence number change Ÿ The identifier is not found on the tape
| allowed field in the operational information indicates that a
| change is allowed. If the value specified is not a valid logical block ID, the value
is ignored and message CPD4076 is issued. If the value is
| For output operations, the following user-specified sequence ignored, the tape positioning is done by sequence numbers.
| numbers may be passed to the tape management system: You can change this value at the SOV tape position exit
type. The default is 0 at the SOV tape position exit type.
| Ÿ blank
| Ÿ *END (left-justified and padded with blanks) Message response. The response to the message exit
type. You can change the value when the tape processing
| Ÿ A numeric value (right-justified with leading zeros or
exit type is message. The default is 0 when the tape pro-
| blanks) from 1 to 16 777 215
cessing exit point is message. If the message response from
| The sequence number may be changed to any of the fol- the user is anything other than 0, a message that states that
| lowing values: the tape management system handled the error is sent to the
| Ÿ blank user. Valid values are as follows:

| Ÿ *END (left-justified and padded with blanks)

0 Ignore the message exit type. The message
is sent when OS/400 regains control of the
| Ÿ A numeric value (right-justified with leading zeros or program from the user exit program.
| blanks) from 1 to 16 777 215 1 Cancel the operation by replying to the
message exit type with a C before the
| For input operations, the following user-specified sequence message is actually sent. This stops the
| numbers may be passed to the tape management system: message from being sent.
| Ÿ blank 2 Ignore the operation by replying to the
message exit type with an I before the
| Ÿ *FIRST (left-justified and padded with blanks)
message is actually sent. This stops the
| Ÿ *NEXT (left-justified and padded with blanks) message from being sent.
| Ÿ A numeric value (right-justified with leading zeros or 3 Retry the operation by replying to the
| blanks) from 1 to 16 777 215 message exit type with an R before the
message is actually sent. This stops the
| The sequence number may be changed to any of the fol- message from being sent.
| lowing values: 4 Initialize the tape volume by replying to the
| Ÿ blank message exit type with an INZ before the
message is actually sent. This stops the
| Ÿ A numeric value (right-justified with leading zeros or
message from being sent.
| blanks) from 1 to 16 777 215
5 Dump the information about the error before
An invalid value or changing the sequence number when it is the message is actually sent. This stops the
not allowed causes message CPF416B to be issued. This message from being sent.
field overrides a value that is specified for the sequence
Mismatch acceptance. The control value that determines
number field. This field has the same function as the
how to handle a cartridge ID mismatch situation. You can

3-98 AS/400 System API Reference V4R4

 Tape Management Exit Program

change the value when the tape library device exit type field field is ignored if a value is specified for the large sequence
is mismatch. The default is 1 when the tape library device number field.
exit type is mismatch. Valid values are:
Use optimum block size. Whether to use the optimum
1 Ignore the mismatch of the cartridge identifier
block size for save commands. If the optimum block size is
and the logical volume identifier.
used on a save command, commands such as Duplicate
2 Initialize the logical volume identifier to match
Tape (DUPTAP) only duplicate the tape volume to devices
the cartridge identifier.
that support the same block size. If the optimum block size
3 Eject the tape cartridge immediately from the
is not used, normal save processing uses the default block
tape library device and place it in the *EJECT
size that can be duplicated to any device type by using the
category. The tape operation ends imme-
DUPTAP command. The field is initialized to the value that
diately.
the user specifies on the save command. The field can be
4 Reject the output operation, leaving the tape
changed at the start-of-command exit type only. At all other
cartridge in the tape library device for input
exit points, the field is set to blanks. Note that if a blank is
operations. The tape operation ends imme-
passed, the value cannot be overridden by the tape manage-
diately.
ment system. For example, on the Save System (SAVSYS)
Sequence number. The sequence number to be used. Use command, the value specified by the user for Use Optimum
the large sequence number field rather than this field if you Block (USEOPTBLK) cannot be changed. Valid values
are adding support for this function to a tape management follow:
system. At the start-of-volume exit type, this field contains 0 Do not use optimum block size
the user-specified sequence number. This field is blank for all 1 Use optimum block size
| other exit types. The field can be changed for both input and blank An override is not allowed for optimum block
| output operations when the sequence number change size
| allowed field in the operational information indicates that a
| change is allowed. Volume acceptance. Whether the exit program accepts the
mounted volume. This field has precedence over all other
| For output operations, the following user-specified sequence fields. You can change this value when the tape position exit
| numbers may be passed to the tape management system: type field is 1 through 6. The default is 1 for tape position
exit types 1 through 5.
| Ÿ blank
| Ÿ *END (left-justified and padded with blanks)
1 Mounted volume is accepted
2 No volume is accepted. The tape operation
| Ÿ A numeric value (right-justified with leading zeros or ends immediately.
| blanks) from 1 to 999 999 3 Reject in favor of another volume
| The sequence number may be changed to any of the fol- 4 Reject and unload in favor of another volume
| lowing values:
An acceptance value of '3' is not allowed when a category is
| Ÿ blank mounted in a tape library device. CPF410B, CPF450B, or
| Ÿ *END (left-justified and padded with blanks) CPF510B will be issued and the tape operation ends imme-
| diately. An acceptance value of '4' is not allowed for a tape
| Ÿ A numeric value (right-justified with leading zeros or | position exit type of SOV when the Initialize new volume
| blanks) from 1 to 999 999 | label field of the Operational Information is set to '1'.
| For input operations, the following user-specified sequence Volume to be used. The volume to be loaded if 3 or 4 is
| numbers may be passed to the tape management system: specified for the volume acceptance field. This field can be
| Ÿ blank set by any exit type to pass a replacement volume identifier.
If the tape position exit type is SOF, SOV, or SOS, this field
| Ÿ *FIRST (left-justified and padded with blanks)
identifies a replacement for the current volume identifier. If
| Ÿ *NEXT (left-justified and padded with blanks) the tape position exit type is EOS or EOF, this field identifies
| Ÿ A numeric value (right-justified with leading zeros or a replacement for the next volume identifier.
| blanks) from 1 to 999 999
The field is ignored during Duplicate Tape (DUPTAP) oper-
| The sequence number may be changed to any of the fol- ations on all tape position exit types except SOF, SOV, and
| lowing values: SOS on the first source and first target volumes.
| Ÿ blank
The field is used as a new volume identifier override during
| Ÿ A numeric value (right-justified with leading zeros or Initialize Tape (INZTAP) operations.
| blanks) from 1 to 999 999
The field must be set to blanks if 4 is specified for the
| An invalid value or changing the sequence number when it is volume acceptance field when a category is mounted in a
| not allowed causes message CPF416B to be issued. This tape library device.

Chapter 3. Backup and Recovery APIs 3-99

Tape Management Exit Program

Error Messages CPF416B E Incorrect user exit control value specified.

CPF4402 D Alternate volume identifier not standard.
CPD4003 D CPF450A E Error detected using program &6 in &7.
Alternate volume identifier not standard. CPF450B E Volume acceptance response not valid.
CPD4076 D CPF450C E
Logical block identifier not correct. End request specified by program &6.
CPF4062 D Alternate volume identifier not standard. CPF510A E Error detected using program &6 in &7.
CPF4063 D Incorrect file expiration date &7 specified. CPF510B E Volume acceptance response not valid.
CPF4067 D Incorrect user exit control value specified. CPF510C E
CPF410A E Error detected using program &6 in &7. End request specified by program &6.
CPF410B E Volume acceptance response not valid. CPF5401 E Interface error on device &4.
CPF410C E
End request specified by program &6.

3-100 AS/400 System API Reference V4R4

 Client Management Support

Part 3. Client Management Support APIs

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

 Copyright IBM Corp. 1998, 1999

Client Management Support

AS/400 System API Reference V4R4

 Client Management Support APIs

| Chapter 4. Client Management Support APIs

| The Client Management Support APIs have moved to the | to the local IBM branch office or IBM representative for
| AS/400 Information Center. To access the Information | postage-paid mailing.
| Center, use the URL furnished below. At the AS/400 Infor-
| mation Entry point, select the Information Center and choose | If you prefer to send comments by FAX, use either of the
| your language. When you reach the Welcome screen for the | following numbers:
| Information Center, select Programming from the navigation | Ÿ United States and Canada: 1-800-937-3430
| bar; under Programming, select OS/400 APIs. The APIs are
| Ÿ Other countries: 1-507-253-5192
| grouped in the Information Center by category.
| If you prefer to send comments electronically, use one of
| Internet access:
| these network IDs:
| http://www.as400.ibm.com/infocenter | Ÿ [email protected]

| Your feedback is important in helping to provide accurate | Ÿ IBMMAIL, to IBMMAIL(USIB56RZ)

| and high-quality information. If you have any comments
| If your comments concern an API in the Information Center,
| about the Client Management Support APIs in particular, the
| be sure to include the name of the API and the category in
| APIs in general, or any other AS/400 documentation, we
| which it is located. If you are commenting about information
| invite you to contact us by mail, fax, or electronically.
| other than the APIs in the Information Center, please include
| If you prefer to send comments by mail, use the readers' | the following:
| comment form in the hardcopy portion of the System API | Ÿ The name of the book.
| Reference book. The address is printed on the back of that
| Ÿ The publication number of the book.
| form. If you are mailing a readers' comment form from a
| country other than the United States, you can give the form | Ÿ The page number or topic to which your comment
| applies.

 Copyright IBM Corp. 1998, 1999 4-1

Client Management Support APIs

4-2 AS/400 System API Reference V4R4

 Cluster

Part 4. Cluster APIs

| Chapter 5. Cluster APIs . . . . . . . . . . . . . . . 5-1 | Error Messages . . . . . . . . . . . . . . . . . . 6-12

| Cluster APIs—Introduction . . . . . . . . . . . . . . . 5-1 | List Cluster Information (QcstListClusterInfo) API . . 6-12
| Terminology for Resilient Resources . . . . . . . . 5-1 | Authorities and Locks . . . . . . . . . . . . . . . 6-12
| Cluster Resource Services Characteristics . . . . . . . 5-1 | Required Parameter Group . . . . . . . . . . . . 6-12
| Cluster Resource Services Job Structure . . . . . . . 5-1 | Format of Generated Lists . . . . . . . . . . . . 6-13
| Cluster Resource Services APIs Behavior . . . . . 5-2 | Input Parameter Section . . . . . . . . . . . . . . 6-13
| Cluster APIs Use of User Queues . . . . . . . . . . . 5-2 | Header Section . . . . . . . . . . . . . . . . . 6-13
| Field Descriptions . . . . . . . . . . . . . . . . . . 5-3 | LCTI0100 Format . . . . . . . . . . . . . . . . . 6-13
| Using Results Information . . . . . . . . . . . . . . . 5-3 | Field Descriptions . . . . . . . . . . . . . . . . . 6-13
| General Information Applicable to Cluster APIs . . . 5-3 | Error Messages . . . . . . . . . . . . . . . . . . 6-14
| Remove Cluster Node Entry
| Chapter 6. Cluster Control APIs . . . . . . . . . . . 6-1 | (QcstRemoveClusterNodeEntry) API . . . . . . . . 6-14
| Cluster Control APIs—Introduction . . . . . . . . . . . 6-1 | Authorities and Locks . . . . . . . . . . . . . . . 6-15
| Network Attributes . . . . . . . . . . . . . . . . . . . 6-1 | Required Parameter Group . . . . . . . . . . . . 6-15
| Cluster Node Status . . . . . . . . . . . . . . . . . . 6-1 | RMVN0100 Format . . . . . . . . . . . . . . . . 6-15
| Cluster Control APIs . . . . . . . . . . . . . . . . . . 6-1 | Field Descriptions . . . . . . . . . . . . . . . . . 6-15
| Add Cluster Node Entry (QcstAddClusterNodeEntry) API 6-1 | Usage Notes . . . . . . . . . . . . . . . . . . . . 6-15
| Authorities and Locks . . . . . . . . . . . . . . . . 6-2 | Results Information User Queue . . . . . . . . 6-15
| Required Parameter Group . . . . . . . . . . . . . 6-2 | Error Messages . . . . . . . . . . . . . . . . . . 6-15
| ADDN0100 Format . . . . . . . . . . . . . . . . . 6-3 | Start Cluster Node (QcstStartClusterNode) API . . . 6-16
| Field Descriptions . . . . . . . . . . . . . . . . . . 6-3 | Authorities and Locks . . . . . . . . . . . . . . . 6-16
| Usage Notes . . . . . . . . . . . . . . . . . . . . . 6-3 | Required Parameter Group . . . . . . . . . . . . 6-16
| Results Information User Queue . . . . . . . . . 6-3 | STRN0100 Format . . . . . . . . . . . . . . . . 6-17
| Error Messages . . . . . . . . . . . . . . . . . . . 6-4 | Field Descriptions . . . . . . . . . . . . . . . . . 6-17
| Change Cluster Node Entry | Usage Notes . . . . . . . . . . . . . . . . . . . . 6-17
| (QcstChangeClusterNodeEntry) API . . . . . . . . . 6-4 | Results Information User Queue . . . . . . . . 6-17
| Authorities and Locks . . . . . . . . . . . . . . . . 6-4 | Error Messages . . . . . . . . . . . . . . . . . . 6-17
| Required Parameter Group . . . . . . . . . . . . . 6-5
| IFCA0100 Format . . . . . . . . . . . . . . . . . . 6-5 | Chapter 7. Cluster Resource Group APIs . . . . . 7-1
| IFCR0100 Format . . . . . . . . . . . . . . . . . . 6-5 | Cluster Resource Group APIs—Introduction . . . . . . 7-1
| IFCC0100 Format . . . . . . . . . . . . . . . . . . 6-5 | Summary of Cluster Resource Group Status . . . . 7-3
| Field Descriptions . . . . . . . . . . . . . . . . . . 6-5 | Add Node To Recovery Domain
| Usage Notes . . . . . . . . . . . . . . . . . . . . . 6-5 | (QcstAddNodeToRcvyDomain) API . . . . . . . . . . 7-5
| Results Information User Queue . . . . . . . . . 6-6 | Authorities and Locks . . . . . . . . . . . . . . . . 7-6
| Error Messages . . . . . . . . . . . . . . . . . . . 6-6 | Required Parameter Group . . . . . . . . . . . . . 7-6
| Create Cluster (QcstCreateCluster) API . . . . . . . . 6-6 | Usage Notes . . . . . . . . . . . . . . . . . . . . . 7-7
| Authorities and Locks . . . . . . . . . . . . . . . . 6-7 | Results Information User Queue . . . . . . . . . 7-7
| Required Parameter Group . . . . . . . . . . . . . 6-7 | Error Messages . . . . . . . . . . . . . . . . . . . 7-7
| NODE0100 Format . . . . . . . . . . . . . . . . . 6-8 | Change Cluster Resource Group
| Field Descriptions . . . . . . . . . . . . . . . . . . 6-8 | (QcstChangeClusterResourceGroup) API . . . . . . 7-8
| Usage Notes . . . . . . . . . . . . . . . . . . . . . 6-8 | Authorities and Locks . . . . . . . . . . . . . . . . 7-8
| Results Information User Queue . . . . . . . . . 6-8 | Required Parameter Group . . . . . . . . . . . . . 7-9
| Error Messages . . . . . . . . . . . . . . . . . . . 6-8 | Data Resiliency (RGDC0100 Format) . . . . . . . . 7-9
| Delete Cluster (QcstDeleteCluster) API . . . . . . . . 6-9 | Application Resiliency (RGDC0200 Format) . . . 7-10
| Authorities and Locks . . . . . . . . . . . . . . . . 6-9 | Field Descriptions . . . . . . . . . . . . . . . . . 7-10
| Required Parameter Group . . . . . . . . . . . . . 6-9 | Usage Notes . . . . . . . . . . . . . . . . . . . . 7-11
| Usage Notes . . . . . . . . . . . . . . . . . . . . 6-10 | Results Information User Queue . . . . . . . . 7-12
| Results Information User Queue . . . . . . . . 6-10 | Error Messages . . . . . . . . . . . . . . . . . . 7-12
| Error Messages . . . . . . . . . . . . . . . . . . 6-10 | Create Cluster Resource Group
| End Cluster Node (QcstEndClusterNode) API . . . . 6-10 | (QcstCreateClusterResourceGroup) API . . . . . . 7-13
| Authorities and Locks . . . . . . . . . . . . . . . 6-11 | Authorities and Locks . . . . . . . . . . . . . . . 7-14
| Required Parameter Group . . . . . . . . . . . . 6-11 | Required Parameter Group . . . . . . . . . . . . 7-14
| ENDN0100 Format . . . . . . . . . . . . . . . . 6-11 | Data Resiliency (RGDI0100 Format) . . . . . . 7-15
| Field Descriptions . . . . . . . . . . . . . . . . . 6-11 | Application Resiliency (RGDI0200 Format) . . 7-15
| Usage Notes . . . . . . . . . . . . . . . . . . . . 6-11 | Field Descriptions . . . . . . . . . . . . . . . . 7-15
| Results Information User Queue . . . . . . . . 6-11 | Usage Notes . . . . . . . . . . . . . . . . . . . . 7-17

 Copyright IBM Corp. 1998, 1999

 Cluster

| Results Information User Queue . . . . . . . . 7-17 | Authorities and Locks . . . . . . . . . . . . . . . 7-27

| Error Messages . . . . . . . . . . . . . . . . . . 7-17 | Required Parameter Group . . . . . . . . . . . . 7-28
| Delete Cluster Resource Group | Format of the Generated Lists . . . . . . . . . . 7-28
| (QcstDeleteClusterResourceGroup) API . . . . . . 7-18 | Input Parameter Section . . . . . . . . . . . . 7-28
| Authorities and Locks . . . . . . . . . . . . . . . 7-18 | Header Section . . . . . . . . . . . . . . . . . 7-29
| Required Parameter Group . . . . . . . . . . . . 7-19 | LRGI0100 Recovery Domain Entries Section . 7-29
| Usage Notes . . . . . . . . . . . . . . . . . . . . 7-19 | Field Descriptions . . . . . . . . . . . . . . . . . 7-29
| Results Information User Queue . . . . . . . . 7-19 | Usage Notes . . . . . . . . . . . . . . . . . . . . 7-30
| Error Messages . . . . . . . . . . . . . . . . . . 7-20 | Results Information User Queue . . . . . . . . 7-30
| End Cluster Resource Group | Error Messages . . . . . . . . . . . . . . . . . . 7-31
| (QcstEndClusterResourceGroup) API . . . . . . . 7-20 | Remove Node From Recovery Domain
| Authorities and Locks . . . . . . . . . . . . . . . 7-20 | (QcstRemoveNodeFromRcvyDomain) API . . . . . 7-31
| Required Parameter Group . . . . . . . . . . . . 7-21 | Authorities and Locks . . . . . . . . . . . . . . . 7-32
| Usage Notes . . . . . . . . . . . . . . . . . . . . 7-21 | Required Parameter Group . . . . . . . . . . . . 7-32
| Results Information User Queue . . . . . . . . 7-21 | Usage Notes . . . . . . . . . . . . . . . . . . . . 7-32
| Error Messages . . . . . . . . . . . . . . . . . . 7-22 | Results Information User Queue . . . . . . . . 7-32
| Initiate Switch Over (QcstInitiateSwitchOver) API . . 7-22 | Error Messages . . . . . . . . . . . . . . . . . . 7-33
| Authorities and Locks . . . . . . . . . . . . . . . 7-23 | Start Cluster Resource Group
| Required Parameter Group . . . . . . . . . . . . 7-23 | (QcstStartClusterResourceGroup) API . . . . . . . 7-33
| Usage Notes . . . . . . . . . . . . . . . . . . . . 7-24 | Authorities and Locks . . . . . . . . . . . . . . . 7-34
| Results Information User Queue . . . . . . . . 7-24 | Required Parameter Group . . . . . . . . . . . . 7-34
| Error Messages . . . . . . . . . . . . . . . . . . 7-24 | Usage Notes . . . . . . . . . . . . . . . . . . . . 7-35
| List Cluster Resource Groups | Results Information User Queue . . . . . . . . 7-35
| (QcstListClusterResourceGroups) API . . . . . . . 7-25 | Error Messages . . . . . . . . . . . . . . . . . . 7-35
| Authorities and Locks . . . . . . . . . . . . . . . 7-25
| Required Parameter Group . . . . . . . . . . . . 7-25 | Chapter 8. Cluster Resource Group Exit Program . 8-1
| Format of the Generated Lists . . . . . . . . . . 7-25 | Cluster Resource Group Exit Program—Introduction . 8-1
| Input Parameter Section . . . . . . . . . . . . 7-26 | Cluster Resource Group Exit Program . . . . . . . . . 8-1
| Header Section . . . . . . . . . . . . . . . . . 7-26 | Required Parameter Group . . . . . . . . . . . . . 8-2
| CRGL0100 Format . . . . . . . . . . . . . . . 7-26 | EXTP0100 Format . . . . . . . . . . . . . . . . . . 8-3
| Field Descriptions . . . . . . . . . . . . . . . . . 7-26 | Field Descriptions . . . . . . . . . . . . . . . . . . 8-3
| Error Messages . . . . . . . . . . . . . . . . . . 7-27 | Reasons an Exit Program Is Called . . . . . . . . . 8-4
| List Cluster Resource Group Information
| (QcstListClusterResourceGroupIn) API . . . . . . . 7-27

AS/400 System API Reference V4R4

 Cluster Resource Services Job Structure

| Chapter 5. Cluster APIs

| nodes and (2) applications using an IP address that can be
| Cluster APIs—Introduction | switched from one node to another.
| An AS/400 cluster is defined as a collection of complete
| systems that work together to provide a single, unified com-
| puting capability. A cluster is identified by a 10-character | Cluster Resource Services Characteristics
| name. The cluster is comprised of one or more cluster
| nodes. A cluster node is an AS/400 system that is a | The cluster resource services APIs allow a user to produce
| member of a cluster. Each cluster node is identified by an | cluster management facilities and to integrate the facilities
| 8-character cluster node identifier that is associated with a | with other system management capabilities. The APIs
| set of IP addresses representing an AS/400 system. | provide access to the OS/400 Cluster Resource Services
| functions.
| Cluster communications running over IP provides the com-
| munications path between cluster services on each node in | The cluster resource services components are:
| the cluster. Cluster Resource Services requires that the | 1. Cluster control (CCTL)
| loopback IP address on each node be active. The set of
| CCTL provides configuration, activation, and manage-
| cluster nodes that have been configured for the cluster is
| ment functions for the cluster and nodes in the cluster
| referred to as the cluster membership list.
| through a set of APIs. These APIs are described in
| Whenever communication with a node is lost, but node | Chapter 6, “Cluster Control APIs” on page 6-1.
| failure cannot be guaranteed, a cluster becomes partitioned. | 2. Cluster Resource Group Manager (CRGM)
| A cluster may be separated into multiple partitions. While
| CRGM provides object management functions for the
| partitioned, some cluster operations may be restricted. The
| Cluster Resource Group (*CRG) object through a set of
| restrictions are discussed in the introductions of the chapters
| APIs. These APIs are described in Chapter 7, “Cluster
| describing the APIs.
| Resource Group APIs” on page 7-1.
| High availability through clustering is accomplished through | 3. Cluster Resource Group Exit Program
| the implementation of resilient resources. A resilient
| This user-provided program is specified on the definition
| resource is any system resource that is available on more
| of a cluster resource group. The program is responsible
| than one node in the cluster. If a node in the cluster that is
| for handling all of the action codes that are passed to it
| the primary access point for a particular set of resilient
| by the cluster resource group manager. The action
| resources should fail, another node that is defined to be the
| codes that result in a call to the exit program are
| backup for that set of resources will become the access
| described in the APIs.
| point. The definition of the relationship between the nodes
| associated with a set of resilient resources is found in the
| cluster resource group (CRG) object. CRGs are distributed
| and coordinated across the nodes in the cluster and contain | Cluster Resource Services Job Structure
| a recovery domain.
| Cluster Resource Services consists of a set of multi-threaded
| jobs. When clustering is active on an AS/400, the jobs will
| Terminology for Resilient Resources | be run in QSYSWRK. The jobs run using the QDFTJOBD
| job description. Should any Cluster Resource Services job
| Recovery domain. A subset of nodes in a cluster grouped | fail, no joblog will be produced. In order to provide a joblog,
| together to provide availability for one or more resources. A | change the LOG parameter of the job description to a level
| domain represents the nodes of the cluster where a cluster | that will produce joblogs.
| resource exists. See Chapter 7, “Cluster Resource Group
| 1. Cluster Control consists of one job and the job is named
| APIs” on page 7-1 for more information.
| QCSTCTL.
| Cluster resource. A resource that is available on more than | 2. Cluster Resource Group Manager consists of one job
| one cluster node. | and the job is named QCSTCRGM.

| Cluster resource group. A grouping of cluster resources. | 3. Cluster Resource Groups consists of one job per CRG
| The group describes a recovery domain and supplies the | object and the job name is the same as the CRG name.
| name of the cluster resource group exit program that
| Most Cluster Resource Group APIs result in a separate job
| manages the movement of an access point.
| being submitted using the user profile specified when the
| Resilient resource. Resources that are recoverable by | CRG was created. The exit program defined in the CRG is
| Cluster Resource Services. Two types of system resources | executed in the submitted job. By default, the jobs are sub-
| that can be resilient are (1) objects being replicated between | mitted to the QBATCH JOBQ. In general, this job queue is

 Copyright IBM Corp. 1998, 1999 5-1

 Cluster APIs Use of User Queues

| used for production batch jobs and will delay or prevent com- | KEYED queue. The key for the user queue is described in
| pletion of the exit programs. In order to allow the APIs to run | the format of the user queue entry. The user queue name is
| effectively, create a separate user profile, job description, | passed to the API.
| and job queue for use by CRGs. Specify the new user profile | Parm: Value of Parm:
| for all CRGs created. The same program is executed on all | QUSCRTUQ (
| nodes within the recovery domain defined for the CRG using | UserQueueName,
| the distributed activity group support provided by Cluster | ExtendedAttr,
| Resource Services. | QueueType, /\ K Keyed \/
| KeyLength, /\ 28 \/
| MaxMsgSize, /\ 64ððð \/
| Cluster Resource Services APIs Behavior | InitialNumMsg, /\ 1 \/
| AddtNumMsg, /\ 1 \/
| Most Cluster Resource Services APIs have an asynchronous | PublicAuth, /\ \EXCLUDE \/
| behavior. In general, whenever a user program calls a | TextDescription,
| Cluster Resource Services API, the API will: | Replace, /\ \NO \/
| Ÿ Check the status of the Cluster Resource Services that | ErrorCode,
| Domain, /\ \USER \/
| will be used to process the API request. If Cluster
| Pointers /\ \NO \/
| Resource Services is not active, the API will fail. See
| );
| the specific API, to see if this condition applies.
| Ÿ Validate the API parameters and check authorities. | User queue key format:
| Ÿ Validate that a restricted API is not being called from a
| Cluster Resource Group Exit Program (see the descrip- | The following is the format of the user queue key. All user
| tion of each API to see if this applies). | queue entries have the same format for the Cluster APIs that
| Ÿ Assign a handle to the request. The handle is defined by | support the Results Information parameter.
| the Request Handle parameter on the Cluster Resource
| Services APIs. | Offset
| Ÿ Send the request handle and request to the Cluster
| Dec Hex Type Field
| Resource Services for processing.
| Ÿ Return to the API caller with the request handle. | 0 0 CHAR(10) Entry type
| Ÿ Process the request on the callers behalf. When the | 10 A CHAR(2) Entry identifier
| processing is complete, one or more messages are sent | 12 C CHAR(16) Request handle
| to the user queue specified by the Results Information
| parameter. Messages indicate whether the processing
| was successful or unsuccessful. Each message that | User queue entry format:
| Cluster Resource Services sends has a specific format.
| The following is the format of the user queue entry. All user
| See “Cluster APIs Use of User Queues” for more infor-
| queue entries have the same format for the Cluster APIs that
| mation on this format. Part of the message key will be
| support the Results Information parameter.
| the Request Handle which is returned to the API user.
| Ÿ Run the API on the originating node, one or more
| Offset
| remote nodes, or both.
| Ÿ Respond to the API request by returning messages to | Dec Hex Type Field
| the requestor's user queue on the originating node. | 0 0 BIN(4) Message format version id

| If the node originating a request fails, the request will not be | 4 4 BINARY(4) Message type
| handled on any nodes in the cluster. | 8 8 CHAR(30) API name
| 38 26 CHAR(7) Message identifier
| 45 2D CHAR(35) Reserved
| Cluster APIs Use of User Queues
| 80 50 CHAR(8) Failing node id
| Functions performed by APIs with a parameter called Results | 88 58 CHAR(10) External object name
| Information operate asynchronously and will have data sent | 98 62 CHAR(2) Reserved
| to a user queue once the API has finished processing. The
| user queue must be created before calling the API. User | 100 64 BINARY(4) Offset to message data
| queues are created with the Create User Queue | 104 68 BINARY(4) Message data length
| (QUSCRTUQ) API. The queue must be created as a | 108 6C CHAR(*) Message data

5-2 AS/400 System API Reference V4R4

 Using Results Information

| Field Descriptions | Using Results Information

| API name. The name of the API that caused the results to
| Messages placed on the user queue should be handled by
| be sent to the user queue.
| user written programs. The messages will indicate the results
| Entry identifier. Format of the data. This is set by the | of the function requested by the API. There are three classes
| OS/400. Valid values are: | of completion results:

| 00 Data distributed by the cluster APIs. | Ÿ Successful - The request completed successfully on all
| nodes that performed the function.
| Entry type. Identifies the entry type on the user queue. This | Ÿ Partially Successful - The request did not complete
| value is set by OS/400. Valid values are: | succesfully on all of the nodes that performed the func-
| tion. In some instances, partial success is caused by
| *CRS Cluster Resource Services sent the results
| one or more nodes in an inactive state. The user
| information to the user queue.
| program needs to determine if a partially successful
| External object name. Identifies the name of the object that | operation is considered successful or unsuccessful.
| was not successfully processed. | Ÿ Unsuccessful - The request failed on all nodes that per-
| formed the function.
| Failing Node ID. Identifies cluster node that detected the | Results that are partially successful or unsuccessful will have
| condition being reported. | diagnostic or informational messages describing the causes
| of failure and the node that failed to process the request.
| Message data. The message data for the message identi-
| See the description of each API for the possible messages
| fier. The format of this field depends on the message identi-
| returned to the user queue.
| fier. The Retrieve Message API can be used to determine
| the format of the message data for each message identifier.
| General Information Applicable to Cluster
| Message data length. The length of the message data for | APIs
| the message identifier.
| The following parameters on Cluster APIs must be a valid
| Message format version id. Identifies the version of the | simple name and uppercase only:
| message format that is being used. | Ÿ Node id
| Ÿ Cluster name
| Message identifier. An OS/400 message identifier associ- | Ÿ Cluster resource group name
| ated with an message description defined by OS/400. | Ÿ Job name specified for an application cluster resource
| group
| Message type. The type of message sent to the user
| queue. Any diagnostic or information messages returned as | A simple name is a character string in which the first char-
| a result of an API will appear before the completion | acter is alphabetic (A-Z), $, #, or @, and the remaining char-
| message. The valid values are: | acters are alphanumeric or (***) or a string of special
| 1 Diagnostic | characters enclosed in apostrophes(') or quotation marks(").
| 2 Information | Underscores are also valid for a simple name.
| 3 Completion
| For details about clustering, see the Clustering topic in the
| Offset to message data. The number of bytes from the | AS/400 Information Center. You can access the Information
| start of the user queue entry to the data. | Center from the AS/400 Information Center CD-ROM or from
| the following web site:
| Reserved. Reserved for future use. Set to hex zeroes. | http://publib.boulder.ibm.com/pubs/html/as400/infocenter.html

| Request handle. A unique identifier assigned by Cluster

| Resource Services and returned to the caller of the API.

Chapter 5. Cluster APIs 5-3

Using Results Information

5-4 AS/400 System API Reference V4R4

 Add Cluster Node Entry (QcstAddClusterNodeEntry) API

| Chapter 6. Cluster Control APIs

| 5 Inactive Pending. Cluster Resource Services is in the
| Cluster Control APIs—Introduction | process of ending on this node as the result of an End
| Cluster Node API call. The node is still in the cluster
| This chapter describes the cluster control APIs that provide
| membership list.
| configuration, activation, and management functions for the
| 6 Inactive. Cluster Resource Services has been ended
| cluster and nodes in the cluster.
| on the node as the result of an End Cluster Node API
| call. The node is still in the cluster membership list, but
| is no longer communicating with other nodes in the
| Network Attributes | cluster.
| 7 Failed. A previously active node has failed. A failure is
| A network attribute is used to control cluster access within a
| defined to be a system failure detected by Cluster
| network. The network attribute is ALWADDCLU (Allow Add
| Resource Services.
| to Cluster). This attribute can be set as follows:
| 8 Partition. The node is only communicating with a
| Ÿ *NONE - The system cannot be added to any cluster. | subset of the cluster due to a network failure detected
| Ÿ *ANY - The system will be added to a cluster without | by Cluster Resource Services which has resulted in the
| verification. | loss of communications to one or more nodes in the
| Ÿ *RQSAUT - The system will be added to a cluster | cluster. Once the partitioned nodes have been merged
| pending succussful verification through digital certificate | back into a whole cluster, the node will change to
| exchange. | ACTIVE status without operator intervention.
| The default value is *NONE. If *RQSAUT is specified the fol-
| lowing must be installed on the systems:
| Ÿ OS/400 option 34 (Digital Certificate Manager)
| Cluster Control APIs
| Ÿ Cryptographic Access Provided Product (AC1, AC2, or | The cluster control APIs are as follows:
| AC3)
| Add Cluster Node Entry (QcstAddClusterNodeEntry)
| adds a node to the membership list of an
| existing cluster.
| Cluster Node Status
| Change Cluster Node Entry (QcstChangeClusterNodeEntry)
| Each cluster node has a status associated with it. The | changes the fields in the cluster node entry.
| status of a cluster node may govern the behavior of a partic- | Create Cluster (QcstCreateCluster)
| ular API call. See the individual API descriptions for more | creates a new cluster of one or more nodes.
| details. The possible values are: | Delete Cluster (QcstDeleteCluster)
| deletes a cluster previously created by the
| 1 New. A node has been added to cluster membership | Create Cluster API.
| list but the Cluster Resource Services has never been | End Cluster Node (QcstEndClusterNode)
| started on that node. The Cluster Resource Services | ends Cluster Resource Services on one or all
| data structures have not been created on the node. | nodes in the cluster.
| During a Create Cluster operation, the Cluster | List Cluster Information (QcstListClusterInfo)
| Resource Services data structures will be created only | retrieves information about a cluster.
| on the node running the Create Cluster API. | Remove Cluster Node Entry (QcstRemoveClusterNodeEntry)
| 2 Active. The node has been started either with the | removes a node from a cluster.
| Create Cluster API or Add Cluster Node Entry API with | Start Cluster Node (QcstStartClusterNode)
| the "Start indicator" parameter set to 1, or with the Start | starts Cluster Resource Services on one node
| Cluster Node API. Cluster Resource Services on the | in the cluster.
| node is active.
| 3 Remove Pending. The node is in the process of being | When a partition is detected, neither the Add Cluster Node
| removed from the cluster membership list as the result | Entry nor the Create Cluster API can be run in any of the
| of a Remove Cluster Node Entry API. | partitions. All of the other APIs may be run in any partition.
| 4 Active Pending. The node is in the process of being | However, the action performed by the API will take effect
| started either as the result of a Create Cluster API or | only in the partition running the API.
| Add Cluster Node Entry API call with the "Start indi-
| cator" parameter set to 1 or because of a Start Cluster
| Node API call. In addition, the node could have previ- | Add Cluster Node Entry
| ously had a status of PARTITION and will change to
| the ACTIVE PENDING status as a result of the parti-
| (QcstAddClusterNodeEntry) API
| tions being merged.

 Copyright IBM Corp. 1998, 1999 6-1

 Add Cluster Node Entry (QcstAddClusterNodeEntry) API

| This API operates in an asynchronous mode. See “Cluster

| Required Parameter Group: | Resource Services APIs Behavior” on page 5-2 for more
| information.
| 1 Request handle Output Char(16)
| 2 Cluster name Input Char(10) | Restriction:
| 3 Node entry Input Char(*) | This API cannot be called from a Cluster Resource
| 4 Start indicator Input Binary(4)
| Group exit program.
| 5 Format name Input Char(8)
| 6 Results information Input Char(30)
| 7 Error code I/O Char(*)
| Authorities and Locks
| Service Program: QCSTCTL | This API is shipped with *EXCLUDE public authority. The
| program that calls this API must be running under a user
| Threadsafe: Yes
| profile with *IOSYSCFG special authority.
| User Queue Authority
| The Add Cluster Node Entry (QcstAddClusterNodeEntry) API | *OBJOPR and *ADD
| is used to add a node to the membership list of an existing | User Queue Library Authority
| cluster. | *EXECUTE
| User Queue Lock
| If the "Start Indicator" parameter is set to 0, the node that is
| *EXCLRD
| being added will have a status of NEW and Cluster Resource
| Services will not be started on that node. The Start Cluster
| Node (QcstStartClusterNode) API can be called from a | Required Parameter Group
| program running on one of the active nodes in the cluster to
| start Cluster Resource Services on a node that does not | Request handle
| have a status of ACTIVE. | OUTPUT; CHAR(16)
| A unique string or handle that identifies this API call. It
| If the "Start Indicator" parameter on this API is set to 1, | is used to associate this call to any responses placed on
| Cluster Resource Services will be started on the node that is | the user queue specified in the results information
| being added. If Cluster Resource Services is successfully | parameter.
| started, the status for the added node will be set to ACTIVE.
| If the Cluster Resource Services cannot be started, the | Cluster name
| status of the added node will be set to NEW. | INPUT; CHAR(10)
| The name of the cluster to which the node is being
| During the activation of Cluster Resource Services, the allow
| added. Must be a valid simple name.
| add to cluster (ALWADDCLU) network attribute is checked to
| see whether the node being added should be part of the | Node entry
| cluster and whether to validate the cluster request through | INPUT; CHAR(*)
| the use of X.509 digital certificates. If validation is required,
| This parameter contains the information associated with
| the requesting node and the node being added must have
| the node which is being added to the cluster member-
| the following installed on the systems:
| ship list.
| Ÿ OS/400 option 34 (Digital Certificate Manager)
| Start indicator
| Ÿ Cryptographic Access Provider Product (AC1, AC2, or | INPUT; BINARY(4)
| AC3)
| An indicator which specifies whether or not Cluster
| The following conditions apply to this API: | Resource Services is to be started on the node that is
| being added.
| Ÿ A node cannot add itself to a cluster. It must be added
| from a node in the cluster that has a status of ACTIVE. | 0 Cluster Resource Services will not be
| If Cluster Resource Services has not been started on | started on the node.
| any of the nodes in the cluster, this API must be called | 1 Cluster Resource Services will be started
| from a program running on the node where the cluster | on the node.
| was originally created, and the start indicator must be
| set to 0. | Format name
| Ÿ The node being added to the cluster must not already be | INPUT; CHAR(8)
| a member of this or any other cluster. A node can only | The content and format of the information supplied for
| be a member of one cluster. | the node entry. The possible format names are:
| Ÿ If the start indicator is set to 1, the node must be IP
| reachable (TCP/IP active and the INETD server started). | ADDN0100 Node entry information
| Ÿ The API will fail if any node in the cluster has a status of
| PARTITION.

6-2 AS/400 System API Reference V4R4

 Add Cluster Node Entry (QcstAddClusterNodeEntry) API

| For more information, see "ADDN0100 Format". | used to make the corresponding change to the cluster inter-
| face address. A mismatch will cause cluster errors to occur.
| Results information
| INPUT; CHAR(30) | Node ID. A valid simple name that uniquely identifies the
| A library qualified user queue name followed by a | node.
| reserved field.
| Number of cluster interfaces. The number of IP interfaces
| Library qualified user queue: A user queue, which exists | associated with a cluster node. It is limited to 1 or 2 entries
| on the node from which the API was called, that | only.
| receives results information after the function has com-
| pleted on all active nodes in the cluster. See the Usage | Offset to first cluster interface entry. The offset from the
| Notes section of this API for a description of the data | beginning of the structure to the first cluster interface address
| that is placed on this queue. This is a 20 character field. | entry.
| The first 10 characters contain the user queue name and
| the second 10 characters contain the user queue library
| name. No special values are supported. QTEMP,
| Usage Notes
| *LIBL, and *CURLIB are not valid for the library name.
| Results Information User Queue: Asynchronous
| The attributes of this user queue must be keyed and
| results are returned to a user queue specified by the Results
| have a domain of user.
| Information parameter of the API. See “Cluster APIs Use of
| Reserved: The last 10 characters of results information | User Queues” on page 5-2 and “Using Results Information”
| are reserved and must be set to hexadecimal zero. | on page 5-3 for details on how to create the results informa-
| tion user queue, the format of the entries, and how to use
| Error code
| the data placed on the queue. The data is sent to the user
| I/O; CHAR(*)
| queue in the form of a message identifier and the substitution
| The structure in which to return error information. For | data for the message (if any exists). The following identifies
| the format of the structure, see “Error Code Parameter” | the data sent to the user queue (excluding the message
| on page 2-6. | text).
| CPCBB01 C
| ADDN0100 Format | Cluster Resource Services API &1 completed.
| CPF2204 D User profile &1 not found.
| Offset | CPF3CF2 D
| Error(s) occurred during running of &1 API.
| Dec Hex Type Field
| CPFBB01 D
| 0 0 Char(8) Node ID | Cluster already exists.
| 8 8 Binary(4) Offset to first cluster inter- | CPFBB05 D
| face entry | Cluster node &1 cannot be started.
| 12 C Binary(4) Number of cluster inter- | CPFBB07 D
| faces | Node &1 could not be added to cluster &2.
| CPFBB11 D
| This field Char(16) Cluster interface address
| repeats for
| Cluster node &1 already exists in cluster &2.
| each number | CPFBB12 D
| of cluster | Cluster node &1 in cluster &2 could not be
| interfaces. | started.
| CPFBB13 D
| Cluster interface address &1 already assigned
| Field Descriptions | to cluster node &2.
| CPFBB17 D
| Cluster interface address. The cluster interface address is | &1 API cannot be processed in cluster &2.
| an IP address that is used by Cluster Resource Services to | CPFBB24 D
| communicate with other nodes in the cluster. The address is | Node &1 not participating in &2 API protocol.
| in dotted decimal format and is a null-terminated string. | CPFBB2D D
| Note: Cluster Resource Services uses existing IP interfaces | Timeout detected while waiting for a response.
| configured for an AS/400. See the TCP/IP Configuration and | CPFBB46 D
| Reference book for instructions for configuring IP interfaces | Cluster Resource Services internal error.
| on the AS/400. The IP addresses defined as cluster inter- | CPFBB54 D
| face addresses can be used by other applications. If an IP | Node &1 not be added to the cluster &2.
| address is reconfigured through the TCP/IP configuration | CPIBB03 I Cluster node &1 added to cluster &2.
| functions, the Change Cluster Node Entry API should be | CPIBB05 I Cluster node &1 started in cluster &2.

Chapter 6. Cluster Control APIs 6-3

 Change Cluster Node Entry (QcstChangeClusterNodeEntry) API

| Error Messages | TCP1901 E Internet address &1 not valid.

| Messages that are delivered through the error code param-

| eter are listed here. The data (messages) sent to the results | Change Cluster Node Entry
| information user queue are listed in the Usage Notes above. | (QcstChangeClusterNodeEntry) API
| CPF3C1E E
| Required parameter &1 omitted.
| CPF3C21 E | Required Parameter Group:
| Format name &1 is not valid.
| CPF3C29 E | 1 Request handle Output Char(16)
| Object name &1 is not valid. | 2 Cluster name Input Char(10)
| 3 Node id Input Char(8)
| CPF3C39 E | 4 Format name Input Char(8)
| Value for reserved field not valid. | 5 Node entry information Input Char(*)
| CPF3CF1 E | 6 Length of node entry infor- Input Binary(4)
| Error code parameter not valid. | mation
| CPF3CF2 E | 7 Results information Input Char(30)
| Error(s) occurred during running of &1 API. | 8 Error code I/O Char(*)
| CPF9801 E Object &2 in library &3 not found.
| CPF9802 E Not authorized to object &2 in &3. | Service Program: QCSTCTL
| CPF9804 E Object &2 in library &3 damaged.
| Threadsafe: Yes
| CPF9810 E Library &1 not found.
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3. | The Change Cluster Node Entry
| CPFBB02 E | (QcstChangeClusterNodeEntry) API is used to change the
| Cluster &1 does not exist. | fields in the cluster node entry. The only fields that can be
| CPFBB04 E | changed are the cluster interface addresses defined for the
| Number of cluster interface addresses not valid. | node.
| CPFBB07 E
| Node &1 could not be added to cluster &2. | The following conditions apply to this API:
| CPFBB0D E | Ÿ This API must be called from a program running on a
| Cluster interface address &1 specified more | cluster node with a status of ACTIVE.
| than once. | Ÿ If the cluster is in a partitioned state, this operation can
| CPFBB11 E | only be performed within the partition running the API.
| Cluster node &1 already exists in cluster &2. | Ÿ The node entry which is being changed may or may not
| CPFBB13 E | have Cluster Resource Services started.
| Cluster interface address &1 already assigned | Ÿ Only one cluster interface address can be changed at a
| to cluster node &2. | time.
| CPFBB17 E
| &1 API cannot be processed in cluster &2. | This API operates in an asynchronous mode. See “Cluster
| CPFBB26 E | Resource Services APIs Behavior” on page 5-2 for more
| Cluster Resource Services not active or not | information.
| responding.
| CPFBB32 E | Restriction:
| Attributes of user queue &1 in library &1 are not | This API cannot be called from a Cluster Resource
| valid. | Group exit program.
| CPFBB39 E
| Current user does not have IOSYSCFG special
| authority. | Authorities and Locks
| CPFBB44 E
| &1 API cannot be called from a cluster resource | This API is shipped with *EXCLUDE public authority. The
| group exit program. | program that calls this API must be running under a user
| CPFBB46 E | profile with *IOSYSCFG special authority.
| Cluster Resource Services internal error. | User Queue Authority
| CPFBB55 E | *OBJOPR and *ADD
| Value &1 specified for start indicator not valid. | User Queue Library Authority
| CPFBB57 E | *EXECUTE
| Offset to cluster interface entry not valid. | User Queue Lock
| *EXCLRD

6-4 AS/400 System API Reference V4R4

 Change Cluster Node Entry (QcstChangeClusterNodeEntry) API

| Required Parameter Group | Error code

| I/O; CHAR(*)
| Request handle
| The structure in which to return error information. For
| OUTPUT; CHAR(16)
| the format of the structure, see “Error Code Parameter”
| A unique string or handle that identifies this API call. It | on page 2-6.
| is used to associate this call to any responses placed on
| the user queue specified in the results information
| parameter. | IFCA0100 Format
| Cluster name | Offset
| INPUT; CHAR(10)
| Dec Hex Type Field
| The name of the cluster contining the node. Must be a
| 0 0 Char(16) Cluster interface address
| valid simple name.

| Node id
| INPUT; CHAR(8) | IFCR0100 Format
| A valid simple name that uniquely identifies the node.
| Offset
| Format name | Dec Hex Type Field
| INPUT; CHAR(8)
| 0 0 Char(16) Cluster interface address
| The content and format of the node entry information.
| The possible format names are:

| IFCA0100 Add cluster node interface

| IFCC0100 Format
| IFCR0100 Remove cluster node interface
| IFCC0100 Replace cluster node interface | Offset
| Dec Hex Type Field
| Node entry information
| INPUT; CHAR(*) | 0 0 Char(16) Old cluster interface
| address
| Detailed information about the node entry.
| 16 10 Char(16) New cluster interface
| Length of node entry information | address
| INPUT; BINARY(4)
| The length of the node entry information. | Field Descriptions
| Results information
| Cluster interface address. The cluster interface address is
| INPUT; CHAR(30)
| an IP address that is used by Cluster Resource Services to
| A library qualified user queue name followed by a | communicate with other nodes in the cluster. The address is
| reserved field. | in dotted decimal format and is a null-terminated string.
| Library qualified user queue: A user queue, which exists | Note: Cluster Resource Services uses existing IP interfaces
| on the node from which the API was called, that | configured for an AS/400. See the TCP/IP Configuration and
| receives results information after the function has com- | Reference book for instructions for configuring IP interfaces
| pleted on all active nodes in the cluster. See the Usage | on the AS/400. The IP addresses defined as cluster inter-
| Notes section of this API for a description of the data | face addresses can be used by other applications. If an IP
| that is placed on this queue. This is a 20 character field. | address is reconfigured through the TCP/IP configuration
| The first 10 characters contain the user queue name and | functions, the Change Cluster Node Entry API should be
| the second 10 characters contain the user queue library | used to make the corresponding change to the cluster inter-
| name. No special values are supported. QTEMP, | face address. A mismatch will cause cluster errors to occur.
| *LIBL, and *CURLIB are not valid for the library name.
| The attributes of this user queue must be keyed and | Old cluster interface address. The cluster interface
| have a domain of user. | address which is being replaced.
| Reserved: The last 10 characters of results information | New cluster interface address. The cluster interface
| are reserved and must be set to hexadecimal zero. | address which replaces the old cluster interface address.

| Usage Notes

Chapter 6. Cluster Control APIs 6-5

 Create Cluster (QcstCreateCluster) API

| Results Information User Queue: Asynchronous | CPFBB09 E

| results are returned to a user queue specified by the Results | Cluster node &1 does not exist in cluster &2.
| Information parameter of the API. See “Cluster APIs Use of | CPFBB13 E
| User Queues” on page 5-2 and “Using Results Information” | Cluster interface address &1 already assigned
| on page 5-3 for details on how to create the results informa- | to cluster node &2.
| tion user queue, the format of the entries, and how to use | CPFBB14 E
| the data placed on the queue. The data is sent to the user | Cluster interface address &1 cannot be added
| queue in the form of a message identifier and the substitution | for cluster node &2.
| data for the message (if any exists). The following identifies | CPFBB15 E
| the data sent to the user queue (excluding the message | Cluster interface address &1 cannot be
| text). | removed.
| CPFBB16 E
| CPCBB01 C
| Cluster interface address &1 cannot be
| Cluster Resource Services API &1 completed.
| changed to &2.
| CPF3CF2 D
| CPFBB17 E
| Error(s) occurred during running of &1 API.
| &1 API cannot be processed in cluster &2.
| CPFBB09 D
| CPFBB32 E
| Cluster node &1 does not exist in cluster &2.
| Attributes of user queue &1 in library &2 are not
| CPFBB13 D
| valid.
| Cluster interface address &1 already assigned
| CPFBB39 E
| to cluster node &2.
| Current user does not have IOSYSCFG special
| CPFBB14 D
| authority.
| Cluster interface address &1 cannot be added
| CPFBB44 E
| for cluster node &2.
| &1 API cannot be called from a cluster resource
| CPFBB15 D
| group exit program.
| Cluster interface address &1 cannot be
| CPFBB46 E
| removed.
| Cluster Resource Services internal error.
| CPFBB16 D
| CPFBB56 E
| Cluster interface address &1 cannot be
| Length of node entry not valid.
| changed to &2.
| TCP1901 E Internet address &1 not valid.
| CPFBB17 D
| &1 API cannot be processed in cluster &2.
| CPFBB24 D
| Node &1 not participating in &2 protocol. | Create Cluster (QcstCreateCluster) API
| CPFBB2D D
| Timeout detected while waiting for a response.
| CPFBB46 D | Required Parameter Group:
| Cluster Resource Services internal error.
| 1 Request handle Output Char(16)
| 2 Cluster name Input Char(10)
| Error Messages | 3 Cluster membership array Input Char(*)
| 4 Number of cluster member- Input Binary(4)
| CPF3C1E E | ship array entries
| Required parameter &1 omitted. | 5 Start indicator Input Binary(4)
| CPF3C21 E | 6 Format name Input Char(8)
| Format name &1 is not valid. | 7 Results information Input Char(30)
| CPF3C39 E | 8 Error code I/O Char(*)
| Value for reserved field not valid.
| Service Program: QCSTCTL
| CPF3CF1 E
| Error code parameter not valid. | Threadsafe: Yes
| CPF3CF2 E
| Error(s) occurred during running of &1 API.
| CPF9801 E Object &2 in library &3 not found. | The Create Cluster (QcstCreateCluster) API is used to create
| CPF9802 E Not authorized to object &2 in &3. | a new cluster of one or more nodes. Each node specified on
| CPF9804 E Object &2 in library &3 damaged. | "Cluster membership array" parameter will be placed in the
| CPF9810 E Library &1 not found. | cluster membership list.
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3. | If the "Start Indicator" parameter is set to 0, each node that is
| CPFBB02 E | being added will have a status of NEW and Cluster Resource
| Cluster &1 does not exist. | Services will not be started on any node. In order to start
| Cluster Resource Services, the Start Cluster Node

6-6 AS/400 System API Reference V4R4

 Create Cluster (QcstCreateCluster) API

| (QcstStartClusterNode) API must be called from a program | Request handle

| running on the node that ran the Create Cluster API. The | OUTPUT; CHAR(16)
| Start Cluster Node API may be used to start nodes in the
| A unique string or handle that identifies this API call. It
| cluster membership list.
| is used to associate this call to any responses placed on
| the user queue specified in the results information
| If the "Start Indicator" parameter is set to 1, the cluster can
| parameter.
| contain only one node. Cluster Resource Services will be
| started on the node being defined. If Cluster Resource Ser- | Cluster name
| vices is successfully started, the status for the node will be | INPUT; CHAR(10)
| set to ACTIVE. If Cluster Resource Services is not
| The name of the cluster which is being created. This
| succesfully started, the status of the node remains NEW. If
| must be a valid simple name.
| a list of nodes is specified, the start indicator is ignored.
| Cluster membership array
| After Cluster Resource Services has been started on the ori-
| INPUT; CHAR(*)
| ginal node, additional nodes can only be started by calling
| the Start Cluster Node (QcstStartClusterNode) API on the | This parameter contains a list of nodes which will be
| original node. If Cluster Resource Services is active on more | placed in the cluster membership list.
| than one node, additional nodes may be started by calling
| Number of cluster membership array entries
| the Start Cluster Node (QcstStartClusterNode) API on any
| INPUT; BINARY(4)
| node that has a status of ACTIVE.
| The number of nodes in the cluster membership array.
| Once the cluster has been created, the Add Cluster Node | Must be greater than or equal to 1 and less than or
| Entry (QcstAddClusterNodeEntry) API can be used to add | equal to 128.
| additional nodes to the cluster membership list. The
| Start indicator
| QcstAddClusterNodeEntry API can be called from a program
| INPUT; BINARY(4)
| running on any node in the cluster that has a status of
| ACTIVE or from the node on which the cluster was originally | An indicator which specifies whether or not Cluster
| created. | Resource Services is to be started on the node being
| defined.
| The following conditions apply to this API:
| 0 Cluster Resource Services will not be
| Ÿ A node can only be a member of one cluster.
| started on any node.
| Ÿ At least one node must be specified in the cluster mem-
| 1 Cluster Resource Services will be started
| bership list. A cluster cannot be created with an empty
| on the node.
| membership list.
| Format name
| This API operates in an asynchronous mode. See “Cluster
| INPUT; CHAR(8)
| Resource Services APIs Behavior” on page 5-2 for more
| information. | The content and format of the information supplied in the
| node entry array. The possible format names are:
| Restriction:
| NODE0100 Cluster membership array information
| This API cannot be called from a Cluster Resource
| Group exit program. | For more information, see "NODE0100
| Format".

| Authorities and Locks | Results information

| INPUT; CHAR(30)
| This API is shipped with *EXCLUDE public authority. The
| A library qualified user queue name followed by a
| program that calls this API must be running under a user
| reserved field.
| profile with *IOSYSCFG special authority.
| Library qualified user queue: A user queue, which exists
| User Queue Authority
| on the node from which the API was called, that
| *OBJOPR and *ADD
| receives results information after the function has com-
| User Queue Library Authority
| pleted on all active nodes in the cluster. See the Usage
| *EXECUTE
| Notes section of this API for a description of the data
| User Queue Lock
| that is placed on this queue. This is a 20 character field.
| *EXCLRD
| The first 10 characters contain the user queue name and
| the second 10 characters contain the user queue library
| Required Parameter Group | name. No special values are supported. QTEMP,
| *LIBL, and *CURLIB are not valid for the library name.
| The attributes of this user queue must be keyed and
| have a domain of user.

Chapter 6. Cluster Control APIs 6-7

 Create Cluster (QcstCreateCluster) API

| Reserved: The last 10 characters of results information | Results Information User Queue: Asynchronous
| are reserved and must be set to hexadecimal zero. | results are returned to a user queue specified by the Results
| Information parameter of the API. See “Cluster APIs Use of
| Error code
| User Queues” on page 5-2 and “Using Results Information”
| I/O; CHAR(*)
| on page 5-3 for details on how to create the results informa-
| The structure in which to return error information. For | tion user queue, the format of the entries, and how to use
| the format of the structure, see “Error Code Parameter” | the data placed on the queue. The data is sent to the user
| on page 2-6. | queue in the form of a message identifier and the substitution
| data for the message (if any exists). The following identifies
| the data sent to the user queue (excluding the message
| NODE0100 Format | text).

| Offset | CPCBB01 C
| Cluster Resource Services API &1 completed.
| Dec Hex Type Field
| CPF3CF2 D
| Note: These fields are repeated for each node entry. | Error(s) occurred during running of &1 API.
| Binary(4) Length of node entry | CPFBB05 D
| Cluster node &1 cannot be started.
| Char(8) Node id
| CPFBB10 D
| Binary(4) Offset to first cluster inter- | Specified cluster interface not defined on this
| face entry
| system.
| Binary(4) Number of cluster inter- | CPFBB12 D
| faces | Cluster node &1 in cluster &2 could not be
| This field is Char(16) Cluster interface address | started.
| repeated for | CPFBB2D D
| each cluster | Timeout detected while waiting for a response.
| interface. | CPFBB46 D
| Cluster Resource Services internal error.
| CPIBB01 I Cluster &1 created.
| Field Descriptions | CPIBB03 I Cluster node &1 added to cluster &2.
| CPIBB05 I Cluster node &1 started in cluster &2.
| Cluster interface address. The cluster interface address is
| an IP address that is used by Cluster Resource Services to
| communicate with other nodes in the cluster. The address is | Error Messages
| in dotted decimal format and is a null-terminated string.
| CPF3C1E E
| Note: Cluster Resource Services uses existing IP interfaces | Required parameter &1 omitted.
| configured for an AS/400. See the TCP/IP Configuration and | CPF3C21 E
| Reference book for instructions for configuring IP interfaces | Format name &1 is not valid.
| on the AS/400. The IP addresses defined as cluster inter- | CPF3C29 E
| face addresses can be used by other applications. If an IP | Object name &1 is not valid.
| address is reconfigured through the TCP/IP configuration | CPF3C39 E
| functions, the Change Cluster Node Entry API should be | Value for reserved field not valid.
| used to make the corresponding change to the cluster inter- | CPF3CF1 E
| face address. A mismatch will cause cluster errors to occur. | Error code parameter not valid.
| CPF3CF2 E
| Length of node entry. The length of the node entry. It must | Error(s) occurred during running of &1 API.
| be at a 4-byte alignment. | CPF9801 E Object &2 in library &3 not found.
| CPF9802 E Not authorized to object &2 in &3.
| Node id. A simple valid name that uniquely identifies a node.
| CPF9804 E Object &2 in library &3 damaged.
| Number of cluster interfaces. The number of IP interfaces | CPF9810 E Library &1 not found.
| that are to be used by Cluster Resource Services. It is | CPF9872 E Program or service program &1 in library &2
| limited to 1 or 2 entries only. | ended. Reason code &3.
| CPFBB01 E
| Offset to first cluster interface entry. The offset from the | Cluster already exists.
| beginning of the structure to the first cluster interface entry. | CPFBB03 E
| Number of cluster node entries not valid.
| CPFBB04 E
| Usage Notes | Number of cluster interface addresses not valid.
| CPFBB0C E
| Cluster node ID &1 specified more than once.

6-8 AS/400 System API Reference V4R4

 Delete Cluster (QcstDeleteCluster) API

| CPFBB0D E | Ÿ This API may be called when the cluster is in a parti-

| Cluster interface address &1 specified more | tioned state. In this case, the delete operation will only
| than once. | be performed within the partition running the API.
| CPFBB32 E
| This API operates in an asynchronous mode. See “Cluster
| Attributes of user queue &1 in library &2 are not
| Resource Services APIs Behavior” on page 5-2 for more
| valid.
| information.
| CPFBB39 E
| Current user does not have IOSYSCFG special | Restriction:
| authority.
| This API cannot be called from a Cluster Resource
| CPFBB44 E
| Group exit program.
| &1 API cannot be called from a cluster resource
| group exit program.
| CPFBB46 E | Authorities and Locks
| Cluster Resource Services internal error.
| CPFBB55 E | This API is shipped with *EXCLUDE public authority. The
| Value &1 specified for start indicator not valid. | program that calls this API must be running under a user
| CPFBB56 E | profile with *IOSYSCFG special authority.
| Length of node entry not valid. | User Queue Authority
| CPFBB57 E | *OBJOPR and *ADD
| Offset to cluster interface entry not valid. | User Queue Library Authority
| TCP1901 E Internet address &1 not valid. | *EXECUTE
| User Queue Lock
| *EXCLRD
| Delete Cluster (QcstDeleteCluster) API
| Required Parameter Group
| Required Parameter Group: | Request handle
| OUTPUT; CHAR(16)
| 1 Request handle Output Char(16)
| 2 Cluster name Input Char(10) | A unique string or handle that identifies this API call. It
| 3 Results information Input Char(30) | is used to associate this call to any responses placed on
| 4 Error code I/O Char(*) | the user queue specified in the results information
| parameter.
| Service Program: QCSTCTL
| Cluster name
| Threadsafe: Yes | INPUT; CHAR(10)
| The name of the cluster which is being deleted. This
| The Delete Cluster (QcstDeleteCluster) API is used to delete | must be a valid simple name.
| a cluster created by the Create Cluster API. Any Cluster
| Results information
| Resource Group (CRG) objects associated with the cluster
| INPUT; CHAR(30)
| are deleted, Cluster Resource Services is ended on each
| node in the cluster membership list, and the cluster is | A library qualified user queue name followed by a
| deleted. | reserved field.

| The following conditions apply to this API: | Library qualified user queue: A user queue, which exists
| on the node from which the API was called, that
| Ÿ The Delete Cluster API must be called from a program | receives results information after the function has com-
| running on a node in the cluster. | pleted on all active nodes in the cluster. See the Usage
| Ÿ If the API is initiated from a cluster node with a status of | Notes section of this API for a description of the data
| ACTIVE, all active cluster nodes will be removed from | that is placed on this queue. This is a 20 character field.
| the cluster, and the CRG objects associated with the | The first 10 characters contain the user queue name and
| cluster will be deleted. CRG objects on nodes with a | the second 10 characters contain the user queue library
| status of INACTIVE or FAILED will not be deleted. | name. No special values are supported. QTEMP,
| Ÿ If the API is initiated from a cluster node with a status of | *LIBL, and *CURLIB are not valid for the library name.
| FAILED or INACTIVE, only that node is removed from | The attributes of this user queue must be keyed and
| the cluster and CRG objects on that node are deleted. | have a domain of user.
| Ÿ Cluster Resource Group Manager will call Cluster
| Resource Group exit programs with an action code of | Reserved: The last 10 characters of results information
| Delete (7). | are reserved and must be set to hexadecimal zero.

Chapter 6. Cluster Control APIs 6-9

 End Cluster Node (QcstEndClusterNode) API

| Error code | CPFBB44 E

| I/O; CHAR(*) | &1 API cannot be called from a cluster resource
| group exit program.
| The structure in which to return error information. For
| CPFBB46 E
| the format of the structure, see “Error Code Parameter”
| Cluster Resource Services internal error.
| on page 2-6.

| Usage Notes | End Cluster Node (QcstEndClusterNode)

| Results Information User Queue: Asynchronous | API
| results are returned to a user queue specified by the Results
| Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information” | Required Parameter Group:
| on page 5-3 for details on how to create the results informa- | 1 Request handle Output Char(16)
| tion user queue, the format of the entries, and how to use | 2 Cluster name Input Char(10)
| the data placed on the queue. The data is sent to the user | 3 Node entry Input Char(*)
| queue in the form of a message identifier and the substitution | 4 Option Input Binary(4)
| data for the message (if any exists). The following identifies | 5 Format name Input Char(8)
| the data sent to the user queue (excluding the message | 6 Results information Input Char(30)
| text). | 7 Error code I/O Char(*)

| CPCBB01 C | Service Program: QCSTCTL

| Cluster Resource Services API &1 completed.
| CPF3CF2 D | Threadsafe: Yes
| Error(s) occurred during running of &1 API.
| CPFBB24 D
| The End Cluster Node (QcstEndClusterNode) API is used to
| Node &1 is not participating in &2 API protocol
| end Cluster Resource Services on one or all the nodes in the
| CPFBB2D D
| membership list of an existing cluster. The status of each
| Timeout detected while waiting for a response.
| node that is ended is set to INACTIVE. In order to restart
| CPFBB46 D
| Cluster Resource Services on nodes that have been ended,
| Cluster Resource Services internal error.
| the Start Cluster Node (QcstStartClusterNode) API is used.
| CPIBB02 I Cluster &1 deleted from node &2.
| When a node in the cluster is ended, it is not removed from
| Error Messages | the cluster membership list.

| CPF3C1E E | If all the nodes in the cluster are being ended, Cluster
| Required parameter &1 omitted. | Resource Group exit programs will not be called with an indi-
| CPF3C39 E | cation to failover.
| Value for reserved field not valid.
| CPF3CF1 E | The following conditions apply to this API:
| Error code parameter not valid. | Ÿ The node being ended must be ACTIVE.
| CPF3CF2 E | Ÿ This API can be called from a program running on the
| Error(s) occurred during running of &1 API. | node which is to be ended, or it can be called from a
| CPF9801 E Object &2 in library &3 not found. | program running on any node in the cluster which has a
| CPF9802 E Not authorized to object &2 in &3. | status of ACTIVE.
| CPF9804 E Object &2 in library &3 damaged. | Ÿ Ending a node that is a assigned the role of primary in
| CPF9810 E Library &1 not found. | any CRG will cause the CRG exit program to be called
| CPF9872 E Program or service program &1 in library &2 | with an action code of failover (9).
| ended. Reason code &3. | Ÿ If this API is called when the cluster is partitioned, only
| CPFBB02 E | nodes in the partition running the API will process the
| Cluster &1 does not exist. | request.
| CPFBB32 E
| Attributes of user queue &1 in library &2 are not | This API operates in an asynchronous mode. See “Cluster
| valid. | Resource Services APIs Behavior” on page 5-2 for more
| CPFBB39 E | information.
| Current user does not have IOSYSCFG special
| Restriction:
| authority.
| This API cannot be called from a Cluster Resource
| Group exit program.

6-10 AS/400 System API Reference V4R4

 End Cluster Node (QcstEndClusterNode) API

| Authorities and Locks | pleted on all active nodes in the cluster. See the Usage
| Notes section of this API for a description of the data
| This API is shipped with *EXCLUDE public authority. The | that is placed on this queue. This is a 20 character field.
| program that calls this API must be running under a user | The first 10 characters contain the user queue name and
| profile with *IOSYSCFG special authority. | the second 10 characters contain the user queue library
| name. No special values are supported. QTEMP,
| User Queue Authority
| *LIBL, and *CURLIB are not valid for the library name.
| *OBJOPR and *ADD
| The attributes of this user queue must be keyed and
| User Queue Library Authority
| have a domain of user.
| *EXECUTE
| User Queue Lock | Reserved: The last 10 characters of results information
| *EXCLRD | are reserved and must be set to hexadecimal zero.

| Error code
| Required Parameter Group | I/O; CHAR(*)

| Request handle | The structure in which to return error information. For

| OUTPUT; CHAR(16) | the format of the structure, see “Error Code Parameter”
| on page 2-6.
| A unique string or handle that identifies this API call. It
| is used to associate this call to any responses placed on
| the user queue specified in the results information | ENDN0100 Format
| parameter.
| Offset
| Cluster name
| INPUT; CHAR(10) | Dec Hex Type Field

| The name of the cluster that contains the node or nodes | 0 0 Char(8) Node id
| being ended.

| Node entry | Field Descriptions

| INPUT; CHAR(*) | Node id. A valid simple name that uniquely identifies a node.
| This parameter contains the node id being ended. It is | A special value of *ALL can be specified to end all nodes in
| ignored if the special value *ALL is specified as the node | a cluster. The special value must be left-justified.
| id.

| Option | Usage Notes

| INPUT; BINARY(4)
| Results Information User Queue: Asynchronous
| The method used to end the node: | results are returned to a user queue specified by the Results
| 0 Immediate. The request to end replication | Information parameter of the API. See “Cluster APIs Use of
| for all CRGs on the node will be pro- | User Queues” on page 5-2 and “Using Results Information”
| cessed immediately. | on page 5-3 for details on how to create the results informa-
| 1 Controlled. Pending CRG actions will | tion user queue, the format of the entries, and how to use
| complete before the request to end repli- | the data placed on the queue. The data is sent to the user
| cation is processed. | queue in the form of a message identifier and the substitution
| data for the message (if any exists). The following identifies
| Format name | the data sent to the user queue (excluding the message
| INPUT; CHAR(8) | text).
| The content and format of the information supplied in the | CPCBB01 C
| node entry array. The possible format names are: | Cluster Resource Services API &1 completed.
| CPF3CF2 D
| ENDN0100 Node id information
| Error(s) occurred during running of &1 API.
| For more information, see "ENDN0100 Format". | CPFBB09 D
| Cluster node &1 does not exist in cluster &2.
| Results information | CPFBB17 D
| INPUT; CHAR(30) | &1 API cannot be processed in cluster &2.
| A library qualified user queue name followed by a | CPFBB1C D
| reserved field. | Cluster node &1 in cluster &2 cannot be ended.
| CPFBB24 D
| Library qualified user queue: A user queue, which exists
| Node &1 not participating in &2 protocol.
| on the node from which the API was called, that
| CPFBB2D D
| receives results information after the function has com-
| Timeout detected while waiting for a response.

Chapter 6. Cluster Control APIs 6-11

 List Cluster Information (QcstListClusterInfo) API

| CPFBB46 D
| Cluster Resource Services internal error. | Required Parameter Group:
| CPIBB06 I Cluster node &1 ended in cluster &2.
| 1 Qualified user space name Output Char(20)
| 2 Cluster name Input Char(10)
| Error Messages | 3 Format name Input Char(8)
| CPF3C1E E | 4 Node ID Input Char(8)
| Required parameter &1 omitted. | 5 Error code I/O Char(*)
| CPF3C21 E
| Service Program: QCSTCTL1
| Format name &1 is not valid.
| CPF3C39 E | Threadsafe: Yes
| Value for reserved field not valid.
| CPF3CF1 E
| Error code parameter not valid. | The List Cluster Information (QcstListClusterInfo) API is used
| CPF3CF2 E | to retrieve information about a cluster. It must be called from
| Error(s) occurred during running of &1 API. | a program running on one of the nodes in the cluster. The
| CPF9801 E Object &2 in library &3 not found. | information returned may not be current if this API is called
| CPF9802 E Not authorized to object &2 in &3. | from a program running on a node that has a status of INAC-
| CPF9804 E Object &2 in library &3 damaged. | TIVE or FAILED. This API may be called from a CRG exit
| CPF9810 E Library &1 not found. | program.
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3.
| CPFBB02 E
| Authorities and Locks
| Cluster &1 does not exist. | User Space Authority
| CPFBB09 E | *CHANGE
| Cluster node &1 does not exist in cluster &2. | User Space Library Authority
| CPFBB17 E | *EXECUTE
| &1 API cannot be processed in cluster &2. | User Queue Lock
| CPFBB1C E | *EXCLRD
| Cluster node &1 in cluster &2 already ended.
| CPFBB26 E
| Cluster Resource Services not active or not
| Required Parameter Group
| responding. | Qualified user space name
| CPFBB32 E | OUTPUT; CHAR(20)
| Attributes of user queue &1 in library &1 are not
| The user space that receives the information and the
| valid.
| library in which it is located. The first 10 characters
| CPFBB39 E
| contain the user space name, and the second 10 char-
| Current user does not have IOSYSCFG special
| acters contain the library name. Special values are not
| authority.
| allowed to be specified for the library name.
| CPFBB44 E
| &1 API cannot be used within a cluster | Cluster name
| resource group exit program. | INPUT; CHAR(10)
| CPFBB46 E
| The name of the cluster for which information is
| Cluster Resource Services internal error.
| retrieved.
| CPFBB59 E
| Value &1 specified for option not valid. | Format name
| INPUT; CHAR(8)
| The format of the information to be returned. Supported
| List Cluster Information | format names are:
| (QcstListClusterInfo) API
| LCTI0100 Returns information about a specific node
| or all nodes in the cluster.

| Node ID
| INPUT; CHAR(8)
| A valid simple name that uniquely identifies a node.
| *ALL special value can be used to return information
| about all nodes in the cluster. The *ALL special value
| must be left-justified.

6-12 AS/400 System API Reference V4R4

 List Cluster Information (QcstListClusterInfo) API

| Error code
| Offset
| I/O; CHAR(*)
| Dec Hex Type Field
| The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter” | These fields Binary(4) Length of node entry
| are repeated
| on page 2-6. | Char(8) Node ID
| for each node
| entry returned. Binary(4) Node status
| Format of Generated Lists | Binary(4) Offset to first cluster inter-
| face entry
| The cluster information list consists of: | Binary(4) Number of cluster inter-
| Ÿ A user space | faces
| Ÿ A generic header | Array(*) of Cluster interface entry
| Ÿ An input parameter section | Char(16) array
| Ÿ A list data section | These fields Char(16) Cluster interface address
| – LCTI0100 format | are repeated
| for each
| For details about the user area and generic header, see | cluster inter-
| "System API Reference, User Space Format for List APIs". | face entry
| For details about the remaining items, see the following | returned.
| sections. For detailed descriptions of the fields in the list
| returned, see "Field Descriptions".
| Field Descriptions
| When you retrieve list entry information from a user space,
| you must not use the entry size returned in the generic | Cluster name. The name of the cluster for which information
| header. Each entry may have a different size. The size of | is retrieved.
| each entry may be padded at the end.
| Cluster interface address. The cluster interface address is
| an IP address which is used by Cluster Resource Services to
| Input Parameter Section | communicate with other nodes in the cluster. It is returned
| as a null-terminated string and represented in dotted decimal
| Offset | format.
| Dec Hex Type Field
| Cluster interface address array. Array of cluster interface
| 0 0 Char(10) User space name | addresses in use by each node in the node entry array.
| 10 A Char(10) User space library name
| Format name. The content and format of the information
| 20 14 Char(10) Cluster name
| returned in the user space.
| 30 1E Char(8) Format name
| 38 26 Char(8) Node ID | Information status. Indicates the consistency of the
| retrieved information.

| Header Section: Global information about the cluster. | 0 The information is consistent for all active
| nodes in the cluster.
| Offset
| 1 The information retrieved from the node
| running the API may not be consistent with all
| Dec Hex Type Field | active nodes in the cluster. In order to obtain
| 0 0 CHAR(1) Information status | consistent information:
| Ÿ Call this API on an active node in the
| cluster.
| LCTI0100 Format | Ÿ Start Cluster Resource Services on the
| node and call the API again.
| Offset
| Length of node entry. The length of the node entry.
| Dec Hex Type Field
| Array(*) of Node entry array | Node entry array. Array of cluster nodes for which informa-
| Char(*) | tion is being returned.

| Node ID. A valid system name that uniquely identifies a

| node.

| Node status. The status of the node in the cluster. The

| valid values for node status are as follows:

Chapter 6. Cluster Control APIs 6-13

 Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) API

| 1 New
| 2 Active | Required Parameter Group:
| 3 Remove Pending
| 4 Active Pending | 1 Request handle Output Char(16)
| 5 Inactive Pending | 2 Cluster name Input Char(10)
| 6 Inactive | 3 Node entry Input Char(*)
| 7 Failed | 4 Format name Input Char(8)
| 8 Partition | 5 Results information Input Char(30)
| 6 Error code I/O Char(*)
| See the Cluster Node Status definitions at the beginning of
| this chapter for more information. | Service Program: QCSTCTL

| Number of cluster interfaces. The number of IP interfaces | Threadsafe: Yes

| used by the node for Cluster Resource Services.

| Offset to first cluster interface entry. The offset from the | The Remove Cluster Node Entry
| beginning of the user space to the first cluster interface entry. | (QcstRemoveClusterNodeEntry) API is used to remove a
| node from a cluster. The node specified will be removed from
| User space name. The name of the user space. | the cluster membership list and will no longer be considered
| a member of the cluster. The Cluster Resource Group
| User space library name. The name of the library in which | (CRG) objects on the node being removed are deleted only if
| the user space resides. No special values are supported for | the node has a status of ACTIVE or if the program that calls
| library name. | this API is running on the node that is being removed.

| The following conditions apply to this API:

| Error Messages
| Ÿ A node can be removed regardless of its status.
| CPF3C1E E | Ÿ If this API is called from a program running on a node
| Required parameter &1 omitted. | with a status of ACTIVE, any node in the cluster can be
| CPF3C21 E | removed.
| Format name &1 is not valid. | Ÿ If this API is called from a program running on a node
| CPF3CF1 E | with a status of INACTIVE or FAILED, only the node
| Error code parameter not valid. | running the API can be removed.
| CPF3CF2 E | Ÿ If all of the nodes in the cluster have a status of NEW,
| Error(s) occurred during running of &1 API. | this API can only be called from a program running on
| CPF9801 E Object &2 in library &3 not found. | the node where the cluster was originally created.
| CPF9802 E Not authorized to object &2 in &3. | Ÿ To remove a node that is not ACTIVE, this API should
| CPF9803 E Cannot allocate object &2 in library &3. | be called from a program running on the node being
| CPF9804 E Object &2 in library &3 damaged. | removed and on a node in the cluster that is ACTIVE.
| CPF9810 E Library &1 not found. | Ÿ There must be more than one node in the membership
| CPF9872 E Program or service program &1 in library &2 | list.
| ended. Reason code &3. | Ÿ If the node being removed is in the recovery domain of
| CPFBB02 E | any CRGs, the node will be eliminated from the recovery
| Cluster &1 does not exist. | domain and the exit program will be called with an action
| CPFBB09 E | code of remove (12).
| Cluster node &1 does not exist in cluster &2. | Ÿ If the node being removed is ACTIVE, Cluster Resource
| CPFBB38 E | Group Exit programs will be called with an action code
| Library name &1 not allowed for this request. | of failover (9) for each CRG that has the node in the
| recovery domain.
| This API operates in an asynchronous mode. See “Cluster
| Remove Cluster Node Entry
| Resource Services APIs Behavior” on page 5-2 for more
| (QcstRemoveClusterNodeEntry) API | information.

| Restriction:
| This API cannot be called from a Cluster Resource
| Group exit program.

6-14 AS/400 System API Reference V4R4

 Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) API

| Authorities and Locks | Reserved: The last 10 characters of results information

| are reserved and must be set to hexadecimal zero.
| This API is shipped with *EXCLUDE public authority. The
| Error code
| program that calls this API must be running under a user
| I/O; CHAR(*)
| profile with *IOSYSCFG special authority.
| The structure in which to return error information. For
| User Queue Authority
| the format of the structure, see “Error Code Parameter”
| *OBJOPR and *ADD
| on page 2-6.
| User Queue Library Authority
| *EXECUTE
| User Queue Lock | RMVN0100 Format
| *EXCLRD
| Offset
| Required Parameter Group | Dec Hex Type Field

| Request handle | 0 0 Char(8) Node id

| OUTPUT; CHAR(16)
| A unique string or handle that identifies this API call. It | Field Descriptions
| is used to associate this call to any responses placed on
| the user queue specified in the results information | Node id. A unique string of characters that identifies a node.
| parameter.

| Cluster name | Usage Notes

| INPUT; CHAR(10)
| Results Information User Queue: Asynchronous
| The name of the cluster from which the node or nodes
| results are returned to a user queue specified by the Results
| will be removed.
| Information parameter of the API. See “Cluster APIs Use of
| Node entry | User Queues” on page 5-2 and “Using Results Information”
| INPUT; CHAR(*) | on page 5-3 for details on how to create the results informa-
| tion user queue, the format of the entries, and how to use
| This parameter contains the information associated with
| the data placed on the queue. The data is sent to the user
| the node which is being removed from the cluster mem-
| queue in the form of a message identifier and the substitution
| bership list. The size of this parameter is implied by the
| data for the message (if any exists). The following identifies
| format name.
| the data sent to the user queue (excluding the message
| Format name | text).
| INPUT; CHAR(8) | CPCBB01 C
| The content and format of the information supplied in the | Cluster Resource Services API &1 completed.
| node entry. The possible format names are: | CPF3CF2 D
| Error(s) occurred during running of &1 API.
| RMVN0100 Node id information | CPFBB09 D
| For more information, see "RMVN0100 Format". | Cluster node &1 does not exist in cluster &2.
| CPFBB24 D
| Results information | Node &1 not participating in &2 protocol.
| INPUT; CHAR(30) | CPFBB2D D
| A library qualified user queue name followed by a | Timeout detected while waiting for a response.
| reserved field. | CPFBB46 D
| Cluster Resource Services internal error.
| Library qualified user queue: A user queue, which exists | CPFBB58 D
| on the node from which the API was called, that | Cluster node &1 cannot removed from cluster
| receives results information after the function has com- | &2.
| pleted on all active nodes in the cluster. See the Usage | CPIBB04 I Cluster node &1 removed from cluster &2.
| Notes section of this API for a description of the data
| that is placed on this queue. This is a 20 character field.
| The first 10 characters contain the user queue name and | Error Messages
| the second 10 characters contain the user queue library | CPF3C1E E
| name. No special values are supported. QTEMP, | Required parameter &1 omitted.
| *LIBL, and *CURLIB are not valid for the library name. | CPF3C21 E
| The attributes of this user queue must be keyed and | Format name &1 is not valid.
| have a domain of user. | CPF3C39 E
| Value for reserved field not valid.

Chapter 6. Cluster Control APIs 6-15

 Start Cluster Node (QcstStartClusterNode) API

| CPF3CF1 E | the use of X.509 digital certificates. If validation is required,

| Error code parameter not valid. | the requesting node and the node being added must have
| CPF3CF2 E | the following installed on the systems:
| Error(s) occurred during running of &1 API.
| Ÿ OS/400 option 34 (Digital Certificate Manager)
| CPF9801 E Object &2 in library &3 not found.
| CPF9802 E Not authorized to object &2 in &3. | Ÿ Cryptographic Access Provider Product (AC1, AC2, or
| CPF9804 E Object &2 in library &3 damaged. | AC3)
| CPF9810 E Library &1 not found.
| The following conditions apply to this API:
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3. | Ÿ The node being started must exist in the cluster mem-
| CPFBB02 E | bership list.
| Cluster &1 deleted from node &2. | Ÿ If all nodes have a status of NEW, this API must be
| CPFBB09 E | called from a program running on the node on which the
| Cluster node &1 does not exist in cluster &2. | cluster was originally created.
| CPFBB26 E | Ÿ The node to be started must be IP reachable (TCP/IP is
| Cluster Resource Services not active or not | active and the INETD server is started).
| responding. | Ÿ The first time a node is started, this API must be called
| CPFBB32 E | from a program running on a node that is ACTIVE.
| Attributes of user queue &1 in library &1 are not | Ÿ Any node that is not ACTIVE can be started from any
| valid. | node in the cluster that is ACTIVE.
| CPFBB39 E | Ÿ This API can be called from a program running on a
| Current user does not have IOSYSCFG special | node that is not ACTIVE only if it had been previously
| authority. | ACTIVE.
| CPFBB44 E | Ÿ If the cluster is partitioned, this API may be used to start
| &1 API cannot be used within a cluster | nodes in the partition running the API.
| resource group exit program.
| This API operates in an asynchronous mode. See “Cluster
| CPFBB46 E
| Resource Services APIs Behavior” on page 5-2 for more
| Cluster Resource Services internal error.
| information.
| CPFBB58 E
| Cluster node &1 cannot removed from cluster | Restriction:
| &2.
| This API cannot be used in a Cluster Resource Group
| exit program.

| Start Cluster Node (QcstStartClusterNode)

| API | Authorities and Locks
| This API is shipped with *EXCLUDE public authority. The
| program that calls this API must be running under a user
| Required Parameter Group:
| profile with *IOSYSCFG special authority.
| 1 Request handle Output Char(16) | User Queue Authority
| 2 Cluster name Input Char(10) | *OBJOPR and *ADD
| 3 Node entry Input Char(*)
| User Queue Library Authority
| 4 Format name Input Char(8)
| 5 Results information Input Char(30)
| *EXECUTE
| 6 Error code I/O Char(*) | User Queue Lock
| *EXCLRD
| Service Program: QCSTCTL

| Threadsafe: Yes | Required Parameter Group

| Request handle
| The Start Cluster Node (QcstStartClusterNode) API is used | OUTPUT; CHAR(16)
| to start Cluster Resource Services on a node in the cluster. | A unique string or handle that identifies this API call. It
| If Cluster Resource Services is successfully started on the | is used to associate this call to any responses placed on
| nodes specified, the status of the node will be set to | the user queue specified in the results information
| ACTIVE. | parameter.

| During the activation of Cluster Resource Services, the allow | Cluster name
| add to cluster (ALWADDCLU) network attribute is checked to | INPUT; CHAR(10)
| see whether the node being added should be part of the | The name of the cluster to which the node belongs.
| cluster and whether to validate the cluster request through

6-16 AS/400 System API Reference V4R4

 Start Cluster Node (QcstStartClusterNode) API

| Node entry | Results Information User Queue: Asynchronous

| INPUT; CHAR(*) | results are returned to a user queue specified by the Results
| The node id to be started. | Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information”
| Format name | on page 5-3 for details on how to create the results informa-
| INPUT; CHAR(8) | tion user queue, the format of the entries, and how to use
| The content and format of the information supplied in the | the data placed on the queue. The data is sent to the user
| node entry array. The possible format names are: | queue in the form of a message identifier and the substitution
| data for the message (if any exists). The following identifies
| STRN0100 Node id information | the data sent to the user queue (excluding the message
| text).
| For more information, see "STRN0100 Format".
| CPCBB01 C
| Results information | Cluster Resource Services API &1 completed.
| INPUT; CHAR(30) | CPF2204 D User profile &1 not found.
| A library qualified user queue name followed by a | CPF3CF2 D
| reserved field. | Error(s) occurred during running of &1 API.
| CPFBB01 D
| Library qualified user queue: A user queue, which exists
| Cluster already exists.
| on the node from which the API was called, that
| CPFBB05 D
| receives results information after the function has com-
| Cluster node &1 cannot be started.
| pleted on all active nodes in the cluster. See the Usage
| CPFBB09 D
| Notes section of this API for a description of the data
| Cluster node &1 does not exist in cluster &2.
| that is placed on this queue. This is a 20 character field.
| CPFBB10 D
| The first 10 characters contain the user queue name and
| Specified cluster interface not defined on this
| the second 10 characters contain the user queue library
| system.
| name. No special values are supported. QTEMP,
| CPFBB12 D
| *LIBL, and *CURLIB are not valid for the library name.
| Cluster node &1 in cluster &2 could not be
| The attributes of this user queue must be keyed and
| started.
| have a domain of user.
| CPFBB19 D
| Reserved: The last 10 characters of results information | Cluster node &1 in cluster &2 already started.
| are reserved and must be set to hexadecimal zero. | CPFBB24 D
| Node &1 not participating in &2 protocol.
| Error code
| CPFBB2D D
| I/O; CHAR(*)
| Timeout detected while waiting for a response.
| The structure in which to return error information. For | CPFBB46 D
| the format of the structure, see “Error Code Parameter” | Cluster Resource Services internal error.
| on page 2-6. | CPFBB54 D
| Node &1 not be added to the cluster &2.
| CPIBB05 I Cluster node &1 started in cluster &2.
| STRN0100 Format
| Offset | Error Messages
| Dec Hex Type Field | CPF3C1E E
| 0 0 Char(8) Node id | Required parameter &1 omitted.
| CPF3C21 E
| Format name &1 is not valid.
| Field Descriptions | CPF3C39 E
| Value for reserved field not valid.
| Node id. A unique string of characters that identifies the | CPF3CF1 E
| node to be started. | Error code parameter not valid.
| CPF3CF2 E
| Error(s) occurred during running of &1 API.
| Usage Notes | CPF9801 E Object &2 in library &3 not found.
| CPF9802 E Not authorized to object &2 in &3.
| CPF9804 E Object &2 in library &3 damaged.
| CPF9810 E Library &1 not found.
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3.

Chapter 6. Cluster Control APIs 6-17

 Start Cluster Node (QcstStartClusterNode) API

| CPFBB02 E | CPFBB39 E
| Cluster &1 does not exist. | Current user does not have IOSYSCFG special
| CPFBB09 E | authority.
| Cluster node &1 does not exist in cluster &2. | CPFBB44 E
| CPFBB19 E | &1 API cannot be used within a cluster
| Cluster node &1 in cluster &2 already started. | resource group exit program.
| CPFBB32 E | CPFBB46 E
| Attributes of user queue &1 in library &1 are not | Cluster Resource Services internal error.
| valid.

6-18 AS/400 System API Reference V4R4

 Cluster Resource Group APIs—Introduction

| Chapter 7. Cluster Resource Group APIs

| contains a copy of a resilient resource. In the
| Cluster Resource Group | case of a data cluster resource group, copies
| APIs—Introduction | of the data are kept current with replication.
| The Cluster Resource Group Manager's (CRGM) function | Replicate Nodes
| within a cluster is to: | Nodes having copies of resilient resources,
| but unable to assume the role of primary or
| Ÿ maintain operationally identical cluster resource group
| backup. A replicate may be changed to a
| (CRGs) on every node of the CRG recovery domain.
| backup through the use of the Change Cluster
| Ÿ call the cluster resource group exit program whenever
| Resource Group API.
| the status of a CRG is changed
| Ÿ coordinate activities performed whenever access points | Some Cluster Control APIs cause Cluster Resource Group
| for CRGs are changed from one node to another. | actions to be taken. For example, an End Cluster Node API
| will cause the End Cluster Resource Group API to be called
| CRGM exists as a part of Cluster Resource Services on
| for all CRGs on the node being ended. In these instances,
| every node of the cluster. As a result, any CRG API may be
| the success indicator returned by the exit program will be
| called on any node in the cluster. Most Cluster Resource
| ignored. The operations will always be considered suc-
| Group Manager APIs have an asynchronous behavior.
| cessful.
| The majority of the Cluster Resource Group API's require
| A cluster resource group has a recovery domain of one or
| that Cluster Resource Services be active. This is necessary
| more nodes. Each node within the recovery domain has two
| to ensure consistency of CRG's across the cluster. Each API
| roles: preferred and current. The two node roles need not be
| indicates whether or not Cluster Resource Services needs to
| the same. When a cluster resource group is initially created,
| be active for the API to complete successfully.
| the preferred and the current roles are the same.
| Cluster Resource Services maintains synchronous copies of
| The current role of a node in the recovery domain is changed
| cluster resource groups (perceptively and operationally iden-
| as a result of operations occurring within the cluster (for
| tical) on all nodes in the group's recovery domain. Whenever
| example nodes ending, nodes starting, and nodes failing).
| a node in the cluster is started, Cluster Resource Services
| The preferred role of a node in the cluster is changed only by
| will copy cluster resource groups to the node being started.
| running the following APIs:
| Only cluster resource groups containing the node being
| started in the recovery domain are copied. | Ÿ Add Node to Recovery Domain
| Ÿ Remove Node from Recovery Domain
| CRGs contain a recovery domain. A Recovery Domain is | Ÿ Change Cluster Resource Group
| that set of cluster nodes which, for a particular cluster
| Changes to the node roles are done independently. The role
| resource group, describes the access points of the cluster
| specified for a node in any of these APIs will be assigned to
| resource group. Each node in the recovery domain is
| both the current and preferred roles of the node. For
| assigned a role that reflects its point of access:
| example, the recovery domain of a cluster resource group
| Primary Node | object has preferred roles of N1-primary, N2-backup1, and
| The current point of access and principal copy | N3-backup2, but the current roles are N1-backup2,
| of a resource. If this node fails, all cluster | N2-primary, and N3-backup1. N4 is being added as
| resource group objects having this node as | backup2. Therefore, the preferred roles of the nodes are
| the primary access point will failover to a | N1-primary, N2-backup1, N3-backup3, and N4-backup2, and
| backup node. | the current roles are N1-backup3, N2-primary, N3-backup1,
| Backup Nodes | and N4-backup2.
| This node will take over the role of primary
| access if the present primary node fails. It

 Copyright IBM Corp. 1998, 1999 7-1

 Cluster Resource Group APIs—Introduction

| Figure 7-1. Nodes role example

| Every CRG has an associated exit program. This exit | restarted on either the same or a different node in the
| program will be called for each of the different action codes | cluster. This is made possible by a Takeover IP Address.
| listed under the Cluster Resource Group Exit Program,
| “Cluster Resource Group Exit Program” on page 8-1. The | A Takover IP Address is a high availability mechanism used
| exit program is called from a separate job using the user | to insulate clients from application server outages. The
| profile supplied when the cluster resource group is created. | concept is to use IP address aliasing (multihoming) to define
| See “Cluster Resource Group Exit Program” on page 8-1, for | a "floating IP address" associated with multiple application
| a description of the conditions that cause the exit program to | servers or hosts. When one application server in a cluster
| be called. | fails, another cluster node can assume the responsibilities of
| the application server without requiring the user to recon-
| The user exit program will be restricted from invoking some | figure the clients.
| of the APIs. Each API specifies the user exit program
| restrictions. | To support address aliasing, application groups contain an IP
| address resource and a recovery domain. When the applica-
| CRG objects are either data resiliency (type-1) or application | tion or the node running the application fails, Cluster
| resiliency (type-2). Data resiliency represents multiple copies | Resource Services initiates a failover of the group using the
| of data maintained on more than one node in a cluster. | IP address to the node assigned the current role of first
| Application resiliency enables an application (program) to be | backup.

7-2 AS/400 System API Reference V4R4

 Cluster Resource Group APIs—Introduction

| The address specified for the takeover IP address must not | 530 End Cluster Resource Group Pending. Resiliency
| be used for any other purposes. Cluster Resource Services | for the cluster resource group is in the process of
| will not allow certain API operations to complete successfully | ending. If the exit program is successful, the status is
| if the IP address is in use. This restriction ensures that the | set to Inactive. If the exit program fails and the ori-
| structures being created will provide application resilience. | ginal state cannot be recovered, Indoubt.
| 540 Initialize Pending. A Cluster Resource Group is being
| created and is in the process of being initialized. If
| Summary of Cluster Resource Group | the exit program is successful, the status is set to
| Status | Inactive. If the exit program fails, the cluster resource
| group will be deleted from all nodes.
| Each cluster resource group has a status associated with it.
| 550 Remove Node Pending. A node is in the process of
| The status of the cluster resource group may govern the
| being removed from the recovery domain of the
| behavior of a particular API call. The possible values are:
| cluster resource group. If the exit program is suc-
| 10 Active. The objects or application of the cluster | cessful, the status is reset to the value at the time the
| resource group are currently resilient. | API was called. If the exit program fails and the ori-
| 20 Inactive. The Cluster resource group contains a | ginal state cannot be recovered, the status is set to
| recovery domain but the resources are not resilient. | Indoubt.
| 30 Indoubt. The information contained within the cluster | 560 Start Cluster Resource Group Pending. Resiliency
| resource group object may not be accurate. This | is in the process of starting for the cluster resource
| status occurs when an exit program is called with an | group. If the exit program is successful, the status is
| action of undo and fails to complete successfully. | set to Active If the exit program fails and the original
| 40 Restored. The cluster resource group object was | state cannot be recovered, the status is set to
| restored on this node and has not been copied to the | Indoubt.
| other nodes in the recovery domain. When Cluster | 570 Switch Over Pending. The Initiate Switch Over API
| Resource Services is started on this node, the cluster | was called, a failure of a cluster resource group
| resource group will be synchronized with the other | occurred, or a node failed, causing a switch over or
| nodes in the recovery domain and its status set to | failure to begin. The first backup node is in the
| inactive. | process of becoming the primary node. If the exit
| 500 Add Node Pending. A new node is in the process of | program is successful, the status is set to Active. If
| being added to the recovery domain of a cluster | the exit program fails and the original state cannot be
| resource group. If the exit program is successful the | recovered, the status is set to Indoubt.
| status is reset to its value at the time the API was | 580 Delete Command Pending. Cluster resource group
| called. If the exit program fails and the original state | object is being deleted by the Delete Cluster Resource
| cannot be recovered, the status is set to Indoubt. | Group (DLTCRG) CL command. The Cluster resource
| 510 Delete Pending. Cluster resource group object is in | group object is only removed from the node running
| the process of being deleted. When the exit program | the command. This is not a distributed request. At the
| completes the cluster resource group is deleted from | completion of the command, the cluster resource
| all nodes in the recovery domain. | group is deleted from the node.
| 520 Change Pending. The Cluster Resource Group is in
| the process of being changed. If the exit program is | The relationship between the cluster resource group status
| successful the status is reset to the value at the time | and the Cluster Resource Group APIs is summarized in the
| the API was called. If the exit program fails and the | following table. See the Cluster Resource Group APIs for
| original state cannot be recovered, status is set to | additional details on the cluster resource group status.
| Indoubt.

| Figure 7-2 (Page 1 of 2). Summary of cluster resource group statuses for each Cluster Resource Group Manager API
| Cluster Resource Original status Status while exit Action Code Status - exit Status - exit
| Group API program running program suc- program failure
| cessful
| Add Node to Ÿ Active Add Node Pending 11 - Add Node original status Indoubt
| Recovery Domain – Adding primary - Error
| – Adding backup or replicate
| Ÿ Inactive
| Ÿ Indoubt
| Ÿ Restored - ERROR
| Ÿ Any pending status - ERROR

Chapter 7. Cluster Resource Group APIs 7-3

 Cluster Resource Group APIs—Introduction

| Figure 7-2 (Page 2 of 2). Summary of cluster resource group statuses for each Cluster Resource Group Manager API
| Cluster Resource Original status Status while exit Action Code Status - exit Status - exit
| Group API program running program suc- program failure
| cessful
| Change Cluster If changing node to primary or changing IP take- Change Pending 13 - Change original status Indoubt
|| Resource Group over address:
Note: Only call exit
| Ÿ Active -- ERROR program for
| Ÿ Inactive changing node role
| Ÿ Indoubt in recovery domain.
| Ÿ Restored - ERROR
| Ÿ Any pending status - ERROR
| All other changes:
| Ÿ Active
| Ÿ Inactive
| Ÿ Indoubt
| Ÿ Restored - ERROR
| Ÿ Any pending status - ERROR
| Create Cluster N/A Initialize Pending 1 - Initialize Inactive *CRG deleted
| Resource Group
| Delete Cluster Ÿ Active -- ERROR Delete Pending 7 - Delete *CRG deleted *CRG deleted**
|| Resource Group Ÿ Inactive
** Indoubt if Cluster
|| Ÿ Indoubt
Resource Services
|| Ÿ Restored
fails
| Ÿ Any pending status - ERROR
| End Cluster Ÿ Active End Cluster 4 - End Inactive Indoubt
| Resource Group Ÿ Inactive -- ERROR Resource Group
| Ÿ Indoubt Pending
| Ÿ Restored -- ERROR
| Ÿ Any pending status - ERROR
| Initiate Switchover Ÿ Active Switch Over Pending 10 - Switchover Active Indoubt
|| Ÿ Inactive -- ERROR
Note: If cluster
|| Ÿ Indoubt -- ERROR
resource group
|| Ÿ Restored -- ERROR
Type-2, exit program
|| Ÿ Any pending status - ERROR
called again with
| action Start.
| List Cluster Any None N/A Not changed Not changed
| Resource Group
| List Cluster Any None N/A Not changed Not changed
| Resource Group
| Information
| Remove Node Ÿ Active Remove Node 12 - Remove Node original status Indoubt
| From Recovery – Removing primary - Error Pending
| Domain – Removing backup or replicate
| Ÿ Inactive
| Ÿ Indoubt
| Ÿ Restored -- ERROR
| Ÿ Any pending status - ERROR
| Start Cluster Ÿ Active -- ERROR Start Cluster 2 - Start Active Indoubt
| Resource Group Ÿ Inactive Resource Group
| Ÿ Indoubt Pending
| Ÿ Restored -- ERROR
| Ÿ Any pending status - ERROR

| The following APIs are provided: | Program to disable the resilience of the
| objects or application.
| Add Node To Recovery Domain
| (QcstAddNodeToRcvyDomain) | Initiate Switch Over (QcstInitiateSwitchOver)
| changes the current recovery domain of a
| adds a new node to the recovery domain of
| cluster resource group by making the primary
| an existing cluster resource group.
| node the last backup node and first backup
| Change Cluster Resource Group
| node the primary node.
| (QcstChangeClusterResourceGroup)
| changes some of the attributes of a cluster
| List Cluster Resource Groups
| resource group.
| (QcstListClusterResourceGroups)
| generates a list of cluster resource groups and
| Create Cluster Resource Group
| descriptive information about them.
| (QcstCreateClusterResourceGroup)
| creates a cluster resource group object.
| List Cluster Resource Group Information
| Delete Cluster Resource Group | (QcstListClusterResourceGroupIn)
| returns the contents of a cluster resource
| (QcstDeleteClusterResourceGroup)
| group object.
| deletes a cluster resource group.
| End Cluster Resource Group | Remove Node From Recovery Domain
| (QcstEndClusterResourceGroup) | (QcstRemoveNodeFromRcvyDomain)
| removes a node from the recovery domain of
| calls the Cluster Resource Group Exit
| an existing cluster resource group.

7-4 AS/400 System API Reference V4R4

 Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API

| Start Cluster Resource Group | After these actions have been taken, returning the failed
| (QcstStartClusterResourceGroup) | nodes to the cluster becomes much more difficult. Thus,
| calls the Cluster Resource Group Exit | these actions should be taken only when the failed node will
| Program to enable resilience for the objects or | be unavailable for an extended period of time. For example,
| application. | a primary site loss.
| When a partition is detected, each partition is designated as
| a primary or secondary partition for each CRG defined in the
| cluster. The primary partition contains the node that has the | Add Node To Recovery Domain
| current node role of primary. All other partitions are sec- | (QcstAddNodeToRcvyDomain) API
| ondary. The primary partitions may not be the same for all
| CRGs. The restrictions for each API are:
| Add Node to Recovery Domain | Required Parameter Group:
| Allowed only in a primary partition.
| 1 Request handle Output Char(16)
| Change Cluster Resource Group | 2 Cluster name Input Char(10)
| Allowed only in a primary partition. | 3 Cluster Resource Group Input Char(10)
| Create Cluster Resource Group | name
| Not allowed in any partition. | 4 Node id Input Char(8)
| Delete Cluster Restore Group | 5 Node role Input Binary(4)
| Allowed in any partition, but only affects parti- | 6 Results information Input Char(30)
| tion running the API. | 7 Error code I/O Char(*)
| End Cluster Resource Group
| Service Program: QCSTCRG1
| Allowed only in a primary partition.
| Initiate Switch Over | Threadsafe: Yes
| Allowed only in a primary partition.
| List Cluster Resource Groups
| Allowed in any partition. | The Add Node To Recovery Domain API is used to add a
| List Cluster Resource Group Information | new node to the recovery domain of an existing cluster
| Allowed in any partition. | resource group. A node can only be added as a primary
| Remove Node from Recovery Domain | node if the Cluster Resource Group has a status of Inactive
| Allowed only in a primary partition. | (20). If the Cluster Resource Group has a status of
| Start Cluster Resource Group. | Active(10), a node can be added as either a backup or a rep-
| Allowed only in a primary partition. | licate. This API causes the preferred and current roles of all
| nodes in the recovery domain to be updated.
| By applying these restrictions, CRGs can be resynchronized
| when the cluster is no longer partitioned. As nodes rejoin the | This API will:
| cluster from a partitioned status, the version of the CRG in
| the primary partition will be copied to nodes in a secondary | 1. Call the Cluster Resource Group exit program with the
| partition. | action code of Add Node (11). on all active nodes in the
| recovery domain. The cluster resource group status is
| On occasion, a partition condition may be reported incorrectly | set to Add Node Pending(500).
| and one or more nodes may have actually failed. If one of | 2. Reset the cluster resource group status to the value at
| these failed nodes has the current role of primary for a CRG, | the time the API was called if the exit program is suc-
| special recovery actions are required in order to assign the | cessful.
| primary node role to a node in a secondary partition. In the | 3. Set the cluster resource group status to Indoubt(30) if
| secondary partition: | the exit program fails and the original state of the cluster
| resource group cannot be recovered.
| 1. Use the Delete Cluster Resource Group API to delete
| 4. Assign the added node the specified role.
| any CRGs from the secondary partition.
| 5. Add a TCP interface for the takeover IP address for a
| 2. Use the Remove Cluster Node API to remove failed
| cluster resource group Type-2. If the takeover IP
| nodes from the cluster. This will eliminate the partition
| address can't be added, this request fails.
| condition.
| 3. Use the Create Cluster Resource Group API to recreate | To change the role of the added node, use the Change
| the CRGs deleted in step 1. When creating the CRGs, | Cluster Resource Group API after this API completes suc-
| specify a recovery domain that assigns the primary node | cessfully. For additional information see “Change Cluster
| role to a node in the secondary partition. | Resource Group (QcstChangeClusterResourceGroup) API”
| 4. Make any necessary changes to the replication of the | on page 7-8.
| information.
| 5. Use the Start Cluster Resource Group API to indicate | To remove a node from the recovery domain use the
| that resilience for the CRG is enabled. | Remove Node From Recovery Domain API. For additional

Chapter 7. Cluster Resource Group APIs 7-5

 Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API

| information see “Remove Node From Recovery Domain | is used to associate this call to any responses placed on
| (QcstRemoveNodeFromRcvyDomain) API” on page 7-31. | the user queue specified in the results information
| parameter.
| This API has the following requirements:
| Cluster name
| 1. Cluster Resource Services must be active on the node
| INPUT; CHAR(10)
| processing the request.
| 2. At least one active node in the recovery domain. | The name of the cluster in which the Cluster Resource
| 3. The node being added must be active in the cluster. | Group exists.
| 4. The Cluster Resource Group exit program must exist on
| Cluster Resource Group name
| each node in the recovery domain, including the node
| INPUT; CHAR(10)
| being added.
| 5. The node being added must not already be a member of | The name of the cluster resource group that will have
| the cluster resource group recovery domain. | the new node added to its recovery domain.
| 6. The node being added may become the primary, if the
| Node id
| CRG is Inactive(20). The old primary becomes the last
| INPUT; CHAR(8)
| backup.
| 7. The user profile running the exit program must have | A unique string of characters that identifies the node
| *USE authority for the CRG. | being added to the recovery domain of the cluster
| resource group specified. The node specified must be in
| This API operates in an asynchronous mode. See “Cluster | the cluster and must be unique in the recovery domain
| Resource Services APIs Behavior” on page 5-2 for more | of the cluster resource group specified.
| information.
| Node role
| Restriction: | INPUT; BINARY(4)

| This API cannot be called from a Cluster Resource | Indicates the role of the node.
| Group exit program.
| 0 Primary. The new node is to be the
| primary node. The cluster resource group
| Authorities and Locks | must have a status of Inactive (20).
| ≥1 Backup. The number indicates the backup
| This API is shipped with *EXCLUDE public authority. The | order. If there is already a node with the
| program that calls this API must be running under a user | same backup order, the new node is
| profile with *IOSYSCFG special authority. | inserted in the position requested. At the
| Cluster Resource Group Authority | completion of the request the nodes with
| *CHANGE | backup roles will be sequentially renum-
| Cluster Resource Group Library Authority | bered from the first backup to the last.
| *EXECUTE | The first backup will always be 1.
| Cluster Resource Group Lock | -1 Replicate. Replicate nodes are not
| *EXCL | ordered.
| Exit Program Authority | -2 Last Backup. The new node id will be
| *EXECUTE | added as the last backup.
| Exit Program Library Authority | Results information
| *EXECUTE | INPUT; CHAR(30)
| User Profile Authority
| *USE | This parameter identifies a qualified user queue field and
| is followed by a reserved field.
| Request Information User Queue Authority
| *OBJOPR, *ADD | Qualified user queue: Completion information is
| Request Information User Queue Library Authority | returned to this user queue, which exists on the node
| *EXECUTE | from which the API was called, after the function has
| Request Information User Queue Lock | completed on all active nodes in the cluster. See the
| *EXCLRD | Usage Notes section of this API for a description of the
| data that is placed on this queue. This is a 20-character
| field. The first 10 characters contain the user queue
| Required Parameter Group | name, and the second 10 characters contain the user
| queue library name. No special values are supported.
| Request handle
| QTEMP, *LIBL, *CURLIB are not valid library names.
| OUTPUT; CHAR(16)
| The attributes of this user queue must be keyed and
| A unique string or handle that identifies this API call. It | have a domain of user.

7-6 AS/400 System API Reference V4R4

 Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API

| Reserved: The last 10 characters of the 30-character | CPFBB35 D

| results information are reserved. Each character in this | The user profile name &1 is not valid for this
| field must be set to hexadecimal zero. | request.
| CPFBB38 D
| Error code
| Library name &1 not allowed on this request.
| I/O; CHAR(*)
| CPFBB39 D
| The structure in which to return error information. For | Current user does not have IOSYSCFG special
| the format of the structure, see “Error Code Parameter” | authority.
| on page 2-6. | CPFBB46 D
| Cluster Resource Service internal error.
| CPFBB52 D
| Usage Notes | Cluster node &1 could not be added to cluster
| resource group &2.
| Results Information User Queue: Asynchronous
| CPIBB10 D Cluster Resource Group exit program &1 in
| results are returned to a user queue specified by the Results
| library &2 on node &3 failed.
| Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information”
| on page 5-3 for details on how to create the results informa- | Error Messages
| tion user queue, the format of the entries, and how to use
| the data placed on the queue. The data is sent to the user | Messages that are delivered through the error code param-
| queue in the form of a message identifier and the substitution | eter are listed here. The data (messages) sent to the results
| data for the message (if any exists). The following identifies | information user queue are listed in the Usage Notes above.
| the data sent to the user queue (excluding the message | CPF24B4 E Severe error while addressing parameter list.
| text). | CPF3C1E E
| CPCBB01 C | Required parameter &1 omitted.
| Cluster Resource Services API &1 completed. | CPF3C39 E
| CPF2204 D User profile &2 not found. | Value for reserved field not valid.
| CPF3CF2 D | CPF3CF1 E
| Error(s) occurred during running of &1 API. | Error code parameter not valid.
| CPF9801 D Object &2 in library &3 not found. | CPF3CF2 E
| CPF9802 D Not authorized to object &2 in &3. | Error(s) occurred during running of &1 API.
| CPF9803 D Cannot allocate object &2 in library &3. | CPF9801 E Object &2 in library &3 not found.
| CPF9804 D Object &2 in library &3 damaged. | CPF9802 E Not authorized to object &2 in &3.
| CPF9810 D Library &1 not found. | CPF9803 E Cannot allocate object &2 in library &3.
| CPFBB09 D | CPF9804 E Object &2 in library &3 not found.
| Node Id &1 does not exist in cluster &2. | CPF9810 E Library &1 not found.
| CPFBB0A D | CPF9872 E Program or service program &1 in library &2
| Cluster node &1 in cluster&2 not active. | ended. Reason code &3.
| CPFBB0B D | CPFBB02 E
| Request using takeover IP address &1 failed. | Cluster &1 does not exist.
| CPFBB0F D | CPFBB09 E
| Cluster resource group &1 does not exist in | Node &1 does not exist in cluster &2.
| cluster &2. | CPFBB0A E
| CPFBB17 D | Cluster node &1 in cluster&2 not active.
| &1 API cannot be processed in cluster &2. | CPFBB0F E
| CPFBB18 D | Cluster resource group &1 does not exist in
| Request &1 not allowed for cluster resource | cluster &2.
| group &2. | CPFBB26 E
| CPFBB2C D | Cluster Resource Services not active or not
| Attributes of exit program &1 in library &2 are | responding.
| not valid. | CPFBB29 E
| CPFBB2D D | Node role value &1 not valid.
| Timeout detected while waiting for a response. | CPFBB2C E
| CPFBB2E D | Attributes of exit program &1 in library &2 are
| Job submission failed for cluster resource group | not valid.
| &1 in cluster &2. | CPFBB32 E
| CPFBB32 D | Attributes of user queue &1 in library &2 are not
| Attributes of user queue &1 in library &2 are not | valid.
| valid.

Chapter 7. Cluster Resource Group APIs 7-7

 Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

| CPFBB39 E | To remove a node from the recovery domain use the

| Current user does not have IOSYSCFG special | Remove Node From Recovery Domain API. See “Remove
| authority. | Node From Recovery Domain
| CPFBB44 E | (QcstRemoveNodeFromRcvyDomain) API” on page 7-31.
| &1 API cannot be called from a cluster resource
| group exit program. | This API will:
| CPFBB52 E | Ÿ Call the Cluster Resource Group Exit Program with an
| Cluster node &1 not added to cluster resource | action code of Change (13) on all active nodes in the
| group &2. | recovery domain when either the preferred or current
| role is changed. The cluster resource group status is
| set to Change Pending (520). If the exit program com-
| Change Cluster Resource Group | pletes successfully, the cluster resource group status is
| (QcstChangeClusterResourceGroup) API | reset to its value at the time the API was called. If the
| exit program fails and the cluster resource group cannot
| be restored to its original condition, the cluster resource
| Required Parameter Group: | group status is set to Indoubt (30).
| Ÿ Remove the current address and add the new address
| 1 Request handle Output Char(16) | when the IP takeover address is changed. If either the
| 2 Cluster name Input Char(10) | add or remove address function fails, the API will fail.
| 3 Cluster Resource Group Input Char(10) | Ÿ Change the Cluster Resource Group without calling the
| group name | exit program if neither role is changed.
| 4 Cluster Resource Group Input Char(*)
| Ÿ Change the name to be used for batch jobs submitted
| description information
| 5 Format name Input Char(8) | by Cluster Resource Group. If the cluster resource group
| 6 Text description Input Char(50) | status is Active (10), batch jobs already submitted will
| 7 Results information Input Char(30) | not be changed. Any jobs submitted after the change will
| 8 Error code I/O Char(*) | use the new name.

| Service Program: QCSTCRG1 | This API requires:

| 1. Cluster Resource Services must be active on the node
| Threadsafe: Yes
| processing the request.
| 2. A cluster resource group must have a status of Inactive
| The Change Cluster Resource Group API changes some of | (20) or Indoubt (30) to designate a new primary node.
| the attributes of a cluster resource group. This API will not | 3. The exit program exist on all nodes in the recovery
| cause the exit program to be called with an action code of | domain when the Cluster Resource Group Exit Program
| switchover (10). | is changed.
| 4. At least one active node in the recovery domain.
| Changing the node role to primary or changing the IP take- | 5. The user profile running the exit program have *USE
| over address can only be done when the cluster resource | authority for the CRG.
| group is Inactive (20) or Indoubt (30). If the cluster resource
| group is Active, the Initiate SwitchOver API can be used to | This API operates in an asynchronous mode. See “Cluster
| assign the primary role to the first backup node. For infor- | Resource Services APIs Behavior” on page 5-2 for more
| mation about the Initiate SwitchOver API, see “Initiate Switch | information.
| Over (QcstInitiateSwitchOver) API” on page 7-22.
| Restriction:
| The following fields may be changed without causing the | This API cannot be called from a Cluster Resource
| Cluster Resource Group exit program to be called: | Group Exit Program.
| Ÿ text description
| Ÿ exit program data
| Ÿ user profile
| Authorities and Locks
| Ÿ takeover IP address | This API is shipped with *EXCLUDE public authority. The
| Ÿ job name | program that calls this API must be running under a user
| Ÿ allow application restart | profile with *IOSYSCFG special authority.
| Ÿ number of restarts
| Ÿ the Cluster Resource Group Exit Program | Cluster Resource Group Authority
| *CHANGE
| To add a node to the recovery domain use the Add Node to | Cluster Resource Group Library Authority
| Recovery Domain API. See “Add Node To Recovery | *EXECUTE
| Domain (QcstAddNodeToRcvyDomain) API” on page 7-5. | Cluster Resource Group Group Lock
| *EXCL

7-8 AS/400 System API Reference V4R4

 Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

| Exit Program Authority | Results information

| *EXECUTE | INPUT; CHAR(30)
| Exit Program Library Authority
| This parameter identifies a qualified user queue field and
| *EXECUTE
| is followed by a reserved field.
| User Profile Authority
| *USE | Qualified user queue: Completion information is
| returned to this user queue, which exists on the node
| Request Information User Queue Authority
| from which the API was called, after the function has
| *OBJOPR, *ADD
| completed on all active nodes in the cluster. See the
| Request Information User Queue Library Authority
| Usage Notes section of this API for a description of the
| *EXECUTE
| data that is placed on this queue. This is a 20-character
| Request Information User Queue Lock
| field. The first 10 characters contain the user queue
| *EXCLRD
| name, and the second 10 characters contain the user
| queue library name. No special values are supported.
| Required Parameter Group | QTEMP, *LIBL, *CURLIB are not valid library names.
| The attributes of this user queue must be keyed and
| Request handle | have a domain of user.
| OUTPUT; CHAR(16)
| Reserved: The last 10 characters of the 30-character
| A unique string or handle that identifies this API call. It | results information are reserved. Each character in this
| is used to associate this call to any responses placed on | field must be set to hexadecimal zero.
| the user queue specified in the results information
| parameter. | Error code
| I/O; CHAR(*)
| Cluster name
| INPUT; CHAR(10) | The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter”
| The name of the cluster to which the Cluster Resource | on page 2-6.
| Group belongs.

| Cluster Resource Group name | Data Resiliency (RGDC0100 Format)

| INPUT; CHAR(10)
| The name of the cluster resource group which is to be | Offset
| changed. | Dec Hex Type Field
| Cluster resource group description information | 0 0 CHAR(10) Cluster Resource Group
| INPUT; CHAR(*) | exit program

| Detailed information about the cluster resource group. | 10 A CHAR(10) Cluster Resource Group
| exit program library name
| For more information, see “Data Resiliency (RGDC0100
| Format).” | 20 14 CHAR(8) Cluster Resource Group
| exit program format name
| Format name
| 28 1C CHAR(10) User profile
| INPUT; CHAR(8)
| 38 26 CHAR(10) Action for recovery
| The content and format of the cluster resource group | domain array
| information. The possible format names are:
| 48 30 CHAR(256) Exit program data
| RGDC0100 This format describes the cluster resource | 304 130 BINARY(4) Offset to recovery domain
| group type 1 (data resiliency). | array
| RGDC0200 This format describes the cluster resource
| 308 134 BINARY(4) Number of nodes in
| group type 2 (application resiliency). | recovery domain
| For more information, see “Data Resiliency (RGDC0100 | 312 138 Array (*) of Recovery domain array
| Format)” and “Application Resiliency (RGDC0200 | CHAR(12)
| Format)” on page 7-10. | These fields CHAR(8) Node ID
| repeat, in the
| Text description | BINARY(4) Node Role
| order listed,
| INPUT; CHAR(50) | for each node
| This text briefly describes the cluster resource group. | in the
| This must be left justified. The following special value | recovery
| can be used: | domain.

| *SAME The current text description is not

| changed. This must be left justified.

Chapter 7. Cluster Resource Group APIs 7-9

 Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

| Application Resiliency (RGDC0200 Format) | 1 Attempt to restart the application on the same
| node. The cluster resource group exit
| program will be called with an action code of
| Offset
| restart (3). If the application cannot be
| Dec Hex Type Field | restarted in the specified maximum number of
| 0 0 CHAR(10) Cluster resource group | attempts, the cluster resource group exit
| exit program | program will be called with an action code of
| 10 A CHAR(10) Cluster resource group
| failover (9).
| exit program library name | -1 Allow application restart is not changed.
| 20 14 CHAR(8) Cluster resource group | Cluster resource group exit program format name. The
| exit program format name | contents and format of the cluster resource group exit
| 28 1C CHAR(10) User profile | program information. The format name supported is:
| 38 26 CHAR(10) Action for recovery | EXTP0100 Exit program information
| domain array
| 48 30 CHAR(256) Exit program data | Cluster resource group exit program name. The name of
| exit program that is used to handle action codes that are
| 304 130 BINARY(4) Offset to recovery domain
| passed to it. The action codes are described in “Cluster
| array
| Resource Group Exit Program” on page 8-1. The following
| 308 134 BINARY(4) Number of nodes in | special value can be used:
| recovery domain
| *SAME The current exit program is not changed. This
| 312 138 CHAR(16) Take over IP address
| must be left justified.
| 328 148 CHAR(10) Job name
| 338 152 CHAR(2) Reserved
| Cluster resource group exit program library name. The
| name of the library where the exit program exists. The
| 340 154 BINARY(4) Allow application restart | special value *CURLIB or *LIBL may not be used for the
| 344 158 BINARY(4) Number of restarts | library name. QTEMP is not a valid library name.
| 348 15C Array (*) of Recovery domain array
| CHAR(12)
| Exit program data. 256 bytes of data that is passed to the
| cluster resource group exit program when it is called. This
| These fields CHAR(8) Node ID | parameter may contain any scalar data except pointers. For
| repeat, in the
| BINARY(4) Node role | example, it can be used to provide state information. This
| order listed,
| for each node | data will be stored with the specified Cluster Resource Group
| in the | and copied to all nodes in the recovery domain. Pointers in
| recovery | this area will not resolve correctly on all nodes and should
| domain. | not be placed in the data. See “Cluster Resource Group Exit
| Program” on page 8-1 for information about the cluster
| resource group exit program. The data specified will replace
| Field Descriptions | the existing exit program data stored with the cluster
| resource group, if the API completes successfully. The fol-
| Action for recovery domain array. Indicates which node | lowing special value can be used:
| role in the recovery domain is being changed. The special
| *SAME The exit program data is not changed. This
| values used are:
| must be left justified.
| *SAME Neither node role is changed.
| *CHGPREFER | Job name The name given the batch job that is submitted by
| The PREFFERED node role in the recovery | the Cluster Resource Group. This job will call the Cluster
| domain will change. | Resource Group Exit Program with the action code gener-
| *CHGCURREN | ated by the API being used. If this field is blank, the job
| The CURRENT node role in the recovery | name will be the value of the job description found in the
| domain will change. | user profile. Valid special values are:
| *SAME The job name is not changed. This must be
| Allow application restart. Attempt to restart an application
| left justified.
| if the cluster resource group exit program fails. Possible
| *JOBD The job name in the job description for the
| values are:
| specified user profile will be used. This must
| 0 Do not attempt to restart the application. The | be left justified.
| cluster resource group exit program is called
| with an action code of failover (9). | Node ID. A unique string of chararcters that identifies a
| node that is participating in the recovery domain of the speci-
| fied cluster resource group. The node specified must be

7-10 AS/400 System API Reference V4R4

 Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

| active in the cluster, and it must be unique in the recovery | The nodes do not have to be arranged in any particular order
| domain of the specified cluster resource group. | in the array. They could be in the array as listed below and
| have the same result.
| Node role. The role the node has in the recovery domain.
| Node Role
| A role must be defined for each node in the recovery
| ----- ----
| domain. A node can have one of three roles: primary, | NodeB 2 <-- backup #2
| backup, or replicate. Only one node can be designated as | NodeA ð <-- primary
| the primary. Backup nodes are assigned a backup order. | NodeC -1 <-- replicate
| One indicates the first backup, two the second backup, and | NodeD 1 <-- backup #1
| so on. Replicates are not ordered and cannot become a
| primary or backup node unless the Change Cluster Resource | Reserved. Must contain hexadecimal zeroes.
| Group API is used to change its role from replicate to either
| a backup or primary. The following summarizes the valid | Take over IP address. This is the floating IP address that is
| values for this field. | to be associated with an application. This field must be
| represented in dotted decimal format and be a null-
| 0 Primary node. Only one node can have this | terminated string. The following special value can be used:
| value.
| ≥1 Backup node. The backup order is designated | *SAME The takeover IP address is not changed. This
| by increasing value. The values need not be | must be left justified.
| consecutive. No two backup nodes can have | If the value is not *SAME, this API will remove the current IP
| the same value. At the completion of the API, | address and add this IP address to the node. If either the
| Cluster Resource Services will sequence the | add or remove address function fails, the API will fail. The
| backups using consecutive numbers starting | Cluster Resource Group must be Inactive (20) to change this
| with 1. | field.
| -1 Replicate node. All replicates have this value.
| User profile. The name of the user profile under which the
| Number of nodes in the recovery domain. The number of | exit program should process. The user profile must exist on
| nodes in the recovery domain array. This should equal the | all nodes in the recovery domain. The following user profiles
| number of backup nodes plus the number of replicate nodes | are not valid:
| plus one (for the primary node). This must be greater than
| Ÿ QAUTPROF
| or equal to one and equal the number of nodes in the
| Ÿ QCOLSRV
| recovery domain.
| Ÿ QDBSHR
| Number of restarts. Number of times a Cluster Resource | Ÿ QDBSHRDO
| Group Exit Program can be called on a same node before | Ÿ QDIRSRV
| failure occurs. Maximum number of restarts is 3. -1 means | Ÿ QDSNX
| the maximum number of restarts does not change. | Ÿ QDOC
| Ÿ QDTFOWN
| Offset to recovery domain array. The byte offset from the | Ÿ QFNC
| beginning of this table to the array of node information. The | Ÿ QGATE
| value for this field must be 4 byte aligned. | Ÿ QRJE
| Ÿ QMSF
| Recovery domain array. This array identifies the nodes | Ÿ QNETSPLF
| that compose the recovery domain. A role must be defined | Ÿ QNFSANON
| for each node in the recovery domain. Nodes in the | Ÿ QLPAUTO
| recovery domain must be unique. See node role for more | Ÿ QLPINSTALL
| information on primary, backup, and replicate nodes. | Ÿ QSECOFR
| Ÿ QSNADS
| An example: A cluster resource group has four nodes: | Ÿ QSPL
| NodeA, NodeB, NodeC and NodeD. NodeA is the primary. | Ÿ QSPLJOB
| There are two backup nodes: NodeB and NodeD. NodeD is | Ÿ QSYS
| the first backup and NodeB is the second backup. There is | Ÿ QTCP
| one replicate: NodeC. | Ÿ QTFTP
| Node Role | Ÿ QTSTRQS
| ----- ----
| The following special value can be used:
| NodeA ð <-- primary
| NodeD 1 <-- backup #1 | *SAME The current user profile is not changed. This
| NodeB 2 <-- backup #2 | must be left justified.
| NodeC -1 <-- replicate

| Usage Notes

Chapter 7. Cluster Resource Group APIs 7-11

 Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

| Results Information User Queue: Asynchronous | Error Messages

| results are returned to a user queue specified by the Results
| Information parameter of the API. See “Cluster APIs Use of | Messages that are delivered through the error code param-
| User Queues” on page 5-2 and “Using Results Information” | eter are listed here. The data (messages) sent to the results
| on page 5-3 for details on how to create the results informa- | information user queue are listed in the Usage Notes above.
| tion user queue, the format of the entries, and how to use | CPF2204 E User profile &1 not found.
| the data placed on the queue. The data is sent to the user | CPF24B4 E Severe error while addressing parameter list.
| queue in the form of a message identifier and the substitution | CPF3C1E E
| data for the message (if any exists). The following identifies | Required parameter &1 omitted.
| the data sent to the user queue (excluding the message | CPF3C21 E
| text). | Format name &1 is not valid.
| CPCBB01 C | CPF3C29 E
| Cluster Resource Services API &1 completed. | Object name &1 is not valid.
| CPF2204 D User profile &1 not found. | CPF3C39 E
| CPF3CF2 D | Value for reserved field not valid.
| Error(s) occurred during running of &1 API. | CPF3CF1 E
| CPF9801 D Object &2 in library &3 not found. | Error code parameter not valid.
| CPF9802 D Not authorized to object &2 in &3. | CPF3CF2 E
| CPF9803 D Cannot allocate object &2 in library &3. | Error(s) occurred during running of &1 API.
| CPF9804 D Object &2 in library &3 damaged. | CPF9801 E Object &2 in library &3 not found.
| CPF9810 D Library &1 not found. | CPF9802 E Not authorized to object &2 in &3.
| CPFBB0A D | CPF9803 E Cannot allocate object &2 in library &3.
| Cluster node &1 in cluster &2 not active. | CPF9804 E Object &2 in library &3 damaged.
| CPFBB0B D | CPF9810 E Library &1 not found.
| Request using takeover IP address &1 failed. | CPF9872 E Program or service program &1 in library &2
| CPFBB0F D | ended. Reason code &3.
| Cluster resource group &1 does not exist in | CPFBB02 E
| cluster &2. | Cluster &1 does not exist.
| CPFBB17 D | CPFBB09 E
| &1 API cannot be processed in cluster &2. | Node Id &1 is not a member of Cluster &2.
| CPFBB18 D | CPFBB0A E
| Request &1 is not allowed for cluster resource | Cluster node &1 in cluster &2 not active.
| group &2. | CPFBB0F E
| CPFBB2C D | Cluster resource group &1 does not exist in
| Attributes of exit program &1 in library &2 are | cluster &2.
| not valid. | CPFBB25 E
| CPFBB2D D | Value &1 specified for recovery domain array
| Timeout detected while waiting for a response. | action is not valid.
| CPFBB2E D | CPFBB26 E
| Job submission failed for cluster resource group | Cluster Resource Services not active or not
| &1 in cluster &2. | responding.
| CPFBB32 D | CPFBB27 E
| Attributes of user queue &1 in library &2 are not | A primary node was not specified for the
| valid. | recovery domain.
| CPFBB35 D | CPFBB28 E
| The user profile name &1 is not valid for this | Cluster node &1 and cluster node &2 have the
| request. | same node role value &3.
| CPFBB38 D | CPFBB29 E
| Library name &1 is not allowed for this request. | Node role value &1 not valid.
| CPFBB39 D | CPFBB2C E
| The current user does not have IOSYSCFG | Attributes of exit program &1 in library &2 are
| special authority. | not valid.
| CPFBB46 D | CPFBB30 E
| Cluster Resource Services internal error. | Take over IP address &1 not part of the TCP/IP
| CPIBB10 D Cluster Resource Group exit program &1 in | subnet.
| library &2 on node &3 failed. | CPFBB31 E
| CPFBB51 D | Value &1 specified for number of restarts not
| Take over IP address &1 already in use by the | valid.
| cluster &3.

7-12 AS/400 System API Reference V4R4

 Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

| CPFBB32 E | identifies a recovery domain. A recovery domain is a set of

| Attributes of user queue &1 in library &2 not | nodes in the cluster that will play a role in recovery. To
| valid. | change attributes of the cluster resource group use the
| CPFBB33 E | Change Cluster Resource Group API.
| Cluster node &1 already exists in recovery
| domain for cluster resource group &4. | This API will:
| CPFBB35 E | Ÿ Create the Cluster Resource Group object on all nodes
| The user profile name &1 is not valid for this | in the recovery domain. The cluster resource group may
| request. | be accessed by a cluster resource group API running on
| CPFBB36 E | any node in the cluster.
| The number of cluster nodes specified for the | Ÿ Provide users a single system image of the Cluster
| recovery domain is not valid. | Resource Group object. That is, any changes made to
| CPFBB37 E | the Cluster Resource Group will be made on all nodes in
| The offset to the recovery domain array is not | the recovery domain.
| valid. | Ÿ Call the Cluster Resource Group Exit Program with an
| CPFBB38 E | action code of Initialize (1) after the cluster resource
| Library name &1 is not allowed for this request. | group has been created on each node in the recovery
| CPFBB39 E | domain. The cluster resource group status will be set to
| Current user does not have IOSYSCFG special | Initialize Pending (540). If the exit program fails, the
| authority. | cluster resource group object is deleted from all nodes in
| CPFBB40 E | the recovery domain.
| The value &1 specified for the allow application | Ÿ If the exit program is successful, the cluster resource
| restarts parameter is not valid. | group status is set to Inactive (20). To change the
| CPFBB43 E | cluster resource group status to Active (10), use the
| Invalid format name &1 for cluster resource | Start Cluster Resource Group API, “Start Cluster
| group teyp &2. | Resource Group (QcstStartClusterResourceGroup) API”
| CPFBB44 E | on page 7-33 for more information.
| &1 API cannot be called from a cluster resource
| group exit program. | This API requires:
| CPFBB51 E
| 1. Cluster Resource Services must be active on the node
| Take over IP address &1 already in use by the
| processing the API request.
| cluster &3.
| 2. All nodes in the recovery domain be in the cluster with a
| TCP1901 E Internet address &1 not valid.
| status of Active.
| 3. The Cluster Resource Group Exit Program must exist all
| nodes in the recovery domain. It must have the same
| Create Cluster Resource Group | name and be in the same library on each node.
| (QcstCreateClusterResourceGroup) API | 4. Each node specified only once in the recovery domain.
| 5. For the specified takeover IP address, all nodes in the
| recovery domain for a cluster resource group type-2 be
| Required Parameter Group: | in the same subnet (network address) and the subnet
| defined on all nodes in the recovery domain.
| 1 Request handle Output Char(16) | 6. A new, unique takeover IP address for all cluster
| 2 Cluster name Input Char(10) | resource group type-2 objects. Cluster Resource Ser-
| 3 Cluster resource group Input Char(10)
| vices will add the takeover IP address on all nodes in
| name
| 4 Cluster resource group Input Binary(4)
| the recovery domain.
| type | 7. The cluster resource group name not used by an
| 5 Cluster resource group Input Char(*) | existing cluster resource group on any node in the
| description information | cluster.
| 6 Format name Input Char(8) | 8. The user profile running the exit program have *USE
| 7 Text description Input Char(50) | authority for the CRG.
| 8 Results information Input Char(30)
| 9 Error code I/O Char(*) | This API operates in an asynchronous mode. See “Cluster
| Resource Services APIs Behavior” on page 5-2 for more
| Service Program: QCSTCRG1
| information.
| Threadsafe: Yes
| Restriction:
| This API cannot be called from a cluster resource group
| The Create Cluster Resource Group API creates a cluster | Exit Program.
| resource group object. The cluster resource group object

Chapter 7. Cluster Resource Group APIs 7-13

 Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

| The cluster resource group name cannot begin with | Cluster Resource Group name
| QCST. | INPUT; CHAR(10)
| Note: For information about the recovery domain, see | The name of the Cluster Resource Group which is to be
| “Cluster Resource Group APIs—Introduction” on page 7-1. | created. The Cluster Resource Group name cannot
| begin with QCST. The cluster resource group object will
| be created in the QUSRSYS library.
| Authorities and Locks
| Cluster Resource Group type
| This API is shipped with *EXCLUDE public authority. The | INPUT; BIN(4)
| program that calls this API must be running under a user
| profile with *IOSYSCFG special authority. The calling user | The type of cluster resource group being created. Valid
| profile is the user profile: | cluster resource group types are:

| Ÿ in use when the API is called | 1 Data resiliency

| Ÿ specified in "cluster resource group description informa- | 2 Application resiliency
| tion" parameter.
| The user profile running the API must be authorized to the | A cluster resource group can contain entries for only one
| results information user queue. | of these types.
| Cluster Resource Group Library Authority | Cluster resource group description information
| *OBJOPR, *ADD, and *READ | INPUT; CHAR(*)
| Cluster Resource Group Lock
| *EXCL | Detailed information about the cluster resource group.
| Invoking User Profile Exit Program Authority | For more information, see “Data Resiliency (RGDI0100
| *EXECUTE | Format)” on page 7-15 and “Application Resiliency
| Invoking User Profile Exit Program Library Authority | (RGDI0200 Format)” on page 7-15.
| *EXECUTE | Format name
| User Profile Authority | INPUT; CHAR(8)
| *USE
| The content and format of the cluster resource group
| Request Information User Queue Authority | information. The possible values for format name are:
| *OBJOPR, *ADD
| Request Information User Queue Library Authority | RGDI0100 This format describes the cluster resource
| *EXECUTE | group type 1 (data resiliency).
| Request Information User Queue Lock | RGDI0200 This format describes the cluster resource
| *EXCLRD | group type 2 (application resiliency).

| Authority to the user profile is checked on all nodes in the | For more information, see “Data Resiliency (RGDI0100
| recovery domain. The cluster resource group object will be | Format)” on page 7-15 and “Application Resiliency
| owned by the user profile in use when the API was called. | (RGDI0200 Format)” on page 7-15.
| Cluster resource group exit program authority applies to the | Text description
| user profile: | INPUT; CHAR(50)
| Ÿ in use at the time the API was called | This text briefly describes the cluster resource group.
| Ÿ used when the Cluster Resource Group exit program is
| run | Results information
| INPUT; CHAR(30)

| Required Parameter Group | This parameter identifies a qualified user queue field and
| is followed by a reserved field.
| Request handle
| Qualified user queue: Completion information is
| OUTPUT; CHAR(16)
| returned to this user queue, which exists on the node
| A unique string or handle that identifies this API call. It | from which the API was called, after the function has
| is used to associate this call to any responses placed on | completed on all active nodes in the cluster. See the
| the user queue specified in the results information | Usage Notes section of this API for a description of the
| parameter. | data that is placed on this queue. This is a 20-character
| field. The first 10 characters contain the user queue
| Cluster name
| name, and the second 10 characters contain the user
| INPUT; CHAR(10)
| queue library name. No special values are supported.
| The name of the cluster which will contain the Cluster | QTEMP, *LIBL, *CURLIB are not valid library names.
| Resource Group. | The attributes of this user queue must be keyed and
| have a domain of user.

7-14 AS/400 System API Reference V4R4

 Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

| Reserved: The last 10 characters of the 30-character

| Offset
| results information are reserved. Each character in this
| field must be set to hexadecimal zero. | Dec Hex Type Field
| 304 130 CHAR(16) Takeover IP address
| Error code
| I/O; CHAR(*) | 320 140 CHAR(10) Job name

| The structure in which to return error information. For | 330 14A CHAR(2) Reserved
| the format of the structure, see “Error Code Parameter” | 332 14C BINARY(4) Allow application restart
| on page 2-6. | 336 150 BINARY(4) Number of restarts

| Data Resiliency (RGDI0100 Format) | 340 154 Array (*) of Recovery domain array
| CHAR(12)

| Offset | These fields CHAR(8) Node id

| repeat, in the
| Dec Hex Type Field | BINARY(4) Node role
| order listed,
| 0 0 CHAR(10) Cluster resource group | for each node
| exit program name | in the
| recovery
| 10 A CHAR(10) Cluster resource group | domain.
| exit program library name
| 20 14 CHAR(8) Cluster resource group
| exit program format name | Field Descriptions
| 28 1C CHAR(10) User profile
| 38 26 CHAR(2) Reserved
| Allow application restart. Attempt to restart an application
| 40 28 CHAR(256) Exit program data
| if the cluster resource group exit program fails. Possible
| 296 128 BINARY(4) Offset to recovery domain | values are:
| array
| 0 Do not attempt to restart the application. The
| 300 12C BINARY(4) Number of nodes in
| cluster resource group exit program is called
| recovery domain
| with an action code of failover (9).
| 304 130 Array (*) of Recovery domain array | 1 Attempt to restart the application on the same
| CHAR(12)
| node. The cluster resource group exit
| These fields CHAR(8) Node id | program will be called with an action code of
| repeat, in the | restart (3). If the application cannot be
| BINARY(4) Node role
| order listed, | restarted in the specified maximum number of
| for each node
| attempts, the cluster resource group exit
| in the
| recovery | program will be called with an action code of
| domain. | failover (9).

| Cluster resource group exit program format name. Indi-

| Application Resiliency (RGDI0200 Format) | cates which format

| Offset | Exit program format name. Indicates which format should

| Dec Hex Type Field
| be used for the Information Given To User parameter on
| the Cluster Resource Group Exit Program when it is called.
| 0 0 CHAR(10) Cluster resource group | This value must be EXTP0100.
| exit program name
| 10 A CHAR(10) Cluster resource group | Cluster resource group exit program library name. The
| exit program library name | name of the library where the exit program exists. The
| 20 14 CHAR(8) Cluster resource group | special value *CURLIB or *LIBL may not be used for the
| exit program format name | library name. QTEMP is not a valid library name.
| 28 1C CHAR(10) User profile | Cluster resource group exit program name. The name of
| 38 26 CHAR(2) Reserved | exit program that is used to handle action codes that are
| 40 28 CHAR(256) Exit program data | passed to it. The action codes are described in “Cluster
| Resource Group Exit Program” on page 8-1.
| 296 128 BINARY(4) Offset to recovery domain
| array | Exit program data. 256 bytes of data that is passed to the
| 300 12C BINARY(4) Number of nodes in | cluster resource group exit program when it is called. This
| recovery domain | parameter may contain any scalar data except pointers. For
| example, it can be used to provide state information. This

Chapter 7. Cluster Resource Group APIs 7-15

 Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

| data will be stored with the specified Cluster Resource Group | recovery domain must be unique. See node role for more
| and copied to all nodes in the recovery domain. Pointers in | information on primary, backup, and replicate nodes.
| this area will not resolve correctly on all nodes and should
| not be placed in the data. See “Cluster Resource Group Exit | An example: A cluster resource group has four nodes:
| Program” on page 8-1 for information about the cluster | NodeA, NodeB, NodeC and NodeD. NodeA is the primary.
| resource group exit program. | There are two backup nodes: NodeB and NodeD. NodeD is
| the first backup and NodeB is the second backup. There is
| Job name The name given the batch job that is submitted. | one replicate: NodeC.
| This is the job that calls the Cluster Resource Group Exit | Node Role
| Program. Valid special values for this field are: | ----- ----
| *JOBD The job name in the job description for the | NodeA ð <-- primary
| specified user profile will be used. This must | NodeD 1 <-- backup #1
| be left justified. | NodeB 2 <-- backup #2
| NodeC -1 <-- replicate
| Node ID. A unique string of chararcters that identifies a
| The nodes do not have to be arranged in any particular order
| node that is participating in the recovery domain of the speci-
| in the array. They could be in the array as listed below and
| fied cluster resource group. The node specified must be
| have the same result.
| active in the cluster, and it must be unique in the recovery
| domain of the specified cluster resource group. | Node Role
| ----- ----
| Node role. The role the node has in the recovery domain. | NodeB 2 <-- backup #2
| A role must be defined for each node in the recovery | NodeA ð <-- primary
| domain. A node can have one of three roles: primary, | NodeC -1 <-- replicate
| backup, or replicate. Only one node can be designated as | NodeD 1 <-- backup #1
| the primary. Backup nodes are assigned a backup order.
| Reserved. Must contain hexadecimal zeroes.
| One indicates the first backup, two the second backup, and
| so on. Replicates are not ordered and cannot become a | Takeover IP address. This is the floating IP address that is
| primary or backup node unless the Change Cluster Resource | to be associated with the application. This field must be
| Group API is used to change its role from replicate to either | represented in dotted decimal format and be a null-
| a backup or primary. The following summarizes the valid | terminated string. The Cluster Resource Services will create
| values for this field. | this IP address on every system in the recovery domain. If
| 0 Primary node. Only one node can have this | the IP address already exists, then this API will fail.
| value.
| ≥1 Backup node. The backup order is designated | User profile. The name of the user profile under which the
| by increasing value. The values need not be | exit program should process. The user profile must exist on
| consecutive. No two backup nodes can have | all nodes in the recovery domain. The following user profiles
| the same value. At the completion of the API, | are not valid:
| Cluster Resource Services will sequence the | Ÿ QAUTPROF
| backups using consecutive numbers starting | Ÿ QCOLSRV
| with 1. | Ÿ QDBSHR
| -1 Replicate node. All replicates have this value. | Ÿ QDBSHRDO
| Ÿ QDIRSRV
| Number of nodes in the recovery domain. The number of | Ÿ QDSNX
| nodes in the recovery domain array. This should equal the | Ÿ QDOC
| number of backup nodes plus the number of replicate nodes | Ÿ QDTFOWN
| plus one (for the primary node). This must be greater than | Ÿ QFNC
| or equal to one and equal the number of nodes in the | Ÿ QGATE
| recovery domain. | Ÿ QRJE
| Ÿ QMSF
| Number of restarts. Number of times an application can be
| Ÿ QNETSPLF
| restarted on the same node before a failover occurs.
| Ÿ QNFSANON
| Maximum number of restarts is 3.
| Ÿ QLPAUTO
| Offset to recovery domain array. The byte offset from the | Ÿ QLPINSTALL
| beginning of this parameter to the Recovery Domain Array | Ÿ QSECOFR
| field. | Ÿ QSNADS
| Ÿ QSPL
| Recovery domain array. This array identifies the nodes | Ÿ QSPLJOB
| that compose the recovery domain. A role must be defined | Ÿ QSYS
| for each node in the recovery domain. Nodes in the | Ÿ QTCP

7-16 AS/400 System API Reference V4R4

 Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

| Ÿ QTFTP | CPFBB2E D
| Ÿ QTSTRQS | Job submission failed for cluster resource group
| &1 in cluster &2.
| CPFBB30 D
| Usage Notes | Takeover IP address &1 is not part of the
| TCP/IP subnetwork.
| Results Information User Queue: Asynchronous
| CPFBB32 D
| results are returned to a user queue specified by the Results
| Atributes of user queue &1 in library &2 are not
| Information parameter of the API. See “Cluster APIs Use of
| valid.
| User Queues” on page 5-2 and “Using Results Information”
| CPFBB34 D
| on page 5-3 for details on how to create the results informa-
| Cluster resource group &1 already exists in
| tion user queue, the format of the entries, and how to use
| cluster &2.
| the data placed on the queue. The data is sent to the user
| CPFBB35 D
| queue in the form of a message identifier and the substitution
| The user profile name &1 is not valid for this
| data for the message (if any exists). The following identifies
| request.
| the data sent to the user queue (excluding the message
| CPFBB38 D
| text).
| Library name &1 is not allowed for this request.
| CPCBB01 C | CPFBB39 D
| Cluster Resource Services API &1 completed. | Current user does not have IOSYSCFG special
| CPF2204 D User profile &1 not found. | authority.
| CPF2108 D Object not added to library. | CPFBB46 D
| CPF2112 D Object &1 in &2 type *&3 already exists. | Cluster Resource Services internal error.
| CPF2113 D Cannot allocate library &1. | CPFBB47 D
| CPF2151 D Operation failed for &2 in &1 type *&3. | Cluster Resource Services ended abnormally.
| CPF2182 D Not authorized to library &1. | CPFBB48 D
| CPF2183 D Object &1 cannot be moved into library &3. | Cluster Resource Services error detected.
| CPF3C29 D | CPFBB51 D
| Object name &1 is not valid. | Takeover IP address &1 already in use by the
| CPF3CF2 D | cluster &3.
| Error(s) occurred during running of &1 API. | CPIBB10 D Cluster Resource Group exit program &1 in
| CPF9801 D Object &2 in library &3 not found. | library &2 on node &3 failed.
| CPF9802 D Not authorized to object &2 in &3.
| CPF9803 E Cannot allocate object &2 in library &3.
| CPF9804 D Object &2 in library &3 damaged. | Error Messages
| CPF9810 D Library &1 not found.
| Messages that are delivered through the error code param-
| CPF9820 D Not authorized to use library &1.
| eter are listed here. The data (messages) sent to the results
| CPF9830 D Cannot assign library &1.
| information user queue are listed in the Usage Notes above.
| CPF9838 D User profile storage limit exceeded.
| CPF9870 D Object &2 type *&5 already exists in library &3. | CPF2112 E Object &1 in &2 type *&3 already exist.
| CPFBB02 D | CPF2204 E User profile &1 not found.
| Cluster &1 does not exist. | CPF24B4 E Severe error while addressing parameter list.
| CPFBB0A D | CPF3C1E E
| Node &1 is not active in cluster &2. | Required parameter &1 omitted.
| CPFBB0B D | CPF3C21 E
| Request using takover IP address &1 failed. | Format name &1 is not valid.
| CPFBB17 D | CPF3C29 E
| &1 API cannot be processed in cluster &2. | Object name &1 is not valid.
| CPFBB27 D | CPF3C39 E
| A primary node was not specified for the | Value for reserved field not valid.
| recovery domain. | CPF3C4B E
| CPFBB28 D | Value not valid for field &1.
| Cluster node &1 and cluster node &2 have the | CPF3CF1 E
| same node role value &3. | Error code parameter not valid.
| CPFBB29 D | CPF3CF2 E
| Node role value &1 not valid. | Error(s) occurred during running of &1 API.
| CPFBB2C D | CPF9801 E Object &2 in library &3 not found.
| Attributes of exit program &1 in library &2 are | CPF9802 E Not authorized to object &2 in &3.
| not valid. | CPF9804 E Object &2 in library &3 damaged. .
| CPFBB2D D | CPF9810 E Library &1 not found.
| Timeout detected while waiting for a response. | CPF9820 E Not authorized to use library &1.

Chapter 7. Cluster Resource Group APIs 7-17

 Delete Cluster Resource Group (QcstDeleteClusterResourceGroup) API

| CPF9838 E User profile storage limit exceeded.

| CPF9872 E Program or service program &1 in library &2 | Delete Cluster Resource Group
| ended. Reason code &3. | (QcstDeleteClusterResourceGroup) API
| CPFBB02 E
| Cluster &1 does not exist.
| CPFBB09 E | Required Parameter Group:
| Clustr node &1 does not exist in cluster &2.
| CPFBB0A E | 1 Request handle Output Char(16)
| 2 Cluster name Input Char(10)
| Cluster node &1 in cluster &2 is not active.
| 3 Cluster resource group Input Char(10)
| CPFBB0E E | name
| Cluster resource group type &1 not valid. | 4 Results information Input Char(30)
| CPFBB26 E | 5 Error code I/O Char(*)
| Cluster Resource Services not active or not
| responding. | Service Program: QCSTCRG1
| CPFBB27 E
| No primary node specified in recovery domain. | Threadsafe: Yes
| CPFBB28 E
| Two or more backup nodes have the same | The Delete Cluster Resource Group API deletes a cluster
| node role value &1. | resource group from all nodes in the recovery domain.
| CPFBB29 E
| Node role value &1 not valid. | The cluster resource group object is marked for deletion and
| CPFBB2C E | is deleted on each active cluster node. The Cluster Resource
| Attributes of exit program &1 in library &2 are | Group object will be deleted on other nodes in the cluster
| not valid. | when they become active. The Cluster Resource Group Exit
| CPFBB31 E | Program is called on each active node in the recovery
| Value &1 specified for number of restarts not | domain with an action code of delete (7). The cluster
| valid. | resource group status is set to Delete Pending (550). The
| CPFBB33 E | cluster resource group will be deleted even if the exit
| Cluster node &1 already exists in the recovery | program fails.
| domain for cluster resource group &4
| CPFBB34 E | The Delete Cluster Resource Group (DLTCRG) CL command
| Cluster resource group &1 already exist in | can be used to delete a Cluster Resource Group object on a
| cluster &2. | system that does not have Cluster Resource Services active.
| CPFBB35 E | For a cluster resource group type-2 the takeover IP address
| User profile name not valid for this request. | will be removed.
| CPFBB36 E
| Number of nodes in recovery domain is not | This API requires:
| valid. | 1. Cluster Resource Services active on the node pro-
| CPFBB37 E | cessing the request.
| Offset to recovery domain is not valid. | 2. Cluster resource group status must not be active (10)
| CPFBB38 E | 3. At least one active node in the recovery domain.
| Library name &1 not allowed for this request. | 4. The user profile running the exit program have *USE
| CPFBB39 E | authority for the CRG.
| Current user does not have IOSYSCFG special
| authority. | This API operates in an asynchronous mode. See “Cluster
| CPFBB40 E | Resource Services APIs Behavior” on page 5-2 for more
| The value &1 specified for the allow application | information.
| restart parameter is not valid.
| CPFBB43 E | Restriction:
| Format name &1 not valid for cluster resource | This API cannot be called from a cluster resource group
| group type &2. | exit program.
| CPFBB44 E | This API will never call the cluster resource group exit
| &1 API cannot be called from a cluster resource | program with an action code of Undo.
| group exit program.
| CPFBB51 E
| Takeover IP address &1 already in use by the | Authorities and Locks
| cluster &3.
| This API is shipped with *EXCLUDE public authority. The
| TCP1901 E Internet address &1 not valid.
| program that calls this API must be running under a user
| profile with *IOSYSCFG special authority.

7-18 AS/400 System API Reference V4R4

 Delete Cluster Resource Group (QcstDeleteClusterResourceGroup) API

| Cluster Resource Group Authority | Error code

| *OBJEXIST, *USE | I/O; CHAR(*)
| Cluster Resource Group Library Authority | The structure in which to return error information. For
| *EXECUTE
| the format of the structure, see “Error Code Parameter”
| Cluster Resource Group Lock | on page 2-6.
| *EXCL
| Exit Program Authority
| *EXECUTE | Usage Notes
| Exit Program Library Authority
| *EXECUTE | Results Information User Queue: Asynchronous
| User Profile Authority | results are returned to a user queue specified by the Results
| *USE | Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information”
| Request Information User Queue Authority
| on page 5-3 for details on how to create the results informa-
| *OBJOPR, *ADD
| tion user queue, the format of the entries, and how to use
| Request Information User Queue Library Authority
| the data placed on the queue. The data is sent to the user
| *EXECUTE
| queue in the form of a message identifier and the substitution
| Request Information User Queue Lock
| data for the message (if any exists). The following identifies
| *EXCLRD
| the data sent to the user queue (excluding the message
| text).
| Required Parameter Group | CPCBB01 C
| Request handle | Cluster Resource Services API &1 completed.
| OUTPUT; CHAR(16) | CPF2204 D User profile &1 not found.
| CPF3CF2 D
| A unique string or handle that identifies this API call. It | Error(s) occurred during running of &1 API.
| is used to associate this call to any responses placed on | CPF9801 D Object &2 in library &3 not found
| the user queue specified in the results information | CPF9802 D Not authorized to object &2 in &3.
| parameter. | CPF9803 D Cannot allocate object &2 in library &3.
| Cluster name | CPF9804 D Object &2 in library &3 damaged.
| INPUT; CHAR(10) | CPF9810 D Library &1 not found
| CPFBB02 D
| The name of the cluster containing the Cluster Resource | Cluster &1 does not exist.
| Group. | CPFBB0F D
| Cluster resource group name | Cluster resource group &1 does not exist in
| INPUT; CHAR(10) | cluster &2.
| CPFBB18 D
| The name of the cluster resource group. | Request &1 not allowed for cluster resource
| Results information | group &2.
| INPUT; CHAR(30) | CPFBB2C D
| Attributes of exit program &1 in library &2 are
| This parameter identifies a qualified user queue field and | not valid.
| is followed by a reserved field. | CPFBB2D D
| Qualified user queue: Completion information is | Timeout detected while waiting for a response.
| returned to this user queue, which exists on the node | CPFBB2E D
| from which the API was called, after the function has | Job submission failed for cluster resource group
| completed on all active nodes in the cluster. See the | &1 in cluster &2.
| Usage Notes section of this API for a description of the | CPFBB39 D
| data that is placed on this queue. This is a 20-character | Current user does not have IOSYSCFG special
| field. The first 10 characters contain the user queue | authority.
| name, and the second 10 characters contain the user | CPFBB46 D
| queue library name. No special values are supported. | Cluster resource service internal error.
| QTEMP, *LIBL, *CURLIB are not valid library names. | CPFBB47 D
| The attributes of this user queue must be keyed and | Cluster Resource Services ended abnormally.
| have a domain of user. | CPIBB10 D Cluster Resource Group exit program &1 in
| library &2 on node &3 failed.
| Reserved: The last 10 characters of the 30-character
| results information are reserved. Each character in this
| field must be set to hexadecimal zero.

Chapter 7. Cluster Resource Group APIs 7-19

 End Cluster Resource Group API (QcstEndClusterResourceGroup)

| Error Messages | The exit program is called on each active node in the
| recovery domain. For additional information about the infor-
| Messages that are delivered through the error code param- | mation passed to exit program see “Cluster Resource Group
| eter are listed here. The data (messages) sent to the results | Exit Program” on page 8-1.
| information user queue are listed in the Usage Notes above.
| When the exit program is called, the cluster resource group
| CPF2204 E User profile &1 not found. | status is set to End Cluster Resource Group Pending(550).
| CPF24B4 E Severe error while addressing parameter list. | Successful completion of the exit program sets the cluster
| CPF3C1E E | resource group status Inactive (20). In addition, for a Cluster
| Required parameter &1 omitted. | Resource Group type-2:
| CPF3CF1 E
| Error code parameter not valid. | Ÿ the current exit program job will be cancelled with the
| CPF3CF2 E | *IMMED option
| Error(s) occurred during running of &1 API. | Ÿ the takeover IP interface for the Cluster Resource Group
| CPF9801 E Object &2 in library &3 not found | will be ended.
| CPF9802 E Not authorized to object &2 in &3. | If the exit program fails and the original state of the cluster
| CPF9803 D Cannot allocate object &2 in library &3. | resource group cannot be recovered, the Cluster Resource
| CPF9810 E Library &1 not found. | Group status is set to indoubt (30).
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3. | This API requires:
| CPFBB02 E | 1. Cluster Resource Services started on the node pro-
| Cluster &1 does not exist. | cessing the request.
| CPFBB0F E | 2. Cluster resource group status of Active (10) or Indoubt
| Cluster resource group &1 does not exist in | (30).
| cluster &2. | 3. The user profile running the exit program have *USE
| CPFBB26 E | authority for the CRG.
| Cluster Resource Services not active or not
| responding. | This API operates in an asynchronous mode. See “Cluster
| CPFBB2C E | Resource Services APIs Behavior” on page 5-2 for more
| Attributes of exit program &1 in library &2 are | information.
| not valid.
| CPFBB39 E | Restriction:
| Current user does not have IOSYSCFG special | This API cannot be called from a cluster resource group
| authority. | exit program.
| CPFBB44 E
| &1 API cannot be called from a cluster resource
| group exit program. | Authorities and Locks
| This API is shipped with *EXCLUDE public authority. The
| program that calls this API must be running under a user
| End Cluster Resource Group | profile with *IOSYSCFG special authority.
| (QcstEndClusterResourceGroup) API
| Cluster Resource Group Authority
| *CHANGE
| Cluster Resource Group Library Authority
| Required Parameter Group:
| *EXECUTE
| 1 Request handle Output Char(16) | Cluster Resource Group Lock
| 2 Cluster name Input Char(10) | *EXCL
| 3 Cluster resource group Input Char(10) | Exit Program Authority
| name | *EXECUTE
| 4 Exit program data Input Char(256) | Exit Program Library Authority
| 5 Results information Input Char(30)
| *EXECUTE
| 6 Error code I/O Char(*)
| User Profile Authority
| Service Program: QCSTCRG2 | *USE
| Request Information User Queue Authority
| Threadsafe: Yes | *OBJOPR, *ADD
| Request Information User Queue Library Authority
| The End Cluster Resource Group API disables resiliency of | *EXECUTE
| the specified cluster resource group. The Cluster Resource | Request Information User Queue Lock
| Group exit program is called with an action code of End (4). | *EXCLRD

7-20 AS/400 System API Reference V4R4

 End Cluster Resource Group API (QcstEndClusterResourceGroup)

| Required Parameter Group | Reserved: The last 10 characters of the 30-character

| results information are reserved. Each character in this
| Request handle | field must be set to hexadecimal zero.
| OUTPUT; CHAR(16)
| Error code
| A unique string or handle that identifies this API call. It | I/O; CHAR(*)
| is used to associate this call to any responses placed on
| the user queue specified in the results information | The structure in which to return error information. For
| parameter. | the format of the structure, see “Error Code Parameter”
| on page 2-6.
| Cluster name
| INPUT; CHAR(10)
| Usage Notes
| The name of the cluster containing the Cluster Resource
| Group. | Results Information User Queue: Asynchronous
| Cluster resource group name | results are returned to a user queue specified by the Results
| INPUT; CHAR(10) | Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information”
| The name of the cluster resource group which will be | on page 5-3 for details on how to create the results informa-
| ended. | tion user queue, the format of the entries, and how to use
| Exit program data | the data placed on the queue. The data is sent to the user
| INPUT; CHAR(256) | queue in the form of a message identifier and the substitution
| data for the message (if any exists). The following identifies
| 256 bytes of data that is passed to the cluster resource | the data sent to the user queue (excluding the message
| group exit program when it is called. This parameter | text).
| may contain any scalar data except pointers. For
| example, it can be used to provide state information. | CPCBB01 C
| This data will be stored with the specified Cluster | Cluster Resource Services API &1 completed.
| Resource Group and copied to all nodes in the recovery | CPF2204 D User profile &1 not found.
| domain. Pointers in this area will not resolve correctly on | CPF9801 D Object &2 in library &3 not found.
| all nodes and should not be placed in the data. See | CPF9802 D Not authorized to object &2 in &3.
| “Cluster Resource Group Exit Program” on page 8-1 for | CPF9803 D Cannot allocate object&2 in library &3.
| information about the cluster resource group exit | CPF9804 D Object &2 in library &3 damaged.
| program. The data specified will replace the existing exit | CPF9810 D Library &1 not found.
| program data stored with the Cluster Resource Group. If | CPFBB0F D
| blanks are specified, then the exit program data stored | Cluster resource group &1 does not exist in
| with the Cluster Resource Group will be cleared. The | cluster &2.
| following special value can be used: | CPFBB17 D
| &1 API cannot be processed in cluster &2.
| *SAME The exit program data stored with the | CPFBB18 D
| Cluster Resource Group specified will be | Request &1 not allowed for cluster resource
| passed to the exit program. This must be | group &2.
| left justified. | CPFBB2C D
| Attributes of exit program &1 in library &2 are
| Results information
| not valid.
| INPUT; CHAR(30)
| CPFBB2D D
| This parameter identifies a qualified user queue field and | Timeout detected while waiting for a response.
| is followed by a reserved field. | CPFBB2E D
| Qualified user queue: Completion information is | Job submission failed for cluster resource group
| returned to this user queue, which exists on the node | &1 in cluster &2.
| from which the API was called, after the function has | CPFBB32 D
| completed on all active nodes in the cluster. See the | Attributes of user queue &1 are not valid.
| Usage Notes section of this API for a description of the | CPFBB47 D
| data that is placed on this queue. This is a 20-character | Cluster Resource Services ended abnormally.
| field. The first 10 characters contain the user queue | CPFBB48 D
| name, and the second 10 characters contain the user | Cluster Resource Services error detected.
| queue library name. No special values are supported. | CPIBB10 D Cluster Resource Group exit program &1 in
| QTEMP, *LIBL, *CURLIB are not valid library names. | library &2 on node &3 failed.
| The attributes of this user queue must be keyed and | TCP1B61 D
| have a domain of user. | Unable to determine if &1 interface ended.&2
| successful (&3 %).

Chapter 7. Cluster Resource Group APIs 7-21

 Initiate Switch Over (QcstInitiateSwitchOver) API

| TCP1B62 D
| Cannot determine if &1 interface ended. | Initiate Switch Over
| TCP1B65 D | (QcstInitiateSwitchOver) API
| &2 interface not ended. Reason &1.
| TCP1B72 D
| &1 interface not ended. &1 interface is not | Required Parameter Group:
| active.
| TCP1B73 D | 1 Request handle Output Char(16)
| 2 Cluster name Input Char(10)
| &1 interface not ended. &1 interface not
| 3 Cluster resource group Input Char(10)
| defined in TCP/IP configuration. | name
| TCP1B74 D | 4 Exit program data Input Char(256)
| &1 interface not ended. Line description &2 not | 5 Results information Input Char(30)
| found. | 6 Error code I/O Char(*)
| TCP1B85 D
| &1 interface not ended. | Service Program: QCSTCRG2
| TCP9999 D Internal system error in program &1.
| Threadsafe: Yes

| Error Messages
| The Initiate Switch Over API changes the current roles of
| Messages that are delivered through the error code param- | nodes in the recovery domain of a cluster resource group:
| eter are listed here. The data (messages) sent to the results | Ÿ the current primary node is assigned the role of last
| information user queue are listed in the Usage Notes above. | active backup.
| CPF2204 E User profile &1 not found. | Ÿ the current first backup is assigned the role of primary.
| CPF24B4 E Severe error while addressing parameter list. | If a backup node does not exist in the recovery domain, the
| CPF3CF2 E | switch over will fail. If the first backup is not the desired
| Error(s) occurred during running of &1 API. | primary, first use the Change Cluster Resource Group API to
| CPF3C1E E | arrange the backup nodes in recovery domain to the desired
| Required parameter &1 omitted. | order.
| CPF3C39 E
| Value for reserved field not valid. | This API will:
| CPF9801 E Object &2 in library &3 not found.
| 1. Set the cluster resource group status Switch Over
| CPF9802 E Not authorized to object &2 in &3.
| Pending (570).
| CPF9803 E Cannot allocate object &2 in library &3.
| 2. Call the cluster resource group exit program with an
| CPF9804 E Object &2 in library &3 damaged.
| action code of Switchover (10). The exit program is
| CPF9810 E Library &1 not found.
| called on all active nodes in the recovery domain.
| CPFBB02 E
| 3. Set the cluster resource group status to active (10) if the
| Cluster &1 does not exist.
| exit program completes successfully.
| CPFBB0F E
| 4. Set the cluster resource group status to indoubt (30) if
| Cluster resource group &1 does not exist in
| the exit program is unsuccessful and the original state of
| cluster &2.
| the cluster resource group cannot be recovered.
| CPFBB26 E
| 5. Perform the additional operations for a cluster resource
| Cluster Resource Services not active or not
| group type-2:
| responding.
| Ÿ End the takeover IP interface on the current
| CPFBB2C E
| primary.
| Attributes of exit program &1 in library &2 are
| Ÿ Start the takeover IP interface on the new primary.
| not valid.
| Ÿ Cancel the cluster resource group exit program job
| CPFBB32 E
| with a Cancel Job Immediate on the current primary.
| Attributes of user queue &1 are not valid.
| Ÿ Start the Cluster Resource Group exit program on
| CPFBB38 E
| the new primary. (Note: The application and exit
| Library name &1 not allowed for this request.
| program code should provide cancel handlers to
| CPFBB39 E
| clean up the job if it is cancelled).
| Current user does not have IOSYSCFG special
| Ÿ Set the cluster resource group status to active (10)
| authority.
| if the TCP/IP address and the cluster resource
| CPFBB44 E
| group exit program job are started.
| &1 API cannot be called from a cluster resource
| Ÿ Set the cluster resource group status to indoubt (30)
| group exit program.
| if either the TCP/IP address or the cluster resource
| CPFBB46 E
| group exit prgram job are not started.
| Cluster Resource Services internal error.

7-22 AS/400 System API Reference V4R4

 Initiate Switch Over (QcstInitiateSwitchOver) API

| When switching over both cluster resource group type-1 and | Cluster name
| type-2 objects, the order of switch over is important. The | INPUT; CHAR(10)
| cluster resource group type-1 objects should be done first.
| The name of the cluster containing the Cluster Resource
| Group.
| If a cluster resource group has a cluster resource group
| status of Indoubt (30), the Start Cluster Resource Group API | Cluster resource group name
| can be used to change the status to Active (10). See “Start | INPUT; CHAR(10)
| Cluster Resource Group (QcstStartClusterResourceGroup)
| The name of the cluster resource group.
| API” on page 7-33 for more information.
| Exit program data
| This API requires:
| INPUT; CHAR(256)
| 1. Cluster Resource Services started on the node pro-
| 256 bytes of data that is passed to the cluster resource
| cessing the request.
| group exit program when it is called. This parameter
| 2. Cluster resource group status of Active (10).
| may contain any scalar data except pointers. For
| 3. The user profile running the exit program must have
| example, it can be used to provide state information.
| *USE authority for the CRG.
| This data will be stored with the specified Cluster
| Resource Group and copied to all nodes in the recovery
| This API operates in an asynchronous mode. See “Cluster
| domain. Pointers in this area will not resolve correctly on
| Resource Services APIs Behavior” on page 5-2 for more
| all nodes and should not be placed in the data. See
| information.
| “Cluster Resource Group Exit Program” on page 8-1 for
| Restriction: | information about the cluster resource group exit
| program. The data specified will replace the existing exit
| This API cannot be called from a cluster resource group
| program data stored with the Cluster Resource Group. If
| exit program.
| blanks are specified, then the exit program data stored
| with the Cluster Resource Group will be cleared. The
| Authorities and Locks | following special value can be used:

| This API is shipped with *EXCLUDE public authority. The | *SAME The exit program data stored with the
| program that calls this API must be running under a user | Cluster Resource Group specified will be
| profile with *IOSYSCFG special authority. | passed to the exit program. This must be
| left justified.
| Cluster Resource Group Authority
| *CHANGE | Results information
| Cluster Resource Group Library Authority | INPUT; CHAR(30)
| *EXECUTE | This parameter identifies a qualified user queue field and
| Cluster Resource Group Lock | is followed by a reserved field.
| *EXCL
| Exit Program Authority | Qualified user queue: Completion information is
| *EXECUTE | returned to this user queue, which exists on the node
| Exit Program Library Authority | from which the API was called, after the function has
| *EXECUTE | completed on all active nodes in the cluster. See the
| User Profile Authority | Usage Notes section of this API for a description of the
| *USE | data that is placed on this queue. This is a 20-character
| field. The first 10 characters contain the user queue
| Request Information User Queue Authority | name, and the second 10 characters contain the user
| *OBJOPR, *ADD | queue library name. No special values are supported.
| Request Information User Queue Library Authority | QTEMP, *LIBL, *CURLIB are not valid library names.
| *EXECUTE | The attributes of this user queue must be keyed and
| Request Information User Queue Lock | have a domain of user.
| *EXCLRD
| Reserved: The last 10 characters of the 30-character
| results information are reserved. Each character in this
| Required Parameter Group | field must be set to hexadecimal zero.
| Request handle | Error code
| OUTPUT; CHAR(16) | I/O; CHAR(*)
| A unique string or handle that identifies this API call. It | The structure in which to return error information. For
| is used to associate this call to any responses placed on | the format of the structure, see “Error Code Parameter”
| the user queue specified in the results information | on page 2-6.
| parameter.

Chapter 7. Cluster Resource Group APIs 7-23

 Initiate Switch Over (QcstInitiateSwitchOver) API

| Usage Notes | TCP1B05 D

| &2 interface not started. Reason &1.
| Results Information User Queue: Asynchronous | TCP1B10 D
| results are returned to a user queue specified by the Results | &2 interface not started.
| Information parameter of the API. See “Cluster APIs Use of | TCP1B11 D
| User Queues” on page 5-2 and “Using Results Information” | &1 interface not started. Tried to exceed
| on page 5-3 for details on how to create the results informa- | maximum number of active interfaces allowed.
| tion user queue, the format of the entries, and how to use | TCP1B12 D
| the data placed on the queue. The data is sent to the user | &1 interface not started. &1 interface already
| queue in the form of a message identifier and the substitution | active.
| data for the message (if any exists). The following identifies | TCP1B13 D
| the data sent to the user queue (excluding the message | &1 interface not started. &1 interface not
| text). | defined the TCP/IP configuration.
| TCP1B14 D
| CPCBB01 C | &1 interface not started. Line description &2
| Cluster Resource Services API &1 completed. | not found.
| CPF2204 D User profile &1 not found. | TCP1B15 D
| CPF3CF2 D | Line description &2 unusable. Internal errors
| Error(s) occurred during running of &1 API. | encountered.
| CPF9801 D Object &2 in library &3 not found | TCP1B16 D
| CPF9802 D Not authorized to object &2 in &3. | &2 interface not started.
| CPF9803 D Cannot allocate object &2 in library &3. | TCP1B25 D
| CPF9804 D Object &2 in library &3 damaged. | &1 interface not started.
| CPF9810 D Library &1 not found | TCP265F D INTNETADR parameter value &2 not valid.
| CPFBB09 D | TCP1B61 D
| Cluster node &1 does not exist in cluster &2. | Unable to determine if &1 interface ended.&2
| CPFBB0A D | successful (&3).
| Cluster node &1 in cluster &2 not active. | TCP1B62 D
| CPFBB0F D | Cannot determine if &1 interface ended.
| Cluster resource group &1 does not exist in | TCP1B65 D
| cluster &2. | &2 interface not ended. Reason &1.
| CPFBB17 D | TCP1B72 D
| &1 API cannot be processed in cluster &2. | &1 interface not ended. &1 interface is not
| CPFBB18 D | active.
| Request &1 not allowed for cluster resource | TCP1B73 D
| group &2. | &1 interface not ended. &1 interface not
| CPFBB1E D | defined in TCP/IP configuration.
| A switch over cannot be done for cluster | TCP1B74 D
| resource group &1. | &1 interface not ended. Line description &2 not
| CPFBB2C D | found.
| Attributes for exit program &1 in library &2 are | TCP1B85 D
| not valid. | &1 interface not ended.
| CPFBB2D D | TCP3210 D Connection verification statistics: &1 of &2 suc-
| Timeout detected while waiting for a response. | cessful (&3).
| CPFBB2E D | TCP9999 D Internal system error in program &1.
| Job submission failed for cluster resource group
| &1 in cluster &2.
| CPFBB38 D | Error Messages
| Value &1 not allowed for library name.
| CPFBB39 D | Messages that are delivered through the error code param-
| Current user does not have IOSYSCFG special | eter are listed here. The data (messages) sent to the results
| authority. | information user queue are listed in the Usage Notes above.
| CPFBB46 D | CPF24B4 E Severe error while addressing parameter list.
| Cluster resource service internal error. | CPF3C1E E Required parameter &1 omitted.
| CPIBB10 D Cluster resource group exit program &1 in | CPF3C39 E Value for reserved field not valid.
| library &2 on node &3 failed. | CPF3CF1 E Error code parameter not valid.
| TCP1B01 D | CPF3CF2 E Error(s) occurred during running of &1 API.
| Unable to determine if &1 interface started. | CPF9801 E Object &2 in library &3 not found
| TCP1B02 D | CPF9802 E Not authorized to object &2 in &3.
| Cannot determine if &1 interface started. | CPF9803 E Cannot allocate object &2 in library &3.

7-24 AS/400 System API Reference V4R4

 List Cluster Resource Groups (QcstListClusterResourceGroups) API

| CPF9804 E Object &2 in library &3 damaged. | User Space Authority

| CPF9810 E Library &1 not found | *CHANGE
| CPFBB02 E Cluster &1 does not exist. | User Space Library Authority
| CPFBB09 E Cluster node &1 does not exist in cluster &2. | *EXECUTE
| CPFBB0A E Cluster node &1 in cluster &2 not active. | User Space Lock
| CPFBB0F E Cluster resource group &1 does not exist in | *EXCLRD
| cluster &2.
| CPFBB1E E A switch over cannot be done for cluster
| resource group &1.
| Required Parameter Group
| CPFBB26 E Cluster Resource Services not active or not | Qualified user space name
| responding. | INPUT; CHAR(20)
| CPFBB2C E Attributes for exit program &1 in library &2 are
| The name of the *USRSPC object that is to receive the
| not valid.
| generated list. The first 10 characters contain the user
| CPFBB32 E Attributes of user queue &1 in library &2 are
| space object name, and the second 10 characters
| not valid.
| contain the name of the library where the user space is
| CPFBB39 E Current user does not have IOSYSCFG
| located. No special values are supported for library
| special authority.
| name.
| CPFBB44 E &1 API cannot be called from a cluster
| resource group exit program. | Format Name
| INPUT; CHAR(8)
| The format of the information returned for each cluster
| List Cluster Resource Groups | resource group object. Possible values are:
| (QcstListClusterResourceGroups) API
| CRGL0100 Cluster Resource Group Object Names

| For more information, see “CRGL0100 Format” on

| Required Parameter Group: | page 7-26.
| 1 Qualified user space name Input Char(20) | Cluster name
| 2 Format name Input Char(8) | INPUT; CHAR(10)
| 3 Cluster name Input Char(10)
| 4 Error code I/O Char(*) | The name of the cluster for which the list of cluster
| resource group objects is retrieved.
| Service Program: QCSTCRG3
| Error code
| Threadsafe: Yes | I/O; CHAR(*)
| The structure in which to return error information. For
| The List Cluster Resource Groups API generates a list of | the format of the structure, see “Error Code Parameter”
| and descriptive information about the Cluster Resource | on page 2-6.
| Groups in the cluster specified by the Cluster Name param-
| eter. The generated list is placed in the specified user space | Format of the Generated Lists
| and replaces any existing list. Information will be returned
| for all cluster resource groups in the cluster, even if they do | The cluster resource group list consists of:
| not exist on the node running the API. All the cluster
| Ÿ A user space
| resource groups will be returned in the generated list regard-
| Ÿ A generic header
| less of the authority of the user calling the API. The List
| Ÿ An input parameter section
| Objects (QUSLOBJ) API can be used to provide a list of
| Ÿ A header section
| Cluster Resource Group objects on this node only. Since the
| Ÿ A list data section:
| request for information is not distributed to other nodes in the
| cluster, the information about a cluster resource group that is | – CRGL0100 format
| returned shows the values obtained from the node running
| the API. Several conditions (for emample, Cluster Resource | For details about the user area and generic header, see
| Services not active on the node running the API) may | “User Space Format for List APIs” on page 2-4. For details
| produce inconsistent information about a cluster resource | about the remaining items, see the following sections. For
| group in the cluster. | detailed descriptions of the fields in the list returned, see
| “Field Descriptions” on page 7-26.
| This API can be called from a cluster resource group exit
| program. | The completion code in the generic header should be
| checked to determine if the API completed successfully.
| When you retrieve list entry information from a user space,
| Authorities and Locks | you must use the entry size returned in the generic header.

Chapter 7. Cluster Resource Group APIs 7-25

 List Cluster Resource Groups (QcstListClusterResourceGroups) API

| The size of each entry may be padded at the end. If you do | 30 Indoubt. The information contained within the cluster
| not use the entry size, the result may not be valid. For | resource group object may not be accurate. This
| examples of how to process lists, see Appendix A, | status occurs when an exit program is called with an
| “Examples.” | action of undo and fails to complete successfully.
| 40 Restored. The cluster resource group object was
| Input Parameter Section: An exact copy of the parame- | restored on this node and has not been copied to the
| ters coded in the call to the API. | other nodes in the recovery domain. When Cluster
| Resource Services is started on this node, the cluster
| Offset | resource group will be synchronized with the other
| Dec Hex Type Field | nodes in the recovery domain and its status set to
| inactive.
| 0 0 CHAR(10) User space name
| 500 Add Node Pending. A new node is in the process of
| 10 A CHAR(10) User space library name | being added to the recovery domain of a cluster
| 20 14 CHAR(8) Format name | resource group. If the exit program is successful the
| status is reset to its value at the time the API was
| 28 1C CHAR(10) Cluster name
| called. If the exit program fails and the original state
| cannot be recovered, the status is set to Indoubt.
| Header Section: Global information about the cluster | 510 Delete Pending. Cluster resource group object is in
| resource groups. | the process of being deleted. When the exit program
| completes the cluster resource group is deleted from
| Offset | all nodes in the recovery domain.
| Dec Hex Type Field | 520 Change Pending. The Cluster Resource Group is in
| the process of being changed. If the exit program is
| 0 0 CHAR(1) Information status
| successful the status is reset to the value at the time
| the API was called. If the exit program fails and the
| CRGL0100 Format: General information about the | original state cannot be recovered, status is set to
| cluster resource groups in the cluster. Detailed information | Indoubt.
| about a single cluster resource group can be obtained by | 530 End Cluster Resource Group Pending. Resiliency
| using the List Cluster Resource Group Information API. For | for the cluster resource group is in the process of
| details reference “List Cluster Resource Group Information | ending. If the exit program is successful, the status is
| (QcstListClusterResourceGroupIn) API” on page 7-27. | set to Inactive. If the exit program fails and the ori-
| ginal state cannot be recovered, Indoubt.
| Offset | 540 Initialize Pending. A Cluster Resource Group is being
| Dec Hex Type Field | created and is in the process of being initialized. If
| the exit program is successful, the status is set to
| 0 0 CHAR(10) Cluster resource group
| Inactive. If the exit program fails, the cluster resource
| name
| group will be deleted from all nodes.
| 10 A CHAR(2) Reserved | 550 Remove Node Pending. A node is in the process of
| 12 C BIN(4) Cluster resource group | being removed from the recovery domain of the
| status | cluster resource group. If the exit program is suc-
| 16 10 CHAR(8) Primary node id | cessful, the status is reset to the value at the time the
| API was called. If the exit program fails and the ori-
| ginal state cannot be recovered, the status is set to
| Field Descriptions | Indoubt.
| 560 Start Cluster Resource Group Pending. Resiliency
| Cluster name. The name of the cluster for which the list of | is in the process of starting for the cluster resource
| cluster resource groups is to be retrieved. | group. If the exit program is successful, the status is
| set to Active If the exit program fails and the original
| Cluster resource group name. The name of the cluster | state cannot be recovered, the status is set to
| resource group. | Indoubt.
| 570 Switch Over Pending. The Initiate Switch Over API
| Cluster resource group status. The status of the cluster | was called, a failure of a cluster resource group
| resource group when this information was gathered. The | occurred, or a node failed, causing a switch over or
| possible values are: | failure to begin. The first backup node is in the
| 10 Active. The objects or application of the cluster | process of becoming the primary node. If the exit
| resource group are currently resilient. | program is successful, the status is set to Active. If
| 20 Inactive. The Cluster resource group contains a | the exit program fails and the original state cannot be
| recovery domain but the resources are not resilient. | recovered, the status is set to Indoubt.

7-26 AS/400 System API Reference V4R4

 List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API

| 580 Delete Command Pending. Cluster resource group | CPFBB02 E Cluster &1 does not exist.
| object is being deleted by the Delete Cluster Resource
| Group (DLTCRG) CL command. The Cluster resource
| group object is only removed from the node running | List Cluster Resource Group Information
| the command. This is not a distributed request. At the (QcstListClusterResourceGroupIn) API
|
| completion of the command, the cluster resource
| group is deleted from the node.

| Format name. The content and format of the information | Required Parameter Group:
| returned for each cluster resource group object entry. The
| 1 Request handle Output Char(16)
| value must be set to CRGL0100. | 2 Qualified user space name Input Char(20)
| 3 Format name Input Char(8)
| Information status. Indicates the consistency of the | 4 Cluster name Input Char(10)
| retrieved information. | 5 Cluster Resource Group Input Char(10)
| 0 The information is consistent for all active | name
| 6 Results information Input Char(30)
| nodes in the cluster.
| 7 Error code I/O Char(*)
| 1 The information retrieved from the node
| running the API may not be consistent with all | Service Program: QCSTCRG3
| active nodes in the cluster. In order to obtain
| consistent information: | Threadsafe: Yes
| Ÿ Call this API on an active node in the
| cluster, if the node running the API is not
| active. | The List Cluster Resource Group API returns the contents of
| Ÿ Start Cluster Resource Services on the | a cluster resource group object. If the status of the cluster
| node running the API if it is not active. | resource group is Initialize Pending (540), the API will fail.
| Ÿ Call the End Cluster Node and Start
| This API can be called from a cluster resource group exit
| Cluster Node APIs on the node running
| program. However, if the Cluster Resource Group exit
| the API, if the node is active.
| program was called as a result of the Create Cluster
| Primary node id. A unique string of characters that identi- | Resource Group command, the API will fail. The Cluster
| fies the node that has a cuurent node role of primary for the | Resource Group Exit Program will not be called when this
| Cluster Resource Group object. | API is run.

| Reserved Space reserved for future use. Information in this | If Cluster Resource Services has not been started:
| field is ignored. | Ÿ the information returned may not be current.
| Ÿ information will only be returned for a cluster resource
| User space library name. The name of the library that con- | group on the node running the API.
| tains the user space.
| If Cluster Resource Services has been started, this API will
| User space name. The name of the user space that | return information about the cluster resource group even if it
| receives the list. | does not exist on the node from which the API is called. For
| information retrieved from another node, the API will always
| Error Messages | indicate success. To determine if data was actually returned,
| check the length returned in the generic header portion of the
| Messages that are delivered through the error code param- | user space.
| eter are listed here. The data (messages) sent to the results
| information user queue are listed in the Usage Notes above.
| Authorities and Locks
| CPF24B4 E Severe error while addressing parameter list.
| Cluster Resource Group Authority
| CPF3C21 E Format name &1 is not valid.
| *USE
| CPF3CF1 E Error code parameter not valid.
| Cluster Resource Group Library Authority
| CPF3CF2 E Error(s) occurred during running of &1 API.
| *EXECUTE
| CPF9801 E Object &2 in library &3 not found.
| Cluster Resource Group Lock
| CPF9802 E Not authorized to object &2 in &3.
| *SHRRD
| CPF9803 E Cannot allocate object &2 in library &3.
| User Space Authority
| CPF9804 E Object &2 in library &3 damaged.
| *CHANGE
| CPF9810 E Library &1 not found.
| User Space Library Authority
| CPF9872 E Program or service program &1 in library &2
| *EXECUTE
| ended. Reason code &3.
| User Space Lock
| *EXCLRD

Chapter 7. Cluster Resource Group APIs 7-27

 List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API

| Request Information User Queue Authority | name, and the second 10 characters contain the user
| *OBJOPR, *ADD | queue library name. No special values are supported.
| Request Information User Queue Library Authority | QTEMP, *LIBL, *CURLIB are not valid library names.
| *EXECUTE | The attributes of this user queue must be keyed and
| Request Information User Queue Lock | have a domain of user.
| *EXCLRD
| Reserved: The last 10 characters of the 30-character
| results information are reserved. Each character in this
| Required Parameter Group | field must be set to hexadecimal zero.

| Request handle | Error code

| OUTPUT; CHAR(16) | I/O; CHAR(*)
| A unique string or handle that identifies this API call. It | The structure in which to return error information. For
| is used to associate this call to any responses placed on | the format of the structure, see “Error Code Parameter”
| the user queue specified in the results information | on page 2-6.
| parameter. If the Cluster resource group exists on this
| node, then the Request handle field will be blank.
| Format of the Generated Lists
| Qualified user space object
| The cluster resource group list consists of:
| INPUT; CHAR(20)
| Ÿ A user space
| The user space that is to receive the created list. The
| Ÿ A generic header
| first 10 characters contain the user space name, and the
| Ÿ An input parameter section
| second 10 characters contain the name of the library
| Ÿ A header section
| where the user space is located. No special values can
| Ÿ A list data section:
| used for the library name.
| – LRGI0100 format
| Format name
| INPUT; CHAR(8)
| For details about the user area and generic header, see
| The format of the information to be returned. The format | “User Space Format for List APIs” on page 2-4. For details
| names supported are: | about the remaining items, see the following sections. For
| detailed descriptions of the fields in the list returned, see
| LRGI0100 Recovery Domain Entries
| “Field Descriptions” on page 7-29.
| Refer to “LRGI0100 Recovery Domain
| Entries Section” on page 7-29 for details | When you retrieve list entry information from a user space,
| on the format. | you must use the entry size returned in the generic header
| for the LRGI0100 format. The size of each entry may be
| Cluster name
| padded at the end. If you do not use the entry size, the
| INPUT; CHAR(10)
| result may not be valid. For examples of how to process
| The name of the cluster containing the cluster resource | lists, see Appendix A, “Examples.”
| group
| Input Parameter Section: A copy of most parameters
| Cluster Resource Group name | coded in the call to the API.
| INPUT; CHAR(10)
| The name of the cluster resource group for which infor- | Offset
| mation is retrieved. | Dec Hex Type Field
| Results information | 0 0 CHAR(10) User space name
| INPUT; CHAR(30) | 10 A CHAR(10) User space library name
| This parameter identifies a qualified user queue field and | 20 14 CHAR(8) Format name
| is followed by a reserved field. This parameter is
| 28 1C CHAR(10) Cluster name
| ignored if the cluster resource group exists on the node
| initiating the API request. | 38 26 CHAR(10) Cluster resource group
| name
| Qualified user queue: Completion information is
| returned to this user queue, which exists on the node | 48 30 CHAR(16) Request handle
| from which the API was called, after the function has | 64 40 CHAR(30) Results information
| completed on all active nodes in the cluster. See the | Note: The Results information field is comprised of the fol-
| Usage Notes section of this API for a description of the | lowing 3 fields.
| data that is placed on this queue. This is a 20-character
| 64 40 CHAR(10) Results information user
| field. The first 10 characters contain the user queue | queue name

7-28 AS/400 System API Reference V4R4

 List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API

| Offset | Field Descriptions

| Dec Hex Type Field
| Allow application restart. Attempt to restart an application
| 74 4A CHAR(10) Results information user | if the cluster resource group exit program fails. Possible
| queue library name | values are:
| 84 54 CHAR(10) Reserved | 0 Do not attempt to restart the application. The
| cluster resource group exit program is called
| Header Section: Global information about the cluster | with an action code of failover (9).
| resource group. | 1 Attempt to restart the application on the same
| node. The cluster resource group exit
| Offset | program will be called with an action code of
| restart (3). If the application cannot be
| Dec Hex Type Field
| restarted in the specified maximum number of
| 0 0 CHAR(1) Information status | attempts, the cluster resource group exit
| 1 1 CHAR(3) Reserved | program will be called with an action code of
| 4 4 BINARY(4) Cluster resource group type
| failover (9).

| 8 8 BINARY(4) Current cluster resource | Cluster name. The name of the cluster containing the
| group status | cluster resource group
| 12 C CHAR(10) Cluster resource group exit
| program name | Cluster resource group exit program library name. The
| name of the library that contains the exit program for the
| 22 16 CHAR(10) Cluster resource group exit
| program library name
| cluster resource group.

| 32 20 CHAR(8) Cluster resource group exit | Cluster resource group exit program format name. Indi-
| program format name | cates which format should be used for the Information
| 40 28 CHAR(10) User profile | Given To User parameter on the Cluster Resource Group
| 50 32 CHAR(256) Exit program data
| Exit Program when it is called.

| 306 132 CHAR(16) Takeover IP address | Cluster resource group exit program name. The name of
| 322 142 CHAR(10) Job name | the user provided exit program.
| 332 14C BINARY(4) Allow application restart | Cluster resource group name. The name of the cluster
| 336 150 BINARY(4) Number of restarts | resource group.
| 340 154 BINARY(4) Previous cluster resource
| Cluster resource group type. The type of resilient resource
| group status
| information contained within the cluster resource group
| 344 158 CHAR(8) Reporting Node | object.
| 1 Data resiliency
| LRGI0100 Recovery Domain Entries Section The | 2 Application resiliency
| cluster resource group recovery domain information is
| returned when LRGI0100 is specified as the format type. | Current cluster resource group status. The current status
| There will always be two node role entries returned in the list | for the cluster resource group. See “Field Descriptions” on
| information. The first list entry will be for the current role of | page 7-26 for a list of the valid status values.
| the node and the second list entry will be for the preferred
| role of the node. For detailed descriptions of the fields in the | Current node role. The current role the node has in the
| table, see “Field Descriptions.” | recovery domain:
| 0 Primary node. Only one node can have this
| Offset | value.
| Dec Hex Type Field | ≥1 Backup node. The backup order is designated
| 0 0 CHAR(8) Node id | by increasing value.
| -1 Replicate node. All replicates have this value.
| 8 8 BINARY(4) Current node role | This value is not valid for a type-2.
| 12 C BINARY(4) Membership status
| Exit program data. 256 bytes of data which is passed to
| 16 10 BINARY(4) Preferred node role
| the Cluster Resource Group Exit Program when it is called.

| Format name. The content and format of the information

| returned in the user space.

Chapter 7. Cluster Resource Group APIs 7-29

 List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API

| Job name. The name given the batch job that is submitted | Request handle. Identifies this API call. It is used to asso-
| to invoke the Cluster Resource Group Exit Program. Valid | ciate this call to a response on the user queue specified in
| special values for this field are: | the Results Information parameter.
| *JOBD The job name is determined from the job
| Reserved. Will be hex zeroes.
| description specified in the user profile for the
| Cluster Resource Group Exit Program. | Results information. This field identifies a qualified user
| queue name and is followed by a reserved field.
| Information status. Indicates the consistency of the
| retrieved information. | Results information user queue name. This field identifies
| 0 The information is consistent for all active | the name of the user queue to which messages are sent
| nodes in the cluster. | when this API operates asynchronously.
| 1 The information retrieved from the node
| Results information user queue library name. This field
| running the API may not be consistent with all
| identifies the library where the results information user queue
| active nodes in the cluster. In order to obtain
| resides.
| consistent information:
| Ÿ Call this API on an active node in the
| Takeover IP Address The floating IP address that is to be
| cluster, if the node running the API is not
| associated with the application. This field is only meaningful
| active.
| for a cluster resource group Type 2. It is set to hex zeroes
| Ÿ Start Cluster Resource Services on the
| for a cluster resource group Type 1. This field will be repre-
| node running the API if it is not active.
| sented in dotted decimal format and returned as a null-
| Ÿ Call the End Cluster Node and Start
| terminated string.
| Cluster Node APIs on the node running
| the API, if the node is active. | User profile. The name of the user profile under which the
| Cluster Resource Group Exit Program is run.
| Membership status. The Cluster Resource Group member-
| ship status for the node. | User space name. The name of the user space which will
| 0 Active | contain the information retrieved from the cluster resource
| 1 Inactive | group.
| 2 Partition
| User space libary name. The name of the library con-
| Node id. A unique string of characters that identifies a node | taining the user space.
| that is in the recovery domain of the cluster resource group.

| Number of restarts. Number of times the Cluster Resource

| Usage Notes
| Group Exit Program can be restarted on the same node
| Results Information User Queue: Asynchronous
| before a failover occurs. Maximum number of restarts is 3.
| results are returned to a user queue specified by the Results
| This field is only valid for a cluster resource group Type 2. It
| Information parameter of the API. See “Cluster APIs Use of
| will always contain X'00' for a cluster resource group Type 1.
| User Queues” on page 5-2 and “Using Results Information”
| Preferred node role. The preferred role the node has in | on page 5-3 for details on how to create the results informa-
| the recovery domain: | tion user queue, the format of the entries, and how to use
| the data placed on the queue. The data is sent to the user
| 0 Primary node. Only one node can have this | queue in the form of a message identifier and the substitution
| value. | data for the message (if any exists). The following identifies
| ≥1 Backup node. The backup order is designated | the data sent to the user queue (excluding the message
| by increasing value. | text).
| -1 Replicate node. All replicates have this value.
| CPCBB01 C
| Previous cluster resource group status. Indicates the | Cluster Resource Services API &1 completed.
| status of this cluster resource group before the current | CPF2204 D User profile &1 not found.
| request was executed. | CPF3CF2 D
| Error(s) occurred during running of &1 API.
| Reporting node. The node ID of the cluster node which | CPF9801 D Object &2 in library &3 not found.
| returned the list information for the cluster resource group | CPF9802 D Not authorized to object &2 in &3.
| Valid special values are: | CPF9803 D Cannot allocate object &2 in library &3.
| *LOCAL The information was retrieved from a cluster | CPF9804 D Object &2 in library &3 damaged..
| resource group on the local system and the | CPF9810 D Library &1 not found.
| local system did not have a cluster node asso- | CPFBB24 D
| ciated with it. | Node &1 not participating in &2 API protocol.

7-30 AS/400 System API Reference V4R4

 Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API

| CPFBB32 D
| Attributes of user queue &1 in library &2 are not | Required Parameter Group:
| valid.
| CPFBB38 D | 1 Request handle Output Char(16)
| Library name &1 not allowed for this request. | 2 Cluster name Input Char(10)
| 3 Cluster resource group Input Char(10)
| name
| Error Messages | 4 Node id Input Char(8)
| 5 Results information Input Char(30)
| CPF3C1E E
| 6 Error code I/O Char(*)
| Required parameter &1 omitted.
| CPF3C21 E | Service Program: QCSTCRG1
| Format name &1 is not valid.
| CPF3C3C E | Threadsafe: Yes
| Value for parameter &1 not valid.
| CPF3C39 E
| Value for reserved field not valid. | The Remove Node From Recovery Domain API is used to
| CPF3C3C E | remove a node from the recovery domain of a cluster
| Value for parameter &1 not valid. | resource group. The node being removed does not need to
| CPF3CF1 E | be active in the cluster to be removed from the recovery
| Error code parameter not valid. | domain. If the CRG is Active, the primary node may not be
| CPF3CF2 E | removed from the CRG. If the cluster resource group has no
| Error(s) occurred during running of &1 API. | backup nodes, the primary node cannot be removed.
| CPF9801 E Object &2 in library &3 not found.
| This API will:
| CPF9802 E Not authorized to object &2 in &3.
| CPF9803 E Cannot allocate object &2 in library &3. | 1. Set the cluster resource group status to Remove Node
| CPF9804 E Object &2 in library &3 damaged.. | Pending (550).
| CPF9810 E Library &1 not found. | 2. Call the cluster resource group exit program on all active
| CPFBB02 E | nodes in the recovery domain with an action code of
| Cluster &1 does not exist. | Remove Node (12).
| CPFBB0F E | 3. Reset the cluster resource group status to the value at
| Cluster resource group &1 does not exist in | the time the API was called, if the exit program com-
| cluster &2. | pletes successfully on all nodes.
| CPFBB26 E | 4. Set the cluster resource group status to Indoubt (30) if
| Cluster Resource Services not active or not | the exit program fails on any node and the original state
| responding. | of the cluster resource group cannot be recovered.
| CPFBB32 E | 5. Remove the takeover IP address for a cluster resource
| Attributes of user queue &1 in library &2 are not | group type-2.
| valid. | 6. Delete the cluster resource group object from the node
| CPFBB38 E | removed.
| Library name &1 not allowed for this request.
| CPFBB39 E | This API requires:
| Current user does not have IOSYSCFG special | 1. Cluster Resource Services started on the node running
| authority. | the API.
| CPFBB40 E | 2. A cluster resource group status other than active (10) in
| The value &1 specified for the allow application | order to remove the node that is currently the primary.
| restarts parameter is not valid | 3. At least one backup node in the recovery domain of the
| CPFBB46 E | cluster resource group, if the primary node is removed.
| Cluster Resource Services internal error. | 4. At least one active node in the recovery domain of the
| cluster resource group after the succssful completion of
| the remove operation.
| Remove Node From Recovery Domain
| This API operates in an asynchronous mode. See “Cluster
| (QcstRemoveNodeFromRcvyDomain) API | Resource Services APIs Behavior” on page 5-2 for more
| information.

| Restriction:
| This API cannot be called from a cluster resource group
| exit program.

Chapter 7. Cluster Resource Group APIs 7-31

 Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API

| Authorities and Locks | Usage Notes section of this API for a description of the
| data that is placed on this queue. This is a 20-character
| This API is shipped with *EXCLUDE public authority. The | field. The first 10 characters contain the user queue
| program that calls this API must be running under a user | name, and the second 10 characters contain the user
| profile with *IOSYSCFG special authority. | queue library name. No special values are supported.
| QTEMP, *LIBL, *CURLIB are not valid library names.
| Cluster Resource Group Authority
| The attributes of this user queue must be keyed and
| *CHANGE, *OBJEXIST
| have a domain of user.
| Cluster Resource Group Library Authority
| *EXECUTE | Reserved: The last 10 characters of the 30-character
| Cluster Resource Group Lock | results information are reserved. Each character in this
| *EXCL | field must be set to hexadecimal zero.
| Exit Program Authority
| Error code
| *EXECUTE
| I/O; CHAR(*)
| Exit Program Library Authority
| *EXECUTE | The structure in which to return error information. For
| User Profile Authority | the format of the structure, see “Error Code Parameter”
| *USE | on page 2-6.
| Request Information User Queue Authority
| *OBJOPR, *ADD | Usage Notes
| Request Information User Queue Library Authority
| *EXECUTE | Results Information User Queue: Asynchronous
| Request Information User Queue Lock | results are returned to a user queue specified by the Results
| *EXCLRD | Information parameter of the API. See “Cluster APIs Use of
| User Queues” on page 5-2 and “Using Results Information”
| on page 5-3 for details on how to create the results informa-
| Required Parameter Group | tion user queue, the format of the entries, and how to use
| Request handle | the data placed on the queue. The data is sent to the user
| OUTPUT; CHAR(16) | queue in the form of a message identifier and the substitution
| data for the message (if any exists). The following identifies
| A unique string or handle that identifies this API call. It
| the data sent to the user queue (excluding the message
| is used to associate this call to any responses placed on
| text).
| the user queue specified in the results information
| parameter. | CPCBB01 C
| Cluster Resource Services API &1 completed.
| Cluster name | CPF2204 D User profile &1 not found.
| INPUT; CHAR(10) | CPF3CF2 D
| The name of the cluster containing the cluster resource | Error(s) occurred during running of &1 API.
| group. | CPF9801 D Object &2 in library &3 not found.
| CPF9802 D Not authorized to object &2 in &3.
| Cluster resource group name | CPF9803 D Cannot allocate object &2 in library &3.
| INPUT; CHAR(10) | CPF9804 D Object &2 in library &3 damaged.
| The name of the cluster resource group from which the | CPF9810 D Library &1 not found.
| node will be removed. | CPFBB09 D
| Cluster node Id &1 does not exist in Cluster &2.
| Node id | CPFBB0A D
| INPUT; CHAR(8) | Cluster node &1 not active in cluster &2.
| A unique string of characters that identifies the node that | CPFBB0B D
| is to be removed from the recovery domain of the | Request using takeover IP address &1 failed.
| Cluster Resource Group. | CPFBB0F D
| Cluster resource group &1 does not exist in
| Results information | cluster &2.
| INPUT; CHAR(30) | CPFBB17 D
| This parameter identifies a qualified user queue field and | &1 API cannot be processed in cluster &2.
| is followed by a reserved field. | CPFBB18 D
| Request &1 not allowed for cluster resource
| Qualified user queue: Completion information is
| group &2.
| returned to this user queue, which exists on the node
| CPFBB1B D
| from which the API was called, after the function has
| Cluster node &1 does not exist in the recovery
| completed on all active nodes in the cluster. See the
| domain for cluster resource group &2.

7-32 AS/400 System API Reference V4R4

 Start Cluster Resource Group (QcstStartClusterResourceGroup) API

| CPFBB2C D | CPFBB26 E
| Attributes of exit program &1 in library &2 are | Cluster Resource Services not active or not
| not valid. | responding.
| CPFBB2D D | CPFBB2C E
| Timeout detected while waiting for a response. | Attributes of exit program &1 in library &2 are
| CPFBB2E D | not valid.
| Job submission failed for cluster resource group | CPFBB32 E
| &1 in cluster &2. | Attributes of user queue &1 in library &2 are not
| CPFBB32 D | valid.
| Attributes of user queue &1 in library &2 are not | CPFBB39 E
| valid. | Current user does not have IOSYSCFG special
| CPFBB38 D | authority.
| Library name &1 not allowed for this request. | CPFBB42 E
| CPFBB39 D | &1 API cannot be used within a cluster
| Current user does not have IOSYSCFG special | resource group exit program.
| authority. | CPFBB50 E
| CPFBB46 D | Cluster node &1 not removed from cluster
| Cluster resource service internal error. | resource group &2.
| CPFBB50 D
| Cluster node &1 not removed from cluster
| resource group &2. | Start Cluster Resource Group
| CPIBB10 D Cluster Resource Group exit program &1 in (QcstStartClusterResourceGroup) API
|
| library &2 on node &3 failed.

| Error Messages | Required Parameter Group:

| Messages that are delivered through the error code param- | 1 Request handle Output Char(16)
| eter are listed here. The data (messages) sent to the results | 2 Cluster name Input Char(10)
| information user queue are listed in the Usage Notes above. | 3 Cluster resource group Input Char(10)
| name
| CPF24B4 E Severe error while addressing parameter list. | 4 Exit program data Input Char(256)
| CPF3C1E E | 5 Results information Input Char(30)
| Required parameter &1 omitted. | 6 Error code I/O Char(*)
| CPF3C39 E
| Service Program: QCSTCRG2
| Value for reserved field not valid.
| CPF3CF1 E | Threadsafe: Yes
| Error code parameter not valid.
| CPF3CF2 E
| Error(s) occurred during running of &1 API. | The Start Cluster Resource Group API will enable resiliency
| CPF9801 E Object &2 in library &3 not found. | for the specified cluster resource group. The Start Cluster
| CPF9802 E Not authorized to object &2 in &3. | Resource Group API can be used to change cluster resource
| CPF9803 E Cannot allocate object &2 in library &3. | group from a status of Indoubt (30) or Inactive (20) to Active
| CPF9804 E Object &2 in library &3 damaged. | (10). Since some changes to the cluster resource group can
| CPF9810 E Library &1 not found. | only be performed when the cluster resource group is not
| CPF9872 E Program or service program &1 in library &2 | active, ensure that cluster resource group is correct before
| ended. Reason code &3. | calling this API.
| CPFBB02 E
| Cluster &1 does not exist. | This API will:
| CPFBB09 E | 1. Set the cluster resource group status to Start Cluster
| Cluster node &1 does not exist in Cluster &2. | Resource Group Pending (560).
| CPFBB0A E | 2. Call the Cluster Resource Group exit program with an
| Cluster node &1 not active in cluster &2. | action code of start (2) on all active nodes in the
| CPFBB0F E | recovery domain.
| Cluster resource group &1 does not exist in | 3. Set the cluster resource group status to active (10) if the
| cluster &2. | exit program is successful on all active nodes in the
| CPFBB1B E | recovery domain.
| Cluster node &1 does not exist in the recovery | 4. Start the TCP/IP interface on the primary node for a
| domain for cluster resource group &2. | cluster resource group type-2.
| 5. Perform the following on all nodes if the exit program is
| unsuccessful on any active node in the recovery domain:

Chapter 7. Cluster Resource Group APIs 7-33

 Start Cluster Resource Group (QcstStartClusterResourceGroup) API

| Ÿ Set the status of the cluster resource group to | Request handle

| indoubt (30). | OUTPUT; CHAR(16)
| Ÿ End the TCP/IP interface on the primary node for a
| A unique string or handle that identifies this API call. It
| cluster resource group type-2.
| is used to associate this call to any responses placed on
| Ÿ Cancel the exit program job with an option of
| the user queue specified in the results information
| *IMMED for a cluster resource group type-2.
| parameter.
| This API requires: | Cluster name
| 1. Cluster Resource Services active on the node running | INPUT; CHAR(10)
| the API. | The name of the cluster containing the cluster resource
| 2. The status of the node currently assigned the role of | group.
| primary must be active.
| 3. A cluster resource group status of inactive (20) or | Cluster Resource Group name
| indoubt(30). | INPUT; CHAR(10)
| 4. The user profile running the exit program must have | The name of the cluster resource group which will be
| *USE authority for the CRG. | started.
| For a type-2 CRG, the exit program is not expected to com-
| Exit program data
| plete on the primary node. The status of the CRG will be set
| INPUT; CHAR(256)
| to active (10) when the exit program job has been started on
| the primary and the exit program has completed successfully | 256 bytes of data that is passed to the cluster resource
| on all other nodes in the recovery domain. | group exit program when it is called. This parameter
| may contain any scalar data except pointers. For
| This API operates in an asynchronous mode. See “Cluster | example, it can be used to provide state information.
| Resource Services APIs Behavior” on page 5-2 for more | This data will be stored with the specified Cluster
| information. | Resource Group and copied to all nodes in the recovery
| domain. Pointers in this area will not resolve correctly on
| Restriction: | all nodes and should not be placed in the data. See
| This API cannot be called from a cluster resource group | “Cluster Resource Group Exit Program” on page 8-1 for
| exit program. | information about the cluster resource group exit
| program. The data specified will replace the existing exit
| program data stored with the Cluster Resource Group
| Authorities and Locks | before the exit program is called. If blanks are specified,
| then the exit program data stored with the Cluster
| This API is shipped with *EXCLUDE public authority. The
| Resource Group will be cleared. The following special
| program that calls this API must be running under a user
| value can be used:
| profile with *IOSYSCFG special authority.
| Cluster Resource Group Authority | *SAME The exit program data stored with the
| *CHANGE | Cluster Resource Group specified will be
| Cluster Resource Group Library Authority | passed to the exit program. This must be
| *EXECUTE | left justified.
| Cluster Resource Group Lock | Results information
| *EXCL | INPUT; CHAR(30)
| Exit Program Authority
| *EXECUTE | This parameter identifies a qualified user queue field and
| Exit Program Library Authority | is followed by a reserved field.
| *EXECUTE | Qualified user queue: Completion information is
| User Profile Authority | returned to this user queue, which exists on the node
| *USE | from which the API was called, after the function has
| Request Information User Queue Authority | completed on all active nodes in the cluster. See the
| *OBJOPR, *ADD | Usage Notes section of this API for a description of the
| Request Information User Queue Library Authority | data that is placed on this queue. This is a 20-character
| *EXECUTE | field. The first 10 characters contain the user queue
| Request Information User Queue Lock | name, and the second 10 characters contain the user
| *EXCLRD | queue library name. No special values are supported.
| QTEMP, *LIBL, *CURLIB are not valid library names.
| The attributes of this user queue must be keyed and
| Required Parameter Group | have a domain of user.

7-34 AS/400 System API Reference V4R4

 Start Cluster Resource Group (QcstStartClusterResourceGroup) API

| Reserved: The last 10 characters of the 30-character | TCP1B01 D

| results information are reserved. Each character in this | Unable to determine if &1 interface started.
| field must be set to hexadecimal zero. | TCP1B02 D
| Cannot determine if &1 interface started.
| Error code
| TCP1B05 D
| I/O; CHAR(*)
| &2 interface not started. Reason &1.
| The structure in which to return error information. For | TCP1B10 D
| the format of the structure, see “Error Code Parameter” | &2 interface not started.
| on page 2-6. | TCP1B11 D
| &1 interface not started. Tried to exceed
| maximum number of active interfaces allowed.
| Usage Notes | TCP1B12 D
| &1 interface not started. &1 interface already
| Results Information User Queue: Asynchronous
| active.
| results are returned to a user queue specified by the Results
| TCP1B13 D
| Information parameter of the API. See “Cluster APIs Use of
| &1 interface not started. &1 interface not
| User Queues” on page 5-2 and “Using Results Information”
| defined the TCP/IP configuration.
| on page 5-3 for details on how to create the results informa-
| TCP1B14 D
| tion user queue, the format of the entries, and how to use
| &1 interface not started. Line description &2
| the data placed on the queue. The data is sent to the user
| not found.
| queue in the form of a message identifier and the substitution
| TCP1B15 D
| data for the message (if any exists). The following identifies
| Line description &2 unusable. Internal errors
| the data sent to the user queue (excluding the message
| encountered.
| text).
| TCP1B16 D
| CPCBB01 C | &2 interface not started.
| Cluster Resource Services API &1 completed. | TCP1B25 D
| CPF2204 D User profile &1 not found. | &1 interface not started.
| CPF9801 D Object &2 in library &3 not found. | TCP9999 D Internal system error in program &1.
| CPF9802 D Not authorized to object &2 in &3.
| CPF9803 D Cannot allocate object &2 in library &3.
| CPF9804 D Object &2 in library &3 damaged. | Error Messages
| CPF9810 D Library &1 not found.
| Messages that are delivered through the error code param-
| CPFBB0A D
| eter are listed here. The data (messages) sent to the results
| Node &1 is not active in cluster &2.
| information user queue are listed in the Usage Notes above.
| CPFBB0F D
| Cluster resource group &1 does not exist in | CPF2204 E User profile &1 not found.
| cluster &2. | CPF24B4 E Severe error while addressing parameter list.
| CPFBB17 D | CPF3C1E E
| &1 API cannot be processed in cluster &2. | Required parameter &1 omitted.
| CPFBB18 D | CPF3C39 E
| Request &1 not allowed for cluster resource | Value for reserved field not valid.
| group &2. | CPF3CF2 E
| CPFBB2C D | Error(s) occurred during running of &1 API.
| Attributes of exit program &1 in library &2 are | CPF9801 E Object &2 in library &3 not found.
| not valid. | CPF9802 E Not authorized to object &2 in &3.
| CPFBB2D D | CPF9803 E Cannot allocate object &2 in library &3.
| Timeout detected while waiting for a response. | CPF9804 E Object &2 in library &3 damaged.
| CPFBB2E D | CPF9810 E Library &1 not found.
| Job submission failed for cluster resource group | CPFBB02 E
| &1 in cluster &2. | Cluster &1 does not exist.
| CPFBB32 D | CPFBB0A E
| Attributes of user queue &1 in library &2 are not | Node &1 is not active in cluster &2.
| valid. | CPFBB0F E
| CPFBB47 D | Cluster resource group &1 does not exist in
| Cluster Resource Services ended abnormally. | cluster &2.
| CPFBB48 D | CPFBB26 E
| Cluster Resource Services error detected. | Cluster Resource Services not active or not
| CPIBB10 D Cluster Resource Group exit program &1 in | responding.
| library &2 on node &3 failed.

Chapter 7. Cluster Resource Group APIs 7-35

 Start Cluster Resource Group (QcstStartClusterResourceGroup) API

| CPFBB2C E | CPFBB39 E
| Attributes of exit program &1 in library &2 are | Current user does not have IOSYSCFG special
| not valid. | authority.
| CPFBB32 D | CPFBB44 E
| Attributes of user queue &1 in library &2 are not | &1 API cannot be called from a cluster resource
| valid. | group exit program.
| CPFBB38 E | CPFBB46 E
| Library name &1 not allowed for this operation. | Cluster Resource Services internal error.

7-36 AS/400 System API Reference V4R4

 Cluster Resource Group Exit Program

| Chapter 8. Cluster Resource Group Exit Program

| For a Cluster Resource Group type-2, the Exit Program
| Cluster Resource Group Exit | should:
| Program—Introduction
| Ÿ Ensure integrity of any related cluster resource group
| This chapter describes the Cluster Resource Group exit | type-1 objects.
| program. | Ÿ Perform any setup work, configuration, or other require-
| ments for the application.
| Ÿ Start the application.
| Cluster Resource Group Exit Program | The functions that an API can perform on a cluster resource
| group depend on the type and status of the Cluster Resource
| Group. For more information, see the description for each
| Required Parameter Group: | API in the Chapter titled 'Cluster Resource Group APIs'.
| 1 Success indicator Output Binary(4)
| The only Cluster Resource Services APIs that can be called
| 2 Action code Input Binary(4)
| from a Cluster Resource Group exit program are:
| 3 Exit program data Input Char(256)
| 4 Information given to Input Char(*) | Ÿ List Cluster Resource Group Information API
| user | Ÿ List Cluster Resource Group API
| 5 Format name Input Char(8) | Ÿ List Cluster Information

| The cluster resource group Exit Program will be called when:

| The Cluster Resource Group exit program is called during
| Ÿ a node leaves the cluster unexpectedly.
| different phases of a cluster environment. This program is
| Ÿ a node leaves the cluster as a result of the End Cluster
| responsible for establishing and managing the environment
| Node API or Remove Cluster Node Entry API.
| necessary for data or application resiliency within a cluster.
| Ÿ The cluster is deleted as a result of the Delete Cluster
| When an API is run, the exit program is called from a sepa- | API.
| rate job with the user profile specified on the Create Cluster | Ÿ a node is activated by via the Start Cluster Node API.
| Resource Group API. If the exit program for a Cluster | Ÿ communication with a partitioned node is reestablished.
| Resource Group type-1 is unsuccessful or ends abnormally, | Ÿ any cluster resource group API (other than either List
| the Cluster Resource Group Exit Program will be called on | API), is run.
| all active nodes in the recovery domain with an action code
| This exit program:
| of Undo (15). This allows any unfinished activity to be
| backed out and the original state of the cluster resource | Ÿ runs in a named activation group or the caller's acti-
| group to be recovered. | vation group (*CALLER).
| Ÿ ignores the restart parameter if the exit program has an
| In general, if the exit program for a Cluster Resource Group | unhandled exception or is cancelled.
| type-2 is unsuccessful or ends abnormally, Cluster Resource | Ÿ provides a cancel handler.
| Services will attempt to restart the application. The cluster
| resource group exit program will be called with an action | Rules:
| code of restart (3). If the application cannot be restarted in | Exit Program Rule
| the specified maximum number of attempts, the cluster | The exit program is called on all active nodes
| resource group exit program will be called with an action | in the recovery domain.
| code of failover (9). During a switchover operation of a | Backup Order Rule
| cluster resource group type-2, if the exit program fails,
| Cluster Resource Services will call the exit program with an | Ÿ When the primary fails, backup 1
| action code of Undo (15). | becomes the primary.
| Ÿ If a backup nodes fails, the node role
| Before the exit program ends, the value of the Success Indi-
| number, for all backup nodes with a
| cator must be set. If an exit program returns a Success
| higher node role number, is decremented
| Indicator of 1 (unsuccessful), the exit program is called on
| by one; that is, moved up in the
| all active nodes in the recovery domain with an action code
| heirarchy.
| of Undo (15). If the exit program fails while processing an
| Ÿ If only one backup exists, when it fails the
| Undo (15), the cluster resource group status will be set to
| cluster resource group is no longer resil-
| Indoubt (30). The Prior Action Code field contains the
| ient. Therefore, the exit program running
| unfinished action code.
| on the primary node should handle this
| situation.

 Copyright IBM Corp. 1998, 1999 8-1

 Cluster Resource Group Exit Program

| Joining Rule When a node is added to the recovery domain | The action codes listed below apply to both types of
| of a cluster resource group, it is assigned the | cluster resource group objects, unless otherwise speci-
| role specified in the node role parameter on | fied.
| the Add Node to Recovery Domain API. The
| Possible action codes:
| cluster resource group exit program will be
| called with an action code of Add Node (11). | 1 - InitializeA cluster resource group object is being
| ReJoining Rule | created.
| When an inactive node that is a member of a | 2 - Start Establish resilience for a cluster resource
| recovery domain becomes active, it is | group. In addition, start the application for
| assigned a current role in the recovery domain | a Cluster Resource Group type-2.
| based on its preferred role: | 3 - Restart Restarts an application. Applies only to
| Ÿ the primary is assigned the role of Last | cluster resource group type-2.
| backup. | 4 - End Disable resilience of a cluster resource
| Ÿ a backup is assigned the role of Last | group on all nodes in the recovery
| backup. | domain. This function could be used prior
| Ÿ a replicate is assigned the role of repli- | to running PWRDWNSYS on all nodes in
| cate. | the recovery domain in order to avoid any
| Leaving Rule When a node is removed from the recovery | failover or switchover operations.
| domain in a cluster resource group, the cluster | 7 - Delete The Cluster Resource Group object is
| resource group exit program is called with an | being deleted.
| action code of Remove Node (12). | 8 - Rejoin An inactive node is being activiated or
| communication with a partitioned node is
| Restrictions: | re-established.
| The cluster resource group exit program runs in a | 9 - Failover A node failure has occurred.
| named activation group or the caller's activation group | 10 - Switchover
| (*CALLER). | Initiate Switchover API is being pro-
| The cluster resource group exit program should have an | cessed. The role of primary is being
| unmonitored exception handler. If the cluster resource | assigned to the node that has the current
| group exit program does not have an unmonitored | role of first backup.
| exception handler, the exit program restart is ignored. | 11 - Add Node
| The cluster resource group exit program should have a | A node is being added to the recovery
| cancel handler. If the job that called the cluster resource | domain.
| group exit program is cancelled while the exit program is | 12 - Remove Node
| running, the cancel handler can set the success indicator | A node is being removed from the
| to indicate that the action was not successfully com- | recovery domain.
| pleted. | 13 - Change The nodes listed in the recovery domain
| have changed their role or order.
| 14 - Delete Command
| Required Parameter Group | The Cluster Resource Group is being
| Success indicator | deleted on the local node only.
| OUTPUT; BINARY(4) | 15 - Undo Backout the prior request. The prior
| request is in the Prior Action Code field.
| Indicates to Cluster Resource Services the results of the | 16 - End Node
| cluster resource group exit program. The exit program | A cluster node is ending.
| must set this parameter. If the job running the exit
| program is cancelled before the exit program completes, | Exit program data
| the exit program cancel handler sets this parameter. | INPUT; CHAR(256)
| Possible values of this parameter: | This parameter can contain anything. For example, it
| 0 Successful. | can be used to provide state information. The owner of
| 1 Unsuccessful, do not attempt restart. | the cluster resource group knows the layout of the infor-
| 2 Unsuccessful, attempt restart (applies | mation contained in this parameter. Because this
| only to a CRG type-2). | parameter is passed between nodes in the cluster, do
| not store pointers in this area.
| This field is ignored by the Delete Cluster Resource
| This data comes into existence when the cluster
| Group, End Cluster Resource Group, and Remove Node
| resource group object is created with the Create Cluster
| from Recovery Domain APIs.
| Resource Group API, see “Create Cluster Resource
| Action code | Group (QcstCreateClusterResourceGroup) API” on
| INPUT; BINARY(4) | page 7-13. Change this data with the Change Cluster
| Resource Group, End Cluster Resource Group, Add
| Identifies the action the exit program should perform.

8-2 AS/400 System API Reference V4R4

 Cluster Resource Group Exit Program

| Node to Recovery Domain, Initiate Switchover, and

| Offset
| Remove Node from Recovery Domain APIs, see the
| description of each API in the the chapter titled 'Cluster | Dec Hex Type Field
| Resource Group APIs'. “Change Cluster Resource | These fields CHAR(8) Node id
| Group (QcstChangeClusterResourceGroup) API” on | repeat, in the
| BINARY(4) Node role
| page 7-8. | order listed,
| for each node BINARY(4) Membership status
| Information given to user | in the
| INPUT; CHAR(*) | recovery
| domain.
| Detailed information for this exit program call. See the
| “EXTP0100 Format” for more information.

| Format name | Field Descriptions

| INPUT; CHAR(8)
| Changing node id. Node in the recovery domain being
| The format of the information provided in the Information | assigned a new role. This field is hex zeroes if it doesn't
| Given To User parameter. The format name supported | apply. This field is used during an Initiate SwitchOver API,
| is: | Add Node to Recovery Domain API, Remove Node from
| Recovery Domain API, Change Cluster Resource Group API,
| EXTP0100 This format is used for actions.
| or a failover. A special value of *LIST is specified for this
| parameter when the action code is failover (9) or change (13)
| EXTP0100 Format | that involves changes to the recovery domain. The special
| value is left-justified.
| This format is used for all action codes.
| Changing node role. The role the node is being assigned.
| Offset | This field is used during an Initiate SwitchOver API, Add
| Node to Recovery Domain API, Remove Node from
| Dec Hex Type Field
| Recovery Domain API, Change Cluster Resource Group API,
| 0 0 BINARY(4) Length of information | or a failover. The values are:
| given to user
| 0 Primary node. Only one node can have this
| 4 4 CHAR(10) Cluster name
| value.
| 14 E CHAR(10) Cluster resource group | ≥1 Backup node. The backup order is designated
| name | by increasing value. The values need not be
| 24 18 BINARY(4) Cluster resource group | consecutive. No two backup nodes can have
| type | the same value. At the completion of the API,
| 28 1C BINARY(4) Cluster resource group | Cluster Resource Services will sequence the
| status | backups using consecutive numbers starting
| with 1.
| 32 20 CHAR(16) Request handle
| -1 Replicate node. All replicates have this value.
| 48 30 BINARY(4) Node role type | -2 Changing node role not used by the action
| 52 34 CHAR(8) Current node id | code being processed.
| 60 3C CHAR(8) Changing node id | -3 *LIST.

| 68 44 BINARY(4) Changing node role | Cluster name. The name of the cluster containing the
| 72 48 CHAR(16) Takeover IP address | cluster resource group.
| 88 58 CHAR(10) Job name
| Cluster resource group changes. A bit mask that identifies
| 98 62 CHAR(2) Reserved | the fields in the cluster resource group that are being
| 100 64 BINARY(8) Cluster resource group | changed by the Change Cluster Resource Group. Set to hex
| changes | zeroes for all other exit program calls. The 64 bits in this
| field are numbered 0 thru 63 starting with the rightmost bit. If
| 108 6C BINARY(8) Prior action code
| a bit is set to '1', it indicates that the action represented by
| 116 74 BINARY(4) Offset to recovery domain | the bit is occurring. The meaning of each of the bits are:
| array
| 0 Recovery domain is changing
| 120 78 BINARY(4) Number of nodes in the
| 1 Takeover IP address is changing
| recovery domain
| 2-63 Reserved. These should be set to '0'.
| 124 7C Array(*) of Recovery domain array
| Char(16) | Cluster resource group name. The cluster resource group
| that is being processed by Cluster Resource Services.

Chapter 8. Cluster Resource Group Exit Program 8-3

 Cluster Resource Group Exit Program

| Cluster resource group status. Status of the cluster | Number of nodes in the recovery domain. The number of
| resource group at the time the exit program was called. See | nodes in the recovery domain. This is the number of ele-
| page 7-26 for the possible values. | ments there are in the Recovery Domain Array.

| Cluster resource group type. The type of cluster resource | Offset to recovery domain array. The byte offset from the
| group: | beginning of this entry to the list of nodes in the recovery
| domain.
| 1 Data resiliency
| 2 Application resiliency
| Preffered node role The preferred role a node is assigned:
| Current node id. Identifies the node running the exit | 0 Primary node. Only one node can have this
| program. | value.
| ≥1 Backup node. The backup order is designated
| Job name. Name of the job associated with a cluster | by increasing value. The values need not be
| resource group type-2 exit program. | consecutive. No two backup nodes can have
| the same value. At the completion of the API,
| Length of information given to user. Actual length of the
| Cluster Resource Services will sequence the
| information in the exit program data field.
| backups using consecutive numbers starting
| with 1.
| Membership status. The cluster resource group member-
| -1 Replicate node. All replicates have this value.
| ship status for the current role of a node:
| 0 Inactive | Prior action code. When a Cluster Resource Group Exit
| 1 Active | Program is called with an action code of Undo (15), the
| 2 Partition | action code for the unsuccessful operation is placed in this
| field. Otherwise, this will be hex zeroes.
| Node id. A unique string of chararcters that identifies a
| node in the recovery domain. | Recovery domain array. The nodes that are the recovery
| domain for the cluster resource group.
| Node role The role a node is to be assigned at the suc-
| cessful completion of the action code being processed. | Request handle. Uniquely identifies the API request. It is
| used to associate responses on the user queue specified in
| 0 Primary node. Only one node can have this
| the Results Information parameter. This field will have a null
| value.
| value when the exit program is called with an action code of
| ≥1 Backup node. The backup order is designated
| failover (9).
| by increasing value. The values need not be
| consecutive. No two backup nodes can have
| Reserved. This field is reserved and is set to hex zeroes.
| the same value. At the completion of the API,
| Cluster Resource Services will sequence the | Takeover IP address. This is the floating IP address that is
| backups using consecutive numbers starting | associated with an application. This is a dotted decimal field
| with 1. | and is a null-terminated string.
| -1 Replicate node. All replicates have this value.
| This value is not valid for a cluster resource
| group type-2. | Reasons an Exit Program Is Called
| Node role type. Indicates which of the two node roles is | The table below shows the reasons an exit program is called
| being processed: | and maps the reason to the Action Code parameter on the
| Cluster Resource Group Exit Program. The following Cluster
| 1 Current | Resource Group Manager APIs do not cause the Cluster
| 2 Preferred | Resource Group Exit Program to be called:
| Ÿ List Cluster Resource Group Information
| Ÿ List Cluster Resource Groups

8-4 AS/400 System API Reference V4R4

 Cluster Resource Group Exit Program

| Figure 8-1 (Page 1 of 3). Reasons an Exit Program Is Called

| Reason an Exit Program Is Action Code Parameter Supplied by Replication Pro- Supplied by Application Pro-
| Called Passed to Exit Program vider vider
| Exit Program Actions - Data Exit Program Actions -
| Resiliency Application Resiliency
| Create Cluster Resource 1 (Initialize) Put data on all nodes in the Put applications on all nodes
| Group API recovery domain. Prime all in the recovery domain. Prime
|| This API creates a cluster
nodes in the recovery domain. all nodes in the recovery
|| resource group object, which
domain.
| identifies a recovery domain.
| Start Cluster Resource 2 (Start) Ÿ Start journaling. Ÿ Start server jobs.
| Group API Ÿ Start replication. Ÿ Keep track of server jobs
|| This API establishes resiliency
started. This will be
|| for a Cluster Resource Group.
needed when server jobs
| are restarted or the End
| Cluster Resource Group
| API is called.
| Cluster Resource Group exit 3 (Restart) Not called. Ÿ Restart server jobs if nec-
| program ends abnormally or essary.
| unexpectly.
| End Cluster Resource Group 4 (End) Ÿ Stop replication. Ÿ End server jobs.
| API Ÿ End journaling. Ÿ End application resilience.
| This API will disable resilience
| for a cluster resource group
| object.
| 5 (Reserved)
| 6 (Reserved)
| Delete Cluster Resource 7 (Delete) 7 (Delete) 7 (Delete)
| Group API
| This API deletes a cluster
| resource group object from all
| nodes in the recovery domain.
| Start Cluster Node API 8 (Rejoin) Ÿ Resynchronize data Start application if the cluster
|| This API is used to start
Ÿ Start replication if the resource group status is active
|| Cluster Resource Services on
cluster resource group (10)
|| one or more nodes in the
status is active (10)
| cluster.
| Node failure or resource 9 (Failover) Ÿ Get data objects to Ÿ Make sure exit program
| failure. highest level of currency. data contains all key infor-
| Ÿ Redirect remote journal mation for application
| receivers. restart. This can be
| accomplished by the
| Change Cluster Resource
| Group API.
| Ÿ Use exit program data to
| restart application at last
| known point. Exit
| program data must
| contain enough key infor-
| mation for most effective
| restart.
| Ÿ Restart server jobs after
| data is current. Actually
| occurs when the Cluster
| Resource Services calls
| the Cluster Resource
| Group Exit Program with
| an action code of 2 (Start)
| on the new primary only.

Chapter 8. Cluster Resource Group Exit Program 8-5

 Cluster Resource Group Exit Program

| Figure 8-1 (Page 2 of 3). Reasons an Exit Program Is Called

| Reason an Exit Program Is Action Code Parameter Supplied by Replication Pro- Supplied by Application Pro-
| Called Passed to Exit Program vider vider
| Exit Program Actions - Data Exit Program Actions -
| Resiliency Application Resiliency
| Initiate Switch Over API 10 (Switchover) Ÿ Stop replication on primary Ÿ Make sure exit program
|| This API changes the current
and journaling. data contains all key infor-
|| role of a node in the recovery
Ÿ Continue replication on mation for application
|| domain of a cluster resource
other active nodes in the restart before the Initiate
|| group by switching the access
recovery domain. This is Switch Over API is called.
|| point from the primary node to
a combination of 4 (End) Ÿ 10 (Switchover - Pre-exit
|| the first backup.
and 9 (Failover). program)
| – Stop server jobs.
| Ÿ 2 (Start - Post-exit
| program)
| – Use exit program data
| to restart application
| at last known point.
| Exit program data
| must contain enough
| key information for
| most effective restart.
| – Restart server jobs
| after data is current.
| Add Node to Recovery 11 (Add Node) Exit program actions per- Perform 1 (Initialize) on the
| Domain API formed on the node being node being added.
|| This API will add a node ID to
added:
| the recovery domain of a Ÿ If cluster resource group is
| cluster resource group. Active, do 1 (Initialize) and
| 2 (Start) actions.
| Ÿ If cluster resource group is
| Inactive, do 1 (Initialize)
| action.
| Remove Node from 12 (Remove Node) Exit program actions on the Exit program actions on the
| Recovery Domain API node being removed: node being removed:
| This API will remove a node Ÿ If the cluster resource Ÿ If the cluster resource
| from the recovery domain of a group is Active, do 4 (End) group is Active, do 4
| cluster resource group. and 7 (Delete) (End) and 7 (Delete)
| Ÿ If cluster resource group is Ÿ If cluster resource group is
| Inactive, do 7 (Delete) Inactive, do 7 (Delete)
| action. action.
| Change Cluster Resource 13 (Change) Ÿ Redirect replication if nec-
| Group API essary.
|| This API changes some of the
Ÿ Redirect journaling if nec-
|| attributes of a cluster resource
essary.
| group. Only if the recovery
| domain is changed will the
| cluster resource group exit
| program be called.
| Delete Cluster Resource 14 (Delete Command)
| Group CL command
| This CL command deletes a
| cluster resource group object
| from the node running the
| command. This is not a distrib-
| uted request.
| 15(Undo) Rollback operations from pre- Rollback operations from pre-
| vious request. vious request.

8-6 AS/400 System API Reference V4R4

 Cluster Resource Group Exit Program

| Figure 8-1 (Page 3 of 3). Reasons an Exit Program Is Called

| Reason an Exit Program Is Action Code Parameter Supplied by Replication Pro- Supplied by Application Pro-
| Called Passed to Exit Program vider vider
| Exit Program Actions - Data Exit Program Actions -
| Resiliency Application Resiliency
| End Cluster Node API 16(End Node). On the node being ended: On the node being ended:
| The End Cluster Node API is Ÿ Do 4 (End) and 13 Ÿ Do 4 (End) and 13
| used to end Cluster Resource (Change) if the cluster (Change) if the cluster
| Services on a node in the resource group status is resource group status is
| recovery domain. active (10). active (10).
| Ÿ Do 13 (Change) if the Ÿ Do 13 (Change) if the
| cluster resource group cluster resource group
| status is inactive(20) or status is inactive(20) or
| indoubt (30). indoubt (30).
| If the node assigned the If the node assigned the
| primary role is ended, exit primary role is ended, exit
| program actions on the first program actions on the first
| backup: backup:
| Ÿ If the cluster resource Ÿ If the cluster resource
| group status is active (10) group status is active (10)
| do 9 (Failover). do 9 (Failover).
| Ÿ If the cluster resource Ÿ If the cluster resource
| group status is inactive group status is inactive
| (20) or indoubt (30) do 13 (20) or indoubt (30) do 13
| (Change). (Change).

Chapter 8. Cluster Resource Group Exit Program 8-7

Cluster Resource Group Exit Program

8-8 AS/400 System API Reference V4R4

 Communications

Part 5. Communications APIs

Chapter 9. User-Defined Chapter 11. Configuration and Queue Entries . . 11-1

Communications—Introduction . . . . . . . . . . . 9-1 Configuring User-Defined Communications Support . 11-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Links . . . . . . . . . . . . . . . . . . . . . . . . 11-1
User-Defined Communications Callable Routines . 9-1 Queue . . . . . . . . . . . . . . . . . . . . . . . 11-1
Input/Output Buffers and Descriptors . . . . . . . . 9-2 Queue Entries . . . . . . . . . . . . . . . . . . . . 11-1
Queues . . . . . . . . . . . . . . . . . . . . . . . 9-2 General Format . . . . . . . . . . . . . . . . . . 11-1
Terminology . . . . . . . . . . . . . . . . . . . . . . . 9-2 Enable-Complete Entry . . . . . . . . . . . . . . 11-2
Relationship to Communications Standards . . . . . . 9-2 Disable-Complete Entry . . . . . . . . . . . . . . 11-2
Local Area Network (LAN) Considerations . . . . . . . 9-4 Permanent-Link-Failure Entry . . . . . . . . . . . 11-3
X.25 Considerations . . . . . . . . . . . . . . . . . . 9-5 Incoming-Data Entry . . . . . . . . . . . . . . . . 11-3
Timer-Expired Entry . . . . . . . . . . . . . . . . 11-3
Chapter 10. Programming Design Considerations 10-1
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 Chapter 12. User-Defined Communications
Application Program Feedback . . . . . . . . . . . . 10-2 Support APIs . . . . . . . . . . . . . . . . . . . . 12-1
Synchronous and Asynchronous Operations . . . 10-2 User-Defined Communications Support
Programming Languages . . . . . . . . . . . . . . . 10-3 APIs—Introduction . . . . . . . . . . . . . . . . . 12-1
Starting and Ending Communications . . . . . . . . 10-3 Disable Link (QOLDLINK) API . . . . . . . . . . . . 12-1
Using Connection Identifiers . . . . . . . . . . . 10-3 Required Parameter Group . . . . . . . . . . . . 12-1
Incoming Connections . . . . . . . . . . . . . 10-13 Return and Reason Codes . . . . . . . . . . . . 12-1
Closing Connections . . . . . . . . . . . . . . 10-17 Enable Link (QOLELINK) API . . . . . . . . . . . . 12-2
Programming Considerations for LAN Applications . 10-18 Authorities and Locks . . . . . . . . . . . . . . . 12-2
Operations . . . . . . . . . . . . . . . . . . . 10-18 Required Parameter Group . . . . . . . . . . . . 12-2
Configuration . . . . . . . . . . . . . . . . . . . 10-18 Optional Parameter Group . . . . . . . . . . . . 12-4
Inbound Routing Information . . . . . . . . . . . 10-19 Return and Reason Codes . . . . . . . . . . . . 12-4
End-to-End Connectivity . . . . . . . . . . . . . . 10-19 Error Messages . . . . . . . . . . . . . . . . . . 12-5
Sending and Receiving Data . . . . . . . . . . . 10-19 Query Line Description (QOLQLIND) API . . . . . . 12-5
Maximum Frame Size . . . . . . . . . . . . . 10-19 Required Parameter Group . . . . . . . . . . . . 12-6
Maximum Amount of Outstanding Data . . . . 10-19 Optional Parameter Group . . . . . . . . . . . . 12-6
Ethernet to Token-Ring Conversion and Routing . 10-20 Format of Data in the User Buffer . . . . . . . . . 12-7
Performance Considerations . . . . . . . . . . . 10-20 LAN Specific Data–Format 01 . . . . . . . . . 12-7
Programming Considerations for X.25 Applications . 10-20 LAN Specific Data–Format 02 . . . . . . . . . 12-8
X.25 Packet Types Supported . . . . . . . . . . 10-20 X.25 Specific Data–Format 01 . . . . . . . . . 12-9
Operations . . . . . . . . . . . . . . . . . . . 10-21 X.25 Specific Data–Format 02 . . . . . . . . . 12-10
Connections . . . . . . . . . . . . . . . . . . . . 10-21 Return and Reason Codes . . . . . . . . . . . . 12-13
Connection Identifiers . . . . . . . . . . . . . 10-22 Error Messages . . . . . . . . . . . . . . . . . . 12-14
Connection Information . . . . . . . . . . . . . 10-22 Receive Data (QOLRECV) API . . . . . . . . . . . . 12-14
Switched Virtual Circuit (SVC) Connectivity . . . . 10-22 Required Parameter Group . . . . . . . . . . . . 12-14
Configuration . . . . . . . . . . . . . . . . . . 10-22 Format of Diagnostic Data Parameter . . . . . . . 12-15
Inbound Routing Information . . . . . . . . . . 10-22 LAN Input Operations . . . . . . . . . . . . . . . 12-16
End-to-End Connectivity . . . . . . . . . . . . 10-23 Data Unit Format–LAN Operation X'0001' . . . 12-17
Permanent Virtual Circuit (PVC) Connectivity . . . 10-23 Input Buffer Descriptor Element Format–LAN
Configuration . . . . . . . . . . . . . . . . . . 10-23 Operation X'0001' . . . . . . . . . . . . . . . 12-18
Inbound Routing Information . . . . . . . . . . 10-23 X.25 SVC and PVC Input Operations . . . . . . . 12-18
End-to-End Connectivity . . . . . . . . . . . . 10-23 X.25 Operation X'0001' . . . . . . . . . . . . . 12-18
Sending and Receiving Data Packets . . . . . . . 10-23 X.25 Operation X'B001' . . . . . . . . . . . . 12-19
Data Sizes . . . . . . . . . . . . . . . . . . . 10-23 X.25 Operation X'B101' . . . . . . . . . . . . 12-21
Interrupts . . . . . . . . . . . . . . . . . . . . 10-24 X.25 Operation X'B111' . . . . . . . . . . . . 12-21
Flow Control . . . . . . . . . . . . . . . . . . 10-24 X.25 Operation X'B201' . . . . . . . . . . . . 12-21
Maximum Amount of Outstanding Data . . . . 10-24 X.25 Operation X'B301' . . . . . . . . . . . . 12-23
Reset Support . . . . . . . . . . . . . . . . . 10-24 X.25 Operation X'B311' . . . . . . . . . . . . 12-23
AS/400 System X.25 Call Control . . . . . . . . . 10-24 X.25 Operation X'BF01' . . . . . . . . . . . . 12-23
Performance Considerations . . . . . . . . . . . 10-24 Return and Reason Codes . . . . . . . . . . . . 12-23
Queue Considerations . . . . . . . . . . . . . . . . 10-25 LAN Return and Reason Codes . . . . . . . . 12-23
User Space Considerations . . . . . . . . . . . . . 10-26 X.25 Return and Reason Codes . . . . . . . . 12-24
Return Codes and Reason Codes . . . . . . . . . . 10-27 Error Messages . . . . . . . . . . . . . . . . . . 12-27
Messages . . . . . . . . . . . . . . . . . . . . . . . 10-27

 Copyright IBM Corp. 1998, 1999

Communications

Send Data (QOLSEND) API . . . . . . . . . . . . . 12-27 Common Errors and Messages . . . . . . . . . 13-11
. .
Required Parameter Group . . . . . . . . . . . . 12-28 Parameter Errors . . . . . . . . . . . . . . 13-11
. .
Diagnostic Data Parameter Format . . . . . . 12-29 User Space Errors . . . . . . . . . . . . . 13-12
. .
LAN Output Operations . . . . . . . . . . . . . . 12-30 Queue Errors . . . . . . . . . . . . . . . . 13-12
. .
Data Unit Format–LAN Operation X'0000' . . . 12-30 Receive Data (QOLRECV) API Errors . . . 13-12
. .
Output Buffer Descriptor Element Format–LAN Send Data (QOLSEND) API Errors . . . . 13-12
. .
Operation X'0000' . . . . . . . . . . . . . . . 12-31 Enable Link (QOLELINK) API Errors . . . . 13-12
. .
X.25 SVC and PVC Output Operations . . . . . . 12-31 Query Line Description (QOLQLIND) API Errors 13-12
X.25 Operation X'0000' . . . . . . . . . . . . . 12-32
X.25 Operation X'B000' . . . . . . . . . . . . 12-33 Chapter 14. Data Stream Translation APIs . . . . 14-1
X.25 Operation X'B100' . . . . . . . . . . . . 12-37 Data Stream Translation APIs—Introduction . . . . . 14-1
X.25 Operation X'B110' . . . . . . . . . . . . 12-37 Using the Data Stream Translation APIs . . . . . . . 14-1
X.25 Operation X'B400' . . . . . . . . . . . . 12-37 Programming Restrictions . . . . . . . . . . . . . 14-1
X.25 Operation X'BF00' . . . . . . . . . . . . 12-39 End Data Stream Translation Session (QD0ENDTS)
Return and Reason Codes . . . . . . . . . . . . 12-40 API . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
LAN Return and Reason Codes . . . . . . . . 12-40 Required Parameter Group . . . . . . . . . . . . 14-2
X.25 Return and Reason Codes . . . . . . . . 12-41 Error Messages . . . . . . . . . . . . . . . . . . 14-2
Error Messages . . . . . . . . . . . . . . . . . . 12-43 Start Data Stream Translation Session (QD0STRTS)
Set Filter (QOLSETF) API . . . . . . . . . . . . . . 12-43 API . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Required Parameter Group . . . . . . . . . . . . 12-44 Authorities and Locks . . . . . . . . . . . . . . . 14-2
Format of Filter Information . . . . . . . . . . . . 12-44 Required Parameter Group . . . . . . . . . . . . 14-2
X.25 Filters (Filter Types X'00' and X'01') . . . 12-45 Error Messages . . . . . . . . . . . . . . . . . . 14-3
LAN Filters (Filter Types X'02', X'03', and X'04') 12-46 Translate Data Stream (QD0TRNDS) API . . . . . . 14-3
LAN Filters (Filter Type X'08') . . . . . . . . . 12-47 Required Parameter Group . . . . . . . . . . . . 14-4
General Rules for Using Filters . . . . . . . . . . 12-48 Error Messages . . . . . . . . . . . . . . . . . . 14-4
Return and Reason Codes . . . . . . . . . . . . 12-48
Error Messages . . . . . . . . . . . . . . . . . . 12-49 Chapter 15. OptiConnect APIs . . . . . . . . . . . 15-1
Set Timer (QOLTIMER) API . . . . . . . . . . . . . 12-49 OptiConnect APIs—Introduction . . . . . . . . . . . 15-1
Required Parameter Group . . . . . . . . . . . . 12-50 Close Path (QzdmClosePath) API . . . . . . . . . . 15-1
Optional Parameter . . . . . . . . . . . . . . . . 12-51 Restrictions . . . . . . . . . . . . . . . . . . . . 15-1
Return and Reason Codes . . . . . . . . . . . . 12-51 Authority and Locks . . . . . . . . . . . . . . . . 15-1
Error Messages . . . . . . . . . . . . . . . . . . 12-51 Required Parameter Group . . . . . . . . . . . . 15-2
CPTH0100 Format . . . . . . . . . . . . . . . . 15-2
Chapter 13. Debugging of User-Defined Field Descriptions . . . . . . . . . . . . . . . . . 15-2
Communications Applications . . . . . . . . . . 13-1 Error Messages . . . . . . . . . . . . . . . . . . 15-2
System Services and Tools . . . . . . . . . . . . . 13-1 Close Stream (QzdmCloseStream) API . . . . . . . 15-2
Program Debug . . . . . . . . . . . . . . . . . . 13-1 Restrictions . . . . . . . . . . . . . . . . . . . . 15-2
Work with Communications Status . . . . . . . . 13-1 Authority and Locks . . . . . . . . . . . . . . . . 15-2
Display Job Log . . . . . . . . . . . . . . . . . . 13-1 Required Parameter Group . . . . . . . . . . . . 15-2
Display Connection Status . . . . . . . . . . . . 13-1 CSTR0100 Format . . . . . . . . . . . . . . . . 15-3
Display Inbound Routing Information . . . . . . . 13-1 Field Descriptions . . . . . . . . . . . . . . . . . 15-3
Work with Communications Trace . . . . . . . . . 13-1 Error Messages . . . . . . . . . . . . . . . . . . 15-3
Work with Error Log . . . . . . . . . . . . . . . . 13-2 Open Path (QzdmOpenPath) API . . . . . . . . . . 15-3
Dump System Object to View User Spaces . . . 13-2 Restrictions . . . . . . . . . . . . . . . . . . . . 15-3
User Space to Set a Filter to Route Inbound Data 13-2 Authority and Locks . . . . . . . . . . . . . . . . 15-4
User Space for X'B000' Operation, Initiating an Required Parameter Group . . . . . . . . . . . . 15-4
SVC Call . . . . . . . . . . . . . . . . . . . 13-3 OPRC0100 Format . . . . . . . . . . . . . . . . 15-4
User Space Containing an Incoming X.25 Call, OPRQ0100 Format . . . . . . . . . . . . . . . . 15-4
Operation X'B201' . . . . . . . . . . . . . . 13-3 Field Descriptions . . . . . . . . . . . . . . . . . 15-4
User Space to Accept an Incoming X.25 Call, Error Messages . . . . . . . . . . . . . . . . . . 15-5
Operation X'B400' . . . . . . . . . . . . . . 13-4 Open Stream (QzdmOpenStream) API . . . . . . . . 15-5
User Spaces for Sending Data, Operation Restrictions . . . . . . . . . . . . . . . . . . . . 15-5
X'0000' . . . . . . . . . . . . . . . . . . . . 13-5 Authority and Locks . . . . . . . . . . . . . . . . 15-5
User Spaces for Receiving Data, Operation Required Parameter Group . . . . . . . . . . . . 15-5
X'0001' . . . . . . . . . . . . . . . . . . . . 13-7 OSTR0100 Format . . . . . . . . . . . . . . . . 15-5
User Space to Clear a Connection or Call, Field Descriptions . . . . . . . . . . . . . . . . . 15-6
Operation X'B100' . . . . . . . . . . . . . . 13-8 Error Messages . . . . . . . . . . . . . . . . . . 15-6
Error Codes . . . . . . . . . . . . . . . . . . . . . . 13-9 Receive Control (QzdmReceiveControl) API . . . . . 15-6
Local Area Network (LAN) Error Codes . . . . . . 13-9 Restrictions . . . . . . . . . . . . . . . . . . . . 15-6
X.25 Error Codes . . . . . . . . . . . . . . . . . 13-9 Authority and Locks . . . . . . . . . . . . . . . . 15-6

AS/400 System API Reference V4R4

 Communications

Required Parameter Group . . . . . . . . . . . . 15-6 Restrictions . . . . . . . . . . . . . . . . . . . . 15-11

RCRC0100 Format . . . . . . . . . . . . . . . . 15-7 Authority and Locks . . . . . . . . . . . . . . . . 15-11
RCRQ0100 Format . . . . . . . . . . . . . . . . 15-7 Required Parameter Group . . . . . . . . . . . . 15-11
Field Descriptions . . . . . . . . . . . . . . . . . 15-7 SRRC0100 Format . . . . . . . . . . . . . . . . 15-12
Error Messages . . . . . . . . . . . . . . . . . . 15-7 SRRQ0100 Format . . . . . . . . . . . . . . . . 15-12
Receive Request (QzdmReceiveRequest) API . . . . 15-7 Field Descriptions . . . . . . . . . . . . . . . . . 15-12
Restrictions . . . . . . . . . . . . . . . . . . . . 15-7 Error Messages . . . . . . . . . . . . . . . . . . 15-13
Authority and Locks . . . . . . . . . . . . . . . . 15-8 Send Response (QzdmSendResponse) API . . . . . 15-13
Required Parameter Group . . . . . . . . . . . . 15-8 Restrictions . . . . . . . . . . . . . . . . . . . . 15-13
RQRC0100 Format . . . . . . . . . . . . . . . . 15-8 Authority and Locks . . . . . . . . . . . . . . . . 15-13
RQRQ0100 Format . . . . . . . . . . . . . . . . 15-8 Required Parameter Group . . . . . . . . . . . . 15-13
Field Descriptions . . . . . . . . . . . . . . . . . 15-8 SRSP0100 Format . . . . . . . . . . . . . . . . 15-14
Error Messages . . . . . . . . . . . . . . . . . . 15-9 Field Descriptions . . . . . . . . . . . . . . . . . 15-14
Receive Response (QzdmReceiveResponse) API . . 15-9 Error Messages . . . . . . . . . . . . . . . . . . 15-14
Restrictions . . . . . . . . . . . . . . . . . . . . 15-10 Wait Message (QzdmWaitMessage) API . . . . . . . 15-14
Authority and Locks . . . . . . . . . . . . . . . . 15-10 Restrictions . . . . . . . . . . . . . . . . . . . . 15-15
Required Parameter Group . . . . . . . . . . . . 15-10 Authority and Locks . . . . . . . . . . . . . . . . 15-15
RSRC0100 Format . . . . . . . . . . . . . . . . 15-10 Required Parameter Group . . . . . . . . . . . . 15-15
RSRQ0100 Format . . . . . . . . . . . . . . . . 15-10 WMRC0100 Format . . . . . . . . . . . . . . . . 15-15
Field Descriptions . . . . . . . . . . . . . . . . . 15-10 WMRQ0100 Format . . . . . . . . . . . . . . . . 15-15
Error Messages . . . . . . . . . . . . . . . . . . 15-11 Field Descriptions . . . . . . . . . . . . . . . . . 15-15
Send Request (QzdmSendRequest) API . . . . . . . 15-11 Error Messages . . . . . . . . . . . . . . . . . . 15-16

Part 5. Communications APIs

Communications

AS/400 System API Reference V4R4

 Overview

Chapter 9. User-Defined Communications—Introduction

User-defined communications support is a set of application ┌──────────────────────────────────────────────────┐
│ │
program interfaces (APIs) that are part of the Operating │ User-Defined Communications Application Program │
System/400 (OS/400) licensed program. These callable rou- └┬───────────┬────────────────────────┬────────────┘
tines allow customers to write their own communications pro- │ │ │
│ ┌─────────┴──────────────┐ ┌─────┴────┐
tocol stacks above the AS/400 data link and physical layer │ │Input/Output Buffers │ │Queues │
support. This section of the System API Reference book │ └─────────┬──────────────┘ └─────┬────┘
uses the term user-defined communications to describe │ │ │
│ │ │
this communications protocol support. The term application ┌┴───────────┴────────────────────────┴───────────┐
program refers to a user-supplied communications applica- │ User-Defined Communications Support │
tion program. │ │
└─┬──────────────┬───────────┬───────┬─────────┬──┘
│ │ │ │ │
This section of the manual defines the user-defined commu- ┌─┴─────────┐┌───┴─────┐┌────┴───┐┌──┴────┐┌───┴────┐
nications support, and describes how to write protocols using │Token-Ring ││Ethernet ││X.25 ││FDDI ││Wireless│
the APIs. In addition, “Using the User-Defined Communica- │Support ││Support ││Support ││Support││Support │
│ ││ ││ ││ ││ │
tions Programs for File Transfer” on page A-35 provides two └─────┬─────┘└───┬─────┘└────┬───┘└───┬───┘└────┬───┘
C language program examples that illustrate the use of the 6 6 │ 6 6
APIs while performing a simple file transfer between two To Token- To ┌───┴───┐ To FDDI To
Ring Ethernet │ │ Network Wireless
systems attached to an X.25 packet switched network. Network Network 6 6 Network
To X.25 To X.25
In addition to the user-defined communications support, the Network Network
Communications part also includes the data stream trans- (RVX (ISDN)
Recommen-
lation APIs and the OptiConnect APIs. dations)

FDDI = fiber distributed data interface

ISDN = integrated services digital network
Overview RVX = an abbreviation for the physical interface that
X.25 can use:
The user-defined communications APIs allow your application R = RS-232 and RS-449 (Electronic Industries
programs to send and receive data, and do specialized func- Association (EIA) types)
tions such as setting timers. V = V.35 (International Telegraph and Telephone
Consultative Committee (CCITT) V series types)
X = X.21 (CCITT X series types)
Your application programs need to work with the following:
Ÿ User-defined communications support Figure 9-1. User-Defined Communications Support
Ÿ Input/output buffers and descriptors
Ÿ A queue User-Defined Communications Callable
Figure 9-1 shows an overview of the user-defined commu- Routines
nications support.
The APIs provided by the OS/400 licensed program are call-
able routines that allow an application program to start,
perform, and end communications, and perform specialized
functions such as setting timers. These routines are listed
below and are discussed in detail in Chapter 12, “User-
Defined Communications Support APIs” on page 12-1.
Ÿ Disable Link (QOLDLINK) ends communications
Ÿ Enable Link (QOLELINK) starts communications
Ÿ Query Line Description (QOLQLIND)
Ÿ Receive Data (QOLRECV)
Ÿ Send Data (QOLSEND)
Ÿ Set Filter (QOLSETF) for inbound routing information
Ÿ Set Timer (QOLTIMER) sets or cancels a timer

 Copyright IBM Corp. 1998, 1999 9-1

Relationship to Communications Standards

Input/Output Buffers and Descriptors system without establishing a connection to it. User-defined
communications support provides connectionless service
The input/output buffers and descriptors are user space over token-ring, Ethernet, fiber distributed data interface
objects (*USRSPC) that contain and describe the data an (FDDI), wireless and X.25 networks only. For a local area
application program is sending or receiving. There are sepa- network (LAN) environment, connectionless service is also
rate buffers and descriptors for input and output. known as unacknowledged service.

When an application program is ready to send data, it fills Connection-oriented service. A method of operation where
the output buffer with data and provides a description of that a connection to the remote computer system must first be
data in the output buffer descriptor. Similarly, when an appli- established before data can be sent to it or received from it.
cation program receives data, the user-defined communica- User-defined communications support provides connection-
tions support fills the input buffer with data and provides a oriented service over X.25 networks only.
description of that data in the input buffer descriptor.
Connection identifier. A local identifier (ID) that a computer
The OS/400 licensed program also provides callable APIs to system uses to distinguish one connection from another.
allow an application program to manipulate the data in the When using the user-defined communications support on the
user spaces. Some of these APIs are listed below. AS/400 system, a connection ID is made up of a user con-
nection end point ID and a provider connection end point ID.
Ÿ Change User Space (QUSCHGUS)
Ÿ Retrieve Pointer to User Space (QUSPTRUS) Disable. The process of deactivating a link so that input and
output operations are no longer possible on a communica-
Ÿ Retrieve User Space (QUSRTVUS)
tions line.
For more information on the User Space APIs, see the
Enable. The process of setting up and activating a link for
Object APIs in the Information Center.
input and output operations on a communications line.

Queues Filter. The technique used to route inbound data to a link

that is enabled by an application program.
A queue is used by the user-defined communications support
to inform an application program of some action to perform Link. The logical path between an application program and
or of an activity that is complete. a communications line. A link is made up of the following
communications objects:
The OS/400 licensed program provides APIs that allow your Ÿ Network interface description running X.25 over ISDN
application programs to manipulate the data and user
queues. Some of these callable APIs are listed below. Ÿ X.25, token-ring, fiber distributed data interface (FDDI),
Ethernet, or wireless line description
Ÿ Clear Data Queue (QCLRDTAQ)
Ÿ Network controller description
Ÿ Create User Queue (QUSCRTUQ)
Ÿ Network device description of type *USRDFN
Ÿ Delete User Queue (QUSDLTUQ)
Ÿ Receive Data Queue (QRCVDTAQ) Provider connection end point ID (PCEP ID). The portion
of the connection ID that the user-defined communications
Ÿ Send Data Queue (QSNDDTAQ) support uses to identify the connection. For example, data
sent by the application program will be on the PCEP ID
See the CL Programming book for more information on data
portion of the connection ID.
queues.
User connection end point ID (UCEP ID). The portion of
the connection ID that the application program uses to iden-
Terminology tify the connection. For example, data received by the appli-
cation program is on the UCEP ID portion of the connection
Listed below are terms that are important in understanding ID.
the information contained in this part.

Communications handle. The name an application

program assigns and uses to refer to a link. Relationship to Communications
Standards
Connection. The logical communication path from one com-
puter system to another. For example, a switched virtual Figure 9-2 on page 9-3 shows the structure of advanced
circuit (SVC) connection on an X.25 network. program-to-program communications (APPC) on the AS/400
system and its relationship to the International Standards
Connectionless service. A method of operation where data Organization (ISO) protocol model. Note that only the appli-
can be sent to and received from the remote computer cation layer above the APPC protocol code is available for

9-2 AS/400 System API Reference V4R4

 Relationship to Communications Standards

definition. The APPC functional equivalents of the ISO pres- AS/4ðð User-Defined International Standards
Communications Organization Model (ISO)
entation, session, networking, transport, data link, and phys- ┌────────────────────────┐ ┌───────────────────────┐
ical layers are performed by the OS/400 operating system or │ │ │ │
Licensed Internal Code, and you cannot replace or change │ ┌────────────────────┐ │ │ ┌───────────────────┐ │
│ │ │ │ │ │ Application │ │
them. Contrast this with Figure 9-3 which shows how much │ │ │ │ │ └─────────┬─────────┘ │
more of the protocol is defined by the user-defined commu- │ │ User─defined │ │ │ │ │
nications application than by the APPC application. │ │ communications │ │ │ ┌─────────┴─────────┐ │
│ │ application │ │ │ │ Presentation │ │
AS/4ðð APPC International Standards │ │ │ │ │ └─────────┬─────────┘ │
Protocol Organization Model (ISO) │ │ This structure │ │ │ │ │
┌──────────────────────────┐ ┌───────────────────────┐ │ │ is open to the │ │ │ ┌─────────┴─────────┐ │
│ │ │ │ │ │ application │ │ │ │ Session │ │
│ ┌────────────────────┐ │ │ ┌─────────────────┐ │ │ │ architect. The │ │ │ └─────────┬─────────┘ │
│ │ APPC Applications │ │ │ │ Application │ │ │ │ design will │ │ │ │ │
│ └──────────┬─────────┘ │ │ └────────┬────────┘ │ │ │ dictate how the │ │ │ ┌─────────┴─────────┐ │
│ │ │ │ │ │ │ │ protocol is │ │ │ │ Transport │ │
│ ┌──────────┴─────────┐ │ │ ┌────────┴────────┐ │ │ │ organized. │ │ │ └─────────┬─────────┘ │
│ │ Presentation │ │ │ │ Presentation │ │ │ │ │ │ │ │ │
│ │ Services │ │ │ └────────┬────────┘ │ │ │ │ │ │ ┌─────────┴─────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │ │ Network │ │
│ │ │ │ │ ┌────────┴────────┐ │ │ └──────────┬─────────┘ │ │ └─────────┬─────────┘ │
│ │ Data Flow │ │ │ │ Session │ │ │ │ │ │ │ │
│ │ Control │ │ │ └────────┬────────┘ │ │ ┌──────────┴─────────┐ │ │ ┌─────────┴─────────┐ │
│ │ │ │ │ │ │ │ │ X.25, LAN Data Link│ │ │ │ Data Link │ │
│ │ │ │ │ ┌────────┴────────┐ │ │ └──────────┬─────────┘ │ │ └─────────┬─────────┘ │
│ │ Transmission │ │ │ │ Transport │ │ │ │ │ │ │ │
│ │ Control │ │ │ └────────┬────────┘ │ │ ┌──────────┴─────────┐ │ │ ┌─────────┴─────────┐ │
│ │ │ │ │ │ │ │ │ V.24, 8ð2.3, ... │ │ │ │ Physical │ │
│ │ │ │ │ ┌────────┴────────┐ │ │ └────────────────────┘ │ │ └───────────────────┘ │
│ │ Path Control │ │ │ │ Network │ │ │ │ │ │
│ │ │ │ │ └────────┬────────┘ │ │ │ │ │
│ │ │ │ │ │ │ └────────────────────────┘ └───────────────────────┘
│ │ │ │ │ ┌────────┴────────┐ │
Figure 9-3. AS/400 User-Defined versus ISO Model
│ │ Data Link Control │ │ │ │ Data Link │ │
│ │ │ │ │ └────────┬────────┘ │
│ │ │ │ │ │ │ You can write protocols that run over local area networks or
│ │ │ │ │ ┌────────┴────────┐ │ X.25 networks completely in high-level languages such as C,
│ │ Physical Control │ │ │ │ Physical │ │
│ └────────────────────┘ │ │ └─────────────────┘ │ COBOL, or RPG. You can also write protocols currently
│ (all layers except │ │ │ running on other systems to run on the AS/400 system. For
│ application are IBM- │ │ │ example, you can write both non-SNA LAN or X.25 packet
│ supplied licensed │ │ │
│ internal code) │ │ │ layer protocols on the AS/400 system.
└──────────────────────────┘ └───────────────────────┘
Configuration instructions also need to be supplied with the
Figure 9-2. AS/400 APPC versus ISO Model
application program. User-defined communications support
Figure 9-3 shows the structure for user-defined communica- simply opens a pathway to the system data links. It is up to
tions and its relationship to the International Standards you as a protocol developer to supply any configuration
Organization (ISO) protocol model. Note that the available instructions that are in addition to the data link or physical
AS/400 data links and physical layers limit user-defined com- layer definition. Data link and physical layer definitions are
munications to run over LAN (token-ring, Ethernet, wireless, defined when you use the following commands:
or FDDI), or X.25 links, but the portion of the protocol above Ÿ Create Line Description (DDI) (CRTLINDDI)
the data link layer is completely open to a user-defined com-
Ÿ Create Line Description (Ethernet) (CRTLINETH)
munications application. In addition, these same X.25 and
LAN links may be shared between the application program Ÿ Create Line Description (Token Ring) (CRTLINTRN)
and other AS/400 communications protocols that support Ÿ Create Line Description (Wireless) (CRTLINWLS)
X.25 and LAN lines. Examples include Systems Network
Architecture (SNA), asynchronous communications, Trans- Ÿ Create Line Description (X.25) (CRTLINX25)
mission Control Protocol/Internet Protocol (TCP/IP), and Ÿ Create Network Interface Description (ISDN)
Open Systems Interconnection (OSI). (CRTNWIISDN)

Figure 9-4 outlines the difference between standard AS/400

communications configuration, such as the AS/400 APPC
protocol, and user-defined communications configuration.

Chapter 9. User-Defined Communications—Introduction 9-3

Local Area Network Considerations

program to use the X'22' SAP, and run at the same time as
Figure 9-4. Comparison between User-Defined Communica-
tions and APPC Communications the first two. All three protocols can be active at the same
time across the same physical media.
APPC User-Defined
Object Communications Communications Note: System-specific configuration information must be
part of the application program and is not supplied by IBM.
Network ISDN basic rate Same as APPC.
Interface interface (BRI). Only X.25 sup-
Description Describes the phys- ported.
ical attachment to Local Area Network (LAN) Considerations
an ISDN BRI. Only
used for ISDN. User-defined communications supports these LAN types:
X.25 or IDLC proto-
cols supported. Ÿ Token ring (IEEE 802.5)
Line Descrip- SDLC, LAN, IDLC, LAN, X.25 lines Ÿ Ethernet (IEEE 802.3)
tion X.25 lines sup- supported. Same
Ÿ Ethernet Version 2
ported. Contains as APPC except
local port informa- some of the infor- Ÿ Wireless
tion for AS/400 mation does not
communication IOP apply to user- Ÿ FDDI
(hardware address, defined commu-
maximum frame nications. For token ring (802.5), Ethernet (802.3), and FDDI, user-
size, exchange defined communications uses the IEEE 802.2 logical link
identifier (XID), control (LLC) layer, which provides type 1 connectionless
local recovery infor- service. Connectionless service is also known as unac-
mation, ...). knowledged service. The LLC layer provides for type 2 con-
Controller APPC, host control- Network controller nection service as well. For Ethernet Version 2, no 802.2
Description lers supported. supported. layer is available.
Describes remote Pathway into
system, and param- network. Only one The wireless LAN type supports the characteristics of both
eters must match specific Ethernet (802.3) and Ethernet Version 2.
the remote hard- parameter—X.25
ware (hardware time-out value. Your application program has access to type 1 unnumbered
address, XID, ...). information (UI) frames. This connectionless service is com-
Device APPC device sup- Network device monly referred to as datagram support where protocol data
Description ported. Describes supported. Only units are exchanged between end points without establishing
remote logical unit describes the com- a data link connection first.
(LU), and parame- munications
ters must match method or type (for The type 1 operations, test and exchange identifier (XID)
partner LU (remote example, TCP/IP, frames, are not supported in user-defined communications.
location name, local OSI, or user-
Any XID or test frames that the physical layer of the AS/400
location name, ...). defined commu-
nications).
system receives are processed by the input/output processor
(IOP) and never reach your application program.
Mode Descrip- Required. Not available.
tion and Class- LAN frames are routed by filtering incoming data using the
of-Service inbound routing data defined by your application program.
(COS)
The filters are hierarchical and are set up by your application
program before communications is started.
Although an APPC network requires one APPC controller
description to describe each remote system in the network, The following list shows the possible settings for LAN
user-defined communications only requires one network con- inbound routing data (filters) from least selective to most
troller for communications with an entire network of remote selective.
systems. Thus, LAN and X.25 lines can be shared between
Ÿ Destination Service Access Point (DSAP)
user-defined communications support and any other proto-
cols that support those same line types. For example, APPC Ÿ DSAP, Source Service Access Point (SSAP), and
may run over a token-ring line and use the X'04' Service optional Ethernet Version 2 frame type
Access Point (SAP). TCP/IP might run at the same time Ÿ DSAP, SSAP, optional Ethernet Version 2 frame type,
using the X'AA' SAP. You might write an application and adapter address

9-4 AS/400 System API Reference V4R4

 X.25 Considerations

Because user-defined communications does not allow appli-

cations to define the data link and physical layers, the entire X.25 Considerations
token-ring or Ethernet frame is not available to your applica-
X.25 user-defined communications support includes access
tions. The following fields are the parts of the LAN frame
to both permanent virtual circuits (PVCs) and switched virtual
that are available to the user-defined communications
circuits (SVCs).
support:
Ÿ DSAP Over X.25 networks, including those using ISDN, your appli-
cation program can initiate and accept X.25 calls, send and
Ÿ SSAP
receive data, reset, and clear connections.
Ÿ Destination address (DA)
X.25 packets are routed by filtering the incoming call request
Ÿ Routing information (RI)1
using the inbound routing data that is defined by your appli-
Ÿ Priority control1 cation program. The filters are hierarchical and are set up by
Ÿ Access control1 the application program before communications is started.

Ÿ Data The following list shows the possible settings for X.25
inbound routing data (filters) from least selective to most
For more information on local area networks, see the LAN, selective.
Frame-Relay and ATM Support book.
Ÿ Protocol identifier (PID)
Ÿ PID, and calling data terminal equipment (DTE) address
When X.25 networks are using ISDN, notification of incoming
calls may be received on the D-channel. You can decide
whether these calls are accepted.

For more information on X.25 networks, see the X.25

Network Support book.

1 These fields are available only when using token ring.

Chapter 9. User-Defined Communications—Introduction 9-5

X.25 Considerations

9-6 AS/400 System API Reference V4R4

 Jobs

Chapter 10. Programming Design Considerations

This chapter discusses concepts related to user-defined com- network device description used by the application becomes
munications and how they might relate to the design of a available to another application.
user-defined communications application. This chapter
covers: For end-to-end communication to begin, the application pro-
grams on each system must be started. There is no function
Ÿ Jobs
equivalent to the intersystem communications function (ICF)
Ÿ Application program feedback program start request. Your application program is respon-
sible for providing this support, if needed. To provide this
Ÿ Programming languages
support, your application can have a batch job servicing
Ÿ Connection identifiers remote requests to start the user-defined communications
Ÿ Token-ring, Ethernet, and wireless networks application program. This job can be created to run in any
subsystem.
Ÿ X.25 networks
Ÿ Queues For more information on jobs and subsystems, see the Work
Management book.
Ÿ User spaces
You can design your application programs so that the entire
protocol resides within one job or separate jobs where each
Jobs job represents a portion of the protocol.

A fundamental concept in user-defined communications is There is a one-to-one correspondence between a job and the
the job. The concept of the job is important because the user-defined communications support for that job. The user-
user-defined communications support performs services for defined communications support for one job does not com-
the job requesting the communications support through one municate with the user-defined communications support for
of the user-defined communications APIs. Information used another job. If two applications wish to communicate
by the user-defined communications support is kept along between themselves, a method such as a shared queue can
with other information about the job. You can display this be used. Also, the queue can be shared between the two
information by using the Work with Job (WRKJOB) command (or more) jobs and the user-defined communications support
and selecting the Work with communications status option. for those jobs.
The user-defined communications information for the job,
such as the communications handle name, last operation, Figure 10-1 on page 10-2 shows how user-defined commu-
and input and output counts are shown. nications relate to the AS/400 system job structure and the
data queue or user queue that provides the ability to commu-
A user-defined communications application program (here- nicate between your application and the user-defined com-
after referred to as an application or application program), munications support.
always runs within a job. This job may be run interactively or
in batch and always represents a separate application to the In this figure, one interactive job is running over an X.25 line
user-defined communications support. This means that the (X25USA) to a system in Rochester, Minnesota, using the
same protocol can be actively running in more than one job user-defined communications support. The link was enabled
on the system. Also, more than one job can have links that with communications handle name ROCHESTER.
share the same line as other jobs running application pro-
The user space application programming interfaces (APIs)
grams.
that the application program is using are shown, along with
Each link that is enabled by an application program logically the programming interfaces for data and user queues and
consists of the line, network controller, and network device the user-defined communications support APIs.
description objects (plus the network interface description
Figure 10-2 on page 10-2 shows two jobs, A and B. Each
object for ISDN links). Many applications can share the
job is using the user-defined communications support to
same line and controller description, provided the applica-
communicate with the networks attached to the AS/400
tions are running in different jobs, but each application uses
system by the line description. The figure shows the
a different device description. Up to 256 device descriptions
relationship between the different APIs and the job which is
can be attached to a controller description. This means that
running the application program.
there can be a maximum of 256 jobs running application pro-
grams that share the same line at one time. When an appli- The lines between the jobs indicate that callable APIs that
cation program has finished using a link and disabling it, the are used to communicate between the application program
and the system services shown.

 Copyright IBM Corp. 1998, 1999 10-1

Application Program Feedback

┌─────────────────────────────────────────┐ (ENQ) Data (QOLSEND) API can fill the output buffer and
│ │ QSNDDTAQ
│ User-Defined Communications │%────────5┌─────────────────┐ descriptor, or another application can do this.
│ Application Program │ QRCVDTAQ │ Queue │
│ │ (DEQ) │ Support │ Ÿ The user-defined communications support sends data to
│ Job name: DSPð6 QPGMR ððð123 │ │ │
└─────&────────────────────────&──────────┘ └──&───┬──────────┘ the application through the input buffer and input
│QUSPTRUS QOLELINK │ (ENQ) QSNDDTAQ │ │ descriptor that is created when the link on which the
│QUSCHGUS QOLDLINK │ ┌──────────────────────┘ │
│QUSRTVUS QOLSETF │ │ │ data is arriving was created. Either the application
│ QOLRECV │ │ │ making the call to the Receive Data (QOLRECV) API
│ QOLSEND │ │ │
│ QOLQLIND │ │ │ retrieves the data from the input buffer and descriptor, or
│ QOLTIMER │ │ │ another application with access to the user spaces does
│ │ │ 6
┌───6──────────┐ ┌─────────6─┴───────────────┐ ┌──────────────┐ this.
│ User Space │ │ User-Defined │ │ Queue │
│ Support, │ │ Communications Support │ │ Object │ Ÿ The application supplies any communications handle
│ Four User │ │ │ │ │ (link name) to the link as long as this name is unique
│ Spaces │ │ Link by Handle: │ └──────────────┘
│ │ │ ROCHESTER │ among all the other links that the job has enabled.
└──────────────┘ └─────────┬─────────────────┘
│ Line Description: Ÿ An application can enable as many links as there are
│ X25USA
│
line descriptions that are supported (X.25, token-ring,
│ Ethernet, wireless, and FDDI) and that are able to be
6
varied on.
Figure 10-1. Overview of API Relationships Ÿ An application is able to run over X.25 and LAN links
concurrently.
┌───────────────────────┐ ┌───────────────────────┐
│ Job A │ │ Job B │
│ │ │ │
│ ┌───────────────────┐ │ │ ┌───────────────────┐ │ Application Program Feedback
│ │User─Defined │ │ ┌───────────┐ │ │User─Defined │ │
│ │Communications ├─┼──┤Queue ├───┼─┤Communications │ │
│ │Application Program├─┼┐ │Support │ ┌─┼─┤Application program│ │ The user-defined communications support uses return and
│ └─────────┬─────────┘ ││ └───────────┘ │ │ └─────────┬─────────┘ │ reason codes to indicate the success or failure of an opera-
│ │ ││ ┌───────────┐ │ │ │ │
│ ┌─────────┴─────────┐ │└─┤ User Space│ │ │ ┌─────────┴─────────┐ │ tion, and provide suggested recovery information. In severe
│ │User─Defined │ │ │ Support ├─┘ │ │User─Defined │ │ error conditions an escape message is signaled to the appli-
│ │Communications │ │ └───────────┘ │ │Communications │ │
│ │Support │ │ │ │Support │ │ cation program. If a severe error occurs, user-defined com-
│ │ │ │ │ │ │ │
│ └───────────────────┘ │ │ └───────────────────┘ │
munications is no longer available to the application.
│ │ │ │
└───────────────────────┘ └───────────────────────┘ When the QOLSEND and QOLRECV APIs return to the
┌─────────┐ ┌───────────┐ ┌───────────┐ ┌────────────┐ application and you are running to an X.25 network, the diag-
│Wireless │ │Ethernet │ │ X.25 │ │Token─Ring │ nostic field is filled in. The reason code indicates whether or
│Network │ │Network │ │ Network │ │Network │
└─────────┘ └───────────┘ └─┬──────┬──┘ └────────────┘ not the application program should look at the data returned
┌─────────┴┐ ┌┴───────┐ in the diagnostic field. The diagnostic field contains addi-
│ ISDN │ │ RVX │
│ │ │ │ tional information on the error or condition that is reported.
└──────────┘ └────────┘
Figure 10-2. Application Programming Interface to Job Structure
Synchronous and Asynchronous
The following list pertains to Figure 10-2. Operations
Ÿ The applications use the data queue APIs, user space
Most operations that an application program requests on the
APIs, and user-defined communications APIs.
call to the QOLSEND API are synchronous operations. Syn-
Ÿ An application can have more than one link enabled, chronous operations involve one step, which is to call the
and can use a separate queue for each link, or the same QOLSEND API, passing the appropriate information. Syn-
queue for some or all the links that it has enabled. chronous operations complete when the QOLSEND API
Ÿ The two jobs can communicate with each other using a returns to the application program. The success or failure of
common queue. This queue can be the same queue the operation is reported in the return and reason codes by
that is used for user-defined communications support or the QOLSEND API.
a different one.
Asynchronous operations do not complete when the
Ÿ Both jobs (or any other job on the system) that has the QOLSEND API returns to the application. There are two
proper authority to the user spaces, can access the user steps for every asynchronous operation:
spaces.
1. Call the QOLSEND API to initiate or request the opera-
Ÿ The user-defined communications support uses the data tion.
in the output user spaces that are created when the link
2. Call the QOLRECV API to receive the results of the
is created. The application making the call to the Send
completed operation.

10-2 AS/400 System API Reference V4R4

 Starting and Ending Communications

When the QOLSEND API returns to the application program,

the request for the operation is successfully submitted. After Starting and Ending Communications
the requested operation is complete, the user-defined com-
Relatively little configuration is required by user-defined com-
munications support sends an incoming data entry (if neces-
munications support to begin communications to the network.
sary) to the queue to instruct the application program to call
For information on configuration, see Chapter 11, “Configura-
the QOLRECV API to receive the data. When this call to the
tion and Queue Entries” on page 11-1.
QOLRECV API returns, the return and reason codes in the
parameter list contain the success or failure of the operation. To start communications with a network, your user-defined
If the operation was unsuccessful due to an application tem- communications application program enables the link to the
plate error in the user space used for output, the request network by calling the Enable Link (QOLELINK) API. Once
data given to QOLSEND using the output buffer and the link is enabled, the application program can call any of
descriptor is copied into the input buffer and descriptor. The the user-defined communications support APIs, and request
offset to the template error detected is returned in the param- any of the operations supported for the link. When the appli-
eter list of the QOLRECV API. Asynchronous operations are cation program completes communications with the network,
only used for open connection requests, close connection it disables the link by calling the Disable Link (QOLDLINK)
requests, and resets. API.
For either type of operation, the application program is Note: Enabling the link does not result in any communica-
allowed to use the output user spaces again as soon as the tions activity on the network. Disabling a link may cause
call to the QOLSEND API returns. communications activity for X.25 links if connections are
active when the link is disabled.

Programming Languages Using Connection Identifiers

Any program written in an AS/400 system-supported lan- Connection identifiers are used for connection-oriented
guage can call user-defined communications support. One support over X.25 networks. The connectionless connection
consideration for choosing one language over another, is that identifiers (UCEP=1, PCEP=1) are used for local area net-
the programming language must have the ability to set a byte works. The following examples (Figure 10-3 on page 10-4
field to any hexadecimal value. This does not restrict pro- through Figure 10-14 on page 10-17) illustrate how to use
gramming in the different languages, but it does make some connection identifiers (UCEP and PCEP). They show how
languages more appealing than others. the two step operations, open connection request, and close
connection request relate to the UCEP and PCEP identifiers.
Note the outstanding two-step operations. This is important
so that the application can correctly interpret the PCEP and
reuse UCEPs.

The connections in each figure refer to SVC connections,

and the examples use the Receive Data Queue
(QRCVDTAQ) API. The same principles apply when using
PVC connections and user queues.

Chapter 10. Programming Design Considerations 10-3

Starting and Ending Communications

Example 1

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC) sends │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP, 1, ├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CALL ACCEPT
│ │ │ (4) Call accept received │%────────────
│(5) Data queue entry │ │ for PCEP 1. Send │
│ indicates data to │ │ entry to data queue. │
│ be received. │QOLRECV│ │
│ ├──────5│ (6) Fill in user space with │
│ │ │ result of call request │
│ │ (rtn) │ for UCEP 7 and return. │
│ │%──────┤ │
│(7) Open connection request │ │ │
│ was successful. │ │ │
│ UCEP (7), PCEP (1) in │ │ │
│ data state. │ │ │
│ │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-3. Example 1: Normal Connection Establishment

1. The application wants to open a connection, so it calls 4. The X.25 call accept is received for PCEP=1. To inform
the QOLSEND API passing it the UCEP it wants to use the application of the incoming data, an incoming data
for the connection. The application keeps track of the entry is sent to the data queue.
UCEP, PCEP pair. At this point, the UCEP=7, and the
5. The application’s call to the QRCVDTAQ API returns
PCEP is undefined.
with the incoming data entry. The application then
2. The user-defined communications support receives the issues a call to the QOLRECV API.
request, stores the UCEP for the connection, and uses
6. The user-defined communications support fills in the
the next available PCEP, which is 1, and returns to the
input buffer and descriptor with data for the open con-
application, acknowledging the receipt of the request.
nection response operation, and determines the UCEP
The user-defined communications support validates the associated with the data by examining the PCEP associ-
request and issues the X.25 call request. ated with the X.25 call accept. Because the call accept
was received for PCEP=1, the UCEP=7.
3. The application records that the PCEP for UCEP=7 is 1.
The UCEP=7, PCEP=1 connection is not yet active. 7. The application’s call to the QOLRECV API returns with
Next, the application calls the Receive Entry From Data successful return and reason codes for the open con-
Queue (QRCVDTAQ) API, to wait for the incoming data nection response operation. This operation was
entry. The application is expecting the open connection reported for UCEP 7; the UCEP=7, PCEP=1 connection
response. is now active.

10-4 AS/400 System API Reference V4R4

 Starting and Ending Communications

Example 2

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC) send │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP, 1, ├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CLEAR
│ │ │ (4) Call was cleared │%────────────
│(5) Data queue entry │ │ for PCEP 1. Send │
│ indicates data to │ │ entry to data queue. │
│ receive. │QOLRECV│ │
│ ├──────5│ (6) Fill in user space with │
│ │ │ result of call request │
│ │ (rtn) │ for UCEP 7 and return. │
│ │%──────┤ │
│(7) Open connection request │ │ │
│ was not successful. │ │ │
│ UCEP 7 available for │ │ │
│ reuse. │ │ │
│ │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-4. Example 2: Connection Request Cleared by Network/Remote System

1. The application wishes to open a connection, so it calls 5. The application’s call to the QRCVDTAQ API returns
the QOLSEND API, passing it the UCEP it wants to use with the incoming data entry. The application then
for the new connection. The application keeps track of issues a call to the QOLRECV API.
the UCEP, PCEP pair. At this point, the UCEP=7, and
6. The user-defined communications support fills in the
the PCEP is undefined.
input buffer and descriptor with data for the open con-
2. The user-defined communications support receives the nection response operation, and determines the UCEP
request, stores the UCEP for the connection, and uses for the data by using the PCEP for which the X.25 call
the next available PCEP, which is 1, and returns to the accept was received. Because the call was cleared for
application, acknowledging the receipt of the request. PCEP=1, the UCEP=7. The PCEP=1 is no longer
active, and may be reused by the user-defined commu-
The user-defined communications support validates the
request and issues the X.25 call request. nications support.

3. The application records that the PCEP for UCEP=7 is 1, 7. The application’s call to the QOLRECV API returns with
and the UCEP=7, PCEP=1 connection is not yet active. unsuccessful return and reason codes for the open con-
Next, the application calls the QRCVDTAQ API to wait nection response operation. Thus for the PCEP=1, the
for the incoming data entry. The application is expecting UCEP=7. The PCEP=1 is no longer active, and the
operation is for UCEP=7. Because the connection is not
the open-connection response.
open, the user-defined communications support’s
4. A clear is received for PCEP=1. To inform the applica- PCEP=1 no longer implies UCEP=7, and the
tion of the incoming data, an incoming data entry is sent application’s UCEP=7 may be reused.
to the data queue.

Chapter 10. Programming Design Considerations 10-5

Starting and Ending Communications

Example 3

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC) send │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP, 1, ├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │
│(4) Send close connection │ │ │
│ request for PCEP 1. │QOLSEND│ (5) Receive request to │
│ ├──────5│ clear PCEP 1. │
│ │ │ │
│ │ (rtn) │ │
│ │%──────┤ (6) User space error found. │
│(7) Data queue indicates │ │ Send entry to data │
│ data to be received. │ │ queue. │
│ │QOLRECV│ │
│ ├──────5│ (8) Fill in user space with │
│ │ │ the close connection │
│ │ (rtn) │ request for UCEP 7 and │
│(9) Close connection request │%──────┤ return. │
│ was not successful. │ │ │
│ UCEP 7, PCEP 1 remains │ │ │
│ active. │ │ │
│ │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-5. Example 3: Request to Clear Connection with Outstanding Call (Unsuccessful)

1. The application wishes to open a connection, so it calls The user-defined communications support validates the
the QOLSEND API passing it the UCEP for the new request and finds an error.
connection. The application keeps track of the UCEP,
6. The user space error is found. A copy of the user
PCEP pair. At this point, the UCEP=7, and the PCEP is
space, which contained an error, is passed back to the
undefined.
application. To inform the application of the unsuc-
2. The user-defined communications support receives the cessful close connection request, an incoming data entry
request, stores the UCEP for the connection, and uses is sent to the data queue.
the next available PCEP, which is 1, and returns to the
7. The application’s call to the QRCVDTAQ API returns
application, acknowledging the receipt of the request.
with the incoming data entry. The application then
The user-defined communications support validates the issues a call to the QOLRECV API.
request and issues the X.25 call request.
8. The user-defined communications support fills in the
3. The application records that the PCEP for UCEP=7 is 1, input buffer and descriptor with data for the unsuccessful
and the UCEP=7, PCEP=1 connection is not yet active. close connection request operation, and determines the
Next, the application calls the QRCVDTAQ API to wait UCEP associated with the data by examining the PCEP
for the incoming data entry. The application is expecting associated with the close connection. Because the
the open connection response. close connection request was for PCEP=1, the UCEP=7.
4. QRCVDTAQ returns to the application (the dequeue 9. The application’s call to the QOLRECV API returns with
time-out value has elapsed), and the application no unsuccessful return and reason codes for the close con-
longer wants the UCEP=7 connection. It calls the nection response operation. This operation is for
QOLSEND API passing the PCEP=1 to identify the con- UCEP=7. The connection UCEP=7, PCEP=1 is still in
nection to be closed. Then the application calls the use by both the application and the user-defined com-
QRCVDTAQ API. munications support. The application can either correct
the error and reissue the operation, or wait for the call to
5. The user-defined communications support receives the
be accepted or rejected.
close connection request, and returns to the application,
acknowledging the receipt of the request.

10-6 AS/400 System API Reference V4R4

 Starting and Ending Communications

Example 4

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC, use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC), sends │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP (1),├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CALL ACCEPT
│(4) Send close─connection │ │ (5) Call accepted for │%────────────
│ request for PCEP 1. │QOLSEND│ PCEP 1. Send to data │
│ ├──────5│ queue. │
│ │ │ │
│ │ (rtn) │ (6) Receive request to │
│ │%──────┤ clear PCEP 1. │
│(7) Data queue indicates data│ │ │
│ to be received. │QOLRECV│ │
│ ├──────5│ (8) Fill in user space with │
│ │ │ result of call request │
│ │ (rtn) │ for UCEP 7 and return. │
│(9) Open connection request │%──────┤ │
│ was successful. │ │(1ð) User space error. Send │
│ UCEP 7, PCEP 1 is active.│ │ entry to data queue. │
│ │ │ │
│(11) Data queue indicates │ │ │
│ there is data to │QOLRECV│ │
│ receive. ├──────5│(12) Fill in user space with │
│ │ │ close connection request│
│ │ (rtn) │ that failed for UCEP 7 │
│(13) Close connection request│%──────┤ and return. │
│ was not successful. │ │ │
│ UCEP (7), PCEP(1) │ │ │
│ active. │ │ │
│ │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-6. Unsuccessful Attempt to Clear Outstanding (Successful) Call

1. The application wishes to open a connection, so it calls 5. The X.25 call accept is received for PCEP=1. To inform
the QOLSEND API, passing the UCEP for the new con- the application of the incoming data, an incoming data
nection. The application keeps track of the UCEP, entry is sent to the data queue.
PCEP pair. At this point, the UCEP=7, and the PCEP is
6. The user-defined communications support receives the
undefined.
close connection request, and returns to the application,
2. The user-defined communications support receives the acknowledging the receipt of the request.
request, stores the UCEP for the connection, and uses
7. The application’s call to the QRCVDTAQ API returns
the next available PCEP, which is 1, and returns to the
with the incoming data entry. The application then
application, acknowledging the receipt of the request.
issues a call to the QOLRECV API.
The user-defined communications support validates the
8. The user-defined communications support fills in the
request and issues the X.25 call request.
input buffer and descriptor with data for the open con-
3. The application records that the PCEP for UCEP=7 is 1, nection response, and determines the UCEP associated
and the UCEP=7, PCEP=1 connection is not yet active. with the data by examining the PCEP for the X.25 call
Next, the application calls the QRCVDTAQ API to wait accept. Because the call accept was received for
for the incoming data entry. The application is expecting PCEP=1, the UCEP=7.
the open connection response.
9. The application’s call to the QOLRECV API returns with
4. QRCVDTAQ returns to the application (the dequeue successful return and reason codes for the open con-
time-out value has elapsed), and the application no nection request operation. This operation is reported for
longer wants the UCEP=7 connection. It calls the UCEP=7; the UCEP=7, PCEP=1 connection is now
QOLSEND API passing the PCEP=1 to identify the con- active with an outstanding close connection request.
nection to be closed. Then the application calls the The application calls the QRCVDTAQ API.
QRCVDTAQ API.

Chapter 10. Programming Design Considerations 10-7

Starting and Ending Communications

10. While processing the close connection request, the user-

defined communications support detects an error in the
user space. The user space that is in error is copied
into the input buffer and descriptor, so the application is
aware of the data in error. To inform the application of
the unsuccessful close connection request, an incoming
data entry is sent to the data queue.
11. The application’s call to the QRCVDTAQ API returns
with the incoming data entry. The application then
issues a call to the QOLRECV API.
12. The user-defined communications support fills the input
buffer and descriptor with data for the unsuccessful
close connection request operation. By using the PCEP
that was requested for the close connection, the support
determines the UCEP with which the data is associated.
Because the close connection request was for PCEP=1,
the UCEP is 7. The PCEP=1 is still active.
13. The application’s call to the QOLRECV API returns with
unsuccessful return and reason codes for the close con-
nection response operation. This operation is for UCEP
7. The connection UCEP=7, PCEP=1 is still in use by
both the application and the user-defined communica-
tions support. The application can either correct the
error and reissue the operation, or wait for the call to be
accepted or rejected.

10-8 AS/400 System API Reference V4R4

 Starting and Ending Communications

Example 5

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌───────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC), sends │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP (1), ├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CALL ACCEPT
│(4) Send close connection │ │ (5) Call accepted for PCEP 1. │%────────────
│ request for PCEP 1. │QOLSEND│ Send entry to data queue. │
│ ├──────5│ │
│ │ │ (6) Receive request to clear │
│ │ (rtn) │ PCEP 1. │
│ │%──────┤ │ CLEAR
│(7) Data queue indicates data│ │ (8) Issue clear request. ├────────────5
│ to be received. │ │ │
│ │QOLRECV│ │
│ ├──────5│ (9) Fill in user space with │
│ │ │ result of call request │
│ │ (rtn) │ for UCEP 7 and return. │ CLEAR CONFIRMED
│ │%──────┤ │%────────────
│(1ð) Open connection request │ │ │
│ was successful. │ │(11) Clear is confirmed. Send │
│ UCEP (7), PCEP (1) │ │ entry to data queue. │
│ is active. │ │ │
│ │ │ │
│(12) Data queue indicates │ │ │
│ there is data to │QOLRECV│ │
│ receive. ├──────5│(13) Fill in user space with │
│ │ (rtn) │ close connection request │
│(14) Close connection request│%──────┤ response for UCEP 7 and │
│ was successful. │ │ return. │
│ UCEP 7 no longer active. │ │ │
└─────────────────────────────┘ └───────────────────────────────┘
Figure 10-7. Example 5: Successful Attempt to Clear Outstanding (Successful) Call

1. The application wishes to open a connection so it calls 5. The X.25 call-accept is received for PCEP=1. To inform
the QOLSEND API, passing it the UCEP for the new the application of the incoming data, an incoming data
connection. The application keeps track of the UCEP, entry is sent to the data queue.
PCEP pair. At this point, the UCEP=7, and the PCEP is
6. The user-defined communications support receives the
undefined.
close connection request, and returns to the application,
2. The user-defined communications support receives the acknowledging the receipt of the request. The applica-
request, stores the UCEP for the connection, and uses tion calls QRCVDTAQ API.
the next available PCEP, which is 1, and returns to the
7. The application’s call to the QRCVDTAQ API returns
application, acknowledging the receipt of the request.
with the incoming data entry. The application then
The user-defined communications support validates the issues a call to QOLRECV.
request and issues the X.25 call request.
8. The user-defined communications support validates the
3. The application records that the PCEP for UCEP=7 is 1, close connection request, and issues an X.25 clear
and the UCEP=7, PCEP=1 connection is not yet active. request.
Next, the application calls the QRCVDTAQ API to wait
9. The user-defined communications support fills in the
for the incoming data entry. The application is expecting
input buffer and descriptor with data for the open con-
the open connection response.
nection response, and determines the UCEP that the
4. QRCVDTAQ returns to the application (the dequeue data is for by using the PCEP for the X.25 call accept.
time-out value has elapsed), and the application no Since the call accept was received for PCEP=1, the
longer wants the UCEP=7 connection. It calls the UCEP is 7.
QOLSEND API passing the PCEP=1 to identify the con-
10. The application’s call to QOLRECV returns with suc-
nection to be closed. The application calls the
cessful return and reason codes for the open connection
QRCVDTAQ API.
request operation. This operation is reported for

Chapter 10. Programming Design Considerations 10-9

Starting and Ending Communications

UCEP=7; the UCEP=7, PCEP=1 connection is now

active with an outstanding close connection request.
11. The clear confirmation is received for PCEP=1. To
inform the application of the successful close connection
request, an incoming data entry is sent to the data
queue.
12. The application's call to the QRCVDTAQ API returns
indicating there is data to receive.
13. The user-defined communications support fills the input
buffer and descriptor with data for the successful close
connection request operation, and determines the UCEP
associated with the data by examining the PCEP that
was requested for the close connection. Because the
close connection request was for PCEP=1, the UCEP=7.
The PCEP=1 is no longer active.
14. The application’s call to the QOLRECV API returns with
successful return and reason codes for the close con-
nection response operation. This operation is for UCEP
7. The UCEP=7, PCEP=1 connection is no longer
active.

Example 6

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC), sends │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP, 1, ├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CLEAR
│(4) Send close connection │ │ (5) Call cleared for PCEP 1.│%────────────
│ request for PCEP 1. │QOLSEND│ Send entry to data │
│ ├──────5│ queue. │
│ │ │ (6) Receive request to clear│
│ │ (rtn) │ PCEP 1. │
│(7) Data queue indicates data│%──────┤ │
│ to be received. │ │ │
│ │QOLRECV│ │
│ ├──────5│ (8) Fill in user space with │
│ │ │ result of unsuccessful │
│ │ (rtn) │ call request for UCEP 7 │
│ │%──────┤ and return. │
│(9) Open connection request │ │ │
│ was not successful. │ │(1ð) Close is successful. │
│ Outstanding close request│ │ Send entry to data │
│ means UCEP 7 still │ │ queue. │
│ active. │ │ │
│ │ │ │
│(11) Data queue indicates │ │ │
│ there is data to receive.│QOLRECV│ │
│ ├──────5│(12) Fill in user space with │
│ │ (rtn) │ close connection response│
│(13) Outstanding close │%──────┤ and return. │
│ connection returned │ │ │
│ not successful. UCEP │ │ │
│ 7 no longer active. │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-8. Example 6: Successful Attempt to Clear Outstanding (Unsuccessful) Call

10-10 AS/400 System API Reference V4R4

 Starting and Ending Communications

1. The application wishes to open a connection, so it calls 8. The user-defined communications support fills in the
the QOLSEND API, passing it the UCEP for the new input buffer and descriptor with data for the open con-
connection. The application keeps track of the UCEP, nection response, and determines the UCEP that the
PCEP pair. At this point, the UCEP=7, and the PCEP is data is for by using the PCEP that the X.25 clear is for.
undefined. Because the clear was received for PCEP=1, the UCEP
2. The user-defined communications support receives the is 7.
request, stores the UCEP for the connection, and uses 9. The application’s call to the QOLRECV API returns with
the next available PCEP, which is 1, and returns to the unsuccessful return and reason codes for the open con-
application, acknowledging the receipt of the request. nection request operation. This operation is reported for
The user-defined communications support validates the UCEP=7. Because the close connection request is out-
request and issues the X.25 call request. standing, the UCEP=7, PCEP=1 connection is not fully
closed. The application calls the QRCVDTAQ API.
3. The application records that the PCEP for UCEP=7 is 1,
and the UCEP=7, PCEP=1 connection is not yet active. 10. The close connection request is validated, but no clear is
Next, the application calls the QRCVDTAQ API to wait sent because the connection was cleared previously.
for the incoming data entry. The application is expecting The close is considered successful, and an entry is sent
the open connection response. to the data queue.

4. QRCVDTAQ API returns to the application (the dequeue 11. The application’s call to the QRCVDTAQ API returns
time-out value has elapsed), and the application no with the incoming data entry. The application then
longer wants the UCEP=7 connection. It calls the issues a call to the QOLRECV API.
QOLSEND API passing the PCEP=1 to identify the con- 12. The user-defined communications support fills in the
nection to be closed. Then the application calls the input buffer and descriptor with data for the successful
QRCVDTAQ API. close connection request operation, and determines the
5. The X.25 clear is received for PCEP=1. To inform the UCEP that the data is for by using the PCEP that the
application of the incoming data, an incoming data entry close connection was requested for. Since the close
is sent to the data queue. connection request was for PCEP=1, and the UCEP is 7.
The PCEP=1 is no longer active.
6. The user-defined communications support receives the
close connection request, and returns to the application, 13. The application’s call to the QOLRECV API returns with
acknowledging the receipt of the request. unsuccessful return and reason codes for the close con-
nection response operation. This operation is for UCEP
7. The application’s call to the QRCVDTAQ API returns 7. The connection UCEP=7, PCEP=1 is no longer
with the incoming data entry. The application then active.
issues a call to the QOLRECV API.

Chapter 10. Programming Design Considerations 10-11

Starting and Ending Communications

Example 7

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Send open connection │ │ │
│ request for SVC; use │ │ (2) Application requests │
│ next available UCEP, 7. │QOLSEND│ connection (SVC), sends │
│ ├──────5│ X.25 call request, uses │ CALL REQUEST
│ │ (rtn) │ next available PCEP (1),├────────────5
│(3) Record new PCEP and │%──────┤ and returns to │
│ wait for response. │ │ application. │
│ │ │ │ CLEAR
│(4) Send close connection │ │ (5) Call cleared for PCEP 1.│%────────────
│ request for PCEP 1. │QOLSEND│ Send entry to data │
│ ├──────5│ queue. │
│ │ │ │
│ │ │ (6) Receive request to clear│
│ │ (rtn) │ PCEP 1. │
│(7) Data queue indicates │%──────┤ │
│ date to be received. │ │ │
│ │QOLRECV│ │
│ ├──────5│ (8) Fill in user space with │
│ │ │ result of unsuccessful │
│ │ (rtn) │ call request for UCEP 7 │
│ │%──────┤ and return. PCEP 1 no │
│(9) Open connection request │ │ longer active. │
│ was not successful. │ │ │
│ UCEP 7 still active. │ │(1ð) User space error trying │
│ │ │ to close UCEP 1. Send │
│(11) Data queue indicates │ │ entry to data queue. │
│ there is data to receive.│QOLRECV│ │
│ ├──────5│(12) Fill in user space with │
│ │ │ close connection request│
│ │ (rtn) │ for UCEP 7 and return. │
│(13) Outstanding close │%──────┤ │
│ connection returned │ │ │
│ unsuccessful. UCEP 7 │ │ │
│ no longer active. │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-9. Example 7: Unsuccessful Attempt to Clear Outstanding (Unsuccessful) Call

1. The application wishes to open a connection, so it calls 5. The X.25 Clear is received for PCEP=1. To inform the
the QOLSEND API passing it the UCEP for the new application of the incoming data, an incoming data entry
connection. The application keeps track of the UCEP, is sent to the data queue.
PCEP pair. At this point, the UCEP=7, and the PCEP is
6. The user-defined communications support receives the
undefined.
close connection request, and returns to the application,
2. The user-defined communications support receives the acknowledging the receipt of the request.
request, stores the UCEP for the connection, and uses
7. The application’s call to the QRCVDTAQ API returns
the next available PCEP (1); and returns to the applica-
with the incoming data entry. The application then
tion, acknowledging the receipt of the request.
issues a call to the QOLRECV API.
The user-defined communications support validates the
8. The user-defined communications support fills in the
request and issues the X.25 call request.
input buffer and descriptor with data for the open con-
3. The application records that the PCEP for UCEP=7 is 1, nection response, and determines the UCEP that the
and the UCEP=7, PCEP=1 connection is not yet active. data is for by using the PCEP that the X.25 clear is for.
Next, the application calls the QRCVDTAQ API to wait Because the clear was received for PCEP=1, the UCEP
for the incoming data entry. The application is expecting is 7.
the open connection response.
9. The application’s call to the QOLRECV API returns with
4. The application no longer wants the UCEP=7 con- unsuccessful return and reason codes for the open con-
nection. It calls the QOLSEND API passing the PCEP=1 nection request operation. This operation is reported for
to identify the connection to be closed. The application UCEP=7. Because the close connection request is out-
calls the QRCVDTAQ API. standing, the UCEP=7, PCEP=1 connection is not fully
closed. The application calls the QRCVDTAQ API.

10-12 AS/400 System API Reference V4R4

 Starting and Ending Communications

10. The close connection request is validated, and an error Incoming Connections: The following figures show how
is found in the user space. An entry is sent to the data the application program handles UCEPs and PCEPs for
queue. incoming connections.
11. The application’s call to the QRCVDTAQ API returns
with the incoming data entry. The application then
issues a call to the QOLRECV API.
12. The user-defined communications support fills in the
input buffer and descriptor with data for the unsuccessful
close connection request operation, and determines the
UCEP that the data is for by using the PCEP that the
close connection was requested for. Since the close
connection request was for PCEP=1, the UCEP is 7.
Because the connection was cleared prior to the close
connection request, the PCEP=1, UCEP=7 connection is
considered no longer active to the user-defined commu-
nications support.
13. The application’s call to the QOLRECV API returns with
unsuccessful return and reason codes for the close con-
nection response operation. This operation is for UCEP
7. The connection UCEP=7, PCEP=1 is no longer
active.

Example 1

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌──────────────────────────────┐
│ │ │ │
│ │ │ │ CALL REQUEST
│ │ │ (1) Incoming call received. │%────────────
│(2) Data queue indicates data│ │ Use next available PCEP │
│ to receive. │QOLRECV│ 1, and send entry to │
│ ├──────5│ the data queue. │
│ │ │ │
│ │ (rtn) │ │
│ │%──────┤ (3) Fill user spaces with │
│(4) Incoming call using PCEP │ │ incoming call and return.│
│ 1. Send call accept; use│ │ │
│ next available UCEP (7). │QOLSEND│ (5) Send call accept for │
│ ├──────5│ PCEP 1, and return to │ CALL ACCEPT
│ │ (rtn) │ the application. ├────────────5
│ │%──────┤ │
│ │ │ │
│(6) Call accept was │ │ │
│ successful. UCEP=7, │ │ │ CALLREQUEST
│ PCEP=1 active. │ │ │ %─────────
│ │ │ │
└─────────────────────────────┘ └──────────────────────────────┘
Figure 10-10. Example 1: Normal Connection Establishment

1. An incoming call request is received by the communica- 3. The input buffer and descriptor are filled with the
tions support, which determines if there is an application incoming call request for PCEP=1, and the QOLRECV
that has a filter satisfying this call request. The commu- API returns.
nications support uses the next available PCEP, which is
4. The application looks at the operation, which indicates
1, for this new connection. An entry is sent to the data
an incoming call indication. The PCEP reported by the
queue.
communications support is 1. The application chooses
2. The application has been waiting for its call to the to accept this call, and passes the UCEP to be used for
QRCVDTAQ API to complete. The call completes indi- this new connection. The call is made to the QOLSEND
cating there is data to be received. The application calls API with PCEP=1, UCEP=7.
the QOLRECV API.
5. The call accept is received and sent for PCEP=1. The
QOLSEND API returns to the application.

Chapter 10. Programming Design Considerations 10-13

Starting and Ending Communications

6. The call accept request was successful for UCEP=7,

PCEP=1. This connection is now active.

Example 2

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌──────────────────────────────┐
│ │ │ │
│ │ │ │ CALL REQUEST
│ │ │ (1) Incoming call received. │%────────────
│(2) Data queue indicates data│ │ Use next available PCEP │
│ to receive. │QOLRECV│ (1), and send entry to │
│ ├──────5│ the data queue. │
│ │ │ │
│ │ (rtn) │ │
│ │%──────┤ (3) Fill user spaces with │
│(4) Incoming call using PCEP │ │ incoming call and return.│
│ 1. Send call accept; use│ │ │
│ next available UCEP (7). │QOLSEND│ (4) User space for call │
│ ├──────5│ accept not valid. Return │
│ │ (rtn) │ to the application. ├
│ │%──────┤ │
│ │ │ │
│(5) Call accept was not │ │ │
│ successful, UCEP= 7 is │ │ │
│ not active and incoming │ │ │
│ call is still │ │ │
│ outstanding. │ │ │
└─────────────────────────────┘ └──────────────────────────────┘
Figure 10-11. Example 2: Send Call Accept Not Valid

1. An incoming call request is received by the communica-

tions support, which determines if there is an application
that has a filter satisfying this call request. The commu-
nications support uses the next available PCEP=1 for
this new connection. An entry is sent to the data queue.
2. The application has been waiting for its call to the
QRCVDTAQ API to complete. It does, indicating there
is data to be received. The application calls the
QOLRECV API.
3. The input buffer and descriptor are filled with the
incoming call request for PCEP=1, and the QOLRECV
API returns.
4. The application looks at the operation which indicates an
incoming call indication. The PCEP reported by the
communications support is 1. The application chooses
to accept this call, and passes the UCEP to be used for
this new connection. The call is made to the QOLSEND
API with PCEP=1, UCEP=7.
5. The call accept is received and an error is found in the
user space. The QOLSEND API returns to the applica-
tion, reporting the error and offset. The incoming call is
still outstanding for PCEP=1.
The application checks the return and reason codes and
finds that an error has occurred. The call accept was
not sent and the incoming call is still waiting for a
response.

10-14 AS/400 System API Reference V4R4

 Starting and Ending Communications

Example 3

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│ │ │ │ CALL REQUEST
│ │ │ (1) Incoming call received. │%────────────
│(2) Data queue indicates data│ │ Use next available PCEP │
│ to be received. │QOLRECV│ (1) and send entry to │
│ ├──────5│ the data queue. │
│ │ │ │
│ │ (rtn) │ │
│ │%──────┤ (3) Fill user spaces with │
│(4) Incoming call using PCEP │ │ incoming call and return│
│ 1. Request to clear this│ │ │
│ call. │QOLSEND│ (5) Send Clear request. │
│ ├──────5│ Return to application. │ CLEAR
│ │ (rtn) │ ├────────────5
│ │%──────┤ │
│ │ │ (6) Clear is confirmed. Send│ CLEAR CONFIRMATION
│ │ │ entry to data queue. │%────────────
│(7) Data queue indicates data│ │ │
│ to be received. │QOLRECV│ │
│ ├──────5│ │
│ │ │ (8) Fill user spaces with │
│ │ (rtn) │ clear confirmation data.│
│ │%──────┤ │
│(9) Clear request was │ │ │
│ successful. │ │ │
│ PCEP 1 no longer active. │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-12. Example 3: Send Clear for Incoming Call

1. An incoming call request is received by the communica- 5. The close connection request is received and the
tions support, which determines if there is an application QOLSEND API returns to the application, acknowledging
that has a filter satisfying this call request. The commu- the request.
nications support uses the next available PCEP, which is
The close connection request is validated and a clear is
1, for this new connection. An entry is sent to the data
sent.
queue.
6. The clear confirmation is received for PCEP=1 which
2. The application has been waiting for its call to the
has no UCEP. An incoming data entry is sent to the
QRCVDTAQ API to complete. It does, indicating there
data queue. The application calls the QRCVDTAQ API.
is data to be received. The application calls the
QOLRECV API. 7. The application’s call to the QRCVDTAQ API returns
with the incoming data entry. The application calls the
3. The input buffer and descriptor are filled for the incoming
QOLRECV API to receive the data.
call request for PCEP=1, and the QOLRECV API
returns. 8. The input buffer and descriptor are filled in with the clear
confirmation data. Since the connection was never
4. The application looks at the operation which indicates an
established (and the application never assigned a UCEP
incoming call indication. The PCEP reported by the
to this connection), the QOLRECV API returns to the
communications support is 1. The application does not
application passing a UCEP=0.
wish to accept the call, so the user space is filled in for a
close connection request and the application calls the 9. The close connection request was successful. PCEP=1
QOLSEND API. The application calls the QRCVDTAQ is no longer active.
API.

Chapter 10. Programming Design Considerations 10-15

Starting and Ending Communications

Example 4

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌──────────────────────────────┐
│ │ │ │
│ │ │ │ CALL REQUEST
│ │ │ (1) Incoming call received. │%────────────
│(2) Data queue indicates data│ │ Use next available PCEP │
│ to be received. │QOLRECV│ (1), and send entry to │
│ ├──────5│ the data queue. │
│ │ │ │
│ │ (rtn) │ │
│ │%──────┤ (3) Fill user spaces with │
│(4) Incoming call using PCEP │ │ incoming call and return.│
│ 1. Request to clear this│ │ │
│ call. │QOLSEND│ (5) Close connection request │
│ ├──────5│ is received. │
│ │ (rtn) │ │
│ │%──────┤ │
│ │ │ (6) Close connection request │
│ │ │ is not valid. Send │
│(7) Data queue indicates data│ │ entry to data queue. │
│ to be received. │QOLRECV│ │
│ ├──────5│ │
│ │ │ (8) Fill user spaces with │
│ │ (rtn) │ the close connection │
│ │%──────┤ request and return. │
│(9) Clear request not │ │ │
│ successful. PCEP=1 │ │ │
│ is still active. │ │ │
└─────────────────────────────┘ └──────────────────────────────┘
Figure 10-13. Example 4: Send Clear for Incoming Call

1. An incoming call request is received by the communica- close connection request and the QOLSEND API. The
tions support, which determines there is an application application calls the QRCVDTAQ API.
that has a filter satisfying this call request. The commu-
5. The close connection request is received and the
nications support uses the next available PCEP=1 for
QOLSEND API returns to the application, acknowledging
this new connection. An entry is sent to the data queue.
the request.
2. The application has been waiting for its call to the
6. The close connection request is validated and an error is
QRCVDTAQ API to complete. It completes indicating
found. An entry is sent to the data queue.
there is data to be received. The application calls the
QOLRECV API. 7. The application’s call to the QRCVDTAQ API return, with
the incoming data entry. The application calls the
3. The input buffer and descriptor are filled for the incoming
QOLRECV API to receive the data.
call request for PCEP=1, and the QOLRECV API
returns. 8. The input buffer and descriptor are filled in with the
unsuccessful close request, and the QOLRECV API
4. The application looks at the operation which indicates an
returns to the application.
incoming call indication. The PCEP reported by the
communications support is 1. The application does not 9. The close connection request was not successful.
wish to accept the call, so the user space is filled in for a PCEP=1 is still active.

10-16 AS/400 System API Reference V4R4

 Starting and Ending Communications

Closing Connections: The following figures show how

the application program closes a connection. The figures
apply to both incoming and outgoing connections.

The next two figures illustrate that a close connection request

never completely guarantees the connection will be closed.

Example 1

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Connection is established│ │ │
│ as UCEP (7), PCEP (1). │ │ │
│ │ │ │
│(2) Send Close connection │QOLSEND│ (3) Receive close connection│
│ request. ├──────5│ request and return. │
│ │ │ │
│ │ (rtn) │ (4) User space value is │
│ │%──────┤ incorrect. Send entry │
│(5) Data queue indicates │ │ to data queue. │
│ data to be received. │ │ │
│ │QOLRECV│ (6) Fill user space with │
│ ├──────5│ close connection │
│ │ (rtn) │ request and return. │
│ │%──────┤ │
│ │ │ │
│(7) Close request was not │ │ │
│ successful. UCEP (7), │ │ │
│ PCEP (1) remains active. │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-14. Example 1: Close Connection Request Is Not Valid

1. A connection is established with the PCEP=1, UCEP=7.

2. The application calls the QOLSEND API to close the
connection. The application calls the QRCVDTAQ API.
3. The user-defined communications support receives the
close connection request and returns to the application,
acknowledging the receipt of the request.
4. The value in the user space is not correct. An entry is
sent to the data queue.
5. The application’s call to the QRCVDTAQ API returns
with the incoming data entry. The application calls the
QOLRECV API to receive the data.
6. The user-defined communications support fills the input
user space with data for the close connection request
and determines the UCEP that the data is for by exam-
ining the PCEP that was requested for the close con-
nection.
7. The application's call to the QOLRECV API returns with
unsuccessful return and reason codes for the close con-
nection response. This operation is for UCEP 7. The
connection UCEP=7, PCEP=1 is still active.

Chapter 10. Programming Design Considerations 10-17

Programming Considerations for LAN Applications

Example 2

Application Program User─Defined Communications Support

┌─────────────────────────────┐ ┌─────────────────────────────┐
│ │ │ │
│(1) Connection is established│ │ │
│ as UCEP (7), PCEP (1). │ │ │
│ │ │ │
│(2) Send close connection │QOLSEND│ (3) Receive close connection│
│ request. ├──────5│ request and return. │
│ │ │ │
│ │ (rtn) │ (4) Send clear request. │ CLEAR REQUEST
│ │%──────┤ ├────────────5
│ │ │ (5) Receive clear │
│ │ │ confirmation │ CLEAR CONFIRMATION
│(6) Data queue indicates data│ │ entry to the data │%────────────
│ to be received. │ │ queue. │
│ │QOLRECV│ (7) Fill user space with │
│ ├──────5│ close connection │
│ │ (rtn) │ confirmation and │
│ │%──────┤ return. │
│ │ │ │
│(8) Close request was │ │ │
│ successful. UCEP (7) │ │ │
│ PCEP (1) no longer │ │ │
│ active. │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
Figure 10-15. Example 2: Close Connection Request Is Valid

1. A connection is established with the PCEP=1, UCEP=7.

Programming Considerations for LAN
2. The application calls the QOLSEND API to close the Applications
connection. The application calls the QRCVDTAQ API.
3. The user-defined communications support receives the User-defined communications over LANs use connectionless
close connection request and returns to the application, (unacknowledged) service. Unacknowledged Information (UI)
acknowledging the receipt of the request. frames are the only frames an application program can gen-
erate.
4. The close connection request is received and the
QOLSEND API returns to the application, acknowledging For a description of the frame formats for Ethernet Version 2,
the request. The close connection request is validated IEEE 802.3, IEEE 802.5, wireless, and FDDI, refer to the
and a clear is sent. LAN, Frame-Relay and ATM Support book. To determine
5. The clear confirmation is received for PCEP=1, how the format and the user buffer are specified, see
UCEP=7. An incoming data entry is sent to the data Chapter 12, “User-Defined Communications Support APIs”
queue. on page 12-1.

6. The application’s call to the QRCVDTAQ API returns Operations: User-defined communications support
with the incoming data entry. The application calls the defines many different operations. Not all operations are
QOLRECV API to receive the data. valid on all data links. The operations which are valid for
7. The user-defined communications support fills the input LAN links are:
user space with data for the close connection confirma- Ÿ X'0000' and X'0001'. These operations together
tion and determines the UCEP that the data is for by represent the send- and receive-data operations for any
examining the PCEP that was requested for the close of the LAN frames types.
connection.
8. The application's call to the QOLRECV API returns with
successful return and reason codes for the close con-
Configuration
nection response. This operation is for UCEP 7. The The service access point (SAP) that the application program
connection UCEP=7, PCEP=1 is no longer active. uses to send and receive data must be configured in the line
description. The 04, 06, and AA SAPs are created if
*SYSGEN is specified on the CRTLINTRN, CRTLINETH,
CRTLINWLS, or CRTLINDDI command. The 04 SAP is
used by SNA, and the 06 and AA SAPs are used by TCP/IP.
An application can choose to use any SAP (including SAPs
defined by SNA or IEEE). The line description must be man-

10-18 AS/400 System API Reference V4R4

 Programming Considerations for LAN Applications

ually configured to include any other SAPs the application tion so that a system without that information can communi-
uses. The SAPTYPE for each SAP used must be configured cate with a new remote system.
as *NONSNA to be used by user-defined communications.

Although it is possible to use any SAP configurable on the Sending and Receiving Data
AS/400 system, it is not recommended to use SNA SAPs for
user-defined communications, because this may restrict the Maximum Frame Size: The user-defined communica-
use of SNA on your AS/400 system. In the same manner, tions support creates a data unit size which is always large
using the same SAP as other well-known protocols, such as enough to contain the maximum frame size supported by any
TCP/IP, may restrict the use of these protocols or the appli- of the SAPs configured for non-SNA use,
cation program on the AS/400 system. (SAPTYPE(*NONSNA)). The data unit size is returned in the
parameter list on the call to the QOLELINK API. For
Note: It is not possible to run an SNA application and a Ethernet (802.3), token-ring, FDDI, and wireless LANs, the
user-defined communications application program over the maximum frame size that the application can specify is the
same SAP concurrently. It is possible to run a TCP/IP appli- maximum frame size allowed by the SAP that the frame is
cation and a user-defined communications application over sent on. There is no minimum frame size for the Ethernet
the same SAP concurrently, provided the inbound routing 802.3, token-ring, FDDI, or wireless LANs.
information is unique among all the non-SNA applications
sharing the network controller. Ethernet Version 2 does not define SAPs for the higher-layer
protocols. Therefore, the maximum frame size is not deter-
mined by the maximum frame size for the SAP that the
Inbound Routing Information frame is sent on. The maximum frame size for Ethernet
For an application program to receive data from a LAN, it Version 2 is 1502 bytes. The first 2 bytes are for the type
must inform the communications support of how to filter the field, and the last 1500 bytes are for user data. The
inbound data and route it to the application. This is accom- minimum amount of data that can be sent is 48 bytes. The
plished by a program call to the Set Filter (QOLSETF) API. first 2 bytes are for the type field, and the next 46 bytes are
The fields in the incoming frame that are used to route the for user data. If the line is configured to handle both
data are DSAP, SSAP, MAC address, and type. Ethernet 802.3 and Ethernet Version 2 data, the larger of the
configured value or 1502 bytes is chosen and reported to the
The inbound routing information acts as a filter to allow the application on the data unit size parameter returned from the
user-defined application to distinguish its data from the rest QOLELINK API.
of the data on the LAN. The more selective the inbound
routing information is, the less chance there is that the appli- If your application program attempts to send data frames that
cation will be processing unnecessary input requests. Also, are larger or smaller than those that are supported, the
more selective inbound routing information allows multiple output request completes with nonzero return and reason
jobs running user-defined communications applications to codes, and an error code is returned to the application in the
share the same SAP. diagnostic information field.

For example, if an application is using 92 SSAP and 92 Application programs access information that is contained in
DSAP but only talking to one remote system, it may want to the line description through the Query Line Description
set a more selective filter which would include DSAP, SSAP, (QOLQLIND) API. It is best to call the QOLQLIND API after
and the MAC address of the remote system. Conversely, if the link has been successfully enabled because the informa-
an application accepts data on the 04 SAP from all systems tion that the QOLQLIND API passes to the application is
sending data on any SAP, then the application would set a accurate for as long as the link is enabled. The application
filter for DSAP only, indicating that it will accept all data uses the information on the frame size for the SAP to send
arriving on the 04 SAP. the correct amount of data over the SAP.

Maximum Amount of Outstanding Data: Most often,

End-to-End Connectivity the data arrives at a slightly faster rate than the application
program can receive it. The communications support keeps
Because user-defined communications on a LAN is data intended for an application so that the application can
connectionless, it is up to your application protocol to define receive it. However, there is a limit to the amount of data
a method to reach the remote systems it communicates with. that can be kept for the application to use later. The limit
There are several ways to do this. One way is to have each helps to avoid one system from overrunning another
system configured in a database file on the AS/400 system. system’s resources. When this limit is reached, all new
Each system could have a local name that the application incoming data frames for that application are discarded until
program uses to correlate with the MAC address and routing the application picks up one third of the data that was stored
information. LANs provide a technique to broadcast, which for the application. Because the data consists of unacknowl-
can be used to retrieve this information as well. An example edged information frames, the higher-layer protocol within the
of this is the Address Resolution Protocol (ARP) used by application detects the loss of data, resends the data, or per-
TCP/IP, which returns the MAC address and routing informa- forms other recovery actions.

Chapter 10. Programming Design Considerations 10-19

Programming Considerations for X.25 Applications

Each time the data limit is exceeded, the communications

support creates an error log entry and puts a message in the Programming Considerations for X.25
QSYSOPR message queue, indicating that the unacknowl- Applications
edged service has temporarily stopped receiving incoming
frames. The user-defined communications support interface to an
X.25 network is at the packet level, which is a connection-
oriented level. Your application program is responsible for
Ethernet to Token-Ring Conversion and ensuring reliable end-to-end connectivity. End-to-end
Routing connectivity means that the application program can initiate,
receive, and accept X.25 calls and handle network errors
The IBM 8209 Ethernet to token-ring bridge provides addi- reported to the application, as well as send and receive data.
tional connectivity options for the AS/400 system. See the
IBM 8209 LAN Bridge Customer Information book, Your application program has access to packets that flow
SA21-9994, for more details. over switched virtual circuits (SVCs) and permanent virtual
circuits (PVCs). The application can have SVC and PVC
connections active concurrently. You can configure up to 64
Performance Considerations virtual circuits on an X.25 line description, depending on the
communications I/O processor used. The X.25 Network
The application program enables connectionless traffic to
Support book provides more information about configuration
enter the AS/400 system from the LAN. In the call to the
limitations.
QOLSETF API, the DSAP field indicates the SAP which will
be activated on the AS/400 system. By activating traffic over The Display Connection Status (DSPCNNSTS) command
a SAP, data is taken from the LAN and brought into the shows the virtual circuits that are in use by a network device,
AS/400 system. Similarly, deactivating traffic over an SAP and the state of each connection. This command also dis-
causes traffic intended for that SAP to be left at the IOP level plays the active inbound routing information that the applica-
rather than to be processed on the AS/400 system. tion program uses to route calls.
To minimize host processing, the SAP or SAPs that the
application uses should be deactivated as soon as the appli- X.25 Packet Types Supported
cation no longer wants to receive traffic for the SAP. If the
link is disabled and no other applications are using the A packet is the basic unit of information transmitted through
SAP(s), they are deactivated automatically by the user- an X.25 network. The following table lists the X.25 packet
defined communications support. types along with the type of service provided. Services for
Switched Virtual Circuit (SVC) and Permanent Virtual Circuit
Protocols that use broadcast frames as a discovery tech- (PVC) connections are identified as well as services that are
nique could flood the network with messages and affect per- not accessible (N/A) to an application program.
formance on all the systems attached to the network.

Packet Type Application Input or Access SVC PVC N/A

Data Q,D bits of the general format identifier (GFI) X X
Note: The modulus used is configured in the line description. The open connection
request allows the user-defined communications support to set the actual window size used.
Interrupt 32 bytes of data X X
Note: On the AS/400 system, the X.25 packet layer provides the confirmation of the
receipt of this packet. The call to the QOLSEND API does not return until the interrupt is
confirmed by the remote system.
Reset Cause and diagnostic codes X X
request
Note: The application program provides the confirmation of this packet.
Reset indi- Cause and diagnostic codes X X
cation
Note: The application program provides the confirmation of this packet.
Reset confir- Note: User-defined communications support detects and reports reset collisions to the X X
mation application on the reset confirmation.
Incoming Call Remote DTE, local virtual circuit, packet and window sizes, up to 109 bytes of additional X
facilities, up to 128 bytes of bytes of call user data
Call Request Remote DTE, local virtual circuit, packet and window sizes, up to 109 bytes of additional X
facilities, up to 128 bytes of bytes of call user data
Call Accept Packet and window sizes, up to 109 bytes of additional facilities X

10-20 AS/400 System API Reference V4R4

 Programming Considerations for X.25 Applications

Packet Type Application Input or Access SVC PVC N/A

Call Con- Negotiated packet and window sizes, facilities X
nected
Clear request Cause and diagnostic codes, facilities, up to 128 bytes of clear user data X
Clear indi- Cause and diagnostic codes, facilities, up to 128 bytes of clear user data X
cation
Note: The X.25 packet layer support provides the confirmation on this request.
Clear confir- Note: The X.25 packet layer support provides this support. X
mation
Receive Note: The flow of RR and RNR packets is determined by the automatic flow control field of X
Ready (RR) Format I, specified in the open connection request.
Receive Not Note: The flow of RR and RNR packets is determined by the automatic flow control field of X
Ready (RNR) Format I, specified in the open connection request.
Reject (REJ) Note: This packet is not necessarily available on all networks and is not supported by the X
AS/400 system.
Restart Note: These packets affect all virtual circuits on the line. X
Request,
Indication,
and Confir-
mation
Diagnostic Note: This packet is not necessarily available on all networks and is not supported by the X
AS/400 system.
Registration Note: This packet is not necessarily available on all networks and is not supported by the X
Request and AS/400 system.
Confirmation

Operations: User-defined communications support QOLRECV API. The X'B201' operation indicates an
defines many different operations. The X'B000' operation incoming X.25 SVC call and is known as the call indication
either initiates an X.25 SVC call request, or a request to operation. The X'B301' operation indicates that a tempo-
open a PVC. By using this operation, an application program rary (reset) or permanent (clear) connection failure has
initiates an open connection request. The X'B100' opera- occurred. It is known as the connection failure indication
tion either initiates an X.25 SVC clear request (or confirms operation. Finally, the X'0000' operation indicates incoming
the connection failure), or requests closing a PVC. By using data. It is known as the receive data operation.
this operation, an application program initiates a close con-
nection request. The application can use the X'BF00' oper-
ation to cause the SVC or PVC connection to be reset.
Connections
User-defined communications support allows X.25 con-
The open connection request, close connection request, and
nections over both switched and permanent virtual circuits.
reset request (or response) operations are two-step oper-
Your application program can have one or many connections
ations. See “Synchronous and Asynchronous Operations” on
active at once. They can be either SVC, PVC, or both. The
page 10-2 for more information on programming for two-step
Display Connection Status (DSPCNNSTS) command shows
operations.
the state of the connection, logical channel identifier, virtual
The X'B400' operation initiates an X.25 SVC call accept. circuit type, and other information about the call. The states
This operation is known as a call accept operation. The of the connection include activate pending, active, deactivate
X'0000' operation initiates an X.25 Data packet for a SVC pending.
or PVC connection. This operation is called a send data
When the open connection request or call accept operations
operation. The call accept and send data operations are
are not yet complete, the connection state is activate
one-step operations. See “Synchronous and Asynchronous
pending. Once the open connection request or call accept
Operations” on page 10-2 for more information on program-
operations are complete with return and reason codes of
ming for one step operations.
zero, the connection state is active. When the close con-
The application program does not request the other available nection request is not yet complete, or if the connection is
X.25 operations. These X.25 operations are inbound packets cleared by the network, but a close connection request has
for responses from the asynchronous operations that are not been issued by the application program, the connection
reported to the application in the parameter list of the state is deactivate pending.

Chapter 10. Programming Design Considerations 10-21

Programming Considerations for X.25 Applications

Notes: ness. Because user-defined communications passes all

incoming data and connection failure indications to the appli-
1. The connection enters the active state when the call
cation program using the UCEP connection identifier, the
accept packet is sent on the network, which is inde-
application should ensure uniqueness of each UCEP. See
pendent of the application program receiving the results
“Using Connection Identifiers” on page 10-3 for information
of the open connection request. Likewise, a connection
on how to reuse connection identifiers.
can become completely closed (deactivated, and no
longer appears on the DSPCNNSTS screen) inde-
Connection Information: In order to ensure reliable
pendent of the application program receiving the results
end-to-end connectivity, an application program must keep
of the close connection request. This closing occurs
track of the control information for each connection it is
when the application confirms the connection failure.
responsible for. Some of this control information is shown in
2. A correctly encoded close connection request will always the following list.
be successful. The only time a close connection request
Ÿ State of the connection (activating, active, deactivating,
is not successful is when the application program has
reset)
coded the close connection request incorrectly. See
“Using Connection Identifiers” on page 10-3 for more Ÿ PCEP for this connection
information. Ÿ SVC or PVC connection indicator

Connection Identifiers: To differentiate between con- Ÿ Negotiated frame sizes; maximum data unit size
nections, user-defined communications support and an appli- Ÿ Connection is no longer active indicator or state
cation program both use connection identifiers from the time
the connection is started to the time the connection has suc- Ÿ Other application specific information
cessfully ended.
The application program can use the UCEP as an index into
User-defined communications support assigns an identifier the program’s data structures, which keep track of this
for each connection. This identifier is reported back to your control information.
application program as the provider connection end point
(PCEP). In the same manner, your application program Switched Virtual Circuit (SVC) Connectivity
assigns an identifier for each connection and reports it to the
communications support as the user connection end point Configuration: All the users of an X.25 line description
(UCEP). This exchange of identifiers allows both the com- share the SVCs that are configured for that line description.
munications support and the application program to refer to a These users are SNA, asynchronous X.25, OSI, TCP/IP, and
connection in a consistent manner. The UCEP and PCEP user-defined communications. You should define the line
are exchanged during the open connection request during description with enough SVCs to accommodate all of the
the following operations: users of the X.25 line.
Ÿ A PVC is opened.
Any SVCs defined in the X.25 line description that are not in
Ÿ An outgoing call is requested. use by any controllers (including the network controller) are
Ÿ The call indication is received and the call accept is available to an application program. The available SVCs are
accepted. distributed as they are requested by the users of the X.25
line description.
User-defined communications support identifies a connection
only in terms of PCEP and UCEP. For example, the user- See the X.25 Network Support book for more information on
defined communications support passes information to an configuring X.25 line descriptions.
application program and reports the UCEP to which the infor-
For user-defined communications, the application uses an
mation pertains. In the same manner the application
SVC when it either initiates a call, or receives an incoming
program initiates requests for a connection identified by the
call. The SVC is no longer in use when the application suc-
PCEP.
cessfully initiates a clear request to the SVC. Like PVCs,
User-defined communications support uses PCEPs over SVCs allow only one application program to have an active
again as they become free. PCEPs become free when the connection using the virtual circuit at a time.
application program receives notification that the open con-
nection request never completed successfully, or the close Inbound Routing Information: Before an application
connection request completed successfully. This means that program can receive and accept an incoming call, it must
PCEPs are not used over again until the application calls the first describe to the user-defined communications support the
QOLRECV API, which returns either the open connection X.25 calls that should be routed to the application. The
request or the close connection request. Until the PCEP is application does this by issuing a program call to the
freed, the connection cannot be reused. QOLSETF API, specifying the inbound routing information in
the filter.
User-defined communications support places no restrictions
on the value of the UCEP, and does not verify its unique-

10-22 AS/400 System API Reference V4R4

 Programming Considerations for X.25 Applications

The inbound routing information that an application program End-to-End Connectivity: The application is responsible
specifies is the first byte of call user data called the protocol for opening and closing PVC connections. To open a PVC,
ID, or the protocol ID combined with the calling DTE address. the application uses the open connection request operation,
In addition, the application specifies whether it will accept just as it does to initiate an X.25 SVC call. To close the
calls with fast select and reverse charging indicated. The PVC, the application uses the close connection request just
application program can either accept or reject any calls of as it does to clear the SVC call.
which it receives indications. The advantage of using filters
to allow the system to reject some calls (based on protocol Both systems that want to communicate end-to-end must first
ID, calling DTE address, fast select, and reverse charging open the virtual circuit on the local system. When the PVC
indicated in the incoming call) is that the application is is opened on the AS/400 system it is considered active and
relieved of some of the calls it would always reject. in use by the application. This is true even if the corre-
sponding remote system doesn’t have the virtual circuit
Once the connection is active, data flows end-to-end active. On the AS/400 system, an open connection request
between systems and does not need any other technique to always completes with return and reason codes of zero as
route it to the appropriate application. long as the PVC is defined in the line description and is not
in use by another application. There is no way to detect
End-to-End Connectivity: End-to-end connectivity is whether true end-to-end connectivity exists on the PVC.
achieved when one system initiates a call and another
accepts the call. When this happens, a connection is estab- If the virtual circuit is not active on both systems, and one
lished, and the state of the connection is active. It remains system attempts to communicate with the other, the virtual
active until either one of the application programs initiates a circuit on the system with the open PVC connection is reset.
clear request, or the network (or system) clears the con- An application that supports X.25 resets, sees the reset
nection due to an error condition. arrive as a result of the attempt to send data. In order to
continue, the application responds to the reset. An applica-
tion that does not support X.25 resets sees a connection
Permanent Virtual Circuit (PVC) failure. The application closes the PVC and opens the PVC
Connectivity again in order to continue to use the PVC.

Configuration: SNA and asynchronous X.25 controllers Similarly, when a PVC connection is closed from one system,
use PVCs on the X.25 line by configuring the controller the other system sees a reset (if reset is supported by that
description to logically attach to the PVC. This is not true for application) or a connection failure if reset is not supported.
users of the network controller description. When a PVC is If the application sees a reset, it must respond to the reset
in use by an application program, the system will logically before communications can continue on that connection.
attach the network controller to the PVC. This means that
any PVC defined in the X.25 line description and not
attached to any controller (including the network controller) is Sending and Receiving Data Packets
available for use by any application that has a link enabled
for the network to which the line is attached. Data Sizes: Data units larger and smaller than the negoti-
ated transmit packet size can be sent by an application
Because the attaching of PVCs to applications is program- program. Each data unit will be segmented into the appro-
mable, one job can have an open connection over the PVC, priate packet sizes by the AS/400 system. Contiguous data
end the connection, and then another job can open a dif- larger than the negotiated packet size can also be sent. The
ferent connection over the same PVC. Like SVCs, PVCs data is divided into individual packets and sent out with the
allow only one application program at a time to have an more-data indicator on. The application program should
active connection using the virtual circuit. request that the data unit size be a multiple of the transmit
and receive packet sizes configured in the line description.
Inbound Routing Information: By definition, the PVC The application program sets other important values that
does not require a call to set up a path from one system to pertain to each connection. See “X.25 SVC and PVC Output
another system. As its name suggests, this path always Operations” on page 12-31 for information about these
exists (permanent). Because there is no incoming call to values.
route, the application has no need to set a filter for the
inbound routing information. Once the application has The values your application supplies should be carefully
opened the PVC, there is no other information needed for the determined and tailored to the needs of the application. Sim-
system to route packets on the PVC to the application. ilarly, your application uses the values returned from the
system to ensure that the application does not exceed nego-
tiated limitations.

The application uses three values to determine how to fill the

user-space output buffer. These values are:
Ÿ Data unit size

Chapter 10. Programming Design Considerations 10-23

Programming Considerations for X.25 Applications

Ÿ Maximum data unit assembly size The automatic flow control value should be set high enough
so that RR/RNR processing does not affect performance on
Ÿ Negotiated transmit packet size
the virtual circuit, and low enough that the application can
The data unit size is the value that an application specifies process the data fast enough. If an application is coded
when the link is enabled. The maximum data unit assembly properly, the RR and RNR processing is not noticed by the
size is the total length of contiguous input data that is assem- application, just as for other system users of X.25.
bled by the AS/400 system before passing it to the applica-
To avoid situations where the virtual circuit is not operational
tion. Contiguous data units have the more-data indicator set
because an RNR was sent, or to avoid excessive amounts of
on in each descriptor for all the data units in the sequence
RR and RNR processing, the application program should
except the last data unit, which has the more-data indicator
always attempt to receive all the data from the communica-
set off. The application specifies the maximum data unit
tions support. An application that is not coded correctly can
assembly size on the open connection request. The
cause another application to wait indefinitely for an RR to
maximum data unit assembly size should always be greater
open the virtual circuit for communications. When the appli-
than the data unit size to make full use of the user spaces.
cations are coded correctly, the RR and RNR packet
The negotiated transmit packet size is returned when the
sequences are not noticed by the applications.
open connection request completes. The application uses
these values together to determine how to fill in the user
Maximum Amount of Outstanding Data: The com-
space output buffer.
munications support sets aside a limited amount of data for
Note: If the maximum data unit assembly size is exceeded, the applications it is servicing. For X.25, it is 128K for each
the data is passed up to the application with the connection. If the 128K limitation is met, an error log entry is
more-data indicator on. If the connection is abnor- created and the connection is cleared (SVCs) or reset
mally reset or cleared, the application may not (PVCs) by the system. Before this limit is reached, the
receive the rest of the contiguous data, which was in AS/400 system attempts to slow the incoming data traffic by
progress during the connection failure. issuing an RNR on behalf of the application. An RR is sent
after the application has received one-third of the amount of
If the two applications remain without exceeding the outstanding data.
maximum data unit assembly size supported on the
remote system, the system guarantees that the appli- Reset Support: When an application program initiates a
cation receives the complete, contiguous data packet reset, it is also responsible for discarding any data that the
sequence. user-defined communications support has received. The
user-defined communications support only discards data if
See “Maximum Amount of Outstanding Data” for related
the connection is closed.
information on incoming data limitations.

Interrupts: The interrupt is a special data packet. The AS/400 System X.25 Call Control
X.25 network imposes the restriction that a DTE cannot have
more than one outstanding interrupt on any virtual call in The X.25 support routes X.25 calls arriving to the AS/400
each direction. An application program issues an interrupt by system primarily based on the protocol ID field. This field is
calling the QOLSEND API. The QOLSEND API does not the first byte of call-user data in the X.25 call packet. For
return to the application program until the interrupt confirma- more information on the X.25 support, see the X.25 Network
tion has been received. It is important to understand the Support book.
interrupt confirmation procedures of the remote DTE and its
implications to the local system and application.
Performance Considerations
Flow Control: The AS/400 system sends the Receive The X'0000' operation is completely synchronous. This
Ready (RR) and Receive Not Ready (RNR) packets on means that control is not returned to the application until all
behalf of the application program. The distribution of these the data passed in the data units are sent and confirmed by
packets is based on the automatic flow control field in the the DCE. Some implications of this are:
open connection request operation. The automatic flow
control (RR/RNR) is sent to prevent one system from over- Ÿ If the application sends data on a connection that has
running another system with data. data flow turned off (the remote system sent an RNR to
the local AS/400 system), a subsequent call to the
When the automatic flow control value is exceeded for a con- QOLSEND API with operation X'0000' will not return
nection because a remote system is sending data at a rate until the remote system sends the RR to turn flow back
too fast for the local system, an RNR packet is sent on on for the connection.
behalf of the application on that local system. Once the Ÿ When transmitting Interrupt packets, control is not
application on the local system receives the data, an RR is returned to the application until the interrupt is confirmed
sent to allow more data to be received by the local system’s by the remote DTE. If the remote DTE is an AS/400
communications support. system, the interrupt is confirmed by the AS/400 system

10-24 AS/400 System API Reference V4R4

 Queue Considerations

X.25 packet layer support. If the network is congested, values can also serve as a way to prioritize entries on the
the use of Interrupt packets may cause a decrease in queue.
performance for the application.
The content of the queue entries that the application defines
In these situations, it may be appropriate to have one job for and uses is not restricted by the user-defined communica-
each connection (each virtual circuit). tions support. User-defined communications support never
attempts to receive any entries from the queue. It is the
responsibility of the application to receive the entries from the
Queue Considerations queue and perform the appropriate actions for an entry
based on its handle (or timer handle).
An application program uses a data queue or user queue for
communications between the application and the commu- This means that it might be necessary for the application to
nications support. The application should create the queue clear the old messages from the queue if it has been used.
prior to the call to the QOLELINK API. For more information For example, if a link is disabled, all communications entries
on creating and using a queue, see the CL Programming for that link (denoted by the communications handle) prior to
book. The link will never be fully enabled if the queue does the disable complete entry are no longer valid.
not exist. For example, in Figure 10-16, communications is Note: Timer support does not depend on the user-defined
no longer available when the user-defined communications communications support; therefore, timer entries are still
support detects that the data queue has been deleted. The valid.
same is true for user queues.
The following example shows an incoming data entry that the
APPLICATION COMMUNICATIONS SUPPORT
application receives is no longer valid because the applica-
(Link is enabled, application is tion made a request to disable the link.
successfully using the link.)
APPLICATION COMMUNICATIONS SUPPORT
│ │ Incoming data from
│ │ the network. (Link is enabled, application is
│ │%────────────────────── successfully using the link)
│ │
' CALL QOL_____ (Any call) ' │ │
│─────────────┐ │ An attempt is made to │ │ Incoming data.
│ │ │ send the incoming data │ │%──────────────────────
│ │ QSNDDTAQ │ entry to the data queue. │ │
│ Error:──────┼──────────────┤ ' CALL QOLDLINK '
│ data queue │ │ │─────────────┐ │ Incoming data entry
│ not found.──┼─────────────5│ The link using this │ │ │
│ │ │ data queue will no longer │ %───────┼──────────────┤ added to data queue.
│ │ │ be usable. │ │ │
│ │ │ │ └─────────────5│ Incoming data is
│ └─────────────5│ │ │ discarded and disable
│ │ Any subsequent CALL │ │ link is requested
│8ð/22ðð Return │ will return with │ ├───────────────────5
│ and Reason Codes │ return and reason codes │ │
│%───────────────────────────┤ indicating a severe │ │ Disable complete entry
│ │ application error. │ %──────────────────────│ added to data queue
' ' │ │
' Return from QOLDLINK '
Figure 10-16. Using the Data Queue │%───────────────────────────┤
' '
In addition to using a queue for communications between the ' The application will now '
│ call QRCVDTAQ waiting to │
application and the user-defined communications support, the │ receive the disable │
application can use the queue to provide communications ' complete entry '
with other applications. │ │
│ The incoming data entry │
│ will be received and │
If multiple processes are using the same queue, the queue │ discarded by the │
can be manipulated so that each process receives queue ' application '
entries based on the unique key for each application. This │ │
' The application will now '
allows the jobs to put many kinds of entries on the queue. │ call QRCVDTAQ (again) and │
For example, one key value is used for communications │ receive the disable │
between the application and the system, and another key ' complete entry. '
│ │
value is used for communications between the user-defined ' '
communications applications and other applications. Key
Figure 10-17. Application Disables the Link

Chapter 10. Programming Design Considerations 10-25

User Space Considerations

(QOLDLINK) API” on page 12-1 for more information on dis-

User Space Considerations abling the link.
Your application uses user space objects (*USRSPC) to hold The application reads from the input buffer and descriptor,
the input and output buffers and descriptors. The AS/400 and writes to the output buffer and descriptor. Similarly, the
system provides APIs you can use to manipulate the user user-defined communications support reads from the output
spaces. buffer and descriptor and writes to the input buffer and
descriptor. As soon as the call to the QOLSEND API or the
When you use the user-defined communications support, you
QOLRECV API is complete, the application can access these
create the user spaces, a total of four, as part of an enable
user spaces.
link request (the QOLELINK API). For each link, there is an
input buffer, input buffer descriptor, output buffer, and output If changes or deletions to the user spaces occur while they
buffer descriptor. The buffers and descriptors are used to are in use by the user-defined communications support, a
pass information to and from your application program. The severe application error is reported to the application, and
buffers are used to contain user data. The descriptors are communications over the link associated with the user
used to describe the data (length and other qualifiers). If the spaces is no longer possible.
enable link request is not successful (return and reason
┌───────────────────────────────┐
codes are nonzero), the user spaces are not created. │ User─Defined Communications │
┌────────┤ Application │%───────┐
┌───────────────────────────────┐ │ └─────┬─────────────────────────┘ │
│ User─Defined Communications │ │ Application │ & Application │
│ Application │ │ writes data │ │ reads data │
└───────────────────────────────┘ │ to output │ │ from input │
6 user spaces. 6 │ user spaces. │
├─────────output─────────────┤ ├──────────input─────────────┤ ┌────────────┐ ┌─────────────┐ ┌───────┴──────┐ ┌──────┴────┐
│ Data │ │Data Buffer │ │Data Buffer │ │Data │
┌────────────┐ ┌─────────────┐ ┌──────────────┐ ┌───────────┐ │ Descriptor │ │ │ │ │ │Descriptor │
│ Data │ │Data Buffer │ │Data Buffer │ │Data │ └─────┬──────┘ │ │ │ │ └───────────┘
│ Descriptor │ │ │ │ │ │Descriptor │ │ │ │ │ │ &
└────────────┘ │ │ │ │ └───────────┘ │ │ │ │ │ │
│ │ │ │ │ └──────┬──────┘ └──────────────┘ │
│ │ │ │ │ │ & │
└─────────────┘ └──────────────┘ └───────────┐ │ │ ┌───────────┘
Data is read from │ │ │ │ Data is written to
┌───────────────────────────────┐ user spaces by 6 6 │ │ user spaces by
│ User─Defined Communications │ ┌────────────────────────┴───┴──┐
│ Support │ │ User─Defined Communications │
└───────────────────────────────┘ │ Support │
└───────────────────────────────┘
Figure 10-19. Input/Output Operations
Figure 10-18. User Spaces
The user-defined communications support defines logical
The buffers are divided into equally sized, contiguous views for the user spaces. These views are sometimes
sections called data units. The output buffer contains data to called formats. There is a format for filters, sending and
be sent on the network. The input buffer contains data receiving LAN frames, and sending and receiving X.25
received from the network. The size of each data unit, as packets. See “Send Data (QOLSEND) API” on page 12-27
well as the number of data units created, is returned from the and “Receive Data (QOLRECV) API” on page 12-14 for
QOLELINK API when the link is enabled. details on these formats.

The buffer descriptors are divided into equally sized, contig- Your application must set all the data fields required for the
uous sections called descriptor elements. Each descriptor format. There are two types of byte fields in the buffer and
element describes the data in the corresponding data unit of descriptors, character (CHAR) and binary (BIN). Binary
the buffer. For example, descriptor element 1 describes the implies that the value is used as a numeric value. Some-
data in data unit 1 of the buffer. The size of each descriptor times this might be a 1-byte numeric value; for example, 12 =
element is 32 bytes. X'0C'. If you write the application in a language that is not
capable of setting this type of binary field, the field should be
For complete and specific information about the input/output declared as character and set to X'0C'. The character type
buffers, descriptors, data units, and data elements, see the contains an EBCDIC value, printable or not printable. In
sections in Chapter 12, “User-Defined Communications contrast, all parameter values are either character or 4-byte
Support APIs” on page 12-1 describing the individual APIs. binary. See “Programming Languages” on page 10-3 for
help in writing your application so that it can provide the
Your application provides the library and name of the user expected input for the user-defined communications support.
space object that is created. The descriptive text for the
object always contains the name of the job that is using The communications support never changes the output
these spaces. Finally, when the link is disabled (either buffer; therefore, your application is responsible for initializing
explicitly or implicitly), these user spaces are deleted by the the buffer and descriptor for the next operation, if necessary.
user-defined communications support. See “Disable Link The data in the output buffer can also be used to help deter-
mine why a particular operation is not successful.

10-26 AS/400 System API Reference V4R4

 Messages

For performance reasons, your application should attempt to Note: ‘x’ represents any decimal number. For example,
fill the output buffer as completely as possible. 1xxx represents the range 1000 - 1999.

Finally, for security reasons, your application chooses the For complete and specific information about the reason
library the user space object will reside in. The library can codes and return codes, see the sections in Chapter 12,
be any system library, including QTEMP. The advantage (or “User-Defined Communications Support APIs” on page 12-1
disadvantage) of using QTEMP for user space objects is that describing the individual APIs.
only the job which has enabled the links has access to the
user spaces. This is because a QTEMP library exists for
each job on the system. If the user space objects are in any Messages
other library, any job having authority to the library that the
user spaces are in can access them. The following messages are used to signal the success or
failure of operations performed by the user-defined commu-
nications APIs:
Return Codes and Reason Codes Ÿ Information
CPI91F0 I X.25 network error occurred.
When control returns from a user-defined communications CPI91F1 I ISDN network error occurred.
API to your application program, the status of the operation
is located in the reason code and return code output parame- Ÿ Escape
ters for each API. CPF91F0 E Internal system error.
CPF91F1 E User-defined communications application
Return codes are 4-byte numbers that determine the error.
recovery action to take. They are grouped into the following CPF9872 E Program or service program &1 in library
categories: &2 ended. Reason code &3.
Ÿ 00 — Operation successful, no recovery needed Ÿ Diagnostic
Ÿ 80 — Irrecoverable error, need to disable link CPD91F0 D
Ÿ 81 — Irrecoverable error, do not need to disable link Error detected in program &1. Condition
code is &2.
Ÿ 82 — Recoverable error, enable link failed
CPD91F1 D
Ÿ 83 — Recoverable error, see recovery actions Unexpected error detected in program &1.
Condition code is &2.
Reason codes are 4-byte numbers that determine what error CPD91F2 D
occurred. They are grouped into the following categories: User space &1 or &3 not accessible.
Ÿ 0000 — No error CPD91F3 D
Data limit exceeded. Some data not sent.
Ÿ 1xxx — Parameter validation or format error
CPD91F4 D
Ÿ 20xx — Line, controller, or device description error Error while accessing queue &1 in library
Ÿ 22xx — Data queue error &2.
CPD91F5 D
Ÿ 24xx — Buffer or buffer descriptor error Error while accessing queue. Time &1
Ÿ 30xx — Link state error canceled.
CPD91F6 D
Ÿ 32xx — Connection state error
Error occurred on line &1 while in use.
Ÿ 34xx — Timer state error CPD91F7 D
Ÿ 4xxx — Communication error Recovery canceled for network interface &3
or line &1.
Ÿ 8xxx — Application error CPD91F8 D
Ÿ 9999 — A condition in which an Authorized Program Error while accessing queue &1 in library
Analysis Report (APAR) may be submitted &2.
CPD91F9 D
Error while enabling line &1.

Chapter 10. Programming Design Considerations 10-27

Messages

10-28 AS/400 System API Reference V4R4

 Queue Entries

Chapter 11. Configuration and Queue Entries

This chapter describes how to do the following: Use the following commands to create or change controller
Ÿ Configure user-defined communications support descriptions:

Ÿ Set up the entries that user-defined communications Ÿ CRTCTLNET — Create Controller Description (Network)
support can send to the queue Ÿ CHGCTLNET — Change Controller Description
(Network)

Configuring User-Defined Communications Use the following commands to create or change device
descriptions:
Support
Ÿ CRTDEVNET — Create Device Description (Network)
This section describes what needs to be configured before Ÿ CHGDEVNET — Change Device Description (Network)
your application program can use the user-defined commu-
nications APIs. You can either use the system-supplied Use the following commands to create or change network
menus or the Control Language (CL) commands to do this interface descriptions:
configuration. For more information on using queue APIs,
Ÿ CRTNWIISDN — Create Network Interface Description
see the Object APIs in the Information Center.
(ISDN)
Ÿ CHGNWIISDN — Change Network Interface Description
Links (ISDN)
Links allow your application program to use a token-ring, See the Communications Configuration book for more infor-
Ethernet, FDDI, wireless, or X.25 communications line. A mation on configuring communications.
link is made up of the following communications objects:
Ÿ Token-ring, Ethernet, FDDI, wireless, or X.25 line
description
Queue
Ÿ Network controller description User-defined communications support uses a queue to
inform your application program of some action to take or of
Ÿ Network device description of type *USRDFN
an activity that is complete. You must create the queue
Ÿ Network interface description for ISDN (X.25 only) before the link is enabled.

You need to configure the line description; user-defined com- The size of each queue entry must be large enough to
munications support automatically configures a network con- accommodate the user-defined communications support
troller and a network device description of type *USRDFN entries. See the following “Queue Entries” for more informa-
when the link is enabled. If you are using X.25 over ISDN, tion on the entries that user-defined communications support
the network interface description must also be configured. can send to the queue.
The network interface, line, controller, and device descrip-
tions are automatically varied on, if necessary. Use the Create Data Queue (CRTDTAQ) command to create
your data queues. Use the QUSCRTUQ and QUSDLTUQ
Use the following commands to create or change line APIs to create and delete your user queues.
descriptions:
Ÿ CRTLINDDI — Create Line Description (DDI)
Ÿ CHGLINDDI — Change Line Description (DDI)
Queue Entries
Ÿ CRTLINETH — Create Line Description (Ethernet) This section describes the entries user-defined communica-
Ÿ CHGLINETH — Change Line Description (Ethernet) tions support can send to the queue.

Ÿ CRTLINTRN — Create Line Description (Token-Ring)

General Format
Ÿ CHGLINTRN — Change Line Description (Token-Ring)
Ÿ CRTLINWLS — Create Line Description (Wireless) The length of each entry is always at least 80 bytes. When
using a keyed queue, however, each entry can be as large
Ÿ CHGLINWLS — Change Line Description (Wireless)
as 336 bytes, depending on the size of the key value sup-
Ÿ CRTLINX25 — Create Line Description (X.25) plied to the user-defined communications support.
Ÿ CHGLINX25 — Change Line Description (X.25)
Figure 11-1 on page 11-2 shows the general format of each
user-defined communications support entry.

 Copyright IBM Corp. 1998, 1999 11-1

Queue Entries

┌────────────┬──────────┬────────────┬───────────┐ Communications handle: The name of the link that is

│ Entry type │ Entry ID │ Entry data │ Key │ being enabled. Your application program supplies this name
│ CHAR(1ð) │ CHAR(2) │ CHAR(68) │ CHAR(256) │ when the QOLELINK API is called.
└────────────┴──────────┴────────────┴───────────┘

Bytes 1-1ð 11-12 13-8ð 81-336 Status: This indicates the outcome of the enable link opera-
tion. A character value of zero indicates the enable link
operation was successful and I/O is now possible on this link.
Figure 11-1. Queue Entry General Format
A character value of one indicates the enable link operation
Entry type: This indicates the type of entry on the queue was not successful (the job log contains messages indicating
and will be *USRDFN for all user-defined communications the reason). The user-defined communications support disa-
support entries. bles the link when the enable link operation does not com-
plete successfully and the disable-complete entry is not sent
Entry ID: This uniquely identifies each entry within an entry to the queue.
type. User-defined communications support has five entries
defined: Key: The key value associated with the enable-complete
entry when using a keyed queue. Your application program
Ÿ Enable-complete entry (entry ID = '00') supplies this key value when the QOLELINK API is called.
Ÿ Disable-complete entry (entry ID = '01') When using a non-keyed queue (indicated by supplying a
key length of zero to the QOLELINK API) this field is not
Ÿ Permanent-link-failure entry (entry ID = '02')
present.
Ÿ Incoming-data entry (entry ID = '03')
Ÿ Timer-expired entry (entry ID = '04') Disable-Complete Entry
Note: The entry type of *USRDFN and all associated entry
IDs, either defined or undefined, are reserved for user- The disable-complete entry is sent to the queue when a link
defined communications support. Therefore, your application is successfully disabled. This entry is always the last entry
program should not define entries using this entry type. sent by the user-defined communications support on this link
and, therefore, provides a way for your application program
Entry data: This data is useful to your application program to remove any enable-complete, incoming-data, or
and varies according to the entry ID. permanent-link-failure entries previously sent to the queue1.

Key: When using a keyed queue, this is the key value sup- Figure 11-3 shows the format of the disable-complete entry.
plied to the user-defined communications support.
┌──────────┬──────┬────────────────┬──────────┬─────┐
│ \USRDFN │ 'ð1' │ Communications │ Reserved │ Key │
Enable-Complete Entry │ │ │ handle │ │ │
└──────────┴──────┴────────────────┴──────────┴─────┘
The enable-complete entry is sent to the queue when the Bytes 1-1ð 11-12 13-22 23─8ð 81─336
enable link operation is complete. This entry is only sent
after the Enable Link (QOLELINK) API returns to your appli- Figure 11-3. Disable-Complete Entry
cation program with a successful return and reason code.
Communications handle: The name of the link that has
Note: The QOLELINK API only initiates the enabling of the been disabled. Your application program supplies this name
link. Your application program must wait for the enable- when the QOLELINK API is called to enable the link.
complete entry before attempting to perform input or output
on the link. Key: The key value associated with the disable-complete
entry, when using a keyed queue. Your application program
Figure 11-2 shows the format of the enable-complete entry. supplies this key value when the QOLELINK API is called to
┌─────────┬──────┬────────────────┬────────┬──────────┬─────┐ enable the link. When using a non-keyed queue (indicated
│ \USRDFN │ 'ðð' │ Communications │ Status │ Reserved │ Key │ by supplying a key length of zero to the QOLELINK API) this
│ │ │ handle │ │ │ │ field is not present.
└─────────┴──────┴────────────────┴────────┴──────────┴─────┘

Bytes 1-1ð 11-12 13-22 23 24-8ð 81-336

Figure 11-2. Enable-Complete Entry

1 User-defined communications support does not associate timers with links. Therefore, it is possible for a timer-expired entry to be sent to
the queue after the link is disabled. Your user-defined communications application program is responsible for handling this.

11-2 AS/400 System API Reference V4R4

 Queue Entries

Permanent-Link-Failure Entry ┌─────────┬──────┬────────────────┬──────────┬─────┐

│ \USRDFN │ 'ð3' │ Communications │ Reserved │ Key │
│ │ │ handle │ │ │
The permanent-link-failure entry is sent to the queue when └─────────┴──────┴────────────────┴──────────┴─────┘
error recovery is canceled on a link. You must disable and
then enable the link to recover. Bytes 1-1ð 11-12 13-22 23-8ð 81-336

Figure 11-4 on page 11-3 shows the format of the Figure 11-5. Incoming-Data Entry
permanent-link-failure entry.
Communications handle: The name of the link on which
┌──────────┬──────┬────────────────┬──────────┬─────┐
│ \USRDFN │ 'ð2' │ Communications │ Reserved │ Key │ the data has come in. Your application program supplies this
│ │ │ handle │ │ │ name when the QOLELINK API is called to enable the link.
└──────────┴──────┴────────────────┴──────────┴─────┘
Bytes 1-1ð 11-12 13-22 23─8ð 81─336 Key: The key value associated with the incoming-data
entry, when using a keyed queue. Your application program
Figure 11-4. Permanent-Link-Failure Entry supplies this key value when the QOLELINK API is called to
enable the link. When using a non-keyed queue (indicated
Communications handle: The name of the link on which by supplying a key length of zero to the QOLELINK API) this
the failure has occurred. Your application program supplies field is not present.
this name when the QOLELINK API is called to enable the
link.
Timer-Expired Entry
Key: The key value associated with the permanent-link-
failure entry, when using a keyed queue. Your application The timer-expired entry is sent to the queue when a timer,
program supplies this key value when the QOLELINK API is previously set by your application program, ends.
called to enable the link. When using a non-keyed queue
Figure 11-6 shows the format of the timer-expired entry.
(indicated by supplying a key length of zero to the
QOLELINK API) this field is not present. ┌──────────┬──────┬────────┬──────┬─────┐
│ \USRDFN │ 'ð4' │ Timer │ User │ Key │
│ │ │ handle │ data │ │
Incoming-Data Entry └──────────┴──────┴────────┴──────┴─────┘

The incoming-data entry is sent to the queue when the user- Bytes 1-1ð 11-12 13-2ð 21-8ð 81-336
defined communications support has data for your application
program to receive. Your application program should call the Figure 11-6. Timer-Expired Entry
Receive Data (QOLRECV) API to pick up the data when this
entry is received. Timer handle: The name of the expired (ended) timer.
Your application program returns this name when the Set or
Note: Another incoming-data entry is not sent to the queue
Cancel Timer (QOLTIMER) API is called to set the timer.
until your application program picks up all the data from the
user-defined communications support. The data available User data: The data associated with the expired timer.
parameter on the call to the QOLRECV API indicates that the Your application program supplies this data when the
receipt of data is not complete. QOLTIMER API is called to set the timer.
Figure 11-5 shows the format of the incoming-data entry. Key: The key value associated with the timer-expired entry,
when using a keyed queue. Your application program sup-
plies this key value when the QOLTIMER API is called to set
the timer. When using a non-keyed queue (indicated by sup-
plying a key length of zero to the QOLTIMER API) this field
is not present.

Chapter 11. Configuration and Queue Entries 11-3

Queue Entries

11-4 AS/400 System API Reference V4R4

 Disable Link (QOLDLINK) API

Chapter 12. User-Defined Communications Support APIs

Ÿ When a job ends in which one or more links were
User-Defined Communications Support enabled
APIs—Introduction
Ÿ When the application program that enabled the link ends
User-defined communications support is made up of seven abnormally
callable APIs that provide services for a user-defined com- Ÿ When the Reclaim Resource (RCLRSC) command is
munications application program. The user-defined commu- used
nications APIs include the following:
Ÿ When an unmonitored escape message is received
Disable Link (QOLDLINK) disables one or all links.
Enable Link (QOLELINK) enables link for input and output. For each link that is successfully disabled, either explicitly or
Query Line Description implicitly, the disable-complete entry will be sent to the data
(QOLQLIND) queries an existing line descrip- queue or user queue specified on the call to the QOLELINK
tion. API when the link was enabled. See “Disable-Complete
Receive Data (QOLRECV) receives data from the link. Entry” on page 11-2 for the format of the disable-complete
Send Data (QOLSEND) sends data from the link. entry.
Set Filter (QOLSETF) activates or deactivates filters.
Set Timer (QOLTIMER) sets or cancels a timer.
Required Parameter Group
The following sections provide detailed information about
each of the user-defined communications APIs. The user- Return code
defined communications APIs are listed in alphabetic order. OUTPUT; BINARY(4)
The recovery action to take. See “Return and Reason
Codes.”
Disable Link (QOLDLINK) API
Reason code
OUTPUT; BINARY(4)
Required Parameter Group: The error that occurred. See “Return and Reason
Codes.”
1 Return code Output Binary(4)
2 Reason code Output Binary(4) Communications handle
3 Communications handle Input Char(10) INPUT; CHAR(10)
4 Vary option Input Char(1)
The name of the link to disable. The special value of
Threadsafe: No *ALL (left-justified and padded on the right with spaces)
may be used to disable all links currently enabled in the
job that the application program is running in.
The Disable Link (QOLDLINK) API disables one or all links
that are currently enabled in the job in which the application Vary option
program is running. When a link is disabled, all system INPUT; CHAR(1)
resources that the link is using are released, the input and The vary option for the network device description asso-
output buffers and descriptors for that link are deleted, and ciated with each link being disabled. The valid values
input or output on that link is no longer possible. are as follows:

In addition to an application program explicitly disabling a link X'00' Do not vary off the network device
by calling the QOLDLINK API, user-defined communications description.
support will implicitly disable a link in the following cases: X'01' Vary off the network device description.
Ÿ When the network device associated with an enabled
link is varied off from the job in which it was enabled Return and Reason Codes

Figure 12-1 (Page 1 of 2). Return and Reason Codes for the QOLDLINK API
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.
83/1004 Vary option not valid. Correct the vary option parameter. Then, try the request
again.

 Copyright IBM Corp. 1998, 1999 12-1

Enable Link (QOLELINK) API

Figure 12-1 (Page 2 of 2). Return and Reason Codes for the QOLDLINK API
Return /
Reason
Code Meaning Recovery
83/3001 Link not enabled. Correct the communications handle parameter. Then, try
the request again.

created, if necessary. In addition, the following are varied

Enable Link (QOLELINK) API on, if necessary.
Ÿ Line description
Required Parameter Group: Ÿ Network controller description
1 Return code Output Binary(4) Ÿ Network device description
2 Reason code Output Binary(4) Ÿ Network interface descriptions used by the line descrip-
3 Data unit size Output Binary(4)
tion
4 Data units created Output Binary(4)
5 LAN user data size Output Binary(4) If the X.25 switched network interface list has multiple
6 X.25 data unit size Input Binary(4) network interface descriptions configured, all of them can be
7 Input buffer Input Char(20) varied on at one time. For more information on varying on
8 Input buffer descriptor Input Char(20)
network interface descriptions, refer to the Communications
9 Output buffer Input Char(20)
10 Output buffer descriptor Input Char(20)
Management book.
11 Key length Input Binary(4)
12 Key value Input Char(256) When the QOLELINK API returns, your application program
13 Qualified queue name Input Char(20) should examine the codes to determine the status of the link.
14 Line description Input Char(10) Successful return and reason codes (both zero) indicate the
15 Communications handle Input Char(10) link is being enabled and an enable-complete entry will be
sent to the data queue or user queue specified on the call to
Optional Parameter Group: the QOLELINK API when the enable operation completes.
See “Enable-Complete Entry” on page 11-2 for more infor-
16 Queue type Input Char(1)
17 Network interface descrip- Input Char(10)
mation on the enable-complete entry. Unsuccessful return
tion and reason codes indicate the link could not be enabled and
18 Extended operations Input Char(1) the enable-complete entry will not be sent to the data queue
or user queue. “Return and Reason Codes” on page 12-4
Threadsafe: No provides more information on the QOLELINK API return and
reason codes.

The Enable Link (QOLELINK) API enables a link for input

and output on a communications line. The communications Authorities and Locks
line, described by the line description parameter, must be a User Space Authority
token-ring, Ethernet, wireless, FDDI, or X.25 line. The link *READ
being enabled can only be accessed within the job in which User Space Library Authority
the QOLELINK API was called. *USE and *ADD. *OBJOPR plus *READ is
equivalent to *USE.
Before calling the QOLELINK API to enable a link, you must
User Space Lock
configure the following objects:
*EXCL
Ÿ Token-ring, Ethernet, wireless, FDDI, or X.25 line
description
Required Parameter Group
Ÿ Data queue or user queue
Return code
Ÿ Network interface description for X.25 networks running
OUTPUT; BINARY(4)
over ISDN
The recovery action to take. See “Return and Reason
See “Configuring User-Defined Communications Support” on Codes” on page 12-4.
page 11-1 for more information on configuration.
Reason code
The QOLELINK API creates the input and output buffers and OUTPUT; BINARY(4)
buffer descriptors used for the link being enabled. The The error that occurred. See “Return and Reason
network controller description and the network device Codes” on page 12-4.
description, associated with the link being enabled, are also

12-2 AS/400 System API Reference V4R4

 Enable Link (QOLELINK) API

Data unit size ters specify the name for the input buffer and the second
OUTPUT; BINARY(4) 10 characters specify the name of an existing library that
the input buffer will be created in. Both entries are left-
The total number of bytes allocated for each data unit in
justified. The special values of *LIBL and *CURLIB can
the input and output buffers. For token-ring links, this
be used for the library name.
includes user data (LAN user data size parameter),
general LAN header information, and optional routing Note: A user space object with the same name as the
information. For Ethernet, wireless, and FDDI links, this input buffer must not already exist in the specified
includes user data (LAN user data size parameter) and library.
general LAN header information. For X.25 links, this
Input buffer descriptor
includes user data (X.25 user data size parameter). For
INPUT; CHAR(20)
more information on the general LAN header, see
Figure 12-11 on page 12-17. The name and library of the input buffer descriptor that
the QOLELINK API creates for this link. The first 10
Data units created
characters specify the name of the input buffer
OUTPUT; BINARY(4)
descriptor and the second 10 characters specify the
The number of data units created for the input buffer and name of an existing library that the input buffer
the output buffer. This parameter also specifies the descriptor will be created in. Both entries are left-
number of elements created for the input buffer justified. The special values of *LIBL and *CURLIB can
descriptor and the output buffer descriptor. The only be used for the library name.
valid value is:
Note: A user space object with the same name as the
8 All protocols input buffer descriptor must not already exist in the spec-
ified library.
Note: Because user-defined communications support
always returns an 8, you should write your application Output buffer
program to avoid having to recompile should this value INPUT; CHAR(20)
ever change. The name and library of the output buffer that the
QOLELINK API creates for this link. The first 10 charac-
LAN user data size
ters specify the name of the output buffer and the
OUTPUT; BINARY(4)
second 10 characters specify the name of an existing
The number of bytes allocated for token ring, Ethernet, library that the output buffer will be created in. Both
wireless, or FDDI in each data unit of the input and entries are left-justified. The special values of *LIBL and
output buffers. This does not include general LAN *CURLIB can be used for the library name.
header information and optional routing information.
Note: A user space object with the same name as the
The content of this parameter is only valid when ena- output buffer must not already exist in the specified
bling a token-ring, Ethernet, wireless, or FDDI link. library.
Note: The maximum amount of token-ring, Ethernet,
Output buffer descriptor
wireless, or FDDI user data that can be sent or received
INPUT; CHAR(20)
in each data unit is determined on a service access
point basis in the line description or by the 1502 byte The name and library of the output buffer descriptor that
maximum for Ethernet Version 2 frames, and may be the QOLELINK API creates for this link. The first 10
less than the LAN user data size. See “Query Line characters specify the name of the output buffer
Description (QOLQLIND) API” on page 12-5 for informa- descriptor and the second 10 characters specify the
tion on retrieving these values. name of an existing library that the output buffer
descriptor will be created in. Both entries are left-
X.25 data unit size justified. The special values of *LIBL and *CURLIB can
INPUT; BINARY(4) be used for the library name.
The number of bytes allocated for X.25 user data in Note: A user space object with the same name as the
each data unit of the input and output buffers. This is output buffer descriptor must not already exist in the
equal to the maximum amount of X.25 user data that specified library.
can be sent or received in each data unit. The content
of this parameter is only valid when enabling an X.25 Key length
link. INPUT; BINARY(4)
The key length when using a keyed data queue or user
Range 512 bytes–4096 bytes
queue.
Input buffer
INPUT; CHAR(20)
0 The data queue or user queue is not
keyed.
The name and library of the input buffer that the Range 1–256
QOLELINK API creates for this link. The first 10 charac-

Chapter 12. User-Defined Communications Support APIs 12-3

Enable Link (QOLELINK) API

Key value D Data queue

INPUT; CHAR(256) U User queue
The key value (left justified) when using a keyed data Network interface description
queue or user queue. INPUT; CHAR(10)
Qualified queue name The name of the network interface description. This
INPUT; CHAR(20) value is specified if you are running X.25 and need to
specify a particular network interface to use. Otherwise,
The name and library of the data queue or user queue
this value should be set to blanks.
where the enable-complete, disable-complete,
permanent-link-failure, and incoming-data entries for this Note: This parameter along with the line description
link will be sent. See “Queue Entries” on page 11-1 for parameter causes only the network interface description
more information about these queue entries. The first specified to be varied on. If this value is not specified
10 characters specify the name of an existing queue and and the line description parameter contains a switched
the second 10 characters specify the library in which the network interface list, all network interface descriptions
queue is located. Both entries are left-justified. The within the list are varied on when the QOLELINK API is
special values of *LIBL and *CURLIB can be used for called.
the library name.
Specifying this parameter causes only the line and the
Line description network interface that are passed to be varied on during
INPUT; CHAR(10) enable processing.

The name of the line description that describes the com- Extended operations
munications line the link being enabled will use. An INPUT; CHAR(1)
existing token-ring, Ethernet, wireless, FDDI, or X.25 line
Indicates whether or not extended operations are sup-
description must be used.
ported.
Communications handle Extended operations affect all connections (UCEPs,
INPUT; CHAR(10) PCEPs) on the link. X'B311' and X'B111' are receive
The name assigned to the link being enabled. Any extended operations. X'B110' is a send extended
name complying with system object naming conventions operation.
may be used.
1 Operations supported
0 Operations not supported
Optional Parameter Group
Queue type Return and Reason Codes
INPUT; CHAR(1)
The type of queue you specified for the Queue name
parameter.

Figure 12-2 (Page 1 of 2). Return and Reason Codes for the QOLELINK API
Return /
Reason
Code Meaning Recovery
0/0 Operation successful, link enabling. Wait to receive the enable-complete entry from the data
queue or user queue before doing input/output on this link.
81/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Then,
will be sent to the application program when this return and report the problem using the ANZPRB command.
reason code is received.
82/1000 User data size not valid for X.25 link. Correct the X.25 user data size parameter. Then, try the
request again.
82/1001 Key length not valid. Correct the key length parameter. Then, try the request
again.
82/1002 Queue name not valid. Correct the queue name parameter. Then, try the request
again.
82/1003 Communications handle not valid. Correct the communications handle parameter. Then, try
the request again.
82/1012 Queue type not valid. Queue type must be D or U. Correct the queue type and
try the request again.

12-4 AS/400 System API Reference V4R4

 Query Line Description (QOLQLIND) API

Figure 12-2 (Page 2 of 2). Return and Reason Codes for the QOLELINK API
Return /
Reason
Code Meaning Recovery
82/1013 Extended operations value not valid. Extended operations value must be 1 or 0. Correct the
extended operations value and try the request again.
82/1020 Group parameters not valid (not all the parameters within a Pass all parameters within the group and try the operation
group were passed). again.
82/2000 Line name not valid or protocol is not supported. The line name specified must be for a line of type Ethernet,
wireless, token ring, FDDI, or X.25. Correct the line name
and try the request again.
82/2001 Line description, network controller description, or network See messages in the job log indicating the affected object
device description not in a valid state. and recommended recovery. Do the recovery, and try the
request again.
82/2002 Not authorized to the line description or network controller See messages in the job log indicating the affected object
description. and get authorization to it. Then, try the request again.
82/2003 Could not allocate the network device description. Try the request again. If the problem continues, report the
problem using the ANZPRB command.
82/2004 Could not create the network controller description or See messages in the job log indicating the affected object
network device description. and recommended recovery. Do the recovery, and try the
request again.
82/2005 Could not vary on the network interface, line description, See messages in the job log indicating the affected object
network controller description, or network device description. and recommended recovery. Do the recovery, and try the
request again.
82/2006 Line description not found. Correct the line description parameter. Then, try the
request again.
82/2007 Line description damaged. Delete and re-create the line description. Then, try the
request again.
82/2008 Unsupported interface. An error occurred that indicated the The network interface value is not correct for the line name
network interface specified cannot be associated with the value. Correct the configuration or your application.
line specified. For example, you specified a network inter-
face for a token-ring, Ethernet, or wireless line.
82/2009 Network interface description not found. Specify the correct network interface name and try the
request again.
82/2010 Network interface description specified could not be used. Check the network interface description for possible errors.
Correct any errors and try the request again.
82/2400 An error occurred while creating the input buffer, input buffer See messages in the job log indicating the affected object
descriptor, output buffer, or output buffer descriptor. and recommended recovery. Do the recovery, and try the
request again.
82/3000 Communications handle already assigned to another link Either disable the link that was assigned this communica-
that is enabled in this job. tions handle, or correct the communications handle param-
eter so it does not specify a communications handle that is
already assigned to a link enabled in this job. Then, try the
request again.
82/3005 Line description already in use by another link that is Disable the link that is using this line description. Then, try
enabled in this job. the request again.

Error Messages CPF9872 E Program or service program &1 in library &2

ended. Reason code &3.
CPF3C90 E
Literal value cannot be changed.
CPF91F0 E Internal system error.
Query Line Description (QOLQLIND) API

Chapter 12. User-Defined Communications Support APIs 12-5

Query Line Description (QOLQLIND) API

Note: You are recommended to set the length user buffer

Required Parameter Group: value to a number large enough to hold the system
maximum values of virtual circuits, SAPs, and group
1 Return code Output Binary(4) addresses with additional space left for future needs.
2 Reason code Output Binary(4)
3 Number of bytes Output Binary(4) Line description
4 User buffer Output Char(*) INPUT; CHAR(10)
5 Line description Input Char(10)
The name of the line description to query. An existing
6 Format Input Char(1)
token-ring, Ethernet, wireless, FDDI, frame relay, or X.25
Optional Parameter Group: line description must be used.

Format
7 Length of user buffer Input Binary(4)
8 Bytes available Output Binary(4) INPUT; CHAR(1)
The format of the data returned in the user buffer. The
Threadsafe: No valid values are as follows:

X'01' Use format 01.

The Query Line Description (QOLQLIND) API queries an X'02' Use format 02.
existing token-ring, Ethernet, wireless, FDDI, frame relay, or
X.25 line description. The data received from the query is See “Format of Data in the User Buffer” on page 12-7
placed in the user buffer parameter. for more information.

The line description to be queried does not have to be asso-

ciated with any links the application program has enabled. Optional Parameter Group
However, data in the line description may change after it is Length of user buffer
queried. INPUT; BINARY(4)
The number of bytes available for the API to use in the
Required Parameter Group user buffer parameter. The valid values are from 0 to
32,767.
Return code
OUTPUT; BINARY(4) Notes:
The recovery action to take. See “Return and Reason 1. This parameter is required if format 2 is specified in
Codes” on page 12-13. the format parameter. It is optional if format 1 is
specified.
Reason code
OUTPUT; BINARY(4) 2. If length user buffer is specified, bytes available
must also be specified.
The error that occurred. See “Return and Reason
Codes” on page 12-13. 3. If additional information exists that could not be
reported, the bytes available parameter will contain
Number of bytes a larger value than the bytes returned parameter.
OUTPUT; BINARY(4)
Bytes available
The number of bytes of data returned in the user buffer.
OUTPUT; BINARY(4)
User buffer The total number of bytes of available information.
OUTPUT; CHAR(*)
Notes:
The buffer where the data from the query will be
received. Any unused space in the buffer will be filled 1. This parameter is required if format 2 is specified in
with X'00'. The length of this character structure is the format parameter. It is optional if format 1 is
determined using Figure 12-3. specified.
2. If bytes available is specified, length user buffer
must also be specified.
Format Group Length of Char(*)
Parameter 3. If the bytes available parameter contains a number
Passed larger than the bytes returned parameter, there is
1 No 256 additional information that the application cannot
access.
1 or 2 Yes Specified by the length user
buffer parameter. 4. If the return code parameter is nonzero, this value is
set to zero.
Figure 12-3. User Buffer Format

12-6 AS/400 System API Reference V4R4

 Query Line Description (QOLQLIND) API

Format of Data in the User Buffer

The data received in the user buffer from the query is made
up of two parts. The first portion starts at offset 0 from the
top of the user buffer and contains general query data. The
format of this data does not depend on value of the format
parameter supplied to the QOLQLIND API.

Figure 12-4. General Query Data

Field Type Description
Line descrip- CHAR(10) The name of the token-ring, Ethernet, wireless, FDDI, frame relay, or X.25 line description that was
tion queried.
Line type CHAR(1) The type of line description that was queried. The valid values are as follows:
X'04' X.25
X'05' Token-ring
X'09' Ethernet
X'0D' FDDI
X'0E' Frame relay
X'10' Wireless
Status CHAR(1) The current status of the line description. The valid values are as follows:
X'00' Varied off
X'01' Varied off pending
X'02' Varied on pending
X'03' Varied on
X'04' Active
X'05' Connect pending
X'06' Recovery pending
X'07' Recovery canceled
X'08' Failed
X'09' Diagnostic mode
X'FF' Unknown

The second portion of the user buffer starts immediately after depends on the value of the format parameter supplied to the
the general query data and contains data specific to the type QOLQLIND API.
of line description that was queried. The format of this data
LAN Specific Data–Format 01

Figure 12-5 (Page 1 of 2). LAN Specific Data–Format 01

Field Type Description
Local adapter CHAR(6) Specifies, in packed form, the local adapter address of this line. The special value of
address X'000000000000' indicates that the preset default address for the adapter card was configured.
However, the line description must be varied on before this address can be retrieved.
Line speed CHAR(1) The speed of this line. The valid values are as follows:
X'01' 4 megabits/second
X'02' 10 megabits/second
X'03' 16 megabits/second
X'04' 100 megabits/second
Line capability CHAR(1) The capability of this line. The valid values are as follows:
X'00' Non-Ethernet
X'01' Ethernet Version 2
X'02' Ethernet 802.3
X'03' Both Ethernet Version 2 and Ethernet 802.3
Line frame size BINARY(2) The maximum frame size possible on this line.
Ethernet BINARY(2) The maximum size for Ethernet Version 2 frames. This will be 1502 if the line is capable of Ethernet
Version 2 frame Version 2 traffic. Otherwise, it will be zero.
size

Chapter 12. User-Defined Communications Support APIs 12-7

Query Line Description (QOLQLIND) API

Figure 12-5 (Page 2 of 2). LAN Specific Data–Format 01

Field Type Description
Number of BINARY(2) The number of source service access points (SSAPs) configured for this line.
SSAPs
Note: The following 3 rows are repeated for each SSAP configured for this line.
SSAP CHAR(1) The configured source service access point.
SSAP type CHAR(1) The SSAP type. The valid values are as follows:
X'00' Non-SNA SSAP
X'01' SNA SSAP
SSAP frame BINARY(2) The maximum frame size allowed on this SSAP.
size
Number of BINARY(2) The number of group addresses configured for this line.
group
Note: This will always be zero for a token-ring line description.
addresses
Note: The following row is repeated for each group address configured for this line.
Group address CHAR(6) Specifies a group address, in packed form.

LAN Specific Data–Format 02

Figure 12-6 (Page 1 of 2). LAN Specific Data–Format 02

Field Type Description
Local adapter CHAR(6) Specifies, in packed form, the local adapter address of this line. The special value of
address X'000000000000' indicates that the preset default address for the adapter card was configured.
However, the line description must be varied on before this address can be retrieved.
Line speed CHAR(1) The speed of this line. The valid values are as follows:
X'01' 4 megabits/second
X'02' 10 megabits/second
X'03' 16 megabits/second
X'04' 100 megabits/second
X'05' Frame relay (line speed is specified separately)
Line capability CHAR(1) The capability of this line. The valid values are as follows:
X'00' Non-Ethernet
X'01' Ethernet Version 2
X'02' Ethernet 802.3
X'03' Both Ethernet Version 2 and Ethernet 802.3
Line frame size BINARY(2) The maximum frame size possible on this line.
Ethernet BINARY(2) The maximum size for Ethernet Version 2 frames. This will be 1502 if the line is capable of Ethernet
Version 2 frame Version 2 traffic. Otherwise, it will be zero.
size
Functional CHAR(6) The hexadecimal functional address configured for the line. An address of X'000000000000' indi-
address field cates there are no functional addresses configured on this line description.
Note: For additional information on functional addresses, refer to the Token-Ring Architecture Reference book, SC30-3374.
Number of BINARY(2) The number of group addresses configured for this line. This value is valid for Ethernet and wireless
group line descriptions only.
addresses
Offset to group BINARY(2) Offset within this structure to the array of group addresses
addresses
Number of BINARY(2) The number of SSAPs configured for this line.
SSAPs
Offset to BINARY(2) Offset within this structure to the array of SSAPs
SSAPs
FR line speed BINARY(4) Frame relay line speed. This value is valid only when the line type field is set to X'0E'.

12-8 AS/400 System API Reference V4R4

 Query Line Description (QOLQLIND) API

Figure 12-6 (Page 2 of 2). LAN Specific Data–Format 02

Field Type Description
Reserved CHAR(*) Reserved for extension
Note: The following row is duplicated by the number of group addresses.
Group address CHAR(6) Specifies a group address, in packed form.
Note: The following three rows are duplicated by the number of SSAPs.
SSAP CHAR(1) The configured source service access point.
SSAP type CHAR(1) The SSAP type. The valid values are as follows:
X'00' Non-SNA SSAP
X'01' SNA SSAP
SSAP frame BINARY(2) The maximum frame size allowed on this SSAP.
size

X.25 Specific Data–Format 01

Figure 12-7 (Page 1 of 2). X.25 Specific Data–Format 01

Field Type Description
Local network CHAR(1) Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the local network
address length address.
Local network CHAR(9) Specifies, in BCD, the local network address of this line.
address
Extended CHAR(1) Specifies whether network addressing is extended to permit the use of 17 digits in an address. The
network valid values are as follows:
addressing
X'01' Network addresses may be up to 15 digits
X'02' Network addresses may be up to 17 digits
Address CHAR(1) Specifies whether the system inserts the local network address in call request and call accept
insertion packets. The valid values are as follows:
'Y' The local network address is inserted in call request and call accept packets.
'N' The local network address is not inserted in call request and call accept packets.
Modulus CHAR(1) The X.25 modulus value. The valid values are as follows:
X'01' Modulus 8
X'02' Modulus 128
X.25 DCE CHAR(1) Specifies whether the system communicates using the integrated X.25 DCE support. This allows the
support system, acting as the DCE, to communicate with another system without going through an X.25
network. The valid values are as follows:
X'01' The system does not communicate using the X.25 DCE support
X'02' The system does communicate using the X.25 DCE support
X'03' The system negotiates whether it communicates using the X.25 DCE support.
Transmit BINARY(2) The transmit maximum packet size configured for this line.
maximum packet
size
Receive BINARY(2) The receive maximum packet size configured for this line.
maximum packet
size
Transmit default BINARY(2) The transmit default packet size configured for this line.
packet size
Receive default BINARY(2) The receive default packet size configured for this line.
packet size
Transmit default BINARY(1) The transmit default window size configured for this line.
window size
Receive default BINARY(1) The receive default window size configured for this line.
window size

Chapter 12. User-Defined Communications Support APIs 12-9

Query Line Description (QOLQLIND) API

Figure 12-7 (Page 2 of 2). X.25 Specific Data–Format 01

Field Type Description
Number of BINARY(2) The number of logical channels configured for this line.
logical channels
Note: The following 4 rows are repeated for each logical channel configured for this line
Logical channel CHAR(1) The logical channel group number. This together with the logical channel number makes up the
group number logical channel identifier.
Logical channel CHAR(1) The logical channel number. This together with the logical channel group number makes up the
number logical channel identifier.
Logical channel CHAR(1) The logical channel type. The valid values are as follows:
type
X'01' Switched virtual circuit (SVC).
X'02' Permanent virtual circuit (PVC) that is eligible for use by a network controller.
Note: This does not necessarily mean that this PVC is available for use. Another job
running on the network controller attached to this line may already have this PVC in
use.
X'22' PVC that is not eligible for use by a network controller. For example, a PVC that is
already attached to an asynchronous controller description.
Logical channel CHAR(1) The direction of calls allowed on the logical channel. The valid values are as follows:
direction
X'00' Not applicable (PVC logical channel).
X'01' Only incoming calls are allowed on this logical channel.
X'02' Only outgoing calls are allowed on this logical channel.
X'03' Both incoming and outgoing calls are allowed on this logical channel.

X.25 Specific Data–Format 02

Figure 12-8 (Page 1 of 4). X.25 Specific Data–Format 02

Field Type Description
Local network CHAR(1) Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the local network
address length address.
Local network CHAR(9) Specifies, in BCD, the local network address of this line.
address
Extended CHAR(1) Specifies whether network addressing is extended to permit the use of 17 digits in an address. The
network valid values are as follows:
addressing
X'01' Network addresses may be up to 15 digits
X'02' Network addresses may be up to 17 digits
Address CHAR(1) Specifies whether the system inserts the local network address in call request and call accept
insertion packets. The valid values are as follows:
'Y' The local network address is inserted in call request and call accept packets.
'N' The local network address is not inserted in call request and call accept packets.
Modulus CHAR(1) The X.25 modulus value. The valid values are as follows:
X'01' Modulus 8
X'02' Modulus 128
X.25 DCE CHAR(1) Specifies whether the system communicates using the integrated X.25 DCE support. This allows the
support system, acting as a DCE, to communicate with another system without going through an X.25
network. The valid values are as follows:
X'01' The system does not communicate using the X.25 DCE support
X'02' The system does communicate using the X.25 DCE support
X'03' The system negotiates whether it communicates using the X.25 DCE support.
Transmit BINARY(2) The transmit maximum packet size configured for this line.
maximum packet
size
Receive BINARY(2) The receive maximum packet size configured for this line.
maximum packet
size

12-10 AS/400 System API Reference V4R4

 Query Line Description (QOLQLIND) API

Figure 12-8 (Page 2 of 4). X.25 Specific Data–Format 02

Field Type Description
Transmit default BINARY(2) The transmit default packet size configured for this line.
packet size
Receive default BINARY(2) The receive default packet size configured for this line.
packet size
Transmit default BINARY(1) The transmit default window size configured for this line.
window size
Receive default BINARY(1) The receive default window size configured for this line.
window size
Number of BINARY(2) The number of logical channels configured for this line.
logical channels
Maximum frame BINARY(2) The maximum frame size configured in the line description. The valid values are as follows:
size
Ÿ 1024
Ÿ 2048
Ÿ 4096
ISDN interface CHAR(1) Indicates if the line uses an ISDN interface. The valid values are as follows:
X'00' X.25 line does not run over an ISDN interface.
X'01' X.25 line runs over an ISDN interface.
Note: The following section applies only if the ISDN interface is specified as X'01'. The sections of format 02 on the call direction field
to the offset to logical channel array field are not meaningful if an ISDN interface is not used and will return zeros in these fields if an
ISDN interface is not specified.
Call direction CHAR(1) The direction of the ISDN call. The valid values are as follows:
X'00' Incoming switched call
X'01' Outgoing switched call
X'02' Either a nonswitched call or not ISDN-capable.
Note: The following fields are only meaningful if the line description is switched.
Length of call ID BINARY(2) Length includes type and plan, as described below, and the call identify information element.
information

Chapter 12. User-Defined Communications Support APIs 12-11

Query Line Description (QOLQLIND) API

Figure 12-8 (Page 3 of 4). X.25 Specific Data–Format 02

Field Type Description
Type of number BINARY(1) Type and plan as represented by the following bit sequence: tttt pppp, where tttt equals the category
and numbering of the calling number and pppp equals the numbering plan identification used when the calling party
plan number was created.
Type '0000 xxxx'
Unknown number
Type '0001 xxxx'
International number
Type '0010 xxxx'
National number
Type '0011 xxxx'
Network specific number
Type '0100 xxxx'
Subscriber number
Type '0110 xxxx'
Abbreviated number
Type '0111 xxxx'
Reserved for extension
Plan 'xxxx 0000'
Unknown
Plan 'xxxx 0001'
ISDN/telephony numbering plan
Plan 'xxxx 0011'
Data numbering plan
Plan 'xxxx 0100'
Telex numbering plan
Plan 'xxxx 1000'
National standard numbering plan
Plan 'xxxx 1001'
Private numbering plan
Plan 'xxxx 1111'
Reserved for extension
Note: Refer to CCITT Recommendation Q.931 for more information.
Reserved BINARY(1) Reserved for extension.
Call ID digits CHAR(128) Calling party number of remote system received off the D-channel, specified in IA5 code (ASCII).
Length of sub- BINARY(2) Length includes type, odd-even indicator, and the subaddress information element. Values can range
address informa- from X'0001' to X'00FF'. The user specified subaddress is restricted to 20 bytes.
tion
Type of subad- BINARY(1) Type and odd-even indicator as represented by the following bit sequence: tttt ixxx, where tttt equals
dress and odd- the type of subaddress and i equals whether the address has an even or odd number of digits.
even indicator
Type '0000 xxxx'
NSAP
Type '0010 xxxx'
User specified
Type remaining
Reserved
Plan 'xxxx 0xxx'
Even number of address digits
Plan 'xxxx 1xxx'
Odd number of address digits
Note: Refer to CCITT Recommendation Q.931 for more information.
Reserved BINARY(1) Reserved for extension.
Subaddress CHAR(128) Calling party subaddress information, received from the D-channel, specified in the IA5 code set (a
superset of ASCII).
Offset to logical BINARY(2) Offset within this structure to the array of logical channels
channel array
Reserved CHAR(*) Reserved for extension
Note: The following 5 rows are repeated for each logical channel configured for this line. This section is not specific to ISDN interfaces.

12-12 AS/400 System API Reference V4R4

 Query Line Description (QOLQLIND) API

Figure 12-8 (Page 4 of 4). X.25 Specific Data–Format 02

Field Type Description
Logical channel CHAR(1) The logical channel group number. This together with the logical channel number makes up the
group number logical channel identifier.
Logical channel CHAR(1) The logical channel number. This together with the logical channel group number makes up the
number logical channel identifier.
Logical channel CHAR(1) The logical channel type. The valid values are as follows:
type
X'01' Switched virtual circuit (SVC).
X'02' Permanent virtual circuit (PVC) that is eligible for use by a network controller.
Note: This does not necessarily mean that this PVC is available for use. Another job
running on the network controller attached to this line may already have this PVC in
use.
Type of calls CHAR(1) Types of calls supported on the logical channel. The valid values are as follows:
allowed
X'00' Not applicable (PVC logical channel).
X'01' Only incoming calls are allowed on this logical channel.
X'02' Only outgoing calls are allowed on this logical channel.
X'03' Both incoming and outgoing calls are allowed on this logical channel.
Availability CHAR(1) Specifies whether the virtual circuit is available or currently is in use. The valid values are as follows:
X'00' Available
X'01' In use

Return and Reason Codes

Figure 12-9 (Page 1 of 2). Return and Reason Codes for the QOLQLIND API
Return /
Reason
Code Meaning Recovery
00/0000 Operation successful. Continue processing.
Notes:
1. When calling QOLQLIND (specifying an X.25 line
description, format 1, and not specifying group parame-
ters), up to 54 logical channels can be contained in the
user buffer because it is limited to a size of 256 bytes.
To increase the size of the user buffer so that it is suffi-
cient to contain all of the logical channels, the group
parameters should be used. To determine if there are
more than 54 logical channels configured, use the
Display Line Description (DSPLIND) command.
2. The application should check to ensure that the bytes
available value returned is less than or equal to the
bytes returned value. If so, there is additional informa-
tion that the application may want to receive. To
receive this information, the application must re-issue
the call, specifying the length user buffer equal to or
greater than the bytes available value.
81/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
83/1005 Format not valid. Correct the format parameter. Try the request again.
83/1014 Length user buffer value not valid. This value cannot be Correct the length user buffer value to a zero or a positive
negative. value less than 32K and try the operation again.
83/1020 Group parameters not valid. All parameters within the group must be specified. Correct
the parameter list and try the request again.
83/1021 Required parameter not specified. Format 2 was requested and the required group parameters
(length user buffer and bytes available) were not specified.
Correct the parameter list and try the request again.

Chapter 12. User-Defined Communications Support APIs 12-13

Receive Data (QOLRECV) API

Figure 12-9 (Page 2 of 2). Return and Reason Codes for the QOLQLIND API
Return /
Reason
Code Meaning Recovery
83/1998 User buffer parameter too small. Either the length user buffer value is negative or it contains
a positive value and the system was not able to put the
data into the user buffer provided by the application.
Correct the application and try the request again.
83/2000 Line description not configured for token-ring, Ethernet, Correct the line description parameter. Try the request
wireless, or X.25. again.
83/2002 Not authorized to line description. Get authorization to the line description. Try the request
again.
83/2006 Line description not found. Correct the line description parameter. Try the request
again.
83/2007 Line description damaged. Delete and re-create the line description. Try the request
again.

Error Messages tions line. See “X.25 SVC and PVC Input Operations” on
page 12-18 for more information on the types of data that
CPF3C90 E
can be received on links using an X.25 communications line.
Literal value cannot be changed.
CPF91F0 E Internal system error. Note: The QOLRECV API should only be called when the
CPF9872 E Program or service program &1 in library &2 user-defined communications support has data available to
ended. Reason code &3. be received. This is indicated either by an incoming-data
entry on the data queue or user queue, or by the data avail-
able parameter on the QOLRECV API.
Receive Data (QOLRECV) API
Required Parameter Group
Required Parameter Group: Return code
OUTPUT; BINARY(4)
1 Return code Output Binary(4)
The recovery action to take. See “Return and Reason
2 Reason code Output Binary(4)
Codes” on page 12-23.
3 Existing user connection Output Binary(4)
end point ID Reason code
4 New provider connection Output Binary(4)
OUTPUT; BINARY(4)
end point ID
5 Operation Output Char(2) The error that occurred. See “Return and Reason
6 Number of data units Output Binary(4) Codes” on page 12-23.
7 Data available Output Char(1)
8 Diagnostic data Output Char(40) Existing user connection end point ID
9 Communications handle Input Char(10) OUTPUT; BINARY(4)

Threadsafe: No The user connection end point (UCEP) ID that the data
was received on. For links using a token-ring, Ethernet,
wireless, or FDDI communications line, the content of
The Receive Data (QOLRECV) API performs an input opera- this parameter will always be 1.
tion on a link that is currently enabled in the job in which the
For links using an X.25 communications line, the content
application program is running. The type of data received is
of this parameter is only valid when the operation
returned in the operation parameter. The data itself, is
parameter is X'0001', X'B001', X'B101', X'B301', or
returned in the input buffer that was created when the link
X'BF01'. It will contain the UCEP ID that was provided
was enabled. For X'0001' operations, a description of that
in the new user connection end point ID parameter on
data is also be returned in the input buffer descriptor that is
the call to the QOLSEND API with operation X'B000' or
created when the link was enabled.
X'B400'.
The QOLRECV API can receive different types of data Note: If an incoming X.25 SVC call is rejected by the
depending on the type of communications line the link is user-defined communications application program by
using. See “LAN Input Operations” on page 12-16 for more calling the QOLSEND API with operation X'B100', the
information on the types of data that can be received on links content of this parameter will be set to zero when notifi-
using a token-ring, Ethernet, wireless, or FDDI communica-

12-14 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

cation of the completion of the X'B100' operation is data. Any value between 1 and the number of data
received from the QOLRECV API (operation X'B101'). units created in the input buffer may be returned when
the operation parameter is X'0001'. Otherwise, any
New provider connection end point ID
value between 0 and 1 may be returned.
OUTPUT; BINARY(4)
Note: The number of data units created in the input
The provider connection end point (PCEP) ID for the
buffer was returned in the data units created parameter
connection that is to be established. This identifier must
on the call to the QOLELINK API. See “Enable Link
be used on all subsequent calls to the QOLSEND API
(QOLELINK) API” on page 12-2 for more information.
for this connection.
Data available
The content of this parameter is only valid for links using
OUTPUT; CHAR(1)
an X.25 communications line and when the operation
parameter is X'B201'. Specifies whether more data is available for the user-
defined communications application program to receive.
Operation
The valid values are as follows:
OUTPUT; CHAR(2)
The type of data received by the application program.
X'00' No more data is available for the user-
defined communications application
With the exception of X'0001', all values are only valid
program to receive.
for links using an X.25 communications line. The valid
values are as follows:
X'01' More data is available for the user-
defined communications application
X'0001' User data. program to receive. The QOLRECV API
X'B001' Completion of the X'B000' output opera- must be called again prior to any other
tion. operations.
X'B101' Completion of the X'B100' output opera-
Note: An incoming-data entry will be sent to the data
tion.
queue or user queue only when the content of this
X'B111' Completion of the X'B110' output opera-
parameter is X'00' and then more data is subsequently
tion.
available to be received. See “Incoming-Data Entry” on
Cleanup of all connections complete. No
page 11-3 for more information.
data is associated with this operation.
X'B201' Incoming X.25 switched virtual circuit Diagnostic data
(SVC) call. OUTPUT; CHAR(40)
X'B301' Connection failure or reset indication
Specifies additional diagnostic data. See “Format of
received.
Diagnostic Data Parameter” for more information.
X'B311' Connection failure applying to all con-
nections for this link. The content of this parameter is only valid when the
operation parameter is X'B001', X'B101', X'B301',
This operation is only received when the
X'B311', or X'BF01'.
extended operations parameter for the
QOLELINK API is set to operations sup- Communications handle
ported. INPUT; CHAR(10)
X'BF01' Completion of the reset (X'BF00') output
The name of the link on which to receive the data.
operation.

Note: The special value of X'0000' will be returned in

the operation parameter to indicate no data was
Format of Diagnostic Data Parameter
received from the QOLRECV API. See “Return and The format of the diagnostic data parameter is shown below.
Reason Codes” on page 12-23 for more information. The contents of the fields within this parameter are only valid
Number of data units on X'B001', X'B101', X'B301', X'B311', and X'BF01'
OUTPUT; BINARY(4) operations for the indicated return and reason codes.

The number of data units in the input buffer that contain

Figure 12-10 (Page 1 of 2). Diagnostic Data Parameter

Field Type Description
Reserved CHAR(2) Reserved for extension.
Error code CHAR(4) Specifies hexadecimal diagnostic information that can be used to determine recovery actions. See “Error
Codes” on page 13-9 for more information.
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes.

Chapter 12. User-Defined Communications Support APIs 12-15

Receive Data (QOLRECV) API

Figure 12-10 (Page 2 of 2). Diagnostic Data Parameter

Field Type Description
Time CHAR(8) The time the error occurred.
stamp
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes.
Error log CHAR(4) The hexadecimal identifier that can be used for locating error information in the error log.
identifier
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes.
Reserved CHAR(10) Reserved for extension.
Indicators CHAR(1) The indicators that the user-defined communications application program can use to diagnose a potential
error condition. This is a bit-sensitive field.
The valid values for bit 0 (leftmost bit) are as follows:
'0'B Either there is no message in the QSYSOPR message queue, or there is a message and it
does not have the capability to run problem analysis report (PAR) to determine the cause of
the error.
'1'B There is a message in the QSYSOPR message queue for this error, and it does have the
capability to run problem analysis report (PAR) to determine the cause of the error.
The valid values for bit 1 are as follows:
'0'B The line error can be retried.
'1'B The line error is not able to be restarted.
The valid values for bit 2 are as follows:
'0'B The cause and diagnostic codes fields are not valid.
'1'B The cause and diagnostic codes fields are valid.
The valid values for bit 3 are as follows:
'0'B The error has not been reported to the system operator message queue.
'1'B The error has been reported to the system operator message queue.
The valid values for bit 4 are as follows:
'0'B A reset request packet was transmitted on the network
'1'B A reset confirmation packet was transmitted on the network instead of a reset request packet.
The content of bit 4 is only valid for operation X'BF01' with 00/0000 return/reason codes.
The content of the indicators field is only valid for 83/4001, 83/4002, and 83/3202 return/reason codes, and
00/0000 return/reason codes for operation X'BF01'.
X.25 CHAR(1) Specifies additional information on the condition reported. See the X.25 Network Support book for inter-
cause preting the values of this field.
code
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes.
X.25 diag- CHAR(1) Specifies additional information on the condition reported. See the X.25 Network Support book for inter-
nostic preting the values of this field.
code
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes.
Reserved CHAR(1) Reserved for extension.
Error BINARY(4) The offset from the top of the input buffer to the incorrect data in the input buffer.
offset
The content of this field is only valid for a 83/1999 return/reason code.
Reserved CHAR(4) Reserved for extension.

LAN Input Operations Ÿ Total length of the data unit. This information is reported
in the corresponding input buffer descriptor element.
The only type of data that an application program can
receive from the QOLRECV API on links using a token-ring, For example, suppose two data frames came in from the
Ethernet, wireless, or FDDI communications line is user data network and the user-defined communications application
(operation X'0001'). User-defined communications support program was notified of this by an incoming-data entry on the
returns the following information for each data frame received data queue or user queue. On return from the QOLRECV
from the QOLRECV API: API, the information for the first frame would be in the first
data unit of the input buffer and described in the first element
Ÿ One or more data units. The first data unit contains a
of the input buffer descriptor. The information for the second
general LAN header, routing information if a token ring is
frame would be in the second data unit of the input buffer
used, and user data.
and described in the second element of the input buffer

12-16 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

descriptor. The number of data units parameter would be set some of them are link specific. For example, routing infor-
to 2. mation is only for token-ring links, and the length of routing
information is X'00' to X'18'. For non-token-ring links, the
Data Unit Format–LAN Operation X'0001': Each data length of the routing information is always X'00'. Also,
frame received from the QOLRECV API corresponds to a DSAP and SSAP are defined for protocols that use the 802.2
data unit in the input buffer. The information in each of these logical link control interface and do not apply to Ethernet
data units is made up of a general LAN header, routing infor- Version 2. A DSAP and SSAP of X'00' tells the commu-
mation (for token-ring links only), followed by user data. nications support that the data frame is an Ethernet Version
2 frame.
The general LAN header is used to pass information about
the frame to the communications support. The fields in the The general LAN header is described in Figure 12-11.
general LAN header are used for all LAN link types, although

Figure 12-11. Format of the General LAN Information

Field Type Description
Length of BINARY(2) The length of the general LAN information in the data unit, including this field. This field is always set
general LAN to 16.
information
Sending CHAR(6) Specifies, in packed form, the adapter address from which this frame was sent. The possible values
adapter returned in this field depend on the filters activated for this link. See “Set Filter (QOLSETF) API” on
address page 12-43 for more information.
Note: Because user-defined communications support only allows connectionless service over LANs,
all frames received on a single call to the QOLRECV API may not have the same source adapter
address.
DSAP address CHAR(1) The service access point on which the AS/400 system received this frame. The possible values
returned in this field depend on the filters activated for this link. See “Set Filter (QOLSETF) API” on
page 12-43 for more information.
Note: The Ethernet Version 2 standard does not define a DSAP address in an Ethernet Version 2
frame. Therefore, when receiving Ethernet Version 2 frames, the DSAP address will be null (X'00').
SSAP address CHAR(1) The service access point on which the source system sent this frame. The possible values returned
in this field depend on the filters activated for this link. See “Set Filter (QOLSETF) API” on
page 12-43 for more information.
Note: The Ethernet Version 2 standard does not define a SSAP address in an Ethernet Version 2
frame. Therefore, when receiving Ethernet Version 2 frames, the SSAP address will be null (X'00').
Reserved CHAR(2) Reserved for extension.
Length of BINARY(2) The length of the routing information in the data unit. For links using a token-ring communications
token-ring line, any value between 0 and 18 may be returned, where 0 indicates that there is no routing informa-
routing informa- tion.
tion
For links using an Ethernet, wireless, or FDDI communications line, the content of this field is not
applicable and will be set to 0 indicating that there is no routing information.
Length of user BINARY(2) The length of the user data in the data unit. This will be less than or equal to the maximum frame
data size allowed on the service access point returned in the DSAP address field. See “Query Line
Description (QOLQLIND) API” on page 12-5 to determine the maximum frame size allowed on the
service access point returned in the DSAP address field.
For Ethernet Version 2 frames, this will be at least 48 and not more than 1502 (including 2 bytes for
the Ethernet type field).
Note: Ethernet 802.3 frames will be padded when the user data is less than 46 bytes.

Token-ring routing information follows the general LAN Token-Ring Frames with No Routing Information
header. The length of this field is specified by the length of
token-ring routing information field found in the general LAN ┌──────────────────────┬──────────────────┐
│ General │ User │
header. If the length of the routing information is nonzero, │ LAN │ Data │
the user data follows the routing information header. │ Header │ │
└──────────────────────┴──────────────────┘
Figure 12-12 shows the fields and offsets used for Ethernet ð 16
802.3, wireless, and token-ring frames without routing infor-
mation. Figure 12-12. Ethernet 802.3, Wireless, and

Chapter 12. User-Defined Communications Support APIs 12-17

Receive Data (QOLRECV) API

The length of the user data is described in the length of user

Figure 12-15. Format of an Element in the Input Buffer
data field in the general LAN header. For Ethernet Version 2 Descriptor
frames, the first 2 bytes of user data are used for the frame
Field Type Description
type. The type field is a 2-byte field that specifies the upper
layer protocol of the frame. Length BINARY(2) The number of bytes of information
in the corresponding data unit of
The adapter address, DSAP, SSAP, and frame type fields the input buffer. This will be equal
are all used to define inbound routing information used by to the length of the general LAN
the QOLSETF API. Refer to “Set Filter (QOLSETF) API” on information with the length of the
routing information and the length
page 12-43 for information on the QOLSETF API and how
of the user data. See
inbound routing information is used to route inbound data to Figure 12-11 for general LAN infor-
the application program. mation fields and descriptions.
Note: Inbound routing information is not related to the Reserved CHAR(30) Reserved for extension.
token-ring routing information described in the general LAN
header.
X.25 SVC and PVC Input Operations
Figure 12-13 shows the fields and offsets used for token-ring
frames with routing information. Figure 12-16 shows the types of data that can be received
from the QOLRECV API on links using an X.25 communica-
┌──────────────────┬──────────────┬─────────┐
│ General │ Routing │ User │ tions line.
│ LAN │ Information │ Data │
│ Header │ │ │ Figure 12-16. X.25 SVC and PVC Input Operations
└──────────────────┴──────────────┴─────────┘
ð 16 16 + Length Operation Meaning
of Routing X'0001' User data (SVC or PVC).
Information
X'B001' Completion of the X'B000' output operation
Figure 12-13. Token-Ring Frames with Routing Information (SVC or PVC).

Figure 12-14 shows the fields and offsets used for Ethernet X'B101' Completion of the X'B100' output operation
(SVC or PVC).
Version 2 frames.
X'B201' Incoming X.25 call (SVC).
Note: For Ethernet Version 2, the frame type field is the first
2 bytes of user data, following the general LAN information, X'B301' Connection failure or reset indication (SVC or
with user data starting at offset 18. PVC).
X'B311' Connection failure applying to all connections for
this link.
┌──────────────────────┐
│ User Data │ X'BF01' Completion of the X'BF00' output operation
' 6 (SVC or PVC).
┌──────────────────┬────────┬─────────────┐
│ General │ Frame │ │
│ LAN │ Type │ Data │ X.25 Operation X'0001': This operation indicates that
│ Header │ │ │ user data was received on an X.25 SVC or PVC connection.
└──────────────────┴────────┴─────────────┘ User-defined communications support will return the following
ð 16 18 information:
Ÿ User data in the next data unit of the input buffer,
Figure 12-14. Ethernet Version 2 Frames
starting with the first data unit
Input Buffer Descriptor Element Format–LAN Oper- Ÿ A description, in the corresponding element of the input
ation X'0001': The information returned in each data unit buffer descriptor, of the user data in that data unit
of the input buffer will be described in the corresponding
element of the input buffer descriptor. For example, suppose two data units of user data came in
from the network and the application program was notified of
Figure 12-15 shows the format of each element in the input this by an incoming-data entry on the data queue or user
buffer descriptor. queue. On return from the QOLRECV API, the first portion
of the user data would be in the first data unit of the input
buffer and described in the first element of the input buffer
descriptor. The second portion of the user data would be in
the second data unit of the input buffer and described in the
second element of the input buffer descriptor. The number
of data units parameter would be set to 2.

12-18 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

User-defined communications support will automatically reas- Data Unit Format–X.25 Operation X'0001': Each data unit
semble the X.25 data packet(s) from a complete packet in the input buffer consists solely of user data and starts
sequence into the next data unit of the input buffer. If the offset 0 from the top of the data unit.
amount of user data in a complete packet sequence is more
than what can fit into a data unit, the more data indicator Input Buffer Descriptor Element Format–X.25 Operation
field in the corresponding element of the input buffer X'0001': The user data returned in each data unit of the
descriptor will be set to X'01' and the next data unit will be input buffer will be described in the corresponding element of
used for the remaining user data, and so on. the input buffer descriptor.

Figure 12-17 shows the format of each element in the input

buffer descriptor.

Figure 12-17. Format of an Element in the Input Buffer Descriptor

Field Type Description
Length BINARY(2) The number of bytes of user data in the corresponding data unit of the input buffer. This will always
be less than or equal to the X.25 user data size parameter that was specified on the call to the
QOLELINK API when the link was enabled. See “Enable Link (QOLELINK) API” on page 12-2 for
more information.
Note: The maximum amount of user data in a data unit of the input buffer may be further limited by
the maximum data unit assembly size for a connection. See “Send Data (QOLSEND) API” on
page 12-27 for more information.
More data indi- CHAR(1) Specifies whether the remaining amount of user data from a complete X.25 packet sequence is more
cator than can fit into the corresponding data unit. The valid values are as follows:
X'00' The remaining amount of user data from a complete X.25 packet sequence fit into the
corresponding data unit.
X'01' The remaining amount of user data from a complete X.25 packet sequence could not
all fit into the corresponding data unit. The next data unit will be used.
Qualified data CHAR(1) Specifies whether the X.25 qualifier bit (Q-bit) was set on or off in all X.25 packets reassembled into
indicator the corresponding data unit. The valid values are as follows:
X'00' The Q-bit was set off in all X.25 packets reassembled into the corresponding data unit.
X'01' The Q-bit was set on in all X.25 packets reassembled into the corresponding data unit.
Interrupt packet CHAR(1) Specifies whether the user data in the corresponding data unit was received in an X.25 interrupt
indicator packet. The valid values are as follows:
X'00' The user data in the corresponding data unit was received in one or more data
packets.
X'01' The user data in the corresponding data unit was received in an X.25 interrupt packet.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) was set on or off in all X.25 packets reas-
mation indicator sembled into the corresponding data unit. The valid values are as follows:
X'00' The D-bit was set off in all X.25 packets reassembled into the corresponding data unit.
X'01' The D-bit was set on in all X.25 packets reassembled into the corresponding data unit.
Note: A packet-level confirmation is sent by the input/output processor (IOP) when a
packet is received with the X.25 D-bit set on.
Reserved CHAR(26) Reserved for extension.

X.25 Operation X'B001': This operation indicates that a The format of the data returned in the input buffer for the
X'B000' output operation has completed. User-defined X'B001' operation depends on whether the X'B000' output
communications support will return the data for this operation operation was used to initiate an SVC call or to open a PVC
(if any) in the first data unit of the input buffer. The input connection. Each format will be explained below.
buffer descriptor is not used. Note: The formats below only apply to 0/0 and 83/4002
return and reason codes. When the X'B001' operation is
Data will be returned in the input buffer for the following
received with a 83/1999 return and reason code, the data
return and reason codes:
returned starts at offset 0 from the top of the first data unit in
Ÿ 0/0 the input buffer and contains the data specified in the output
Ÿ 83/1999 buffer on the X'B000' output operation. See “Send Data
(QOLSEND) API” on page 12-27 for more information.
Ÿ 83/4002 (only when the number of data units parameter
is set to one)

Chapter 12. User-Defined Communications Support APIs 12-19

Receive Data (QOLRECV) API

Data Unit Format–X.25 Operation X'B001' (Completion of Figure 12-18 shows the format of the data returned for the
SVC Call): The data returned starts at offset 0 from the top X'B001' operation.
of the first data unit in the input buffer.

Figure 12-18. Format of Data for X'B001' Operation (Completion of SVC Call)
Field Type Description
Reserved CHAR(2) Reserved for extension.
Logical CHAR(2) The logical channel identifier assigned to the SVC connection.1
channel identi-
fier
Transmit BINARY(2) The negotiated transmit packet size for this connection.1
packet size
Transmit BINARY(2) The negotiated transmit window size for this connection.1
window size
Receive BINARY(2) The negotiated receive packet size for this connection.1
packet size
Receive BINARY(2) The negotiated receive window size for this connection.1
window size
Reserved CHAR(32) Reserved for extension.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) was set on or off in the call connected
mation support packet. This also specifies the D-bit support for this connection.1 The valid values are as follows:
X'00' The D-bit was set off in the call connected packet. D-bit will be supported for sending
data but not for receiving data.
Note: When this value is returned and an X.25 packet is received with the D-bit set on,
the input/output processor (IOP) will send a reset packet.
X'01' The D-bit was set on in the call connected packet. D-bit will be supported for sending
data and for receiving data.
Reserved CHAR(11) Reserved for extension.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be
length returned.
X.25 facilities CHAR(109) The X.25 facilities data.
Reserved CHAR(48) Reserved for extension.
Call/clear user BINARY(2) The number of bytes of data in the call/clear user data field. Any value between 0 and 128 may be
data length returned.
Call/clear user CHAR(128) For a 0/0 return and reason code, this specifies the call user data. For an 83/4002 return and reason
data code, this specifies the clear user data.
Reserved CHAR(168) Reserved for extension.
1 The content of this field is only valid for a 0/0 return and reason code.

Data Unit Format–X.25 Operation X'B001' (Completion of Figure 12-19 shows the format of the data returned for the
Open PVC): The data returned starts at offset 0 from the X'B001' operation.
top of the first data unit in the input buffer.

Figure 12-19 (Page 1 of 2). Format of Data for X'B001' Operation (Completion of Open PVC)
Field Type Description
Reserved CHAR(4) Reserved for extension.
Transmit packet BINARY(2) The negotiated transmit packet size for this connection.
size
Note: This will be the same as the requested transmit packet size specified on the X'B000' output
operation.
Transmit BINARY(2) The negotiated transmit window size for this connection.
window size
Note: This will be the same as the requested transmit window size specified on the X'B000' output
operation.

12-20 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

Figure 12-19 (Page 2 of 2). Format of Data for X'B001' Operation (Completion of Open PVC)
Field Type Description
Receive packet BINARY(2) The negotiated receive packet size for this connection.
size
Note: This will be the same as the requested receive packet size specified on the X'B000' output
operation.
Receive window BINARY(2) The negotiated receive window size for this connection.
size
Note: This will be the same as the requested receive window size specified on the X'B000' output
operation.
Reserved CHAR(500) Reserved for extension.

X.25 Operation X'B101': This operation indicates that a Note: The format below only applies for a 0/0 return and
X'B100' output operation has completed. User-defined reason code. When the X'B101' operation is received with
communications support will return the data for this operation an 83/1999 return and reason code, the data returned starts
(if any) in the first data unit of the input buffer. The input at offset 0 from the top of the first data unit in the input buffer
buffer descriptor is not used. and contains the data specified in the output buffer on the
X'B100' output operation. See “Send Data (QOLSEND)
Data will be returned in the input buffer for the following API” on page 12-27 for more information.
return and reason codes:
Data Unit Format–X.25 Operation X'B101': The data
Ÿ 0/0 (only when the number of data units parameter is set
returned starts at offset 0 from the top of the first data unit in
to one)
the input buffer.
Ÿ 83/1999
Figure 12-20 shows the format of the data returned for the
X'B101' operation.

Figure 12-20. Format of Data for X'B101' Operation

Field Type Description
Clear type CHAR(2) The type of clear user data returned. The valid values are as follows:
X'0001' Clear confirmation data included.
X'0002' Clear indication data included.
Cause code CHAR(1) The X.25 cause code.
Diagnostic CHAR(1) The X.25 diagnostic code.
code
Reserved CHAR(4) Reserved for extension.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be
length returned.
X.25 facilities CHAR(109) The X.25 facilities data.
Reserved CHAR(48) Reserved for extension.
Clear user data BINARY(2) The number of bytes of data in the clear user data field. Any value between 0 and 128 may be
length returned.
Clear user data CHAR(128) The clear user data.
Reserved CHAR(216) Reserved for extension.

X.25 Operation X'B111': This operation indicates a X.25 Operation X'B201': This operation indicates that an
X'B110' output operation has completed. All connections incoming X.25 SVC call was received. User-defined commu-
have been closed and the clean up of connection control nications support returns the data for this operation in the
information is complete. All UCEPs and PCEPs are freed. first data unit of the input buffer. The input buffer descriptor
There is no data associated with this operation. is not used.
Note: It is the responsibility of the application program to
either accept or reject the incoming call. This is done by
calling the QOLSEND API with operation X'B400' or
X'B100', respectively.

Chapter 12. User-Defined Communications Support APIs 12-21

Receive Data (QOLRECV) API

Data Unit Format–X.25 Operation X'B201': The data Figure 12-21 shows the format of the data returned for the
returned starts at offset 0 from the top of the first data unit in X'B201' operation.
the input buffer.

Figure 12-21. Format of Data for X'B201' Operation

Field Type Description
Reserved CHAR(2) Reserved for extension.
Logical channel CHAR(2) The logical channel identifier assigned to the incoming SVC call.
identifier
Transmit packet BINARY(2) The requested transmit packet size for this connection.
size
Transmit BINARY(2) The requested transmit window size for this connection.
window size
Receive packet BINARY(2) The requested receive packet size for this connection.
size
Receive window BINARY(2) The requested receive window size for this connection.
size
Reserved CHAR(7) Reserved for extension.
Calling DTE BINARY(1) The number of binary coded decimal (BCD) digits in the calling DTE address.
address length
Calling DTE CHAR(16) Specifies, in binary coded decimal (BCD), the calling DTE address. The address will be left justified
address and padded on the right with BCD zeros.
Reserved CHAR(8) Reserved for extension.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) was set on or off in the incoming call
mation support packet. The valid values are as follows:
X'00' The D-bit was set off in the incoming call packet.
X'01' The D-bit was set on in the incoming call packet.
Reserved CHAR(9) Reserved for extension.
Reverse CHAR(1) Specifies reverse charging options. The valid values are as follows:
charging indi-
X'00' Reverse charging not requested.
cator
X'01' Reverse charging requested.
Fast select indi- CHAR(1) Specifies fast select options. The valid values are as follows:
cator
X'00' Fast select not requested.
X'01' Fast select with restriction requested.
X'02' Fast select without restriction requested.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be
length returned.
X.25 facilities CHAR(109) The X.25 facilities data.
Reserved CHAR(48) Reserved for extension.
Call user data BINARY(2) The number of bytes of data in the call user data field. Any value between 0 and 128 may be
length returned.
Call user data CHAR(128) The call user data.
Note: The AS/400 system treats the first byte of call user data as the protocol identifier (PID).
Called DTE BINARY(1) The number of binary coded decimal (BCD) digits in the called DTE address.
address length
Called DTE CHAR(16) Specifies, in binary coded decimal (BCD), the called DTE address. The address will be left-justified
address and padded on the right with BCD zeros.
Reserved CHAR(111) Reserved for extension.

12-22 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

X.25 Operation X'B301': This operation indicates that a Note: The diagnostic data parameter will contain the X.25
failure has occurred, or a reset indication has been received, cause and diagnostic codes when a reset indication is
on an X.25 SVC or PVC connection. User-defined commu- received.
nications support will return data for this operation in the first
data unit of the input buffer only on a 83/4002 return and Data Unit Format–X.25 Operation X'B301': The data
reason code when the number of data units parameter is set returned starts at offset 0 from the top of the first data unit in
to one. The input buffer descriptor is not used. the input buffer.

Figure 12-22 shows the format of the data returned for the
X'B301' operation.

Figure 12-22. Format of Data for X'B301' Operation

Field Type Description
Reserved CHAR(8) Reserved for extension.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be returned.
length
X.25 facilities CHAR(109) The X.25 facilities data.
Reserved CHAR(48) Reserved for extension.
Clear user BINARY(2) The number of bytes of data in the clear user data field. Any value between 0 and 128 may be
data length returned.
Clear user CHAR(128) The clear user data.
data
Reserved CHAR(216) Reserved for extension.

X.25 Operation X'B311': This operation indicates that an Return and Reason Codes
error has occurred that has caused the system to close all
connections on the link. The error may be a system error or The return and reason codes that can be returned from the
a network error. The error information is returned in the QOLRECV API depend on the type of communications line
diagnostic data and no additional data is provided. the link is using and on the type of data (operation) that was
received.
Note: This operation is only received when the extended
operation parameter on the QOLELINK API is set to opera- LAN Return and Reason Codes
tion supported. If the extended operations are not supported
and an error occurs that will close all connections, X'B301' Return and Reason Codes Indicating No Data Received:
is received for each connection. Figure 12-23 shows the return and reason codes that indi-
cate data could not be received from the QOLRECV API.
X.25 Operation X'BF01': This operation indicates that a
X'BF00' output operation has been completed. Neither the Note: When these return and reason codes are returned, all
input buffer nor the input buffer descriptor is used for this output parameters except the return and reason codes will
operation. contain hexadecimal zeros.

Note: When the X'BF01' operation is received with a 0/0

return and reason code, the diagnostic data parameter will
contain information indicating if a reset request or reset con-
firmation packet was sent.

Figure 12-23 (Page 1 of 2). Return and Reason Codes Indicating No Data Received
Return /
Reason
Code Meaning Recovery
0/3203 No data available to be received. Ensure that user-defined communications support has data
available to be received before calling the QOLRECV API.
Try the request again.
80/2200 Queue error detected. Escape message CPF91F1 will be Ensure the link is disabled and see messages in the job log
sent to the application program when this return and reason for further information. Correct the error, enable the link,
code is received. and try the request again.

Chapter 12. User-Defined Communications Support APIs 12-23

Receive Data (QOLRECV) API

Figure 12-23 (Page 2 of 2). Return and Reason Codes Indicating No Data Received
Return /
Reason
Code Meaning Recovery
80/2401 Input buffer or input buffer descriptor error detected. Ensure the link is disabled and see messages in the job log
Escape message CPF91F1 will be sent to the application for further information. Correct the error, enable the link,
program when this return and reason code is received. and try the request again.
80/3002 A previous error occurred on this link that was reported to Ensure the link is disabled and see messages in the job log
the application program by escape message CPF91F0 or for further information. If escape message CPF91F0 was
CPF91F1. However, the application program has attempted sent to the application program, then report the problem
another operation. using the ANZPRB command. Otherwise, correct the error,
enable the link, and try the request again.
80/4000 Error recovery has been canceled for this link. Ensure the link is disabled and see messages in the job log
for further information. Correct the condition, enable the
link, and try the request again.
80/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
83/3001 Link not enabled. Correct the communications handle parameter. Try the
request again.
83/3004 Link is enabling. Wait for the enable-complete entry to be sent to the data
queue or user queue. If the link was successfully enabled,
try the request again.

Return and Reason Codes for LAN Operation X'0001'

Figure 12-24. Return and Reason Codes for LAN Operation X'0001'.
Return /
Reason
Code Meaning Recovery
0/0 User data received successfully. Continue processing.

X.25 Return and Reason Codes Note: When these return and reason codes are returned, all
output parameters except the return and reason codes will
Return and Reason Codes Indicating No Data Received: contain hexadecimal zeros.
Figure 12-25 shows the return and reason codes that indi-
cate data could not be received from the QOLRECV API.

Figure 12-25 (Page 1 of 2). Return and Reason Codes Indicating No Data Received
Return /
Reason
Code Meaning Recovery
0/3203 No data available to be received. Ensure that user-defined communications support has data
available to be received before calling the QOLRECV API.
Try the request again.
80/2200 Queue error detected. Escape message CPF91F1 will be Ensure the link is disabled and see messages in the job log
sent to the application program when this return and reason for further information. Correct the error, enable the link,
code is received. and try the request again.
80/2401 Input buffer or input buffer descriptor error detected. Ensure the link is disabled and see messages in the job log
Escape message CPF91F1 will be sent to the application for further information. Correct the error, enable the link,
program when this return and reason code is received. and try the request again.
80/3002 A previous error occurred on this link that was reported to Ensure the link is disabled and see messages in the job log
the application program by escape message CPF91F0 or for further information. If escape message CPF91F0 was
CPF91F1. However, the application program has attempted sent to the application program, then report the problem
another operation. using the ANZPRB command. Otherwise, correct the error,
enable the link, and try the request again.

12-24 AS/400 System API Reference V4R4

 Receive Data (QOLRECV) API

Figure 12-25 (Page 2 of 2). Return and Reason Codes Indicating No Data Received
Return /
Reason
Code Meaning Recovery
80/4000 Error recovery has been canceled for this link. Ensure the link is disabled and see messages in the job log
for further information. Correct the condition, enable the
link, and try the request again.
80/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
83/3001 Link not enabled. Correct the communications handle parameter. Try the
request again.
83/3004 Link is enabling. Wait for the enable-complete entry to be sent to the data
queue or user queue. If the link was successfully enabled,
try the request again.

Return and Reason Codes for X.25 Operation X'0001'

Figure 12-26. Return and Reason Codes for X.25 Operation X'0001'
Return /
Reason
Code Meaning Recovery
0/0 User data received successfully. Continue processing.

Return and Reason Codes for X.25 Operation X'B001'

Figure 12-27. Return and Reason Codes for X.25 Operation X'B001'
Return /
Reason
Code Meaning Recovery
0/0 The X'B000' output operation was successful. Continue processing.
83/1999 Incorrect data was specified in output buffer when the Correct the incorrect data. Then, try the X'B000' output
X'B000' output operation was issued. operation again.
Note: The data specified in the output buffer will be copied
into the input buffer and the error offset field in the diag-
nostic data parameter will point to the incorrect data.
83/3204 Connection ending because a X'B100' output operation Wait for notification of the completion of the X'B100' output
was issued. operation from the QOLRECV API (X'B101' operation).
83/4001 Link failure, system starting error recovery for this link. The Wait for the link to recover. Then, try the X'B000' output
connection has ended. operation again.
83/4002 Connection failure. The connection has ended. The diag- Correct any errors and try the X'B000' output operation
nostic data parameter will contain more information on this again.
error.
83/4005 All SVC channels are currently in use, or the requested Wait for a virtual circuit to become available. Then, try the
PVC channel is already in use. X'B000' output operation again.

Return and Reason Codes for X.25 Operation X'B101'

Figure 12-28 (Page 1 of 2). Return and Reason Codes for X.25 Operation X'B101'
Return /
Reason
Code Meaning Recovery
0/0 The X'B100' output operation was successful. The con- Continue processing.
nection has ended.

Chapter 12. User-Defined Communications Support APIs 12-25

Receive Data (QOLRECV) API

Figure 12-28 (Page 2 of 2). Return and Reason Codes for X.25 Operation X'B101'
Return /
Reason
Code Meaning Recovery
83/1007 Connection identifier not valid because connection has Continue processing.
already ended.
83/1999 Incorrect data was specified in output buffer when the Correct the incorrect data. Then, try the X'B100' output
X'B100' output operation was issued. operation again.
Note: The data specified in the output buffer will be copied
into the input buffer and the error offset field in the diag-
nostic data parameter will point to the incorrect data.

Return and Reason Codes for X.25 Operation X'B111'

Figure 12-29. Return and Reason Codes for X.25 Operation X'B111'
Return /
Reason
Code Meaning Recovery
0/0 The X'B100' output operation was successful. The con- Continue processing.
nection has ended.
83/1007 Connection identifier not valid because connection has Continue processing.
already ended.
83/3205 The X'B110' operation is rejected because the application Correct the application.
has not received the X'B311' operation prior to requesting
the X'B110' operation.

Return and Reason Codes for X.25 Operation X'B201'

Figure 12-30. Return and Reason Codes for X.25 Operation X'B201'
Return /
Reason
Code Meaning Recovery
0/0 Incoming X.25 SVC call received successfully. Continue processing.

Return and Reason Codes for X.25 Operation X'B301'

Figure 12-31. Return and Reason Codes for X.25 Operation X'B301'
Return /
Reason
Code Meaning Recovery
83/3201 The maximum amount of incoming user data that can be Issue the X'B100' output operation to end the connection.
held by user-defined communications support for the appli-
cation program on this connection has been exceeded.
83/3202 A reset indication has been received on this connection. Issue the X'BF00' output operation to send a reset confir-
The X.25 cause and diagnostic code fields in the diagnostic mation packet.
data parameter will contain the cause and diagnostic codes
of the reset indication.
83/4001 Link failure, system starting error recovery for this link. Issue the X'B100' output operation to end the connection.
83/4002 Connection failure. The diagnostic data parameter will Issue the X'B100' output operation to end the connection.
contain more information on this error.

Return and Reason Codes for X.25 Operation X'B311'

12-26 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Figure 12-32. Return and Reason Codes for X.25 Operation X'B311'
Return /
Reason
Code Meaning Recovery
83/4001 Link failure, system starting error recovery for this link. All Issue the X'B110' operation to free the connections.
connections that were active on this link are closed or
cleared.
83/4002 A network error has occurred that affects all connections on Issue the X'B110' operation to free the connections.
this link. All connections that were active on this link are
closed or cleared. The diagnostic data contains more infor-
mation on this error.

Return and Reason Codes for X.25 Operation X'BF01'

Figure 12-33. Return and Reason Codes for X.25 Operation X'BF01'
Return /
Reason
Code Meaning Recovery
0/0 The X'BF00' output operation was successful. The diag- Continue processing.
nostic data parameter will contain information indicating if a
reset request or reset confirmation packet was sent.
83/1006 Operation not valid. Do not issue the X'BF00' output operation on connections
that do not support resets.
83/3201 The maximum amount of incoming user data that can be Wait to receive a failure notification from the QOLRECV API
held by user-defined communications support for the appli- indicating this condition (X'B301' operation, 83/3201 return
cation program on this connection has been exceeded. and reason code). Then issue the X'B100' output opera-
tion to end the connection.
83/3204 Connection ending because a X'B100' output operation Wait for notification of the completion of the X'B100' output
was issued. operation from the QOLRECV API (X'B101' operation).
83/4001 Link failure, system starting error recovery for this link. Wait to receive a failure notification from the QOLRECV API
indicating this condition (X'B301' operation, 83/4001 return
and reason code). Then, issue the X'B100' output opera-
tion to end the connection.
83/4002 Connection failure. Wait to receive a failure notification from the QOLRECV API
indicating this condition (X'B301' operation, 83/4002 return
and reason code). Then, issue the X'B100' output opera-
tion to end the connection.

Error Messages
CPF3C90 E Required Parameter Group:
Literal value cannot be changed. 1 Return code Output Binary(4)
CPF91F0 E Internal system error. 2 Reason code Output Binary(4)
CPF91F1 E User-defined communications application error. 3 Diagnostic data Output Char(40)
CPF9872 E Program or service program &1 in library &2 4 New provider connection Output Binary(4)
ended. Reason code &3. end point ID
5 New user end point con- Input Binary(4)
nection ID
6 Existing provider connection Input Binary(4)
Send Data (QOLSEND) API end point ID
7 Communications handle Input Char(10)
8 Operation Input Char(2)
9 Number of data units Input Binary(4)

Threadsafe: No

The Send Data (QOLSEND) API performs output on a link

that is currently enabled in the job in which the application
program is running. The operation parameter allows you to

Chapter 12. User-Defined Communications Support APIs 12-27

Send Data (QOLSEND) API

specify the type of output operation to perform. The applica- Existing provider connection end point ID
tion program must provide the data associated with the INPUT; BINARY(4)
output operation in the output buffer that was created when
The PCEP ID for the connection on which this operation
the link was enabled. For X'0000' operations, the applica-
will be performed. For links using a token-ring, Ethernet,
tion program must also provide a description of that data in
or wireless communications line, the content of this
the output buffer descriptor that was created when the link
parameter must always be set to 1.
was enabled.
For links using an X.25 communications line, the content
The types of output operations that can be performed on a of this parameter is only valid when the operation
link depend on the type of communications line that the link parameter is set to X'0000', X'B100', X'B400', or
is using. See “LAN Output Operations” on page 12-30 for X'BF00'. It must contain the PCEP ID that was
more information on output operations that are supported on returned in the new provider connection end point ID
links using a token-ring, Ethernet, wireless, or FDDI commu- parameter from the call to the QOLSEND API with oper-
nications line. See “X.25 SVC and PVC Output Operations” ation X'B000', or the PCEP ID that was returned in the
on page 12-31 for more information on output operations new provider connection end point ID parameter from
that are supported on links using an X.25 communications the call to the QOLRECV API with operation X'B201'
line. (incoming call). See “Receive Data (QOLRECV) API” on
page 12-14 for more information on receiving X.25 calls.
Required Parameter Group Communications handle
INPUT; CHAR(10)
Return code
OUTPUT; BINARY(4) The name of the link on which to perform the output
operation.
The recovery action to take. See “Return and Reason
Codes” on page 12-40. Operation
INPUT; CHAR(2)
Reason code
OUTPUT; BINARY(4) The type of output operation to perform. With the
exception of X'0000', all values are only valid for links
The error that occurred. See “Return and Reason
using an X.25 communications line. The valid values
Codes” on page 12-40.
are as follows:
Diagnostic data
X'0000' Send data.
OUTPUT; CHAR(40)
X'B000' Send call request packet (SVC) or open
Additional diagnostic data. See “Diagnostic Data Param- PVC connection.
eter Format” on page 12-29 for more information. X'B100' Send clear packet (SVC) or close PVC
The content of this parameter is only valid when the connection.
operation parameter is set to X'0000' or X'B400'. X'B110' Initiate final cleanup of all connections
that were closed by the system.
New provider connection end point ID
This operation is only valid when the
OUTPUT; BINARY(4)
application receives an X'B311' opera-
The provider connection end point (PCEP) ID for the tion to receive connection failure data.
connection that is to be established. This identifier must X'B400' Send call accept packet (SVC).
be used on all subsequent calls to the QOLSEND API X'BF00' Send reset request packet or reset confir-
for this connection. mation packet (SVC or PVC).
The content of this parameter is only valid for links using Number of data units
an X.25 communications line and when the operation INPUT; BINARY(4)
parameter is set to X'B000'.
The number of data units in the output buffer that
New user connection end point ID contain data. Any value between 1 and the number of
INPUT; BINARY(4) data units created in the output buffer may be used.
The user connection end point (UCEP) ID for the con- The content of this parameter is only valid when the
nection that is to be established. This is the identifier on operation parameter is set to X'0000'.
which all incoming data for this connection will be
Note: The number of data units created in the output
received. Any numeric value except zero should be
buffer was returned in the data units created parameter
used. See “Receive Data (QOLRECV) API” on
on the call to the QOLELINK API. See “Enable Link
page 12-14 for more information.
(QOLELINK) API” on page 12-2 for more information.
The content of this parameter is only valid for links using
an X.25 communications line and when the operation
parameter is set to X'B000' or X'B400'.

12-28 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Diagnostic Data Parameter Format: The format of the

diagnostic data parameter is shown below. The contents of
the fields within this parameter are only valid on X'0000'
and X'B400' operations for the indicated return and reason
codes.

Figure 12-34. Diagnostic Data Parameter

Field Type Description
Reserved CHAR(2) Reserved for extension.
Error code CHAR(4) Specifies hexadecimal diagnostic information that can be used to determine recovery actions. See
“Error Codes” on page 13-9 for more information.
The content of this field is only valid for 83/4001, 83/4002, and 83/4003 return/reason codes.
Time stamp CHAR(8) The time the error occurred.
The content of this field is only valid for 83/4001, 83/4002, and 83/4003 return/reason codes.
Error log identi- CHAR(4) The hexadecimal identifier that can be used for locating error information in the error log.
fier
The content of this field is only valid for 83/4001, 83/4002, and 83/4003 return/reason codes.
Reserved CHAR(10) Reserved for extension.
Indicators CHAR(1) Specifies indicators the user-defined communications application program can use for diagnosing a
potential error condition. This is a bit sensitive field.
The valid values for bit 0 (leftmost bit) are as follows:
'0'B Either there is no message in the QSYSOPR message queue, or there is a message and
it does not have the capability to run problem analysis report (PAR) to determine the
cause of the error.
'1'B There is a message in the QSYSOPR message queue for this error, and it does have
the capability to run problem analysis report (PAR) to determine the cause of the error.
The valid values for bit 1 are as follows:
'0'B The line error can be retried.
'1'B The line error cannot be retried.
The valid values for bit 2 are as follows:
'0'B The cause and diagnostic codes fields are not valid.
'1'B The cause and diagnostic codes fields are valid.
The valid values for bit 3 are as follows:
'0'B The error has not been reported to the system operator message queue.
'1'B The error has been reported to the system operator message queue.
For example, consider the following values for the indicators field:
X'20' A condition has caused X.25 cause and diagnostic codes to be passed to the application.
This information can determine the cause of the condition.
X'50' An error has occurred and been reported to the QSYSOPR message queue. The error
cannot be retried.
X'F0' An error has occurred and been reported to the QSYSOPR message queue. The error
cannot be retried, and has X.25 cause and diagnostic codes associated with it. Also a
problem analysis report can be generated to determine the probable cause.
The content of this field is only valid for 83/4001, 83/4002, 83/3202 and 83/4003 return/reason codes.
X.25 cause CHAR(1) Specifies additional information on the condition reported. See the X.25 Network Support for inter-
code preting the values of this field.
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes.
X.25 diagnostic CHAR(1) Specifies additional information on the condition reported. See the X.25 Network Support for inter-
code preting the values of this field.
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes.
Reserved CHAR(1) Reserved for extension.
Error offset BINARY(4) The offset from the top of the output buffer to the incorrect data in the output buffer.
The content of this field is only valid for a 83/1999 return/reason code.
Reserved CHAR(4) Reserved for extension.

Chapter 12. User-Defined Communications Support APIs 12-29

Send Data (QOLSEND) API

LAN Output Operations buffer descriptor. The information for the second frame
would be placed in the second data unit of the output buffer
The only output operation supported on links using a token- and described in the second element of the output buffer
ring, Ethernet, wireless, or FDDI communications line is descriptor. The number of data units parameter on the call
X'0000' (send user data). For each data frame to be sent to the QOLSEND API would be set to 2.
on the network, the application program must provide the fol- Note: The X'0000' operation is synchronous. Control will
lowing information: not return from the QOLSEND API until the operation com-
Ÿ General LAN information, optional routing information, pletes.
and user data in the next data unit of the output buffer,
starting with the first data unit Data Unit Format–LAN Operation X'0000': Each data
frame to be sent on the network corresponds to a data unit in
Ÿ A description, in the corresponding element of the output
the output buffer. The information in each of these data units
buffer descriptor, of the information in that data unit.
is made up of general LAN information, optional routing data,
For example, suppose a user-defined communications appli- and user data.
cation program wants to send two data frames. The informa-
Figure 12-35 shows the format of the general LAN informa-
tion for the first frame would be placed in first data unit of the
tion.
output buffer and described in the first element of the output

Figure 12-35 (Page 1 of 2). Format of the General LAN Information

Field Type Description
Length of BINARY(2) The length of the general LAN information in the data unit. This must be set to 16.
general LAN
information
Destination CHAR(6) Specifies, in packed form, the adapter address to which this data frame will be sent.
adapter address
Note: Because user-defined communications support only allows connectionless service over LANs, it
is not necessary for all frames being sent on a single output operation to have the same destination
adapter address.
DSAP address CHAR(1) The service access point on which the destination system will receive this frame. Any value may be
used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. There-
fore, to send Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP
address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must
be configured as either *ETHV2 or *ALL.
SSAP address CHAR(1) The service access point on which the AS/400 system will send this frame. Any service access point
configured in the token-ring, Ethernet, wireless, or FDDI line description may be used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. There-
fore, to send Ethernet Version 2 frames, a null SSAP address (X'00') must be specified in the SSAP
address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must
be configured as either *ETHV2 or *ALL.
Access control CHAR(1) Specifies outbound frame priority and is mapped to the access priority bits in the access control field of
802.5 frames. For links using a token-ring communications line, any value between X'00' and X'07'
may be used, where X'00' is the lowest priority and X'07' is the highest priority.
For links using an Ethernet or wireless communications line, the content of this field is not applicable
and must be set to X'00'.
Priority control CHAR(1) Specifies how to interpret the value set in the access control field. For links using a token-ring commu-
nications line, the valid values are as follows:
X'00' Use any priority less than or equal to the value set in the access control field.
X'01' Use the priority exactly equal to the value set in the access control field.
X'FF' Use the AS/400 system default priority.
For links using an Ethernet or wireless communications line, the content of this field is not applicable
and must be set to X'00'.
Length of BINARY(2) The length of the routing information in the data unit. For links using a token-ring communications line,
routing informa- any value between 0 and 18 may be used, where 0 indicates that there is no routing information.
tion
For links using an Ethernet or wireless communications line, the content of this field is not applicable
and must be set to 0 indicating that there is no routing information.

12-30 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Figure 12-35 (Page 2 of 2). Format of the General LAN Information

Field Type Description
Length of user BINARY(2) The length of the user data in the data unit. This must be less than or equal to the maximum frame
data size allowed on the service access point specified in the SSAP address field. See “Query Line Descrip-
tion (QOLQLIND) API” on page 12-5 to determine the maximum frame size allowed on the service
access point specified in the SSAP address field.
For Ethernet Version 2 frames, this must be at least 48 and not more than 1502 (including 2 bytes for
the Ethernet type field).
Note: Ethernet 802.3 frames will be padded when the user data is less than 46 bytes.

Output Buffer Descriptor Element Format–LAN Figure 12-37. X.25 SVC and PVC Output Operations
Operation X'0000': The information specified in each Operation Meaning
data unit of the output buffer must be described in the corre-
sponding element of the output buffer descriptor. X'B100' Send a clear packet (SVC) or close the PVC
connection.
Figure 12-36 shows the format of each element in the output
buffer descriptor. Note: This is an asynchronous operation.
Notification of the completion of this operation
will be returned from the QOLRECV API with
Figure 12-36. Format of an Element in the Output Buffer
operation X'B101' only after control returns
Descriptor
from the QOLSEND API with a 0/0 return and
Field Type Description reason code. See “Receive Data (QOLRECV)
API” on page 12-14 for more information.
Length BINARY(2) The number of bytes of information
in the corresponding data unit of X'B110' Close all connections which were cleared by the
the output buffer. This must be reason given in the connection failure date
equal to the length of the general received on X 'B311'.
LAN information plus the length of Note: This is an asynchronous operation.
the routing information plus the Notification of the completion of this operation
length of the user data. See will be returned from the QOLRECV API with
Figure 12-35 on page 12-30 for operation X'B111' only after control returns
more information on the format of from the QOLSEND API with a 0/0 return and
the general LAN information. reason code. See “Receive Data (QOLRECV)
Reserved CHAR(30) Reserved for extension. API” on page 12-14 for more information.
X'B400' Send a call accept packet (SVC only).
Note: This is a synchronous operation.
X.25 SVC and PVC Output Operations Control will not return from the QOLSEND API
until the operation completes.
Figure 12-37 shows the output operations that are supported
on links using an X.25 communications line. X'BF00' Send a reset request or reset confirmation
packet (SVC or PVC).

Figure 12-37. X.25 SVC and PVC Output Operations Note: This is an asynchronous operation.
Notification of the completion of this operation
Operation Meaning will be returned from the QOLRECV API with
X'0000' Send user data (SVC or PVC). operation X'BF01' only after control returns
from the QOLSEND API with a 0/0 return and
Note: This is a synchronous operation.
reason code. See “Receive Data (QOLRECV)
Control will not return from the QOLSEND API
API” on page 12-14 for more information.
until the operation completes.
Note: The maximum number of outstanding asynchronous
X'B000' Send a call request packet (SVC) or open the
operations (notification of completion not yet received from the
PVC connection.
QOLRECV API) is five. All calls made to the QOLSEND API or
Note: This is an asynchronous operation. QOLSETF API under this condition will be rejected with a return
Notification of the completion of this operation and reason code of 83/3200.
will be returned from the QOLRECV API with
operation X'B001' only after control returns
from the QOLSEND API with a 0/0 return and
reason code. See “Receive Data (QOLRECV)
API” on page 12-14 for more information.

Chapter 12. User-Defined Communications Support APIs 12-31

Send Data (QOLSEND) API

X.25 Operation X'0000': This operation allows the appli- User-defined communications support automatically frag-
cation program to send user data on an SVC or PVC X.25 ments the user data in each data unit into one or more
connection. The application must provide the following infor- appropriately sized X.25 packets based on the negotiated
mation: transmit packet size for the connection. All packets con-
structed for a data unit, except for the last (or only) packet,
Ÿ User data in the next data unit of the output buffer,
will always have the X.25 more data bit (M-bit) set on. See
starting with the first data unit
“Output Buffer Descriptor Element Format–X.25 Operation
Ÿ A description, in the corresponding element of the output X'0000'” for more information on how to set the X.25 M-bit on
buffer descriptor, of the user data in that data unit. or off in the last (or only) packet constructed for a data unit.

For example, suppose a user-defined communications appli- Data Unit Format–X.25 Operation X'000': Each data unit
cation program wants to send two data units of user data. in the output buffer consists solely of user data and starts
The first portion of the user data would be placed in first data offset 0 from the top of the data unit.
unit of the output buffer and described in the first element of
the output buffer descriptor. The second portion of the user Output Buffer Descriptor Element Format–X.25 Operation
data would be placed in the second data unit of the output X'0000': The user data specified in each data unit of the
buffer and described in the second element of the output output buffer must be described in the corresponding
buffer descriptor. The number of data units parameter on the element of the output buffer descriptor.
call to the QOLSEND API would be set to 2.
Figure 12-38 shows the format of each element in the output
buffer descriptor.

Figure 12-38. Format of an Element in the Output Buffer Descriptor

Field Type Description
Length BINARY(2) The number of bytes of user data in the corresponding data unit of the output buffer. This must always
be less than or equal to the X.25 user data size parameter that was specified on the call to the
QOLELINK API when the link was enabled. See “Enable Link (QOLELINK) API” on page 12-2 for
more information.
More data indi- CHAR(1) Specifies whether the X.25 more data bit (M-bit) should be set on or off in the last (or only) X.25 packet
cator constructed for the corresponding data unit. The valid values are as follows:
X'00' Set the M-bit off in the last (or only) X.25 packet constructed for the corresponding data
unit.
X'01' Set the M-bit on in the last (or only) X.25 packet constructed for the corresponding data
unit.
Note: When this value is selected, the length field must be set to a multiple of the
negotiated transmit packet size for the connection.
Qualified data CHAR(1) Specifies whether the X.25 qualifier bit (Q-bit) should be set on or off in all X.25 packets constructed for
indicator the corresponding data unit. The valid values are as follows:
X'00' Set the Q-bit off in all X.25 packets constructed for the corresponding data unit.
X'01' Set the Q-bit on in all X.25 packets constructed for the corresponding data unit.
Interrupt CHAR(1) Specifies whether the user data in the corresponding data unit should be sent in an X.25 interrupt
packet indi- packet. The valid values are as follows:
cator
X'00' Send the user data in the corresponding data unit in one or more X.25 data packets.
X'01' Send the user data in the corresponding data unit in an X.25 interrupt packet. An inter-
rupt packet causes the data to be expedited.
Note: When this value is selected, the length field must be set to a value between 1
and 32, and the number of data units parameter on the call to the QOLSEND API must
be set to 1. Also, the contents of the more data indicator, qualified data indicator, and
delivery confirmation indicator fields are ignored.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in all X.25 packets
mation indi- constructed for the corresponding data unit. The valid values are as follows:
cator
X'00' Set the D-bit off in all X.25 packets constructed for the corresponding data unit.
X'01' Set the D-bit on in all X.25 packets constructed for the corresponding data unit.
Note: The AS/400 system does not fully support delivery confirmation when sending user data. Con-
firmation is from the local data circuit equipment (DCE).
Reserved CHAR(26) Reserved for extension.

12-32 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

X.25 Operation X'B000': This operation allows the appli- tifier of the SVC that was chosen will be returned when notifi-
cation program to either initiate an SVC call or to open a cation of the completion of X'B000' is received from the
PVC connection. The application must provide the data for QOLRECV API (operation X'B001'). See “Receive Data
this operation in the first data unit of the output buffer. The (QOLRECV) API” on page 12-14 for more information.
output buffer descriptor is not used.
Data Unit Format–X.25 Operation X'B000' (Initiate an SVC
The format of the data required for the X'B000' operation Call): The data for this operation starts at offset 0 from the
depends on whether it is used to initiate an SVC call or to top of the first data unit in the output buffer.
open a PVC connection. Each format is explained in the fol-
lowing table. Figure 12-39 shows the format of the data required for the
X'B000' operation when initiating an SVC call.
Note: When initiating an SVC call, the AS/400 system
chooses an available SVC to use. The logical channel iden-

Figure 12-39 (Page 1 of 3). Format of Data for X'B000' Operation (Initiate an SVC Call)
Field Type Description
Reserved CHAR(1) This field must be set to X'02'.
Reserved CHAR(3) This field must be set to hexadecimal zeros.
Transmit packet BINARY(2) The requested transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024,
size 2048, and 4096. The value specified must be less than or equal to the transmit maximum packet
size configured for this line. The special value of X'FFFF' may be specified to use the transmit
default packet size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
transmit maximum packet size and the transmit default packet size configured for this line.
Transmit BINARY(2) The requested transmit window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the transmit default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the transmit default window size configured for this line.
Receive packet BINARY(2) The requested receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024,
size 2048, and 4096. The value specified must be less than or equal to the receive maximum packet size
configured for this line. The special value of X'FFFF' may be specified to use the receive default
packet size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
receive maximum packet size and the receive default packet size configured for this line.
Receive BINARY(2) The requested receive window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the receive default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the receive default window size configured for this line.
Reserved CHAR(7) This field must be set to hexadecimal zeros.
DTE address BINARY(1) The number of binary coded decimal (BCD) digits in the DTE address to call. The valid values are as
length follows:
1–15 When extended network addressing is not configured for this line.
1–17 When extended network addressing is configured in the line description.
See “Query Line Description (QOLQLIND) API” on page 12-5 to determine if extended network
addressing is configured for this line.
DTE address CHAR(16) Specifies, in binary coded decimal (BCD), the DTE address to call. The address must be left justified
and padded on the right with BCD zeros.
Reserved CHAR(8) This field must be set to hexadecimal zeros.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in the call request
mation support packet. The valid values are as follows:
X'00' Set the D-bit off in the call request packet.
X'01' Set the D-bit on in the call request packet.

Chapter 12. User-Defined Communications Support APIs 12-33

Send Data (QOLSEND) API

Figure 12-39 (Page 2 of 3). Format of Data for X'B000' Operation (Initiate an SVC Call)
Field Type Description
Reserved CHAR(7) This field must be set to hexadecimal zeros.
Closed user CHAR(1) Specifies whether the closed user group (CUG) identifier should be included in the call packet. The
group indicator valid values are as follows:
X'00' Do not include the CUG identifier in the call packet.
X'01' Include the CUG identifier in the call packet.
Closed user CHAR(1) The CUG identifier to be included in the call packet. The valid values are as follows:
group identifier
X'00' When the closed user group indicator field is set to X'00'
X'00'–X'99'
When the closed user group indicator field is set to X'01'
Reverse CHAR(1) Specifies reverse charging options. The valid values are as follows:
charging indi-
X'00' Do not request reverse charging.
cator
X'01' Request reverse charging.
Fast select indi- CHAR(1) Specifies fast select options. The valid values are as follows:
cator
X'00' Do not request fast select.
X'01' Request fast select with restriction.
X'02' Request fast select without restriction.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be used.
length
Note: The AS/400 system codes the closed user group, reverse charging, and fast select facilities in
the X.25 facilities field, if the user requested them in the above fields. Additionally, if the network user
identification parameter (NETUSRID) is specified in the line description, the network user identification
(NUI) facility is coded in the field, following the other additional facilities, if present. Finally, if the
packet and window size values specified are different than the network default, the facilities con-
taining these values are coded in the field as well. The system will update the X.25 facilities length
field appropriately for each facility to which the AS/400 system adds the X.25 facilities field. This
length cannot exceed 109 bytes.
X.25 facilities CHAR(109) Specifies additional X.25 facilities data requested.
Note: The application programmer should not code the facilities for NUI, fast select, reverse
charging, closed user group, packet size, or window size in this field. By doing so, this field could
contain duplicate facilities, which may not be consistently supported by all X.25 networks.
Reserved CHAR(48) This field must be set to hexadecimal zeros.
Call user data BINARY(2) The number of bytes of data in the call user data field. The valid values are as follows:
length
0–16 When the fast select indicator field is set to X'00'.
0–128 When the fast select indicator field is set to X'01' or X'02'.
Call user data CHAR(128) The call user data.
Reserved CHAR(128) This field must be set to hexadecimal zeros.
Control informa- CHAR(1) Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit)
tion defined for reset support. The remaining bits are undefined and should be set off ('0'B).
The valid values for bit 0 are as follows:
'0'B Resets are not supported on this connection.
When this value is selected, the X'BF00' output operation will not be valid on this
connection. Also, a reset indication packet received on this connection will cause the
connection to be ended.
'1'B Resets are supported on this connection.
When this value is selected, the X'BF00' output operation will be valid on this con-
nection. Also, the user-defined communications application program will be required to
handle reset indications received on this connection.
For example, consider the following values for the control information field:
X'00' Resets are not supported on this connection.
X'80' Resets are supported on this connection.
Reserved CHAR(3) This field must be set to hexadecimal zeros.

12-34 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Figure 12-39 (Page 3 of 3). Format of Data for X'B000' Operation (Initiate an SVC Call)
Field Type Description
Maximum data BINARY(4) The maximum number of bytes of user data that is received in a complete X.25 packet sequence
unit assembly before passing the user data to the application. Any value between 1024 and 32767 may be used,
size and should be set to the largest value that the application will support.
Notes:
1. The system attempts to assemble the entire packet sequence before passing the data to the
application. The only exception to this is when the size of the packet sequence exceeds the
value the user specified for this field.
2. If the number of bytes of user data received in a complete X.25 packet sequence is more than
can fit into one data unit of the input buffer, the more data indicator field in the corresponding
element of the input buffer descriptor will be set to X'01' and the remaining user data will be
filled in the next data unit. See “Receive Data (QOLRECV) API” on page 12-14 for more infor-
mation.
3. There is no limitation on the number of bytes of user data that can be sent in a complete X.25
packet sequence. However, the QOLSEND API may need to called more than once.
Automatic flow BINARY(2) Relates to the amount of data that will be held by user-defined communications support before
control sending a receive not ready (RNR) packet to the sending system. The recommended value for this
field is 32, but any value between 1 and 128 may be used.
Note: A receive ready (RR) packet will be sent when the user-defined communications application
program receives some of the data.
Reserved CHAR(30) This field must be set to hexadecimal zeros.

Data Unit Format–X.25 Operation X'B000' (Open a PVC Figure 12-40 shows the format of the data required for the
Connection): The data for this operation starts at offset 0 X'B000' operation when opening a PVC connection
from the top of the first data unit in the output buffer.

Figure 12-40 (Page 1 of 2). Format of Data for X'B000' Operation (Open a PVC Connection)
Field Type Description
Reserved CHAR(1) This field must be set to hexadecimal zeros.
Reserved CHAR(1) This field must be set to hexadecimal zeros.
Logical channel CHAR(2) The logical channel identifier of the PVC to open. Any PVC configured for this line that is eligible to
identifier be used by the network controller that the link is using may be specified and must be in the range of
X'0001'–X'0FFF'.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the PVCs
configured for this line that are eligible to be used by the network controller the link is using.
Transmit packet BINARY(2) The requested transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024,
size 2048, and 4096. The value specified must be less than or equal to the transmit maximum packet size
configured for this line. The special value of X'FFFF' may be specified to use the transmit default
packet size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
transmit maximum packet size and the transmit default packet size configured for this line.
Transmit BINARY(2) The requested transmit window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the transmit default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the transmit default window size configured for this line.
Receive packet BINARY(2) The requested receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024,
size 2048, and 4096. The value specified must be less than or equal to the receive maximum packet size
configured for this line. The special value of X'FFFF' may be specified to use the receive default
packet size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
receive maximum packet size and the receive default packet size configured for this line.

Chapter 12. User-Defined Communications Support APIs 12-35

Send Data (QOLSEND) API

Figure 12-40 (Page 2 of 2). Format of Data for X'B000' Operation (Open a PVC Connection)
Field Type Description
Receive BINARY(2) The requested receive window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the receive default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the receive default window size configured for this line.
Reserved CHAR(32) This field must be set to hexadecimal zeros.
Delivery confir- CHAR(1) The X.25 delivery confirmation bit (D-bit) support for this connection. The valid values are as follows:
mation support
X'00' D-bit will be supported for sending data but not for receiving data.
Note: When this value is selected and an X.25 packet is received with the D-bit set
on, the input/output processor (IOP) will send a reset packet.
X'01' D-bit will be supported for sending data and for receiving data.
Reserved CHAR(427) This field must be set to hexadecimal zeros.
Control informa- CHAR(1) Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit)
tion defined for reset support. The remaining bits are undefined and should be set off ('0'B).
The valid values for bit 0 are as follows:
'0'B Resets are not supported on this connection.
When this value is selected, the X'BF00' output operation will not be valid on this con-
nection. Also, a reset indication packet received on this connection will cause the con-
nection to be ended.
'1'B Resets are supported on this connection.
When this value is selected, the X'BF00' output operation will be valid on this con-
nection. Also, the user-defined communications application program will be required to
handle reset indications received on this connection.
For example, consider the following values for the control information field:
X'00' Resets are not supported on this connection.
X'80' Resets are supported on this connection.
Reserved CHAR(3) This field must be set to hexadecimal zeros.
Maximum data BINARY(4) The maximum number of bytes of user data that is received in a complete X.25 packet sequence
unit assembly before passing the user data to the application. Any value between 1024 and 32767 may be used,
size and should be set to the largest value that the application will support.
Notes:
1. The system attempts to assemble the entire packet sequence before passing the data to the
application. The only exception to this is when the size of the packet sequence exceeds the
value the user specified for this field.
2. If the number of bytes of user data received in a complete X.25 packet sequence is more than
can fit into one data unit of the input buffer, the more data indicator field in the corresponding
element of the input buffer descriptor will be set to X'01' and the remaining user data will be
filled in the next data unit. See “Receive Data (QOLRECV) API” on page 12-14 for more infor-
mation.
3. There is no limit of the number of bytes of user data that can be sent in a complete X.25 packet
sequence. However, the QOLSEND API may need to called more than once.
Automatic flow BINARY(2) Relates to the amount of data that will be held by user-defined communications support before
control sending a receive not ready (RNR) packet to the sending system. The recommended value for this
field is 32, but any value between 1 and 128 may be used.
Note: A receive ready (RR) packet will be sent when the user-defined communications application
program receives some of the data.
Reserved CHAR(30) This field must be set to hexadecimal zeros.

12-36 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

X.25 Operation X'B100': This operation allows the appli- Notes:

cation program to either send a clear packet on an SVC, 1. The AS/400 system provides the confirmation of the
close an SVC connection that was cleared by the remote clear indication, however, the local user-defined commu-
system, or to close a PVC connection. The application must nications application must issue the X'B100' operation
provide the data for this operation in the first data unit of the to free the PCEP for the connection.
output buffer. The output buffer descriptor is not used.
2. Closing a PVC connection will cause a reset packet to
The format of the data required for the X'B100' operation is be sent to the remote system.
the same whether or not it is used to send a clear packet on
an SVC or to close a PVC connection. The format of the Data Unit Format–X.25 Operation X'B100': The data for
data required for the X'B100' operation should be set to this operation starts at offset 0 from the top of the first data
hexadecimal zeros if it is used to close an SVC connection unit in the output buffer.
that was previously cleared by the remote system.
Figure 12-41 shows the format of the data required for the
X'B100' operation.

Figure 12-41. Format of Data for X'B100' Operation

Field Type Description
Reserved CHAR(2) This field must be set to hexadecimal zeros.
Cause code CHAR(1) The X.25 cause code.
Diagnostic CHAR(1) The X.25 diagnostic code.
code
Reserved CHAR(4) This field must be set to hexadecimal zeros.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be used.
length1
X.25 facilities1 CHAR(109) The X.25 facilities data.
Reserved CHAR(48) This field must be set to hexadecimal zeros.
Clear user data BINARY(2) The number of bytes of data in the clear user data field. Any value between 0 and 128 may be used.
length1
Clear user CHAR(128) The clear user data.
data1
Note: The CCITT standard recommends that this field only be present in conjunction with the fast
select or call deflection selection facility. The AS/400 system does not enforce this restriction,
however.
Reserved CHAR(216) This field must be set to hexadecimal zeros.
1 This field is not used for PVC connections and should be set to hexadecimal zeros.

X.25 Operation X'B110': This operation allows the appli- X.25 Operation X'B400': This operation allows the appli-
cation program to clean up all internal control information on cation program to accept an incoming SVC call. The appli-
all the connections over the link and free up all PCEPs and cation must provide the data for this operation in the first
UCEPs. This operation is only valid following the receipt of data unit of the output buffer. The output buffer descriptor is
the X'B311' operation that reports the connection failure not used.
data to the application. There is no data associated with this
Note: Notification of incoming calls are received from the
operation.
QOLRECV API with operation X'B201'. See “Receive Data
(QOLRECV) API” on page 12-14 for more information.

Data Unit Format–X.25 Operation X'B400': The data for

this operation starts at offset 0 from the top of the first data
unit in the output buffer.

Figure 12-42 shows the format of the data required for the
X'B400' operation.

Figure 12-42 (Page 1 of 3). Format of Data for X'B400' Operation

Field Type Description
Reserved CHAR(1) This field must be set to hexadecimal zeros.

Chapter 12. User-Defined Communications Support APIs 12-37

Send Data (QOLSEND) API

Figure 12-42 (Page 2 of 3). Format of Data for X'B400' Operation

Field Type Description
Reserved CHAR(3) This field must be set to hexadecimal zeros.
Transmit BINARY(2) The transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and
packet size 4096. The value specified must be less than or equal to the transmit maximum packet size config-
ured for this line. The special value of X'FFFF' may be specified to use the transmit default packet
size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
transmit maximum packet size and the transmit default packet size configured for this line.
Transmit BINARY(2) The transmit window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the transmit default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the transmit default window size configured for this line.
Receive BINARY(2) The receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and
packet size 4096. The value specified must be less than or equal to the receive maximum packet size configured
for this line. The special value of X'FFFF' may be specified to use the receive default packet size
configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
receive maximum packet size and the receive default packet size configured for this line.
Receive BINARY(2) The receive window size for this connection. The valid values are as follows:
window size
1–7 When modulus 8 is configured for this line.
1–15 When modulus 128 is configured for this line.
X'FFFF' Use the receive default window size configured for this line.
See “Query Line Description (QOLQLIND) API” on page 12-5 for information on determining the
modulus value and the receive default window size configured for this line.
Reserved CHAR(32) This field must be set to hexadecimal zeros.
Delivery confir- CHAR(1) Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in the call accept
mation support packet. This also specifies the D-bit support for this connection. The valid values are as follows:
X'00' Set the D-bit off in the call accept packet. D-bit will be supported for sending data but
not for receiving data.
Note: When this value is selected and an X.25 packet is received with the D-bit set
on, the input/output processor (IOP) will send a reset packet.
X'01' Set the D-bit on in the call accept packet. D-bit will be supported for sending data and
for receiving data.
Reserved CHAR(11) This field must be set to hexadecimal zeros.
X.25 facilities BINARY(1) The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be used.
length
Note: The AS/400 system codes the packet and window size facilities in this field, if necessary. The
total length of all facilities can not exceed 109 bytes.
X.25 facilities CHAR(109) The X.25 facilities data.
Note: The application programmer should not code the facilities for packet or window sizes in this
field. By doing so, this field could contain duplicate facilities, which may not be consistently supported
by all X.25 networks.
Reserved CHAR(306) This field must be set to hexadecimal zeros.

12-38 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Figure 12-42 (Page 3 of 3). Format of Data for X'B400' Operation

Field Type Description
Control infor- CHAR(1) Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit)
mation defined for reset support. The remaining bits are undefined and should be set off ('0'B).
The valid values for bit 0 are as follows:
'0'B Resets are not supported on this connection.
When this value is selected, the X'BF00' output operation will not be valid on this
connection. Also, a reset indication packet received on this connection will cause the
connection to be ended.
'1'B Resets are supported on this connection.
When this value is selected, the X'BF00' output operation will be valid on this con-
nection. Also, the user-defined communications application program will be required to
handle reset indications received on this connection.
For example, consider the following values for the control information field:
X'00' Resets are not supported on this connection.
X'80' Resets are supported on this connection.
Reserved CHAR(3) This field must be set to hexadecimal zeros.
Maximum data BINARY(4) The maximum number of bytes of user data that can be received in a complete X.25 packet
unit assembly sequence on this connection. If this limit is exceeded, the connection will be ended. Any value
size between 1024 and 32767 may be used.
Notes:
1. If the number of bytes of user data received in a complete X.25 packet sequence is more than
can fit into one data unit of the input buffer, the more data indicator field in the corresponding
element of the input buffer descriptor will be set to X'01' and the remaining user data will be
filled in the next data unit. See “Receive Data (QOLRECV) API” on page 12-14 for more infor-
mation.
2. There is no limitation on the number of bytes of user data that can be sent in a complete X.25
packet sequence. However, the QOLSEND API may need to called more than once.
Automatic flow BINARY(2) Relates to the amount of data that will be held by user-defined communications support before
control sending a receive not ready (RNR) packet to the sending system. The recommended value for this
field is 32, but any value between 1 and 128 may be used.
Note: A receive ready (RR) packet will be sent when the user-defined communications application
program receives some of the data.
Reserved CHAR(30) This field must be set to hexadecimal zeros.

X.25 Operation X'BF00': This operation allows an appli- Ÿ After a reset indication packet has been received on the
cation program to send a reset request packet or a reset connection but before the application has received it
confirmation packet on an X.25 SVC or PVC connection. from the QOLRECV API
The application must provide the X.25 cause and diagnostic Ÿ When a reset indication packet is received on the con-
codes required for this operation in the first data unit of the nection at the same time the X'BF00' output operation
output buffer. The output buffer descriptor is not used. is issued
Information indicating whether a reset request or reset confir- This is known as a reset collision. In this case, user-
mation packet was sent is returned when notification of the defined communications support will discard the reset
completion of the X'BF00' operation is received from the indication and, therefore, the application program will not
QOLRECV API (operation X'BF01'). This information will receive it from the QOLRECV API. However, the cause
be in the diagnostic data parameter of the QOLRECV API. and diagnostic codes from the reset indication are
See “Receive Data (QOLRECV) API” on page 12-14 for returned in the diagnostic data parameter of the
more information. QOLRECV program when the application receives notifi-
cation of the completion of the X'BF00' operation. See
A reset confirmation packet will be sent under the following “Receive Data (QOLRECV) API” on page 12-14 for
conditions: more information.
Ÿ After a reset indication packet has been received on the
A reset request packet will be sent when none of the above
connection and the application has received it from the
conditions are true.
QOLRECV API (X'B301' operation, 83/3202 return and
reason code)

Chapter 12. User-Defined Communications Support APIs 12-39

Send Data (QOLSEND) API

Notes: Data Unit Format–X.25 Operation X'BF00': The first 2

bytes of the data unit in the output buffer are used for this
1. Data not yet received by the application program on a
operation. The first byte contains the X.25 cause code. The
connection will not be deleted when a X'BF00' opera-
second byte contains the X.25 diagnostic code.
tion is issued on that connection. This data will be
received before the notification of the completion of the
X'BF00' operation is received from the QOLRECV API Return and Reason Codes
(operation X'BF01'). Data received after the notification
of the completion of the X'BF00' operation is received The return and reason codes that can be returned from the
should be treated as new data. QOLSEND API depend on the type of communications line
the link is using and on the operation that was requested.
2. The X'BF00' operation is only valid on connections that
support resets. See “X.25 Operation X'B000'” on
LAN Return and Reason Codes
page 12-33 and “X.25 Operation X'B400'” on
page 12-37 for more information on specifying reset Return and Reason Codes for LAN Operation X'0000'
support.

Figure 12-43 (Page 1 of 2). Return and Reason Codes for LAN Operation X'0000'
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.
80/2200 Queue error detected. Escape message CPF91F1 will be Ensure the link is disabled and see messages in the job log
sent to the application program when this return and reason for further information. Then correct the error, enable the
code is received. link, and try the request again.
80/2401 Output buffer or output buffer descriptor error detected. Ensure the link is disabled and see messages in the job log
Escape message CPF91F1 will be sent to the application for further information. Then correct the error, enable the
program when this return and reason code is received. link, and try the request again.
80/3002 A previous error occurred on this link that was reported to Ensure the link is disabled and see messages in the job log
the application program by escape message CPF91F0 or for further information. If escape message CPF91F0 was
CPF91F1. However, the application program has attempted sent to the application program, then report the problem
another operation. using the ANZPRB command. Otherwise, correct the error,
enable the link, and try the request again.
80/4000 Error recovery has been canceled for this link. Ensure the link is disabled and see messages in the job log
for further information. Correct the condition, enable the
link, and try the request again.
80/8000 The amount of user data in a data unit of the output buffer Ensure the link is disabled. Correct the error, enable the
is greater than the maximum frame size allowed on the link, and try the request again.
communications line the link is using. Escape message
CPF91F1 will be sent to the application program when this
return and reason code is received.
80/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
83/1006 Output operation not valid. Correct the operation parameter. Try the request again.
83/1007 Connection identifier not valid. Correct the existing provider connection end point ID
parameter. Try the request again.
83/1008 Number of data units not valid. Correct the number of data units parameter. Try the
request again.
83/1998 The amount of data in a data unit of the output buffer is not Correct the amount of user data, or the total amount of
correct. general LAN information, routing information, and user data
in the offending data unit. Try the request again.
83/1999 Incorrect data in a data unit of the output buffer. The error Correct the incorrect data. Try the request again.
offset field in the diagnostic data parameter will point to the
incorrect data.
83/3001 Link not enabled. Correct the communications handle parameter. Try the
request again.

12-40 AS/400 System API Reference V4R4

 Send Data (QOLSEND) API

Figure 12-43 (Page 2 of 2). Return and Reason Codes for LAN Operation X'0000'
Return /
Reason
Code Meaning Recovery
83/3004 Link is enabling. Wait for the enable-complete entry to be sent to the data
queue or user queue. If the link was successfully enabled,
try the request again.
83/4001 Link failure, system starting error recovery for this link. Wait for the link to recover. Try the request again.
83/4003 Error detected by the input/output processor (IOP). The Correct the error, and try the request again.
diagnostic data parameter will contain more information on
this error.

X.25 Return and Reason Codes General X.25 Return and Reason Codes: Figure 12-44
shows the return and reason codes that can be received
from the QOLSEND API for any requested operation.

Figure 12-44. Return and Reason Codes Valid for All X.25 Operations
Return /
Reason
Code Meaning Recovery
80/2200 Queue error detected. Escape message CPF91F1 will be Ensure the link is disabled and see messages in the job log
sent to the application program when this return and reason for further information. Correct the error, enable the link,
code is received. and try the request again.
80/2401 Output buffer or output buffer descriptor error detected. Ensure the link is disabled and see messages in the job log
Escape message CPF91F1 will be sent to the application for further information. Correct the error, enable the link,
program when this return and reason code is received. and try the request again.
80/3002 A previous error occurred on this link that was reported to Ensure the link is disabled and see messages in the job log
the application program by escape message CPF91F0 or for further information. If escape message CPF91F0 was
CPF91F1. However, the application has attempted another sent to the application program, report the problem using
operation. the ANZPRB command. Otherwise, correct the error,
enable the link, and try the request again.
80/4000 Error recovery has been canceled for this link. Ensure the link is disabled and see messages in the job log
for further information. Correct the condition, enable the
link, and try the request again.
80/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
83/1006 Output operation not valid. Correct the operation parameter. Try the request again.
83/3001 Link not enabled. Correct the communications handle parameter. Try the
request again.
83/3004 Link is enabling. Wait for the enable-complete entry to be sent to the data
queue or user queue. If the link was successfully enabled,
try the request again.
83/3200 All resources are currently in use by asynchronous oper- Wait for at least one of the asynchronous operations to
ations that have not yet completed. complete. Notification of completion of these operations will
be received from the QOLRECV API. Try the request
again.

Return and Reason Codes for X.25 Operation X'0000'

Figure 12-45 (Page 1 of 2). Return and Reason Codes for X.25 Operation X'0000'
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.

Chapter 12. User-Defined Communications Support APIs 12-41

Send Data (QOLSEND) API

Figure 12-45 (Page 2 of 2). Return and Reason Codes for X.25 Operation X'0000'
Return /
Reason
Code Meaning Recovery
83/1007 Connection identifier not valid. Correct the existing provider connection end point ID
parameter. Try the request again.
83/1008 Number of data units not valid. Correct the number of data units parameter. Try the
request again.
83/1997 The amount of user data in a data unit of the output buffer Correct the amount of user data in the offending data unit.
is not a multiple of the negotiated transmit packet size, and Try the request again.
the more data indicator in the corresponding element of the
output buffer descriptor is set to X'01'.
83/1998 The amount of user data in a data unit of the output buffer Correct the amount of user data in the offending data unit.
is not correct. Try the request again.
83/3201 The maximum amount of incoming user data that can be Wait to receive a failure notification from the QOLRECV API
held by user-defined communications support for the appli- indicating this condition (X'B301' operation, 83/3201 return
cation program on this connection has been exceeded. and reason code). Issue the X'B100' output operation to
end the connection.
83/3202 A reset indication has been received on this connection. Wait to receive notification from the QOLRECV API indi-
The X.25 cause and diagnostic code fields in the diagnostic cating this condition (X'B301' operation, 83/3202 return
data parameter will contain the cause and diagnostic codes and reason code). Issue the X'BF00' output operation to
of the reset indication. send a reset confirmation packet.
83/3205 Connection not in a valid state. Ensure the connection is in a valid state for this operation.
Try the request again.
83/4001 Link failure, system starting error recovery for this link. Wait to receive a failure notification from the QOLRECV API
indicating this condition (X'B301' or X'B311' operation,
83/4001 return and reason code). Issue the X'B100'
output operation to end the connection.
83/4002 Connection failure. Wait to receive a failure notification from the QOLRECV API
indicating this condition (X'B301' operation, 83/4002 return
and reason code). Issue the X'B100' output operation to
end the connection.
83/4003 Data not sent. Error detected by input/output processor. Try the request again. If the error persists, use the
ANZPRB command to analyze and report the problem.

Return and Reason Codes for X.25 Operation X'B000'

Figure 12-46. Return and Reason Codes for X.25 Operation X'B000'
Return /
Reason
Code Meaning Recovery
0/0 Operation initiated. Wait for notification of the completion of the X'B000' opera-
tion from the QOLRECV API (X'B001' operation).
83/4005 All connections are currently in use. Wait for a connection to become available and try the
request again.

Return and Reason Codes for X.25 Operation X'B100'

Figure 12-47 (Page 1 of 2). Return and Reason Codes for X.25 Operation X'B100'
Return /
Reason
Code Meaning Recovery
0/0 Operation initiated. Wait for notification of the completion of the X'B100' opera-
tion from the QOLRECV API (X'B101' operation).
83/1007 Connection identifier not valid. Correct the existing provider connection end point ID
parameter. Try the request again.

12-42 AS/400 System API Reference V4R4

 Set Filter (QOLSETF) API

Figure 12-47 (Page 2 of 2). Return and Reason Codes for X.25 Operation X'B100'
Return /
Reason
Code Meaning Recovery
83/3205 Connection not in a valid state. Ensure the connection is in a valid state for this operation.
Try the request again.

Return and Reason Codes for X.25 Operation X'B110'

Figure 12-48. Return and Reason Codes for X.25 Operation X'B110'
Return /
Reason
Code Meaning Recovery
0/0 Operation initiated. Wait for notification of the completion of the X'B110' opera-
tion from the QOLRECV API (X'B111' operation).

Return and Reason Codes for X.25 Operation X'B400'

Figure 12-49. Return and Reason Codes for X.25 Operation X'B400'
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.
83/1007 Connection identifier not valid. Correct the existing provider connection end point ID
parameter. Try the request again.
83/1999 Incorrect data in a data unit of the output buffer. The error Correct the incorrect data. Try the request again.
offset field in the diagnostic data parameter will point to the
incorrect data.
83/3205 Connection not in a valid state. Ensure the connection is in a valid state for this operation.
Try the request again.
83/4001 Link failure, system starting error recovery for this link. Issue the X'B100' output operation to end the connection.
83/4004 Inbound call timed out. Issue the X'B100' output operation to end the connection.

Return and Reason Codes for X.25 Operation X'BF00'

Figure 12-50. Return and Reason Codes for X.25 Operation X'BF00'
Return /
Reason
Code Meaning Recovery
0/0 Operation initiated. Wait for notification of the completion of the X'BF00' oper-
ation from the QOLRECV API (X'BF01' operation).
83/1007 Connection identifier not valid. Correct the existing provider connection end point ID
parameter. Try the request again.
83/3205 Connection not in a valid state. Ensure the connection is in a valid state for this operation.
Try the request again.

Error Messages CPF9872 E Program or service program &1 in library &2

ended. Reason code &3.
CPF3C90 E
Literal value cannot be changed.
CPF91F0 E Internal system error.
CPF91F1 E User-defined communications application error. Set Filter (QOLSETF) API

Chapter 12. User-Defined Communications Support APIs 12-43

Set Filter (QOLSETF) API

tive. For example, suppose two user-defined communica-

Required Parameter Group: tions application programs (application program A and B) in
different jobs each have a link enabled that use the same
1 Return code Output Binary(4) token-ring communications line. Further suppose that appli-
2 Reason code Output Binary(4) cation program A has activated a filter on DSAP X'22' and
3 Error offset Output Binary(4) application program B has activated a filter on DSAP X'22'
4 Communications handle Input Char(10) and SSAP X'22'. If a data frame comes in with a DSAP of
X'22' and an SSAP of X'22', application program B will
Threadsafe: No
receive the frame. If a data frame comes in with a DSAP of
X'22' and an SSAP not equal to X'22', application program
The Set Filter (QOLSETF) API activates and/or deactivates A will receive the frame.
one or more filters for a link that is currently enabled in the
job in which the application program is running. The applica- Required Parameter Group
tion program must provide the required filter information in
the output buffer that was created when the link was Return code
enabled. The output buffer descriptor is not used. See OUTPUT: BINARY(4)
“Format of Filter Information” for details on the format of the The recovery action to take. See “Return and Reason
filter information in the output buffer. Codes” on page 12-48.
Filters contain inbound routing information that user-defined Reason code
communications support uses to route incoming data to a link OUTPUT; BINARY(4)
that is enabled by an application program. The incoming
The error that occurred. See “Return and Reason
data that is routed depends on the type of communications
Codes” on page 12-48.
line the link is using. On an X.25 communications line, the
incoming data is an incoming switched virtual circuit (SVC) Error offset
call. On a token-ring, Ethernet, wireless, or FDDI commu- OUTPUT; BINARY(4)
nications line, the incoming data is the actual data frame.
The offset from the top of the output buffer to the incor-
The type of filters activated for a link determine the way rect filter header data or to the incorrect filter in the filter
incoming data is routed to that link1. For links using a token- list.
ring, Ethernet, wireless, or FDDI communications line, there The content of this parameter is only valid for 83/1999
are three types of filters. The following list of filters is from and 83/3003 return/reason codes.
most to least restrictive:
Communications handle
Ÿ Destination service access point (DSAP), source service INPUT; CHAR(10)
access point (SSAP), frame type, optional sending
adapter address, and protocol (or group) ID. The name of the link on which to perform the filter oper-
ation.
Ÿ Destination service access point (DSAP), source service
access point (SSAP), optional frame type, and sending
adapter address Format of Filter Information
Ÿ DSAP, SSAP, and optional frame type The application must provide all filter information in the
Ÿ DSAP output buffer that was created when the link was enabled.
The application should treat the output buffer as one large
For links using an X.25 communications line, there are two space with the size equal to the number of data units created
types of filters. The following list of filters is from most to for the output buffer multiplied by the size of each data unit.
least restrictive: This information is returned by the QOLELINK API when the
Ÿ Protocol identifier (PID) and calling data terminal equip- link was enabled.
ment (DTE) address
The filter information in the output buffer is made up of two
The AS/400 system treats the first byte of call-user data parts. The first portion starts at offset 0 from the top of the
in an X.25 call request packet as the PID. output buffer and contains filter header data. The second
Ÿ PID portion of the filter information starts immediately after the
filter header data in the output buffer and contains the filters
The order for checking filters when multiple links are using that make up the filter list.
the same communications line, is from most to least restric-

1 All active filters for a link must be of the same type.

12-44 AS/400 System API Reference V4R4

 Set Filter (QOLSETF) API

Figure 12-51. Filter Header Data

Field Type Description
Func- CHAR(1) The filter function to perform. The valid values are as follows:
tion
X'00' Deactivate all filters that are currently active for this link and activate the filters specified in the
filter list for this link.
X'01' Activate the filters specified in the filter list for this link. All filters currently active for this link will
remain active.
X'02' Deactivate the filters specified in the filter list that are currently active for this link.
Filter CHAR(1) The type of the filters in the filter list. All filters in the filter list must be of this type. In addition, this must be the
type same type as the filters currently active for this link, if any. The valid values are as follows:
X'00' PID.
This filter type is only applicable for links using an X.25 communications line and only applies to
incoming SVC calls.
X'01' PID and calling DTE address.
This filter type is only applicable for links using an X.25 communications line and only applies to
incoming SVC calls.
X'02' DSAP.
This filter type is only applicable for links using a token-ring, Ethernet, wireless, or FDDI commu-
nications line.
X'03' DSAP, SSAP, and optional frame type.
This filter type is only applicable for links using a token-ring, Ethernet, wireless, or FDDI commu-
nications line.
X'04' DSAP, SSAP, optional frame type, and sending adapter address.
This filter type is only applicable for links using a token-ring, Ethernet, wireless, or FDDI commu-
nications line.
X'08' DSAP, SSAP, frame type, optional and sending adapter address, and protocol identifier (or
organization ID).
This filter type is only applicable for links using a LAN communications line.
Note: The filter type field must be set even if there are no filters in the filter list.
Number BINARY(2) The number of filters in the filter list. Any value between 0 and 256 may be used.
of
Note: The maximum number of filters that can be specified in the filter list is also limited by the total size of the
filters
output buffer which may accommodate less than 256 filters.
Filter BINARY(2) The length of each filter in the filter list. This value must be 16 for filter types X'00' and X'01', and 14 for filter
length types X'02', X'03', and X'04', and 25 for filter type X'08'.
Note: The filter length field must be set even if there are no filters in the filter list.

The format of each filter in the previous list of filters is must be contiguous with each other and be of the type speci-
described in the following table. All filters in the list of filters fied in the filter type field in the filter header data.

X.25 Filters (Filter Types X'00' and X'01')

Figure 12-52 (Page 1 of 2). Filter Types X'00' and X'01'

Field Type Description
PID length CHAR(1) The length of the PID on which to route incoming calls. The valid values are as follows:
X'00' Route incoming calls with no PID specified. That is, with no call user data in the call
request packet.
X'01' Route incoming calls with the PID being treated as the first byte of call user data in the call
request packet.
PID CHAR(1) The PID on which to route incoming calls. This should be set to X'00' when the PID length field is set to
X'00'. Otherwise, any value may be used.
Note: Care should be taken when setting the PID field to an SNA PID (X'C3', X'C6', X'CB', X'CE'),
asynchronous PID (X'01', X'C0'), or TCP/IP PID (X'CC'). See the X.25 Network Support book for
more information.

Chapter 12. User-Defined Communications Support APIs 12-45

Set Filter (QOLSETF) API

Figure 12-52 (Page 2 of 2). Filter Types X'00' and X'01'

Field Type Description
Calling DTE CHAR(1) Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the calling DTE address
address length on which to route incoming calls. The valid values are as follows:
X'00' For filter type X'00'.
X'01'–X'0F'
For filter type X'01' when extended network addressing is not configured in the line
description. See “Query Line Description (QOLQLIND) API” on page 12-5 to determine if
extended network addressing is configured for this line.
X'01'–X'11'
For filter type X'01' when extended network addressing is configured in the line descrip-
tion. See “Query Line Description (QOLQLIND) API” on page 12-5 to determine if
extended network addressing is configured for this line.
Calling DTE CHAR(12) Specifies, in binary coded decimal (BCD), the calling DTE address on which to route incoming calls. This
address should be set to BCD zeros when the calling DTE address length field is set to X'00'. Otherwise, any
valid DTE address left-justified and padded on the right with BCD zeros may be used.
Additional CHAR(1) Specifies additional data on which to route incoming calls. This field is applicable for all X.25 filter types
routing data and is bit-sensitive with bit 0 (leftmost bit) defined for reverse charging options and bit 1 defined for fast
select options. The remaining bits are undefined and should be set off ('0'B).
The valid values for bit 0 are as follows:
'0'B Accept reverse charging.
'1'B Do not accept reverse charging.
The valid values for bit 1 are as follows:
'0'B Accept fast select.
'1'B Do not accept fast select.
For example, consider the following values for the additional routing data field:
X'00' Accept reverse charging and accept fast select.
X'40' Accept reverse charging and do not accept fast select.
X'80' Do not accept reverse charging and accept fast select.
X'C0' Do not accept reverse charging and do not accept fast select.

LAN Filters (Filter Types X'02', X'03', and X'04')

Figure 12-53 (Page 1 of 2). Filter Types X'02', X'03', and X'04'
Field Type Description
DSAP address CHAR(1) The length of the DSAP address on which to route incoming frames. This must be set to X'01'.
length
DSAP address CHAR(1) The DSAP address on which to route incoming frames. The DSAP address is the service access point
on which the incoming frame arrived. Any service access point configured in the token-ring, Ethernet,
wireless, or FDDI line description as *NONSNA may be used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. There-
fore, to receive Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP
address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must
be configured as either *ETHV2 or *ALL.
SSAP address CHAR(1) The length of the SSAP address on which to route incoming frames. The valid values are as follows:
length
X'00' For filter type X'02'.
X'01' For filter types X'03' and X'04'.
SSAP address CHAR(1) The SSAP address on which to route incoming frames. The SSAP address is the service access point
on which the incoming frame was sent. The valid values are as follows:
X'00' For filter type X'02'.
X'00'–X'FF'
For filter types X'03' and X'04'.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes
SAPs. Therefore, to receive Ethernet Version 2 frames, a null SSAP address (X'00')
must be specified in the SSAP address field. Also, the Ethernet Standard (ETHSTD)
parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL.

12-46 AS/400 System API Reference V4R4

 Set Filter (QOLSETF) API

Figure 12-53 (Page 2 of 2). Filter Types X'02', X'03', and X'04'
Field Type Description
Frame type CHAR(1) The length of the frame type on which to route incoming frames. The valid values are as follows:
length
X'00' For filter type X'02'. Also for filter types X'03' and X'04' when the DSAP address and
SSAP address fields are not both set to X'00'.
X'00' or X'02'
For filter types X'03' and X'04' when the 'DSAP address' and SSAP address fields are
both set to X'00'.
Frame type CHAR(2) The frame type on which to route incoming frames. The frame type is defined in an Ethernet Version 2
frame to indicate the upper layer protocol being used. This must be set to X'0000' when the frame
type length field is set to X'00'. Otherwise, any value except X'80D5' (encapsulated LLC) may be
used, but should be in the range of X'05DD'–X'FFFF'.
Sending CHAR(1) Specifies, in hexadecimal, the length of the sending adapter address on which to route incoming
adapter frames. The valid values are as follows:
address length
X'00' For filter types X'02' and X'03'.
X'06' For filter type X'04'.
Sending CHAR(6) Specifies, in packed form, the sending adapter address on which to route incoming frames. This must
adapter be set to X'000000000000' when the sending adapter address length field is set to X'00'. Otherwise,
address any valid adapter address may be used.

LAN Filters (Filter Type X'08')

Figure 12-54 (Page 1 of 2). Filter Type X'08'

Field Type Description
DSAP address CHAR(1) The length of the DSAP address on which to route incoming frames. This must be set to X'01'.
length
DSAP address CHAR(1) The DSAP address on which to route incoming frames. The DSAP address is the service access point
on which the incoming frame arrived. Any service access point configured in the token-ring, Ethernet,
wireless, or FDDI line description as *NONSNA may be used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. There-
fore, to receive Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP
address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must
be configured as either *ETHV2 or *ALL.
SSAP address CHAR(1) The length of the SSAP address on which to route incoming frames. The valid values are as follows:
length
X'01' For filter type X'08'.
SSAP address CHAR(1) The SSAP address on which to route incoming frames. The SSAP address is the service access point
on which the incoming frame was sent. The valid values are as follows:
X'00'–X'FF'
For filter type X'08'.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes
SAPs. Therefore, to receive Ethernet Version 2 frames, a null SSAP address (X'00')
must be specified in the SSAP address field. Also, the Ethernet Standard (ETHSTD)
parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL.
Frame type CHAR(1) The length of the frame type on which to route incoming frames. The valid values are as follows:
length
X'02' For filter type X'08'.
Frame type CHAR(2) The frame type on which to route incoming frames. The frame type is defined in an Ethernet Version 2
frame to indicate the upper layer protocol being used. This must be set to X'0000' when the frame
type length field is set to X'00'. Otherwise, any value except X'80D5' (encapsulated LLC) may be
used, but should be in the range of X'05DD'–X'FFFF'.
Sending CHAR(1) In hexadecimal, the length of the sending adapter address on which to route incoming frames. The
adapter valid values are as follows:
address length
X'00' or
X'06' For filter type X'08'.

Chapter 12. User-Defined Communications Support APIs 12-47

Set Filter (QOLSETF) API

Figure 12-54 (Page 2 of 2). Filter Type X'08'

Field Type Description
Sending CHAR(6) In packed form, the sending adapter address on which to route incoming frames. This must be set to
adapter X'000000000000' when the sending adapter address length field is set to X'00'. Otherwise, any valid
address adapter address may be used.
Protocol ID CHAR(1) In hexadecimal, the length of the protocol ID on which to route incoming frames. This must be set to
length X'03'.
Protocol ID CHAR(3) In hexadecimal, the protocol ID (or organization ID) to route incoming frames.
Reserved field CHAR(7) This field must be initialized to hexadecimal zeros, X'00000000000000'.

General Rules for Using Filters Ÿ A request to deactivate a filter for a link that has no such
filter active will be successful
The following is a list of rules for activating and deactivating
Ÿ If the return and reason code from the QOLSETF API is
filters:
not 0/0, none of the specified filters were activated or
Ÿ All active filters for a link must be of the same type deactivated
Ÿ A link can have a maximum of 256 active filters Ÿ Once a filter is activated, it will remain active until one of
Ÿ The maximum number of filters that can be specified in the following occurs:
the filter list can be no more than 256, and may be less, – It is deactivated by explicitly calling the QOLSETF
depending on the size of the output buffer API
Ÿ A request to activate a filter for a link that already has – The link that the filter was active for is disabled
the same filter active will be successful, but the filter will
only be activated once
Return and Reason Codes

Figure 12-55 (Page 1 of 2). Return and Reason Codes for the QOLSETF API
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.
80/2200 Queue error detected. Escape message CPF91F1 will be Ensure the link is disabled and see messages in the job log
sent to the application program when this return and reason for further information. Then correct the error, enable the
code is received. link, and try the request again.
80/2401 Output buffer error detected. Escape message CPF91F1 Ensure the link is disabled and see messages in the job log
will be sent to the application program when this return and for further information. Then correct the error, enable the
reason code is received. link, and try the request again.
80/3002 A previous error occurred on this link that was reported to Ensure the link is disabled and see messages in the job log
the application program by escape message CPF91F0 or for further information. If escape message CPF91F0 was
CPF91F1. However, the application program has attempted sent to the application program, then report the problem
another operation. using the ANZPRB command. Otherwise, correct the error,
enable the link, and try the request again.
80/4000 Error recovery has been canceled for this link. Ensure the link is disabled and see messages in the job log
for further information. Then correct the condition, enable
the link, and try the request again.
80/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Then,
will be sent to the application program when this return and report the problem using the ANZPRB command.
reason code is received.
83/1998 The size of the output buffer is not large enough for the Reduce the number of filters in the filter list so that the size
specified number of filters. of the filter list plus the size of the filter header data is less
than or equal to the size of the output buffer. Try the
request again.
83/1999 Incorrect filter header data or incorrect filter in the filter list. Correct the incorrect filter header data or the incorrect filter
If the filter header data is incorrect, the error offset param- in the filter list. Try the request again.
eter will point to the field in error. If a filter in the filter list is
incorrect, the error offset parameter will point to the begin-
ning of the incorrect filter.

12-48 AS/400 System API Reference V4R4

 Set Timer (QOLTIMER) API

Figure 12-55 (Page 2 of 2). Return and Reason Codes for the QOLSETF API
Return /
Reason
Code Meaning Recovery
83/3001 Link not enabled. Correct the communications handle parameter. Try the
request again.
83/3003 One of the following is true of a filter in the filter list. The Do one of the following, and try the request again:
error offset parameter will point to the beginning of the
Ÿ End the job that has already activated the filter
offending filter.
Ÿ Configure the service access point in the token-ring,
Ÿ The filter is already activated by another job using the
Ethernet, wireless, or FDDI line description
same communications line
Ÿ Delete the Ethernet line description, and create another
Ÿ The service access point, specified in the DSAP
Ethernet line description specifying *ETHV2 or *ALL in
address field of the filter, is not configured in the token-
the Ethernet Standard (ETHSTD) parameter
ring, Ethernet, wireless, or FDDI line description
Ÿ Change the service access point in the token-ring,
Ÿ The DSAP address field of the filter contains the null
Ethernet, or wireless line description to non-SNA use
DSAP address (X'00'), but the Ethernet Standard
(*NONSNA)
(ETHSTD) parameter in the Ethernet line description is
not configured as *ETHV2 or *ALL
Ÿ The service access point, specified in the DSAP
address field of the filter, is configured in the token-ring,
Ethernet, wireless, or FDDI line description for SNA use
only (*SNA)
83/3004 Link is enabling. Wait for the enable-complete entry to be sent to the data
queue or user queue. If the link was successfully enabled,
try the request again.
83/3200 All resources are currently in use by asynchronous oper- Wait for at least one of the asynchronous operations to
ations that have not yet completed. complete. Notification of completion of these operations will
be received from the QOLRECV API. Try the request
Note: This return and reason code is only possible for links
again.
using an X.25 communications line. See “Send Data
(QOLSEND) API” on page 12-27 for more information.
83/4001 Link failure, system starting error recovery for this link. Wait for the link to recover. Try the request again.

Error Messages
CPF3C90 E Required Parameter Group:
Literal value cannot be changed. 1 Return code Output Binary(4)
CPF91F0 E Internal system error. 2 Reason code Output Binary(4)
CPF91F1 E User-defined communications application error. 3 Timer set Output Char(8)
CPF9872 E Program or service program &1 in library &2 4 Timer to cancel Input Char(8)
ended. Reason code &3. 5 Qualified queue name Input Char(20)
6 Operation Input Char(1)
7 Interval Input Binary(4)
8 Establish count Input Binary(4)
Set Timer (QOLTIMER) API 9 Key length Input Binary(4)
10 Key value Input Char(256)
11 User data Input Char(60)

Optional Parameter:

12 Queue type Input Char(1)

Threadsafe: No

The Set Timer (QOLTIMER) API either sets or cancels a

timer. Up to 128 timers, each uniquely identified by a name
(timer handle), can be set in the job in which the application
program is running.

Chapter 12. User-Defined Communications Support APIs 12-49

Set Timer (QOLTIMER) API

When the QOLTIMER API is called to set a timer, a timer timers currently set in the job in which the user-defined
handle (timer set parameter) is returned to the application communications application program is running.
program. The timer handle, along with the user data sup-
The content of this parameter is only valid when
plied when the timer was set, is included in the timer-expired
canceling a timer.
entry that is sent to the data queue or user queue when the
specified amount of time for this timer has elapsed. The Qualified queue name
timer is then reestablished, if necessary. INPUT; CHAR(20)
The name and library of the data queue or user queue
For example, suppose a user-defined communications appli-
where the timer-expired entry will be sent when the timer
cation program sets a timer with a five-second interval to be
expires. The first 10 characters specify the name of the
established two times. After five seconds, the timer-expired
data queue or user queue and the second 10 characters
entry for this timer will be sent to the data queue or user
specify the library in which the queue is located. Both
queue specified when the timer was set. The timer will then
entries are left-justified. The special values of *LIBL and
be automatically reestablished, and five seconds later,
*CURLIB may be used for the library name.
another timer-expired entry for this timer will be sent to the
data queue or user queue. See “Timer-Expired Entry” on The content of this parameter is only valid when setting
page 11-3 for the format of the timer-expired entry. a timer.

In addition to setting a timer, the application program can call Operation

the QOLTIMER API to cancel one or all timers currently set INPUT; CHAR(1)
in the job in which the application program is running. User- The timer operation to perform. The valid values are as
defined communications support will implicitly cancel a timer follows:
in the following cases:
X'01' Set a timer.
Ÿ After a timer has expired the specified number of times
X'02' Cancel a timer.
(establish count parameter)
Interval
Ÿ When a job ends that had one or more timers set
INPUT; BINARY(4)
Note: User-defined communications support does not asso-
The number of milliseconds for which to set this timer.
ciate timers with links. If necessary, that association must be
Any value between 1,048 and 3,600,000 may be used.
done by the application.
The content of this parameter is only valid when setting
a timer.
Required Parameter Group
Establish count
Return code
INPUT; BINARY(4)
OUTPUT; BINARY(4)
The number of times this timer will be established. Any
The recovery action to take. See “Return and Reason
value between 1 and 60 may be used. The special
Codes” on page 12-51.
value of -1 may be used to always have this timer estab-
Reason code lished after it expires.
OUTPUT; BINARY(4) The content of this parameter is only valid when setting
The error that occurred. See “Return and Reason a timer.
Codes” on page 12-51.
Key length
Timer set INPUT; BINARY(4)
OUTPUT; CHAR(8) The key length when using a keyed data queue or user
The name of the timer (timer handle) that was set. queue. Any value between 0 and 256 may be used,
TIMER001, TIMER002, ... , TIMER128 are the possible where 0 indicates the data queue or user queue is not
values. keyed.
The content of this parameter is only valid when setting The content of this parameter is only valid when setting
a timer. a timer.

Timer to cancel Key value

INPUT; CHAR(8) INPUT; CHAR(256)
The name of the timer (timer handle) to cancel. The key value when using a keyed data queue or user
TIMER001, TIMER002, ... , TIMER128 may be used as queue.
values. The special value of *ALL (left-justified and The content of this parameter is only valid when setting
padded on right with spaces) may be used to cancel all a timer.

12-50 AS/400 System API Reference V4R4

 Set Timer (QOLTIMER) API

User data Queue type

INPUT; CHAR(60) INPUT; CHAR(1)
The user data that is to be included in the timer-expired The type of queue you specified for the queue name
entry when the timer expires. parameter.
The content of this parameter is only valid when setting D Data queue
a timer. U User queue
Note: This data is treated as character data only and
should not contain pointers. Return and Reason Codes

Optional Parameter
Figure 12-56. Return and Reason Codes for the QOLTIMER API
Return /
Reason
Code Meaning Recovery
0/0 Operation successful. Continue processing.
81/9999 Internal system error detected. Escape message CPF91F0 See messages in the job log for further information. Report
will be sent to the application program when this return and the problem using the ANZPRB command.
reason code is received.
82/1011 Queue type not valid. Correct the queue type parameter. Try the request again.
83/1001 Key length not valid. Correct the key length parameter. Try the request again.
83/1009 Timer operation not valid. Correct the operation parameter. Try the request again.
83/1010 Timer interval not valid. Correct the interval parameter. Try the request again.
83/1011 Number of times to establish timer not valid. Correct the establish count parameter. Try the request
again.
83/3400 Timer not valid on cancel operation. Correct the timer to cancel parameter. Try the request
again.
83/3401 All timers are currently set for the requested set operation. Cancel a timer. Try the request again.
83/3402 Timer not set on cancel operation. Continue processing.

Error Messages CPF91F0 E Internal system error.

CPF9872 E Program or service program &1 in library &2
CPF3C90 E
ended. Reason code &3.
Literal value cannot be changed.

Chapter 12. User-Defined Communications Support APIs 12-51

Set Timer (QOLTIMER) API

12-52 AS/400 System API Reference V4R4

 System Services and Tools

Chapter 13. Debugging of User-Defined Communications Applications

This section is intended to help you debug your user-defined Work with Communications Status
communications applications. It contains information about:
The Work with Job command, Work with Communications
Ÿ System services and tools
Status option, (WRKJOB OPTION(*CMNSTS)) shows the
Ÿ Error codes reported to the application program and enabled links and operation counts for each link. It also
QSYSOPR operation reports information such as the communications handle the
Ÿ Common error list last operation requested, and the total input, output, and
other operations requested. This information is shown for
every link enabled by the job.
System Services and Tools
Display Job Log
There are several tools on the AS/400 system you can use
to debug your user-defined communications application. The Work with Job command, selecting the Display job log
Some of the system provided tools that are useful for devel- option (WRKJOB OPTION(*JOBLOG)) allows you to view the
oping user-defined communications applications include the messages in the job log that help determine the exact cause
following CL commands: of the problem.
Ÿ Program Debug (STRDBG)
Ÿ Work with Job, Work with Communications Status Display Connection Status
(WRKJOB OPTION(*CMNSTS))
The Display Connection Status (DSPCNNSTS) command
Ÿ Work with Job, Display Job Log (WRKJOB shows information about the switched virtual circuits (SVCs)
OPTION(*JOBLOG)) and permanent virtual circuits (PVCs) that are in use by the
Ÿ Display Connection Status (DSPCNNSTS) application using the device description.
Ÿ Display Inbound Routing Data (press F6 (Display Note: The Display Line Description (DSPLIND) command
inbound routing information) following the DSPCNNSTS also shows for each line, the SVCs that are in use, available,
command) or attached to a controller description. This is not true for
PVCs.
Ÿ Check Communications Trace (CHKCMNTRC)
Ÿ Delete Communications Trace (DLTCMNTRC)
Display Inbound Routing Information
Ÿ End Communications Trace (ENDCMNTRC)
Ÿ Print Communications Trace (PRTCMNTRC) Pressing F6 (Display inbound routing information) when the
Display Connection Status display is shown (DSPCNNSTS
Ÿ Start Communications Trace (STRCMNTRC) command) shows the results of the calls to the Set Filter
Ÿ Start System Service Tools (STRSST) (QOLSETF) API. It also helps to determine which device
description has set a filter with duplicate inbound routing
– Work with communications trace
information.
– Work with error log
Ÿ Dump System Object (DMPSYSOBJ) Work with Communications Trace
Using the communications trace function you can obtain
Program Debug information about a communications line. You can access
Program debug (STRDBG) allows you to trace the program the communications trace function through the following CL
and variables, set stops, change variables, and display vari- commands:
ables. You can use this function to verify that the parame- Ÿ Check Communications Trace (CHKCMNTRC)
ters are passed correctly.
Ÿ Delete Communications Trace (DLTCMNTRC)
Ÿ End Communications Trace (ENDCMNTRC)
Ÿ Print Communications Trace (PRTCMNTRC)
Ÿ Start Communications Trace (STRCMNTRC)
For more information on using the communications trace CL
commands, see the Communications Management book.

 Copyright IBM Corp. 1998, 1999 13-1

System Services and Tools

You can also access the communications trace function system, could cause an entry to be generated in the error log
through the system service tools. You can use this function if one of the following conditions are met:
by entering the Start System Service Tools (STRSST)
Ÿ When using a LAN, data is not received by the applica-
command and selecting the option to start a service tool.
tion and exceeds internal threshold values (3 MB).
Using the option to Work with communications trace shows Ÿ When using an X.25 network, data is not received by the
data just as it appears to the network. If the application application and exceeds internal threshold values
requests that data be sent and the request does not appear (128KB).
in the communications trace, the request is rejected. The
return and reason codes, and the error code reported in the For both cases, the associated message in QSYSOPR iden-
parameter list for the Send Data (QOLSEND) API indicates tifies the error log that contains the error log entry. The error
the reason the request was rejected. log entry contains information only.

Work with Error Log Dump System Object to View User Spaces
The error log utility is part of the system service tools. You The Dump System Object (DMPSYSOBJ) command is used
can use it by entering the Start System Service Tools to inspect the user spaces after they are filled in by your
(STRSST) command and selecting the option to start a application. The following examples indicate what the user
service tool. spaces look like for some of the operations.

Some communications errors are reported by the system to User Space to Set a Filter to Route Inbound Data:
the error log. A remote application that is communicating This user space is filled in to activate two X.25 filters which
with a user-defined communications application on the local will route any X.25 call containing X'BB', or X'DD' in the
first byte of call user data (protocol ID byte).
5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:42:ð7 PAGE 1
DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTBUFFER TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:4ð:ð3 SIZE- ðððð22ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAððAðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3C2E4C6 C6C5D94ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTBUFFER \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð2ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ð1ððððð2 ðð1ðð1BB ðððððððð ðððððððð ðððððððð ððððð1DD ðððððððð ðððððððð \ Y t \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ðð1FFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF1D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F5 \QPADEVððð1QSECOFR ðð6625 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F4Fð FðF44ð4ð \ V2R1Mðð9ð1221124ðð4 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-1. User Space to Set a Filter to Route Incoming X.25 Calls

13-2 AS/400 System API Reference V4R4

 System Services and Tools

User Space for X'B000' Operation, Initiating an SVC Ÿ Other facilities (not selected)
Call: The user space below has been filled in to initiate an Ÿ One byte of call user data, X'BB', which is the protocol
SVC call specifying the following: identifier
Ÿ Default packet and window sizes Ÿ X.25 reset not supported by the user-defined commu-
Ÿ D-bit (not selected) nications application program

Ÿ Reverse charging (not selected) Ÿ 16KB is the maximum amount of contiguous data to be
received
Ÿ Fast select (not selected)
Ÿ Automatic flow control value of 32
Ÿ Closed user group (not selected)

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:47:42 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUF CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTPUTBUF TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:36:28 SIZE- ðððð12ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAðð1ðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3D7E4E3 C2E4C64ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTPUTBUF \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð1ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ð2ðððððð FFFFFFFF FFFFFFFF ðððððððð ððððððð8 4ð1ðððð1 ðððððððð ðððððððð \ \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ððððBF SAME AS ABOVE
ððððCð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ððððððð1 BBðððððð ðððððððð \ Y \
ððððEð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð1ðð TO ððð1BF SAME AS ABOVE
ððð1Cð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððð4ððð \ \
ððð1Eð ðð2ððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ððð2ðð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð22ð TO ðððFFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF2D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F7 \QPADEVððð2QSECOFR ðð6627 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F3F6 F2F84ð4ð \ V2R1Mðð9ð1221123628 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-2. User Space to Send an SVC Call

User Space Containing an Incoming X.25 Call, Ÿ No other facilities are requested
Operation X'B201': This user space shows the following: Ÿ One byte of call user data, X'BB', which is the protocol
Ÿ The call is using SVC 005 identifier

Ÿ Both transmit and receive packet sizes are 128 The application received this call because it had set a filter to
Ÿ Both transmit and receive window sizes are 7 indicate to the system that it should route incoming X.25 calls
that have the first byte of call user data (the protocol identi-
Ÿ The calling DTE address is 40100000 fier) equal to X'BB' to the application.
Ÿ The called DTE address is 40200000

Chapter 13. Debugging of User-Defined Communications Applications 13-3

System Services and Tools

5763SS1 V3R1Mð 94ð9ð9 AS/4ðð DUMP ð23ð99/QSYSOPR/QPADEVðð14 ð3/ð7/94 11:57:24 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- INBUFFER CONTEXT- USRDFNCMN
TYPE- \ALL SUBTYPE-\ALL
OBJECT TYPE- SPACE \USRSPC
NAME- INBUFFER TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- ð3/ð7/94 11:53:15 SIZE- ðððððð22ðð
OWNER- QSYSOPR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððððð1DE7Aðð ðððð
SPACE ATTRIBUTES-
ðððððð ððFFFFðð ðððððð6ð 1934C9D5 C2E4C6C6 C5D94ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - INBUFFER \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð2ððð ðð81ðððð ðððððððð ðððððððð \ \ a \
ðððð4ð ðððððððð ðððððððð ððD6ð1DE 73ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ O ú \
SPACE-
ðððððð ððððððð5 ðð8ðððð7 ðð8ðððð7 ðððððððð ððððððð8 4ð1ððððð ðððððððð ðððððððð \ \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ððððBF SAME AS ABOVE
ððððCð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ððððððð1 BBðððððð ðððððððð \ \
ððððEð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð1ðð TO ððð13F SAME AS ABOVE
ððð14ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ð84ð2ððð ðððððððð \ \
ððð16ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð18ð TO ðð1FFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð F1F4D8E2 E8E2D6D7 D94ð4ð4ð FðF2F3Fð F9F9 \QPADEVðð14QSYSOPR ð23ð99 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F3D9F1D4 FðFðF9F4 FðF3FðF7 F1F1F5F3 F1F54ð4ð \ V3R1Mðð94ð3ð7115315 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
USAGE-
ðððððð D8E2E8E2 D6D7D94ð 4ð4ðD9C3 C8C1E2F3 F2Fð \QSYSOPR RCHAS32ð \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-3. User Space Containing an Incoming X.25 Call

User Space to Accept an Incoming X.25 Call, Oper-

ation X'B400': This user space was filled in to accept the
incoming call, request default packet and window sizes, and
no other additional facilities. The a maximum amount of con-
tiguous data is set at 16KB and the automatic flow control is
set at 32.

13-4 AS/400 System API Reference V4R4

 System Services and Tools

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:48:ð6 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTBUFFER TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:4ð:ð3 SIZE- ðððð22ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAððAðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3C2E4C6 C6C5D94ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTBUFFER \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð2ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ðððððððð FFFFFFFF FFFFFFFF ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ððð1BF SAME AS ABOVE
ððð1Cð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððð4ððð \ \
ððð1Eð ðð2ððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ððð2ðð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð22ð TO ðð1FFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF1D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F5 \QPADEVððð1QSECOFR ðð6625 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F4Fð FðF44ð4ð \ V2R1Mðð9ð1221124ðð4 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-4. User Space to Accept an Incoming X.25 Call

User Spaces for Sending Data, Operation X'0000': Note: This link was enabled, specifying a data unit size of
Two user spaces are shown below. The first is the output 512 bytes.
buffer and the second is the output buffer descriptor.

The user spaces below are filled in to send three data units
of 512 bytes each. The first two data units have the more
data indicator turned on, indicating that all the data units are
contiguous.

Chapter 13. Debugging of User-Defined Communications Applications 13-5

System Services and Tools

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:55:19 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUF CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTPUTBUF TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:36:28 SIZE- ðððð12ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAðð1ðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3D7E4E3 C2E4C64ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTPUTBUF \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð1ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð FðF1ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð1 \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ððð1FF SAME AS ABOVE
ððð2ðð FðF2ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð2 \
ððð22ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð24ð TO ððð3FF SAME AS ABOVE
ððð4ðð FðF3ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð3 \
ððð42ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð44ð TO ðððFFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF2D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F7 \QPADEVððð2QSECOFR ðð6627 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F3F6 F2F84ð4ð \ V2R1Mðð9ð1221123628 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-5. User Space (Buffer) to Send Three Data Units

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:55:58 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUFD CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTPUTBUFD TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:36:27 SIZE- ððððð4ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ðð9FFEðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3D7E4E3 C2E4C6C4 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTPUTBUFD \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ððððð2ðð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ð2ððð1ðð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð2ð ð2ððð1ðð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð4ð ð2ðððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð6ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð8ð TO ððð1FF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF2D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F7 \QPADEVððð2QSECOFR ðð6627 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F3F6 F2F74ð4ð \ V2R1Mðð9ð1221123627 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-6. User Space (Descriptor Element) to Describe the Three Data Units

13-6 AS/400 System API Reference V4R4

 System Services and Tools

User Spaces for Receiving Data, Operation considered to be logically contiguous to the application
X'0001': Two user spaces are shown below. The first is program.
the input buffer and the second is the input buffer descriptor. Note: This link was enabled specifying a data unit size of
1024 bytes. The sending system sent the data in data unit
The user spaces below are filled in showing that 2 data units sizes of 512 bytes and they were combined into the 1024
were received. The first data unit has the more data indi- byte data unit size by the local system. The data unit size is
cator turned on in the buffer descriptor for the data unit. This not negotiated end-to-end, neither is the maximum amount of
means that the X.25 more indicator was turned on in all the contiguous data or the automatic flow control. Because the
X.25 packets that this data unit contains. The second data values are important, each application should be aware of
unit does not have the more data indicator turned on, indi- what the other application has specified for each value.
cating that the last X.25 packet in the data unit had the X.25 Refer to “Sending and Receiving Data Packets” on
more indicator turned off. The first and second data unit are page 10-23 for more information.

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:59:33 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- INBUFFER CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- INBUFFER TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:4ð:ð3 SIZE- ðððð22ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAðð4ðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934C9D5 C2E4C6C6 C5D94ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - INBUFFER \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð2ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð FðF1ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð1 \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ððð1FF SAME AS ABOVE
ððð2ðð FðF2ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð2 \
ððð22ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð24ð TO ððð3FF SAME AS ABOVE
ððð4ðð FðF3ðððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ð3 \
ððð42ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ððð44ð TO ðð1FFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF1D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F5 \QPADEVððð1QSECOFR ðð6625 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F4Fð FðF34ð4ð \ V2R1Mðð9ð1221124ðð3 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-7. User Space (Buffer) Containing the Three Data Units

Chapter 13. Debugging of User-Defined Communications Applications 13-7

System Services and Tools

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 12:59:41 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- INBUFFERD CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- INBUFFERD TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:4ð:ð3 SIZE- ððððð4ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAðð2ðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934C9D5 C2E4C6C6 C5D9C44ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - INBUFFERD \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ððððð2ðð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ð4ððð1ðð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð2ð ð2ðððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
ðððð4ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð6ð TO ððð1FF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF1D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F5 \QPADEVððð1QSECOFR ðð6625 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F4Fð FðF34ð4ð \ V2R1Mðð9ð1221124ðð3 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-8. User Space (Descriptor Element) Describing the Three Data Units

User Space to Clear a Connection or Call, Opera-

tion X'B100': This user space was filled in to end an SVC
connection or clear an incoming call. No facilities or clear
user data are requested with this, but cause and diagnostic
codes are specified (these are not ISO or SNA codes).

5738SS1 V2R1Mð 91ð524 AS/4ðð DUMP ðð6625/QSECOFR/QPADEVððð1 12/21/9ð 13:14:48 PAGE 1

DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER CONTEXT-USRDFNCMN
OBJTYPE- \USRSPC
OBJECT TYPE- SPACE \USRSPC
NAME- OUTBUFFER TYPE- 19 SUBTYPE- 34
LIBRARY- USRDFNCMN TYPE- ð4 SUBTYPE- ð1
CREATION- 12/21/9ð 12:4ð:ð3 SIZE- ðððð22ðð
OWNER- QSECOFR TYPE- ð8 SUBTYPE- ð1
ATTRIBUTES- ð8ðð ADDRESS- ððAððAðð ðððð
SPACE ATTRIBUTES-
ðððððð ðððððð8ð ðððððð6ð 1934D6E4 E3C2E4C6 C6C5D94ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ - OUTBUFFER \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð Eððððððð ðððððððð ðððð2ððð ðð8ððððð ðððððððð ðððððððð \ \ \
ðððð4ð ðððððððð ðððððððð ððð5ðð4D 42ððð4ðð ðððððððð ðððððððð ðððððððð ðððððððð \ (a \
SPACE-
ðððððð ððððBEBE ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ XX \
ðððð2ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð \ \
LINES ðððð4ð TO ðð1FFF SAME AS ABOVE
POINTERS-
NONE
OIR DATA-
TEXT-
ðððððð D8D7C1C4 C5E5FðFð FðF1D8E2 C5C3D6C6 D94ð4ð4ð FðFðF6F6 F2F5 \QPADEVððð1QSECOFR ðð6625 \
SERVICE-
ðððððð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ðF14ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ 1 \
ðððð2ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ðE5 F2D9F1D4 FðFðF9Fð F1F2F2F1 F1F2F4Fð FðF44ð4ð \ V2R1Mðð9ð1221124ðð4 \
ðððð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð \ \
ðððð6ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð 4ð4ð4ð4ð ðððððððð ðððððððð \ \
ðððð8ð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð ðððððððð 4ð4ððððð ðððððððð \ \
ððððAð ðððððððð ðððððððð \ \
END OF DUMP
\ \ \ \ \ E N D O F L I S T I N G \ \ \ \ \

Figure 13-9. User Space to Send an SVC Clear

13-8 AS/400 System API Reference V4R4

 Error Codes

defined communications APIs, see Chapter 12, “User-

Error Codes Defined Communications Support APIs” on page 12-1.
The system and user-defined communications support
reports important information that is useful for determining Local Area Network (LAN) Error Codes
recovery actions when an error occurs. This information is
referred to as error codes that are reported either to the job Figure 13-10 shows the valid hexadecimal codes your appli-
log or to the QSYSOPR message queue. For a complete list cation can receive as a result of a call to the QOLSEND API
of the messages that are signaled by the user-defined com- using operation code X'0000'. The codes indicate that the
munications APIs, see “Messages” on page 10-27. data was never sent on the line. Associated with these error
codes is a message in QSYSOPR, indicating the device
In some cases error codes are reported to your application in description that caused the error, and the error code. After
the error specific parameter. The following sections list the receiving the error code, the link will still be enabled and
valid error codes. Some of the error codes represent actual usable.
coding errors, others only report additional information. For
information about the error codes for the individual user- These error codes indicate to your application that a coding
error was made and should be corrected.

Figure 13-10. Error Codes Received While Sending Data over LAN
Error Code Description Cause
3300 2A55 Routing length not valid Routing length is not valid, or length does not equal
length in routing field.
3300 2A5D Maximum frame size limit exceeded Length of data is greater than maximum frame size
supported by the source SAP
5300 2A7B Access Control not valid Access Control specified is not supported
3300 2AA9 SAP address not valid SAP address is not configured in the line description
3300 2AA9 SAP address not valid SAP address is not configured in the line description
3300 2AD4 Data length too small (Ethernet Version 2 only) Data must be at least 48 bytes long (46 bytes of data,
plus 2 bytes for the Ethernet type field)
3300 2AD5 Ethernet type field is not valid (Ethernet Version 2 Ethernet type field (first two bytes of data)
only)

X.25 Error Codes returns the results of the open connection request opera-
tion, X'B101'
Figure 13-11 shows the valid error codes your application
Ÿ The connection failure indication, reported by operation
can receive as a result of
X'B301'
Ÿ A call to the QOLSEND API with operation X'B400' to
accept an SVC call These error codes indicate to your application that a coding
error was made, or a failure condition occurred.
Ÿ A call to the Receive Data (QOLRECV) API which

Figure 13-11 (Page 1 of 2). Error Codes Reported on X'B001', X'B301', and X'B400' Operations
Error Code Description Cause
1200 3122 Outgoing channel not available The logical channel is still active and in the process of
being deactivated
3200 3050 Restart in progress Temporary condition; retry operation
3200 3172 Outgoing channel not available Temporary condition; retry operation
3200 3368 Remote address length not valid Remote address length not supported by the network
3200 3384 Facility field error A facility was encoded incorrectly or a duplicate facility
was encoded
3200 3388 Facility field too long The total length of the facilities, which includes user-
specified facilities, the NUI facility from the line
description, and system generated facilities, exceeded
X.25 limits (109 bytes)
3200 338C Response restricted by fast select User data is not allowed with restriction

Chapter 13. Debugging of User-Defined Communications Applications 13-9

Error Codes

Figure 13-11 (Page 2 of 2). Error Codes Reported on X'B001', X'B301', and X'B400' Operations
Error Code Description Cause
3200 3394 User data not allowed User data is not allowed on the call accept if fast
select was not requested.
3200 33CC Call user data length not valid The length of call user data is greater than 16 and fast
select is not selected.
4200 3210 Reset request transmitted The virtual circuit was reset by the local system.
Refer to cause and diagnostic codes to determine
recovery.
4200 3220 Clear request transmitted The virtual circuit was cleared by the local system.
Refer to cause and diagnostic codes to determine
recovery.
4200 3222 Clear request transmitted The virtual circuit was cleared by the local system
because there was a problem with the packet size in
the call accept. This is either a configuration problem
or a network problem. Verify that the default packet
size in the line description is correct.
4200 3224 Clear request transmitted The virtual circuit was cleared by the local system
because there was a problem with the window size in
the call accept. This is either a configuration problem
or a network problem. Verify that the default window
size in the line description is correct.
4200 3230 Restart request transmitted The virtual circuit was cleared by the local system.
Refer to cause and diagnostic codes for more informa-
tion.
4200 3280 Time-out on call Call timed out
4600 3134 Clear indication was received The virtual circuit was cleared by either the remote
system or the network. Refer to cause and diagnostic
codes for more information.
4600 3138 Restart indication received Temporary condition; refer to the cause and diagnostic
codes reported to correct the problem, then retry the
operation

Figure 13-12 shows the valid error codes your application These error codes indicate to your application that the con-
can receive as a result of a call to the QOLRECV API with nection was cleared or reset for the following reasons.
an operation code returned as X'B101'.

Figure 13-12. Error Codes Reported on the X'B101' Operation

Error Code Description Cause
3200 3388 Facility field too long The total length of the facilities, which includes user-
specified facilities, the NUI facility from the line
description, and system generated facilities, exceeded
X.25 limits (109 bytes)
3200 3394 User data not allowed User data is not allowed when fast select is not
selected.
3200 33CC Call user data length not valid The length of call user data is greater than 16 and fast
select is not selected.
4200 3240 Time-out on reset The clear request resulted in an X.25 reset, which
timed out
4200 3284 Time-out on clear The remote system did not respond to the CLEAR
within the time-out value
4600 3134 Clear indication was received The virtual circuit was cleared by either the remote
system or the network. Refer to cause and diagnostic
codes for more information.

13-10 AS/400 System API Reference V4R4

 Common Errors and Messages

Figure 13-13 on page 13-11 shows the valid error codes These error codes indicate to your application that the con-
your application can receive as a result of a call to the nection was cleared or reset for the following reasons.
QOLRECV API, returning the operation code, X'BF01'.

Figure 13-13. Error Codes Reported on the X'BF01' Operation

Error Code Description Cause
3200 3050 Network Restart in progress Temporary condition; connection is no longer active.
3200 3A0C Close pending The virtual circuit is being closed.
3200 3A0D Reset pending The virtual circuit is in the process of being reset by
either the remote system or the network.
4200 3210 Reset packet transmitted A Reset packet was transmitted from the local system.
4200 3240 Time-out on reset The clear request resulted in an X.25 reset, which
timed out
4600 3130 Reset indication was received The virtual circuit received a reset by either the
remote system or the network. Refer to cause and
diagnostic codes for more information.
4600 3134 Clear indication was received The virtual circuit was cleared by either the remote
system or the network. Refer to cause and diagnostic
codes for more information.

Figure 13-14 shows the valid error codes your application These error codes indicate to your application that the con-
can receive as a result of a call to the QOLSEND API with nection was cleared or reset for the following reasons.
an operation code returned as X'0000'.

Figure 13-14. Error Codes Resulting from a X'0000' Operation

Error Code Description Cause
3200 3050 Network restart in progress Temporary condition; connection is no longer active.
3200 336A Q/M bit sequence not valid If the data is qualified, the Q bit must be set for all
data units.
3200 33C8 Data length not valid The length of the packet is not supported for this
virtual circuit.
3200 3A0C Close pending The virtual circuit is being closed.
3200 3A0D Reset pending The virtual circuit is in the process of being reset by
either the remote system or the network.
4200 3284 Interrupt timed out The local DTE sent an interrupt packet. The response
to this packet was not received within the time-out
period, and the connection has been reset by the
AS/400 system.
4600 3130 Reset indication was received The virtual circuit received a reset by either the
remote system or the network. Refer to cause and
diagnostic codes for more information.
4600 3134 Clear indication was received The virtual circuit was cleared by either the remote
system or the network. Refer to cause and diagnostic
codes for more information.

Common Errors and Messages Parameter Errors:

Ÿ Switching use of connection identifiers (PCEP and
This section shows some of the common errors that you or UCEP)
your application programmer may encounter. Some of these
Ÿ Switching use of timer handles
errors are detected by the APIs and reported to the applica-
tion by the unsuccessful return and reason codes returned Ÿ Not encoding parameters if not used
on each API. Other errors are program design errors, that Ÿ Operation code not in hexadecimal format
your application programmer must detect and correct. The
errors are listed by category: Ÿ Parameter not declared with proper length

Chapter 13. Debugging of User-Defined Communications Applications 13-11

Common Errors and Messages

User Space Errors: Send Data (QOLSEND) API Errors:

Ÿ Not encoding reserved space for fields not used Ÿ After a call to the QOLSEND API with an operation code
of X'B000', X'B100', or X'BF00', the application
Ÿ Not initializing user space fields as necessary.
should then call the QRCVDTAQ API and wait for
The output user spaces can only be changed by the incoming data to be placed on the queues. The success
user-defined communications application. Operations or failure of these operations is reported through the
are validated on each request. If there are fields that QOLRECV API with operation codes of X'B001',
the current operation does not use, they should be set to X'B101' and X'BF01', respectively.
contain zeros with X'00', to prevent a template error
Ÿ Using the wrong data unit descriptor for the data unit
resulting from information on the previous operation still
(each data unit has its own descriptor)
being in the user space. Not resetting the indicators in
the output buffer descriptors on each operation and not
Enable Link (QOLELINK) API Errors:
zeroing out fields before making a call request may
result in template errors. Ÿ User space names not unique
Ÿ Queue not created before program call
Queue Errors:
Ÿ Line description not created or incorrect prior to program
Ÿ Queue not created
call
Ÿ Queue created with different key length than specified in
the parameter list of the Enable Link (QOLELINK) API Query Line Description (QOLQLIND) API Errors:
Ÿ Parameter buffer not large enough
Receive Data (QOLRECV) API Errors:
Ÿ Not checking the more data output parameter and
issuing another call to the QOLRECV API
Ÿ Not calling the QOLSETF API to set the filter to route
inbound data to the application
Ÿ Using the wrong data unit descriptor for the data unit
(each data unit has its own descriptor)

13-12 AS/400 System API Reference V4R4

 Using the Data Stream Translation APIs

Chapter 14. Data Stream Translation APIs

Data Stream Translation ┌────────┐ ┌───────────┐ ┌────────┐

APIs—Introduction │ 327ð │ │ │ │ 525ð │
│ data │%─────│ Formatted │%─────│ data │
This section describes the data stream translation application │ stream │ │ buffer │ │ stream │
│ │ │ │ │ │
program interfaces (APIs) that allow your user-written appli- └────────┘ └───────────┘ └────┬───┘
cations access to the data stream translation routines for & │
5250, 3270, and formatted buffer display data streams. Only └───────────────────────────────────┘
display device data streams are supported by this API. For Figure 14-2. Translations for Input Operations
more information on display data streams using formatted
buffers, see the SNA Upline Facility Programming book. The
data stream translation APIs are listed in alphabetical order
following a brief discussion of the function they provide and
Using the Data Stream Translation APIs
the considerations for using them in a user-written application
The data stream APIs consist of three program calls that are
program.
shown in the following list:
Using the data stream APIs, your applications can: End Data Stream Translation Session
Ÿ Translate from a 3270 output data stream to a formatted (QD0ENDTS) ends a session for data stream
buffer translation.
Start Data Stream Translation Session
Ÿ Translate from a 3270 output data stream to a 5250 data (QD0STRTS) starts a session for data stream
stream translation.
Ÿ Translate from a formatted output buffer to a 5250 data Translate Data Stream
stream (QD0TRNDS) translates a data stream in one
format to another format.
Ÿ Translate from a formatted input buffer to a 3270 data
stream When your application calls the QD0STRTS API, a trans-
Ÿ Translate from a 5250 input data stream to a formatted lation session is opened using a user-specified device as a
buffer basis for the translation parameters. You can open as many
sessions as you need, because for every session a unique
Ÿ Translate from a 5250 input data stream to a 3270 data
translation session handle is passed back to your application.
stream
Ÿ Translate from a 5250 read screen format to a 3270 A call to the QD0TRNDS API does the actual data stream
read buffer format translation using the specified parameters to indicate the type
of translation. Multiple translation sessions can be active at
Ÿ Translate from a 5250 read screen with extended attri-
the same time. A translation session remains open, that is
butes to a 3270 read buffer format
the handle remains valid, until the QD0ENDTS API is called
The following figures show the translation options available using that handle or the job that called QD0STRTS ends.
when your application calls the data stream translation APIs. The final call to the QD0ENDTS API closes or ends the
translation session.
┌────────┐ ┌───────────┐ ┌────────┐ Note: If you are using the same translation parameters for
│ 327ð │ │ │ │ 525ð │ many translations, you may decide to use only one
│ data │─────5│ Formatted │─────5│ data │ QD0STRTS call for each unique set of parameters to
│ stream │ │ buffer │ │ stream │ enhance performance.
│ │ │ │ │ │
└───┬────┘ └───────────┘ └────────┘
│ &
└───────────────────────────────────┘
Programming Restrictions
Figure 14-1. Translations for Output Operations The 5250 data streams generated by the QD0TRNDS API
for your application have the following restrictions:
Ÿ Read commands are not added to the end of a data
stream. Your application is responsible for sending
Read modified data tag (MDT) fields to the destination
display.
Ÿ If the device for which the data stream is intended does
not support data in row 1, column 1 then this location is
restricted from use in the input field.

 Copyright IBM Corp. 1998, 1999 14-1

Start Data Stream Translation Session (QD0STRTS) API

Ÿ The number of input fields is dependent on the type of CPF5D58 E

work station controller. The following is a list of the Translation session handle parameter value not
maximum number of input and output fields allowed per valid.
device. CPF5D67 E
Severe error occurred while addressing param-
126 3270 display station
eter list.
255 5250 local display station
CPF9872 E Program or service program &1 in library &2
126 5250 pass-through
ended. Reason code &3.
126 5251 display station
230 5294 Remote Control Unit
255 5394 Remote Control Unit
255 5494 Remote Control Unit Start Data Stream Translation Session
254 Client Access running work station func- (QD0STRTS) API
tion
Ÿ Fields that are detectable by light pens are not sup-
ported. Required Parameter Group:

1 Translation session handle Output Char(16)

There are some 3270 data stream commands, orders, and
2 Display device name Input Char(10)
attributes that are not supported. For a list of the 3270 data 3 Default screen size Input Char(10)
stream commands, orders, and attributes that are supported, 4 Alternate screen size Input Char(10)
see the 3270 Device Emulation Support book. 5 Error code I/O Char(*)

All parameter values must be uppercased and left justified. Threadsafe: No

End Data Stream Translation Session The Start Data Stream Translation Session (QD0STRTS) API
initiates a session for data stream translation. Your applica-
(QD0ENDTS) API tion can start as many translation sessions as you need.

Required Parameter Group: Authorities and Locks

1 Translation session handle Input Char(16)
Device Authority
2 Error code I/O Char(*) The user must have at least *USE authority to
the device specified in the display device
Threadsafe: No name parameter.

The End Data Stream Translation Session (QD0ENDTS) API Required Parameter Group
ends a session for data stream translation.
Translation session handle
OUTPUT; CHAR(16)
Required Parameter Group The name of the translation session. This name is sup-
Translation session handle plied to your application so that you can keep track of a
INPUT; CHAR(16) particular session. It is also required that you pass this
name to the other data stream APIs.
The name of the translation session. This name is
returned to your application following the call to the Display device name
QD0STRTS API. INPUT; CHAR(10)

Error code The name of the 5250 device for which the translation is
I/O; CHAR(*) being done. The 5250 data stream that is generated
depends on the capabilities of the display device. You
The structure in which to return error information. For can specify the following values:
the format of the structure, see “Error Code Parameter”
on page 2-6. Name The name of a display device that is
known to the system.

Error Messages Note: An error will occur if the job you

are using for data stream translation is
CPF3C90 E not authorized to the device you specify.
Literal value cannot be changed. *REQUESTER
CPF3CF1 E The display device that is associated with
Error code parameter not valid. this job is to be used.

14-2 AS/400 System API Reference V4R4

 Translate Data Stream (QD0TRNDS) API

Note: An error will occur if there is no Error code

display device associated with this job. I/O; CHAR(*)
For example, the job is a batch job.
The structure in which to return error information. For
*BASIC The display device is assumed to have
the format of the structure, see “Error Code Parameter”
the lowest common characteristics. The
on page 2-6.
following characteristics are assumed:
Ÿ The display is monochrome.
Error Messages
Ÿ The display has a screen size of
CPF3C90 E
24x80. If a larger screen size is
Literal value cannot be changed.
specified when *BASIC is specified
CPF3CF1 E
for the display device name, an error
Error code parameter not valid.
occurs.
CPF5D50 E
Ÿ Input in row 1, column 1 is not sup- Display device description &1 not found.
ported. CPF5D51 E
Ÿ The Home key does not work like the Device &1 is not a display device.
3270 home key. CPF5D52 E
Not authorized to display device &1.
Ÿ The maximum number of input fields CPF5D5B E
is 126. Value &1 for default screen size parameter not
Ÿ The language is defaulted to the Key- valid.
board Type (QKBDTYPE) system CPF5D61 E
value. Value for display device parameter not valid.
CPF5D66 E
Ÿ The display does not support
Value for alternate screen size parameter not
extended attributes.
valid.
CPF5D67 E
Note: The full capabilities of the device can be deter-
Severe error occurred while addressing param-
mined only if a 5250 query has been sent to the device.
eter list.
The 5250 query is sent the first time a user signs on
CPF5D68 E
after the device is varied on. The results remain in
Default screen size parameter is not valid.
effect until the device is varied off. If no one has signed
CPF5D69 E
on since the device was varied on, some of the charac-
Alternate screen size parameter is not valid.
teristics will default to those assumed for *BASIC display
CPF9872 E Program or service program &1 in library &2
devices.
ended. Reason code &3.
Default screen size
INPUT; CHAR(10)
The size of the screen for the selected display device. Translate Data Stream (QD0TRNDS) API
Either this value or the alternate screen size value is
used depending on the command used in the 3270 data
stream. The possible screen sizes are: Required Parameter Group:

024X080 24 lines by 80 columns 1 Translation session handle Input Char(16)

027X132 27 lines by 132 columns 2 To buffer Output Char(*)
*DEVMAX The maximum screen size allowed by the 3 To buffer output length Output Binary(4)
device 4 To buffer length Input Binary(4)
5 To buffer type Input Char(10)
Alternate screen size 6 From buffer Input Char(*)
INPUT; CHAR(10) 7 From buffer length Input Binary(4)
8 From buffer type Input Char(10)
The alternate size of the screen for the selected display 9 Operation Input Char(1)
device. Either this value or the default screen size value 10 Error code I/O Char(*)
is used depending on the command used in the 3270
data stream. The possible screen sizes are: Threadsafe: No

024X080 24 lines by 80 columns

027X132 27 lines by 132 columns The Translate Data Stream (QD0TRNDS) API translates data
*DEVMAX The maximum screen size allowed by the from one format to another format. The data formats depend
device on the parameter values you specify.

Chapter 14. Data Stream Translation APIs 14-3

Translate Data Stream (QD0TRNDS) API

Required Parameter Group 5250RSE Contains a 5250 data stream that results
from a 5250 Read Screen with Extended
Translation session handle Attributes command
INPUT; CHAR(16) 3270 Contains a 3270 data stream
The name of the translation session. This name is *FORMAT Contains a formatted buffer for the data.
returned to your application following the call to the See the SNA Upline Facility Programming
QD0STRTS API. book to determine the format of the buffer
header.
To buffer
OUTPUT; CHAR(*) See Figure 14-3 for a list of the allowable combinations
of this parameter with the operations and to buffer type
The buffer used to contain the output of the data stream parameters.
translation. This value should be large enough to
contain the expected results. Operation
INPUT; CHAR(1)
To buffer output length
OUTPUT; BINARY(4) Indicates whether the data to be translated is input or
output data. You can specify the following values:
The length of the translated data that is placed in the to
buffer parameter. I The data to be translated is for an input
operation
To buffer length O The data to be translated is for an output
INPUT; BINARY(4) operation
The length of the buffer that is available for output.
See Figure 14-3 for a list of the allowable combinations
To buffer type of this parameter with the to buffer type and from buffer
INPUT; CHAR(10) type parameters.
The type of data to be put into the to buffer parameter. Error code
The possible values are: I/O; CHAR(*)
5250 Create a 5250 data stream The structure in which to return error information. For
3270 Create a 3270 data stream the format of the structure, see “Error Code Parameter”
3270RB Create a 3270 data stream for the data on page 2-6.
stream that is expected in response to a
3270 Read Buffer command The following table lists the valid combinations of the from
*FORMAT Create a formatted buffer for the data. buffer type, to buffer type, and operations parameters.
See the SNA Upline Facility Programming
book to determine the format of the buffer Figure 14-3. Valid Parameter Combinations
header. Operation From Buffer To Buffer Type
Type
See Figure 14-3 for a list of the allowable combinations
of this parameter with the operations and from buffer O 3270 *FORMAT
type parameters. O 3270 5250

From buffer O *FORMAT 5250

INPUT; CHAR(*) I 5250 *FORMAT
The buffer that contains the data to be translated. I 5250 3270
I *FORMAT 3270
From buffer length
INPUT; BINARY(4) I 5250RS 3270RB

The length of the data contained in the from buffer I 5250RSE 3270RB
parameter.

From buffer type Error Messages

INPUT; CHAR(10)
CPF3C90 E
The type of data that is contained in the from buffer Literal value cannot be changed.
parameter. The possible values are: CPF3CF1 E
5250 Contains a 5250 data stream Error code parameter not valid.
5250RS Contains a 5250 data stream that results CPF5D53 E
from a 5250 Read Screen command To and from buffers overlap.
CPF5D54 E
Value &1 for operation parameter not valid.

14-4 AS/400 System API Reference V4R4

 Translate Data Stream (QD0TRNDS) API

CPF5D55 E X'0021' A set buffer address order is

Value &1 is not valid for the To buffer type missing after a row-column AID
parameter. code.
CPF5D56 E X'0022' A set buffer address order that
Value &1 is not valid for the From buffer type was not valid was found in the
parameter. data stream.
CPF5D57 E X'D030' A data stream resulting from a
Combination of parameter values not valid. Read Screen with Extended Attri-
CPF5D58 E butes command was specified
Translation session handle parameter value not for a display device that does not
valid. support extended attributes.
CPF5D59 E CPF5D5E E
Value &1 for from buffer length parameter not Return code in formatted buffer indicates error.
valid. Codes returned in this message are listed in
CPF5D5A E SNA Upline Facility Programming.
Value &1 for the to buffer length parameter not CPF5D5F E
valid. Data integrity error in from buffer. The error
CPF5D5C E code for the translation was &1. The possible
3270 data stream in from buffer not valid. error codes are:
An error was found while translating the 3270
X'0023' Character not valid.
data stream in the from buffer. The error code
X'0050' Shift out (X'0E') and shift in
(X'0F') not correctly balanced in
for translation was &1.
a DBCS session.
X'0002' A 3270 command or order that is
not supported or not valid was
X'0051' Shift out (X'0E') and shift in
(X'0F') in a DBCS field.
detected in the data stream.
X'0003' A parameter or address that is
X'0052' The dead position in a DBCS
field is not null.
not valid was detected in the
3270 data stream.
X'0053' A DBCS character is not valid.
CPF5D60 E
X'0004' Excess fields were detected in
To buffer not large enough for translation
the data stream. A certain
output.
number of these fields are
CPF5D62 E
allowed based on the device
Error occurred in translation routines.
specified on the QD0STRTS call.
CPF5D63 E
This number of fields was
Data integrity error in formatted buffer. The
exceeded.
error code for the translation was &1. The pos-
X'0021' A set buffer address order is
sible error codes are:
missing after a row-column AID
code.
X'0023' Character not valid.
X'0863' A character set attribute that is
X'0050' Shift out (X'0E') and shift in
(X'0F') not correctly balanced in
not valid was found in the data
a DBCS session.
stream.
CPF5D5D E
X'0051' Shift out (X'0E') or shift in
(X'0F') in a DBCS field.
5250 data stream in from buffer not valid.
X'0052' The dead position in a DBCS
An error was found while translating the 5250 field is not null.
data stream in the from buffer. The error code X'0053' A DBCS character is not valid.
for the translation was &1. CPF5D64 E
X'0001' A 5250 AID code that was not To buffer length not valid for to buffer.
correct was found in the data CPF5D65 E
stream. From buffer length not valid for from buffer.
X'0020' A cursor position that was not CPF5D67 E
valid was detected in the 5250 Severe error occurred while addressing param-
data stream. eter list.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.

Chapter 14. Data Stream Translation APIs 14-5

Translate Data Stream (QD0TRNDS) API

14-6 AS/400 System API Reference V4R4

 Close Path (QzdmClosePath) API

Chapter 15. OptiConnect APIs

OptiConnect APIs—Introduction
Required Parameter Group:
The OptiConnect APIs are used to move user data between
1 Request variable Input Char(*)
two or more AS/400 systems, which are connected by the
2 Length of request variable Input Binary(4)
OptiConnect fiber-optic bus. The OptiConnect APIs require 3 Format name of request Input Char(8)
that the OptiConnect hardware and software products have variable
been installed on all of the systems that will be used for com- 4 Error code I/O Char(*)
munications. A maximum of 32KB (where KB equals 1024
bytes) of data may be transferred in a single send or receive Library Name/Service Program: QSOC/QZDMMDTA
function.
Threadsafe: No
Note: To use these APIs, you need the OptiConnect for
OS/400 feature.
The Close Path (QzdmClosePath) API is used to close an
The OptiConnect APIs include the following: OptiConnect path. The Close Path (QzdmClosePath) API
Close Path (QzdmClosePath) closes an OptiConnect should be performed after the path is no longer needed to
path. free the system resources associated with the path.
Close Stream
The system that initiated the last transaction, by using the
(QzdmCloseStream) closes an OptiConnect
Send Request (QzdmSendRequest) API, should be the
stream.
system that closes the path after the transaction is completed
Open Path (QzdmOpenPath) opens an OptiConnect path.
with the Receive Response (QzdmReceiveResponse) API. If
Open Stream (QzdmOpenStream) opens an OptiConnect
the system that received the request using the Receive
stream.
Request (QzdmReceiveRequest) API is the system that
Receive Control
closes the path after issuing the Send Response
(QzdmReceiveControl) receives a control
(QzdmSendResponse) API, then unpredictable results may
message on an OptiConnect stream.
occur. This is due to the Close Path (QzdmClosePath) API
Receive Request
being able to close the path before the response is actually
(QzdmReceiveRequest) receives a request or
received by the other system that uses the Receive
a message over an OptiConnect path.
Response (QzdmReceiveResponse) API.
Receive Response
(QzdmReceiveResponse) receives an After the Close Path (QzdmClosePath) API has been issued,
acknowledgement and the response data over the other system should complete the close sequence by
an OptiConnect path. issuing the Receive Control (QzdmReceiveControl) API to
Send Request receive the close path message from the closing system.
(QzdmSendRequest) sends a request or a
message over an OptiConnect path.
Send Response Restrictions
(QzdmSendResponse) sends an acknowl-
edgement and the response data over an The following restrictions apply:
OptiConnect path. Ÿ The OptiConnect QSOC subsystem must be started on
Wait Message both the local and remote systems prior to calling this
(QzdmWaitMessage) waits for a message on API.
an OptiConnect stream.
Ÿ A stream must be opened to the OptiConnect device
The detailed API descriptions are presented in alphabetical driver on the local system by using the Open Stream
order. (QzdmOpenStream) API prior to calling this API.
Ÿ A path must be opened to the remote system by using
the Open Path (QzdmOpenPath) API prior to calling this
Close Path (QzdmClosePath) API API.

Authority and Locks

Service Program Authority
*EXECUTE

 Copyright IBM Corp. 1998, 1999 15-1

Close Stream (QzdmCloseStream) API

Required Parameter Group CPF3C90 E

Literal value cannot be changed.
Request variable CPF3CF1 E
INPUT; CHAR(*) Error code parameter not valid.
The request variable structure that describes the input CPF9872 E Program or service program &1 in library &2
for the Close Path (QzdmClosePath) API. ended. Reason code &3.
CPFADF0 E
Length of request variable The OptiConnect QSOC subsystem must be
INPUT; BINARY(4) active.
The length of the request variable, in bytes. The length CPFADF1 E
of the request variable must be at least equal to the OptiConnect communication error.
length of the input format, and less than or equal to the CPFADF3 E
maximum length of 4KB. OptiConnect path not valid or closed.
CPFADF5 E
Format name of request variable OptiConnect API internal error, function code
INPUT; CHAR(8) &1, return code &2.
The format of the information that is provided as input CPFADF6 E
for the Close Path (QzdmClosePath) API. The format Request variable not valid, reason code &1.
CPTH0100 is the only supported format used by this API
for the request variable. See “CPTH0100 Format” for
more information on the CPTH0100 format. Close Stream (QzdmCloseStream) API
Error code
I/O; CHAR(*)
Required Parameter Group:
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” 1 Request variable Input Char(*)
2 Length of request variable Input Binary(4)
on page 2-6.
3 Format name of request Input Char(8)
variable
CPTH0100 Format 4 Error code I/O Char(*)

The following table defines the information required for Library Name/Service Program: QSOC/QZDMMDTA
format CPTH0100.
Threadsafe: No
Offset
Dec Hex Type Field The Close Stream (QzdmCloseStream) API is used to close
an OptiConnect stream. The Close Stream
0 0 CHAR(16) Stream identifier
(QzdmCloseStream) API should be performed after the
16 10 CHAR(8) Path identifier stream is no longer needed to free the system resources
associated with the stream.

Field Descriptions
Restrictions
Path identifier. The OptiConnect path that is to be closed.
This field is provided as output with the Open Path The following restrictions apply:
(QzdmOpenPath) API. Ÿ The OptiConnect QSOC subsystem must be started on
the system prior to calling this API.
Stream identifier. The OptiConnect stream that is to be
used for communications. This field is provided as output Ÿ A stream must be opened to the OptiConnect device
with the Open Stream (QzdmOpenStream) API. driver on the system by using the Open Stream
(QzdmOpenStream) API prior to calling this API.

Error Messages
Authority and Locks
CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E Service Program Authority
Length specified in parameter &1 not valid. *EXECUTE
CPF3C21 E
Format name &1 is not valid. Required Parameter Group

15-2 AS/400 System API Reference V4R4

 Open Path (QzdmOpenPath) API

Request variable CPFADF1 E

INPUT; CHAR(*) OptiConnect communication error.
CPFADF5 E
The request variable structure that describes the input
OptiConnect API internal error, function code
for the Close Stream (QzdmCloseStream) API.
&1, return code &2.
Length of request variable CPFADF6 E
INPUT; BINARY(4) Request variable not valid, reason code &1.
The length of the request variable, in bytes. The length
of the request variable must be at least equal to the
length of the input format, and less than or equal to the Open Path (QzdmOpenPath) API
maximum length of 4KB.

Format name of request variable Required Parameter Group:

INPUT; CHAR(8)
1 Receiver variable Output Char(*)
The format of the information that is provided as input
2 Length of receiver variable Input Binary(4)
for the Close Stream (QzdmCloseStream) API. The
3 Format name of receiver Input Char(8)
CSTR0100 format is used by this API for the request variable
variable. See “CSTR0100 Format” for more information 4 Request variable Input Char(*)
on the CSTR0100 format. 5 Length of request variable Input Binary(4)
6 Format name of request Input Char(8)
Error code variable
I/O; CHAR(*) 7 Error code I/O Char(*)
The structure in which to return error information. For
Library Name/Service Program: QSOC/QZDMMDTA
the format of the structure, see “Error Code Parameter”
on page 2-6. Threadsafe: No

CSTR0100 Format The Open Path (QzdmOpenPath) API is used to open an

The following table defines the information required for OptiConnect path. The Open Path (QzdmOpenPath) API
format CSTR0100. returns a path identifier that is then required as input for sub-
sequent OptiConnect APIs that require a path identifier.
Offset
Dec Hex Type Field Restrictions
0 0 CHAR(16) Stream identifier The following restrictions apply:
Ÿ The OptiConnect QSOC subsystems must be started on
Field Descriptions both the local and remote systems prior to calling this
API.
Stream identifier. The OptiConnect stream that is to be Ÿ A stream must be opened to the OptiConnect device
closed. This field is provided as output with the Open driver on the local system by using the Open Stream
Stream (QzdmOpenStream) API. (QzdmOpenStream) API prior to calling this API.
Ÿ A user profile must exist on the remote system by the
Error Messages same name as the user profile that is running the Open
CPF24B4 E Severe error while addressing parameter list. Path (QzdmOpenPath) API on the local system.
CPF3C1D E It is the responsibility of the user to verify that the user
Length specified in parameter &1 not valid. profile name on the remote system is the same as the
CPF3C21 E user profile name on the local system. The purpose of
Format name &1 is not valid. this verification is to ensure that the user's authority is
CPF3C90 E the same on both systems.
Literal value cannot be changed.
Ÿ If a job description (*JOBD) is specified in the user
CPF3CF1 E
profile on the remote system, the job description must
Error code parameter not valid.
also reside on the remote system.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3. Ÿ A maximum of 256 path identifiers may be opened for a
CPFADF0 E single job.
The OptiConnect QSOC subsystem must be
active.

Chapter 15. OptiConnect APIs 15-3

Open Path (QzdmOpenPath) API

Authority and Locks Offset

Service Program Authority Dec Hex Type Field
*EXECUTE 0 0 CHAR(8) Path identifier

Required Parameter Group

OPRQ0100 Format
Receiver variable
OUTPUT; CHAR(*) The following table defines the information required for
format OPRQ0100.
The receiver variable that is to receive the output control
information from the Open Path (QzdmOpenPath) API.
Offset
Length of receiver variable Dec Hex Type Field
INPUT; BINARY(4)
0 0 CHAR(16) Stream identifier
The length of the receiver variable, in bytes. The length
16 10 CHAR(8) Remote system name
of the receiver variable must be at least equal to or
greater than the length of the output format. 24 18 CHAR(10) Program name
34 22 CHAR(10) Program library name
Format name of receiver variable
INPUT; CHAR(8)
The format of the information that is returned from the Field Descriptions
Open Path (QzdmOpenPath) API. The OPRC0100
format is used by this API for the receiver variable. See Path identifier. The OptiConnect path that is to be used for
“OPRC0100 Format” for more information on the communications. This field is provided as output with the
OPRC0100 format. Open Path (QzdmOpenPath) API. This field must then be
provided as input on all subsequent OptiConnect APIs that
Request variable require a path identifier.
INPUT; CHAR(*)
The request variable structure that describes the input The path identifier is associated with the stream identifier that
for the Open Path (QzdmOpenPath) API. is provided as input, as a stream-identifier and path-identifier
pair. For most applications, this stream-identifier and path-
Length of request variable identifier pair needs to be used for all subsequent
INPUT; BINARY(4) OptiConnect APIs that are used to control communications
The length of the request variable, in bytes. The length on the local system.
of the request variable must be at least equal to the
Remote system name. The name of the remote system to
length of the input format, and less than or equal to the
which the OptiConnect path is being opened. This is the
maximum length of 4KB.
current system name as displayed on the Display Network
Format name of request variable Attributes (DSPNETA) display on the remote system.
INPUT; CHAR(8)
Program name. The program name on the remote system
The format of the information that is provided as input that controls communications on the remote system. This
for the Open Path (QzdmOpenPath) API. The program is called by the OptiConnect agent job
OPRQ0100 format is used by this API for the request (QZDMAGNT) on the remote system, and is passed a
variable. See “OPRQ0100 Format” for more information stream-identifier and path-identifier pair.
on the OPRQ0100 format.
For most applications, this stream-identifier and path-
Error code
identifier pair needs to be used for all subsequent
I/O; CHAR(*)
OptiConnect APIs that are used to control communications
The structure in which to return error information. For on the remote system.
the format of the structure, see “Error Code Parameter”
on page 2-6. Program library name. The program library name on the
remote system in which the program is contained.
OPRC0100 Format Stream identifier. The OptiConnect stream that is to be
used for communications. This field is provided as output on
The following table defines the information returned for
the Open Stream (QzdmOpenStream) API.
format OPRC0100.
The stream identifier is associated with the path identifier that
is provided as output, as a stream-identifier and path-
identifier pair. For most applications, this stream-identifier

15-4 AS/400 System API Reference V4R4

 Open Stream (QzdmOpenStream) API

and path-identifier pair needs to be used for all subsequent The Open Stream (QzdmOpenStream) API is used to open
OptiConnect APIs that are used to control communications an OptiConnect stream. The Open Stream
on the local system. (QzdmOpenStream) API returns a stream identifier, which is
then required as input for subsequent OptiConnect APIs that
require a stream identifier.
Error Messages
CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E
Restrictions
Length specified in parameter &1 not valid.
The following restrictions apply:
CPF3C21 E
Format name &1 is not valid. Ÿ The OptiConnect QSOC subsystem must be started on
CPF3C90 E the local system prior to calling this API.
Literal value cannot be changed. Ÿ A maximum of 256 stream identifiers may be opened for
CPF3CF1 E a single job.
Error code parameter not valid.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3. Authority and Locks
CPFADF0 E Service Program Authority
The OptiConnect QSOC subsystem must be *EXECUTE
active.
CPFADF1 E
OptiConnect communication error. Required Parameter Group
CPFADF2 E Receiver variable
OptiConnect path open error. OUTPUT; CHAR(*)
CPFADF5 E
OptiConnect API internal error, function code The receiver variable that is to receive the output control
&1, return code &2. information from the Open Stream (QzdmOpenStream)
CPFADF6 E API.
Request variable not valid, reason code &1. Length of receiver variable
CPFADF7 E INPUT; BINARY(4)
OptiConnect API open path error, function code
&1, return code &2. The length of the receiver variable, in bytes. The length
CPFADF8 E of the receiver variable must be at least equal to or
Program name not found. greater than the length of the output format.
CPFADF9 E Format name of receiver variable
Program library name not found. INPUT; CHAR(8)
CPFADFA E
User not authorized to program. The format of the information that is returned from the
CPFADFB E Open Stream (QzdmOpenStream) API. The OSTR0100
Open path rejected. format is used by this API for the receiver variable. See
CPFADFD E “OSTR0100 Format” for more information on the
Remote system &1 not found or not valid. OSTR0100 format.

Error code
I/O; CHAR(*)
Open Stream (QzdmOpenStream) API
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6.
Required Parameter Group:

1 Receiver variable Output Char(*) OSTR0100 Format

2 Length of receiver variable Input Binary(4)
3 Format name of receiver Input Char(8) The following table defines the information returned for
variable
format OSTR0100.
4 Error code I/O Char(*)

Library Name/Service Program: QSOC/QZDMMDTA Offset

Dec Hex Type Field
Threadsafe: No
0 0 CHAR(16) Stream identifier

Chapter 15. OptiConnect APIs 15-5

Receive Control (QzdmReceiveControl) API

Field Descriptions sequence. If the Receive Control (QzdmReceiveControl) API

is not issued, the stream identifier that is associated with the
Stream identifier. The OptiConnect stream that is to be path that is being closed is not available for subsequent com-
used for communications. This field is provided as output munications until the control message is received.
with the Open Stream (QzdmOpenStream) API. This field
must then be provided as input on all subsequent
OptiConnect API requests that require a stream identifier.
Restrictions
The following restrictions apply:
Error Messages Ÿ The OptiConnect QSOC subsystem must be started on
CPF24B4 E Severe error while addressing parameter list. both the local and remote systems prior to calling this
CPF3C1D E API.
Length specified in parameter &1 not valid. Ÿ A stream must be opened to the OptiConnect device
CPF3C21 E driver on the local system by using the Open Stream
Format name &1 is not valid. (QzdmOpenStream) API prior to calling this API.
CPF3C90 E
Ÿ A path must be opened to the remote system by using
Literal value cannot be changed.
the Open Path (QzdmOpenPath) API prior to calling this
CPF3CF1 E
API.
Error code parameter not valid.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3. Authority and Locks
CPFADF0 E
Service Program Authority
The OptiConnect QSOC subsystem must be
*EXECUTE
active.
CPFADF1 E
OptiConnect communication error. Required Parameter Group
CPFADF5 E
OptiConnect API internal error, function code Receiver variable
&1, return code &2. OUTPUT; CHAR(*)
The receiver variable that is to receive the output control
information from the Receive Control
Receive Control (QzdmReceiveControl) (QzdmReceiveControl) API.
API Length of receiver variable
INPUT; BINARY(4)
The length of the receiver variable, in bytes. The length
Required Parameter Group:
of the receiver variable must be at least equal to or
1 Receiver variable Output Char(*) greater than the length of the output format.
2 Length of receiver variable Input Binary(4)
3 Format name of receiver Input Char(8) Format name of receiver variable
variable INPUT; CHAR(8)
4 Request variable Input Char(*) The format of the information that is returned from
5 Length of request variable Input Binary(4)
Receive Control (QzdmReceiveControl) API. The
6 Format name of request Input Char(8)
variable RCRC0100 format is used by this API for the receiver
7 Error code I/O Char(*) variable. See “RCRC0100 Format” on page 15-7 for
more information on the RCRC0100 format.
Library Name/Service Program: QSOC/QZDMMDTA
Request variable
Threadsafe: No INPUT; CHAR(*)
The request variable structure that describes the input
for the Receive Control (QzdmReceiveControl) API.
The Receive Control (QzdmReceiveControl) API is used to
receive a control message on an OptiConnect stream. Length of request variable
INPUT; BINARY(4)
When the Close Path (QzdmClosePath) API is issued on a
system to close a path, the system that is at the other end of The length of the request variable, in bytes. The length
the path must issue the Receive Control of the request variable must be at least equal to the
(QzdmReceiveControl) API to complete the close path length of the input format, and less than or equal to the
maximum length of 4KB.

15-6 AS/400 System API Reference V4R4

 Receive Request (QzdmReceiveRequest) API

Format name of request variable CPF3C1D E

INPUT; CHAR(8) Length specified in parameter &1 not valid.
CPF3C21 E
The format of the information that is provided as input
Format name &1 is not valid.
for the Receive Control (QzdmReceiveControl) API. The
CPF3C90 E
RCRQ0100 format is used by this API for the request
Literal value cannot be changed.
variable. See “RCRQ0100 Format” for more information
CPF3CF1 E
on the RCRQ0100 format.
Error code parameter not valid.
Error code CPF9872 E Program or service program &1 in library &2
I/O; CHAR(*) ended. Reason code &3.
CPFADF0 E
The structure in which to return error information. For
The OptiConnect QSOC subsystem must be
the format of the structure, see “Error Code Parameter”
active.
on page 2-6.
CPFADF1 E
OptiConnect communication error.
RCRC0100 Format CPFADF4 E
OptiConnect detected sequence error.
The following table defines the information returned for CPFADF5 E
format RCRC0100. OptiConnect API internal error, function code
&1, return code &2.
Offset CPFADF6 E
Dec Hex Type Field Request variable not valid, reason code &1.
0 0 CHAR(1) Control message type
1 1 CHAR(8) Control message data
Receive Request (QzdmReceiveRequest)
API
RCRQ0100 Format
The following table defines the information required for Required Parameter Group:
format RCRQ0100.
1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
Offset 3 Format name of receiver Input Char(8)
Dec Hex Type Field variable
4 Request variable Input Char(*)
0 0 CHAR(16) Stream identifier 5 Length of request variable Input Binary(4)
6 Format name of request Input Char(8)
variable
Field Descriptions 7 Error code I/O Char(*)

Control message data. The control message data returned Library Name/Service Program: QSOC/QZDMMDTA
for the control message type. For example, the control
message data for the close path message contains the path Threadsafe: No
identifier of the path that is being closed.

Control message type. The type of control message to be The Receive Request (QzdmReceiveRequest) API is used to
received. This field is provided as output on the Receive receive a request or a message over an OptiConnect path.
Control (QzdmReceiveControl) API. The possible value A maximum of 32KB of data may be transferred in a single
follows: receive request.

1 Close path message

Restrictions
Stream identifier. The OptiConnect stream that is used for
communications. This field is provided as output with the The following restrictions apply:
Open Stream (QzdmOpenStream) API. Ÿ The OptiConnect QSOC subsystem must be started on
both the local and remote systems prior to calling this
Error Messages API.

CPF24B4 E Severe error while addressing parameter list. Ÿ A stream must be opened to the OptiConnect device
driver on the local system by using the Open Stream
(QzdmOpenStream) API prior to calling this API.

Chapter 15. OptiConnect APIs 15-7

Receive Request (QzdmReceiveRequest) API

Ÿ A path must be opened to the remote system by using Error code

the Open Path (QzdmOpenPath) API prior to calling this I/O; CHAR(*)
API.
The structure in which to return error information. For
Ÿ If the receiving system does not provide a large enough the format of the structure, see “Error Code Parameter”
data buffer to receive all of the data, the data that will fit on page 2-6.
into the data buffer is moved, but the remaining data is
truncated. The user must then increase the size of the
data buffer and then retry the entire transaction.
RQRC0100 Format
Ÿ A maximum of 16 transactions may be in progress for a The following table defines the information returned for
stream-identifier and path-identifier pair. format RQRC0100.

Offset
Authority and Locks
Dec Hex Type Field
Service Program Authority
*EXECUTE 0 0 CHAR(8) Transaction identifier
8 8 CHAR(8) Path identifier

Required Parameter Group 16 10 BINARY(4) Total request data length

20 14 BINARY(4) Current output data length
Receiver variable
OUTPUT; CHAR(*) 24 18 BINARY(4) Maximum response data
length
The receiver variable that is to receive the output control
information from the Receive Request
(QzdmReceiveRequest) API. RQRQ0100 Format
Length of receiver variable
The following table defines the information required for
INPUT; BINARY(4)
format RQRQ0100.
The length of the receiver variable, in bytes. The length
of the receiver variable must be at least equal to or Offset
greater than the length of the output format.
Dec Hex Type Field
Format name of receiver variable 0 0 CHAR(16) Stream identifier
INPUT; CHAR(8)
16 10 BINARY(4) Time-out value
The format of the information that is returned from the 20 14 BINARY(4) Offset to output descriptors
Receive Request (QzdmReceiveRequest) API. The
RQRC0100 format is used by this API for the receiver 24 18 BINARY(4) Number of output descrip-
tors
variable. See “RQRC0100 Format” for more information
on the RQRC0100 format. 28 1C CHAR(4) Reserved
These fields PTR(SPP) Data buffer pointer
Request variable
repeat for
INPUT; CHAR(*) BINARY(4) Data buffer length
each output
The request variable structure that describes the input descriptor CHAR(12) Reserved
for the Receive Request (QzdmReceiveRequest) API.

Length of request variable Field Descriptions

INPUT; BINARY(4)
The length of the request variable, in bytes. The length Current output data length. The total data length of the
of the request variable must be at least equal to the request that was moved to the user's data buffer area. If the
length of the input format, and less than or equal to the current output data length is less than the total request data
maximum length of 4KB. length, then this indicates that not all of the data was
received. It is the responsibility of the user's application
Format name of request variable program to retry the entire transaction by using a larger data
INPUT; CHAR(8) buffer size for the Receive Request (QzdmReceiveRequest)
The format of the information that is provided as input API to receive all of the data.
for the Receive Request (QzdmReceiveRequest) API.
Data buffer length. The length of the data buffer that is
The RQRQ0100 format is used by this API for the
used for receiving data.
request variable. See “RQRQ0100 Format” for more
information on the RQRQ0100 format. Data buffer pointer. The pointer to the data buffer that is
used for receiving data.

15-8 AS/400 System API Reference V4R4

 Receive Response (QzdmReceiveResponse) API

Maximum response data length. The maximum length that Error Messages
is allowed for the response data. This field is provided by
the user as input on the Send Request (QzdmSendRequest) CPF24B4 E Severe error while addressing parameter list.
API and indicates the maximum response data length CPF3C1D E
allowed for the Send Response (QzdmSendResponse) API. Length specified in parameter &1 not valid.
CPF3C21 E
Number of output descriptors. The number of output Format name &1 is not valid.
descriptors that are used. An output descriptor describes CPF3C90 E
where the output data may be found. The output descriptor Literal value cannot be changed.
consists of a space pointer to a data buffer and the length of CPF3CF1 E
the data buffer. A maximum of three output descriptors may Error code parameter not valid.
be specified. CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.
Offset to output descriptors. The offset to the output CPFADF0 E
descriptors. The OptiConnect QSOC subsystem must be
active.
Path identifier. The OptiConnect path that is to be used for CPFADF1 E
communications. This field is provided as output on the OptiConnect communication error.
Receive Request (QzdmReceiveRequest) API. CPFADF3 E
OptiConnect path not valid or closed.
Reserved. A reserved space for the purpose of aligning
CPFADF4 E
pointer values on a 16-byte boundary. This field must be ini-
OptiConnect detected sequence error.
tialized to binary 0.
CPFADF5 E
Stream identifier. The OptiConnect stream that is used for OptiConnect API internal error, function code
communications. This field is provided as output on the Open &1, return code &2.
Stream (QzdmOpenStream) API. CPFADF6 E
Request variable not valid, reason code &1.
Time-out value. A length of time, in milliseconds, to wait for CPFADFE E
the Receive Request (QzdmReceiveRequest) API to com- Time-out occurred.
plete. If the Receive Request (QzdmReceiveRequest) API CPFADFF E
does not complete before the specified time-out value, then Transaction was terminated.
the exception CPFADFE is returned. The user should then
re-issue the Receive Request (QzdmReceiveRequest) API
and specify the same time-out value or an increased time-out Receive Response
value. (QzdmReceiveResponse) API
The Receive Request (QzdmReceiveRequest) API remains
outstanding, and control is not returned to the user applica-
tion until either of the following occurs: Required Parameter Group:

Ÿ The request either completes successfully or unsuccess- 1 Receiver variable Output Char(*)
fully. 2 Length of receiver variable Input Binary(4)
3 Format name of receiver Input Char(8)
Ÿ The time-out value has been exceeded. variable
4 Request variable Input Char(*)
A value of -1 may be specified, which indicates to wait 5 Length of request variable Input Binary(4)
forever for the Receive Request (QzdmReceiveRequest) API 6 Format name of request Input Char(8)
to complete. variable
7 Error code I/O Char(*)
Total request data length. The total data length of the
request that is available to be received. This field is provided Library Name/Service Program: QSOC/QZDMMDTA
as output on the Receive Request (QzdmReceiveRequest)
API. Threadsafe: No

Transaction identifier. The specific transaction associated

The Receive Response (QzdmReceiveResponse) API is
with this Receive Request (QzdmReceiveRequest) API. This
used to receive an acknowledgement and the response data
field is provided as output on the Receive Request
over an OptiConnect path. A maximum of 32KB of data may
(QzdmReceiveRequest) API. This field must then be pro-
be received in a single receive response.
vided as input on the corresponding Send Response
(QzdmSendResponse) API. The response data is received into the output buffers, which
were previously defined in the output descriptors on the Send
Request (QzdmSendRequest) API.

Chapter 15. OptiConnect APIs 15-9

Receive Response (QzdmReceiveResponse) API

Restrictions length of the input format, and less than or equal to the
maximum length of 4KB.
The following restrictions apply:
Format name of request variable
Ÿ The OptiConnect QSOC subsystem must be started on INPUT; CHAR(8)
both the local and remote systems prior to calling this
The format of the information that is provided as input
API.
for the Receive Response (QzdmReceiveResponse)
Ÿ A stream must be opened to the OptiConnect device API. The RSRQ0100 format is used by this API for the
driver on the local system by using the Open Stream request variable. See “RSRQ0100 Format” for more
(QzdmOpenStream) API prior to calling this API. information on the RSRQ0100 format.
Ÿ A path must be opened to the remote system by using Error code
the Open Path (QzdmOpenPath) API prior to calling this I/O; CHAR(*)
API.
The structure in which to return error information. For
Ÿ If the receiving system does not provide a large enough the format of the structure, see “Error Code Parameter”
data buffer to receive all of the data, the data that will fit on page 2-6.
into the data buffer is moved, but the remaining data is
truncated. The user must then increase the size of the
data buffer, and then retry the entire transaction. RSRC0100 Format
Ÿ A maximum of 16 transactions may be in progress for a The following table defines the information returned for
stream-identifier and path-identifier pair. format RSRC0100.

Authority and Locks Offset

Service Program Authority Dec Hex Type Field

*EXECUTE 0 0 CHAR(4) Acknowledgement data
4 4 BINARY(4) Actual response data length
Required Parameter Group
Receiver variable RSRQ0100 Format
OUTPUT; CHAR(*)
The following table defines the information required for
The receiver variable that is to receive the output control
format RSRQ0100.
information from the Receive Response
(QzdmReceiveResponse) API.
Offset
Length of receiver variable Dec Hex Type Field
INPUT; BINARY(4)
0 0 CHAR(16) Stream identifier
The length of the receiver variable, in bytes. The length
16 10 CHAR(8) Path identifier
of the receiver variable must be at least equal to or
greater than the length of the output format. 24 18 BINARY(4) Time-out value
28 1C CHAR(8) Transaction identifier
Format name of receiver variable
INPUT; CHAR(8)
The format of the information that is returned from the Field Descriptions
Receive Response (QzdmReceiveResponse) API. The
RSRC0100 format is used by this API for the receiver Acknowledgement data. The acknowledgement data for
variable. See “RSRC0100 Format” for more information the request. This field is provided as input on the Send
on the RSRC0100 format. Response (QzdmSendResponse) API.

Request variable Actual response data length. The actual length that was
INPUT; CHAR(*) received for the response data. If the response data that was
The request variable structure that describes the input sent from the Send Response (QzdmSendResponse) API is
for the Receive Response (QzdmReceiveResponse) larger than the buffer that was provided with the Send
API. Request (QzdmSendRequest) API, not all of the data was
received. It is the responsibility of the user's application
Length of request variable program to retry the entire transaction by using a larger data
INPUT; BINARY(4) buffer size for the Send Request (QzdmSendRequest) API to
The length of the request variable, in bytes. The length receive all of the data with the Receive Response
of the request variable must be at least equal to the (QzdmReceiveResponse) API.

15-10 AS/400 System API Reference V4R4

 Send Request (QzdmSendRequest) API

Path identifier. The OptiConnect path that is used for com- CPFADFE E
munications. This field is provided as output on the Open Time-out occurred.
Path (QzdmOpenPath) API. CPFADFF E
Transaction was terminated.
Stream identifier. The OptiConnect stream that is used for
communications. This field is provided as output on the Open
Stream (QzdmOpenStream) API.
Send Request (QzdmSendRequest) API
Time-out value. A length of time, in milliseconds, to wait for
the Receive Response (QzdmReceiveResponse) API to com-
plete. If the Receive Response (QzdmReceiveResponse) Required Parameter Group:
API does not complete before the specified time-out value,
1 Receiver variable Output Char(*)
the exception CPFADFE is returned. The user should then 2 Length of receiver variable Input Binary(4)
re-issue the Receive Response (QzdmReceiveResponse) 3 Format name of receiver Input Char(8)
API and specify the same time-out value or an increased variable
time-out value. 4 Request variable Input Char(*)
5 Length of request variable Input Binary(4)
The Receive Response (QzdmReceiveResponse) API 6 Format name of request Input Char(8)
remains outstanding, and control is not returned to the user variable
application until either of the following occurs: 7 Error code I/O Char(*)

Ÿ The request either completes successfully or unsuccess- Library Name/Service Program: QSOC/QZDMMDTA
fully.
Threadsafe: No
Ÿ The time-out value has been exceeded.

A value of -1 may be specified, which indicates to wait

The Send Request (QzdmSendRequest) API is used to send
forever for the Receive Response (QzdmReceiveResponse)
a request or a message over an OptiConnect path. A
API to complete.
maximum of 32KB of data may be transferred in a single
Transaction identifier. The specific transaction associated send request.
with this Receive Response (QzdmReceiveResponse) API.
This field is provided as output on the Send Request Restrictions
(QzdmSendRequest) API.
The following restrictions apply:
Error Messages Ÿ The OptiConnect QSOC subsystem must be started on
both the local and remote systems prior to calling this
CPF24B4 E Severe error while addressing parameter list.
API.
CPF3C1D E
Length specified in parameter &1 not valid. Ÿ A stream must be opened to the OptiConnect device
CPF3C21 E driver on the local system by using the Open Stream
Format name &1 is not valid. (QzdmOpenStream) API prior to calling this API.
CPF3C90 E Ÿ A path must be opened to the remote system by using
Literal value cannot be changed. the Open Path (QzdmOpenPath) API prior to calling this
CPF3CF1 E API.
Error code parameter not valid.
CPF9872 E Program or service program &1 in library &2 Ÿ A maximum of 16 transactions may be in progress for a
ended. Reason code &3. stream-identifier and path-identifier pair.
CPFADF0 E
The OptiConnect QSOC subsystem must be Authority and Locks
active.
CPFADF1 E Service Program Authority
OptiConnect communication error. *EXECUTE
CPFADF3 E
OptiConnect path not valid or closed. Required Parameter Group
CPFADF5 E
OptiConnect API internal error, function code Receiver variable
&1, return code &2. OUTPUT; CHAR(*)
CPFADF6 E The receiver variable that is to receive the output control
Request variable not valid, reason code &1. information from the Send Request (QzdmSendRequest)
API.

Chapter 15. OptiConnect APIs 15-11

Send Request (QzdmSendRequest) API

Length of receiver variable

Offset
INPUT; BINARY(4)
Dec Hex Type Field
The length of the receiver variable, in bytes. The length
0 0 CHAR(16) Stream identifier
of the receiver variable must be at least equal to or
greater than the length of the output format. 16 10 CHAR(8) Path identifier

Format name of receiver variable 24 18 BINARY(4) Maximum response data

length
INPUT; CHAR(8)
28 1C BINARY(4) Offset to input descriptors
The format of the information that is returned from the
Send Request (QzdmSendRequest) API. The 32 20 BINARY(4) Number of input descriptors
SRRC0100 format is used by this API for the receiver 36 24 BINARY(4) Offset to output descriptors
variable. See “SRRC0100 Format” for more information 40 28 BINARY(4) Number of output descrip-
on the SRRC0100 format. tors
Request variable 44 2C CHAR(4) Reserved
INPUT; CHAR(*) These fields PTR(SPP) Data buffer pointer
The request variable structure that describes the input repeat for
BINARY(4) Data buffer length
each input
for the Send Request (QzdmSendRequest) API.
descriptor CHAR(12) Reserved
Length of request variable These fields PTR(SPP) Data buffer pointer
INPUT; BINARY(4) repeat for
BINARY(4) Data buffer length
each output
The length of the request variable, in bytes. The length
descriptor CHAR(12) Reserved
of the request variable must be at least equal to the
length of the input format, and less than or equal to the
maximum length of 4KB.
Field Descriptions
Format name of request variable
INPUT; CHAR(8) Data buffer length. The length of the data buffer that is
used for the input or output data.
The format of the information that is provided as input
for the Send Request (QzdmSendRequest) API. The Data buffer pointer. The pointer to the input data buffer
SRRQ0100 format is used by this API for the request that is used for input or output data.
variable. See “SRRQ0100 Format” for more information
on the SRRQ0100 format. Maximum response data length. The maximum length that
is allowed for the response data. This field is provided as
Error code output on the Receive Request (QzdmReceiveRequest) API
I/O; CHAR(*) and indicates the maximum response data length allowed for
The structure in which to return error information. For the Send Response (QzdmSendResponse) API. If the
the format of the structure, see “Error Code Parameter” response data that is sent from the Send Response
on page 2-6. (QzdmSendResponse) API is larger than the buffer that is
provided with the Send Request (QzdmSendRequest) API,
not all of the data is received. It is the responsibility of the
SRRC0100 Format user's application program to retry the entire transaction by
using a larger data buffer size for the Send Request
The following table defines the information returned for
(QzdmSendRequest) API to receive all of the data with the
format SRRC0100.
Receive Response (QzdmReceiveResponse) API.
Offset Number of output descriptors. The number of output
Dec Hex Type Field descriptors that are used. An output descriptor describes
where the output data that is to be received from the remote
0 0 CHAR(8) Transaction identifier
system may be found. The output descriptor consists of a
space pointer to a data buffer and the length of the data
buffer. A maximum of three output descriptors may be speci-
SRRQ0100 Format
fied. The total length of the output buffers must be equal to
The following table defines the information required for the maximum response data length that is specified.
format SRRQ0100.
Number of input descriptors. The number of input descrip-
tors that are used. An input descriptor describes where the
input data that is to be sent to the remote system may be
found. The input descriptor consists of a space pointer to a

15-12 AS/400 System API Reference V4R4

 Send Response (QzdmSendResponse) API

data buffer and the length of the data buffer. A maximum of

three input descriptors may be specified. Required Parameter Group:
Offset to output descriptors. The offset to the output 1 Request variable Input Char(*)
descriptors. 2 Length of request variable Input Binary(4)
3 Format name of request Input Char(8)
Offset to input descriptors. The offset to the input descrip- variable
tors. 4 Error code I/O Char(*)

Path identifier. The OptiConnect path that is used for com- Library Name/Service Program: QSOC/QZDMMDTA
munications. This field is provided as output on the Open
Path (QzdmOpenPath) API. Threadsafe: No

Reserved. A reserved space for the purpose of aligning

pointer values on a 16-byte boundary. This field must be ini- The Send Response (QzdmSendResponse) API is used to
tialized to binary 0. send an acknowledgement and the response data over an
OptiConnect path. A maximum of 32KB of data may be
Stream identifier. The OptiConnect stream that is used for transferred in a single send response.
communications. This field is provided as output on the Open
Stream (QzdmOpenStream) API.
Restrictions
Transaction identifier. The specific transaction associated
The following restrictions apply:
with this Send Request. This field is provided as output on
the Send Request (QzdmSendRequest) API. This field must Ÿ The OptiConnect QSOC subsystem must be started on
then be provided as input on the corresponding Receive both the local and remote systems prior to calling this
Response (QzdmReceiveResponse) API. API.
Ÿ A stream must be opened to the OptiConnect device
Error Messages driver on the local system by using the Open Stream
(QzdmOpenStream) API prior to calling this API.
CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E Ÿ A path must be opened to the remote system by using
Length specified in parameter &1 not valid. the Open Path (QzdmOpenPath) API prior to calling this
CPF3C21 E API.
Format name &1 is not valid. Ÿ If the receiving system does not provide a large enough
CPF3C90 E data buffer to receive all of the data, the data that will fit
Literal value cannot be changed. into the data buffer is moved, but the remaining data is
CPF3CF1 E truncated. The user must increase the size of the data
Error code parameter not valid. buffer and then retry the entire transaction.
CPF9872 E Program or service program &1 in library &2
Ÿ A maximum of 16 transactions may be in progress for a
ended. Reason code &3.
stream-identifier and path-identifier pair.
CPFADF0 E
The OptiConnect QSOC subsystem must be
active. Authority and Locks
CPFADF1 E
Service Program Authority
OptiConnect communication error.
*EXECUTE
CPFADF3 E
OptiConnect path not valid or closed.
CPFADF5 E Required Parameter Group
OptiConnect API internal error, function code
&1, return code &2. Request variable
CPFADF6 E INPUT; CHAR(*)
Request variable not valid, reason code &1. The request variable structure that describes the input
for the Send Response (QzdmSendResponse) API.

Length of request variable

Send Response (QzdmSendResponse) API INPUT; BINARY(4)
The length of the request variable, in bytes. The length
of the request variable must be at least equal to the
length of the input format, and less than or equal to the
maximum length of 4KB.

Chapter 15. OptiConnect APIs 15-13

Wait Message (QzdmWaitMessage) API

Format name of request variable Data buffer pointer. The pointer to the data buffer that is
INPUT; CHAR(8) used for sending data.
The format of the information that is provided as input
Number of input descriptors. The number of input descrip-
for the Send Response (QzdmSendResponse) API. The
tors that are used. An input descriptor describes where the
SRSP0100 format is used by this API for the request
input data may be found. The input descriptor consists of a
variable. See “SRSP0100 Format” for more information
space pointer to a data buffer and the length of the data
on the SRSP0100 format.
buffer. A maximum of three input descriptors may be speci-
Error code fied.
I/O; CHAR(*)
Offset to input descriptors. The offset to the input descrip-
The structure in which to return error information. For tors.
the format of the structure, see “Error Code Parameter”
on page 2-6. Reserved. A reserved space for the purpose of aligning
pointer values on a 16-byte boundary. This field must be ini-
tialized to binary 0.
SRSP0100 Format
Stream identifier. The OptiConnect stream that is used for
The following table defines the information required for
communications. This field is provided as output on the Open
format SRSP0100.
Stream (QzdmOpenStream) API.

Offset Transaction identifier. The specific transaction associated

Dec Hex Type Field with this Send Response (QzdmSendResponse) API. This
field is provided as output on the Receive Request
0 0 CHAR(16) Stream identifier
(QzdmReceiveRequest) API.
16 10 CHAR(8) Transaction identifier
24 18 BINARY(4) Actual response data length
Error Messages
28 1C CHAR(4) Acknowledgement data
CPF24B4 E Severe error while addressing parameter list.
32 20 BINARY(4) Offset to input descriptors CPF3C1D E
36 24 BINARY(4) Number of input descriptors Length specified in parameter &1 not valid.
40 28 CHAR(8) Reserved CPF3C21 E
Format name &1 is not valid.
These fields PTR(SPP) Data buffer pointer CPF3C90 E
repeat for
BINARY(4) Data buffer length Literal value cannot be changed.
each input
descriptor CHAR(12) Reserved CPF3CF1 E
Error code parameter not valid.
CPF9872 E Program or service program &1 in library &2
Field Descriptions ended. Reason code &3.
CPFADF0 E
Acknowledgement data. The acknowledgement data for The OptiConnect QSOC subsystem must be
the request. This field is provided as output on the Receive active.
Response (QzdmReceiveResponse) API and indicates the CPFADF1 E
acknowledgement data. OptiConnect communication error.
CPFADF3 E
Actual response data length. The actual length that is sent OptiConnect path not valid or closed.
for the response data. If the response data that is sent is CPFADF4 E
larger than the buffer that is provided on the Send Request OptiConnect detected sequence error.
(QzdmSendRequest) API, not all of the data is sent. It is the CPFADF5 E
responsibility of the user's application program to retry the OptiConnect API internal error, function code
entire transaction by using a larger data buffer size for the &1, return code &2.
Send Request (QzdmSendRequest) API to receive all of the CPFADF6 E
data with the Receive Response (QzdmReceiveResponse) Request variable not valid, reason code &1.
API. CPFADFF E
Transaction was terminated.
Data buffer length. The length of the data buffer that is
used for sending data.
Wait Message (QzdmWaitMessage) API

15-14 AS/400 System API Reference V4R4

 Wait Message (QzdmWaitMessage) API

WMRC0100 format is used by this API for the receiver

Required Parameter Group: variable. See “WMRC0100 Format” for more information
on the WMRC0100 format.
1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
Request variable
3 Format name of receiver Input Char(8) INPUT; CHAR(*)
variable The request variable structure that describes the input
4 Request variable Input Char(*)
for the Wait Message (QzdmWaitMessage) API.
5 Length of request variable Input Binary(4)
6 Format name of request Input Char(8) Length of request variable
variable INPUT; BINARY(4)
7 Error code I/O Char(*)
The length of the request variable, in bytes. The length
Library Name/Service Program: QSOC/QZDMMDTA of the request variable must be at least equal to the
length of the input format, and less than or equal to the
Threadsafe: No maximum length of 4KB.

Format name of request variable

The Wait Message (QzdmWaitMessage) API is used to wait INPUT; CHAR(8)
for a message on an OptiConnect stream. The message may
The format of the information that is provided as input
be a request message, a response message, or a control
for the Wait Message (QzdmWaitMessage) API. The
message.
WMRQ0100 format is used by this API for the request
variable. See “WMRQ0100 Format” for more information
Restrictions on the WMRQ0100 format.

The following restrictions apply: Error code

I/O; CHAR(*)
Ÿ The OptiConnect QSOC subsystem must be started on
both the local and remote systems prior to calling this The structure in which to return error information. For
API. the format of the structure, see “Error Code Parameter”
on page 2-6.
Ÿ A stream must be opened to the OptiConnect device
driver on the local system by using the Open Stream
(QzdmOpenStream) API prior to calling this API. WMRC0100 Format
Ÿ A path must be opened to the remote system by using The following table defines the information returned for
the Open Path (QzdmOpenPath) API prior to calling this format WMRC0100.
API.
Offset
Authority and Locks Dec Hex Type Field
Service Program Authority 0 0 CHAR(1) Message type
*EXECUTE

Required Parameter Group WMRQ0100 Format

Receiver variable The following table defines the information required for
OUTPUT; CHAR(*) format WMRQ0100.

The receiver variable that is to receive the output control

Offset
information from the Wait Message (QzdmWaitMessage)
API. Dec Hex Type Field
0 0 CHAR(16) Stream identifier
Length of receiver variable
INPUT; BINARY(4) 16 10 BINARY(4) Time-out value

The length of the receiver variable, in bytes. The length

of the receiver variable must be at least equal to or Field Descriptions
greater than the length of the output format.
Message type. The type of message that is received. This
Format name of receiver variable
field is provided as output on the Wait Message
INPUT; CHAR(8)
(QzdmWaitMessage) API. Possible values follow:
The format of the information that is returned from the
1 Request message
Wait Message (QzdmWaitMessage) API. The

Chapter 15. OptiConnect APIs 15-15

Wait Message (QzdmWaitMessage) API

2 Response message Error Messages

3 Control message
CPF24B4 E Severe error while addressing parameter list.
Stream identifier. The OptiConnect stream that is used for CPF3C1D E
communications. This field is provided as output on the Open Length specified in parameter &1 not valid.
Stream (QzdmOpenStream) API. CPF3C21 E
Format name &1 is not valid.
Time-out value. A length of time, in milliseconds, to wait for CPF3C90 E
the Wait Message (QzdmWaitMessage) API to complete. If Literal value cannot be changed.
the Wait Message (QzdmWaitMessage) API does not com- CPF3CF1 E
plete before the specified time-out value, the exception Error code parameter not valid.
CPFADFE is returned. The user should then re-issue the CPF9872 E Program or service program &1 in library &2
Wait Message (QzdmWaitMessage) API and specify the ended. Reason code &3.
same time-out value or an increased time-out value. CPFADF0 E
The OptiConnect QSOC subsystem must be
The Wait Message (QzdmWaitMessage) API remains out- active.
standing, and control is not returned to the user application CPFADF1 E
until either of the following occurs: OptiConnect communication error.
Ÿ The request either completes successfully or unsuccess- CPFADF5 E
fully. OptiConnect API internal error, function code
&1, return code &2.
Ÿ The time-out value has been exceeded.
CPFADF6 E
A value of -1 may be specified, which indicates to wait Request variable not valid, reason code &1.
forever for the Wait Message (QzdmWaitMessage) API to CPFADFE E
complete. Time-out occurred.

15-16 AS/400 System API Reference V4R4

 Configuration

Part 6. Configuration APIs

Chapter 16. Configuration APIs . . . . . . . . . . 16-1 DEVD0400 Format . . . . . . . . . . . . . . . 16-31

Configuration APIs—Introduction . . . . . . . . . . . 16-1 DEVD0500 Format . . . . . . . . . . . . . . . 16-31
Change Configuration Description (QDCCCFGD) API 16-1 DEVD0600 Format . . . . . . . . . . . . . . . 16-31
Authorities and Locks . . . . . . . . . . . . . . . 16-1 DEVD0700 Format . . . . . . . . . . . . . . . 16-33
Required Parameter Group . . . . . . . . . . . . 16-1 DEVD0800 Format . . . . . . . . . . . . . . . 16-33
Format for Variable Length Record . . . . . . . . 16-1 DEVD0900 Format . . . . . . . . . . . . . . . 16-33
Field Descriptions . . . . . . . . . . . . . . . . . 16-2 DEVD1000 Format . . . . . . . . . . . . . . . 16-33
Validation of New Values . . . . . . . . . . . . . 16-2 DEVD1100 Format . . . . . . . . . . . . . . . 16-33
Error Messages . . . . . . . . . . . . . . . . . . 16-2 DEVD1200 Format . . . . . . . . . . . . . . . 16-35
List Configuration Descriptions (QDCLCFGD) API . . 16-2 DEVD1300 Format . . . . . . . . . . . . . . . 16-35
Authorities and Locks . . . . . . . . . . . . . . . 16-3 DEVD1400 Format . . . . . . . . . . . . . . . 16-36
Required Parameter Group . . . . . . . . . . . . 16-3 DEVD1500 Format . . . . . . . . . . . . . . . 16-36
Format of Configuration Lists . . . . . . . . . . . 16-5 DEVD1600 Format . . . . . . . . . . . . . . . 16-36
Input Parameter Section . . . . . . . . . . . . 16-5 DEVD1700 Format . . . . . . . . . . . . . . . 16-36
Header Section . . . . . . . . . . . . . . . . . 16-5 | DEVD1800 Format . . . . . . . . . . . . . . . 16-37
CFGD0100 Format . . . . . . . . . . . . . . . 16-5 Field Descriptions . . . . . . . . . . . . . . . . . 16-37
CFGD0200 Format . . . . . . . . . . . . . . . 16-5 Error Messages . . . . . . . . . . . . . . . . . . 16-45
Field Descriptions . . . . . . . . . . . . . . . . . 16-6 Retrieve Line Description (QDCRLIND) API . . . . . 16-45
Error Messages . . . . . . . . . . . . . . . . . . 16-8 Authorities and Locks . . . . . . . . . . . . . . . 16-45
Retrieve Configuration Status (QDCRCFGS) API . . 16-8 Required Parameter Group . . . . . . . . . . . . 16-45
Authorities and Locks . . . . . . . . . . . . . . . 16-8 Format of Line Information . . . . . . . . . . . . 16-46
Required Parameter Group . . . . . . . . . . . . 16-8 LIND0100 Format . . . . . . . . . . . . . . . 16-46
Format of Status Information . . . . . . . . . . . 16-9 LIND0200 Format . . . . . . . . . . . . . . . 16-46
CFGS0100 Format . . . . . . . . . . . . . . . 16-9 LIND0300 Format . . . . . . . . . . . . . . . 16-46
Field Descriptions . . . . . . . . . . . . . . . . . 16-9 LIND0400 Format . . . . . . . . . . . . . . . 16-47
Error Messages . . . . . . . . . . . . . . . . . . 16-10 LIND0500 Format . . . . . . . . . . . . . . . 16-48
Retrieve Controller Description (QDCRCTLD) API . . 16-11 LIND0600 Format . . . . . . . . . . . . . . . 16-50
Authorities and Locks . . . . . . . . . . . . . . . 16-11 LIND0700 Format . . . . . . . . . . . . . . . 16-50
Required Parameter Group . . . . . . . . . . . . 16-11 LIND0800 Format . . . . . . . . . . . . . . . 16-51
Format of Controller Information . . . . . . . . . 16-11 LIND0900 Format . . . . . . . . . . . . . . . 16-52
CTLD0100 Format . . . . . . . . . . . . . . . 16-11 LIND1000 Format . . . . . . . . . . . . . . . 16-52
CTLD0200 Format . . . . . . . . . . . . . . . 16-12 LIND1100 Format . . . . . . . . . . . . . . . 16-54
CTLD0300 Format . . . . . . . . . . . . . . . 16-12 LIND1200 Format . . . . . . . . . . . . . . . 16-55
CTLD0400 Format . . . . . . . . . . . . . . . 16-13 LIND1300 Format . . . . . . . . . . . . . . . 16-56
CTLD0500 Format . . . . . . . . . . . . . . . 16-14 LIND1400 Format . . . . . . . . . . . . . . . 16-56
CTLD0600 Format . . . . . . . . . . . . . . . 16-15 LIND1500 Format . . . . . . . . . . . . . . . 16-57
CTLD0700 Format . . . . . . . . . . . . . . . 16-16 LIND1600 Format . . . . . . . . . . . . . . . 16-57
CTLD0800 Format . . . . . . . . . . . . . . . 16-18 Field Descriptions . . . . . . . . . . . . . . . . . 16-58
CTLD0900 Format . . . . . . . . . . . . . . . 16-18 Error Messages . . . . . . . . . . . . . . . . . . 16-69
CTLD1000 Format . . . . . . . . . . . . . . . 16-19 Retrieve Network Server Description (QDCRNWSD)
CTLD1100 Format . . . . . . . . . . . . . . . 16-21 API . . . . . . . . . . . . . . . . . . . . . . . . . 16-69
CTLD1200 Format . . . . . . . . . . . . . . . 16-21 Authorities and Locks . . . . . . . . . . . . . . . 16-70
CTLD1300 Format . . . . . . . . . . . . . . . 16-21 Required Parameter Group . . . . . . . . . . . . 16-70
Field Descriptions . . . . . . . . . . . . . . . . . 16-21 Format of Network Server Information . . . . . . 16-70
Error Messages . . . . . . . . . . . . . . . . . . 16-29 NWSD0100 Format . . . . . . . . . . . . . . 16-70
Retrieve Device Description (QDCRDEVD) API . . . 16-29 NWSD0200 Format . . . . . . . . . . . . . . 16-70
Authorities and Locks . . . . . . . . . . . . . . . 16-29 NWSD0300 Format . . . . . . . . . . . . . . 16-71
Required Parameter Group . . . . . . . . . . . . 16-29 NWSD0400 Format . . . . . . . . . . . . . . 16-72
Format of Device Information . . . . . . . . . . . 16-30 NWSD0500 Format . . . . . . . . . . . . . . 16-73
DEVD0100 Format . . . . . . . . . . . . . . . 16-30 NWSD0600 Format . . . . . . . . . . . . . . 16-73
DEVD0200 Format . . . . . . . . . . . . . . . 16-30 Field Descriptions . . . . . . . . . . . . . . . . . 16-75
DEVD0300 Format . . . . . . . . . . . . . . . 16-31 Error Messages . . . . . . . . . . . . . . . . . . 16-77

 Copyright IBM Corp. 1998, 1999

Configuration

AS/400 System API Reference V4R4

 Change Configuration Description (QDCCCFGD) API

Chapter 16. Configuration APIs

Configuration description authority
Configuration APIs—Introduction *CHANGE
The configuration application programming interfaces (APIs)
allow you to get information about the configuration status of Required Parameter Group
the system and about individual configuration descriptions.
The configuration APIs available to you are: Configuration description name
INPUT; CHAR(10)
Change Configuration Description
(QDCCCFGD) changes the value of one or The name of the configuration description being
more parameters in an existing configuration changed. This parameter must be in uppercase.
description. Configuration description type
List Configuration Descriptions INPUT; CHAR(10)
(QDCLCFGD) returns a list of configuration
descriptions. The type of configuration description being changed.
Retrieve Configuration Status Possible values for this parameter are:
(QDCRCFGS) retrieves the current status of a *CFGL Configuration list
controller, device, line, or network interface. *CNNL Connection list
Retrieve Controller Description *COSD Class of service description
(QDCRCTLD) retrieves information about a *CTLD Controller description
controller description. *DEVD Device description
Retrieve Device Description *IPXD IPX description
(QDCRDEVD) retrieves information about a *LIND Line description
device description. *MODD Mode description
Retrieve Line Description *NTBD NetBIOS description
(QDCRLIND) retrieves information about a line *NWID Network interface
description. *NWSD Network server description
Retrieve Network Server Description
(QDCRNWSD) retrieves information about a Changes
network server description. INPUT; CHAR(*)
The changes to be made to the specified configuration
The following sections describe each API in detail. The API
description. The information must be in the following
descriptions are presented in alphabetical order.
format:

Number of variable length records

Change Configuration Description BINARY(4)
(QDCCCFGD) API The total number of all of the variable
length records.
Variable length records
Required Parameter Group: Each variable length record contains a
keyword plus its associated new value.
1 Configuration description Input Char(10)
Refer to “Format for Variable Length
name
Record” for the format of this field.
2 Configuration description Input Char(10)
type Error code
3 Changes Input Char(*)
I/O; CHAR(*)
4 Error code I/O Char(*)
The structure in which to return error information. For
Threadsafe: No the format of the structure, see “Error Code Parameter”
on page 2-6.
The Change Configuration Object (QDCCCFGD) API
changes the value of one or more parameters in an existing Format for Variable Length Record
configuration description.
The following table shows the format for the variable length
record. For a detailed description of each field, see “Field
Authorities and Locks Descriptions” on page 16-2.

 Copyright IBM Corp. 1998, 1999 16-1

List Configuration Descriptions (QDCLCFGD) API

CPF260F E Configuration list not found.

Offset
CPF262C E
Dec Hex Type Field Mode description damaged.
0 0 BINARY(4) Key CPF2625 E Not able to allocate object &1.
4 4 BINARY(4) Length of new value CPF2634 E Not authorized to object &1.
CPF266C E
8 8 CHAR(*) New value Connection list not found.
CPF2670 E Class of service description not found.
If the length of the new value is longer than the data length CPF2675 E Class of service description damaged.
of the key field, the data is truncated to the right. No CPF27A4 E Network interface description &1 not found.
message is issued. CPF2702 E Device description &1 not found.
CPF2703 E Controller description &1 not found.
If the length of the new value is shorter than the data length CPF2704 E Line description &1 not found.
of the key field, the data is padded with blanks to the right. CPF3CF1 E
No message is issued. Error code parameter not valid.
CPF3C4D E
It is not an error to specify a key more than once. If dupli-
Length &1 for key &2 not valid.
cate keys are specified, the last specified value for that key
CPF3C88 E
is used.
Number of variable length records &1 is not
valid.
Field Descriptions CPF3C90 E
Literal value cannot be changed.
Key. The keyword parameter of the configuration description CPF8FCF E
to be changed. Only specific keywords can be changed. The IPX description not found.
following table lists the valid key for the key-field area of the CPF8F5D E
variable length record: NetBIOS description not found.
CPF8104 E Controller description &4 damaged.
Key Value CFGD type CFGD CPF8105 E Device description &4 damaged.
keyword CPF811D E
201 CHAR(5000) *DEVD USRDFNDTA Network interface description &4 damaged.
CPF811E E Connection list damaged.
Length of new value. The length of the new value to be CPF8124 E Configuration list damaged.
assigned to the keyword. CPF8125 E Line description &4 damaged.
CPF814D E
New value. The value to which a specific keyword is to be NetBIOS description &4 damaged.
set. CPF815C E
IPX description damaged.
CPF9872 E Program or service program &1 in library &2
Validation of New Values ended. Reason code &3.
Inclusion of any keyword parameter and its accompanying
values in this API implies that the parsing of the value is sup-
ported in this API at a level equivalent to that provided by a List Configuration Descriptions
Change (CHG) command that supports the same keyword. (QDCLCFGD) API
In addition to the CPF26C9 escape message signaled to the
caller, one or more CPD messages are placed on the caller's Required Parameter Group:
job log by the API to more fully describe the syntax error
found while parsing the new value. 1 Qualified user space name Input Char(20)
2 Format name Input CHAR(8)
3 Configuration description Input Char(10)
Error Messages type
4 Object qualifier Input Char(40)
CPF24B4 E Severe error while addressing parameter list. 5 Status qualifier Input Char(20)
CPF26A8 E Configuration description type not valid for this 6 Error code I/O Char(*)
API.
CPF26C7 E Threadsafe: Yes
Key not valid.
CPF26C9 E
New value not valid. The List Configuration Descriptions (QDCLCFGD) API
CPF260A E Mode description not found. returns a list of configuration descriptions. The list elements
are all of one type (such as line, controller, or device). The

16-2 AS/400 System API Reference V4R4

 List Configuration Descriptions (QDCLCFGD) API

list contents can be further restricted by one or more qual- description type parameter, an error message is
ifiers, specified as parameters. returned. A null list is returned if no configuration
descriptions meet the qualifications. If this parameter is
set to all blanks, no object qualification is performed.
Authorities and Locks This parameter is divided into four 10-character fields.
Configuration Description Authority
The primary qualifier value is placed in the first 10 char-
*USE
acters of the parameter. The allowable values are:
| User Space Authority
| *CHANGE Object name Object of this name only, of the specified
| User Space Library Authority configuration description type
| *USE Generic object name
(If one or more listed objects do not meet the authority All objects that have names matching the
requirement, they will be omitted from the returned list. generic string, of the specified configura-
Only objects to which the user has proper authority are tion description type
in the list.) *ALL All objects of the specified configuration
description type
*APPC APPC controllers and devices only
Required Parameter Group *ASYNC Asynchronous lines, controllers, and
devices only
Qualified user space name
*ATM Asynchronous transfer mode network
INPUT; CHAR(20)
interfaces only
The user space that receives the information, and the *BSC BSC lines, controllers, and devices only
library in which it is located. The user must have *CMN Communications controllers or devices
read/write access to this space. The first 10 characters only
contain the user space name, and the second 10 char- | *CRP Cryptographic devices only
acters contain the library name. You can use these *DDI Distributed data interface lines only
special values for the library name: *DKT Diskette devices only
*DSP Display devices only
*CURLIB The job’s current library
*ELAN Ethernet lines only
*LIBL The library list
*FAX Fax lines only
Format name *FNC Finance controllers and devices only
INPUT; CHAR(8) *FR Frame relay network interfaces and lines
only
The content and format of the list returned. The pos-
*HOST Host controllers and devices only
sible format names are:
*IDLC IDLC lines only
CFGD0100 List of selected configuration descriptions *INTRA Intrasystem devices only
CFGD0200 List of selected configuration descriptions, *ISDN Integrated Services Digital Network
plus current status of each one (ISDN) network interfaces only
*LANPRT LAN printer devices only
See “Format of Configuration Lists” on page 16-5 for a *LCLDSP Local display devices only
description of these formats. *LCLPRT Local printer devices only
Configuration description type *LOC Devices that match the specified remote
INPUT; CHAR(10) location name only
*LWS Local work station controllers only
The type of configuration descriptions to be included in *MLB Media library devices only
the list. The possible description types are: *NET Network lines, controllers, or devices only
*LIND Line descriptions *OPT Optical devices only
*CTLD Controller descriptions *OPTICAL All optical devices and optical media
*DEVD Device descriptions library devices (equivalent to *OPT plus
*NWID Network interface descriptions *OPTMLB)
*NWSD Network server descriptions *OPTMLB Optical media library devices only
*NTBD NetBIOS descriptions *PPP Point-to-point lines only
*IPXD Internetwork Packet Exchange (IPX) *PRT Printer devices only
descriptions *RMTDSP Remote display devices only
*RMTPRT Remote printer devices only
Object qualifier *RSRC Network interfaces, lines, controllers, or
INPUT; CHAR(40) devices that match the specified resource
A restriction on the objects to be listed. If a qualifier is name only
specified that is inconsistent with the configuration *RTL Retail controllers and devices only
*RWS Remote work station controllers only

Chapter 16. Configuration APIs 16-3

 List Configuration Descriptions (QDCLCFGD) API

*SDLC SDLC lines only

If... Then...
*SNPT SNPT devices and SNPT-class devices
only (SNPT-class devices include printer, Configuration description type Type qualifier value may be
parameter is *CTLD or placed in third 10 characters
display, finance, and retail devices)
*DEVD
*SNUF SNA upline facility devices only
| *T1 Network interface of type T1. Note: If a type qualifier is specified with any other value for the
*TAP Tape devices and controllers only configuration description type parameter, an error message is
returned.
*TAPE All tape devices and tape media library
devices (equivalent to *TAP plus A list of valid type values can be found in the Local Device
*TAPMLB) Configuration book. If the type value is not valid, a null list is
returned.
*TAPMLB Tape media library devices only
*TDLC TDLC lines only
*TRLAN Token-ring lines only If... Then...
*VWS Virtual work station controllers only
Configuration description type Model qualifier value may be
*VRTDSP Virtual display devices only parameter is *CTLD or placed in fourth 10 characters
*VRTPRT Virtual printer devices only *DEVD and type qualifier is
*WLS Wireless lines only coded in third 10 characters
*WS Work station controllers only
Note: If a model qualifier value is specified with any other
*X25 X.25 lines only value for the configuration description type parameter or if the
type qualifier is blank, an error message is returned.
The information in the following tables describes the
requirements for the first (primary qualifier), second, A list of valid model values can be found in the Local Device
third, and fourth 10 characters of this parameter. Configuration book. If the model value is not valid, a null list is
returned.

If... Then...
Status qualifier
Configuration description type The last 2 characters of the
INPUT; CHAR(20)
parameter is *NWSD and the 10-character primary qualifier
primary qualifier equals an must be blanks Specifies a logical operator and a status value that are
object name used to qualify which configuration descriptions are
Note: This is because network server names can only be up to included in the list. The first 10 bytes contain a logical
8 characters. operator, left-justified. The valid values for the logical
operator are:
If... Then... *GT Greater than
Configuration description type Primary qualifier must be *GE Greater than, or equal to
parameter is *NWSD specified as only *ALL, *LT Less than
*RSRC, or an object name *LE Less than, or equal to
Configuration description type Primary qualifier must be *EQ Equal to
parameter is *NTBD specified as only *ALL or an *NE Not equal to
object name
The second 10 bytes contain a value denoting status,
Configuration description type Primary qualifier must be left-justified. The allowed status values, in order of pre-
parameter is *IPXD specified as only *ALL or an cedence, are:
object name
*ACTIVE Object is active.
*VARYON Object is varied on.
If... Then...
*VARYOFF Object is varied off.
Configuration description type Remote location name to be
parameter is *DEVD and used is placed in second 10 The value in the second 10 bytes has an inherent hier-
primary qualifier is *LOC characters archy: *ACTIVE is “greater than” *VARYON, and
Note: If a remote location name is specified with any other *VARYON is “greater than” *VARYOFF. The two values
combination of the configuration description type parameter and are used together to form a logical qualifier. For
primary qualifier, an error message is returned. example, “\GE \VARYON ” causes only objects
that are active or varied on to be listed. Objects that are
currently varied off are excluded. Both values must be
If... Then...
present if either is present. An invalid logical qualifier
Primary qualifier is *RSRC Resource name to be used is results in a null list being returned. This qualifier must
placed in second 10 charac- be blank if the configuration description type parameter
ters is *NTBD or *IPXD.
Note: If a resource name is specified with any other primary
qualifier, an error message is returned.

16-4 AS/400 System API Reference V4R4

 List Configuration Descriptions (QDCLCFGD) API

Error code Header Section

I/O; CHAR(*)
The structure in which to return error information. For Offset
the format of the structure, see “Error Code Parameter” Dec Hex Type Field
on page 2-6.
0 0 CHAR(10) Configuration description
type used
Format of Configuration Lists 10 A CHAR(40) Object qualifier used
50 32 CHAR(20) Status qualifier used
To request a list of configuration descriptions of a specific
type, use format CFGD0100. To request the current status 70 46 CHAR(2) Reserved
for each description returned, use format CFGD0200. 72 48 CHAR(10) User space name used
82 52 CHAR(10) User space library name
The configuration description list consists of:
used
Ÿ A user area
Ÿ A generic header CFGD0100 Format
Ÿ An input parameter section
Offset
Ÿ A header section
Dec Hex Type Field
Ÿ A list data section:
0 0 CHAR(10) Configuration description
– CFGD0100 format name
– CFGD0200 format 10 A CHAR(10) Configuration description
category
For details about the user area and generic header, see 20 14 CHAR(8) Retrieve API format name
“User Space Format for List APIs” on page 2-4. For details
about the remaining items, see the following sections. For 28 1C CHAR(4) Configuration description
command suffix
detailed descriptions of the fields in the list returned, see
“Field Descriptions” on page 16-6.
CFGD0200 Format
When you retrieve list entry information from a user space,
you must use the entry size returned in the generic header. Offset
The size of each entry may be padded at the end. If you do
Dec Hex Type Field
not use the entry size, the result may not be valid. For
examples of how to process lists, see Appendix A, 0 0 BINARY(4) Current status: numeric
“Examples.” code
4 4 CHAR(10) Configuration description
Input Parameter Section name
14 E CHAR(10) Configuration description
Offset category
Dec Hex Type Field 24 18 CHAR(20) Current status: display-
able text
0 0 CHAR(10) User space name speci-
fied 44 2C CHAR(50) Text description
10 A CHAR(10) User space library name 94 5E CHAR(10) Job name
specified
104 68 CHAR(10) User name
20 14 CHAR(8) Format name specified
114 72 CHAR(6) Job number
28 1C CHAR(10) Configuration description
120 78 CHAR(10) Pass-through device
type specified
130 82 CHAR(8) Retrieve API format name
38 26 CHAR(40) Object qualifier specified
138 8A CHAR(4) Configuration description
78 4E CHAR(20) Status qualifier specified
command suffix
98 62 CHAR(2) Reserved

Chapter 16. Configuration APIs 16-5

List Configuration Descriptions (QDCLCFGD) API

Field Descriptions Controller Controller Controller

Description Cat- Description API Description
Configuration description name. The name of an object egory Format Name Command Suffix
selected for inclusion in the list.
*HOST CTLD0700 HOST
Configuration description category. The value returned in *LWS CTLD1200 LWS
this field depends on the value specified for the configuration *NET CTLD0800 NET
description type parameter when the API was called, as
*RTL CTLD0900 RTL
follows:
*RWS CTLD1000 RWS
Ÿ Line description
*TAP CTLD1300 TAP
If the configuration description type parameter is *LIND
(line description), the value is one of the following. *VWS CTLD1100 VWS
A specific con- Appropriate Appropriate suffix
Note: The Retrieve Line Description (QDCRLIND) API
troller type value format
can be used to retrieve detailed information about the
configuration description. Use a format name shown in
the following table as input when you call the Ÿ Device description
QDCRLIND API. If the configuration description type parameter is *DEVD
(device description), the value is one of the following.
Line Description Line Description Line Description
Note: The Retrieve Device Description (QDCRDEVD)
Category API Format Command Suffix
API can be used to retrieve detailed information about
Name
the configuration description. Use a format name shown
*ASYNC LIND0300 ASC in the following table as input when you call the
*BSC LIND0400 BSC QDCRDEVD API.
*DDI LIND1200 DDI
Device Descrip- Device Descrip- Device Descrip-
*ELAN LIND0500 ETH tion Category tion API Format tion Command
*FAX LIND1400 FAX Name Suffix
*FR LIND1300 FR *APPC DEVD0200 APPC
*IDLC LIND0600 IDLC *ASYNC DEVD0300 ASC
*NET LIND0700 NET *BSC DEVD0400 BSC
*PPP LIND1600 PPP | *CRP DEVD1800 CRP
*SDLC LIND0800 SDLC *DKT DEVD0500 DKT
*TDLC LIND0900 TDLC *DSP DEVD0600 DSP
*TRLAN LIND1000 TRN *FNC DEVD0700 FNC
*WLS LIND1500 WLS *HOST DEVD0800 HOST
*X25 LIND1100 X25 *INTR DEVD0900 INTR
*MLB DEVD1700 MLB
Ÿ Controller description *NET DEVD1000 NET
If the configuration description type parameter is *CTLD *OPT DEVD1600 OPT
(controller description), the value is one of the following:
*OPTMLB DEVD1700 MLB
Note: The Retrieve Controller Description
*PRT DEVD1100 PRT
(QDCRCTLD) API can be used to retrieve detailed infor-
mation about the configuration description. Use a format *RTL DEVD1200 RTL
name shown in the following table as input when you *SNPT DEVD1300 SNPT
call the QDCRCTLD API. *SNUF DEVD1400 SNUF
*TAP DEVD1500 TAP
Controller Controller Controller
Description Cat- Description API Description *TAPMLB DEVD1700 MLB
egory Format Name Command Suffix
A specific device Appropriate Appropriate suffix
*APPC CTLD0300 APPC type value format
*ASYNC CTLD0400 ASC
Ÿ Network interface description
*BSC CTLD0500 BSC
*FNC CTLD0600 FNC

16-6 AS/400 System API Reference V4R4

 List Configuration Descriptions (QDCLCFGD) API

If the configuration description type parameter is *NWID Configuration description type used. The type of
(network interface description), the value is one of the configuration description included in the list.
following:
Current status. The current status of the selected object
Note: There is no API available to retrieve network
using two fields:
interface descriptions. Therefore, the API format name
is set to blanks and is not included in the following table. Ÿ Current status: numeric code
Ÿ Current status: displayable text
| Network Interface Descrip- Network Interface Descrip-
| tion Category tion Command Suffix
Note: The displayable text will be returned translated. This
text is retrieved from message CPX2651 in message file
| *ATM ATM QCPFMSG in *LIBL. The value is one of the following:
| *FR FR
Status Numeric
| *ISDN ISDN Code (decimal) Status Displayable Text
| *T1 T1 0 VARIED OFF
5 AS/36 DISABLED
Ÿ Network server description 20 VARY ON PENDING
30 VARIED ON
If the configuration description type parameter is *NWSD 40 CONNECT PENDING
(network server description), the value is one of the fol- 50 SIGNON DISPLAY
lowing: 60 ACTIVE
62 AS/36 ENABLED
Note: The Retrieve Network Server Description 63 ACTIVE READER
(QDCRNWSD) API can be used to retrieve detailed 66 ACTIVE WRITER
information about the configuration description. Use a 70 HELD
format name shown in the following table as input when 75 POWERED OFF
you call the QDCRNWSD API. The command suffix is 80 RCYPND
set to blanks. 90 RCYCNL
95 SYSTEM REQUEST
96 REBUILD
Network Server Description Network Server Description
100 FAILED
Category API Format Name
103 FAILED READER
*AIX NWSD0500 106 FAILED WRITER
107 SHUTDOWN
*BASE NWSD0400
110 DIAGNOSTIC MODE
*LANSERVER NWSD0200 111 DAMAGED
112 LOCKED
*NETWARE NWSD0300
113 UNKNOWN
*WINDOWSNT NWSD0600
Format name specified. The name specified for the format
Note: The category values are derived from the command to be used in generating the list. The possible formats are:
that is used to create the configuration description. CFGD0100 List of selected configuration descriptions
CFGD0200 List of selected configuration descriptions, plus
Configuration description command suffix. The current status of each one
configuration description command suffix consists of the last
characters (up to 4) that are associated with the create and Job name. The name of the job associated with an active
change command for the configuration description types. device, if applicable.
Note: For the format name values, see the tables defined
Job number. The job number portion of a fully qualified job
for the configuration description category field.
name.
Configuration description type specified. The value spec-
Object qualifier specified. The qualifier values specified
ified for the type of configuration description to be included in
that define which objects are to be included in the generated
the list. The possible types are:
list. See the object qualifier parameter in the “Required
*LIND Line descriptions Parameter Group” on page 16-3 for details on the possible
*CTLD Controller descriptions values.
*DEVD Device descriptions
*NWID Network interface descriptions Object qualifier used. The qualifier values used to deter-
*NWSD Network server descriptions mine which objects are included in the list.
*NTBD NetBIOS descriptions
*IPXD Internetwork Packet Exchange (IPX) descrip- Pass-through device. The name of an upstream device
tions used to complete a pass-through session, if applicable. This
field is only filled in for SNA pass-through devices. These

Chapter 16. Configuration APIs 16-7

 Retrieve Configuration Status (QDCRCFGS) API

devices are created using the Create Device Description CPF9872 E Program or service program &1 in library &2
(SNA Pass-Through) (CRTDEVSNPT) command. If an SNA ended. Reason code &3.
pass-through device does not exist, the field is blank.

Reserved. Space included for alignment.

Retrieve Configuration Status
Retrieve API format name. The format name that is used (QDCRCFGS) API
to retrieve detailed information about a configuration descrip-
tion by using a retrieve API. The following are the available
APIs: Required Parameter Group:
| Retrieve Line Description (QDCRLIND) 1 Receiver variable Output Char(*)
| Retrieve Controller Description (QDCRCTLD) 2 Length of receiver variable Input Binary(4)
| Retrieve Device Description (QDCRDEVD) 3 Format name Input Char(8)
| Retrieve Network Server Description (QDCRNWSD) 4 Configuration description Input Char(10)
type
| Note: This field is filled in only for configuration description 5 Configuration description Input Char(10)
| categories of *LIND, *CTLD, *DEVD, and *NWSD. For the name
| format name values, see the tables defined for the configura- 6 Error code I/O Char(*)
| tion description category field.
Threadsafe: Yes
Status qualifier specified. The status values specified that
define which configuration descriptions are to be included in
the generated list. See the status qualifier parameter in the The Retrieve Configuration Status (QDCRCFGS) API
“Required Parameter Group” on page 16-3 for details on the retrieves the current status of a line, controller, device,
possible values. network interface, or network server description.

Status qualifier used. The status values used to determine

which configuration descriptions are included in the list.
Authorities and Locks
Configuration Description Authority
Text description. The text that describes the selected *USE
object.

User name. The user name portion of a fully qualified job Required Parameter Group
name.
Receiver variable
User space library name specified. The name specified OUTPUT; CHAR(*)
for the library that contains the user space to receive the The variable that is to receive the status information.
generated list. Format CFGS0100 describes the layout of the status
information returned in this variable.
User space library name used. The actual name of the
library used to contain the user space that received the list. Length of receiver variable
INPUT; BINARY(4)
User space name specified. The name specified for the
The length of the area referenced by the receiver vari-
user space that is to receive the generated list.
able parameter. If the amount of information to be
User space name used. The actual name of the user returned is greater than this value, the information is
space that received the list. truncated to this length.

Format name
Error Messages INPUT; CHAR(8)

CPF24B4 E Severe error while addressing parameter list. The content and format of the status information
CPF26A8 E Configuration description type not valid for this returned for the specified configuration description. The
API. format name is:
CPF26A9 E Object qualifier not valid for this API. CFGS0100 Configuration description object status
CPF26AA E
Status qualifier not valid for this API. See “Format of Status Information” on page 16-9 for a
CPF3C21 E description of this format.
Format name &1 is not valid.
Configuration description type
CPF3C90 E
INPUT; CHAR(10)
Literal value cannot be changed.
CPF3CF1 E The type of configuration description object for which
Error code parameter not valid. status is being retrieved. The possible values are:

16-8 AS/400 System API Reference V4R4

 Retrieve Configuration Status (QDCRCFGS) API

*LIND The object is a line description.

Offset
*CTLD The object is a controller description.
*DEVD The object is a device description. Dec Hex Type Field
*NWID The object is a network interface descrip- These fields BINARY(4) Conversation status
tion. repeat for numeric value
*NWSD The object is a network server descrip- each active
CHAR(20) Conversation status text
tion. conversation
value

Configuration description name CHAR(10) Conversation mode name

INPUT; CHAR(10) CHAR(10) Conversation job name
The name of the line, controller, device or network inter- CHAR(10) Conversation user name
face for which status is being retrieved. CHAR(6) Conversation job number
Error code These fields CHAR(10) Multiple job name
I/O; CHAR(*) repeat for
CHAR(10) Multiple job user name
each addi-
The structure in which to return error information. For tional job CHAR(6) Multiple job number
the format of the structure, see “Error Code Parameter”
on page 2-6.
Field Descriptions
Format of Status Information
Bytes available. The number of bytes of data available to
Following is the format of the status information returned. be returned. All available data is returned if enough space is
For detailed descriptions of the fields in the list, see “Field provided.
Descriptions.”
Bytes returned. The number of bytes of data returned.
CFGS0100 Format Conversation job name. The job name portion of the quali-
fied job name for an active conversation on an APPC device.
Offset
Dec Hex Type Field Conversation job number. The job number portion of the
qualified job name for an active conversation on an APPC
0 0 BINARY(4) Bytes returned
device.
4 4 BINARY(4) Bytes available
8 8 BINARY(4) Current status: numeric Conversation mode name. The mode name for an active
code conversation on an APPC device.
12 C CHAR(7) Date information retrieved Conversation status numeric value. A numeric value that
19 13 CHAR(6) Time information retrieved represents the current status of an active conversation on an
25 19 CHAR(20) Current Status: display- APPC device. See the current status field for valid status
able text values.
45 2D CHAR(10) Job name Conversation status text value. A text value that repre-
55 37 CHAR(10) User name sents the current status of an active conversation on an
65 41 CHAR(6) Job number APPC device. See the current status field for valid status
values.
71 47 CHAR(10) Pass-through device
81 51 CHAR(3) Reserved Conversation user name. The user name portion of the
qualified job name for an active conversation on an APPC
84 54 BINARY (4) Offset to list of active con-
versations device.

88 58 BINARY(4) Number of active conver- Current status. The current status of the selected object
sations using two fields:
92 5C BINARY(4) Entry length for list of
Ÿ Current status: numeric code
active conversations
Ÿ Current status: displayable text
96 60 BINARY(4) Offset to list of multiple
job information Note: The displayable text is translated when it is returned.
100 64 BINARY(4) Number of multiple jobs This text is retrieved from message CPX2651 in message file
QCPFMSG in library *LIBL.
104 68 BINARY(4) Entry length for list of
multiple jobs
Possible values follow:

Chapter 16. Configuration APIs 16-9

 Retrieve Configuration Status (QDCRCFGS) API

Status Numeric Number of active conversations. The number of entries in

Code (decimal) Status Displayable Text the list of active conversations returned with this format. A
0 VARIED OFF value of zero is returned if the list is empty.
10 VARY OFF PENDING
20 VARY ON PENDING Number of multiple jobs. The number of entries in the list
30 VARIED ON of multiple jobs returned with this format. A value of zero is
32 VARYON/CNN PENDING returned if the list is empty.
40 CONNECT PENDING
50 SIGNON DISPLAY Offset to list of active conversations. The offset, in bytes,
51 ACTIVE/CNN PENDING to the list of active conversations returned with this format. A
60 ACTIVE value of zero is returned if the list is empty.
63 ACTIVE READER
66 ACTIVE WRITER Offset to list of multiple job information. The offset, in
70 HELD
bytes, to the list of multiple jobs returned with this format. A
80 RCYPND
90 RCYCNL
value of zero is returned if the list is empty.
95 SYSTEM REQUEST
100 FAILED Pass-through device. The name of an upstream device
103 FAILED READER used to complete a pass-through session, if applicable.
106 FAILED WRITER
107 SHUTDOWN Reserved. An ignored field.
110 DIAGNOSTIC MODE
111 DAMAGED Time information retrieved. The time that the information
112 LOCKED was provided by the API. It is returned as 6 characters in the
113 UNKNOWN form HHMMSS, where:

Date information retrieved. The date that the information HH Hour

was provided by the API. This is returned as 7 characters in MM Minute
the form CYYMMDD, where: SS Second

C Century, where 0 indicates years 19xx and 1 User name. The user name portion of a fully qualified job
indicates years 20xx. name.
YY Year
MM Month
DD Day Error Messages
CPF24B4 E Severe error while addressing parameter list.
Entry length for list of active conversations. The entry CPF2625 E Not able to allocate object &1.
length, in bytes, of each element in the list of active conver- CPF2634 E Not authorized to object &1.
sations returned with this format. A value of zero is returned CPF26A8 E Configuration description type not valid for this
if the list is empty. API.
CPF26AE E
Entry length for list of multiple jobs. The entry length, in
Network server description &1 not found.
bytes, of each element in the list of multiple jobs returned
CPF2702 E Device description &1 not found.
with this format. A value of zero is returned if the list is
CPF2703 E Controller description &1 not found.
empty.
CPF2704 E Line description &1 not found.
Job name. The name of the job associated with an active CPF27A4 E Network interface description &1 not found.
device, if applicable. CPF3C19 E
Error occurred with receiver variable specified.
Job number. The job number portion of a fully qualified job CPF3C21 E
name. Format name &1 is not valid.
CPF3C24 E
Multiple job name. The job name portion of the qualified Length of the receiver variable is not valid.
| job name for optical, media library, or network (*TEL type CPF3C90 E
| only) devices that are being used by more than one job. Literal value cannot be changed.
CPF3CF1 E
Multiple job number. The job number portion of the quali- Error code parameter not valid.
| fied job name for optical, media library, or network (*TEL CPF8104 E Controller description &4 damaged.
| type only) devices that are being used by more than one job. CPF8105 E Device description &4 damaged.
CPF811D E
Multiple job user name. The user name portion of the qual-
Network interface description &4 damaged.
| ified job name for optical, media library, or network (*TEL
CPF8125 E Line description &4 damaged.
| type only) devices that are being used by more than one job.
CPF814C E
Network server description &4 damaged.

16-10 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

CPF9872 E Program or service program &1 in library &2 CTLD0500 Detailed information for controller cate-
ended. Reason code &3. gory *BSC
CTLD0600 Detailed information for controller cate-
gory *FNC
Retrieve Controller Description CTLD0700 Detailed information for controller cate-
(QDCRCTLD) API gory *HOST
CTLD0800 Detailed information for controller cate-
gory *NET
CTLD0900 Detailed information for controller cate-
Required Parameter Group:
gory *RTL
1 Receiver variable Output Char(*) CTLD1000 Detailed information for controller cate-
2 Length of receiver variable Input Binary(4) gory *RWS
3 Format name Input CHAR(8) CTLD1100 Detailed information for controller cate-
4 Controller name Input Char(10) gory *VWS
5 Error code I/O Char(*) CTLD1200 Detailed information for controller cate-
gory *LWS
Threadsafe: Yes
CTLD1300 Detailed information for controller cate-
gory *TAP
The Retrieve Controller Description (QDCRCTLD) API See “Format of Controller Information” for a description
retrieves information about a controller description. of these formats.

Controller name
Authorities and Locks INPUT; CHAR(10)
Controller Description Authority The name of the controller description to be retrieved.
*USE
Device Description Authority Error code
*USE I/O; CHAR(*)
Controller Description Lock The structure in which to return error information. For
*EXCLRD the format of the structure, see “Error Code Parameter”
Device Description Lock on page 2-6.
*EXCLRD

Format of Controller Information

Required Parameter Group
When the controller category is unknown, specify CTLD0100
Receiver variable
or CTLD0200 and the basic information (including controller
OUTPUT; CHAR(*)
category) will be returned. When the controller category is
The variable that is to receive the controller information. known, specify one of the other category-specific formats.
Length of receiver variable For detailed descriptions of the fields returned in these
INPUT; BINARY(4) formats, see “Field Descriptions” on page 16-21.
The length of the area referenced by the receiver vari-
able parameter. If the amount of information to be CTLD0100 Format: Use this format to find out the con-
returned is greater than this value, the information will be troller category, plus some very basic information about the
truncated to this length. controller. Then you may use the returned controller cate-
gory to select one of the other (category-specific) formats to
Format name call the API again for detailed information about the controller
INPUT; CHAR(8) description. This format also returns the number of devices
The content and format of the information returned for currently attached to this controller.
each controller description. The possible format names
are: Offset

CTLD0100 Basic controller information. Dec Hex Type Field

CTLD0200 Basic controller information, plus list of 0 0 BINARY(4) Bytes returned
attached devices. 4 4 BINARY(4) Bytes available
CTLD0300 Detailed information for controller cate-
8 8 BINARY(4) Number of attached
gory *APPC
devices
CTLD0400 Detailed information for controller cate-
gory *ASC 12 C CHAR(7) Date information retrieved
19 13 CHAR(6) Time information retrieved

Chapter 16. Configuration APIs 16-11

Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
25 19 CHAR(10) Controller name 164 A4 BINARY(4) SDLC connect poll retry
35 23 CHAR(10) Controller category 168 A8 BINARY(4) SDLC NDM poll timer
45 2D CHAR(10) Online at IPL 172 AC BINARY(4) LAN frame retry
55 37 CHAR(50) Text description 176 B0 BINARY(4) LAN connection retry
105 69 CHAR(3) Reserved 180 B4 BINARY(4) LAN response timer
184 B8 BINARY(4) LAN connection timer
CTLD0200 Format: This format returns basic controller 188 BC BINARY(4) LAN acknowledgement
information, plus a list of attached devices. Some basic infor- timer
mation is also included for each attached device.
192 C0 BINARY(4) LAN inactivity timer

Offset 196 C4 BINARY(4) LAN acknowledgement

frequency
Dec Hex Type Field
200 C8 BINARY(4) LAN maximum out-
0 0 Returns everything from standing frames
format CTLD0100
204 CC BINARY(4) LAN access priority
108 6C BINARY(4) Offset to list of attached
devices. 208 D0 BINARY(4) LAN window step

112 70 BINARY(4) Entry length for list of 212 D4 BINARY(4) Default packet size:
attached devices transmit

These fields CHAR(10) Attached device name 216 D8 BINARY(4) Default packet size:
repeat for receive
CHAR(10) Device category
each attached 220 DC BINARY(4) Negotiated packet size:
device CHAR(10) Device type transmit
CHAR(50) Device text description 224 E0 BINARY(4) Negotiated packet size:
receive
CTLD0300 Format: This format returns detailed informa- 228 E4 BINARY(4) Default window size:
tion about a controller of category *APPC. transmit
232 E8 BINARY(4) Default window size:
Offset receive
Dec Hex Type Field 236 EC BINARY(4) Negotiated window size:
transmit
0 0 Returns everything from
format CTLD0100 240 F0 BINARY(4) Negotiated window size:
receive
108 6C BINARY(4) Maximum frame size
244 F4 BINARY(4) X.25 frame retry
112 70 BINARY(4) IDLC default window size
248 F8 BINARY(4) X.25 connection retry
116 74 BINARY(4) IDLC frame retry
252 FC BINARY(4) X.25 response timer
120 78 BINARY(4) IDLC response timer
256 100 BINARY(4) X.25 connection timer
124 7C BINARY(4) IDLC connect retry
260 104 BINARY(4) X.25 delayed connection
128 80 BINARY(4) Predial delay
timer
132 84 BINARY(4) Redial delay
264 108 BINARY(4) X.25 acknowledgement
136 88 BINARY(4) Dial retries timer
140 8C BINARY(4) Disconnect timer: 268 10C BINARY(4) X.25 inactivity timer
minimum connect
272 110 BINARY(4) APPN transmission group
144 90 BINARY(4) Disconnect timer: discon- number
nect delay
276 114 BINARY(4) Autodelete device
148 94 BINARY(4) Short-hold mode discon-
280 118 BINARY(4) User-defined 1
nect limit
284 11C BINARY(4) User-defined 2
152 98 BINARY(4) Short-hold mode discon-
nect timer 288 120 BINARY(4) User-defined 3
156 9C BINARY(4) SDLC poll limit 292 124 BINARY(4) Recovery limits: count
limit
160 A0 BINARY(4) SDLC out limit

16-12 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
296 128 BINARY(4) Recovery limits: time 626 272 CHAR(10) X.25 link protocol
interval
636 27C CHAR(10) X.25 logical channel ID
300 12C BINARY(4) Offset to list of attached
646 286 CHAR(10) X.25 connection pass-
devices
word
304 130 BINARY(4) Entry length for list of
656 290 CHAR(10) X.25 switched line
attached devices
selection
308 134 BINARY(4) Offset to list of switched
666 29A CHAR(10) X.25 user group ID
lines
676 2A4 CHAR(10) X.25 reverse charging
312 138 BINARY(4) Number of switched lines
686 2AE CHAR(10) APPC CP session
316 13C BINARY(4) Entry length for list of
support
switched lines
| 696 2B8 CHAR(10) Remote APPN node type
320 140 CHAR(10) Link type
706 2C2 CHAR(10) APPN minimum switched
330 14A CHAR(10) Controller type
status
340 154 CHAR(10) Switched connection
716 2CC CHAR(10) Model controller descrip-
350 15E CHAR(10) Short-hold mode tion
360 168 CHAR(10) Switched network backup 726 2D6 CHAR(10) Connection network iden-
tifier
370 172 CHAR(10) Activate switched network
backup 736 2E0 CHAR(10) Connection network CP
name
380 17C CHAR(10) APPN capable
746 2EA CHAR(10) Control owner
390 186 CHAR(10) Attached nonswitched line
name 756 2F4 CHAR(218) User facilities
400 190 CHAR(10) Character code 974 3CE CHAR(10) Autocreate device
410 19A CHAR(10) Remote network identifier 984 3D8 CHAR(10) APPN/HPR capable
420 1A4 CHAR(10) Remote control point 994 3E2 CHAR(10) Active switched line
name
1004 3EC CHAR(8) Remote system name
430 1AE CHAR(10) Exchange identifier
1012 3F4 CHAR(10) HPR path switching
440 1B8 CHAR(12) System service control
1022 3FE CHAR(10) System job name
point identifier
1032 408 BINARY(4) Current maximum frame
452 1C4 CHAR(10) Initial connection
size
462 1CE CHAR(10) Dial initiation
| 1036 40C CHAR(10) Message queue: name
472 1D8 CHAR(32) Connection number
| 1046 416 CHAR(10) Message queue: library
504 1F8 CHAR(10) Answer number
| 1056 420 CHAR(10) Current message queue:
514 202 CHAR(10) Activate X.25 network | name
address
| 1066 42A CHAR(10) Current message queue:
524 20C CHAR(10) Connection list | library
534 216 CHAR(10) Connection list entry | 1076 434 CHAR(10) Branch extender role
544 220 CHAR(10) Switched disconnect These fields CHAR(10) Attached device name
repeat for
554 22A CHAR(10) Data link role CHAR(2) Reserved
each attached
564 234 CHAR(10) Station address device
574 23E CHAR(10) SDLC poll priority These fields CHAR(10) Switched line name
repeat for
584 248 CHAR(12) LAN remote adapter CHAR(2) Reserved
each switched
address
line
596 254 CHAR(10) Destination service
access point
CTLD0400 Format: This format returns detailed informa-
606 25E CHAR(10) Source service access
tion about a controller of category *ASC.
point
616 268 CHAR(10) X.25 network level

Chapter 16. Configuration APIs 16-13

Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
0 0 Returns everything from 300 12C CHAR(10) Switched disconnect
format CTLD0100
310 136 CHAR(10) Remote verify
108 6C BINARY(4) Predial delay
320 140 CHAR(10) Local location name
112 70 BINARY(4) Redial delay
330 14A CHAR(10) Local identifier
116 74 BINARY(4) Dial retries
340 154 CHAR(10) PAD emulation
120 78 BINARY(4) File transfer acknowl-
350 15E CHAR(10) X.25 logical channel ID
edgement timer
360 168 CHAR(10) X.25 switched line
124 7C BINARY(4) File transfer retry
selection
128 80 BINARY(4) Default packet size:
370 172 CHAR(10) X.25 user group ID
transmit
380 17C CHAR(10) X.25 reverse charging
132 84 BINARY(4) Default packet size:
receive 390 186 CHAR(218) User facilities
136 88 BINARY(4) Negotiated packet size: | 608 260 CHAR(10) Message queue: name
transmit
| 618 26A CHAR(10) Message queue: library
140 8C BINARY(4) Negotiated packet size:
| 628 274 CHAR(10) Current message queue:
receive
| name
144 90 BINARY(4) Default window size:
| 638 27E CHAR(10) Current message queue:
transmit
| library
148 94 BINARY(4) Default window size:
These fields CHAR(10) Attached device name
receive
repeat for
CHAR(2) Reserved
152 98 BINARY(4) Negotiated window size: each attached
transmit device
156 9C BINARY(4) Negotiated window size: These fields CHAR(10) Switched line name
receive repeat for
CHAR(2) Reserved
each switched
160 A0 BINARY(4) Recovery limits: count
line
limit
164 A4 BINARY(4) Recovery limits: time
interval CTLD0500 Format: This format returns detailed informa-
tion about a controller of category *BSC.
168 A8 BINARY(4) Offset to list of attached
devices
Offset
172 AC BINARY(4) Entry length for list of
attached devices Dec Hex Type Field

176 B0 BINARY(4) Offset to list of switched 0 0 Returns everything from

lines format CTLD0100

180 B4 BINARY(4) Number of entries in list 108 6C BINARY(4) Predial delay

of switched lines 112 70 BINARY(4) Redial delay
184 B8 BINARY(4) Entry length for list of 116 74 BINARY(4) Dial retries
switched lines
120 78 BINARY(4) Recovery limits: count
188 BC CHAR(10) Link type limit
198 C6 CHAR(10) Switched connection 124 7C BINARY(4) Recovery limits: time
208 D0 CHAR(10) Switched network backup interval

218 DA CHAR(10) Activate switched network 128 80 BINARY(4) Offset to list of attached
backup devices

228 E4 CHAR(10) Attached nonswitched line 132 84 BINARY(4) Entry length for list of
name attached devices

238 EE CHAR(10) Initial connection 136 88 BINARY(4) Offset to list of switched

lines
248 F8 CHAR(32) Connection number
140 8C BINARY(4) Number of entries in list
280 118 CHAR(10) Answer number of switched lines
290 122 CHAR(10) Activate X.25 network
address

16-14 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
144 90 BINARY(4) Entry length for list of 140 8C BINARY(4) SDLC connect poll retry
switched lines
144 90 BINARY(4) SDLC NDM poll timer
148 94 BINARY(4) Offset to list of remote
148 94 BINARY(4) LAN frame retry
identifiers
152 98 BINARY(4) LAN connection retry
152 98 BINARY(4) Number of entries in list
of remote identifiers 156 9C BINARY(4) LAN response timer
156 9C BINARY(4) Entry length for list of 160 A0 BINARY(4) LAN connection timer
remote identifiers
164 A4 BINARY(4) LAN acknowledgement
160 A0 CHAR(10) Connection type timer
170 AA CHAR(10) Switched network backup 168 A8 BINARY(4) LAN inactivity timer
180 B4 CHAR(10) Activate switched network 172 AC BINARY(4) LAN acknowledgement
backup frequency
190 BE CHAR(10) Attached nonswitched line 176 B0 BINARY(4) LAN maximum out-
name standing frames
200 C8 CHAR(10) Application type 180 B4 BINARY(4) LAN access priority
210 D2 CHAR(10) Initial connection 184 B8 BINARY(4) LAN window step
220 DC CHAR(32) Connection number 188 BC BINARY(4) Default packet size:
transmit
252 FC CHAR(10) Local identifier
192 C0 BINARY(4) Default packet size:
262 106 CHAR(10) RJE host type
receive
272 110 CHAR(80) RJE host signon/logon
196 C4 BINARY(4) Negotiated packet size:
These fields CHAR(10) Attached device name transmit
repeat for
CHAR(2) Reserved 200 C8 BINARY(4) Negotiated packet size:
each attached
receive
device
204 CC BINARY(4) Default window size:
These fields CHAR(10) Switched line name
transmit
repeat for
CHAR(2) Reserved
each switched 208 D0 BINARY(4) Default window size:
line receive
These fields CHAR(30) Remote identifier 212 D4 BINARY(4) Negotiated window size:
repeat for transmit
CHAR(2) Reserved
each remote
216 D8 BINARY(4) Negotiated window size:
identifier
receive
220 DC BINARY(4) X.25 frame retry
CTLD0600 Format: This format returns detailed informa-
224 E0 BINARY(4) X.25 connection retry
tion about a controller of category *FNC.
228 E4 BINARY(4) X.25 response timer
Offset 232 E8 BINARY(4) X.25 connection timer
Dec Hex Type Field 236 EC BINARY(4) X.25 delayed connection
0 0 Returns everything from timer
format CTLD0100 240 F0 BINARY(4) X.25 acknowledgement
108 6C BINARY(4) Maximum frame size timer

112 70 BINARY(4) Predial delay 244 F4 BINARY(4) X.25 inactivity timer

116 74 BINARY(4) Redial delay 248 F8 BINARY(4) Recovery limits: count

limit
120 78 BINARY(4) Dial retries
252 FC BINARY(4) Recovery limits: time
124 7C BINARY(4) Short-hold mode discon- interval
nect limit
256 100 BINARY(4) Offset to list of attached
128 80 BINARY(4) Short-hold mode discon- devices
nect timer
260 104 BINARY(4) Entry length for list of
132 84 BINARY(4) SDLC poll limit attached devices
136 88 BINARY(4) SDLC out limit

Chapter 16. Configuration APIs 16-15

Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
264 108 BINARY(4) Offset to list of switched These fields CHAR(10) Attached device name
lines repeat for
CHAR(2) Reserved
each attached
268 10C BINARY(4) Number of entries in list
device
of switched lines
These fields CHAR(10) Switched line name
272 110 BINARY(4) Entry length for list of
repeat for
switched lines CHAR(2) Reserved
each switched
276 114 CHAR(10) Controller type line
286 11E CHAR(10) Controller model
296 128 CHAR(10) Link type CTLD0700 Format: This format returns detailed informa-
tion about a controller of category *HOST.
306 132 CHAR(10) Switched connection
316 13C CHAR(10) Short-hold mode Offset
326 146 CHAR(10) Switched network backup Dec Hex Type Field
336 150 CHAR(10) Activate switched network 0 0 Returns everything from
backup format CTLD0100
346 15A CHAR(10) Attached nonswitched line 108 6C BINARY(4) Maximum frame size
name
112 70 BINARY(4) IDLC default window size
356 164 CHAR(10) Character code
116 74 BINARY(4) IDLC frame retry
366 16E CHAR(10) Exchange identifier
120 78 BINARY(4) IDLC response timer
376 178 CHAR(12) System service control
point identifier 124 7C BINARY(4) IDLC connect retry

388 184 CHAR(10) Initial connection 128 80 BINARY(4) Predial delay

398 18E CHAR(32) Connection number 132 84 BINARY(4) Redial delay

430 1AE CHAR(10) Answer number 136 88 BINARY(4) Dial retries

440 1B8 CHAR(10) Activate X.25 network 140 8C BINARY(4) Disconnect timer:
address minimum connect

450 1C2 CHAR(10) Switched disconnect 144 90 BINARY(4) Disconnect timer: discon-
nect delay
460 1CC CHAR(10) Station address
148 94 BINARY(4) LAN frame retry
470 1D6 CHAR(10) SDLC poll priority
152 98 BINARY(4) LAN connection retry
480 1E0 CHAR(12) LAN remote adapter
address 156 9C BINARY(4) LAN response timer

492 1EC CHAR(10) Destination service 160 A0 BINARY(4) LAN connection timer
access point 164 A4 BINARY(4) LAN acknowledgement
502 1F6 CHAR(10) Source service access timer
point 168 A8 BINARY(4) LAN inactivity timer
512 200 CHAR(10) X.25 network level 172 AC BINARY(4) LAN acknowledgement
522 20A CHAR(10) X.25 link protocol frequency

532 214 CHAR(10) X.25 logical channel ID 176 B0 BINARY(4) LAN maximum out-
standing frames
542 21E CHAR(10) X.25 connection pass-
word 180 B4 BINARY(4) LAN access priority

552 228 CHAR(10) X.25 switched line 184 B8 BINARY(4) LAN window step
selection 188 BC BINARY(4) Default packet size:
562 232 CHAR(10) X.25 user group ID transmit

572 23C CHAR(10) X.25 reverse charging 192 C0 BINARY(4) Default packet size:
receive
582 246 CHAR(218) User facilities
196 C4 BINARY(4) Negotiated packet size:
800 320 BINARY(4) Current maximum frame transmit
size
200 C8 BINARY(4) Negotiated packet size:
receive

16-16 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
204 CC BINARY(4) Default window size: 406 196 CHAR(10) Local exchange identifier
transmit
416 1A0 CHAR(10) Initial connection
208 D0 BINARY(4) Default window size:
426 1AA CHAR(10) Dial initiation
receive
436 1B4 CHAR(32) Connection number
212 D4 BINARY(4) Negotiated window size:
transmit 468 1D4 CHAR(10) Answer number
216 D8 BINARY(4) Negotiated window size: 478 1DE CHAR(10) Activate X.25 network
receive address
220 DC BINARY(4) X.25 frame retry 488 1E8 CHAR(10) Connection list
224 E0 BINARY(4) X.25 response timer 498 1F2 CHAR(10) Connection list entry
228 E4 BINARY(4) X.25 acknowledgement 508 1FC CHAR(10) Switched disconnect
timer
518 206 CHAR(10) Station address
232 E8 BINARY(4) X.25 inactivity timer
528 210 CHAR(12) LAN remote adapter
236 EC BINARY(4) APPN transmission group address
number
540 21C CHAR(10) Destination service
240 F0 BINARY(4) Autodelete device access point
244 F4 BINARY(4) User-defined 1 550 226 CHAR(10) Source service access
point
248 F8 BINARY(4) User-defined 2
560 230 CHAR(10) X.25 network level
252 FC BINARY(4) User-defined 3
570 23A CHAR(10) X.25 link protocol
256 100 BINARY(4) Recovery limits: count
limit 580 244 CHAR(10) X.25 logical channel ID
260 104 BINARY(4) Recovery limits: time 590 24E CHAR(10) X.25 connection pass-
interval word
264 108 BINARY(4) Offset to list of attached 600 258 CHAR(10) X.25 switched line
devices selection
268 10C BINARY(4) Entry length for list of 610 262 CHAR(10) X.25 user group ID
attached devices
620 26C CHAR(10) X.25 reverse charging
272 110 BINARY(4) Offset to list of switched
630 276 CHAR(10) APPC CP session
lines
support
276 114 BINARY(4) Number of entries in list
| 640 280 CHAR(10) Remote APPN node type
of switched lines
650 28A CHAR(10) APPN minimum switched
280 118 BINARY(4) Entry length for list of
status
switched lines
660 294 CHAR(10) Recontact at vary off
284 11C CHAR(10) Link type
670 29E CHAR(10) Autocreate device
294 126 CHAR(10) Switched connection
680 318 CHAR(218) User facilities
304 130 CHAR(10) Short-hold mode
898 382 CHAR(10) APPN/HPR capable
314 13A CHAR(10) Switched network backup
908 38C CHAR(10) Primary DLUS name—PU
324 144 CHAR(10) Activate switched network
name
backup
918 396 CHAR(10) Primary DLUS
334 14E CHAR(10) APPN capable
name—network ID
344 158 CHAR(10) Attached nonswitched line
928 3A0 CHAR(10) Backup DLUS name—PU
name
name
354 162 CHAR(10) Character code
938 3AA CHAR(10) Backup DLUS
364 16C CHAR(10) Remote network identifier name—network ID
374 176 CHAR(10) Remote control point 948 3B4 CHAR(10) Dependent PU name
name
958 3BE CHAR(2) Reserved/unused for
384 180 CHAR(10) Adjacent link station alignment
394 18A CHAR(12) System service control 960 3C0 BINARY(4) Activation timer
point identifier

Chapter 16. Configuration APIs 16-17

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
964 3C4 BINARY(4) Reconnect timer 120 78 BINARY(4) Dial retries
968 3C8 CHAR(10) HPR path switching 124 7C BINARY(4) SDLC poll limit
978 3D2 CHAR(2) Reserved 128 80 BINARY(4) SDLC out limit
980 3D4 BINARY(4) Current maximum frame 132 84 BINARY(4) SDLC connect poll retry
size
136 88 BINARY(4) SDLC NDM poll timer
| 984 3D8 CHAR(10) Message queue: name
140 8C BINARY(4) LAN frame retry
| 994 3E2 CHAR(10) Message queue: library
144 90 BINARY(4) LAN connection retry
| 1004 3EC CHAR(10) Current message queue:
148 94 BINARY(4) LAN response timer
| name
152 98 BINARY(4) LAN connection timer
| 1014 3F6 CHAR(10) Current message queue:
| library 156 9C BINARY(4) LAN acknowledgement
timer
| 1024 400 CHAR(10) Branch extender role
160 A0 BINARY(4) LAN inactivity timer
These fields CHAR(10) Attached device name
repeat for 164 A4 BINARY(4) LAN acknowledgement
CHAR(2) Reserved
each attached frequency
device
168 A8 BINARY(4) LAN maximum out-
These fields CHAR(10) Switched line name standing frames
repeat for
CHAR(2) Reserved 172 AC BINARY(4) LAN access priority
each switched
line 176 B0 BINARY(4) LAN window step
180 B4 BINARY(4) Default packet size:
CTLD0800 Format: This format returns detailed informa- transmit
tion about a controller of category *NET. 184 B8 BINARY(4) Default packet size:
receive
Offset 188 BC BINARY(4) Negotiated packet size:
Dec Hex Type Field transmit

0 0 Returns everything from 192 C0 BINARY(4) Negotiated packet size:

format CTLD0100 receive

108 6C BINARY(4) Connection response 196 C4 BINARY(4) Default window size:

timer transmit

112 70 BINARY(4) Offset to list of attached 200 C8 BINARY(4) Default window size:
devices receive

116 74 BINARY(4) Entry length for list of 204 CC BINARY(4) Negotiated window size:
attached devices transmit

120 78 CHAR(10) Attached line 208 D0 BINARY(4) Negotiated window size:

receive
These fields CHAR(10) Attached device name
repeat for 212 D4 BINARY(4) X.25 frame retry
CHAR(2) Reserved
each attached 216 D8 BINARY(4) X.25 connection retry
device
220 DC BINARY(4) X.25 response timer
224 E0 BINARY(4) X.25 connection timer
CTLD0900 Format: This format returns detailed informa-
tion about a controller of category *RTL. 228 E4 BINARY(4) X.25 delayed connection
timer
Offset 232 E8 BINARY(4) Recovery limits: count
limit
Dec Hex Type Field
236 EC BINARY(4) Recovery limits: time
0 0 Returns everything from
interval
format CTLD0100
240 F0 BINARY(4) Offset to list of attached
108 6C BINARY(4) Maximum frame size
devices
112 70 BINARY(4) Predial delay
244 F4 BINARY(4) Entry length for list of
116 74 BINARY(4) Redial delay attached devices

16-18 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
248 F8 BINARY(4) Offset to list of switched These fields CHAR(10) Switched line name
lines repeat for
CHAR(2) Reserved
each switched
252 FC BINARY(4) Number of entries in list
line
of switched lines
256 100 BINARY(4) Entry length for list of
switched lines CTLD1000 Format: This format returns detailed informa-
tion about a controller of category *RWS.
260 104 CHAR(10) Controller type
270 10E CHAR(10) Controller model Offset
280 118 CHAR(10) Link type Dec Hex Type Field
290 122 CHAR(10) Switched line 0 0 Returns everything from
300 12C CHAR(10) Switched network backup format CTLD0100

310 136 CHAR(10) Activate switched network 108 6C BINARY(4) Device wait timer
backup 112 70 BINARY(4) Maximum frame size
320 140 CHAR(10) Attached nonswitched line 116 74 BINARY(4) IDLC default window size
name
120 78 BINARY(4) IDLC frame retry
330 14A CHAR(10) Character code
124 7C BINARY(4) IDLC response timer
340 154 CHAR(10) Exchange identifier
128 80 BINARY(4) IDLC connect retry
350 15E CHAR(12) System service control
point identifier 132 84 BINARY(4) Predial delay

362 16A CHAR(10) Initial connection 136 88 BINARY(4) Redial delay

372 174 CHAR(32) Connection number 140 8C BINARY(4) Dial retries

404 194 CHAR(10) Answer number 144 90 BINARY(4) Short-hold mode discon-
nect limit
414 19E CHAR(10) Activate X.25 network
address 148 94 BINARY(4) Short-hold mode discon-
nect timer
424 1A8 CHAR(10) Switched disconnect
152 98 BINARY(4) SDLC poll limit
434 1B2 CHAR(10) Station address
156 9C BINARY(4) SDLC out limit
444 1BC CHAR(10) SDLC poll priority
160 A0 BINARY(4) SDLC connect poll retry
454 1C6 CHAR(12) LAN remote adapter
address 164 A4 BINARY(4) SDLC NDM poll timer

466 1D2 CHAR(10) Destination service 168 A8 BINARY(4) LAN frame retry
access point 172 AC BINARY(4) LAN connection retry
476 1DC CHAR(10) Source service access 176 B0 BINARY(4) LAN response timer
point
180 B4 BINARY(4) LAN connection timer
486 1E6 CHAR(10) X.25 network level
184 B8 BINARY(4) LAN acknowledgement
496 1F0 CHAR(10) X.25 logical channel ID timer
506 1FA CHAR(10) X.25 connection pass- 188 BC BINARY(4) LAN inactivity timer
word
192 C0 BINARY(4) LAN acknowledgement
516 204 CHAR(10) X.25 switched line frequency
selection
196 C4 BINARY(4) LAN maximum out-
526 20E CHAR(10) X.25 user group ID standing frames
536 218 CHAR(10) X.25 reverse charging 200 C8 BINARY(4) LAN access priority
546 222 CHAR(218) User facilities 204 CC BINARY(4) LAN window step
764 2FC BINARY(4) Current maximum frame 208 D0 BINARY(4) Default packet size:
size transmit
These fields CHAR(10) Attached device name 212 D4 BINARY(4) Default packet size:
repeat for receive
CHAR(2) Reserved
each attached
device 216 D8 BINARY(4) Negotiated packet size:
transmit

Chapter 16. Configuration APIs 16-19

Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
220 DC BINARY(4) Negotiated packet size: 420 1A4 CHAR(10) Remote network identifier
receive
430 1AE CHAR(10) Exchange identifier
224 E0 BINARY(4) Default window size:
440 1B8 CHAR(12) System service control
transmit
point identifier
228 E4 BINARY(4) Default window size:
452 1C4 CHAR(10) Initial connection
receive
462 1CE CHAR(10) Dial initiation
232 E8 BINARY(4) Negotiated window size:
transmit 472 1D8 CHAR(32) Connection number
236 EC BINARY(4) Negotiated window size: 504 1F8 CHAR(10) Answer number
receive
514 202 CHAR(10) Activate X.25 network
240 F0 BINARY(4) X.25 frame retry address
244 F4 BINARY(4) X.25 connection retry 524 20C CHAR(10) Connection list
248 F8 BINARY(4) X.25 response timer 534 216 CHAR(10) Connection list entry
252 FC BINARY(4) X.25 connection timer 544 220 CHAR(10) Station address
256 100 BINARY(4) X.25 delayed connection 554 22A CHAR(10) SDLC poll priority
timer
564 234 CHAR(12) LAN remote adapter
260 104 BINARY(4) X.25 acknowledgement address
timer
576 240 CHAR(10) Destination service
264 108 BINARY(4) X.25 inactivity timer access point
268 10C BINARY(4) Allocation retry timer 586 24A CHAR(10) Source service access
point
272 110 BINARY(4) Recovery limits: count
limit 596 254 CHAR(10) X.25 network level
276 114 BINARY(4) Recovery limits: time 606 25E CHAR(10) X.25 link protocol
interval
616 268 CHAR(10) X.25 logical channel ID
280 118 BINARY(4) Offset to list of attached
626 272 CHAR(10) X.25 connection pass-
devices
word
284 11C BINARY(4) Entry length for list of
636 27C CHAR(10) X.25 switched line
attached devices
selection
288 120 BINARY(4) Offset to list of switched
646 286 CHAR(10) X.25 user group ID
lines
656 290 CHAR(10) X.25 reverse charging
292 124 BINARY(4) Number of entries in list
of switched lines 666 29A CHAR(218) User facilities
296 128 BINARY(4) Entry length for list of 884 374 CHAR(10) Autocreate device
switched lines 894 37E CHAR(10) Switched disconnect
300 12C CHAR(10) Controller type 904 388 CHAR(10) Associated APPC device
310 136 CHAR(10) Controller model 914 392 CHAR(10) Serial number
320 140 CHAR(10) Link type 924 39C CHAR(10) Release level
330 14A CHAR(10) Switched connection 934 3A6 CHAR(2) Reserved
340 154 CHAR(10) Short-hold mode 936 3A8 BINARY(4) Current maximum frame
350 15E CHAR(10) Switched network backup size
360 168 CHAR(10) Activate switched network | 940 3AC CHAR(10) Message queue: name
backup | 950 3B6 CHAR(10) Message queue: library
370 172 CHAR(10) Attached nonswitched line | 960 3C0 CHAR(10) Current message queue:
name | name
380 17C CHAR(10) TDLC line name | 970 3CA CHAR(10) Current message queue:
390 186 CHAR(10) Character code | library
400 190 CHAR(10) Remote location name
410 19A CHAR(10) Local location name

16-20 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
These fields CHAR(10) Attached device name 180 B4 CHAR(10) Initialization source file
repeat for library name
CHAR(10) Serial number
each attached
190 BE CHAR(10) Initialization source
device
member name
These fields CHAR(10) Switched line name
200 C8 CHAR(10) Initialization program
repeat for
CHAR(2) Reserved name
each switched
line 210 D2 CHAR(10) Initialization program
library name

CTLD1100 Format: This format returns detailed informa- | 220 DC CHAR(10) Message queue: name
tion about a controller of category *VWS. | 230 E6 CHAR(10) Message queue: library
| 240 F0 CHAR(10) Current message queue:
Offset | name
Dec Hex Type Field | 250 FA CHAR(10) Current message queue:
0 0 Returns everything from | library
format CTLD0100 These fields CHAR(10) Attached device name
108 6C BINARY(4) Offset to list of attached repeat for
CHAR(2) Reserved
devices each attached
device
112 70 BINARY(4) Entry length for list of
attached devices
CTLD1300 Format: This format returns detailed informa-
| 116 74 CHAR(10) Message queue: name
tion about a controller of category *TAP.
| 126 7E CHAR(10) Message queue: library
| 136 88 CHAR(10) Current message queue: Offset
| name
Dec Hex Type Field
| 146 92 CHAR(10) Current message queue:
0 0 Returns everything from
| library
format CTLD0100
These fields CHAR(10) Attached device name
108 6C BINARY(4) Offset to list of attached
repeat for
CHAR(2) Reserved devices
each attached
device 112 70 BINARY(4) Entry length for list of
attached devices

CTLD1200 Format: This format returns detailed informa- 116 74 CHAR(10) Controller type
tion about a controller of category *LWS. 126 7E CHAR(10) Controller model
136 88 CHAR(10) Resource name
Offset
146 92 CHAR(10) Automatic configuration
Dec Hex Type Field
These fields CHAR(10) Attached device name
0 0 Returns everything from repeat for
format CTLD0100 CHAR(2) Reserved
each attached
108 6C BINARY(4) Device wait timer device

112 70 BINARY(4) Offset to list of attached

devices
Field Descriptions
116 74 BINARY(4) Entry length for list of
attached devices Fields in the various formats returned by this API are
120 78 CHAR(10) Controller type described in the online command help for the communica-
tions controller parameters.
130 82 CHAR(10) Controller model
140 8C CHAR(10) Resource name In certain cases, numeric values are assigned by this API to
150 96 CHAR(10) TDLC line name represent character values for some of the returned fields.
Where a numeric value is assigned, the numeric value and
160 A0 CHAR(10) Automatic configuration
the equivalent character value are listed as an Exception in
170 AA CHAR(10) Initialization source file the following field descriptions.
name

Chapter 16. Configuration APIs 16-21

Retrieve Controller Description (QDCRCTLD) API

Activate switched network backup (ACTSNBU). Shows Associated APPC device. The APPC device associated
whether the switched network backup is activated. with the remote workstation controller description. This is the
device name that is displayed when F15 (Display associated
Activate X.25 network address (ACTXADR). The current APPC device) is used on the Display Controller Description
X.25 network address for active X.25 controller descriptions. (DSPCTLD) command. If there is no associated APPC
device, the value in this field is blanks.
Activation timer (ACTTMR). This timer is used when the
AS/400 attempts to activate a session to the remote Attached device name (DEV). The name of one or more
dependent-logical-unit-server (DLUS) node (initial connection devices to be attached to this controller. (See the DEV
*DIAL). It is the amount of time this system will wait for an keyword in the online command help.)
answer from the remote DLUS.
Attached line. For network controllers, the name of the line
Active switched line. The switched line that is active and that connects the network to the AS/400 system.
that the controller is using for communications. If no
switched line is active, the value in this field is blanks. Attached nonswitched line name (LINE). The name of the
line description that connects the network to the AS/400
Adjacent link station (ASJLNKSTN). The link station name system. (See the LINE keyword in the online command
of the adjacent system. (See the ADJLNKSTN keyword in help.)
the online command help.)
Autocreate device (AUTOCRTDEV). Which devices are
Allocation retry timer (ALCRTYTMR). The time to wait automatically created. (See the AUTOCRTDEV keyword in
between attempts to activate devices associated with this the online command help.)
controller. (See the ALCRTYTMR keyword in the online
command help.) Autodelete device (AUTODLTDEV). The number of
minutes an automatically created device can remain in an
Answer number (ANSNBR). The X.25 network addresses idle state with no bound sessions and no active conversa-
from which this controller can accept calls. (See the tions on the device. (See the AUTODLTDEV keyword in the
ANSNBR keyword in the online command help.) online command help.)

APPC CP session support (CPSSN). Whether this con- Exception:

troller supports control point-to-control point sessions. (See
Ÿ Value of -2 implies *NO
the CPSSN keyword in the online command help.)
Automatic configuration. Whether this controller has been
Application type (APPTYPE). The type of application that
configured automatically.
this controller is to be used for. (See the APPTYPE keyword
in the online command help.)
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is
APPN capable (APPN). Whether the local AS/400 system
provided.
appears to the adjacent system as either a network node or
an end node in the local system network attributes, or the
Bytes returned. The number of bytes of data returned.
local system appears to the adjacent system as a low-entry
networking node. (See the APPN keyword in the online Backup DLUS name—network ID (BKUDLUS). The
command help.) backup DLUS network ID. This is the network ID of the
APPN network (subnet) that the remote DLUS resides in. It
APPN/HPR capable (HPR). Whether to use APPN high-
is the network qualified CP name of the remote DLUS
performance routing (HPR) support. (See the HPR keyword
(SSCP) that the AS/400 dependent-logical-unit-requester
in the online command help.)
(DLUR) host controller communicates with in the absence of
the primary DLUS node.
APPN minimum switched status (MINSWTSTS). The
minimum status required for this controller description to be
Backup DLUS name—PU name (BKUDLUS). The backup
considered eligible for APPN routing. (See the MINSWTSTS
DLUS name. This is the physical unit name of the remote
keyword in the online command help.)
DLUS. This is the network qualified CP name of the remote
DLUS (SSCP) that the AS/400 DLUR host controller commu-
APPN transmission group number (TMSGRPNBR). The
nicates with in the absence of the primary DLUS node.
value to be used by the APPN support for transmission
group negotiation with the remote system. (See the
| Branch extender role. The role of the the local system in
TMSGRPNBR keyword in the online command help.)
| an APPN network for the remote controller being configured.
| This parameter is used only when the local system supports
Exception:
| the branch extender function. (See the BEXROLE keyword
Ÿ Value of -11 implies *CALC | in the online command help.)

16-22 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Character code (CODE). The type of character code The category value is derived from the command used to
(EBCDIC or ASCII) used to send the information in a remote create the controller description.
work station data stream over the communications line. (See
the CODE keyword in the online command help.) Controller model (MODEL). The model number of the con-
troller. (See the MODEL keyword in the online command
Connection list (CNNLSTOUT). The name of a connection help.)
list containing the network-assigned numbers used for out-
going calls on this controller. (See the CNNLSTOUT Controller name. The name of the controller description.
keyword in the online command help.)
Controller type (TYPE). The type of controller being
Connection list entry (CNNLSTOUTE). The name of the described. (See the TYPE keyword in the online command
connection list entry containing the network-assigned help.)
numbers used for outgoing calls on this controller. (See the
CNNLSTOUTE keyword in the online command help.) Current maximum frame size. The maximum frame size
that is currently being used by this controller. This field is
Connection network CP name (CNNCPNAME). The name only valid for controllers that have been varied on and are
of the connection network control point. (See the connected to a LAN.
CNNCPNAME keyword in the online command help.)
| Current message queue. The message queue to which
Connection network identifier (CNNNETID). The name of | messages are currently being sent using this controller
the connection network identifier. (See the CNNNETID | description. This field is valid only for controllers that are
keyword in the online command help.) | varied on. Note that the value of the current message queue
| may be different from the message queue field (MSGQ
Connection number (CNNNBR). The number (for a | parameter) under certain error conditions. See the MSGQ
switched connection or a nonswitched connection with | keyword in the online command help for more details. This
switched network backup) of the remote controller that is | information is returned in two separate fields:
called from the AS/400 system to establish a connection.
| Ÿ Name of the queue
(See the CNNNBR keyword in the online command help.)
| Ÿ Library in which the queue can be found
Connection response timer (CNNRSPTMR). The amount
of time to wait for a response to an incoming connection Data link role (ROLE). Whether the remote system is
request. (See the CNNRSPTMR keyword in the online primary, secondary, or dynamically negotiates its role. (See
command help.) the ROLE keyword in the online command help.)

Connection type (CNN). The type of connection this BSC Date information retrieved. The date that the information
controller will be used on. (See the CNN keyword in the was provided by the API. This is returned as 7 characters in
online command help.) the form CYYMMDD, where:
C Century, where 0 indicates years 19xx and 1
Control owner (CTLOWN). Whether this description is
indicates years 20xx.
owned by the system or the user. *USER identifies the user
YY Year
as the owner, and *SYS identifies the system as the owner.
MM Month
If the system is the control owner, the user cannot make any
DD Day
changes to the description.
Default packet size (DFTPKTSIZE). The default packet
Controller category. This value will be one of the following:
size to use on the virtual circuit represented by this con-
*APPC troller. This information is returned in two separate fields:
*ASC Ÿ Transmit
*BSC Ÿ Receive
*FNC
(See the DFTPKTSIZE keyword in the online command
*HOST help.)
*LWS
Exceptions:
*NET
Ÿ Value of -10 implies *TRANSMIT
*RTL
Ÿ Value of -16 implies *LIND
*RWS
Default window size (DFTWDWSIZE). The default window
*TAP size to use on the virtual circuit represented by this con-
*VWS troller. This information is returned in two separate fields:
Ÿ Transmit

Chapter 16. Configuration APIs 16-23

Retrieve Controller Description (QDCRCTLD) API

Ÿ Receive Dial retries (DIALRTY). The number of times to retry dialing

the number before considering the dialing unsuccessful.
(See the DFTWDWSIZE keyword in the online command (See the DIALRTY keyword in the online command help.)
help.)
Disconnect timer (DSCTMR). The options for automatic
Exceptions: disconnection. These options are returned in two separate
Ÿ Value of -10 implies *TRANSMIT fields:

Ÿ Value of -16 implies *LIND Ÿ Minimum connect: The minimum length of time the link
stays active after the connection has been made.
Dependent PU name. The dependent location name that is
Ÿ Disconnect delay: The length of time the system delays
used for DLUR, which provides additional security for the
disconnection after the last session for the controller is
connection.
ended.
Destination service access point (DSAP). The logical
(See the DSCTMR keyword in the online command help.)
address that this system will send to when it communicates
with the remote controller. (See the DSAP keyword in the Entry length for list of attached devices. Entry length in
online command help.) bytes of each element in the list of attached devices returned
with this format. A value of zero is returned if the list is
Device category. This value will be one of the following:
empty.
*APPC
Entry length for list of remote identifiers. Entry length in
*ASC
bytes of each element in the list of remote identifiers returned
*BSC with this format. A value of zero is returned if the list is
empty.
*DKT
*DSP Entry length for list of switched lines. Entry length in
bytes of each element in the list of switched lines returned
*FNC
with this format. A value of zero is returned if the list is
*HOST empty.
*INTR
Exchange identifier (EXCHID). A hexadecimal value used
*NET to identify the remote controller. (See the EXCHID keyword
*PRT in the online command help.)

*RTL File transfer acknowledgement timer (ACKTMR). The

*SNPT time allowed, in seconds, for an acknowledgement when
using file transfer support. (See the ACKTMR keyword in the
*SNUF online command help.)
*TAP
File transfer retry (RETRY). The number of attempts to
The category value is derived from the command used to transmit a frame after an unsuccessful transmission when
create the device description. using file transfer support. (See the RETRY keyword in the
online command help.)
Device name. The name of a device associated with this
controller. HPR path switching (HPRPTHSWT). Whether or not path
switching is done for HPR connections that use this controller
Device text description. A brief description of a device at the time the controller is varied off. (See the
associated with this controller. HPRPTHSWT keyword in the online command help.)

Device type (TYPE). The type of device being described. IDLC connect retry (IDLCCNNRTY). The number of times
For a full list of the possible type values, see the TYPE to retry a transmission at connection time. (See the
keyword in the online command help. IDLCCNNRTY keyword in the online command help.)

Device wait timer (DEVWAITTMR). The device wait Exceptions:

time-out value. (See the DEVWAITTMR keyword in the
Ÿ Value of -8 implies *NOMAX
online command help.)
Ÿ Value of -16 implies *LIND
Dial initiation (DIALINIT). Whether or not the system
should dial the remote system or controller immediately when IDLC default window size (IDLCWDWSIZ). The default
this controller description is varied on. (See the DIALINIT window size used for this line description. (See the
keyword in the online command help.) IDLCWDWSIZ keyword in the online command help.)

16-24 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

Exception: Exception:
Ÿ Value of -16 implies *LIND Ÿ Value of -11 implies *CALC

IDLC frame retry (IDLCFRMRTY). The maximum number LAN connection retry (LANCNNRTY). The number of
of transmissions to attempt before reporting an error. (See times a frame will be retransmitted during the connection
the IDLCFRMRTY keyword in the online command help.) establishment if there is no acknowledgement from the
remote controller in the time period specified by the
Exception: LANCNNTMR parameter. (See the LANCNNRTY keyword in
Ÿ Value of -16 implies *LIND the online command help.)

IDLC response timer (IDLCRSPTMR). The length of time Exception:

to wait before retransmitting a frame when an acknowledge- Ÿ Value of -11 implies *CALC
ment is not received. (See the IDLCRSPTMR keyword in the
online command help.) LAN connection timer (LANCNNTMR). The length of time
to wait for an acknowledgement from the remote controller
Exception: during the connection establishment before retransmitting a
Ÿ Value of -16 implies *LIND frame. (See the LANCNNTMR keyword in the online
command help.)
Initial connection (INLCNN). Whether the initial switched
connection is made by the system when it answers an Exception:
incoming call or by a call started from the system. (See the Ÿ Value of -11 implies *CALC
INLCNN keyword in the online command help.)
LAN frame retry (LANFRMRTY). The number of times a
Initialization program library name. The name of the frame will be retransmitted if there is no acknowledgement
library in which the initialization program resides. from the remote controller in the time period specified by the
LANRSPTMR parameter. (See the LANFRMRTY keyword in
Initialization program name. The name of a program that
the online command help.)
is called to manage configuration initialization data.
Exception:
Initialization source file library name. The name of the
library in which the initialization source file resides. Ÿ Value of -11 implies *CALC

Initialization source file name. The name of a source file LAN inactivity timer (LANINACTMR). The length of time
containing configuration initialization data. that the system will wait for a frame from the remote con-
troller before requesting data with a frame of its own. (See
Initialization source member name. The name of a source the LANINACTMR keyword in the online command help.)
member containing configuration initialization data.
Exception:
LAN access priority (LANACCPTY). The priority set in the
Ÿ Value of -11 implies *CALC
actual frames that the system will send to the remote con-
troller. (See the LANACCPTY keyword in the online LAN maximum outstanding frames (LANMAXOUT). The
command help.) maximum number of outstanding frames that the system
sends to the remote controller before it waits for an acknowl-
Exception: edgment. (See the LANMAXOUT keyword in the online
Ÿ Value of -11 implies *CALC command help.)

LAN acknowledgement frequency (LANACKFRQ). The Exception:

maximum number of frames the system can receive before
Ÿ Value of -11 implies *CALC
sending an acknowledgement to the remote controller. (See
the LANACKFRQ keyword in the online command help.) LAN remote adapter address (ADPTADR). The adapter
address of the remote controller. (See the ADPTADR
Exception: keyword in the online command help.)
Ÿ Value of -11 implies *CALC
LAN response timer (LANRSPTMR). The length of time to
LAN acknowledgement timer (LANACKTMR). The length wait for an acknowledgement from the remote controller
of time the system will delay before sending an acknowl- before retransmitting a data frame. (See the LANRSPTMR
edgement to the remote controller for a received data frame. keyword in the online command help.)
(See the LANACKTMR keyword in the online command
help.) Exception:
Ÿ Value of -11 implies *CALC

Chapter 16. Configuration APIs 16-25

 Retrieve Controller Description (QDCRCTLD) API

LAN window step (LANWDWSTP). Whether the number of (See the DFTPKTSIZE keyword in the online command
outstanding frames (frames sent without receiving an help.)
acknowledgement from the remote system) should be
reduced during periods of network congestion. (See the Negotiated window size. The default window size to use
LANWDWSTP keyword in the online command help.) on the virtual circuit represented by this controller. This infor-
mation is returned in two separate fields:
Exception: Ÿ Transmit
Ÿ Value of -3 implies *NONE
Ÿ Receive
Link type (LINKTYPE). The type of line this controller will
(See the DFTWDWSIZE keyword in the online command
be attached to. (See the LINKTYPE keyword in the online
help.)
command help.)
Number of attached devices. The number of elements in
Local exchange identifier (LCLEXCHID). A hexadecimal
the list of attached devices returned with this format. A value
value used to identify the local system to the remote system.
of zero is returned if the list is empty.
(See the LCLEXCHID keyword in the online command help.)
Number of remote identifiers. The number of elements in
Local identifier (LCLID). The name that, when combined
the list of remote identifiers returned with this format. A
with the local location name, identifies your controller to a
value of zero is returned if the list is empty.
remote system. (See the LCLID keyword in the online
command help.) Number of switched lines. The number of elements in the
list of switched lines returned with this format. A value of
Local location name (LCLLOCNAME). The name which,
zero is returned if the list is empty.
when combined with the local identifier, identifies your con-
troller to a remote system. (See the LCLLOCNAME keyword Offset to list of attached devices. The offset in bytes to
in the online command help.) the first element in the list of attached devices returned with
this format. A value of zero is returned if the list is empty.
Maximum frame size (MAXFRAME). The maximum path
information unit (PIU) size that the controller can send or Offset to list of remote identifiers. The offset in bytes to
receive. (See the MAXFRAME keyword in the online the first element in the list of remote identifiers returned with
command help.) this format. A value of zero is returned if the list is empty.

Exception: Offset to list of switched lines. The offset in bytes to the

Ÿ Value of -17 implies *LINKTYPE first element in the list of switched lines returned with this
format. A value of zero is returned if the list is empty.
| Message queue (MSGQ). The message queue to which
| operational messages for this controller should normally be Online at IPL (ONLINE). Whether the controller is varied on
| sent. Note that this is the value entered on the MSGQ automatically when the system is turned on or you want to
| parameter of the CL command, but under certain error condi- vary it on manually by using the Vary Configuration
| tions it may not be the message queue currently in use. See (VRYCFG) command. (See the ONLINE keyword in the
| the current message queue field to determine what message online command help.)
| queue is actually being used at a given time. See the
PAD emulation (PADEML). Whether or not this controller is
| MSGQ keyword in the online command help for more infor-
to emulate an X.25 packet assembler/disassembler (PAD).
| mation. This information is returned in two separate fields:
(See the PADEML keyword in the online command help.)
| Ÿ Name of the queue
Predial delay (PREDIALDLY). The length of time to wait
| Ÿ Library in which the queue can be found
before dialing the number to establish a connection to the
Model controller description (MDLCTL). Whether this con- specified controller. (See the PREDIALDLY keyword in the
troller description is to be used as a model controller for online command help.)
automatically created controller descriptions associated with
Primary DLUS name—network ID (PRIDLUS). The primary
the line description specified on the SWTLINLST parameter.
DLUS network ID. This is the network ID of the APPN
(See the MDLCTL keyword in the online command help.)
network (subnet) that the remote DLUS resides in. It is the
Negotiated packet size. The default packet size to use on network qualified CP name of the remote DLUS (SSCP) that
the virtual circuit represented by this controller. This informa- the AS/400 DLUR host controller prefers to communicate
tion is returned in two separate fields: with.

Ÿ Transmit Primary DLUS name—PU name (PRIDLUS). The primary

Ÿ Receive DLUS name. This is the physical unit name of the remote
DLUS. This is the network qualified CP name of the remote

16-26 AS/400 System API Reference V4R4

 Retrieve Controller Description (QDCRCTLD) API

DLUS (SSCP) that the AS/400 DLUR host controller prefers an adjacent system to which there is an OptiConnect bus
to communicate with. connection. The current system name of that system can be
found by using the Display Network Attributes (DSPNETA)
Reconnect timer (RECNNTMR). command on that system.

This timer is used when a session outage occurs to the Remote verify (RMTVFY). Whether a remote system
remote DLUS node. It is the amount of time the AS/400 requires verification if a generic controller and device are
DLUR support will wait for the DLUS node to drive an acti- configured to accept calls from any X.25 network address.
vation request back to the AS/400. (See the RMTVFY keyword in the online command help.)

Recontact at vary off (RECONTACT). Whether a recontact Reserved. Space included for alignment.
request is to be sent to the host system when this controller
is varied off normally. (See the RECONTACT keyword in the Resource name (RSRCNAME). The unique name that is
online command help.) assigned by the system to the physical equipment (in this
case, a communications port) attached to the system. (See
Recovery limits (CMNRCYLMT). The second-level commu- the RSRCNAME keyword in the online command help.)
nications recovery limit for each controller description. These
limits are returned in two separate fields: RJE host type (RJEHOST). The name of the host system
used by remote job entry. (See the RJEHOST keyword in
Ÿ Count limit: The number of second-level recovery
the online command help.)
attempts to be automatically performed by the system.
Ÿ Time interval: The length of time (in minutes) in which RJE host signon/logon (RJELOGON). The logon informa-
the specified number of second-level recoveries can be tion required by the host system if you specified remote job
attempted. entry as the application type. (See the RJELOGON keyword
in the online command help.)
(See the CMNRCYLMT keyword in the online command
help.) SDLC connect poll retry (CNNPOLLRTY). The number of
connect poll retries that will be attempted before the AS/400
Exception: system indicates an error in contacting the remote system.
Ÿ Value of -14 implies *SYSVAL (See the CNNPOLLRTY keyword in the online command
help.)
Redial delay (REDIALDLY). The length of time to wait
before redialing the number to establish a connection to the Exceptions:
specified controller if the previous attempt was unsuccessful. Ÿ Value of -8 implies *NOMAX
(See the REDIALDLY keyword in the online command help.)
Ÿ Value of -11 implies *CALC
Release level. The release level reported by the remote
SDLC NDM poll timer (NDMPOLLTMR). The minimum
control unit the last time the controller was varied on. The
interval at which a secondary station should be polled if a
value is blanks when no release level is reported.
poll from the primary to the secondary station (which is in
Remote control point name (RMTCPNAME). The name of normal disconnect mode) does not result in receiving the
the remote control point. (See the RMTCPNAME keyword in appropriate response. (See the NDMPOLLTMR keyword in
the online command help.) the online command help.)

Remote identifier. The identifier used to identify the remote Exception:

system to the local system. Ÿ Value of -11 implies *CALC

Remote location name (RMTLOCNAME). The name by SDLC out limit (OUTLMT). The number of additional frame
which the remote work station controller is known to the sequences the AS/400 system will send to the controller
network. (See the RMTLOCNAME keyword in the online before polling the next station in the poll list. (See the
command help.) OUTLMT keyword in the online command help.)

Remote network identifier (RMTNETID). The name of the Exception:

remote network in which the adjacent control point resides.
Ÿ Value of -18 implies *POLLLMT
(See the RMTNETID keyword in the online command help.)
SDLC poll limit (POLLLMT). The number of additional con-
| Remote APPN node type (NODETYPE). The type of node
secutive polls that the AS/400 system will send to a controller
| that this controller represents. (See the NODETYPE
when that controller responds by sending a number of
| keyword in the online command help.)
frames equal to the maximum outstanding frames (MAXOUT
Remote system name (RMTSYSNAME). The remote parameter) specified on the line description. (See the
system name supplied should be a current system name of POLLLMT keyword in the online command help.)

Chapter 16. Configuration APIs 16-27

Retrieve Controller Description (QDCRCTLD) API

SDLC poll priority (POLLPTY). Whether this controller System service control point identifier (SSCPID). The
should have priority when being polled. (See the POLLPTY system service control point identifier that the AS/400 system
keyword in the online command help.) sends to the remote system in the activate physical unit
(ACTPU) request. (See the SSCPID keyword in the online
Serial number. The serial number reported by the resource command help.)
the last time the resource was varied on. The value is
blanks when no serial number is reported. TDLC line name. The name of a line associated with this
controller.
Short-hold mode (SHM). Whether this controller is used for
X.21 short-hold mode. (See the SHM keyword in the online Text description (TEXT). A brief description of the con-
command help.) troller and its location. (See the TEXT keyword in the online
command help.)
Short-hold mode disconnect limit (SHMDSCLMT). The
number of consecutive nonproductive responses (RR or Time information retrieved. The time that the information
RNR) that are required from the remote station before the was provided by the API. It is returned as 6 characters in
connection can be suspended for this X.21 short-hold mode the form HHMMSS, where:
connection. (See the SHMDSCLMT keyword in the online
HH Hour
command help.)
MM Minute
Exception: SS Second

Ÿ Value of -8 implies *NOMAX User facilities (USRFCL). Allows network subscribers to

request network-supplied facilities that are not available
Short-hold mode disconnect timer (SHMDSCTMR). The through the AS/400 parameters. (See the USRFCL keyword
minimum length of time that the primary station will maintain in the online command help.)
the connection to the remote system for this X.21 short-hold
mode controller. (See the SHMDSCTMR keyword in the User-defined 1, 2, and 3 (USRDFN1, USRDFN2,
online command help.) USRDFN3). Used to describe any unique characteristics of
this connection that you want to control. (See the
Source service access point (SSAP). The logical address USRDFN1, USRDFN2, and USRDFN3 keywords in the
this system will use when it sends data to the remote con- online command help.)
troller. (See the SSAP keyword in the online command
help.) Exception:
Ÿ Value of -16 implies *LIND
Station address (STNADR). The station address to be
used when communicating with the remote system using
X.25 acknowledgement timer (X25ACKTMR). The ELLC
SDLC. (See the STNADR keyword in the online command
LT2 acknowledgement timer, which is only used for control-
help.)
lers that have the X.25 link protocol (LINKPCL) set to *ELLC.
(See the X25ACKTMR keyword in the online command help.)
Switched connection. Whether this controller is attached to
a switched line, a local area network, or an X.25 switched
X.25 connection password. For X.25 SVC connections, the
virtual circuit (SVC) connection. (See the SWITCHED
password used when connecting to this controller.
keyword in the online command help.)
X.25 connection retry (X25CNNRTY). Same as the
Switched disconnect (SWTDSC). Whether the switched
X25FRMRTY parameter, except that it applies only to logical
connection is dropped when the last session is unbound and
link control (LLC) connection establishment, such as
the disconnect timer (DSCTMR) has ended. (See the
LSABME-LUA LLC protocol data units for ELLC and
SWTDSC keyword in the online command help.)
QSM-QUA for QLLC LLC protocol data units. (See the
X25CNNRTY keyword in the online command help.)
Switched line. Whether this controller is attached to a
switched line. (See the SWITCHED keyword in the online
X.25 connection timer (X25CNNTMR). Same as the
command help.)
X25RSPTMR parameter, except that it applies only to LLC
connection establishment, such as LSABME-LUA LLC pro-
Switched line name. The name of a line that can be con-
tocol data units for ELLC and QSM-QUA LLC protocol data
nected to this controller for switched connections. (See the
units for QLLC. (See the X25CNNTMR keyword in the
SWTLINLST keyword in the online command help.)
online command help.)
Switched network backup (SNBU). Whether you want the
X.25 delayed connection timer (X25DLYTMR). The time
switched network backup capability. (See the SNBU
between retries of polling exchange identifier commands
keyword in the online command help.)
when the system is trying to establish a connection to the
System job name. The name of the system job that is remote data terminal equipment (DTE) represented by the
associated with this controller.

16-28 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

controller description. (See the X25DLYTMR keyword in the CPF26A7 E Category of object not compatible with API
online command help.) format.
CPF2702 E Device description &1 not found.
Exception: CPF2703 E Controller description &1 not found.
Ÿ Value of -11 implies *CALC CPF3C19 E
Error occurred with receiver variable specified.
X.25 frame retry (X25FRMRTY). The number of times that CPF3C21 E
a data or logical link disconnection protocol data unit (PDU) Format name &1 is not valid.
can be retransmitted if no acknowledgement is received from CPF3C24 E
the adjacent logical link station in the remote DTE in the time Length of the receiver variable is not valid.
specified by the X.25 response timer (X25RSPTMR). (See CPF3CF1 E
the X25FRMRTY keyword in the online command help.) Error code parameter not valid.
CPF3C90 E
X.25 inactivity timer (X25INACTMR). The ELLC LTI inac- Literal value cannot be changed.
tivity timer, which is only used for controllers that have the CPF8104 E Controller description &4 damaged.
X.25 link protocol (LINKPCL) set to *ELLC. (See the CPF8105 E Device description &4 damaged.
X25INACTMR keyword in the online command help.) CPF8125 E Line description &4 damaged.
CPF9872 E Program or service program &1 in library &2
X.25 link protocol (LINKPCL). The logical link protocol to
ended. Reason code &3.
be used to communicate with the remote DTE represented
by this controller description. (See the LINKPCL keyword in
the online command help.)
Retrieve Device Description (QDCRDEVD)
X.25 logical channel ID (LGLCHLID). The logical channel API
identifier that is to be used for this controller. (See the
LGLCHLID keyword in the online command help.)
Required Parameter Group:
X.25 network level (NETLVL). The level of the support by
the X.25 network and the remote DTE represented by this 1 Receiver variable Output Char(*)
controller description. (See the NETLVL keyword in the 2 Length of receiver variable Input Binary(4)
online command help.) 3 Format name Input Char(8)
4 Device name Input Char(10)
X.25 response timer (X25RSPTMR). The maximum amount 5 Error code I/O Char(*)
of time allowed between the transmission of a data or logical
Threadsafe: Yes
link disconnection link protocol data unit (PDU) and the
receipt of a corresponding acknowledgement from the adja-
cent link station on the remote DTE. (See the X25RSPTMR The Retrieve Device Description (QDCRDEVD) API retrieves
keyword in the online command help.) information about a device description.
X.25 reverse charging (RVSCRG). For incoming calls,
whether reverse charging will be accepted, and for outgoing Authorities and Locks
calls, whether reverse charging will be requested. (See the
Device Description Authority
RVSCRG keyword in the online command help.)
*USE
X.25 switched line selection (SWTLINSLCT). Which of the | User-Defined Data Authority
lines listed on the SWTLINLST parameter will be selected for | *USE
making the switched connection. (See the SWTLINSLCT Device Description Lock
keyword in the online command help.) *EXCLRD

X.25 user group ID (USRGRPID). A value that is supplied

Required Parameter Group
as a unique identifier by the network if the closed user group
facility is subscribed to. (See the USRGRPID keyword in the Receiver variable
online command help.) OUTPUT; CHAR(*)
The variable that is to receive the device information.
Error Messages Length of receiver variable
CPF24B4 E Severe error while addressing parameter list. INPUT; BINARY(4)
CPF2625 E Not able to allocate object &1.
The length of the area referenced by the receiver vari-
CPF2634 E Not authorized to object &1.
able parameter. If the amount of information to be
CPF268B E &1 not valid for controller &2.
returned is greater than this value, the information will be
truncated to this length.

Chapter 16. Configuration APIs 16-29

 Retrieve Device Description (QDCRDEVD) API

Format name Format of Device Information

INPUT; CHAR(8)
The content and format of the information returned for When the device category is unknown, specify DEVD0100
each device description. The possible format names and the basic information (including device category) will be
are: returned. When the device category is known, specify one of
the other category-specific formats.
DEVD0100 Basic device information.
DEVD0200 Detailed information for device category For detailed descriptions of the fields returned in these
*APPC formats, see “Field Descriptions” on page 16-37.
DEVD0300 Detailed information for device category
*ASC DEVD0100 Format: Use this format to find out the device
DEVD0400 Detailed information for device category category, plus some basic information about the device.
*BSC Then you may use the returned device category to select
DEVD0500 Detailed information for device category one of the other (category-specific) formats to call the API
*DKT again for detailed information about the device description.
DEVD0600 Detailed information for device category
*DSP Offset
DEVD0700 Detailed information for device category Dec Hex Type Field
*FNC
0 0 BINARY(4) Bytes returned
DEVD0800 Detailed information for device category
*HOST 4 4 BINARY(4) Bytes available
DEVD0900 Detailed information for device category 8 8 CHAR(7) Date information retrieved
*INTR
15 F CHAR(6) Time information retrieved
DEVD1000 Detailed information for device category
*NET 21 15 CHAR(10) Device name
DEVD1100 Detailed information for device category 31 1F CHAR(10) Device category
*PRT 41 29 CHAR(10) Online at IPL
DEVD1200 Detailed information for device category
*RTL 51 33 CHAR(50) Text description
DEVD1300 Detailed information for device category 101 65 CHAR(3) Reserved
*SNPT
DEVD1400 Detailed information for device category DEVD0200 Format: This format returns detailed informa-
*SNUF tion about a device of category *APPC.
DEVD1500 Detailed information for device category
*TAP Offset
DEVD1600 Detailed information for device category
*OPT Dec Hex Type Field
DEVD1700 Detailed information for device category 0 0 Returns everything from
*MLB format DEVD0100
| DEVD1800 Detailed information for device category 104 68 BINARY(4) Offset to list of mode
| *CRP names

See “Format of Device Information” for a description of 108 6C BINARY(4) Number of mode names
these formats. 112 70 BINARY(4) Entry length for list of
mode names
Device name
INPUT; CHAR(10) 116 74 CHAR(10) Remote location name
126 7E CHAR(10) Local location name
The name of the device description to be retrieved.
136 88 CHAR(10) Remote network identifier
Error code
146 92 CHAR(10) Attached nonswitched
I/O; CHAR(*)
controller name
The structure in which to return error information. For
156 9C CHAR(10) Message queue: name
the format of the structure, see “Error Code Parameter”
on page 2-6. 166 A6 CHAR(10) Message queue: library
176 B0 CHAR(10) Local location address
186 BA CHAR(10) APPN capable
196 C4 CHAR(10) Single session: indication
206 CE CHAR(10) Single session: number of
conversations

16-30 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
216 D8 CHAR(10) Locally controlled session 112 70 CHAR(10) Local location address
226 E2 CHAR(10) Pre-established session 122 7A CHAR(10) Remote location name
236 EC CHAR(10) Secure location 132 84 CHAR(10) Attached nonswitched
controller name
246 F6 CHAR(10) Automatically configured
142 8E CHAR(10) Connection type
256 100 BINARY(4) Offset to list of active
modes 152 98 CHAR(10) Application type
260 104 BINARY(4) Number of active modes 162 A2 CHAR(10) Contention resolution
winner
264 108 BINARY(4) Entry length for list of
active modes 172 AC CHAR(10) Blocking type
| 268 10C CHAR(10) Current message queue: 182 B6 CHAR(10) Separator character
| name
192 C0 CHAR(10) Remote BSCEL
| 278 116 CHAR(10) Current message queue:
202 CA CHAR(10) Transmit in transparent
| library
mode
These fields CHAR(10) Mode name
212 D4 CHAR(10) Compress and decom-
repeat for
CHAR(2) Reserved press data
each mode
name 222 DE CHAR(10) Truncate trailing blanks
These fields CHAR(10) Mode name 232 E8 CHAR(10) Group separator type
repeat for
CHAR(10) Allocated by job name 242 F2 CHAR(10) Emulated device
each active
mode CHAR(10) Allocated by user name 252 FC CHAR(10) Emulated keyboard
CHAR(6) Allocated by job number 262 106 CHAR(10) Emulated numeric lock
272 110 CHAR(10) Emulated work station
DEVD0300 Format: This format returns detailed informa- 282 11A CHAR(10) Allocated by job name
tion about a device of category *ASC.
292 124 CHAR(10) Allocated by user name

Offset 302 12E CHAR(6) Allocated by job number

Dec Hex Type Field

DEVD0500 Format: This format returns detailed informa-
0 0 Returns everything from
tion about a device of category *DKT.
format DEVD0100
104 68 CHAR(10) Remote location name
Offset
114 72 CHAR(10) Attached nonswitched
Dec Hex Type Field
controller name
0 0 Returns everything from
124 7C CHAR(10) Allocated by job name
format DEVD0100
134 86 CHAR(10) Allocated by user name
104 68 CHAR(10) Device type
144 90 CHAR(6) Allocated by job number
114 72 CHAR(10) Device model
| 150 96 CHAR(10) Current message queue:
124 7C CHAR(10) Resource name
| name
| 160 A0 CHAR(10) Current message queue:
| library
DEVD0600 Format: This format returns detailed informa-
tion about a device of category *DSP.

DEVD0400 Format: This format returns detailed informa- Offset

tion about a device of category *BSC.
Dec Hex Type Field
Offset 0 0 Returns everything from
format DEVD0100
Dec Hex Type Field
104 68 BINARY(4) Character identifier:
0 0 Returns everything from
graphic character set
format DEVD0100
108 6C BINARY(4) Character identifier: code
104 68 BINARY(4) Record length
page
108 6C BINARY(4) Block length

Chapter 16. Configuration APIs 16-31

Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
112 70 BINARY(4) Maximum length of 394 18A CHAR(10) Work station customizing
request unit object: library
116 74 BINARY(4) Inactivity timer 404 194 CHAR(10) Application type
120 78 BINARY(4) DBCS feature: RAM size 414 19E CHAR(10) DBCS feature: matrix size
124 7C BINARY(4) Activation timer 424 1A8 CHAR(10) DBCS feature: language
ID
128 80 BINARY(4) Switch setting
434 1B2 CHAR(10) DBCS feature: last code
132 84 BINARY(4) Device port
point
136 88 BINARY(4) Maximum outstanding
444 1BC CHAR(10) SNA pass-through device
frames
454 1C6 CHAR(10) SNA pass-through group
140 8C BINARY(4) Idle timer
name
144 90 BINARY(4) NRM poll timer
464 1D0 CHAR(10) Emulated device
148 94 BINARY(4) Frame retry
474 1DA CHAR(10) Emulated device model
152 98 BINARY(4) Offset to list of auxiliary
484 1E4 CHAR(10) Emulating ASCII device
devices
494 1EE CHAR(10) Physical attachment
156 9C BINARY(4) Number of auxiliary
devices 504 1F8 CHAR(10) Line speed
160 A0 BINARY(4) Entry length for list of 514 202 CHAR(10) Word length
auxiliary devices
524 20C CHAR(10) Parity type
164 A4 CHAR(10) Device class
534 216 CHAR(10) Stop bits
174 AE CHAR(10) Device type
544 220 CHAR(20) ASCII terminal identifier
184 B8 CHAR(10) Device model
564 234 CHAR(10) Associated APPC device
194 C2 CHAR(10) Local location address
574 23E CHAR(256) Host signon/logon
204 CC CHAR(10) Attached nonswitched command
controller name
830 33E CHAR(1) Pass-through indicator
214 D6 CHAR(10) Keyboard language type
831 33F CHAR(10) Automatically configured
224 E0 CHAR(10) Drop line at signoff
841 349 CHAR(3) Reserved
234 EA CHAR(10) Allow blinking cursor
844 34C BINARY(4) Shared session number
244 F4 CHAR(10) Print device
848 350 CHAR(10) Dependent location name
254 FE CHAR(10) Remote location name
858 35A CHAR(1) Network protocol
264 108 CHAR(10) Local location name
859 35B CHAR(18) Network protocol address
274 112 CHAR(10) Remote network identifier
877 36D CHAR(15) Internet Protocol (IP)
284 11C CHAR(10) Control session device internet address in dotted
description decimal form
294 126 CHAR(10) Associated printer: name 892 37C CHAR(10) Allocated by job name
304 130 CHAR(10) Associated printer: remote 902 386 CHAR(10) Allocated by user name
network identifier
912 390 CHAR(6) Allocated by job number
314 13A CHAR(10) Alternate printer: name
| 918 396 CHAR(10) Current message queue:
324 144 CHAR(10) Alternate printer: remote | name
network identifier
| 928 3A0 CHAR(10) Current message queue:
334 14E CHAR(10) Output queue: name | library
344 158 CHAR(10) Output queue: library | 938 3AA CHAR(1) Server network protocol
354 162 CHAR(10) Printer | 939 3AB CHAR(18) Server network protocol
| address
364 16C CHAR(10) Print file: name
| 957 3BD CHAR(15) Server Internet Protocol
374 176 CHAR(10) Print file: library
| (IP) internet address in
384 180 CHAR(10) Work station customizing | dotted decimal form
object: name

16-32 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
These fields BINARY(4) Auxiliary device address 198 C6 CHAR(10) End session with host
repeat for
CHAR(10) Auxiliary device type 208 D0 CHAR(10) Dependent location name
each auxiliary
device CHAR(2) Reserved 218 DA CHAR(10) Allocated by job name
228 E4 CHAR(10) Allocated by user name
DEVD0700 Format: This format returns detailed informa- 238 EE CHAR(6) Allocated by job number
tion about a device of category *FNC.
| 244 F4 CHAR(10) Current message queue:
| name
Offset
| 254 FE CHAR(10) Current message queue:
Dec Hex Type Field | library
0 0 Returns everything from
format DEVD0100 DEVD0900 Format: This format returns detailed informa-
104 68 BINARY(4) Maximum length of tion about a device of category *INTR.
request unit
108 6C BINARY(4) Inactivity timer Offset
112 70 BINARY(4) Activation timer Dec Hex Type Field
116 74 CHAR(10) Device type 0 0 Returns everything from
format DEVD0100
126 7E CHAR(10) Local location address
104 68 CHAR(10) Remote location name
136 88 CHAR(10) Remote location name
114 72 CHAR(10) Allocated by job name
146 92 CHAR(10) Attached nonswitched
controller name 124 7C CHAR(10) Allocated by user name
156 9C CHAR(10) Device class 134 86 CHAR(6) Allocated by job number
166 A6 CHAR(10) SNA pass-through device
176 B0 CHAR(10) SNA pass-through group DEVD1000 Format: This format returns detailed informa-
name tion about a device of category *NET.
186 BA CHAR(10) Allocated by job name
Offset
196 C4 CHAR(10) Allocated by user name
Dec Hex Type Field
206 CE CHAR(6) Allocated by job number
0 0 Returns everything from
format DEVD0100
DEVD0800 Format: This format returns detailed informa- 104 68 CHAR(10) Network type
tion about a device of category *HOST.
114 72 CHAR(10) Attached nonswitched
controller name
Offset
124 7C CHAR(10) Allocated by job name
Dec Hex Type Field
134 86 CHAR(10) Allocated by user name
0 0 Returns everything from
format DEVD0100 144 90 CHAR(6) Allocated by job number
104 68 BINARY(4) Maximum length of
request unit DEVD1100 Format: This format returns detailed informa-
108 6C CHAR(10) Local location address tion about a device of category *PRT.
118 76 CHAR(10) Remote location name
Offset
128 80 CHAR(10) Attached nonswitched
controller name Dec Hex Type Field

138 8A CHAR(10) Application type 0 0 Returns everything from

format DEVD0100
148 94 CHAR(10) Emulated device
104 68 BINARY(4) Font identifier: integer
158 9E CHAR(10) Emulated device model value of point size
168 A8 CHAR(10) Emulated keyboard 108 6C BINARY(4) Maximum length of
178 B2 CHAR(10) Emulated numeric lock request unit

188 BC CHAR(10) Emulated work station 112 70 BINARY(4) Pacing

Chapter 16. Configuration APIs 16-33

Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
116 74 BINARY(4) Maximum pending 422 1A6 CHAR(10) SNA pass-through device
requests
432 1B0 CHAR(10) SNA pass-through group
120 78 BINARY(4) Print request timer name
124 7C BINARY(4) Character identifier: 442 1BA CHAR(10) Emulated device
graphic character set
452 1C4 CHAR(10) Emulated device model
128 80 BINARY(4) Character identifier: code
462 1CE CHAR(10) Emulating ASCII device
page
472 1D8 CHAR(10) Physical attachment
132 84 BINARY(4) DBCS feature: RAM size
482 1E2 CHAR(10) Auxiliary printer
136 88 BINARY(4) Inactivity timer
492 1EC CHAR(10) Language type
140 8C BINARY(4) Activation timer
502 1F6 CHAR(10) Line speed
144 90 BINARY(4) Switch setting
512 200 CHAR(10) Word length
148 94 BINARY(4) Device port
522 20A CHAR(10) Parity type
152 98 CHAR(10) Device class
532 214 CHAR(10) Stop bits
162 A2 CHAR(10) Device type
542 21E CHAR(10) Number of drawers
172 AC CHAR(10) Device model
552 228 CHAR(10) Print quality
182 B6 CHAR(10) Advanced Function
Printing 562 232 CHAR(10) Transform enabled
192 C0 CHAR(10) AFP attachment 572 23C CHAR(20) Manufacturer type and
model
202 CA CHAR(10) Local location address
592 250 CHAR(10) Paper source 1
212 D4 CHAR(10) Attached nonswitched
controller name 602 25A CHAR(10) Paper source 2
222 DE CHAR(10) Font identifier: identifier 612 264 CHAR(10) Envelope source
232 E8 CHAR(10) Form feed 622 26E CHAR(10) ASCII code page 899
support
242 F2 CHAR(10) Separator drawer
632 278 CHAR(10) Separator exit program:
252 FC CHAR(10) Printer error message
name
262 106 CHAR(10) Message queue: name
642 282 CHAR(10) Separator exit program:
272 110 CHAR(10) Message queue: library library
282 11A CHAR(10) Application type 652 28C CHAR(256) Host signon/logon
command
292 124 CHAR(10) Print while converting
908 38C CHAR(10) Automatically configured
302 12E CHAR(10) Form definition: name
918 396 CHAR(2) Reserved
312 138 CHAR(10) Form definition: library
920 398 BINARY(4) Offset to list of switched
322 142 CHAR(10) Work station customizing
lines
object: name
924 39C BINARY(4) Number of switched lines
332 14C CHAR(10) Work station customizing
object: library 928 3A0 BINARY(4) Entry length for list of
switched lines
342 156 CHAR(10) SNA remote location
name 932 3A4 CHAR(12) Adapter address
352 160 CHAR(10) Local location name 944 3B0 CHAR(10) Adapter type
362 16A CHAR(10) Remote network identifier 954 3BA CHAR(10) Adapter connection type
372 174 CHAR(10) Control session device 964 3C4 BINARY(4) Offset to list of user-
description defined options
382 17E CHAR(10) Mode name 968 3C8 BINARY(4) Number of user-defined
options
392 188 CHAR(10) DBCS feature: matrix size
972 3CC BINARY(4) Entry length for list of
402 192 CHAR(10) DBCS feature: language
user-defined options
ID
976 3D0 BINARY(4) Offset to user-defined
412 19C CHAR(10) DBCS feature: last code
data
point

16-34 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
980 3D4 BINARY(4) Length of user-defined These fields CHAR(10) User-defined option
data repeat for
CHAR(2) Reserved
each user-
984 3D8 CHAR(10) LAN attachment
defined option
994 3E2 CHAR(10) User-defined object name
Variable- CHAR(*) User-defined data
1004 3EC CHAR(10) User-defined object library length
string
1014 3F6 CHAR(10) User-defined object type
containing
1024 400 CHAR(10) User driver program user-defined
name data
1034 40A CHAR(10) User driver program
library DEVD1200 Format: This format returns detailed informa-
1044 414 CHAR(10) User-defined data trans- tion about a device of category *RTL.
form program name
1054 41E CHAR(10) User-defined data trans- Offset
form program library Dec Hex Type Field
1064 428 CHAR(255) Remote location name 0 0 Returns everything from
1319 527 CHAR(1) Reserved format DEVD0100

1320 528 CHAR(10) Font identifier: real value 104 68 BINARY(4) Pacing
of point size 108 6C BINARY(4) Maximum length of
1330 532 CHAR(10) Remote location name request unit
type 112 70 BINARY(4) Inactivity timer
1340 53C CHAR(15) System driver program 116 74 BINARY(4) Activation timer
name
120 78 CHAR(10) Local location address
1355 54B CHAR(10) Reserved
130 82 CHAR(10) Remote location name
1365 555 CHAR(10) Image configuration
140 8C CHAR(10) Attached nonswitched
1375 55F CHAR(10) Reserved controller name
1385 569 CHAR(1) Network protocol 150 96 CHAR(10) Application type
1386 56A CHAR(18) Network protocol address 160 A0 CHAR(10) Device class
1404 57C CHAR(15) Internet Protocol (IP) 170 AA CHAR(10) SNA pass-through device
internet address in dotted
decimal form 180 B4 CHAR(10) SNA pass-through group
name
1419 58B CHAR(10) Dependent location name
190 BE CHAR(10) Allocated by job name
1429 595 CHAR(10) Allocated by job name
200 C8 CHAR(10) Allocated by user name
1439 59F CHAR(10) Allocated by user name
210 D2 CHAR(6) Allocated by job number
1449 5A9 CHAR(6) Allocated by job number
| 1455 5AF CHAR(10) Current message queue:
DEVD1300 Format: This format returns detailed informa-
| name
tion about a device of category *SNPT.
| 1465 5B9 CHAR(10) Current message queue:
| library
Offset
| 1475 5C3 CHAR(1) Server network protocol
Dec Hex Type Field
| 1476 5C4 CHAR(18) Server network protocol
0 0 Returns everything from
| address
format DEVD0100
| 1494 5D6 CHAR(15) Server Internet Protocol
104 68 BINARY(4) Activation timer
| (IP) internet address in
| dotted decimal form 108 6C CHAR(10) Local location address
These fields CHAR(10) Switched line name 118 76 CHAR(10) SNA pass-through class
repeat for
CHAR(2) Reserved 128 80 CHAR(10) Attached nonswitched
each switched
controller name
line
138 8A CHAR(10) SNA pass-through device

Chapter 16. Configuration APIs 16-35

Retrieve Device Description (QDCRDEVD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
148 94 CHAR(10) SNA pass-through group 158 9E CHAR(10) Attached nonswitched
name controller name
158 9E CHAR(10) Dependent location name 168 A8 CHAR(10) Assign device at vary on
168 A8 CHAR(10) Allocated by job name 178 B2 CHAR(10) Unload device at vary off
178 B2 CHAR(10) Allocated by user name
188 BC CHAR(6) Allocated by job number DEVD1600 Format: This format returns detailed informa-
tion about a device of category *OPT.

DEVD1400 Format: This format returns detailed informa-

Offset
tion about a device of category *SNUF.
Dec Hex Type Field
Offset 0 0 Returns everything from
format DEVD0100
Dec Hex Type Field
104 68 CHAR(10) Device type
0 0 Returns everything from
format DEVD0100 114 72 CHAR(10) Device model
104 68 BINARY(4) Record length 124 7C CHAR(10) Resource name
108 6C BINARY(4) Block length 134 86 CHAR(10) Message queue: name
112 70 CHAR(10) Local location address 144 90 CHAR(10) Message queue: library
122 7A CHAR(10) Remote location name
132 84 CHAR(10) Attached nonswitched DEVD1700 Format: This format returns detailed informa-
controller name tion about a device of category *MLB.
142 8E CHAR(10) Program start request
capable Offset

152 98 CHAR(10) Special host application Dec Hex Type Field

162 A2 CHAR(10) Application identifier 0 0 Returns everything from

format DEVD0100
172 AC CHAR(10) Host type
104 68 BINARY(4) Offset to list of drive
182 B6 CHAR(10) Default program: name resources
192 C0 CHAR(10) Default program: library 108 6C BINARY(4) Number of drive
202 CA CHAR(10) HCP emulation resources

212 D4 CHAR(10) Dependent location name 112 70 BINARY(4) Entry length for list of
drive resources
222 DE CHAR(10) Allocated by job name
116 74 BINARY(4) Unload wait time
232 E8 CHAR(10) Allocated by user name
120 78 BINARY(4) Maximum device time
242 F2 CHAR(6) Allocated by job number
124 7C CHAR(10) Device class

DEVD1500 Format: This format returns detailed informa- 134 86 CHAR(10) Device type
tion about a device of category *TAP. 144 90 CHAR(10) Device model
154 9A CHAR(10) Resource name
Offset
164 A4 CHAR(10) Message queue: name
Dec Hex Type Field
174 AE CHAR(10) Message queue: library
0 0 Returns everything from
184 B8 CHAR(10) Generate cartridge identi-
format DEVD0100
fiers
104 68 BINARY(4) Reserved
194 C2 CHAR(10) First robot device descrip-
108 6C CHAR(10) Device type tion
118 76 CHAR(10) Device model 204 CC BINARY(4) Resource allocation pri-
ority
128 80 CHAR(10) Resource name
208 D0 BINARY(4) Initial mount wait time
138 8A CHAR(10) Message queue: name
212 D4 BINARY(4) End of volume mount wait
148 94 CHAR(10) Message queue: library
time

16-36 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

the equivalent character value are listed as an Exception in

Offset
the following field descriptions.
Dec Hex Type Field
| 216 D8 BINARY(4) Offset to list of robot Activation timer (ACTTMR). The number of seconds that
| device descriptions the system should wait for the device to respond to an acti-
vation request from the host. (See the ACTTMR keyword in
| 220 DC BINARY(4) Number of robot device
| descriptions the online command help.)

| 224 E0 BINARY(4) Entry length for list of Adapter address. The remote adapter address for an ASCII
| robot device descriptions printer directly attached to the LAN.
These fields CHAR(10) Drive resource name
repeat for Adapter connection type. The adapter connection type for
CHAR(20) Drive resource text status
each drive an ASCII printer directly attached to the LAN.
resource CHAR(2) Reserved
BINARY(4) Drive resource numeric Adapter type. The adapter type for an ASCII printer directly
status attached to the LAN.
| These fields CHAR(10) Robot device description Advanced Function Printing (AFP). Whether this printer is
| repeat for
used for Advanced Function Printing support. (See the AFP
| each robot
keyword in the online command help.)
| device
| description
AFP attachment (AFPATTACH). The type of attachment
that is used for printers that are configured for Advanced
| DEVD1800 Format: This format returns detailed informa- Function Printing support. (See the AFPATTACH keyword in
| tion about a device of category *CRP. the online command help.)

| Offset Allocated by job name. The name portion of the qualified

job name of the job that has allocated this device description.
| Dec Hex Type Field
The value *NONE indicates that this device is not allocated
| 0 0 Returns everything from by a job.
| format DEVD0100
| 104 68 CHAR(10) Device type Allocated by job number. The number portion of the quali-
fied job name of the job that has allocated this device
| 114 72 CHAR(10) Resource name
description.
| 124 7C CHAR(10) Message queue: name
| 134 86 CHAR(10) Message queue: library Allocated by user name. The user name portion of the
qualified job name of the job that has allocated this device
| 144 90 CHAR(10) PKA key store file: name
description.
| 154 9A CHAR(10) PKA key store file: library
| 164 A4 CHAR(10) DES key store file: name
Allow blinking cursor (ALWBLN). Whether or not the
cursor will blink for display devices. (See the ALWBLN
| 174 AE CHAR(10) DES key store file: library keyword in the online command help.)
| 184 B8 CHAR(10) Allocated by job name
Alternate printer: name. The name of the secondary printer
| 194 C2 CHAR(10) Allocated by user name
that is specified for a session.
| 204 CC CHAR(10) Allocated by job number
| 210 D6 CHAR(10) Current message queue: Alternate printer: remote network identifier. The name of
| name the remote network identifier that is specified for the alternate
printer. (See the RMTNETID keyword in the online
| 220 E0 CHAR(10) Current message queue:
| library
command help.)

Application identifier (APPID). The VTAM application iden-

tifier of the CICS/VS or IMS/VS host subsystem with which
Field Descriptions the AS/400 system communicates. (See the APPID keyword
Fields in the various formats returned by this API are in the online command help.)
described in the online command help for the communica-
Application type (APPTYPE). The application type this
tions device parameters.
device uses. (See the APPTYPE keyword in the online
In certain cases, numeric values are assigned by this API to command help.)
represent character values for some of the returned fields.
APPN capable (APPN). Whether or not networking is used.
Where a numeric value is assigned, the numeric value and
(See the APPN keyword in the online command help.)

Chapter 16. Configuration APIs 16-37

Retrieve Device Description (QDCRDEVD) API

ASCII code page 899 support. Whether this printer has Exceptions:
ASCII code page 899 installed.
Ÿ Value of -14 implies *SYSVAL
ASCII terminal identifier. A user-specified terminal identifier Ÿ Value of -27 implies *KBDTYPE
for the physical device.
Compress and decompress data (DTACPR). Whether or
Assign device at vary on. Whether the tape device is not to have blanks in BSC data compressed for output and
assigned to the system when it is varied on. (See the decompressed for input. (See the DTACPR keyword in the
ASSIGN keyword in the online command help.) online command help.)

Associated APPC device. The name of an APPC device Connection type (CNN). The connection type. (See the
associated with a display station. CNN keyword in the online command help.)

Associated printer: name. The name of the primary printer Contention resolution winner (CTNWIN). Which BSC
that is specified for a session. system is to be the primary unit and which is to be the sec-
ondary unit for contention resolution on a BSC line. (See the
Associated printer: remote network identifier. The name CTNWIN keyword in the online command help.)
of the remote network identifier that is specified for the asso-
ciated printer. (See the RMTNETID keyword in the online Control session device description. Which control session
command help.) device description created or selected a specific device
description that is being used in a session.
Attached nonswitched controller name (CTL). The name
of the controller description to which this device is attached. | Current message queue. The message queue to which
(See the CTL keyword in the online command help.) | messages are currently being sent using this device descrip-
| tion. This field is valid only for devices that are varied on.
Automatically configured. Whether this device has been | Note that the value of the current message queue may be
configured automatically. | different from the message queue field (MSGQ parameter)
| under certain error conditions. See the MSGQ keyword in
Auxiliary device address. The address of an additional
| the online command help for more details. This information
device attached to an IEEE-48 port on this device. (See the
| is returned in two separate fields:
AUXDEV keyword in the online command help.)
| Ÿ Name of the queue
Auxiliary device type. The type of additional device
| Ÿ Library in which the queue can be found
attached to an IEEE-48 port on this device. (See the
AUXDEV keyword in the online command help.) Date information retrieved. The date that the information
was provided by the API. This is returned as 7 characters in
Auxiliary printer. For ASCII printers, whether the printer is
the form CYYMMDD, where:
attached to a display station.
C Century, where 0 indicates years 19xx and 1
Block length (BLKLEN). The maximum block length (in indicates years 20xx.
bytes) for data to be transmitted when communicating with YY Year
this device. (See the BLKLEN keyword in the online MM Month
command help.) DD Day

Blocking type (BLOCK). Whether you or the AS/400 DBCS feature (IGCFEAT). The values that should be speci-
system will block and deblock transmitted records. (See the fied for DBCS display stations and printers. This information
BLOCK keyword in the online command help.) is returned in four separate fields:

Bytes available. The number of bytes of data available to Ÿ RAM size: The relative buffer size.
be returned. All available data is returned if enough space is Ÿ Matrix size: The number of matrix points used to create
provided. the character.

Bytes returned. The number of bytes of data returned. Ÿ Language ID: A letter code that identifies the language
used.
Character identifier (CHRID). The character identifier that Ÿ Last code point: The code point of the last double-byte
this display station supports. This identifier has two parts, character.
which are returned in separate fields:
Ÿ Graphic character set (See the IGCFEAT keyword in the online command help.)

Ÿ Code page Default program (DFTPGM). The program to be called if a

program start request is received from a host system that is
(See the CHRID keyword in the online command help.) not using an \EXEC/\EXEX/\TXTC/\TXTX format. This informa-
tion is returned in two separate fields:

16-38 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

Ÿ Name of the program | Exception:

Ÿ Library in which the program can be found | Ÿ Value of *TAP implies that a self configuring tape device
| is emulating a device type that contains characters
(See the DFTPGM keyword in the online command help.) | outside the range of 0 to 9 and A to Z.

| DES key store file (DESKEYFILE). The name of the key | (See the TYPE keyword in the online command help.)
| store file containing the data encryption standard (DES) keys
Drive resource name. The resource name of a drive within
| to be used with this cryptographic device. This information is
this library.
| returned in two separate fields:
| Ÿ Name of the DES file Drive resource numeric status. A numeric value that
represents the drive's current status.
| Ÿ Library in which the file can be found
Numeric Status
Dependent location name (DEPLOCNAME). The (Decimal) Text Status
dependent logical location name that is used for the
dependent-logical-unit requester (DLUR), which provides 1 OPERATIONAL
5 DEALLOCATE
additional security for the connection.
6 UNPROTECTED
7 ALLOCATED
Device category. This value will be one of the following:
100 FAILED
*APPC
Drive resource text status. A text value that represents the
*ASC
current status of the drive within this library. Possible values
*BSC are allocated, deallocated, or unprotected.
| *CRP Note: The displayable text is translated when it is returned.
*DKT This text is retrieved from message CPX2651 in
message file QCPFMSG in library *LIBL.
*DSP
*FNC Drop line at signoff (DROP). Whether display stations
attached to controllers on switched lines will be disconnected
*HOST by the system when all work stations on the line are no
*INTR longer being used. (See the DROP keyword in the online
command help.)
*MLB
*NET Emulated device (EMLDEV). The type of device that is to
be emulated. For devices of category *DSP and *PRT, this
*OPT
is a twinaxial device. For devices of category *HOST, this is
*PRT a 3270 device. (See the EMLDEV keyword in the online
*RTL command help.)

*SNPT Emulated device model. The model of the device type that
*SNUF is to be emulated.

*TAP Emulated keyboard (EMLKBD). The type of 3278 display

keyboard that is to be emulated. (See the EMLKBD keyword
The category value is derived from the command used to in the online command help.)
create the device description.
Emulated numeric lock (EMLNUMLCK). Whether numeric
Device class (DEVCLS). The class of the device. (See the input fields allow only numeric data on a 5250 keyboard.
DEVCLS keyword in the online command help.) (See the EMLNUMLCK keyword in the online command
help.)
Device model (MODEL). The model number of the device.
(See the MODEL keyword in the online command help.) Emulated work station (EMLWRKSTN). The name of an
emulated device associated with a real display station or
Device name. The name of the device description.
printer device. (See the EMLWRKSTN keyword in the online
Device port. The identification of the port to which this command help.)
device is currently attached.
Emulating ASCII device. Whether this device emulates a
| Device type (TYPE). The type of device this description supported ASCII device type. (See the EMLASCII keyword
| represents. in the online command help.)

Chapter 16. Configuration APIs 16-39

 Retrieve Device Description (QDCRDEVD) API

End of volume mount wait time (EOVMNTWAIT). The Ÿ Point size (real value)
maximum amount of time a request will wait for allocation of
a tape resource for the end of volume mount. (See the FONT keyword in the online command help.)

Exceptions: Exception:
Ÿ Value of -31 implies *JOB Ÿ Value of -3 implies *NONE

Ÿ Value of -32 implies *IMMED Form definition (FORMDF). The form definition to be used
Ÿ Value of -8 implies *NOMAX for print requests that do not specify a form definition. This
information is returned in two separate fields:
End session with host. Whether a request-shutdown or
Ÿ Name of the form definition
unbind will be used to end a session.
Ÿ Library in which the form definition can be found
Entry length for list of active modes. The entry length in
bytes of each element in the list of active modes that are (See the FORMDF keyword in the online command help.)
returned with this format. A value of zero is returned if the
Form feed (FORMFEED). The mode in which forms are fed
list is empty.
into the *IPDS, 4212, or 5219 printers. (See the
Entry length for list of auxiliary devices. The entry length FORMFEED keyword in the online command help.)
in bytes of each element in the list of auxiliary devices
Frame retry (FRAMERTY). The number of retries for an
returned with this format. A value of zero is returned if the
unanswered command frame or an unacknowledged informa-
list is empty.
tion frame. (See the FRAMERTY keyword in the online
Entry length for list of drive resources. The entry length command help.)
in bytes of each element in the list of drive resources.
Generate cartridge IDs (GENCTGID). For tape library
Entry length for list of mode names. The entry length in devices without bar-code readers, indicates how cartridge
bytes of each element in the list of mode names returned identifiers are generated. Possible values are as follows:
with this format. A value of zero is returned if the list is Ÿ *VOLID
empty.
Ÿ *SYSGEN
| Entry length for list of robot device descriptions. The
(See the GENCTGID keyword in the Local Device Configura-
| entry length in bytes of each element in the list of robot
| device descriptions.
tion book.)

Group separator type (GRPSEP). The separator for groups

Entry length for list of switched lines. The entry length in
of data (data sets, documents, and so forth). (See the
bytes of each element in the list of switched lines returned
GRSEP keyword in the online command help.)
with this format. A value of zero is returned if the list is
empty.
HCP emulation (HCLEML). The type of host command
processor emulated session that this device description will
Entry length for list of user-defined options. The entry
be used for. (See the HCPEML keyword in the online
length in bytes of each element in the list of user-defined
command help.)
options returned with this format.
Host signon/logon command (LOGON). The logon string
Envelope source. The type of envelope to be used in paper
that is sent to the host network when the file is opened.
source three.
(See the LOGON keyword in the online command help.)
| First robot device description (ROBOTDEV). For a library
Host type (HOST). The type of host system with which the
| device with a robot, the name of the device description used
device will communicate. (See the HOST keyword in the
| to communicate with the robot. This field always contains
online command help.)
| the first robot device. For a list of the robot device descrip-
| tion, see the robot device description field for this format.
Idle timer (IDLTMR). The time that the system waits for a
| (See the ROBOTDEV keyword in the Local Device
response. (See the IDLTMR keyword in the online command
| Configuration book. help.)
Font identifier (FONT). The font identifier and point size
Image configuration (IMGCFG). The transform services for
that are used by *IPDS, 3812, and 5219 printers. This infor-
a variety of image and print data-stream formats. (See the
mation is returned in separate fields:
IMGCFG keyword in the online command help.)
Ÿ Font identifier
Inactivity timer (INACTTMR). The amount of time the
Ÿ Point size (integer value)
device can be inactive before the session is ended. (See the
INACTTMR keyword in the online command help.)

16-40 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

Exceptions: Manufacturer type and model. The manufacturer, type,

and model for a printer using transform support.
Ÿ Value of -8 implies *NOMAX
Ÿ Value of -19 implies *ATTACH Maximum device time (MAXDEVTIME). The maximum
amount of time a volume can remain mounted in an internal
Ÿ Value of -20 implies *SEC15
device if there are requests for other volumes.
Ÿ Value of -21 implies *SEC30
Exceptions:
Initial mount wait time (INLMNTWAIT). The maximum
Ÿ Value of -22 implies *SYSGEN
amount of time a request will wait for allocation of a tape
resource for the initial mount.
Maximum length of request unit (MAXLENRU). The
default maximum size of the request/response unit (RU) that
Exceptions:
can be sent or received by the local system if the maximum
Ÿ Value of -31 implies *JOB size is not specified in the bind command received from the
Ÿ Value of -32 implies *IMMED host system. (See the MAXLENRU keyword in the online
command help.)
Ÿ Value of -8 implies *NOMAX
Exception:
Internet Protocol (IP) internet address in dotted decimal
form. A 32-bit address usually written as 4 decimal numbers, Ÿ Value of -11 implies *CALC
each representing 8 bits of the address. An example internet
Maximum outstanding frames (MAXOUT). The maximum
address is 128.12.28.43.
number of frames that are sent to a remote system before it
Each system on the TCP/IP network is assigned a unique must respond. (See the MAXOUT keyword in the online
internet address that is used in all communications with the command help.)
system.
Maximum pending requests (MAXPNDRQS). The
Note: This field applies only to display or printer devices maximum number of print requests that can be queued for
that are used by TELNET or TCP/IP over Twinax. printers configured for Advanced Function Printing support.
(See the MAXPNDRQS keyword in the online command
Keyboard language type (KBDTYPE). The 3-character
help.)
keyboard type identified for type 3277, 3278, or 3279 display
stations. (See the KBDTYPE keyword in the online | Message queue (MSGQ). The message queue to which
command help.) | operational messages for this device should normally be
| sent. Note that this is the value entered on the MSGQ
LAN attachment. The type of LAN attachment that is used
| parameter of the CL command, but under error conditions for
when *LAN is specified for the device class (DEVCLS)
| certain types of devices (APPC and Printer), it may not be
parameter.
| the message queue currently in use. See the current
| message queue field to determine what message queue is
Language type. The keyboard language type for an ASCII
| actually being used at a given time. See the MSGQ keyword
printer.
| in the online command help for more information. This infor-
Length of user-defined data. The length, in bytes, of the | mation is returned in two separate fields:
user-defined data that is returned with this format. A value of | Ÿ Name of the queue
zero is returned if no data exists.
| Ÿ Library in which the queue can be found
Line speed (LINESPEED). A line speed for use with this
Mode name (MODE). The names used by the local AS/400
device. (See the LINESPEED keyword in the online
system and the remote system to refer to the group of ses-
command help.)
sions between the local and remote locations with the same
Local location address (LOCADR). The local location characteristics. (See the MODE keyword in the online
address. (See the LOCADR keyword in the online command command help.)
help.)
Network protocol. The following defines the network pro-
Local location name (LCLLOCNAME). The name by which tocol:
the local AS/400 system is known to other devices in the Ÿ Internet Protocol (IP) value is X'02'.
network. (See the LCLLOCNAME keyword in the online
Ÿ Internetwork Packet Exchange (IPX) value is X'06'.
command help.)
Note: This field applies only to display and printer devices
Locally controlled session (LCLCTLSSN). Whether the that are used by TELNET.
single session is locally or remotely controlled. (See the
LCLCTLSSN keyword in the online command help.)

Chapter 16. Configuration APIs 16-41

 Retrieve Device Description (QDCRDEVD) API

Network protocol address. The network address is Offset to list of auxiliary devices. The offset in bytes to
uniquely assigned to each system and is used in all commu- the first element in the list of auxiliary devices returned with
nications with the system. this format. A value of zero is returned if the list is empty.

The following format defines the network address based on Offset to list of drive resources. The offset in bytes to the
the network protocol: first element in the list of drive resources. A value of zero is
returned if the list is empty.
Ÿ Internet Protocol (IP)
– CHAR(2) TCP port number Offset to list of mode names. The offset in bytes to the
first element in the list of mode names returned with this
– CHAR(4) Internet address
format. A value of zero is returned if the list is empty.
Ÿ Internetwork Packet Exchange (IPX)
| Offset to list of robot device descriptions. The offset in
– CHAR(4) Network identifier
| bytes to the first element in the list of robot device descrip-
– CHAR(6) Node identifier | tions. A value of zero is returned if the list is empty.
– CHAR(2) Socket number
Offset to list of switched lines. The offset in bytes to the
Note: This field applies only to display and printer devices list of switched lines returned with this format. A value of
that are used by TELNET. zero is returned if the list is empty.

Network type. The type of network the device represents. Offset to list of user-defined options. The offset in bytes
to the first element in the list of user-defined options that are
NRM poll timer (NRMPOLLTMR). The time interval for returned with this format. A value of zero is returned if the
polling this device in normal response mode. (See the list is empty.
NRMPOLLTMR keyword in the online command help.)
Offset to user-defined data. The offset in bytes to the
Number of active modes. The number of elements in the user-defined data that is returned with this format. A value of
list of active modes that are returned with this format. A zero is returned if no data exists.
value of zero is returned if the list is empty.
Online at IPL (ONLINE). The name that will be used when
Number of auxiliary devices. The number of elements in you are working with the Vary Configuration (VRYCFG) and
the list of auxiliary devices returned with this format. A value Work with Configuration Status (WRKCFGSTS) commands.
of zero is returned if the list is empty. (See the ONLINE keyword in the online command help.)
Number of drawers. The number of drawers the printer Output queue (OUTQ). The output queue to be used for
physically supports, not which drawer the paper is selected printed output associated with this display station. This infor-
from. The individual print files sent to the printer determine mation is returned in two separate fields:
which drawer is selected.
Ÿ Name of the queue
Number of drive resources. The number of elements in
Ÿ Library in which the queue can be found
the list of drive resources. A value of zero is returned if the
list is empty. (See the OUTQ keyword in the online command help.)

Number of mode names. The number of elements in the Pacing (PACING). The number of request units (RUs) that
list of mode names returned with this format. A value of zero can be sent or received before a pacing response must be
is returned if the list is empty. sent or received. (See the PACING keyword in the online
command help.)
| Number of robot device descriptions. The number of ele-
| ments in the list of robot device descriptions. A value of zero Paper source 1. The type of paper to be used in paper
| is returned if the list is empty. source one.

Number of switched lines. The number of entries in the list Paper source 2. The type of paper to be used in paper
of switched lines returned with this format. A value of zero is source two.
returned if the list is empty.
Parity type (PARITY). For ASCII devices, the parity used to
Number of user-defined options. The number of elements communicate over the attachment between the controller and
in the list of user-defined options that is returned with this the device. (See the PARITY keyword in the online
format. A value of zero is returned if the list is empty. command help.)

Offset to list of active modes. The offset in bytes to the Pass-through indicator. Whether the current session is a
first element in the list of active modes that are returned with pass-through session on a device. Possible values follow:
this format. A value of zero is returned if the list is empty.
0 Not pass-through

16-42 AS/400 System API Reference V4R4

 Retrieve Device Description (QDCRDEVD) API

1 5250 emulation type display for recoverable errors. (See the PRTERRMSG keyword in
2 Virtual display using Virtual Terminal APIs (not the online command help.)
TELNET)
3 Virtual display (TELNET) Program start request capable (PGMSTRRQS). Whether
4 Pass-through device (Start Pass-Through or not to have the device reserved for program start
(STRPASTHR) command used) requests. (See the PGMSTRRQS keyword in the online
command help.)
| PKA key store file (PKAKEYFILE). The name of the key
| store file containing the public key algorithm (PKA) keys to Record length (RCDLEN). The maximum record length
| be used with this cryptographic device. This information is allowed when communicating with this device. (See the
| returned in two separate fields: RCDLEN keyword in the online command help.)

| Ÿ Name of the PKA file Remote BSCEL (RMTBSCEL). Whether this device will
| Ÿ Library in which the file can be found communicate with a remote system that can recognize
BSCEL commands and messages. (See the RMTBSCEL
Physical attachment. The attachment of a display station to keyword in the online command help.)
the ASCII workstation controller. (See the ATTACH keyword
in the online command help.) Remote location name (RMTLOCNAME). The SNA
network ID and control point name, an internet protocol (IP)
Pre-established session (PREESTSSN). Whether the host name, or an internet address of the printer device. (See
single session is to be established when connection with the the RMTLOCNAME keyword in the online command help.)
remote system is established. (See the PREESTSSN
keyword in the online command help.) Exception:
Ÿ The remote network ID is not filled in if it is *NETATR or
Print device (PRTDEV). The name of the printer to be used
*NONE.
for printed output from this display device. (See the
PRTDEV keyword in the online command help.) Remote location name type. The remote location name
type is *SNA or *IP.
Print file (PRTFILE). The alternative printer device file to be
used when no associated work station printer exists or when Remote network identifier (RMTNETID). The 8-character
an error occurs during an attempt to use the work station name of the remote network in which the location resides.
printer. This information is returned in two separate fields: (See the RMTNETID keyword in the online command help.)
Ÿ Name of the device file
Reserved. Space included for alignment.
Ÿ Library in which the device file can be found
Resource allocation priority (RSCALCPTY). The priority of
(See the PRTFILE keyword in the online command help.) a job when requesting a resource.

Print quality. For printers, the quality of print to be Exception:

produced.
Ÿ Value of -31 implies *JOB
Print request timer (PRTRQSTMR). The number of
Resource name. The unique name that is assigned by the
seconds to wait after a print request has been sent to a con-
system to the physical equipment attached to the system.
tinuous forms printer before the last printed output is forced
For an explanation of resource names for devices, see the
into the output hopper. (See the PRTRQSTMR keyword in
the online command help.)
Local Device Configuration book.

Robot device description (ROBOTDEV). For library

Exception:
devices with separate robots, the name of the device
Ÿ Value of -8 implies *NOMAX description used to communicate with the robot. (See the
ROBOTDEV keyword in the Local Device Configuration
Print while converting (PRTCVT). Allows printers config-
book.)
ured as AFP(*YES) to begin printing a spooled file while that
file is being converted to an Advanced Function Printing data Secure location (SECURELOC). Whether or not the remote
stream (AFPDS). (See the PRTCVT keyword in the online location is secure. If the remote location is secure then an
command help.) already verified indicator is allowed to be sent with program
start requests. If it is not secure, then either no security infor-
Printer (PRINTER). The device name of the printer to be
mation is allowed or the User ID with encrypted password is
associated with the display device. (See the PRINTER
retrieved. (See the SECURELOC keyword in the online
keyword in the online command help.)
command help.)
Printer error message (PRTERRMSG). Whether to have
the printer send inquiry messages or informational messages

Chapter 16. Configuration APIs 16-43

 Retrieve Device Description (QDCRDEVD) API

Separator character (SEPCHAR). The separator character versations may also be specified. This information is
to be used (if you specified *SEP for the blocking type). returned in two separate fields:
(See the SEPCHAR keyword in the online command help.)
Ÿ Indication of whether communications is limited to one
session
Separator drawer (SEPDRAWER). The sheet feeding
drawer for file and job separators. (See the SEPDRAWER Ÿ Number of conversations allowed if limited to one
keyword in the online command help.) session

Separator exit program (SEPPGM). A user exit program to (See the SNGSSN keyword in the online command help.)
be called when printing the job and file separators. This
information is returned in two separate fields: SNA pass-through class (SNPTCLS). Whether this device
is to be used as an upstream or downstream pass-through
Ÿ Name of the program
device. (See the SNPTCLS keyword in the online command
Ÿ Library in which the program can be found help.)

(See the SEPPGM keyword in the online command help.) SNA pass-through device (SNPTDEV). The name of the
pass-through device with which this device is associated.
| Server network protocol. The following defines the server (See the SNPTDEV keyword in the online command help.)
| network protocol:
SNA pass-through group name (SNPTGAP). The name of
| Ÿ Internet Protocol (IP) value is X'02'.
a group of upstream SNA pass-through devices with which
| Ÿ Internetwork Packet Exchange (IPX) value is X'06'. this device can be associated. (See the SNPTGRP keyword
| Note: This field applies only to display and printer devices in the online command help.)
| that are used by TELNET.
SNA remote location name (RMTLOCNAME). The name
| Server network protocol address. The server network of the remote location with which your system will be com-
| address is uniquely assigned to each system and is used in municating. (See the RMTLOCNAME keyword in the online
| all communications with the system. command help.)

| The following format defines the server network address Special host application (SPCHOSTAPP). Whether this
| based on the server network protocol: device is used to communicate with a special host applica-
tion. (See the SPCHOSTAPP keyword in the online
| Ÿ Internet Protocol (IP) command help.)
| – CHAR(2) TCP port number
Stop bits (STOPBITS). For ASCII devices, the number of
| – CHAR(4) Internet address stop bits used to communicate over the attachment between
| Ÿ Internetwork Packet Exchange (IPX) the controller and the device. (See the STOPBITS keyword
in the online command help.)
| – CHAR(4) Network identifier
| – CHAR(6) Node identifier Switch setting. The value of the current switch settings at
the actual device, equivalent to the current device address.
| – CHAR(2) Socket number
| Note: This field applies only to display and printer devices Switched line name. The name of a switched line associ-
| that are used by TELNET. ated with an ASCII printer directly attached to the LAN.

| Server Internet Protocol (IP) internet address in dotted Text description (TEXT). A brief description of the device
| decimal form. A 32-bit address usually written as 4 decimal and its location. (See the TEXT keyword in the online
| numbers, each representing 8 bits of the address. An command help.)
| example internet address is 128.12.28.43.
Time information retrieved. The time that the information
| Each system on the TCP/IP network is assigned a unique was provided by the API. It is returned as 6 characters in
| internet address that is used in all communications with the the form HHMMSS, where:
| system. HH Hour
| Note: This field applies only to display or printer devices MM Minute
| that are used by TELNET or TCP/IP over Twinax. SS Second

Shared session number. The shared session number that Transform enabled. Whether this printer will use the host-
is associated with this device. based transform support to convert SCS to ASCII.

Single session (SNGSSN). Whether communications with Transmit in transparent mode (TRNSPY). Whether trans-
the remote location is limited to one session. If communica- parency is to be used by this device. (See the TRNSPY
tions is limited to one session, a maximum number of con- keyword in the online command help.)

16-44 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Truncate trailing blanks (TRUNC). Whether trailing blanks CPF2634 E Not authorized to object &1.
are to be removed from the output records. (See the CPF26A7 E Category of object not compatible with API
TRUNC keyword in the online command help.) format.
CPF2702 E Device description &1 not found.
Unload device at vary off. Whether the tape device will be CPF3C19 E
unloaded when the device is varied off. Error occurred with receiver variable specified.
CPF3C21 E
Unload wait time (UNLOADWAIT). The amount of time the
Format name &1 is not valid.
system waits for another request to a mounted volume
CPF3C24 E
before unloading the volume if there are outstanding
Length of the receiver variable is not valid.
requests for an available device.
CPF3CF1 E
Error code parameter not valid.
User-defined data. A string of data that is associated with
CPF3C90 E
the printer device description and specified by the user. See
Literal value cannot be changed.
the “Change Configuration Description (QDCCCFGD) API”
CPF8104 E Controller description &4 damaged.
on page 16-1 for information on how to set this data.
CPF8105 E Device description &4 damaged.
User-defined data transform program library. The name CPF9872 E Program or service program &1 in library &2
of the library that contains the data transform program. ended. Reason code &3.

User-defined data transform program name. The name of

the user-defined data transform program to be used by the Retrieve Line Description (QDCRLIND) API
user driver program. (See the user driver program name
field.)
Required Parameter Group:
User-defined object library. The name of the library that
contains the user-defined object. 1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
User-defined object name. The name of the user-defined 3 Format name Input Char(8)
object that is to be used by the user driver program. 4 Line name Input Char(10)
5 Error code I/O Char(*)
User-defined object type. The type of the user-defined
object that is to be used by the user driver program. Threadsafe: Yes

User-defined option. An option to be accessed by the user

driver program. The Retrieve Line Description (QDCRLIND) API retrieves
information about a line description.
User driver program library. The name of the library that
contains the user-defined driver program.
Authorities and Locks
User driver program name. The name of a user-defined Controller Description Authority
driver program. *USE
Line Description Authority
Word length. For ASCII devices, the word length used to
*USE
communicate over the attachment between the controller and
Controller Description Lock
the device. (See the WORDLEN keyword in the online
*EXCLRD
command help.)
Line Description Lock
Work station customizing object (WSCST). The object *EXCLRD
containing pointers to the work station customizing tables for
this device. This information is returned in two separate Required Parameter Group
fields:
Receiver variable
Ÿ Name of the customizing object
OUTPUT; CHAR(*)
Ÿ Library in which the object can be found
The variable that is to receive the line information.
(See the WSCST keyword in the online command help.) Length of receiver variable
INPUT; BINARY(4)
Error Messages The length of the area referenced by the receiver vari-
CPF24B4 E Severe error while addressing parameter list. able parameter. If the amount of information to be
CPF2625 E Not able to allocate object &1. returned is greater than this value, the information will be
truncated to this length.

Chapter 16. Configuration APIs 16-45

Retrieve Line Description (QDCRLIND) API

Format name LIND0100 Format: Use this format to find out the line
INPUT; CHAR(8) category, plus some basic information about the line. Then
The content and format of the information returned for you may use the returned line category to select one of the
each line description. The possible format names are: other (category-specific) formats to call the API again for
detailed information about the line description. This format
LIND0100 Basic line information also returns the number of controllers currently attached to
LIND0200 Basic line information, plus list of attached this line.
nonswitched controllers
LIND0300 Detailed information for line category Offset
*ASC
Dec Hex Type Field
LIND0400 Detailed information for line category
*BSC 0 0 BINARY(4) Bytes returned
LIND0500 Detailed information for line category 4 4 BINARY(4) Bytes available
*ETH
8 8 BINARY(4) Number of attached non-
LIND0600 Detailed information for line category switched controllers
*IDLC
12 C CHAR(7) Date information retrieved
LIND0700 Detailed information for line category
*NET 19 13 CHAR(6) Time information retrieved
LIND0800 Detailed information for line category 25 19 CHAR(10) Line name
*SDLC
35 23 CHAR(10) Line category
LIND0900 Detailed information for line category
*TDLC 45 2D CHAR(10) Online at IPL
LIND1000 Detailed information for line category 55 37 CHAR(50) Text description
*TRN
105 69 CHAR(3) Reserved
LIND1100 Detailed information for line category
*X25
LIND1200 Detailed information for line category *DDI LIND0200 Format: This format returns basic line informa-
LIND1300 Detailed information for line category *FR tion, plus a list of attached nonswitched controllers. Some
LIND1400 Detailed information for line category basic information is also included for each attached non-
*FAX switched controller.
LIND1500 Detailed information for line category
*WLS Offset
LIND1600 Detailed information for line category Dec Hex Type Field
*PPP
0 0 Returns everything from
See “Format of Line Information” for a description of format LIND0100
these formats. 108 6C BINARY(4) Offset to list of attached
nonswitched controllers
Line name
INPUT; CHAR(10) 112 70 BINARY(4) Entry length for list of
attached nonswitched
The name of the line description to be retrieved. controllers

Error code These fields CHAR(10) Attached nonswitched

I/O; CHAR(*) repeat for controller name
each non-
CHAR(10) Controller category
The structure in which to return error information. For switched con-
the format of the structure, see “Error Code Parameter” troller CHAR(10) Controller type
on page 2-6. CHAR(50) Controller text description

Format of Line Information LIND0300 Format: This format returns detailed informa-
tion about a line of category *ASC.
When the line category is unknown, specify LIND0100 or
LIND0200, and the basic information (including line category) Offset
will be returned. When the line category is known, specify
Dec Hex Type Field
one of the other category-specific formats.
0 0 Returns everything from
For detailed descriptions of the fields returned in these format LIND0100
formats, see “Field Descriptions” on page 16-58. 108 6C BINARY(4) Vary on wait
112 70 BINARY(4) Line speed

16-46 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
116 74 BINARY(4) Inactivity timer 322 142 CHAR(10) Switched connection type
120 78 BINARY(4) Maximum buffer size 332 14C CHAR(10) Autoanswer
124 7C BINARY(4) Idle timer 342 156 CHAR(10) Autodial
128 80 BINARY(4) Data Set Ready drop 352 160 CHAR(10) Dial command type
timer
362 16A CHAR(10) Autocall resource name
132 84 BINARY(4) Clear to Send timer
372 174 CHAR(32) Calling number
136 88 BINARY(4) Remote answer timer
404 194 CHAR(10) Error threshold level
140 8C BINARY(4) Recovery limits: count
414 19E CHAR(10) Flow control
limit
424 1A8 CHAR(10) XON character
144 90 BINARY(4) Recovery limits: time
interval 434 1B2 CHAR(10) XOFF character
148 94 BINARY(4) Offset to list of attached 444 1BC CHAR(10) Autoanswer type
nonswitched controllers
454 1C6 CHAR(10) Autoconfigured for AS/36
152 98 BINARY(4) Entry length for list of
| 464 1D0 CHAR(2) Reserved
attached nonswitched
controllers 466 1D2 CHAR(40) Set modem to ASYNC
command
156 9C BINARY(4) Offset to list of switched
controllers | 506 1FA CHAR(60) Modem initialization
| command
160 A0 BINARY(4) Number of switched con-
trollers | 566 236 CHAR(2) Reserved
164 A4 BINARY(4) Entry length for list of These fields CHAR(10) Attached nonswitched
switched controllers repeat for controller name
each non-
168 A8 BINARY(4) Offset to list of active CHAR(2) Reserved
switched con-
switched controllers
troller
172 AC BINARY(4) Number of active
These fields CHAR(10) Switched controller name
switched controllers
repeat for
CHAR(2) Reserved
176 B0 BINARY(4) Entry length for list of each switched
active switched controllers controller
180 B4 BINARY(4) Offset to list of EOR char- These fields CHAR(10) Active switched controller
acters repeat for name
each active
184 B8 BINARY(4) Number of EOR charac- CHAR(2) Reserved
switched con-
ters
troller
188 BC BINARY(4) Entry length for list of
These fields BINARY(4) Number of trailing charac-
EOR characters
repeat for ters
192 C0 CHAR(10) Resource name each EOR
CHAR(10) EOR character
character
202 CA CHAR(10) Physical Interface
CHAR(2) Reserved
212 D4 CHAR(10) Connection type
222 DE CHAR(10) Switched network backup LIND0400 Format: This format returns detailed informa-
232 E8 CHAR(10) Activate switched network tion about a line of category *BSC.
backup
242 F2 CHAR(10) Autocall unit Offset

252 FC CHAR(10) Data bits per character Dec Hex Type Field

262 106 CHAR(10) Type of parity 0 0 Returns everything from

format LIND0100
272 110 CHAR(10) Stop bits
108 6C BINARY(4) Vary on wait
282 11A CHAR(10) Duplex
112 70 BINARY(4) Line speed
292 124 CHAR(10) Echo support
116 74 BINARY(4) Inactivity timer
302 12E CHAR(10) Modem type supported
120 78 BINARY(4) Maximum buffer size
312 138 CHAR(10) Modem data rate select
124 7C BINARY(4) Receive timer

Chapter 16. Configuration APIs 16-47

Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
128 80 BINARY(4) Continue timer 350 15E CHAR(10) Dial command type
132 84 BINARY(4) Contention state retry 360 168 CHAR(10) Autocall resource name
136 88 BINARY(4) Data state retry 370 172 CHAR(32) Calling number
140 8C BINARY(4) Transmit TTD or WACK 402 192 CHAR(10) Character code
retry
412 19C CHAR(10) SYN characters
144 90 BINARY(4) Receive TTD or WACK
422 1A6 CHAR(10) Error threshold level
retry
432 1B0 CHAR(10) Include STX character in
148 94 BINARY(4) Data Set Ready drop
the LRC
timer
442 1BA CHAR(10) Autoanswer type
152 98 BINARY(4) Clear To Send timer
452 1C4 CHAR(10) Autoconfigured for AS/36
156 9C BINARY(4) Remote answer timer
| 462 1CE CHAR(2) Reserved
160 A0 BINARY(4) Recovery limits: count
limit These fields CHAR(10) Attached nonswitched
repeat for controller name
164 A4 BINARY(4) Recovery limits: time
each non-
interval CHAR(2) Reserved
switched con-
168 A8 BINARY(4) Offset to list of attached troller
nonswitched controllers
These fields CHAR(10) Switched controller name
172 AC BINARY(4) Entry length for list of repeat for
CHAR(2) Reserved
attached nonswitched each switched
controllers controller
176 B0 BINARY(4) Offset to list of switched These fields CHAR(10) Active switched controller
controllers repeat for name
each active
180 B4 BINARY(4) Number of switched con- CHAR(2) Reserved
switched con-
trollers
troller
184 B8 BINARY(4) Entry length for list of
switched controllers
LIND0500 Format: This format returns detailed informa-
188 BC BINARY(4) Offset to list of active tion about a line of category *ETH.
switched controllers
192 C0 BINARY(4) Number of active Offset
switched controllers
Dec Hex Type Field
196 C4 BINARY(4) Entry length for list of
active switched controllers 0 0 Returns everything from
format LIND0100
200 C8 CHAR(10) Resource name
108 6C BINARY(4) Vary on wait
210 D2 CHAR(10) Application type
112 70 BINARY(4) Maximum controllers
220 DC CHAR(10) Physical Interface
116 74 BINARY(4) Link speed
230 E6 CHAR(10) Connection type
120 78 BINARY(4) Cost per connect time
240 F0 CHAR(10) Switched network backup
124 7C BINARY(4) Cost per byte
250 FA CHAR(10) Activate switched network
backup 128 80 BINARY(4) User-defined 1

260 104 CHAR(10) Autocall unit 132 84 BINARY(4) User-defined 2

270 10E CHAR(10) Station address 136 88 BINARY(4) User-defined 3

280 118 CHAR(10) Clocking 140 8C BINARY(4) Autodelete controller

290 122 CHAR(10) Duplex 144 90 BINARY(4) Recovery limits: count

limit
300 12C CHAR(10) Modem type supported
148 94 BINARY(4) Recovery limits: time
310 136 CHAR(10) Modem data rate select interval
320 140 CHAR(10) Switched connection type 152 98 BINARY(4) Offset to list of active
330 14A CHAR(10) Autoanswer switched controllers

340 154 CHAR(10) Autodial

16-48 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
156 9C BINARY(4) Number of active 368 170 BINARY(4) Entry length for list of
switched controllers PVC identifiers
160 A0 BINARY(4) Entry length for list of 372 174 CHAR(13) ATM access type
active switched controllers
385 181 CHAR(32) Emulated LAN name
164 A4 BINARY(4) Offset to list of SSAPs
417 1A1 CHAR(26) Local ATM address:
168 A8 BINARY(4) Number of SSAPs network prefix
172 AC BINARY(4) Entry length for list of 443 1BB CHAR(12) Local ATM address: end-
SSAPs system-identifier
176 B0 BINARY(4) Offset to list of group 455 1C7 CHAR(2) Local ATM address: LAN
addresses emulation client (LEC)
selector byte
180 B4 BINARY(4) Number of group
addresses 457 1C9 CHAR(26) LAN emulation server
(LES) ATM address:
184 B8 BINARY(4) Entry length for list of
network prefix
group addresses
483 1E3 CHAR(12) LAN emulation server
188 BC CHAR(10) Resource name
(LES) ATM address: end
198 C6 CHAR(10) Network controller system identifier
208 D0 CHAR(12) Local adapter address 495 1EF CHAR(2) LAN emulation server
(LES) ATM address:
220 DC CHAR(10) Exchange identifier
selector byte
230 E6 CHAR(10) Ethernet standard
497 1F1 CHAR(26) Last contacted LAN emu-
240 F0 CHAR(10) Error threshold level lation server (LES) ATM
250 FA CHAR(10) Security for line address: network prefix

260 104 CHAR(10) Propagation delay 523 20B CHAR(12) Last contacted LAN emu-
lation server (LES) ATM
270 10E CHAR(10) Autocreate controller address: end system
280 118 BINARY(4) Port number identifier

284 11C CHAR(10) Attached nonswitched 535 217 CHAR(2) Last contacted LAN emu-
NWI lation server (LES) ATM
address: selector byte
294 128 CHAR(10) Network interface DLC
identifier 537 219 CHAR(10) Use LAN emulation
configuration server
304 130 CHAR(10) Network server descrip- (LECS) address
tion
547 223 CHAR(10) Network inteface type
314 13A CHAR(10) Duplex
557 22D CHAR(32) Reported emulated LAN
324 144 BINARY(4) Line Speed name
328 148 CHAR(10) Generate test frame 589 24D CHAR(3) Reserved
338 152 CHAR(2) Reserved 592 250 BINARY(4) LAN emulation client
340 154 BINARY(4) LAN emulation client (LEC) frame size
(LEC) cache aging time 596 254 BINARY(4) Link speed multiplier
344 158 BINARY(4) Address resolution pro- | 600 258 CHAR(10) Message queue: name
tocol (ARP) retry count
| 610 262 CHAR(10) Message queue: library
348 15C BINARY(4) Address resolution pro-
tocol (ARP) retry timer | 620 26C CHAR(10) Current message queue:
| name
352 160 BINARY(4) Maximum address resolu-
tion protocol (ARP) | 630 276 CHAR(10) Current message queue:
entries | library

356 164 BINARY(4) LAN emulation client | 640 280 CHAR(10) TCP/IP only
(LEC) disconnect time out | 650 28A CHAR(2) Reserved
360 168 BINARY(4) Offset to list of PVC iden-
tifiers
364 16C BINARY(4) Number of PVC identifiers

Chapter 16. Configuration APIs 16-49

Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
These fields CHAR(10) Active switched controller 196 C4 BINARY(4) Offset to list of attached
repeat for name nonswitched controllers
each active
CHAR(2) Reserved 200 C8 BINARY(4) Entry length for list of
switched con-
attached nonswitched
troller
controllers
These fields BINARY(4) SSAP maximum frame
204 CC BINARY(4) Offset to list of active
repeat for
CHAR(10) SSAP address switched controllers
each SSAP
CHAR(10) SSAP type 208 D0 BINARY(4) Number of active
switched controllers
This field CHAR(12) Group address
repeats for 212 D4 BINARY(4) Entry length for list of
each group active switched controllers
address
216 D8 BINARY(4) Offset to list of switched
This field BINARY(4) PVC identifier NWIs
repeats for
220 DC BINARY(4) Number of switched NWIs
each PVC
identifier 224 E0 BINARY(4) Entry length for list of
switched NWIs

LIND0600 Format: This format returns detailed informa- 228 E4 CHAR(10) Connection type
tion about a line of category *IDLC. 238 EE CHAR(10) Attached nonswitched
NWI
Offset 248 F8 CHAR(10) NWI channel type
Dec Hex Type Field 258 102 CHAR(10) NWI channel number
0 0 Returns everything from 268 10C CHAR(10) Switched connection type
format LIND0100
278 116 CHAR(10) Connection list
108 6C BINARY(4) Vary on wait
288 120 CHAR(10) Exchange identifier
112 70 BINARY(4) Line speed
298 12A CHAR(10) Error threshold level
116 74 BINARY(4) CRC errors received
308 134 CHAR(13) Information transfer type
120 78 BINARY(4) Short frame
321 141 CHAR(10 Switched NWI selection
124 7C BINARY(4) Receive overrun
331 14B CHAR(10) Security for line
128 80 BINARY(4) Transmit underrun
341 155 CHAR(10) Propagation delay
132 84 BINARY(4) Frame aborts
These fields CHAR(10) Attached nonswitched
136 88 BINARY(4) Retransmitted frames repeat for controller name
140 8C BINARY(4) Frame sequence errors each non-
CHAR(2) Reserved
switched con-
144 90 BINARY(4) Maximum frame size troller
148 94 BINARY(4) Default window size These fields CHAR(10) Active switched controller
152 98 BINARY(4) Frame retry limit repeat for name
each active
156 9C BINARY(4) Response timer CHAR(2) Reserved
switched con-
160 A0 BINARY(4) Connect retry count troller
164 A4 BINARY(4) Link speed These fields CHAR(10) NWI name
repeat for
168 A8 BINARY(4) Cost per connect time CHAR(10) NWI channel type
each switched
172 AC BINARY(4) Cost per byte NWI CHAR(10) NWI channel number
176 B0 BINARY(4) User-defined 1 CHAR(2) Reserved
180 B4 BINARY(4) User-defined 2
184 B8 BINARY(4) User-defined 3
LIND0700 Format: This format returns detailed informa-
tion about a line of category *NET.
188 BC BINARY(4) Recovery limits: count
limit
192 C0 BINARY(4) Recovery limits: time
interval

16-50 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
0 0 Returns everything from 196 C4 BINARY(4) Data Set Ready drop
format LIND0100 timer
108 6C BINARY(4) Offset to list of attached 200 C8 BINARY(4) Clear To Send timer
nonswitched controllers
204 CC BINARY(4) Remote answer timer
112 70 BINARY(4) Entry length for list of
208 D0 BINARY(4) Link speed
attached nonswitched
controllers 212 D4 BINARY(4) Cost per connect time
116 74 CHAR(10) Attached nonswitched 216 D8 BINARY(4) Cost per byte
NWI
220 DC BINARY(4) User-defined 1
These fields CHAR(10) Attached nonswitched
224 E0 BINARY(4) User-defined 2
repeat for controller name
each non- 228 E4 BINARY(4) User-defined 3
CHAR(2) Reserved
switched con- 232 E8 BINARY(4) Recovery limits: count
troller limit
236 EC BINARY(4) Recovery limits: time
LIND0800 Format: This format returns detailed informa- interval
tion about a line of category *SDLC.
240 F0 BINARY(4) Offset to list of attached
nonswitched controllers
Offset
244 F4 BINARY(4) Entry length for list of
Dec Hex Type Field attached nonswitched
0 0 Returns everything from controllers
format LIND0100 248 F8 BINARY(4) Offset to list of active
108 6C BINARY(4) Vary on wait switched controllers

112 70 BINARY(4) Maximum controllers 252 FC BINARY(4) Number of active

switched controllers
116 74 BINARY(4) Line speed
256 100 BINARY(4) Entry length for list of
120 78 BINARY(4) SHM call timer active switched controllers
124 7C BINARY(4) SHM maximum connect 260 104 BINARY(4) Offset to list of resource
timer names
128 80 BINARY(4) SHM answer delay timer 264 108 BINARY(4) Number of resource
132 84 BINARY(4) Connect poll retry names

136 88 BINARY(4) Connect timer 268 10C BINARY(4) Entry length for list of
resource names
140 8C BINARY(4) Short timer
272 110 BINARY(4) Offset to list of call
144 90 BINARY(4) Long timer progress signal retry
148 94 BINARY(4) Short retry values

152 98 BINARY(4) Long retry 276 114 BINARY(4) Number of call progress
signal retry values
156 9C BINARY(4) Maximum frame size
280 118 BINARY(4) Entry length for list of call
160 A0 BINARY(4) Maximum outstanding progress signal retry
frames values
164 A4 BINARY(4) Inactivity timer 284 11C CHAR(10) Data link role
168 A8 BINARY(4) Poll response delay 294 126 CHAR(10) Physical interface
172 AC BINARY(4) Nonproductive receive 304 130 CHAR(10) Connection type
timer
314 13A CHAR(10) Switched network backup
176 B0 BINARY(4) Idle timer
324 144 CHAR(10) Activate switched network
180 B4 BINARY(4) Connect poll timer backup
184 B8 BINARY(4) Poll cycle pause 334 14E CHAR(10) SHM node type
188 BC BINARY(4) Frame retry 344 158 CHAR(10) Autocall unit
192 C0 BINARY(4) Fair polling timer 354 162 CHAR(10) Exchange identifier
364 16C CHAR(10) NRZI data encoding

Chapter 16. Configuration APIs 16-51

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
374 176 CHAR(10) Clocking 108 6C BINARY(4) Offset to list of attached
nonswitched controllers
384 180 CHAR(10) Modem type supported
112 70 BINARY(4) Entry length for list of
394 18A CHAR(10) Modem data rate select
attached nonswitched
404 194 CHAR(10) Switched connection type controllers
414 19E CHAR(10) Autoanswer 116 74 CHAR(10) Attached work station
controller
424 1A8 CHAR(10) Autodial
126 7E CHAR(10) Network controller
434 1B2 CHAR(10) Dial command type
These fields CHAR(10) Attached nonswitched
444 1BC CHAR(10) Autocall resource name
repeat for controller name
454 1C6 CHAR(10) SHM call format each non-
CHAR(2) Reserved
464 1D0 CHAR(10) SHM access code switched con-
troller
474 1DA CHAR(32) Calling number
506 1FA CHAR(10) Station address LIND1000 Format: This format returns detailed informa-
516 204 CHAR(10) Error threshold level tion about a line of category *TRN.
526 20E CHAR(10) Duplex
Offset
536 218 CHAR(10) Modulus
Dec Hex Type Field
546 222 CHAR(10) Autoanswer type
0 0 Returns everything from
556 22C CHAR(10) Security for line
format LIND0100
566 236 CHAR(10) Propagation delay
108 6C BINARY(4) Vary on wait
576 240 CHAR(10) Autoconfigured for AS/36
112 70 BINARY(4) Maximum controllers
| 586 24A CHAR(60) Modem initialization
116 74 BINARY(4) Line speed
| command
120 78 BINARY(4) Maximum frame size
| 646 286 CHAR(2) Reserved
124 7C BINARY(4) Link speed
These fields CHAR(10) Attached nonswitched
repeat for controller name 128 80 BINARY(4) Cost per connect time
each non- 132 84 BINARY(4) Cost per byte
CHAR(2) Reserved
switched con-
troller 136 88 BINARY(4) User-defined 1

These fields CHAR(10) Active switched controller 140 8C BINARY(4) User-defined 2

repeat for name 144 90 BINARY(4) User-defined 3
each active
CHAR(2) Reserved 148 94 BINARY(4) Autodelete controller
switched con-
troller 152 98 BINARY(4) Recovery limits: count
These fields CHAR(10) Resource name limit
repeat for 156 9C BINARY(4) Recovery limits: time
CHAR(2) Reserved
each resource interval
name
160 A0 BINARY(4) Offset to list of active
These fields CHAR(10) Call progress signal retry switched controllers
repeat for value
each call 164 A4 BINARY(4) Number of active
CHAR(2) Reserved switched controllers
signal retry
value 168 A8 BINARY(4) Entry length for list of
active switched controllers
LIND0900 Format: This format returns detailed informa- 172 AC BINARY(4) Offset to list of SSAPs
tion about a line of category *TDLC. 176 B0 BINARY(4) Number of SSAPs
180 B4 BINARY(4) Entry length for list of
Offset
SSAPs
Dec Hex Type Field
184 B8 BINARY(4) Offset to list of function
0 0 Returns everything from addresses
format LIND0100

16-52 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
188 BC BINARY(4) Number of function 436 1B4 BINARY(4) Entry length for list of
addresses PVC identifiers
192 C0 BINARY(4) Entry length for list of 440 1B8 CHAR(13) ATM access type
function addresses
453 1C5 CHAR(32) Emulated LAN name
196 C4 CHAR(10) Resource name
485 1E5 CHAR(26) Local ATM address:
206 CE CHAR(10) Network controller network prefix
216 D8 CHAR(10) TRLAN manager logging 511 1FF CHAR(12) Local ATM address: end-
level: configured system-identifier
226 E2 CHAR(10) TRLAN manager logging 523 20B CHAR(2) Local ATM address: LAN
level: current emulation client (LEC)
selector byte
236 EC CHAR(12) TRLAN manager mode
525 20D CHAR(26) LAN emulation server
248 F8 CHAR(10) Log configuration
(LES) ATM address:
changes
network prefix
258 102 CHAR(10) Token-ring inform of
551 227 CHAR(12) LAN emulation server
beacon
(LES) ATM address: end
268 10C CHAR(12) Local adapter address system identifier
280 118 CHAR(10) Exchange identifier 563 233 CHAR(2) LAN emulation server
(LES) ATM address:
290 122 CHAR(10) Early token release
selector byte
300 12C CHAR(10) Error threshold level
565 235 CHAR(26) Last contacted LAN emu-
310 136 CHAR(10) Security for line lation server (LES) ATM
320 140 CHAR(10) Propagation delay address: network prefix

330 14A CHAR(10) Autocreate controller 591 24F CHAR(12) Last contacted LAN emu-
lation server (LES) ATM
340 154 BINARY(4) Port number address: end system
344 158 CHAR(10) Attached nonswitched identifier
NWI 603 25B CHAR(2) Last contacted LAN emu-
354 162 CHAR(10) Network interface DLC lation server (LES) ATM
identifier address: selector byte

364 16C CHAR(10) Network server descrip- 605 25D CHAR(10) Use LAN emulation
tion configuration server
(LECS) address
374 176 CHAR(10) Autoconfigured for AS/36
615 267 CHAR(10) Network interface type
384 180 CHAR(10) Duplex
625 271 CHAR(32) Reported emulated LAN
394 18A CHAR(10) Activate LAN manager name
404 194 BINARY(4) LAN emulation client 657 291 CHAR(3) Filler for alignment
(LEC) cache aging time
660 294 BINARY(4) Link speed multiplier
408 198 BINARY(4) Address resolution pro-
tocol (ARP) retry count | 664 298 CHAR(10) Message queue: name

412 19C BINARY(4) Address resolution pro- | 674 2A2 CHAR(10) Message queue: library
tocol (ARP) retry timer | 684 2AC CHAR(10) Current message queue:
416 1A0 BINARY(4) LAN emulation client | name
(LEC) frame size | 694 2B6 CHAR(10) Current message queue:
420 1A4 BINARY(4) Maximum address resolu- | library
tion protocol (ARP) These fields CHAR(10) Active switched controller
entries repeat for name
424 1A8 BINARY(4) LAN emulation client each active
CHAR(2) Reserved
(LEC) disconnect time out switched con-
troller
428 1AC BINARY(4) Offset to list of PVC iden-
tifiers These fields BINARY(4) SSAP maximum frame
repeat for
432 1B0 BINARY(4) Number of PVC identifiers CHAR(10) SSAP address
each SSAP
CHAR(10) SSAP type

Chapter 16. Configuration APIs 16-53

Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
This field CHAR(12) Function address 200 C8 BINARY(4) User-defined 2
repeats for
204 CC BINARY(4) User-defined 3
each function
address 208 D0 BINARY(4) Recovery limits: count
limit
This field BINARY(4) PVC identifier
repeats for 212 D4 BINARY(4) Recovery limits: time
each PVC interval
identifier
216 D8 BINARY(4) Offset to list of switched
controllers
LIND1100 Format: This format returns detailed informa- 220 DC BINARY(4) Number of switched con-
tion about a line of category *X25. trollers
224 E0 BINARY(4) Entry length for list of
Offset switched controllers
Dec Hex Type Field 228 E4 BINARY(4) Offset to list of active
0 0 Returns everything from switched controllers
format LIND0100 232 E8 BINARY(4) Number of active
108 6C BINARY(4) Vary on wait switched controllers

112 70 BINARY(4) Line speed 236 EC BINARY(4) Entry length for list of
active switched controllers
116 74 BINARY(4) Maximum frame size
240 F0 BINARY(4) Offset to list of logical
120 78 BINARY(4) Default packet size: channel entries
transmit
244 F4 BINARY(4) Number of logical channel
124 7C BINARY(4) Default packet size: entries
receive
248 F8 BINARY(4) Entry length for list of
128 80 BINARY(4) Maximum packet size: logical channel entries
transmit
252 FC BINARY(4) Offset to list of switched
132 84 BINARY(4) Maximum packet size: NWIs
receive
256 100 BINARY(4) Number of switched NWIs
136 88 BINARY(4) Default window size:
transmit 260 104 BINARY(4) Entry length for list of
switched NWIs
140 8C BINARY(4) Default window size:
receive 264 108 CHAR(10) Resource name

144 90 BINARY(4) Idle timer 274 112 CHAR(20) Local network address

148 94 BINARY(4) Frame retry 294 126 CHAR(10) Connection initiation

152 98 BINARY(4) Predial delay 304 130 CHAR(10) Physical interface

156 9C BINARY(4) Redial delay 314 13A CHAR(10) Connection type

160 A0 BINARY(4) Dial retries 324 144 CHAR(10) Attached nonswitched

NWI
164 A4 BINARY(4) Switched disconnect
timers: minimum con- 334 14E CHAR(10) NWI channel type
nection 344 158 CHAR(10) NWI channel number
168 A8 BINARY(4) Switched disconnect 354 162 CHAR(10) X.25 DCE support
timers: disconnect delay
364 16C CHAR(10) Network controller
172 AC BINARY(4) Data Set Ready drop
timer 374 176 CHAR(10) Exchange identifier

176 B0 BINARY(4) Clear To Send timer 384 180 CHAR(10) Packet mode

180 B4 BINARY(4) Remote answer timer 394 18A CHAR(13) Information transfer type

184 B8 BINARY(4) Link speed 407 197 CHAR(10) Extended network

addressing
188 BC BINARY(4) Cost per connect time
417 1A1 CHAR(10) Modulus
192 C0 BINARY(4) Cost per byte
427 1AB CHAR(10) Insert network address in
196 C4 BINARY(4) User-defined 1 packets

16-54 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
437 1B5 CHAR(10) Error threshold level These fields CHAR(10) NWI name
repeat for
447 1BF CHAR(32) Connection number CHAR(10) NWI channel type
each switched
479 1DF CHAR(32) Calling number NWI CHAR(10) NWI channel number
511 1FF CHAR(10) Modem type supported CHAR(2) Reserved
521 209 CHAR(10) Modem data rate select
531 213 CHAR(10) Switched connection type LIND1200 Format: This format returns detailed informa-
tion about a line of category *DDI.
541 21D CHAR(10) Outgoing connection list
551 227 CHAR(10) Outgoing connection list Offset
entry
Dec Hex Type Field
561 231 CHAR(10) Incoming connection list
0 0 Returns everything from
571 23B CHAR(10) Autoanswer format LIND0100
581 245 CHAR(10) Autodial 108 6C BINARY(4) Vary on wait
591 24F CHAR(10) Dial command type 112 70 BINARY(4) Maximum controllers
601 259 CHAR(10) Call immediate 116 74 BINARY(4) Maximum frame size
611 263 CHAR(10) Autocall unit 120 78 BINARY(4) Token rotation time
621 26D CHAR(10) Autocall resource name 124 7C BINARY(4) Link speed
631 277 CHAR(10) Switched disconnect 128 80 BINARY(4) Autodelete controller
641 281 CHAR(10) Autoanswer type 132 84 BINARY(4) Cost per connect time
651 28B CHAR(10) Switched NWI selection 136 88 BINARY(4) Cost per byte
661 295 CHAR(10) Security for line 140 8C BINARY(4) User-defined 1
671 29F CHAR(10) Propagation delay 144 90 BINARY(4) User-defined 2
681 2A9 CHAR(214) Network user identifica- 148 94 BINARY(4) User-defined 3
tion facility
152 98 BINARY(4) Recovery limits: count
896 380 CHAR(10) Clocking limit
906 38A CHAR(10) Autoconfigured for AS/36 156 9C BINARY(4) Recovery limits: time
| 916 394 CHAR(10) Message queue: name interval

| 926 39E CHAR(10) Message queue: library 160 A0 BINARY(4) Offset to list of active
switched controllers
| 936 3A8 CHAR(10) Current message queue:
| name 164 A4 BINARY(4) Number of active
switched controllers
| 946 3B2 CHAR(10) Current message queue:
| library 168 A8 BINARY(4) Entry length for list of
active switched controllers
| 956 3BC CHAR(60) Modem initialization
| command 172 AC BINARY(4) Offset to list of SSAPs

These fields CHAR(10) Switched controller name 176 B0 BINARY(4) Number of SSAPs
repeat for 180 B4 BINARY(4) Entry length for list of
CHAR(2) Reserved
each switched SSAPs
controller
184 B8 BINARY(4) Offset to list of group
These fields CHAR(10) Active switched controller addresses
repeat for name
each active 188 BC BINARY(4) Number of group
CHAR(2) Reserved addresses
switched con-
troller 192 C0 BINARY(4) Entry length for list of
These fields CHAR(10) Logical channel identifier group addresses
repeat for 196 C4 CHAR(10) Resource name
CHAR(10) Logical channel type
each logical
channel entry CHAR(10) Logical channel controller 206 CE CHAR(10) NWI name

CHAR(2) Reserved 216 D8 CHAR(10) Network interface DLC

identifier
226 E2 CHAR(12) Local adapter address

Chapter 16. Configuration APIs 16-55

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
238 EE CHAR(10) Exchange identifier 152 98 BINARY(4) Offset to list of active
switched controllers
248 F8 CHAR(10) Attach mode
156 9C BINARY(4) Number of active
258 102 CHAR(10) Security for line
switched controllers
268 10C CHAR(10) Propagation delay
160 A0 BINARY(4) Entry length for list of
278 116 CHAR(10) Autocreate controller active switched controllers
288 120 CHAR(10) Logging level 164 A4 BINARY(4) Offset to list of SSAPs
298 12A CHAR(10) Local manager mode 168 A8 BINARY(4) Number of SSAPs
308 134 CHAR(10) Network controller 172 AC BINARY(4) Entry length for list of
SSAPs
| 318 13E CHAR(10) Message queue: name
176 B0 CHAR(10) Attached nonswitched
| 328 148 CHAR(10) Message queue: library
NWI
| 338 152 CHAR(10) Current message queue:
186 BA CHAR(10) Network interface DLC
| name
identifier
| 348 15C CHAR(10) Current message queue:
196 C4 CHAR(10) Exchange identifier
| library
206 CE CHAR(10) Security for line
| 358 166 CHAR(2) Reserved
216 D8 CHAR(10) Propagation delay
These fields CHAR(10) Active switched controller
repeat for name 226 E2 CHAR(10) Network controller
each active
CHAR(2) Reserved | 236 EC CHAR(10) Message queue: name
switched con-
troller | 246 F6 CHAR(10) Message queue: library
These fields BINARY(4) SSAP maximum frame | 256 100 CHAR(10) Current message queue:
repeat for | name
CHAR(10) SSAP address
each SSAP
| 266 10A CHAR(10) Current message queue:
CHAR(10) SSAP type
| library
This field CHAR(12) Group address
These fields CHAR(10) Active switched controller
repeats for
repeat for name
each group
each active
address CHAR(2) Reserved
switched con-
troller
LIND1300 Format: This format returns detailed informa- These fields BINARY(4) SSAP maximum frame
tion about a line of category *FR. repeat for
CHAR(10) SSAP address
each SSAP
Offset CHAR(10) SSAP type

Dec Hex Type Field

0 0 Returns everything from
LIND1400 Format: This format returns detailed informa-
format LIND0100 tion about a line of category *FAX.

108 6C BINARY(4) Vary on wait

Offset
112 70 BINARY(4) Maximum controllers
Dec Hex Type Field
116 74 BINARY(4) Maximum frame size
0 0 Returns everything from
120 78 BINARY(4) Link speed format LIND0100
124 7C BINARY(4) Cost per connect time 108 6C BINARY(4) Vary on wait
128 80 BINARY(4) Cost per byte 112 70 BINARY(4) Offset to list of attached
nonswitched controllers
132 84 BINARY(4) User-defined 1
116 74 BINARY(4) Entry length for list of
136 88 BINARY(4) User-defined 2
attached nonswitched
140 8C BINARY(4) User-defined 3 controllers
144 90 BINARY(4) Recovery limits: count 120 78 BINARY(4) Offset to list of resource
limit names
148 94 BINARY(4) Recovery limits: time 124 7C BINARY(4) Number of resource
interval names

16-56 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
128 80 BINARY(4) Entry length for list of 208 D0 CHAR(12) Local adapter address
resource names
220 DC CHAR(10) Exchange identifier
These fields CHAR(10) Attached nonswitched
230 E6 CHAR(10) Ethernet standard
repeat for controller name
each non- 240 F0 CHAR(10) Security for line
CHAR(2) Reserved
switched con-
250 FA CHAR(10) Propagation delay
troller
260 104 CHAR(10) Autocreate controller
These fields CHAR(10) Resource name
repeat for 270 10E CHAR(10) Initialization source file
CHAR(2) Reserved
each resource name
name 280 118 CHAR(10) Initialization source file
library name
LIND1500 Format: This format returns detailed informa- 290 122 CHAR(10) Initialization source
tion about a line of category *WLS. member name
300 12C CHAR(10) Initialization program
Offset name
Dec Hex Type Field 310 136 CHAR(10) Initialization program
0 0 Returns everything from library name
format LIND0100 These fields CHAR(10) Active switched controller
108 6C BINARY(4) Vary on wait repeat for name
each controller
112 70 BINARY(4) Maximum controllers CHAR(2) Reserved

116 74 BINARY(4) Link speed These fields BINARY(4) SSAP maximum frame
repeat for
120 78 BINARY(4) Cost per connect time CHAR(10) SSAP address
each SSAP
124 7C BINARY(4) Cost per byte CHAR(10) SSAP type

128 80 BINARY(4) User-defined 1 This field CHAR(12) Group address

repeats for
132 84 BINARY(4) User-defined 2 each group
136 88 BINARY(4) User-defined 3 address

140 8C BINARY(4) Autodelete controller

LIND1600 Format: This format returns detailed informa-
144 90 BINARY(4) Recovery limits: count
limit
tion about a line of category *PPP.

148 94 BINARY(4) Recovery limits: time

Offset
interval
Dec Hex Type Field
152 98 BINARY(4) Offset to list of active
switched controllers 0 0 Returns everything from
format LIND0100
156 9C BINARY(4) Number of active
switched controllers 108 6C BINARY(4) Vary on wait
160 A0 BINARY(4) Entry length for list of 112 70 BINARY(4) Line speed
active switched controllers
116 74 BINARY(4) Maximum frame size
164 A4 BINARY(4) Offset to list of SSAPs
120 78 BINARY(4) Inactivity Timer
168 A8 BINARY(4) Number of SSAPs
124 7C BINARY(4) Remote answer timer
172 AC BINARY(4) Entry length for list of
128 80 BINARY(4) Clear to send timer
SSAPs
132 84 BINARY(4) Recovery limits: count
176 B0 BINARY(4) Offset to list of group
limit
addresses
136 88 BINARY(4) Recovery limits: time
180 B4 BINARY(4) Number of group
interval
addresses
140 8C BINARY(4) Link control protocol
184 B8 BINARY(4) Entry length for list of
authentication values:
group addresses
remote peer challenge
188 BC CHAR(10) Resource name timer
198 C6 CHAR(10) Network controller

Chapter 16. Configuration APIs 16-57

 Retrieve Line Description (QDCRLIND) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
144 90 BINARY(4) Link control protocol | 459 1CB CHAR(10) Current message queue:
authentication values: | name
maximum authentication
| 469 1D5 CHAR(10) Current message queue:
attempts
| library
148 94 BINARY(4) Link control protocol
| 479 1DF CHAR(60) Modem init command
configuration values:
| string
configuration retry timer
| 539 21B CHAR(1) Reserved
152 98 BINARY(4) Link control protocol
configuration values: | 540 21C BINARY(4) Offset to list of switched
maximum configuration | NWIs
failures
| 544 220 BINARY(4) Number of switched NWIs
156 9C BINARY(4) Link control protocol
| 548 224 BINARY(4) Entry length for list of
configuration values:
| switched NWIs
maximum configuration
requests | These fields CHAR(10) NWI name
| repeat for
160 A0 BINARY(4) Link control protocol | CHAR(10) NWI channel type
| each switched
configuration values: | CHAR(10) NWI channel number
NWI
maximum termination
requests | CHAR(2) Reserved

164 A4 CHAR(10) Link control protocol

configuration values:
configuration retry timer Field Descriptions
174 AE CHAR(10) Async control character Fields in the various formats returned by this API are
map
described in the online command help for the communica-
184 B8 CHAR(10) Resource name tions line parameters.
194 C2 CHAR(10) Physical interface
In certain cases, numeric values are assigned by this API to
204 CC CHAR(10) Framing type represent character values for some of the returned fields.
214 D6 CHAR(10) Connection type Where a numeric value is assigned, the numeric value and
224 E0 CHAR(10) Network controller
the equivalent character value are listed as an Exception in
the following field descriptions.
234 EA CHAR(10) NRZI
244 F4 CHAR(10) Switched connection type Activate LAN manager (ACTLANMGR). Whether the LAN
manager support is activated. (See the ACTLANMGR
254 FE CHAR(10) Clocking
keyword in the online command help.)
264 108 CHAR(10) Dial command type
274 112 CHAR(40) Set modem to ASYNC Activate switched network backup (ACTSNBU). Whether
command the switched network backup is activated.
314 13A CHAR(32) Calling number Active switched controller name. The name of a controller
346 15A CHAR(10) Flow control associated with this line.
| 356 164 CHAR(10) Attached nonswitched
| NWI
Application type (APPTYPE). The type of application that
this BSC line is used for. (See the APPTYPE keyword in the
| 366 16E CHAR(10) NWI channel number online command help.)
| 376 178 CHAR(13) Information transfer type
ARP retry count. Specifies the number of times an address
| 389 185 CHAR(10) Outgoing connection list
resolution protocol (ARP) request will be retried if no
| 399 18F CHAR(10) Outgoing connection list response is received.
| entry
| 409 199 CHAR(10) Incoming connection list ARP retry timer Specifies the amount of time to wait for a
response to an address resolution protocol (ARP) request.
| 419 1A3 CHAR(10) Switched NWI selection
| 429 1AD CHAR(10) Compression Async control character map. Specifies control characters
| 439 1B7 CHAR(10) Message queue: name that either may not be successfully received over an asyn-
chronous serial line or which may be spuriously introduced
| 449 1C1 CHAR(10) Message queue: library
by other data communications equipment into a transmission
on the line.

16-58 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Attach mode. The attach mode specified when the line was Bytes available. The number of bytes of data available to
created. The term attach mode means the same thing as be returned. All available data is returned if enough space is
station type. provided.

Attached nonswitched controller name. The name of a Bytes returned. The number of bytes of data returned.
controller associated with this line.
Call immediate (CALLIMMED). For switched X.25 lines,
Attached nonswitched NWI. The name of the nonswitched whether a call should be made immediately after varying on
network interface (NWI) description that contains the channel the line description. (See the CALLIMMED keyword in the
to which this line is to be attached. (See the NWI keyword in online command help.)
the online command help.)
Calling number (CALLNBR). The local connection number
Attached workstation controller (WSC). The name of the of a line. (See the CALLNBR keyword in the online
controller description for the 5394 work station controller or command help.)
the work station controller to which the personal computer is
attached. (See the WSC keyword in the online command Call progress signal retry value (CPSRTY). Whether a call
help.) attempt should be retried if the specified call progress signal
is received. (See the CPSRTY keyword in the online
ATM access type (ACCTYPE). The type of access to the command help.)
ATM network.
Character code (CODE). The type of character code used.
Autoanswer (AUTOANS). Whether you intend to use your (See the CODE keyword in the online command help.)
modem’s automatic answer function. (See the AUTOANS
keyword in the online command help.) Clear to send timer (CTSTMR). The length of time that the
system should wait for the modem (DCE) to raise or drop
Autoanswer type (AUTOANSTYP). The method to be used Clear to Send (CTS) before signaling an error. (See the
by the system and modem to answer incoming calls. (See CTSTMR keyword in the online command help.)
the AUTOANSTYP keyword in the online command help.)
Clocking (CLOCK). The clocking function for the line is pro-
Autocall resource name (ACRSRCNAME). The name that vided by the modem (*MODEM). (See the CLOCK keyword
is assigned by the system to a communications port from in the online command help.)
which a communications line attaches to an automatic call
unit. (See the ACRSRCNAME keyword in the online | Compression (COMPRESS). The compression function is
command help.) | provided. (See the COMPRESS keyword in the online
| command help.)
Autocall unit (AUTOCALL). An associated automatic call
unit. (See the AUTOCALL keyword in the online command Connection initiation (CNNINIT). The values to initiate the
help.) X.25 data link connection. (See the CNNINIT keyword in the
online command help.)
Autoconfigured for AS/36. The line was automatically con-
figured for AS/36. Connection list (CNNLSTIN). The name of the connection
list used to retrieve ISDN call information when authorizing
Autocreate controller (AUTOCRTCTL). Whether the incoming calls. (See the CNNLSTIN keyword in the online
system is to automatically create APPC controller descrip- command help.)
tions when incoming calls are received from other systems
on the local area network. (See the AUTOCRTCTL keyword Connection number (CNNNBR). For switched X.25 lines,
in the online command help.) the number of the remote DCE (packet switched data
network) that can be contacted using this line description.
Autodelete controller (AUTODLTCTL). The number of (See the CNNNBR keyword in the online command help.)
minutes the system should wait before automatically varying
off and deleting automatically created controller descriptions Connect poll retry (CNNPOLLRTY). The number of
associated with this line. (See the AUTODLTCTL keyword in connect poll retries that will be attempted before the AS/400
the online command help.) system indicates an error in contacting the remote system or
controller. (See the CNNPOLLRTY keyword in the online
Exception: command help.)
Ÿ Value of -3 implies *NONE Connect poll timer (CNNPOLLTMR). The length of time
that the system waits for the response to a poll while in
Autodial (AUTODIAL). Whether or not you intend to use
normal disconnect mode before polling the next station.
the automatic call function to dial the remote system or
(See the CNNPOLLTMR keyword in the online command
network to establish a switched line connection. (See the
help.)
AUTODIAL keyword in the online command help.)

Chapter 16. Configuration APIs 16-59

Retrieve Line Description (QDCRLIND) API

Connect retry count (IDLCCNNRTY). The number of times Cost per byte (COSTBYTE). The relative cost per byte of
to retry a transmission at connection time. (See the sending and receiving data on the line. (See the
IDLCCNNRTY keyword in the online command help.) COSTBYTE keyword in the online command help.)

Exceptions: Exception:
Ÿ Value of -8 implies *NOMAX Ÿ Value of -9 implies *CNN
Ÿ Value of -9 implies *CNN
Cost per connect time (COSTCNN). The relative cost of
being connected on the line. (See the COSTCNN keyword
Connect timer (CNNTMR). The amount of time that an
in the online command help.)
automatic answer connect request waits for an incoming call
on an X.21 circuit-switched line. (See the CNNTMR keyword
Exception:
in the online command help.)
Ÿ Value of -9 implies *CNN
Exception:
CRC errors received (CRCRCV). The level of error
Ÿ Value of -8 implies *NOMAX
threshold monitoring done by the system for CRC errors
received. (See the CRCRCV keyword in the online
Connection type (CNN). The type of line connection. (See
command help.)
the CNN keyword in the online command help.)

Contention state retry (CTNRTY). The number of con-

Exceptions:
tention state retries that can be attempted before discon- Ÿ Value of -4 implies *OFF
necting the line. (See the CTNRTY keyword in the online
Ÿ Value of -5 implies *MIN
command help.)
Ÿ Value of -6 implies *MED
Continue timer (CONTTMR). The length of time that the
Ÿ Value of -7 implies *MAX
system waits before sending a TTD or WACK control char-
acter. (See the CONTTMR keyword in the online command | Current message queue. The message queue to which
help.) | messages are currently being sent using this line description.
| This field is valid only for lines that are varied on. Note that
Controller category. This value will be one of the following:
| the value of the current message queue may be different
*APPC | from the message queue field (MSGQ parameter) under
| certain error conditions. (See the MSGQ keyword in the
*ASC
| online command help for more details.) This information is
*BSC | returned in two separate fields:
*FNC | Ÿ Name of the queue
*HOST | Ÿ Library in which the queue can be found
*LWS
Data bits per character (BITSCHAR). The data bits per
*NET character (either 7 or 8 bits excluding the parity bit). (See
*RTL the BITSCHAR keyword in the online command help.)

*RWS Data link role (ROLE). Whether this system is the primary
*VWS station or secondary station, or if this station should dynam-
ically negotiate its role with the remote station when the line
*TAP is varied on. (See the ROLE keyword in the online
command help.)
The category value is derived from the command used to
create the controller description. Data set ready drop timer (DSRDRPTMR). The length of
time that the system should wait for the modem (DCE) to
Controller name (CTL). The names of one or more con-
drop Data Set Ready (DSR) after the system has dropped
troller descriptions associated with this line.
Data Terminal Ready (DTR) before signalling an error. (See
Controller text description. A brief description of a con- the DSRDRPTMR keyword in the online command help.)
troller associated with this line.
Data state retry (DTASTTRTY). The time before retry when
Controller type. The type of controller being described. BSC is sending or receiving data on the communications
See the TYPE keyword in the online command help. for a line. (See the DTASTTRTY keyword in the online command
full list of the possible type values. help.)

16-60 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Date information retrieved. The date that the information Echo support (ECHO). Whether the AS/400 system is to
was provided by the API. This is returned as 7 characters in send back (echo) to the remote station none of the charac-
the form CYYMMDD, as follows: ters that it receives, all of the characters it receives, or all
data up to, but not including, the end-of-record character
C Century, where 0 indicates years 19xx and 1
(*CNTL). (See the ECHO keyword in the online command
indicates years 20xx.
help.)
YY Year
MM Month
Emulated LAN name (EMLLANNAME). Specifies the emu-
DD Day
lated LAN name.
Default packet size (DFTPKTSIZE). The default packet
Entry length for list of active switched controllers. The
size to use for controllers attached to this line description.
entry length in bytes of each element in the list of active
This information is returned in two separate fields:
switched controllers returned with this format. A value of
Ÿ Transmit zero is returned if the list is empty.
Ÿ Receive
Entry length for list of attached nonswitched controllers.
The entry length in bytes of each element in the list of
(See the DFTPKTSIZE keyword in the online command
attached nonswitched controllers returned with this format. A
help.)
value of zero is returned if the list is empty.
Exception:
Entry length for list of call progress signal retry values.
Ÿ Value of -10 implies *TRANSMIT The entry length in bytes of each element in the list of call
progress signal retry values returned with this format. A
Default window size: transmit/receive (IDLCWDWSIZ,
value of zero is returned if the list is empty.
DFTWDWSIZE) The default window size used for this line
description. (See the IDLCWDWSIZ and DFTWDWSIZE Entry length for list of EOR characters. The entry length
keywords in the online command help.) in bytes of each element in the list of end-of-record (EOR)
characters returned with this format. A value of zero is
Exceptions: returned if the list is empty.
Ÿ Value of -9 implies *CNN
Entry length for list of function addresses. The entry
Ÿ Value of -10 implies *TRANSMIT length in bytes of each element in the list of function
addresses returned with this format. A value of zero is
Dial command type (DIALCMD). The dial command type
returned if the list is empty.
used to establish a connection with a remote system. (See
the DIALCMD keyword in the online command help.) Entry length for list of group addresses. The entry length
in bytes of each element in the list of group addresses
Dial retries (DIALRTY). The number of times to retry dialing
returned with this format. A value of zero is returned if the
the number before considering the dialing unsuccessful.
list is empty.
(See the DIALRTY keyword in the online command help.)
Entry length for list of logical channel entries. The entry
Duplex (DUPLEX).
length in bytes of each element in the list of logical channel
Ÿ WAN (Async, SDLC, or Bisync): Whether the AS/400 entries returned with this format. A value of zero is returned
system will leave the request-to-send (RTS) modem if the list is empty.
signal on continuously, or whether the RTS will be raised
when the AS/400 system must transmit data and Entry length for list of PVC identifiers. The entry length in
dropped when it is finished transmitting. bytes of each element in the list of permanent virtual circuits
(PVC) returned with this format. A value of zero is returned
Ÿ LAN (Ethernet or Token-Ring): Whether the hardware is
if the list is empty.
able to send and receive data simultaneously. In half
duplex, one wire must alternate between sending and Entry length for list of resource names. The entry length
receiving. With duplex, one wire is dedicated to send in bytes of each element in the list of resource names
and another to receive, and hence simultaneous send returned with this format. A value of zero is returned if the
and receive operations may occur. With full duplex, a list is empty.
hub is required. With *AUTO, the duplex value will be
determined by the hardware. Entry length for list of SSAPs. The entry length in bytes of
each element in the list of SSAPs returned with this format.
(See the DUPLEX keyword in the online command help.) A value of zero is returned if the list is empty.
Early token release (ELYTKNRLS). Allows greater Entry length for list of switched controllers. The entry
throughput on 16MB token-ring network lines. (See the length in bytes of each element in the list of switched control-
ELYTKNRLS keyword in the online command help.)

Chapter 16. Configuration APIs 16-61

Retrieve Line Description (QDCRLIND) API

lers returned with this format. A value of zero is returned if Frame sequence errors (FRMSEQERR). The level of error
the list is empty. threshold monitoring done by the system for frame sequence
errors. (See the FRMSEQERR keyword in the online
Entry length for list of switched NWIs. The entry length in command help.)
bytes of each element in the list of switched network inter-
face (NWI) descriptions returned with this format. A value of Exceptions:
zero is returned if the list is empty.
Ÿ Value of -4 implies *OFF
EOR character. The end-of-record character. Ÿ Value of -5 implies *MIN
Ÿ Value of -6 implies *MED
Error threshold level (THRESHOLD). The level of the error
threshold that is monitored by the system. (See the Ÿ Value of -7 implies *MAX
THRESHOLD keyword in the online command help.)
Framing type (FRAMING). Specifies whether the line uses
Ethernet standard (ETHSTD). The standard used by the asynchronous or synchronous framing.
Ethernet local area network. (See the ETHSTD keyword in
the online command help.) Function address. Functional address used by token-ring
network lines.
Exchange identifier (EXCHID). The exchange identifier that
the local AS/400 system can send to the remote controller or Generate test frame (GENTSTFRM). Whether the system
system. (See the EXCHID keyword in the online command will have test frames automatically generated. Test frames
help.) are used to detect whether the Ethernet network has become
inoperational during idle periods. (See the GENTSTFRM
Extended network addressing (EXNNETADR). Whether keyword in the online command help.)
extended network addressing is used by this line description
and attached controller descriptions. (See the EXNNETADR Group address. The group of addresses to which a subset
keyword in the online command help.) of nodes on the network respond to, in addition to their local
adapter addresses.
Fair polling timer (FAIRPLLTMR). The maximum length of
time (in seconds) that the system will send data to one or Idle timer (IDLTMR). The maximum allowable time between
more stations on the line before polling stations without characters before the adapter forwards the receive buffer to
pending output requests. (See the FAIRPLLTMR keyword in the system. (See the IDLTMR keyword in the online
the online command help.) command help.)

Flow control (FLOWCNTL). Whether you will use the XON Inactivity timer (INACTTMR). The time that the system
and XOFF flow control characters to control the flow of data waits for activity on a line before disconnecting. (See the
to your system. (See the FLOWCNTL keyword in the online INACTTMR keyword in the online command help.)
command help.)
Exception:
Frame aborts (ABORTS). The level of error threshold moni- Ÿ Value of -8 implies *NOMAX
toring done by the system for frame aborts. (See the
ABORTS keyword in the online command help.) Include STX character in the LRC (STXLRC). Whether to
exclude the start-of-text (STX) character in the longitudinal
Exceptions: redundancy check (LRC) calculation. (See the STXLRC
Ÿ Value of -4 implies *OFF keyword in the online command help.)

Ÿ Value of -5 implies *MIN Incoming connection list (CNNLSTIN). The name of the
Ÿ Value of -6 implies *MED connection list used to retrieve ISDN call information when
authorizing incoming calls. (See the CNNLSTIN keyword in
Ÿ Value of -7 implies *MAX the online command help.)
Frame retry (FRAMERTY). The number of retries for an Information transfer type (INFTRFTYPE). How data is to
unanswered or unacknowledged frame. (See the be encoded for the ISDN B-channel associated with this line
FRAMERTY keyword in the online command help.) description. (See the INFTRFTYPE keyword in the online
command help.)
Frame retry limit (IDLCFRMRTY). The maximum number
of frame retransmissions to attempt before initiating recovery. Initialization program library name. The name of the
(See the IDLCFRMRTY keyword in the online command library in which the initialization program resides.
help.)
Initialization program name. The name of a program that
Exception: is called to manage configuration initialization data.
Ÿ Value of -9 implies *CNN

16-62 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Initialization source file library name. The name of the Line speed (LINESPEED). The line speed in bits per
library in which the initialization source file resides. second (bps). (See the LINESPEED keyword in the online
command help.)
Initialization source file name. The name of a source file
containing configuration initialization data. Exception:
Ÿ Value of -11 implies *CALC
Initialization source member name. The name of a source
member containing configuration initialization data. Ÿ Value of -23 implies 10M
Ÿ Value of -24 implies 4M
Insert network address in packets (ADRINSERT).
Whether the AS/400 system inserts the local network Ÿ Value of -25 implies 16M
address (NETADR) in call-request and call-accept packets.
Ÿ Value of -27 implies *NWI
(See the ADRINSERT keyword in the online command help.)
Ÿ Value of -29 implies 100M
Last contacted LES ATM address. Specifies the most
Ÿ Value of -30 implies *AUTO
recently used LAN emulation server (LES) ATM network
address associated with this line.
Ÿ Element 1: Network prefix: The network prefix of the Link control protocol authentication values (LCPAUT).
ATM address of the remote server. This is a 26 digit Specifies values controlling how the Link Control Protocol
hexadecimal value. layer of AS/400 Point-to-Point Protocol (PPP) authenticates a
remote peer. These values are returned in two separate
Ÿ Element 2: End-system-identifier: The end system identi-
fields:
fier of the remote server. This is a 12 digit hexadecimal
value. Ÿ Remote peer challenge timer: Specifies the interval, in
minutes, to periodically issue an authentication challenge
Ÿ Element 3: Selector byte: The selector byte of the
to the remote peer.
remote server. This is a two digit hexadecimal value.
Ÿ Maximum authentication attempts: Specifies the
LEC cache aging time. Specifies the time-out period for maximum number of unacknowledged authentication
which an address resolution protocol (ARP) entry will be challenges sent to a remote peer before assuming that
cached without verification of that entry. the peer is unable to respond.

LAN emulation client (LEC) frame size. The LAN emu- Exceptions:
lation client (LEC) frame size.
Ÿ Value of 0 implies *NONE
Exception: Link control protocol configuration values (LCPCFG).
Ÿ Value of -11 implies *CALC Specifies values controlling how the Link Control Protocol
layer of AS/400 PPP negotiates mutually acceptable link
Line category. This value will be one of the following: configuration values with a remote peer. These values are
*ASC returned in four separate fields:

*BSC Ÿ Configuration retry timer: Specifies the interval, in

seconds, that the AS/400 waits before resending an
*DDI
unacknowledged configuration, termination, or
*ETH authentication challenge request to a remote peer. This
value is returned in two seperate fields:
*FAX
– As an integer representing tenths of a second.
*FR
– As a CHAR(10) string with the real number value in
*IDLC
seconds.
*NET
Ÿ Maximum configuration failures: Specifies the maximum
*SDLC number of attempts that are made to negotiate a mutu-
*TDLC ally acceptable configuration with a remote peer before
assuming that configuration is not converging.
*TRN
Ÿ Maximum configuration requests: Specifies the
*WLS maximum number of unacknowledged configuration
*X25 requests sent to a remote peer before assuming that the
peer is unable to respond.
The category value is derived from the command used to
Ÿ Maximum termination requests: Specifies the maximum
create the line description.
number of unacknowledged termination request packets
Line name. The name of the line description.

Chapter 16. Configuration APIs 16-63

Retrieve Line Description (QDCRLIND) API

sent to a remote peer before assuming that the peer is Logical channel controller. Either an SVC or an attached
unable to respond. PVC controller.

Link speed (LINKSPEED). The link speed in bits per For a switched virtual circuit (SVC) logical channel, this is the
second (bps). (See the LINKSPEED keyword in the online controller description currently active on this logical channel.
command help.)
For a permanent virtual circuit (PVC) logical channel, this is
Exceptions: the controller description permanently attached to this logical
channel.
Ÿ Value of -5 implies *MIN
Ÿ Value of -7 implies *MAX Logical channel identifier. An identifier consisting of 3
hexadecimal characters that can range from hex 001 to hex
Ÿ Value of -12 implies *INTERFACE
FFF. The first character represents the logical channel
Ÿ Value of -23 implies 10 megabits per second group, as assigned by the network subscription. The last 2
Ÿ Value of -24 implies 4 megabits per second characters are the network-assigned logical channel number.

Ÿ Value of -25 implies 16 megabits per second Logical channel type. The type of logical channel.
Ÿ Value of -29 implies 100 megabits per second
Long retry (LONGRTY). The number of bursts of call retry
Note: For Ethernet (LIND0500) and Token-Ring (LIND1000), attempts that the system makes when processing a con-
link speeds over one gigabit per second must be retrieved nection request. (See the LONGRTY keyword in the online
from two parameters as follows: command help.)
LINKSPEED = (linkspeed_multiplier x (10**9)) + linkspeed
Long timer (LONGTMR). The length of time that the system
For link speeds less than one gigabit per second, the
waits between connection retry attempts. (See the
linkspeed multiplier will contain zero.
LONGTMR keyword in the online command help.)
Local ATM address. Specifies the local ATM network
Maximum ARP entries. Specifies the maximum number of
address associated with this line.
address resolution protocol (ARP) table entries. This repre-
Ÿ Element 1: Network prefix: The network prefix of the sents the maximum number of LAN emulation MAC
ATM address of the remote server. This is a 26 digit addresses that can be resolved at any point in time.
hexadecimal value.
Maximum buffer size (MAXBUFFER). The maximum size
Ÿ Element 2: End-system-identifier: The end system identi-
of the incoming and outgoing buffers. (See the
fier of the remote server. This is a 12 digit hexadecimal
MAXBUFFER keyword in the online command help.)
value.
Ÿ Element 3: LAN emulation client (LEC) selector byte: Maximum controllers (MAXCTL). The maximum number of
The LEC selector byte. This is a two digit hexadecimal controllers this line can support. (See the MAXCTL keyword
value. in the online command help.)

Local adapter address. The address used by the adapter Maximum frame size (MAXFRAME). The maximum frame
for this line to transmit from and answer to on the token-ring size or logical link control data unit that can be transmitted
or LAN. (See the ADPTADR keyword in the online and received on this line. (See the MAXFRAME keyword in
command help.) the online command help.)

Local manager mode (LCLMGRMODE). The local Maximum outstanding frames (MAXOUT). The maximum
manager mode used with a distributed data interface (DDI) number of information frames that can be sent to a remote
line. (See the LCLMGRMODE keyword in the online system and received from a remote system before allowing
command help.) the receiving system to respond. (See the MAXOUT
keyword in the online command help.)
Local network address. The network address of the
AS/400 system. (See the NETADR keyword in the online Maximum packet size (MAXPKTSIZE). The maximum
command help.) packet size that can be used by any controller associated
with this line description. This information is returned in two
Log configuration changes (LOGCFGCHG). Whether the separate fields:
token-ring network manager for this line is to log configura-
Ÿ Transmit
tion changes on the ring. (See the LOGCFGCHG keyword in
the online command help.) Ÿ Receive

Logging level (LOGLVL). The error logging level used with (See the MAXPKTSIZE keyword in the online command
a distributed data interface (DDI) line. (See the LOGLVL help.)
keyword in the online command help.)
Exceptions:

16-64 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Ÿ Value of -10 implies *TRANSMIT with this format. A value of zero is returned if the list is
empty.
Ÿ Value of -13 implies *DFTPKTSIZE
Number of attached nonswitched controllers. The
| Message queue (MSGQ). The message queue to which
number of elements in the list of attached nonswitched con-
| operational messages for this line should normally be sent.
trollers returned with this format. A value of zero is returned
| Note that this is the value entered on the MSGQ parameter
if the list is empty.
| of the CL command, but under certain error conditions it may
| not be the message queue currently in use. See the current Number of call progress signal retry values. The number
| message queue field to determine what message queue is of elements in the list of call progress signal retry values
| actually being used at a given time. (See the MSGQ returned with this format. A value of zero is returned if the
| keyword in the online command help for more information.) list is empty.
| This information is returned in two separate fields:
| Ÿ Name of the queue Number of EOR characters. The number of elements in
the list of end-of-record (EOR) characters returned with this
| Ÿ Library in which the queue can be found format. A value of zero is returned if the list is empty.
Modem data rate select (MODEMRATE). Whether this Number of function addresses. The number of elements
modem is being operated at its full rated speed, or at an in the list of function addresses returned with this format. A
alternate or half speed. (See the MODEMRATE keyword in value of zero is returned if the list is empty.
the online command help.)
Number of group addresses. The number of elements in
| Modem initialization command string (MDMINZCMD). the list of group addresses returned with this format. A value
| The command string to send to set the modem. (See the of zero is returned if the list is empty.
| MDMINZCMD keyword in the online command help.)
Number of logical channel entries. The number of ele-
Modem type supported (MODEM). The type of modem ments in the list of logical channel entries returned with this
diagnostic tests to be used on the line. (See the MODEM format. A value of zero is returned if the list is empty.
keyword in the online command help.)
Number of PVC identifiers. The number of elements in the
Modulus (MODULUS). Whether extended sequence list of permanent virtual circuits returned with this format. A
numbers are used (modulus 128) or not (modulus 8). (See value of zero is returned if the list is empty.
the MODULUS keyword in the online command help.)
Number of resource names. The number of elements in
Network controller (NETCTL). The name of an existing the list of resource names returned with this format. A value
network controller description. (See the NETCTL keyword in of zero is returned if the list is empty.
the online command help.)
Number of SSAPs. The number of elements in the list of
Network interface DLC identifier. The data link control source service access points (SSAPs) returned with this
(DLC) identifier used to connect to the network. format. A value of zero is returned if the list is empty.
Network server description. The name of the network Number of switched controllers. The number of elements
server to which the nonswitched line is attached. in the list of switched controllers returned with this format. A
value of zero is returned if the list is empty.
Network user identification facility (NETUSRID). Allows
X.25 network subscribers to specify the network user identifi- Number of switched NWIs. The number of elements in the
cation (NUI) selection facility that is encoded in the facility list of switched network interface (NWI) descriptions returned
field of all call request packets sent on this line. (See the with this format. A value of zero is returned if the list is
NETUSRID keyword in the online command help.) empty.
Nonproductive receive timer (NPRDRCVTMR). The time Number of trailing characters. The value returned with
that the system waits for either a final frame or an idle signal each element in the list of EOR characters.
while the secondary station is continuously transmitting.
(See the NPRDRCVTMR keyword in the online command NWI channel number (NWICHLNBR). The network inter-
help.) face (NWI) channel to be used by this line description. (See
the NWICHLNBR keyword in the online command help.)
NRZI data encoding (NRZI). Whether or not the AS/400
system uses the non-return-to-zero inverted (NRZI) trans- NWI channel type (NWICHLTYPE). The type of network
mission coding method. (See the NRZI keyword in the interface channels to be used by this line description. (See
online command help.) the NWICHLTYPE keyword in the online command help.)

Number of active switched controllers. The number of NWI name. The name of the existing network interface
elements in the list of active switched controllers returned description.

Chapter 16. Configuration APIs 16-65

Retrieve Line Description (QDCRLIND) API

Offset to list of active switched controllers. The offset in Outgoing connection list (CNNLSTOUT). For switched
bytes to the first element in the list of active switched control- ISDN connections, the name of a connection list containing
lers returned with this format. A value of zero is returned if the network-assigned numbers used for outgoing calls on this
the list is empty. controller. (See the CNNLSTOUT keyword in the online
command help.)
Offset to list of attached nonswitched controllers. The
offset in bytes to the first element in the list of attached non- Outgoing connection list entry (CNNLSTOUTE). For
switched controllers returned with this format. A value of switched ISDN connections, the name of the connection list
zero is returned if the list is empty. entry containing the network-assigned numbers used for out-
going calls on this line. (See the CNNLSTOUTE keyword in
Offset to list of call progress signal retry values. The the online command help.)
offset in bytes to the first element in the list of call progress
signal retry values returned with this format. A value of zero Packet mode (PKTMODE). Allows an AS/400 system to
is returned if the list is empty. communicate directly with another system by using the
B-channel X.25 virtual circuit service integrated within an
Offset to list of EOR characters. The offset in bytes to the ISDN. (See the PKTMODE keyword in the online command
first element in the list of EOR characters returned with this help.)
format. A value of zero is returned if the list is empty.
PVC identifiers (PVCID). Specifies the virtual path identifier
Offset to list of function addresses. The offset in bytes to and virtual circuit ID.
the first element in the list of function addresses returned
with this format. A value of zero is returned if the list is Physical interface (INTERFACE). The type of physical
empty. communications line interface that this communications
adapter port and cable will be attached to. (See the INTER-
Offset to list of group addresses. The offset in bytes to FACE keyword in the online command help.)
the first element in the list of group addresses returned with
this format. A value of zero is returned if the list is empty. Poll cycle pause (POLLPAUSE). The length of time that
the system waits after the last remote system in the poll list
Offset to list of logical channel entries. The offset in is polled before beginning another pass through the poll list.
bytes to the first element in the list of logical channel entries (See the POLLPAUSE keyword in the online command help.)
returned with this format. A value of zero is returned if the
list is empty. Poll response delay (POLLRSPDLY). The minimum dura-
tion of time that the system waits before it responds to a data
Offset to list of PVC identifiers. The offset in bytes to the poll if there is no information frame to transmit. (See the
first element in the list of permanent virtual circuits returned POLLRSPDLY keyword in the online command help.)
with this format. A value of zero is returned if the list is
empty. Port number. The port number on the network server to
which this line is physically attached.
Offset to list of resource names. The offset in bytes to the
first element in the list of resource names returned with this Exceptions:
format. A value of zero is returned if the list is empty.
Ÿ Value of -28 implies *INTERNAL
Offset to list of SSAPs. The offset in bytes to the first
Predial delay (PREDIALDLY). The length of time to wait
element in the list of source service access points (SSAPs)
before dialing the number to establish a connection to the
returned with this format. A value of zero is returned if the
remote system or network. (See the PREDIALDLY keyword
list is empty.
in the online command help.)
Offset to list of switched controllers. The offset in bytes
Propagation delay (PRPDLY). The time required for a
to the first element in the list of switched controllers returned
signal to travel from one end of a link to the other end. (See
with this format. A value of zero is returned if the list is
the PRPDLY keyword in the online command help.)
empty.
Receive overrun (OVERRUN). The level of error threshold
Offset to list of switched NWIs. The offset in bytes to the
monitoring done by the system for receive overrun errors.
first element in the list of switched network interface (NWI)
(See the OVERRUN keyword in the online command help.)
descriptions returned with this format. A value of zero is
returned if the list is empty. Exceptions:
Online at IPL (ONLINE). Whether or not the line is varied Ÿ Value of -4 implies *OFF
on automatically when the system is turned on. (See the Ÿ Value of -5 implies *MIN
ONLINE keyword in the online command help.)
Ÿ Value of -6 implies *MED
Ÿ Value of -7 implies *MAX

16-66 AS/400 System API Reference V4R4

 Retrieve Line Description (QDCRLIND) API

Receive timer (RCVTMR). The maximum amount of time Response timer (IDLCRSPTMR). The length of time to wait
the AS/400 system waits for a response from the remote before retransmitting a frame when an acknowledgement is
system before a time-out occurs. (See the RCVTMR not received. (See the IDLCRSPTMR keyword in the online
keyword in the online command help.) command help.)

Receive TTD or WACK retry (RCVRTY). The number of Exception:

times that a temporary text delay (TTD) or wait-before-
Ÿ Value of -9 implies *CNN
transmit-positive acknowledgement (WACK) is received
before the session fails. (See the RCVRTY keyword in the Resource name (RSRCNAME). The unique name that is
online command help.) assigned by the system to the physical equipment (in this
case, a communications port) attached to the system. (See
Exception: the RSRCNAME keyword in the online command help.)
Ÿ Value of -8 implies *NOMAX
Retransmitted frames (RETRANSMIT). The level of error
Recovery limits (CMNRCYLMT). The second-level commu- threshold monitoring done by the system for retransmitted
nications recovery limit for each line description. These limits frames. (See the RETRANSMIT keyword in the online
are returned in two separate fields: command help.)
Ÿ Count limit: The number of second-level recovery
Exceptions:
attempts to be automatically performed by the system.
Ÿ Value of -4 implies *OFF
Ÿ Time interval: The length of time (in minutes) in which
the specified number of second-level recoveries can be Ÿ Value of -5 implies *MIN
attempted. Ÿ Value of -6 implies *MED

(See the CMNRCYLMT keyword in the online command Ÿ Value of -7 implies *MAX
help.)
Security for line (SECURITY). The types of security pro-
Exception: tection available on the line. (See the SECURITY keyword in
the online command help.)
Ÿ Value of -14 implies *SYSVAL
Segment number. The unique number that identifies the
Redial delay (REDIALDLY). The length of time to wait
LAN to which the network server is attached.
before redialing the number to establish a connection to the
remote system or network if the prevaous attempt was Set modem to ASYNC command (SETMDMASC). The
unsuccessful. (See the REDIALDLY keyword in the online V25BIS command that is used to set the modem to ASYNC
command help.) mode. (See the SETMDMASC keyword in the online
command help.)
LES ATM address (LESATMADR). Specifies the ATM
network address of the remote LAN emulation server. This Short frame (SHORTFRAME). The level of error threshold
address is returned in three separate fields: monitoring done by the system for short frame errors. (See
Ÿ Element 1: Network prefix: The network prefix of the the SHORTFRAME keyword in the online command help.)
ATM address of the remote server. This is a 26 digit
hexadecimal value.
Exceptions:
Ÿ Value of -4 implies *OFF
Ÿ Element 2: End system identifier: Specify the end
system identifier of the remote server. This is a 12 digit Ÿ Value of -5 implies *MIN
hexadecimal value.
Ÿ Value of -6 implies *MED
Ÿ Element 3: Selector byte: The selector byte of the
Ÿ Value of -7 implies *MAX
remote server. This is a two digit hexadecimal value.
SHM access code (SHMACC). The access code used by
Remote answer timer (RMTANSTMR). The length of time
an X.21 short-hold mode (SHM) line when calling a system
that the system should wait for the modem (DCE) to raise
on another network. (See the SHMACC keyword in the
Data Set Ready (DSR) after dialing before signaling an error.
online command help.)
(See the RMTANSTMR keyword in the online command
help.) SHM answer delay timer (SHMANSDLY). The length of
time the system waits for controllers to call in before
Reported emulated LAN name. The reported emulated
attempting to call out. (See the SHMANSDLY keyword in the
LAN name.
online command help.)
Reserved. Space included for alignment.
Exception:
Ÿ Value of -8 implies *NOMAX

Chapter 16. Configuration APIs 16-67

Retrieve Line Description (QDCRLIND) API

SHM call format (SHMCALLFMT). The format of the Switched controller name. The name of a controller asso-
network identifier used in the local system’s connection ciated with this line.
number. (See the SHMCALLFMT keyword in the online
command help.) Switched disconnect (SWTDSC). For switched lines
(CNN(*SWTPP)), whether the line is to be dropped when no
SHM call timer (SHMCALLTMR). The interval at which a virtual circuits are active and the disconnection timers speci-
connection is reestablished on an X.21 short-hold mode line fied on the SWTDSCTMR parameter have expired. (See the
to verify the state of the remote system if no normal data SWTDSC keyword in the online command help.)
traffic occurs in the specified interval. (See the
SHMCALLTMR keyword in the online command help.) LEC disconnect time out (LECDSCTIMO). Specifies the
amount of time in minutes a LAN emulation client will wait
Exception: before disconnecting an idle virtual circuit connection to
another client.
Ÿ Value of -3 implies *NONE

SHM maximum connect timer (SHMMAXCNN). The length

Exception:
of time the system allows connection to any one controller Ÿ Value of -8 implies *NOMAX
when there are more controllers than there are available
ports. (See the SHMMAXCNN keyword in the online Switched disconnect timers (SWTDSCTMR). The timers
command help.) used for disconnecting switched lines from a network or
remote system. The timer values are returned in two sepa-
Exception: rate fields:
Ÿ Value of -8 implies *NOMAX Ÿ Minimum connection: The minimum length of time the
system keeps the connection active.
SHM node type (SHMNODE). The physical unit type of the
Ÿ Disconnect delay: The length of time the system waits
controllers using the X.21 short-hold mode line. (See the
before attempting to disconnect the switched connection
SHMNODE keyword in the online command help.)
when the line is idle and the minimum connection time
Short retry (SHORTRTY). The number of retry attempts has expired.
that the system makes during a burst of call retries. (See the
(See the SWTDSCTMR keyword in the online command
SHORTRTY keyword in the online command help.)
help.)
Short timer (SHORTTMR). The length of time that the
Switched network backup (SNBU). Whether or not you
system waits between retry attempts when processing a con-
want the switched network backup capability. (See the
nection request. (See the SHORTTMR keyword in the online
SNBU keyword in the online command help.)
command help.)
Switched NWI selection (SWTNWISLCT). The method
SSAP address. The hexadecimal logical channel address
used to select network interface (NWI) descriptions from the
that is used to route data off the line to the proper user.
switched NWI list. (See the SWTNWISLCT keyword in the
SSAP maximum frame. The largest frame size allowed on online command help.)
this source service access point (SSAP).
SYN characters (SYNCCHARS). The number of SYN char-
Exception: acters used to establish and maintain synchronization and as
time-fill characters in the absence of any data or other
Ÿ Value of -26 implies *MAXFRAME
control character. (See the SYNCCHARS keyword in the
online command help.)
SSAP type. The type of communications used by the
system on this SSAP.
| TCP/IP only (TCPONLY). Whether or not you want the line
| description to be used for TCP/IP only.
Station address (STNADR). The address used by the
remote control station to poll the AS/400 system. (See the
Text description (TEXT). A brief description of the line and
STNADR keyword in the online command help.)
its location. (See the TEXT keyword in the online command
help.)
Stop bits (STOPBITS). The number of bits to be added to
the end of each character to keep the local and remote ends
Time information retrieved. The time that the information
of the line synchronized. (See the STOPBITS keyword in the
was provided by the API. It is returned as 6 characters in
online command help.)
the form HHMMSS, where:
Switched connection type (SWTCNN). Whether the line HH Hour
can be used for incoming and outgoing calls, incoming calls MM Minute
only, or outgoing calls only. (See the SWTCNN keyword in SS Second
the online command help.)

16-68 AS/400 System API Reference V4R4

 Retrieve Network Server Description (QDCRNWSD)

Token-ring inform of beacon (TRNINFBCN). Whether the the line that you want to control. (See the USRDFN1,
token-ring network manager for this line is to provide notifica- USRDFN2, and USRDFN3 keywords in the online command
tion of beaconing on the ring to the system operator. (See help.)
the TRNINFBCN keyword in the online command help.)
Vary on wait (VRYWAIT). Whether the line is varied on
Token rotation time. The token rotation time requested synchronously or asynchronously. (See the VRYWAIT
when the line was created. keyword in the online command help.)

Exception: Exception:
Ÿ Value of -11 implies *CALC Ÿ Value of -15 implies *NOWAIT

Transmit TTD or WACK retry (TMTRTY). The number of X.25 DCE support (X25DCE). Allows an AS/400 system to
times that a temporary-text-delay (TTD) or wait-before- communicate directly with another system without going
transmit-positive acknowledgement (WACK) control character through an X.25 network. (See the X25DCE keyword in the
is sent to hold up the line when the AS/400 system is not online command help.)
ready to respond to the remote end. (See the TMTRTY
keyword in the online command help.) XOFF character (XOFFCHAR). The hexadecimal value
used to tell your line to stop sending data. (See the
Exception: XOFFCHAR keyword in the online command help.)
Ÿ Value of -8 implies *NOMAX
XON character (XONCHAR). The hexadecimal value used
to tell your line to start sending data. (See the XONCHAR
Transmit underrun (UNDERRUN). The level of error
keyword in the
threshold monitoring done by the system for transmit
underrun errors. (See the UNDERRUN keyword in the
online command help.) Error Messages
Exceptions: CPF24B4 E Severe error while addressing parameter list.
CPF2625 E Not able to allocate object &1.
Ÿ Value of -4 implies *OFF CPF2634 E Not authorized to object &1.
Ÿ Value of -5 implies *MIN CPF26A7 E Category of object not compatible with API
format.
Ÿ Value of -6 implies *MED
CPF26B2 E NetBIOS description &1 previously deleted.
Ÿ Value of -7 implies *MAX CPF2703 E Controller description &1 not found.
CPF2704 E Line description &1 not found.
TRLAN manager logging level (TRNLOGLVL). The CPF3C19 E
logging level to be used by the token-ring network manager. Error occurred with receiver variable specified.
This information is returned in two separate fields: CPF3C21 E
Ÿ Configured Format name &1 is not valid.
CPF3C24 E
Ÿ Current
Length of the receiver variable is not valid.
(See the TRNLOGLVL keyword in the online command help.) CPF3CF1 E
Error code parameter not valid.
TRLAN manager mode (TRNMGRMODE). Whether the CPF3C90 E
token-ring network manager for this line is operating in Literal value cannot be changed.
observing or controlling mode. (See the TRNMGRMODE CPF8104 E Controller description &4 damaged.
keyword in the online command help.) CPF811D E
Network interface description &4 damaged.
Use LECS address (USELECSADR). Specifies whether the CPF8125 E Line description &4 damaged.
local system contacts the LAN emulation server (LES) CPF9872 E Program or service program &1 in library &2
address. ended. Reason code &3.

Type of parity (PARITY). The type of parity for error

checking. (See the PARITY keyword in the online command
help.)
Retrieve Network Server Description
(QDCRNWSD) API
User-defined 1, 2, and 3 (USRDFN1, USRDFN2,
USRDFN3). Used to describe any unique characteristics of

Chapter 16. Configuration APIs 16-69

Retrieve Network Server Description (QDCRNWSD)

| Note: Format NWSD0500 is no longer supported.

Required Parameter Group: Network server name
INPUT; CHAR(10)
1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4) The name of the network server description to be
3 Format name Input Char(8) retrieved.
4 Network server name Input Char(10)
5 Error code I/O Char(*) Error code
I/O; CHAR(*)
Threadsafe: Yes
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
The Retrieve Network Server Description (QDCRNWSD) API on page 2-6.
retrieves information about a network server description.
Format of Network Server Information
Authorities and Locks
When the network server category is unknown, specify
Line Description Authority NWSD0100 and the basic information (including network
*USE server category) will be returned. When the network server
Network Server Description Authority category is known, specify one of the other category-specific
*USE formats.
Line Description Lock
*EXCLRD For detailed descriptions of the fields returned in these
Network Server Description Lock formats, see “Field Descriptions” on page 16-75.
*EXCLRD
NWSD0100 Format: Use this format to find out the
network server category, plus some basic information about
Required Parameter Group the network server. Then you may use the returned network
Receiver variable server category to select one of the other (category-specific)
OUTPUT; CHAR(*) formats to call the API again for detailed information about
the network server description. This format also returns the
The variable that is to receive the network server infor-
number of lines that are currently attached to this network
mation.
server.
Length of receiver variable
INPUT; BINARY(4) Offset

The length of the area that is referred to by the receiver Dec Hex Type Field
variable parameter. If the amount of information to be 0 0 BINARY(4) Bytes returned
returned is greater than this value, the information will be
4 4 BINARY(4) Bytes available
truncated to this length.
8 8 BINARY(4) Offset to higher-level
Format name format
INPUT; CHAR(8) 12 C CHAR(10) Number of attached non-
The content and format of the information that is switched lines
returned for each network server. The possible format 22 16 CHAR(7) Date information retrieved
names are:
29 1D CHAR(6) Time information retrieved
NWSD0100 Basic network server information 35 23 CHAR(8) Network server name
NWSD0200 Detailed information for network server
43 2B CHAR(10) Online at IPL
category *LANSERVER
NWSD0300 Detailed information for network server 53 35 CHAR(50) Text description
category *NETWARE 103 67 CHAR(1) Network server type
NWSD0400 Detailed information for network server
category *BASE
NWSD0200 Format: This format returns detailed informa-
NWSD0500 Detailed information for network server
tion about a network server of category *LANSERVER.
category *AIX
NWSD0600 Detailed information for network server
Offset
category *WINDOWSNT
Dec Hex Type Field
See “Format of Network Server Information” for a
0 0 Returns everything from
description of these formats.
format NWSD0100

16-70 AS/400 System API Reference V4R4

 Retrieve Network Server Description (QDCRNWSD)

Offset Offset
Dec Hex Type Field Dec Hex Type Field
104 68 BINARY(4) Offset to attached non- These fields CHAR(10) Attached nonswitched line
switched lines repeat for
CHAR(10) Line category
each non-
108 6C BINARY(4) Number of attached non-
switched line CHAR(10) Port number
switched lines
CHAR(50) Line text description
112 70 BINARY(4) Entry length of attached
nonswitched line These fields CHAR(10) Storage space size
repeat for
116 74 BINARY(4) Offset to storage spaces CHAR(10) Storage space name
each network
120 78 BINARY(4) Number of storage storage list CHAR(1) Drive letter
spaces
CHAR(50) Storage space text
124 7C BINARY(4) Entry length of storage description
spaces
These fields CHAR(10) TCP/IP port number
128 80 CHAR(10) Vary on wait repeat for
CHAR(15) Internet address
each TCP/IP
138 8A CHAR(4) Language version
port configura- CHAR(1) Reserved
142 8E CHAR(10) Country code tion
CHAR(15) Subnet mask
152 98 CHAR(10) Code page
CHAR(1) Reserved
162 A2 CHAR(10) Resource name
BINARY(4) MTU for port
172 AC CHAR(10) Reserved
These fields CHAR(15) Route destination
182 B6 CHAR(10) Domain role repeat for
CHAR(1) Reserved
each TCP/IP
192 C0 CHAR(10) Group profile
route entry CHAR(15) Route subnet mask
202 CA CHAR(10) NetBios description
CHAR(1) Reserved
212 D4 CHAR(2) Reserved
CHAR(15) Next hop
214 D6 CHAR(10) Configuration file name
CHAR(1) Reserved
224 E0 CHAR(10) Configuration file library
These fields CHAR(15) TCP/IP name server
name
repeat for
CHAR(1) Reserved
234 EA CHAR(10) Start TCP/IP each TCP/IP
name server
244 F4 BINARY(4) Offset to list of TCP/IP
port configurations
248 F8 BINARY(4) Length of TCP/IP port NWSD0300 Format: This format returns detailed informa-
configuration entries tion about a network server of category *NETWARE.
252 FC BINARY(4) Number of TCP/IP port
configurations Offset

256 100 BINARY(4) Offset to list of TCP/IP Dec Hex Type Field
route entries 0 0 Returns everything from
260 104 BINARY(4) Length of TCP/IP route format NWSD0100
entries 104 68 BINARY(4) Offset to attached non-
264 108 BINARY(4) Number of TCP/IP route switched lines
entries 108 6C BINARY(4) Number of attached non-
268 10C BINARY(4) Offset to list of TCP/IP switched lines
name server entries 112 70 BINARY(4) Entry length of attached
272 110 BINARY(4) Length of TCP/IP name nonswitched line
server entries 116 74 BINARY(4) Offset to storage spaces
276 114 BINARY(4) Number of TCP/IP name 120 78 BINARY(4) Number of storage
server entries spaces
280 118 CHAR(63) TCP/IP host name 124 7C BINARY(4) Entry length of storage
343 157 CHAR(1) Reserved space

344 158 CHAR(255) TCP/IP domain name 128 80 CHAR(10) Vary on wait

599 257 CHAR(1) Reserved 138 8A CHAR(4) Language version

142 8E CHAR(10) Country code

Chapter 16. Configuration APIs 16-71

Retrieve Network Server Description (QDCRNWSD)

Offset Offset
Dec Hex Type Field Dec Hex Type Field
152 98 CHAR(10) Code page 124 7C BINARY(4) Entry length of storage
spaces
162 A2 CHAR(10) Resource name
128 80 CHAR(10) Vary on wait
172 AC CHAR(10) IPX description
138 8A CHAR(4) Language version
182 B6 CHAR(10) Local IPX connection
142 8E CHAR(10) Country code
192 C0 CHAR(10) Configuration file name
152 98 CHAR(10) Code page
202 CA CHAR(10) Configuration file library
name 162 A2 CHAR(10) Resource name
212 D4 CHAR(10) Message queue name 172 AC CHAR(10) NetBios description
222 DE CHAR(10) Message queue library 182 B6 CHAR(10) Configuration file name
name
192 C0 CHAR(10) Configuration file library
232 E8 CHAR(10) Synchronize date and name
time
202 CA CHAR(10) Start NetBios
242 F2 BINARY(4) Offset to list of restricted
212 D4 CHAR(10) Start TCP/IP
device resources
222 DE CHAR(2) Reserved
246 F6 BINARY(4) Length of restricted
device resource 224 E0 BINARY(4) Offset to list of TCP/IP
port configurations
250 FA BINARY(4) Number of restricted
device resource entries 228 E4 BINARY(4) Length of TCP/IP port
configuration entries
These fields CHAR(10) Attached nonswitched line
repeat for 232 E8 BINARY(4) Number of TCP/IP port
CHAR(10) Line category
each non- configurations
switched line CHAR(10) Port number
236 EC BINARY(4) Offset to list of TCP/IP
CHAR(10) Line text description route entries
These fields CHAR(10) Storage space size 240 F0 BINARY(4) Length of TCP/IP route
repeat for entries
CHAR(10) Storage space name
each network
244 F4 BINARY(4) Number of TCP/IP route
storage list CHAR(1) Drive letter
entries
CHAR(50) Storage space text
248 F8 BINARY(4) Offset to list of TCP/IP
description
name server entries
This field CHAR(10) Restricted device
252 FC BINARY(4) Length of TCP/IP name
repeats for resource
server entries
each restricted
CHAR(2) Reserved
device 256 100 BINARY(4) Number of TCP/IP name
resource server entries
260 104 CHAR(63) TCP/IP host name
NWSD0400 Format: This format returns detailed informa- 323 143 CHAR(1) Reserved
tion about a network server of category *BASE.
324 144 CHAR(255) TCP/IP domain name

Offset 579 243 CHAR(1) Reserved

Dec Hex Type Field 580 244 CHAR(10) Message queue name

0 0 Returns everything from 590 24E CHAR(10) Message queue library

format NWSD0100 name

104 68 BINARY(4) Offset to attached non- 600 258 CHAR(10) Synchronize date and
switched lines time

108 6C BINARY(4) Number of attached non- These fields CHAR(10) Attached nonswitched line
switched lines repeat for
CHAR(10) Line category
each non-
112 70 BINARY(4) Entry length of attached switched line CHAR(10) Port number
nonswitched lines
CHAR(10) Line text description
116 74 BINARY(4) Offset to storage spaces
120 78 BINARY(4) Number of storage
spaces

16-72 AS/400 System API Reference V4R4

 Retrieve Network Server Description (QDCRNWSD)

Offset Offset
Dec Hex Type Field Dec Hex Type Field
These fields CHAR(10) Storage space size 178 B2 CHAR(10) Synchronize date and
repeat for time
CHAR(10) Storage space name
each network
188 BC CHAR(4) Reserved
storage list CHAR(1) Drive letter
192 C0 BINARY(4) Offset to list of TCP/IP
CHAR(50) Storage space text
port configurations
description
196 C4 BINARY(4) Length of TCP/IP port
These fields CHAR(10) TCP/IP port number
configuration entries
repeat for
CHAR(15) Internet address
each TCP/IP 200 C8 BINARY(4) Number of TCP/IP port
port configura- CHAR(1) Reserved configurations
tion
CHAR(15) Subnet mask 204 CC CHAR(63) TCP/IP host name
CHAR(1) Reserved 267 10B CHAR(1) Reserved
BINARY(4) MTU for port 268 10C CHAR(10) Message queue name
These fields CHAR(15) Route destination 278 116 CHAR(10) Message queue library
repeat for name
CHAR(1) Reserved
each TCP/IP
288 120 BINARY(4) Default CCSID
route entry CHAR(15) Route subnet mask
292 124 CHAR(15) AIX version
CHAR(1) Reserved
307 133 CHAR(5) Default locale
CHAR(15) Next hop
These fields CHAR(10) Attached nonswitched line
CHAR(1) Reserved
repeat for
CHAR(10) Line category
These fields CHAR(15) TCP/IP name server each non-
repeat for switched line CHAR(10) Port number
CHAR(1) Reserved
each TCP/IP
CHAR(10) Line text description
name server
These fields CHAR(10) Storage space size
repeat for
NWSD0500 Format: This format returns detailed informa- CHAR(10) Storage space name
each network
tion about a network server of category *AIX. storage list CHAR(1) Reserved
| Note: Format NWSD0500 is no longer supported. CHAR(50) Storage space text
description
Offset CHAR(3) Drive number
Dec Hex Type Field CHAR(8) Physical volume name
0 0 Returns everything from CHAR(15) Volume group name
format NWSD0100
CHAR(14) Level identifier
104 68 BINARY(4) Offset to attached non-
switched lines CHAR(1) Remove link allowed

108 6C BINARY(4) Number of attached non- CHAR(1) Reserved

switched lines These fields CHAR(10) TCP/IP port number
112 70 BINARY(4) Entry length of attached repeat for
CHAR(15) Internet address
nonswitched lines each TCP/IP
port configura- CHAR(1) Reserved
116 74 BINARY(4) Offset to storage spaces tion
CHAR(15) Subnet mask
120 78 BINARY(4) Number of storage
CHAR(1) Reserved
spaces
BINARY(4) MTU for port
124 7C BINARY(4) Entry length of storage
spaces
128 80 CHAR(10) Vary on wait NWSD0600 Format: This format returns detailed informa-
tion about a network server of category *WINDOWSNT.
138 8A CHAR(10) Resource name
148 94 CHAR(10) Console buffer size Offset
158 9E CHAR(10) Delete server users Dec Hex Type Field
168 A8 CHAR(10) Set password rules 0 0 Returns everything from
format NWSD0100

Chapter 16. Configuration APIs 16-73

Retrieve Network Server Description (QDCRNWSD)

Offset Offset
Dec Hex Type Field Dec Hex Type Field
104 68 BINARY(4) Offset to attached non- 576 240 BINARY(4) Number of restricted
switched lines device resource entries
108 6C BINARY(4) Number of attached non- 580 244 BINARY(4) Offset to list of event logs
switched lines
584 248 BINARY(4) Length of event log
112 70 BINARY(4) Entry length of attached
588 24C BINARY(4) Number of event log
nonswitched lines
entries
116 74 BINARY(4) Offset to storage spaces
| 592 250 CHAR(10) Configuration file name
120 78 BINARY(4) Number of storage
| 602 25A CHAR(10) Configuration file library
spaces
| name
124 7C BINARY(4) Entry length of storage
These fields CHAR(10) Attached nonswitched line
spaces
repeat for
CHAR(10) Line category
128 80 CHAR(10) Vary on wait each non-
switched line CHAR(10) Port number
138 8A CHAR(10) Resource name
CHAR(10) Line text description
148 94 CHAR(10) Domain role
These fields CHAR(10) Storage space size
158 9E CHAR(4) Language version
repeat for
CHAR(10) Storage space name
162 A2 CHAR(10) Country code each network
storage list CHAR(1) Drive letter
172 AC CHAR(10) Code page
CHAR(50) Storage space text
182 B6 CHAR(10) Message queue name
description
192 C0 CHAR(10) Message queue library
CHAR(3) Drive number
name
These fields CHAR(10) TCP/IP port number
202 CA CHAR(10) Synchronize date and
repeat for
time CHAR(15) Internet address
each TCP/IP
212 D4 BINARY(4) Offset to list of TCP/IP port configura- CHAR(1) Reserved
port configurations tion
CHAR(15) Subnet mask
216 D8 BINARY(4) Length of TCP/IP port
CHAR(1) Reserved
configuration entries
BINARY(4) MTU for port
220 DC BINARY(4) Number of TCP/IP port
configurations These fields CHAR(15) Route destination
repeat for
224 E0 BINARY(4) Offset to list of TCP/IP CHAR(1) Reserved
each TCP/IP
route entries CHAR(15) Route subnet mask
route entry
228 E4 BINARY(4) Length of TCP/IP route CHAR(1) Reserved
entries
CHAR(15) Next hop
232 E8 BINARY(4) Number of TCP/IP route
entries CHAR(1) Reserved

236 EC BINARY(4) Offset to list of TCP/IP These fields CHAR(15) TCP/IP name server
name server entries repeat for
CHAR(1) Reserved
each TCP/IP
240 F0 BINARY(4) Length of TCP/IP name name server
server entries
This field CHAR(10) Restricted device
244 F4 BINARY(4) Number of TCP/IP name repeats for resource
server entries each restricted
CHAR(2) Reserved
248 F8 CHAR(63) TCP/IP host name device
resource
311 137 CHAR(1) Reserved
This field CHAR(10) Event log
312 138 CHAR(255) TCP/IP domain name
repeats for
CHAR(2) Reserved
567 237 CHAR(1) Reserved each event log
568 238 BINARY(4) Offset to list of restricted
device resources
572 23C BINARY(4) Length of restricted
device resource

16-74 AS/400 System API Reference V4R4

 Retrieve Network Server Description (QDCRNWSD)

Field Descriptions This information is updated when the network server is

varied off or when the AIX update400 command is run.
Fields in the various formats returned by this API are
described in the online command help for communications Delete server users (DLTSVRUSR). Whether the AS/400
line parameters. system will delete user identities that were created on the
network server by using the network server interfaces.
In certain cases, numeric values are assigned by this API to
represent character values for some of the returned fields. Domain role (DMNROLE). The domain controller role that
Where a numeric value is assigned, the numeric value and is performed by this network server.
the equivalent character value are listed as an Exception in
Drive letter. The drive that is associated with this storage
the following field descriptions.
space for the network server.
AIX version. The version of AIX that is installed on the
Drive number. The number assigned to a drive.
storage space linked to the network server.
Entry length of attached nonswitched lines. The entry
Attached nonswitched line. The name of a line that is
length in bytes of each element in the list of attached non-
associated with this network server.
switched lines returned with this format. A value of zero is
Bytes available. The number of bytes of data available to returned if the list is empty.
be returned to the user.
Entry length of storage spaces. The entry length in bytes
Bytes returned. The number of bytes that were returned to of each element in the list of storage spaces.
the user. This is the lesser of the number of bytes available
Event log (EVTLOG). The event log messages that are
to be returned or the length of the receiver variable.
received from the server. This field contains the following
Code page (CODEPAGE). The ASCII code page that repre- values:
sents the character set to be used by this network server. *SYS The system event log messages are received.
*SEC The security event log messages are
Configuration file name (CFGFILE). The name of the received.
source file that contains configuration data to be used in acti- *APP The application event log messages are
vating or further defining the server. received.
Configuration file library name. The name of the library Group profile (GRPPRF). The AS/400 users that are
that contains configuration data to be used in activating or authorized to log on to this network server.
further defining the server.
Internet address. The internet address assigned to each
Console buffer size (CSLBUFSIZ). The maximum number port.
of bytes to use for the AIX console message buffer.
IPX description(IPX). The name of the IPX description.
Country code (CNTRYCODE). The country code that repre-
sents the character set to be used by this network server. Language version(LNGVER). The language version of the
| The country code controls the format of dates. This field will network server product.
| be set to blanks when TYPE is *WINDOWSNT.
Length of event log. The length in bytes of each element in
Date information retrieved. The date that the information the list of event logs.
was provided by the API. It is returned as 7 characters in
the form CYYMMDD, as follows: Length of restricted device resource. The length in bytes
of each element in the list of restricted device resources.
C Century, where 0 indicates years 19xx and 1
indicates years 20xx. Length of TCP/IP name server entries. The length in bytes
YY Year of each element in the list of TCP/IP name servers.
MM Month
DD Day Length of TCP/IP port configuration entries. The length in
bytes of each element in the list of TCP/IP port configuration
Default CCSID. The default coded character set identifier entries.
(CCSID) of AIX that is installed in the storage space linked to
the network server. This information is updated when the Length of TCP/IP route entries. The length in bytes of
network server is varied off or when the AIX update400 | each element in the list of TCP/IP route entries. A value of
command is run. | zero is returned if the list is empty.

Default locale. The default locale of the network server. A Level identifier. The identifier assigned by the AS/400
locale is made up of the language, territory, and code set system to every storage space within a particular AIX volume
combination used to identify a set of language conventions. group.

Chapter 16. Configuration APIs 16-75

 Retrieve Network Server Description (QDCRNWSD)

Line category. This value will be one of the following: Number of TCP/IP route entries. The number of elements
| in the list of TCP/IP route entries. A value of zero is returned
*ETH Ethernet
| if the list is empty.
*TRN Token Ring Network
Offset to list of event logs. The offset in bytes to the first
The category value is derived from the command that is used
element in the list of event logs.
to create the line description.
Offset to higher-level format. The offset in bytes to the
Line name. The name of the line description.
network server specific information.
Line text description. A brief description of the line.
Offset to attached nonswitched lines. The offset in bytes
Local IPX connection (LCLIPXCNN). Whether a con- to the first element in the list of attached nonswitched lines
nection is to be made to local AS/400 IPX at the time that that are returned with this format. A value of zero is returned
this network server is varied on. if the list is empty.

Message queue name (MSGQ). The name of the message Offset to list of restricted device resources. The offset in
queue to receive the server console messages. bytes to the first element in the list of restricted device
resources.
Message queue library name. The name of the message
queue library to receive the server console messages. Offset to storage spaces. The offset in bytes to the first
element in the list of storage spaces.
MTU for port. The maximum transmission unit (MTU) value
specifies the maximum value in bytes that can be transmitted Offset to list of TCP/IP name server entries. The offset in
over the TCP/IP interface. bytes to the first element in the list of TCP/IP name server
entries.
NetBios description (NTB). The name of the NetBios
description. Offset to list of TCP/IP port configurations. The offset in
bytes to the first element in the list of TCP/IP port configura-
Network server name (NWSD). The name of the network tions.
server description.
Offset to list of TCP/IP route entries. The offset in bytes
Network server type (TYPE). The types of network server | to the first element in the list of TCP/IP route entries. A
descriptions. Possible values follow: | value of zero is returned if the list is empty.
| '82'X *BASE - used for Integrated NetFinity Server Online at IPL (ONLINE). Whether or not the line is varied
| for AS/400 on automatically when the system is turned on. (See the
'80'X *LANSERVER - used for OS/2 Warp Server ONLINE keyword in the online command help.)
'81'X *NETWARE - used for Netware
'84'X *WINDOWSNT - used for Windows NT Server Physical volume name. The physical volume name of the
storage space as it is defined on the network server. The
Next hop. The internet address of the next system physical volume name is the name that the AIX operating
(gateway) on the route. system assigns to a network server storage space when it is
defined to the system.
Number of attached nonswitched lines. The number of
elements in the list of attached nonswitched lines that are Port number (PORTS). The port number on the network
returned with this format. A value of zero is returned if the server to which a line is physically attached.
list is empty.
Exceptions:
Number of event log entries. The number of elements in
the list of event logs. Ÿ Value of -28 implies *INTERNAL

Number of restricted device resource entries. The Remove link allowed. Whether this storage space can be
number of elements in the list of restricted device resources. unlinked using the Remove Server Storage Link
(RMVNWSSTGL) command while this network server
Number of storage spaces. The number of elements in the description is varied on.
list of storage spaces.
Reserved. An ignored field.
Number of TCP/IP name server entries. The number of
elements in the list of TCP/IP name server entries. Resource name (RSRCNAME). The unique name that is
assigned by the system to the physical equipment (in this
Number of TCP/IP port configurations. The number of case, a communications port) attached to the system. (See
elements in the list of TCP/IP port configurations. the RSRCNAME keyword in the online command help.)

16-76 AS/400 System API Reference V4R4

 Retrieve Network Server Description (QDCRNWSD)

| Restricted device resource (RSTDDEVRSC). The TCP/IP port number. The TCP/IP port number on the
| restricted device resource name that cannot be used from network server.
| the AS/400 by the network server.
TCP/IP route (TCPRTE). The TCP/IP route identifies routes
Route destination. The internet address of the remote from the network server to remote systems. The route con-
system. sists of three parts that include the route destination, the
subnet mask, and the next hop interface.
Route subnet mask. The subnet mask being used with the
route. The mask is in the form, nnn.nnn.nnn.nnn, where nnn Text description (TEXT). A brief description of the network
is a decimal number that ranges from 0 through 255. server and its location. (See the TEXT keyword in the online
command help.)
Set password rules (SETPWDRULE). Whether the default
rules for passwords on the network server are set to the Time information retrieved. The time that the information
AS/400 system value and defaults or are allowed to use the was provided by the API. It is returned as 6 characters in
default rules for passwords of the network server. the form HHMMSS, where:

Start NetBios (STRNTB). Whether or not the NetBios pro-

HH Hour
tocol is activated when the network server is varied on.
MM Minute
SS Second
Start TCPIP (STRTCP). Whether or not the TCP/IP protocol
Vary on wait (VRYWAIT). Whether the line is varied on
is activated when the network server is varied on.
synchronously or asynchronously. (See the VRYWAIT
Storage space name. The text that is entered to describe keyword in the online command help.)
the storage space.
Exception:
Storage space size. The size that is associated with this Ÿ Value of -15 implies *NOWAIT
storage space for the network server.
Volume group name. The volume group to which this
Storage space text description. The names of existing network server storage space is assigned on the network
client storage spaces. server. A volume group is a collection of one or more phys-
ical volumes. Every physical volume must be assigned to a
Subnet mask. The subnet mask that is assigned to each
volume group before it can be used.
internet address. The mask is in the form, nnn.nnn.nnn.nnn,
where nnn is a decimal number that ranges from 0 through
255. Error Messages
CPF24B4 E Severe error while addressing parameter list.
Synchronize date and time (SYNCTIME). Whether the
CPF2625 E Not able to allocate object &1.
AS/400 has synchronized the network server date and time
CPF2634 E Not authorized to object &1.
with the AS/400 system date and time.
CPF26AE E
TCP/IP host name (TCPHOSTNAM). The short form of the Network server description &1 not found.
host name to be associated with the network server. CPF2704 E Line description &1 not found.
CPF3C19 E
TCP/IP domain name (TCPDMNNAME). The local domain Error occurred with receiver variable specified.
name that is associated with the network server. CPF3C21 E
Format name &1 is not valid.
TCP/IP name server (TCPNAMSVR). The internet address CPF3C24 E
of the name server system that is used by the network Length of the receiver variable is not valid.
server. CPF3C90 E
Literal value cannot be changed.
TCP/IP port configuration (TCPPORTCFG). The TCP/IP CPF3CF1 E
configuration values specific to a port on a network server. Error code parameter not valid.
The information consists of four parts that include the CPF8125 E Line description &4 damaged.
network server port, the internet address assigned to the CPF814C E
port, the subnet mask of the port, and the maximum trans- Network server description &4 damaged.
mission unit. CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.

Chapter 16. Configuration APIs 16-77

Retrieve Network Server Description (QDCRNWSD)

16-78 AS/400 System API Reference V4R4

 Debugger

Part 7. Debugger APIs

Chapter 17. Debugger APIs . . . . . . . . . . . . 17-1 Required Parameter . . . . . . . . . . . . . . . . 17-18

Debugger APIs—Introduction . . . . . . . . . . . . . 17-1 Error Messages . . . . . . . . . . . . . . . . . . 17-18
Source Debugger APIs—Introduction . . . . . . . . 17-1 End View Creation (QteEndViewCreation) API . . . 17-18
How a Source Debugger Uses the APIs to Debug Authorities . . . . . . . . . . . . . . . . . . . . . 17-18
ILE or OPM Programs . . . . . . . . . . . . . . 17-1 Required Parameter . . . . . . . . . . . . . . . . 17-18
Source Debugger APIs and Exit Error Messages . . . . . . . . . . . . . . . . . . 17-18
Programs—Introduction . . . . . . . . . . . . . . . 17-2 Map View Position (QteMapViewPosition) API . . . . 17-18
Create View APIs—Introduction . . . . . . . . . . . 17-3 Required Parameter Group . . . . . . . . . . . . 17-19
Add Breakpoint (QteAddBreakpoint) API . . . . . . . 17-4 Format of Receiver Variable . . . . . . . . . . 17-19
Required Parameter Group . . . . . . . . . . . . 17-4 Field Descriptions . . . . . . . . . . . . . . . . . 17-19
Error Messages . . . . . . . . . . . . . . . . . . 17-4 Error Messages . . . . . . . . . . . . . . . . . . 17-19
Add View Description (QteAddViewDescription) API . 17-4 Register Debug View (QteRegisterDebugView) API . 17-20
Required Parameter Group . . . . . . . . . . . . 17-5 Authorities . . . . . . . . . . . . . . . . . . . . . 17-20
Error Messages . . . . . . . . . . . . . . . . . . 17-6 Required Parameter Group . . . . . . . . . . . . 17-20
Add View File (QteAddViewFile) API . . . . . . . . . 17-6 Format of JAVA Returned Library Parameter . . . 17-21
Required Parameter Group . . . . . . . . . . . . 17-6 Field Descriptions . . . . . . . . . . . . . . . . . 17-21
FILA0100 Format . . . . . . . . . . . . . . . . . 17-7 Error Messages . . . . . . . . . . . . . . . . . . 17-22
FILA0200 Format . . . . . . . . . . . . . . . . . 17-7 Remove All Breakpoints (QteRemoveAllBreakpoints)
Field Descriptions . . . . . . . . . . . . . . . . . 17-7 API . . . . . . . . . . . . . . . . . . . . . . . . . 17-22
Error Messages . . . . . . . . . . . . . . . . . . 17-7 Required Parameter Group . . . . . . . . . . . . 17-22
Add View Map (QteAddViewMap) API . . . . . . . . 17-8 Error Messages . . . . . . . . . . . . . . . . . . 17-22
Required Parameter Group . . . . . . . . . . . . 17-8 Remove Breakpoint (QteRemoveBreakpoint) API . . 17-22
MAPA0100 Format . . . . . . . . . . . . . . . . 17-9 Required Parameter Group . . . . . . . . . . . . 17-23
Field Descriptions . . . . . . . . . . . . . . . . . 17-9 Error Messages . . . . . . . . . . . . . . . . . . 17-23
Error Messages . . . . . . . . . . . . . . . . . . 17-9 Remove Debug View (QteRemoveDebugView) API . 17-23
Add View Text (QteAddViewText) API . . . . . . . . 17-10 Required Parameter Group . . . . . . . . . . . . 17-23
Required Parameter Group . . . . . . . . . . . . 17-10 Error Messages . . . . . . . . . . . . . . . . . . 17-23
TXTA0100 Format . . . . . . . . . . . . . . . 17-11 Retrieve Debug Attribute (QteRetrieveDebugAttribute)
TXTA0101 Format . . . . . . . . . . . . . . . 17-11 API . . . . . . . . . . . . . . . . . . . . . . . . . 17-23
TXTA0102 Format . . . . . . . . . . . . . . . 17-11 Required Parameter Group . . . . . . . . . . . . 17-24
| TXTA0103 Format . . . . . . . . . . . . . . . 17-11 Error Messages . . . . . . . . . . . . . . . . . . 17-24
Field Descriptions . . . . . . . . . . . . . . . . . 17-11 Retrieve Debugged Threads
Error Messages . . . . . . . . . . . . . . . . . . 17-12 (QteRetrieveDebuggedThreads) API . . . . . . . . 17-24
Change Current Thread (QteChangeCurrentThread) Authorities and Locks . . . . . . . . . . . . . . . 17-25
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-12 Required Parameter Group . . . . . . . . . . . . 17-25
Required Parameter Group . . . . . . . . . . . . 17-12 Format of Receiver Variable . . . . . . . . . . . 17-25
Error Messages . . . . . . . . . . . . . . . . . . 17-12 THDL0100 Format . . . . . . . . . . . . . . . 17-25
Change Thread Status (QteChangeThreadStatus) API 17-13 THDL0200 Format . . . . . . . . . . . . . . . 17-25
Authorities and Locks . . . . . . . . . . . . . . . 17-13 Field Descriptions . . . . . . . . . . . . . . . . . 17-26
Required Parameter Group . . . . . . . . . . . . 17-13 Error Messages . . . . . . . . . . . . . . . . . . 17-26
Error Messages . . . . . . . . . . . . . . . . . . 17-13 Retrieve Module Views (QteRetrieveModuleViews)
Dump Module Variables (QteDumpModuleVariables) API . . . . . . . . . . . . . . . . . . . . . . . . . 17-27
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-13 Authorities . . . . . . . . . . . . . . . . . . . . . 17-27
Required Parameter Group . . . . . . . . . . . . 17-14 Required Parameter Group . . . . . . . . . . . . 17-27
Format of the Receiver Variable . . . . . . . . . 17-15 VEWL0100 Format . . . . . . . . . . . . . . . . 17-28
Receiver Variable Header Section . . . . . . . 17-15 Field Descriptions . . . . . . . . . . . . . . . . . 17-29
Module Variable Header Section . . . . . . . . 17-15 Format of JAVA Returned Library Name Parameter 17-29
Module Variable Section (Scalar Variable Entry Field Descriptions . . . . . . . . . . . . . . . . . 17-29
Type) . . . . . . . . . . . . . . . . . . . . . 17-15 Error Messages . . . . . . . . . . . . . . . . . . 17-30
Module Variable Section (Array Definition Entry Retrieve Program Variable (QTERTVPV) API . . . . 17-30
Type) . . . . . . . . . . . . . . . . . . . . . 17-16 Restriction . . . . . . . . . . . . . . . . . . . 17-30
Module Variable Section (Block Definition Entry Required Parameter Group . . . . . . . . . . . . 17-30
Type) . . . . . . . . . . . . . . . . . . . . . 17-16 Format of Receiver Variable . . . . . . . . . . . 17-31
Field Descriptions . . . . . . . . . . . . . . . . . 17-16 Data for Binary Numeric (1) . . . . . . . . . . 17-31
Error Messages . . . . . . . . . . . . . . . . . . 17-17 Data for Floating Point (2) . . . . . . . . . . . 17-31
End Source Debug (QteEndSourceDebug) API . . . 17-18 Data for Zoned Decimal (3) . . . . . . . . . . 17-32

 Copyright IBM Corp. 1998, 1999

Debugger

Data for Packed Decimal (4) . . . . . . . . . . 17-32 Authorities . . . . . . . . . . . . . . . . . . . . . 17-47

Data for Fixed Character (5) . . . . . . . . . . 17-32 Required Parameter Group . . . . . . . . . . . . 17-47
Data for Varying Character (6) . . . . . . . . . 17-32 Error Messages . . . . . . . . . . . . . . . . . . 17-47
Data for Fixed Bit (7) . . . . . . . . . . . . . . 17-32 Start View Creation (QteStartViewCreation) API . . . 17-47
Data for Unsigned Binary (8) . . . . . . . . . . 17-32 Authorities . . . . . . . . . . . . . . . . . . . . . 17-48
Data for Space Pointer (9) . . . . . . . . . . . 17-32 Required Parameter Group . . . . . . . . . . . . 17-48
Data for Data Pointer (10) . . . . . . . . . . . 17-32 FILA0100 Format . . . . . . . . . . . . . . . . . 17-48
Data for Instruction Definition List (11) . . . . . 17-32 Field Descriptions . . . . . . . . . . . . . . . . . 17-48
Data for System Pointer (12) . . . . . . . . . . 17-32 Error Messages . . . . . . . . . . . . . . . . . . 17-49
Data for Machine Space Pointer (13) . . . . . 17-33 Step (QteStep) API . . . . . . . . . . . . . . . . . . 17-49
Data for Exception Description (14) . . . . . . 17-33 Required Parameter Group . . . . . . . . . . . . 17-49
Field Descriptions . . . . . . . . . . . . . . . . . 17-33 Error Messages . . . . . . . . . . . . . . . . . . 17-49
Error Messages . . . . . . . . . . . . . . . . . . 17-35 Stop Debugged Job (QteStopDebuggedJob) API . . 17-49
Retrieve Statement View (QteRetrieveStatementView) Required Parameter Group . . . . . . . . . . . . 17-50
API . . . . . . . . . . . . . . . . . . . . . . . . . 17-35 Error Messages . . . . . . . . . . . . . . . . . . 17-50
Required Parameter Group . . . . . . . . . . . . 17-35 Submit Debug Command
Format of Receiver Variable . . . . . . . . . . . 17-36 (QteSubmitDebugCommand) API . . . . . . . . . . 17-50
Receiver Variable Header Section . . . . . . . 17-36 Required Parameter Group . . . . . . . . . . . . 17-50
Statement View Section . . . . . . . . . . . . 17-36 Receiver Variable Format . . . . . . . . . . . . . 17-50
Procedure Information Section . . . . . . . . . 17-36 Field Descriptions . . . . . . . . . . . . . . . . . 17-51
Procedure Name String Space . . . . . . . . . 17-36 Description of the Structure of the Receiver
Statement-View-Line Additional-Information Variable . . . . . . . . . . . . . . . . . . . . 17-51
Offsets Section . . . . . . . . . . . . . . . . 17-36 Results Array Entry Structure Summary . . . . . 17-51
Statement-View-Line Additional-Information StepR (1) . . . . . . . . . . . . . . . . . . . . . 17-52
Section . . . . . . . . . . . . . . . . . . . . 17-37 BreakR (2) . . . . . . . . . . . . . . . . . . . . . 17-52
Variable Length Field Section . . . . . . . . . 17-37 ClearBreakpointR (3) . . . . . . . . . . . . . . . 17-52
Field Descriptions . . . . . . . . . . . . . . . . . 17-37 ClearPgmR (4) . . . . . . . . . . . . . . . . . . . 17-52
Error Messages . . . . . . . . . . . . . . . . . . 17-38 BreakPositionR (5) . . . . . . . . . . . . . . . . 17-52
Retrieve Stopped Position EvaluationR (6) . . . . . . . . . . . . . . . . . . 17-52
(QteRetrieveStoppedPosition) API . . . . . . . . . 17-38 ExpressionTextR (7) . . . . . . . . . . . . . . . . 17-52
Required Parameter Group . . . . . . . . . . . . 17-38 ExpressionValueR (8) . . . . . . . . . . . . . . . 17-52
Format of Receiver Variable . . . . . . . . . . . 17-39 ExpressionTypeR (9) . . . . . . . . . . . . . . . 17-53
Field Descriptions . . . . . . . . . . . . . . . . . 17-39 QualifyR (10) . . . . . . . . . . . . . . . . . . . 17-53
Error Messages . . . . . . . . . . . . . . . . . . 17-39 TypeR (11) . . . . . . . . . . . . . . . . . . . . 17-53
Retrieve View File (QteRetrieveViewFile) API . . . . 17-39 TypeDescR (12) . . . . . . . . . . . . . . . . . . 17-53
Required Parameter Group . . . . . . . . . . . . 17-40 DecimalR (13) . . . . . . . . . . . . . . . . . . . 17-53
Format of Text Descriptor Receiver Variable . . . 17-40 ArrayR (14) . . . . . . . . . . . . . . . . . . . . 17-53
Format of File Name Receiver Variable . . . . . . 17-40 DimensionR (15) . . . . . . . . . . . . . . . . . . 17-53
Field Descriptions . . . . . . . . . . . . . . . . . 17-41 WatchR (16) . . . . . . . . . . . . . . . . . . . . 17-53
Formats of File Format Name . . . . . . . . . . . 17-41 WatchNumberR (17) . . . . . . . . . . . . . . . . 17-53
RTVF0100 Format . . . . . . . . . . . . . . . 17-41 ClearWatchNumberR (18) . . . . . . . . . . . . . 17-54
Field Descriptions . . . . . . . . . . . . . . . . . 17-41 ClearWatchR (19) . . . . . . . . . . . . . . . . . 17-54
RTVF0200 Format . . . . . . . . . . . . . . . 17-41 TBreakR (20) . . . . . . . . . . . . . . . . . . . 17-54
Field Description . . . . . . . . . . . . . . . . . . 17-41 Field Descriptions . . . . . . . . . . . . . . . . . 17-54
Error Messages . . . . . . . . . . . . . . . . . . 17-41 Statement Results . . . . . . . . . . . . . . . . . 17-55
Retrieve View Line Information Examples of Result Records Returned by Submit
(QteRetrieveViewLineInformation) API . . . . . . . 17-42 Debug Command API . . . . . . . . . . . . . . 17-56
Required Parameter Group . . . . . . . . . . . . 17-42 Break Statement Example . . . . . . . . . . . 17-56
RTVL0100 Format . . . . . . . . . . . . . . . . . 17-42 Scalar Evaluate Statement Example . . . . . . 17-56
Field Descriptions . . . . . . . . . . . . . . . . . 17-43 Scalar Evaluate Statement Example . . . . . . 17-57
Error Messages . . . . . . . . . . . . . . . . . . 17-43 Structure Evaluate Statement Example . . . . 17-57
Retrieve View Text (QteRetrieveViewText) API . . . 17-43 Step Statement Example . . . . . . . . . . . . 17-58
Required Parameter Group . . . . . . . . . . . . 17-43 ATTR Statement Example . . . . . . . . . . . 17-58
Format of Receiver Variable . . . . . . . . . . . 17-44 WATCH Statement Example . . . . . . . . . . 17-58
Field Descriptions . . . . . . . . . . . . . . . . . 17-44 Error Messages . . . . . . . . . . . . . . . . . . 17-59
Error Messages . . . . . . . . . . . . . . . . . . 17-45 Debug Language Statements . . . . . . . . . . . 17-60
Set Debug Attribute (QteSetDebugAttribute) API . . 17-45 ATTR Statement . . . . . . . . . . . . . . . . . . 17-60
Required Parameter Group . . . . . . . . . . . . 17-46 Break Statement . . . . . . . . . . . . . . . . . . 17-60
Error Messages . . . . . . . . . . . . . . . . . . 17-46 Clear Statement . . . . . . . . . . . . . . . . . . 17-61
Start Source Debug (QteStartSourceDebug) API . . 17-46 Evaluate Statement . . . . . . . . . . . . . . . . 17-61

AS/400 System API Reference V4R4

 Debugger

Locality . . . . . . . . . . . . . . . . . . . . . 17-62 Required Parameter Group . . . . . . . . . . . . 17-66

Qualify Statement . . . . . . . . . . . . . . . . . 17-62 Format of Watch-Program Stop Reason for
Step Statement . . . . . . . . . . . . . . . . . . 17-63 Receiver Variable . . . . . . . . . . . . . . . . 17-67
TBreak Statement . . . . . . . . . . . . . . . . . 17-63 Watch Receiver Variable Header . . . . . . . 17-67
Watch Statement . . . . . . . . . . . . . . . . . 17-63 Watch Stopped Program Information . . . . . 17-67
Debug Session Handler Exit Program . . . . . . . . 17-64 Watch Interrupt Information . . . . . . . . . . 17-67
Required Parameter Group . . . . . . . . . . . . 17-64 Field Descriptions . . . . . . . . . . . . . . . . . 17-68
Format of *STARTJAVA Program List Parameter 17-65 Format of Message Data . . . . . . . . . . . . 17-68
Field Descriptions . . . . . . . . . . . . . . . . . 17-65 Field Descriptions . . . . . . . . . . . . . . . . . 17-69
Program-Stop Handler Exit Program . . . . . . . . . 17-65

Part 7. Debugger APIs

Debugger

AS/400 System API Reference V4R4

 Source Debugger APIs—Introduction

Chapter 17. Debugger APIs

used at the same time in another job without being affected
Debugger APIs—Introduction by the debugger functions set up.
The debugger APIs can be used for program debugging on
the AS/400 system. These APIs are divided into separate How a Source Debugger Uses the APIs to
sets of APIs, as follows: Debug ILE or OPM Programs
Ÿ Integrated Language Environment (ILE) APIs
The Start Debug command has a parameter, SRCDBGPGM,
– Source debugger APIs that specifies which program is called when an ILE or OPM
– Create view APIs program is debugged. The system calls this program, indi-
cating that the debug session is to begin. It also calls this
– Dump Module Variable API
program when the user wants to show the Display Module
Ÿ Original program model (OPM) APIs Source display. When OPM programs are to be debugged,
– Retrieve Program Variable API the additional OPMSRC(*YES) parameter must be specified
on the Start Debug command.
– Source debugger APIs
When the system calls the source debugger program, indi-
The debugger API user can use these sets of APIs inde- cating the start of a debug session, that program uses
pendently of each other or together as needed. Each of source debugger APIs to perform debug functions. The first
these sets of APIs is described below. Following this are the API that is called is the Start Source Debug
detailed API descriptions presented in alphabetical order. (QteStartSourceDebug) API, which indicates to the system
Note: For general information about the Integrated Lan- that a source debugger is running.
guage Environment, see the ILE Concepts book.
When an ILE program is debugged, the Retrieve Module
Views (QteRetrieveModuleViews) API is used to obtain infor-
mation about the views available in the modules of that
Source Debugger APIs—Introduction
program. For an OPM program, information about the views
The source debugger APIs can be used to write debuggers available for that program is obtained. These views were
for the AS/400 system. The users of these APIs include: previously created by the compiler by using the create view
Ÿ The source debugger that is shipped with the OS/400 APIs for ILE programs. For OPM programs, the views were
licensed program. A source debugger is a tool for created by using OPTION(*SRCDBG) or OPTION(*LSTDBG)
debugging Integrated Language Environment (ILE) pro- on the appropriate OPM language create program command.
grams or original program model (OPM) programs by The OPM CL, COBOL, and RPG languages are supported
displaying a representation of their source code. by the source debugger APIs. A view is text that is dis-
played by the source debugger. A module may have several
Ÿ Any other debugger that IBM or a business partner views, depending on the debug data supplied by the compiler
writes. of that module. OPM programs always have a statement
view, and either a source or listing view, depending on the
Debugger functions are designed to help you write and main-
OPM compiler option selected. See the appropriate lan-
tain your applications. You can run your programs in a
guage reference manual to determine which views are avail-
special testing environment while closely observing and con-
able.
trolling the processing of these programs in the testing envi-
ronment. You can write a debugger application that interacts To be debugged, a module has to have at least one view,
with the APIs provided in this chapter, or you can use the the statement view. A statement view is a low-level view
debugger provided with the AS/400 system. that contains information about each high-level statement in
that module. This view is not meant to be displayed,
No special commands specifically for testing are contained in
although there is text associated with that view. The infor-
the program being tested. The same program being tested
mation in the statement view text can be used by the source
can run normally without changes. All debugger APIs must
debugger to determine the following:
be called within the job in which the Start Debug (STRDBG)
command is issued. The debugger APIs should not be Ÿ Procedure name
called from within the program being tested. With the Ÿ Statement number
debugger APIs provided, you interact with your programs
symbolically in the same terms as the high-level language Ÿ Statement type associated with any high-level language
(HLL) in the program. You refer to variables by their names statement in the module
and to locations as the line and the column within a view. In
The source debugger application uses the Register Debug
addition, the debugger functions are only applicable to the
View (QteRegisterDebugView) API to register the views of a
job in which they are set up. The same program can be

 Copyright IBM Corp. 1998, 1999 17-1

Source Debugger APIs and Exit Programs—Introduction

program. Once these views are registered, various debug Change Thread Status
operations can be performed against these views. These (QteChangeThreadStatus) changes the
operations include: debug status for threads being debugged.
Ÿ Retrieving the text associated with the views
End Source Debug
(QteEndSourceDebug) takes the job out
Ÿ Adding a breakpoint to the program at a certain location of debug mode.
in a view Retrieve Debug Attribute
Ÿ Displaying variables that are defined in the program (QteRetrieveDebugAttribute) retrieves the
attributes of the source debug session.
The source debugger application uses the Retrieve View Retrieve Debugged Threads
Text (QteRetrieveViewText) API to retrieve the text of a view. (QteRetrieveDebuggedThreads) retrieves
Every view has text associated with it that can be retrieved information for threads being debugged.
using the QteRetrieveViewText API. Retrieve Module Views
(QteRetrieveModuleViews) returns to the
When a program is being debugged and it stops at a break- caller the list of modules and views that
point, the system indicates that it has stopped by calling the are associated with a specific ILE or OPM
Program-Stop Handler exit program. This program is passed program.
a line number in the statement view where the program Set Debug Attribute
being debugged has stopped. (QteSetDebugAttribute) sets the attributes
of the source debug session.
The Map View Position (QteMapViewPosition) API is used to
Start Source Debug
map positions in one view to positions in another view. For
(QteStartSourceDebug) enables your
example, if the source debugger is currently displaying a
session to use the source debugger.
source view in a module, and a breakpoint occurs, the
Stop Debugged Job
Program-Stop Handler exit program is called. This program
(QteStopDebuggedJob) causes debug to
is passed a line number in the statement view of that
halt all threads in a job being debugged.
module, which indicates at which statement the program has
Program Stop Handler exit program
stopped. To show the position in the source view where the
is registered on the Start Source Debug
program has stopped, the application maps the statement
API. This program is called by the source
view position to a source view position. This mapping func-
debugger support when an ILE or OPM
tion is made possible by maps, which are created by the ILE
program stops at a breakpoint or for other
compiler using the create view APIs, or by the debug data,
reasons.
which is created by OPM compilers.
Debug Session Handler exit program
manages the source debugger, telling it
When the debug session is over, the source debugger appli-
when to start, stop, and display its
cation issues the End Source Debug (QteEndSourceDebug)
screens. This program is registered on
API, which removes all ILE and OPM programs from debug
the Start Debug Command.
mode. No source debugger APIs can be issued until the
source debug session is ended with the End Debug Ÿ View Information APIs
Command and started again with the Start Debug command.
These APIs retrieve view information, including view text
information and view mapping information, and allow the
program to set parameters associated with a view.
Source Debugger APIs and Exit
Map View Position
Programs—Introduction (QteMapViewPosition) maps positions
from one view to another view within the
The source debugger APIs are divided into the following
same program and module.
functional areas:
Register Debug View
Ÿ Debug Session Control APIs and Exit Programs (QteRegisterDebugView) registers a view
These APIs are used to: of a module, which allows a program to
be debugged in terms of that view.
– Start and end the source debug session Remove Debug View
– Determine which programs, modules, and views are (QteRemoveDebugView) removes a view
referenced of a module that was previously regis-
tered by the Register Debug View API.
– Control certain attributes of the debug environment
This is necessary when a program is to
Change Current Thread be removed from debug mode so it can
(QteChangeCurrentThread) changes the be deleted and recompiled.
current thread to any thread being
debugged.

17-2 AS/400 System API Reference V4R4

 Create View APIs—Introduction

Retrieve Statement View

(QteRetrieveStatementView) returns the Create View APIs—Introduction
statement view and related information.
To enable source-level debugging of ILE programs, view
Retrieve Stopped Position
information must be stored with the compiled program. The
(QteRetrieveStoppedPosition) determines
ILE compilers use the create view APIs to create view infor-
if a program is on the call stack and indi-
mation. This information is then available to source-level
cates the position in the view at which the
debugger applications through the source debugger APIs
program is stopped if it is on the stack.
described above.
Retrieve View File
(QteRetrieveViewFile) returns all the files The first API that is called is the Start View Creation
and text information necessary to con- (QteStartViewCreation) API, which is used to initialize the
struct the text for a view. debug view creation environment.
Retrieve View Line Information
(QteRetrieveViewLineInformation) returns The views being created are described by the Add View
information about the specified number of Description (QteAddViewDescription) API. Examples of
lines in a registered view. views created by a compiler are text views (for example, the
Retrieve View Text input source) and listing views (for example, a compiler
(QteRetrieveViewText) retrieves source output listing). A parameter passed back by this API is the
text from the specified view. view number, which is used by subsequent APIs to identify
Ÿ Debug Command API the view being processed.

Debug commands are a part of the API that takes on The text of a view comes from files (for example, the input
free-form expressions. They are referred to as the source file to the compiler) or supplied text (for example,
debug language that the program may supply to the macro expansion text). The supplied text is stored with the
source debugger support. view information in the program object. The file text is
Submit Debug Command copied at source debugging time when the text is retrieved.
(QteSubmitDebugCommand) allows a Thus, the view information stored for the file text contains ref-
program to issue debug language state- erences to the files containing the text and not the text itself.
ments. Debug language statements The files to be used in a view are described by use of the
permit programs to enter breakpoints, run Add View File (QteAddViewFile) API.
one or more statements of a program
The Add View Text (QteAddViewText) API is used to
being debugged, and evaluate
describe how the text for a view is constructed. The view
expressions.
text can be composed of pieces of text, which are concat-
Ÿ Fast-path Debugger APIs enated together when the text is retrieved, according to the
The APIs allow the caller to bypass the generalized instructions specified through this API.
Debug Command API for some of the simpler but more
The Add View Map (QteAddViewMap) API is used to map
common source debugging functions.
positions in one view to positions in another view. This is
Add Breakpoint necessary to be able to relate positions in one view to equiv-
(QteAddBreakpoint) adds a breakpoint to alent positions in another view. In some cases a map can
the specified location in a registered view. be generated automatically without using this API (see
Remove Breakpoint QteAddViewDescription API). Other maps may need to be
(QteRemoveBreakpoint) removes a supplied to allow certain source debugger functions such as
breakpoint from the specified location in a breakpoint processing, in which the breakpoint parameters
registered view. are supplied by the system in terms of the statement view
Remove All Breakpoints only.
(QteRemoveAllBreakpoints) removes all
breakpoints from all modules in a When the view creation processing is complete, a call to the
program. End View Creation (QteEndViewCreation) API is required.
Step (QteStep) adds a step to a program spec-
ifying that the program will run one or In summary, the view creation APIs are as follows:
more statements after which program pro- Start View Creation
cessing is suspended. (QteStartViewCreation) initializes the view cre-
ation environment.
To use a source debugger API, the application must bind to Add View Description
the service program QTEDBGS in library QSYS. All source (QteAddViewDescription) describes a view to
debugger API functions are then available to the application. be created.
For a coding example of how to write a source debugger,
see “Using Source Debugger APIs” on page A-65.

Chapter 17. Debugger APIs 17-3

Add View Description (QteAddViewDescription) API

Add View File Line in statement view

(QteAddViewFile) describes the files that can OUTPUT; BINARY(4)
be used to construct the text for a view.
The API returns the line number in the statement view
Add View Text
where the breakpoint was added.
(QteAddViewText) describes the pieces of text
making up the view text. Error code
Add View Map I/O; CHAR(*)
(QteAddViewMap) describes how to map posi-
The structure in which to return error information. For
tions in one view to positions in another view.
the format of the structure, see “Error Code Parameter”
End View Creation
on page 2-6.
(QteEndViewCreation) completes view cre-
ation processing.
Error Messages
To use a create view API, the application must bind to the
CPF1938 E Command is not allowed while serviced job is
service program QTECRTVS in QSYS. All create view API
not active.
functions are then available to the application.
CPF1939 E Time-out occurred waiting for a reply from the
serviced job.
CPF1941 E Serviced job has completed. Debug commands
Add Breakpoint (QteAddBreakpoint) API are not allowed.
CPF3CF1 E
Error code parameter not valid.
Required Parameter Group: CPF7102 E Unable to add breakpoint or trace.
CPF9541 E Not in debug mode.
1 View ID Input Binary(4)
2 Line number Input Binary(4) CPF9542 E View not found.
3 Column number Input Binary(4) CPF9549 E Error addressing API parameter.
4 Line in statement view Output Binary(4) CPF9567 E Column number not valid.
5 Error code I/O Char(*) CPF9568 E Line number not valid.

Service Program: QTEDBGS

Threadsafe: No
Add View Description
(QteAddViewDescription) API
The calling program uses the Add Breakpoint
(QteAddBreakpoint) API to add a breakpoint at a location in Required Parameter Group:
a registered view.
1 Previous view number Input Binary(4)
2 View type Input Char(10)
Required Parameter Group 3 Input/output Input Char(10)
4 Create map Input Char(10)
View ID 5 View description Input Char(50)
INPUT; BINARY(4) 6 View number Output Binary(4)
The identifier of a previously registered view obtained by 7 Error code I/O Char(*)
using the Register Debug View API.
Service Program: QTECRTVS
Line number
INPUT; BINARY(4) Threadsafe: No

The line in the View ID where the breakpoint is to be

added. The program uses the Add View Description
(QteAddViewDescription) API to add a new view in the
Column number existing view information. The added view can then be used
INPUT; BINARY(4) on subsequent APIs when providing text and map details
The column in the line where the breakpoint is to be associated with this view.
added.
It is the responsibility of each processor to create its input
Note: At this time, column numbers are ignored. view, which is the root source file read by the processor.
Column one must be specified. Each processor must also create its output view, which is the
source produced by the processor. Other intermediate views
may be produced, but, as a minimum, there must be a map
between a processor's input and output view.

17-4 AS/400 System API Reference V4R4

 Add View Description (QteAddViewDescription) API

If a processor discards views produced by previous pre- be present in the view information. View type can be
processors, then it is not necessary for the input source view one of the following values:
to be created. For example, the C compiler can create only
a listing file view, as long as it discards all previous views.
*TEXT The view may contain supplied text as a
result of macro expansions. Text may
It is possible to create several views at one time. It is the also come from a previous view or from
responsibility of the processes creating multiple views to files.
manage them. *LISTING Text for this view comes entirely from
supplied text. Thus, the entire text for
When a view is created, a handle to that view is returned in this view is encapsulated with the view
the form of a view number. This number is needed when debug data and is not dependent on the
adding text or maps that refer to the view. Once a view has existence of source files.
been created, it cannot be created again. However, text and *STATEMENT
maps can be added to the view if it already exists. Thus, This view has no source text. Instead,
one processor can create the view, and another processor the text of the view consists of HLL state-
can add a map to the view, if that processor knows the view ment number, statement type, and the
number. procedure dictionary ID. This view is nec-
essary because breakpoint positions are
There is only one statement view per module. If the state- given in terms of positions in this view.
ment view is created more than once, an error results.
However, the statement view number is returned. This Input/output
allows one processor to create the statement view and INPUT; CHAR(10)
another processor to determine which number the view is. Indicates whether the view is an input view, an output
Note: The following restrictions apply to the adding of view, or an intermediate view. An input view is the view
views. created from the output of the previous processor, or the
view created from the root source file. It is not neces-
1. If a *TEXT view is added and that view refers to text in a
sary for each processor to have an input view.
previous view, the previous view must also be a *TEXT
view. An output view is the view created by the processor to
be input to the next processor. If a processor creates
2. The *INPUT and *OUTPUT views of a processor must
views that will not be used by any subsequent
be *TEXT views. A processor does not have to create
processors, then no output view is specified.
these views.
The allowable values for this parameter are:

Required Parameter Group *INPUT The view is an input view. This means
that it must come from a root source file
Previous view number created by the user or by a previous
INPUT; BINARY(4) processor, generally the input file speci-
The view number of a previous view whose text is used fied on Start View Creation.
in creating the text for this view. When describing text *OUTPUT The view is an output view. This means
for this view, it can be indicated that part of the text is a that it forms the text of a view that may
direct copy of text in the previous view. This allows the be read by a subsequent processor, and
API to automatically generate a map between this view is generally stored in the output file speci-
and the previous view. fied on Start View Creation.
blank The view is neither an input nor an output
As an example, if a preprocessor takes as input some
view, but is an intermediate view
source, changes it by expanding macros or SQL state-
produced by the processor.
ments, and outputs the changed source, then the output
view would have the input view as its previous view. Create map
When creating text from the output view, some of the INPUT; CHAR(10)
text could come from the input view.
Specifies whether the using program will be supplying
The previous view of a *TEXT view must also be a mapping information for this view, or whether the source
*TEXT view. debugger support should infer (create) the mapping at
If there is no previous view, specify zero for the view the time the text is described.
number. . The purpose of the automatic mapping is to allow the
ease of creating an include view. An include view has a
View type
previous view (usually the input view) which consists of
INPUT; CHAR(10)
only one file. The include view gets its text from this file
The type of view being created. Not all view types need and from include files.

Chapter 17. Debugger APIs 17-5

Add View File (QteAddViewFile) API

This parameter applies only when the view type speci- CPF955D E
fied in the previous parameter is *TEXT, and when this View data overflow. All debug data lost.
view has a previous view. A map can then be inferred
from the previous view to this view. To do so, the fol-
lowing criteria must be met: Add View File (QteAddViewFile) API
Ÿ This view must contain text from the previous view
whenever possible.
Required Parameter Group:
Ÿ The first file specified on the QteAddViewFile API
call for this view must be the file which is equivalent 1 File descriptor buffer Input Char(*)
to the previous view. 2 Number of entries Input Binary(4)
3 Format name Input Char(8)
Ÿ When constructing the include view, the line with the 4 View number Input Binary(4)
include statement must never be included in the text 5 Error code I/O Char(*)
of the view. Instead, it is replaced with the file that
is specified. Service Program: QTECRTVS

Create map can be one of the following values: Threadsafe: No

*YES The source debugger support should infer
the map between this *TEXT view and its The Add View File (QteAddViewFile) API provides a list of
previous view based on the text added files that can be used when describing text for a previously
with the QteAddViewText API. This is the added view. If a file is read more than once (such as a mul-
only map to this view that is inferred. tiple included file), it should be added multiple times. When
*NO The program creating this *TEXT view this file needs to be identified to other APIs, its file index is
uses the QteAddViewMap API to provide given, which is an index into the list of files supplied. The
mapping information for this view. first file supplied has an index of zero.
View description
The first file added to a view must be the root file for that
INPUT; CHAR(50)
view. For example, if a processor produces a source view,
A character string that describes the view being created. where a root file includes other files, the root file must be
The source debugger has the option of displaying this specified as the first file for the view. This is true even if the
text with the view for identification purposes. The file is not the first file to produce view text (which would
description should be left-justified. happen if an include statement is on the first line of the file).
View number All files for a view must be added at one time, with one call
OUTPUT; BINARY(4) to this API.
A number used to identify the view. Other APIs must be
passed this number when they require a view.
Required Parameter Group
Error code
File descriptor buffer
I/O; CHAR(*)
INPUT; CHAR(*)
The structure in which to return error information. For
Specifies the input variable containing the list of files that
the format of the structure, see “Error Code Parameter”
make up the specified view text.
on page 2-6.
The source debugger support does not validate the
existence of this file. This validation is done when text
Error Messages from the file is retrieved.
CPF3CF1 E
Number of entries
Error code parameter not valid.
INPUT; BINARY(4)
CPF3CF2 E
Error(s) occurred during running of &1 API. Specifies the number of files that are provided in the file
CPF9547 E Previous view not correct. descriptor buffer parameter.
CPF9549 E Error addressing API parameter. Many files may be described in a single file descriptor
CPF954B E Statement view already exists. buffer. However, each entry must represent a single file,
CPF954D E and this parameter must be a count of the number of
View type not valid. files provided.
CPF9555 E Create Map parameter not valid.
CPF9556 E API not valid at this time. For format FILA0200, the number specifies the number
CPF955A E Input Output parameter not valid. of format entries, each containing seven fields, that are
present before the external file names buffer.

17-6 AS/400 System API Reference V4R4

 Add View File (QteAddViewFile) API

Format name Field Descriptions

INPUT; CHAR(8)
Indicates the content and format of the information sup- AS/400 file library. The name of the library that contains
plied by the calling program in the file descriptor buffer. the file being listed. It is an AS/400 object name, left-
The valid values for format name are: justified, and padded with blanks.

FILA0100 AS/400 file AS/400 file name. The name of the AS/400 file being listed.
FILA0200 External file (workstation file not on an It is an AS/400 object name, left-justified, and padded with
AS/400) or AS/400 integrated file system blanks.
file
AS/400 member name. The name of the member in the file
For more information, see “FILA0100 Format” or being listed. It is an AS/400 object name, left-justified, and
“FILA0200 Format.” padded with blanks.
View number CCSID of file name. The CCSID the file name is in. A
INPUT; BINARY(4) value of zero indicates to use the CCSID value of the job. A
This is the number assigned by the debug support as an value of 65 535 causes an error message to be sent and the
output parameter on the Add View Description API, request to be ended.
which must be called prior to this API. If a file is used
for more than one view, it must be supplied once for Country ID of file name. The country ID of the file name.
each view in which it is used. A value of blanks indicates to use the country ID value of the
job.
Error code
I/O; CHAR(*) File flag. Whether the file is an AS/400 integrated file
system file or an external file (a workstation file not on an
The structure in which to return error information. For
AS/400).
the format of the structure, see “Error Code Parameter”
on page 2-6. 0 External file
1 AS/400 integrated file system file

FILA0100 Format File names buffer. The names of external files or AS/400
integrated file system files being listed. The file names are
Offset laid out one after another in this buffer. There is a pair of
Dec Hex Type Field offset and length fields for each file name in this buffer.

0 0 CHAR(10) AS/400 file name Language ID of file name. The language ID of the file
10 A CHAR(10) AS/400 file library name. A value of blanks indicates to use the language ID
value of the job.
20 14 CHAR(10) AS/400 member name
Length of file name. This is the length in bytes of the
external file name in the external file names buffer.
FILA0200 Format
Offset of file name. This offset from the start of the file
Offset descriptor buffer specifies the start of an external file name.
Dec Hex Type Field
Reserved. Reserved for future use.
Note: The first seven fields repeat the number of times speci-
fied in the number of entries parameter.
BINARY(4) Offset of file name Error Messages
BINARY(4) Length of file name CPF3C21 E
Format name &1 is not valid.
BINARY(4) File flag
CPF3CF1 E
BINARY(4) CCSID of file name Error code parameter not valid.
CHAR(2) Country ID of file name CPF3CF2 E
Error(s) occurred during running of &1 API.
CHAR(3) Language ID of file name
CPF9542 E View not found.
CHAR(3) Reserved CPF9549 E Error addressing API parameter.
Note: The following field occurs after the preceding header CPF9556 E API not valid at this time.
fields. CPF9558 E View already contains file descriptors.
CHAR(*) File names buffer CPF955B E Number of entries not valid.
CPF955D E
View data overflow. All debug data lost.

Chapter 17. Debugger APIs 17-7

Add View Map (QteAddViewMap) API

CPF956B E File name length not valid. parameters (from view number and from line) and specifying
CPF956C E the statement view number in the to view parameters (to
File name offset not valid. view number and to line).
CPF9575 E File flag not valid.
CPF9581 E CCSID of file name parameter not valid. This API is also used when mapping HLL statement numbers
(the statement view) to block numbers. This is accomplished
by putting positions in the *STATEMENT view in the from
line parameter and the block number in the to line parameter.
Add View Map (QteAddViewMap) API
All the map positions for the two views must be added at
once, with one call to this API. For this reason, the maps
Required Parameter Group: must be built up in a buffer as the processor produces its
output. At the end of view creation, all maps are then sup-
1 Map descriptor buffer Input Char(*)
2 Number of entries Input Binary(4) plied to this API.
3 Format name Input Char(8)
4 From view number Input Binary(4)
5 To view number Input Binary(4)
Required Parameter Group
6 Error code I/O Char(*) Map descriptor buffer
INPUT; CHAR(*)
Service Program: QTECRTVS
The input variable containing view-mapping information
Threadsafe: No that is to be passed to the API. This variable may
contain multiple sets of information as long as each
format in the variable is the same and the number of
The Add View Map (QteAddViewMap) API is used to map
entries is specified appropriately.
positions in one view to positions in another view. Both the
view being mapped from and the view being mapped to must Note: It is required that all map descriptors for a view
be previously added with the Add View Description API. be supplied with one call to this API.

When mapping one view to another view, positions on both Number of entries
views are specified. There are two ways of specifying a INPUT; BINARY(4)
position in the view: The number of map descriptors that are provided in the
Ÿ A line and column number in the view can be specified. map descriptor buffer parameter.
This is the line number of the text of the view. The text Many map entries may be described in a single map
is the concatenation of all text described by text descrip- descriptor buffer. However, each entry must represent a
tors. single map descriptor, and this parameter must be a
Ÿ Alternatively, a file index, and a line and column in the count of the number of entries provided.
file, can be specified. This allows view positions to be Each entry must contain all fields indicated, but,
specified in terms of file positions. depending on the type of map being described by the
entry, certain fields will not be used by the API.
A few rules must be followed when using the file method to
specify positions. These rules pertain to the view for which Format name
file positions are to be specified: INPUT; CHAR(8)
1. The view must be a text view (type *TEXT). The content and format of the information supplied by
the calling program in the map descriptor buffer. The
2. All positions in the view must be specified using the file
valid values for format name are:
method. File positions and view positions may not be
mixed. MAPA0100 Line and column mapping
3. The view may have a *TEXT view as a previous view, From view number
but the text from the previous view must consist of INPUT; BINARY(4)
exactly one text descriptor, and that text descriptor must
indicate that text comes from a file. The number of the view being mapped from. This
number must have been obtained from a previously
All lines in the from view must map to a position in the to added view with the Add View Description API.
view. For this reason, the first element in the mapping must Note: The from view number cannot refer to a state-
specify line 1 of the from view. ment view unless a map block is being created. In other
words, a statement view cannot be mapped to a text
This API is also used when mapping locations in a view to
view. However, text views may be mapped to the state-
HLL statement numbers (the *STATEMENT view). This is
ment view.
accomplished by referencing the locations in the from view

17-8 AS/400 System API Reference V4R4

 Add View Map (QteAddViewMap) API

To view number When the from view is a *STATEMENT view, this parameter
INPUT; BINARY(4) indicates which statement to map from. Its position in the
*STATEMENT view is supplied, the first statement having
The number of the view being mapped to. This number
position 1.
must have been obtained from a view previously added
with the Add View Description API. The special value
Map type. Specifies how text from the from view is being
supported is:
mapped to the to view at the position indicated.
-1 This may be specified when providing a 0 The type is not supplied, and is allowed only
map from a *STATEMENT view to block for statement or block mappings where the
identifiers. type is always known.
Error code
1 The text from the from view is being copied to
the to view at the specified positions.
I/O; CHAR(*)
2 The text in the to view is an expansion of text
The structure in which to return error information. For in the from view at the specified positions.
the format of the structure, see “Error Code Parameter” This is because of a macro expansion or an
on page 2-6. include statement.

To column. The column number specifying the starting

MAPA0100 Format character position within the line where the text is to go.
The following table shows the information supplied in the Column numbers in the range 1 through 255 can be speci-
MAPA0100 format: fied.
Note: Column numbers are not supported at this time. For
Offset upward compatibility, you should specify a value of 1.
Dec Hex Type Field
To file index. The number of the file, if the position is speci-
0 0 BINARY(4) From file index fied in terms of a file. This file must have been added and
4 4 BINARY(4) From line used in a text descriptor of the view. If the position is speci-
fied in terms of a view, the file index must be set to special
8 8 BINARY(4) From column
value -1.
12 C BINARY(4) To file index
16 10 BINARY(4) To line When file 0 is specified and the view has a previous view,
then this file is assumed to mean a line in the previous view,
20 14 BINARY(4) To column
because the first file specified in the file descriptor must be
24 18 BINARY(4) Map type the root source file used to construct this view. This root
source file is the same as the previous view.

Field Descriptions To line. The line number of the view or file where the text is
mapped to.
From column. The column number where text is located.
This is the character position on the line specified above. When the to view is a *STATEMENT view, this parameter
Column numbers in the range 1 through 255 can be speci- indicates which statement to map to, the first view having
fied. position 1.
Note: Column numbers are not supported at this time. For When the to view is a block view (special value -1), this
upward compatibility, you should specify a value of 1. parameter indicates which block number to map to.
From file index. The number of the file, if the position is
specified in terms of a file. This file must have been added Error Messages
and used in a text descriptor of the view. If the position is
CPF3C21 E
specified in terms of a view, the file index must be set to
Format name &1 is not valid.
special value -1.
CPF3CF1 E
When file 0 is specified and the view has a previous view, Error code parameter not valid.
then this file is assumed to mean a line in the previous view, CPF3CF2 E
because the first file specified in the file descriptor must be Error(s) occurred during running of &1 API.
the root source file used to construct this view. This root CPF9543 E From view not found.
source file is the same as the previous view. CPF9544 E To view not found.
CPF9549 E Error addressing API parameter.
From line. The line number of the view or file where the text CPF9551 E File not found.
is mapped from. CPF9552 E Cannot map between views.
CPF9553 E Map type not defined.

Chapter 17. Debugger APIs 17-9

Add View Text (QteAddViewText) API

CPF9556 E API not valid at this time. Number of entries

CPF955B E Number of entries not valid. INPUT; BINARY(4)
CPF955D E
The number of text descriptors that are provided in the
View data overflow. All debug data lost.
text descriptor buffer parameter.
Many pieces of text may be described in a single text
descriptor buffer. However, each entry must represent a
Add View Text (QteAddViewText) API
single piece of contiguous text, and this parameter must
be a count of the number of entries provided.
Required Parameter Group: Each entry must contain all fields indicated, but,
depending on the type of text being described by the
1 View number Input Binary(4) entry, certain fields will not be used by the API.
2 Text descriptor buffer Input Char(*)
3 Number of entries Input Binary(4) If any text is supplied by the calling program, it is identi-
4 Format name Input Char(8) fied by a text descriptor, but the text itself is contained in
5 Supplied text buffer Input Char(*) the supplied text buffer.
6 Length of text buffer Input Binary(4)
7 Error code I/O Char(*) Format name
INPUT; CHAR(8)
Service Program: QTECRTVS
The content and format of the information supplied by
Threadsafe: No the calling program in the text descriptor buffer. The
valid values for format name are:

TXTA0100 Used when the text being added to this

The Add View Text (QteAddViewText) API is used to
view can come from any of the following:
describe a piece of text of a previously added view. As a
processor reads its input source, it creates at least one view. Ÿ Blanks
This API is called to add the directions for re-creating the text Ÿ Stored in a file
of these views. For the debugger to show the text that
makes up a view, the location of the pieces of text that make Ÿ Copied from the previous view
up the view must be specified. Ÿ Supplied by the calling program
within the supplied text buffer param-
When the view is reconstructed by the debugger, the pieces eter
of text will be retrieved and concatenated into a single piece
of text, following the directions given when this API is called. This is the case for a *TEXT view.
Thus, when it is mentioned that text is copied, it is referring TXTA0101 Used when the entire text for this view is
to a later time, when the view is reconstructed. supplied text. This is the case for a
*LISTING view.
All the text for a view must be added at once, with one call to TXTA0102 Used when statement information for a
this API. For this reason, the text must be built up in a buffer *STATEMENT view is to be supplied.
as the processor produces its output. At the end of view cre- | TXTA0103 Used when the entire text for this view is
ation, all text is then supplied to this API. | supplied text. This is the case for a
| *LISTING view. Note that this format is
If any text comes from files, the file descriptors must have | identical to TXTA0101; however, when
been previously added to the view with the Add View File | the TXTA0103 format is specified, the
(QteAddViewFile) API. | listing view that is created will be com-
| pressed. It will be decompressed at the
| time it is reconstructed.
Required Parameter Group
Supplied text buffer
View number
INPUT; CHAR(*)
INPUT; BINARY(4)
The input variable that is to be passed to the API, con-
The number of the view to which a piece of text is being
taining the text that is supplied when a text descriptor in
added. This number must be the same as the number
the text descriptor buffer parameter indicates that text is
previously returned by the Add View Description API.
supplied. Text descriptors within the text descriptor
Text descriptor buffer buffer refer to text locations within this buffer by the
INPUT; CHAR(*) offset from the beginning of the buffer. The piece of text
| is ended by a NULL (hex 00) character. To conserve
The input variable containing the text descriptors. Text
| storage, delete the trailing blanks in lines of supplied text
descriptors define the location of text used to build the
| and end the text with a null character.
view specified in the view name parameter.

17-10 AS/400 System API Reference V4R4

 Add View Text (QteAddViewText) API

Note: A line of supplied text must not be more than specified. File 0 is assumed to mean a line in the previous
255 characters in length, not counting the NULL char- view because the first file specified in the file descriptor must
acter. be the root source file used to construct this view. This root
source file is the same as the previous view. Instead, *PRE-
Length of text buffer
VIOUS should be specified in the text location field. If file 0
INPUT; BINARY(4)
is specified instead of the previous view and the previous
The length of the supplied text buffer. view was created by another preprocessor that created a
temporary file as its output, that file may not exist at run time.
Error code
In that case, text for the view could not be retrieved.
I/O; CHAR(*)
However, if *PREVIOUS is specified, the View Retrieval API
The structure in which to return error information. For can use the text descriptors of the output view created by the
the format of the structure, see “Error Code Parameter” preprocessor to reconstruct the text.
on page 2-6.
Note: The source debugger support does not validate the
existence of this file. It merely uses the name in the view
TXTA0100 Format
information to refer to the location of debug data. When the
text of the view is reconstructed, text will be retrieved from
Offset
the file named in this parameter (and the member name
Dec Hex Type Field parameter), and the file name will be validated at that time.
0 0 CHAR(10) Text location
From line. The line number where text is located. If the text
10 A CHAR(2) Reserved location is a file, this is the line number in that file. If the text
12 C BINARY(4) File index location is a previous view, this is the line position within that
16 10 BINARY(4) Starting offset | view. This can be thought of as the start line position. This
| field is required if the text location is set to *FILE or *PRE-
20 14 BINARY(4) Number of lines | VIOUS.
24 18 BINARY(4) From line
Number of lines. The number of lines of text being
described. It is intended that views be created in order,
TXTA0101 Format
where each piece of text comes directly after the previous
| text added. This field is required when text location is set to
Offset
| *FILE or *PREVIOUS.
Dec Hex Type Field
0 0 BINARY(4) Starting offset
Procedure dictionary ID. The dictionary number of the pro-
cedure where the statement is located.

TXTA0102 Format Reserved. Reserved for future use.

Offset Starting offset. The location within the supplied text buffer
of the start of the supplied text. This is an offset from the
Dec Hex Type Field
| beginning of the buffer to the start of the text. This field is
0 0 BINARY(4) Procedure dictionary ID | required if the text location is set to *SUPPLIED in the
4 4 BINARY(4) Statement number | TXTA0100 format.
8 8 CHAR(1) Statement type Statement number. The HLL statement number of the
statement.
| TXTA0103 Format
Statement type. The type of the statement being added.
| Offset Possible values are:
| Dec Hex Type Field X'01' INIT CODE
X'02' PROC ENTRY
| 0 0 BINARY(4) Starting offset
X'03' PROC EXIT
X'04' ALLOC
X'05' STMT
Field Descriptions X'06' ENTRY
File index. A file member added by the Add View File API. X'07' EXIT
| This field is required if the text location is set to *FILE; other- X'08' MULTIEXIT
| wise, it is ignored. The first file added for the specified view X'09' PATH LABEL
is file 0, the second is file 1, and so forth. X'10' PATH CALL BGN
X'11' PATH CALL RET
When the view has a previous view, file 0 should not be X'12' PATH DO BGN

Chapter 17. Debugger APIs 17-11

 Change Current Thread API

X'13' PATH TRUEIF

X'14' PATH FALSEIF Required Parameter Group:
X'15' PATH WHEN BGN
X'16' PATH OTHERW 1 Thread ID Input Char(8)
X'17' GOTO 2 Error code I/O Char(*)
X'18' POST COMPOUND
Service Program: QTETHRD
Text location. Where the text being referred to is located.
This field is required for all entries. Threadsafe: No

| *FILE The text is stored in a file.

| *PREVIOUS The text is a copy of the previous view text. The Change Current Thread (QteChangeCurrentThread) API
| The previous view is specified when the view changes the current thread to any thread being debugged.1 A
| is created. current thread has several properties that distinguish it from
| *SUPPLIED The text is supplied by the API user within the other threads being debugged:
| supplied text buffer parameter. The text that
Ÿ Debug commands are run in this thread.
| is supplied by the using program must be in
| the suppled text buffer parameter and referred Ÿ This is the first thread released after a return to the base
| to by a text descriptor within the text debug support after a debug stop (breakpoint, step,
| descriptor buffer parameter. watch, or unmonitored exception).
| *BLANK The text consists of blank lines. The number Ÿ If there are multiple debug stops at the same time, this
| of blank lines inserted is specified by the thread is the first one processed.
| number of lines field.
Before the current thread can be changed the new current
thread must be stopped or halted and is waiting for debug to
Error Messages restart it. If this is not true, an error is returned to the API
CPF3C21 E caller and the current thread is not changed.
Format name &1 is not valid.
CPF3CF1 E Threads debugging is supported if a service job is used to
Error code parameter not valid. debug a job that was spawned by native threads support. If
CPF3CF2 E this is not the debug environment present when this API is
Error(s) occurred during running of &1 API. called, a CPF958B error is returned.
CPF9542 E View not found.
CPF9545 E No previous view.
Required Parameter Group
CPF9549 E Error addressing API parameter.
CPF954E E Text location is not valid. Thread ID
CPF9551 E File not found. INPUT; CHAR(8)
CPF9552 E Cannot map between views.
This is an 8-byte handle assigned by the system.
CPF9556 E API not valid at this time.
CPF9557 E View already contains text descriptors. Error code
CPF955B E Number of entries not valid. I/O; CHAR(*)
CPF955C E
The structure in which to return error information. For
Supplied Text Length parameter not valid.
the format of the structure, see “Error Code Parameter”
CPF955D E
on page 2-6.
View data overflow. All debug data lost.
CPF9569 E Missing supplied text.
CPF956A E No such text in previous view. Error Messages
CPF3CF1 E
Error code parameter not valid.
Change Current Thread CPF3CF2 E
(QteChangeCurrentThread) API Error(s) occurred during running of &1 API.
CPF9541 E Not in debug mode.
CPF9549 E Error addressing API parameter.
CPF9589 E Thread &1 not stopped or halted.
CPF958A E Thread &1 not found.

1 A job may have several threads, each of which are debugged if the job is debugged. By default, the current thread is the initial thread of the
debugged job, or the thread at a debug stop.

17-12 AS/400 System API Reference V4R4

 Dump Module Variables (QteDumpModuleVariables) API

CPF958B E Threads debugging not supported. Each thread identifier in the thread array is 8 bytes long.
The number of thread identifiers is specified in the
number of threads parameter.
Change Thread Status If the number of threads parameter is minus one, the
(QteChangeThreadStatus) API first and only thread array parameter must be a special
value. In this case, all other thread array parameters
are ignored. Valid special values are:
Required Parameter Group:
*ALL The debug status for all threads is
1 Thread debug status Input Char(10) changed to the debug status specified in
2 Thread array Input Array of the thread debug status parameter.
Char(8)
3 Number of threads Input Binary(4) Number of threads
4 Error code I/O Char(*) INPUT; BINARY(4)
The number of thread identifiers provided in the thread
Service Program: QTETHRD
array parameter. The number of threads parameter
Threadsafe: No must be greater than zero or a minus one. If it has a
value of minus one, the first and only thread array
parameter must be a special value. If it is greater than
The Change Thread Status (QteChangeThreadStatus) API zero, the number specified is the number of thread array
changes the debug status for threads being debugged.2 parameters that must be provided.

Before the debug status of a thread can be changed, the Error code
thread must be stopped or halted by debug support. If any I/O; CHAR(*)
thread specified in the thread array has not been stopped or The structure in which to return error information. For
halted by debug support, an error is returned to the API the format of the structure, see “Error Code Parameter”
caller and the debug status of all threads is unchanged. on page 2-6.

Threads debugging is supported if a service job is used to

debug a job that was spawned by native threads support. If Error Messages
this is not the debug environment present when this API is CPF3C1E E
called, a CPF958B error is returned. Required parameter &1 omitted.
CPF3CF1 E
Authorities and Locks Error code parameter not valid.
CPF3CF2 E
None Error(s) occurred during running of &1 API.
CPF9541 E Not in debug mode.
CPF9549 E Error addressing API parameter.
Required Parameter Group CPF958A E Thread &1 not found.
Thread debug status CPF958B E Threads debugging not supported.
INPUT; CHAR(10) CPF958C E
Number of threads not valid.
The desired debug status for the thread identifiers speci- CPF959B E Thread status value not valid.
fied in the thread array parameter. The valid debug CPF959C E
status values are: Thread array special value not valid.
*ENABLE Enable the specified threads. CPF959D E
*DISABLE Disable the specified threads. Thread status cannot be changed.

Thread array
INPUT; ARRAY OF CHAR(8) Dump Module Variables
The thread identifiers for which debug status is changed. (QteDumpModuleVariables) API

2 A job may have several threads, each of which are debugged if the job is debugged. By default, the current thread is the initial thread of the
debugged job, or the thread at a debug stop.

Chapter 17. Debugger APIs 17-13

Dump Module Variables (QteDumpModuleVariables) API

Format name
Required Parameter Group: INPUT; CHAR(8)
The format of the information returned for the module.
1 Receiver variable Output Char(*) The possible format name is:
2 Receiver variable length Input Binary(4)
3 Format name Input Char(8) DMPV0100 Dump module variables.
4 Qualified program name Input Char(20)
5 Program type Input Char(10) Qualified program name
6 Module name Input Char(10) INPUT; CHAR(20)
7 Data option Input Binary(4)
8 Continuation handle Input Char(16) The name of the program for which the variables and
9 Error code I/O Char(*) values will be provided.
The first 10 characters contain the name of the program.
Service Program: QTEDMPV
The second 10 characters contain the name of the
Threadsafe: No library where the program is located. Each name will be
left-justified. The special values of *LIBL and *CURLIB
may be specified.
The Dump Module Variables (QteDumpModuleVariables) API
Program type
is used to get a list of all the variable names and current
INPUT; CHAR(10)
values of those variables. Variable values may only be
requested if an active call stack entry for the module speci- The object type of the program. The possible values
fied exists in the job in which this API is called. Values are:
existing in program static or automatic storage are not acces-
*PGM ILE program
sible by this API unless the program has a current call stack
*SRVPGM ILE service program
entry. All variables that were defined by the compiler and
stored in the module HLL symbol table will be returned. This This API cannot be used to dump variable information
API supports the ILE CL, ILE COBOL, and ILE RPG com- for an OPM program.
pilers.
Module name
The module for which variable information is being requested INPUT; CHAR(10)
must contain debug data. See the debug view (DBGVIEW) The name of the module (left-justified) within the
parameter of the Create RPG Module (CRTRPGMOD), program. The module must be written in one of the sup-
Create COBOL Module (CRTCBLMOD), or Create CL ported ILE languages or an error is reported.
Module (CRTCLMOD) command. It is not necessary that the
job in which the program is running be in debug mode to use Data option
this API. INPUT; BINARY(4)
The content of the information returned for the module.
Variable names and, optionally, their values will be provided
The possible values are:
within the block in which they were declared. This API does
not guarantee that those variables are returned in any partic- 0 Variable names only.
ular order within the block. 1 Variable names and current values in
default character format (the type associ-
ated with the variable will be used in
Required Parameter Group
determining the format of the value
Receiver variable returned).
OUTPUT; CHAR(*) 2 Variable names, the current values in
default character format, and the current
The variable that is to receive the list of program vari-
values in hex format.
ables and current values for the specified module.
Continuation handle
Receiver variable length
INPUT; CHAR(16)
INPUT; BINARY(4)
The handle used to continue from a previous call to this
The length of the receiver variable that is provided in the
API that resulted in partially complete information. You
previous parameter. This value must be at least 48 to
can determine if a previous call resulted in partially com-
provide space for the receiver variable header section.
plete information by checking the continuation handle
The bytes available field tells the caller what size is
variable in the receiver variable header section following
required to receive the entire results of the request.
the API call.
If the API is not attempting to continue from a previous
call, this parameter must be set to blanks. Otherwise, a
valid continuation value must be supplied. When contin-

17-14 AS/400 System API Reference V4R4

 Dump Module Variables (QteDumpModuleVariables) API

uing, the first entry in the returned receiver variable

Figure 17-2. Module Variable Header Section
parameter is the entry that immediately follows the last
entry returned in the previous call. Offset
Dec Hex Type Field
An error will occur under the following conditions:
0 0 BINARY(4) Length of module variable
Ÿ The continuation handle is not blank on the first section
request for a given set of input parameters.
4 4 BINARY(4) Offset to next variable
Ÿ The continuation handle is not the same as provided
8 8 BINARY(4) Variable entry type
in the receiver variable header section on the pre-
vious call to this API.
This portion of the module variable section will always start in
Error code the next available 4-word boundary to ensure proper align-
I/O; CHAR(*) ment of the BINARY(4) fields within each section. The caller
The structure in which to return error information. For must use the offset to next variable field to find the start of
the format of the structure, see “Error Code Parameter” the next module variable section and use the length of
on page 2-6. module variable section to determine the length of the
current section.

Format of the Receiver Variable Module Variable Section (Scalar Variable Entry
Type): The following table is used when the variable entry
The receiver variable area consists of: being returned is scalar. This section could occur by itself or
Ÿ A receiver variable header section. following an array definition.
Ÿ A module variable header section for each variable
Figure 17-3. Scalar Variable Section
returned by the Dump Module Variables API. The
module variable header section consists of: Offset

– A fixed-length header section Dec Hex Type Field

– A variable-length section containing the information 0 0 BINARY(4) Variable type

requested for the module variable. 4 4 BINARY(4) Total digits
8 8 BINARY(4) Precision
Receiver Variable Header Section
12 C BINARY(4) Scaling factor
Figure 17-1. Receiver Variable Header Section 16 10 BINARY(4) Offset to variable name
Offset 20 14 BINARY(4) Length of variable name
Dec Hex Type Field 24 18 BINARY(4) Length of default value
0 0 BINARY(4) Bytes returned 28 1C BINARY(4) Length of hexadecimal
value
4 4 BINARY(4) Bytes available
| 32 20 BINARY(4) String content descriptor
8 8 BINARY(4) Number of variable sections
| 36 24 BINARY(4) Length of string prefix
12 C CHAR(10) Returned library
CHAR(*) Variable name
22 16 CHAR(10) Reserved
CHAR(*) Default value
32 20 CHAR(16) Continuation handle
CHAR(*) Hexadecimal value
Note: The following information is repeated as many times as
the value specified in the number of variable sections field.
All variable values will be returned in displayable character
Module variable header
section
format. For example, if the internal representation of a
2-byte unsigned integer is X'0345' the data returned through
Module variable section this API in the default value area will be '837 '
(X'F8F3F7404040'), and in the hex value area will be '0345'
Module Variable Header Section: This table describes (X'F0F3F4F5').
the common header area to each subsequently defined
module variable section. When the scalar values of an array are being retrieved, the
values will be returned in row major order, with no separating
characters. The data option parameter will be used to deter-
mine if any values are displayed and in what form.
0 No values will be returned.

Chapter 17. Debugger APIs 17-15

Dump Module Variables (QteDumpModuleVariables) API

1 Only the default value of each scalar will be Field Descriptions

returned. The length of default value field will
specify the length of each value. Each scalar Array name. The field containing the name of the array.
value in the array will be provided in row
major order. Block name. The field containing the name of the block.
2 The default value and the hex value of each
scalar will be returned. The length of default Block number. The number of the block.
value field and the length of hex value field
Bytes available. The number of bytes of data available to
will specify the length of each value. Each
be returned. All available data is returned if enough space is
scalar value in the array will be provided with
provided.
each representation in row major order with
the default value leading each pair of values. Bytes returned. The number of bytes of data returned.

Module Variable Section (Array Definition Entry Continuation handle. When not all the requested data can
Type): The following table is used when the variable entry be returned on a single call to this API, a value will be sup-
being returned is an array. This section will define the array plied in this field which may be used to continue on the next
and will be followed by one or more scalar variable sections. call to this API.

Figure 17-4. Array Definition Variable Section Default value. The value of the variable represented in the
default format for the variable type.
Offset
Dec Hex Type Field Dimension lower bound. The lower bound of an array
0 0 BINARY(4) Number of scalar fields dimension.

4 4 BINARY(4) Offset to first variable Dimension upper bound. The upper bound of an array
8 8 BINARY(4) Offset to dimensions dimension.
12 C BINARY(4) Offset to array name Hexadecimal value. The value of the variable represented
16 10 BINARY(4) Number of array dimensions in hexadecimal format as it is stored in the machine.
20 14 BINARY(4) Length of array name
Length of array name. The length of the array name field.
BINARY(4) Dimension lower bound
BINARY(4) Dimension upper bound Length of block name. The length of the block name field
(may be zero if no name is associated with the block).
CHAR(*) Array name
Length of default value. The length of the data in the
Module Variable Section (Block Definition Entry default value field. This will be zero if the data option param-
Type): The following table is used when the variable entry eter is 0.
being returned is a block definition. One of these sections
Length of hexadecimal value. The length of the data in the
will exist for each block defined in the program. A block defi-
hexadecimal value field. This will be zero if the data option
nition entry will precede all other variable entry sections for
parameter is 0 or 1.
variables defined within the specified block.
Length of module variable section. The module variable
Figure 17-5. Block Definition Variable Section entry section length, including the length of the module vari-
Offset able section header.
Dec Hex Type Field
| Length of string prefix. The length of the string prefix (may
0 0 BINARY(4) Block number | be 0 if no prefix is associated with the string).
4 4 BINARY(4) Offset to block name
Length of variable name. The length of the variable name
8 8 BINARY(4) Length of block name field.
CHAR(*) Block name
Number of array dimensions. The number of dimensions
in the array. The dimension upper and lower bound fields
are repeated for each array dimension.

Number of scalar fields. Number of scalar fields in each

array element. There will be one module variable section for
each scalar following an array definition header.

17-16 AS/400 System API Reference V4R4

 Dump Module Variables (QteDumpModuleVariables) API

Number of variable sections. The number of variable 2 Block definition

entries returned by the API. These include block variable
entries, scalar variable entries, and array variable entries. Variable name. The field containing the name of the vari-
able.
Offset to array name. Offset to the start of the array name
field. Variable type. The data type of the variable. It may be one
of the following values:
Offset to block name. Offset to the start of the block name
0 An error occurred evaluating the variable
field.
1 An 8-bit (1-byte) character
Offset to dimensions. Offset to the start of the first dimen-
2 A 16-bit character
sion lower bound field.
3 A 32-bit quantity having ordinal values of zero
or one. Zero is the ordinal value for FALSE,
Offset to first variable. Offset to the start of the module and one is the ordinal value for TRUE.
variable header section for the first scalar variable. 4 A 16-bit unsigned integer
5 A 32-bit unsigned integer
Offset to next module variable header section. Offset to 6 A 16-bit two's complement (signed) integer
the start of the next module variable header section. 7 A 32-bit two's complement (signed) integer
8 A 32-bit IEEE 754 floating point value
Offset to variable name. Offset to the start of the variable 9 A 64-bit IEEE 754 floating point value
name field. 10 A 128-bit space pointer
11 A fixed-length character string
Precision. The precision associated with a decimal type
12 A packed decimal
(packed, zoned, or binary decimal).
13 A zoned trailing embedded sign
Reserved. An ignored field.
14 A zoned leading embedded sign
15 A zoned trailing separate sign
Returned library. The library where the program was found. 16 A zoned leading separate sign
This is useful when *LIBL or *CURLIB is specified for the 17 A 16-bit binary decimal
program library portion of the program name parameter. 18 A 32-bit binary decimal
19 A 64-bit binary decimal
Scaling factor. The scaling factor associated with a decimal 20 A 32-bit index value
type (packed, zoned, or binary decimal). | 21 An 8-bit unsigned integer
| 22 An 8-bit signed integer
| String content descriptor. The type of the string variable. It | 23 A 64-bit unsigned integer
| may be one of the following values: | 24 A 64-bit signed integer
| 0 An error occurred evaluating the variable | 25 A variable-length character string
| 1 A null-terminated unicode string
| 2 A length-prefix-2 unicode string Error Messages
| 3 A length-prefix-4 unicode string
| 4 A fixed-length unicode string CPF3C21 E
| 5 A variable-length unicode string Format name &1 is not valid.
| 6 A null-terminated graphic string CPF3CF1 E
| 7 A length-prefix-2 graphic string Error code parameter not valid.
| 8 A length-prefix-4 graphic string CPF3CF2 E
| 9 A fixed-length graphic string Error(s) occurred during running of &1 API.
| 10 A variable-length graphic string CPF9549 E Error addressing API parameter.
| 11 A date string CPF954F E Module &1 not found.
| 12 A packed date string CPF955F E Program &1 not a bound program.
| 13 A time string CPF9562 E Module &1 cannot be debugged.
| 14 A packed time string CPF956D E
| 15 A timestamp string Parameter does not match on continuation
request.
Total digits. The total number of digits associated with a CPF956E E Program language of module not supported.
decimal type (packed, zoned, or binary decimal). CPF956F E Continuation handle parameter not valid.
CPF9573 E Program type parameter not valid.
Variable entry type. The type of variable section that CPF9574 E Call stack entry does not exist.
follows the module variable header section. It may be one of CPF9579 E Data option specified not valid.
the following values: CPF9801 E Object &2 in library &3 not found.
0 Scalar variable CPF9802 E Not authorized to object &2 in &3.
1 Array definition CPF9803 E Cannot allocate object &2 in library &3.
CPF9809 E Library &1 cannot be accessed.

Chapter 17. Debugger APIs 17-17

Map View Position (QteMapViewPosition) API

CPF9810 E Library &1 not found. is not complete (for example, if a compiler that is creating the
CPF9820 E Not authorized to use library &1. view fails the compilation).

Authorities
End Source Debug (QteEndSourceDebug)
API Library Authority
*USE
File Authority *CHANGE
Required Parameter:
Required Parameter
1 Error code I/O Char(*)
Error code
Service Program: QTEDBGS I/O; CHAR(*)

Threadsafe: No The structure in which to return error information. For

the format of the structure, see “Error Code Parameter”
on page 2-6.
The End Source Debug (QteEndSourceDebug) API is used
to end the source debug support. All ILE and OPM pro-
grams being debugged under the source debug support are Error Messages
removed from debug mode. All registered views to programs CPF3CF1 E
being debugged are no longer valid. Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
Required Parameter CPF9546 E View information damaged.
Error code CPF9549 E Error addressing API parameter.
I/O; CHAR(*) CPF9556 E API not valid at this time.
CPF955D E
The structure in which to return error information. For
View data overflow. All debug data lost.
the format of the structure, see “Error Code Parameter”
CPF9803 E Cannot allocate object &2 in library &3.
on page 2-6.
CPF9809 E Library &1 cannot be accessed.
CPF9810 E Library &1 not found.
Error Messages CPF9815 E Member &5 file &2 in library &3 not found.
CPF9820 E Not authorized to use library &1.
CPF3CF1 E
CPF9822 E Not authorized to file &1 in library &2.
Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
CPF9541 E Not in debug mode. Map View Position (QteMapViewPosition)
CPF9549 E Error addressing API parameter. API

End View Creation (QteEndViewCreation) Required Parameter Group:

API 1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 From view ID Input Binary(4)
Required Parameter: 4 From line number Input Binary(4)
5 From column number Input Binary(4)
1 Error code I/O Char(*) 6 To view ID Input Binary(4)
7 Error code I/O Char(*)
Service Program: QTECRTVS
Service Program: QTEDBGS
Threadsafe: No
Threadsafe: No

The End View Creation (QteEndViewCreation) API is used

by a processor when all debug data views have been The Map View Position (QteMapViewPosition) API maps
created. At that time, views are written to the output file positions from one view to another view within the same
member (if any) specified on the Start View Creation API. program and module. A specified position in the view identi-
This End View Creation API should not be called if the view fied in the from view ID parameter is used for the mapping.

17-18 AS/400 System API Reference V4R4

 Map View Position (QteMapViewPosition) API

The position is specified as a line number and a column If the from view ID parameter is a statement view, this
number in the from view ID. parameter is not used and should be set to column one.

A position in one view can map to more than one position in To view ID
another view. For example, an SQL statement in the SQL INPUT; BINARY(4)
input source view may map to many positions in the C input The identifier of a previously registered view, which is
source view. This is because a single SQL statement may obtained using the Register Debug View API. This
distribute source throughout the output of the SQL processor. specifies the to view in the mapping function provided.

One or more positions in the to view ID are returned as a Error code

line number and a column number. 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.
Receiver variable
OUTPUT; CHAR(*) Format of Receiver Variable: The following table
The variable that is to receive the information requested. shows the information supplied in the receiver variable
You can specify the size of this area to be smaller than parameter.
the format requested if you specify the length of receiver
variable parameter correctly. As a result, the API Offset
returns only the data that the area can hold. For more Dec Hex Type Field
information on the size and format of the receiver vari-
0 0 BINARY(4) Bytes returned
able, see “Format of Receiver Variable.”
4 4 BINARY(4) Bytes available
Length of receiver variable
8 8 BINARY(4) Number of map elements
INPUT; BINARY(4)
Note: The following fields are repeated for each map element.
The length of the receiver variable. The minimum length
is 8 bytes. BINARY(4) Line number
BINARY(4) Column number
It is suggested that a receiver variable length be given
that is large enough to hold one map element. Because
this is normally the number of elements returned, a
single call to this API is usually sufficient.
Field Descriptions
From view ID Bytes available. The number of bytes of data available to
INPUT; BINARY(4) be returned to the user.

The identifier of a previously registered view, which is Bytes returned. The number of bytes of data returned to
obtained using the Register Debug View API. This ID the user.
specifies the from view in the mapping function provided.
Column number. The column number within the from line
From line number number parameter that maps to the current position in the to
INPUT; BINARY(4) view ID parameter. Column numbers are 1 through 255.
The line number in the view specified by the from view
ID parameter mapped to a line number in the view spec- If the view is a statement view, this number is not used and
ified by the to view ID parameter. is set to column one.

If the information in the from view ID parameter is a Line number. The line number in the view specified by the
statement view, this parameter represents the line to view ID parameter.
number in the statement view.
Number of map elements. The line number and column
Note: The statement view is the lowest level view.
number fields are repeated this number of times, once for
Breakpoints, steps, and unmonitored exceptions are
each map available.
reported as a line number within this view. Therefore,
the statement view must exist and be registered to
accomplish source level debugging. Error Messages
From column number CPF3C24 E
INPUT; BINARY(4) Length of the receiver variable is not valid.
CPF3CF1 E
The position in the line specified by the from line number
Error code parameter not valid.
parameter. Column numbers are 1 through 255.
CPF3CF2 E
Error(s) occurred during running of &1 API.

Chapter 17. Debugger APIs 17-19

Register Debug View (QteRegisterDebugView) API

CPF9541 E Not in debug mode. Authorities

CPF9543 E From view not found.
CPF9544 E To view not found. The authorities required are dependent on the program type
CPF9548 E Map not available. parameter. If the program type is *PGM or *SRVPGM, the
CPF9567 E Column number not valid. authorities are as follows:
CPF9568 E Line number not valid.
Program Authority
CPF9549 E Error addressing API parameter.
Either *SERVICE and *USE, or *CHANGE
Library Authority
*USE
Register Debug View
(QteRegisterDebugView) API If the program type is *CLASS, the authorities are as follows:
Class File Authority
*R
Required Parameter Group:

1 View ID Output Binary(4) Required Parameter Group

2 Number of lines Output Binary(4)
3 Returned library Output Char(10) View ID
or Char(*) OUTPUT; BINARY(4)
4 View timestamp Output Char(13)
5 Qualified program name Input Char(20)
The returned ID of the successfully (or previously) regis-
or Char(*) tered debug view. The source debugger support sup-
6 Program type Input Char(10) plies and maintains the view IDs. If no error is reported
7 Module name Input Char(10) by the API, this value is used by the program in view ID
or input parameters that occur on subsequent debugger
Binary(4) APIs.
8 View number Input Binary(4)
9 Error code I/O Char(*) Number of lines
OUTPUT; BINARY(4)
Service Program: QTEDBGS
The number of lines of text in the view.
Threadsafe: No
Returned library
OUTPUT; CHAR(10) or CHAR(*)
The Register Debug View (QteRegisterDebugView) API reg- The format of this parameter is dependent on the
isters a view of a module, which allows a program to be program type parameter. If the program type is *PGM or
debugged in terms of that view. An identifier to the view is *SRVPGM, the format of this parameter is OUTPUT
returned on successful completion of the API to be used in CHAR(10) as follows:
subsequent view information APIs. A program is considered
to be active under ILE debug only after at least one of its The library where the program was found. This is
debug views is registered. useful when *LIBL or *CURLIB is specified for the
program library.
Views retrieved by the Retrieve Module Views
If the program type is *CLASS, the format of this param-
(QteRetrieveModuleViews) API can be registered. This
eter is OUTPUT CHAR(*) as follows:
includes both ILE and OPM program views. OPM program
views must have been created by the OPM CL, OPM Class path name information for the requested class
COBOL, or OPM RPG compiler using the *SRCDBG or file. For more information, see “Format of JAVA
*LSTDBG option. Returned Library Parameter” on page 17-21.

This API will also register JAVA class file views. In this case View timestamp
the input program type parameter must be *CLASS and the OUTPUT; CHAR(13)
input qualified program name parameter must be a null- The date and time the view was created. If this time is
terminated JAVA class file name. The class path name of greater than the time obtained from the Retrieve Module
the file that contains the class file is returned in the returned Views API, the view may not be the same as the pre-
library parameter. vious one. Users should run the Retrieve Module Views
API before registering the view. The value is the Amer-
If a request is made to register an already registered view,
ican National Standard 13-character timestamp
no error occurs. Instead, the previous ID is returned.
CYYMMDDHHMMSS format, where:
Note: Before registering views for a program again, it is
recommended that all views for that program first be C Century, where 0 indicates years 19xx
removed. and 1 indicates years 20xx.

17-20 AS/400 System API Reference V4R4

 Register Debug View (QteRegisterDebugView) API

YY Year View number

MM Month INPUT; BINARY(4)
HH Hour
The number of a view to be registered for subsequent
MM Minute
view information and debug command APIs. If -1 is
SS Second
specified, the statement view is registered. The value -1
Qualified program name is a shortcut to allow the registering of this view without
INPUT; CHAR(20) or CHAR(*) going through the Retrieve Module Views API to obtain
the number.
The format of this parameter is dependent on the
program type parameter. If the program type is *PGM or Information for this parameter is available by using the
*SRVPGM, the format of this parameter is as follows: Retrieve Module Views API to retrieve available view
numbers for modules associated with a specific program.
The name of a program for which a view is to be
registered. The first 10 characters contain the Error code
program name. The second 10 characters contain I/O; CHAR(*)
the name of the library where the program is The structure in which to return error information. For
located. The following special values may be used the format of the structure, see “Error Code Parameter”
for the library name: on page 2-6.
*CURLIB The job's current library.
*LIBL The library list. Format of JAVA Returned Library
If the program type is *CLASS, the format of this param- Parameter
eter is as follows:
When the program type parameter is *CLASS, class path
The null-terminated class file name of the JAVA name information is returned in the returned library param-
class to register. eter. The following table shows the format of the returned
library parameter when JAVA class file view information is
Program type
registered. For more information on the fields, see “Field
INPUT; CHAR(10)
Descriptions.”
The type of program for which a view is to be registered.
This is the object type of the program object. The valid Offset
values are:
Dec Hex Type Field
*PGM ILE or OPM program 0 0 BINARY(4) Bytes returned
*SRVPGM ILE service program
4 4 BINARY(4) Bytes available
*CLASS JAVA class file
8 8 BINARY(4) Offset to class path name
Module name
C C BINARY(4) Length of class path name
INPUT; CHAR(10) or BINARY(4)
CHAR(*) Class path name
The format of this parameter is dependent on the
program type parameter. If the program type is *PGM or
*SRVPGM, the format of this parameter is as follows:
Field Descriptions
The name of a module for which a view is to be reg-
istered. The module name should be left-justified. Bytes available. The number of bytes available to be
The module name parameter must be specified as returned in the returned library parameter. If the bytes avail-
all blanks for OPM programs. able value is larger than the bytes provided value passed in
the module name parameter, the API should be called again
Information for this parameter is available by using with a value that is at least as large as the bytes available. If
the Retrieve Module Views API to retrieve available the space provided is not large enough, the string space is
module names for a specified program. filled with as many characters of the class path name as will
If the program type is *CLASS, the format of this param- fit.
eter is as follows:
Bytes returned. The number of bytes returned in the
The module name parameter must contain a 4-byte returned library parameter.
binary field. This field contains the number of bytes
provided in the returned library parameter for Class path name. The path name of the file that contains
returned JAVA class path name information. The the class file that was retrieved.
value specified in this parameter must be at least 8
Length of class path name. The length of the class path
bytes.
name returned.

Chapter 17. Debugger APIs 17-21

Remove Breakpoint (QteRemoveBreakpoint) API

Offset to class path name. The offset from the start of the View ID
returned library parameter to the class path name. INPUT; BINARY(4)
The identifier of a previously registered view obtained by
Error Messages using the Register Debug View API.
CPF3CF1 E Remove type
Error code parameter not valid. INPUT; CHAR(10)
CPF3CF2 E
Specifies which breakpoints are to be removed. The fol-
Error(s) occurred during running of &1 API.
lowing is allowed:
CPF9541 E Not in debug mode.
CPF9542 E View not found. *PGM All breakpoints in the program or service
CPF9549 E Error addressing API parameter. program specified by view ID are
CPF954F E Module &1 not found. removed.
CPF955F E Program &1 not a bound program.
CPF9562 E Module &1 cannot be debugged. Error code
CPF9584 E OPM program &1 cannot be added to ILE I/O; CHAR(*)
debug environment. The structure in which to return error information. For
CPF9585 E Program &1 already active in OPM debug envi- the format of the structure, see “Error Code Parameter”
ronment. on page 2-6.
CPF9587 E Module name value &1 not valid.
CPF9588 E OPM source cannot be accessed.
CPF9591 E Value specified in module name parameter is
Error Messages
not valid. CPF1938 E Command is not allowed while serviced job is
CPF9592 E Class file not found. not active.
CPF9593 E Not authorized to class file. CPF1939 E Time-out occurred waiting for a reply from the
CPF9594 E JAVA class file not available. serviced job.
CPF9599 E Class file cannot be debugged. CPF1941 E Serviced job has completed. Debug commands
CPF9801 E Object &2 in library &3 not found. are not allowed.
CPF9802 E Not authorized to object &2 in &3. CPF3CF1 E
CPF9803 E Cannot allocate object &2 in library &3. Error code parameter not valid.
CPF9809 E Library &1 cannot be accessed. CPF9541 E Not in debug mode.
CPF9810 E Library &1 not found. CPF9542 E View not found.
CPF9820 E Not authorized to use library &1. CPF9549 E Error addressing API parameter.
CPF9578 E Remove type not valid.

Remove All Breakpoints

(QteRemoveAllBreakpoints) API Remove Breakpoint
(QteRemoveBreakpoint) API

Required Parameter Group:

Required Parameter Group:
1 View ID Input Binary(4)
2 Remove type Input Char(10) 1 View ID Input Binary(4)
3 Error code I/O Char(*) 2 Line number Input Binary(4)
3 Column number Input Binary(4)
Service Program: QTEDBGS 4 Line in statement view Output Binary(4)
5 Error code I/O Char(*)
Threadsafe: No
Service Program: QTEDBGS

The calling program uses the Remove All Breakpoints Threadsafe: No

(QteRemoveAllBreakpoints) API to remove all breakpoints
from a program. All breakpoints in all modules will be
removed, even though only one view in the program is speci- The calling program uses the Remove Breakpoint
fied. It does not matter which view of the program is speci- (QteRemoveBreakpoint) API to remove a breakpoint from a
fied, as long as it is a registered view. location in a registered view. The API will complete normally
whether or not there was actually a breakpoint previously
added to that location.
Required Parameter Group

17-22 AS/400 System API Reference V4R4

 Retrieve Debug Attribute (QteRetrieveDebugAttribute) API

Required Parameter Group

Required Parameter Group:
View ID
INPUT; BINARY(4) 1 View ID Input Binary(4)
The identifier of a previously registered view obtained by 2 Error code I/O Char(*)
using the Register Debug View API.
Service Program: QTEDBGS
Line number
INPUT; BINARY(4) Threadsafe: No

The line in the view ID where the breakpoint is to be

removed. The Remove Debug View (QteRemoveDebugView) API
removes a view of a module that was previously registered
Column number by the Register Debug View API. This API is needed when
INPUT; BINARY(4) a program is to be removed from debug, so that it can be
The column in the line where the breakpoint is to be deleted and recompiled. Once a view is removed from being
removed. debugged, its view number may not be used again.
Note: At this time, column numbers are ignored. If the last registered view of a program is removed, all break-
Column one must be specified. points are removed from that program, and the step state-
Line in statement view ment is disabled if it was active.
OUTPUT; BINARY(4)
The API returns the line number in the statement view Required Parameter Group
where the breakpoint was removed.
View ID
Error code INPUT; BINARY(4)
I/O; CHAR(*) The ID of a view to be removed from debug. This ID
The structure in which to return error information. For was obtained from a previous use of the Register Debug
the format of the structure, see “Error Code Parameter” View API.
on page 2-6.
Error code
I/O; CHAR(*)
Error Messages The structure in which to return error information. For
CPF1938 E Command is not allowed while serviced job is the format of the structure, see “Error Code Parameter”
not active. on page 2-6.
CPF1939 E Time-out occurred waiting for a reply from the
serviced job.
CPF1941 E Serviced job has completed. Debug commands
Error Messages
are not allowed. CPF3CF1 E
CPF3CF1 E Error code parameter not valid.
Error code parameter not valid. CPF3CF2 E
CPF9541 E Not in debug mode. Error(s) occurred during running of &1 API.
CPF9542 E View not found. CPF9541 E Not in debug mode.
CPF9549 E Error addressing API parameter. CPF9542 E View not found.
CPF9567 E Column number not valid. CPF9549 E Error addressing API parameter.
CPF9568 E Line number not valid.

Retrieve Debug Attribute

Remove Debug View (QteRetrieveDebugAttribute) API
(QteRemoveDebugView) API
Required Parameter Group:

1 Debug attribute Input Char(10)

2 Attribute value Output Char(10)
3 Error code I/O Char(*)

Service Program: QTEDBGS

Threadsafe: No

Chapter 17. Debugger APIs 17-23

Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API

The Retrieve Debug Attribute (QteRetrieveDebugAttribute) *YES Allow OPM programs that have source
API is used to retrieve the attributes of the source debug debug data to be debugged by using the
session. These attributes may be any of the following: ILE debug APIs.
Ÿ Default attributes established when the debug session
*NO Do not allow OPM programs to be
debugged by using the ILE debug APIs.
was started
Ÿ Attributes changed with the Set Debug Attribute API Error code
I/O; CHAR(*)
Ÿ Attributes changed by the Change Debug (CHGDBG)
command The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
The attributes of the debug environment cannot be retrieved on page 2-6.
unless the job is currently in debug mode.
Error Messages
Required Parameter Group CPF3CF1 E
Debug attribute Error code parameter not valid.
INPUT; CHAR(10) CPF3CF2 E
Error(s) occurred during running of &1 API.
The name of the debug environment attribute that is
CPF9541 E Not in debug mode.
retrieved. The valid values for this parameter are:
CPF9549 E Error addressing API parameter.
*UPDPROD Retrieves the value of the update pro- CPF9559 E Debug attribute parameter not valid.
duction files attribute.
*DEBUGJOB Retrieves an indicator of which job is
being debugged. Retrieve Debugged Threads
*OPMSRC Retrieves the value of the OPM source (QteRetrieveDebuggedThreads) API
debug attribute.

Attribute value
OUTPUT; CHAR(10) Required Parameter Group:

The current value of the attribute identified in the debug 1 Receiver variable Output Char(*)
attribute parameter. 2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8)
When the debug attribute parameter contains 4 Thread array Input Array of
*UPDPROD, the attribute value parameter can have one Char(8)
of the following values: 5 Number of threads Input Binary(4)
6 Error code I/O Char(*)
*YES Allow the updating of production files
while in debug mode. Service Program: QTETHRD
*NO Do not allow the updating of production
files while in debug mode. Threadsafe: No

When the debug attribute parameter contains

*DEBUGJOB, the attribute value parameter can have The Retrieve Debugged Threads
one of the following values: (QteRetrieveDebuggedThreads) API retrieves information for
threads being debugged.3 Information about the requested
*LOCAL The debug session is debugging pro-
threads is returned in the receiver variable. This allows the
grams that run in the job in which this API
writer of a debugger to maintain and control a list of threads
is running.
that are being debugged. If this API is processed when
*REMOTE The debug session is debugging pro-
threads are active, the information returned by the API may
grams that run in the job specified in the
no longer be accurate. Check the job status flag to see what
Start Service Job (STRSRVJOB)
state the job was in when the API was processed.
command.

When the debug attribute parameter contains Threads debugging is supported if a service job is used to
*OPMSRC, the attribute value parameter can have one debug a job that was spawned by native threads support. If
of the following values: this is not the debug environment present when this API is
called, a CPF958B error is returned.

3 A job may have several threads, each of which is debugged if the job is debugged. By default, the current thread is the initial thread of the
debugged job or the thread at a debug stop.

17-24 AS/400 System API Reference V4R4

 Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API

Authorities and Locks *ENABLE Thread debug information for all enabled
threads is returned.
None *DISABLE Thread debug information for all disabled
threads is returned.

Required Parameter Group Number of threads

INPUT; BINARY(4)
Receiver variable
OUTPUT; CHAR(*) The number of thread identifiers provided in the thread
array parameter. The number of threads parameter
The receiver variable that receives the information must be greater than zero or minus one. If it has a
requested. You can specify the size of this area to be value of minus one, the first and only thread array
smaller than the format requested as long as you specify parameter must be a special value. If it is greater than
the length parameter correctly. As a result, the API zero, the number specified is the number of thread array
returns only the data the area can hold. For more infor- parameters that must be provided.
mation, see “Format of Receiver Variable.” Entries are
only returned in their entirety. The API never returns Error code
anything less. If there is not enough space for the entire I/O; CHAR(*)
entry, that entry is not returned and bytes available and The structure in which to return error information. For
bytes returned are not equal. the format of the structure, see “Error Code Parameter”
Length of receiver variable on page 2-6.
INPUT; BINARY(4)
The length of the receiver variable. The length of Format of Receiver Variable
receiver variable parameter may be specified up to the
size of the receiver variable specified in the user The following receiver variable formats are returned based
program. If the length of receiver variable parameter on the format name parameter:
specified is larger than the allocated size of the receiver
variable in the user program, the results are not predict- THDL0100 Format: The following table shows the format
able. The minimum length is 8 bytes. of the receiver variable for the THDL0100 format. For more
information on the fields, see “Field Descriptions” on
Format name page 17-26.
INPUT; CHAR(8)
The content and format of the information returned in the Offset
receiver variable. The possible format names are: Dec Hex Type Field

THDL0100 Basic thread debug information. 0 0 BINARY(4) Bytes returned

THDL0200 Extended thread debug information. 4 4 BINARY(4) Bytes available

Thread array 8 8 CHAR(1) Job status flag

INPUT; ARRAY OF CHAR(8) 9 9 CHAR(3) Reserved
The thread identifiers (IDs) for which debug information 12 C BINARY(4) Offset to thread records
is returned. In the thread array parameter, thread IDs 16 10 BINARY(4) Number of thread records
are specified and debug information about the requested
20 14 BINARY(4) Size of thread record
threads is returned in the receiver variable. Each thread
identifier in the thread array is 8 bytes long. The CHAR(*) Reserved
number of thread identifiers is specified in the number of Note: The following fields repeat the number of times specified
threads parameter. in the number of thread records field.
If the number of threads parameter is minus one, the CHAR(8) Thread ID
first thread array parameter must be a special value. In CHAR(1) Current thread flag
this case, all other thread array parameters are ignored.
CHAR(1) Initial thread flag
Valid special values are:
CHAR(1) Thread run state
*ALL Thread debug information for all threads
CHAR(1) Thread debug status
is returned.
*CURRENT Thread debug information for the current
thread is returned. THDL0200 Format: The following table shows the format
*INITIAL Thread debug information for the initial of the receiver variable for the THDL0200 format. For more
thread is returned. information on the fields, see “Field Descriptions” on
page 17-26.

Chapter 17. Debugger APIs 17-25

Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API

Line in statement view stopped in. If the thread is stopped

Offset
in a module that has been registered under debug, this is the
Dec Hex Type Field line number in the module's statement view where the thread
0 0 BINARY(4) Bytes returned is stopped. See the statement view ID stopped in field for
4 4 BINARY(4) Bytes available more information. This field is only applicable for the current
thread. If the thread being returned is not the current thread
8 8 CHAR(1) Job status flag then this field will contain a -1.
9 9 CHAR(3) Reserved
Number of thread records. The number of thread records
12 C BINARY(4) Offset to thread records
that are returned in the receiver variable. Each record has
16 10 BINARY(4) Number of thread records the same format, and is repeated in the receiver variable.
20 14 BINARY(4) Size of thread record
Offset to thread records. The offset in bytes from the start
CHAR(*) Reserved
of the receiver variable to the first requested thread informa-
Note: The following fields repeat the number of times specified tion record.
in the number of thread records field.
CHAR(8) Thread ID Reserved. An ignored field.
CHAR(1) Current thread flag Size of thread record. The number of bytes occupied by
CHAR(1) Initial thread flag each thread record.
CHAR(1) Thread run state
Statement view ID stopped in. The view ID of a previously
CHAR(1) Thread debug status registered debug statement view. It is the statement view ID
CHAR(3) Reserved of the highest module found on the call stack that has been
registered under debug. If no statement views on the stack
CHAR(1) Top of stack flag
are registered, the thread is not stopped by debug, or if the
BINARY(4) Statement view ID stopped thread is not the current thread a value of -1 is returned.
in
BINARY(4) Line in statement view Thread debug status. The debug status of the thread.
stopped in 0 The thread is disabled.
1 The thread is enabled.

Field Descriptions Thread ID. This is an 8-byte thread handle assigned by the
system.
Bytes available. The number of bytes of data available to
be returned to the user. Thread run state. The debug run status of the thread.

Bytes returned. The number of bytes of data returned to 0 The thread is running.
the user. 1 The thread is currently stopped at a break-
point, step, watch or unmonitored exception.
Current thread flag. Whether the thread is the current When this happens all other threads are
thread or not. Possible values are: halted.
2 This is a thread that was halted by debug
0 The thread is not the current thread.
because of a debug stop that occurred in one
1 The thread is the current thread.
of the debugged job's threads. The reason for
Initial thread flag. Whether the thread is the initial thread or stopping or halting all threads is to provide a
not. Possible values are: static debugging environment.

0 The thread is not the initial thread. Top of stack flag. Whether the stopped view ID is at the
1 The thread is the initial thread. top of the call stack or not. Possible values are:

Job status flag. The status of the job when the API was blank This is not the current thread. This field is
processed. only applicable for the current thread.
0 The view ID is not at the top of the call stack.
0 The job is stopped by debug. The information 1 The view ID is at the top of the call stack.
returned by this API is accurate.
1 The job is running and has not been stopped
by debug (for example, breakpoint, step, Error Messages
watch, or unmonitored exception). If threads CPF3C19 E
are running it is not possible for debug to Error occurred with receiver variable specified.
present a stable debugging environment. The
information returned by this API may no
longer be accurate.

17-26 AS/400 System API Reference V4R4

 Retrieve Module Views (QteRetrieveModuleViews) API

CPF3C1E E The module name parameter must be specified as either

Required parameter &1 omitted. *ALL or blanks for OPM programs. The statement view and
CPF3C21 E a source view (or the statement view and a listing view) are
Format name &1 is not valid. always returned. The module name field is returned as
CPF3C24 E blanks.
Length of the receiver variable is not valid.
CPF3CF1 E This API also supports JAVA class file debug views. In this
Error code parameter not valid. case the program type parameter must be *CLASS and the
CPF3CF2 E qualified program name parameter must be a null-terminated
Error(s) occurred during running of &1 API. JAVA class file name. The class path name of the file that
CPF9541 E Not in debug mode. contains the JAVA class file is returned in the returned library
CPF9549 E Error addressing API parameter. name parameter. For JAVA, the module name parameter
CPF958A E Thread &1 not found. must be specified as a binary field that contains the number
CPF958B E Threads debugging not supported. of bytes provided in the returned library name field for JAVA
CPF958C E class path name information.
Number of threads not valid.
Information returned by the Retrieve Module Views API is
CPF958E E Thread array special value not valid.
used by the calling program as input parameters to the Reg-
CPF9872 E Program or service program &1 in library &2
ister Debug View API. Every module returned has at least
ended. Reason code &3.
one view associated with it. This is the statement view. It
can be assumed that any additional views returned have text
associated with them, and source debug can be done on
Retrieve Module Views these modules.
(QteRetrieveModuleViews) API
Authorities
Required Parameter Group:
The authorities required are dependent on the program type
1 Receiver variable Output Char(*) parameter. If the program type is *PGM or *SRVPGM, the
2 Length of receiver variable Input Binary(4) authorities are as follows:
3 Format name Input Char(8)
Program Authority
4 Qualified program name Input Char(20)
or Char(*)
Either *SERVICE and *USE, or *CHANGE
5 Program type Input Char(10) Library Authority
6 Module name Input Char(10) *USE
or
Binary(4) If the program type is *CLASS, the authorities are as follows:
7 Returned library name Output Char(10)
Class File Authority
or Char(*)
*R
8 Error code I/O Char(*)

Service Program: QTEDBGS Required Parameter Group

Threadsafe: No Receiver variable
OUTPUT; CHAR(*)
The Retrieve Module Views (QteRetrieveModuleViews) API A variable that is to receive the information requested.
is used to return a list of modules and views associated with You can specify the size of this area to be smaller than
a specified program to the caller of the API. The list includes that needed to hold the information. In this case, only
all of the following: part of the information is returned. However, the number
of bytes that the API needs to return all of the informa-
Ÿ All modules bound to the program that can be debugged
tion is still returned.
Ÿ Every view (by number and type) that was created by
the compiler when the module object was created Length of receiver variable
INPUT; BINARY(4)
Ÿ Views created by the OPM RPG, OPM COBOL, and
OPM CL compilers using the *SRCDBG and *LSTDBG The length of the receiver variable. The minimum length
options is 8 bytes.

Ÿ Views created by the AS/400 JAVA language support It is suggested that a length of 8 be passed to the API,
which fills in the first two fields of the receiver variable.
If you specify a module name, a list of views for that module One of the fields, bytes available, indicates how much
is returned. If you specify *ALL for the module name, the list
includes all modules for a given program.

Chapter 17. Debugger APIs 17-27

Retrieve Module Views (QteRetrieveModuleViews) API

space must be provided. This space can then be parameter for returning JAVA class path name infor-
obtained, and a second call to the API can be made. mation. The value specified in this parameter must
be at least 8 bytes.
Format name
INPUT; CHAR(8) Returned library name
OUTPUT; CHAR(10) or CHAR(*)
The content and format of the module view information
that is returned. The only valid value for this parameter The format of this parameter is dependent on the
is: program type parameter. If the program type is *PGM or
*SRVPGM, the format of this parameter is OUTPUT
VEWL0100 Module view information. For more infor-
CHAR(10) as follows:
mation, see “VEWL0100 Format.”
The library where the program was found. This is
Qualified program name
useful when *LIBL or *CURLIB is specified for the
INPUT; CHAR(20) or CHAR(*)
program library.
The format of this parameter is dependent on the
If the program type is *CLASS, the format of this param-
program type parameter. If the program type is *PGM or
eter is OUTPUT CHAR(*) as follows:
*SRVPGM, the format of this parameter is as follows:
Class path name information for the requested class
The name of a program about which module and
file. For more information, see “Format of JAVA
view information is listed. The first 10 characters
Returned Library Name Parameter” on page 17-29.
contain the program name. The second 10 charac-
ters contain the name of the library where the Error code
program can be located. Both entries must be left- I/O; CHAR(*)
justified. The following special values may be used
The structure in which to return error information. For
for the library name:
the format of the structure, see “Error Code Parameter”
*CURLIB The job's current library. on page 2-6.
*LIBL The library list.

If the program type is *CLASS, the format of this param- VEWL0100 Format
eter is as follows:
The following table shows the format of the receiver variable
The null-terminated class file name of the JAVA for the VEWL0100 format. For more information on the
class. fields, see “Field Descriptions.”
Program type
INPUT; CHAR(10) Offset

The type of program for which a view is to be registered. Dec Hex Type Field
This is the object type of the program object. The allow- 0 0 BINARY(4) Bytes returned
able values are:
4 4 BINARY(4) Bytes available
*PGM ILE or OPM program 8 8 BINARY(4) Number of elements
*SRVPGM ILE service program
Note: The following fields repeat once for each element.
*CLASS JAVA class file name
CHAR(10) Module name
Module name
CHAR(10) View type
INPUT; CHAR(10) or BINARY(4)
CHAR(20) Compiler ID
The format of this parameter is dependent on the
CHAR(10) Main indicator
program type parameter. If the program type is *PGM or
*SRVPGM, the format of this parameter is as follows: CHAR(13) View timestamp

A module name or *ALL (*ALL refers to all modules CHAR(50) View description
in the program). The module name parameter must CHAR(3) Reserved
be specified as either *ALL or blanks for OPM pro- BINARY(4) View number
grams.
BINARY(4) Number of views
If the program type is *CLASS, the format of this param-
eter is as follows: All views for a module are listed together in the receiver vari-
able. The number of views field contains the total number of
A 4-byte binary field. This field contains the number
views for the module. The views are contiguous.
of bytes provided in the returned library name

17-28 AS/400 System API Reference V4R4

 Retrieve Module Views (QteRetrieveModuleViews) API

Field Descriptions used when you specify a specific view to register using the
Register Debug View API.
Bytes available. The number of bytes of data available to
be returned to the user. View timestamp. The timestamp indicating when the view
was created. It has the format of the American National
Bytes returned. The number of bytes of data returned to Standard timestamp.
the user.
View type. The type of view. The view type can be one of
Compiler ID. The ID of the compiler that generated this the following values:
view. For unique identification the first 4 bytes are used as *TEXT This is a view where text comes from files or
follows. text supplied by the processor.
x'00050000' ILE C *LISTING This is a view where text comes entirely from
x'00050001' CSET C++ cooperative compiler text supplied by the processor.
x'00060000' ILE CL *STATEMENT
x'00060001' OPM CL This is a view consisting of statement identi-
x'00070000' OPM COBOL fiers. All modules have a statement view.
x'00070001' ILE COBOL
x'00170001' OPM RPG
x'00170002' ILE RPG
Format of JAVA Returned Library Name
x'001D0000' JAVA Parameter

Main indicator. Whether the module is a main module When the program type parameter is *CLASS, class path
(entry point) for the program. The main indicator field can name information is returned in the returned library name
have one of the following values: parameter. The following table shows the format of the
returned library name parameter when the JAVA class file
*MAIN Module is a main module view information is retrieved. For more information on the
*NOMAIN Module is not a main module fields, see “Field Descriptions.”
There is at most one main module per program. Service
Offset
programs contain no main entry point. *MAIN is always
returned for OPM programs. For JAVA class files *MAIN is Dec Hex Type Field
returned if the class file has a main procedure. Otherwise, 0 0 BINARY(4) Bytes returned
*NOMAIN is returned for JAVA.
4 4 BINARY(4) Bytes available
Module name. The name of the module for this list entry. 8 8 BINARY(4) Offset to class path name
For OPM programs and JAVA class files, the module name C C BINARY(4) Length of class path name
is returned as blanks.
CHAR(*) Class path name
Number of elements. The number of elements returned in
the receiver variable. Each element has the same format,
and it is repeated in the receiver variable. If the number of Field Descriptions
elements is zero and the receiver variable has room for at
least one element, the program has no views in the module Bytes available. The number of bytes available to be
requested. If the module requested is *ALL, zero elements returned in the returned library name parameter. If the bytes
indicate the program cannot be debugged. For OPM pro- available value is larger than the bytes provided value
grams, a CPF9584 error code is returned, instead of a zero passed in the module name parameter, the API should be
number of elements value, if the program cannot be called again with a value that is at least as large as the bytes
debugged. For class files, a CPF9599 error code is available. If the space provided is not large enough, the
returned, instead of a zero number of elements value, if the string space is filled with as many characters of the class
program cannot be debugged. path name as will fit.

Number of views. The number of views in this module Bytes returned. The number of bytes returned in the
listed in the receiver variable returned library name parameter.

Reserved. An ignored field. Class path name. The path name of the file that contains
the class file that was retrieved.
View description. A character string that describes the
view. Length of class path name. The length of the class path
name returned.
View number. A number that identifies a view within a
module. Each view has a unique view number, which is Offset to class path name. The offset from the start of the
returned library name parameter to the class path name.

Chapter 17. Debugger APIs 17-29

Retrieve Program Variable (QTERTVPV) API

Error Messages Restriction: This API is valid only in debug mode and
supports original program model (OPM) programs only. It
CPF3C21 E
cannot be used if the user is servicing another job and that
Format name &1 is not valid.
job is on a job queue, or is held, suspended, or ended.
CPF3C24 E
Length of the receiver variable is not valid.
CPF3CF1 E Required Parameter Group
Error code parameter not valid.
Receiver variable
CPF3CF2 E
OUTPUT; CHAR(*)
Error(s) occurred during running of &1 API.
CPF9541 E Not in debug mode. The variable that is to receive the information requested.
CPF9549 E Error addressing API parameter. The minimum size for this area is 8 bytes. If the size of
CPF954F E Module &1 not found. this area is smaller than the available information, the
CPF955F E Program &1 not a bound program. API returns only the data that the area can hold.
CPF9584 E OPM program &1 cannot be added to ILE See “Format of Receiver Variable” on page 17-31 for
debug environment. details about the format.
CPF9585 E Program &1 already active in OPM debug envi-
ronment. Length of receiver variable
CPF9587 E Module name value &1 not valid. INPUT; BINARY(4)
CPF9591 E Value specified in module name parameter is The length of the receiver variable. If this value is larger
not valid. than the actual size of storage allocated for the receiver
CPF9592 E Class file not found. variable, the results are not predictable. The minimum
CPF9593 E Not authorized to class file. length is 8 bytes.
CPF9594 E JAVA class file not available.
CPF9599 E Class file cannot be debugged. Program variable
CPF9801 E Object &2 in library &3 not found. INPUT; CHAR(132)
CPF9802 E Not authorized to object &2 in &3. The name of the program variable whose value is to be
CPF9803 E Cannot allocate object &2 in library &3. retrieved. Possible values follow:
CPF9809 E Library &1 cannot be accessed.
CPF9810 E Library &1 not found. *CHAR This special value is specified instead of
CPF9820 E Not authorized to use library &1. a variable name if a basing pointer is also
specified. This special value returns a
character view of the area addressed by
Retrieve Program Variable (QTERTVPV) a pointer.
API Program variable name
The name of the program variable. For
information about program variables, see
the topic on program-variable description
Required Parameter Group:
in “Appendix C” of the CL Reference
1 Receiver variable Output Char(*) (Abridged) book.
2 Length of receiver variable Input Binary(4)
Basing pointer
3 Program variable Input Char(132)
4 Basing pointer Input Array(5) of INPUT; ARRAY(5) of CHAR(132)
Char(132) In languages where a program variable may be based
5 Starting position Input Binary(4) on a pointer variable, you can specify the basing
6 Length of string Input Binary(4)
pointers for the variable to be retrieved. Up to five
7 Output format Input Char(10)
8 Program Input Char(10) basing pointers may be specified. If the basing pointer
9 Recursion level Input Binary(4) is an element in an array, the subscript representing an
10 Error code I/O Char(*) element in the array must be specified. Up to 132 char-
acters can be specified for one basing pointer name. If
Threadsafe: No no basing pointer is specified, then the structure must be
initialized to blanks. If one or more basing pointers are
specified, then the subsequent array entries must be ini-
The Retrieve Program Variable (QTERTVPV) API retrieves
tialized to blanks. For more information on basing
the current value of one program variable in a program that
pointers, refer to the topic on basing-pointer description
is being debugged. The information is returned to the calling
in “Appendix C” of the CL Reference (Abridged) book.
program in a receiver variable. The amount of returned infor-
mation is limited to the size of the receiver variable. This Starting position
information is similar to the information returned using the INPUT; BINARY(4)
Display Program Variable (DSPPGMVAR) command.
For string variables only, the starting position in the

17-30 AS/400 System API Reference V4R4

 Retrieve Program Variable (QTERTVPV) API

string from which its value is being retrieved. For a bit Error code
string, the value is the starting bit position. For a char- I/O; CHAR(*)
acter string, the value is the starting character position.
The structure in which to return error information. For
This parameter is ignored on nonstring variables but the format of the structure, see “Error Code Parameter”
must be initialized to any number greater than 0. on page 2-6.

Length of string
INPUT; BINARY(4) Format of Receiver Variable
For string variables only, the length of the string The following table shows the information supplied in the
retrieved, starting at the position specified by the start receiver variable parameter. For more information on each
parameter. For a bit string, this value is the number of field, see “Field Descriptions” on page 17-33.
bits to retrieve. For a character string, this value is the
number of characters to retrieve.
Offset
0 The value of the string variable is Dec Hex Type Field
retrieved to the end of the string or
0 0 BINARY(4) Bytes returned
retrieved for 200 bytes, whichever is less.
If the string variable has a maximum 4 4 BINARY(4) Bytes available
length of zero, only 0 is allowed. 8 8 BINARY(4) Variable type
Retrieve length
12 C BINARY(4) Data error
The length of data to retrieve.
16 10 POINTER Pointer to variable
This parameter is ignored on nonstring
32 20 BINARY(4) Bit position
variables but must be initialized to any
number 0 or greater. 36 24 BINARY(4) Variable length
40 28 BINARY(4) Variable precision
Output format
INPUT; CHAR(10) 44 2C BINARY(4) Number of array dimensions

The format in which the value is to be returned. 48 30 BINARY(4) Number of array elements
returned
*CHAR The value of the program variable is
52 34 ARRAY(15) of Subscript bounds
returned in character form. BINARY(4)
*HEX The value of the program variable is
172 AC BINARY(4) Element length
returned in hexadecimal form.
176 B0 BINARY(4) Character string length
Program
INPUT; CHAR(10) 180 B4 CHAR(64) Reserved
244 F4 CHAR(*) Data retrieved
The name of the program that contains the program vari-
able to be retrieved.
The following tables show the information supplied in the
*DFTPGM The program currently specified as the data retrieved field. The variable type field, which is
default program will be used. enclosed in parentheses, indicates which table is used.
Program name
The name of the program whose program Data for Binary Numeric (1)
variable is retrieved.
Offset
Recursion level
INPUT; BINARY(4) Dec Hex Type Field

The recursion level of the program that contains the 244 F4 CHAR(7) Message ID
program variable. 251 FB CHAR(1) Reserved

0 The last (most recent) call of the program 252 FC CHAR(*) Variable value
is the one from which the automatic
program variable is retrieved. Data for Floating Point (2)
n The number of the recursion level of the
program from which the automatic Offset
program variable is retrieved.
Dec Hex Type Field
This parameter is ignored on static variables but must be 244 F4 CHAR(7) Message ID
initialized to any number 0 or greater.
251 FB CHAR(1) Reserved

Chapter 17. Debugger APIs 17-31

Retrieve Program Variable (QTERTVPV) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
252 FC CHAR(*) Variable value 244 F4 CHAR(7) Message ID
251 FB CHAR(1) Reserved
Data for Zoned Decimal (3) 252 FC CHAR(*) Variable value

Offset
Data for Space Pointer (9)
Dec Hex Type Field
244 F4 CHAR(7) Message ID Offset
251 FB CHAR(1) Reserved Dec Hex Type Field
252 FC CHAR(*) Variable value 244 F4 CHAR(7) Message ID
251 FB CHAR(1) Reserved
Data for Packed Decimal (4) 252 FC CHAR(8) Hexadecimal offset
260 104 CHAR(8) Reserved
Offset
268 10C CHAR(30) Object addressed by pointer
Dec Hex Type Field
298 12A CHAR(10) Library name
244 F4 CHAR(7) Message ID
308 134 CHAR(8) Object type
251 FB CHAR(1) Reserved
252 FC CHAR(*) Variable value
Data for Data Pointer (10)

Data for Fixed Character (5) Offset

Dec Hex Type Field
Offset
244 F4 CHAR(7) Message ID
Dec Hex Type Field
251 FA CHAR(1) Reserved
244 F4 CHAR(7) Message ID
252 FB CHAR(8) Hexadecimal offset
251 FB CHAR(1) Reserved
260 104 CHAR(30) Object addressed by pointer
252 FC CHAR(*) Variable value
290 122 CHAR(10) Library name

Data for Varying Character (6) 300 12C CHAR(8) Object type
308 134 BINARY(4) Data type
Offset 312 138 BINARY(4) Data length
Dec Hex Type Field 316 13C BINARY(4) Data precision
244 F4 CHAR(7) Message ID 320 140 BINARY(4) Data string length
251 FB CHAR(1) Reserved 324 144 BINARY(4) Element length
252 FC BINARY(4) Varying character length 328 148 CHAR(*) Data
256 100 CHAR(*) Variable value
Data for Instruction Definition List (11)
Data for Fixed Bit (7)
Offset
Offset Dec Hex Type Field
Dec Hex Type Field 244 F4 CHAR(7) Message ID
244 F4 CHAR(7) Message ID 251 FB CHAR(1) Reserved
251 FB CHAR(1) Reserved 252 FC CHAR(8) Instruction number
252 FC CHAR(*) Variable value 260 104 CHAR(8) Reserved
268 10C CHAR(30) Object addressed by pointer
Data for Unsigned Binary (8)
298 12A CHAR(10) Library name
308 134 CHAR(8) Object type

Data for System Pointer (12)

17-32 AS/400 System API Reference V4R4

 Retrieve Program Variable (QTERTVPV) API

Offset Field Descriptions

Dec Hex Type Field
Array of messages. An array of the number of message
244 F4 CHAR(7) Message ID IDs is returned.
251 FB CHAR(1) Reserved
Authorization. Pointer authorization.
252 FC CHAR(16) Authorization
268 10C CHAR(30) Object addressed by pointer Bit position. The starting bit position, 1–8, for bit strings
returned in *HEX format. The least significant bit is 1 and 8
298 12A CHAR(10) Library name
the most significant bit. This field will be initialized to 0 for
308 134 CHAR(8) Object type any other variable type.

Bytes available. The number of bytes of data available to

Data for Machine Space Pointer (13)
be returned. All available data is returned if enough space is
provided.
Offset
Dec Hex Type Field Bytes returned. The number of bytes of data returned.
244 F4 CHAR(7) Message ID
Character string length. For output format *CHAR, this
251 FB CHAR(1) Reserved value is the length of the returned character string. For
252 FC CHAR(8) Hexadecimal offset output format *HEX, this value is initialized to 0. For fixed
character, varying character, and fixed bit variables this field
260 104 CHAR(8) Reserved
contains the actual length of the data returned for *CHAR
268 10C CHAR(30) Object addressed by pointer and *HEX output formats. For pointers and exception moni-
298 12A CHAR(10) Library name tors this field is 0.
308 134 CHAR(8) Object type
Comparison string. The specified comparison string.

Data for Exception Description (14) Comparison string length. The length of the comparison
string. This value is 0 if a value is not specified.
Offset
Control. Exception monitor control action. The following
Dec Hex Type Field values may be returned:
244 F4 CHAR(7) Message ID
X'00' Default
251 FB CHAR(1) Reserved X'01' Off
252 FC CHAR(1) Control X'02' Resignal
X'04' Defer
253 FD CHAR(1) Handler type
X'05' Handle
254 FE CHAR(8) Instruction number
262 106 CHAR(10) Program name Data. The data addressed by the pointer. This field is
returned in the corresponding output format for the variable
272 110 CHAR(10) Library name
type (data type).
282 11A CHAR(2) Reserved
Data error. Whether an error was returned when returning a
284 11C BINARY(4) Compare string length
variable.
288 120 CHAR(28) Compare string
0 No errors were returned with the variable
316 13C CHAR(1) Job log
data.
317 13D CHAR(3) Message type 1 One or more errors were returned with the
320 140 BINARY(4) Number of message IDs variable data.
324 144 ARRAY(*) of Array of messages Data length. The length of the data addressed by the
CHAR(7) pointer. This is the same value as in the variable length field
in the header.

Data precision. The precision of the data addressed by the

pointer. This is the same value as in the variable precision
field in the header.

Data retrieved. If an error is encountered while retrieving

the data, CPD messages may be returned instead of the var-
iable data. The structure of this parameter is dependent on

Chapter 17. Debugger APIs 17-33

Retrieve Program Variable (QTERTVPV) API

the object type. The format of the data depends on the vari- Pointer to variable. Pointer to variable, if applicable. For
able type field. example, a pointer is not returned to a variable of type
machine space pointer or for an exception description. For
Data string length. The string length of the data addressed system security reasons a pointer is not returned if the secu-
by the pointer. This is the same value as in the variable rity level is 50 and if the job using the API is servicing and
string length field in the header. debugging another job.

Data type. The type of data addressed by the pointer. This Program name. External handler program name or X'0' for
is the same value as in the variable type field in the header. an internal monitor.

Element length. The length of the data element returned. If Reserved. An ignored field.
this field is 0, each element can be a different length and the
user must go to the element to get the element length. Subscript bounds. The subscript lower bounds and sub-
script upper bounds for each array dimension. If the variable
Handler type. Exception monitor handler type. is not an element of an array, or the dimension is not used,
'00'X External handler the subscript lower and upper bounds are initialized to 0.
'01'X Call internal handler
Varying character length. The actual length of the varying
'02'X Branch point handler
character string.
Hexadecimal offset. Hexadecimal offset of the space
Variable length. The length of the variable value. For bit
pointed to by the space or machine space pointer.
strings, this value is the number of bits. For packed and
Instruction number. The exception handler instruction zoned variables, this value is the number of digits. For
number for a monitor with an internal handler or X'0' for an pointers and exception monitors this field is 0. For all other
external handler. variable types, this value is the number of bytes.

Job log. Put messages on job log. Variable precision. The number of decimal digits or frac-
tional digits for zoned and packed variables. For any other
0 No variable type, this field will be initialized to 0.
1 Yes
Variable type. The following are the possible variable types:
Library name. The library containing the object addressed
by the pointer, *LIBL, or X'0' for internal monitors. 1 Binary numeric
2 Floating point
Message ID. If an error was received with the variable data, 3 Zoned decimal
this field contains the diagnostic message ID. If no error was 4 Packed decimal
received with the variable's data, this field contains blanks. 5 Fixed character
6 Varying character
Message type. Message types being monitored. 7 Fixed bit
100 Escape 8 Unsigned binary
010 Notify 9 Space pointer
001 Status 10 Data pointer
11 Instruction definition list
More than one message type can be monitored at a time. If 12 System pointer
the first and third characters are 1's, then escape and status 13 Machine space pointer
messages are being monitored. 14 Exception description

Number of array dimensions. If the variable is an array or Variable value. The value of the variable being retrieved.
an element of an array, this field is the number of array The following messages may be returned in this field:
dimensions. Otherwise, this field is initialized to 0.
CPD1901 Variable contains invalid decimal data.
Number of array elements returned. If the variable is an
CPD1902 Pointer to be displayed not set to any
address.
array, this field is the number of array elements returned.
Otherwise, this field is initialized to 0.
CPD1903 Floating-point value displayed is not exact.
CPD1904 Object not found for system pointer with initial
Number of message IDs. The number of message identi- value.
fiers being monitored. CPD1905 Variable not found for data pointer with initial
value.
Object addressed by pointer. The fully qualified name of CPD1906 Variable to be displayed contained in deleted
the object addressed by the pointer. object.
CPD1907 Variable refers to object with freed storage.
Object type. The Machine Interface (MI) type of the object CPD1908 Space addressing error for variable.
addressed by the pointer.

17-34 AS/400 System API Reference V4R4

 Retrieve Statement View (QteRetrieveStatementView) API

CPD1909 Pointer alignment error. Pointer not on Ÿ The number of statement view lines to retrieve
16-byte boundary.
Ÿ A buffer to contain the statement view and related infor-
CPD1910 High-level language (HLL) pointer invalid.
mation
CPD1911 START plus LEN values exceed length of
string.
CPD1913 Space addressing error for variable. Required Parameter Group
CPD1914 Pointer addresses a deleted object.
Receiver variable
OUTPUT; CHAR(*)
Error Messages The receiver variable that receives the information
CPF1902 E No default program exists. requested. You can specify the size of the area to be
CPF1903 E Program &1 not in debug mode. smaller than the format requested as long as you specify
CPF1905 E Starting position parameter is not valid. the length parameter correctly. As a result, the API
CPF1906 E Command is not valid. No programs in debug returns only the data that the area can hold. For more
mode. information, see “Format of Receiver Variable” on
CPF1915 E Length parameter is not valid. page 17-36.
CPF1919 E Recursion level parameter is not valid.
Length of receiver variable
CPF1927 E Output format name not valid.
INPUT; BINARY(4)
CPF1938 E Command is not allowed while serviced job is
not active. The length of the receiver variable provided. The length
CPF1939 E Time-out occurred waiting for a reply from the of receiver variable parameter may be specified up to
serviced job. the size of the receiver variable specified in the user
CPF1941 E Serviced job has completed. Debug commands program. If the length of receiver variable parameter
are not allowed. specified is larger than the allocated size of the receiver
CPF24B4 E Severe error while addressing parameter list. variable specified in the user program, the results are
CPF3C19 E not predictable. The minimum length is 8 bytes.
Error occurred with receiver variable specified.
View ID
CPF3C24 E
INPUT; BINARY(4)
Length of the receiver variable is not valid.
CPF7133 E Variable or basing pointer name missing. The identifier of the previously registered statement view
CPF9549 E Error addressing API parameter. obtained by using the Register Debug View
CPF9872 E Program or service program &1 in library &2 (QteRegisterDebugView) API.
ended. Reason code &3.
Start line number
INPUT; BINARY(4)

Retrieve Statement View The number of the first statement view line that the API
(QteRetrieveStatementView) API is to retrieve. Statement view lines begin at line 1.

Number of lines
INPUT; BINARY(4)
Required Parameter Group:
The number of lines of the statement view to be
1 Receiver variable Output Char(*) retrieved. This number includes the line specified in the
2 Length of receiver variable Input Binary(4) start line number parameter. If fewer lines than
3 View ID Input Binary(4) requested are available, the number of lines placed in
4 Start line number Input Binary(4) the receiver variable may be less than the number speci-
5 Number of lines Input Binary(4) fied. No more than the number of lines specified is
6 Error code I/O Char(*) placed in the receiver variable.
Service Program: QTEDBGS The following special value is supported for this param-
eter:
Threadsafe: No
0 All lines from the start line number to the
end of the statement view should be
The Retrieve Statement View (QteRetrieveStatementView) retrieved.
API is used to retrieve the statement view and related infor-
mation. The statement view information that is retrieved can Error code
be useful for breakpoint processing. The caller must specify I/O; CHAR(*)
the following: The structure in which to return error information. For
Ÿ The registered statement view ID the format of the structure, see “Error Code Parameter”
on page 2-6.
Ÿ The starting statement view line number to be retrieved

Chapter 17. Debugger APIs 17-35

Retrieve Statement View (QteRetrieveStatementView) API

Format of Receiver Variable Offset

Dec Hex Type Field
The receiver variable consists of:
8 8 BINARY(4) Offset to statement proce-
Ÿ A receiver variable header section.
dure information structure
Ÿ A section containing the statement view lines.
Ÿ A section containing information for each procedure in Procedure Information Section: The procedure infor-
the statement view. mation section contains one variable-length data structure for
each procedure in the statement view. The first procedure
Ÿ A string space containing the statement view procedure
information data structure can be accessed by using the first
names.
procedure information offset in the receiver header. Each
Ÿ A section containing offsets to additional information statement view line contains a statement procedure informa-
about individual statement view lines. tion offset that can be used to locate procedure information
Ÿ A section containing additional information about indi- for the statement line. Each procedure information data
vidual statement view lines. structure has the following format.

Ÿ A space containing variable length fields that are refer-

Offset
enced by other returned data sections.
Dec Hex Type Field
Variables containing offsets are used to access statement 0 0 BINARY(4) Offset to next procedure
view data. All offsets are relative to the beginning of the information structure
receiver variable.
4 4 BINARY(4) Procedure dictionary
number
Receiver Variable Header Section: The following table
shows the information supplied in the receiver variable 8 8 BINARY(4) Offset to procedure name
parameter. For more information on each field, see “Field 12 C BINARY(4) Length of procedure name
Descriptions” on page 17-37. 16 10 BINARY(4) Offset to first statement line
range element
Offset
20 14 BINARY(4) Number of statement line
Dec Hex Type Field ranges
0 0 BINARY(4) Bytes returned Note: The following fields are repeated for each statement line
range.
4 4 BINARY(4) Bytes available
BINARY(4) Low line number
8 8 BINARY(4) Offset to first statement
view line BINARY(4) High line number
12 C BINARY(4) Number of lines returned
16 10 BINARY(4) Length of statement view Procedure Name String Space: The procedure name
line string space contains the text of the procedure names in the
module. The procedure name offset in the procedure infor-
20 14 BINARY(4) Offset to first procedure
information structure mation section is used to access a procedure name. The
procedure name length is also contained in the procedure
24 18 BINARY(4) Offset to first statement-
information section. The procedure name is converted to the
view-line additional-
coded character set identifier (CCSID) of the job.
information offset.

Offset
Statement View Section: The statement view is
returned as an array of statement lines. The first statement Dec Hex Type Field
view line can be accessed by using the first view line offset CHAR(*) Procedure name
in the receiver header. The number of lines returned vari-
able in the receiver header is used to tell how many state- Statement-View-Line Additional-Information Offsets
ment lines were returned. The total number of bytes in each
Section: If the compiler supplies it, additional information
line is equal to the line length. Each line has the following
is returned for individual statement view lines. For example,
format.
a statement may have a name associated with it, such as a
block or label name. Each line in the statement view section
Offset has a corresponding offset to additional information for the
Dec Hex Type Field line. Thus, the first offset in this section is used to find the
0 0 BINARY(4) Statement number additional information for the first statement view line
returned. The second offset will reference additional informa-
4 4 BINARY(4) Statement type
tion for the second statement view line returned, and so on.

17-36 AS/400 System API Reference V4R4

 Retrieve Statement View (QteRetrieveStatementView) API

There must be space in the receiver variable for the Field Descriptions
additional-information offsets of all statement view lines
returned or none of the offsets is returned. The presence of Bytes available. The number of bytes of data available to
this section is indicated by a nonzero value in the offset to be returned. All available data is returned if enough space is
first statement-view-line additional-information offset in the provided.
receiver header. If this section is present, there is one offset
for each statement view line returned. If there is additional Bytes returned. The number of bytes of data returned.
information for a statement view line, the additional informa-
tion offset for it is nonzero. Each offset has the following High line number. The high view-line number in the state-
format. ment view of a procedure statement range.

Length of procedure name. The length of the procedure

Offset
name in the procedure string space. For OPM programs the
Dec Hex Type Field procedure name length is set to a value of 1.
Note: The following field is repeated for each statement view
line returned. Length of statement name. The length of the statement
name associated with the statement view line.
0 0 BINARY(4) Offset to statement-view-line
additional information Length of statement view line. The length of each state-
ment view line in the statement view section.
Statement-View-Line Additional-Information
Section: If the compiler supplies it, additional information Low line number. The low view-line number in the state-
is returned for individual statement view lines. For example, ment view of a procedure statement range.
a statement may have a name associated with it, such as a
Number of lines returned. The number of statement view
block or label name. The statement-view-line additional-
lines retrieved by this API. This may be less than the
information section contains one variable-length data struc-
number of lines requested or available if the receiver variable
ture for each statement view line that has additional
is not large enough to hold the number of lines requested.
information associated with it. If there is not enough room in
the receiver variable for all of the additional-information data Number of statement line ranges. The number of state-
structures to be returned, the number that fits is returned. ment view line ranges in the procedure information data
The additional information data structures are referenced by structure.
the offsets in the statement-view-line additional-information
offsets section. Each additional-information data structure Offset to first procedure information structure. The dis-
has the following format. placement from the start of the receiver variable to the first
procedure information data structure in the procedure infor-
Offset mation section. This value is zero when no procedure infor-
Dec Hex Type Field
mation is returned because of insufficient receiver variable
space.
0 0 BINARY(4) Offset to statement name
4 4 BINARY(4) Length of statement name Offset to first statement line range element. The dis-
placement from the start of the receiver variable to the first
statement range element in the procedure information data
Variable Length Field Section: This section contains
structure.
space to return variable length fields. These fields are refer-
enced by other returned data structures through offsets. Offset to first statement view line. The displacement from
Usually, a length field would also be contained within the the start of the receiver variable to the first statement view
same data structure that references a field in this space. line. This value is zero if no statement view lines are
returned because of insufficient receiver variable space.
Offset
Dec Hex Type Field Offset to first statement-view-line additional-information
offset. The displacement from the start of the receiver vari-
CHAR(*) Variable length field
able to the first statement-view-line additional-information
offset. This value is zero if no statement-view-line additional-
information offsets are returned because of insufficient
receiver variable space, or if the compiler does not support
debug data for additional statement view lines.

Offset to next procedure information structure. The dis-

placement from the start of the receiver variable to the next
procedure information data structure. This value is zero

Chapter 17. Debugger APIs 17-37

Retrieve Stopped Position (QteRetrieveStoppedPosition) API

when there are no more procedure information data struc- 14 PATH FALSEIF
tures. 15 PATH WHEN BGN
16 PATH OTHERW
Offset to procedure name. The displacement from the start 17 GOTO
of the receiver variable to the procedure name. This value is 18 POST COMPOUND
zero if the procedure name is not returned because it would
not fit in the procedure string space. Variable length field. A field referenced by an offset in a
returned data structure. The data type is determined by
Offset to statement name. The displacement from the start where it is referenced. For example, a statement name field
of the receiver variable to the statement name that is associ- is a text string.
ated with the statement view line. For example, this could be
a block or label name. This value is zero if the statement
name is not returned because it would not fit in the variable Error Messages
length field section, or because the compiler did not provide CPF3C24 E
a statement name. Length of the receiver variable is not valid.
CPF3CF1 E
Offset to statement procedure information structure. The Error code parameter not valid.
displacement from the start of the receiver variable to appro- CPF3CF2 E
priate procedure information data structure in the procedure Error(s) occurred during running of &1 API.
information section. This value is zero if the procedure infor- CPF9541 E Not in debug mode.
mation for this statement was not returned because of insuffi- CPF9542 E View not found.
cient receiver-variable space. CPF9549 E Error addressing API parameter.
CPF954A E No source text available.
Offset to statement-view-line additional information. The
CPF9563 E Number of lines not valid.
displacement from the start of the receiver variable to the
CPF9564 E Starting line number not valid.
statement-view-line additional-information data structure.
CPF9582 E View is not a statement view.
This value is zero if no statement-view-line additional infor-
mation is returned because of insufficient receiver variable
space, or because there is no additional information for the
statement view line. Retrieve Stopped Position
(QteRetrieveStoppedPosition) API
Procedure dictionary number. The number that uniquely
identifies the procedure in this module. For OPM programs
the procedure dictionary number is set to a value of 0. Required Parameter Group:
Procedure name. The name of the procedure. The proce- 1 Receiver variable Output Char(*)
dure name is converted to the CCSID of the job. For OPM 2 Length of receiver variable Input Binary(4)
programs the procedure name is set to a blank value with a 3 View ID Input Binary(4)
length of 1 byte. 4 Error code I/O Char(*)

Statement number. The number that uniquely identifies the Service Program: QTEDBGS
statement in the procedure. This number is shown on the
compiler listing. For OPM programs the statement number is Threadsafe: No
the same as the machine interface (MI) number.
The Retrieve Stopped Position (QteRetrieveStoppedPosition)
Statement type. The type number of statement produced by
API is used to determine if a module in a program is on the
the compiler. Possible values are as follows:
call stack. It indicates the position in the view at which the
1 INIT CODE program stopped if the program is on the stack. The caller
2 PROC ENTRY must specify a registered view ID. The most recently called
3 PROC EXIT procedure in the specified module is the one whose line is
4 ALLOC returned. If a program is on the stack, the stack is searched
5 STMT from the most recent call backward until a procedure in the
6 ENTRY module is found. The location in that procedure is returned.
7 EXIT
8 MULTIEXIT If no procedure in the identified module is on the stack, a
9 PATH LABEL zero is returned.
10 PATH CALL BGN
11 PATH CALL RET
12 PATH DO BGN
Required Parameter Group
13 PATH TRUEIF

17-38 AS/400 System API Reference V4R4

 Retrieve View File (QteRetrieveViewFile) API

Receiver variable Field Descriptions

OUTPUT; CHAR(*)
The variable that is to receive the information requested. Bytes available. The number of bytes of data available to
You can specify the size of this area to be smaller than be returned. All available data is returned if enough space is
the format requested if you specify the length of receiver provided.
variable parameter correctly. As a result, the API
Bytes returned. The number of bytes of data returned.
returns only the data that the area can hold. For more
information, see “Format of Receiver Variable.” Column number. The column number within the line
Length of receiver variable number specified where the program is stopped in the view
INPUT; BINARY(4) ID. Column numbers can be 1 through 255.

The length of the receiver variable. The minimum length Line number. The line number within the view ID where the
is 8 bytes. program is stopped. This number represents the line number
It is suggested that a receiver variable length be given within the view that corresponds to text retrieved using the
that is large enough to hold one position element. Retrieve View Text API.
Because this normally is the number of elements that
Number of stopped positions. A stopped position consists
are returned, a single call to this API is usually sufficient.
of the line number and column number fields and are
Also, this allows the number of stopped positions field to
repeated this number of times, once for each position avail-
be used to determine whether the program is stopped.
able. If the view is not on the stack, this number is zero. If
If zero elements are returned, the program is not
there is no room in the receiver variable to hold any stopped
stopped in the specified view.
positions, this number is also zero. Therefore, there should
View ID be enough room in the receiver variable to hold at least one
INPUT; BINARY(4) stopped position.
The identifier of a previously registered view obtained Because of program optimization, it is possible for the API
using the Register Debug View API. not to know exactly where the view is stopped. For this
Error code reason, more than one position may be returned.
I/O; CHAR(*)
The structure in which to return error information. For Error Messages
the format of the structure, see “Error Code Parameter” CPF3C24 E
on page 2-6. Length of the receiver variable is not valid.
CPF3CF1 E
Format of Receiver Variable Error code parameter not valid.
CPF3CF2 E
The following table shows the information supplied in the Error(s) occurred during running of &1 API.
receiver variable parameter. For more information on the CPF9541 E Not in debug mode.
fields see, “Field Descriptions.” CPF9542 E View not found.
CPF9548 E Map not available.
Offset CPF9549 E Error addressing API parameter.
Dec Hex Type Field
0 0 BINARY(4) Bytes returned
Retrieve View File (QteRetrieveViewFile)
4 4 BINARY(4) Bytes available API
8 8 BINARY(4) Number of stopped posi-
tions
Note: The following fields are repeated for each stopped posi-
tion.
BINARY(4) Line number
BINARY(4) Column number

Chapter 17. Debugger APIs 17-39

Retrieve View File (QteRetrieveViewFile) API

For more information, see “Format of File Name

Required Parameter Group: Receiver Variable.”

View ID
1 Text descriptor receiver var- Output Char(*)
iable
INPUT; BINARY(4)
2 Length of text descriptor Input Binary(4) The identifier of a previously registered view obtained by
receiver variable using the Register Debug View API.
3 File name receiver variable Output Char(*)
4 Length of file name receiver Input Binary(4) Error code
variable I/O; CHAR(*)
5 Format of file name Input Char(8)
receiver variable The structure in which to return error information. For
6 View ID Input Binary(4) the format of the structure, see “Error Code Parameter”
7 Error code I/O Char(*) on page 2-6.

Service Program: QTEDBGS

Format of Text Descriptor Receiver
Threadsafe: No Variable
Offset
The Retrieve View File (QteRetrieveViewFile) API is used to
retrieve all the files and text information necessary to con- Dec Hex Type Field
struct the text for the entire view specified by the view ID 0 0 BINARY(4) Bytes returned
parameter. A list of text descriptors is returned. Each text
4 4 BINARY(4) Bytes available
descriptor describes where a piece of text for the view comes
from, either from a file specified in the file name receiver var- 8 8 BINARY(4) Number of text descriptor
iable or from supplied text that may be obtained using the entries
Retrieve View Text API. Note: The following three fields are repeated the number of
times specified in the number of text descriptor entries field.

Required Parameter Group BINARY(4) File name index

BINARY(4) Line number
Text descriptor receiver variable
OUTPUT; CHAR(*) BINARY(4) Number of lines

The output variable containing the list of text descriptors,

which describe how the specified view is constructed. Format of File Name Receiver Variable
For more information, see “Format of Text Descriptor
Receiver Variable.” Offset
Length of text descriptor receiver variable Dec Hex Type Field
INPUT; BINARY(4) 0 0 BINARY(4) Bytes returned
Specifies the length in bytes of the text descriptor 4 4 BINARY(4) Bytes available
receiver variable parameter. The minimum length is 8
8 8 BINARY(4) Number of file name entries
bytes.
Note: The following eight fields are repeated the number of
File name receiver variable times specified on the number of file name entries field.
OUTPUT; CHAR(*)
BINARY(4) Offset of file name
The output variable containing the list of files referenced
BINARY(4) Length of file name
by the text descriptor receiver variable.
CHAR(8) File format name
Length of file name receiver variable
BINARY(4) External or AS/400 IFS file
INPUT; BINARY(4) flag
The length in bytes of the file name receiver variable. BINARY(4) CCSID of file name
The minimum length is 8 bytes.
CHAR(2) Country ID of file name
Format of file name receiver variable CHAR(3) Language ID of file name
INPUT; CHAR(8)
CHAR(3) Reserved
The content and format of the information to be supplied
Note: The file names buffer follows all file name entries.
by the API in the file name receiver variable. The only
valid value is: CHAR(*) File names buffer

RVFN0100 Format of file name receiver variable

17-40 AS/400 System API Reference V4R4

 Retrieve View File (QteRetrieveViewFile) API

Field Descriptions Offset of file name. From the start of the file names buffer,
the start of a file name.
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is
provided.
Formats of File Format Name

Bytes returned. The number of bytes of data returned. RTVF0100 Format

CCSID of file name. The CCSID the file name is in. The Offset
value of this field is only valid for file format name Dec Hex Type Field
RTVF0200.
0 0 CHAR(10) AS/400 file name
Country ID of file name. The country ID of the file name. 10 A CHAR(10) AS/400 library
The value of this field is only valid for file format name 20 14 CHAR(10) AS/400 member name
RTVF0200.

External or IFS file flag. Whether the file is an AS/400 inte-

grated file system file or an external file. A value of 0 means
Field Descriptions
external file; a value of 1 means AS/400 integrated file AS/400 file name. The name of an AS/400 file from which
system file. The value of this field is valid only for file format text should be retrieved. It is an AS/400 object name, left-
name RTVF0200. justified, and padded with blanks.
File names buffer. A list of file names from which text AS/400 library. The name of a library that contains the file
should be retrieved. from which text should be retrieved. It is an AS/400 object
name, left-justified, and padded with blanks.
File name index. An index into the file name receiver vari-
able array. 0 is the first file entry in the file name receiver AS/400 member name. The name of the member of the file
variable. If the index is -1, the text comes from supplied text. from which text should be retrieved. It is an AS/400 object
name, left-justified, and padded with blanks.
File format name. The format of a file in the file names
buffer. Possible formats are:
RTVF0200 Format
RTVF0100 AS/400 file (see “RTVF0100 Format”)
RTVF0200 External or AS/400 HFS file (see “RTVF0200 Offset
Format”)
Dec Hex Type Field
Language ID of file name. The language ID of the file 0 0 CHAR(*) External file or AS/400 inte-
name. The value of this field is valid only for file format grated file system file name
name RTVF0200.

Length of file name. The length in bytes of a file name in Field Description
the file names buffer.
External file or AS/400 integrated file system file name.
Line number. The line number in the file that is referenced The name of an external file or AS/400 integrated file system
by the file name index to start reading text from. If the file file from which text should be retrieved. The value of this
name index is -1, this specifies the line number in the view field is valid only for file format name RTVF0200.
where the supplied text can be retrieved using the
QteRetrieveViewText API.
Error Messages
Number of file name entries. The number of entries CPF3C21 E
returned in the file name receiver variable. Format name &1 is not valid.
CPF3C24 E
Number of lines. The number of lines of text described by
Length of the receiver variable is not valid.
the text descriptor. The number of lines to read from the file,
CPF3CF1 E
which is the number of lines of supplied text to be retrieved
Error code parameter not valid.
using the QteRetrieveViewText API.
CPF3CF2 E
Number of text descriptor entries. The number of entries Error(s) occurred during running of &1 API.
returned in the receiver variable. The file name index, line CPF9541 E Not in debug mode.
number, and number of lines fields are repeated this number CPF9542 E View not found.
of times. CPF9549 E Error addressing API parameter.
CPF954A E No source text available.

Chapter 17. Debugger APIs 17-41

Retrieve View Line Information (QteRetrieveViewLineInformation) API

using the Register Debug View (QteRegisterDebugView)

Retrieve View Line Information API.
(QteRetrieveViewLineInformation) API
Start line number
INPUT; BINARY(4)

Required Parameter Group: The number of the first line in the view for which the API
is to retrieve information. This must be greater than or
1 Receiver variable Output Char(*) equal to 1 and less than or equal to the total number of
2 Receiver variable length Input Binary(4) lines in the view.
3 Format name Input Char(8)
4 View ID Input Binary(4) Number of lines
5 Start line number Input Binary(4) INPUT; BINARY(4)
6 Number of lines Input Binary(4)
7 Error code I/O Char(*) The number of lines in the view for which the API is to
retrieve information. This number includes the line spec-
Service Program: QTEDBGS ified in the start line number parameter. Fewer than
number of lines elements may be placed in the receiver
Threadsafe: No variable if fewer lines than requested are available. No
more than number of lines elements are placed in the
receiver variable.
The Retrieve View Line Information
(QteRetrieveViewLineInformation) API is used to retrieve The following special values are supported for this
information about a specified number of lines in a registered parameter:
view. -1 All lines associated with this view starting
at the value specified for the start line
The data returned to the caller of the API indicates whether a
number parameter should be processed.
given line or range of lines within a view can be run or not.
Error code
Required Parameter Group I/O; CHAR(*)
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 receiver variable that receives the information
requested. You can specify the size of the area to be
smaller than the format requested as long as you specify
RTVL0100 Format
the length parameter correctly. As a result, the API For a description of the fields in the receiver variable, see
returns only the data that the area can hold. “Field Descriptions” on page 17-43.
See “RTVL0100 Format” for details on the format of the
receiver variable. Offset

Length of receiver variable Dec Hex Type Field

INPUT; BINARY(4) 0 0 BINARY(4) Bytes returned
The length of the receiver variable provided by the 4 4 BINARY(4) Bytes available
receiver variable parameter. If this value is larger than 8 8 BINARY(4) Offset to line information
the actual amount of storage allocated for the receiver array
variable, the results are not predictable. The minimum
12 C BINARY(4) Number of line informa-
length is 8 bytes.
tion array elements
Format name 16 10 BINARY(4) Length of line information
INPUT; CHAR(8) array element
The format of the information returned. The possible CHAR(*) Reserved
format names are: Note: The following fields describe an element in the line infor-
mation array and are repeated the "number of line information
RTVL0100 Retrieve view line information. array elements" times. The nth element of the array (n > 0)
View ID describes the start line number + n-1 line in the view, where
start line number is a parameter to this API.
INPUT; BINARY(4)
CHAR(1) Line disposition
The identifier of a previously registered view obtained by
CHAR(*) Reserved

17-42 AS/400 System API Reference V4R4

 Retrieve View Text (QteRetrieveViewText) API

Field Descriptions
Required Parameter Group:
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is 1 Receiver variable Output Char(*)
provided. 2 Length of receiver variable Input Binary(4)
3 View ID Input Binary(4)
Bytes returned. The number of bytes of data returned. 4 Start line number Input Binary(4)
5 Number of lines Input Binary(4)
Length of line information array element. The number of 6 Line length Input Binary(4)
bytes occupied by a single element of the line information 7 Error code I/O Char(*)
array. Line information array elements are contiguous and
Service Program: QTEDBGS
all have the same length.
Threadsafe: No
Line disposition. Whether the line in the view described by
this array element can be run or not. Possible values are:
0 Line cannot be run The Retrieve View Text (QteRetrieveViewText) API is used
1 Line can be run to retrieve source text from a specified view. This text may
be formatted and displayed by the user of this API. The
Number of line information array elements. The number caller must specify the following:
of elements in the line information array that were returned Ÿ A registered view ID
by this API.
Ÿ The starting line number to be retrieved
Offset to line information array. The offset (in bytes) from Ÿ The number of lines of text to retrieve
the start of the receiver variable to the first element of the
line information array. Ÿ A buffer to contain the text retrieved

Reserved. An ignored field. All text retrieved, whether it comes from files or as text sup-
plied by a processor, is in the CCSID of the job.

Error Messages If source files have changed since the view was created,
diagnostic messages CPF9561 (for AS/400 files) and
CPF3C21 E
CPF9596 (for AS/400 integrated file system files) are sent to
Format name &1 is not valid.
the calling program's message queue for each file. Error
CPF3C24 E
messages CPF9566 (for AS/400 files) and CPF9597 (for
Length of the receiver variable is not valid.
AS/400 integrated file system files) also are issued, and all of
CPF3CF1 E
the text available is retrieved. The calling program should
Error code parameter not valid.
warn the user that the view text may be incorrect.
CPF3CF2 E
Error(s) occurred during running of &1 API. If a source file cannot be accessed because it is deleted or
CPF9541 E Not in debug mode. the user is not authorized, error messages CPF9565 (for
CPF9542 E View not found. AS/400 files) and CPF9598 (for AS/400 integrated file system
CPF9549 E Error addressing API parameter. files) are issued. No more text is retrieved. Text up to that
CPF9564 E Starting line number not valid. file is retrieved and this is indicated in the fields of the
CPF957A E Number of lines not valid. receiver variable. If the calling program attempts to read text
CPF957B E Required information not found for operation. in the view following the file, the starting line number can be
set to a line after the file. The number of lines in the file that
should have been read is returned in the exception data.
Retrieve View Text (QteRetrieveViewText) This allows the calling program to skip over this file if
API desired.

It is suggested that the calling program buffer the retrieved

text to minimize use of this API. Source files accessed by
this API do not remain open across API calls. Performance
degradation occurs for every use of the API that results in file
access because of opening and closing files.

Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)
The variable that is to receive the information requested.

Chapter 17. Debugger APIs 17-43

Retrieve View Text (QteRetrieveViewText) API

You can specify the size of this area to be smaller than

Offset
the format requested if you specify the length of receiver
variable parameter correctly. As a result, the API Dec Hex Type Field
returns only the data that the area can hold. For more 0 0 BINARY(4) Bytes returned
information, see “Format of Receiver Variable.” 4 4 BINARY(4) Bytes available
Length of receiver variable 8 8 BINARY(4) Number of lines returned
INPUT; BINARY(4) 12 C BINARY(4) Line length
The length of the receiver variable parameter. The Note: The following field is repeated for each line returned.
minimum length is 8 bytes. The number of characters is equal to the line length.

View ID CHAR(*) Listing view source line

INPUT; BINARY(4)
The identifier of a previously registered view obtained by For the statement view:
using the Register Debug View API.
Offset
Start line number
Dec Hex Type Field
INPUT; BINARY(4)
0 0 BINARY(4) Bytes returned
The number of the first line to be retrieved.
4 4 BINARY(4) Bytes available
Number of lines 8 8 BINARY(4) Number of lines returned
INPUT; BINARY(4)
12 C BINARY(4) Line length
The number of lines of source text to be retrieved. This
Note: The following fields are repeated for each line returned.
number includes the line specified in the start line
The total number of characters in each line is equal to the line
number parameter. Fewer than the number of lines may length (10 + 10 + 10 + * = line length).
be placed in the receiver variable if fewer lines than
requested are available. No more than the number of CHAR(10) Procedure dictionary
number
lines specified is placed in the receiver variable.
CHAR(10) Statement number
The following special value is supported for this param-
eter: CHAR(10) Statement type number
CHAR(*) Procedure name
0 All of the text associated with this view
should be retrieved.
For the text view:
Line length
INPUT; BINARY(4) Offset
The length of each line of text to be retrieved. Each line Dec Hex Type Field
takes exactly this many characters. If the actual line of
0 0 BINARY(4) Bytes returned
text is shorter, it is padded to the right with blanks. If
the line is longer than this length, it is truncated to fit. 4 4 BINARY(4) Bytes available
The line length must be a number from 1 through 255. 8 8 BINARY(4) Number of lines returned

Error code 12 C BINARY(4) Line length

I/O; CHAR(*) Note: The following fields are repeated for each line returned.
The structure in which to return error information. For CHAR(12) Sequence number
the format of the structure, see “Error Code Parameter” CHAR(*) Text view source line
on page 2-6.

Format of Receiver Variable Field Descriptions

The following tables show the information supplied in the Bytes available. The number of bytes of data available to
receiver variable parameter. The information returned be returned.
depends on the type of view being used. For more informa-
Bytes returned. The number of bytes of data returned.
tion on each field, see “Field Descriptions.”
Line length. The length of each line of text in the receiver
For the listing view:
variable parameter.

17-44 AS/400 System API Reference V4R4

 Set Debug Attribute (QteSetDebugAttribute) API

Listing view source line. The text associated with each CPF3C24 E
line retrieved. The number of characters in each line is Length of the receiver variable is not valid.
equal to the line length. CPF3CF1 E
Error code parameter not valid.
Number of lines returned. The number of lines of source CPF3CF2 E
text retrieved by this API and available in the receiver vari- Error(s) occurred during running of &1 API.
able. This may be less than the number of lines requested CPF9541 E Not in debug mode.
or available, if the receiver variable is not large enough to CPF9542 E View not found.
hold the text requested. CPF9549 E Error addressing API parameter.
CPF954A E No source text available.
Procedure dictionary number. The number that uniquely
CPF954C E
identifies the procedure in this module. The number is left-
Cannot retrieve text from file.
justified and padded on the right with blanks. For OPM pro-
CPF9560 E Line length not valid.
grams the procedure dictionary number is set to a value of 0.
CPF9561 E Source file has changed.
CPF9563 E Number of lines not valid.
Procedure name. The name of the procedure. The name
CPF9564 E Starting line number not valid.
is left-justified and padded on the right with blanks. For OPM
CPF9565 E Source cannot be accessed.
programs the procedure name is blanks.
CPF9566 E One or more source files have changed.
Sequence number. If the text is from a source physical file, CPF9596 E Source file has changed.
these 12 bytes contain the sequence number and source CPF9597 E One or more source files have changed.
date for that line. If the text is from an AS/400 integrated file CPF9598 E Source file cannot be accessed.
system file, these 12 bytes are blank. If the text is supplied CPF959A E Source file type not valid.
by the compiler, these 12 bytes are blank.

Statement number. The number that uniquely identifies the Set Debug Attribute
statement in the procedure. The number is left-justified and (QteSetDebugAttribute) API
padded on the right with blanks. This number is shown on
the compiler listing. For OPM programs the statement
number is the same as the machine interface (MI) number.
Required Parameters:
Statement type number. The type of statement produced
1 Debug attribute Input Char(10)
by the compiler. The number is left-justified and padded on 2 Attribute value Input Char(10)
the right with blanks. Possible values are: 3 Error code I/O Char(*)
1 INIT CODE
Service Program: QTEDBGS
2 PROC ENTRY
3 PROC EXIT Threadsafe: No
4 ALLOC
5 STMT
6 ENTRY The Set Debug Attribute (QteSetDebugAttribute) API is used
7 EXIT to set the attributes of the source debug session.
8 MULTIEXIT
9 PATH LABEL The attributes of the debug session cannot be set unless the
10 PATH CALL BGN job is currently in debug mode. The job is put in debug
11 PATH CALL RET mode by a call to the Start Source Debug
12 PATH DO BGN (QteStartSourceDebug) API.
13 PATH TRUEIF
14 PATH FALSEIF The *UPDPROD value on the debug attribute parameter sets
15 PATH WHEN BGN the update production files attribute of the debug session.
16 PATH OTHERW
You can use files in production libraries while you are in
17 GOTO
debug mode. To prevent database files in production
18 POST COMPOUND
libraries from being changed unintentionally, you can specify
Text view source line. The text associated with each line a value of *NO. Then, only files in test libraries can be
retrieved. The number of characters in each line equals the opened for updating or adding new records. If you want to
line length minus 12 bytes (the sequence number). open database files in production libraries for updating or
adding new libraries, or if you want to delete members from
production physical files, you can specify *YES. The initial
Error Messages setting when the Start Source Debug API is issued is *NO.
However, this value can be changed at any time while in
debug mode.

Chapter 17. Debugger APIs 17-45

Start Source Debug (QteStartSourceDebug) API

You can use this function with the library list. In the library When the debug attribute parameter specifies
list for your debug job, you can place a test library before a *OPMSRC, the attribute value parameter can have one
production library. In the test library, you should have copies of the following values:
of the production files that might be updated by the program
*YES
being debugged. Then, when the program runs, it uses the
Allow OPM programs that have source debug data
files in the test library. Therefore, production files cannot be
to be debugged by using the ILE debug APIs.
unintentionally updated.
*NO
The *OPMSRC value on the debug attribute parameter sets Do not allow OPM programs to be debugged by
the OPM source debug attribute of the debug session. It is using the ILE debug APIs.
used to enable or disable the OPM source debug support.
Error code
When this support is enabled, OPM RPG, OPM COBOL, and
I/O; CHAR(*)
OPM CL programs can be debugged by using the ILE debug
APIs if they were compiled with the *SRCDBG or *LSTDBG The structure in which to return error information. For
option on the following CL commands: the format of the structure, see “Error Code Parameter”
on page 2-6.
Ÿ Create RPG/400 Program (CRTRPGPGM)
Ÿ Create COBOL Program (CRTCBLPGM)
Error Messages
Ÿ Create Control language Program (CRTCLPGM)
CPF3CF1 E Error code parameter not valid.
Ÿ Create SQL RPG Program (CRTSQLRPG) CPF3CF2 E Error(s) occurred during running of &1 API.
Ÿ Create SQL COBOL Program (CRTSQLCBL) CPF9541 E Not in debug mode.
CPF9549 E Error addressing API parameter.
Ÿ Create Auto Report RPG Program (CRTRPTPGM) CPF9550 E Value for debug attribute not valid.
The initial value of the *OPMSRC attribute is set by the Start CPF9559 E Debug attribute parameter not valid.
Debug (STRDBG) command, and can also be changed by
the Change Debug (CHGDBG) command. Changing the
*OPMSRC value has no effect on programs that are already Start Source Debug
under debug. They remain in the debug environment (ILE or (QteStartSourceDebug) API
OPM) that they are currently added to.

Required Parameter Group Required Parameter Group:

Debug attribute 1 Qualified program name Input Char(20)

INPUT; CHAR(10) 2 Error code I/O Char(*)

The name of the debug session that is to be set. The Service Program: QTEDBGS
value of the debug attribute must be:
Threadsafe: No
*UPDPROD
Set the value of the update production files attribute.
The Start Source Debug (QteStartSourceDebug) API lets you
*OPMSRC
use the source debugging APIs in your session. This allows
Set the value of the OPM source debug attribute.
the debugging of any ILE programs or service programs that
Attribute value contain debug information. OPM CL, OPM RPG, and OPM
INPUT; CHAR(10) COBOL programs that are created with OPTION(*SRCDBG)
or OPTION(*LSTDBG) may also be debugged.
The value of the attribute specified in the debug attribute
parameter. Your job must be put in debug mode before this API is
When the debug attribute parameter specifies issued. Debug mode is a special environment in which the
*UPDPROD, the attribute value parameter can have one debug functions can be used in addition to routine system
of the following values: functions. Debug functions cannot be used outside debug
mode. To start debug mode, you must issue the Start
*YES Debug (STRDBG) command.
Allow the updating of production files while in debug
mode. The Start Source Debug API must be used before an ILE or
*NO OPM program can be debugged. This API requires that you
Do not allow the updating of production files while in specify a user exit program to be called by the source
debug mode. debugger support to handle breakpoints, steps, and unmoni-
tored exceptions.

17-46 AS/400 System API Reference V4R4

 Start View Creation (QteStartViewCreation) API

Your job remains in debug mode until an End Source Debug

(QteEndSourceDebug) API is issued or until your current Required Parameter Group:
routing step ends.
1 Input file descriptor buffer Input Char(*)
If the job is servicing another job, the job will actually debug 2 Output file descriptor buffer Input Char(*)
the job being serviced. 3 Format name Input Char(8)
4 Discard previous views Input Char(10)
5 Processor ID Input Char(20)
Authorities 6 View CCSID Input Binary(4)
7 Error code I/O Char(*)
Program Authority
*USE
Service Program: QTECRTVS
Library Authority
*USE Threadsafe: No

Required Parameter Group The calling program uses the Start View Creation
Qualified program name (QteStartViewCreation) API to initialize the debug view cre-
INPUT; CHAR(20) ation environment. This API should be the first one of the
view creation APIs to be called.
The name of the exit program that is called whenever a
breakpoint, a program step, or an unmonitored exception This calling program is usually a text preprocessor or a com-
occurs. See “Program-Stop Handler Exit Program” on piler. In this document, the term processor will be used to
page 17-65 for a discussion of the parameters passed specify any program that reads input text and produces view
to this program to assist in processing breakpoint, step, data for the debugger.
and exception information.
The processor that calls the Start View Creation API must
The first 10 characters contain the program name. The
provide the names of the input source member read and the
second 10 characters contain the name of the library
output source member created (if any).
where the program is located. Both entries must be left-
justified. The input member name is the name of the root source
Error code member read by the processor. If a previously run processor
I/O; CHAR(*) created this member, then view information is stored with the
member. This view information is combined with that
The structure in which to return error information. For produced by the processor and stored in the output source
the format of the structure, see “Error Code Parameter” member specified by the processor.
on page 2-6.
If an input member is specified and there is no view informa-
tion in the associated space of the member, it is assumed
Error Messages that this member is the root source from which the program
CPF3CF1 E is created. It is also assumed that the processor that speci-
Error code parameter not valid. fies this member is the first processor in the chain of
CPF3CF2 E processors that produces the program.
Error(s) occurred during running of &1 API.
CPF9540 E Already in debug mode. The processor creating the view supplies the CCSID in which
CPF9541 E Not in debug mode. all supplied text is stored. Thus, when view text is extracted,
CPF9803 E Cannot allocate object &2 in library &3. all supplied text is translated from this CCSID to the CCSID
CPF9809 E Library &1 cannot be accessed. of the job. When view text (such as macro expansion text) is
CPF9810 E Library &1 not found. supplied, it must be supplied in the same CCSID. Text that
CPF9811 E Program &1 in library &2 not found. comes from other files may be in any CCSID, as it will auto-
CPF9820 E Not authorized to use library &1. matically be translated into the job's CCSID when the text is
CPF9821 E Not authorized to program &1 in library &2. retrieved.
CPF9549 E Error addressing API parameter.
If no input member is specified, it is assumed that a previous
processor created view information in a temporary space,
instead of storing it in an output member. This is the case
Start View Creation (QteStartViewCreation) when a compiler runs and produces view information. Since
API the compiler does not produce an output member to be read
by another processor, the view information is stored in a tem-
porary location associated with the process, and no output
file is specified.

Chapter 17. Debugger APIs 17-47

Start View Creation (QteStartViewCreation) API

Each processor creates view information that is combined the calling program in the input file descriptor buffer and
with information produced by previous processors. The final, the output file descriptor buffer. The only valid value for
and complete, view information is stored by the binder in the format name is:
module and program object associated space.
FILA0100 AS/400 file names
After the view information is complete, the End View Creation
Discard previous views
API should be called.
INPUT; CHAR(10)
The input file must exist and be available at the time this API Whether the program creating debug view information
is issued. The output file must exist and be available at the wants the source debugger support to throw away any
time the QteEndViewCreation API is issued. previously created view information. This allows a
processor to force the view information created to be the
only debug data available. In general, processors would
Authorities specify *NO to allow any previous processor's view infor-
Input file member specified mation to be included in the final program object.
*USE
Output file member specified *YES The source debugger support does not
*CHANGE use any previously built view information
but rather starts with the information pro-
vided by the processor creating debug
Required Parameter Group data.
*NO The source debugger support uses any
Input file descriptor buffer
previously built and existing view informa-
INPUT; CHAR(*)
tion and adds to it the view information
The name of the file member read by the processor cre- created during this compiler step.
ating debug data. This member may be a member
created by the customer, or it may be the output of a Processor ID
previously run preprocessor. The special value of INPUT; CHAR(20)
*NONE is used when input from the processor does not The processor that creates view information.
come from a source member. In general, the only
processor which would indicate *NONE is the back end View CCSID
of the compiler. INPUT; BINARY(4)

This file may contain view information if it is created by a The CCSID of any text supplied to the view creation
previously run preprocessor. APIs.

The structure of this parameter is specified by the format Error code

name parameter. I/O; CHAR(*)

Output file descriptor buffer The structure in which to return error information. For
INPUT; CHAR(*) the format of the structure, see “Error Code Parameter”
on page 2-6.
The file member written by the processor creating debug
data. A special value of *NONE for the output file indi-
cates that the view information created will remain with FILA0100 Format
the job and will be passed to the next compilation step
without being associated with a specific file. Generally, Offset
only the compiler uses this special value, as it does not Dec Hex Type Field
create a source member to be read by another
0 0 CHAR(10) File name
processor.
10 A CHAR(10) File library
The associated space of this file will contain view infor-
mation created by this processor in addition to view 20 14 CHAR(10) Member name
information created by any previous preprocessor steps.
It is the responsibility of the processor to create this file
and make it available before the QteEndViewCreation Field Descriptions
API is called.
File library. The name of the library that contains the file
The structure of this parameter is specified by the format being listed. It is an AS/400 object name, left-justified, and
name parameter. padded with blanks.
Format name File name. The name of the file being listed. It is an
INPUT; CHAR(8) AS/400 object name, left-justified, and padded with blanks.
The content and format of the information supplied by

17-48 AS/400 System API Reference V4R4

 Stop Debugged Job API

Member name. The name of the member in the file being *INTO Statements in the procedure currently
listed. It is an AS/400 object name, left-justified, and padded stopped in are counted. Also, if that pro-
with blanks. cedure calls other procedures, these
statements are also counted as they are
run. Thus, it is possible to stop the
Error Messages program in a procedure called by the pro-
CPF3C21 E cedure currently stopped.
Format name &1 is not valid. *OVER Only statements in the procedure cur-
CPF3CF1 E rently stopped in are counted in the step.
Error code parameter not valid. Thus, procedures that this procedure calls
CPF3CF2 E are “stepped over” when doing the step.
Error(s) occurred during running of &1 API. If the program is not currently stopped,
CPF9549 E Error addressing API parameter. then the step count will start with the first
CPF9554 E Discard Previous Views parameter not valid. procedure called in that program, and all
CPF9803 E Cannot allocate object &2 in library &3. procedures that are called by this proce-
CPF9809 E Library &1 cannot be accessed. dure are not stepped into, and their state-
CPF9810 E Library &1 not found. ments are not counted.
CPF9815 E Member &5 file &2 in library &3 not found.
CPF9820 E Not authorized to use library &1. Error code
CPF9822 E Not authorized to file &1 in library &2. I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Step (QteStep) API on page 2-6.

Error Messages
Required Parameter Group:
CPF1938 E Command is not allowed while serviced job is
1 View ID Input Binary(4) not active.
2 Step count Input Binary(4) CPF1939 E Time-out occurred waiting for a reply from the
3 Step type Input Char(10) serviced job.
4 Error code I/O Char(*) CPF1941 E Serviced job has completed. Debug commands
are not allowed.
Service Program: QTEDBGS
CPF3CF1 E
Threadsafe: No Error code parameter not valid.
CPF9541 E Not in debug mode.
CPF9542 E View not found.
The calling program uses the Step (QteStep) API to start a CPF9549 E Error addressing API parameter.
step in a program. A step count is specified. When the CPF9576 E Step count not valid.
number of statements specified by the step count is run, the CPF9577 E Step type not valid.
program will be stopped.

Required Parameter Group Stop Debugged Job

(QteStopDebuggedJob) API
View ID
INPUT; BINARY(4)
The identifier of a previously registered view obtained by Required Parameter Group:
using the Register Debug View API.
1 Error code I/O Char(*)
Step count
INPUT; BINARY(4) Service Program: QTETHRD
The number of statements to be run before the program Threadsafe: No
is to be stopped.

Step type The Stop Debugged Job (QteStopDebuggedJob) API causes

INPUT; CHAR(10) debug to halt all threads in a job being debugged. The job
Which statements are counted when stepping in the stopped is being serviced and debugged by the job calling
program. The following are allowed: the QteStopDebuggedJob API. This API is allowed for ser-
vicing of both threaded and nonthreaded applications.

Chapter 17. Debugger APIs 17-49

Submit Debug Command (QteSubmitDebugCommand) API

Required Parameter Group must be to contain the results for the Debug Language
statements submitted. If more data is available than the
Error code receiver variable can contain, a larger buffer should be
I/O; CHAR(*) provided and the API should be reissued.
The structure in which to return error information. For Length of receiver variable
the format of the structure, see “Error Code Parameter” INPUT; BINARY(4)
on page 2-6.
The length of the receiver variable. If the length is larger
than the size of the receiver variable, the results may not
Error Messages be predictable. The minimum length is 8 bytes.
CPF3CF1 E View ID
Error code parameter not valid. INPUT; BINARY(4)
CPF3CF2 E
Error(s) occurred during running of &1 API. An identifier of a view of a module whose operation is
CPF9541 E Not in debug mode. managed by the source debugger. The view ID is
CPF958F E Debug is not servicing a job. returned as a result of issuing the Register Debug View
CPF9590 E Debugged job not stopped. API. The view ID is used to find debug data associated
with the module.

Input buffer
Submit Debug Command INPUT; CHAR(*)
(QteSubmitDebugCommand) API The input variable that is passed to the Submit Debug
Command API. The information passed in the buffer is
debug language statements.
Required Parameter Group:
Input buffer length
1 Receiver variable Output Char(*) INPUT; BINARY(4)
2 Length of receiver variable Input Binary(4)
3 View ID Input Binary(4) The length of the data provided in the input buffer.
4 Input buffer Input Char(*)
Compiler ID
5 Input buffer length Input Binary(4)
6 Compiler ID Input Char(20) INPUT; CHAR(20)
7 Error code I/O Char(*) The compiler ID of the compiler that produced the
module being debugged. This information is used by the
Service Program: QTEDBGS debug translator during expression evaluation. The
compiler ID is returned by the Retrieve Module Views
Threadsafe: No
(QteRetrieveModuleViews) API.

Error code
The Submit Debug Command (QteSubmitDebugCommand)
I/O; CHAR(*)
API allows a client program to issue debug language state-
ments. Debug language statements permit client programs The structure in which to return error information. For
to enter breakpoints, run one or more statements of the the format of the structure, see “Error Code Parameter”
program under investigation (step), and evaluate on page 2-6.
expressions. Watch conditions may also be entered to
cause a breakpoint when the contents at a specified storage
location are changed.
Receiver Variable Format
The following table shows the structure of the receiver vari-
Required Parameter Group able. For more information on the fields contained in the
table, see “Field Descriptions” on page 17-51.
Receiver variable
OUTPUT; CHAR(*) Figure 17-6. Receiver Variable Structure
The variable that is to receive the results of the Submit Offset
Debug Command API. For more information on the
Dec Hex Type Field
structure of the receiver variable, see Figure 17-7 on
page 17-51. 0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
The Submit Debug Command API may have more data
to return than can be stored in the receiver variable. 8 8 BINARY(4) Entry count
The bytes available field, described in Figure 17-7 on 12 C CHAR(*) Results array
page 17-51, specifies how large the receiver variable
CHAR(*) String space

17-50 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

Field Descriptions Each row of Figure 17-7 occupies 12 bytes. The row con-
taining the headings describes the remainder of the receiver
Bytes available. The number of bytes of data available to variable. The number of bytes returned is assigned to that
be returned. All available data is returned if enough space is field. The value of the bytes returned field is always less
provided. than or equal to the size of the receiver variable. The
number of bytes available may be greater than the number
Bytes returned. The number of bytes of data returned. returned. In that case, the client program should reissue the
Submit Debug Command API to obtain all data produced for
Entry count. The number of entries in the results array. the input debug language statements. The entry count field
The value of the field is the number of entries in the results in the first row indicates the number of 12-byte records, each
array. Each entry occupies 12 bytes. Depending on the kind beginning with a result type field, that follow.
of information returned, values in entries vary.
Records beginning with a result type field have the following
Results array. The results of interpreting debug language basic formats.
statements. This is an array of records having similar struc-
tures. Each record in the array occupies 12 bytes. There Ÿ The first entry in the array shows a record containing
can be up to three fields in each record. Each field occupies only one field, result type. Records having this structure
4 bytes and can be interpreted as an unsigned (nonnegative) acknowledge that a kind of debug language statement
integer. The first field in a record is the result type field and was translated. An example of this kind of record is the
is used to select the remaining fields. Entries in the result result record for a CLEAR PGM statement.
record array fall into several classes. Figure 17-7 depicts Ÿ The second entry in the array shows a record containing
several formats of result records. a count field as well as a result type field. The count
field can serve two purposes:
Statements are interpreted sequentially and the results of
each statement are placed in the order in which statements – It can acknowledge that a debug language state-
appear in the input buffer. The evaluate statement can ment was properly translated as in the case of the
return many values if an array or a structure is evaluated. StepR result record.
The entry count field contains the number of entries in the – It can enumerate the number of related records to
results array, and the structure of each entry is summarized follow as in the case of the BreakR result record.
in Figure 17-7.
Ÿ The offset field contains the displacement from the start
String space. A sequence of strings. Each string is an of the receiver variable to the first byte of the character
array of characters whose last character is a null character. string. All character strings are stored at the end of the
receiver variable directly after the record entries. Dis-
Description of the Structure of the Receiver Vari- placements are measured in bytes.
able: Figure 17-7 illustrates three possible variations in the The length field contains the number of characters in the
structure of the receiver variable. The receiver variable con- character string.
sists of the following structures:
The last character of each string in the string space has
Ÿ A header record an ordinal value of zero. All characters in the string
This structure consists of three fields: space occupy 8 bits. The length of a string in the string
space does not include the last character.
– Bytes returned
Ÿ The last row of Figure 17-7 depicts an arbitrarily large
– Bytes available string space containing character data. Names and other
– Entry count text fields that are referred to in the result type fields
shown in the other rows of Figure 17-7 are stored in this
Ÿ A result array
area.
Ÿ A string space

Figure 17-7. Variations in Receiver Variable Structure

Results Array Entry Structure Summary
Header Bytes Bytes Avail- Entry Count The following tables describe each result record in detail.
Returned able Each result record contains up to three fields and always
Result array Result type occupies 12 bytes. The first field, the result type field, is
1 used as an enumerated type. The result type field deter-
Result array Result type Count mines the format of each result record.
2
Each of the following enumeration constants has both a sym-
Result array Result type Offset Length bolic name and an ordinal value. The terms symbolic and
3
ordinal refer to enumerations found in programming lan-
String space guages. The symbolic value of an enumeration constant is

Chapter 17. Debugger APIs 17-51

Submit Debug Command (QteSubmitDebugCommand) API

the symbol, usually a descriptive word that serves as a BreakPositionR (5)

keyword for the programmer (for example, StepR). The
ordinal value of an enumeration constant is the integer con- Record format BreakPositionR identifies the line number on
stant assigned, usually by the compiler, to the symbolic which a breakpoint was entered. This may not be the same
value. For example, 1 is assigned for StepR. line number as the one entered in the break statement.

Offset
StepR (1)
Dec Hex Type Field
Record format StepR is returned as a result of evaluating a
0 0 BINARY(4) Result type
step statement.
4 4 BINARY(4) Line number
Offset 8 8 CHAR(4) Reserved
Dec Hex Type Field
0 0 BINARY(4) Result type EvaluationR (6)
4 4 BINARY(4) Step count
Record format EvaluationR contains the number of records
8 8 CHAR(4) Reserved
returned for an evaluate statement that are referred to in the
subsequent ExpressionValueR record.
BreakR (2)
Offset
Record format BreakR contains the number of records Dec Hex Type Field
returned for a break statement.
0 0 BINARY(4) Result type
4 4 BINARY(4) Evaluation count
Offset
8 8 BINARY(4) Reserved
Dec Hex Type Field
0 0 BINARY(4) Result type
4 4 BINARY(4) Break results count ExpressionTextR (7)
8 8 CHAR(4) Reserved
Record format ExpressionTextR describes a character string
that contains the expression that was evaluated by the eval-
uate statement.
ClearBreakpointR (3)
Record format ClearBreakpointR contains the line number of Offset
the breakpoint removed as a result of interpreting the CLEAR Dec Hex Type Field
break-position statement.
0 0 BINARY(4) Result type
4 4 BINARY(4) Expression text offset
Offset
8 8 BINARY(4) Expression text length
Dec Hex Type Field
0 0 BINARY(4) Result type
4 4 BINARY(4) Line number ExpressionValueR (8)
8 8 CHAR(4) Reserved
Record format ExpressionValueR refers to text that contains
the formatted value of the expression that is described by the
ExpressionTextR record.
ClearPgmR (4)
Record format ClearPgmR indicates that all breakpoints have Offset
been removed in the current program as result of interpreting Dec Hex Type Field
the CLEAR PGM statement.
0 0 BINARY(4) Result type
4 4 BINARY(4) Expression value offset
Offset
8 8 BINARY(4) Expression value length
Dec Hex Type Field
0 0 BINARY(4) Result type
4 4 CHAR(4) Reserved
8 8 CHAR(4) Reserved

17-52 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

ExpressionTypeR (9) Offset

Dec Hex Type Field
Record format ExpressionTypeR contains the type of the
expression whose value is referred to in the 0 0 BINARY(4) Result type
ExpressionValueR record. 4 4 BINARY(4) Total digits
8 8 BINARY(4) Fraction digits
Offset
Dec Hex Type Field
0 0 BINARY(4) Result type ArrayR (14)
4 4 BINARY(4) Expression type Record format ArrayR is returned only for array type vari-
8 8 CHAR(4) Reserved ables and contains the number of dimensions in the array.
The ArrayR record is followed by a DimensionR record for
each dimension.
QualifyR (10)
Offset
Record format QualifyR is returned as a result of evaluating
Dec Hex Type Field
a qualify statement.
0 0 BINARY(4) Result type
Offset 4 4 BINARY(4) Dimensions
Dec Hex Type Field 8 8 BINARY(4) Reserved
0 0 BINARY(4) Result type
4 4 BINARY(4) Line number
DimensionR (15)
8 8 BINARY(4) Reserved
Record format DimensionR is returned only for array type
variables and contains the low and high bounds of the array
TypeR (11) dimensions. There is one DimensionR record for each
dimension in the array.
Record format TypeR contains the number of records that
are returned for an ATTR statement. Offset
Dec Hex Type Field
Offset
0 0 BINARY(4) Result type
Dec Hex Type Field
4 4 BINARY(4) Low bound
0 0 BINARY(4) Result type
8 8 BINARY(4) High bound
4 4 BINARY(4) Type record count
8 8 BINARY(4) Reserved
WatchR (16)
TypeDescR (12) Record format WatchR contains the number of records
returned for a watch statement.
Record format TypeDescR contains the type and length of
the program variable. Offset
Dec Hex Type Field
Offset
0 0 BINARY(4) Result type
Dec Hex Type Field
4 4 BINARY(4) Watch results count
0 0 BINARY(4) Result type
8 8 BINARY(4) Reserved
4 4 BINARY(4) Type
8 8 BINARY(4) Length
WatchNumberR (17)
DecimalR (13) Record format WatchNumberR describes the watch condition
that was set as a result of the watch statement.
Record format DecimalR is returned only for decimal type
variables and contains the total and fractional number of
digits in the decimal number.

Chapter 17. Debugger APIs 17-53

Submit Debug Command (QteSubmitDebugCommand) API

Expression text offset. The displacement from the start of

Offset
the receiver variable to the first character of the expression
Dec Hex Type Field text. Displacement is measured in bytes.
0 0 BINARY(4) Result type
Expression value length. The number of characters in the
4 4 BINARY(4) Watch number
expression value text.
8 8 BINARY(4) Watch length
Expression value offset. The displacement from the start
of the receiver variable to the first byte of the expression
ClearWatchNumberR (18) value text. Displacement is measured in bytes.

Record format ClearWatchNumberR contains the watch Evaluation count. The number of records returned for an
number that is cleared as a result of interpreting the CLEAR evaluate statement.
WATCH watch-number statement.
Expression type. The data type of the expression. The
Offset
expression type may be one of the following:

Dec Hex Type Field Type Enumeration Description

0 kNoType__E Type is not valid
0 0 BINARY(4) Result type
1 kChar__8_E 8-bit character value
4 4 BINARY(4) Watch number 2 kChar_16_E 16-bit character value
8 8 BINARY(4) Reserved 3 kBool_32_E 32-bit Boolean value
4 kCard_16_E 16-bit unsigned integer value
5 kCard_32_E 32-bit unsigned integer value
6 kInt__16_E 16-bit two's complement integer
ClearWatchR (19) value
7 kInt__32_E 32-bit two's complement integer
Record format ClearWatchR indicates that all watches in this value
debug session have been removed as a result of interpreting 8 kReal_32_E 32-bit real floating-point value
the CLEAR WATCH ALL statement. 9 kReal_64_E 64-bit real floating-point value
10 kSpcPtr__E 128-bit pointer
11 kFncPtr__E 128-bit function pointer
Offset
12 kMchAddr_E 128-bit machine pointer
Dec Hex Type Field 13 kRecord__E Structure or record
0 0 BINARY(4) Result type 14 kArray___E Array
15 kEnum____E Enumerated type
4 4 BINARY(4) Reserved 16 kString__E String (:s format on EVAL)
8 8 BINARY(4) Reserved 17 kPacked__E Packed decimal
18 kZonedTE_E Zoned, trailing embedded sign
19 kZonedTS_E Zoned, trailing separate sign
20 kZonedLE_E Zoned, leading embedded sign
TBreakR (20) 21 kZonedLS_E Zoned, leading separate sign
22 kBinD_16_E 16-bit binary decimal value
Record format TBreakR contains the number of records that 23 kBinD_32_E 32-bit binary decimal value
are returned for a tbreak statement. 24 kBinD_64_E 64-bit binary decimal value
25 kTable___E Multiple occurrence data structure
Offset 26 kInd_____E Indicator
27 kDate____E Date
Dec Hex Type Field 28 kTime____E Time
0 0 BINARY(4) Result type 29 kTstamp__E Timestamp
30 kFixedL__E Fixed-length string
4 4 BINARY(4) TBreak results count
31 kStringF_E String (:f, :a, :u format on EVAL
8 8 CHAR(4) Reserved command)
100 kHex_____E Hexadecimal (:x format on EVAL
command)
Field Descriptions
Fraction digits. The number of digits to the right of the
Break results count. The number of entries returned for the decimal point in a decimal number.
break statement.
High bound. The high boundary of the array dimension.
Dimensions. The number of dimensions in the array.
Length. The program variable length that is returned by the
Expression text length. The number of characters in the TypeDescR result record. The length units are bits.
expression text.
Line number. The number of the line on which the action
requested was performed.

17-54 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

Low bound. The low boundary of the array dimension. the line on which the breakpoint was entered. Be aware
that the input line number may be mapped to a different
Reserved. An ignored field. line. For example, a breakpoint entered on a line that
contains a comment is mapped to the next line that con-
Result type. The ordinal value of the result array.
tains an operational statement.
Step count. The number of statements processed. Ÿ The text of the expression that defines a conditional
breakpoint. Record type ExpressionTextR refers to the
TBreak results count. The number of entries returned for text of the condition.
the tbreak statement.
The break statement is interpreted. Program operation is
Total digits. The total number of digits in a decimal number. managed by OS/400 according to the definition of the break
statement.
Type. The program variable type that is returned by the
TypeDescR result record. The meanings of this field's value Clear Statement Results. One record is returned. The
are the same as the expression type field. record type depends on the operand following the keyword
CLEAR. If the operand is a line number, the record type is
Type record count. The number of records returned for an
ClearBreakpointR. If the operand is the keyword PGM, the
attr statement.
record type is ClearPgmR. If the operand is WATCH and a
Watch length. The length in bytes of the storage being watch number is specified, the record type is
watched for this watch condition. ClearWatchNumberR. If the operand is WATCH and all
watches are cleared, the record type is ClearWatchR.
Watch number. The identification number assigned to the
watch condition. This number is used by various debug The ClearBreakpointR record contains the line number input
functions to identify individual watches. for the break position.

Watch results count. The number of result records The clear statement is interpreted. One or more breakpoints
returned for the watch statement. are removed from the program under investigation.

Evaluate Statement Results. An evaluate statement

Statement Results produces a variable number of Result Records. The first four
result records follow:
ATTR Statement Results. The Submit Debug Command
Ÿ An EvaluationR record is returned, which enumerates
API returns a description of the symbol table entry for the
itself and subsequent records. The EvaluationR result
program variable entered. A variable number of result
record always contains an evaluation count of four.
records may be produced:
Ÿ An Expression text record is returned, which contains
Ÿ A TypeR record is returned, which provides a count of
the offset and length of the string, which represents the
the number of records returned for an ATTR statement.
expression text.
Ÿ A TypeDescR record is returned, which provides the
Ÿ An Expression value record is returned, which contains
type and size of the program variable.
the offset and length of the string, which represents the
Ÿ A DecimalR record is returned only if the program vari- value of the expression.
able is a decimal type. This record describes the total
Ÿ An Expression type record is returned, which contains
and fractional digits in the decimal number.
the type of the expression.
Ÿ An ArrayR record is returned only if the program variable
is an array. This record returns the number of dimen- A single value is returned for an arithmetic expression or
sions in an array. scalar variable. Multiple values are returned when a struc-
ture is evaluated. Refer to section “Examples of Result
Ÿ A DimensionR record is returned only if the program var-
Records Returned by Submit Debug Command API” on
iable is an array. This record returns the low and high
page 17-56 for examples of the result records returned when
bounds of the array dimensions.
a structure or an array is evaluated.
Break Statement Results. The Submit Debug Command
The evaluate statement is interpreted. Data is formatted
API returns a detailed description of the break-position and
according to the type of the input expression. Refer to
conditional expression of a conditional breakpoint when a
Figure 17-15 on page 17-62 for a description of presentation
break statement is translated. The items returned follow:
formats.
Ÿ The number of records returned as a result of evaluating
a break statement. Record type BreakR contains this Qualify Statement Results. One record is returned. The
information. value of the result type field is QualifyR. The QualifyR
record contains the input line number used to establish the
Ÿ The position on which the breakpoint was entered.
current locality for subsequent evaluate statements.
Record type BreakPositionR contains the line number of

Chapter 17. Debugger APIs 17-55

Submit Debug Command (QteSubmitDebugCommand) API

A reference to the block that defines the current locality is Examples of Result Records Returned by
assigned by the qualify statement.
Submit Debug Command API
Step Statement Results. One record is returned. The
This section contains examples of result records returned by
value of the result type field is StepR. The StepR record
the Submit Debug Command API. Each example contains a
contains the number of statements to be run when control is
fragment of a program, a debug language statement that
given to the program under investigation.
appears in the input buffer, and the results produced in the
The step statement is interpreted. Program processing is receiver variable.
managed by OS/400 according to the definition of the step
The null termination symbol (Ø) denotes the end of a char-
statement.
acter string in the examples that follow.
TBreak Statement Results. The Submit Debug Command
API returns a detailed description of the thread break-position
Break Statement Example
and conditional expression of a conditional breakpoint when C Program Fragment: Assume program operation is sus-
a tbreak statement is translated. The items returned follow: pended in the program shown in Figure 17-8 just before line
Ÿ The number of records returned as a result of evaluating 6 runs.
a tbreak statement. Record type TBreakR contains this
information. Line C Source
Ÿ The position on which the thread breakpoint was
1 #include stdio.h
entered. Record type BreakPositionR contains the line 2 int T[] = {1,2,3,5,7,11,13,17,23,29};
number of the line on which the thread breakpoint was 3 int BinarySearch(int v, int f, int l);
4 main()
entered. Be aware that the input line number may be 5 { int result;
mapped to a different line. For example, a thread break- 6 result = BinarySearch(17,ð,9);
point entered on a line that contains a comment is 7 printf("result= "); printf("%d",result); printf(" \n");
8 }
mapped to the next line that contains an operational
statement. Figure 17-8. Program for Break Example
Ÿ The text of the expression that defines a conditional
breakpoint for a thread. Record type ExpressionTextR Input Buffer
refers to the text of the condition. BREAK 7 WHEN result > 5

The tbreak statement is interpreted. Program operation is Receiver Variable

managed by OS/400 according to the definition of the tbreak
statement. Offset Field Value
0 Bytes returned 59
Watch Statement Results. The watch statement returns the
Bytes available 59
following result records: Entry count 3
Ÿ A WatchR record is returned, which provides a count of 12 Result type BreakR
the number of result records for the watch statement. Break results count 3
Reserved
Ÿ A WatchNumberR record is returned, which contains the
watch number assigned and the length in bytes of the 24 Result type BreakPositionR
storage being watched. Line number 7
Reserved
Ÿ An ExpressionTextR record, which contains the offset
36 Result type ExpressionTextR
and length of a string. This record represents the watch
Expression text offset 48
statement expression text. Expression text length 10
Ÿ An ExpressionValueR record, which contains the offset 48 String space result > 5Ø
and length of a string. This record represents the watch
storage location address. This value is always a text
representation of a space pointer that contains the value
Scalar Evaluate Statement Example
of the pointer to the watched storage location (for C Program Fragment: Consider the C program fragment in
example, 'SPP:08006F0054001004'). Figure 17-9. Variable i defines an integer.

Line C Source

1 int i = 29;

Figure 17-9. Program for Scalar Evaluate Example

17-56 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

Input Buffer
Offset Field Value
EVAL i
60 String space IØ1Ø
Receiver Variable
Structure Evaluate Statement Example
Offset Field Value
C Program Fragment: Consider the C program fragment in
0 Bytes returned 65 Figure 17-11.
Bytes available 65
Entry count 4
12 Result type EvaluationR Line C Source
Evaluation count 4
Reserved 1 struct {
2 int i;
24 Result type ExpressionTextR
Expression text offset 60
3 float f;
Expression text length 1 4 struct {
5 char c;
36 Result type ExpressionValueR 6 enum e {red,yellow};
Expression value offset 62 7 } s2;
Expression value length 2 8 } s1 = { 1 , 5.ð, {'a' , red } };
48 Result type ExpressionTypeR
Expression type kInt__32_E Figure 17-11. Program for Structure Evaluate Example
Reserved
Input Buffer
60 String space iØ29Ø
EVAL s1
Scalar Evaluate Statement Example Receiver Variable
RPG Program Fragment: Consider the RPG program frag-
Offset Field Value
ment in Figure 17-10. The fragment assigns 1 to a
zoned(1,0) variable I. 0 Bytes returned 246
Bytes available 246
The program is currently stopped at line 2. Entry count 16
12 Result type EvaluationR
CLðNð1Factor1++++++OpcodeE+Extended-factor2
Evaluation count 4
Reserved
1 C EVAL I=1
2 C MOVE \ON \INLR 24 Result type ExpressionTextR
Expression text offset 204
Figure 17-10. RPG Programming Language Example, Evaluate Expression text length 4
36 Result type ExpressionValueR
Input Buffer
Expression value offset 209
EVAL I Expression value length 1
48 Result type ExpressionTypeR
Receiver Variable
Expression type kInt__32_E
Reserved
Offset Field Value
60 Result type EvaluationR
0 Bytes returned 64 Evaluation count 4
Bytes available 64 Reserved
Entry count 4
72 Result type ExpressionTextR
12 Result type EvaluationR Expression text offset 211
Evaluation count 4 Expression text length 4
Reserved
84 Result type ExpressionValueR
24 Result type ExpressionTextR Expression value offset 216
Expression text offset 60 Expression value length 7
Expression text length 1
96 Result type ExpressionTypeR
36 Result type ExpressionValueR Expression type kReal_64_E
Expression value offset 62 Reserved
Expression value length 1
108 Result type EvaluationR
48 Result type ExpressionTypeR Evaluation count 4
Expression type kZonedTE_E Reserved
Reserved

Chapter 17. Debugger APIs 17-57

Submit Debug Command (QteSubmitDebugCommand) API

RPG Program Fragment: Consider the RPG program frag-

Offset Field Value
ment in Figure 17-13. The fragment assigns 1 to a
120 Result type ExpressionTextR zoned(1,0) variable I.
Expression text offset 224
Expression text length 7 The program is currently stopped at line 2.
132 Result type ExpressionValueR
Expression value offset 232
CLðNð1Factor1++++++OpcodeE+Extended-factor2
Expression value length 1
1 C EVAL I=1
144 Result type ExpressionTypeR 2 C MOVE \ON \INLR
Expression type kChar__8_E
Reserved Figure 17-13. RPG Programming Language Example, Evaluate
156 Result type EvaluationR
Evaluation count 4
Input Buffer
Reserved ATTR I
168 Result type ExpressionTextR
Expression text offset 234
Receiver Variable
Expression text length 7
Offset Field Value
180 Result type ExpressionValueR
Expression value offset 242 0 Bytes returned 48
Expression value length 3 Bytes available 48
Entry count 3
192 Result type ExpressionTypeR
Expression type kEnum____E 12 Result type TypeR
Reserved Type record count 3
Reserved
204 String space See Note.
24 Result type TypeDescR
Note: s1.iØ1Øs1.fØ5.0E+00Øs1.s2.cØaØs1.s2.eØredØ
Type kZonedTE_E
Length 1
Step Statement Example 36 Result type DecimalR
Total digits 1
C Program Fragment: Assume program operation is sus- Fractional digits 0
pended in the program shown in Figure 17-12 just before
line 6 runs.
WATCH Statement Example

Line C Source C Program Fragment: Consider the C program fragment in

Figure 17-14. Variable i defines an integer.
1 #include stdio.h
2 int T[] = {1,2,3,5,7,11,13,17,23,29};
3 int BinarySearch(int v, int f, int l);
4 main() Line C Source
5 { int result;
6 result = BinarySearch(17,ð,9);
7 printf("result= "); printf("%d",result); printf(" \n"); 1 int i = 29;
8 }
Figure 17-14. Program for Scalar Evaluate Example
Figure 17-12. Program for Step Example
Input Buffer
Input Buffer WATCH i
STEP
Receiver Variable
Receiver Variable
Offset Field Value
Offset Field Value 0 Bytes returned 83
0 Bytes Returned 24 Bytes available 83
Bytes Available 24 Entry count 4
Entry Count 1 12 Result type WatchR
12 Result type StepR Watch results count 4
Step Count 1 Reserved
Reserved 24 Result type WatchNumberR
Watch number 1
ATTR Statement Example Watch length 4

17-58 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

CPF7E23 E Assignment type error occurred.

Offset Field Value
CPF7E24 E Line number not found.
36 Result type ExpressionTextR CPF7E25 E Array type error occurred.
Expression text offset 60
CPF7E26 E Subscript type error occurred.
Expression text length 1
CPF7E27 E Format type error occurred.
48 Result type ExpressionValueR CPF7E28 E Type error occurred.
Expression value offset 62 CPF7E29 E Unsupported bit field alignment
Expression value length 20
CPF7E2A E
60 String space See note. String constants are not supported.
Note: iØSPP:08006F0054001004Ø CPF7E2B E
Type compatibility error occurred.
CPF7E2C E
Error Messages Too few array dimensions specified.
CPF7E2D E
CPF1938 E Command is not allowed while serviced job is Too many array dimensions specified.
not active. CPF7E2E E
CPF1939 E Time-out occurred waiting for a reply from the Incorrectly formed range expression
serviced job. CPF7E2F E
CPF1941 E Serviced job has completed. Debug commands Range expression expands to exceed input
are not allowed. buffer
CPF3C19 E CPF7E50 E Decimal type error occurred.
Error occurred with receiver variable specified. CPF7E51 E Decimal size error occurred.
CPF3C24 E CPF7E52 E Unsupported syntax.
Length of the receiver variable is not valid. CPF7E53 E Assignment size error occurred.
CPF3CF1 E CPF7E54 E Integer type error occurred.
Error code parameter not valid. CPF7E55 E Constant type error occurred.
CPF7102 E Unable to add breakpoint or trace. CPF7E56 E Identifier is ambiguous.
CPF7E01 E Pointer to receiver variable is NULL. CPF7E57 E Integer constant not valid.
CPF7E02 E Receiver variable length not valid. CPF7E58 E Compiler not valid.
CPF7E03 E Pointer to input buffer is NULL. CPF7E59 E String type error occurred.
CPF7E04 E Input buffer length not valid. CPF7E5A E
CPF7E05 E Input buffer is not as long as specified. Substring extends beyond end of string.
CPF7E06 E Pointer to error code structure is NULL. CPF7E5B E
CPF7E07 E Not enough space was provided for error code. Format length error occurred.
CPF7E08 E Value of BytesProvided field is not correct. CPF7E5C E
CPF7E09 E Value of BytesProvided field, &1, is not correct. Hexadecimal constant not valid.
CPF7E10 E Internal error occurred. CPF7E5D E
CPF7E11 E Type error occurred. Decimal constant size error occurred.
CPF7E12 E Identifier does not exist. CPF7E5E E
CPF7E14 E Field does not exist. Integer constant size error occurred.
CPF7E15 E Syntax error occurred. CPF7E5F E
CPF7E16 E Token error occurred. Relational size error occurred.
CPF7E17 E Structure type error occurred. CPF7E60 E Constant not a decimal number.
CPF7E18 E Pointer type error occurred. CPF7E61 E System cannot determine which expansion of
CPF7E19 E Integral type error occurred. the template to use.
CPF7E1A E CPF7E62 E Watch cannot be set on this variable.
Enumerated type error occurred. CPF7E63 E Watch length is not valid.
CPF7E1B E CPF7E64 E Clear watch number not found.
Arithmetic type error occurred. CPF8E03 E Internal error occurred.
CPF7E1C E CPF8E04 E Internal error occurred.
Scalar type error occurred. CPF8E05 E Error on equal operator.
CPF7E1D E CPF8E06 E Error on not-equal operator.
Address type error occurred. CPF8E07 E Error on greater-than operator.
CPF7E1E E CPF8E08 E Error on greater-than-or-equal-to operator.
Adding type error occurred. CPF8E09 E Error on less-than operator.
CPF7E1F E CPF8E0A E
Subtracting type error occurred. Error on less-than-or-equal-to operator.
CPF7E20 E Relational type error occurred. CPF8E0B E
CPF7E21 E Equality type error occurred. Error on logical-and operator.
CPF7E22 E Casting type error occurred.

Chapter 17. Debugger APIs 17-59

Submit Debug Command (QteSubmitDebugCommand) API

CPF8E0C E Ÿ Entering step statements to run one or more statements

Error on logical-or operator. of the program under investigation
CPF8E0D E
Ÿ Entering watch statements to stop the program when a
Error on logical-exclusive-or operator.
specified storage location is changed
CPF8E0E E
Error on logical-not operator. The clear statement enables programmers to remove a par-
CPF8E0F E ticular breakpoint or all breakpoints. It can also be used to
Error on add operator. clear watches. Information about the state of the program
CPF8E10 E Error on subtract operator. being debugged can be extracted when program processing
CPF8E11 E Error on negate operator. is suspended. The evaluate statement permits programmers
CPF8E12 E Error on multiply operator. to display the value of an expression, or to display an aggre-
CPF8E13 E Error on divide operator. gate, and to alter the value of a variable.
CPF8E14 E Error on increment operator.
Debug language statements are constructed by the client
CPF8E15 E Error on decrement operator.
program and placed in the input buffer. If multiple debug lan-
CPF8E16 E Error on modulo operator.
guage statements are placed in the input buffer, they must
CPF8E17 E Pointer not set for location referenced.
be separated by one or more blanks. The Submit Debug
CPF8E18 E Conversion error.
Command API accepts the debug language statements of
CPF8E19 E Error on absolute value operator.
ATTR, BREAK, CLEAR, EVAL, QUAL, STEP, TBREAK, and
CPF8E1A E
WATCH.
Domain violation occurred.
CPF8E1B E
When multiple debug statements are specified in the same
Domain violation occurred.
input buffer, a QUAL statement must not follow an EVAL
CPF8E1C E
statement. The WATCH debug statement cannot be speci-
Error on write operator.
fied with any other debug statement, including another
CPF8E1D E
WATCH statement.
Error on shift operator.
CPF8E1E E
Error on operand value. ATTR Statement
CPF8E1F E
Error on load constant operator. The variable appearing in an ATTR statement is found in the
CPF8E20 E Error on load address operator. debug symbol table. The symbol table information for the
CPF8E21 E Error on store indirect operator. variable is returned.
CPF8E22 E Error on move operator.
The following example shows an ATTR statement:
CPF8E23 E Error on fill operator.
CPF8E24 E Incorrect array index value. ─5ATTR──5variable──5
CPF8E25 E Call stack entry does not exist.
The locality of variables that appear in an ATTR statement is
CPF8E26 E Translation failed.
defined by the most recently run qualify statement. The
CPF8E27 E Call to user method failed.
program calling this API is advised to issue a qualify state-
CPF8E28 E Variable not available to display.
ment that defines the stop position when program operation
CPF8E29 E Debug recursion error.
is suspended.
CPF8E2A E
Error occurred while processing operation.
CPF8E2B E Break Statement
Watch cannot overlap another active watch.
CPF8E2C E The break statement permits a programmer to enter a break-
Maximum number of watches exceeded. point. Breakpoints are entered on the program under investi-
CPF9541 E Not in debug mode. gation. When the program under investigation encounters a
CPF9542 E View not found. breakpoint, operation is suspended.
CPF9549 E Error addressing API parameter.
The following example shows a break statement:
─5BREAK──5position──5
Debug Language Statements ─5BREAK──5position──┬────────────────────┬─5
└─WHEN──5expression──┘
Debug language statements are the principal mechanism by
which a programmer debugs a program. Programmers The position marks where program operation is suspended
control the operation of a program by: when a breakpoint is encountered. Line numbers are used
Ÿ Entering break statements to select where the program to identify the position when the break statement is entered.
will stop The line number entered is mapped to a statement by the
Submit Debug Command API. A breakpoint causes the
program to stop just before the break statement is run.

17-60 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

Unconditional and conditional breakpoints can be entered. Clear Statement

Unconditional breakpoints are discussed first, followed by a
discussion of conditional breakpoints. The clear statement enables a programmer to remove a par-
ticular breakpoint or all breakpoints in a program. Particular
An unconditional breakpoint is entered by issuing the first breakpoints are identified by the number of the line on which
form of the break statement. they are active. All breakpoints in a program are designated
─5BREAK──5position──5 by the keyword PGM. The clear statement is also used to
clear one or all watch conditions. The keyword WATCH fol-
A line number is entered for the position. Line numbers are lowed by the ALL keyword clears all watch conditions. If a
associated with each view in that they identify the lines of watch number is specified after the WATCH keyword, only
source in a view. Line numbers are assigned sequentially the watch represented by that watch number is cleared.
beginning with line one.
The following example shows a clear statement:
A conditional breakpoint is entered by issuing the second
─5CLEAR──┬──5position──┬─5
form of the break statement. ├───PGM───────┤
─5BREAK──5position──┬─────────────────────┬─5 └───WATCH─────┴───┬───────ALL────────┬──5
└──WHEN──5expression──┘ └───watch number───┘

The position of a conditional breakpoint is assigned in the For threaded applications, if a thread breakpoint is in effect
same way as the position in an unconditional breakpoint. A at the position specified, it is cleared in the current thread
line number is entered for the position. only. If the breakpoint is a job breakpoint, it is cleared for
the job. When the clear statement with the PGM keyword is
The condition of a conditional breakpoint is the expression specified, it will remove all job and thread breakpoints.
following the reserved word WHEN. The result of the
expression must have a Boolean or a logical value when
evaluated. The expression is interpreted before the state- Evaluate Statement
ment on which the breakpoint was entered is run. If the
The expression appearing in an evaluate statement is evalu-
value of the expression is TRUE, operation of the program
ated, and the value of the expression is returned. The value
investigation is suspended. If the value of the expression is
of an expression is formatted according to the expression
FALSE, operation continues without interruption.
type.
The locality of variables used in the conditional expression is
The following example shows an evaluate statement:
defined by the line number that defines the position.
─5EVAL──5expression───┬─────────────────────────┬────────5
└────formatting option────┘
A breakpoint can be replaced by entering another breakpoint
using the same position. The most recent breakpoint An evaluate statement allows a programmer to display the
entered on a position is the active breakpoint. value of an expression or an aggregate, or to alter the value
of a variable. The precise definition of what can be dis-
BREAK may be replaced by the reserved word AT in the
played or altered is dependent on the language of the
statement that defines the break statement.
module being debugged.
─5AT──5position──5
─5AT──5position──┬─────────────────────┬─5 Variables can be displayed or altered when program pro-
└──WHEN──5expression──┘ cessing is suspended. Program operation is temporarily sus-
pended as a result of encountering a breakpoint or
For threaded applications, breakpoints that are specified with
completing a step statement. It is also suspended when a
the break statement are global to all threads in the job being
watch condition is satisfied.
debugged. These are called job breakpoints. Thread-
specific breakpoints are set with the tbreak statement. A job Variables are formatted according to their type recorded in
may not have both a job breakpoint and thread breakpoints the HLL symbol table, and according to the language of the
at the same position. When a job breakpoint is in effect and module being debugged. Formats available include integer,
a thread breakpoint is specified, the job breakpoint is hexadecimal, exponential, and address, among others.
replaced. When thread breakpoints are in effect and a job
breakpoint is specified, the thread breakpoints are replaced. Variables also may be formatted using the formatting option.
The formatting option has the general form of: :<format
code> <length>, such as EVAL STRING :s 50.

The :<format code> can be one of the following:

Format Description
Code
:c An EBCDIC single-character format
:x A hexadecimal format

Chapter 17. Debugger APIs 17-61

Submit Debug Command (QteSubmitDebugCommand) API

:s An EBCDIC character-string format (only for Figure 17-15. Presentation Formats

the C and C++ languages)
Type Format Example
:f An EBCDIC character-string format (only for
the C and C++ languages). This returned kBinD_32_E dd.ddd 5678.01
-dd.ddd
type can be used by the source debugger to
kBinD_64_E dd.ddd 5678.01
indicate that alternative formatting was
-dd.ddd
requested by the user.
kFixedL__E ccccc Hello World
:a An ASCII character-string format (only for the
ILE languages). The string is converted from kHex_____E xx xx xx xx F1 F2 F3

the job CCSID's related-ASCII CCSID to the kCard_32_E dd...d 546

job CCSID. kReal_64_E +d.d...dE+dd -1.2345678901234E-95
:u A Unicode character-string format (only for ILE -d.d...dE-dd
languages). The string is converted from KSpcPtr__E Pointer types: SPP:*NULL
Unicode CCSID 13488 to the job CCSID. BEP (behavior) IVP:COFE001001201003
IVP (invocation) SPP:COCE100201021003
LBL (label)
The <length> is a positive integer that indicates the number MTP (method)
of bytes to format. The defaults for the format codes are as OBP (object)
follows: PRP (procedure)
SPP (space)
Format Default SYP (system)
Code
:c 1 For threaded applications, the EVAL statement is run in the
:x The length of the expression value current thread.
:s 30
:f 1024 Locality: Locality is the term used to describe the range
:a 1024 over which an entity may be referred to in a module. The
:u 1024 terms locality and scope are synonymous. By this definition,
the locality of an entity is always confined to the compilation
The locality of variables that appear in an evaluate statement unit in which it was declared.
is defined by the most recently run qualify statement. The
program calling this API is advised to issue a qualify state- Entity is a formal way of describing all things that can be
ment that defines the stop position when program operation declared in a module. Variables, procedures, labels, types,
is suspended. and constants are entities.

EVAL may be replaced by the reserved word LIST in the The locality of an entity is defined by the block in which it is
statement that defines the evaluate statement. declared. An entity is visible in the block in which it is
─5LIST──5expression───┬─────────────────────────┬────────5 declared and all subordinate blocks. A variable can be
└────formatting option────┘ referred to in the block in which it is declared.
Figure 17-15 describes the formatting of data by type.
An entity may be declared in a block that encloses other
blocks. The entity declared in the outer, enclosing block is
Figure 17-15. Presentation Formats
visible in inner blocks if the name does not collide with other
Type Format Example entities in inner blocks. A variable declared in an outer block
kChar__8_E c A can be referred to in an inner block if no variable of the same
kChar_16_E Shift-out cc... shift-in name is declared in the inner block.
kEnum____E ccccc (dd) yellow (25)
To fully qualify a particular locality in a program, both
kString__E ccccccccc Hello World
program and module must be identified.
kInt_32__E -dd...d -676
dd...d
kPacked__E dd.ddd 5678.01 Qualify Statement
-dd.ddd
kZonedTE_E dd.ddd 5678.01 The qualify statement permits a programmer to define the
-dd.ddd locality of variables that appear in succeeding evaluate state-
kZonedTS_E dd.ddd 5678.01 ments. Locality is defined by the line number operand on the
-dd.ddd qualify statement. The locality assigned is that block in
kZonedLE_E dd.ddd 5678.01 which the line number appears.
-dd.ddd
kZonedLS_E dd.ddd 5678.01 The following example shows a qualify statement:
-dd.ddd ─5QUAL──5position──5
kBinD_16_E dd.ddd 5678.01
-dd.ddd

17-62 AS/400 System API Reference V4R4

 Submit Debug Command (QteSubmitDebugCommand) API

The locality assigned when a qualify statement is issued TBreak Statement

remains in effect until the next qualify statement is issued.
The Submit Debug Command API keeps the locality The tbreak statement permits a programmer to enter a
assigned for the purpose of evaluating expressions. Users of breakpoint for the current thread. Breakpoints are entered
the Submit Debug Command API are advised to issue the on the program under investigation. When the program
qualify statement whenever program operation is suspended. under investigation encounters a breakpoint in the thread,
Use the line number of the stopped position to identify the operation is suspended. The tbreak statement has the same
current locality. In this way, programmers may issue several format and operation as the break statement.
evaluate statements that refer to variables that are defined in
the locality of the stopped position. Each thread in a threaded application may have a different
thread breakpoint at the same position. Job breakpoints and
For threaded applications, the QUAL statement is run in the thread breakpoints cannot coexist.
current thread.
A tbreak statement entered at the same position as a tbreak
that was specified earlier in the same thread is replaced by
Step Statement the new thread breakpoint.
The step statement permits a programmer to run one or A tbreak statement entered at the same position as a job
more statements of the program under investigation for breakpoint that was specified earlier replaces the job break-
testing purposes. The program being tested runs the point with a thread breakpoint.
number of statements specified in the statement-count
operand. Operation of the program under test is suspended A break statement entered at the same position as thread
at completion of the step statement. breakpoints that were specified earlier replaces all thread
breakpoints at that position with a job breakpoint that is in
The following example shows a step statement: effect for all threads.
─5STEP──5
─5STEP──5OVER──5
Watch Statement
─5STEP──5INTO──5
─5STEP──┬──51────────────────┬─┬──5OVER──┬─5 The watch statement permits a programmer to request a
└───statement─count──┘ └───INTO──┘ breakpoint when the content of a specified storage location is
changed from its current value. After the watch condition is
If no value is entered for the statement-count, one statement
successfully set, a change to the content of the watched
is run.
storage location causes program operation to be suspended.
The reserved words OVER and INTO direct the source Then the Program Stop Handler exit program that is speci-
debugger to step over or into procedures, respectively. If fied on the Start Source Debug API is called.
OVER appears in a step statement, the source debugger
The following shows the syntax of the watch statement:
does not suspend operation in any procedures that are
called. Procedures and functions are run without inter- ─5WATCH──5expression───┬──────────────────────┬───5
└─── : watch length ───┘
ruption.
The expression is used to determine the address of the
The INTO reserved word directs the source debugger to stop
storage location to watch. The expression must resolve to
in procedures that are called.
an lvalue (that is, a location that can be assigned to). If an
If neither INTO or OVER is entered on the step statement, expression is specified that is not supported, error code
OVER is assumed. CPF7E62 is returned. The scope of the expression variables
in a watch statement is defined by the most recently issued
There are some step limitations. The following code cannot QUAL debug language statement.
be entered using the step statement:
The length of the watch comparison operation is the same as
Ÿ Procedures in modules that have no debug data. the expression type length, or the length specified with the
Ÿ Modules that are optimized at level 40. optional watch length parameter. For example, if a 4-byte
binary integer is specified without the watch length param-
For threaded applications, the STEP statement is run in the eter, the comparison length is 4 bytes. If the watch length
current thread. Each thread can step independently of each parameter is specified, it overrides the length of the
other, at the same time. expression in determining the watch length. The watch
length specification format is a colon character followed by
the length in bytes to watch. For example, the watch
command below would watch 2 bytes starting at the first byte
of variable i:

watch i : 2

Chapter 17. Debugger APIs 17-63

Debug Session Handler Exit Program

The watch length must be in the range 1 through 128 bytes. program is called by the STRDBG command to initialize the
If the watch length is not valid, error code CPF7E63 is user-written debugger, and is called by the End Debug
returned. (ENDDBG) command to end it. It is also called by the
STRDBG and the Display Module Source (DSPMODSRC)
The maximum number of watches that can be active across commands to show the Display Module Source display.
the entire system is guaranteed to be at least 128, but may
range up through 256, depending on how the watched If a JAVA class file name was specified in the JAVA param-
storage is mapped by the system. This includes dedicated eter of the STRDBG command, the Debug Session Handler
service tools (DST) watches. Exceeding this number results exit program will be called during debug initialization with a
in error code CPF8E2C being returned. A user session may reason of *STARTJAVA. This call will be in addition to a
have as many watches as are available. separate call with a *START reason if ILE or OPM programs
were also specified in the STRDBG PGM parameter.
There are some restrictions on overlapping watch locations.
If any of the following conditions are true, error code
CPF8E2B is returned: Required Parameter Group
Ÿ Watches in same job: Two watch locations may not Reason
overlap in any way. INPUT; CHAR(10)
Ÿ Watches in different jobs: Two watch locations may not The reason the program was called. Valid reasons
start at the same storage address. Otherwise, overlap is include:
permitted.
*START The program-stop handler should be ini-
A watch condition is cleared by using the CLEAR debug lan- tialized by the Start Source Debug API if
guage statement. this has not been done. The program list
parameter format consists of 30-character
It is important to understand that the watch statement estab- entries. See the program list parameter
lishes the watched storage location address when the watch description below.
statement is entered, and it does not change. This can *STARTJAVA
cause misleading results if a temporary storage location is The program-stop handler should be ini-
watched and that storage location is reused while the appli- tialized by the Start Source Debug API if
cation is running. An example of this is the automatic storage this has not been done. The program list
of an ILE C procedure, which can be reused if the procedure parameter format consists of JAVA class
ends. file names. See the program list param-
eter description below.
The WATCH debug statement cannot be specified with any *STOP The program-stop handler should be
other debug statement, including another WATCH statement. removed by the End Source Debug API.
*DISPLAY The debugger should display itself.
For threaded applications, the WATCH statement is run in *RLSJOB The batch job being debugged has been
the current thread. The address watched is global to all released from the job queue. This is only
threads. Any thread changing a watched location will cause supported for a debug session handler
a breakpoint in that thread. running in a batch job.

Program list
Debug Session Handler Exit Program INPUT; CHAR(*)
The format of this parameter depends on the value of
the reason parameter. If the reason parameter is
Required Parameter Group: *START, the program list format is as follows:

1 Reason Input Char(10) The list that is to receive a list of ILE or OPM programs
2 Program list Input Char(*) to add to the debugger. This list contains the number of
3 Number of programs Input Binary(4) program entries, each entry being 30 characters in
length. The first 10 characters contain the name of the
Threadsafe: No program. The second 10 characters contain the name
of the library where the program is located. The third 10
characters contain the type of object being named and
The Debug Session Handler exit program is a user-written
can be *PGM (a callable program) or *SRVPGM (a
program that manages the Integrated Language Environment
service program). Each name is left-justified within the
(ILE) debugger. It determines when the debugger starts,
field.
stops, and shows its displays.
If the reason parameter is *STARTJAVA, the format is
The name of the program is specified in the SRCDBGPGM as follows:
parameter of the Start Debug (STRDBG) command. This

17-64 AS/400 System API Reference V4R4

 Program-Stop Handler Exit Program

A list of JAVA class file name entries. For more infor- Field Descriptions
mation see “Format of *STARTJAVA Program List
Parameter” on page 17-65. The number of list entries is Class file names. The class file names that are specified
contained in the number of programs parameter. on the STRDBG command.
| If the reason parameter is *DISPLAY, the format is as
Length of class file name. The length of the class file
| follows:
name.
| The eight-character thread identifier of the current
| thread. This is valid only if threads debugging is allowed Offset to class file name. The offset from the start of the
| and the number of programs parameter contains a value program list parameter to the class file name.
| of 1.
| If the reason parameter is *STOP or *RLSJOB, this
| parameter is not valid. Program-Stop Handler Exit Program
Number of programs
INPUT; BINARY(4) Required Parameter Group:
| The format of this parameter depends on the value of
1 Qualified program name Input Char(20)
| the reason parameter. If the reason parameter is
or Char(*)
| *START or *STARTJAVA, the format is as follows: 2 Program type Input Char(10)
| The number of programs stored in the program list 3 Module name Input Char(10)
| parameter. 4 Stop reason Input Char(10)
5 Receiver variable Input Char(*)
| If the reason parameter is *DISPLAY, the format is as 6 Number of entries Input Binary(4)
| follows: 7 Message data Input Char(*)

| The status of the threaded job. This is valid only if QSYSINC Member Name: ETEPGMST
| threads debugging is allowed.
Threadsafe: No
| 0 The job is running and has not been
| stopped by debug (for example, break-
| point, step, watch, or unmonitored excep- The Program-Stop Handler exit program is a user-written
| tion). program that handles program-stop conditions.
| 1 The job is stopped by debug.
This program must be identified to the Source Debugger
| If the reason parameter is *STOP or *RLSJOB, this
support with the Start Source Debug (QteStartSourceDebug)
| parameter is not valid.
API.

Format of *STARTJAVA Program List Breakpoint- and step-program stop conditions are reported
using stop reasons 2, 3, and 4. The location at which the
Parameter program-stop condition occurred is specified in the receiver
When the reason parameter is *STARTJAVA the program list variable parameter and is in terms of the statement view.
parameter contains JAVA class file names. The following The user-supplied program may use the Map View Position
table shows the format of the program list parameter for the (QteMapViewPosition) API to determine the location to which
*STARTJAVA reason. For more information on the fields, this program maps any other registered view.
see “Field Descriptions.”
Watch-program stop conditions are reported using stop
reasons 5 and 6. For watch-program stop conditions, the
Offset
program stopped might not have debug data. In this case,
Dec Hex Type Field the machine interface (MI) number is reported for OPM pro-
Note: The following fields are repeated for each input class file grams and the statement number is reported for ILE pro-
name. The number of programs parameter contains the grams. If the program can be debugged, the line number in
number of class file names. the statement view is reported for both OPM and ILE pro-
0 0 BINARY(4) Offset to class file name grams. Other information is also included in the receiver var-
iable to identify the program that caused the watch condition
4 4 BINARY(4) Length of class file name
to be satisfied.
Note: Following all of the above fields is a string space con-
taining the input class file names. Unmonitored-exception-program stop conditions are repre-
CHAR(*) Class file names sented through stop reason 1. Unmonitored exceptions are
reported through this exit program only when the program
and module identified have been created with debug data.
Without debugging data, the message that is the cause of

Chapter 17. Debugger APIs 17-65

Program-Stop Handler Exit Program

the unmonitored exception is issued, and the Program-Stop 1 This reason is set when an unmonitored
Handler exit program is not called. exception is received by the program
being serviced by the source debugger
When a job being debugged by a servicing job is stopped by support.
the QteStopDebuggedJob API, reason code 7 is reported. 0 No unmonitored exception
When this reason code is reported, none of the other input 1 Unmonitored exception
parameters are used and can be ignored. 2 The program stopped because an uncon-
ditional or conditional breakpoint was sat-
Debugging of threaded jobs is enabled by the thread ID field
isfied.
that is contained in the parameters passed to the stop
0 No break condition
handler. Threads debugging is supported if a service job is
1 Break condition
used to debug a job that was spawned by native threads
3 The program stopped because a step
support. For nonthreaded applications, the thread ID passed
condition was reached.
will always be that of the initial job thread.
0 No step condition
1 Step condition
Required Parameter Group 4 The program stopped because a condi-
tional breakpoint was set and there was a
Qualified program name failure in running the condition. The
INPUT; CHAR(20) or CHAR(*) program is stopped at the break position
The format of this parameter is dependent on the specified.
program type parameter. If the program type is *PGM or 0 No break condition failure
*SRVPGM, the format of this parameter is as follows: 1 Break condition failure
5 The program stopped because a watch
The name of the program that is stopped as a result of a
condition set with the watch debug state-
breakpoint, program step, or unmonitored exception.
ment was satisfied.
This parameter may also be the name of the program
0 No watch condition
that is stopped because a watch condition has been sat-
1 Watch condition
isfied.
6 The program stopped because there was
The first 10 characters contain the name of the program. a failure in processing the watch condi-
The second 10 characters contain the name of the tion.
library where the program is located. Each name is left- 0 No watch condition failure
justified. 1 Watch condition failure
If the program type is *CLASS, the format of this param- 7 The debugged job being serviced was
eter is as follows: stopped by the QteStopDebuggedJob
API.
The null-terminated class file name of the JAVA class. 0 Debugged job not stopped
Program type 1 Debugged job stopped
INPUT; CHAR(10) 8-10 Reserved. These characters are set to 0.

The object type of the program that is stopped. The Receiver variable
possible values are: INPUT; CHAR(*)

*PGM Bound program or OPM program Stop Reasons 1, 2, 3, 4:

*SRVPGM Service program If only stop reason 1, 2, 3, or 4 is present, the following
*CLASS JAVA class file receiver variable format is passed:
Module name A list of locations within the statement view where the
INPUT; CHAR(10) program stop condition occurred. This list contains the
number of entries where each number is defined as
The name of the module (left-justified) that is stopped.
follows:
The value of this field is blank for OPM programs and
JAVA class files. Stopped locations
Array of BINARY(4)
Stop reason
INPUT; CHAR(10) The line number in the statement view
where the program is stopped.
The reason the program was called. Each character of
Thread ID CHAR(8)
this parameter has a specific meaning. The characters
and their meanings are: The thread identification of the thread
where the program is stopped. This
value immediately follows the last stopped
location.

17-66 AS/400 System API Reference V4R4

 Program-Stop Handler Exit Program

Stop Reasons 5, 6: Watch Stopped Program Information: The following

Whenever stop reason 5 or 6 is present (other stop table shows the stopped program information that is supplied
reasons can be present also), the following receiver vari- in the receiver variable parameter. This data structure is
able format is passed: accessible by adding the offset to stopped program informa-
tion field in the receiver variable header to the address of the
Information about the watch stop condition, including the receiver variable.
program stopped and the program that caused the watch
condition to be satisfied. See “Format of Watch-Program
Offset
Stop Reason for Receiver Variable.”
Dec Hex Type Field
Stop Reason 7:
0 0 BINARY(4) Offset to stopped procedure
For stop reason 7, the receiver variable parameter is not name
used and can be ignored.
4 4 BINARY(4) Length of stopped proce-
Number of entries dure name
INPUT; BINARY(4) 8 8 BINARY(4) Offset to stopped locations
The number of positions stored in the receiver variable 12 C BINARY(4) Number of stopped
parameter. In some cases, it is not known exactly locations
where a program is stopped; therefore, multiple positions 16 10 CHAR(1) Stopped locations flag
are given. Each entry specifies one position in the state-
17 11 CHAR(3) Reserved
ment view. This number is not less than one nor greater
than three. At least one stopped position will be identi- 20 14 CHAR(8) Thread ID
fied; if stopped at more than one position, no more than CHAR(*) Reserved
the first three positions are made available. Array of Stopped locations
This parameter is valid when stop reason 1, 2, 3, or 4 is BINARY(4)
the only reason present (stop reason 5 or 6 cannot be CHAR(*) Stopped procedure name
present). If stop reason 5 or 6 is present, the receiver
variable contains the equivalent number of stopped
Watch Interrupt Information: The following table shows
locations parameter.
the watch-interrupt information that is supplied in the receiver
Message data variable parameter. This data structure is accessible by
INPUT; CHAR(*) adding the offset to watch interrupt information field in the
receiver variable header to the address of the receiver vari-
Information about the message. The information in this
able.
parameter is valid only when the stop reason specified is
an unmonitored exception. For a detailed description of
Offset
the format, see “Format of Message Data” on
page 17-68. Dec Hex Type Field
0 0 CHAR(26) Qualified interrupt job name

Format of Watch-Program Stop Reason for 26 1A CHAR(20) Qualified interrupt program

name
Receiver Variable
46 2E CHAR(10) Interrupt program type
The following table shows the information supplied in the
56 38 CHAR(10) Interrupt module name
receiver variable parameter when a stop reason of 5 or 6 is
present. For more information on the fields, see “Field 66 42 CHAR(1) Interrupt locations flag
Descriptions” on page 17-68. 67 43 CHAR(1) Reserved
68 44 BINARY(4) Offset to interrupt procedure
Watch Receiver Variable Header name
72 48 BINARY(4) Length of interrupt proce-
Offset
dure name
Dec Hex Type Field
76 4C BINARY(4) Offset to interrupt locations
0 0 BINARY(4) Watch number
80 50 BINARY(4) Number of interrupt
4 4 BINARY(4) Offset to stopped program locations
information
84 54 CHAR(8) Thread ID
8 8 BINARY(4) Offset to watch interrupt
CHAR(*) Reserved
information
Array of Interrupt locations
BINARY(4)
CHAR(*) Interrupt procedure name

Chapter 17. Debugger APIs 17-67

Program-Stop Handler Exit Program

Field Descriptions Offset to stopped procedure name. The offset from the
start of the receiver variable to the name of the procedure
Interrupt locations. A list of locations, of the type described that contains the stopped program location. This field is zero
by the interrupt locations flag, that caused the watch condi- if there is no stopped procedure name available (for
tion to be satisfied. example, OPM programs).

Interrupt locations flag. The type of the locations in the Offset to stopped program information. The offset from
interrupt locations field. All locations are of the same type. the start of the receiver variable to the stop information for
the program that is stopped as a result of the watch condition
1 Line number in statement view
being satisfied.
2 Statement number
3 MI number Offset to watch interrupt information. The offset from the
start of the receiver variable to the watch interrupt informa-
Interrupt module name. The name of the module (left-
tion. This data structure describes the program that caused
justified) in the program that caused the watch condition to
the interruption.
be satisfied. The value of this field is blank for OPM pro-
grams and JAVA class files. Qualified interrupt job name. The name of the job that
caused the watch condition to be satisfied. The first 10 char-
Interrupt procedure name. The procedure name of the pro-
acters contain the job name. The second 10 characters
cedure that contains the program locations that caused the
contain the user profile name. The next 6 characters contain
watch condition to be satisfied. For OPM programs the pro-
the job number. Each name is left-justified.
cedure name is not returned.
Note: This field is the same as the name of the job being
Interrupt program type. The object type of the program debugged. Watch program interruptions in other jobs are
that caused the watch condition to be satisfied. The possible ignored.
values follow:
Qualified interrupt program name. The name of the
*PGM Bound program or OPM program
program that caused the watch condition to be satisfied. The
*SRVPGM Service program
first 10 characters contain the name of the program. The
*CLASS JAVA class file
second 10 characters contain the name of the library where
Length of interrupt procedure name. The length of the the program is located. Each name is left-justified.
interrupt procedure name. This field is zero if there is no
Reserved. An ignored field.
interrupt procedure name available (for example, OPM pro-
grams). Stopped locations. A list of locations, of the type described
by the stop location flag, where the program stop condition
Length of stopped procedure name. The length of the
occurred.
stopped procedure name. This field is zero if there is no
stopped procedure name available (for example, OPM pro- Stopped locations flag. The type of the locations in the
grams). stop locations field. All stop locations are of the same type.
Number of interrupt locations. The number of locations in 1 Line number in the statement view
the program that caused the watch condition to be satisfied. 2 Statement number
At most, three locations are returned. 3 MI number

Number of stopped locations. The number of stopped Stopped procedure name. The name of the procedure that
program locations. At most, three stop locations are contains the stopped locations. For OPM programs the pro-
returned. cedure name is not returned.

Offset to interrupt locations. The offset from the start of Thread ID. This is an 8-byte thread identification that is
the receiver variable to the list of locations in the program assigned by the system. It identifies the thread associated
that caused the watch condition to be satisfied. with the stopped or interrupt locations fields.

Offset to interrupt procedure name. The offset from the Watch number. The watch number identifier of the watch
start of the receiver variable to the name of the procedure condition being satisfied. This is the same number that is
that contains the program location that caused the watch returned by the Submit Debug Command API when the
condition to be satisfied. This field is zero if there is no inter- watch condition was set.
rupt procedure name available (for example, OPM pro-
grams). Format of Message Data: The following table shows the
information supplied in the message data parameter. For
Offset to stopped locations. The offset from the start of more information on the fields, see “Field Descriptions” on
the receiver variable to the stopped program location entries. page 17-69.

17-68 AS/400 System API Reference V4R4

 Program-Stop Handler Exit Program

predefined message specified in the message ID field and

Offset
located in the message file field.
Dec Hex Type Field
0 0 BINARY(4) Length of message data Message file. The name of the message file that contains
the message identified in the message ID field.
4 4 CHAR(7) Message ID
11 B CHAR(20) Message file The first 10 characters contain the message file name. The
31 1F CHAR(1) Reserved
second 10 characters contain the name of the library where
the file can be located. Both entries are left-justified.
32 20 CHAR(512) Message data
Message ID. The identifying code of the message.

Field Descriptions Reserved. An ignored field.

Length of message data. The length of the data available

in the message data parameter, in bytes. This field contains
the length of the available message data for the predefined
message indicated in the message ID field.

Message data. The values for substitution variables in the

Chapter 17. Debugger APIs 17-69

Program-Stop Handler Exit Program

17-70 AS/400 System API Reference V4R4

 Directory Services

Part 8. Directory Services APIs

Chapter 18. Directory Services APIs . . . . . . . 18-1 ldap_compare_s()—Perform a Synchronous LDAP

Terminology . . . . . . . . . . . . . . . . . . . . 18-1 Compare Operation . . . . . . . . . . . . . . . . . 18-7
Lightweight Directory Access Protocol (LDAP) Client Parameters . . . . . . . . . . . . . . . . . . . . 18-7
APIs—Introduction . . . . . . . . . . . . . . . . . 18-1 Authorities and Locks . . . . . . . . . . . . . . . 18-7
LDAP Client APIs—Summary . . . . . . . . . . . 18-1 Return Value . . . . . . . . . . . . . . . . . . . 18-7
CCSID Considerations . . . . . . . . . . . . . . 18-2 Error Conditions . . . . . . . . . . . . . . . . . . 18-8
Thread Safety . . . . . . . . . . . . . . . . . . . 18-2 Error Messages . . . . . . . . . . . . . . . . . . 18-8
Header File . . . . . . . . . . . . . . . . . . . . 18-2 Related Information . . . . . . . . . . . . . . . . 18-8
ldap_abandon()—Abandon an LDAP Operation in ldap_count_attributes()—Retrieve Count of Attributes
Progress . . . . . . . . . . . . . . . . . . . . . . . 18-3 for an LDAP Entry . . . . . . . . . . . . . . . . . . 18-8
Parameters . . . . . . . . . . . . . . . . . . . . 18-3 Parameters . . . . . . . . . . . . . . . . . . . . 18-8
Authorities and Locks . . . . . . . . . . . . . . . 18-3 Authorities and Locks . . . . . . . . . . . . . . . 18-8
Return Value . . . . . . . . . . . . . . . . . . . 18-3 Return Value . . . . . . . . . . . . . . . . . . . 18-8
Error Conditions . . . . . . . . . . . . . . . . . . 18-3 Error Conditions . . . . . . . . . . . . . . . . . . 18-8
Error Messages . . . . . . . . . . . . . . . . . . 18-3 Error Messages . . . . . . . . . . . . . . . . . . 18-8
Related Information . . . . . . . . . . . . . . . . 18-3 Related Information . . . . . . . . . . . . . . . . 18-8
ldap_add()—Perform an LDAP Add Operation . . . . 18-3 ldap_count_entries()—Retrieve Count of LDAP Entries 18-8
Parameters . . . . . . . . . . . . . . . . . . . . 18-4 Parameters . . . . . . . . . . . . . . . . . . . . 18-8
Authorities and Locks . . . . . . . . . . . . . . . 18-4 Authorities and Locks . . . . . . . . . . . . . . . 18-9
Return Value . . . . . . . . . . . . . . . . . . . 18-4 Return Value . . . . . . . . . . . . . . . . . . . 18-9
Error Conditions . . . . . . . . . . . . . . . . . . 18-4 Error Conditions . . . . . . . . . . . . . . . . . . 18-9
Error Messages . . . . . . . . . . . . . . . . . . 18-4 Error Messages . . . . . . . . . . . . . . . . . . 18-9
Related Information . . . . . . . . . . . . . . . . 18-4 Related Information . . . . . . . . . . . . . . . . 18-9
ldap_add_s()—Perform an LDAP Add Operation ldap_count_values()—Retrieve Count of Attribute
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-4 Values . . . . . . . . . . . . . . . . . . . . . . . . 18-9
Parameters . . . . . . . . . . . . . . . . . . . . 18-4 Parameters . . . . . . . . . . . . . . . . . . . . 18-9
Authorities and Locks . . . . . . . . . . . . . . . 18-4 Authorities and Locks . . . . . . . . . . . . . . . 18-9
Return Value . . . . . . . . . . . . . . . . . . . 18-4 Return Value . . . . . . . . . . . . . . . . . . . 18-9
Error Conditions . . . . . . . . . . . . . . . . . . 18-5 Error Conditions . . . . . . . . . . . . . . . . . . 18-9
Error Messages . . . . . . . . . . . . . . . . . . 18-5 Error Messages . . . . . . . . . . . . . . . . . . 18-9
Related Information . . . . . . . . . . . . . . . . 18-5 Related Information . . . . . . . . . . . . . . . . 18-9
ldap_bind()—Perform an LDAP Bind Request . . . . 18-5 ldap_count_values_len()—Retrieve Count of Binary
Parameters . . . . . . . . . . . . . . . . . . . . 18-5 Attribute Values . . . . . . . . . . . . . . . . . . . 18-9
Authorities and Locks . . . . . . . . . . . . . . . 18-5 Parameters . . . . . . . . . . . . . . . . . . . . 18-9
Return Value . . . . . . . . . . . . . . . . . . . 18-5 Authorities and Locks . . . . . . . . . . . . . . . 18-10
Error Conditions . . . . . . . . . . . . . . . . . . 18-5 Return Value . . . . . . . . . . . . . . . . . . . 18-10
Error Messages . . . . . . . . . . . . . . . . . . 18-5 Error Conditions . . . . . . . . . . . . . . . . . . 18-10
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-5 Error Messages . . . . . . . . . . . . . . . . . . 18-10
Related Information . . . . . . . . . . . . . . . . 18-5 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-10
ldap_bind_s()—Perform an LDAP Bind Request Related Information . . . . . . . . . . . . . . . . 18-10
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-6 ldap_delete()—Perform an LDAP Delete Operation . 18-10
Parameters . . . . . . . . . . . . . . . . . . . . 18-6 Parameters . . . . . . . . . . . . . . . . . . . . 18-10
Authorities and Locks . . . . . . . . . . . . . . . 18-6 Authorities and Locks . . . . . . . . . . . . . . . 18-10
Return Value . . . . . . . . . . . . . . . . . . . 18-6 Return Value . . . . . . . . . . . . . . . . . . . 18-10
Error Conditions . . . . . . . . . . . . . . . . . . 18-6 Error Conditions . . . . . . . . . . . . . . . . . . 18-10
Error Messages . . . . . . . . . . . . . . . . . . 18-6 Error Messages . . . . . . . . . . . . . . . . . . 18-10
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-6 Related Information . . . . . . . . . . . . . . . . 18-10
Related Information . . . . . . . . . . . . . . . . 18-6 ldap_delete_s()—Perform an LDAP Delete Operation
ldap_compare()—Perform an LDAP Compare (Synchronous) . . . . . . . . . . . . . . . . . . . . 18-10
Operation . . . . . . . . . . . . . . . . . . . . . . 18-6 Parameters . . . . . . . . . . . . . . . . . . . . 18-11
Parameters . . . . . . . . . . . . . . . . . . . . 18-7 Authorities and Locks . . . . . . . . . . . . . . . 18-11
Authorities and Locks . . . . . . . . . . . . . . . 18-7 Return Value . . . . . . . . . . . . . . . . . . . 18-11
Return Value . . . . . . . . . . . . . . . . . . . 18-7 Error Conditions . . . . . . . . . . . . . . . . . . 18-11
Error Conditions . . . . . . . . . . . . . . . . . . 18-7 Error Messages . . . . . . . . . . . . . . . . . . 18-11
Error Messages . . . . . . . . . . . . . . . . . . 18-7 Related Information . . . . . . . . . . . . . . . . 18-11
Related Information . . . . . . . . . . . . . . . . 18-7

 Copyright IBM Corp. 1998, 1999

Directory Services

ldap_err2string()—Retrieve LDAP Error Message Usage Notes . . . . . . . . . . . . . . . . . . . . 18-16

String . . . . . . . . . . . . . . . . . . . . . . . . 18-11 Related Information . . . . . . . . . . . . . . . . 18-17
Parameters . . . . . . . . . . . . . . . . . . . . 18-11 ldap_get_values()—Retrieve a Set of Attribute Values
Authorities and Locks . . . . . . . . . . . . . . . 18-11 from an Entry . . . . . . . . . . . . . . . . . . . . 18-17
Return Value . . . . . . . . . . . . . . . . . . . 18-11 Parameters . . . . . . . . . . . . . . . . . . . . 18-17
Error Conditions . . . . . . . . . . . . . . . . . . 18-11 Authorities and Locks . . . . . . . . . . . . . . . 18-17
Error Messages . . . . . . . . . . . . . . . . . . 18-11 Return Value . . . . . . . . . . . . . . . . . . . 18-17
Related Information . . . . . . . . . . . . . . . . 18-11 Error Conditions . . . . . . . . . . . . . . . . . . 18-17
ldap_explode_dn()—Break a Distinguished Name into Error Messages . . . . . . . . . . . . . . . . . . 18-17
Its Components . . . . . . . . . . . . . . . . . . . 18-11 Related Information . . . . . . . . . . . . . . . . 18-17
Parameters . . . . . . . . . . . . . . . . . . . . 18-12 ldap_get_values_len()—Retrieve a Set of Binary
Authorities and Locks . . . . . . . . . . . . . . . 18-12 Attribute Values . . . . . . . . . . . . . . . . . . . 18-17
Return Value . . . . . . . . . . . . . . . . . . . 18-12 Parameters . . . . . . . . . . . . . . . . . . . . 18-18
Error Conditions . . . . . . . . . . . . . . . . . . 18-12 Authorities and Locks . . . . . . . . . . . . . . . 18-18
Error Messages . . . . . . . . . . . . . . . . . . 18-12 Return Value . . . . . . . . . . . . . . . . . . . 18-18
Related Information . . . . . . . . . . . . . . . . 18-12 Error Conditions . . . . . . . . . . . . . . . . . . 18-18
ldap_first_attribute()—Retrieve First Attribute in an Error Messages . . . . . . . . . . . . . . . . . . 18-18
Entry . . . . . . . . . . . . . . . . . . . . . . . . . 18-12 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-18
Parameters . . . . . . . . . . . . . . . . . . . . 18-12 Related Information . . . . . . . . . . . . . . . . 18-18
Authorities and Locks . . . . . . . . . . . . . . . 18-12 ldap_init()—Perform an LDAP Initialization Operation 18-18
Return Value . . . . . . . . . . . . . . . . . . . 18-12 Parameters . . . . . . . . . . . . . . . . . . . . 18-18
Error Conditions . . . . . . . . . . . . . . . . . . 18-13 Authorities and Locks . . . . . . . . . . . . . . . 18-19
Error Messages . . . . . . . . . . . . . . . . . . 18-13 Return Value . . . . . . . . . . . . . . . . . . . 18-19
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-13 Error Conditions . . . . . . . . . . . . . . . . . . 18-19
Related Information . . . . . . . . . . . . . . . . 18-13 Error Messages . . . . . . . . . . . . . . . . . . 18-19
ldap_first_entry()—Retrieve First LDAP Entry . . . . 18-13 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-19
Parameters . . . . . . . . . . . . . . . . . . . . 18-13 Related Information . . . . . . . . . . . . . . . . 18-19
Authorities and Locks . . . . . . . . . . . . . . . 18-13 ldap_is_ldap_url()—Verify LDAP URL . . . . . . . . 18-19
Return Value . . . . . . . . . . . . . . . . . . . 18-13 Parameters . . . . . . . . . . . . . . . . . . . . 18-19
Error Conditions . . . . . . . . . . . . . . . . . . 18-14 Authorities and Locks . . . . . . . . . . . . . . . 18-19
Error Messages . . . . . . . . . . . . . . . . . . 18-14 Return Value . . . . . . . . . . . . . . . . . . . 18-19
Related Information . . . . . . . . . . . . . . . . 18-14 Error Conditions . . . . . . . . . . . . . . . . . . 18-19
ldap_free_urldesc()—Free an LDAP URL Description 18-14 Error Messages . . . . . . . . . . . . . . . . . . 18-19
Parameters . . . . . . . . . . . . . . . . . . . . 18-14 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-19
Authorities and Locks . . . . . . . . . . . . . . . 18-14 Related Information . . . . . . . . . . . . . . . . 18-20
Return Value . . . . . . . . . . . . . . . . . . . 18-14 ldap_memfree()—Free Memory Allocated by LDAP
Error Conditions . . . . . . . . . . . . . . . . . . 18-14 API . . . . . . . . . . . . . . . . . . . . . . . . . 18-20
Error Messages . . . . . . . . . . . . . . . . . . 18-14 Parameters . . . . . . . . . . . . . . . . . . . . 18-20
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-14 Authorities and Locks . . . . . . . . . . . . . . . 18-20
Related Information . . . . . . . . . . . . . . . . 18-14 Return Value . . . . . . . . . . . . . . . . . . . 18-20
ldap_get_dn()—Retrieve the Distinguished Name of Error Conditions . . . . . . . . . . . . . . . . . . 18-20
an Entry . . . . . . . . . . . . . . . . . . . . . . . 18-14 Error Messages . . . . . . . . . . . . . . . . . . 18-20
Parameters . . . . . . . . . . . . . . . . . . . . 18-14 Related Information . . . . . . . . . . . . . . . . 18-20
Authorities and Locks . . . . . . . . . . . . . . . 18-15 ldap_modify()—Perform an LDAP Modify Entry
Return Value . . . . . . . . . . . . . . . . . . . 18-15 Request . . . . . . . . . . . . . . . . . . . . . . . 18-20
Error Conditions . . . . . . . . . . . . . . . . . . 18-15 Parameters . . . . . . . . . . . . . . . . . . . . 18-20
Error Messages . . . . . . . . . . . . . . . . . . 18-15 Authorities and Locks . . . . . . . . . . . . . . . 18-20
Related Information . . . . . . . . . . . . . . . . 18-15 Return Value . . . . . . . . . . . . . . . . . . . 18-20
ldap_get_errno()—Retrieve Error Information . . . . 18-15 Error Conditions . . . . . . . . . . . . . . . . . . 18-20
Parameters . . . . . . . . . . . . . . . . . . . . 18-15 Error Messages . . . . . . . . . . . . . . . . . . 18-21
Authorities and Locks . . . . . . . . . . . . . . . 18-15 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-21
Return Value . . . . . . . . . . . . . . . . . . . 18-15 Related Information . . . . . . . . . . . . . . . . 18-21
Error Conditions . . . . . . . . . . . . . . . . . . 18-15 ldap_modify_s()—Perform an LDAP Modify Entry
Error Messages . . . . . . . . . . . . . . . . . . 18-15 Request (Synchronous) . . . . . . . . . . . . . . . 18-21
ldap_get_option()—Retrieve LDAP Options . . . . . 18-15 Parameters . . . . . . . . . . . . . . . . . . . . 18-21
Parameters . . . . . . . . . . . . . . . . . . . . 18-15 Authorities and Locks . . . . . . . . . . . . . . . 18-21
Authorities and Locks . . . . . . . . . . . . . . . 18-15 Return Value . . . . . . . . . . . . . . . . . . . 18-22
Return Value . . . . . . . . . . . . . . . . . . . 18-16 Error Conditions . . . . . . . . . . . . . . . . . . 18-22
Error Conditions . . . . . . . . . . . . . . . . . . 18-16 Error Messages . . . . . . . . . . . . . . . . . . 18-22
Error Messages . . . . . . . . . . . . . . . . . . 18-16 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-22

AS/400 System API Reference V4R4

 Directory Services

Related Information . . . . . . . . . . . . . . . . 18-22 Error Messages . . . . . . . . . . . . . . . . . . 18-27

ldap_modrdn()—Perform an LDAP Modify RDN ldap_result()—Retrieve Result of an Asynchronous
Request . . . . . . . . . . . . . . . . . . . . . . . 18-22 LDAP Operation . . . . . . . . . . . . . . . . . . . 18-27
Parameters . . . . . . . . . . . . . . . . . . . . 18-22 Parameters . . . . . . . . . . . . . . . . . . . . 18-28
Authorities and Locks . . . . . . . . . . . . . . . 18-23 Authorities and Locks . . . . . . . . . . . . . . . 18-28
Return Value . . . . . . . . . . . . . . . . . . . 18-23 Return Value . . . . . . . . . . . . . . . . . . . 18-28
Error Conditions . . . . . . . . . . . . . . . . . . 18-23 Error Conditions . . . . . . . . . . . . . . . . . . 18-28
Error Messages . . . . . . . . . . . . . . . . . . 18-23 Error Messages . . . . . . . . . . . . . . . . . . 18-28
Related Information . . . . . . . . . . . . . . . . 18-23 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-29
ldap_modrdn_s()—Perform an LDAP Modify RDN Related Information . . . . . . . . . . . . . . . . 18-29
Request (Synchronous) . . . . . . . . . . . . . . . 18-23 ldap_result2error()—Retrieve LDAP Error Information 18-29
Parameters . . . . . . . . . . . . . . . . . . . . 18-23 Parameters . . . . . . . . . . . . . . . . . . . . 18-29
Authorities and Locks . . . . . . . . . . . . . . . 18-23 Authorities and Locks . . . . . . . . . . . . . . . 18-29
Return Value . . . . . . . . . . . . . . . . . . . 18-23 Return Value . . . . . . . . . . . . . . . . . . . 18-29
Error Conditions . . . . . . . . . . . . . . . . . . 18-23 Error Conditions . . . . . . . . . . . . . . . . . . 18-29
Error Messages . . . . . . . . . . . . . . . . . . 18-24 Error Messages . . . . . . . . . . . . . . . . . . 18-29
Related Information . . . . . . . . . . . . . . . . 18-24 ldap_search()—Perform an LDAP Search Operation 18-29
ldap_mods_free()—Free LDAP Modify Storage . . . 18-24 Parameters . . . . . . . . . . . . . . . . . . . . 18-30
Parameters . . . . . . . . . . . . . . . . . . . . 18-24 Authorities and Locks . . . . . . . . . . . . . . . 18-30
Authorities and Locks . . . . . . . . . . . . . . . 18-24 Return Value . . . . . . . . . . . . . . . . . . . 18-30
Return Value . . . . . . . . . . . . . . . . . . . 18-24 Error Conditions . . . . . . . . . . . . . . . . . . 18-30
Error Conditions . . . . . . . . . . . . . . . . . . 18-24 Error Messages . . . . . . . . . . . . . . . . . . 18-30
Error Messages . . . . . . . . . . . . . . . . . . 18-24 Related Information . . . . . . . . . . . . . . . . 18-30
Related Information . . . . . . . . . . . . . . . . 18-24 ldap_search_s()—Perform an LDAP Search Operation
ldap_msgfree()—Free LDAP Result Message . . . . 18-24 (Synchronous) . . . . . . . . . . . . . . . . . . . . 18-30
Parameters . . . . . . . . . . . . . . . . . . . . 18-24 Parameters . . . . . . . . . . . . . . . . . . . . 18-31
Authorities and Locks . . . . . . . . . . . . . . . 18-24 Authorities and Locks . . . . . . . . . . . . . . . 18-31
Return Value . . . . . . . . . . . . . . . . . . . 18-24 Return Value . . . . . . . . . . . . . . . . . . . 18-31
Error Conditions . . . . . . . . . . . . . . . . . . 18-25 Error Conditions . . . . . . . . . . . . . . . . . . 18-31
Error Messages . . . . . . . . . . . . . . . . . . 18-25 Error Messages . . . . . . . . . . . . . . . . . . 18-31
Related Information . . . . . . . . . . . . . . . . 18-25 Related Information . . . . . . . . . . . . . . . . 18-31
ldap_next_attribute()—Retrieve Next Attribute in an ldap_search_st()—Perform an LDAP Search
Entry . . . . . . . . . . . . . . . . . . . . . . . . . 18-25 Operation (Timed Synchronous) . . . . . . . . . . 18-31
Parameters . . . . . . . . . . . . . . . . . . . . 18-25 Parameters . . . . . . . . . . . . . . . . . . . . 18-32
Authorities and Locks . . . . . . . . . . . . . . . 18-25 Authorities and Locks . . . . . . . . . . . . . . . 18-32
Return Value . . . . . . . . . . . . . . . . . . . 18-25 Return Value . . . . . . . . . . . . . . . . . . . 18-32
Error Conditions . . . . . . . . . . . . . . . . . . 18-25 Error Conditions . . . . . . . . . . . . . . . . . . 18-32
Error Messages . . . . . . . . . . . . . . . . . . 18-25 Error Messages . . . . . . . . . . . . . . . . . . 18-32
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-25 Related Information . . . . . . . . . . . . . . . . 18-32
Related Information . . . . . . . . . . . . . . . . 18-25 ldap_set_option()—Set LDAP Options . . . . . . . . 18-32
ldap_next_entry()—Retrieve Next LDAP Entry . . . . 18-26 Parameters . . . . . . . . . . . . . . . . . . . . 18-33
Parameters . . . . . . . . . . . . . . . . . . . . 18-26 Authorities and Locks . . . . . . . . . . . . . . . 18-33
Authorities and Locks . . . . . . . . . . . . . . . 18-26 Return Value . . . . . . . . . . . . . . . . . . . 18-33
Return Value . . . . . . . . . . . . . . . . . . . 18-26 Error Conditions . . . . . . . . . . . . . . . . . . 18-33
Error Conditions . . . . . . . . . . . . . . . . . . 18-26 Error Messages . . . . . . . . . . . . . . . . . . 18-33
Error Messages . . . . . . . . . . . . . . . . . . 18-26 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-33
Related Information . . . . . . . . . . . . . . . . 18-26 Related Information . . . . . . . . . . . . . . . . 18-34
ldap_open()—Perform an LDAP Open Operation . . 18-26 ldap_set_rebind_proc()—Set Rebind Procedure . . . 18-34
Parameters . . . . . . . . . . . . . . . . . . . . 18-26 Parameters . . . . . . . . . . . . . . . . . . . . 18-34
Authorities and Locks . . . . . . . . . . . . . . . 18-27 Authorities and Locks . . . . . . . . . . . . . . . 18-34
Return Value . . . . . . . . . . . . . . . . . . . 18-27 Return Value . . . . . . . . . . . . . . . . . . . 18-34
Error Conditions . . . . . . . . . . . . . . . . . . 18-27 Error Conditions . . . . . . . . . . . . . . . . . . 18-34
Error Messages . . . . . . . . . . . . . . . . . . 18-27 Error Messages . . . . . . . . . . . . . . . . . . 18-34
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-27 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-34
Related Information . . . . . . . . . . . . . . . . 18-27 Related Information . . . . . . . . . . . . . . . . 18-34
ldap_perror()—Print LDAP Error Information . . . . . 18-27 ldap_simple_bind()—Perform a Simple LDAP Bind
Parameters . . . . . . . . . . . . . . . . . . . . 18-27 Request . . . . . . . . . . . . . . . . . . . . . . . 18-34
Authorities and Locks . . . . . . . . . . . . . . . 18-27 Parameters . . . . . . . . . . . . . . . . . . . . 18-35
Return Value . . . . . . . . . . . . . . . . . . . 18-27 Authorities and Locks . . . . . . . . . . . . . . . 18-35
Error Conditions . . . . . . . . . . . . . . . . . . 18-27 Return Value . . . . . . . . . . . . . . . . . . . 18-35

Part 8. Directory Services APIs

Directory Services

Error Conditions . . . . . . . . . . . . . . . . . . 18-35 Error Messages . . . . . . . . . . . . . . . . . . 18-43

Error Messages . . . . . . . . . . . . . . . . . . 18-35 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-43
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-35 Related Information . . . . . . . . . . . . . . . . 18-43
Related Information . . . . . . . . . . . . . . . . 18-35 ldap_url_search_st()—Perform an LDAP URL Search
ldap_simple_bind_s()—Perform a Simple LDAP Bind Operation (Timed Synchronous) . . . . . . . . . . 18-43
Request (Synchronous) . . . . . . . . . . . . . . . 18-35 Parameters . . . . . . . . . . . . . . . . . . . . 18-44
Parameters . . . . . . . . . . . . . . . . . . . . 18-35 Authorities and Locks . . . . . . . . . . . . . . . 18-44
Authorities and Locks . . . . . . . . . . . . . . . 18-36 Return Value . . . . . . . . . . . . . . . . . . . 18-44
Return Value . . . . . . . . . . . . . . . . . . . 18-36 Error Conditions . . . . . . . . . . . . . . . . . . 18-44
Error Conditions . . . . . . . . . . . . . . . . . . 18-36 Error Messages . . . . . . . . . . . . . . . . . . 18-44
Error Messages . . . . . . . . . . . . . . . . . . 18-36 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-44
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-36 Related Information . . . . . . . . . . . . . . . . 18-44
Related Information . . . . . . . . . . . . . . . . 18-36 ldap_value_free()—Free Memory Allocated by
ldap_ssl_start()—Start a Secure LDAP Connection . 18-36 ldap_get_values() . . . . . . . . . . . . . . . . . . 18-44
Parameters . . . . . . . . . . . . . . . . . . . . 18-36 Parameters . . . . . . . . . . . . . . . . . . . . 18-45
Authorities and Locks . . . . . . . . . . . . . . . 18-37 Authorities and Locks . . . . . . . . . . . . . . . 18-45
Return Value . . . . . . . . . . . . . . . . . . . 18-37 Return Value . . . . . . . . . . . . . . . . . . . 18-45
Error Conditions . . . . . . . . . . . . . . . . . . 18-37 Error Conditions . . . . . . . . . . . . . . . . . . 18-45
Error Messages . . . . . . . . . . . . . . . . . . 18-38 Error Messages . . . . . . . . . . . . . . . . . . 18-45
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-39 Related Information . . . . . . . . . . . . . . . . 18-45
Related Information . . . . . . . . . . . . . . . . 18-39 ldap_value_free_len()—Free Memory Allocated by
Example . . . . . . . . . . . . . . . . . . . . . . 18-39 ldap_get_values_len() . . . . . . . . . . . . . . . . 18-45
ldap_unbind()—Perform an LDAP Unbind Request . 18-39 Parameters . . . . . . . . . . . . . . . . . . . . 18-45
Parameters . . . . . . . . . . . . . . . . . . . . 18-40 Authorities and Locks . . . . . . . . . . . . . . . 18-45
Authorities and Locks . . . . . . . . . . . . . . . 18-40 Return Value . . . . . . . . . . . . . . . . . . . 18-45
Return Value . . . . . . . . . . . . . . . . . . . 18-40 Error Conditions . . . . . . . . . . . . . . . . . . 18-45
Error Conditions . . . . . . . . . . . . . . . . . . 18-40 Error Messages . . . . . . . . . . . . . . . . . . 18-45
Error Messages . . . . . . . . . . . . . . . . . . 18-40 Usage Notes . . . . . . . . . . . . . . . . . . . . 18-45
Related Information . . . . . . . . . . . . . . . . 18-40 Related Information . . . . . . . . . . . . . . . . 18-45
ldap_unbind_s()—Perform an LDAP Unbind Request LDAP Client API Error Conditions . . . . . . . . . . 18-45
(Synchronous) . . . . . . . . . . . . . . . . . . . . 18-40
Parameters . . . . . . . . . . . . . . . . . . . . 18-40 Chapter 19. Directory Services Configuration APIs 19-1
Authorities and Locks . . . . . . . . . . . . . . . 18-40 Directory Services Configuration APIs—Introduction . 19-1
Return Value . . . . . . . . . . . . . . . . . . . 18-40 Terminology . . . . . . . . . . . . . . . . . . . . 19-1
Error Conditions . . . . . . . . . . . . . . . . . . 18-40 Change Directory Server Attributes (QgldChgDirSvrA)
Error Messages . . . . . . . . . . . . . . . . . . 18-40 API . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Related Information . . . . . . . . . . . . . . . . 18-40 Authorities and Locks . . . . . . . . . . . . . . . 19-1
ldap_url_parse()—Parse an LDAP URL . . . . . . . 18-40 Required Parameter Group . . . . . . . . . . . . 19-2
Parameters . . . . . . . . . . . . . . . . . . . . 18-41 Format of Input Data . . . . . . . . . . . . . . . 19-2
Authorities and Locks . . . . . . . . . . . . . . . 18-41 CSVR0100 Format . . . . . . . . . . . . . . . 19-2
Return Value . . . . . . . . . . . . . . . . . . . 18-41 CSVR0200 Format . . . . . . . . . . . . . . . 19-2
Error Conditions . . . . . . . . . . . . . . . . . . 18-41 CSVR0300 Format . . . . . . . . . . . . . . . 19-3
Error Messages . . . . . . . . . . . . . . . . . . 18-41 CSVR0400 Format . . . . . . . . . . . . . . . 19-3
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-41 | CSVR0500 Format . . . . . . . . . . . . . . . 19-3
Related Information . . . . . . . . . . . . . . . . 18-41 Field Descriptions . . . . . . . . . . . . . . . . . 19-4
ldap_url_search()—Perform an LDAP URL Search Error Messages . . . . . . . . . . . . . . . . . . 19-7
Operation . . . . . . . . . . . . . . . . . . . . . . 18-41 Configure Directory Server (QgldCfgDirSvr) API . . . 19-7
Parameters . . . . . . . . . . . . . . . . . . . . 18-42 Authorities and Locks . . . . . . . . . . . . . . . 19-7
Authorities and Locks . . . . . . . . . . . . . . . 18-42 Required Parameter Group . . . . . . . . . . . . 19-8
Return Value . . . . . . . . . . . . . . . . . . . 18-42 Format of Input Data . . . . . . . . . . . . . . . 19-8
Error Conditions . . . . . . . . . . . . . . . . . . 18-42 CFGD0100 Format . . . . . . . . . . . . . . . 19-8
Error Messages . . . . . . . . . . . . . . . . . . 18-42 Field Descriptions . . . . . . . . . . . . . . . . . 19-8
Usage Notes . . . . . . . . . . . . . . . . . . . . 18-42 Error Messages . . . . . . . . . . . . . . . . . . 19-9
Related Information . . . . . . . . . . . . . . . . 18-42 Export LDIF File (QgldExportLdif) API . . . . . . . . 19-9
ldap_url_search_s()—Perform an LDAP URL Search Authorities and Locks . . . . . . . . . . . . . . . 19-9
Operation (Synchronous) . . . . . . . . . . . . . . 18-42 Required Parameter Group . . . . . . . . . . . . 19-9
Parameters . . . . . . . . . . . . . . . . . . . . 18-43 Format of Input Data . . . . . . . . . . . . . . . 19-10
Authorities and Locks . . . . . . . . . . . . . . . 18-43 LDIF0100 Format . . . . . . . . . . . . . . . . 19-10
Return Value . . . . . . . . . . . . . . . . . . . 18-43 Field Descriptions . . . . . . . . . . . . . . . . . 19-10
Error Conditions . . . . . . . . . . . . . . . . . . 18-43 Error Messages . . . . . . . . . . . . . . . . . . 19-10

AS/400 System API Reference V4R4

 Directory Services

Import LDIF File (QgldImportLdif) API . . . . . . . . 19-10 | Field Descriptions . . . . . . . . . . . . . . . . . 19-16

Authorities and Locks . . . . . . . . . . . . . . . 19-11 | Error Messages . . . . . . . . . . . . . . . . . . 19-17
Required Parameter Group . . . . . . . . . . . . 19-11 Retrieve Directory Server Attributes (QgldRtvDirSvrA)
Format of Input Data . . . . . . . . . . . . . . . 19-11 API . . . . . . . . . . . . . . . . . . . . . . . . . 19-17
LDIF0100 Format . . . . . . . . . . . . . . . . 19-11 Authorities and Locks . . . . . . . . . . . . . . . 19-18
Field Descriptions . . . . . . . . . . . . . . . . . 19-11 Required Parameter Group . . . . . . . . . . . . 19-18
Error Messages . . . . . . . . . . . . . . . . . . 19-11 Format of Output Data . . . . . . . . . . . . . . 19-18
List Directory Server Attributes (QgldLstDirSvrA) API 19-12 RSVR0100 Format . . . . . . . . . . . . . . . 19-18
Authorities and Locks . . . . . . . . . . . . . . . 19-12 RSVR0400 Format . . . . . . . . . . . . . . . 19-19
Required Parameter Group . . . . . . . . . . . . 19-12 Field Descriptions . . . . . . . . . . . . . . . . . 19-19
Format of Output Data . . . . . . . . . . . . . . 19-12 Error Messages . . . . . . . . . . . . . . . . . . 19-20
LSVR0200 Format . . . . . . . . . . . . . . . 19-12 Synchronize System Distribution Directory to LDAP
LSVR0300 Format . . . . . . . . . . . . . . . 19-13 (QGLDSSDD) API . . . . . . . . . . . . . . . . . . 19-20
| LSVR0500 Format . . . . . . . . . . . . . . . 19-13 inetOrgPerson and publisher Object Class . . 19-22
Field Descriptions . . . . . . . . . . . . . . . . . 19-13 System Distribution Directory to LDAP Mapping 19-22
Error Messages . . . . . . . . . . . . . . . . . . 19-14 Distinguished Name (dn) and Common Name
| Publish Directory Object (QgldPubDirObj) API . . . . 19-14 (cn) . . . . . . . . . . . . . . . . . . . . . . 19-22
| Authorities and Locks . . . . . . . . . . . . . . . 19-14 User Profile (uid) for AS/400 Users . . . . . . 19-23
| Required Parameter Group . . . . . . . . . . . . 19-14 Authorities and Locks . . . . . . . . . . . . . . . 19-23
| Format of Input Data . . . . . . . . . . . . . . . 19-15 Required Parameter Group . . . . . . . . . . . . 19-23
| POBJ0100 Format . . . . . . . . . . . . . . . 19-15 Usage Notes . . . . . . . . . . . . . . . . . . . . 19-24
| POBJ0200 Format . . . . . . . . . . . . . . . 19-15 Synchronization Procedure . . . . . . . . . . . 19-24
| POBJ0300 Format . . . . . . . . . . . . . . . 19-15 Error Messages . . . . . . . . . . . . . . . . . . 19-25
| POBJ0400 Format . . . . . . . . . . . . . . . 19-16

Part 8. Directory Services APIs

Directory Services

AS/400 System API Reference V4R4

 LDAP Client APIs

Chapter 18. Directory Services APIs

The Directory Services part includes the Lightweight Direc- being accessed may or may not be located on an AS/400.
tory Access Protocol (LDAP) client APIs and the directory The applications access the LDAP client by using these
services configuration APIs. This chapter discusses the client APIs. TCP/IP is always used to access remote directo-
LDAP client APIs, and the following chapter discusses the ries, and the administrator can configure the connection to
directory services configuration APIs. either use the Secure Sockets Layer (SSL) or not.
Note: To use the Directory Services APIs, you need to
Terminology install the OS/400 Directory Services feature. You can install
this feature by using the GO LICPGM function of OS/400.
The following terms are used in various APIs within the Select the Install licensed programs option on the Work with
Directory Services part: Licensed Programs display, and the OS/400 Directory Ser-
vices option on the Install Licensed Programs display.
Backus-Naur Form (BNF). A standard form that is used to
write formal language descriptions.
LDAP Client APIs—Summary
certificate. A digital document that binds a public key to the
identity of the certificate owner, thereby enabling the certif- Figure 18-1 lists the LDAP client functions and what they do.
icate owner to be authenticated. A certificate authority issues
a certificate. Figure 18-1 (Page 1 of 2). LDAP Client Functions
Function Description
Certificate authority. An organization that issues certif-
icates. The certificate authority authenticates the certificate ldap_abandon() Abandon an LDAP operation in
progress
owner's identity and the services that the owner is authorized
to use. The certificate authority also manages the issuance ldap_add() Perform an LDAP add operation
of new certificates and the revocation of certificates that ldap_add_s() Perform an LDAP add operation
belong to users who are no longer authorized to use them. (synchronous)
A certificate authority is considered to be trusted when a user
ldap_bind() Perform an LDAP bind request
accepts any certificate issued by that certificate authority as
proof of the certificate owner's identity. ldap_bind_s() Perform an LDAP bind request (syn-
chronous)
Chase. To retry an LDAP request against a server that was ldap_compare() Perform an LDAP compare opera-
received as a referral. tion
ldap_compare_s() Perform a synchronous LDAP
Key ring file. A file that contains public keys, private keys, compare operation
trusted roots, and certificates.
ldap_count_attributes() Retrieve count of attributes for an
Leaf. An entry that has no children beneath it in the direc- LDAP entry
tory tree. ldap_count_entries() Retrieve count of LDAP entries
ldap_count_values() Retrieve count of attribute values
ldap_count_values_len() Retrieve count of binary attribute
Lightweight Directory Access Protocol values
(LDAP) Client APIs—Introduction ldap_delete() Perform an LDAP delete operation
Lightweight Directory Access Protocol (LDAP) is an Internet ldap_delete_s() Perform an LDAP delete operation
protocol to access directory servers. The directories on the (synchronous)
Internet may be "pure" LDAP directories, that is, they only ldap_err2string() Retrieve LDAP error message string
communicate through LDAP, or they may be X.500 or other
ldap_explode_dn() Break a distinguished name into its
types of servers that allow access through LDAP. Access to components
servers that are not pure LDAP servers is accomplished
ldap__first_attribute() Retrieve first attribute in an entry
through an LDAP gateway. Gateways from LDAP to other
protocols are also common. Client programs that allow a ldap_first_entry() Retrieve first LDAP entry
user to access an LDAP directory are called LDAP clients. ldap_free_urldesc() Free an LDAP URL description
Applications that extract information from an LDAP directory
ldap_get_dn() Retrieve the distinguished name of
are referred to as LDAP-enabled.
an entry
The LDAP client is part of the OS/400. The LDAP client is ldap_get_errno() Retrieve Error Information
used by OS/400 and customer applications for access to ldap_get_option() Retrieve LDAP Options
LDAP-enabled directories in the network. The directories

 Copyright IBM Corp. 1998, 1999 18-1

LDAP Client APIs

Figure 18-1 (Page 2 of 2). LDAP Client Functions Figure 18-1 (Page 2 of 2). LDAP Client Functions
Function Description Function Description
ldap_get_values() Retrieve a set of attribute values ldap_value_free_len() Free memory allocated by
from an entry ldap_get_values_len()
ldap_get_values_len() Retrieve a set of binary attribute
values
ldap_is_ldap_url() Verify LDAP URL
CCSID Considerations
ldap_init() Perform an LDAP initialization oper- Unless specified otherwise, the character string parameters
ation and return values will be converted using the CCSID (coded
ldap_memfree() Free memory allocated by LDAP character set identifier) of the job. If the CCSID value for the
API job is 65535, then the default job CCSID is used for the
ldap_modify() Perform an LDAP modify entry
translation.
request
The character string data will be translated from the CCSID
ldap_modify_s() Perform an LDAP modify entry of the job to CCSID 819 prior to being sent to the directory
request (synchronous) server. The character strings returned as a result of issuing
ldap_modrdn() Perform an LDAP modify RDN a request to a directory server will be translated from CCSID
request 819 to the CCSID of the job. These conversions can cause
ldap_modrdn_s() Perform an LDAP modify RDN data to be lost.
request (synchronous)
Binary values, which can be specified on some of the LDAP
ldap_mods_free() Free LDAP modify storage
APIs, are not translated.
ldap_msgfree() Free LDAP result message API
ldap_next_attribute() Retrieve next attribute in an entry
Thread Safety
ldap_next_entry() Retrieve next LDAP entry
The LDAP APIs are threadsafe. Multiple LDAP functions can
ldap_open() Perform an LDAP open operation
be safely initiated from multiple threads in a client program.
ldap_perror() Print LDAP error information row. This is currently implemented by serializing all LDAP function
ldap_results() Retrieve result of an asynchronous calls made against a particular LDAP connection. To have
LDAP operation multiple LDAP requests sent to a directory server for possible
ldap_result2error() Retrieve LDAP error information parallel processing by the server, asynchronous LDAP APIs
must be used. For more information on processing results of
ldap_search() Perform an LDAP search operation
asynchronous LDAP APIs in a threaded environment, see
ldap_search_s() Perform an LDAP search operation “ldap_result()—Retrieve Result of an Asynchronous LDAP
(synchronous) Operation” on page 18-27.
ldap_search_st() Perform an LDAP search operation
(timed synchronous)
Header File
ldap_set_option() Set LDAP options
ldap_set_rebind_proc() Set rebind procedure These functions use the ldap.h header (include) file from the
library QSYSINC, which is optionally installable. Make sure
ldap_simple_bind() Perform an LDAP bind request
QSYSINC is installed on your system before using any of the
ldap_simple_bind_s() Perform an LDAP bind request functions. The file name of the header file in QSYSINC is H,
ldap_ssl_start() Start a secure LDAP connection and the member name is LDAP.
ldap_unbind() Perform an LDAP unbind request
You can display a header file in QSYSINC by using one of
ldap_unbind_s() Perform an LDAP unbind request the following methods:
(synchronous)
Ÿ Using your editor. For example, to display the unistd.h
ldap_url_parse() Parse an LDAP URL
header file using the Source Entry Utility editor, enter the
ldap_url_search() Perform an LDAP URL search oper- following command:
ation
STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5)
ldap_url_search_s() Perform an LDAP URL search oper-
Ÿ Using the Display Physical File Member command. For
ation (synchronous)
example, to display the sys/stat.h header file, enter the
ldap_url_search_st() Perform an LDAP URL search oper- following command:
ation (timed synchronous)
DSPPFM FILE(QSYSINC/SYS) MBR(STAT)
ldap_value_free() Free memory allocated by
ldap_get_values() You can print a header file in QSYSINC by using one of the
following methods:

18-2 AS/400 System API Reference V4R4

 ldap_add

Ÿ Using your editor. For example, to print the unistd.h [LDAP_SUCCESS]

header file using the Source Entry Utility editor, enter the The ldap_abandon() request completed suc-
following command: cessfully.
STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(6) −1 ldap_abandon() was not successful. The
ld_errno of the ld structure is set to indicate
Ÿ Using the Copy File command. For example, to print the
the error.
sys/stat.h header file, enter the following command:
CPYF FROMFILE(QSYSINC/SYS) TOFILE(\PRINT) FROMMBR(STAT)
Error Conditions
The following descriptions of the LDAP client functions are
organized in alphabetical order by function name. If ldap_abandon() is not successful, ld_errno will be set to
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the
ld_errno field. Use the ldap_get_errno() function to retrieve
ldap_abandon()—Abandon an LDAP
the error information.
Operation in Progress
Error Messages
Syntax
The following message may be sent from this function.
#include <ldap.h>
CPF3CF2 E Error(s) occurred during running of &1 API.
int ldap_abandon(LDAP \ld,
int msgid)
Related Information
Library Name/Service Program: QDIRSRV/QGLDCLNT Ÿ “ldap_get_errno()—Retrieve Error Information” on
page 18-15
Threadsafe: Yes
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
page 18-26
The ldap_abandon() function is used to abandon or cancel
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
an LDAP operation in progress. The msgid passed should
LDAP Operation” on page 18-27
be the message identifier of an outstanding asynchronous
LDAP operation.

The ldap_abandon() API checks to see if the result of the ldap_add()—Perform an LDAP Add
operation has already come in. If the result has come in, the Operation
API deletes it from the queue of pending messages. If not,
the API sends an LDAP abandon request to the LDAP
server. Syntax
The caller can expect that the result of an abandoned opera- #include <ldap.h>
tion will not be returned from a future call to ldap_result().
int ldap_add(LDAP \ld,
char \dn,
Parameters LDAPMod \attrs[])

ld (Input) An LDAP pointer returned by a previous call to Library Name/Service Program: QDIRSRV/QGLDCLNT
ldap_open().
Threadsafe: Yes
msgid
(Input) The LDAP message identifier of an outstanding
asynchronous LDAP operation, as returned by the asyn- The ldap_add() function is used to perform an LDAP add
chronous LDAP API calls (ldap_search() and operation.
ldap_modify() for example).
The API uses the distinguished name of the entry to add,
and uses attrs, a null-terminated array of the entry's attri-
Authorities and Locks butes. The LDAPMod structure is used to represent attri-
butes. The mod_type and mod_values fields are used as
No OS/400 authority is required. All authority checking is described under ldap_modify(), and the mod_op field is
done by the LDAP server. used only if you need to specify the LDAP_MOD_BVALUES
option. Otherwise, the mod_op field should be set to zero.
Return Value

Chapter 18. Directory Services APIs 18-3

ldap_add_s

Note that all entries except that specified by the last compo-
nent in the given distinguished name must already exist. ldap_add_s()—Perform an LDAP Add
Operation (Synchronous)
ldap_add() is an asynchronous request. The result of the
operation can be obtained by a subsequent call to
ldap_result(). Syntax
#include <ldap.h>
Parameters
int ldap_add_s(LDAP \ld,
ld (Input) An LDAP pointer returned by a previous call to char \dn,
ldap_open(). LDAPMod \attrs[])

dn (Input) The distinguished name (DN) of the entry to add. Library Name/Service Program: QDIRSRV/QGLDCLNT
attrs Threadsafe: Yes
(Input) A null-terminated array of the entry's attributes.
The LDAPMod structure is used to represent attributes.
The mod_type and mod_values fields are used as The ldap_add_s() function is used to perform an LDAP add
described under ldap_modify(), and the mod_op field is operation.
used only if you need to specify the
LDAP_MOD_VALUES option. Otherwise, the mod_op The API uses the distinguished name of the entry to add,
field should be set to 0. and uses attrs, a null-terminated array of the entry's attri-
butes. The ldapmod structure is used to represent attributes.
The mod_type and mod_values fields are used as
Authorities and Locks described under ldap_modify(), and the mod_op field is
used only if you need to specify the LDAP_MOD_BVALUES
No OS/400 authority is required. All authority checking is
option. Otherwise, the mod_op field should be set to zero.
done by the LDAP server.
Note that all entries except that specified by the last compo-
Return Value nent in the given distinguished name must already exist.

LDAP message identifier ldap_add_s() is a synchronous request.

ldap_add() request was sent. The result of the opera-
tion can be obtained by a subsequent call to
ldap_result(). Parameters
−1 ldap_add() was not successful. The ld_errno of the ld ld (Input) An LDAP pointer returned by a previous call to
structure is set to indicate the error. ldap_open().

dn (Input) The distinguished name (DN) of the entry to add.

Error Conditions
attrs
If ldap_add() is not successful, ld_errno will be set to indi- (Input) A null-terminated array of the entry's attributes.
cate the error. See “LDAP Client API Error Conditions” on The ldapmod structure is used to represent attributes.
page 18-45 for a description of the possible values for the The mod_type and mod_values fields are used as
ld_errno field. described under ldap_modify(), and the mod_op field is
used only if you need to specify the
LDAP_MOD_VALUES option. Otherwise, mod_op field
Error Messages should be set to 0.
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API. Authorities and Locks
No OS/400 authority is required. All authority checking is
Related Information done by the LDAP server.
Ÿ “ldap_add_s()—Perform an LDAP Add Operation
(Synchronous)” Return Value
Ÿ “ldap_modify()—Perform an LDAP Modify Entry ld_errno
Request” on page 18-20 The ld_errno value of the ld structure is returned indi-
Ÿ “ldap_result()—Retrieve Result of an Asynchronous cating a success or failure condition. See “Error
LDAP Operation” on page 18-27

18-4 AS/400 System API Reference V4R4

 ldap_bind

Conditions” on page 18-5 for a description of the return cred

values that can be returned. (Input) The user's password. The user's unencrypted
password will be used when authenticating the user to
an LDAP server.
Error Conditions
method
If ldap_add_s() is not successful, ld_errno will be set to indi- (Input) The authentication method to use. Specify
cate the error. See “LDAP Client API Error Conditions” on LDAP_AUTH_SIMPLE for simple authentication. Simple
page 18-45 for a description of the possible values for the authentication is the only supported method.
ld_errno field.

Authorities and Locks

Error Messages
No OS/400 authority is required. All authority checking is
The following message may be sent from this function. done by the LDAP server.
CPF3CF2 E Error(s) occurred during running of &1 API.
Return Value
Related Information LDAP message identifier
Ÿ “ldap_modify()—Perform an LDAP Modify Entry ldap_bind() request was sent. The result of the opera-
Request” on page 18-20 tion can be obtained by a subsequent call to
ldap_result().
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
−1 ldap_bind() was not successful. The ld_errno of the ld
LDAP Operation” on page 18-27
structure is set to indicate the error.

ldap_bind()—Perform an LDAP Bind Error Conditions

Request If ldap_bind() is not successful, ld_errno will be set to indi-
cate the error. See “LDAP Client API Error Conditions” on
page 18-45 for a description of the possible values for the
Syntax ld_errno field.
#include <ldap.h>

int ldap_bind(LDAP \ld, Error Messages

char \who,
char \cred, The following message may be sent from this function.
int method) CPF3CF2 E Error(s) occurred during running of &1 API.

Library Name/Service Program: QDIRSRV/QGLDCLNT

Usage Notes
Threadsafe: Yes
1. Securing an LDAP Connection
When a connection has been made to an LDAP server
The ldap_bind() function is used to authenticate a distin- using either the ldap_open() or ldap_init() function, the
guished name (DN) to a directory server. user's unencrypted password will be used when
authenticating the user to an LDAP server. The
After a connection is made to an LDAP server by using the
ldap_ssl_start() function can be used when password
ldap_open() API, an LDAP bind API must be called before
encryption is desired.
any other LDAP APIs can be called for that connection.

ldap_bind() is an asynchronous request. The result of the Related Information

operation can be obtained by a subsequent call to
ldap_result(). Ÿ “ldap_bind_s()—Perform an LDAP Bind Request
(Synchronous)” on page 18-6
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
Parameters page 18-26
ld (Input) An LDAP pointer returned by a previous call to Ÿ “ldap_result()—Retrieve Result of an Asynchronous
ldap_open(). LDAP Operation” on page 18-27
who Ÿ “ldap_ssl_start()—Start a Secure LDAP Connection” on
(Input) A pointer to the null-terminated distinguished page 18-36
name (DN) of the entry in which to bind.

Chapter 18. Directory Services APIs 18-5

ldap_compare

ldap_bind_s()—Perform an LDAP Bind Error Conditions

Request (Synchronous) If ldap_bind_s() is not successful, ld_errno will be set to
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the
Syntax ld_errno field.
#include <ldap.h>
Error Messages
int ldap_bind_s(LDAP \ld,
char \who, The following message may be sent from this function.
char \cred,
int method) CPF3CF2 E Error(s) occurred during running of &1 API.

Library Name/Service Program: QDIRSRV/QGLDCLNT Usage Notes

Threadsafe: Yes 1. Securing an LDAP Connection
When a connection has been made to an LDAP server
The ldap_bind_s() function is used to authenticate a distin- using either the ldap_open() or ldap_init() function, the
guished name (DN) to a directory server. user's unencrypted password will be used when
authenticating the user to an LDAP server. The
After a connection is made to an LDAP server by using the ldap_ssl_start() function can be used when password
ldap_open() API, an LDAP bind API must be called before encryption is desired.
any other LDAP APIs can be called for that connection.

ldap_bind_s() is a synchronous request. Related Information

Ÿ “ldap_bind()—Perform an LDAP Bind Request” on
page 18-5
Parameters
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
ld (Input) An LDAP pointer returned by a previous call to page 18-26
ldap_open().
Ÿ “ldap_ssl_start()—Start a Secure LDAP Connection” on
who page 18-36
(Input) A pointer to the null-terminated distinguished
name (DN) of the entry in which to bind.

cred ldap_compare()—Perform an LDAP

(Input) The user's password. The user's unencrypted Compare Operation
password will be used when authenticating the user to
an LDAP server.
Syntax
method
(Input) The authentication method to use. Specify #include <ldap.h>
LDAP_AUTH_SIMPLE for simple authentication. Simple
authentication is the only supported method. int ldap_compare(LDAP \ld,
char \dn,
char \attr,
Authorities and Locks char \value)

No OS/400 authority is required. All authority checking is Library Name/Service Program: QDIRSRV/QGLDCLNT
done by the LDAP server.
Threadsafe: Yes

Return Value
The ldap_compare() function is used to perform an LDAP
ld_errno compare operation.
The ld_errno value of the ld structure is returned indi-
cating a success or failure condition. See “Error The API uses as input the distinguished name of the entry on
Conditions” for a description of the return values that which to perform the compare, and uses an attr and value
can be returned. (the attribute type and value to compare to those found in the
entry).

Binary values are not supported by this API.

18-6 AS/400 System API Reference V4R4

 ldap_compare_s

ldap_compare() is an asynchronous request. The result of

the operation can be obtained by a subsequent call to Syntax
ldap_result().
#include <ldap.h>

Parameters int ldap_compare_s(LDAP \ld,

char \dn,
ld (Input) An LDAP pointer returned by a previous call to char \attr,
ldap_open(). char \value)
dn (Input) The distinguished name (DN) of the entry to Library Name/Service Program: QDIRSRV/QGLDCLNT
compare.
Threadsafe: Yes
attr
(Input) The attribute type to compare to the attribute
found in the entry. The ldap_compare_s() function is used to perform an LDAP
value compare operation.
(Input) The attribute value to compare to the value found
The API uses as input the distinguished name of the entry on
in the entry.
which to perform the compare, and uses an attr and value
(the attribute type and value to compare to those found in the
Authorities and Locks entry).

No OS/400 authority is required. All authority checking is Binary values are not supported by this API.
done by the LDAP server.
ldap_compare_s() is a synchronous request.

Return Value
Parameters
LDAP message identifier
ldap_compare() request was sent. The result of the ld (Input) An LDAP pointer returned by a previous call to
operation can be obtained by a subsequent call to ldap_open().
ldap_result().
dn (Input) The distinguished name (DN) of the entry to
−1 ldap_compare() was not successful. The ld_errno of
compare.
the ld structure is set to indicate the error.
attr
(Input) The attribute type to compare to the attribute
Error Conditions found in the entry.
If ldap_compare() is not successful, ld_errno will be set to value
indicate the error. See “LDAP Client API Error Conditions” (Input) The attribute value to compare to the value found
on page 18-45 for a description of the possible values for the in the entry.
ld_errno field.

Authorities and Locks

Error Messages
No OS/400 authority is required. All authority checking is
The following message may be sent from this function. done by the LDAP server.
CPF3CF2 E Error(s) occurred during running of &1 API.
Return Value
Related Information ld_errno
Ÿ “ldap_result()—Retrieve Result of an Asynchronous The ld_errno value of the ld structure is returned indi-
LDAP Operation” on page 18-27 cating a success or failure condition. See “Error
Conditions” on page 18-8 for a description of the return
values that can be returned.
ldap_compare_s()—Perform a
Synchronous LDAP Compare Operation

Chapter 18. Directory Services APIs 18-7

ldap_count_entries

Error Conditions −1 A null entry was returned from ldap_first_entry() or

ldap_next_entry(), and was passed as input to
If the LDAP entry contains the attribute, ldap_count_attributes().
[LDAP_COMPARE_TRUE] is returned. If the entry does not
contain the attribute, [LDAP_COMPARE_FALSE] is returned.
Otherwise, see “LDAP Client API Error Conditions” on
Error Conditions
page 18-45 for a description of the possible values for the If a null entry is returned from ldap_first_entry() or
ld_errno field. ldap_next_entry(), and is passed as input to
ldap_count_attributes(), a −1 is returned.
Error Messages If −1 is returned from ldap_count_attributes(), the Id_errno()
The following message may be sent from this function. field in the Id parameter may be set to indicate the error.
See “LDAP Client API Error Conditions” on page 18-45 for a
CPF3CF2 E Error(s) occurred during running of &1 API. list of errors that can be returned.

Related Information Error Messages

Ÿ “ldap_compare()—Perform an LDAP Compare
Operation” on page 18-6 The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.

ldap_count_attributes()—Retrieve Count of Related Information

Attributes for an LDAP Entry
Ÿ “ldap_first_attribute()—Retrieve First Attribute in an
Entry” on page 18-12
Syntax Ÿ “ldap_next_attribute()—Retrieve Next Attribute in an
#include <ldap.h> Entry” on page 18-25

int ldap_count_attributes(LDAP \ld,

LDAPMessage \entry) ldap_count_entries()—Retrieve Count of
LDAP Entries
Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes
Syntax
#include <ldap.h>
The ldap_count_attributes() function returns a count of the
number of attributes in an LDAP entry. int ldap_count_entries(LDAP \ld,
LDAPMessage \result)
Parameters Library Name/Service Program: QDIRSRV/QGLDCLNT
ld (Input) An LDAP pointer returned by a previous call to
ldap_open(). Threadsafe: Yes

entry
(Input) The attribute information as returned by The ldap_first_entry(), ldap_next_entry(), and
ldap_first_entry() or ldap_next_entry(). The structure ldap_count_entries() functions are used to parse results
LDAPMessage is defined in ldap.h. received from ldap_result() or the synchronous LDAP
search functions ldap_search_s() and ldap_search_st().

Authorities and Locks The ldap_count_entries() function returns a count of the

number of entries in the search result.
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Parameters
Return Value ld (Input) An LDAP pointer returned by a previous call to
ldap_open().
attribute count
The count of the number of attributes in an LDAP entry. result
(Input) The result returned by ldap_result(),
ldap_search_s(), or ldap_search_st().

18-8 AS/400 System API Reference V4R4

 ldap_count_values_len

Authorities and Locks Authorities and Locks

No OS/400 authority is required. All authority checking is No OS/400 authority is required. All authority checking is
done by the LDAP server. done by the LDAP server.

Return Value Return Value

entry count count
The count of the number of entries in a search result. The number of values in the array returned by the
−1 An error occurred in ldap_count_entries(). ldap_get_values function.

Error Conditions Error Conditions

If −1 is returned from ldap_count_entries(), the ld_errno() None
field in the ld parameter is set to indicate the error. See
“LDAP Client API Error Conditions” on page 18-45 for a list
of errors that can be returned.
Error Messages
The following message may be sent from this function.
Error Messages CPF3CF2 E Error(s) occurred during running of &1 API.

The following message may be sent from this function.

CPF3CF2 E Error(s) occurred during running of &1 API.
Related Information
Ÿ “ldap_get_values()—Retrieve a Set of Attribute Values
from an Entry” on page 18-17
Related Information
Ÿ “ldap_value_free()—Free Memory Allocated by
Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on
ldap_get_values()” on page 18-44
page 18-13
Ÿ “ldap_next_entry()—Retrieve Next LDAP Entry” on
page 18-26 ldap_count_values_len()—Retrieve Count
of Binary Attribute Values
ldap_count_values()—Retrieve Count of
Attribute Values Syntax
#include <ldap.h>

Syntax int ldap_count_values_len(struct berval \\vals)

#include <ldap.h>
Library Name/Service Program: QDIRSRV/QGLDCLNT
int ldap_count_values(char \\vals)
Threadsafe: Yes
Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes The ldap_count_values_len function returns the number of

values in the array returned by the ldap_get_values_len
function. The array of values returned can be freed by
The ldap_count_values function returns the number of calling ldap_value_free_len().
values in the array returned by the ldap_get_values() func-
tion. The array of values returned can be freed by calling
ldap_value_free().
Parameters
vals
(Input) A pointer to a null-terminated array of pointers to
Parameters
berval structures, as returned by ldap_get_values_len().
vals See the Usage Notes for details of the berval structure.
(Input) a pointer to a null-terminated array of attribute
values, as returned by ldap_get_values().

Chapter 18. Directory Services APIs 18-9

ldap_delete_s

Authorities and Locks ldap_delete() is an asynchronous request. The result of the

operation can be obtained by a subsequent call to
No OS/400 authority is required. All authority checking is ldap_result().
done by the LDAP server.
Parameters
Return Value ld (Input) An LDAP pointer returned by a previous call to
count ldap_open().
The number of values in the array returned by the
ldap_get_values_len function. dn (Input) The distinguished name (DN) of the entry to be
deleted.

Error Conditions
Authorities and Locks
None
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Error Messages
The following message may be sent from this function. Return Value
CPF3CF2 E Error(s) occurred during running of &1 API. LDAP message identifier
ldap_delete() request was sent. The result of the
operation can be obtained by a subsequent call to
Usage Notes ldap_result().
1. Berval Structure −1 ldap_delete() was not successful. The ld_errno of the
ld structure is set to indicate the error.
The berval structure is defined as follows:

typedef struct berval { Error Conditions

unsigned long bv_len;
char \bv_val; If ldap_delete() is not successful, ld_errno will be set to indi-
}; cate the error. See “LDAP Client API Error Conditions” on
page 18-45 for a description of the possible values for the
ld_errno field.
Related Information
Ÿ “ldap_get_values_len()—Retrieve a Set of Binary Attri-
bute Values” on page 18-17
Error Messages
Ÿ “ldap_value_free_len()—Free Memory Allocated by The following message may be sent from this function.
ldap_get_values_len()” on page 18-45 CPF3CF2 E Error(s) occurred during running of &1 API.

ldap_delete()—Perform an LDAP Delete Related Information

Operation Ÿ “ldap_result()—Retrieve Result of an Asynchronous
LDAP Operation” on page 18-27

Syntax
#include <ldap.h> ldap_delete_s()—Perform an LDAP Delete
Operation (Synchronous)
int ldap_delete(LDAP \ld,
char \dn)
Syntax
Library Name/Service Program: QDIRSRV/QGLDCLNT
#include <ldap.h>
Threadsafe: Yes
int ldap_delete_s(LDAP \ld,
char \dn)
The ldap_delete() function is used to perform an LDAP
delete operation for an entry associated with the specified Library Name/Service Program: QDIRSRV/QGLDCLNT
distinguished name.
Threadsafe: Yes

18-10 AS/400 System API Reference V4R4

 ldap_explode_dn

The ldap_delete_s() function is used to perform an LDAP The ldap_err2string() function is used to retrieve the text
delete operation for an entry associated with the specified description corresponding to an LDAP error code.
distinguished name.
The text description returned will be provided in English only.
ldap_delete_s() is a synchronous request.
The string returned from ldap_err2string() should be freed
by using the ldap_memfree() API.
Parameters
ld (Input) An LDAP pointer returned by a previous call to Parameters
ldap_open().
err (Input) The LDAP error code to be described.
dn (Input) The distinguished name (DN) of the entry to be
deleted.
Authorities and Locks
Authorities and Locks No OS/400 authority is required. All authority checking is
done by the LDAP server.
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Return Value
Return Value error code string
The text describing the error code is returned.
ld_errno NULL
The ld_errno value of the ld structure is returned indi- If NULL is returned, then ldap_err2string() was unable
cating a success or failure condition. See “Error to allocate storage for the string. If so, the caller of the
Conditions” for a description of the return values that API does not need to call the ldap_memfree() API.
can be returned.

Error Conditions
Error Conditions
None
If ldap_delete_s() is not successful, ld_errno will be set to
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the Error Messages
ld_errno field.
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.
Error Messages
The following message may be sent from this function. Related Information
CPF3CF2 E Error(s) occurred during running of &1 API. Ÿ “ldap_memfree()—Free Memory Allocated by LDAP API”
on page 18-20
Related Information
Ÿ “ldap_delete()—Perform an LDAP Delete Operation” on
ldap_explode_dn()—Break a Distinguished
page 18-10
Name into Its Components

ldap_err2string()—Retrieve LDAP Error Syntax

Message String
#include <ldap.h>

char \\ldap_explode_dn(char \dn,

Syntax int notypes)
#include <ldap.h>
Library Name/Service Program: QDIRSRV/QGLDCLNT
char \ldap_err2string(int err)
Threadsafe: Yes
Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes The ldap_explode_dn() function uses the distinguished

name returned by ldap_get_dn() and breaks it up into its

Chapter 18. Directory Services APIs 18-11

ldap_first_attribute

component parts. Each part is known as a relative distin-

guished name, or RDN. ldap_explode_dn() returns a ldap_first_attribute()—Retrieve First
NULL-terminated array, each component of which contains Attribute in an Entry
an RDN from the DN. The notypes parameter is used to
request that only the RDN values be returned, not their
types. For example, the distinguished name cn=Bob,c=US Syntax
would return as either "cn=Bob","c=US",NULL or "Bob","US", #include <ldap.h>
NULL depending on whether notypes was 0 or 1, respec-
tively. The result can be freed by calling ldap_value_free(). char \ldap_first_attribute(LDAP \ld,
LDAPMessage \entry,
BerElement \\berptr)
Parameters
Library Name/Service Program: QDIRSRV/QGLDCLNT
dn (Input) The distinguished name of the entry to be
parsed. Threadsafe: Yes
notypes
(Input) Specifies that only the RDN values be returned,
The ldap_first_attribute() function returns the first attribute
not their types.
in an entry.
notypes can have the following values:
ldap_first_attribute() takes an entry returned by
0 The RDN values and their types are ldap_first_entry() or ldap_next_entry() and returns a
returned. pointer to a buffer containing the first attribute type in the
1 Only the RDN values are returned. entry. This string must be freed when its use is completed
using ldap_memfree().
Authorities and Locks The ldap_first_attribute() and ldap_next_attribute() func-
No OS/400 authority is required. All authority checking is tions are used to step through the attributes in an LDAP
done by the LDAP server. entry.

Return Value Parameters

relative distinguished names ld (Input) An LDAP pointer returned by a previous call to
A NULL-terminated array of character strings, each ldap_open().
component of which contains a relative distinguished
entry
name from the distinguished name.
(Input) The attribute information as returned by
NULL
ldap_first_entry() or ldap_next_entry().
An error occurred.
berptr
(Output) A pointer to a BerElement structure returned
Error Conditions from ldap_first_attribute(). The BerElement is allo-
If NULL is returned, the ld_errno() field in the ld parameter is cated to keep track of the current position and is used
set to indicate the error. See “LDAP Client API Error as an input and output parameter for subsequent calls to
Conditions” on page 18-45 for a list of errors that can be ldap_next_attribute(). See the Usage Notes for more
returned. information.

Error Messages Authorities and Locks

No OS/400 authority is required.
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API. Return Value
attribute type
Related Information A pointer to a buffer containing the first attribute type in
Ÿ “ldap_get_dn()—Retrieve the Distinguished Name of an the entry.
Entry” on page 18-14 NULL
No attribute is returned.
Ÿ “ldap_value_free()—Free Memory Allocated by
ldap_get_values()” on page 18-44

18-12 AS/400 System API Reference V4R4

 ldap_first_entry

Error Conditions ldap_first_entry()—Retrieve First LDAP

If NULL is returned, the ld_errno() field in the ld parameter is Entry
set to indicate the error. See “LDAP Client API Error
Conditions” on page 18-45 for a description of the possible
values for the ld_errno field. Syntax
#include <ldap.h>
Error Messages LDAPMessage \ldap_first_entry(LDAP \ld,
LDAPMessage \result)
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API. Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes
Usage Notes
1. Berptr Use
The ldap_first_entry(), ldap_next_entry(), and
The pointer returned by ldap_first_attribute() in berptr ldap_count_entries() functions are used to parse results
should be passed to subsequent calls to received from ldap_result() or the synchronous LDAP
ldap_next_attribute() and is used to step through the search functions ldap_search_s() and ldap_search_st().
entry's attributes. This pointer is freed by
ldap_next_attribute() when there are no more attributes The ldap_first_entry() function takes the result from a call to
(that is, when ldap_next_attribute() returns NULL). ldap_result(), ldap_search_s(), or ldap_search_st() and
Otherwise, the caller is responsible for freeing the returns a pointer to the first entry in the result.
BerElement pointed to by berptr when it is no longer
needed by calling ldap_memfree(). The entry pointer returned by ldap_first_entry() can then be
used as input into ldap_next_entry() to obtain the next entry
The BerElement is used for internal communication in the chain of results.
between API calls, and must not be modified by the API
caller. The entry returned by ldap_first_entry() can also be used
2. Retrieving Values for an Attribute by functions such as ldap_get_dn(), ldap_first_attribute(),
and ldap_get_values(), as well as other functions to obtain
The attribute names returned by ldap_first_attribute() additional information about the entry.
are suitable for inclusion in a call to ldap_get_values().
3. Memory Allocation
Parameters
The ldap_first_attribute() function allocates memory
that may need to be freed by the caller using ld (Input) An LDAP pointer returned by a previous call to
ldap_memfree(). ldap_open().

result
Related Information (Input) The result returned by ldap_result(),
ldap_search_s(), or ldap_search_st().
Ÿ “ldap_count_attributes()—Retrieve Count of Attributes for
an LDAP Entry” on page 18-8
Authorities and Locks
Ÿ “ldap_count_entries()—Retrieve Count of LDAP Entries”
on page 18-8 No OS/400 authority is required. All authority checking is
Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” done by the LDAP server.
Ÿ “ldap_get_values()—Retrieve a Set of Attribute Values
from an Entry” on page 18-17 Return Value
Ÿ “ldap_memfree()—Free Memory Allocated by LDAP API” LDAP entry
on page 18-20 A pointer to the first LDAP entry in a chain of results.
Ÿ “ldap_next_attribute()—Retrieve Next Attribute in an NULL
Entry” on page 18-25 No entry is returned.

Ÿ “ldap_next_entry()—Retrieve Next LDAP Entry” on

page 18-26

Chapter 18. Directory Services APIs 18-13

ldap_get_dn

Error Conditions Return Value

If NULL is returned, the ld_errno() field in the ld parameter is None
set to indicate the error. See “LDAP Client API Error
Conditions” on page 18-45 for a list of errors that can be
returned.
Error Conditions
None
Error Messages
The following message may be sent from this function.
Error Messages
CPF3CF2 E Error(s) occurred during running of &1 API. The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.
Related Information
Ÿ “ldap_count_entries()—Retrieve Count of LDAP Entries” Usage Notes
on page 18-8 1. LDAPURLDesc Structure
Ÿ “ldap_next_entry()—Retrieve Next LDAP Entry” on The LDAPURLDesc structure as defined in ldap.h is as
page 18-26 follows:
Ÿ “ldap_result()—Retrieve Result of an Asynchronous typedef struct ldap_url_desc
LDAP Operation” on page 18-27) {
char \lud_host; /\ LDAP host to contact \/
Ÿ “ldap_search_s()—Perform an LDAP Search Operation int lud_port; /\ port on host \/
char \lud_dn; /\ base for search \/
(Synchronous)” on page 18-30 char \\lud_attrs; /\ NULL-terminate list of attributes \/
int lud_scope; /\ a valid LDAP_SCOPE_... value \/
Ÿ “ldap_search_st()—Perform an LDAP Search Operation char \lud_filter; /\ LDAP search filter \/
(Timed Synchronous)” on page 18-31 char \lud_string; /\ for internal use only \/
} LDAPURLDesc;

ldap_free_urldesc()—Free an LDAP URL

Description Related Information
Ÿ “ldap_url_parse()—Parse an LDAP URL” on page 18-40

Syntax
#include <ldap.h> ldap_get_dn()—Retrieve the Distinguished
Name of an Entry
void ldap_free_urldesc(LDAPURLDesc \ludp)

Library Name/Service Program: QDIRSRV/QGLDCLNT Syntax

#include <ldap.h>
Threadsafe: Yes
char \ldap_get_dn(LDAP \ld,
LDAPMessage \entry)
The ldap_free_urldesc function is called to free an LDAP
URL description that was obtained from a call to the Library Name/Service Program: QDIRSRV/QGLDCLNT
ldap_url_parse() function.
Threadsafe: Yes

Parameters
The ldap_get_dn() function takes an entry as returned by
ludp ldap_first_entry() or ldap_next_entry() and returns a copy
(Input) A pointer to the LDAP URL description. See the of the entry's distinguished name. Memory for the distin-
Usage Notes for details of this structure. guished name will have been allocated and should be freed
by a call to ldap_memfree().
Authorities and Locks
No OS/400 authority is required. Parameters
ld (Input) An LDAP pointer returned by a previous call to
ldap_open().

18-14 AS/400 System API Reference V4R4

 ldap_get_option

entry Authorities and Locks

(Input) The attribute information as returned by
No OS/400 authority is required.
ldap_first_entry() or ldap_next_entry().

Authorities and Locks Return Value

No OS/400 authority is required. ld_errno
The ld_errno value of the ld structure is returned. See
“Error Conditions” for a description of the possible
Return Value values for the ld_errno field.
distinguished name
A pointer to a buffer containing the distinguished name Error Conditions
of the entry.
NULL If ldap_get_errno() is not successful,
An error occurred. [LDAP_PARAM_ERROR] or [LDAP_LOCAL_ERROR] is
returned.
Error Conditions
Error Messages
If NULL is returned, the ld_errno() field in the ld parameter is
set to indicate the error. See “LDAP Client API Error The following message may be sent from this function.
Conditions” on page 18-45 for a description of the possible
CPF3CF2 E Error(s) occurred during running of &1 API.
values for the ld_errno field.

Error Messages ldap_get_option()—Retrieve LDAP Options

The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API. Syntax
#include <ldap.h>
Related Information
int ldap_get_option(LDAP \ld,
Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on int optionToGet,
page 18-13 void \optionValue)
Ÿ “ldap_next_entry()—Retrieve Next LDAP Entry” on
Library Name/Service Program: QDIRSRV/QGLDCLNT
page 18-26
Threadsafe: Yes

ldap_get_errno()—Retrieve Error
The ldap_get_option() function is used to query settings
Information
associated with the specified LDAP connection.

Syntax Parameters
#include <ldap.h> ld (Input) An LDAP pointer returned by a previous call to
ldap_open() or ldap_init().
int ldap_get_errno(LDAP \ld)
optionToGet
Library Name/Service Program: QDIRSRV/QGLDCLNT (Input) The option value that is to be queried on the
ldap_get_option call.
Threadsafe: Yes
optionValue
(Output) The address of the storage in which to return
The ldap_get_errno() function retrieves information about the queried value returned by the ldap_get_option()
the most recent error that occurred. call.

Parameters Authorities and Locks

ld (Input) An LDAP pointer returned by a previous call to No OS/400 authority is required.
ldap_open().

Chapter 18. Directory Services APIs 18-15

ldap_get_option

ldap_get_option(ld,
Return Value LDAP_OPT_SSL_CIPHER, &cipher);
return code LDAP_OPT_SIZELIMIT (0x00)
[LDAP_SUCCESS] is returned when ldap_get_option() Specifies the maximum number of entries
completes successfully. See “Error Conditions” for a that can be returned on a search operation,
list of return codes that can be returned when bounded by the maximum number of entries
ldap_get_option() does not complete successfully. that the server is configured to return. An
example follows:
Error Conditions ldap_get_option(ld,
LDAP_OPT_SIZELIMIT, &value);

If ldap_get_option() does not complete successfully, the fol- LDAP_OPT_TIMELIMIT (0x01)

lowing error code is returned: Specifies the number of seconds to wait for
[LDAP_PARAM_ERROR] search results. An example follows:
An LDAP API was called with a bad param- ldap_get_option(ld,
LDAP_OPT_TIMELIMIT, &value);
eter.
LDAP_OPT_DEREF (0x03)
Specifies alternative rules for following
Error Messages aliases at the server. Supported values
follow:
The following message may be sent from this function.
LDAP_DEREF_NEVER ð
CPF3CF2 E Error(s) occurred during running of &1 API. LDAP_DEREF_SEARCHING 1
LDAP_DEREF_FINDING 2
Usage Notes LDAP_DEREF_ALWAYS 3

1. Supported LDAP Options An example follows:

ldap_get_option(ld,
The following options, and associated values are sup- LDAP_OPT_DEREF, &value );
ported for the ldap_set_option() function.
LDAP_OPT_REFERRALS (0x02)
LDAP_OPT_SSL_TIMEOUT (0x08) Specifies whether the LDAP support will
Specifies in seconds the Secure Sockets automatically follow referrals returned by
Layer (SSL) inactivity timer. After the speci- LDAP servers. It can be set to one of the
fied seconds, in which no SSL activity has constants LDAP_OPT_ON or
occurred, the SSL connection will be LDAP_OPT_OFF. By default, the LDAP
refreshed with new session keys. A smaller client will follow referrals.
value may marginally increase security, but
An example follows:
will have a small impact on performance.
ldap_get_option( ld,
An example follows: LDAP_OPT_REFERRALS, LDAP_OPT_ON);
ldap_get_option(ld,
LDAP_OPT_SSL_TIMEOUT, &value); LDAP_OPT_REFHOPLIMIT (0x05)
Specifies the maximum number of hops that
LDAP_OPT_SSL_CIPHER (0x07)
the LDAP client will take when chasing
Specifies a set of one or more ciphers to be
referrals. The default is 5.
used when negotiating the cipher algorithm
with the LDAP server. The first cipher in the An example follows:
list that is common with the list of ciphers hoplimit=7;
ldap_get_option( ld,
supported by the server is chosen. The LDAP_OPT_REFHOPLIMIT, &hoplimit);
default ciphers are the first two export type
ciphers shown in the list. Note that the LDAP_OPT_RESTART (0x04)
ciphers supported by the export version of Specifies if the LDAP library should restart
the LDAP client library are fixed to the the select() system call when it is inter-
defaults, and are not modified with the use rupted by the system (that is, errno is set to
of ldap_set_option. Supported ciphers [EINTR]). Supported values follow:
follows: LDAP_OPT_ON
LDAP_SSL_RC4_MD5_EX "ð3" LDAP_OPT_OFF
LDAP_SSL_RC2_MD5_EX "ð6"
LDAP_SSL_RC4_SHA_US "ð5" (Non-export only) An example follows:
LDAP_SSL_RC4_MD5_US "ð4" (Non-export only) ldap_get_option(ld,
LDAP_SSL_DES_SHA_US "ð9" (Non-export only) LDAP_OPT_RESTART, &value);
LDAP_SSL_3DES_SHA_US "ðA" (Non-export only)

An example follows: 2. Memory Usage

18-16 AS/400 System API Reference V4R4

 ldap_get_values_len

Note that a successful call of ldap_get_option() to Return Value

obtain the SSL cipher string returns a pointer to storage
that should be released with ldap_memfree(). attribute values
A NULL-terminated array of character strings of the
attribute's values.
Related Information NULL
Ÿ “ldap_init()—Perform an LDAP Initialization Operation” An error occurred.
on page 18-18
Ÿ “ldap_memfree()—Free Memory Allocated by LDAP API” Error Conditions
on page 18-20
If NULL is returned, the ld_errno() field in the ld parameter is
Ÿ “ldap_open()—Perform an LDAP Open Operation” on set to indicate the error. See “LDAP Client API Error
page 18-26 Conditions” on page 18-45 for a description of the possible
Ÿ “ldap_set_option()—Set LDAP Options” on page 18-32 values for the ld_errno field.

Error Messages
ldap_get_values()—Retrieve a Set of
Attribute Values from an Entry The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.

Syntax
Related Information
#include <ldap.h>
Ÿ “ldap_count_values_len()—Retrieve Count of Binary
char \\ldap_get_values(LDAP \ld, Attribute Values” on page 18-9
LDAPMessage \entry,
Ÿ “ldap_first_attribute()—Retrieve First Attribute in an
char \attr)
Entry” on page 18-12
Library Name/Service Program: QDIRSRV/QGLDCLNT Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on
page 18-13
Threadsafe: Yes
Ÿ “ldap_get_values_len()—Retrieve a Set of Binary Attri-
bute Values”
The ldap_get_values() function is used to retrieve attribute
values from an LDAP entry as returned by ldap_first_entry()
or ldap_next_entry(). ldap_get_values() uses the entry ldap_get_values_len()—Retrieve a Set of
and the attribute attr whose values are wanted and returns a
Binary Attribute Values
NULL-terminated array of the attribute's values.

The attr parameter may be an attribute type as returned from

ldap_first_attribute() or ldap_next_attribute(), or if the attri- Syntax
bute type is known, it can simply be given. #include <ldap.h>

The array of values returned can be freed by calling struct berval \\ldap_get_values_len(LDAP \ld,
ldap_value_free(). LDAPMessage \entry,
char \attr)
Parameters Library Name/Service Program: QDIRSRV/QGLDCLNT
ld (Input) An LDAP pointer returned by a previous call to
Threadsafe: Yes
ldap_open().

entry
The ldap_get_values_len() function is used to retrieve attri-
(Input) The pointer to an entry returned on a previous
bute values that are binary in nature from an LDAP entry as
call to ldap_first_entry() or ldap_next_entry().
returned by ldap_first_entry() or ldap_next_entry().
attr ldap_get_values_len() uses the same parameters as
(Input) The attribute whose values are to be retrieved. ldap_get_values(), but returns a NULL-terminated array of
pointers to berval structures, each containing the length of
and a pointer to a value.
Authorities and Locks
No OS/400 authority is required.

Chapter 18. Directory Services APIs 18-17

ldap_init

The attr parameter may be an attribute type as returned from Related Information
ldap_first_attribute() or ldap_next_attribute(), or if the attri-
bute type is known, it can simply be given. Ÿ “ldap_count_values_len()—Retrieve Count of Binary
Attribute Values” on page 18-9
No translation is done on the attribute values that are Ÿ “ldap_first_attribute()—Retrieve First Attribute in an
retrieved. Entry” on page 18-12
The array of values returned can be freed by calling Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on
ldap_value_free_len(). page 18-13
Ÿ “ldap_get_values()—Retrieve a Set of Attribute Values
Parameters from an Entry” on page 18-17
Ÿ “ldap_value_free_len()—Free Memory Allocated by
ld (Input) An LDAP pointer returned by a previous call to
ldap_get_values_len()” on page 18-45
ldap_open().

entry
(Input) The pointer to an entry returned on a previous ldap_init()—Perform an LDAP Initialization
call to ldap_first_entry() or ldap_next_entry(). Operation
attr
(Input) The attribute whose values are to be retrieved.
Syntax
#include <ldap.h>
Authorities and Locks
No OS/400 authority is required. All authority checking is LDAP \ldap_init(char \defhost,
int \defport)
done by the LDAP server.
Library Name/Service Program: QDIRSRV/QGLDCLNT
Return Value
Threadsafe: Yes
berval structures
A NULL-terminated array of berval structures each con-
taining the length of and a pointer to a value. See the The ldap_init() function is used to allocate an LDAP struc-
Usage Notes for details of the berval structure. ture, which is used to identify the connection and to maintain
NULL per-connection information.
An error occurred.
The ldap_init() function returns a pointer to an LDAP struc-
ture, which should be passed to subsequent calls to other
Error Conditions LDAP functions such as ldap_bind() and ldap_search().

If NULL is returned, the ld_errno() field in the ld parameter is

set to indicate the error. See “LDAP Client API Error Parameters
Conditions” on page 18-45 for a list of errors that can be
defhost
returned.
(Input) The name of the host for the default LDAP
server. The defhost parameter may contain a blank-
Error Messages separated list of default hosts, and each host may
optionally be of the form host:port. If present, the :port
The following message may be sent from this function. portion of the defhost parameter overrides the defport
CPF3CF2 E Error(s) occurred during running of &1 API. parameter to ldap_init(). If the host parameter is null,
the LDAP server will be assumed to be running on the
local host.
Usage Notes
defport
1. Berval Structure (Input) The default port number to which to connect. If
The berval structure is defined as follows: the default IANA-assigned port of 389 is desired, the
constant LDAP_PORT should be specified. To use the
typedef struct berval { default Secure Sockets Layer (SSL) port 636 for SSL
unsigned long bv_len; connections, use the constant LDAPS_PORT.
char \bv_val;
};

18-18 AS/400 System API Reference V4R4

 ldap_is_ldap_url

Authorities and Locks The ldap_is_ldap_url() function is used to check a string to

verify if it could be an LDAP URL. It can be used as a quick
No OS/400 authority is required. All authority checking is check for an LDAP URL.
done by the LDAP server.
Parameters
Return Value url (Input) A pointer to a URL string.
LDAP pointer
A pointer to an LDAP structure.
NULL Authorities and Locks
ldap_init() was not successful. No OS/400 authority is required.

Error Conditions Return Value

value
NULL is returned when the ldap_init() fails.
The ldap_is_ldap_url() function returns a nonzero
value if the url parameter begins with ldap://.
Error Messages
The following message may be sent from this function. Error Conditions
CPF3CF2 E Error(s) occurred during running of &1 API. None.

Usage Notes Error Messages

1. Setting LDAP Options
The following message may be sent from this function.
Direct manipulation of the LDAP structure is not recom-
CPF3CF2 E Error(s) occurred during running of &1 API.
mended. The ldap_set_option() function is provided to
set options for the specified LDAP connection. The
ldap_get_option() function is provided to query settings Usage Notes
associated with the specified LDAP connection.
1. LDAP URL Format
The format of an LDAP URL is as follows:
Related Information
ldap://hostport/dn[?attributes[?scope[?filter]]]
Ÿ “ldap_bind()—Perform an LDAP Bind Request” on
Where:
page 18-5
hostport A host name with an optional
Ÿ “ldap_get_errno()—Retrieve Error Information” on
":portnumber"
page 18-15
dn The base distinguished name to be used
Ÿ “ldap_get_option()—Retrieve LDAP Options” on for an LDAP search operation.
page 18-15 attributes a comma separated list of attributes to
Ÿ “ldap_open()—Perform an LDAP Open Operation” on retrieved.
page 18-26 scope is one of these three strings: base (the
default), one, or sub
Ÿ “ldap_set_option()—Set LDAP Options” on page 18-32 filter LDAP search filter as used in a call to
ldap_search().
For example:
ldap_is_ldap_url()—Verify LDAP URL
ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich

URLs that are wrapped in less than and greater than

Syntax signs or are preceded by "URL:" are also tolerated. For
example:
#include <ldap.h>
URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
int ldap_is_ldap_url(char \url)
<URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich>

Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes

Chapter 18. Directory Services APIs 18-19

ldap_modify

Related Information ldap_modify()—Perform an LDAP Modify

Ÿ “ldap_url_parse()—Parse an LDAP URL” on page 18-40 Entry Request
Ÿ “ldap_url_search()—Perform an LDAP URL Search
Operation” on page 18-41
Syntax
Ÿ “ldap_url_search_s()—Perform an LDAP URL Search
Operation (Synchronous)” on page 18-42 #include <ldap.h>

Ÿ “ldap_url_search_st()—Perform an LDAP URL Search int ldap_modify(LDAP \ld,

Operation (Timed Synchronous)” on page 18-43 char \dn,
LDAPMods \mods[])

ldap_memfree()—Free Memory Allocated Library Name/Service Program: QDIRSRV/QGLDCLNT

by LDAP API Threadsafe: Yes

Syntax The ldap_modify() function is used to perform an LDAP

modify operation.
#include <ldap.h>
ldap_modify() is an asynchronous request. The result of the
void ldap_memfree(char \mem)
operation can be obtained by a subsequent call to
Library Name/Service Program: QDIRSRV/QGLDCLNT ldap_result().

Threadsafe: Yes
Parameters
ld (Input) An LDAP pointer returned by a previous call to
The ldap_memfree() function is used to free storage that is ldap_open().
allocated by an LDAP API.
dn (Input) The distinguished name (DN) of the entry to be
modified.
Parameters
mods
mem (Input) A null-terminated array of modifications to make
(Input) The address of storage that was allocated by an
to the entry. Each element of the mods array is a
LDAP API.
pointer to an ldapmod structure.

Authorities and Locks Authorities and Locks

No OS/400 authority is required.
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Return Value
None Return Value
LDAP message identifier
Error Conditions ldap_modify() request was sent. The result of the
operation can be obtained by a subsequent call to
None ldap_result().
−1 ldap_modify() was not successful. The ld_errno of the
Error Messages ld structure is set to indicate the error.

None
Error Conditions

Related Information If ldap_modify() is not successful, ld_errno will be set to

indicate the error. See “LDAP Client API Error Conditions”
Ÿ “ldap_msgfree()—Free LDAP Result Message” on on page 18-45 for a description of the possible values for the
page 18-24 ld_errno field.

18-20 AS/400 System API Reference V4R4

 ldap_modify_s

Error Messages
typedef struct berval {
The following message may be sent from this function. unsigned long bv_len;
char \bv_val;
CPF3CF2 E Error(s) occurred during running of &1 API. };
3. Freeing Elements in the Array of Modification Structures
Usage Notes The ldap_mods_free() function can be used to free
1. LDAPMod Structure each element of a null-terminated array of modification
The mods parameter is a null-terminated array of modifi- structures.
cations to make to the entry. Each element of the mods
array is a pointer to an LDAPMod structure, which is Related Information
defined as follows:
Ÿ “ldap_add()—Perform an LDAP Add Operation” on
typedef struct ldapmod { page 18-3
int \mod_op;
char \mod_type; Ÿ “ldap_modify_s()—Perform an LDAP Modify Entry
union { Request (Synchronous)”
char \\modv_strvals;
struct berval \\modv_bvals; Ÿ “ldap_mods_free()—Free LDAP Modify Storage” on
} mod_vals;
page 18-24
struct ldapmod \mod_next;
}LDAPMod; Ÿ “ldap_result()—Retrieve Result of an Asynchronous
#define mod_values mod_vals.modv_strvals LDAP Operation” on page 18-27
#define mod_bvalues mod_vals.modv_bvals

The mod_op field is used to specify the type of modifica-

tion to perform and should be one of LDAP_MOD_ADD, ldap_modify_s()—Perform an LDAP Modify
LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The Entry Request (Synchronous)
mod_type and mod_values fields specify the attribute
type to modify and a null-terminated array of values to
add, delete, or replace, respectively. The mod_next field Syntax
is used only by the LDAP server and may be ignored by
#include <ldap.h>
the client.
If you need to specify a nonstring value (for example, to int ldap_modify_s(LDAP \ld,
add a photograph or audio attribute value), mod_op char \dn,
should be set to the logical OR of the operation as LDAPMods \mods[])
above (for example, LDAP_MOD_REPLACE) and the
constant LDAP_MOD_BVALUES. In this case, Library Name/Service Program: QDIRSRV/QGLDCLNT
mod_bvalues should be used instead of mod_values,
Threadsafe: Yes
and it should point to a null-terminated array of berval
structures as defined in <lber.h>.
When the mod_op field is set using the The ldap_modify_s() function is used to perform a synchro-
LDAP_MOD_BVALUES constant, the values specified in nous LDAP modify operation.
the berval structures are not translated prior to being
sent to the directory server. Parameters
For LDAP_MOD_ADD modifications, the given values
ld (Input) An LDAP pointer returned by a previous call to
are added to the entry, creating the attribute if neces-
ldap_open().
sary. For LDAP_MOD_DELETE modifications, the given
values are deleted from the entry, removing the attribute dn (Input) The distinguished name (DN) of the entry to be
if no values remain. If the entire attribute is to be modified.
deleted, the mod_values field should be set to NULL.
For LDAP_MOD_REPLACE modifications, the attribute mods
will have the listed values after the modification, having (Input) A null-terminated array of modifications to make
been created if necessary. All modifications are per- to the entry. Each element of the mods array is a
formed in the order in which they are listed. pointer to an ldapmod structure.

2. Berval Structure
The berval structure is defined as follows:
Authorities and Locks
No OS/400 authority is required. All authority checking is
done by the LDAP server.

Chapter 18. Directory Services APIs 18-21

ldap_modrdn

Return Value For LDAP_MOD_ADD modifications, the given values

are added to the entry, creating the attribute if neces-
ld_errno sary. For LDAP_MOD_DELETE modifications, the given
The ld_errno value of the ld structure is returned indi- values are deleted from the entry, removing the attribute
cating a success or failure condition. See “Error if no values remain. If the entire attribute is to be
Conditions” for a description of the return values that deleted, the mod_values field should be set to NULL.
can be returned. For LDAP_MOD_REPLACE modifications, the attribute
will have the listed values after the modification, having
Error Conditions been created if necessary. All modifications are per-
formed in the order in which they are listed.
If ldap_modify_s() is not successful, ld_errno will be set to 2. Freeing Elements in the Array of Modification Structures
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the The ldap_mods_free() function can be used to free
ld_errno field. each element of a null-terminated array of modification
structures.

Error Messages
Related Information
The following message may be sent from this function. Ÿ “ldap_add_s()—Perform an LDAP Add Operation
CPF3CF2 E Error(s) occurred during running of &1 API. (Synchronous)” on page 18-4
Ÿ “ldap_modify()—Perform an LDAP Modify Entry
Usage Notes Request” on page 18-20

1. LDAPMod Structure Ÿ “ldap_mods_free()—Free LDAP Modify Storage” on

page 18-24
The mods parameter is a null-terminated array of modifi-
cations to make to the entry. Each element of the mods
array is a pointer to an LDAPMod structure, which is
defined as follows:
ldap_modrdn()—Perform an LDAP Modify
RDN Request
typedef struct ldapmod {
int \mod_op;
char \mod_type;
union { Syntax
char \\modv_strvals;
struct berval \\modv_bvals; #include <ldap.h>
} mod_vals;
struct ldapmod \mod_next; int ldap_modrdn(LDAP \ld,
}LDAPMod;
char \dn,
#define mod_values mod_vals.modv_strvals char \newrdn,
#define mod_bvalues mod_vals.modv_bvals int deleteoldrdn)
The mod_op field is used to specify the type of modifica-
Library Name/Service Program: QDIRSRV/QGLDCLNT
tion to perform and should be one of LDAP_MOD_ADD,
LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The Threadsafe: Yes
mod_type and mod_values fields specify the attribute
type to modify and a null-terminated array of values to
add, delete, or replace, respectively. The mod_next field The ldap_modrdn() function is used to perform an LDAP
is used only by the LDAP server and may be ignored by modify relative distinguished name (RDN) operation. The
the client. function takes the distinguished name of the entry whose
RDN is to be changed, and newrdn, the new RDN to give the
If you need to specify a nonstring value (for example, to
entry. The deleteoldrdn parameter is used as a boolean
add a photograph or audio attribute value), mod_op
value to indicate whether the old RDN values should be
should be set to the logical OR of the operation as
deleted from the entry or not.
above (for example, LDAP_MOD_REPLACE) and the
constant LDAP_MOD_BVALUES. In this case, ldap_modrdn() is an asynchronous request. The result of
mod_bvalues should be used instead of mod_values, the operation can be obtained by a subsequent call to
and it should point to a null-terminated array of berval ldap_result().
structures as defined in <lber.h>.
When the mod_op field is set using the
LDAP_MOD_BVALUES constant, the values specified in
Parameters
the berval structures are not translated prior to being ld (Input) An LDAP pointer returned by a previous call to
sent to the directory server. ldap_open().

18-22 AS/400 System API Reference V4R4

 ldap_modrdn_s

dn (Input) The distinguished name (DN) of the entry whose

RDN is to be changed. Syntax
newrdn #include <ldap.h>
(Input) The new RDN to be given to the entry.
int ldap_modrdn_s(LDAP \ld,
deleteoldrdn char \dn, \newrdn,
(Input) A boolean value that indicates whether the old int deleteoldrdn)
RDN values should be deleted from the entry.
Library Name/Service Program: QDIRSRV/QGLDCLNT
0 Do not delete the old RDN values.
Non zero Delete the old RDN values. Threadsafe: Yes

Authorities and Locks The ldap_modrdn_s() function is used to perform an LDAP

modify relative distinguished name (RDN) operation. The
No OS/400 authority is required. All authority checking is
function takes the distinguished name of the entry whose
done by the LDAP server.
RDN is to be changed, and newrdn, the new RDN to give the
entry. The deleteoldrdn parameter is used as a boolean
Return Value value to indicate whether the old RDN values should be
deleted from the entry or not.
LDAP message identifier
ldap_modrdn() request was sent. The result ldap_modrdn_s() is a synchronous request.
of the operation can be obtained by a subse-
quent call to ldap_result().
−1 ldap_modrdn() was not successful. The Parameters
ld_errno of the ld structure is set to indicate
ld (Input) An LDAP pointer returned by a previous call to
the error.
ldap_open().

dn (Input) The distinguished name (DN) of the entry whose

Error Conditions RDN is to be changed.
If ldap_modrdn() is not successful, ld_errno will be set to newrdn
indicate the error. See “LDAP Client API Error Conditions” (Input) The new RDN to be given to the entry.
on page 18-45 for a description of the possible values for the
ld_errno field. deleteoldrdn
(Input) A boolean value that indicates whether the old
RDN values should be deleted from the entry.
Error Messages
0 Do not delete the old RDN values.
The following message may be sent from this function. Nonzero
CPF3CF2 E Error(s) occurred during running of &1 API. Delete the old RDN values.

Related Information Authorities and Locks

Ÿ “ldap_modrdn_s()—Perform an LDAP Modify RDN No OS/400 authority is required. All authority checking is
Request (Synchronous)” done by the LDAP server.
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
LDAP Operation” on page 18-27 Return Value
ld_errno
The ld_errno value of the ld structure is returned indi-
ldap_modrdn_s()—Perform an LDAP cating a success or failure condition. See “Error
Modify RDN Request (Synchronous) Conditions” for a description of the return values that
can be returned.

Error Conditions
If ldap_modify_s() is not successful, ld_errno will be set to
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the
ld_errno field.

Chapter 18. Directory Services APIs 18-23

ldap_msgfree

Error Messages Error Conditions

The following message may be sent from this function. None
CPF3CF2 E Error(s) occurred during running of &1 API.
Error Messages
Related Information The following message may be sent from this function.
Ÿ “ldap_modrdn()—Perform an LDAP Modify RDN
CPF3CF2 E Error(s) occurred during running of &1 API.
Request” on page 18-22

Related Information
ldap_mods_free()—Free LDAP Modify Ÿ “ldap_modify()—Perform an LDAP Modify Entry
Storage Request” on page 18-20
Ÿ “ldap_modify_s()—Perform an LDAP Modify Entry
Request (Synchronous)” on page 18-21
Syntax
#include <ldap.h>
ldap_msgfree()—Free LDAP Result
void ldap_mods_free(LDAPMods \mods[],
int freemods)
Message

Library Name/Service Program: QDIRSRV/QGLDCLNT

Syntax
Threadsafe: Yes #include <ldap.h>

int ldap_msgfree(LDAPMessage \msg)

The ldap_mods_free() function is used to free storage asso-
ciated with the ldap_modify() and ldap_modify_s() func- Library Name/Service Program: QDIRSRV/QGLDCLNT
tions.
Threadsafe: Yes
ldap_mods_free() can be used to free each element of a
NULL-terminated array of modification structures. If
freemods is nonzero, the mods pointer itself is freed as well. The ldap_msgfree() function is used to free the memory
See “ldap_modify()—Perform an LDAP Modify Entry allocated for a result by ldap_result(), as well as
Request” on page 18-20 for a description of the ldapmod ldap_search_s() or ldap_search_st(). It takes a pointer to
structure. the result to be freed and returns the type of the message it
freed.
Parameters
Parameters
mods
(Input) A null-terminated array of modifications that were msg
made to the entry. Each element of the mods array is a (Input) A pointer to a result, as returned from
pointer to an ldapmod structure. ldap_result(), ldap_search_s(), or ldap_search_st().
This pointer is used as input to ldap_msgfree().
freemods
(Input) Whether or not the mods pointer is to be freed in
addition to the null-terminated array of modification struc- Authorities and Locks
tures. No OS/400 authority is required.

Authorities and Locks Return Value

No OS/400 authority is required.
type The type of the result message freed. The possible
result types returned are:
Return Value #define
#define
LDAP_RES_BIND
LDAP_RES_SEARCH_ENTRY
ðx61L
ðx64L
(decimal
(decimal
97)
1ðð)
#define LDAP_RES_SEARCH_RESULT ðx65L (decimal 1ð1)
None #define LDAP_RES_MODIFY ðx67L (decimal 1ð3)
#define LDAP_RES_ADD ðx69L (decimal 1ð5)
#define LDAP_RES_DELETE ðx6bL (decimal 1ð7)
#define LDAP_RES_MODRDN ðx6dL (decimal 1ð9)
#define LDAP_RES_COMPARE ðx6fL (decimal 111)

18-24 AS/400 System API Reference V4R4

 ldap_next_attribute

Error Conditions Authorities and Locks

None No OS/400 authority is required. All authority checking is
done by the LDAP server.
Error Messages
Return Value
The following message may be sent from this function.
attribute type
CPF3CF2 E Error(s) occurred during running of &1 API. A pointer to a buffer containing the next attribute type in
the entry.
Related Information NULL
No more attributes to be returned.
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
LDAP Operation” on page 18-27
Error Conditions
Ÿ “ldap_search_s()—Perform an LDAP Search Operation
(Synchronous)” on page 18-30 If an error occurs, NULL is returned and the ld_errno() field
Ÿ “ldap_search_st()—Perform an LDAP Search Operation in the ld parameter is set to indicate the error. See “LDAP
(Timed Synchronous)” on page 18-31 Client API Error Conditions” on page 18-45 for a list of errors
that can be returned.

ldap_next_attribute()—Retrieve Next Error Messages

Attribute in an Entry
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.
Syntax
#include <ldap.h> Usage Notes
char \ldap_next_attribute(LDAP \ld, 1. Berptr Use
LDAPMessage \entry, berptr, as returned by ldap_next_attribute(), is a pointer
BerElement \\berptr)
to a BerElement that was allocated by
Library Name/Service Program: QDIRSRV/QGLDCLNT ldap_first_attribute() to keep track of its current posi-
tion. This pointer is passed to ldap_next_attribute()
Threadsafe: Yes and is used to step through the entry's attributes. This
pointer is freed by ldap_next_attribute() when there are
no more attributes (that is, when ldap_next_attribute()
The ldap_next_attribute() function returns a string that con- returns NULL). Otherwise, the caller is responsible for
tains the name of the next type in the entry. This string must freeing the BerElement pointed to by berptr when it is no
be freed using ldap_memfree() when its use is completed. longer needed by calling ldap_memfree().
The BerElement is used for internal communications
Parameters between API calls, and must not be modified by the API
caller.
ld (Input) An LDAP pointer returned by a previous call to
ldap_open(). 2. Retrieving Values for an Attribute
The attribute names returned by ldap_next_attribute()
entry
are suitable for inclusion in a call to ldap_get_values().
(Input) The attribute information as returned by
ldap_first_entry() or ldap_next_entry().

berptr
Related Information
(Input/Output) A pointer to a BerElement returned from Ÿ “ldap_count_attributes()—Retrieve Count of Attributes for
ldap_first_attribute(). The BerElement is allocated to an LDAP Entry” on page 18-8
keep track of the current position and is used as an Ÿ “ldap_count_entries()—Retrieve Count of LDAP Entries”
input and output parameter for subsequent calls to on page 18-8
ldap_next_attribute(). For more details about this
parameter, see the Usage Notes. Ÿ “ldap_first_attribute()—Retrieve First Attribute in an
Entry” on page 18-12
Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on
page 18-13

Chapter 18. Directory Services APIs 18-25

ldap_open

Ÿ “ldap_get_values()—Retrieve a Set of Attribute Values Error Conditions

from an Entry” on page 18-17
Ÿ “ldap_memfree()—Free Memory Allocated by LDAP API” If NULL is returned, the ld_errno() field in the ld parameter is
on page 18-20 set to indicate the error. See “LDAP Client API Error
Conditions” on page 18-45 for a description of the possible
Ÿ “ldap_next_entry()—Retrieve Next LDAP Entry” values for the ld_errno field.

ldap_next_entry()—Retrieve Next LDAP Error Messages

Entry The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.
Syntax
#include <ldap.h> Related Information
Ÿ “ldap_count_entries()—Retrieve Count of LDAP Entries”
LDAPMessage \ldap_next_entry(LDAP \ld, on page 18-8
LDAPMessage \entry)
Ÿ “ldap_first_entry()—Retrieve First LDAP Entry” on
Library Name/Service Program: QDIRSRV/QGLDCLNT page 18-13

Threadsafe: Yes
ldap_open()—Perform an LDAP Open
The ldap_first_entry(), ldap_next_entry(), and Operation
ldap_count_entries() functions are used to parse results
received from ldap_result() or the synchronous LDAP
search functions ldap_search_s() and ldap_search_st(). Syntax

The ldap_next_entry() function takes the result from a pre- #include <ldap.h>
vious call to ldap_first_entry() or ldap_next_entry() and
LDAP \ldap_open(char \host,
returns a pointer to the next entry in a chain of results.
int \port)
The entry returned by ldap_next_entry() can be used by
Library Name/Service Program: QDIRSRV/QGLDCLNT
functions such as ldap_get_dn(), ldap_first_attribute(), and
ldap_get_values(), as well as other functions to obtain addi- Threadsafe: Yes
tional information about the entry.

The ldap_open() function opens a connection to an LDAP

Parameters server and allocates an LDAP structure, which is used to
ld (Input) An LDAP pointer returned by a previous call to identify the connection and to maintain per-connection infor-
ldap_open(). mation.

entry The ldap_open() function returns a pointer to an LDAP

(Input) The pointer to an entry returned on a previous structure, which should be passed to subsequent calls to
call to ldap_first_entry() or ldap_next_entry(). other LDAP functions such as ldap_bind() and
ldap_search().

Authorities and Locks

Parameters
No OS/400 authority is required. All authority checking is
done by the LDAP server. host
(Input) The name of the host on which the LDAP server
is running. The host parameter may contain a blank-
Return Value separated list of hosts, and each host may optionally be
LDAP entry of the form host:port. If present, the :port portion of the
A pointer to the next LDAP entry in a chain of results. host parameter overrides the port parameter to
NULL ldap_open(). If the host parameter is null, the LDAP
No entry is returned. server will be assumed to be running on the local host.

port
(Input) The port number to which to connect. If the
default IANA-assigned port of 389 is desired,

18-26 AS/400 System API Reference V4R4

 ldap_result

LDAP_PORT should be specified. To use the default

Secure Sockets Layer (SSL) port 636 for SSL con- ldap_perror()—Print LDAP Error
nections, use the constant LDAPS_PORT. Information

Authorities and Locks Syntax

No OS/400 authority is required. All authority checking is #include <ldap.h>
done by the LDAP server.
void ldap_perror(LDAP \ld,
char \s)
Return Value
Library Name/Service Program: QDIRSRV/QGLDCLNT
LDAP pointer
A pointer to an LDAP structure. Threadsafe: Yes
NULL
ldap_open() was not successful.
The ldap_perror() function prints an indication of the error
on standard error. The error string printed out will be in
Error Conditions English only.
NULL is returned when the ldap_open() fails.
Parameters
Error Messages ld (Input) An LDAP pointer returned by a previous call to
ldap_open().
The following message may be sent from this function.
s (Input) A character string that is printed out prior to the
CPF3CF2 E Error(s) occurred during running of &1 API.
LDAP message itself.

Usage Notes
Authorities and Locks
1. Setting LDAP Options No OS/400 authority is required.
Direct manipulation of the LDAP structure is not recom-
mended. The ldap_set_option() function is provided to
set options for the specified LDAP connection. The
Return Value
ldap_get_option() function is provided to query settings None
associated with the specified LDAP connection.

Error Conditions
Related Information
Ÿ “ldap_bind()—Perform an LDAP Bind Request” on None
page 18-5
Ÿ “ldap_get_option()—Retrieve LDAP Options” on Error Messages
page 18-15
The following message may be sent from this function.
Ÿ “ldap_init()—Perform an LDAP Initialization Operation”
on page 18-18 CPF3CF2 E Error(s) occurred during running of &1 API.

Ÿ “ldap_set_option()—Set LDAP Options” on page 18-32

ldap_result()—Retrieve Result of an
Asynchronous LDAP Operation

Chapter 18. Directory Services APIs 18-27

ldap_result

result
Syntax (Output) The result of the asynchronous LDAP operation
identified by the msgid parameter. This result should be
#include <sys/time.h> passed to the LDAP parsing routines.
#include <ldap.h>

int ldap_result(LDAP \ld, Authorities and Locks

int msgid,
int all, No OS/400 authority is required. All authority checking is
struct timeval \timeout, done by the LDAP server.
LDAPMessage \\result)

Library Name/Service Program: QDIRSRV/QGLDCLNT Return Value

0 Zero is returned if the timeout specified was
Threadsafe: Yes
exceeded. The result value returned in this
case is meaningless.
The ldap_result() function is used to wait for and return the −1 ldap_result() was not successful. The
result of an operation previously initiated by one of the LDAP ldap_result2error() function can be used to
asynchronous operation functions (such as ldap_search() get an error value. The ld_errno of the ld
and ldap_modify()). Those functions return a call identifier structure is set to indicate the error. The
upon successful initiation of the operation or -1 in case of result value returned in this case is meaning-
error. This unique identifier can be used to request the result less.
of a specific operation from ldap_result() through the msgid [LDAP_SUCCESS]
parameter. The ldap_result() request completed success-
fully.
[LDAP_RES_BIND]
Parameters A bind result was returned.
ld (Input) An LDAP pointer returned by a previous call to [LDAP_RES_SEARCH_ENTRY]
ldap_open() and ldap_init(). A single entry from a previous search was
returned.
msgid [LDAP_RES_SEARCH_RESULT]
(Input) The call identifier returned when an operation The final result along with one or more entries
was initiated. Provide the msgid if the result of a spe- matching a previous search was returned.
cific operation is required; otherwise, supply [LDAP_RES_MODIFY]
LDAP_RES_ANY. The result of a modify request was returned.
[LDAP_RES_ADD]
all (Input) For search responses, whether a single entry of
The result of an add request was returned.
the search should be returned or all results of the search
[LDAP_RES_DELETE]
should be returned.
The result of a delete request was returned.
A search response is made up of zero or more search [LDAP_RES_MODRDN]
entries followed by a search result. If all is set to 0, The result of a modify RDN request was
search entries will be returned one at a time as they returned.
come in, through separate calls to ldap_result(). If the [LDAP_RES_COMPARE]
all parameter is non-zero, the search response will only The result of a compare request was returned.
be returned in its entirety, that is, after all entries and the
final search result have been received.
Error Conditions
timeout
(Input) Specifies blocking for ldap_result(). If the If ldap_result() is not successful, ld_errno will be set to indi-
timeout parameter is not NULL, it specifies a maximum cate the error. See “LDAP Client API Error Conditions” on
interval to wait for the selection to complete. If timeout page 18-45 for a description of the possible values for the
is NULL, the select blocks indefinitely until the result for ld_errno field.
the operation identified by msgid is received. To poll,
the timeout parameter should be non-NULL, pointing to
a zero-valued timeval structure.
Error Messages
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.

18-28 AS/400 System API Reference V4R4

 ldap_search

Usage Notes Parameters

1. Freeing Memory ld (Input) An LDAP pointer returned by a previous call to
Memory is allocated to store the results from the ldap_open().
ldap_result() call. The memory can be freed by calling
res
ldap_msgfree.
(Input) The result, as produced by ldap_result() or
2. Running in a Threaded Environment ldap_search_s() to be converted to the error code with
which it is associated.
To allow multiple LDAP APIs to be performed from mul-
tiple client program threads against a single LDAP con- freeit
nection, the LDAP functions are serialized. If (Input) Whether or not the result, res, should be freed as
asynchronous LDAP requests have been made from a result of calling ldap_result2error(). If nonzero, free it.
multiple client program threads against the same LDAP If 0, do not free it.
connection, the first ldap_result() call will cause all
LDAP API calls in the other threads to be held up until
that first ldap_result() has completed. Authorities and Locks
No OS/400 authority is required.
To effectively use asynchronous operations to the
advantage of the client program, calls to the
ldap_result() API should be designed to complete as Return Value
quickly as possible. This will prevent other LDAP API
ld_errno
calls for that same LDAP connection from experiencing
The ld_errno value of the ld structure is returned. See
long wait times. It is recommended that calls to
“Error Conditions” for a description of the possible
ldap_result() be made to wait for the first available
values for the ld_errno field.
result instead of waiting for specific results when running
in a multithreaded environment.
Error Conditions
Related Information The ld_errno will be set to indicate the error. See “LDAP
Ÿ “ldap_msgfree()—Free LDAP Result Message” on Client API Error Conditions” on page 18-45 for a description
page 18-24 of the possible return values for the ld_errno field.
Ÿ “ldap_result2error()—Retrieve LDAP Error Information”
Error Messages
ldap_result2error()—Retrieve LDAP Error The following message may be sent from this function.
Information CPF3CF2 E Error(s) occurred during running of &1 API.

Syntax ldap_search()—Perform an LDAP Search

#include <ldap.h> Operation
int ldap_result2error(LDAP \ld,
LDAPMessage \res, Syntax
int freeit)
#include <ldap.h>
Library Name/Service Program: QDIRSRV/QGLDCLNT
int ldap_search(LDAP \ld,
Threadsafe: Yes char \base,
int scope,
char \filter,
The ldap_result2error() API takes res, a result as produced char \attrs[],
by ldap_result() or ldap_search_s(), and returns the corre- int attrsonly)
sponding error code.
Library Name/Service Program: QDIRSRV/QGLDCLNT
If the freeit parameter is nonzero it indicates that the res
parameter should be freed by a call to the ldap_msgfree() Threadsafe: Yes
API after the error code has been extracted. The ld_errno
field in ld is set and returned. The ldap_search() function is used to perform an LDAP
search operation.

Chapter 18. Directory Services APIs 18-29

ldap_search_s

ldap_search() is an asynchronous request. The result of the Authorities and Locks

operation can be obtained by a subsequent call to
ldap_result(). No OS/400 authority is required. All authority checking is
done by the LDAP server.
Both read and list functions can be obtained by using a filter
such as objectclass=\ and a scope of either
LDAP_SCOPE_BASE (to emulate read) or Return Value
LDAP_SCOPE_ONELEVEL (to emulate list). LDAP message identifier
ldap_search() request was sent. The result of the
Parameters operation can be obtained by a subsequent call to
ldap_result().
ld (Input) An LDAP pointer returned by a previous call to −1 ldap_search() was not successful. The ld_errno of the
ldap_open() or ldap_init(). ld structure is set to indicate the error.
base
(Input) The distinguished name of the entry at which to Error Conditions
start the search.
If ldap_search() is not successful, ld_errno will be set to
scope indicate the error. See “LDAP Client API Error Conditions”
(Input) The scope of the search. The scope can be on page 18-45 for a description of the possible values for the
LDAP_SCOPE_BASE (to search the object itself), ld_errno field.
LDAP_SCOPE_ONELEVEL (to search the object's
immediate children), or LDAP_SCOPE_SUBTREE (to
search the object and all its descendents). Error Messages
filter The following message may be sent from this function.
(Input) The string representation of the filter to apply in
CPF3CF2 E Error(s) occurred during running of &1 API.
the search. Simple filters can be specified as
attributetype=attributevalue. More complex filters are
specified using a prefix notation according to the fol- Related Information
lowing Backus-Naur Form (BNF):
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <simple> LDAP Operation” on page 18-27
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist> Ÿ “ldap_search_s()—Perform an LDAP Search Operation
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist> (Synchronous)”
<simple> ::= <attributetype> <filtertype> <attributevalue>
<filtertype> ::= '=' | '˜=' | '<=' | '>=' Ÿ “ldap_search_st()—Perform an LDAP Search Operation
(Timed Synchronous)” on page 18-31
The ˜= construct is used to specify approximate
matching. The representation for <attributetype> and
<attributevalue> are as described in RFC 1778. In addi-
tion, <attributevalue> can be a single asterisk (*) to ldap_search_s()—Perform an LDAP Search
achieve an attribute existence test, or can contain text Operation (Synchronous)
and asterisks interspersed to achieve substring
matching.
For example, the filter mail=\ will find any entries that Syntax
#include <ldap.h>
have a mail attribute. The filter
mail=\@terminator.rs.itd.umich.edu will find any int ldap_search_s(LDAP \ld,
char \base,
entries that have a mail attribute ending in the specified int scope,
string. To put parentheses in a filter, precede them with char \filter, \attrs[],
int attrsonly,
a backslash (\) character. See RFC 1558 for a more LDAPMessage \\res)
complete description of allowable filters.
Library Name/Service Program: QDIRSRV/QGLDCLNT
attrs
(Input) A null-terminated array of character-string attri- Threadsafe: Yes
bute types to return from entries that match filter. If
NULL is specified, all attributes will be returned.
The ldap_search_s() function is used to perform an LDAP
attrsonly search operation.
(Input) Attribute information. attrsonly should be set to 1
to request attribute types only. Set to 0 to request both ldap_search_s() is a synchronous request.
attributes types and attribute values.

18-30 AS/400 System API Reference V4R4

 ldap_search_st

Both read and list functions can be obtained by using a filter Authorities and Locks
such as objectclass=\ and a scope either of
LDAP_SCOPE_BASE (to emulate read) or No OS/400 authority is required. All authority checking is
LDAP_SCOPE_ONELEVEL (to emulate list). done by the LDAP server.

Parameters Return Value

ld (Input) An LDAP pointer returned by a previous call to ld_errno
ldap_open() or ldap_init(). The ld_errno value of the ld structure is returned indi-
cating a success or failure condition. See “Error
base Conditions” for a description of the return values that
(Input) The distinguished name of the entry at which to can be returned.
start the search.

scope Error Conditions

(Input) The scope of the search. The scope can be
LDAP_SCOPE_BASE (to search the object itself), If ldap_search_s() is not successful, ld_errno will be set to
LDAP_SCOPE_ONELEVEL (to search the object's indicate the error. See “LDAP Client API Error Conditions”
immediate children), or LDAP_SCOPE_SUBTREE (to on page 18-45 for a description of the possible values for the
search the object and all its descendents). ld_errno field.
filter
(Input) The string representation of the filter to apply in Error Messages
the search. Simple filters can be specified as
attributetype=attributevalue. More complex filters are The following message may be sent from this function.
specified using a prefix notation according to the fol- CPF3CF2 E Error(s) occurred during running of &1 API.
lowing Backus-Naur Form (BNF):
<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <simple> Related Information
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist> Ÿ “ldap_search()—Perform an LDAP Search Operation” on
<not> ::= '!' <filter> page 18-29
<filterlist> ::= <filter> | <filter> <filterlist>
<simple> ::= <attributetype> <filtertype> <attributevalue> Ÿ “ldap_search_st()—Perform an LDAP Search Operation
<filtertype> ::= '=' | '˜=' | '<=' | '>='
(Timed Synchronous)”
The ˜= construct is used to specify approximate
matching. The representation for <attributetype> and
<attributevalue> are as described in RFC 1778. In addi- ldap_search_st()—Perform an LDAP
tion, <attributevalue> can be a single asterisk (*) to
achieve an attribute existence test, or can contain text
Search Operation (Timed Synchronous)
and asterisks interspersed to achieve substring
matching.
Syntax
For example, the filter mail=\ will find any entries that
#include <sys/time.h>
have a mail attribute. The filter
#include <ldap.h>
mail=\@terminator.rs.itd.umich.edu will find any
entries that have a mail attribute ending in the specified int ldap_search_st(LDAP \ld,
string. To put parentheses in a filter, precede them with char \base,
a backslash (\) character. See RFC 1558 for a more int scope,
complete description of allowable filters. char \filter, \attrs[],
int attrsonly,
attrs struct timeval \timeout,
(Input) A null-terminated array of character-string attri- LDAPMessage \\res)
bute types to return from entries that match filter. If
NULL is specified, all attributes will be returned. Library Name/Service Program: QDIRSRV/QGLDCLNT
attrsonly Threadsafe: Yes
(Input) Attribute information. attrsonly should be set to 1
to request attribute types only. Set to 0 to request both
attributes types and attribute values. The ldap_search_st() function is used to perform a timed
LDAP search operation.
res
(Output) The result of the search request. This result
should be passed to the LDAP parsing functions.

Chapter 18. Directory Services APIs 18-31

ldap_set_option

ldap_search_st() is a synchronous request. timeout

(Input) A timeout value for a synchronous search.
Both read and list functions can be obtained by using a filter
such as objectclass=\ and a scope of either res
LDAP_SCOPE_BASE (to emulate read) or (Output) The result of the search request. This result
LDAP_SCOPE_ONELEVEL (to emulate list). should be passed to the LDAP parsing functions.

Parameters Authorities and Locks

ld (Input) An LDAP pointer returned by a previous call to No OS/400 authority is required. All authority checking is
ldap_open() or ldap_init(). done by the LDAP server.

base
(Input) The distinguished name of the entry at which to Return Value
start the search. ld_errno
scope The ld_errno value of the ld structure is returned indi-
(Input) The scope of the search. The scope can be cating a success or failure condition. See “Error
LDAP_SCOPE_BASE (to search the object itself), Conditions” for a description of the return values that
LDAP_SCOPE_ONELEVEL (to search the object's can be returned.
immediate children), or LDAP_SCOPE_SUBTREE (to
search the object and all its descendents). Error Conditions
filter
If ldap_search_st() is not successful, ld_errno will be set to
(Input) The string representation of the filter to apply in
indicate the error. See “LDAP Client API Error Conditions”
the search. Simple filters can be specified as
on page 18-45 for a description of the possible values for the
attributetype=attributevalue. More complex filters are
ld_errno field.
specified using a prefix notation according to the fol-
lowing Backus-Naur Form (BNF):
<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <simple>
Error Messages
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist> The following message may be sent from this function.
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<simple> ::= <attributetype> <filtertype> <attributevalue>
CPF3CF2 E Error(s) occurred during running of &1 API.
<filtertype> ::= '=' | '˜=' | '<=' | '>='

The ˜= construct is used to specify approximate Related Information

matching. The representation for <attributetype> and
<attributevalue> are as described in RFC 1778. In addi- Ÿ “ldap_search()—Perform an LDAP Search Operation” on
tion, <attributevalue> can be a single asterisk (*) to page 18-29
achieve an attribute existence test, or can contain text Ÿ “ldap_search_s()—Perform an LDAP Search Operation
and asterisks interspersed to achieve substring (Synchronous)” on page 18-30
matching.
For example, the filter mail=\ will find any entries that
have a mail attribute. The filter ldap_set_option()—Set LDAP Options
mail=\@terminator.rs.itd.umich.edu will find any
entries that have a mail attribute ending in the specified
string. To put parentheses in a filter, precede them with Syntax
a backslash (\) character. See RFC 1558 for a more #include <ldap.h>
complete description of allowable filters.
int ldap_set_option(LDAP \ld,
attrs
int optionToSet,
(Input) A null-terminated array of character-string attri- void \optionValue)
bute types to return from entries that match filter. If
NULL is specified, all attributes will be returned. Library Name/Service Program: QDIRSRV/QGLDCLNT
attrsonly Threadsafe: Yes
(Input) Attribute information. attrsonly should be set to 1
to request attribute types only. Set to 0 to request both
attributes types and attribute values. The ldap_set_option() function is used to set options for the
specified LDAP connection.

18-32 AS/400 System API Reference V4R4

 ldap_set_option

Parameters with the LDAP server. The first cipher in the

list that is common with the list of ciphers
ld (Input) An LDAP pointer returned by a previous call to supported by the server is chosen. The
ldap_open() or ldap_init(). default ciphers are the first two export type
ciphers shown in the list. Note that the
optionToSet
ciphers supported by the export version of
(Input) The option value that is to be set.
the LDAP client library are fixed to the
optionValue defaults, and are not modified with the use
(Input) The value to be set by ldap_set_option(). of ldap_set_option. Supported ciphers
follows:
LDAP_SSL_RC4_MD5_EX "ð3"
Authorities and Locks LDAP_SSL_RC2_MD5_EX "ð6"
LDAP_SSL_RC4_SHA_US "ð5" (Non-export only)
No OS/400 authority is required. All authority checking is LDAP_SSL_RC4_MD5_US "ð4" (Non-export only)
LDAP_SSL_DES_SHA_US "ð9" (Non-export only)
done by the LDAP server. LDAP_SSL_3DES_SHA_US "ðA" (Non-export only)

An example follows:
Return Value ldap_set_option( ld,
LDAP_OPT_SSL_CIPHER,
return code [LDAP_SUCCESS] is returned when (void \)LDAP_SSL_RC4_MD5_EX);
ldap_set_option() completes successfully.
LDAP_OPT_SIZELIMIT (0x00)
See “Error Conditions” for a list of return
Specifies the maximum number of entries
codes that can be returned when
that can be returned on a search operation,
ldap_set_option() does not complete suc-
bounded by the maximum number of entries
cessfully.
that the server is configured to return. An
example follows:
Error Conditions ldap_set_option( ld,
LDAP_OPT_SIZELIMIT, (void \) 5ð);
If ldap_set_option() does not complete successfully, the fol-
LDAP_OPT_TIMELIMIT (0x01)
lowing error code is returned:
Specifies the number of seconds to wait for
[LDAP_PARAM_ERROR] search results. An example follows:
An LDAP API was called with a bad param- ldap_set_option( ld,
eter. LDAP_OPT_TIMELIMIT, (void \)5);

LDAP_OPT_DEREF (0x03)
Error Messages Specifies alternative rules for following
aliases at the server. Supported values
The following message may be sent from this function. follow:
LDAP_DEREF_NEVER ð
CPF3CF2 E Error(s) occurred during running of &1 API. LDAP_DEREF_SEARCHING 1
LDAP_DEREF_FINDING 2
LDAP_DEREF_ALWAYS 3
Usage Notes An example follows:
1. Supported LDAP Options ldap_set_option( ld, LDAP_OPT_DEREF,
(void \)LDAP_DEREF_ALWAYS );
The following options, and associated values are sup-
ported for the ldap_set_option() function. LDAP_OPT_REFERRALS (0x02)
Specifies whether the LDAP support will
LDAP_OPT_SSL_TIMEOUT (0x08)
automatically follow referrals returned by
Specifies in seconds the Secure Sockets
LDAP servers. It can be set to one of the
Layer (SSL) inactivity timer. After the speci-
constants LDAP_OPT_ON or
fied seconds, in which no SSL activity has
LDAP_OPT_OFF. By default, the LDAP
occurred, the SSL connection will be
client will follow referrals.
refreshed with new session keys. A smaller
value may marginally increase security, but An example follows:
will have a small impact on performance. ldap_set_option( ld,
An example follows: LDAP_OPT_REFERRALS, LDAP_OPT_ON);

ldap_set_option( ld, LDAP_OPT_REFHOPLIMIT (0x05)

LDAP_OPT_SSL_TIMEOUT, (void \) 1ðð );
Specifies the maximum number of hops that
LDAP_OPT_SSL_CIPHER (0x07) the LDAP client will take when chasing
Specifies a set of one or more ciphers to be referrals. The default is 5.
used when negotiating the cipher algorithm An example follows:

Chapter 18. Directory Services APIs 18-33

ldap_simple_bind

ldap_set_option( ld, rebindproc

LDAP_OPT_REFHOPLIMIT, (void \) 7);
(Input) The entry point of a function that will be called
LDAP_OPT_RESTART (0x04) back to obtain bind credentials that are used when a
Specifies whether the LDAP support should new server is contacted due to an LDAP referral. See
restart the select() system call when it is the Usage Notes for details of this parameter.
interrupted by the system (that is, errno is
set to [EINTR]). Supported values follow:
Authorities and Locks
LDAP_OPT_ON
LDAP_OPT_OFF No OS/400 authority is required. All authority checking is
An example follows: done by the LDAP server.
ldap_set_option(ld,
LDAP_OPT_RESTART, (void \)LDAP_OPT_OFF );
Return Value
None
Related Information
Ÿ “ldap_get_option()—Retrieve LDAP Options” on
page 18-15
Error Conditions
Ÿ “ldap_init()—Perform an LDAP Initialization Operation” None
on page 18-18
Ÿ “ldap_open()—Perform an LDAP Open Operation” on Error Messages
page 18-26
The following message may be sent from this function.
CPF3CF2 E Error(s) occurred during running of &1 API.
ldap_set_rebind_proc()—Set Rebind
Procedure
Usage Notes
1. Rebinding While Following Referrals
Syntax The rebindproc function should be declared like this:
#include <ldap.h> int rebindproc(LDAP \ld,
char \\whop,
void ldap_set_rebind_proc(LDAP \ld, char \\credp,
int (\rebindproc)()) int \methodp,
int freeit);
Library Name/Service Program: QDIRSRV/QGLDCLNT
The system will first call rebindproc to obtain the referral
Threadsafe: Yes bind credentials, and the freeit parameter will be zero.
The whop, credp, and methodp should be set as appro-
priate. If the rebindproc returns LDAP_SUCCESS,
The ldap_set_rebind_proc() API is used to set the entry referral processing continues, and the rebindproc will be
point of a function that will be called back to obtain bind cre- called a second time with freeit set to nonzero. The
dentials for use when a new server is contacted due to an nonzero value gives the user application a chance to
LDAP referral. (Bind credentials refer to the credentials, free any memory allocated in the previous call.
usually the user's distinguished name and password, that are
used to authenticate the user or application to the server.) If anything but LDAP_SUCCESS is returned by the first
Note that this function is only available when call to the rebindproc, then referral processing is stopped
LDAP_OPT_REFERRALS is set (this is the default). If and that error code is returned for the original LDAP API
ldap_set_rebind_proc() is never called, or if it is called with call.
a NULL rebindproc parameter, a simple LDAP bind function
that is not authenticated will always be done when chasing Related Information
referrals.
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
page 18-26
Parameters
ld (Input) An LDAP pointer returned by a previous call to
ldap_open(). ldap_simple_bind()—Perform a Simple
LDAP Bind Request

18-34 AS/400 System API Reference V4R4

 ldap_simple_bind_s

Error Messages
Syntax
The following message may be sent from this function.
#include <ldap.h>
CPF3CF2 E Error(s) occurred during running of &1 API.
int ldap_simple_bind(LDAP \ld,
char \who,
char \passwd) Usage Notes
1. Securing an LDAP Connection
Library Name/Service Program: QDIRSRV/QGLDCLNT
When a connection has been made to an LDAP server
Threadsafe: Yes using either the ldap_open() or ldap_init() function, an
unencrypted password will be used when authenticating
the DN to an LDAP server. The ldap_ssl_start() func-
The ldap_simple_bind() function is used to authenticate a tion can be used when password encryption is desired.
distinguished name (DN) to a directory server.

After a connection is made to an LDAP server by using the Related Information

ldap_open() API, an LDAP bind API must be called before Ÿ “ldap_bind()—Perform an LDAP Bind Request” on
any other LDAP APIs can be called for that connection. page 18-5
ldap_simple_bind() is an asynchronous request. The result Ÿ “ldap_open()—Perform an LDAP Open Operation” on
of the operation can be obtained by a subsequent call to page 18-26
ldap_result(). Ÿ “ldap_result()—Retrieve Result of an Asynchronous
LDAP Operation” on page 18-27
Parameters Ÿ “ldap_ssl_start()—Start a Secure LDAP Connection” on
ld (Input) An LDAP pointer returned by a previous call to page 18-36
ldap_open().

who ldap_simple_bind_s()—Perform a Simple

(Input) A pointer to the null-terminated distinguished LDAP Bind Request (Synchronous)
name (DN) of the entry in which to bind.

passwd
(Input) The password used in association with the distin- Syntax
guished name of the entry in which to bind. An #include <ldap.h>
unencrypted password will be used when authenticating
the DN to an LDAP server. int ldap_simple_bind_s(LDAP \ld,
char \who,
char \passwd)
Authorities and Locks
Library Name/Service Program: QDIRSRV/QGLDCLNT
No OS/400 authority is required. All authority checking is
done by the LDAP server. Threadsafe: Yes

Return Value The ldap_simple_bind_s() function is used to authenticate a

LDAP message identifier distinguished name (DN) to a directory server.
ldap_simple_bind() request was sent. The result of
the operation can be obtained by a subsequent call to After a connection is made to an LDAP server by using the
ldap_result(). ldap_open() API, an LDAP bind API must be called before
−1 ldap_simple_bind() was not successful. The ld_errno any other LDAP APIs can be called for that connection.
of the ld structure is set to indicate the error.
ldap_simple_bind_s() is a synchronous request.

Error Conditions Parameters

If ldap_simple_bind() is not successful, ld_errno will be set ld (Input) An LDAP pointer returned by a previous call to
to indicate the error. See “LDAP Client API Error Conditions” ldap_open().
on page 18-45 for a description of the possible values for the
ld_errno field.

Chapter 18. Directory Services APIs 18-35

ldap_ssl_start

who
(Input) A pointer to the null-terminated distinguished Syntax
name (DN) of the entry in which to bind.
#include <ldap.h>
passwd #include <ldapssl.h>
(Input) The password used in association with the distin-
guished name of the entry in which to bind. An int ldap_ssl_start(LDAP \ld,
unencrypted password will be used when authenticating char \keyring,
the DN to an LDAP server. char \keyring_pw,
char \name)

Authorities and Locks Library Name/Service Program: QDIRSRV/QGLDCLNT

No OS/400 authority is required. All authority checking is Threadsafe: Yes

done by the LDAP server.
The ldap_ssl_start() function is used to start a secure con-
Return Value nection (using Secure Sockets Layer (SSL)) to an LDAP
server. ldap_ssl_start() accepts the ld from an ldap_open()
ld_errno
and performs an SSL handshake to a server.
The ld_errno value of the ld structure is returned indi-
ldap_ssl_start() must be called after ldap_open() and prior
cating a success or failure condition. See “Error
to ldap_bind(). Once the secure connection is established
Conditions” for a description of the return values that
for the ld, all subsequent LDAP messages that flow over the
can be returned.
secure connection are encrypted, including the ldap_bind()
parameters, until ldap_unbind() is called.
Error Conditions
If ldap_simple_bind_s() is not successful, ld_errno will be Parameters
set to indicate the error. See “LDAP Client API Error ld (Input) An LDAP pointer returned by a previous call to
Conditions” on page 18-45 for a description of the possible ldap_open().
values for the ld_errno field.
keyring
(Input) The name of a key ring file. The key ring file
Error Messages name is required. The key ring file typically contains
one or more certificates of certificate authorities (CAs)
The following message may be sent from this function.
that are trusted by the client. These types of X.509 cer-
CPF3CF2 E Error(s) occurred during running of &1 API. tificates are also known as trusted roots. A key ring file
can also be used to store one or more client's private
keys and one or more associated client certificates. A
Usage Notes
private key and associated client certificate is required
1. Securing an LDAP Connection only if the LDAP server is configured to require client
When a connection has been made to an LDAP server and server authentication.
using either the ldap_open() or ldap_init() function, an A fully qualified path and file name is recommended. If
unencrypted password will be used when authenticating a file name without a fully qualified path is specified, the
the DN to an LDAP server. The ldap_ssl_start() func- LDAP APIs will look in the current directory for the file.
tion can be used when password encryption is desired.
If the LDAP server is configured to provide only server
authentication, a private key and client certificate are not
Related Information required (and name can be set to null).
Ÿ “ldap_open()—Perform an LDAP Open Operation” on If the LDAP server is configured to perform client and
page 18-26 server authentication, a client certificate is required.
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
name can be set to null if a default certificate and
private-key pair has been designated as the default.
LDAP Operation” on page 18-27
Similarly, certificatename can be set to null if there is a
Ÿ “ldap_ssl_start()—Start a Secure LDAP Connection” single certificate and private-key pair in the designated
key ring file.

keyring_pw
ldap_ssl_start()—Start a Secure LDAP
(Input) The password that is used to protect the contents
Connection of the key ring file. This password is important since it
protects the private key stored in the key ring file. The

18-36 AS/400 System API Reference V4R4

 ldap_ssl_start

password was specified when the key ring file was ini- [LDAP_SSL_ERROR_BAD_CERT_SIG]
tially created. A null password is accepted. The client or server certificate signature is not
valid.
This parameter is assumed to be represented in the
CCSID (coded character set identifier) currently in effect
[LDAP_SSL_ERROR_BAD_CIPHER_SUITE]
A specified cipher is not valid.
for the job. If the CCSID of the job is 65535, this param-
eter is assumed to be represented in the default CCSID
[LDAP_SSL_ERROR_BAD_KEY_LEN_FOR_EXPORT]
The key length specified for the SSL session
of the job.
was greater than the value allowed for export
name environments.
(Input) The name, or label, associated with the client [LDAP_SSL_ERROR_BAD_MAC]
private-key and certificate pair in the key ring file. It is A bad message authentication code was
used to uniquely identify a private-key and certificate received.
pair, as stored in the key ring file, and may be some- [LDAP_SSL_ERROR_BAD_MALLOC]
thing like: Digital ID for Fred Smith. An attempt to allocate memory space for SSL
processing failed.
[LDAP_SSL_ERROR_BAD_MESSAGE]
Authorities and Locks A badly formatted message was received.
[LDAP_SSL_ERROR_BAD_PEER]
Figure 18-2. Authorization Required for ldap_ssl_start() The peer system is not recognized.
Authority [LDAP_SSL_ERROR_BAD_SSL_HANDLE]
Object Referred to Required The pointer to the SSL handle structure is not
Each directory in the path to the key ring file and *X valid.
the directory the key ring file is located in. [LDAP_SSL_ERROR_BAD_STATE]
Key ring file *R
A bad state was detected for the session.
[LDAP_SSL_ERROR_CLOSED]
Key-ring password file (if configured and used) *R The SSL object associated with this SSL
session no longer exists.
[LDAP_SSL_ERROR_CRYPTO_NOT_INSTALLED]
Return Value One of the required Cryptographic Access
value Provider licensed products is not installed on
[LDAP_SSL_INITIALIZE_OK] is returned when this AS/400.
ldap_ssl_start() completes successfully. See “Error [LDAP_SSL_ERROR_HANDLE_CREATION_FAILED]
Conditions” for a description of the return values that A sec_soc_data structure could not be
can be returned when an error occurs. created.
[LDAP_SSL_ERROR_INTERNAL]
An internal APAR condition occurred during
Error Conditions SSL processing.
[LDAP_SSL_ERROR_IO]
If ldap_ssl_start() is not successful, one of the following
A general I/O error occurred.
error values is returned:
[LDAP_SSL_ERROR_LDAP_SSL_INITIALIZATION_FAILED
[LDAP_SSL_BAD_FORMAT_OR_INVALID_PW] ]
The specified key ring file either has a format The attempt to initialize the SSL environment
that is not valid or the password specified for failed to complete successfully.
the key ring file is not valid. [LDAP_SSL_ERROR_NO_ACCESS]
[LDAP_SSL_BAD_PARAMETER] The user does not have authority to the speci-
A parameter value that is not valid was speci- fied key ring file.
fied. [LDAP_SSL_ERROR_NO_CERTIFICATE]
[LDAP_SSL_ERR_INIT_PARM_NOT_VALID] There is no client or server certificate avail-
A parameter specified for the initialization able.
operation is not valid. This is usually a bad [LDAP_SSL_ERROR_NO_CIPHERS]
cipher specification. The ciphers were not specified or no common
[LDAP_SSL_ERROR_BAD_BUFFER_SIZE] ciphers could be negotiated.
A negative number was specified for the [LDAP_SSL_ERROR_NO_INITIALIZE]
buffer size on an SSL read or write operation. An SSL operation was attempted before SSL
[LDAP_SSL_ERROR_BAD_CERT] initialization of the socket descriptor was suc-
The client or server certificate is not valid. cessfully completed.
[LDAP_SSL_ERROR_BAD_CERTIFICATE] [LDAP_SSL_ERROR_NO_KEYRING]
The certificate is not valid. There is no key ring file specified. A key ring
file is required for SSL processing.

Chapter 18. Directory Services APIs 18-37

ldap_ssl_start

[LDAP_SSL_ERROR_NO_PRIVATE_KEY] [LDAP_SSL_KEYFILE_BAD_MALLOC]
There is no private key available for SSL pro- An attempt to allocate memory space for SSL
cessing. processing of the key ring file failed.
[LDAP_SSL_ERROR_NOT_ENABLED] [LDAP_SSL_KEYFILE_BAD_PASSWORD]
An SSL operation was attempted before the Password for key ring file was not valid.
socket descriptor was enabled for SSL pro- [LDAP_SSL_KEYFILE_CERT_EXPIRED]
cessing. The validity time period of the certificate has
[LDAP_SSL_ERROR_NOT_SSLV3_CLIENT] expired.
The current SSL session was specified as an [LDAP_SSL_KEYFILE_DUPLICATE_KEY]
SSL Version 3 client, and the operation The specified key ring file contains a duplicate
requested was not for an SSL Version 3 key value of another key ring file. The key
client. cannot be used.
[LDAP_SSL_ERROR_NOT_TRUSTED_ROOT] [LDAP_SSL_KEYFILE_DUPLICATE_LABEL]
The certificate is signed by a certificate The specified key ring file contains a duplicate
authority that is not known. label value of another key ring file. The label
[LDAP_SSL_ERROR_PASSWORD_EXPIRED] cannot be used.
The specified key ring file's password has [LDAP_SSL_KEYFILE_DUPLICATE_NAME]
expired. The specified key ring file name is a duplicate
[LDAP_SSL_ERROR_PERMISSION_DENIED] of another key ring file name and cannot be
Not authorized to do operation. used.
[LDAP_SSL_ERROR_SELF_SIGNED] [LDAP_SSL_KEYFILE_IO_ERROR]
The certificate was signed by the peer system. An attempt to access the key file containing
[LDAP_SSL_ERROR_SOCKET_CLOSED] the keys and certificate failed.
The socket that was being used for SSL pro- [LDAP_SSL_KEYFILE_NOT_FOUND]
cessing has been closed. The specified key ring file does not exist.
[LDAP_SSL_ERROR_UNKNOWN_ERROR] [LDAP_SSL_KEYFILE_OPEN_FAILED]
An unknown error has occurred. An attempt to open the key file containing the
[LDAP_SSL_ERROR_UNSUPPORTED] keys and certificate failed.
This return code indicates one of the fol- [LDAP_SSL_KEYFILE_WRITE_FAILED]
lowing: The attempt to write data to the SSL enabled
Ÿ Operation is not supported by OS/400. socket descriptor failed.
Ÿ The hs_type value is not valid. [LDAP_SSL_SOC_BAD_SEC_TYPE]
[LDAP_SSL_ERROR_UNSUPPORTED_CERTIFICATE_TYPE] The sec_types value is not valid.
The root certificate authority for the client or [LDAP_SSL_SOC_BAD_SEC_TYPE_COMBINATION]
server certificate is not supported or recog- The hs_type value of AS_CLIENT is not
nized. allowed when ldap_ssl_initialize() was issued
[LDAP_SSL_ERROR_WOULD_BLOCK] with a sec_types value of ALL.
The input or output operation would have [LDAP_SSL_SOC_BAD_V2_CIPHER]
caused the process or thread to block either An SSL Version 2 cipher value was specified
waiting for incoming data or waiting for a that was not valid.
window in which to send outgoing data. [LDAP_SSL_SOC_BAD_V3_CIPHER]
[LDAP_SSL_INIT_SEC_TYPE_NOT_VALID] An SSL Version 3 cipher value was specified
The sec_types value was not valid. that was not valid.
[LDAP_SSL_INIT_V2_TIMEOUT_NOT_VALID] [LDAP_SSL_STASH_PASSWORD_FILE_NOT_FOUND]
The V2_session_timeout value was not valid. The password key-ring file does not exist, or
[LDAP_SSL_INIT_V3_TIMEOUT_NOT_VALID] you do not have authority to the file or to a
The V3_session_timeout value was not valid. directory where the file exists.
[LDAP_SSL_KEYFILE_BAD_DNAME] [LDAP_SSL_STASH_PASSWORD_FILE_OPEN_FAILED]
The distinguished name specified for key ring The specified key ring file could not be
file was not valid. opened.
[LDAP_SSL_KEYFILE_BAD_FORMAT] [LDAP_SSL_WARNING_INVALID_SERVER_CERT]
The key ring file is not of the correct format. The specified key ring contains a server certif-
[LDAP_SSL_KEYFILE_BAD_KEY] icate that is not valid.
The private or public key in the specified key [LDAP_SSL_WARNING_INVALID_SERVER_PRIV_KEY]
ring file is not valid. The SSL server's private key is not valid.
[LDAP_SSL_KEYFILE_BAD_LABEL]
The specified key ring file has a label that is
not valid.
Error Messages
The following message may be sent from this function.

18-38 AS/400 System API Reference V4R4

 ldap_unbind

CPF3CF2 E Error(s) occurred during running of &1 API. The export version follows:

#define LDAP_SSL_RC4_MD5_EX
Usage Notes #define LDAP_SSL_RC2_MD5_EX
1. ldapssl.h
The nonexport version follows:
The ldapssl.h header file contains return codes that are
specific to the ldap_ssl_start() function. #define LDAP_SSL_RC4_SHA_US
2. Authentication #define LDAP_SSL_RC4_MD5_US
#define LDAP_SSL_DES_SHA_US
If the LDAP servers accessed by the client use server #define LDAP_SSL_3DES_SHA_US
authentication, it is sufficient to define one or more #define LDAP_SSL_RC4_MD5_EX
trusted root certificates in the key ring file. With server #define LDAP_SSL_RC2_MD5_EX
authentication, the client can be assured that the target
LDAP server has been issued a certificate by one of the
trusted certificate authorities. In addition, all LDAP
transactions that flow over the SSL connection with the
Related Information
server are encrypted (including the LDAP credentials Ÿ “ldap_open()—Perform an LDAP Open Operation” on
that are supplied on the ldap_open() call. page 18-26
If an LDAP server accessed by the client requires client Ÿ “ldap_set_option()—Set LDAP Options” on page 18-32
and server authentication, you must obtain a client certif-
icate that has been issued by a certificate authority that
is trusted by the server. If a network administrator has
Example
given you a key ring file that already contains the The following example shows a sequence where the entire
required certificate (and private key), then no additional set of LDAP transactions are protected by using an SSL con-
setup is required. nection, including the DN and password that flow on the
3. Options ldap_bind():
Options are supported for controlling the nature of the
secure connection. These options are set using the ld = ldap_open( ldaphost, ldapport );
ldap_set_option() function. To specify the number of rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, (void \)
LDAP_SSL_3DES_SHA_US
seconds for the SSL session-level inactivity timer, use:
LDAP_SSL_RC4_MD5_US
ldap_set_option(ld,
LDAP_OPT_SSL_TIMEOUT, (void \)timeout)
LDAP_SSL_RC4_MD5_EX);
rc = ldap_ssl_start(ld, keyfile, keyfile_pw, name);
where timeout specifies a timeout in seconds. When rc = ldap_simple_bind_s(ld, binddn, passwd);
timeout occurs, SSL re-establishes the session keys for
the session for increased security. ...additional LDAP API calls
To specify a specific cipher (or set of ciphers) to be used rc = ldap_unbind( ld );
when negotiating with the server, use ldap_set_option()
to define a sequence of ciphers. For example, the fol- The following ciphers are attempted for the SSL handshake
lowing defines a sequence of three ciphers to be used by default, in the order shown.
when negotiating with the server. The first cipher that is
found to be in common with the server's list of ciphers is The export version:
used.
RC4_MD5_EXPORT
ldap_set_option( ld, RC2_MD5_EXPORT
LDAP_OPT_SSL_CIPHER,
(void \)LDAP_SSL_3DES_SHA_US
The nonexport version:
LDAP_SSL_RC4_MD5_US);

RC4_SHA_US
The following ciphers are defined in ldap.h: RC4_MD5_US
DES_SHA_US
3DES_SHA_US
RC4_MD5_EXPORT
RC2_MD5_EXPORT

ldap_unbind()—Perform an LDAP Unbind

Request

Chapter 18. Directory Services APIs 18-39

ldap_url_parse

Syntax Syntax
#include <ldap.h> #include <ldap.h>

int ldap_unbind(LDAP \ld) int ldap_unbind_s(LDAP \ld)

Library Name/Service Program: QDIRSRV/QGLDCLNT Library Name/Service Program: QDIRSRV/QGLDCLNT

Threadsafe: Yes Threadsafe: Yes

The ldap_unbind() function is used to end the connection to The ldap_unbind_s() function is used to end the connection
the LDAP server and free the resources contained in the ld to the LDAP server and free the resources contained in the
structure. ld structure.

ldap_unbind() is a synchronous request.

Parameters
Parameters ld (Input) An LDAP pointer returned by a previous call to
ldap_open().
ld (Input) An LDAP pointer returned by a previous call to
ldap_open().
Authorities and Locks
Authorities and Locks No OS/400 authority is required. All authority checking is
done by the LDAP server.
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Return Value
Return Value ld_errno
The ld_errno value of the ld structure is returned indi-
ld_errno cating a success or failure condition. See “Error
The ld_errno value of the ld structure is returned indi- Conditions” for a description of the return values that
cating a success or failure condition. See “Error can be returned.
Conditions” for a description of the return values that
can be returned.
Error Conditions
Error Conditions If ldap_unbind_s() is not successful, ld_errno will be set to
indicate the error. See “LDAP Client API Error Conditions”
If ldap_unbind() is not successful, ld_errno will be set to on page 18-45 for a description of the possible values for the
indicate the error. See “LDAP Client API Error Conditions” ld_errno field.
on page 18-45 for a description of the possible values for the
ld_errno field.
Error Messages
Error Messages The following message may be sent from this function.

The following message may be sent from this function.

CPF3CF2 E Error(s) occurred during running of &1 API.

CPF3CF2 E Error(s) occurred during running of &1 API.

Related Information
Ÿ “ldap_bind()—Perform an LDAP Bind Request” on
Related Information
page 18-5
Ÿ “ldap_bind()—Perform an LDAP Bind Request” on
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
page 18-5
page 18-26
Ÿ “ldap_open()—Perform an LDAP Open Operation” on
page 18-26
ldap_url_parse()—Parse an LDAP URL
ldap_unbind_s()—Perform an LDAP
Unbind Request (Synchronous)

18-40 AS/400 System API Reference V4R4

 ldap_url_search

CPF3CF2 E Error(s) occurred during running of &1 API.

Syntax
#include <ldap.h> Usage Notes
1. LDAP URL Format
int ldap_url_parse(char \url,
LDAPURLDesc \\ludpp) The format of an LDAP URL is as follows:
ldap://hostport/dn[?attributes[?scope[?filter]]]

Library Name/Service Program: QDIRSRV/QGLDCLNT Where:

hostport A host name with an optional
Threadsafe: Yes ":portnumber"
dn The base distinguished name to be used
The ldap_url_parse() function is used to extract the various for an LDAP search operation.
components of the URL. The ldap_url_parse() breaks down attributes A list of attributes to be retrieved, sepa-
an LDAP URL passed in the url parameter into its compo- rated by commas.
nent pieces. scope One of these three strings: base (the
default), one, or sub.
If successful, an LDAP URL description is allocated and filled filter An LDAP search filter as used in a call to
in, and ludpp is set to point to it. ldap_search().
For example:
The ldap_free_urldesc should be called to free an LDAP
ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
URL description that was obtained from a call to
ldap_url_parse(). URLs that are wrapped in less than and greater than
signs or are preceded by URL: are also accepted. For
example:
Parameters
URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
url (Input) A pointer to a URL string.
<URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich>
ludpp
(Output) A pointer to the LDAP URL description. 2. LDAPURLDesc Format
The LDAPURLDesc structure as defined in the ldap.h
Authorities and Locks header file is as follows:
No OS/400 authority is required. typedef struct ldap_url_desc
{
char \lud_host; /\ LDAP host to contact \/
int lud_port; /\ Port on host \/
Return Value char \lud_dn; /\ Base for search \/
char \\lud_attrs; /\ NULL-terminate list of attributes \/
[LDAP_SUCCESS] int lud_scope; /\ A valid LDAP_SCOPE_... value \/
The ldap_url_parse() function completed successfully. char \lud_filter; /\ LDAP search filter \/
char \lud_string; /\ For internal use only \/
} LDAPURLDesc;

Error Conditions
The ldap_url_parse() function did not complete successfully. Related Information
One of the following error codes is returned:
Ÿ “ldap_free_urldesc()—Free an LDAP URL Description”
[LDAP_URL_ERR_BADSCOPE] on page 18-14
The URL scope string is not valid.
Ÿ “ldap_is_ldap_url()—Verify LDAP URL” on page 18-19
[LDAP_URL_ERR_MEM]
ldap_url_parse() cannot allocate memory. Ÿ “ldap_url_search()—Perform an LDAP URL Search
[LDAP_URL_ERR_NODN] Operation”
The URL has no distinguished name, which is Ÿ “ldap_url_search_s()—Perform an LDAP URL Search
required. Operation (Synchronous)” on page 18-42
[LDAP_URL_ERR_NOTLDAP]
The URL does not begin with "ldap://" Ÿ “ldap_url_search_st()—Perform an LDAP URL Search
Operation (Timed Synchronous)” on page 18-43

Error Messages
The following message may be sent from this function.
ldap_url_search()—Perform an LDAP URL
Search Operation

Chapter 18. Directory Services APIs 18-41

ldap_url_search_s

CPF3CF2 E Error(s) occurred during running of &1 API.

Syntax
#include <ldap.h> Usage Notes
1. LDAP URL Format
int ldap_url_search(LDAP \ld,
char \url, The format of an LDAP URL is as follows:
int attrsonly) ldap://hostport/dn[?attributes[?scope[?filter]]]

Library Name/Service Program: QDIRSRV/QGLDCLNT Where:

hostport A host name with an optional
Threadsafe: Yes :portnumber.
dn The base distinguished name to be used
The ldap_url_search() function initiates an asynchronous for an LDAP search operation.
LDAP search based on the contents of the url parameter attributes A list of attributes to be retrieved, sepa-
string. This function acts like ldap_search() except that the rated by commas.
search parameters are pulled out of the URL. The result of scope One of these three strings: base (the
the operation can be obtained by a subsequent call to default), one, or sub.
ldap_result(). filter An LDAP search filter as used in a call to
ldap_search().
For example:
Parameters ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
ld (Input) An LDAP pointer returned by a previous call to URLs that are wrapped in less than and greater than
ldap_open() or ldap_init(). signs or are preceded by URL: are also accepted. For
url (Input) A pointer to the URL string. example:

URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
attrsonly
(Input) Attribute information. attrsonly should be set to 1 <URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich>
to request attribute types only. Set to 0 to request both
attributes types and attribute values. 2. hostport Processing
For search operations, if hostport is omitted, host and
Authorities and Locks port for the current connection are used. If hostport is
specified, and is different from the host and port combi-
No OS/400 authority is required. All authority checking is nation used for the current connection, the search is
done by the LDAP server. directed to hostport, instead of using the current con-
nection. In this case, the underlying referral mechanism
is used to bind to hostport.
Return Value
3. Search Filter Processing
LDAP message identifier
ldap_url_search() request was sent. The result of the If the LDAP URL does not contain a search filter, the
operation can be obtained by a subsequent call to filter defaults to objectClass=*.
ldap_result().
−1 ldap_url_search() was not successful. The ld_errno of
Related Information
the ld structure is set to indicate the error.
Ÿ “ldap_result()—Retrieve Result of an Asynchronous
LDAP Operation” on page 18-27
Error Conditions
Ÿ “ldap_search()—Perform an LDAP Search Operation” on
If ldap_url_search() is not successful, ld_errno will be set to page 18-29
indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the
ld_errno field. ldap_url_search_s()—Perform an LDAP
URL Search Operation (Synchronous)
Error Messages
The following message may be sent from this function.

18-42 AS/400 System API Reference V4R4

 ldap_url_search_st

Error Messages
Syntax
The following message may be sent from this function.
#include <ldap.h>
CPF3CF2 E Error(s) occurred during running of &1 API.
int ldap_url_search_s(LDAP \ld,
char \url,
int attrsonly, Usage Notes
LDAPMessage \\res) 1. LDAP URL Format

Library Name/Service Program: QDIRSRV/QGLDCLNT The format of an LDAP URL is as follows:

ldap://hostport/dn[?attributes[?scope[?filter]]]
Threadsafe: Yes
Where:
hostport A host name with an optional
The ldap_url_search_s() function is used to perform a syn- :portnumber.
chronous LDAP search based on the contents of the url dn The base distinguished name to be used
parameter string. for an LDAP search operation.
attributes A list of attributes to be retrieved, sepa-
This function acts like ldap_search_s() except that the rated by commas.
search parameters are pulled out of the URL. scope One of these three strings: base (the
default), one, or sub.
Parameters filter An LDAP search filter as used in a call to
ldap_search_s().
ld (Input) An LDAP pointer returned by a previous call to
For example:
ldap_open() or ldap_init().
ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
url (Input) A pointer to the URL string.
URLs that are wrapped in less than and greater than
attrsonly signs or are preceded by URL: are also accepted. For
(Input) Attribute information. attrsonly should be set to 1 example:
to request attribute types only. Set this parameter to 0
URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
to request both attributes types and attribute values.
<URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich>
res
(Output) The result of the search request. This result 2. hostport Processing
should be passed to the LDAP parsing functions.
For search operations, if hostport is omitted, host and
port for the current connection are used. If hostport is
Authorities and Locks specified, and is different from the host and port combi-
nation used for the current connection, the search is
No OS/400 authority is required. All authority checking is directed to hostport, instead of using the current con-
done by the LDAP server. nection. In this case, the underlying referral mechanism
is used to bind to hostport.
Return Value 3. Search Filter Processing
ld_errno If the LDAP URL does not contain a search filter, the
The ld_errno value of the ld structure is returned indi- filter defaults to objectClass=*.
cating a success or failure condition. See “Error
Conditions” for a description of the return values that
can be returned.
Related Information
Ÿ “ldap_search_s()—Perform an LDAP Search Operation
(Synchronous)” on page 18-30
Error Conditions
If ldap_url_search_s() is not successful, ld_errno will be set
to indicate the error. See “LDAP Client API Error Conditions” ldap_url_search_st()—Perform an LDAP
on page 18-45 for a description of the possible values for the URL Search Operation (Timed
ld_errno field. Synchronous)

Chapter 18. Directory Services APIs 18-43

ldap_value_free

Error Messages
Syntax
The following message may be sent from this function.
#include <sys/time.h>
#include <ldap.h> CPF3CF2 E Error(s) occurred during running of &1 API.

int ldap_url_search_st(LDAP \ld,

char \url, Usage Notes
int attrsonly, 1. LDAP URL Format
struct timeval \timeout,
LDAPMessage \\res) The format of an LDAP URL is as follows:
ldap://hostport/dn[?attributes[?scope[?filter]]]
Library Name/Service Program: QDIRSRV/QGLDCLNT Where:
Threadsafe: Yes hostport A host name with an optional
:portnumber.
dn The base distinguished name to be used
The ldap_url_search_st() function is used to perform a syn- for an LDAP search operation.
chronous LDAP URL search with a specified timeout. This attributes A list of attributes to be retrieved, sepa-
function acts like ldap_search_st() except that the search rated by commas.
parameters are pulled out of the URL. scope One of these three strings: base (the
default), one, or sub.
Parameters filter An LDAP search filter as used in a call to
ldap_search_st().
ld (Input) An LDAP pointer returned by a previous call to
For example:
ldap_open() or ldap_init().
ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
url (Input) A pointer to the URL string.
URLs that are wrapped in less than and greater than
attrsonly signs or are preceded by URL: are also accepted. For
(Input) Attribute information. attrsonly should be set to 1 example:
to request attribute types only. Set this parameter to 0
URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
to request both attributes types and attribute values.
<URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich>
timeout
(Input) A timeout value for a synchronous search. 2. hostport Processing
res For search operations, if hostport is omitted, host and
(Output) The result of the search request as defined in port for the current connection are used. If hostport is
ldap.h. This result should be passed to the LDAP specified, and is different from the host and port combi-
parsing functions. nation used for the current connection, the search is
directed to hostport, instead of using the current con-
nection. In this case, the underlying referral mechanism
Authorities and Locks is used to bind to hostport.
No OS/400 authority is required. All authority checking is 3. Search Filter Processing
done by the LDAP server. If the LDAP URL does not contain a search filter, the
filter defaults to objectClass=*.
Return Value
ld_errno Related Information
The ld_errno value of the ld structure is returned indi- Ÿ “ldap_search_st()—Perform an LDAP Search Operation
cating a success or failure condition. See “Error (Timed Synchronous)” on page 18-31
Conditions” for a description of the return values that
can be returned.
ldap_value_free()—Free Memory Allocated
Error Conditions by ldap_get_values()
If ldap_url_search_st() is not successful, ld_errno will be set
to indicate the error. See “LDAP Client API Error Conditions”
on page 18-45 for a description of the possible values for the
ld_errno field.

18-44 AS/400 System API Reference V4R4

 LDAP Client API Error Conditions

The ldap_value_free_len() function frees the memory allo-

Syntax cated by the ldap_get_values_len() function.

#include <ldap.h>
Parameters
void ldap_value_free(char \\vals)
vals
Library Name/Service Program: QDIRSRV/QGLDCLNT (Input) A pointer to a null-terminated array of pointers to
berval structures, as returned by ldap_get_values_len().
Threadsafe: Yes See the Usage Notes for details of this parameter.

The ldap_value_free() function frees the memory allocated Authorities and Locks
by the ldap_get_values() function.
No OS/400 authority is required. All authority checking is
done by the LDAP server.
Parameters
vals Return Value
(Input) A pointer to a null-terminated array of attribute
values, as returned by ldap_get_values(). None

Authorities and Locks Error Conditions

No OS/400 authority is required. All authority checking is None
done by the LDAP server.
Error Messages
Return Value
The following message may be sent from this function.
None CPF3CF2 E Error(s) occurred during running of &1 API.

Error Conditions Usage Notes

None 1. Berval Structure
The berval structure is defined as follows:
Error Messages
typedef struct berval {
The following message may be sent from this function. unsigned long bv_len;
CPF3CF2 E Error(s) occurred during running of &1 API. char \bv_val;
};

Related Information
Related Information
Ÿ “ldap_get_values()—Retrieve a Set of Attribute Values
Ÿ “ldap_get_values_len()—Retrieve a Set of Binary Attri-
from an Entry” on page 18-17
bute Values” on page 18-17

ldap_value_free_len()—Free Memory
LDAP Client API Error Conditions
Allocated by ldap_get_values_len()
When most LDAP APIs fail to complete successfully,
ld_errno usually indicates one of the following errors. Under
Syntax some conditions, ld_errno could indicate an error other than
#include <ldap.h> those listed here.
[LDAP_ALIAS_DEREF_PROBLEM]
void ldap_value_free_len(struct berval \\vals)
A problem was encountered when derefer-
Library Name/Service Program: QDIRSRV/QGLDCLNT encing an alias.
[LDAP_ALIAS_PROBLEM]
Threadsafe: Yes An alias in the directory points to a nonex-
istent entry.

Chapter 18. Directory Services APIs 18-45

LDAP Client API Error Conditions

[LDAP_ALREADY_EXISTS] [LDAP_NO_OBJECT_CLASS_MODS]
The entry already exists. Object class modifications are not allowed.
[LDAP_AUTH_UNKNOWN] [LDAP_NO_SUCH_ATTRIBUTE]
The authentication method specified to The attribute type specified does not exist in
ldap_bind() is not known. the entry.
[LDAP_BUSY] [LDAP_NO_SUCH_OBJECT]
The directory system agent is busy. The specified object does not exist in the
[LDAP_COMPARE_FALSE] directory.
A compare operation returned false. [LDAP_NOT_ALLOWED_ON_NONLEAF]
[LDAP_COMPARE_TRUE] The operation is not allowed on a nonleaf
A compare operation returned true. object.
[LDAP_CONSTRAINT_VIOLATION] [LDAP_NOT_ALLOWED_ON_RDN]
An attribute value specified violates some con- The operation is not allowed on a relative dis-
straint (for example, a postal address has too tinguished name.
many lines, or a line that is too long). [LDAP_OBJECT_CLASS_VIOLATION]
[LDAP_DECODING_ERROR] An object class violation occurred (for
An error was encountered while the API was example, a "must" attribute was missing from
decoding a result from the LDAP server. the entry).
[LDAP_ENCODING_ERROR] [LDAP_OPERATIONS_ERROR]
An error was encountered while the API was An operations error occurred.
encoding parameters to send to the LDAP [LDAP_OTHER]
server. An unknown error occurred.
[LDAP_FILTER_ERROR] [LDAP_PARAM_ERROR]
A filter that is not valid was supplied to An LDAP API was called with a bad param-
ldap_search() (for example, unbalanced eter (for example, a NULL ld pointer).
parentheses). [LDAP_PARTIAL_RESULTS]
[LDAP_INAPPROPRIATE_AUTH] Partial results only returned.
Inappropriate authentication was specified (for [LDAP_PROTOCOL_ERROR]
example, LDAP_AUTH_SIMPLE was specified A protocol violation was detected.
and the entry does not have a user password [LDAP_SERVER_DOWN]
attribute). The LDAP API cannot contact the LDAP
[LDAP_INAPPROPRIATE_MATCHING] server.
Filter type not supported for the specified attri- [LDAP_SIZELIMIT_EXCEEDED]
bute. An LDAP size limit was exceeded.
[LDAP_INSUFFICIENT_ACCESS] [LDAP_STRONG_AUTH_NOT_SUPPORTED]
The user has insufficient access to perform The LDAP server does not support strong
the operation. authentication.
[LDAP_INVALID_CREDENTIALS] [LDAP_STRONG_AUTH_REQUIRED]
Credentials that are not valid were presented Strong authentication is required for the oper-
(for example, the wrong password). ation.
[LDAP_INVALID_DN_SYNTAX] [LDAP_SUCCESS]
A distinguished name was specified that is The request was successful.
syntactically not valid. [LDAP_TIMELIMIT_EXCEEDED]
[LDAP_INVALID_SYNTAX] An LDAP time limit was exceeded.
An attribute value was specified that is not [LDAP_TIMEOUT]
valid. A time limit was exceeded while API was
[LDAP_IS_LEAF] waiting for a result.
The object specified is a leaf. [LDAP_TYPE_OR_VALUE_EXISTS]
[LDAP_LOCAL_ERROR] An attribute type or attribute value specified
Some local error occurred. This usually indi- already exists in the entry.
cates that either the LDAP support (OS/400 [LDAP_UNAVAILABLE]
option 32) is not installed on the system, or a The directory system agent is unavailable.
malloc() operation has failed. [LDAP_UNDEFINED_TYPE]
[LDAP_LOOP_DETECT] The attribute type specified is not valid.
A loop was detected. [LDAP_UNWILLING_TO_PERFORM]
[LDAP_NAMING_VIOLATION] The directory system agent is unwilling to
A naming violation occurred. perform the operation.
[LDAP_NO_MEMORY]
A memory allocation (for example, a malloc()
call) failed in an LDAP API.

18-46 AS/400 System API Reference V4R4

 Change Directory Server Attributes (QgldChgDirSvrA) API

Chapter 19. Directory Services Configuration APIs

Retrieve Directory Server Attributes
Directory Services Configuration (QgldRtvDirSvrA) retrieves information about
APIs—Introduction the directory server configuration.
Synchronize System Distribution Directory to LDAP
This chapter describes the administration and configuration
(QGLDSSDD) exports system distribution
APIs for the OS/400 Directory Services feature. These APIs
directory entries to an LDAP directory and
may be used to:
keeps the LDAP directory synchronized with
Ÿ Create, modify, and view the configuration of the direc- changes made in the system distribution direc-
tory server residing on your AS/400. tory.
Ÿ Define where AS/400 objects (user profiles, and so forth)
are published in the directory. The directory may reside Terminology
on a directory server on this or another system.
Ÿ Exchange data with an LDAP server, or populate your The following terms are used in various APIs within this
directory, using LDAP Data Interchange Format (LDIF) chapter:
files.
Distinguished name (DN). The directory name that
Ÿ Synchronize a directory with the contents of the system uniquely identifies an object within the directory.
distribution directory.
Master server. The primary copy of the directory data.
The first three tasks can also be accomplished through the
AS/400 Operations Navigator. The directory server appears Replica server. The read-only directory data that was
under TCP/IP servers (Network, Servers, TCP/IP). Informa- copied from the master server to other servers.
tion about where to publish AS/400 objects is available
through the Directory Services page of the AS/400 system Suffix. The directory name for the starting point of a direc-
properties. tory information tree.

Refer to the articles about "Administering AS/400 Directory The detailed API descriptions are presented in alphabetical
Services" in the AS/400 Information Center for more informa- order.
tion on managing the LDAP directory server. The AS/400
Information Center is located at the following URL:
http://publib.boulder.ibm.com/html/as4ðð/infocenter.html Change Directory Server Attributes
(QgldChgDirSvrA) API
The following APIs are provided for server administration and
configuration:
Change Directory Server Attributes (QgldChgDirSvrA) Required Parameter Group:
changes the directory server configuration.
Configure Directory Server 1 Input data Input Char(*)
(QgldCfgDirSvr) creates the initial directory 2 Length of input data Input Binary(4)
3 Format name Input Char(8)
server configuration.
4 Error code I/O Char(*)
Export LDIF File
(QgldExportLdif) exports the directory server Library Name/Service Program: QDIRSRV/QGLDUAPI
contents to a Lightweight Directory Access
Protocol Data Interchange Format (LDIF) file. Threadsafe: No
Import LDIF File
(QgldImportLdif) imports directory server data
from a Lightweight Directory Access Protocol The Change Directory Server Attributes (QgldChgDirSvrA)
Data Interchange Format (LDIF) file. API changes the directory server configuration. It can be
List Directory Server Attributes used to change the following server properties:
(QgldLstDirSvrA) retrieves a list of directory Ÿ General server properties
server attributes including the suffixes present Ÿ Suffixes served by this server
on the server and attribute indexes maintained Ÿ Encrypted connection configuration. The Secure Sockets
by the underlying database. Layer (SSL) is used for encrypted communication.
Publish Directory Object Ÿ Performance settings
(QgldPubDirObj) publishes objects to the
directory server.
Authorities and Locks

 Copyright IBM Corp. 1998, 1999 19-1

 Change Directory Server Attributes (QgldChgDirSvrA) API

Special Authorities
Offset
*ALLOBJ and *IOSYSCFG special authority is
required to use this API. Dec Hex Type Field
20 14 BINARY(4) Current cipher protocols

Required Parameter Group 24 18 BINARY(4) Search time limit

28 1C BINARY(4) Search size limit
Input data
INPUT; CHAR(*) 32 20 BINARY(4) Maximum connections

A variable that contains the input data. See “Format of 36 24 BINARY(4) Reserved
Input Data” for a description of the data associated with 40 28 BINARY(4) Referral port
a specific format name. 44 2C BINARY(4) Password format
Length of input data 48 30 BINARY(4) Offset to referral server
INPUT; BINARY(4) 52 34 BINARY(4) Length of referral server
The length of the input data area. 56 38 BINARY(4) Offset to administrator DN
Format name 60 3C BINARY(4) Length of administrator
INPUT; CHAR(8) DN

The format name identifying the type of information to be 64 40 BINARY(4) Offset to administrator
password
changed. The possible format names follow:
68 48 BINARY(4) Length of administrator
CSVR0100 Basic server configuration password
CSVR0200 Add or remove suffixes from this server
72 48 BINARY(4) Offset to update DN
CSVR0300 Add, change, or remove directory
indexing rules 76 4C BINARY(4) Length of update DN
CSVR0400 Add or change the attributes for pub- 80 50 BINARY(4) Offset to update pass-
lishing users in an LDAP directory. word
| CSVR0500 Add or change the network server pub- 84 54 BINARY(4) Length of update pass-
| lishing attributes associated with the word
| LDAP server.
92 5C BINARY(4) Offset to key ring file
See “Format of Input Data” for a description of these 96 60 BINARY(4) Length of key ring file
formats.
100 64 BINARY(4) Offset to database path
Error code 104 64 BINARY(4) Length of database path
I/O; CHAR(*)
108 68 BINARY(4) Reserved
The structure in which to return error information. For
CHAR(*) Referral server
the format of the structure, see “Error Code Parameter”
on page 2-6. CHAR(*) Administrator DN
CHAR(*) Administrator password

Format of Input Data CHAR(*) Update DN

CHAR(*) Update password
For details about the format of the input data, see the fol-
CHAR(*) Key ring file
lowing sections. For details about the fields in each format,
see “Field Descriptions” on page 19-4. CHAR(*) Database path

CSVR0100 Format: This format is used to change basic CSVR0200 Format: This format is used to add or remove
server configuration information. suffixes from the server. The input data consists of a header
and a series of change entries. The header identifies the
Offset number of suffixes to be added or removed. Each change
Dec Hex Type Field entry identifies a suffix and the action to be performed (add
or remove the suffix).
0 0 BINARY(4) Read only
4 4 BINARY(4) Server is replica Note: Removing a suffix from a server will result in the loss
of all directory entries with that suffix.
8 8 BINARY(4) Security
12 C BINARY(4) Nonencrypted port Offset
number
Dec Hex Type Field
16 10 BINARY(4) Encrypted port number
0 0 BINARY(4) Offset to change entry

19-2 AS/400 System API Reference V4R4

 Change Directory Server Attributes (QgldChgDirSvrA) API

Offset CSVR0400 Format: This format is used to set the attri-

butes for publishing users in an LDAP directory. User infor-
Dec Hex Type Field
mation from the System Distribution Directory (SDD) can be
4 4 BINARY(4) Number of change entries published to an LDAP server by the Synchronize System
Change entry Distribution Directory to LDAP (QGLDSSDD) API and from
AS/400 Operations Navigator. The publishing attributes
Suffix change entries:
define how to publish user information.
0 0 BINARY(4) Displacement to next
entry
Offset
4 4 BINARY(4) Action
Dec Hex Type Field
8 8 BINARY(4) Displacement to suffix
0 0 BINARY(4) Offset to the server name
12 C BINARY(4) Length of suffix
4 4 BINARY(4) Length of server name
CHAR(*) Suffix
8 8 BINARY(4) LDAP port number
12 C BINARY(4) Connection type
CSVR0300 Format: This format is used to add, change,
16 10 BINARY(4) Offset to parent distin-
or remove directory indexes. Creating indexes for one or
guished name
more attributes allows for faster retrieval of directory entries
based on those attributes. The input data consists of a 20 14 BINARY(4) Length of parent distin-
header and a series of change entries. The header identifies guished name
the number of indexes to be added, changed, or removed. 24 18 BINARY(4) Reserved
Each change entry identifies an attribute and the action to be CHAR(*) Server name
performed (add, change, or remove the indexes).
CHAR(*) Parent distinguished
name
Offset
Dec Hex Type Field
| CSVR0500 Format: This format is used to set the
0 0 BINARY(4) Offset to change entry | network server publishing attributes associated with the
4 4 BINARY(4) Number of change entries | server.
Change entries
| Offset
Add or change attribute index entries:
| Dec Hex Type Field
0 0 BINARY(4) Displacement to next
entry | 0 0 BINARY(4) Offset to change entries

4 4 BINARY(4) Action | 4 4 BINARY(4) Number of change entries

8 8 BINARY(4) Displacement to attribute | Change entries

name | Add or change publishing agent change entries:
12 C BINARY(4) Length of attribute name | 0 0 BINARY(4) Displacement to next
16 10 BINARY(4) Index type | entry

20 14 BINARY(4) Reserved | 4 4 BINARY(4) Action

CHAR(*) Attribute name | 8 8 BINARY(4) Displacement to pub-

| lishing agent name
Delete attribute index entries:
| 12 C BINARY(4) Length of publishing
0 0 BINARY(4) Displacement to next | agent name
entry
| 16 10 BINARY(4) Displacement to server
4 4 BINARY(4) Action | name
8 8 BINARY(4) Displacement to attribute | 20 14 BINARY(4) Length of server name
name
| 24 18 BINARY(4) Displacement to bind DN
12 C BINARY(4) Length of attribute name
| 28 1C BINARY(4) Length of bind DN
16 10 BINARY(4) Reserved
| 32 20 BINARY(4) Displacement to bind cre-
CHAR(*) Attribute name | dentials
| 36 24 BINARY(4) Length of bind credentials
| 40 28 BINARY(4) LDAP port number
| 44 2C BINARY(4) Connection type

Chapter 19. Directory Services Configuration APIs 19-3

 Change Directory Server Attributes (QgldChgDirSvrA) API

fied in UCS-2 (CCSID 13488). The following special value

| Offset
may be specified:
| Dec Hex Type Field
*DEFAULT Specifies the index types to be created for
| 48 30 BINARY(4) Displacement to parent
those attributes that have no explicit rules
| distinguished name
defined.
| 52 34 BINARY(4) Length of parent distin-
| guished name Note: The *DEFAULT attribute entry may be removed or
added. Adding or removing *DEFAULT attribute is equivalent
| 56 38 BINARY(4) Disable publishing agent
to not creating any indexes, or creating indexes for all attri-
| 60 3C BINARY(4) Reserved butes, depending on the index types specified.
| CHAR(*) Publishing agent name
| Bind credentials. The password used when connecting to
| CHAR(*) Server name | the directory server using the bind DN. When either the bind
| CHAR(*) Bind DN | DN or the bind credentials field is changed, both must be
| CHAR(*) Bind credentials | specified. This field is specified in UCS-2 (CCSID 13488).
| To leave the value unchanged, specify a length and displace-
| CHAR(*) Parent distinguished | ment to this field of zero.
| name
| Delete publishing agent change entries: | Bind DN. A distinguished name to use when publishing
| 0 0 BINARY(4) Displacement to next
| objects to the directory. When either the bind DN or the bind
| entry | credentials field is changed, both must be specified. This
| field is specified in UCS-2 (CCSID 13488). To leave the
| 4 4 BINARY(4) Action
| value unchanged, specify a length and displacement to this
| 8 8 BINARY(4) Displacement to pub- | field of zero.
| lishing agent name
| 12 C BINARY(4) Length of publishing | Change entry. A structure identifying a change to be made.
| agent name | The structure identifies the suffix, attribute, or publishing
| agent, and the operation to be performed (add, change, or
| 16 10 BINARY(4) Reserved
| delete).
| CHAR(*) Publishing agent name
Connection type. The type of connection to use to the
LDAP server. The following values may be specified:
Field Descriptions 1 Nonsecure
Action. The action to be performed for a given entry. The 2 Secured, using SSL
following values may be specified: | -1 The value remains the same

| 1 Add suffix, index rule, or publishing agent Current cipher protocols. The cipher protocols that the
| 2 Change index rule or publishing agent server will allow when using encrypted connections. The fol-
| 3 Remove suffix, index rule, or publishing agent lowing values may be specified:
| Note: Change is valid only for the CSVR0300 and -1 The value remains the same
| CSVR0500 formats.
Or, the sum of one or more of the following values:
Administrator DN. A distinguished name that has access to
0x0100 Triple Data Encryption Standard (DES) Secure
all objects in the directory. When either the administrator DN
Hash Algorithm (SHA) (U.S.)
or the administrator password field is changed, both must be
0x0200 DES SHA (U.S.)
specified. This field is specified in UCS-2 (CCSID 13488).
0x0400 Rivest Cipher 4 (RC4) SHA (U.S.)
To leave the value unchanged, specify a length and offset to
0x0800 RC4 Message Digest 5 (MD5) (U.S.)
this field of zero.
0x1000 RC2 MD5 (export)
Administrator password. The password used when con- 0x2000 RC4 MD5 (export)
necting to the directory server using the administrator DN.
Database path. The path to an existing library containing
When either the administrator DN or the administrator pass-
the directory database objects. This is an integrated file
word field is changed, both must be specified. This field is
system path name, for example, /QSYS.LIB/DIRSRV.LIB. By
specified in UCS-2 (CCSID 13488). To leave the value
changing this field, you make the current directory contents
unchanged, specify a length and offset to this field of zero.
inaccessible. By changing the field back to its original value,
Attribute index entries. The list of changes to be made to you restore the original directory contents. This field is spec-
the attribute indexes. ified in UCS-2 (CCSID 13488). To leave the value
unchanged, specify a length and offset to this field of zero.
Attribute name. The name of a directory object attribute for
which database indexes will be created. This field is speci-

19-4 AS/400 System API Reference V4R4

 Change Directory Server Attributes (QgldChgDirSvrA) API

| Disable publishing agent. Whether or not the publishing | LDAP port number. The LDAP server's TCP/IP port. The
| agent is disabled. The following values may be specified: | following value may be specified:
| 0 The publishing agent is enabled. | -1 The value remains the same
| 1 The publishing agent is disabled.
Length of administrator DN. The length, in Unicode char-
Displacement to attribute name. The displacement, in acters, of the administrator DN field.
bytes, from the start of the current entry to the attribute name
field. Length of administrator password. The length, in Unicode
characters, of the administrator password field.
| Displacement to bind credentials. The displacement, in
| bytes, from the start of the current entry to the bind creden- Length of attribute name. The length, in Unicode charac-
| tials field. ters, of the the attribute name field.

| Displacement to bind DN. The displacement, in bytes, from | Length of bind credentials. The length, in Unicode charac-
| the start of the current entry to the bind DN field. | ters, of the bind credentials field.

Displacement to next entry. The displacement, in bytes, | Length of bind DN. The length, in Unicode characters, of
from the start of the current entry to the next entry in the | the bind DN field.
input data.
Length of database path. The length, in Unicode charac-
Displacement to parent distinguished name. The dis- ters, of the database path field.
placement, in bytes, from the start of the current entry to the
Length of key ring file. The length, in Unicode characters,
parent distinguished name field.
of the key ring file field.
| Displacement to publishing agent name. The displace-
Length of parent distinguished name. The length, in
| ment, in bytes, from the start of the current entry to the pub-
Unicode characters, of the parent distinguished name field.
| lishing agent name field.
| Length of publishing agent name. The length, in Unicode
| Displacement to server name. The displacement, in bytes,
| characters, of the publishing agent name. The length can be
| from the start of the current entry to the server name field.
| at most 50 Unicode characters.
Displacement to suffix. The displacement, in bytes, from
Length of referral server. The length, in Unicode charac-
the start of the current entry to the suffix field.
ters, of the referral server name.
Encrypted port number. The port number to use for
Length of server name. The length, in Unicode characters,
encrypted connections. The standard port number for
of the server name field.
encrypted connections (SSL) is 636. Valid port numbers are
in the range 1 to 65535. The following special value may be
Length of suffix. The length, in Unicode characters, of the
specified:
the suffix field.
-1 The value of this field does not change.
Length of update DN. The length, in Unicode characters, of
Index type. The kind of database indexes that will be the update DN field.
created for an attribute. Creating database indexes improved
the performance of directory searches on those attributes. Length of update password. The length, in Unicode char-
The following values may be specified: acters, of the update password field.

0 No indexes will be maintained for the specified Maximum connections. The maximum number of simul-
attribute taneous connections that can be established with the server.
1 Equal The following special values may be specified:
Note: For a delete request, 0 must be specified for this -1 The value of this field does not change.
field. 0 Do not limit the number of connections.

Key ring file. The path name of the SSL key ring file. A Nonencrypted port number. The port number to be used
key ring file must be configured when using SSL. for nonencrypted connections. The standard port number is
389. Valid port numbers are in the range 1 to 65535. The
| Starting with V4R4M0, this field is ignored for format
following special value may be specified:
| CSVR0100. This field is specified in UCS-2 (CCSID 13488).
The following special value may be specified: -1 The value of this field does not change.

*NONE No value is specified. Number of change entries. The number of change entries
To leave the value unchanged, specify a length and offset to present in the input data.
this field of zero.

Chapter 19. Directory Services Configuration APIs 19-5

 Change Directory Server Attributes (QgldChgDirSvrA) API

Offset to administrator DN. The offset, in bytes, from the Server is replica field to make this server a replica. Valid
start of the input data area to the administrator DN field. port numbers are in the range 1 to 65535. The following
special value may be specified:
Offset to administrator password. The offset, in bytes,
from the start of the input data area to the administrator
0 No port number is returned as part of the
referral.
password field.
-1 The value of this field does not change.
Offset to change entry. The offset, in bytes, from the start
Referral server. The IP name or address of a server to
of the input data area to the the first change entry.
return to a client when a request is made for a directory
Offset to database path. The offset, in bytes, from the start object that does not reside on this server. The referral port
of the input data area to the database path field. and referral server are used together to form a referral URL.
The referral server and port fields must be configured when
Offset to key ring file. The offset, in bytes, from the start of changing the Server is a replica field to make this server a
the input data area to the key ring file field. replica. In this case, the referral is typically to the master
server. This field is specified in UCS-2 (CCSID 13488). To
Offset to parent distinguished name. The offset, in bytes, leave the value unchanged, specify a length and offset to this
from the start of the input data area to the parent distin- field of zero. The following special value may be specified:
guished name field.
*NONE No value is specified.
Offset to referral server. The offset, in bytes, from the start
Reserved. A reserved field. This field must be set to zero.
of the input data area to the referral server field.
Search size limit. The maximum number of entries that the
Offset to server name. The offset, in bytes, from the start
server will return for a given search request. The following
of the input data to the server name field.
special values may be specified:
Offset to suffix. The offset, in bytes, from the start of the -1 The value of this field does not change.
input data area to the suffix field. 0 Do not limit the number of entries returned.

Offset to update DN. The offset, in bytes, from the start of Search time limit. The maximum time, in seconds, that the
the input data area to the update DN field. server will spend performing a given search request. The
following special values may be specified:
Offset to update password. The offset, in bytes, from the
start of the input data area to the update password field. -1 The value of this field does not change.
0 Do not limit the search time.
Parent distinguished name. The parent distinguished
name for published objects. For example, if the parent dis- Security. Whether the server should use encrypted con-
tinguished name is "ou=rochester, o=ibm, c=us", a published nections. The following values may be specified:
directory object for user John Smith might be "cn=john smith, -1 The value does not change
ou=rochester, o=ibm, c=us". This field is specified in UCS-2 1 Allow nonencrypted connections only
| (CCSID 13488). To leave the value unchanged, specify a 2 Allow encrypted connections only
| length and offset to this field of zero. 3 Allow both encrypted and nonencrypted con-
nections
| Publishing agent name. The agent that will publish infor-
| mation to a directory server and parent distinguished name. Server is replica. Whether the server is a master server or
| This field is specified in UCS-2 (CCSID 13488). a replica server. When this field is changed to make the
server a replica, the update DN, update password, and
Read only. Whether the directory server will allow updates
referral fields must be specified. The following values may
to be made to the directory contents. The following values
be specified:
may be specified:
-1 The value of this field does not change.
-1 The value of this field does not change.
0 The server is a master for the directory suf-
0 Places the directory server into update mode
fixes present on the server.
to allow directory updates. This is the normal
1 The server is a replica server for the directory
mode of operation.
suffixes present on the server.
1 Places the directory server into read-only
mode. Server name. The name of the server. This field is speci-
| fied in UCS-2 (CCSID 13488). To leave the value
Referral port. An optional port number to be returned to a
| unchanged, specify a length and offset to this field of zero.
client when a request is made for a directory object that does
not reside on this server. The referral port and referral Suffix. The name of the directory suffix to be added or
server together are used to form a referral URL. The referral removed from the server. This field is specified in UCS-2
server and port fields must be configured when changing the (CCSID 13488).

19-6 AS/400 System API Reference V4R4

 Configure Directory Server (QgldCfgDirSvr) API

Suffix change entries. The list of suffixes to be added or GLD020B E

deleted. Referral server name not valid.
GLD020D E
Update DN. The distinguished name that the master server Index rule already defined for attribute.
must use when propagating directory updates to this replica GLD020E E
server. This field may be specified only when the server is a Index rule not found for attribute.
replica. When either the update DN or the update password GLD0211 E Value &1 specified at offset &2 in input format
field is changed, both must be specified. This field is speci- &3 is not valid.
fied in UCS-2 (CCSID 13488). The following special value GLD0212 E Field &1 required when server is using SSL.
may be specified: GLD0215 E Directory Services server has not been config-
*NONE No value is specified. ured.
GLD0217 E A value was specified in list entry &1 that is not
To leave the value unchanged, specify a length and offset to
valid. Reason code &2.
this field of zero.
GLD0219 E Administrator DN and password both required.
GLD021A E
Update password. The password used when connecting to
Field not allowed when server is not a replica.
this server using the update DN. This field may be specified
GLD021B E
only when the server is a replica. When either the update
Field is required when server is a replica.
DN or the update password field is changed, both must be
GLD021C E
specified. This field is specified in UCS-2 (CCSID 13488).
The caller of the API must have *ALLOBJ and
To leave the value unchanged, specify a length and offset to
*IOSYSCFG special authority to configure the
this field of zero. The following special value may be speci-
server.
fied:
GLD021D E
*NONE No value is specified. Error occurred when processing the input list of
entries.
Error Messages GLD021E E
&1 password is not valid.
CPF2209 E Library &1 not found. GLD0221 E Offset &1 specified in input data is not valid.
CPF24B4 E Severe error while addressing parameter list. GLD0222 E Length &1 specified in input data is not valid.
CPF3C17 E GLD0223 E Database path not valid.
Error occurred with input data parameter. GLD0224 E &1 is not a valid key ring file.
CPF3C1D E GLD0227 E Distinguished names cannot be modified while
Length specified in parameter &1 not valid. the server is active.
CPF3C1E E GLD0229 E Validation list not found.
Required parameter &1 omitted.
CPF3C21 E
Format name &1 is not valid.
Configure Directory Server
CPF3C39 E
Value for reserved field not valid.
(QgldCfgDirSvr) API
CPF3C90 E
Literal value cannot be changed.
CPF3CF1 E Required Parameter Group:
Error code parameter not valid.
1 Input data Input Char(*)
CPF3CF2 E 2 Length of input data Input Binary(4)
Error(s) occurred during running of &1 API. 3 Format name Input Char(8)
CPF9872 E Program or service program &1 in library &2 4 Error code I/O Char(*)
ended. Reason code &3.
CPFA0A9 E Library Name/Service Program: QDIRSRV/QGLDUAPI
Object not found.
CPFA0DB E Threadsafe: No
Object name not a QSYS object.
CPFA314 E Memory allocation error. The Configure Directory Server (QgldCfgDirSvr) API creates
GLD0204 E Attribute name not valid. the initial directory server configuration. This includes identi-
GLD0205 E Administrator DN not valid. fying the library that will contain the underlying database
GLD0208 E Key ring file name not valid. objects, the administrator of the server, and the initial set of
GLD0209 E Update DN not valid. suffixes to be present on the server.
GLD020A E
Suffix not valid.
Authorities and Locks

Chapter 19. Directory Services Configuration APIs 19-7

Configure Directory Server (QgldCfgDirSvr) API

Special Authorities
Offset
The caller must have *ALLOBJ and
*IOSYSCFG special authority. Dec Hex Type Field
32 20 BINARY(4) Reserved

Required Parameter Group CHAR(*) Database path

CHAR(*) Administrator DN
Input data
INPUT; CHAR(*) CHAR(*) Administrator password

Data that describes the desired directory server Suffixes:

configuration. The content and format of this structure 0 0 BINARY(4) Displacement to next
are determined by the format name. See “Format of suffix
Input Data” for a description of these formats. 4 4 BINARY(4) Displacement to suffix
name
Length of input data
INPUT; BINARY(4) 8 8 BINARY(4) Length of suffix name

The length of the input data structure. CHAR(*) Suffix name

Format name
INPUT; CHAR(8) Field Descriptions
The content and format of the input configuration data.
The possible format names follow:
Administrator DN. The distinguished name of a directory
CFGD0100 Configure Directory Server. object that has access to all objects in the directory. This
field is specified in UCS-2 (CCSID 13488).
See “Format of Input Data” for a description of these
formats. Administrator password. The password used when you
connect to the directory as the administrator. This field is
Error code
specified in UCS-2 (CCSID 13488).
I/O; CHAR(*)
The structure in which to return error information. For Database path. The path to an existing library containing
the format of the structure, see “Error Code Parameter” the directory database objects. This is an integrated file
on page 2-6. system path name, for example, /QSYS.LIB/QDIRSRV.LIB.
This field is specified in UCS-2 (CCSID 13488).

Format of Input Data Displacement to next suffix. The displacement, in bytes,

from the start of the current suffix entry to the next suffix
For details about the format of the input data, see the fol- entry.
lowing sections. For details about the fields in each format,
see “Field Descriptions.” Displacement to suffix name. The displacement, in bytes,
from the start of the current suffix entry to the suffix name
CFGD0100 Format: This format is used to provide initial field.
configuration data about the directory server.
Length of administrator DN. The length, in Unicode char-
Offset acters, of the administrator DN
Dec Hex Type Field
Length of administrator password. The length, in Unicode
0 0 BINARY(4) Offset to database path characters, of the administrator password field.
4 4 BINARY(4) Length of database path
Length of database path. The length, in Unicode charac-
8 8 BINARY(4) Offset to administrator ters, of the database path field.
distinguished name (DN)
12 C BINARY(4) Length of administrator Length of suffix name. The length, in Unicode characters,
DN of the suffix name field.
16 10 BINARY(4) Offset to administrator
Number of suffixes. The number of suffixes present in the
password
suffix list.
20 14 BINARY(4) Length of administrator
password Offset to administrator DN. The offset, in bytes, from the
24 18 BINARY(4) Offset to suffixes start of the input data to the administrator DN field.
28 1C BINARY(4) Number of suffixes

19-8 AS/400 System API Reference V4R4

 Export LDIF File (QgldExportLdif) API

Offset to administrator password. The offset, in bytes,

from the start of the input data to the administrator password Required Parameter Group:
field.
1 Input data Input Char(*)
Offset to database path. The offset, in bytes, from the start 2 Length of input data Input Binary(4)
of the input data to the database path field. 3 Format name Input Char(8)
4 Error code I/O Char(*)
Offset to suffixes. The offset, in bytes, from the start of the
input data to the list of suffixes. Library Name/Service Program: QDIRSRV/QGLDUAPI

Reserved. A reserved field. This field must be set to zero. Threadsafe: No

Suffixes. The list of suffixes to be present on the server. At

least one must be present in the initial configuration. The Export LDIF File (QgldExportLdif) API exports the direc-
tory server contents to a Lightweight Directory Access Pro-
Suffix name. The distinguished name of the root of a direc- tocol Data Interchange Format (LDIF) file.
tory tree present on the server. This field is specified in
UCS-2 (CCSID 13488).
Authorities and Locks
Special Authorities
Error Messages The caller must have *ALLOBJ and
CPF2209 E Library &1 not found. *IOSYSCFG special authorities or provide the
CPF24B4 E Severe error while addressing parameter list. correct administrator DN and password.
CPF3C17 E Directory Authority
Error occurred with input data parameter. The caller must provide the administrator DN
CPF3C1D E and password if the caller does not have
Length specified in parameter &1 not valid. *ALLOBJ and *IOSYSCFG special authorities.
CPF3C1E E Object Authorities
Required parameter &1 omitted. The caller must have Execute (*X) authority to
CPF3C21 E each directory in the path name preceding the
Format name &1 is not valid. name of the LDIF file.
CPF3C90 E The caller must have Write (*W) authority to
Literal value cannot be changed. the LDIF file.
CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Required Parameter Group
Error(s) occurred during running of &1 API. Input data
CPF9872 E Program or service program &1 in library &2 INPUT; CHAR(*)
ended. Reason code &3.
Input data required to identify the LDIF file and the
CPFA0DB E
administrator name and password. The content and
Object name not a QSYS object.
format of this structure are determined by the format
CPFA314 E Memory allocation error.
name. See “Format of Input Data” on page 19-10 for a
GLD0205 E Administrator DN not valid.
description of these formats.
GLD020A E
Suffix not valid. Length of input data
GLD021C E INPUT; BINARY(4)
*ALLOBJ and *IOSYSCFG special authority
The length of the input data structure.
required.
GLD0223 E Database path not valid. Format name
GLD0228 E Validation list not created. INPUT; CHAR(8)
GLD022A E
The content and format of the input data. The possible
Server configuration cannot be modified while
format name follows:
the server is active.
LDIF0100 Export LDIF file.

See “Format of Input Data” on page 19-10 for a descrip-

Export LDIF File (QgldExportLdif) API
tion of this format.

Error code
I/O; CHAR(*)
The structure in which to return error information. For

Chapter 19. Directory Services Configuration APIs 19-9

Import LDIF File (QgldImportLdif) API

the format of the structure, see “Error Code Parameter” Offset to administrator DN. The offset, in bytes, from the
on page 2-6. start of the input data to the administrator DN field.

Offset to administrator password. The offset, in bytes,

Format of Input Data from the start of the input data to the administrator password
field.
For details about the format of the input data, see the fol-
lowing section. For details about the fields in each format, Offset to LDIF file. The offset, in bytes, from the start of the
see “Field Descriptions.” input data to the LDIF file field.

LDIF0100 Format Offset to subtree DN. The offset, in bytes, from the start of
the input data to the subtree DN field.
Offset
Subtree DN. The distinguished name (DN) of the root of a
Dec Hex Type Field
directory subtree to export to the LDIF file. This object, and
0 0 BINARY(4) Offset to LDIF file all descendant objects will be exported. To export the entire
4 4 BINARY(4) Length of LDIF file directory tree, specify 0 (zero) for the offset to subtree DN
and length of subtree DN fields. This field is specified in
8 8 BINARY(4) Offset to administrator DN
UCS-2 (CCSID 13488).
12 C BINARY(4) Length of administrator
DN
16 10 BINARY(4) Offset to administrator Error Messages
password CPF24B4 E Severe error while addressing parameter list.
20 14 BINARY(4) Length of administrator CPF3C14 E
password Starting position &1 and length &2 cause space
24 18 BINARY(4) Offset to subtree DN overflow.
CPF3C1D E
28 1C BINARY(4) Length of subtree DN
Length specified in parameter &1 not valid.
CHAR(*) LDIF file CPF3C21 E
CHAR(*) Administrator DN Format name &1 is not valid.
CPF3C90 E
CHAR(*) Administrator password
Literal value cannot be changed.
CHAR(*) Subtree DN GLD0202 E Administrator DN or password not correct.
GLD0213 E Error opening or creating file.
GLD0215 E Server has not been configured.
Field Descriptions GLD0218 E *ALLOBJ and *IOSYSCFG special authorities
required.
Administrator DN. The distinguished name of the server GLD022B E
administrator. This field is specified in UCS-2 (CCSID Cannot find object &1.
13488).

Administrator password. The password for the server

administrator. This field is specified in UCS-2 (CCSID Import LDIF File (QgldImportLdif) API
13488).

LDIF file. The integrated file system path name of the LDIF Required Parameter Group:
file to be used. This field is specified in UCS-2 (CCSID
13488). 1 Input data Input Char(*)
2 Length of input data Input Binary(4)
Length of administrator DN. The length, in Unicode char- 3 Format name Input Char(8)
acters, of the administrator DN field. 4 Error code I/O Char(*)

Length of administrator password. The length, in Unicode Library Name/Service Program: QDIRSRV/QGLDUAPI
characters, of the administrator password field.
Threadsafe: No
Length of LDIF file. The length, in Unicode characters, of
the LDIF file field. The Import LDIF File (QgldImportLdif) API imports directory
server data from a Lightweight Directory Access Protocol
Length of subtree DN. The length, in Unicode characters,
Data Interchange Format (LDIF) file.
of the subtree DN field.

19-10 AS/400 System API Reference V4R4

 Import LDIF File (QgldImportLdif) API

The Directory Services server must be stopped to use this

Offset
API. To stop the server, use the End TCP/IP Server
(ENDTCPSVR SVR(*DIRSRV)) command. Dec Hex Type Field
0 0 BINARY(4) Offset to LDIF file

Authorities and Locks 4 4 BINARY(4) Length of LDIF file

Special Authorities 8 8 BINARY(4) Offset to administrator DN

The caller must have *ALLOBJ and 12 C BINARY(4) Length of administrator
*IOSYSCFG special authorities or provide the DN
correct administrator DN and password. 16 10 BINARY(4) Offset to administrator
Directory Authority password
The caller must provide the administrator DN 20 14 BINARY(4) Length of administrator
and password if the caller does not have password
*ALLOBJ and *IOSYSCFG special authorities.
CHAR(*) LDIF file
Object Authorities
The caller must have Execute (*X) authority to CHAR(*) Administrator DN
each directory in the path name preceding the CHAR(*) Administrator password
name of the LDIF file.
The caller must have Read (*R) authority to
the LDIF file. Field Descriptions
Administrator DN. The distinguished name of the server
Required Parameter Group administrator. This field is specified in UCS-2 (CCSID
Input data 13488).
INPUT; CHAR(*)
Administrator password. The password for the server
Input data required to identify the LDIF file and the administrator. This field is specified in UCS-2 (CCSID
administrator name and password. The content and 13488).
format of this structure are determined by the format
name. See “Format of Input Data” for a description of LDIF file. The integrated file system path name of the LDIF
these formats. file to be used. This field is specified in UCS-2 (CCSID
13488).
Length of input data
INPUT; BINARY(4) Length of administrator DN. The length, in Unicode char-
The length of the input data structure. acters, of the administrator DN field.

Format name Length of administrator password. The length, in Unicode

INPUT; CHAR(8) characters, of the administrator password field.
The content and format of the input data. The possible Length of LDIF file. The length, in Unicode characters, of
format name follows: the LDIF file field.
LDIF0100 Import LDIF file.
Offset to administrator DN. The offset, in bytes, from the
See “Format of Input Data” for a description of these start of the input data to the administrator DN field.
formats.
Offset to administrator password. The offset, in bytes,
Error code from the start of the input data to the administrator password
I/O; CHAR(*) field.
The structure in which to return error information. For
Offset to LDIF file. The offset, in bytes, from the start of the
the format of the structure, see “Error Code Parameter”
input data to the LDIF file field.
on page 2-6.

Format of Input Data Error Messages

CPF24B4 E Severe error while addressing parameter list.
For details about the format of the input data, see the fol- CPF3C14 E
lowing section. For details about the fields in each format, Starting position &1 and length &2 cause space
see “Field Descriptions.” overflow.
CPF3C17 E
LDIF0100 Format Error occurred with input data parameter.

Chapter 19. Directory Services Configuration APIs 19-11

 List Directory Server Attributes (QgldLstDirSvrA) API

CPF3C1D E See “Format of Output Data” for a description of these

Length specified in parameter &1 not valid. formats.
CPF3C21 E
Format name
Format name &1 is not valid.
INPUT; CHAR(8)
CPF3C90 E
Literal value cannot be changed. The content and format of the data to be retrieved. The
GLD0125 E
Directory Services failed for reason code &4. possible format names follow:
GLD0202 E
Administrator DN or password not correct.
GLD0213 E
Error opening or creating file.
LSVR0200 Retrieve a list of suffixes on the server.
GLD0215 E
Server has not been configured.
LSVR0300 Retrieve a list of database indexes main-
tained by the server.
GLD0218 E
*ALLOBJ and *IOSYSCFG special authorities
required.
| LSVR0500 Retrieve a list of network server pub-
| lishing attributes associated with the
GLD0225 E &1 items added to directory, &2 items not
| LDAP server.
added.
GLD0226 E LDAP server is read-only. See “Format of Output Data” for a description of these
formats.

Error code
List Directory Server Attributes
I/O; CHAR(*)
(QgldLstDirSvrA) API
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Required Parameter Group: on page 2-6.

1 Qualified user space name Input Char(20)

2 Format name Input Char(8) Format of Output Data
3 Error code I/O Char(*)
The user space will contain:
Library Name/Service Program: QDIRSRV/QGLDUAPI Ÿ A user area

Threadsafe: No Ÿ A generic area

Ÿ A list data section:
The List Directory Server Attributes (QgldLstDirSvrA) API – LSVR0200
retrieves a list of directory server attributes including the fol- – LSVR0300
lowing:
| – LSVR0500
Ÿ Suffixes present on the server
Ÿ Attribute indexes maintained by the underlying database For details about the user area and generic header, see
| Ÿ Network server publishing attributes associated with the “User Space Format for List APIs” on page 2-4. For details
| LDAP server. about the remaining items, see the following sections. For
detailed descriptions of the fields in the list that is returned,
see “Field Descriptions” on page 19-13.
Authorities and Locks
List Space Authority When you retrieve list entry information from the list space,
*CHANGE do not use the entry size that is returned in the generic
| List Space Library Authority header. Instead, use the displacement to next entry field that
| *EXECUTE is returned in each list entry. If you do not use the displace-
List Space Lock ment to next entry field, the results may not be valid. For
An exclusive, no-read lock is obtained on the examples of how to process lists, see Appendix A,
list space. “Examples.”

LSVR0200 Format: The LSVR0200 format is used to

Required Parameter Group retrieve a list of the directory suffixes present on this server.
Qualified user space name
INPUT; CHAR(20) Offset

The user space that is to receive the created list. The Dec Hex Type Field
first 10 characters contain the user space name, and the 0 0 BINARY(4) Displacement to next
second 10 characters contain the name of the library entry
where the user space is located. The content and 4 4 BINARY(4) Displacement to suffix
format of this space is determined by the format name.

19-12 AS/400 System API Reference V4R4

 List Directory Server Attributes (QgldLstDirSvrA) API

Offset | Offset
Dec Hex Type Field | Dec Hex Type Field
8 8 BINARY(4) Length of suffix | CHAR(*) Bind DN
12 C BINARY(4) Reserved | CHAR(*) Parent distinguished
| name
CHAR(*) Suffix

LSVR0300 Format: The LSVR0300 format is used to Field Descriptions

retrieve information about database indexes maintained by
the server. The indexes are used to speed up retrieval of Attribute name. The name of a directory object attribute for
objects when a directory server client searches for specified which database indexes will be maintained. This field is
object attributes. specified in UCS-2 (CCSID 13488). The following special
value may also be returned:
Offset *DEFAULT The rules for this attribute apply to all attri-
Dec Hex Type Field butes for which no explicit rules have been
0 0 BINARY(4) Displacement to next defined.
entry
| Bind DN. A distinguished name to use when publishing
4 4 BINARY(4) Displacement to attribute | objects to the directory. This field is specified in UCS-2
name
| (CCSID 13488).
8 8 BINARY(4) Length of attribute name
12 C BINARY(4) Index type | Connection type. The type of connection to use to the
| LDAP server. The following values may be returned:
16 10 BINARY(4) Reserved
| 1 Nonsecure
CHAR(*) Attribute name
| 2 Secured, using SSL

| LSVR0500 Format: The LSVR0500 format is used to Displacement to attribute name. The displacement, in
| retrieve the network server publishing attributes associated bytes, from the start of the current entry to the attribute name
| with the server. field.

| Offset
| Displacement to bind DN. The displacement, in bytes, from
| the start of the current entry to the bind DN field.
| Dec Hex Type Field
| 0 0 BINARY(4) Displacement to next Displacement to next entry. The displacement, in bytes,
| entry from the start of the current entry to the next entry.
| 16 10 BINARY(4) Displacement to pub-
| Displacement to parent distinguished name. The dis-
| lishing agent name
| placement, in bytes, from the start of the current entry to the
| 12 C BINARY(4) Length of publishing | parent distinguished name field.
| agent name
| 16 10 BINARY(4) Displacement to server | Displacement to publishing agent name. The displace-
| name | ment, in bytes, from the start of the current entry to the pub-
| 20 14 BINARY(4) Length of server name
| lishing agent name field.

| 24 18 BINARY(4) Displacement to bind DN | Displacement to server name. The displacement, in bytes,

| 28 1C BINARY(4) Length of bind DN | from the start of the current entry to the server name field.
| 32 20 BINARY(4) LDAP port number Displacement to suffix. The displacement, in bytes, from
| 36 24 BINARY(4) Connection type the start of the current entry to the suffix.
| 40 28 BINARY(4) Displacement to parent
| distinguished name
Format name specified. The format name specified on the
call to this API.
| 44 2C BINARY(4) Length of parent distin-
| guished name Index type. The kind of database indexes that will be
| 48 30 BINARY(4) Publishing agent disabled created for an attribute. Creating database indexes improved
the performance of directory searches on those attributes.
| 52 34 BINARY(4) Reserved
The following values may be returned:
| CHAR(*) Publishing agent name
0 No indexes will be created for the attribute.
| CHAR(*) Server name
1 Equal

Chapter 19. Directory Services Configuration APIs 19-13

 Publish Directory Object (QgldPubDirObj) API

| LDAP port number. The LDAP server's TCP/IP port. GLD0215 E Server has not been configured.

Length of attribute name. The length, in Unicode charac-

ters, of the attribute name field.
| Publish Directory Object (QgldPubDirObj)
| Length of bind DN. The length, in Unicode characters, of | API
| the bind DN field.

| Length of parent distinguished name. The length, in | Required Parameter Group:

| Unicode characters, of the parent distinguished name field.
| 1 Input data Input Char(*)
| Length of publishing agent name. The length, in Unicode | 2 Length of input data Input Binary(4)
| characters, of the publishing agent name field. | 3 Format name Input Char(8)
| 4 Error code I/O Char(*)
| Length of server name. The length, in Unicode characters,
| of the server name field. | Library Name/Service Program: QSYS/QGLDPAPI

Length of suffix. The length, in Unicode characters, of the | Threadsafe: No

suffix field.
| The Publish Directory Object (QgldPubDirObj) API publishes
Length of update DN. The length, in Unicode characters, of
| objects to the directory server. It can be used to perform the
the update DN field.
| following publishing requests:
| Parent distinguished name. The parent distinguished | Ÿ Add an object to the directory.
| name to be used. This field is specified in UCS-2 (CCSID | Ÿ Delete an object from the directory.
| 13488). | Ÿ Change an object in the directory.
| Ÿ Change the relative distinguished name of an object in
| Publishing agent name. The agent that will publish infor- | the directory server.
| mation to a directory server and parent distinguished name.
| This field is specified in UCS-2 (CCSID 13488). | The Directory Services feature needs to be installed on your
| AS/400 to run this API. Directory Services is option 32 of the
| Publishing agent disabled. Whether or not the publishing | OS/400.
| agent is disabled. The configuration data still exists, but pub-
| lishing has been disabled for the publishing agent. The fol- | Before this API can be called, the Directory Services property
| lowing values may be returned: | page for the AS/400 must be configured. This can be done
| 0 The publishing agent is enabled. | from the AS/400 Operations Navigator or by using the
| 1 The publishing agent is disabled. | Change Directory Server Attributes (QgldChgDirSrvA) API.
| The directory server indicates the server to which objects will
Reserved. A reserved field. This field must be set to zero. | be published. The parent distinguished name, or publish
| point, indicates the suffix in the directory to which objects
| Server name. The name of the server. This field is speci- | will be published.
| fied in UCS-2 (CCSID 13488).

Suffix. The directory name for the starting point of a direc- | Authorities and Locks
tory information tree. This field is specified in UCS-2 (CCSID | Special Authorities
13488). | *ALLOBJ special authority is required to use
| this API.
Error Messages
CPF24B4 E Severe error while addressing parameter list. | Required Parameter Group
CPF3C1E E
| Input data
Required parameter &1 omitted.
| INPUT; CHAR(*)
CPF3C21 E
Format name &1 is not valid. | A variable that contains the input data. See “Format of
CPF3C90 E | Input Data” on page 19-15 for a description of the data
Literal value cannot be changed. | associated with a specific format name.
CPF3CF1 E
| Length of input data
Error code parameter not valid.
| INPUT; BINARY(4)
CPF3CF2 E
Error(s) occurred during running of &1 API. | The length of the input data area. The maximum value
CPF9872 E Program or service program &1 in library &2 | for this parameter is 16 776 704.
ended. Reason code &3.

19-14 AS/400 System API Reference V4R4

 Publish Directory Object (QgldPubDirObj) API

| Format name
| Offset
| INPUT; CHAR(8)
| Dec Hex Type Field
| The format name identifying the type of publishing
| request. The possible format names follow: | CHAR(*) Attribute name
| Attribute values:
| POBJ0100 Add an object to the directory server.
| POBJ0200 Delete an object from the directory server. | 0 0 BINARY(4) Displacement to next
| value
| POBJ0300 Change an object in the directory server.
| POBJ0400 Change the relative distinguished name of | 4 4 BINARY(4) Displacement to attribute
| an object in the directory server. | value
| 8 8 BINARY(4) Length of attribute value
| See “Format of Input Data” for a description of these
| formats. | 12 C CHAR(4) Reserved
| CHAR(*) Attribute value
| Error code
| I/O; CHAR(*)
| POBJ0200 Format: This format is used to delete an
| The structure in which to return error information. For | object from the directory server.
| the format of the structure, see “Error Code Parameter”
| on page 2-6.
| Offset
| Dec Hex Type Field
| Format of Input Data | 0 0 BINARY(4) Offset to publishing agent
| name
| For details about the format of the input data, see the fol-
| lowing sections. For details about the fields in each format, | 4 4 BINARY(4) Length of publishing
| see “Field Descriptions” on page 19-16. | agent name
| 8 8 BINARY(4) Offset to object RDN
| POBJ0100 Format: This format is used to add an object
| 12 C BINARY(4) Length of object RDN
| to the directory server.
| 16 10 BINARY(4) Delete directory subtree
| Offset | 20 14 CHAR(44) Reserved
| Dec Hex Type Field | CHAR(*) Publishing agent name
| 0 0 BINARY(4) Offset to publishing agent | CHAR(*) Object RDN
| name
| 4 4 BINARY(4) Length of publishing | POBJ0300 Format: This format is used to change an
| agent name | object in the directory server.
| 8 8 BINARY(4) Offset to object RDN
| 12 C BINARY(4) Length of object RDN | Offset

| 16 10 BINARY(4) Offset to attribute entries | Dec Hex Type Field

| 20 14 BINARY(4) Number of attribute | 0 0 BINARY(4) Offset to publishing agent

| entries | name

| 24 18 CHAR(40) Reserved | 4 4 BINARY(4) Length of publishing

| agent name
| CHAR(*) Publishing agent name
| 8 8 BINARY(4) Offset to object RDN
| CHAR(*) Object RDN
| 12 C BINARY(4) Length of object RDN
| Attribute entries:
| 16 10 BINARY(4) Offset to modification
| 0 0 BINARY(4) Displacement to next | entries
| entry
| 20 14 BINARY(4) Number of modification
| 4 4 BINARY(4) Displacement to attribute | entries
| name
| 24 18 BINARY(4) Add object if it does not
| 8 8 BINARY(4) Length of attribute name | exist
| 12 C BINARY(4) Displacement to attribute | 28 1C CHAR(36) Reserved
| values
| CHAR(*) Publishing agent name
| 16 10 BINARY(4) Number of attribute
| values | CHAR(*) Object RDN

| 20 14 BINARY(4) Attribute value data type | Modification entries:

| 24 18 CHAR(8) Reserved

Chapter 19. Directory Services Configuration APIs 19-15

 Publish Directory Object (QgldPubDirObj) API

| Offset | Offset
| Dec Hex Type Field | Dec Hex Type Field
| 0 0 BINARY(4) Displacement to next | CHAR(*) New object RDN
| entry
| 4 4 BINARY(4) Change type
| 8 8 BINARY(4) Displacement to attribute
| Field Descriptions
| entries
| Add object if it does not exist. Create the object if a
| 12 C BINARY(4) Number of attribute | request is made to modify an object that does not exist. The
| entries | following values may be specified:
| Attribute entries: | 0 Do not create the object if it does not exist.
| 0 0 BINARY(4) Displacement to next | 1 Create the object if it does not exist. All
| entry | required attributes for the object must be
| 4 4 BINARY(4) Displacement to attribute | specified on the API for the object to be suc-
| name | cessfully created.
| 8 8 BINARY(4) Length of attribute name
| Attribute name. The name of a directory object attribute.
| 12 C BINARY(4) Displacement to attribute | This field is specified in UCS-2 (CCSID 13488).
| values
| 16 10 BINARY(4) Number of attribute | Attribute value. The value of a directory object attribute.
| values
| Attribute value data type. The type of data for the attribute
| 20 14 BINARY(4) Attribute value data type | values. The following values may be specified:
| 24 18 CHAR(8) Reserved
| 1 The attribute values are specified in UCS-2
| CHAR(*) Attribute name | (CCSID 13488).
| Attribute values: | 2 The attribute values contain binary data.
| 3 The attribute values contain integer data.
| 0 0 BINARY(4) Displacement to next
| value
| 4 The attribute values contain boolean data.

| 4 4 BINARY(4) Displacement to attribute | Change type. The type of change being made to a directory
| value | object. The following values may be specified:
| 8 8 BINARY(4) Length of attribute value | 1 Add an attribute
| 12 C CHAR(4) Reserved | 2 Delete an attribute
| CHAR(*) Attribute value | 3 Replace an attribute
| 4 Add an attribute if it does not exist
| 5 Add an attribute value if it does not exist
| POBJ0400 Format: This format is used to change the
| relative distinguished name (RDN) of an object in the direc- | Delete directory subtree. The directory object and any
| tory server. | child directory objects should be deleted. The following
| values may be specified:
| Offset
| 0 Do not delete the directory subtree. Only the
| Dec Hex Type Field | directory object itself will be deleted.
| 0 0 BINARY(4) Offset to publishing agent | 1 Delete the directory subtree.
| name | 2 Delete the directory subtree. The root of the
| 4 4 BINARY(4) Length of publishing | subtree will not be deleted.
| agent name
| Delete old RDN. The old relative distinguished name (RDN)
| 8 8 BINARY(4) Offset to object RDN | of a directory object should be deleted. The following values
| 12 C BINARY(4) Length of object RDN | may be specified:
| 16 10 BINARY(4) Offset to new object RDN | 0 Do not delete the old RDN. The old RDN
| 20 14 BINARY(4) Length of new object | attribute value will be retained as an attribute
| RDN | of the object.
| 1 Delete the old RDN.
| 24 18 BINARY(4) Delete old RDN
| 28 1C CHAR(36) Reserved | Displacement to attribute entries. The displacement, in
| CHAR(*) Publishing agent name | bytes, from the start of the current entry to the attribute
| entries.
| CHAR(*) Object RDN

19-16 AS/400 System API Reference V4R4

 Retrieve Directory Server Attributes (QgldRtvDirSvr A) API

| Displacement to attribute name. The displacement, in | object DN to be published is 'CN=Bart, O=ACME Corp.,
| bytes, from the start of the current entry to the attribute name | C=US'.
| field.
| Offset to attribute entries. The offset, in bytes, from the
| Displacement to attribute value. The displacement, in | start of the input data area to the attribute entries.
| bytes, from the start of the current entry to the attribute value
| field. | Offset to modification entries. The offset, in bytes, from
| the start of the input data area to the modification entries.
| Displacement to attribute values. The displacement, in
| bytes, from the start of the current entry to the attribute | Offset to new object RDN. The offset, in bytes, from the
| values. | start of the input data area to the new object RDN field.

| Displacement to next entry. The displacement, in bytes, | Offset to object RDN. The offset, in bytes, from the start of
| from the start of the current entry to the next entry in the | the input data area to the object RDN field.
| input data.
| Offset to publishing agent name. The offset, in bytes,
| Displacement to next value. The displacement, in bytes, | from the start of the input data area to the publishing agent
| from the start of the current value to the next value in the | name field.
| input data.
| Publishing agent name. The agent making the publishing
| Length of attribute name. The length, in Unicode charac- | request. This determines where in the directory the object
| ters, of the attribute name field. | will be published. The publishing agent information must be
| configured using the QgldChgDirSvrA API before calling this
| Length of attribute value. The length of the attribute value | API. This field is specified in UCS-2 (CCSID 13488).
| field. If the attribute value is specified in UCS-2 (CCSID
| 13488), this is the length in Unicode characters. If the attri- | Reserved. A reserved field. This field must be set to binary
| bute value contains binary data, this is the length in bytes. If | zero.
| the attribute value contains integer or boolean data, this field
| must contain the value 4. | Error Messages
| Length of new object RDN. The length, in Unicode charac- | CPF24B4 E Severe error while addressing parameter list.
| ters, of the new object RDN field. | CPF3C17 E
| Error occurred with input data parameter.
| Length of object RDN. The length, in Unicode characters, | CPF3C1D E
| of the object RDN field. | Length specified in parameter &1 not valid.
| CPF3C1E E
| Length of publishing agent name. The length, in Unicode | Required parameter &1 omitted.
| characters, of the publishing agent name field. | CPF3C21 E
| Format name &1 is not valid.
| New object RDN. The new relative distinguished name
| CPF3C39 E
| (RDN) of the directory object. This field is specified in
| Value for reserved field not valid.
| UCS-2 (CCSID 13488).
| CPF3C90 E
| Number of attribute entries. The number of attribute | Literal value cannot be changed.
| entries. | CPF3CF1 E
| Error code parameter not valid.
| Number of attribute values. The number of attribute | CPF3CF2 E
| values. | Error(s) occurred during running of &1 API.
| CPF9872 E Program or service program &1 in library &2
| Number of modification entries. The number of modifica- | ended. Reason code &3.
| tion entries. | CPFA314 E Memory allocation error.
| CPFB802 E The caller of the API must have *ALLOBJ
| Object RDN. The relative distinguished name (RDN) of the | special authority.
| directory object being published. This name, combined with | CPFB803 E Unknown publishing agent &1.
| the publishing point specified during configuration, form a dis- | CPFB805 E Value specified in input data is not valid.
| tinguished name (DN). This field is specified in UCS-2
| (CCSID 13488). For example, if the publishing point is
| 'O=ACME Corp., C=US' and the object RDN is 'CN=Bart', the
Retrieve Directory Server Attributes
(QgldRtvDirSvrA) API

Chapter 19. Directory Services Configuration APIs 19-17

Retrieve Directory Server Attributes (QgldRtvDirSvr A) API

Format of Output Data

Required Parameter Group:
For details about the format of the output data, see the fol-
1 Receiver variable Output Char(*) lowing sections. For details about the fields in each format,
2 Length of receiver variable Input Binary(4) see “Field Descriptions” on page 19-19.
3 Format name Input Char(8)
4 Error code I/O Char(*) RSVR0100 Format: This format is used to retrieve basic
server configuration information.
Library Name/Service Program: QDIRSRV/QGLDUAPI

Threadsafe: No Offset
Dec Hex Type Field

The Retrieve Directory Server Attributes (QgldRtvDirSvrA) 0 0 BINARY(4) Bytes returned

API retrieves information about the directory server 4 4 BINARY(4) Bytes available
configuration. It can be used to retrieve information about: 8 8 BINARY(4) Version
Ÿ General server properties 12 C BINARY(4) Read only
Ÿ Encrypted communications configuration. The Secure 16 10 BINARY(4) Server is replica
Sockets Layer (SSL) is used for encrypted communica-
20 14 BINARY(4) Security
tions.
24 18 BINARY(4) Unencrypted port number
Ÿ Performance settings
28 1C BINARY(4) Encrypted port number
32 20 BINARY(4) Current cipher protocols
Authorities and Locks
36 24 BINARY(4) Installed cipher protocols
None. 40 28 BINARY(4) Search time limit
44 2C BINARY(4) Search size limit
Required Parameter Group 48 30 BINARY(4) Maximum connections
Receiver variable 52 34 BINARY(4) Reserved
OUTPUT; CHAR(*) 56 38 BINARY(4) Referral port
The variable to receive output data. See “Format of 60 3C BINARY(4) Password format
Output Data” for a description of the format of the output
64 40 BINARY(4) Offset to referral server
data associated with a specific format name.
68 44 BINARY(4) Length of referral server
Length of receiver variable
72 48 BINARY(4) Offset to administrator
INPUT; BINARY(4) distinguished name (DN)
The length of the receiver variable area. 76 4C BINARY(4) Length of administrator
DN
Format name
INPUT; CHAR(8) 80 50 BINARY(4) Offset to update DN

The format name identifying the type of information to be 84 54 BINARY(4) Length of update DN
retrieved. The possible format names follow: | 88 58 BINARY(4) Reserved

RSVR0100 Basic server configuration | 92 5C BINARY(4) Reserved

RSVR0400 Attributes for publishing users in an LDAP 96 60 BINARY(4) Offset to database path
directory 100 64 BINARY(4) Length of database path
See “Format of Output Data” for a description of these 104 68 BINARY(4) Reserved
formats. CHAR(*) Referral server
Error code CHAR(*) Administrator DN
I/O; CHAR(*) CHAR(*) Update DN
The structure in which to return error information. For CHAR(*) Database path
the format of the structure, see “Error Code Parameter”
on page 2-6.

19-18 AS/400 System API Reference V4R4

 Retrieve Directory Server Attributes (QgldRtvDirSvr A) API

RSVR0400 Format: This format is used to retrieve the Encrypted port number. The port number to use for
attributes for publishing users in an LDAP directory. User encrypted connections. The standard port number for
information from the system distribution directory can be pub- encrypted connections is 636.
lished to an LDAP server by the Synchronize System Distri-
bution Directory to LDAP (QGLDSSDD) API and from Installed cipher protocols. The cipher protocols installed
AS/400 Operations Navigator. The publishing attributes on the system. Refer to the current cipher protocols field for
define how to publish user information. a description of the values.

LDAP port number. The LDAP server's TCP/IP port.

Offset
Dec Hex Type Field Length of administrator DN. The length, in Unicode char-
acters, of the administrator DN field.
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available Length of database path. The length, in Unicode charac-
8 8 BINARY(4) Offset to the server name ters, of the database path field.
12 C BINARY(4) Length of server name Length of parent distinguished name. The length, in
16 10 BINARY(4) LDAP port number Unicode characters, of the parent distinguished name field.
20 14 BINARY(4) Connection type
Length of referral server. The length, in Unicode charac-
24 18 BINARY(4) Offset to parent distin- ters, of the referral server field.
guished name.
28 1C BINARY(4) Length of parent distin- Length of server name. The length, in Unicode characters,
guished name. of the server name field.
CHAR(*) Server name
Length of update DN. The length, in Unicode characters, of
CHAR(*) Parent distinguished the update DN field.
name.
Maximum connections. Returns the maximum number of
simultaneous connections that can be established with the
Field Descriptions server. The following special value may be specified:
0 Do not limit the number of connections.
Administrator DN. A distinguished name (DN) that has
access to all objects in the directory. This field is specified in Unencrypted port number. The port number to be used for
UCS-2 (CCSID 13488). unencrypted connections. The standard port number is 389.
Bytes available. The number of bytes of data available to Offset to administrator DN. The offset, in bytes, from the
be returned. All available data is returned if enough space is start of the receiver variable to the administrator DN field.
provided.
Offset to database path. The offset, in bytes, from the start
Bytes returned. The number of bytes of data returned. of the receiver variable to the database path field.
Connection type. The type of connection to use to the Offset to parent distinguished name. The offset, in bytes,
LDAP server. The following values may be specified: from the start of the receiver variable to the parent distin-
1 Nonsecure guished name field.
2 Secured, using SSL
Offset to referral server. The offset, in bytes, from the start
Current cipher protocols. The cipher protocols that the of the receiver variable to the referral server field.
server allows when using encrypted connections. The value
is the sum of zero or more of the following values: Offset to server name. The offset, in bytes, from the start
of the receiver variable to the server name field.
0x0100 Triple Data Encryption Standard (DES) Secure
Hash Algorithm (SHA) (U.S.) Offset to update DN. The offset, in bytes, from the start of
0x0200 DES SHA (U.S) the receiver variable to the update DN field.
0x0400 Rivest Cipher 4 (RC4) SHA (U.S.)
0x0800 RC4 Message Digest (MD) 5 (U.S.) Parent distinguished name. The parent distinguished
0x1000 RC2 MD5 (export) name for published objects. For example, if the parent dis-
0x2000 RC4 MD5 (export) tinguished name is "ou=rochester, o=ibm, c=us", a published
directory object for user John Smith might be "cn=john smith,
Database path. The integrated file system path name of the ou=rochester, o=ibm, c=us". This field is specified in UCS-2
library containing the directory database. This field is speci- (CCSID 13488).
fied in UCS-2 (CCSID 13488).

Chapter 19. Directory Services Configuration APIs 19-19

Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

Password format. The format of the encrypted password. Server name. The name of the server. This field is speci-
The following values may be specified: fied in UCS-2 (CCSID 13488).
1 Unencrypted.
Update DN. The distinguished name that the master server
2 SHA (this is the default).
must use when propagating directory updates to this replica
3 MD5.
server. This field is specified in UCS-2 (CCSID 13488). The
following value may be specified:
Read only. Whether the directory server allows changes to
be made to the directory contents. The following values may *NONE No value is specified.
be specified:
Use encrypted connections. Whether this server should
0 The directory server is not read only. Updates
use encrypted connections when making updates to the
are allowed to the directory.
replica server. The following values may be specified:
1 The directory server is read only. Updates
are not allowed to the directory. 0 Use unencrypted connections.
1 Use encrypted connections.
Referral port. An optional port number to be returned to a
client when a request is made for a directory object that does Version. Returns the version of the LDAP server.
not reside on this server. The referral port and referral
server together are used to form a referral URL. The fol- Error Messages
lowing special value may be specified:
CPF24B4 E Severe error while addressing parameter list.
0 No port number is returned as part of the CPF3C1E E
referral. Required parameter &1 omitted.
CPF3C21 E
Referral server. The IP name of a server to return to a
Format name &1 is not valid.
client when a request is made for a directory object that does
CPF3C90 E
not reside on this server. This field is specified in UCS-2
Literal value cannot be changed.
(CCSID 13488). The referral port and referral server are
CPF3CF1 E
used together to form a referral URL. The following special
Error code parameter not valid.
value may be specified:
CPF3CF2 E
*NONE No value is specified. Error(s) occurred during running of &1 API.
CPF9872 E Program or service program &1 in library &2
Reserved. A reserved field. This field must be set to zero. ended. Reason code &3.
CPFA314 E Memory allocation error.
Search size limit. The maximum number of entries that the
GLD0215 E Server has not been configured.
server will return for a given search request. The following
special value may be specified:
0 Do not limit the number of entries returned. Synchronize System Distribution Directory
Search time limit. The maximum time, in seconds, that the to LDAP (QGLDSSDD) API
server will spend performing a given search request. The
following special value may be specified:
Required Parameter Group:
0 Do not limit the search time.
1 Option Input Char(10)
Security. Whether the server is to use encrypted con- 2 LDAP user ID Input Char(1024)
nections. The following values may be specified: 3 LDAP user ID password Input Char(128)
1 Allow unencrypted connections only. | 4 No longer used Input Char(1024)
| 5 No longer used Input Char(128)
2 Allow encrypted connections only.
6 Error code I/O Char(*)
3 Allow both encrypted and unencrypted con-
nections. Threadsafe: No
Note: SSL is used for encrypted connections to the server.

Server is replica. Whether the server is a master server or The Synchronize System Distribution Directory to LDAP
a replica server. The following values may be specified: (QGLDSSDD) API publishes system distribution directory
entries to an LDAP directory and keeps the LDAP directory
0 The server is a master server for the directory synchronized with changes made in the system distribution
suffixes present on the server. directory. The following users from the system distribution
1 The server is a replica server for the directory directory are published:
suffixes present on the server.
Ÿ Local users

19-20 AS/400 System API Reference V4R4

 Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

Ÿ Remote users that have been added to the local AS/400 Note that if changes are made in the LDAP directory, these
system and have a Simple Mail Transfer Protocol changes are not synchronized back to the system distribution
(SMTP) address directory.

The system distribution directory users that are not published | Some entries are prevented automatically from being pub-
are: | lished to LDAP. They are the *ANY system distribution
| directory entries and some other IBM-supplied entries
Ÿ Shadowed users
| starting with Q (QSECOFR, QDOC, QSYS, QDFTOWN,
Ÿ Remote users that do not have a SMTP address
| QUSER for example). A specific user can be prevented from
The Directory Services product needs to be installed on your | being published to LDAP by doing the following:
system to run this API. This product is option 32 under the | 1. Add the user-defined field QREPL QLDAP to the system
base operating system. | distribution directory. This only needs to be done once
| per system.
| The Directory Services property page must be set up. In
| V4R4 and later, users are published automatically when they | CHGSYSDIRA USRDFNFLD((QREPL QLDAP \ADD \DATA 4))
| are set up in the Directory Services property page to publish | 2. Specify *NO as the value for the QREPL QLDAP user-
| under the LDAP server. Prior to V4R4, this API | defined field for those users that you do not want to rep-
| (QGLDSSDD) must be called regularly to publish the users | licate to LDAP. Any other value or absence of the
| because publishing users is not automatic prior to V4R4. | QREPL QLDAP user-defined field will replicate the user.
| See “Usage Notes” on page 19-24 for the procedure for | It is recommended that you either leave the QREPL
| setting up the Directory Services property page. | QLDAP value blank or specify *YES if you want the user
| to be replicated.
| If you are using SSL, the SSL key database information is
| configured using Digital Certificate Manager. See “Usage | For example, using Work with Directory Entries
| Notes” on page 19-24 for information on accessing the | (WRKDIRE), option 1 to add a user or option 2 to
| Digital Certificate Manager. | change a user, press the F20 key to specify user-
| defined fields. When using the ADDDIRE or CHGDIRE
| When using a V4R4 or later AS/400 Operations Navigator | commands, specify USRDFNFLD((QREPL QLDAP
| client to publish users to a V4R4 or later AS/400 server, the | *NO)) to prevent the user from being replicated.
| following no longer applies because this is done automat- | 3. If the user is already replicated to LDAP and *NO is
| ically. The synchronization is restricted to one LDAP server | specified in the QREPL QLDAP user-defined field, the
and one distinguished name to publish to. If you need to | user will be deleted from the LDAP directory. Likewise,
change the LDAP server or distinguished name that the | if the value of the QREPL QLDAP user-defined field is
system distribution directory information gets published to, | changed to anything but *NO, the user will be added to
first end the synchronization (using option value *END). | the LDAP directory.
Then change the LDAP server attributes from the AS/400
Operations Navigator or from the Change Directory Server AS/400 supports LDAP Version 2. This version of LDAP
Attributes (QgldChgDirSrvA) API. You can then use option does not support NLS characters. LDAP Version 2 supports
*ALL to initialize all the system distribution directory data to the IA5 character set (characters A-Z, a-z, 0-9, and some
the new LDAP server or distinguished name. special characters). At least one of the following fields in the
system distribution directory entry needs to contain only IA5
Before users can be published, the host and domain name characters in order for the entry to synchronize to LDAP:
must be set using the Change TCP/IP Domain
(CHGTCPDMN) command. The keywords that must be set Ÿ First name
are HOSTNAME and DMNNAME. Ÿ Last name
Ÿ Middle name
Also, before users can be published, the SMTP information Ÿ Preferred name
must be configured using the Change SMTP Attributes Ÿ Full name
(CHGSMTPA) command. This command is used to set the Ÿ User ID
user ID delimiter value when a user does not have an SMTP For all other fields listed in Figure 19-1 on page 19-22, if the
name. The user ID delimiter value can be the default value field contains characters outside the IA5 character set, the
or one of the other values allowed. LDAP user will exist but without the mapped LDAP attribute.
LDAP uses the distinguished name (dn) as the key for the As an administrator, you will need to understand some addi-
user. For the system distribution directory entries in LDAP, tional items that are needed to synchronize the system distri-
the distinguished name is the common name (cn) combined bution directory to LDAP. These include the following:
with the distinguished name that LDAP is being published to.
See “Distinguished Name (dn) and Common Name (cn)” on Ÿ inetOrgPerson and publisher object classes used in syn-
page 19-22 for more information. chronization.
Ÿ How the system distribution directory fields map to LDAP
attributes.

Chapter 19. Directory Services Configuration APIs 19-21

Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

Ÿ What is a distinguished name and common name and Distinguished Name (dn) and Common Name (cn):
why they are important for synchronization. LDAP uses the distinguished name (dn) as the key for the
Ÿ How the AS/400 user profile field is used in LDAP. user. For the system distribution directory entries in LDAP,
the distinguished name is the common name (cn) com-
inetOrgPerson and publisher Object Class: If your bined with the distinguished name that LDAP is being pub-
LDAP server is not on an AS/400, you must ensure that the lished to.
inetOrgPerson and publisher object classes are defined in
The user will have the following common names in LDAP.
the schema file of the server. The inetOrgPerson object
The first nonblank one will be used in the distinguished
class is used in LDAP to store the system distribution direc-
name:
tory information. The publisher object class requires a new
attribute, publisherName. Documentation on the 1. 'First name' 'Middle Name' 'Last name'
inetOrgPerson and publisher object class can be found in the 2. 'Preferred name' 'Last name'
AS/400 Information Center (under Networking). The AS/400 3. 'Full name'
Information Center is located at the following URL: 4. 'UserID'
http://publib.boulder.ibm.com/html/as4ðð/infocenter.html For example, if a user has the following field values in the
system distribution directory,
System Distribution Directory to LDAP Mapping:
The system distribution directory entry is published to the Ÿ First name: Jonathan
LDAP directory by using the inetOrgPerson object class. Ÿ Middle name: T.
Figure 19-1 on page 19-22 describes the mapping of system Ÿ Preferred name: John
distribution directory fields to attributes of the inetOrgPerson Ÿ Last name: Smith
object class. Ÿ Full name: Smith, John T.
Ÿ User ID: JSMITH
System Distribution Directory Field LDAP Attribute the user will have the following common names (cn):
User profile uid
Descriptions description Ÿ cn=Jonathan T. Smith
Last name sn (surname), cn (common name) Ÿ cn=John Smith
First name givenName, cn (common name)
Preferred name cn (common name) Ÿ cn="Smith, John T."
Full name cn (common name) Ÿ cn=JSMITH
User ID cn (common name)
Department departmentNumber
Job title title
If the distinguished name that LDAP is being published to is
Telephone number 1 & 2 telephoneNumber 'ou=chicago,o=acme,c=us', then the distinguished name of
FAX telephone number facsimileTelephoneNumber
Office roomNumber
this user is 'cn=Jonathan T. Smith,ou=chicago,o=acme,c=us'
Address lines 1-4 registeredAddress using the first cn in the list. The cn value is enclosed in quo-
SMTP name mail
tation marks if it contains a comma, pound sign, plus sign,
Figure 19-1. System Distribution Directory Fields Mapped to LDAP equal sign, less than or greater than sign, or a semicolon.
Attributes Leading blanks from the system distribution directory fields
are removed for the cn value. For example, if the first name
If the field is blank in the system distribution directory, then is ' Jane', the cn value will use 'Jane'. Also, the system dis-
the attribute is not created in LDAP for that user, with the tribution directory field values containing quotation marks will
following exceptions: not be used when deriving the cn values as described above.
Ÿ Last name: If last name is blank, then the user ID is
Attention: If you have two users in the system distribution
used in the LDAP directory for the surname (sn) attri-
directory that will resolve to the same distinguished name,
bute.
they will overlay each other in the LDAP directory. Some-
Ÿ SMTP name: For local users, if the SMTP name is times overlaying names is what you want if you are merging
blank, then the User ID and address fields are used for multiple AS/400 system distribution directories into one LDAP
the mail attribute in the format directory. If you have different users with the same name,
'UserID?Address@Domain'. Domain is the value speci- ensure they have different distinguished names to prevent
fied on the Change TCP/IP Domain (CHGTCPDMN) overlaying each other.
command and the '?' is the default SMTP User ID delim-
iter value specified on the Change SMTP Attributes This API can run on other AS/400 systems to synchronize
(CHGSMTPA) command. the system distribution directory on those systems to the
same LDAP server and distinguished name being published
to. If you have the same user on multiple AS/400 systems,
they will become one user in the LDAP directory. The distin-
guished name (dn) identifies the user. Note that you can run
this API from multiple AS/400 systems to different directory
servers or to the same directory server, but different distin-
guished name that LDAP is being published to. You may
want to do this if you would like to ensure that information

19-22 AS/400 System API Reference V4R4

 Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

from different system distribution directories does not overlay distribution directory fields will be used in the
each other. LDAP directory.
The *ALL option value also sets up the necessary
User Profile (uid) for AS/400 Users: For local users,
AS/400 objects needed to synchronize the system
the user profile field is used to set the uid attribute in the
distribution directory changes to the LDAP direc-
LDAP directory. This API does not publish AS/400 pass-
tory after the LDAP directory is replicated.
words for security reasons. Therefore, when the LDAP
server is on an AS/400, the uid attribute is used to see if that You must request the *ALL option value first, but
user exists on the AS/400. The password is verified with the it can be specified more than once. For example,
password that is passed from the client. to reload the LDAP directory, you would use the
*CHG option value to send any pending changes
If you are publishing the system distribution directory infor- to the LDAP directory followed by the *ALL option
mation to a different AS/400 or to a system that is not an value. If you change which LDAP server or dis-
AS/400, then you will need to set the userPassword attribute tinguished name you want the system distribution
for those users that you want to access the LDAP directory. directory entries to be replicated to, you can use
You would set the userPassword attribute for the user after the *ALL option value to replicate to that server or
you use the QGLDSSDD API to publish the system distribu- distinguished name.
tion directory users. The following shows a client command
*CHG
from a UNIX shell that is used to set the userPassword attri-
The system distribution directory entries that were
bute of two users:
added, changed, removed, or renamed since the
ldapmodify -h ldapserver -f /path/filename *ALL or previous *CHG option value was used
-D cn=Admin -w password are updated in the LDAP directory.
The ldapserver is the server name that was configured in the Changes made to the system distribution directory
Directory Services system property. The /path/filename file users in the LDAP directory are overwritten by
contains the distinguished name and password for the users. changes made in the system distribution directory
An example file with two user entries would be: on the AS/400 for the attributes listed above. All
dn:cn=Jonathan T. Smith,ou=chicago,o=acme,c=us other attributes of inetOrgPerson that are
userPassword:secret changed in LDAP by using an LDAP client are not
overwritten by the *CHG option value.
dn:cn=Barb Jones,ou=chicago,o=acme,c=us
userPassword:secret *END End the synchronization of the system distribution
directory to LDAP.
| If the LDAP user ID is passed in, this first syn-
chronizes any changes from the system distribu-
Authorities and Locks tion directory to the LDAP directory since the last
*ALLOBJ and *IOSYSCFG special authorities are needed to | synchronization request. An example is:
run this API. | CALL PGM(QDIRSRV/QGLDSSDD)
| PARM(\END 'LDAPuserID' 'LDAPpassword' ð ð ð)

Required Parameter Group | If the LDAP user ID is not passed in, the synchro-
| nization is just ended and the changes left in the
Option | queue from the last synchronization request are
INPUT; CHAR(10) | not published. An example is:
The option to use for publishing system distribution | CALL PGM(QDIRSRV/QGLDSSDD)
directory information to the LDAP directory. | PARM(\END ð ð ð ð ð)
The valid values are: The users in the LDAP directory where publishing
is being ended are not deleted. They are left in
*ALL All the local users and all the remote users that the LDAP directory. Changes made to the
have been added from this system and that have system distribution directory after publishing is
an SMTP name will be replicated from the system ended are no longer queued.
distribution directory to the LDAP directory. The
LDAP directory is on the LDAP server specified in To start replication again after this value is used,
the Directory Services dialog of the AS/400 Oper- call this API with the *ALL option value. A *CHG
ations Navigator. These users will be placed in option value will result in an error.
the LDAP tree under the distinguished name that *RESET
is specified in the Directory Services dialog. See Ensures that all the AS/400 objects exist for this
Figure 19-1 on page 19-22 as to what system replication function and clears the queue that
keeps track of the changes made to the system
distribution directory.

Chapter 19. Directory Services Configuration APIs 19-23

 Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

Specify zero for the LDAP user ID, LDAP user ID | Notes” below for more information on the Digital Certif-
password, key database file, and key database | icate Manager.
password when you use this value. For example,
| No longer used (Used to be 'Key database password')
CALL PGM(QDIRSRV/QGLDSSDD) | INPUT; CHAR(128)
PARM(\RESET ð ð ð ð ð)
| Specify zero (0) as a placeholder for this parameter as it
LDAP user ID | is no longer used. If a value is specified, it will be
INPUT; CHAR(1024) | ignored for compatibility reasons. If you need SSL key
| database information configured, it is now configured
| The LDAP user ID that has administrator authority to | using the Digital Certificate Manager. See the “Usage
| add, change, and remove entries in the LDAP entry. | Notes” below for more information on the Digital Certif-
| The valid values are: | icate Manager.

| *CFG Use the configured LDAP user ID that can be Error code
| specified when publishing users (using AS/400 I/O; CHAR(*)
| Operations Navigator). The structure in which to return error information. For
| See “Usage Notes” for the procedure for config- the format of the structure, see “Error Code Parameter”
| uring the Directory Services property page. If the on page 2-6.
| Directory Services property page is not configured
| and the *CFG value is passed, then error Note: All character data is assumed to be represented in
| GLD0310 with reason code 12 is signalled. the CCSID (coded character set identifier) currently in effect
for the job. If the CCSID of the job is 65535, the data is
A null-terminated string containing the LDAP user ID that assumed to be represented in the default CCSID of the job.
has administrator authority to add, change, and
remove entries in the LDAP entry.
An example user ID is cn=Admin. Specify a zero- Usage Notes
length string if the LDAP server does not require
authority checking or the option value *RESET is If the system distribution directory field values for two users
specified. Only IA5 characters are allowed (char- result in the same distinguished name, then these names will
acters A-Z, a-z, 0-9, and some special charac- overlay each other in the LDAP directory. To ensure this
ters). does not happen when not intended, you must have unique
names for your users before you synchronize the system dis-
LDAP user ID password tribution directory to an LDAP directory.
INPUT; CHAR(128)
Use the Convert SMTP Names (CVTNAMSMTP) command if
| The password for the LDAP user ID.
you have not already done so to convert the Simple Mail
| The valid values are: Transfer Protocol (SMTP) fields to the system distribution
directory. The SMTP information is loaded when the option
| *CFG Use the configured LDAP user ID password that
value *ALL is used from this API. If you do not do
| can be specified when publishing users (using
CVTNAMSMTP, however, when you change the SMTP infor-
| AS/400 Operations Navigator).
mation using the Work with Names for SMTP
| See “Usage Notes” for the procedure for config- (WRKNAMSMTP) command, those changes do not go to the
| uring the Directory Services property page. If the LDAP directory. After you use the CVTNAMSMTP
| Directory Services property page is not configured command, the SMTP name is in the system distribution
| and the *CFG value is passed, then error directory in the user-defined fields SMTPAUSRID SMTP,
| GLD0310 with reason code 12 is signaled. SMTPDMN SMTP, and SMTPRTE SMTP. When these
A null-terminated string containing the password for the fields are updated by using the system distribution directory
LDAP user ID. commands (WRKDIRE, ADDDIRE, CHGDIRE), LDAP is kept
Specify a zero-length string if the LDAP server synchronized. If you cannot do CVTNAMSMTP, the other
does not require authority checking or the option option is to periodically use the option value *ALL to reload
value *RESET is specified. the LDAP directory to update all the system distribution direc-
tory information, including the SMTP information.
| No longer used (Used to be 'Key database file')
| INPUT; CHAR(1024) Synchronization Procedure: A procedure for synchro-
| Specify zero (0) as a placeholder for this parameter as it nizing the system distribution directory with an LDAP direc-
| is no longer used. If a value is specified, it will be tory is as follows:
| ignored for compatibility reasons. If you need SSL key 1. First ensure the Directory Services product is loaded on
| database information configured, it is now configured your system. From the command line, type: GO
| using the Digital Certificate Manager. See the “Usage LICPGM, then take option 10. This product is option 32
under the base operating system.

19-24 AS/400 System API Reference V4R4

 Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

2. The Directory Services property page for the LDAP The LDAP user ID must have sufficient authority to add,
server to publish to must be set up. Using the AS/400 change, and remove entries in the LDAP directory.
Operations Navigator, select 'Properties' of the system,
| If you have the LDAP user ID and password configured
| and then 'Directory Services'. In V4R4 and later, Direc-
| in the Directory Services property page, you can call the
| tory Services will bring up a list of AS/400 information to
| API using *CFG. For example, from the command line,
| publish. Select 'Users' from this list to configure the
| type:
| information. If your AS/400 Operations Navigator or
| AS/400 system is prior to V4R4, just the Directory Ser- | CALL PGM(QDIRSRV/QGLDSSDD)
| vices properties are set and no list is displayed. | PARM(\ALL \CFG \CFG ð ð ð)

The LDAP server to publish to must be specified and | For security reasons, it is recommended that you call
exist. The distinguished name to publish under must be | this API using the *CFG option if the call is being logged
specified and must be one that the server supports. All | in a job log.
the users in the system distribution directory will be | 8. If you are using V4R4 or later and select 'Users' in the
placed under the distinguished name (DN) specified. | list when configuring the Directory Services property
See LDAP documentation in the AS/400 Information | page, the system distribution directory users will auto-
Center (under Networking) for more information on using | matically be published to LDAP and you will not need to
the AS/400 Operations Navigator to configure the | do the following step (although you have the option to
system properties for Directory Services. | call it manually).

Configuring the Directory Services property can also be Periodically call QGLDSSDD to synchronize the LDAP
done using the Change Directory Server Attributes directory with the system distribution directory. The
(QgldChgDirSrvA) API. command to synchronize the LDAP directory is:
CALL PGM(QDIRSRV/QGLDSSDD)
3. If you are synchronizing the system distribution directory
PARM(\CHG 'LDAPuserID' 'LDAPpassword' ð ð ð)
to an LDAP server that is not on an AS/400, then you
need to ensure that the inetOrgPerson and publisher | If you have the LDAP user ID and password configured
object classes are defined in the schema file for the | in the Directory Services property page, you can call the
server. The publisher object class requires a new attri- | API using *CFG. For example, from the command line,
bute, publisherName, so ensure publisherName is also | type:
defined in a schema file. Documentation on the | CALL PGM(QDIRSRV/QGLDSSDD)
inetOrgPerson and publisher object class is found in the | PARM(\CHG \CFG \CFG ð ð ð)
AS/400 Information Center (under Networking)
| For security reasons, it is recommended that you call
4. Ensure the TCP/IP host and domain name are set. Use | this API using the *CFG option if the call is being logged
the Change TCP/IP Domain (CHGTCPDMN) command | in a job log.
and prompt by using F4.
The CL program can be run from a job schedule entry to
5. Use Change SMTP Attribute (CHGSMTPA) command to automatically run with scheduled frequency. Use the
set the user ID delimiter value. You can keep the Add Job Schedule Entry (ADDJOBSCDE) command or
default set to '?'. Ensure you press Enter so that the the Work with Job Schedule Entries (WRKJOBSCDE)
SMTP attributes are created. command to automatically schedule jobs.
| 6. If you need SSL certificate information configured, it is
| configured using the Digital Certificate Manager. You Error Messages
| can get to Digital Certificate Manager from the AS/400
| Operations Navigator under 'Network - Internet - Digital CPF3C90 E
| ID'. Literal value cannot be changed.
CPF3CF1 E
| 7. If you are using V4R4 or later and select 'Users' in the Error code parameter not valid.
| list when configuring the Directory Services property GLD0301 E Error encountered when accessing the LDAP
| page, the system distribution directory users will auto- Directory Server.
| matically be published to LDAP and you will not need to GLD0302 E Input option *CHG currently unavailable.
| do the following step. If needed, you could call it GLD0303 E The caller of this API must have &1 and &2
| optionally to reinitialize system distribution directory data special authorities.
| to an LDAP server. GLD0304 E Unable to export the system distribution direc-
Call the Synchronize System Distribution Directory to tory entry &1 &2 to the LDAP Directory Server.
LDAP API with the *ALL option value. For example, GLD0305 C Synchronization between the system distribution
from the command line, type: directory and the LDAP directory server com-
pleted.
CALL PGM(QDIRSRV/QGLDSSDD)
PARM(\ALL 'LDAPuserID' 'LDAPpassword' ð ð ð) GLD0309 E Value not valid for input parameter &1.
GLD0310 E Error occurred with QGLDSSDD API. Reason
code &1.

Chapter 19. Directory Services Configuration APIs 19-25

Synchronize System Distribution Directory to LDAP (QGLDSSDD) API

GLD0311 E Input parameter &1 is not valid. Reason code GLD0312 D Error encountered when setting up a secure
&2. connection to an LDAP server. The error
number is &1.

19-26 AS/400 System API Reference V4R4

 DSM

Part 9. Dynamic Screen Manager APIs

Chapter 20. Dynamic Screen Manager Delete Low-Level Environment (QsnDltEnv) API . . . 22-7
APIs—Introduction . . . . . . . . . . . . . . . . . 20-1 Authorities and Locks . . . . . . . . . . . . . . . 22-7
Dynamic Screen Manager APIs—Introduction . . . . 20-1 Required Parameter . . . . . . . . . . . . . . . . 22-7
Data Structures for DSM APIs . . . . . . . . . . . . 20-1 Omissible Parameter . . . . . . . . . . . . . . . 22-8
Omitting Parameters with Associated Lengths . . . . 20-1 Returned Value . . . . . . . . . . . . . . . . . . 22-8
Error Messages . . . . . . . . . . . . . . . . . . 22-8
Chapter 21. Low-Level Screen I/O Services APIs 21-1 Initialize Low-Level Environment Description
Low-Level Screen I/O Services APIs—Introduction . 21-1 (QsnInzEnvD) API . . . . . . . . . . . . . . . . . . 22-8
DSM Error Handling . . . . . . . . . . . . . . . . . 21-1 Authorities and Locks . . . . . . . . . . . . . . . 22-8
Device Support . . . . . . . . . . . . . . . . . . . . 21-1 Required Parameter Group . . . . . . . . . . . . 22-8
Operating Environments . . . . . . . . . . . . . . . 21-1 Omissible Parameter . . . . . . . . . . . . . . . 22-8
Direct and Indirect Operations . . . . . . . . . . . . 21-1 Returned Value . . . . . . . . . . . . . . . . . . 22-8
DBCS Considerations . . . . . . . . . . . . . . . . 21-1 Error Messages . . . . . . . . . . . . . . . . . . 22-8
5250 Data Stream Details . . . . . . . . . . . . . . 21-2 Query Color Support (QsnQryColorSup) API . . . . 22-9
AID-Generating Keys . . . . . . . . . . . . . . . 21-2 Authorities and Locks . . . . . . . . . . . . . . . 22-9
Control Characters . . . . . . . . . . . . . . . . 21-2 Omissible Parameter Group . . . . . . . . . . . . 22-9
Screen Attribute Characters . . . . . . . . . . . . 21-3 Returned Value . . . . . . . . . . . . . . . . . . 22-9
Display Address . . . . . . . . . . . . . . . . . . 21-5 Error Messages . . . . . . . . . . . . . . . . . . 22-9
Insert Cursor Address . . . . . . . . . . . . . . . 21-5 Query Display Mode Support (QsnQryModSup) API . 22-9
Modified Data Tag (MDT) Bit . . . . . . . . . . . 21-5 Authorities and Locks . . . . . . . . . . . . . . . 22-9
Resequencing . . . . . . . . . . . . . . . . . . . 21-5 Required Parameter . . . . . . . . . . . . . . . . 22-9
States and Modes . . . . . . . . . . . . . . . . . 21-5 Omissible Parameter Group . . . . . . . . . . . . 22-10
Dumping the 5250 Data Stream Commands . . . 21-5 Returned Value . . . . . . . . . . . . . . . . . . 22-10
Error Messages . . . . . . . . . . . . . . . . . . 22-10
Chapter 22. Screen Manipulation and Query APIs 22-1 Query 5250 (QsnQry5250) API . . . . . . . . . . . . 22-10
Screen Manipulation and Query APIs—Introduction . 22-1 Authorities and Locks . . . . . . . . . . . . . . . 22-10
Change Low-Level Environment (QsnChgEnv) API . 22-1 Restrictions . . . . . . . . . . . . . . . . . . . . 22-10
Authorities and Locks . . . . . . . . . . . . . . . 22-1 Required Parameter Group . . . . . . . . . . . . 22-10
Required Parameter Group . . . . . . . . . . . . 22-1 Omissible Parameter . . . . . . . . . . . . . . . 22-11
Omissible Parameter Group . . . . . . . . . . . . 22-2 Returned Value . . . . . . . . . . . . . . . . . . 22-11
Returned Value . . . . . . . . . . . . . . . . . . 22-2 Format of the Query Data . . . . . . . . . . . . . 22-11
Error Messages . . . . . . . . . . . . . . . . . . 22-2 Field Descriptions . . . . . . . . . . . . . . . . . 22-11
Clear Field Table (QsnClrFldTbl) API . . . . . . . . 22-2 Error Messages . . . . . . . . . . . . . . . . . . 22-14
Authorities and Locks . . . . . . . . . . . . . . . 22-2 Restore Screen (QsnRstScr) API . . . . . . . . . . 22-14
Omissible Parameter Group . . . . . . . . . . . . 22-2 Authorities and Locks . . . . . . . . . . . . . . . 22-14
Returned Value . . . . . . . . . . . . . . . . . . 22-2 Restrictions . . . . . . . . . . . . . . . . . . . . 22-14
Error Messages . . . . . . . . . . . . . . . . . . 22-3 Required Parameter . . . . . . . . . . . . . . . . 22-14
Clear Screen (QsnClrScr) API . . . . . . . . . . . . 22-3 Omissible Parameter Group . . . . . . . . . . . . 22-14
Authorities and Locks . . . . . . . . . . . . . . . 22-3 Returned Value . . . . . . . . . . . . . . . . . . 22-14
Restrictions . . . . . . . . . . . . . . . . . . . . 22-3 Error Messages . . . . . . . . . . . . . . . . . . 22-15
Omissible Parameter Group . . . . . . . . . . . . 22-3 Retrieve Display Mode (QsnRtvMod) API . . . . . . 22-15
Returned Value . . . . . . . . . . . . . . . . . . 22-3 Authorities and Locks . . . . . . . . . . . . . . . 22-15
Error Messages . . . . . . . . . . . . . . . . . . 22-3 Omissible Parameter Group . . . . . . . . . . . . 22-15
Create Low-Level Environment (QsnCrtEnv) API . . 22-4 Returned Value . . . . . . . . . . . . . . . . . . 22-15
Authorities and Locks . . . . . . . . . . . . . . . 22-4 Error Messages . . . . . . . . . . . . . . . . . . 22-15
Required Parameter Group . . . . . . . . . . . . 22-4 Retrieve Low-Level Environment Description
Omissible Parameter Group . . . . . . . . . . . . 22-4 (QsnRtvEnvD) API . . . . . . . . . . . . . . . . . 22-15
Returned Value . . . . . . . . . . . . . . . . . . 22-4 Authorities and Locks . . . . . . . . . . . . . . . 22-15
Format of the Low-Level Environment Description 22-4 Required Parameter Group . . . . . . . . . . . . 22-16
Format of the Low-Level User Environment Omissible Parameter Group . . . . . . . . . . . . 22-16
Extension Information . . . . . . . . . . . . . . 22-5 Returned Value . . . . . . . . . . . . . . . . . . 22-16
Field Descriptions . . . . . . . . . . . . . . . . . 22-5 Format of the Data Returned . . . . . . . . . . . 22-16
Exit Routine Error Handling . . . . . . . . . . . . 22-7 Error Messages . . . . . . . . . . . . . . . . . . 22-16
Change Low-Level Environment Exit Routine . . . 22-7 Retrieve Low-Level Environment User Data
Delete Low-Level Environment Exit Routine . . . 22-7 (QsnRtvEnvDta) API . . . . . . . . . . . . . . . . 22-16
Error Messages . . . . . . . . . . . . . . . . . . 22-7 Authorities and Locks . . . . . . . . . . . . . . . 22-16

 Copyright IBM Corp. 1998, 1999

DSM

Required Parameter . . . . . . . . . . . . . . . . 22-16 Returned Value . . . . . . . . . . . . . . . . . . 23-3

Omissible Parameter Group . . . . . . . . . . . . 22-17 Error Messages . . . . . . . . . . . . . . . . . . 23-3
Returned Value . . . . . . . . . . . . . . . . . . 22-17 Create Command Buffer (QsnCrtCmdBuf) API . . . 23-3
Error Messages . . . . . . . . . . . . . . . . . . 22-17 Authorities and Locks . . . . . . . . . . . . . . . 23-3
Retrieve Low-Level Environment Window Mode Required Parameter . . . . . . . . . . . . . . . . 23-3
(QsnRtvEnvWinMod) API . . . . . . . . . . . . . . 22-17 Omissible Parameter Group . . . . . . . . . . . . 23-3
Authorities and Locks . . . . . . . . . . . . . . . 22-17 Returned Value . . . . . . . . . . . . . . . . . . 23-4
Required Parameter Group . . . . . . . . . . . . 22-17 Error Messages . . . . . . . . . . . . . . . . . . 23-4
Omissible Parameter Group . . . . . . . . . . . . 22-17 Create Input Buffer (QsnCrtInpBuf) API . . . . . . . 23-4
Returned Value . . . . . . . . . . . . . . . . . . 22-18 Authorities and Locks . . . . . . . . . . . . . . . 23-4
Format of the Data Returned . . . . . . . . . . . 22-18 Required Parameter . . . . . . . . . . . . . . . . 23-4
Field Descriptions . . . . . . . . . . . . . . . . . 22-18 Omissible Parameter Group . . . . . . . . . . . . 23-4
Error Messages . . . . . . . . . . . . . . . . . . 22-18 Returned Value . . . . . . . . . . . . . . . . . . 23-4
Retrieve Screen Dimensions (QsnRtvScrDim) API . 22-18 Error Messages . . . . . . . . . . . . . . . . . . 23-4
Authorities and Locks . . . . . . . . . . . . . . . 22-18 Delete Buffer (QsnDltBuf) API . . . . . . . . . . . . 23-5
Omissible Parameter Group . . . . . . . . . . . . 22-18 Authorities and Locks . . . . . . . . . . . . . . . 23-5
Returned Value . . . . . . . . . . . . . . . . . . 22-19 Required Parameter . . . . . . . . . . . . . . . . 23-5
Error Messages . . . . . . . . . . . . . . . . . . 22-19 Omissible Parameter . . . . . . . . . . . . . . . 23-5
Roll Down (QsnRollDown) API . . . . . . . . . . . . 22-19 Returned Value . . . . . . . . . . . . . . . . . . 23-5
Restrictions . . . . . . . . . . . . . . . . . . . . 22-19 Error Messages . . . . . . . . . . . . . . . . . . 23-5
Authorities and Locks . . . . . . . . . . . . . . . 22-19 Put Command Buffer (QsnPutBuf) API . . . . . . . . 23-5
Required Parameter Group . . . . . . . . . . . . 22-19 Authorities and Locks . . . . . . . . . . . . . . . 23-5
Omissible Parameter Group . . . . . . . . . . . . 22-19 Required Parameter . . . . . . . . . . . . . . . . 23-5
Returned Value . . . . . . . . . . . . . . . . . . 22-19 Omissible Parameter Group . . . . . . . . . . . . 23-5
Error Messages . . . . . . . . . . . . . . . . . . 22-20 Returned Value . . . . . . . . . . . . . . . . . . 23-6
Roll Up (QsnRollUp) API . . . . . . . . . . . . . . . 22-20 Error Messages . . . . . . . . . . . . . . . . . . 23-6
Usage Notes . . . . . . . . . . . . . . . . . . . . 22-20 Put Command Buffer and Perform Get (QsnPutGetBuf)
Authorities and Locks . . . . . . . . . . . . . . . 22-20 API . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Required Parameter Group . . . . . . . . . . . . 22-20 Authorities and Locks . . . . . . . . . . . . . . . 23-6
Omissible Parameter Group . . . . . . . . . . . . 22-20 Required Parameter Group . . . . . . . . . . . . 23-6
Returned Value . . . . . . . . . . . . . . . . . . 22-20 Omissible Parameter Group . . . . . . . . . . . . 23-6
Error Messages . . . . . . . . . . . . . . . . . . 22-20 Returned Value . . . . . . . . . . . . . . . . . . 23-6
Save Screen (QsnSavScr) API . . . . . . . . . . . . 22-21 Error Messages . . . . . . . . . . . . . . . . . . 23-7
Authorities and Locks . . . . . . . . . . . . . . . 22-21 Retrieve AID Code on Read (QsnRtvReadAID) API . 23-7
Restrictions . . . . . . . . . . . . . . . . . . . . 22-21 Authorities and Locks . . . . . . . . . . . . . . . 23-7
Omissible Parameter Group . . . . . . . . . . . . 22-21 Required Parameter . . . . . . . . . . . . . . . . 23-7
Returned Value . . . . . . . . . . . . . . . . . . 22-21 Omissible Parameter Group . . . . . . . . . . . . 23-7
Error Messages . . . . . . . . . . . . . . . . . . 22-21 Returned Value . . . . . . . . . . . . . . . . . . 23-7
Set Low-Level Environment Window Mode Error Messages . . . . . . . . . . . . . . . . . . 23-8
(QsnSetEnvWinMod) API . . . . . . . . . . . . . . 22-22 Retrieve Available Data (QsnRtvAvailData) API . . . 23-8
Authorities and Locks . . . . . . . . . . . . . . . 22-23 Authorities and Locks . . . . . . . . . . . . . . . 23-8
Required Parameter . . . . . . . . . . . . . . . . 22-23 Required Parameter Group . . . . . . . . . . . . 23-8
Omissible Parameter Group . . . . . . . . . . . . 22-23 Omissible Parameter Group . . . . . . . . . . . . 23-8
Returned Value . . . . . . . . . . . . . . . . . . 22-23 Returned Value . . . . . . . . . . . . . . . . . . 23-8
Format of the Window Mode Description . . . . . 22-24 Error Messages . . . . . . . . . . . . . . . . . . 23-8
Field Descriptions . . . . . . . . . . . . . . . . . 22-24 Retrieve Buffer Data Length (QsnRtvBufLen) API . . 23-8
Error Messages . . . . . . . . . . . . . . . . . . 22-24 Authorities and Locks . . . . . . . . . . . . . . . 23-9
Required Parameter . . . . . . . . . . . . . . . . 23-9
Chapter 23. Buffer Manipulation and Query APIs 23-1 Omissible Parameter Group . . . . . . . . . . . . 23-9
Buffer Manipulation and Query APIs—Introduction . 23-1 Returned Value . . . . . . . . . . . . . . . . . . 23-9
Clear Buffer (QsnClrBuf) API . . . . . . . . . . . . . 23-1 Error Messages . . . . . . . . . . . . . . . . . . 23-9
Authorities and Locks . . . . . . . . . . . . . . . 23-2 Retrieve Buffer Size (QsnRtvBufSiz) API . . . . . . 23-9
Required Parameter . . . . . . . . . . . . . . . . 23-2 Authorities and Locks . . . . . . . . . . . . . . . 23-9
Omissible Parameter . . . . . . . . . . . . . . . 23-2 Required Parameter . . . . . . . . . . . . . . . . 23-9
Returned Value . . . . . . . . . . . . . . . . . . 23-2 Omissible Parameter Group . . . . . . . . . . . . 23-9
Error Messages . . . . . . . . . . . . . . . . . . 23-2 Returned Value . . . . . . . . . . . . . . . . . . 23-10
Copy Buffer (QsnCpyBuf) API . . . . . . . . . . . . 23-2 Error Messages . . . . . . . . . . . . . . . . . . 23-10
Authorities and Locks . . . . . . . . . . . . . . . 23-2 Retrieve Cursor Address on Read (QsnRtvReadAdr)
Required Parameter Group . . . . . . . . . . . . 23-2 API . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Omissible Parameter . . . . . . . . . . . . . . . 23-2 Authorities and Locks . . . . . . . . . . . . . . . 23-10

AS/400 System API Reference V4R4

 DSM

Required Parameter . . . . . . . . . . . . . . . . 23-10 Chapter 24. Screen Input APIs . . . . . . . . . . 24-1

Omissible Parameter Group . . . . . . . . . . . . 23-10 Screen Input APIs—Introduction . . . . . . . . . . . 24-1
Returned Value . . . . . . . . . . . . . . . . . . 23-10 Read Command Processing . . . . . . . . . . . . . 24-1
Error Messages . . . . . . . . . . . . . . . . . . 23-10 Get AID (QsnGetAID) API . . . . . . . . . . . . . . 24-1
Retrieve Field Information (QsnRtvFldInf) API . . . . 23-11 Authorities and Locks . . . . . . . . . . . . . . . 24-1
Authorities and Locks . . . . . . . . . . . . . . . 23-11 Omissible Parameter Group . . . . . . . . . . . . 24-2
Required Parameter Group . . . . . . . . . . . . 23-11 Returned Value . . . . . . . . . . . . . . . . . . 24-2
Omissible Parameter Group . . . . . . . . . . . . 23-11 Error Messages . . . . . . . . . . . . . . . . . . 24-2
Returned Value . . . . . . . . . . . . . . . . . . 23-11 Get Cursor Address (QsnGetCsrAdr) API . . . . . . 24-2
Format of the Query Input Field Result . . . . . . 23-11 Authorities and Locks . . . . . . . . . . . . . . . 24-2
Field Descriptions . . . . . . . . . . . . . . . . . 23-12 Restrictions . . . . . . . . . . . . . . . . . . . . 24-2
Error Messages . . . . . . . . . . . . . . . . . . 23-12 Omissible Parameter Group . . . . . . . . . . . . 24-2
Retrieve Length of Data in Input Buffer Returned Value . . . . . . . . . . . . . . . . . . 24-3
(QsnRtvDtaLen) API . . . . . . . . . . . . . . . . 23-12 Error Messages . . . . . . . . . . . . . . . . . . 24-3
Authorities and Locks . . . . . . . . . . . . . . . 23-12 Get Cursor Address with AID (QsnGetCsrAdrAID) API 24-3
Required Parameter . . . . . . . . . . . . . . . . 23-12 Authorities and Locks . . . . . . . . . . . . . . . 24-3
Omissible Parameter Group . . . . . . . . . . . . 23-12 Omissible Parameter Group . . . . . . . . . . . . 24-3
Returned Value . . . . . . . . . . . . . . . . . . 23-12 Returned Value . . . . . . . . . . . . . . . . . . 24-3
Error Messages . . . . . . . . . . . . . . . . . . 23-12 Error Messages . . . . . . . . . . . . . . . . . . 24-3
Retrieve Length of Field Data in Buffer Put Input Command (QsnPutInpCmd) API . . . . . . 24-4
(QsnRtvFldDtaLen) API . . . . . . . . . . . . . . . 23-13 Authorities and Locks . . . . . . . . . . . . . . . 24-4
Authorities and Locks . . . . . . . . . . . . . . . 23-13 Required Parameter . . . . . . . . . . . . . . . . 24-4
Required Parameter . . . . . . . . . . . . . . . . 23-13 Omissible Parameter Group . . . . . . . . . . . . 24-4
Omissible Parameter Group . . . . . . . . . . . . 23-13 Returned Value . . . . . . . . . . . . . . . . . . 24-5
Returned Value . . . . . . . . . . . . . . . . . . 23-13 Error Messages . . . . . . . . . . . . . . . . . . 24-5
Error Messages . . . . . . . . . . . . . . . . . . 23-13 Read Immediate (QsnReadImm) API . . . . . . . . 24-5
Retrieve Number of Bytes Read from Screen Authorities and Locks . . . . . . . . . . . . . . . 24-5
(QsnRtvReadLen) API . . . . . . . . . . . . . . . 23-13 Restrictions . . . . . . . . . . . . . . . . . . . . 24-5
Authorities and Locks . . . . . . . . . . . . . . . 23-14 Omissible Parameter Group . . . . . . . . . . . . 24-5
Required Parameter . . . . . . . . . . . . . . . . 23-14 Returned Value . . . . . . . . . . . . . . . . . . 24-6
Omissible Parameter Group . . . . . . . . . . . . 23-14 Error Messages . . . . . . . . . . . . . . . . . . 24-6
Returned Value . . . . . . . . . . . . . . . . . . 23-14 Read Input Fields (QsnReadInp) API . . . . . . . . 24-6
Error Messages . . . . . . . . . . . . . . . . . . 23-14 Restrictions . . . . . . . . . . . . . . . . . . . . 24-7
Retrieve Number of Fields Read (QsnRtvFldCnt) API 23-14 Authorities and Locks . . . . . . . . . . . . . . . 24-7
Authorities and Locks . . . . . . . . . . . . . . . 23-14 Required Parameter Group . . . . . . . . . . . . 24-7
Required Parameter . . . . . . . . . . . . . . . . 23-15 Omissible Parameter Group . . . . . . . . . . . . 24-7
Omissible Parameter Group . . . . . . . . . . . . 23-15 Returned Value . . . . . . . . . . . . . . . . . . 24-7
Returned Value . . . . . . . . . . . . . . . . . . 23-15 Error Messages . . . . . . . . . . . . . . . . . . 24-8
Error Messages . . . . . . . . . . . . . . . . . . 23-15 Read from Invited Device (QsnReadInvited) API . . 24-8
Retrieve Pointer to Data in Input Buffer (QsnRtvDta) Authorities and Locks . . . . . . . . . . . . . . . 24-8
API . . . . . . . . . . . . . . . . . . . . . . . . . 23-15 Restrictions . . . . . . . . . . . . . . . . . . . . 24-8
Authorities and Locks . . . . . . . . . . . . . . . 23-15 Required Parameter Group . . . . . . . . . . . . 24-8
Required Parameter . . . . . . . . . . . . . . . . 23-15 Omissible Parameter Group . . . . . . . . . . . . 24-8
Omissible Parameter Group . . . . . . . . . . . . 23-15 Returned Value . . . . . . . . . . . . . . . . . . 24-9
Returned Value . . . . . . . . . . . . . . . . . . 23-15 Error Messages . . . . . . . . . . . . . . . . . . 24-9
Error Messages . . . . . . . . . . . . . . . . . . 23-16 Read Modified Alternate (QsnReadMDTAlt) API . . . 24-9
Retrieve Pointer to Field Data (QsnRtvFldDta) API . 23-16 Authorities and Locks . . . . . . . . . . . . . . . 24-9
Authorities and Locks . . . . . . . . . . . . . . . 23-16 Restrictions . . . . . . . . . . . . . . . . . . . . 24-9
Required Parameter . . . . . . . . . . . . . . . . 23-16 Required Parameter Group . . . . . . . . . . . . 24-10
Omissible Parameter Group . . . . . . . . . . . . 23-16 Omissible Parameter Group . . . . . . . . . . . . 24-10
Returned Value . . . . . . . . . . . . . . . . . . 23-16 Returned Value . . . . . . . . . . . . . . . . . . 24-10
Error Messages . . . . . . . . . . . . . . . . . . 23-16 Error Messages . . . . . . . . . . . . . . . . . . 24-10
Retrieve Read Information (QsnRtvReadInf) API . . 23-17 Read Modified Fields (QsnReadMDT) API . . . . . . 24-10
Authorities and Locks . . . . . . . . . . . . . . . 23-17 Restrictions . . . . . . . . . . . . . . . . . . . . 24-11
Required Parameter Group . . . . . . . . . . . . 23-17 Authorities and Locks . . . . . . . . . . . . . . . 24-11
Omissible Parameter Group . . . . . . . . . . . . 23-17 Required Parameter Group . . . . . . . . . . . . 24-11
Returned Value . . . . . . . . . . . . . . . . . . 23-17 Omissible Parameter Group . . . . . . . . . . . . 24-11
Format of the Query Result . . . . . . . . . . . . 23-17 Returned Value . . . . . . . . . . . . . . . . . . 24-12
Field Descriptions . . . . . . . . . . . . . . . . . 23-17 Error Messages . . . . . . . . . . . . . . . . . . 24-12
Error Messages . . . . . . . . . . . . . . . . . . 23-18

Part 9. Dynamic Screen Manager APIs

DSM

Read Modified Immediate Alternate Error Messages . . . . . . . . . . . . . . . . . . 25-9

(QsnReadMDTImmAlt) API . . . . . . . . . . . . . 24-12 Set Error State (QsnSetErr) API . . . . . . . . . . . 25-9
Restrictions . . . . . . . . . . . . . . . . . . . . 24-12 Authorities and Locks . . . . . . . . . . . . . . . 25-10
Authorities and Locks . . . . . . . . . . . . . . . 24-12 Omissible Parameter Group . . . . . . . . . . . . 25-10
Omissible Parameter Group . . . . . . . . . . . . 24-12 Returned Value . . . . . . . . . . . . . . . . . . 25-11
Returned Value . . . . . . . . . . . . . . . . . . 24-13 Error Messages . . . . . . . . . . . . . . . . . . 25-11
Error Messages . . . . . . . . . . . . . . . . . . 24-13 Set Field (QsnSetFld) API . . . . . . . . . . . . . . 25-11
Read Screen (QsnReadScr) API . . . . . . . . . . . 24-13 Authorities and Locks . . . . . . . . . . . . . . . 25-12
Authorities and Locks . . . . . . . . . . . . . . . 24-13 Restrictions . . . . . . . . . . . . . . . . . . . . 25-12
Restrictions . . . . . . . . . . . . . . . . . . . . 24-13 Omissible Parameter Group . . . . . . . . . . . . 25-12
Omissible Parameter Group . . . . . . . . . . . . 24-13 Returned Value . . . . . . . . . . . . . . . . . . 25-13
Returned Value . . . . . . . . . . . . . . . . . . 24-14 Format of the Field Format Word . . . . . . . . . 25-13
Error Messages . . . . . . . . . . . . . . . . . . 24-14 Format of the Field Control Word . . . . . . . . . 25-16
Error Messages . . . . . . . . . . . . . . . . . . 25-17
Chapter 25. Screen Output APIs . . . . . . . . . 25-1 Set Output Address (QsnSetOutAdr) API . . . . . . 25-17
Screen Output APIs—Introduction . . . . . . . . . . 25-1 Authorities and Locks . . . . . . . . . . . . . . . 25-18
Delete Field ID Definition (QsnDltFldId) API . . . . . 25-1 Omissible Parameter Group . . . . . . . . . . . . 25-18
Authorities and Locks . . . . . . . . . . . . . . . 25-1 Returned Value . . . . . . . . . . . . . . . . . . 25-18
Required Parameter . . . . . . . . . . . . . . . . 25-1 Error Messages . . . . . . . . . . . . . . . . . . 25-18
Omissible Parameter . . . . . . . . . . . . . . . 25-1 Write Data (QsnWrtDta) API . . . . . . . . . . . . . 25-18
Returned Value . . . . . . . . . . . . . . . . . . 25-1 Restrictions . . . . . . . . . . . . . . . . . . . . 25-19
Error Messages . . . . . . . . . . . . . . . . . . 25-1 Authorities and Locks . . . . . . . . . . . . . . . 25-19
Generate a Beep (QsnBeep) API . . . . . . . . . . 25-2 Required Parameter Group . . . . . . . . . . . . 25-19
Authorities and Locks . . . . . . . . . . . . . . . 25-2 Omissible Parameter Group . . . . . . . . . . . . 25-19
Restrictions . . . . . . . . . . . . . . . . . . . . 25-2 Returned Value . . . . . . . . . . . . . . . . . . 25-20
Omissible Parameter Group . . . . . . . . . . . . 25-2 Error Messages . . . . . . . . . . . . . . . . . . 25-20
Returned Value . . . . . . . . . . . . . . . . . . 25-2 Write Structured Field Major (QsnWrtSFMaj) API . . 25-21
Error Messages . . . . . . . . . . . . . . . . . . 25-2 Authorities and Locks . . . . . . . . . . . . . . . 25-21
Insert Cursor (QsnInsCsr) API . . . . . . . . . . . . 25-2 Restrictions . . . . . . . . . . . . . . . . . . . . 25-21
Authorities and Locks . . . . . . . . . . . . . . . 25-3 Required Parameter Group . . . . . . . . . . . . 25-21
Restrictions . . . . . . . . . . . . . . . . . . . . 25-3 Omissible Parameter Group . . . . . . . . . . . . 25-21
Omissible Parameter Group . . . . . . . . . . . . 25-3 Returned Value . . . . . . . . . . . . . . . . . . 25-22
Returned Value . . . . . . . . . . . . . . . . . . 25-3 Error Messages . . . . . . . . . . . . . . . . . . 25-22
Error Messages . . . . . . . . . . . . . . . . . . 25-3 Write Structured Field Minor (QsnWrtSFMin) API . . 25-22
Pad between Two Screen Addresses (QsnWrtPadAdr) Authorities and Locks . . . . . . . . . . . . . . . 25-23
API . . . . . . . . . . . . . . . . . . . . . . . . . 25-4 Restrictions . . . . . . . . . . . . . . . . . . . . 25-23
Authorities and Locks . . . . . . . . . . . . . . . 25-4 Required Parameter Group . . . . . . . . . . . . 25-23
Restrictions . . . . . . . . . . . . . . . . . . . . 25-4 Omissible Parameter Group . . . . . . . . . . . . 25-23
Required Parameter Group . . . . . . . . . . . . 25-4 Returned Value . . . . . . . . . . . . . . . . . . 25-23
Omissible Parameter Group . . . . . . . . . . . . 25-4 Error Messages . . . . . . . . . . . . . . . . . . 25-23
Returned Value . . . . . . . . . . . . . . . . . . 25-5 Write to Display (QsnWTD) API . . . . . . . . . . . 25-23
Error Messages . . . . . . . . . . . . . . . . . . 25-5 Authorities and Locks . . . . . . . . . . . . . . . 25-24
Pad for N Positions (QsnWrtPad) API . . . . . . . . 25-5 Required Parameter Group . . . . . . . . . . . . 25-24
Authorities and Locks . . . . . . . . . . . . . . . 25-6 Omissible Parameter Group . . . . . . . . . . . . 25-24
Restrictions . . . . . . . . . . . . . . . . . . . . 25-6 Returned Value . . . . . . . . . . . . . . . . . . 25-24
Required Parameter Group . . . . . . . . . . . . 25-6 Error Messages . . . . . . . . . . . . . . . . . . 25-24
Omissible Parameter Group . . . . . . . . . . . . 25-6 Write Transparent Data (QsnWrtTDta) API . . . . . 25-25
Returned Value . . . . . . . . . . . . . . . . . . 25-7 Authorities and Locks . . . . . . . . . . . . . . . 25-25
Error Messages . . . . . . . . . . . . . . . . . . 25-7 Restrictions . . . . . . . . . . . . . . . . . . . . 25-25
Put Output Command (QsnPutOutCmd) API . . . . . 25-7 Required Parameter Group . . . . . . . . . . . . 25-25
Authorities and Locks . . . . . . . . . . . . . . . 25-7 Omissible Parameter Group . . . . . . . . . . . . 25-25
Required Parameter . . . . . . . . . . . . . . . . 25-7 Returned Value . . . . . . . . . . . . . . . . . . 25-26
Omissible Parameter Group . . . . . . . . . . . . 25-7 Error Messages . . . . . . . . . . . . . . . . . . 25-26
Returned Value . . . . . . . . . . . . . . . . . . 25-8 Low-Level Services Examples . . . . . . . . . . . . 25-26
Error Messages . . . . . . . . . . . . . . . . . . 25-8 Low-Level Services Example—1 . . . . . . . . . 25-27
Set Cursor Address (QsnSetCsrAdr) API . . . . . . 25-8 Low-Level Services Example—2 . . . . . . . . . 25-27
Authorities and Locks . . . . . . . . . . . . . . . 25-8 Low-Level Services Example—3 . . . . . . . . . 25-27
Restrictions . . . . . . . . . . . . . . . . . . . . 25-8 Low-Level Services Example—4 . . . . . . . . . 25-29
Omissible Parameter Group . . . . . . . . . . . . 25-9 Performance Considerations . . . . . . . . . . . . . 25-29
Returned Value . . . . . . . . . . . . . . . . . . 25-9 Limitations and Restrictions . . . . . . . . . . . . . 25-30

AS/400 System API Reference V4R4

 DSM

Chapter 26. Introduction to the Window Services Authorities and Locks . . . . . . . . . . . . . . . 27-12
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 26-1 Required Parameter . . . . . . . . . . . . . . . . 27-12
Omissible Parameter Group . . . . . . . . . . . . 27-12
Chapter 27. Window Manipulation and Query APIs 27-1 Returned Value . . . . . . . . . . . . . . . . . . 27-12
Window Manipulation and Query APIs—Introduction 27-1 Error Messages . . . . . . . . . . . . . . . . . . 27-12
Change Window (QsnChgWin) API . . . . . . . . . 27-1 Retrieve Window Description (QsnRtvWinD) API . . 27-12
Authorities and Locks . . . . . . . . . . . . . . . 27-1 Authorities and Locks . . . . . . . . . . . . . . . 27-13
Required Parameter Group . . . . . . . . . . . . 27-1 Required Parameter Group . . . . . . . . . . . . 27-13
Omissible Parameter . . . . . . . . . . . . . . . 27-1 Omissible Parameter . . . . . . . . . . . . . . . 27-13
Returned Value . . . . . . . . . . . . . . . . . . 27-2 Returned Value . . . . . . . . . . . . . . . . . . 27-13
Error Messages . . . . . . . . . . . . . . . . . . 27-2 Format of the Window Description Returned . . . 27-13
Create a Window (QsnCrtWin) API . . . . . . . . . . 27-2 Field Descriptions . . . . . . . . . . . . . . . . . 27-13
Authorities and Locks . . . . . . . . . . . . . . . 27-2 Error Messages . . . . . . . . . . . . . . . . . . 27-13
Required Parameter Group . . . . . . . . . . . . 27-2 Set Window Services Attributes (QsnSetWinAtr) API 27-13
Omissible Parameter Group . . . . . . . . . . . . 27-2 Authorities and Locks . . . . . . . . . . . . . . . 27-14
Returned Value . . . . . . . . . . . . . . . . . . 27-3 Required Parameter Group . . . . . . . . . . . . 27-14
Restrictions . . . . . . . . . . . . . . . . . . . . 27-3 Omissible Parameter . . . . . . . . . . . . . . . 27-14
Format of the Window Description . . . . . . . . 27-3 Returned Value . . . . . . . . . . . . . . . . . . 27-14
Field Descriptions . . . . . . . . . . . . . . . . . 27-4 Format of the Window Services Attribute
Format of the Window User Extension Information 27-6 Description . . . . . . . . . . . . . . . . . . . . 27-14
Field Descriptions . . . . . . . . . . . . . . . . . 27-6 Field Descriptions . . . . . . . . . . . . . . . . . 27-14
Window Exit Routines . . . . . . . . . . . . . . . 27-6 Error Messages . . . . . . . . . . . . . . . . . . 27-14
Exit Routine Error Handling . . . . . . . . . . . . 27-7
Change Window Exit Routine . . . . . . . . . 27-7 Chapter 28. Window I/O APIs . . . . . . . . . . . 28-1
Delete Window Exit Routine . . . . . . . . . . 27-7 Window I/O APIs—Introduction . . . . . . . . . . . . 28-1
Change Window Coordinates Exit Routine . . 27-7 Clear Window (QsnClrWin) API . . . . . . . . . . . 28-1
Draw Window Exit Routine . . . . . . . . . . . 27-7 Authorities and Locks . . . . . . . . . . . . . . . 28-1
Current Window Exit Routine . . . . . . . . . 27-8 Required Parameter . . . . . . . . . . . . . . . . 28-1
Error Messages . . . . . . . . . . . . . . . . . . 27-8 Omissible Parameter . . . . . . . . . . . . . . . 28-1
Initialize Window Description (QsnInzWinD) API . . . 27-8 Returned Value . . . . . . . . . . . . . . . . . . 28-1
Authorities and Locks . . . . . . . . . . . . . . . 27-8 Error Messages . . . . . . . . . . . . . . . . . . 28-1
Required Parameter Group . . . . . . . . . . . . 27-8 Clear Window Message (QsnClrWinMsg) API . . . . 28-1
Omissible Parameter Group . . . . . . . . . . . . 27-8 Authorities and Locks . . . . . . . . . . . . . . . 28-2
Returned Value . . . . . . . . . . . . . . . . . . 27-9 Required Parameter . . . . . . . . . . . . . . . . 28-2
Error Messages . . . . . . . . . . . . . . . . . . 27-9 Omissible Parameter . . . . . . . . . . . . . . . 28-2
Move Window (QsnMovWin) API . . . . . . . . . . . 27-9 Returned Value . . . . . . . . . . . . . . . . . . 28-2
Authorities and Locks . . . . . . . . . . . . . . . 27-9 Error Messages . . . . . . . . . . . . . . . . . . 28-2
Required Parameter Group . . . . . . . . . . . . 27-9 Display Window (QsnDspWin) API . . . . . . . . . . 28-2
Omissible Parameter . . . . . . . . . . . . . . . 27-9 Authorities and Locks . . . . . . . . . . . . . . . 28-2
Returned Value . . . . . . . . . . . . . . . . . . 27-9 Required Parameter . . . . . . . . . . . . . . . . 28-2
Error Messages . . . . . . . . . . . . . . . . . . 27-9 Omissible Parameter . . . . . . . . . . . . . . . 28-2
Move Window by User (QsnMovWinUsr) API . . . . 27-9 Returned Value . . . . . . . . . . . . . . . . . . 28-3
Authorities and Locks . . . . . . . . . . . . . . . 27-10 Error Messages . . . . . . . . . . . . . . . . . . 28-3
Required Parameter . . . . . . . . . . . . . . . . 27-10 Put Window Message (QsnPutWinMsg) API . . . . . 28-3
Omissible Parameter . . . . . . . . . . . . . . . 27-10 Authorities and Locks . . . . . . . . . . . . . . . 28-3
Returned Value . . . . . . . . . . . . . . . . . . 27-10 Required Parameter . . . . . . . . . . . . . . . . 28-3
Error Messages . . . . . . . . . . . . . . . . . . 27-10 Omissible Parameter Group . . . . . . . . . . . . 28-3
Resize Window (QsnRszWin) API . . . . . . . . . . 27-10 Returned Value . . . . . . . . . . . . . . . . . . 28-4
Authorities and Locks . . . . . . . . . . . . . . . 27-10 Error Messages . . . . . . . . . . . . . . . . . . 28-4
Required Parameter Group . . . . . . . . . . . . 27-10
Omissible Parameter . . . . . . . . . . . . . . . 27-11 Chapter 29. Window Manager Services APIs . . . 29-1
Returned Value . . . . . . . . . . . . . . . . . . 27-11 Window Manager Services APIs—Introduction . . . 29-1
Error Messages . . . . . . . . . . . . . . . . . . 27-11 End a Window (QsnEndWin) API . . . . . . . . . . 29-1
Resize Window by User (QsnRszWinUsr) API . . . . 27-11 Authorities and Locks . . . . . . . . . . . . . . . 29-1
Authorities and Locks . . . . . . . . . . . . . . . 27-11 Required Parameter . . . . . . . . . . . . . . . . 29-1
Required Parameter . . . . . . . . . . . . . . . . 27-11 Omissible Parameter Group . . . . . . . . . . . . 29-1
Omissible Parameter . . . . . . . . . . . . . . . 27-11 Returned Value . . . . . . . . . . . . . . . . . . 29-1
Returned Value . . . . . . . . . . . . . . . . . . 27-12 Error Messages . . . . . . . . . . . . . . . . . . 29-1
Error Messages . . . . . . . . . . . . . . . . . . 27-12 Retrieve Current Window (QsnRtvCurWin) API . . . 29-2
Retrieve Window Data (QsnRtvWinDta) API . . . . . 27-12 Authorities and Locks . . . . . . . . . . . . . . . 29-2

Part 9. Dynamic Screen Manager APIs

DSM

Omissible Parameter Group . . . . . . . . . . . . 29-2 Display Scroller Bottom (QsnDspSclB) API . . . . . 31-8
Returned Value . . . . . . . . . . . . . . . . . . 29-2 Authorities and Locks . . . . . . . . . . . . . . . 31-8
Error Messages . . . . . . . . . . . . . . . . . . 29-2 Required Parameter . . . . . . . . . . . . . . . . 31-8
Set Current Window (QsnSetCurWin) API . . . . . . 29-2 Omissible Parameter . . . . . . . . . . . . . . . 31-8
Authorities and Locks . . . . . . . . . . . . . . . 29-2 Returned Value . . . . . . . . . . . . . . . . . . 31-8
Required Parameter . . . . . . . . . . . . . . . . 29-2 Error Messages . . . . . . . . . . . . . . . . . . 31-9
Omissible Parameter . . . . . . . . . . . . . . . 29-2 Display Scroller Top (QsnDspSclT) API . . . . . . . 31-9
Returned Value . . . . . . . . . . . . . . . . . . 29-3 Authorities and Locks . . . . . . . . . . . . . . . 31-9
Error Messages . . . . . . . . . . . . . . . . . . 29-3 Required Parameter . . . . . . . . . . . . . . . . 31-9
Start a Window (QsnStrWin) API . . . . . . . . . . . 29-3 Omissible Parameter . . . . . . . . . . . . . . . 31-9
Authorities and Locks . . . . . . . . . . . . . . . 29-3 Returned Value . . . . . . . . . . . . . . . . . . 31-9
Required Parameter . . . . . . . . . . . . . . . . 29-3 Error Messages . . . . . . . . . . . . . . . . . . 31-9
Omissible Parameter Group . . . . . . . . . . . . 29-3 Initialize Session Description (QsnInzSsnD) API . . . 31-9
Returned Value . . . . . . . . . . . . . . . . . . 29-3 Authorities and Locks . . . . . . . . . . . . . . . 31-9
Error Messages . . . . . . . . . . . . . . . . . . 29-3 Required Parameter Group . . . . . . . . . . . . 31-10
Performance Considerations . . . . . . . . . . . . . 29-4 Omissible Parameter . . . . . . . . . . . . . . . 31-10
Creating/Manipulating Windows Example . . . . . . 29-4 Returned Value . . . . . . . . . . . . . . . . . . 31-10
Error Messages . . . . . . . . . . . . . . . . . . 31-10
Chapter 30. Introduction to the Session Services Query If Scroller in Line Wrap Mode (QsnQrySclWrp)
APIs . . . . . . . . . . . . . . . . . . . . . . . . . 30-1 API . . . . . . . . . . . . . . . . . . . . . . . . . 31-10
Session Services APIs—Introduction . . . . . . . . . 30-1 Authorities and Locks . . . . . . . . . . . . . . . 31-10
Session Details . . . . . . . . . . . . . . . . . . . . 30-1 Required Parameter . . . . . . . . . . . . . . . . 31-10
Line Mode and Character Mode I/O . . . . . . . . 30-1 Omissible Parameter Group . . . . . . . . . . . . 31-10
Command Key Action Routines . . . . . . . . . . . 30-1 Returned Value . . . . . . . . . . . . . . . . . . 31-10
Action Routine Parameters . . . . . . . . . . . . 30-2 Error Messages . . . . . . . . . . . . . . . . . . 31-10
Active Position . . . . . . . . . . . . . . . . . . . . 30-2 Retrieve Number of Columns to Shift Scroller
EBCDIC Display Control Characters . . . . . . . . . 30-3 (QsnRtvSclNumShf) API . . . . . . . . . . . . . . 31-11
DBCS Considerations . . . . . . . . . . . . . . . . 30-3 Authorities and Locks . . . . . . . . . . . . . . . 31-11
Required Parameter . . . . . . . . . . . . . . . . 31-11
Chapter 31. Session Manipulation and Query APIs 31-1 Omissible Parameter Group . . . . . . . . . . . . 31-11
Session Manipulation and Query APIs—Introduction 31-1 Returned Value . . . . . . . . . . . . . . . . . . 31-11
Change Session (QsnChgSsn) API . . . . . . . . . 31-1 Error Messages . . . . . . . . . . . . . . . . . . 31-11
Authorities and Locks . . . . . . . . . . . . . . . 31-1 Retrieve Number of Rows to Roll Scroller
Required Parameter Group . . . . . . . . . . . . 31-1 (QsnRtvSclNumRoll) API . . . . . . . . . . . . . . 31-11
Omissible Parameter . . . . . . . . . . . . . . . 31-1 Authorities and Locks . . . . . . . . . . . . . . . 31-12
Returned Value . . . . . . . . . . . . . . . . . . 31-2 Required Parameter . . . . . . . . . . . . . . . . 31-12
Error Messages . . . . . . . . . . . . . . . . . . 31-2 Omissible Parameter Group . . . . . . . . . . . . 31-12
Clear Scroller (QsnClrScl) API . . . . . . . . . . . . 31-2 Returned Value . . . . . . . . . . . . . . . . . . 31-12
Authorities and Locks . . . . . . . . . . . . . . . 31-2 Error Messages . . . . . . . . . . . . . . . . . . 31-12
Required Parameter . . . . . . . . . . . . . . . . 31-2 Retrieve Session Data (QsnRtvSsnDta) API . . . . . 31-12
Omissible Parameter Group . . . . . . . . . . . . 31-2 Authorities and Locks . . . . . . . . . . . . . . . 31-12
Returned Value . . . . . . . . . . . . . . . . . . 31-2 Required Parameter . . . . . . . . . . . . . . . . 31-12
Error Messages . . . . . . . . . . . . . . . . . . 31-2 Omissible Parameter Group . . . . . . . . . . . . 31-12
Create a Session (QsnCrtSsn) API . . . . . . . . . . 31-2 Returned Value . . . . . . . . . . . . . . . . . . 31-12
Authorities and Locks . . . . . . . . . . . . . . . 31-3 Error Messages . . . . . . . . . . . . . . . . . . 31-13
Required Parameter Group . . . . . . . . . . . . 31-3 Retrieve Session Description (QsnRtvSsnD) API . . 31-13
Omissible Parameter Group . . . . . . . . . . . . 31-3 Authorities and Locks . . . . . . . . . . . . . . . 31-13
Returned Value . . . . . . . . . . . . . . . . . . 31-4 Required Parameter Group . . . . . . . . . . . . 31-13
Format of the Session Description . . . . . . . . 31-4 Omissible Parameter . . . . . . . . . . . . . . . 31-13
Field Descriptions . . . . . . . . . . . . . . . . . 31-4 Returned Value . . . . . . . . . . . . . . . . . . 31-13
Format of the Session User Extension Data . . . 31-6 Format of the Session Description Returned . . . 31-13
Field Descriptions . . . . . . . . . . . . . . . . . 31-6 Error Messages . . . . . . . . . . . . . . . . . . 31-13
Session Exit Routines . . . . . . . . . . . . . . 31-6 Roll Scroller Down (QsnRollSclDown) API . . . . . . 31-14
Change Session Exit Routine . . . . . . . . . 31-6 Authorities and Locks . . . . . . . . . . . . . . . 31-14
Delete Session Exit Routine . . . . . . . . . . 31-7 Required Parameter . . . . . . . . . . . . . . . . 31-14
Change Session Coordinates Exit Routine . . 31-7 Omissible Parameter Group . . . . . . . . . . . . 31-14
Exit Routine Error Handling . . . . . . . . . . . . 31-7 Returned Value . . . . . . . . . . . . . . . . . . 31-14
Draw Session Exit Routine . . . . . . . . . . 31-7 Error Messages . . . . . . . . . . . . . . . . . . 31-14
Current Session Exit Routine . . . . . . . . . 31-8 Roll Scroller Up (QsnRollSclUp) API . . . . . . . . . 31-14
Error Messages . . . . . . . . . . . . . . . . . . 31-8 Authorities and Locks . . . . . . . . . . . . . . . 31-15

AS/400 System API Reference V4R4

 DSM

Required Parameter . . . . . . . . . . . . . . . . 31-15 Returned Value . . . . . . . . . . . . . . . . . . 32-3

Omissible Parameter Group . . . . . . . . . . . . 31-15 Error Messages . . . . . . . . . . . . . . . . . . 32-3
Returned Value . . . . . . . . . . . . . . . . . . 31-15 Print Scroller Data (QsnPrtScl) API . . . . . . . . . 32-3
Error Messages . . . . . . . . . . . . . . . . . . 31-15 Authorities and Locks . . . . . . . . . . . . . . . 32-4
Shift Scroller Left (QsnShfSclL) API . . . . . . . . . 31-15 Required Parameter . . . . . . . . . . . . . . . . 32-4
Authorities and Locks . . . . . . . . . . . . . . . 31-15 Omissible Parameter . . . . . . . . . . . . . . . 32-4
Required Parameter . . . . . . . . . . . . . . . . 31-15 Returned Value . . . . . . . . . . . . . . . . . . 32-4
Omissible Parameter Group . . . . . . . . . . . . 31-15 Error Messages . . . . . . . . . . . . . . . . . . 32-4
Returned Value . . . . . . . . . . . . . . . . . . 31-15 Read Data from Session (QsnReadSsnDta) API . . 32-4
Error Messages . . . . . . . . . . . . . . . . . . 31-16 Authorities and Locks . . . . . . . . . . . . . . . 32-4
Shift Scroller Right (QsnShfSclR) API . . . . . . . . 31-16 Required Parameter Group . . . . . . . . . . . . 32-4
Authorities and Locks . . . . . . . . . . . . . . . 31-16 Omissible Parameter Group . . . . . . . . . . . . 32-5
Required Parameter . . . . . . . . . . . . . . . . 31-16 Returned Value . . . . . . . . . . . . . . . . . . 32-5
Omissible Parameter Group . . . . . . . . . . . . 31-16 Error Messages . . . . . . . . . . . . . . . . . . 32-5
Returned Value . . . . . . . . . . . . . . . . . . 31-16 Retrieve Session Line to Input Line (QsnRtvSsnLin)
Error Messages . . . . . . . . . . . . . . . . . . 31-16 API . . . . . . . . . . . . . . . . . . . . . . . . . 32-5
Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) Authorities and Locks . . . . . . . . . . . . . . . 32-5
API . . . . . . . . . . . . . . . . . . . . . . . . . 31-16 Required Parameter . . . . . . . . . . . . . . . . 32-5
Authorities and Locks . . . . . . . . . . . . . . . 31-17 Omissible Parameter . . . . . . . . . . . . . . . 32-5
Required Parameter . . . . . . . . . . . . . . . . 31-17 Returned Value . . . . . . . . . . . . . . . . . . 32-5
Omissible Parameter Group . . . . . . . . . . . . 31-17 Error Messages . . . . . . . . . . . . . . . . . . 32-6
Returned Value . . . . . . . . . . . . . . . . . . 31-17 Start New Scroller Line at Current Position (QsnSclLF)
Error Messages . . . . . . . . . . . . . . . . . . 31-17 API . . . . . . . . . . . . . . . . . . . . . . . . . 32-6
Authorities and Locks . . . . . . . . . . . . . . . 32-6
Chapter 32. Session I/O APIs . . . . . . . . . . . 32-1 Required Parameter . . . . . . . . . . . . . . . . 32-6
Session I/O APIs—Introduction . . . . . . . . . . . . 32-1 Omissible Parameter . . . . . . . . . . . . . . . 32-6
Backspace on Scroller Line (QsnSclBS) API . . . . . 32-1 Returned Value . . . . . . . . . . . . . . . . . . 32-6
Authorities and Locks . . . . . . . . . . . . . . . 32-1 Error Messages . . . . . . . . . . . . . . . . . . 32-6
Required Parameter . . . . . . . . . . . . . . . . 32-1 Start New Scroller Page (QsnSclFF) API . . . . . . 32-6
Omissible Parameter . . . . . . . . . . . . . . . 32-1 Authorities and Locks . . . . . . . . . . . . . . . 32-6
Returned Value . . . . . . . . . . . . . . . . . . 32-1 Required Parameter . . . . . . . . . . . . . . . . 32-6
Error Messages . . . . . . . . . . . . . . . . . . 32-1 Omissible Parameter . . . . . . . . . . . . . . . 32-7
Go to Next Tab Position in Scroller Line (QsnSclTab) Returned Value . . . . . . . . . . . . . . . . . . 32-7
API . . . . . . . . . . . . . . . . . . . . . . . . . 32-2 Error Messages . . . . . . . . . . . . . . . . . . 32-7
Authorities and Locks . . . . . . . . . . . . . . . 32-2 Write Characters to Scroller (QsnWrtSclChr) API . . 32-7
Required Parameter . . . . . . . . . . . . . . . . 32-2 Authorities and Locks . . . . . . . . . . . . . . . 32-7
Omissible Parameter . . . . . . . . . . . . . . . 32-2 Required Parameter Group . . . . . . . . . . . . 32-7
Returned Value . . . . . . . . . . . . . . . . . . 32-2 Omissible Parameter . . . . . . . . . . . . . . . 32-7
Error Messages . . . . . . . . . . . . . . . . . . 32-2 Returned Value . . . . . . . . . . . . . . . . . . 32-7
Go to Start of Current Scroller Line (QsnSclCR) API 32-2 Error Messages . . . . . . . . . . . . . . . . . . 32-7
Authorities and Locks . . . . . . . . . . . . . . . 32-2 Write Line to Scroller (QsnWrtSclLin) API . . . . . . 32-8
Required Parameter . . . . . . . . . . . . . . . . 32-2 Authorities and Locks . . . . . . . . . . . . . . . 32-8
Omissible Parameter . . . . . . . . . . . . . . . 32-2 Required Parameter Group . . . . . . . . . . . . 32-8
Returned Value . . . . . . . . . . . . . . . . . . 32-3 Omissible Parameter . . . . . . . . . . . . . . . 32-8
Error Messages . . . . . . . . . . . . . . . . . . 32-3 Returned Value . . . . . . . . . . . . . . . . . . 32-8
Go to Start of Next Scroller Line (QsnSclNL) API . . 32-3 Error Messages . . . . . . . . . . . . . . . . . . 32-8
Authorities and Locks . . . . . . . . . . . . . . . 32-3 Performance Considerations . . . . . . . . . . . . . 32-8
Required Parameter . . . . . . . . . . . . . . . . 32-3 Create Session and Read Data—Example . . . . . . 32-9
Omissible Parameter . . . . . . . . . . . . . . . 32-3

Part 9. Dynamic Screen Manager APIs

DSM

AS/400 System API Reference V4R4

 Omitting Parameters

Chapter 20. Dynamic Screen Manager APIs—Introduction

Ÿ Session services
Dynamic Screen Manager
APIs—Introduction The session services APIs provide a general scrolling
interface that can be used to create, query, and manipu-
The Dynamic Screen Manager (DSM) APIs are a set of late sessions, and to perform input and output oper-
screen I/O interfaces that provide a dynamic way to create ations to sessions.
and manage screens for the Integrated Language Environ- Each group of DSM services APIs is discussed in detail in
ment (ILE) high-level languages. Because the DSM inter- the chapters that follow.
faces are bindable, they are accessible to ILE programs only.

The DSM APIs provide an alternative to the existing way of

defining screen appearance outside a program by coding in Data Structures for DSM APIs
DDS or UIM, for example. Instead, programmers can use a
Data structures for use with ILE C, ILE COBOL, and ILE
series of calls to DSM within their programs to dynamically
RPG/400 are available in the QSYSINC library in member
specify and control screen appearance for their applications.
QSNAPI for service program QSNAPI.
Unlike static definition methods, the DSM interfaces provide
the flexibility needed for those applications requiring more
dynamic screen control. The DSM support provided varies
from low-level interfaces for direct screen manipulation to Omitting Parameters with Associated
windowing support. Lengths
The DSM APIs fall into the following functional groups: To omit a parameter with an associated length parameter,
that length parameter should be omitted or specified as 0. If
Ÿ Low-level services
the length parameter is specified with a value greater than 0,
The low-level services APIs provide a direct interface to the parameter with which it is associated is required.
the 5250 data stream commands. These APIs are used
to query and manipulate the state of the screen; to For example, to omit the user extension information on the
create, query, and manipulate input and command low-level environment, specify either a NULL pointer by
buffers used to interact with the screen; and to define value, or 0 by reference for the length. The extension infor-
fields and write data to the screen. mation structure is ignored. If the length is greater than 0,
the extension information structure cannot be NULL. If it is,
Ÿ Window services
then a Required parameter omitted error is generated.
The window services APIs are used to create, delete,
move, and resize windows, and to manage multiple
windows during a session.

 Copyright IBM Corp. 1998, 1999 20-1

Omitting Parameters

20-2 AS/400 System API Reference V4R4

 DBCS Considerations

Chapter 21. Low-Level Screen I/O Services APIs

Low-Level Screen I/O Services Device Support

APIs—Introduction
The 5250 Query command is used to determine the valid
The low-level screen I/O services APIs provide a direct inter- commands for a particular device. This command is issued
face to the 5250 data stream commands and user-defined for the current device at the start of each DSM session and
data streams for performing basic screen I/O operations. For the information is saved for subsequent queries. If the 5250
detailed information about the results and interactions of Query command is not supported, the base data stream
these operations, refer to the following 5250 data stream support as documented in the 5250 Functions Reference is
documentation: assumed, with color and wide support being determined by
the device type.
Ÿ 5250 Functions Reference, SA21-9247
Ÿ 5494 Remote Control Unit Functions Reference,
SC30-3533 Operating Environments
The low-level services are divided into the following func- The low-level interfaces operate within an environment that
tional groups: can be defined using the Create Low-Level Environment
Ÿ Screen Manipulation and Query APIs are used to (QsnCrtEnv) API. The low-level environment defines the
query and manipulate the state of the screen. operating modes, such as DBCS support and the window
mode. The environment is passed as a parameter to most of
Ÿ Buffer Manipulation and Query APIs are used to
the low-level services APIs. There is no need to define a
create, query, and manipulate input and command
low-level environment unless you need a specific operating
buffers used to interact with the screen.
environment that is different from the default. The default
Ÿ Screen Input APIs are used to read field data and other low-level environment is indicated on the low-level service
information from the screen. APIs by specifying the environment handle as zero.
Ÿ Screen Output APIs are used to define fields and write
data and other information to the screen.
Direct and Indirect Operations

DSM Error Handling Many of the low-level APIs accept an optional command
buffer as a parameter. For such APIs, the command buffer
Calls to most of the interfaces can result in a direct I/O oper- can be used to store and accumulate a group of requested
ation, or in the storing of commands in a command buffer. operations. The accumulated operations can then be written
The command buffer provides a way of saving the com- to the screen in a single I/O operation. Better performance
mands so that multiple operations can be specified and per- can be achieved because a group of repetitive operations
formed in a single I/O operation. DSM performs error can be issued to the screen without having to re-invoke the
handling as much as possible prior to issuing an I/O opera- sequence of individual APIs for each repeated operation.
tion. For example, if a request is made to place the screen
A direct operation is one that omits the command buffer.
in wide mode, and the display does not support this mode,
The requested operation takes place immediately. For most
DSM detects and reports the error condition before per-
APIs, specifying the command buffer results in an indirect
forming an I/O operation. This way of handling errors is par-
operation. No I/O operation takes place and the operation
ticularly useful in the case where multiple commands have
is simply stored in the command buffer. Several of the
been saved in a buffer. Otherwise, there is no obvious way
screen input APIs, however, do perform a direct operation
to determine which command was in error when the I/O
when the command buffer is specified. This semantic is dis-
operation fails.
cussed in “Read Input Fields (QsnReadInp) API” on
The errors that can occur for each operation are listed with page 24-6.
the operation. If an error message indicates that the error is
issued for a negative response code, this means that the
error was not detected by DSM and occurred on the I/O DBCS Considerations
operation.
You can write DBCS data enclosed with SO/SI to the screen,
Note: When you are using the AS/400 TELNET display
and when the underlying display supports it, graphic DBCS
station emulation, an unsuccessful I/O operation may be
using the Write Data (QsnWrtDta) API to specify the data
undetected initially, but will be reported on the next opera-
stream Write Extended Attribute order. (See the 5250 data
tion.
stream documentation for further details.) You can define
fields as being DBCS through the Set Field (QsnSetFld) API

 Copyright IBM Corp. 1998, 1999 21-1

5250 Data Stream Details

using the appropriate field control word. DBCS data can be field, you must enclose the graphic DBCS data with SO/SI
written to such fields as described above. If you specify prior to calling the QsnWrtDta API.
DBCS support on the low-level environment description, (see
“Format of the Low-Level Environment Description” on
page 22-4), the APIs will handle the parsing of DBCS data 5250 Data Stream Details
and fields appropriately.

The APIs do not provide any special processing of DBCS AID-Generating Keys
data, such as adding SO/SI to DBCS graphic data when
graphic data is not supported by the display. For example, if The AID (attention indicator) code identifies to the host
you want to define a field as graphic DBCS and write graphic system the function being requested from the keyboard. The
DBCS data to it, code the QsnSetFld API specifying a control AID code is returned via certain input operations when the
word of QSN_FCS_DBCS_PURE (x'8220') and then write the operator presses an AID-generating key. Figure 21-1 lists
graphic data to a command buffer using the QsnWrtDta API. the AID-generating keys and the AID codes associated with
Precede and follow this data with Write Extended Attribute each key. See “Format of the Low-Level Environment
orders to add the extended NLS SO/SI attributes. If you Description” on page 22-4 for instructions on how to specify
want to write a graphic data value to a non-graphic DBCS an alternative help key.

Figure 21-1. AID Codes

AID key Mnemonic AID Code
Cmd 1 - 12 (cmd 1=x'31', cmd12=x'3C') QSN_F1 - QSN_F12 x'31' - x'3C'
Selector Light Pen Auto Enter QSN_SLP x'3F'
Forward Edge Trigger Auto Enter QSN_FET x'50'
PA1 QSN_PA1 x'6C'
PA2 QSN_PA2 x'6E'
PA3 QSN_PA3 x'6B'
Cmd 13 - 24 (cmd 13=x'B1', cmd24=x'BC') QSN_F13 - QSN_F24 x'B1' - x'BC'
Clear QSN_CLEAR x'BD'
Enter or Record Advance QSN_ENTER x'F1'
Help (not in error state) QSN_HELP x'F3'
Roll Down or Page Up QSN_ROLLDOWN or QSN_PAGEUP x'F4'
Roll Up or Page Down QSN_ROLLUP or QSN_PAGEDOWN x'F5'
Print QSN_PRINT x'F6'
Record Backspace QSN_RECBS x'F8'

Control Characters cessed immediately while the second CC is not processed

until all the other information associated with the API has
The display control characters (CCs) are always specified as been processed. When used with an input operation, both
a pair of 1-byte fields. They are used on the QsnWTD, CCs are processed after the operation has completed.
QsnReadInp, QsnReadMDT, and QsnReadMDTAlt APIs. Figure 21-2 and Figure 21-3 on page 21-3 list the valid
These characters select specific operations for the display control character values and their associated mnemonics.
station to perform. Byte 1 is always processed first. When
the CCs are used with the QsnWTD API, the first CC is pro-

Figure 21-2 (Page 1 of 2). Control Character Byte 1

Mnemonic Bits 0-2 Reset Clear Clear Null Nonby- Null All
Pending Master Master pass Fields Nonbypass
Aid; Lock MDT;Reset MDT;Reset with MDT Fields
Keyboard MDT Flags MDT Flags On
in Nonby- in All Fields
pass Fields
QSN_CC1_NULL 000
QSN_CC1_LOCKBD 001 x
QSN_CC1_MDTNBY 010 x x

21-2 AS/400 System API Reference V4R4

 5250 Data Stream Details

Figure 21-2 (Page 2 of 2). Control Character Byte 1

Mnemonic Bits 0-2 Reset Clear Clear Null Nonby- Null All
Pending Master Master pass Fields Nonbypass
Aid; Lock MDT;Reset MDT;Reset with MDT Fields
Keyboard MDT Flags MDT Flags On
in Nonby- in All Fields
pass Fields
QSN_CC1_MDTALL 011 x x
QSN_CC1_CLRMOD 100 x x
QSN_CC1_MDTNBY_CLRALL 101 x x x
QSN_CC1_MDTNBY_CLRMOD 110 x x x
QSN_CC1_MDTALL_CLRALL 111 x x x
Note:
1. Bits 3 through 7 are reserved and must be 0. A CPFA31C error will be issued if this is not the case.
2. If there are no bypass fields with MDT flags on, then the master MDT will be cleared.

Figure 21-3. Control Character Byte 2

Mnemonic Bit Meaning
0 reserved
QSN_CC2_NO_IC 1 0: Cursor moves to default or IC order position when keyboard unlocks
1: Cursor does not move when keyboard unlocks
QSN_CC2_RST_CSR_BL 2 0: no action
1: Reset blinking cursor
QSN_CC2_SET_CSR_BL 3 0: no action
1: Set blinking cursor
QSN_CC2_UNLOCKBD 4 0: no action
1: Unlock the keyboard and reset any pending AID bytes
QSN_CC2_ALARM 5 0: no action
1: Sound alarm
QSN_CC2_MSG_OFF 6 0: no action
1: Set Message Waiting indicator off
QSN_CC2_MSG_ON 7 0: no action
1: Set Message Waiting indicator on
Notes:
Ÿ The mnemonics for control character byte 2 can be combined with a bitwise OR operation.
Ÿ See notes in the 5250 data stream documentation for further details regarding these functions.

Screen Attribute Characters displays are shown in Figure 21-4 and for color displays in
Figure 21-5 on page 21-4. There are certain operations that
The screen or field attributes control the image produced on allow a value to be specified for a screen attribute that indi-
the display station screen. Each attribute occupies one char- cates no screen attribute should be used. Where supported,
acter position in the display station regeneration buffer and is the value is X'00' and the mnemonic is QSN_NO_SA.
displayed as a blank. The effect produced by an attribute
begins at its location in the regeneration buffer and continues
until the next attribute appears. The attributes for non-color

Figure 21-4 (Page 1 of 2). Screen Attributes for Non-Color Displays

Mnemonic Bits Value
QSN_SA_NORM 0-2 001: Attribute identification flag

Chapter 21. Low-Level Screen I/O Services APIs 21-3

5250 Data Stream Details

Figure 21-4 (Page 2 of 2). Screen Attributes for Non-Color Displays

Mnemonic Bits Value
QSN_SA_CS 3 0: Column separator off
1: Column separator on
QSN_SA_BL 4 0: Do not blink field
1: Blink field
QSN_SA_UL 5 0: Do not underscore field
1: Underscore field
QSN_SA_HI 6 0: Low intensity
1: High intensity
QSN_SA_RI 7 0: Normal image
1: Reverse image
QSN_SA_ND Non-display: equivalent to specifying QSN_SA_UL, QSN_SA_HI, and QSN_SA_RI.
Note: Multiple functions can be selected by combining the mnemonics with a logical OR operation.

Figure 21-5 (Page 1 of 2). Screen Attributes for Color Displays

Mnemonic Value Meaning
QSN_SA_GRN x'20' Green
QSN_SA_GRN_RI x'21' Green/Reverse Image
QSN_SA_WHT x'22' White
QSN_SA_WHT_RI x'23' White/Reverse Image
QSN_SA_GRN_UL x'24' Green/Underscore
QSN_SA_GRN_UL_RI x'25' Green/Underscore/Reverse Image
QSN_SA_WHT_UL x'26' White/Underscore
QSN_SA_ND x'27' Nondisplay
QSN_SA_RED x'28' Red
QSN_SA_RED_RI x'29' Red/Reverse Image
QSN_SA_RED_BL x'2A' Red/Blink
QSN_SA_RED_RI_BL x'2B' Red/Reverse Image/Blink
QSN_SA_RED_UL x'2C' Red/Underscore
QSN_SA_RED_UL_RI x'2D' Red/Underscore/Reverse Image
QSN_SA_RED_UL_BL x'2E' Red/Underscore/Blink
QSN_SA_ND_2F x'2F' Nondisplay
QSN_SA_TRQ_CS x'30' Turquoise/Column Separators
QSN_SA_TRQ_CS_RI x'31' Turquoise/Column Separators/Reverse Image
QSN_SA_YLW_CS x'32' Yellow/Column Separators
QSN_SA_YLW_CS_RI x'33' Yellow/Column Separators/Reverse Image
QSN_SA_TRQ_UL x'34' Turquoise/Underscore
QSN_SA_TRQ_UL_RI x'35' Turquoise/Underscore/Reverse Image
QSN_SA_YLW_UL x'36' Yellow/Underscore
QSN_SA_ND_37 x'37' Nondisplay
QSN_SA_PNK x'38' Pink
QSN_SA_PNK_RI x'39' Pink/Reverse Image
QSN_SA_BLU x'3A' Blue
QSN_SA_BLU_RI x'3B' Blue/Reverse Image

21-4 AS/400 System API Reference V4R4

 5250 Data Stream Details

Figure 21-5 (Page 2 of 2). Screen Attributes for Color Displays

Mnemonic Value Meaning
QSN_SA_PNK_UL x'3C' Pink/Underscore
QSN_SA_PNK_UL_RI x'3D' Pink/Underscore/Reverse Image
QSN_SA_BLU_UL x'3E' Blue/Underscore
QSN_SA_ND_3F x'3F' Nondisplay

Display Address Resequencing

The display address is the address at which data is dis- Resequencing allows the control unit to return up to 128
played or a field definition begins. This can be modified input fields in any specified order. Resequencing is accom-
explicitly with a Set Output Address (QsnSetOutAdr) call, or plished by chaining input fields together with Field Control
implicitly with output operations, such as those associated Words specifying resequencing. (See “Format of the Field
with the Write Data (QsnWrtDta) API, that accept a cursor Control Word” on page 25-16 and the 5250 data stream doc-
position. The 5250 Write to Display (WTD) command initial- umentation for details.)
izes the display address to row 1, column 1. Because each
output operation contains a WTD command, this means that
the display address is reset on each direct screen output
States and Modes
operation. The display station can be in one of several states (condi-
tions), each with its accompanying modes (methods of oper-
Insert Cursor Address ation). The following is a list of these states and their
associated modes:
The insert cursor (IC) order specifies the position of the
Ÿ Hardware error state
cursor when the host system unlocks the keyboard and when
the display station operator presses the Home key. The Ÿ Normal locked state
display address is not affected by this address. This can be Ÿ Normal unlocked state
set with the Insert Cursor (QsnInsCsr) API, and in some
– Command mode
cases with the Set Cursor Address (QsnSetCsrAdr) API (only
when the Move Cursor (MC) order is not supported). – Insert mode
– Data mode
Modified Data Tag (MDT) Bit Ÿ Power-on state
There is a modified data tag (MDT) bit for each input field Ÿ Prehelp error state
and a master MDT bit. These bits are used to determine Ÿ Post-help error state
which fields should be returned in response to the Read
Modified Fields (QsnReadMDT), Read Modified Alternate Ÿ System services (SS) message state
(QsnReadMDTAlt), and Read Modified Immediate Alternate Ÿ System request state
(QsnReadMDTImmAlt) APIs. The MDT bit for a field and the
master MDT bit can be set using bit 4 of the field format See the 5250 data stream documentation for a detailed
word (see “Format of the Field Format Word” on page 25-13) explanation of each state and mode.
on a Set Field (QsnSetFld) API. The master MDT bit and
the MDT bit for a field are set on anytime the operator types
Dumping the 5250 Data Stream Commands
into or alters a field on the display. Once the bits are set,
only a control character for resetting them (see Figure 21-2 If you wish to produce a dump of the 5250 data stream com-
on page 21-2), or a clear screen operation using the Clear mands that are produced by the DSM APIs, you should
Screen (QsnClrScr) API or a Start of Header order, can reset create a physical file (using the CRTPF command) having a
them. record length of 2000. Name the physical file QSNDEBUGF,
and ensure that the QSNDEBUGF file exists in the library
list. DSM will dump the 5250 data stream commands to that
file.

Chapter 21. Low-Level Screen I/O Services APIs 21-5

5250 Data Stream Details

21-6 AS/400 System API Reference V4R4

 Change Low-Level Environment (QsnChgEnv) API

Chapter 22. Screen Manipulation and Query APIs

Save Screen (QsnSavScr) saves the present display so it
Screen Manipulation and Query can be restored later.
APIs—Introduction Set Low-Level Environment Window Mode
(QsnSetEnvWinMod) sets the window mode
The screen manipulation and query APIs are used to query
for the low-level interface environment.
and manipulate the state of the screen and comprise the
following: The detailed API descriptions are presented in alphabetical
Change Low-Level Environment order.
(QsnChgEnv) changes the low-level environ-
ment description.
Clear Field Table Change Low-Level Environment
(QsnClrFldTbl) clears the format table but (QsnChgEnv) API
does not alter the display.
Clear Screen (QsnClrScr) clears the screen and sets the
screen size. Required Parameter Group:
Create Low-Level Environment
(QsnCrtEnv) creates the environment for the 1 Low-level environment Input Char(*)
low-level services APIs. description
Delete Low-Level Environment 2 Length of low-level envi- Input Binary(4)
(QsnDltEnv) deletes the environment for the ronment description
low-level services APIs.
Omissible Parameter Group:
Initialize Low-Level Environment Description
(QsnInzEnvD) initializes the low-level environ- 3 Low-level environment Input Binary(4)
ment description. handle
Query Color Support 4 Error Code I/O Char(*)
(QsnQryColorSup) determines if the display
device supports color. Returned Value:
Query Display Mode Support
Return code Output Binary(4)
(QsnQryModSup) queries if the display device
allows a given mode. Service Program: QSNAPI
Query 5250 (QsnQry5250) returns the results of the 5250
Query command. Threadsafe: No
Restore Screen
(QsnRstScr) restores the contents of a screen
saved with Save Screen (QsnSavScr) API. The Change Low-Level Environment (QsnChgEnv) API
Retrieve Display Mode changes the description for the given low-level environment.
(QsnRtvMod) queries the current device The Change Low-Level Environment exit routine will be
mode. called if specified on the user extension information of the
Retrieve Low-Level Environment Description Create Low-Level Environment (QsnCrtEnv) API.
(QsnRtvEnvD) retrieves the low-level environ-
ment description. Authorities and Locks
Retrieve Low-Level Environment User Data
(QsnRtvEnvDta) returns a pointer to the user Display file authority
data for the low-level environment. *USE
Retrieve Low-Level Environment Window Mode Display file library authority
(QsnRtvEnvWinMod) retrieves the low-level *USE
interface environment window mode descrip- Exit routine authority
tion. *EXECUTE
Retrieve Screen Dimensions
(QsnRtvScrDim) retrieves the screen dimen- Required Parameter Group
sions.
Roll Down (QsnRollDown) rolls the screen down by the Low-level environment description
given number of rows. INPUT; CHAR(*)
Roll Up (QsnRollUp) rolls the screen up by the given The new environment description for the given environ-
number of rows. ment. The format of this parameter is shown in “Format

 Copyright IBM Corp. 1998, 1999 22-1

Clear Field Table (QsnClrFldTbl) API

of the Low-Level Environment Description” on

page 22-4. Omissible Parameter Group:
Length of low-level environment description
1 Command buffer handle Input Binary(4)
INPUT; Binary(4) 2 Low-level environment Input Binary(4)
The length of the low-level environment description handle
parameter. The value specified must be 16, 36 or 38. 3 Error code I/O Char(*)

Returned Value:
Omissible Parameter Group
Return code Output Binary(4)
Low-level environment handle
INPUT; BINARY(4) Service Program: QSNAPI
The low-level environment to be modified. If this param- Threadsafe: No
eter is omitted or specified as 0, the default low-level
environment is used.
The Clear Field Table (QsnClrFldTbl) API erases the con-
Error code tents of the format table without affecting the display station
I/O; CHAR(*) screen. This allows for example, all input field definitions to
The structure in which to return error information. For be erased from the screen without altering the physical
the format of the structure, see “Error Code Parameter” appearance of the screen.
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. This command corresponds directly to the 5250 Clear Format
Table command. See the 5250 data stream documentation
for details.
Returned Value
Return code Authorities and Locks
OUTPUT; BINARY(4)
None
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
or -1 otherwise. Omissible Parameter Group
Command buffer handle
Error Messages INPUT; BINARY(4)
CPF24B4 E Severe error while addressing parameter list. If this parameter is omitted or specified as 0, this is a
CPF3C1D E direct operation and the format table is cleared imme-
Length specified in parameter &1 not valid. diately. Otherwise, this is an indirect operation and the
CPF3CF1 E command is stored in the command buffer without an I/O
Error code parameter not valid. operation taking place.
CPF3CF2 E
Error(s) occurred during running of &1 API. Low-level environment handle
CPFA318 E Error calling exit routine. INPUT; BINARY(4)
CPFA31E E The low-level environment that the operation applies to.
Required parameter &1 omitted. If this parameter is omitted or given with a value of zero,
CPFA327 E Low level environment description value incor- the default low-level environment is used.
rect.
CPFA334 E Low level environment handle incorrect. Error code
CPFA344 E The file &2 in library &3 is not valid. I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Clear Field Table (QsnClrFldTbl) API on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value
Return code
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The

22-2 AS/400 System API Reference V4R4

 Clear Screen (QsnClrScr) API

value returned will be 0 if the operation was successful, Mode

or -1 otherwise. INPUT; CHAR(1)
The mode to place the screen in after the screen is
Error Messages cleared. If this parameter is omitted, a value of 0 is
assumed. The possible values are:
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E 0 Indicates that the current screen size
Error code parameter not valid. should be kept. For indirect operations
CPF3CF2 E where this value is specified, the subse-
Error(s) occurred during running of &1 API. quent clear operation will be based on the
CPFA301 E Command buffer is full. current screen size, not on whatever size
CPFA303 E Error occurred for screen I/O operation. the screen is when the command buffer is
CPFA304 E Data-stream error &1 reported for screen I/O ultimately written out. The current display
operation. size will be determined using the
CPFA305 E Cannot add operation to command buffer. QsnRtvMod interface.
CPFA331 E Buffer handle incorrect. 3 Set screen to 24x80 mode.
CPFA334 E Low level environment handle incorrect. 4 Set screen to 27x132 mode. This value
CPFA343 E Output operation not done. is not supported by all devices. A
CPFA344 E The file &2 in library &3 is not valid. CPFA306 error will occur if an attempt is
CPFA345 E The invite active flag is not valid. made to specify this value with a device
that does not support it.

Command buffer handle

Clear Screen (QsnClrScr) API INPUT; BINARY(4)
If this parameter is omitted or specified as 0, this is a
Omissible Parameter Group: direct operation and the screen is cleared immediately.
Otherwise, this is an indirect operation and the
1 Mode Input Char(1) command is stored in the command buffer without an I/O
2 Command buffer handle Input Binary(4) operation taking place.
3 Low-level environment Input Binary(4)
handle Low-level environment handle
4 Error code I/O Char(*) INPUT; BINARY(4)

Returned Value: The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
Return code Output Binary(4) the default low-level environment is used.

Service Program: QSNAPI Error code

I/O; CHAR(*)
Threadsafe: No The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
The Clear Screen (QsnClrScr) API clears the screen and on page 2-6. If this parameter is omitted, diagnostic
sets the screen size to the specified mode. This command and escape messages are issued to the application.
corresponds directly to the 5250 Clear Unit or Clear Unit
Alternate command, depending upon the current screen Returned Value
presentation size. See the 5250 data stream documentation
for details. Return code
OUTPUT; BINARY(4)

Authorities and Locks A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
None or -1 otherwise.

Restrictions Error Messages

CPF24B4 E Severe error while addressing parameter list.
If this is an indirect operation, it must be the first command in
CPF3CF1 E
the command buffer.
Error code parameter not valid.
CPF3CF2 E
Omissible Parameter Group Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full.

Chapter 22. Screen Manipulation and Query APIs 22-3

Create Low-Level Environment (QsnCrtEnv) API

CPFA303 E Error occurred for screen I/O operation. Low-level environment description
CPFA304 E Data-stream error &1 reported for screen I/O INPUT; CHAR(*)
operation.
The environment description for the low-level interfaces.
CPFA306 E Command not supported by current device.
The format of this parameter is shown in “Format of the
CPFA321 E Operation not first command in command
Low-Level Environment Description.”
buffer.
CPFA322 E Incorrect display mode &1 specified. Length of low-level environment description
CPFA331 E Buffer handle incorrect. INPUT; Binary(4)
CPFA334 E Low level environment handle incorrect.
The length of the low-level environment description
CPFA343 E Output operation not done.
parameter. The value specified must be 16, 36, or 38.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
Omissible Parameter Group
User extension information
Create Low-Level Environment INPUT; CHAR(*)
(QsnCrtEnv) API
The user extension information is used to associate data
and exit routines with the low-level environment. This
essentially enables the object-oriented programming
Required Parameter Group:
concept of inheritance, allowing the low-level environ-
1 Low-level environment Input Char(*) ment to be extended in a natural way. The user exten-
description sion information cannot be changed once the
2 Length of low-level envi- Input Binary(4) environment has been created. The format of this
ronment description parameter is shown in “Format of the Low-Level User
Environment Extension Information” on page 22-5.
Omissible Parameter Group:
User extension information length
3 User Extension Informa- Input Char(*) INPUT; BINARY(4)
tion
4 Length of user extension Input Binary(4) The length of the user extension information parameter.
information If this parameter is specified with a zero value, the user
5 Low-level environment Output Binary(4) extension information parameter is ignored. If a non-
handle zero value is specified, it must be 48 and the user exten-
6 Error Code I/O Char(*) sion parameter is required.
Returned Value: Low-level environment handle
OUTPUT; BINARY(4)
Low-level environment Output Binary(4)
handle The low-level environment that is created as a result of
this operation. This handle can be used across acti-
Service Program: QSNAPI vation groups if the activation group in which the handle
was created is still active.
Threadsafe: No
Error code
I/O; CHAR(*)
The Create Low-Level Environment (QsnCrtEnv) API creates
an operating environment for low-level interface routines. The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Authorities and Locks and escape messages are issued to the application.
Display file authority
*USE Returned Value
Display file library authority
*USE Low-level environment handle
Exit routine authority OUTPUT; BINARY(4)
*EXECUTE The value for parameter 5 is returned. If an error occurs
during processing, returns -1.
Required Parameter Group
Format of the Low-Level Environment
Description

22-4 AS/400 System API Reference V4R4

 Create Low-Level Environment (QsnCrtEnv) API

This field specifies whether the DSM low-level routines are to

Offset
check for X'3F' in the data to be displayed and perform any
Dec Hex Type Field conversions if necessary. Conversion will be performed for
0 0 CHAR(1) Color support both direct and indirect operations on data output through the
1 1 CHAR(1) Character conversion QsnWrtDta and QsnWrtTDta APIs, and input through the
QsnReadInp, QsnReadMDT, QsnReadMDTAlt,
2 2 CHAR(1) CDRA conversions to 0x3F QsnReadMDTAlt, QsnReadImm, and QsnReadMDTImmAlt
3 3 CHAR(1) DBCS support APIs.
4 4 CHAR(1) Coexistence
The default is convert if character conversion (see below) is
5 5 CHAR(1) Alternative help key support specified as convert. Otherwise, the default is standard.
6 6 CHAR(10) Target device (See “Limitations and Restrictions” on page 25-30 for further
16 10 CHAR(20) Display file
details.) The possible values for this field are:

36 24 CHAR(1) Invite active 0 Same: Keep the current setting.

1 Standard: Always display data as standard
37 25 CHAR(1) Prevent override
data with no replacement.
2 Convert: Always check for X'3F' in data and
convert to X'1F' before displaying the data
Format of the Low-Level User Environment and convert X'1F' in incoming data to X'3F'.
Extension Information
Character conversion. This field specifies whether CDRA
Offset conversion takes place on the data when the job CCSID
Dec Hex Type Field
does not match that of the display device. Conversion will
be performed for both direct and indirect operations on data
0 0 PTR(SPP) User data associated with output through the QsnWrtDta and QsnWrtTDta APIs, and
the environment
input through the QsnReadInp, QsnReadMDT,
16 10 PTR(PP) Exit routine to call when the QsnReadMDTAlt, QsnReadMDTAlt, QsnReadImm, and
low-level environment is QsnReadMDTImmAlt APIs.
changed
32 20 PTR(PP) Exit routine to call when the The CCSID for the display device is determined from the
low-level environment is CHRID of the device. The default is convert if the job CCSID
deleted does not match that of the underlying device; otherwise,
standard is the default. The possible values for this field are:
0 Same: Keep the current setting.
Field Descriptions 1 Standard: Do not perform conversion.
In the following descriptions, specifying the value Same indi- 2 Convert: If the job CCSID does not match that
cates the current value when using the Change Low-Level of the display device and neither has the
Environment (QsnChgEnv) API. The default value refers to value 65535, perform the appropriate conver-
the value set by the Initialize Low-Level Environment sion on outgoing and incoming data. (See
Description (QsnInzEnvD) API. “Limitations and Restrictions” on page 25-30
for further details.)
Alternative help key support. Specifies if the alternative
help key is used. The default is no alternative help key Coexistence. Whether DSM coexists with other screen I/O
support. methods, such as DDS- or UIM-coded interfaces, during the
course of this application. Better performance can be
The possible values for this field are: achieved if coexistence is not required; the DSM APIs can
assume the state of the device, for example, wide or normal
0 Same: Keep the current setting.
mode. The default is 2.
1 None: No alternative help key support is used.
QSN_F1 through QSN_F24 The possible values for this field are:
The specified key is the alternative help key.
See Figure 21-1 on page 21-2 for the values 0 Same: Keep the current setting.
that correspond to these mnemonics. When 1 Coexist: Other screen I/O methods are used
this key is pressed, the AID code for the Help in conjunction with DSM.
key will be returned. 2 Only: DSM is the only screen I/O method
being used.
CDRA conversions to X'3F'. When CDRA conversion takes
place, all characters not supported in the target CCSID are Color support. This field determines the color selection
converted to X'3F'. Sending data containing X'3F' to the used when both a monochrome and a color display attribute
display causes adverse effects. are supplied. The default is select.

Chapter 22. Screen Manipulation and Query APIs 22-5

Create Low-Level Environment (QsnCrtEnv) API

The possible values for this field are: see “Change Low-Level Environment Exit Routine” on
page 22-7. Specify NULL for this field if no exit routine is
0 Same: Keep the current setting.
required.
1 Mono: Always use the monochrome attributes
specified regardless of the underlying device
Exit routine to call when low-level environment deleted.
type.
Exit routine to call when the low-level environment is deleted
2 Color: Always use the color attributes speci-
through the QsnDltEnv API. The exit routine will be called
fied regardless of the underlying device type.
before the environment itself is deleted. For a description of
3 Select: Select the appropriate attribute based
the parameters passed to this routine, see “Delete Low-Level
on the underlying display type.
Environment Exit Routine” on page 22-7. Specify NULL for
this field if no exit routine is required.
DBCS support. This field specifies whether the data being
sent to the display contains DBCS data. This field affects,
Invite active. This field determines whether each write that
for example, how data is handled within sessions. For
is sent out causes the device to be invited. After the device
devices that do not support DBCS data, the default is
is invited, the user is able to enter data, but the application
standard; for DBCS-capable devices, it is mixed. If a value
can continue processing instead of waiting for input. When
other than standard is specified for a device that does not
the application is ready for the input, it can call
support DBCS data, a CPFA306 error will occur.
QsnReadInvited, which will issue a read from invited device
operation.
The possible values for this field are:
0 Same: Keep the current setting. The invite active flag is ignored by the read APIs, like
1 Standard: Always handle data as single-byte QsnReadMDT. If the operation is indirect, then the read
characters. command will be added to the command buffer. This
2 Only: Data contains double-byte characters command buffer can be passed into the QsnReadInvited API,
only. SO/SI control characters must enclose where it will be sent out before the read from invited device
the data; these are not implicitly added. is done. If the operation is direct, then the read command
3 Either: Data contains either double-byte or will be sent in a data stream to the device. The new data
single-byte characters, but not both. SO/SI stream will cause the invite to be retracted. A read with wait
control characters must enclose the DBCS will be performed.
part of the data, unless a graphic DBCS value
is passed. In this case, extended ideographic If the display file value is specified for the environment, the
attributes must enclose the data, which can be INVITE keyword must be specified on the USRRCD record of
written using the QsnWrtDta API (see “Write the specified display file.
Data (QsnWrtDta) API” on page 25-18).
The timeout value for the read from invited device operation
4 Mixed: Data may contain both single- and
can be controlled, by supplying a display file for the environ-
double-byte characters. All double-byte char-
ment. The WAITRCD parameter on the CRTDSPF
acter strings within the data must be enclosed
command can be set to the desired timeout value. See the
by SO/SI control characters. Graphic DBCS
return value for the QsnReadInvited API to determine the
data must be enclosed by extended
return value if the read from invited device operation times
ideographic attributes as described for the
out.
preceding value.
The possible values for this field are:
Display file. The name of the display file to be used. The
first 10 characters contain the file name, and the last 10 0 Same: Keep the current setting.
characters contain the library name. By specifying a display 1 Not active: The INVITE keyword, if specified in
file, you can, for example, direct the input/output of different the display file, will be ignored. A normal read
DSM environments to different devices, and you can specify of the device will be performed.
the restore display parameter on the display file at creation 2 Active: Any request to get data from the
time. The default for this field is blanks, which indicate that display will result in a read from invited device
the system-supplied display file should be used. being issued.
For more information on invite processing, see
If a file name is specified, the file must contain a record
the Application Display Programming book.
named USRRCD. This record must have the USRDFN
keyword specified.
Prevent override. This field determines whether the display
file used by DSM can be overridden or not. This value is
Exit routine to call when low-level environment changed.
ignored if the display file value is not specified.
Exit routine to call when the low-level environment is
changed through the QsnChgEnv or QsnSetEnvWinMod API.
The possible values for this field are:
For a description of the parameters passed to this routine,
0 Same: Keep the current setting.

22-6 AS/400 System API Reference V4R4

 Delete Low-Level Environment (QsnDltEnv) API

1 Do not prevent override: When opened, the Delete Low-Level Environment Exit Routine Parameter
display file will allow overrides. For create
Low-level environment handle
and initialize operations, this is the default.
INPUT; BINARY(4)
2 Prevent overrides: When the display file is
opened, the flag to block overrides will be set. A handle for the environment that was deleted.

User data associated with the environment. A pointer to

any data the user wants to associate with this environment. Error Messages
This field can be used by the programmer to attach informa- CPF24B4 E Severe error while addressing parameter list.
tion to the low-level environment that can be of any format. CPF3C1D E
For example, if multiple environments are being used, a list Length specified in parameter &1 not valid.
of the fields currently defined in an environment could be CPF3CF1 E
associated with the environment through this pointer. Error code parameter not valid.
Specify NULL for this field if you do not have any user data. CPF3CF2 E
Error(s) occurred during running of &1 API.
Target device. The program device name of the target CPFA314 E Memory allocation error.
display device for the environment. This parameter must be CPFA31E E
specified with a value of *REQUESTER, which is the default. Required parameter &1 omitted.
CPFA327 E Low level environment description value incor-
Exit Routine Error Handling rect.
CPFA344 E The file &2 in library &3 is not valid.
If an exception occurs during the processing of an exit
routine, the exception is ignored and processing continues.
A CPFA318 will be issued as a diagnostic message only. Delete Low-Level Environment
You can explicitly handle errors in an exit routine by adding (QsnDltEnv) API
an exception handler to the routine.

Change Low-Level Environment Exit Required Parameter:

Routine 1 Low-level environment Input Binary(4)
handle
This exit routine, if specified on the user extension informa-
tion, is called after the environment is changed through the Omissible Parameter:
QsnChgEnv or QsnSetEnvWinMod API. The following
parameter is passed to the exit routine: 2 Error Code I/O Char(*)

Returned Value:
1 Low-level environment Input Binary(4)
handle Return code Output Binary(4)

Service Program: QSNAPI

Change Low-Level Environment Exit Routine Parameter Threadsafe: No
Low-level environment handle
INPUT; BINARY(4) The Delete Low-Level Environment (QsnDltEnv) API deallo-
A handle for the environment that was changed. cates an operating environment for low-level interface rou-
tines.

Delete Low-Level Environment Exit

Routine Authorities and Locks
This exit routine, if specified on the user extension informa- None
tion, is called before the environment is deleted. The fol-
lowing parameter is passed to the exit routine: Required Parameter
Low-level environment handle
1 Low-level environment Input Binary(4) INPUT; BINARY(4)
handle
The low-level environment to be deallocated.

Chapter 22. Screen Manipulation and Query APIs 22-7

Initialize Low-Level Environment Description (QsnInzEnvD) API

Omissible Parameter Environment Description” on page 22-4, pointer fields are set
to the null pointer, numeric fields to 0, character flag fields to
Error code 0, and other character fields to blanks. For example, the
I/O; CHAR(*) default value for the color support field is 3, so this field will
The structure in which to return error information. For be set to 3.
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Authorities and Locks
and escape messages are issued to the application.
Display file authority
*USE
Returned Value Display file library authority
*USE
Return code
Exit routine authority
OUTPUT; BINARY(4)
*EXECUTE
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
or -1 otherwise. Required Parameter Group
Low-level environment description
Error Messages OUTPUT; CHAR(*)

CPF24B4 E Severe error while addressing parameter list. The low-level environment description to be initialized.
CPF3CF1 E Length of low-level environment description
Error code parameter not valid. INPUT; Binary(4)
CPF3CF2 E
Error(s) occurred during running of &1 API. The length of the low-level environment description
CPFA317 E Cannot deallocate memory dynamically. parameter. This parameter must be specified as 16, 36
CPFA318 E Error calling exit routine. or 38.
CPFA31E E
Required parameter &1 omitted. Omissible Parameter
CPFA334 E Low level environment handle incorrect.
Error code
I/O; CHAR(*)
Initialize Low-Level Environment The structure in which to return error information. For
Description (QsnInzEnvD) API the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Required Parameter Group:

1 Low-level environment Output Char(*) Returned Value

description
Return code
2 Length of low-level envi- Input Binary(4)
ronment description
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
Omissible Parameter: value returned will be 0 if the operation was successful,
or -1 otherwise.
3 Error code I/O Char(*)

Returned Value: Error Messages

Return code Output Binary(4) CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E
Service Program: QSNAPI Length specified in parameter &1 not valid.
CPF3CF1 E
Threadsafe: No
Error code parameter not valid.
CPF3CF2 E
The Initialize Low-Level Environment Description Error(s) occurred during running of &1 API.
(QsnInzEnvD) API initializes a low-level environment descrip- CPFA31E E
tion with default values. Unless otherwise specified in the Required parameter &1 omitted.
low-level environment description in “Format of the Low-Level CPFA344 E The file &2 in library &3 is not valid.

22-8 AS/400 System API Reference V4R4

 Query Display Mode Support (QsnQryModSup) API

Query Color Support (QsnQryColorSup) Error Messages

API CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Omissible Parameter Group: Error(s) occurred during running of &1 API.
1 Color indication Output Char(1) CPFA334 E Low level environment handle incorrect.
2 Low-level environment Input Binary(4)
handle
3 Error code I/O Char(*) Query Display Mode Support
Returned Value:
(QsnQryModSup) API
Color indication Output Binary(4)
Required Parameter:
Service Program: QSNAPI
1 Display mode Input Char(1)
Threadsafe: No
Omissible Parameter Group:

The Query Color Support (QsnQryColorSup) API determines 2 Mode indication Output Char(1)
whether the current display device supports color or not. 3 Low-level environment Input Binary(4)
handle
4 Error code I/O Char(*)
Authorities and Locks
Returned Value:
None
Mode indication Output Binary(4)

Omissible Parameter Group Service Program: QSNAPI

Color indication Threadsafe: No

OUTPUT; CHAR(1)
Whether the device supports color or not. This informa-
The Query Display Mode Support (QsnQryModSup) API
tion will be set based on the results of the 5250 Query
determines if the current display device supports the given
command, if the display supports it; otherwise, certain
mode. Certain devices, like the 3486 and 3487, support
defaults are assumed. See “Device Support” on
27x132 mode but can be switched by keystroke to turn off
page 21-1 for details. The possible values are:
the wide capability. This will be reflected in the result
0 Device does not support color returned by the QsnQryModSup API. Use this API to deter-
1 Device supports color mine if a subsequent mode change request through the
Clear Screen (QsnClrScr) API is valid. You can use the
Low-level environment handle result of the Query 5250 (QsnQry5250) API to determine if
INPUT; BINARY(4) the display is capable of supporting wide mode or not.
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
Authorities and Locks
the default low-level environment is used.
None
Error code
I/O; CHAR(*)
The structure in which to return error information. For Required Parameter
the format of the structure, see “Error Code Parameter” Display mode
on page 2-6. If this parameter is omitted, diagnostic INPUT; CHAR(1)
and escape messages are issued to the application.
The display mode for which to query support. The pos-
sible values are:
Returned Value
3 24x80 mode
Color indication 4 27x132 mode
OUTPUT; BINARY(4)
This API returns the value for the color indication param-
eter if successful, or -1 otherwise.

Chapter 22. Screen Manipulation and Query APIs 22-9

Query 5250 (QsnQry5250) API

Omissible Parameter Group

Required Parameter Group:
Mode indication
OUTPUT; CHAR(1) 1 Receiver variable Output Char(*)
Whether the device allows the specified mode or not. 2 Length of receiver vari- Input Binary(4)
able
The possible values are:

0 Device does not support the mode Omissible Parameter:

1 Device supports the mode
3 Error Code I/O Char(*)
Low-level environment handle
INPUT; BINARY(4) Returned Value:

The low-level environment that the operation applies to. Return code Output Binary(4)
If this parameter is omitted or given with a value of zero,
the default low-level environment is used. Service Program: QSNAPI

Error code Threadsafe: No

I/O; CHAR(*)
The structure in which to return error information. For The Query 5250 (QsnQry5250) API is used to retrieve the
the format of the structure, see “Error Code Parameter” results of the Query 5250 command for the current device.
on page 2-6. If this parameter is omitted, diagnostic The Query 5250 command returns device and controller attri-
and escape messages are issued to the application. butes for the current device, such as whether wide mode and
graphical user interface (GUI) are supported.
Returned Value
Mode indication
Authorities and Locks
OUTPUT; BINARY(4)
None
This API returns the value for the mode indication
parameter if successful, or -1 otherwise.
Restrictions
Error Messages This command is not supported by all control units. A query
status of 3 indicates if the query failed.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid. Required Parameter Group
CPF3CF2 E
Receiver variable
Error(s) occurred during running of &1 API.
OUTPUT; CHAR(*)
CPFA322 E Incorrect display mode &1 specified.
CPFA334 E Low level environment handle incorrect. The receiver variable that is to receive the result of the
query. You can specify that the size of the area be
smaller than the format requested as long as you specify
Query 5250 (QsnQry5250) API the length of the receiver variable parameter correctly.
As a result, the API returns only the data the area can
hold. The format of the data returned is shown in
“Format of the Query Data” on page 22-11.

Length of receiver variable

INPUT; BINARY(4)
The length of the receiver variable. If the length is larger
than the size of the receiver variable, the results are
unpredictable. The minimum length is 8 bytes.
The API returns as much information as it can fit in this
length. If the available information is longer, it is trun-
cated. If the available information is shorter, the unused
output is unchanged; whatever is already stored in that
space remains there. To determine how much informa-
tion the API actually returns in response to this call, see
the bytes returned field. To determine how much infor-

22-10 AS/400 System API Reference V4R4

 Query 5250 (QsnQry5250) API

mation the API could return if space were available, see

Offset
the bytes available field.
Dec Hex Type Field
69 45 CHAR(1) Invisible tags
Omissible Parameter
70 46 CHAR(2) Reserved
Error code
I/O; CHAR(*)
The structure in which to return error information. For Field Descriptions
the format of the structure, see “Error Code Parameter”
Further details on the fields listed can be found in the 5494
on page 2-6. If this parameter is omitted, diagnostic
Remote Control Unit Functions Reference manual.
and escape messages are issued to the application.
Bytes available. The number of bytes of data available to
Returned Value be returned. All available data is returned if enough space is
provided.
Return code
OUTPUT; BINARY(4) Bytes returned. The number of bytes of data returned.
A return code indicating the result of the operation. The Code Level. Identifies the code release level.
value returned will be 0 if the operation was successful,
or -1 otherwise. Control unit customization. Indicates customization
parameters for the control unit as:
Format of the Query Data Byte 0

Offset Ÿ Bit 0: Indicates that the AS/400 system can send a 5250
WSC Customization command when set on
Dec Hex Type Field
Ÿ Bit 1: Indicates that the AS/400 system can send a 5250
0 0 BINARY(4) Bytes returned
Query Station State command when set on
4 4 BINARY(4) Bytes available
Ÿ Bit 2: Indicates that the AS/400 system can send a 5250
8 8 CHAR(1) Query status Workstation Customization command to select the SBA
9 9 BINARY(2) Work station control unit code returned in READ commands for displays with
11 B CHAR(3) Code Level ideographic extended attributes when set on.

14 E CHAR(16) Reserved Ÿ Bit 3: Indicates that the 5250 Workstation Customization

command may be either 6 bytes or greater than 8 bytes
30 1E CHAR(1) Work station type code
in length when set on.
31 1F CHAR(4) Machine type code
Ÿ Bits 4–7: Reserved
35 23 CHAR(3) Model number
38 26 CHAR(1) Keyboard ID Byte 1: Reserved
39 27 CHAR(1) Extended keyboard ID Device capabilities. Defines the operating capabilities of
40 28 CHAR(1) PC keyboard ID the designated device as:
41 29 CHAR(4) Serial number
Byte 0
45 2D BINARY(2) Maximum input fields
Ÿ Bits 0–1: Indicate Row 1/Column 1 support as:
47 2F CHAR(2) Control unit customization
B'00' No support
48 30 CHAR(1) Reserved B'01' limited support
50 32 CHAR(12) Device capabilities
Ÿ Bit 2: Indicates the Read MDT Alternate command is
62 3E CHAR(1) Grid buffers supported when set on
63 3F CHAR(1) Type of grid line support Ÿ Bit 3: Indicates the work station and control unit have
64 40 CHAR(1) Reserved PA1 and PA2 support when set on
65 41 CHAR(1) Images or faxes Ÿ Bit 4: Indicates the work station and control unit have
66 42 CHAR(1) Image or fax scaling PA3 support when set on
granularity Ÿ Bit 5: Indicates the work station and control unit have
67 43 CHAR(1) Image or fax rotating cursor select support when set on
granularity
Ÿ Bit 6: Indicates the work station and control unit have
68 44 CHAR(1) Image or fax support move cursor order support when set on

Chapter 22. Screen Manipulation and Query APIs 22-11

Query 5250 (QsnQry5250) API

Ÿ Bit 7: Indicates the Read Modified Immediate Alternate B'001' 5292-style graphics
command is supported when set on B'010' GDDM-OS/2 Link Graphics
Ÿ Bit 3: Indicates extended 3270 data stream capability
Byte 1—display screen capabilities
when set on
Ÿ Bits 0–3: Define screen size as:
Ÿ Bit 4: Indicates a pointer device is available when set on
B'0001' 24 x 80
Ÿ Bit 5: Indicates that GUI-like characters are available
B'0011' 24 x 80 or 27 x 132
when set on
Ÿ Bit 4: Indicates selector light pen (SLP) is supported
Ÿ Bit 6: Indicates the control unit supports enhanced user
when set on
interface commands and field control words (FCWs)
Ÿ Bit 5: Indicates magnetic stripe reader (MSR) is sup- when set on.
ported when set on
The commands include:
Ÿ Bits 6–7: Define color support as:
Create Window
B'00' Monochrome display
B'01' Color support Unrestricted Cursor Movement
Remove GUI Window
Byte 2
Remove All GUI Constructs
Ÿ Bit 0: Indicates Text Symbols support when set on
Read Screen To Print
Ÿ Bit 1: Indicates work station and control unit have
extended primary attribute Read Screen To Print With Extended Attributes

Ÿ Bits 2–4: Indicate Office Editor/Text support as: Write Error Code To Window

B'000' No Office Editor/Text support Save Partial Screen

B'001' single language Office Editor/Text support Restore Partial Screen
B'010' dual language Office Editor/Text support
Define Selection Field
Ÿ Bit 5: Indicates work station and control unit have
Remove GUI Selection Field
extended primary attribute support in data processing
(DP) mode (WEA order) when set on Define Scroll Bar
Ÿ Bits 6–7: Indicates extended foreground color attribute Remove GUI Scroll Bar
support The FCWs include:
B'01' Available in DP mode. Fourteen colors Continued
are defined, but only seven are available.
The other seven colors are mapped into Cursor Progression
the available colors. Highlighted
B'10' Available in DP mode. Fourteen colors
Pointer Device Selection.
are supported.
Ÿ Bit 7: Indicates Write Error Code To Window command
Byte 3 is supported when set on
Ÿ Bits 0–2: Indicate ideographic capability as:
Byte 5
B'000' No ideographic capability
Ÿ Bit 0: Indicates the Write Data and Programmable
B'001' Ideographic capability for presentation
Mouse Buttons structured field commands, the Word
screen only
Wrap FCW, and Ideographic Continued entry fields are
B'010' Ideographic data type and presentation
supported when set on
screen ideographic capability
Ÿ Bit 1: Indicates this is a GUI device which will use all-
Ÿ Bits 3–5: Indicate bidirectional support as:
points-addressable constructs for windows, selection
B'000' No bidirectional capability fields, and scroll bars, when set on
B'001' Bidirectional capability
Ÿ Bits 2–7: Reserved
Ÿ Bits 6: Ideographic
Byte 6: Reserved
Ÿ Bits 7: Reserved
Bytes 7–8:
Byte 4
Ÿ Bit 0–13: Reserved
Ÿ Bits 0–2: Indicate graphics capability as:
Ÿ Bit 14–15: 5250 fax or image support
B'000' No graphics capability
B'00' No 5250 image or fax support

22-12 AS/400 System API Reference V4R4

 Query 5250 (QsnQry5250) API

B'01' Support for seven formats: X'01' Support for scaling percentages from 3% to
400%. No scroll-bar scaling, fill scaling, no
– TIFF
change scaling, increment and decrement
- No compression X'02–7E' Reserved
- CCITT Group 3 fax one- X'7F' Support for continuous scaling
dimensional, modified-Huffman X'80–FF' Reserved for use by 5250 PWS emulators
run-length encoding
Image or fax rotating granularity.
- CCITT Group 3 fax compression
X'00' No 5250 image or fax support
- CCITT Group 4 fax compression X'01' Support for rotating of 0, 90, 180, and 270
- PackBits run-length encoding degrees
X'02–7E' Reserved
– PCX monochrome format X'7F' Support for continuous rotation
– Stand-alone CCITT Group 3 fax com- X'80–FF' Reserved for use by 5250 PWS emulators
pression
Image or fax support.
B'11' Support for the seven previous formats,
plus five additional formats: X'00' No 5250 image or fax support
B'0' Pop-up and pull-down windows
– IOCA
that were written after image or
- IBM MMR algorithm fax are presented over image
or fax data when set on
- No compression
B'1' This device supports trans-
- CCITT Group 3 fax one- parent mode.
dimensional, modified-Huffman B'2–7' Reserved
run-length encoding
Invisible tags. Defines more device capabilities of the des-
- CCITT Group 3 fax compression
ignated device as:
- CCITT Group 4 fax compression
Ÿ Bits 0–5: Reserved

Byte 9: Reserved for use by PC emulators to indicate addi- Ÿ Bit 6: EBCDIC-to-ASCII translation. This is used by
tional 5250 image or fax formats supported workstation gateway devices.
Ÿ Bit 7: True transparency.
Byte 10:
Ÿ Bit 0: Indicates printer type as: Keyboard ID. Reserved. This field is set to X'00'.

B'0' SCS printer Machine type code. An EBCDIC code for the machine
B'1' IPDS printer type.
Ÿ Bits 1–7: Reserved
Maximum input fields. The maximum number of input
Byte 11: Reserved fields available (256).

Extended keyboard ID. The device code for extended 5250 Model number. An EBCDIC code for the machine model
keyboards. number.

Grid buffers. The number of grid buffers that are available PC keyboard ID. Device code for PC keyboards attached to
in the device. a 5250 work station (X'00' for nonprogrammable work
stations).
X'00' Not grid-capable.
Query status. The status of the 5250 query data. The pos-
Images or faxes. The number of images or faxes that can
sible values are:
be presented on a display screen.
DSM_5250Q_YES (1)
X'00' No 5250 image or fax support
Query information successfully retrieved.
X'01–FE' Number allowed
DSM_5250Q_NO (2)
X'FF' Variable, dependent on the size of the image
Query cannot be issued for the device. This
or fax
occurs when the device configuration specifies
that the query command should not be issued
Image or fax scaling granularity.
against the device.
X'00' No 5250 image or fax support DSM_5250Q_FAIL (3)
Query command failed. Default values are
supplied based on the device type. This

Chapter 22. Screen Manipulation and Query APIs 22-13

Restore Screen (QsnRstScr) API

occurs, for example, when the controller does commands can be added to the command buffer subject to
not support the query command. the conditions described in “Restrictions.”

Reserved. An ignored field. This command corresponds directly to the 5250 Restore
Screen or Restore Partial Screen command. See the 5250
Serial number. Field for device serial number. This field is data stream documentation for details.
set to zero for a work station with no serial number.

Type of grid line support. Authorities and Locks

X'00' No grid line support None
X'01' Type 1 grid line support including support for
grid line commands
Restrictions
Work station control unit. The type of control unit.
This command must be the last command in the command
Work station type code. The workstation type. The value buffer except when GUI support is used. In this case, other
is X'01' for display station. input commands may follow.

Error Messages Required Parameter

CPF24B4 E Severe error while addressing parameter list. Input buffer containing saved data
CPF3C24 E INPUT; BINARY(4)
Length of the receiver variable is not valid.
CPF3CF1 E An input buffer that contains the result of an indirect
Error code parameter not valid. QsnSavScr operation. The data will be copied from this
CPF3CF2 E input buffer and used for the restore screen operation.
Error(s) occurred during running of &1 API.
CPFA31E E Omissible Parameter Group
Required parameter &1 omitted.
Command buffer handle
INPUT; BINARY(4)
Restore Screen (QsnRstScr) API If this parameter is omitted or specified as 0, this is a
direct operation and the screen is restored immediately.
Otherwise, this is an indirect operation and the
Required Parameter: command is stored in the command buffer without an I/O
operation taking place.
1 Input buffer containing Input Binary(4)
saved data Low-level environment handle
INPUT; BINARY(4)
Omissible Parameter Group:
The low-level environment that the operation applies to.
2 Command buffer handle Input Binary(4) If this parameter is omitted or given with a value of zero,
3 Low-level environment Input Binary(4) the default low-level environment is used.
handle
4 Error code I/O Char(*) Error code
I/O; CHAR(*)
Returned Value:
The structure in which to return error information. For
Return code Output Binary(4) the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Service Program: QSNAPI and escape messages are issued to the application.

Threadsafe: No
Returned Value
The Restore Screen (QsnRstScr) API restores the state of Return code
the display as saved with an indirect command. The display OUTPUT; BINARY(4)
will be restored using the data contained in the input buffer A return code indicating the result of the operation. The
given by parameter 1. If an indirect operation is specified, value returned will be 0 if the operation was successful,
the resulting command buffer will contain the Restore Screen or -1 otherwise.
command and the data to restore the screen. Additional

22-14 AS/400 System API Reference V4R4

 Retrieve Low-Level Environment Description (QsnRtvEnvD) API

Error Messages Error code

I/O; CHAR(*)
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E The structure in which to return error information. For
Error code parameter not valid. the format of the structure, see “Error Code Parameter”
CPF3CF2 E on page 2-6. If this parameter is omitted, diagnostic
Error(s) occurred during running of &1 API. and escape messages are issued to the application.
CPFA301 E Command buffer is full.
CPFA303 E Error occurred for screen I/O operation. Returned Value
CPFA304 E Data-stream error &1 reported for screen I/O
operation. Display mode
CPFA305 E Cannot add operation to command buffer. OUTPUT; CHAR(1)
CPFA316 E Saved data not valid. This API returns the value for the display mode param-
CPFA31E E eter, or 0 if an error occurs during processing.
Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect. Error Messages
CPFA343 E Output operation not done. CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid.
Retrieve Display Mode (QsnRtvMod) API CPF3CF2 E
Error(s) occurred during running of &1 API.
CPFA322 E Incorrect display mode &1 specified.
Omissible Parameter Group: CPFA334 E Low level environment handle incorrect.

1 Display mode Output Char(1)

2 Low-level environment Input Binary(4)
handle Retrieve Low-Level Environment
3 Error code I/O Char(*) Description (QsnRtvEnvD) API
Returned Value:

Display mode Output Char(1)

Required Parameter Group:

1 Low-level environment Output Char(*)

Service Program: QSNAPI description
2 Length of low-level envi- Input Binary(4)
Threadsafe: No ronment description

Omissible Parameter Group:

The Retrieve Display Mode (QsnRtvMod) API returns the
current display mode. 3 Low-level environment Input Binary(4)
handle
4 Error code I/O Char(*)
Authorities and Locks
Returned Value:
None
Return code Output Binary(4)

Omissible Parameter Group Service Program: QSNAPI

Display mode
Threadsafe: No
OUTPUT; CHAR(1)
The current display mode. The possible values are:
The Retrieve Low-Level Environment Description
3 Device is in 24x80 mode (QsnRtvEnvD) API returns the description corresponding to
4 Device is in 27x132 mode the specified low-level environment.
Low-level environment handle
INPUT; BINARY(4) Authorities and Locks
The low-level environment that the operation applies to.
None
If this parameter is omitted or given with a value of zero,
the default low-level environment is used.

Chapter 22. Screen Manipulation and Query APIs 22-15

Retrieve Low-Level Environment User Data (QsnRtvEnvDta) API

Required Parameter Group Offset

Low-level environment description Dec Hex Type Field

Output; CHAR(*) 8 8 CHAR(*) Environment description
The variable that contains the low-level environment The format of the remaining
description when the QsnRtvEnvD API has completed. data returned is shown in
The format of the data returned is shown in “Format of “Format of the Low-Level
the Data Returned.” Environment Description” on
page 22-4.
Length of low-level environment description
INPUT; Binary(4)
The length of the low-level environment description
Error Messages
parameter. The minimum length is 8. If the length is CPF24B4 E Severe error while addressing parameter list.
larger than the size of the receiver variable, the results CPF3C24 E
are not predictable. The API returns as much informa- Length of the receiver variable is not valid.
tion as it can fit in this length. It the available informa- CPF3CF1 E
tion is longer, it is truncated. If the available information Error code parameter not valid.
is shorter, the unused output is unchanged; whatever is CPF3CF2 E
already stored in that space remains there. To deter- Error(s) occurred during running of &1 API.
mine how much information the API actually returns in CPFA31E E
response to this call, see the bytes returned field. To Required parameter &1 omitted.
determine how much information the API could return if CPFA334 E Low level environment handle incorrect.
space were available, see the bytes available field.

Omissible Parameter Group Retrieve Low-Level Environment User Data

(QsnRtvEnvDta) API
Low-level environment handle
INPUT; BINARY(4)
The low-level environment for which the description Required Parameter:
should be retrieved. If this parameter is omitted or spec-
1 Low-level environment Input Binary(4)
ified as 0, the description for the default low-level envi-
handle
ronment is retrieved.

Error code Omissible Parameter Group:

I/O; CHAR(*) 2 User data pointer Output PTR(SPP)
The structure in which to return error information. For 3 Error code I/O Char(*)
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Returned Value:
and escape messages are issued to the application. User data pointer Output PTR(SPP)

Service Program: QSNAPI

Returned Value
Return code Threadsafe: No
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The The Retrieve Low-Level Environment User Data
value returned will be 0 if the operation was successful, (QsnRtvEnvDta) API returns a pointer to the user data for the
or -1 otherwise. given low-level environment.

Format of the Data Returned Authorities and Locks

Offset None

Dec Hex Type Field

0 0 BINARY(4) Bytes returned Required Parameter
4 4 BINARY(4) Bytes available Low-level environment handle
INPUT; BINARY(4)
A handle for the low-level environment for which the

22-16 AS/400 System API Reference V4R4

 Retrieve Low-Level Environment Window Mode (QsnRtvEnvWinMod) API

user data should be returned. If this parameter is omitted

or specified as 0, the default low-level environment is Required Parameter Group:
used.
1 Window mode description Output Char(*)
2 Length of window mode Input Binary(4)
Omissible Parameter Group description
User data pointer
Omissible Parameter Group:
OUTPUT; PTR(SPP)
A pointer to the user data, as specified on the low-level 3 Low-level environment Input Binary(4)
handle
environment description, for the given low-level environ-
4 Error Code I/O Char(*)
ment.

Error code Returned Value:

I/O; CHAR(*)
Return code Output Binary(4)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Service Program: QSNAPI
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Threadsafe: No

Returned Value The Retrieve Low-Level Environment Window Mode

(QsnRtvEnvWinMod) API queries the state of the window
User data pointer mode for the low-level interfaces.
OUTPUT; PTR(SPP)
This API returns the value for the user data pointer Authorities and Locks
parameter, or the null pointer if an error occurs.
None
Error Messages
CPF24B4 E Severe error while addressing parameter list. Required Parameter Group
CPF3C1F E Window mode description
Pointer is not on a 16 byte boundary. OUTPUT; CHAR(*)
CPF3CF1 E
Error code parameter not valid. The field in which the window mode description should
CPF3CF2 E be stored. The format of the data returned in this field is
Error(s) occurred during running of &1 API. described in “Format of the Data Returned” on
CPFA31E E page 22-18.
Required parameter &1 omitted. Length of window mode description
CPFA334 E Low level environment handle incorrect. INPUT; BINARY(4)
The length of the window mode description parameter.
If the length is larger than the size of the receiver vari-
Retrieve Low-Level Environment Window able, the results are not predictable. The minimum
Mode (QsnRtvEnvWinMod) API length is 8. The API returns as much information as it
can fit in this length. If the available information is
longer, it is truncated. If the available information is
shorter, the unused output is unchanged; whatever is
already stored in that space remains there. To deter-
mine how much information the API actually returns in
response to this call, see the bytes returned field. To
determine how much information the API could return if
space were available, see the bytes available field.

Omissible Parameter Group

Low-level environment handle
INPUT; BINARY(4)
The low-level environment that the operation applies to.

Chapter 22. Screen Manipulation and Query APIs 22-17

Retrieve Screen Dimensions (QsnRtvScrDim) API

If this parameter is omitted or given with a value of zero, CPFA31E E

the default low-level environment is used. Required parameter &1 omitted.
CPFA334 E Low level environment handle incorrect.
Error code
I/O; CHAR(*)
The structure in which to return error information. For Retrieve Screen Dimensions
the format of the structure, see “Error Code Parameter” (QsnRtvScrDim) API
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Omissible Parameter Group:
Returned Value
1 Number of rows Output Binary(4)
Return code 2 Number of columns Output Binary(4)
OUTPUT; BINARY(4) 3 Low-level environment Input Binary(4)
handle
A return code indicating the result of the operation. The 4 Error code I/O Char(*)
value returned will be 0 if the operation was successful,
or -1 otherwise. Returned Value:

Return code Output Binary(4)

Format of the Data Returned
Service Program: QSNAPI
Offset
Threadsafe: No
Dec Hex Type Field
0 0 BINARY(4) Bytes returned
The Retrieve Screen Dimensions (QsnRtvScrDim) API
4 4 BINARY(4) Bytes available retrieves the current dimensions of the screen. You must
8 8 CHAR(1) Window mode specify either the number-of-rows or the number-of-columns
9 9 CHAR(*) Window mode description parameter, or a CPFA31E message will be issued.

Authorities and Locks

Field Descriptions
None
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is
provided. Omissible Parameter Group
Bytes returned. The number of bytes of data returned. Number of rows
OUTPUT; BINARY(4)
Window mode. Whether window mode is enabled or disa- The current height of the screen. This information will
bled. The possible values are: be set based on the current display size.
0 Window mode is disabled.
Number of columns
1 Window mode is enabled.
OUTPUT; BINARY(4)
Window mode description. The format of the remaining The current width of the screen. This information will be
data returned is shown in “Format of the Window Mode set based on the current display size.
Description” on page 22-24.
Low-level environment handle
INPUT; BINARY(4)
Error Messages The low-level environment that the operation applies to.
CPF24B4 E Severe error while addressing parameter list. If this parameter is omitted or given with a value of zero,
CPF3C1D E the default low-level environment is used.
Length specified in parameter &1 not valid.
CPF3C24 E Error code
Length of the receiver variable is not valid. I/O; CHAR(*)
CPF3CF1 E The structure in which to return error information. For
Error code parameter not valid. the format of the structure, see “Error Code Parameter”
CPF3CF2 E on page 2-6. If this parameter is omitted, diagnostic
Error(s) occurred during running of &1 API. and escape messages are issued to the application.

22-18 AS/400 System API Reference V4R4

 Roll Down (QsnRollDown) API

Returned Value Restrictions

Return code The following considerations apply to the QsnRollDown API:
OUTPUT; BINARY(4)
Ÿ Lines vacated due to a roll are not cleared to nulls.
A return code indicating the result of the operation. The
Ÿ The command does not change the format table, and so,
value returned will be 0 if the operation was successful,
should be avoided when it could produce discrepancies
or -1 otherwise.
between the format table and the display.
Ÿ Data rolled out of the roll area are lost.
Error Messages
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Authorities and Locks
Error code parameter not valid.
None
CPF3CF2 E
Error(s) occurred during running of &1 API.
CPFA31E E Required Parameter Group
Required parameter &1 omitted.
Number of lines to roll
CPFA334 E Low level environment handle incorrect.
INPUT; BINARY(4)
The number of lines to roll the designated area down by.
Roll Down (QsnRollDown) API Top row of roll area
INPUT; BINARY(4)

Required Parameter Group: The line number defining the top line of the area that will
participate in the roll.
1 Number of lines to roll Input Binary(4)
2 Top row of roll area Input Binary(4) Bottom row of roll area
3 Bottom row of roll area Input Binary(4) INPUT; BINARY(4)
The line number defining the bottom line of the area that
Omissible Parameter Group: will participate in the roll.
4 Command buffer handle Input Binary(4)
5 Low-level environment Input Binary(4)
handle
Omissible Parameter Group
6 Error code I/O Char(*) Command buffer handle
INPUT; BINARY(4)
Returned Value:
If this parameter is omitted or specified as 0, this is a
Return code Output Binary(4) direct operation and the screen is rolled down imme-
diately. Otherwise, this is an indirect operation and the
Service Program: QSNAPI command is stored in the command buffer without an I/O
operation taking place.
Threadsafe: No
Low-level environment handle
INPUT; BINARY(4)
The Roll Down (QsnRollDown) API rolls the screen down a
given number of lines within the roll area specified. The fol- The low-level environment that the operation applies to.
lowing conditions cause a CPFA315 error to occur: If this parameter is omitted or given with a value of zero,
the default low-level environment is used.
Ÿ A top row of zero
Ÿ A bottom row greater than the number of display lines Error code
I/O; CHAR(*)
Ÿ A top row greater than or equal to the bottom row
The structure in which to return error information. For
Ÿ A roll area greater than the bottom row minus the top the format of the structure, see “Error Code Parameter”
row on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
This API corresponds directly to the 5250 Roll command.
See the 5250 data stream documentation for details.
Returned Value

Chapter 22. Screen Manipulation and Query APIs 22-19

Roll Up (QsnRollUp) API

Return code Authorities and Locks

OUTPUT; BINARY(4)
A return code indicating the result of the operation. The None
value returned will be 0 if the operation was successful,
or -1 otherwise. Required Parameter Group
Number of lines to roll
Error Messages INPUT; BINARY(4)
CPF24B4 E Severe error while addressing parameter list. The number of lines to roll the designated area up by.
CPF3CF1 E
Error code parameter not valid. Top row of roll area
CPF3CF2 E INPUT; BINARY(4)
Error(s) occurred during running of &1 API. The line number defining the top line of the area that will
CPFA301 E Command buffer is full. participate in the roll.
CPFA303 E Error occurred for screen I/O operation.
CPFA304 E Data-stream error &1 reported for screen I/O Bottom row of roll area
operation. INPUT; BINARY(4)
CPFA305 E Cannot add operation to command buffer. The line number defining the bottom line of the area that
CPFA315 E Roll parameters not valid. will participate in the roll.
CPFA31E E
Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect. Omissible Parameter Group
CPFA334 E Low level environment handle incorrect.
Command buffer handle
CPFA343 E Output operation not done.
INPUT; BINARY(4)
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. If this parameter is omitted or specified as 0, this is a
direct operation and the screen is rolled up immediately.
Otherwise, this is an indirect operation and the
Roll Up (QsnRollUp) API command is stored in the command buffer without an I/O
operation taking place.

Low-level environment handle

Required Parameter Group: INPUT; BINARY(4)
1 Number of lines to roll Input Binary(4) The low-level environment that the operation applies to.
2 Top row of roll area Input Binary(4) If this parameter is omitted or given with a value of zero,
3 Bottom row of roll area Input Binary(4) the default low-level environment is used.

Omissible Parameter Group: Error code

I/O; CHAR(*)
4 Command buffer handle Input Binary(4)
5 Low-level environment Input Binary(4) The structure in which to return error information. For
handle the format of the structure, see “Error Code Parameter”
6 Error code I/O Char(*) on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Returned Value:

Return code Output Binary(4) Returned Value

Service Program: QSNAPI Return code
OUTPUT; BINARY(4)
Threadsafe: No
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
or -1 otherwise.
Usage Notes
The Roll Up (QsnRollUp) API is identical in function to the Error Messages
QsnRollDown API, except the lines are rolled up instead of CPF24B4 E Severe error while addressing parameter list.
down. CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.

22-20 AS/400 System API Reference V4R4

 Save Screen (QsnSavScr) API

CPFA301 E Command buffer is full. Screen command. See the 5250 data stream documentation
CPFA303 E Error occurred for screen I/O operation. for details.
CPFA304 E Data-stream error &1 reported for screen I/O
operation.
CPFA305 E Cannot add operation to command buffer.
Authorities and Locks
CPFA315 E Roll parameters not valid. None
CPFA31E E
Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect. Restrictions
CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done. This command must be the last command in the command
CPFA344 E The file &2 in library &3 is not valid. buffer, except when GUI support is available. In this case,
CPFA345 E The invite active flag is not valid. other non-input commands may follow.

Omissible Parameter Group

Save Screen (QsnSavScr) API
Saved data command buffer handle
OUTPUT; BINARY(4)
Omissible Parameter Group: The variable that will contain the command buffer handle
for the restore screen operation if this is a direct opera-
1 Saved data command Output Binary(4) tion.
buffer handle
2 Command buffer handle Input Binary(4) For an indirect operation, the result of the save screen
3 Low-level environment Input Binary(4) will be returned in the input buffer of a subsequent input
handle operation, which can be used to restore the screen using
4 Error code I/O Char(*) the QsnRstScr operation.
Returned Value: Command buffer handle
INPUT; BINARY(4)
Saved data command Output Binary(4)
buffer handle If this parameter is omitted or specified as 0, this is a
direct operation and the screen is saved immediately.
Service Program: QSNAPI Otherwise, this is an indirect operation and the
command is stored in the command buffer without an I/O
Threadsafe: No operation taking place.

Low-level environment handle

The Save Screen (QsnSavScr) API saves the current state of INPUT; BINARY(4)
the display. If this is a direct operation, the API creates a
command buffer that contains the operations used to restore The low-level environment that the operation applies to.
the screen state and returns a handle for this buffer. When a If this parameter is omitted or given with a value of zero,
direct save screen operation is issued, the saved screen data the default low-level environment is used.
is returned in a command buffer. This command buffer con- Error code
tains the Restore Screen command along with the data to I/O; CHAR(*)
restore the screen. Additional commands can be added to
the command buffer as described in “Restrictions” on The structure in which to return error information. For
page 22-14 under the Restore Screen (QsnRstScr) API. the format of the structure, see “Error Code Parameter”
The screen can be restored by sending this command buffer on page 2-6. If this parameter is omitted, diagnostic
using the Put Command Buffer (QsnPutBuf) API. and escape messages are issued to the application.

When an indirect save screen operation is issued, the Save

Returned Value
Screen command is stored in the command buffer and is
considered an input operation. The command can be issued Saved data
to the screen only through the Put Command Buffer and OUTPUT; BINARY(4)
Perform Get (QsnPutGetBuf) API. The saved data will be
For a successful operation, this API returns the value for
returned in the input buffer parameter specified for the
the saved data parameter if this is a direct operation;
QsnPutGetBuf API. The screen can subsequently be
otherwise, it returns zero. For an unsuccessful opera-
restored by specifying this input buffer on the QsnRstScr
tion, it returns -1.
API.

This command corresponds directly to the 5250 Save Screen Error Messages
(when the underlying control unit supports it) or Save Partial

Chapter 22. Screen Manipulation and Query APIs 22-21

Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API

CPF24B4 E Severe error while addressing parameter list. error is issued for that particular API. If data or a field is
CPF3CF1 E written to the window that exceeds the window boundary, no
Error code parameter not valid. error condition occurs and the data or field is truncated.
CPF3CF2 E
Error(s) occurred during running of &1 API. The size of the logical window area can be determined
CPFA301 E Command buffer is full. through the Retrieve Low-Level Environment Window Mode
CPFA303 E Error occurred for screen I/O operation. (QsnRtvEnvWinMod) API. When window mode is enabled,
CPFA304 E Data-stream error &1 reported for screen I/O screen addresses must be explicitly specified for APIs such
operation. as the QsnWrtDta API in order for the address to be inter-
CPFA305 E Cannot add operation to command buffer. preted relative to the window area. If a screen address is
CPFA313 E Command buffer already contains an input not specified, the current display address will be used as an
operation. absolute screen address irrespective of the current window
CPFA314 E Memory allocation error. mode. This is because the current screen address is not
CPFA331 E Buffer handle incorrect. tracked by DSM, but is handled by the control unit.
CPFA334 E Low level environment handle incorrect.
When window mode is enabled, APIs where a cursor position
CPFA343 E Output operation not done.
is specified, such as the QsnSetFld API, issue a CPFA307
error if the given cursor position is outside the bounds of the
current window area. For APIs that return a cursor position,
Set Low-Level Environment Window Mode such as the Get Cursor Address (QsnGetCsrAdr) API, both
(QsnSetEnvWinMod) API the row and column returned will be -1 if the cursor screen
location is outside of the current window area, 0 if the cursor
is on the top or left border, or the number of screen rows or
Required Parameter: columns plus 1 if the cursor is on the bottom or right border
of the window area, respectively. The following low-level
1 Enable window mode Input Char(1)
APIs are affected by the window mode:
Omissible Parameter Group: QsnRtvReadAdr

2 Previous window mode Output Char(1) QsnRtvFldInf

setting QsnGetCsrAdr
3 Window mode description Input Char(*)
4 Length of window mode Input Binary(4) QsnGetCsrAdrAID
description QsnSetOutAdr
5 Low-level environment Input Binary(4)
handle QsnWrtDta
6 Error Code I/O Char(*)
QsnWrtSFMaj
Returned Value: QsnWrtTDta

Return code Output Binary(4) QsnWrtExtAtr

QsnWrtPad
Service Program: QSNAPI
QsnWrtPadAdr
Threadsafe: No QsnSetFld
QsnSetCsrAdr
The Set Low-Level Environment Window Mode
QsnInsCsr
(QsnSetEnvWinMod) API enables or disables the window
mode for the low-level environment. Use this API to affect QsnSetErr
how row and cursor positions specified on low-level interface
operations are interpreted for operations to the given low- The actual screen location used for a screen I/O operation is
level environment. Additional details regarding windows can calculated using the formula base+offset=actual, where
be found in Chapter 26, “Introduction to the Window Ser- base is the upper left row/column location of the window
vices APIs” on page 26-1. border (0 for full screen) if offset is positive and the lower
right row/column location of the window border (screen
When window mode is enabled, screen locations and cursor height/width plus 1 for full screen), if offset is negative,
positions specified and retrieved in the low-level interface offset is the row/column specified on the API, and actual is
routines are interpreted relative to the logical window area the actual screen location. For example, if the window area
defined. The logical window area is treated as a logical were defined to be from row 3, column 10 with 15 rows and
screen in terms of validity of cursor and data starting posi- 30 columns, as shown in Figure 22-1 on page 22-23, then
tions. If an attempt is made to write data or define a field an attempt to position the cursor through the QsnSetCsrAdr
that starts outside of the current window area, a CPFA31D API at row 4, column 5 would actually position the cursor on

22-22 AS/400 System API Reference V4R4

 Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API

the screen at row 7, column 15, as indicated by the letter a in Window mode is initially disabled.
Figure 22-1 on page 22-23. Specifying row 9, column -7
would position the cursor on the screen at row 12, column 34
(b in Figure 22-1). An attempt to position the cursor at error
Omissible Parameter Group
issue a CPFA307 error row 16, column 5 would result error Previous window mode setting
(Screen position &1,&2 outside of display or window area). OUTPUT; CHAR(1)
since this position is outside the bounds of the current
Whether window mode was enabled or disabled prior to
window area. Given the same window area description, a
this API being called. The possible values returned are:
call to the QsnRtvFldInf API specifying an input buffer con-
taining a field read from row 10, column 20 on the actual 0 Window mode was disabled prior to this
screen (the c in Figure 22-1), would return a field row and API being called
column location of 7 and 10 respectively. A call to the 1 Window mode was enabled prior to this
QsnGetCsrAdr API would return -1,-1 if the cursor were API being called
located outside of the window area, such as in row 18
column 32. Window mode description
INPUT; CHAR(*)
Enabling or disabling the window mode does not affect any The window mode description. If this parameter is
data currently displayed on the screen or the behavior of any omitted or the length parameter is specified as 0, and
commands stored previously in a command buffer. For window mode is to be enabled, the values from the pre-
example, if the window mode were enabled as described vious window mode setting will be used. If no such
above and the QsnSetCsrAdr API was invoked as an indirect values exist, the current screen size will be used. The
operation specifying row 4 and column 5, the cursor position window area described must fall within the bounds of the
command stored in the command buffer would reflect the current screen size. in a CPFA307 error (Screen posi-
current window mode. Whenever that command buffer is tion &1,&2 outside of display or window area). The
written out, the cursor would always be set on the screen at format of this field is shown in “Set Low-Level Environ-
row 6, column 14, regardless of whether or not window mode ment Window Mode (QsnSetEnvWinMod) API” on
was disabled or changed at the point when the command page 22-22.
buffer was written to the screen.
... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8
This parameter is ignored if window mode is to be disa-
┌--------------------------------------------------------------------------------┐ bled.
1│ . . . . . │
2│ . . . . . │
3│ ┌------------------------------┐ │ Length of window mode description
4│ │ . . . │ │
5│ │ . . . │ │ INPUT; BINARY(4)
6│ │ . . . │ │
7│.........│....a
8│ │
.
.
.
.
│
│
│
│
The length of the window mode description parameter.
9│ │ . . │ │ If this parameter is specified, it must be either 0, in
1ð│.........│.........c . │ │
11│ │ . │ │ which case the window mode description parameter is
12│.........│.......................b │ │
13│ │ │ │ ignored, or exactly 13 bytes in which case the window
14│
15│
│
│
│
│
│
│
mode description is required.
16│ │ │ │
17│ │ │ │ Low-level environment handle
18│ └------------------------------┘ │
19│ │ INPUT; BINARY(4)
2ð│ │
21│ │
22│ │
The low-level environment that the operation applies to.
23│
24│
│
│
If this parameter is omitted or given with a value of zero,
└--------------------------------------------------------------------------------┘ the default low-level environment is used.
Figure 22-1. Window Area
Error code
I/O; CHAR(*)
Authorities and Locks The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
None
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Required Parameter
Window mode Returned Value
INPUT; CHAR(1)
Return code
Whether window mode should be enabled or disabled. OUTPUT; BINARY(4)
The possible values are:
A return code indicating the result of the operation. The
0 Disable window mode value returned will be 0 if the operation was successful,
1 Enable window mode or -1 otherwise.

Chapter 22. Screen Manipulation and Query APIs 22-23

Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API

Format of the Window Mode Description 1 Attributes can be written to column containing
left logical window border
Offset Number of columns in window area. The number of
Dec Hex Type Field columns in the window area.
0 0 CHAR(1) Attribute column indication
Number of rows in window area. The number of rows in
1 1 BINARY(4) Upper left row of window the window area.
area border
5 5 BINARY(4) Upper left column of window Upper left column of window area border. The column
area border location of the leftmost column in the window area. This
parameter must be a value between 0 and the screen width
9 9 BINARY(4) Number of rows in window
area
inclusive.

13 D BINARY(4) Number of columns in Upper left row of window border. The row location of the
window area upper border of the logical window area. This parameter
must be a value between 0 and the screen height inclusive.

Field Descriptions
Error Messages
Attribute column indication. Whether the column con-
CPF24B4 E Severe error while addressing parameter list.
taining the left border of the logical window is an attribute
CPF3C1D E
column. Operations such as QsnWrtDta can specify column
Length specified in parameter &1 not valid.
1 for the data location and specify a leading attribute. In this
CPF3CF1 E
case the data will be written to the first column of the window
Error code parameter not valid.
area and the attribute will be written to the column containing
CPF3CF2 E
the logical window border. If the attribute column is not
Error(s) occurred during running of &1 API.
specified for the window area, such an operation would result
CPFA31E E
in a CPFA31D error (Attempt to write outside of window
Required parameter &1 omitted.
area.). This column would also be used to insert the leading
CPFA324 E Window area definition is incorrect.
attribute when line wrapping occurs within the window.
CPFA32A E
The allowable values are: Window mode indicator must be '0' or '1'.
CPFA334 E Low level environment handle incorrect.
0 No attribute column

22-24 AS/400 System API Reference V4R4

 Clear Buffer (QsnClrBuf) API

Chapter 23. Buffer Manipulation and Query APIs

Retrieve Buffer Size
Buffer Manipulation and Query (QsnRtvBufSiz) returns the size of a buffer.
APIs—Introduction Retrieve Cursor Address on Read
(QsnRtvReadAdr) retrieves the cursor position
The buffer manipulation and query APIs are used to create,
at the completion of an input operation.
query, and manipulate input and command buffers that
Retrieve Field Information
interact with the screen.
(QsnRtvFldInf) returns information about a
The two buffer types used by the low-level interfaces are particular field in an input buffer.
command and input. A command buffer can be used to Retrieve Length of Data in Input Buffer
accumulate a sequence of low-level commands without per- (QsnRtvDtaLen) retrieves the number of data
forming an I/O operation. The entire buffer can be written bytes in an input buffer after an input opera-
out at once in a single I/O operation. See “Direct and Indi- tion.
rect Operations” on page 21-1 for further discussion of Retrieve Length of Field Data in Buffer
command buffers. When an input operation is performed, (QsnRtvFldDtaLen) retrieves the number of
you can specify an input buffer as the target of the operation. bytes of field data after an input operation.
The input results are placed in this buffer, which can then be Retrieve Number of Bytes Read from Screen
queried through several interfaces. You may query for indi- (QsnRtvReadLen) retrieves the number of
vidual pieces of information, such as the AID byte from the data bytes read from the screen after an input
input operation using the Retrieve AID Code on Read operation.
(QsnRtvReadAID) API or for multiple pieces of information Retrieve Number of Fields Read
using the Retrieve Read Information (QsnRtvReadInf) API. (QsnRtvFldCnt) retrieves the number of fields
in an input buffer.
Command and input buffers can be used across activation Retrieve Pointer to Data in Input Buffer
groups if the activation group in which the buffer was created (QsnRtvDta) returns a pointer to the first byte
still exists. of input data in an input buffer.
Retrieve Pointer to Field Data
The buffer manipulation and query interfaces include the (QsnRtvFldDta) returns a pointer to the first
following: byte of field data in an input buffer.
Clear Buffer (QsnClrBuf) clears all commands or data in a Retrieve Read Information
buffer resets its state. (QsnRtvReadInf) returns information about the
Copy Buffer (QsnCpyBuf) copies the contents of one buffer input operation.
to another.
The detailed API descriptions are presented in alphabetical
Create Command Buffer
order.
(QsnCrtCmdBuf) creates a command buffer to
accumulate low-level commands.
Create Input Buffer
(QsnCrtInpBuf) creates an input buffer to Clear Buffer (QsnClrBuf) API
receive input results.
Delete Buffer (QsnDltBuf) deletes a buffer.
Put Command Buffer Required Parameter:
(QsnPutBuf) sends the commands in a
1 Buffer handle Input Binary(4)
command buffer to the screen.
Put Command Buffer and Perform Get Omissible Parameter:
(QsnPutGetBuf) sends the commands in a
command buffer to the screen and performs a 2 Error code I/O Char(*)
read operation.
Retrieve AID Code on Read Returned Value:
(QsnRtvReadAID) determines the Aid code for
Return code Output Binary(4)
a given input operation.
Retrieve Available Data Service Program: QSNAPI
(QsnRtvAvailData) copies the user's data into
an input buffer. Threadsafe: No
Retrieve Buffer Data Length
(QsnRtvBufLen) returns the length of data in a
buffer.

 Copyright IBM Corp. 1998, 1999 23-1

Copy Buffer (QsnCpyBuf) API

The Clear Buffer (QsnClrBuf) API clears all commands or

data and resets the state of the given buffer. This is the only Required Parameter Group:
API that clears or removes data in a buffer.
1 Source buffer handle Input Binary(4)
2 Target buffer handle Input Binary(4)
Authorities and Locks
Omissible Parameter:
None
3 Error code I/O Char(*)

Required Parameter Returned Value:

Buffer handle Return code Output Binary(4)
INPUT; BINARY(4)
A handle for the buffer to be cleared. The storage asso- Service Program: QSNAPI
ciated with the buffer is not deallocated.
Threadsafe: No

Omissible Parameter
The Copy Buffer (QsnCpyBuf) API copies the contents of
Error code one buffer to another buffer. Both buffers must be the same
I/O; CHAR(*) type—command or input. If the target and source buffers are
The structure in which to return error information. For the same, no operation takes place and no error is reported.
the format of the structure, see “Error Code Parameter”
If a target command buffer contains data, the data in the
on page 2-6. If this parameter is omitted, diagnostic
source buffer is appended to the target buffer. A CPFA301
and escape messages are issued to the application.
error is issued if the target command buffer is not large
enough to hold the contents of the source buffer and cannot
Returned Value be resized.

Return code If input buffers are being copied, the target buffer must be
OUTPUT; BINARY(4) empty. If the target input buffer is not large enough to hold
A return code indicating the result of the operation. The the data from the source buffer, the data is truncated and no
value returned will be 0 if the operation was successful, error is reported.
or -1 otherwise.
Authorities and Locks
Error Messages None
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid. Required Parameter Group
CPF3CF2 E Source buffer handle
Error(s) occurred during running of &1 API. INPUT; BINARY(4)
CPFA31E E
Required parameter &1 omitted. A handle for the buffer from which data is to be copied.
CPFA331 E Buffer handle incorrect. The contents of this buffer are not affected by this oper-
ation.

Target buffer handle

Copy Buffer (QsnCpyBuf) API INPUT; BINARY(4)
A handle for the buffer to which data is to be copied.

Omissible Parameter
Error code
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

23-2 AS/400 System API Reference V4R4

 Create Command Buffer (QsnCrtCmdBuf) API

Returned Value Initial command buffer size

INPUT; BINARY(4)
Return code
The initial size of the command buffer, in bytes, to
OUTPUT; BINARY(4)
create. This parameter must be greater than 0 and less
A return code indicating the result of the operation. The than the size of the underlying display file I/O buffer:
value returned will be 0 if the operation was successful, approximately 4500 bytes for 24x80, 6300 bytes for
or -1 otherwise. 27x132, 8000 bytes for DBCS-capable displays, 8800
bytes for DBCS presentation screen-capable displays,
and 16000 bytes for DBCS ideographic-capable dis-
Error Messages plays.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid. Omissible Parameter Group
CPF3CF2 E Increment amount
Error(s) occurred during running of &1 API. INPUT; BINARY(4)
CPFA305 E Cannot add operation to command buffer.
CPFA301 E Command buffer is full. The amount to increment the command buffer size by if
CPFA313 E Command buffer already contains an input there is not enough space to store a specified command.
operation. If this parameter is omitted or specified with a zero
CPFA31E E value, the buffer size will not be incremented and a
Required parameter &1 omitted. CPFA301 error will be issued when there is no space in
CPFA330 E Buffer type mismatch. the buffer to store a requested command. If an attempt
CPFA331 E Buffer handle incorrect. is made to increment a command buffer to a size that
exceeds the available memory resources or the size of
the underlying display file I/O buffer, the increment will
not take place and a CPFA301 error will be issued for
Create Command Buffer (QsnCrtCmdBuf) that operation.
API
Maximum size
INPUT; BINARY(4)
Required Parameter: The maximum size to increment the command buffer to
when there is not enough space to store a specified
1 Initial command buffer Input Binary(4)
size
command. If this parameter is nonzero, it must be
greater than the initial command buffer size parameter,
Omissible Parameter Group: and less than the size of the underlying display file I/O
buffer. If this parameter is omitted or specified with a
2 Increment amount Input Binary(4) zero value, no maximum value is assigned for the
3 Maximum size Input Binary(4) command buffer. If the buffer is to be incremented, it
4 Command buffer handle Output Binary(4) will be incremented until either there is no additional
5 Error code I/O Char(*)
storage available or the command buffer exceeds the
Returned Value: size of the display file I/O buffer. If the increment
amount parameter is omitted or specified with a zero
Command buffer handle Output Binary(4) value, this parameter is ignored and the maximum size
is the same as the initial command buffer size.
Service Program: QSNAPI
Command buffer handle
Threadsafe: No OUTPUT; BINARY(4)
The variable containing the handle for the command
The Create Command Buffer (QsnCrtCmdBuf) API creates a buffer created after the QsnCrtCmdBuf API has com-
command buffer for use with low-level operations that accept pleted. The buffer state will be the same as that fol-
a command buffer parameter. lowing a QsnClrBuf operation.

Error code
Authorities and Locks I/O; CHAR(*)
The structure in which to return error information. For
None the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Required Parameter and escape messages are issued to the application.

Chapter 23. Buffer Manipulation and Query APIs 23-3

Create Input Buffer (QsnCrtInpBuf) API

Returned Value Omissible Parameter Group

Command buffer handle Increment amount
OUTPUT; BINARY(4) INPUT; BINARY(4)
This API returns the value for the command buffer The amount to increment the buffer size by if there is not
handle parameter if successful, or -1 otherwise. enough space to store a read operation. If this param-
eter is omitted or specified with a zero value, the buffer
size is not be incremented and input data is truncated if
Error Messages there is not enough space.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Maximum size
Error code parameter not valid. INPUT; BINARY(4)
CPF3CF2 E The maximum size to increment the input buffer to when
Error(s) occurred during running of &1 API. there is not enough space to store the result of a read
CPFA312 E Buffer size parameter error. operation. If this parameter is nonzero, it must be
CPFA314 E Memory allocation error. greater than the initial input buffer size parameter, and
less than the size of the underlying display file I/O buffer.
If this parameter is omitted or specified with a zero
Create Input Buffer (QsnCrtInpBuf) API value, no maximum value is assigned for the input
buffer, if the buffer is to be incremented, it will be incre-
mented until either there is no additional storage avail-
Required Parameter: able or the input buffer exceeds the size of the display
file I/O buffer. If the increment amount parameter is
1 Input buffer size Input Binary(4) omitted or specified with a zero value, this parameter is
ignored and the maximum size is the same as the initial
Omissible Parameter Group: input buffer size.
2 Increment amount Input Binary(4) Input buffer handle
3 Maximum size Input Binary(4) OUTPUT; BINARY(4)
4 Input buffer handle Output Binary(4)
5 Error code I/O Char(*) The variable containing the handle for the created input
buffer after the QsnCrtInpBuf API has completed. The
Returned Value: buffer state becomes the same as that following a
QsnClrBuf operation.
Input buffer handle Output Binary(4)
Error code
Service Program: QSNAPI I/O; CHAR(*)

Threadsafe: No The structure in which to return error information. For

the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
The Create Input Buffer (QsnCrtInpBuf) API creates an input and escape messages are issued to the application.
buffer for use with low-level commands that accept an input
buffer parameter.
Returned Value
Authorities and Locks Input buffer handle
OUTPUT; BINARY(4)
None This API returns the value for the input buffer handle
parameter, or -1 otherwise.
Required Parameter
Input buffer size Error Messages
INPUT; BINARY(4) CPF24B4 E Severe error while addressing parameter list.
The size of the input buffer, in bytes, to create. This CPF3CF1 E
parameter must be greater than 0 and less than the size Error code parameter not valid.
of the underlying display file I/O buffer: approximately CPF3CF2 E
4500 bytes for 24x80, 6300 bytes for 27x132, 8000 Error(s) occurred during running of &1 API.
bytes for DBCS-capable displays, 8800 bytes for DBCS CPFA312 E Buffer size parameter error.
presentation screen-capable displays, and 16000 bytes CPFA314 E Memory allocation error.
for DBCS ideographic-capable displays.

23-4 AS/400 System API Reference V4R4

 Put Command Buffer (QsnPutBuf) API

CPF3CF2 E
Delete Buffer (QsnDltBuf) API Error(s) occurred during running of &1 API.
CPFA31E E
Required parameter &1 omitted.
Required Parameter: CPFA331 E Buffer handle incorrect.

1 Buffer handle Input Binary(4)

Omissible Parameter:
Put Command Buffer (QsnPutBuf) API
2 Error code I/O Char(*)
Required Parameter:
Returned Value:
1 Command buffer handle Input Binary(4)
Return code Output Binary(4)
Omissible Parameter Group:
Service Program: QSNAPI
2 Low-level environment Input Binary(4)
Threadsafe: No handle
3 Error code I/O Char(*)

The Delete Buffer (QsnDltBuf) API deletes a command or Returned Value:

input buffer created with the Create Command Buffer
(QsnCrtCmdBuf) or the Create Input Buffer (QsnCrtInpBuf) Return code Output Binary(4)
API, respectively. All storage associated with the buffer is
Service Program: QSNAPI
deallocated.
Threadsafe: No
Authorities and Locks
The Put Command Buffer (QsnPutBuf) API sends the com-
None
mands accumulated in a command buffer to the screen.
This corresponds to a write operation to the display file. If
Required Parameter the command buffer contains no data, the operation returns
successfully, but no I/O operation is performed.
Buffer handle
Input; BINARY(4)
A handle for the buffer to be deleted.
Authorities and Locks
None
Omissible Parameter
Error code Required Parameter
I/O; CHAR(*) Command buffer handle
The structure in which to return error information. For INPUT; BINARY(4)
the format of the structure, see “Error Code Parameter” A handle for the command buffer. The command buffer
on page 2-6. If this parameter is omitted, diagnostic is not modified in any way as a result of this command.
and escape messages are issued to the application.

Omissible Parameter Group

Returned Value
Low-level environment handle
Return code INPUT; BINARY(4)
OUTPUT; BINARY(4)
The low-level environment that the operation applies to.
A return code indicating the result of the operation. The If this parameter is omitted or given with a value of zero,
value returned will be 0 if the operation was successful, the default low-level environment is used.
or -1 otherwise.
Error code
I/O; CHAR(*)
Error Messages
The structure in which to return error information. For
CPF24B4 E Severe error while addressing parameter list.
the format of the structure, see “Error Code Parameter”
CPF3CF1 E
on page 2-6. If this parameter is omitted, diagnostic
Error code parameter not valid.
and escape messages are issued to the application.

Chapter 23. Buffer Manipulation and Query APIs 23-5

Put Command Buffer and Perform Get (QsnPutGetBuf) API

Returned Value
Required Parameter Group:
Return code
OUTPUT; BINARY(4) 1 Command buffer handle Input Binary(4)
A return code indicating the result of the operation. The 2 Input buffer handle Input Binary(4)
value returned will be 0 if the operation was successful,
Omissible Parameter Group:
or -1 otherwise.
3 Low-level environment Input Binary(4)
handle
Error Messages 4 Error code I/O Char(*)
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Returned Value:
Error code parameter not valid.
Return code Output Binary(4)
CPF3CF2 E
Error(s) occurred during running of &1 API. Service Program: QSNAPI
CPFA303 E Error occurred for screen I/O operation.
CPFA304 E Data-stream error &1 reported for screen I/O Threadsafe: No
operation.
CPFA308 E Attempt to write data past end of display.
CPFA309 E Invalid cursor position in command buffer. The Put Command Buffer and Perform Get (QsnPutGetBuf)
CPFA30A E API sends the commands accumulated in a command buffer
Field length &1 not valid. to the screen and performs a read operation. The command
CPFA30B E buffer must contain an input operation. If it has no input
Invalid starting address for field. operation, a CPFA333 error occurs.
CPFA30C E
Maximum allowable number of fields exceeded. Authorities and Locks
CPFA316 E Saved data not valid.
CPFA31B E None
From position &1, &2 greater than to position
&3, &4.
CPFA31E E Required Parameter Group
Required parameter &1 omitted. Command buffer handle
CPFA331 E Buffer handle incorrect. INPUT; BINARY(4)
CPFA334 E Low level environment handle incorrect.
CPFA338 E Command buffer contains an input operation. A handle for the command buffer to be sent to the
CPFA343 E Output operation not done. screen.
CPFA344 E The file &2 in library &3 is not valid. Input buffer handle
CPFA345 E The invite active flag is not valid. INPUT; BINARY(4)
A handle for the input buffer that receives the result of
the input operation.
Put Command Buffer and Perform Get
(QsnPutGetBuf) API
Omissible Parameter Group
Low-level environment handle
INPUT; BINARY(4)
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
the default low-level environment is used.

Error code
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value

23-6 AS/400 System API Reference V4R4

 Retrieve AID Code on Read (QsnRtvReadAID) API

Return code
OUTPUT; BINARY(4) Required Parameter:
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful, 1 Input buffer handle Input Binary(4)
or -1 otherwise.
Omissible Parameter Group:

2 AID code Output Char(1)

Error Messages 3 Error code I/O Char(*)
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Returned Value:
Error code parameter not valid.
AID code Output Char(1)
CPF3CF2 E
Error(s) occurred during running of &1 API. Service Program: QSNAPI
CPFA303 E Error occurred for screen I/O operation.
CPFA304 E Data-stream error &1 reported for screen I/O Threadsafe: No
operation.
CPFA308 E Attempt to write data past end of display.
CPFA309 E Invalid cursor position in command buffer. The Retrieve AID Code on Read (QsnRtvReadAID) API
CPFA30A E determines the AID code corresponding to the input opera-
Field length &1 not valid. tion that filled the given input buffer.
CPFA30B E
Invalid starting address for field.
Authorities and Locks
CPFA30C E
Maximum allowable number of fields exceeded. None
CPFA316 E Saved data not valid.
CPFA31B E
From position &1, &2 greater than to position Required Parameter
&3, &4. Input buffer handle
CPFA31E E INPUT; BINARY(4)
Required parameter &1 omitted.
CPFA326 E Screen must be redrawn. A handle for the input buffer that contains the results of
CPFA331 E Buffer handle incorrect. the input operation. The input buffer must be filled as a
CPFA334 E Low level environment handle incorrect. result of a Read Input Fields (QsnReadInp), Read Modi-
CPFA33E E fied Fields (QsnReadMDT), or Read Modified Alternate
Command buffer does not contain an input (QsnReadMDTAlt) operation. If the input buffer is filled
operation. as a result of any other input operation, a CPFA32E
CPFA343 E Output operation not done. error is issued.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. Omissible Parameter Group
AID code
Retrieve AID Code on Read OUTPUT; CHAR(1)
(QsnRtvReadAID) API The variable that contains the AID code when the
QsnRtvReadAID API has completed. See
“AID-Generating Keys” on page 21-2 for a description of
the possible values.

Error code
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value

Chapter 23. Buffer Manipulation and Query APIs 23-7

Retrieve Buffer Data Length (QsnRtvBufLen) API

AID code Required Parameter Group

OUTPUT; CHAR(1)
Input buffer handle
This API returns the value for the AID code parameter or
INPUT; BINARY(4)
X'00' if an error occurs during processing.
A handle for the input buffer where available data should
be moved.
Error Messages
Read command used
CPF24B4 E Severe error while addressing parameter list.
OUTPUT; CHAR(1)
CPF3CF1 E
Error code parameter not valid. The read command that was used to fill the input buffer.
CPF3CF2 E This can be used to determine what buffer manipulation
Error(s) occurred during running of &1 API. API to use to retrieve the data from the input buffer. The
CPFA319 E No data in input buffer. possible values are :
CPFA31E E
X'42' Read input fields
Required parameter &1 omitted.
X'52' Read MDT fields
CPFA32E E
X'72' Read immediate
Input data for query operation incorrect.
X'82' Read MDT alternate
CPFA32F E
Buffer type incorrect.
CPFA331 E Buffer handle incorrect. Omissible Parameter Group
CPFA334 E Low level environment handle incorrect.
Error code
I/O; CHAR(*)
Retrieve Available Data (QsnRtvAvailData) The structure in which to return error information. For
API the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Required Parameter Group:
Returned Value
1 Input buffer handle Input Binary(4)
2 Read command used Output Binary(4) Return code
OUTPUT; BINARY(4)
Omissible Parameter Group:
A return code indicating the result of the operation. The
3 Error code I/O Char(*) value returned will be 0 if the operation was successful,
or -1 otherwise.
Returned Value:

Return code Output Binary(4) Error Messages

Service Program: QSNAPI CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Threadsafe: No Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
The Retrieve Available Data (QsnRtvAvailData) API is used CPFA319 E No data in input buffer.
to retrieve invited available data. If the invite active flag is on CPFA31E E
in a low-level environment description when an output opera- Required parameter &1 omitted.
tion is done, the end user is able to enter data. If a subse- CPFA320 E Pointer parameter is null.
quent output operation is done, without checking for input CPFA32F E
using the QsnReadInvited API, and the user has entered Buffer type incorrect.
data, DSM will store the end user's data in an internal input CPFA331 E Buffer handle incorrect.
buffer and issue CPFA343. The Retrieve Available Data
(QsnRtvAvailData) API will copy the data into the specified
input buffer, as well as return the read command that is used
to fill the buffer.
Retrieve Buffer Data Length
(QsnRtvBufLen) API
Authorities and Locks
None

23-8 AS/400 System API Reference V4R4

 Retrieve Buffer Size (QsnRtvBufSiz) API

CPF24B4 E Severe error while addressing parameter list.

Required Parameter: CPF3CF1 E
Error code parameter not valid.
1 Buffer handle Input Binary(4) CPF3CF2 E
Error(s) occurred during running of &1 API.
Omissible Parameter Group: CPFA31E E
Required parameter &1 omitted.
2 Buffer data length Output Binary(4)
CPFA331 E Buffer handle incorrect.
3 Error code I/O Char(*)

Returned Value:
Retrieve Buffer Size (QsnRtvBufSiz) API
Buffer data length Output Binary(4)

Service Program: QSNAPI

Required Parameter:
Threadsafe: No
1 Buffer handle Input Binary(4)

The Retrieve Buffer Data Length (QsnRtvBufLen) API returns Omissible Parameter Group:
the number of bytes of command data in a command buffer 2 Buffer size Output Binary(4)
or of input data in an input buffer. After an indirect opera- 3 Error code I/O Char(*)
tion is applied to a command buffer, the QsnRtvBufLen API
result reflects the increase in the underlying command Returned Value:
stream to accommodate the command.
Buffer size Output Binary(4)

Authorities and Locks Service Program: QSNAPI

None Threadsafe: No

Required Parameter The Retrieve Buffer Size (QsnRtvBufSiz) API returns the total
number of bytes allocated for a command or input buffer.
Buffer handle The result returned from this API is the current allocated
INPUT; BINARY(4) buffer size, including any increments that may have taken
A handle for the buffer to be queried. place.

Omissible Parameter Group Authorities and Locks

Buffer data length None
OUTPUT; BINARY(4)
The variable containing the buffer data length after the Required Parameter
QsnRtvBufLen API has completed.
Buffer handle
Error code INPUT; BINARY(4)
I/O; CHAR(*)
A handle for the buffer to be queried.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Omissible Parameter Group
and escape messages are issued to the application.
Buffer size
OUTPUT; BINARY(4)
Returned Value The variable containing the buffer size after the
Buffer data length QsnRtvBufSiz API has completed.
OUTPUT; BINARY(4) Error code
This API returns the value for the buffer data length I/O; CHAR(*)
parameter, or -1 otherwise. The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Error Messages on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Chapter 23. Buffer Manipulation and Query APIs 23-9

Retrieve Cursor Address on Read (QsnRtvReadAdr) API

Returned Value Authorities and Locks

Buffer size None
OUTPUT; BINARY(4)
This API returns the value for the buffer size parameter, Required Parameter
or -1 otherwise.
Input buffer handle
INPUT; BINARY(4)
Error Messages
A handle for the input buffer that contains the results of
CPF24B4 E Severe error while addressing parameter list.
the input operation.
CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E Omissible Parameter Group
Error(s) occurred during running of &1 API.
Cursor row
CPFA31E E
OUTPUT; BINARY(4)
Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect. The variable that contains the row position of the cursor
when the QsnRtvReadAdr API has completed.

Cursor column
Retrieve Cursor Address on Read OUTPUT; BINARY(4)
(QsnRtvReadAdr) API
The variable that contains the column position of the
cursor when the QsnRtvReadAdr API has completed.
Required Parameter: Low-level environment handle
INPUT; BINARY(4)
1 Input buffer handle Input Binary(4)
The low-level environment that the operation applies to.
Omissible Parameter Group: If this parameter is omitted or given with a value of zero,
the default low-level environment is used.
2 Cursor row Output Binary(4)
3 Cursor column Output Binary(4) Error code
4 Low-level environment Input Binary(4) I/O; CHAR(*)
handle
5 Error code I/O Char(*) The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Returned Value: on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Return code Output Binary(4)

Service Program: QSNAPI Returned Value

Threadsafe: No Return code
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
The Retrieve Cursor Address on Read (QsnRtvReadAdr) API
value returned will be 0 if the operation was successful,
determines the row and column position of the cursor when
or -1 otherwise.
the input operation that filled the given input buffer has com-
pleted. You must specify at least one of the cursor row or
the cursor column parameter. If both of these parameters Error Messages
are omitted, a CPFA31E error occurs.
CPF24B4 E Severe error while addressing parameter list.
The input buffer must be filled as a result of a Read Input CPF3CF1 E
Fields (QsnReadInp), Read Modified Fields (QsnReadMDT), Error code parameter not valid.
Read Modified Alternate (QsnReadMDTAlt), Read Immediate CPF3CF2 E
(QsnReadImm), or Read Modified Immediate Alternate Error(s) occurred during running of &1 API.
(QsnReadMDTImmAlt) operation. If the input buffer is filled CPFA319 E No data in input buffer.
as a result of any other input operation, a CPFA32E CPFA31E E
message is issued. Required parameter &1 omitted.
CPFA32E E
Input data for query operation incorrect.
CPFA32F E
Buffer type incorrect.

23-10 AS/400 System API Reference V4R4

 Retrieve Field Information (QsnRtvFldInf) API

CPFA331 E Buffer handle incorrect. Field number

CPFA334 E Low level environment handle incorrect. INPUT; BINARY(4)
The number of the field to query, specified as n, where n
is the nth field in the input buffer. The value specified
Retrieve Field Information (QsnRtvFldInf) must not be greater than the field count returned by the
API read operation.

Receiver variable
Output; CHAR(*)
Required Parameter Group:
The structure that will contain the result of the query
1 Input buffer handle Input Binary(4) when the QsnRtvFldInf API has completed.
2 Field number Input Binary(4)
3 Receiver variable Output Char(*) Length of receiver variable
4 Length of receiver vari- Input Bin(4) Input; BINARY(4)
able
The length of the receiver variable parameter.
Omissible Parameter Group:

5 Low-level environment Input Binary(4) Omissible Parameter Group

handle
Low-level environment handle
6 Error code I/O Char(*)
INPUT; BINARY(4)
Returned Value: The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
Return code Output Binary(4)
the default low-level environment is used.
Service Program: QSNAPI Error code
I/O; CHAR(*)
Threadsafe: No
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
The Retrieve Field Information (QsnRtvFldInf) API retrieves on page 2-6. If this parameter is omitted, diagnostic
information about a field in an input buffer filled by a Read and escape messages are issued to the application.
Modified Fields (QsnReadMDT), Read Modified Alternate
(QsnReadMDTAlt), or Read Modified Immediate Alternate
(QsnReadMDTImmAlt) operation. Returned Value
Return code
To query the results from a Read Input Fields (QsnReadInp)
OUTPUT; BINARY(4)
or Read Immediate (QsnReadImm) operation, use the
Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) A return code indicating the result of the operation. The
and Retrieve Pointer to Field Data (QsnRtvFldDta) APIs. To value returned will be 0 if the operation was successful,
query the result from any other input operations, use the or -1 otherwise.
Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) and
Retrieve Pointer to Data in Input Buffer (QsnRtvDta) APIs.
Format of the Query Input Field Result
Authorities and Locks Offset
Dec Hex Type Field
None
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
Required Parameter Group
8 8 CHAR(1) Type of field
Input buffer handle
9 9 BINARY(4) Row position of field
INPUT; BINARY(4)
13 D BINARY(4) Column position of field
A handle for the input buffer that contains the results of
the input operation. 17 11 BINARY(4) Length of data read
21 15 CHAR(11) Reserved
32 20 PTR(SPP) Pointer to field data

Chapter 23. Buffer Manipulation and Query APIs 23-11

Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) API

Field Descriptions
Required Parameter:
Bytes available. The number of bytes of data available to
be returned. All available data is returned if enough space is 1 Input buffer handle Input Binary(4)
provided.
Omissible Parameter Group:
Bytes returned. The number of bytes of data returned.
2 Input data length Output Binary(4)
Column position of field. The column position relative to 3 Error code I/O Char(*)
the window of the specified field on the screen.
Returned Value:
Length of data read. The length of the data read from the
Input data length Output Binary(4)
specified field.
Service Program: QSNAPI
Pointer to field data. A pointer to the data for the specified
field. Threadsafe: No
Row position of field. The row position relative to the
window of the specified field on the screen. The Retrieve Length of Data in Input Buffer (QsnRtvDtaLen)
API determines the number of bytes of input data contained
Type of field. The type of the specified field. The possible in an input buffer after an input operation.
values are:
Value Description
1 Normal field
Authorities and Locks
2 Transparent field None

Error Messages Required Parameter

CPF24B4 E Severe error while addressing parameter list.
Input buffer handle
CPF3C24 E
INPUT; BINARY(4)
Length of the receiver variable is not valid.
CPF3CF1 E A handle for the input buffer that contains the results of
Error code parameter not valid. the input operation.
CPF3CF2 E
Error(s) occurred during running of &1 API.
CPFA319 E No data in input buffer.
Omissible Parameter Group
CPFA31A E Input data length
Incorrect field number value &1 specified. OUTPUT; BINARY(4)
CPFA31E E
The variable that contains the input data length when the
Required parameter &1 omitted.
QsnRtvDtaLen API has completed. This number may
CPFA32E E
be smaller than the number of bytes actually read if the
Input data for query operation incorrect.
input buffer was not large enough to hold all the data.
CPFA32F E
Use the Retrieve Number of Bytes Read from Screen
Buffer type incorrect.
(QsnRtvReadLen) API to determine the amount of data
CPFA331 E Buffer handle incorrect.
actually read from the screen. If the value returned by
CPFA334 E Low level environment handle incorrect.
the QsnRtvReadLen API is less than the input data
length, then truncation of the input data occurred.

Retrieve Length of Data in Input Buffer

(QsnRtvDtaLen) API Returned Value
Input data length
OUTPUT; BINARY(4)
This API returns the value for the input data length
parameter, or -1 otherwise.

Error Messages
CPF24B4 E Severe error while addressing parameter list.

23-12 AS/400 System API Reference V4R4

 Retrieve Number of Bytes Read from Screen (QsnRtvReadLen) API

CPF3CF1 E Required Parameter

Error code parameter not valid.
CPF3CF2 E Input buffer handle
Error(s) occurred during running of &1 API. INPUT; BINARY(4)
CPFA319 E No data in input buffer. A handle for the input buffer that contains the results of
CPFA31E E the input operation. The input buffer must be filled as a
Required parameter &1 omitted. result of a QsnReadInp or QsnReadImm operation.
CPFA32F E
Buffer type incorrect.
CPFA331 E Buffer handle incorrect. Omissible Parameter Group
CPFA334 E Low level environment handle incorrect.
Length of field data
OUTPUT; BINARY(4)

Retrieve Length of Field Data in Buffer The variable that contains the field data length when the
QsnRtvFldDtaLen API has completed. The field data
(QsnRtvFldDtaLen) API length is 3 bytes less than the value returned by the
QsnRtvDtaLen API. (The cursor and AID-key values
account for the first 3 bytes of the input data returned).
Required Parameter:
Error code
1 Input buffer handle Input Binary(4) I/O; CHAR(*)
Omissible Parameter Group: The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
2 Length of field data Output Binary(4) on page 2-6. If this parameter is omitted, diagnostic
3 Error code I/O Char(*) and escape messages are issued to the application.
Returned Value:
Returned Value
Length of field data Output Binary(4)
Length of field data
Service Program: QSNAPI OUTPUT; BINARY(4)

Threadsafe: No This API returns the value for the length of field data
parameter, or -1 otherwise.

The Retrieve Length of Field Data in Buffer

(QsnRtvFldDtaLen) API determines the number of bytes of Error Messages
field data returned after a Read Input Fields (QsnReadInp) or CPF24B4 E Severe error while addressing parameter list.
Read Immediate (QsnReadImm) input operation. You can CPF3CF1 E
use the Retrieve Pointer to Field Data (QsnRtvFldDta) API to Error code parameter not valid.
retrieve a pointer to this data so that you can parse the field CPF3CF2 E
values. Refer to the Read Input Fields (QsnReadInp) API for Error(s) occurred during running of &1 API.
a description of the format of the data returned. CPFA319 E No data in input buffer.
CPFA31E E
To query the results from a Read Modified Fields Required parameter &1 omitted.
(QsnReadMDT), Read Modified Alternate (QsnReadMDTAlt), CPFA32E E
or Read Modified Immediate Alternate (QsnReadMDTImmAlt) Input data for query operation incorrect.
operation, use the Retrieve Number of Fields Read CPFA32F E
(QsnRtvFldCnt) and Retrieve Field Information Buffer type incorrect.
(QsnRtvFldInf) APIs. To query the result from any other CPFA331 E Buffer handle incorrect.
input operation, use the Retrieve Length of Data in Input CPFA334 E Low level environment handle incorrect.
Buffer (QsnRtvDtaLen) and Retrieve Pointer to Data in Input
Buffer (QsnRtvDta) APIs.
Retrieve Number of Bytes Read from
Authorities and Locks Screen (QsnRtvReadLen) API
None

Chapter 23. Buffer Manipulation and Query APIs 23-13

Retrieve Number of Fields Read (QsnRtvFldCnt) API

Read data length

Required Parameter: OUTPUT; BINARY(4)
This API returns the value for the read data length
1 Input buffer handle Input Binary(4) parameter, or -1 otherwise.
Omissible Parameter Group
Error Messages
2 Read data length Output Binary(4)
3 Error code I/O Char(*) CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Returned Value: Error code parameter not valid.
CPF3CF2 E
Read data length Output Binary(4)
Error(s) occurred during running of &1 API.
Service Program: QSNAPI CPFA319 E No data in input buffer.
CPFA31E E
Threadsafe: No Required parameter &1 omitted.
CPFA320 E Pointer parameter is null.
CPFA331 E Buffer handle incorrect.
The Retrieve Number of Bytes Read from Screen CPFA334 E Low level environment handle incorrect.
(QsnRtvReadLen) API returns the number of bytes of data
read from the screen into an input buffer after an input oper-
ation. Retrieve Number of Fields Read
(QsnRtvFldCnt) API
Authorities and Locks
None Required Parameter:

1 Input buffer handle Input Binary(4)

Required Parameter
Input buffer handle Omissible Parameter Group:
INPUT; BINARY(4) 2 Field count Output Binary(4)
A handle for the input buffer that contains the results of 3 Error code I/O Char(*)
the input operation.
Returned Value:

Omissible Parameter Group Field count Output Binary(4)

Read data length Service Program: QSNAPI

OUTPUT; BINARY(4)
Threadsafe: No
The variable that contains the read data length when the
QsnRtvReadLen API has completed. This number may
be larger than the number of bytes actually contained in The Retrieve Number of Fields Read (QsnRtvFldCnt) API
the buffer if the input buffer was not large enough to returns the number of fields contained in an input buffer after
hold all the data. Use the Retrieve Length of Data in a Read Modified Fields (QsnReadMDT), Read Modified Alter-
Input Buffer (QsnRtvDtaLen) API to determine the nate (QsnReadMDTAlt), or Read Modified Immediate Alter-
amount of data contained in the buffer or to determine if nate (QsnReadMDTImmAlt) operation. Use the Retrieve
truncation occurred. Field Information (QsnRtvFldInf) API to retrieve information
about a specific field.
Error code
I/O; CHAR(*) To query the results from a QsnReadInp or QsnReadImm
The structure in which to return error information. For operation, use the Retrieve Length of Field Data in Buffer
the format of the structure, see “Error Code Parameter” (QsnRtvFldDtaLen) and Retrieve Pointer to Field Data
on page 2-6. If this parameter is omitted, diagnostic (QsnRtvFldDta) APIs. To query the result from any other
and escape messages are issued to the application. input operation, use the Retrieve Length of Data in Input
Buffer (QsnRtvDtaLen) and Retrieve Pointer to Data in Input
Buffer (QsnRtvDta) APIs.
Returned Value
Authorities and Locks
None

23-14 AS/400 System API Reference V4R4

 Retrieve Pointer to Data in Input Buffer (QsnRtvDta) API

Required Parameter
Required Parameter:
Input buffer handle
INPUT; BINARY(4) 1 Input buffer handle Input Binary(4)
A handle for the input buffer that contains the results of
Omissible Parameter Group:
the input operation. The input buffer must be filled as a
result of a QsnReadMDT, QsnReadMDTAlt, or 2 Pointer to input data Output PTR(SPP)
QsnReadMDTImmAlt operation. 3 Error code I/O Char(*)

Returned Value:
Omissible Parameter Group
Pointer to input data Output PTR(SPP)
Field count
OUTPUT; BINARY(4) Service Program: QSNAPI
The variable that contains the field count when the
QsnRtvFldCnt API has completed. Threadsafe: No

Error code
I/O; CHAR(*) The Retrieve Pointer to Data in Input Buffer (QsnRtvDta) API
returns a pointer to the first byte of input data in an input
The structure in which to return error information. For buffer after a read operation.
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Authorities and Locks
None
Returned Value
Field count Required Parameter
OUTPUT; BINARY(4)
Input buffer handle
This API returns the value for the field count parameter, INPUT; BINARY(4)
or -1 otherwise.
A handle for the input buffer that contains the results of
the input operation.
Error Messages
CPF24B4 E Severe error while addressing parameter list. Omissible Parameter Group
CPF3CF1 E
Error code parameter not valid. Pointer to input data
CPF3CF2 E OUTPUT; PTR(SPP)
Error(s) occurred during running of &1 API. The variable that contains the pointer to the input data
CPFA314 E Memory allocation error. after the QsnRtvDta API has completed. You can use
CPFA319 E No data in input buffer. the Retrieve Length of Data in Input Buffer
CPFA31E E (QsnRtvDtaLen) API to retrieve the length of this data.
Required parameter &1 omitted. Refer to the appropriate read operation for a description
CPFA32E E of the format of the data returned. The value returned
Input data for query operation incorrect. by this API is equivalent to the data returned by the
CPFA32F E system on an input operation. This parameter must be
Buffer type incorrect. on a 16-byte boundary.
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect. Error code
I/O; CHAR(*)
The structure in which to return error information. For
Retrieve Pointer to Data in Input Buffer the format of the structure, see “Error Code Parameter”
(QsnRtvDta) API on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value

Chapter 23. Buffer Manipulation and Query APIs 23-15

Retrieve Pointer to Field Data (QsnRtvFldDta) API

Pointer to input data from any other input operations, use the QsnRtvDtaLen and
OUTPUT; PTR(SPP) QsnRtvDta APIs.
This API returns the value for the pointer to input data
parameter, or the null pointer otherwise. Authorities and Locks
None
Error Messages
CPF24B4 E Severe error while addressing parameter list.
CPF3C1F E
Required Parameter
Pointer is not on a 16 byte boundary. Input buffer handle
CPF3CF1 E INPUT; BINARY(4)
Error code parameter not valid.
A handle for the input buffer that contains the results of
CPF3CF2 E
the input operation. The input buffer must be filled as a
Error(s) occurred during running of &1 API.
result of a QsnReadInp or QsnReadImm operation.
CPFA319 E No data in input buffer.
CPFA31E E
Required parameter &1 omitted. Omissible Parameter Group
CPFA32F E
Buffer type incorrect. Pointer to field data
CPFA331 E Buffer handle incorrect. OUTPUT; PTR(SPP)
CPFA334 E Low level environment handle incorrect. The variable that contains the pointer to the field data
when the QsnRtvFldDta API has completed. The value
returned by this API is the null pointer if the buffer con-
Retrieve Pointer to Field Data tains no field data. Otherwise, it is equivalent to adding
(QsnRtvFldDta) API 3 bytes to the address returned by QsnRtvDta API.
(The cursor and AID key values account for the first 3
bytes of input data returned.) This parameter must be
Required Parameter: on a 16-byte boundary.

Error code
1 Input buffer handle Input Binary(4)
I/O; CHAR(*)
Omissible Parameter Group: The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
2 Pointer to field data Output PTR(SPP)
on page 2-6. If this parameter is omitted, diagnostic
3 Error code I/O Char(*)
and escape messages are issued to the application.
Returned Value:

Pointer to field data Output PTR(SPP) Returned Value

Pointer to field data
Service Program: QSNAPI
OUTPUT; PTR(SPP)
Threadsafe: No This API returns the value for the pointer to field data
parameter, or the null pointer otherwise.
The Retrieve Pointer to Field Data (QsnRtvFldDta) API
returns a pointer to the first byte of field data in an input Error Messages
buffer after a Read Input Fields (QsnReadInp), Read Imme-
CPF24B4 E Severe error while addressing parameter list.
diate (QsnReadImm), Read Modified Fields (QsnReadMDT),
CPFA319 E No data in input buffer.
Read Modified Alternate (QsnReadMDTAlt), or Read Modi-
CPFA331 E Buffer handle incorrect.
fied Immediate Alternate (QsnReadMDTImmAlt) operation.
CPFA334 E Low level environment handle incorrect.
You can use the Retrieve Length of Field Data in Buffer
CPFA31E E
(QsnRtvFldDtaLen) API to retrieve the length of this data.
Required parameter &1 omitted.
Refer to the “Read Input Fields (QsnReadInp) API” on
CPFA32E E
page 24-6 for a description of the format of the data
Input data for query operation incorrect.
returned.
CPFA32F E
To query the results from a QsnReadMDT, QsnReadMDTAlt, Buffer type incorrect.
or QsnReadMDTImmAlt operation, you can also use the CPF3C1F E
QsnRtvFldCnt and QsnRtvFldInf APIs. To query the result Pointer is not on a 16 byte boundary.

23-16 AS/400 System API Reference V4R4

 Retrieve Read Information (QsnRtvReadInf) API

CPF3CF1 E Low-level environment handle

Error code parameter not valid. INPUT; BINARY(4)
CPF3CF2 E
The low-level environment that the operation applies to.
Error(s) occurred during running of &1 API.
If this parameter is omitted or given with a value of zero,
the default low-level environment is used.

Retrieve Read Information Error code

(QsnRtvReadInf) API I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Required Parameter Group: on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
1 Input buffer handle Input Binary(4)
2 Query result Output Char(*)
3 Length of query result Input Binary(4) Returned Value
Omissible Parameter Group: Return code
OUTPUT; BINARY(4)
4 Low-level environment Input Binary(4)
handle
A return code indicating the result of the operation. The
5 Error code I/O Char(*) value returned will be 0 if the operation was successful,
or -1 otherwise.
Returned Value:

Return code Output Binary(4) Format of the Query Result

Service Program: QSNAPI Offset
Dec Hex Type Field
Threadsafe: No
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
The Retrieve Read Information (QsnRtvReadInf) API returns
information about the input operation that filled the given 8 8 CHAR(8) Reserved
input buffer. 16 10 PTR(SPP) Pointer to first byte of data
32 20 PTR(SPP) Pointer to first byte of field
Authorities and Locks data
48 30 BINARY(4) Number of bytes of input
None data
52 34 BINARY(4) Number of bytes of field
Required Parameter Group data
56 38 BINARY(4) Number of fields in input
Input buffer handle
buffer
INPUT; BINARY(4)
60 3C BINARY(4) Number of bytes of data
A handle for the input buffer that contains the results of received
the input operation.
64 40 BINARY(4) Row location of cursor
Query result 68 44 BINARY(4) Column location of cursor
OUTPUT; CHAR(*)
72 48 CHAR(1) AID code for AID-associated
The structure that contains the result of the query when read request
the QsnRtvReadInf API has completed. The format of 73 49 CHAR(7) Reserved
this structure is shown in “Format of the Query Result.”

Length of query result

INPUT; BINARY(4) Field Descriptions
The length of the query result parameter. The minimum Bytes available. The number of bytes of data available to
value must be 8. be returned. All available data is returned if enough space is
provided.
Omissible Parameter Group Bytes returned. The number of bytes of data returned.

AID code for AID-associated read request. AID code cor-

Chapter 23. Buffer Manipulation and Query APIs 23-17

Retrieve Read Information (QsnRtvReadInf) API

responding to key pressed to service an AID-associated read Pointer to first byte of data. Pointer to first byte of data in
request. The input buffer must be filled as a result of a input buffer. This includes header information such as row
QsnReadInp, QsnReadMDT, or QsnReadMDTAlt operation. and column position.
If the input buffer is filled as a result of any other input opera-
tion, this field is set to X'00'. See “AID-Generating Keys” on Pointer to first byte of field data. Pointer to first byte of
page 21-2 for a description of the possible values. field data in input buffer. This will be the first byte of data
following the header information (the cursor row and column,
Column location of cursor. Column location of cursor and the AID byte). If the buffer does not contain field data,
when the input operation was serviced. The input buffer this field is set to the null pointer.
must be filled as a result of a QsnReadInp, QsnReadMDT,
QsnReadMDTAlt, QsnReadImm, or QsnReadMDTImmAlt Reserved. An ignored field.
operation. If the input buffer is filled as a result of any other
Row location of cursor. Row location of cursor when the
input operation, this field is set to -1.
input operation was serviced. The input buffer must be filled
Number of bytes of data sent. Number of bytes of data as a result of a QsnReadInp, QsnReadMDT,
sent from screen. If this value is larger than the number of QsnReadMDTAlt, QsnReadImm, or QsnReadMDTImmAlt
bytes of input data, then truncation occurs on the input oper- operation. If the input buffer is filled as a result of any other
ation. input operation, this field is set to -1.

Number of bytes of field data. Number of bytes of field

data in input buffer. This does not include the 3 bytes of
Error Messages
header information (the cursor row and column, and the AID CPF24B4 E Severe error while addressing parameter list.
byte). The input buffer must be filled as a result of a CPF3C1F E
QsnReadInp, QsnReadMDT, QsnReadMDTAlt, Pointer is not on a 16 byte boundary.
QsnReadImm, or QsnReadMDTImmAlt operation. If the CPF3C24 E
input buffer is filled as a result of any other input operation, Length of the receiver variable is not valid.
this field is set to -1. CPF3CF1 E
Error code parameter not valid.
Number of bytes of input data. Number of bytes of input CPF3CF2 E
data in input buffer. This includes header information such Error(s) occurred during running of &1 API.
as row and column position. CPFA319 E No data in input buffer.
CPFA31E E
Number of fields in input buffer. Number of fields in input Required parameter &1 omitted.
buffer. This does not include header information such as row CPFA320 E Pointer parameter is null.
and column position. The input buffer must be filled as a CPFA32F E
result of a QsnReadMDT, QsnReadMDTAlt, or Buffer type incorrect.
QsnReadMDTImmAlt operation. If the input buffer is filled as CPFA331 E Buffer handle incorrect.
a result of any other input operation, or the input data format CPFA334 E Low level environment handle incorrect.
cannot be determined, this field is set to -1.

23-18 AS/400 System API Reference V4R4

 Get AID (QsnGetAID) API

Chapter 24. Screen Input APIs

Screen Input APIs—Introduction Read Command Processing

The screen input APIs allow you to read data and other infor- The read commands fall into two categories– AID-associated
mation from the screen. This includes field data, screen attri- and immediate. When an AID-associated read command is
butes, and the cursor address. The screen-input interfaces issued, an AID-generating key must be pressed at the ter-
correspond, either directly or indirectly, to the 5250 data minal for control to return to the program. (The keyboard
stream read commands. must be unlocked to allow an AID key to be pressed.) For
direct read operations or indirect operations where the asso-
The screen input APIs are: ciated command buffer does not contain a Write to Display
Get AID (QsnGetAID) waits for an AID-generating key command, DSM implicitly issues a Write to Display
to be pressed. (QsnWTD) operation with control characters
Get Cursor Address QSN_CC1_NULL and QSN_CC2_UNLOCKBD before issuing
(QsnGetCsrAdr) gets the current cursor the read command.
address.
At most, one read command can be issued with a given
Get Cursor Address with AID
screen I/O operation. An attempt to add a read operation to
(QsnGetCsrAdrAID) gets the current cursor
a command buffer that already has one results in an error. If
address after an AID-generating key is
a command buffer contains a read command, the command
pressed.
buffer must be sent to the screen using the Put Command
Put Input Command
Buffer and Perform Get (QsnPutGetBuf) API. An attempt to
(QsnPutInpCmd) issues a supplied read
send such a buffer using the Put Command Buffer
command.
(QsnPutBuf) API will result in an error.
Read Immediate
(QsnReadImm) reads the contents of all input
fields on the display without requiring an AID
key to be pressed. Get AID (QsnGetAID) API
Read Input Fields
(QsnReadInp) reads the contents of all input
fields on the display requiring an AID key to Omissible Parameter Group:
be pressed.
1 AID code Output Char(1)
Read from Invited Device
2 Low-level environment Input Binary(4)
(QsnReadInvited) performs a read from invited
handle
device on a display that has already been 3 Error code I/O Char(*)
invited.
Read Modified Alternate Returned Value
(QsnReadMDTAlt) reads the contents of all
modified fields on the display, alternate form, AID code Output Char(1)
requiring an AID key to be pressed.
Service Program: QSNAPI
Read Modified Fields
(QsnReadMDT) reads the contents of all mod-
Threadsafe: No
ified fields requiring an AID key to be pressed.
Read Modified Immediate Alternate
(QsnReadMDTImmAlt) reads the contents of The Get AID (QsnGetAID) API waits for an AID-generating
all modified fields on the display, alternate key to be pressed.
form, without requiring an AID key to be
pressed. This command corresponds indirectly to the 5250 Read Input
Read Screen (QsnReadScr) reads the contents of the Fields command. Because the control characters specified
screen without requiring an AID key to be on the underlying command are both X'00', this operation
pressed. will cause the cursor to move to the insert cursor position
when the keyboard is unlocked.
The detailed API descriptions are presented in alphabetical
order.
Authorities and Locks
None

 Copyright IBM Corp. 1998, 1999 24-1

Get Cursor Address (QsnGetCsrAdr) API

Omissible Parameter Group

Omissible Parameter Group:
AID code
OUTPUT; CHAR(1) 1 Cursor row Output Binary(4)
The variable that contains the AID code when the 2 Cursor column Output Binary(4)
3 Low-level environment Input Binary(4)
QsnRtvReadAID API has completed.
handle
Low-level environment handle 4 Error code I/O Char(*)
INPUT; BINARY(4)
Returned Value:
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero, Return code Output Binary(4)
the default low-level environment is used.
Service Program: QSNAPI
Error code
I/O; CHAR(*) Threadsafe: No
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” The Get Cursor Address (QsnGetCsrAdr) API returns the
on page 2-6. If this parameter is omitted, diagnostic current cursor address, without requiring an AID-generating
and escape messages are issued to the application. key to be pressed. Either the cursor row or cursor column
parameter must be specified. If both of these parameters
are omitted, a CPFA31E error occurs.
Returned Value
AID code This command corresponds indirectly to the 5250 Read
OUTPUT; CHAR(1) Immediate command.

This API returns the value for the AID code parameter,
X'00' if a general error occurs during processing. Authorities and Locks
None
Error Messages
CPF24B4 E Severe error while addressing parameter list. Restrictions
CPF3CF1 E
Error code parameter not valid. The same restrictions apply as for the “Read Immediate
CPF3CF2 E (QsnReadImm) API” on page 24-5.
Error(s) occurred during running of &1 API.
CPFA303 E Error occurred for screen I/O operation.
CPFA304 E Data-stream error &1 reported for screen I/O Omissible Parameter Group
operation. Cursor row
CPFA326 E Screen must be redrawn. OUTPUT; BINARY(4)
CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done. The variable that contains the cursor row when the
CPFA344 E The file &2 in library &3 is not valid. QsnGetCsrAdr API has completed.
CPFA345 E The invite active flag is not valid. Cursor column
OUTPUT; BINARY(4)
The variable that contains the cursor column when the
Get Cursor Address (QsnGetCsrAdr) API QsnGetCsrAdr API has completed.

Low-level environment handle

INPUT; BINARY(4)
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
the default low-level environment is used.

Error code
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

24-2 AS/400 System API Reference V4R4

 Get Cursor Address with AID (QsnGetCsrAdrAID) API

Returned Value Authorities and Locks

Return code None
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The Omissible Parameter Group
value returned will be 0 if the operation was successful,
or -1 otherwise. Cursor row
OUTPUT; BINARY(4)

Error Messages The variable that contains the cursor row when the
QsnGetCsrAdrAID API has completed.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Cursor column
Error code parameter not valid. OUTPUT; BINARY(4)
CPFA304 E Data-stream error &1 reported for screen I/O
The variable that contains the cursor column when the
operation.
QsnGetCsrAdrAID API has completed.
CPF3CF2 E
Error(s) occurred during running of &1 API. AID code
CPFA31E E OUTPUT; CHAR(1)
Required parameter &1 omitted.
The variable that contains the AID code when the
CPFA334 E Low level environment handle incorrect.
QsnGetCsrAdrAID API has completed.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Low-level environment handle
CPFA345 E The invite active flag is not valid. INPUT; BINARY(4)
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero,
Get Cursor Address with AID the default low-level environment is used.
(QsnGetCsrAdrAID) API
Error code
I/O; CHAR(*)
Omissible Parameter Group: The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
1 Cursor row Output Binary(4) on page 2-6. If this parameter is omitted, diagnostic
2 Cursor column Output Binary(4) and escape messages are issued to the application.
3 AID code Output Char(1)
4 Low-level environment Input Binary(4)
handle Returned Value
5 Error code I/O Char(*)
Return code
Returned Value: OUTPUT; BINARY(4)
Return code Output Binary(4) A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
Service Program: QSNAPI or -1 otherwise.

Threadsafe: No
Error Messages
CPF24B4 E Severe error while addressing parameter list.
The Get Cursor Address with AID (QsnGetCsrAdrAID API
CPF3CF1 E
returns the cursor address after an AID-generating key is
Error code parameter not valid.
pressed. Either the cursor row or the cursor column param-
CPF3CF2 E
eter must be specified. If both of these parameters are
Error(s) occurred during running of &1 API.
omitted, a CPFA31E error occurs.
CPFA301 E Command buffer is full.
This command corresponds indirectly to the 5250 Read Input CPFA304 E Data-stream error &1 reported for screen I/O
Fields command. Because the control characters specified operation.
on the underlying command are both X'00', this operation CPFA305 E Cannot add operation to command buffer.
may cause the cursor to move to the default, or insert cursor, CPFA31E E
position when the keyboard is unlocked. Required parameter &1 omitted.
CPFA326 E Screen must be redrawn.
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect.

Chapter 24. Screen Input APIs 24-3

Put Input Command (QsnPutInpCmd) API

CPFA343 E Output operation not done. This is a direct operation. The input operation is issued
CPFA344 E The file &2 in library &3 is not valid. to the screen, and the resulting input data is stored in
CPFA345 E The invite active flag is not valid. the input buffer.
Ÿ Both a command buffer handle and an input buffer
handle are specified with nonzero values.
Put Input Command (QsnPutInpCmd) API
This is a direct operation. The input operation is
appended to the command stream given by the
command buffer, and the entire command stream is
Required Parameter:
written to the display. The resulting input data is stored
1 Command Input Char(1) in the input buffer. The contents of the command buffer
are not affected by this operation. That is, the input
Omissible Parameter Group: operation is not stored in the command buffer.

2 Command data Input Char(*) This operation corresponds to an Escape character followed
3 Command data length Input Binary(4) by the specified command.
4 Number of data bytes Output Binary(4)
read
5 Input buffer handle Input Binary(4) Authorities and Locks
6 Command buffer handle Input Binary(4)
7 Low-level environment Input Binary(4) None
handle
8 Error code I/O Char(*)
Required Parameter
Returned Value:
Command
Number of data bytes Output Binary(4) INPUT; CHAR(1)
read
The 1-byte character code for the input command to be
Service Program: QSNAPI issued. For example, to issue a Save Partial Screen
command, the command data should contain X'03' and
Threadsafe: No the command data will contain the dimensions of the
partial screen to be saved.

The Put Input Command (QsnPutInpCmd) API is used to

issue data stream input commands that are not directly sup- Omissible Parameter Group
ported through a DSM API. An Escape (X'04') character is
Command data
inserted in the stream directly before the command itself for
INPUT; CHAR(*)
both direct and indirect operations.
The data for the command to be issued.
You must use this operation to issue an input command that
is not directly supported by DSM as this will cause the appro- Command data length
priate underlying screen I/O operation to occur in order to INPUT; BINARY(4)
retrieve input. You cannot, for example, use the Put Output The length of the command data parameter.
Command (QsnPutOutCmd) API to issue an input command
because no input data will be requested by the underlying Number of data bytes read
DSM screen I/O operation. OUTPUT; BINARY(4)
The variable that contains the number of data bytes
The following command buffer handle and input buffer handle returned after the QsnPutInpCmd API has completed if a
combinations are valid. direct operation is specified. The parameter is not modi-
Ÿ The command buffer handle is specified with a nonzero fied for an indirect operation and the value remains
value. The input buffer handle is omitted or specified unchanged from whatever was passed.
with a zero value.
Input buffer handle
This is an indirect operation. The command is stored in INPUT; BINARY(4)
the command buffer without an I/O operation taking
A handle for the input buffer that receives the result of
place.
the input operation if a direct operation is specified.
Ÿ The command buffer handle is omitted or specified with
a zero value. The input buffer handle is specified with a Command buffer handle
nonzero value. INPUT; BINARY(4)
A handle for the command buffer in which to store the
command.

24-4 AS/400 System API Reference V4R4

 Read Immediate (QsnReadImm) API

Low-level environment handle

INPUT; BINARY(4) Omissible Parameter Group:
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero, 1 Number of field data Output Binary(4)
bytes read
the default low-level environment is used.
2 Input buffer handle Input Binary(4)
Error code 3 Command buffer handle Input Binary(4)
4 Low-level environment Input Binary(4)
I/O; CHAR(*)
handle
The structure in which to return error information. For 5 Error code I/O Char(*)
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Returned Value:
and escape messages are issued to the application.
Number of field data Output Binary(4)
bytes read
Returned Value
Service Program: QSNAPI
Number of data bytes read
OUTPUT; BINARY(4) Threadsafe: No

This API returns the value for the number of data bytes
read parameter if a direct operation was specified, or -1 The Read Immediate (QsnReadImm) API reads the contents
if an error occurs during processing. If this is an indirect of all input fields on the display without requiring an AID key
operation, this API returns zero if successful, or -1 if to be pressed. The command buffer handle or input buffer
there was a general failure. handle parameter must be specified as described in “Put
Input Command (QsnPutInpCmd) API” on page 24-4.
Error Messages The information returned depends on the condition of the
CPF24B4 E Severe error while addressing parameter list. master MDT bit. (See “Modified Data Tag (MDT) Bit” on
CPF3CF1 E page 21-5.) If the bit is not set, the input returned consists
Error code parameter not valid. of the cursor address and an AID code only. If the bit is set,
CPF3CF2 E the input returned also includes the field data in the data
Error(s) occurred during running of &1 API. portion of the input buffer. In each case, the returned cursor
CPFA301 E Command buffer is full. address indicates the current location of the cursor and an
CPFA303 E Error occurred for screen I/O operation. AID code of X'00'. The format of the field data returned is
CPFA304 E Data-stream error &1 reported for screen I/O the same as that for the Read Input Fields (QsnReadInp)
operation. API.
CPFA305 E Cannot add operation to command buffer.
CPFA313 E Command buffer already contains an input This command corresponds directly to the 5250 Read Imme-
operation. diate command.
CPFA31E E
Required parameter &1 omitted. Authorities and Locks
CPFA331 E Buffer handle incorrect.
CPFA333 E Parameter &1 not positive integer value. None
CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Restrictions
CPFA345 E The invite active flag is not valid.
This command must be the last command in the command
buffer. A CPFA305 error is issued if there is a subsequent
attempt to add another command to the specified command
Read Immediate (QsnReadImm) API buffer after this command.

Omissible Parameter Group

Number of field data bytes read
OUTPUT; BINARY(4)
The variable that contains the number of field data bytes
returned after the QsnReadImm API has completed if a
direct operation is specified. The parameter is not modi-
fied for an indirect operation and the value remains
unchanged from whatever was passed.

Chapter 24. Screen Input APIs 24-5

Read Input Fields (QsnReadInp) API

Input buffer handle CPFA345 E The invite active flag is not valid.
INPUT; BINARY(4)
A handle for the input buffer that receives the result of
the input operation if a direct operation is specified. Read Input Fields (QsnReadInp) API
The result can be queried using the input buffer query
operations. See “Retrieve Pointer to Field Data
(QsnRtvFldDta) API” on page 23-16 Required Parameter Group:
and “Retrieve Length of Field Data in Buffer
1 Control character byte 1 Input Char(1)
(QsnRtvFldDtaLen) API” on page 23-13 .
2 Control character byte 2 Input Char(1)
Command buffer handle
INPUT; BINARY(4) Omissible Parameter Group:

A handle for the command buffer in which to store the 3 Number of field data Output Binary(4)
command. bytes read
4 Input buffer handle Input Binary(4)
Low-level environment handle 5 Command buffer handle Input Binary(4)
INPUT; BINARY(4) 6 Low-level environment Input Binary(4)
handle
The low-level environment that the operation applies to. 7 Error code I/O Char(*)
If this parameter is omitted or given with a value of zero,
the default low-level environment is used. Returned Value:
Error code Number of field data Output Binary(4)
I/O; CHAR(*) bytes read
The structure in which to return error information. For
Service Program: QSNAPI
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Threadsafe: No
and escape messages are issued to the application.

The Read Input Fields (QsnReadInp) API reads the contents

Returned Value of all input fields on the display while requiring an
Number of field data bytes read AID-generating key to be pressed. The command buffer
OUTPUT; BINARY(4) handle or input buffer handle parameter must be specified as
described in “Put Input Command (QsnPutInpCmd) API” on
This API returns the value for the number of field data
page 24-4. The format of the data returned is:
bytes read parameter if a direct operation was specified,
or -1 if an error occurs during processing. If this is an Cursor AID Code Field Data Field Data Field Data
Address in 1 byte
indirect operation, this API returns zero if successful, or Row/Column
FMT
-1 otherwise. 2 bytes

Error Messages The information returned depends on the condition of the

master MDT bit (see “Modified Data Tag (MDT) Bit” on
CPF24B4 E Severe error while addressing parameter list. page 21-5) and the AID-generating key pressed. If the bit is
CPF3CF1 E not set, the input returned consists of the cursor address and
Error code parameter not valid. an AID code only. If the bit is set, the input returned also
CPF3CF2 E includes the field data in the data portion of the input buffer.
Error(s) occurred during running of &1 API. In either case, the returned cursor address indicates the
CPFA301 E Command buffer is full. location of the cursor when the AID-generating key was
CPFA302 E Command buffer or input buffer parameters pressed and the AID code for the AID-generating key the
required. operator used. See “AID-Generating Keys” on page 21-2 for
CPFA304 E Data-stream error &1 reported for screen I/O a description of the AID-generating character values.
operation.
CPFA305 E Cannot add operation to command buffer. Field data is returned only when one of the following
CPFA309 E Invalid cursor position in command buffer. AID-generating keys is used:
CPFA313 E Command buffer already contains an input
Roll Up
operation.
CPFA331 E Buffer handle incorrect. Roll Down
CPFA334 E Low level environment handle incorrect. Enter/Auto Record Advance
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Auto Enter
An unmasked command function key

24-6 AS/400 System API Reference V4R4

 Read Input Fields (QsnReadInp) API

The field data, when returned, consists of the contents of all operation has been serviced. See “Control Characters”
input fields as they appear on the display, unless rese- on page 21-2 for a description of the control character
quencing has been specified. (See “Resequencing” on values.
page 21-5.) Any attributes contained in a field are treated as
Control character byte 2
data and returned as such. The attributes that start and end
INPUT; CHAR(1)
a field are not returned. These are considered to be outside
the boundaries of the field. No field delimiters are added; The operation for the display to perform after the read
data from each field is followed directly by the data from the operation and control character byte 1 have been ser-
next field. Data for nontransparent fields is formatted as viced. See “Control Characters” on page 21-2 for a
follows: description of the control character values.
Ÿ All nulls (leading, embedded, or trailing) are converted to
blanks. Omissible Parameter Group
Ÿ If the specified field is a signed numeric field: Number of field data bytes read
– The last character of the field is stripped off. OUTPUT; BINARY(4)
– The last location of the field is checked for a nega- The variable that contains the number of field data bytes
tive sign. If detected, the zone portion of the returned after the QsnReadInp API has completed if a
second to last character of the field is changed to a direct operation is specified. The parameter is not modi-
X'D'. fied for an indirect operation and the value remains
unchanged from whatever was passed.
The data returned for transparent fields is not edited. A
transparent field is defined with a transparency field control Input buffer handle
word X'84yy'. (See “Set Field (QsnSetFld) API” on INPUT; BINARY(4)
page 25-11.) Each field read is returned unedited with no A handle for the input buffer that receives the result of
intervening control information. If a field is both transparent the input operation if a direct operation is specified.
and signed numeric, unpredictable results can occur in the The result can be queried using the input buffer query
field data. operations. See “Retrieve Pointer to Field Data
(QsnRtvFldDta) API” on page 23-16 and “Retrieve
This command corresponds directly to the 5250 Read Input Length of Field Data in Buffer (QsnRtvFldDtaLen) API”
Fields command. on page 23-13.

Command buffer handle

Restrictions INPUT; BINARY(4)
This command cannot be issued if the control unit supports A handle for the command buffer in which to store the
ideographic data types. A CPFA306 error will occur if an command.
attempt is made to issue this command to a control unit that
Low-level environment handle
supports ideographic data types.
INPUT; BINARY(4)
Some control units, like those emulated by the Client Access The low-level environment that the operation applies to.
program, do not support a control character associated with If this parameter is omitted or given with a value of zero,
input commands. For such units, the control character speci- the default low-level environment is used.
fied would be ignored. A program could cause further
actions to be suspended if, for example, the control character Error code
byte 2 specified to unlock the keyboard and this action was I/O; CHAR(*)
not specified elsewhere in the data stream. If the underlying The structure in which to return error information. For
control unit does not support a control character with input the format of the structure, see “Error Code Parameter”
commands, you must specify the action to perform using the on page 2-6. If this parameter is omitted, diagnostic
QsnWTD API. and escape messages are issued to the application.

Authorities and Locks Returned Value

None Number of field data bytes read
OUTPUT; BINARY(4)
Required Parameter Group This API returns the value for the number of field data
bytes read parameter if a direct operation was specified,
Control character byte 1 or -1 if an error occurs during processing. If this is an
INPUT; CHAR(1) indirect operation, this API returns zero if successful, or
The operation for the display to perform after the read -1 otherwise.

Chapter 24. Screen Input APIs 24-7

Read from Invited Device (QsnReadInvited) API

Error Messages added to the data stream. Then the read from invited device
will be issued.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E The input buffer handle parameter must be specified.
Error code parameter not valid.
CPF3CF2 E See the appropriate read API for information on the format of
Error(s) occurred during running of &1 API. the data returned.
CPFA301 E Command buffer is full.
CPFA302 E Command buffer or input buffer parameters
required.
Authorities and Locks
CPFA303 E Error occurred for screen I/O operation. None
CPFA304 E Data-stream error &1 reported for screen I/O
operation.
CPFA305 E Cannot add operation to command buffer. Restrictions
CPFA309 E Invalid cursor position in command buffer.
CPFA313 E Command buffer already contains an input The invite active flag must be on in the low level environment
operation. description.
CPFA31C E
An error will be issued if the command buffer is empty, or not
Incorrect value for control character byte &1.
specified, and no other write has been done with the invite
CPFA31E E
active flag on in the low level environment description.
Required parameter &1 omitted.
CPFA326 E Screen must be redrawn.
CPFA331 E Buffer handle incorrect. Required Parameter Group
CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done. Input buffer handle
CPFA344 E The file &2 in library &3 is not valid. INPUT; BINARY(4)
CPFA345 E The invite active flag is not valid. A handle for the input buffer that receives the result of
the input operation if a direct operation is specified. The
result can be queried using the input buffer query oper-
Read from Invited Device (QsnReadInvited) ations.
API
Omissible Parameter Group
Required Parameter Group: Command buffer handle
INPUT; BINARY(4)
1 Input buffer handle Input Binary(4)
A handle for the command buffer in which to find the
Omissible Parameter Group: read command.
If no read command is found in the specified command
2 Command buffer handle Input Binary(4)
buffer, a read MDT with null control characters will be
3 Low-level environment Input Binary(4)
added to the data stream. This is the equivalent of
handle
4 Return code Output Binary(4) calling the QsnReadMDT API.
5 Error code I/O Char(*)
Low-level environment handle
INPUT; BINARY(4)
Returned Value:
The low-level environment that the operation applies to.
Return code Output Binary(4) If this parameter is omitted or given with a value of zero,
the default low-level environment is used.
Service Program: QSNAPI
Return code
OUTPUT; BINARY(4)
The Read from Invited Device (QsnReadInvited) API issues a
read from invited device operation. Data will be returned in A return code indicating the result of the operation. The
the format corresponding to the read command used. value returned will be 0 if the operation was successful,
-1 if there was a general failure, and -2 if the operation
If the command buffer handle is specified and there is data was a read from invited device which timed out.
to be sent in the command buffer, a QsnPutBuf will be
Check the WAITRCD parameter on the display file spec-
issued to send the data to the screen. If no read command
ified in the low level environment description, to deter-
is in the command buffer, a read MDT command will be
mine the time out value.

24-8 AS/400 System API Reference V4R4

 Read Modified Alternate (QsnReadMDTAlt) API

Error code
I/O; CHAR(*) Required Parameter Group:
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” 1 Control character byte 1 Input Char(1)
2 Control character byte 1 Input Char(1)
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Omissible Parameter Group:

3 Field count Output Binary(4)

Returned Value 4 Input buffer handle Input Binary(4)
5 Command buffer handle Input Binary(4)
Return code
6 Low-level environment Input Binary(4)
OUTPUT; BINARY(4)
handle
A return code indicating the result of the operation. The 7 Error code I/O Char(*)
value returned will be 0 if the operation was successful,
-1 if there was a general failure, and -2 if the operation Returned Value:
was a read from invited device which timed out. Field count Output Binary(4)
Check the WAITRCD parameter on the display file spec-
ified in the low level environment description, to deter- Service Program: QSNAPI
mine the time out value.
Threadsafe: No

Error Messages
The Read Modified Alternate (QsnReadMDTAlt) API reads
CPF24B4 E Severe error while addressing parameter list. the contents of all modified fields on the screen, alternate
CPF3CF1 E form, requiring an AID-generating key to be pressed. The
Error code parameter not valid. QsnReadMDTAlt API is functionally equivalent to the
CPF3CF2 E QsnReadMDT API with the following exceptions:
Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full. Ÿ Leading and embedded nulls within the fields remain
CPFA304 E Data-stream error &1 reported for screen I/O nulls. However, trailing nulls are stripped off.
operation. Ÿ For fields consisting entirely of nulls, but with their MDT
CPFA305 E Cannot add operation to command buffer. bit on, only the field's address is returned.
CPFA309 E Invalid cursor position in command buffer.
CPFA31E E See “Read Modified Fields (QsnReadMDT) API” on
Required parameter &1 omitted. page 24-10 for details.
CPFA326 E Screen must be redrawn.
CPFA327 E Low level environment description value incor- This command corresponds directly to the 5250 Read MDT
rect. Alternate command.
CPFA32F E
Buffer type incorrect. Authorities and Locks
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect. None
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
Restrictions
This command is not supported by all control units. A
Read Modified Alternate (QsnReadMDTAlt) CPFA306 error occurs if an attempt is made to issue this
API command to a control unit that does not support it.

Some control units, like those emulated by the Client Access

program, do not support a control character associated with
input commands. For such units, the control character speci-
fied would be ignored. A program could cause further
actions to be suspended if, for example, the control character
byte 2 specified to unlock the keyboard and this action was
not specified elsewhere in the data stream. If the underlying
control unit does not support a control character with input
commands, you must specify the action to perform using the
QsnWTD API.

Chapter 24. Screen Input APIs 24-9

Read Modified Fields (QsnReadMDT) API

Required Parameter Group Field count

OUTPUT; BINARY(4)
Control character byte 1
Returns the value for the field count parameter if a direct
INPUT; CHAR(1)
operation was specified or -1 if an error occurs during
The operation for the display to perform after the read processing. If this is an indirect operation, returns zero if
operation has been serviced. See “Control Characters” successful, or -1 otherwise.
on page 21-2 for a description of the control character
values.
Error Messages
Control character byte 2
CPF24B4 E Severe error while addressing parameter list.
INPUT; CHAR(1)
CPF3CF1 E
The operation for the display to perform after the read Error code parameter not valid.
operation and control character byte 1 have been ser- CPF3CF2 E
viced. See “Control Characters” on page 21-2 for a Error(s) occurred during running of &1 API.
description of the control character values. CPFA301 E Command buffer is full.
CPFA302 E Command buffer or input buffer parameters
required.
Omissible Parameter Group CPFA304 E Data-stream error &1 reported for screen I/O
Field count operation.
OUTPUT; BINARY(4) CPFA305 E Cannot add operation to command buffer.
CPFA306 E Command not supported by current device.
The variable that will contain the number of input fields
CPFA309 E Invalid cursor position in command buffer.
read after the QsnReadMDTAlt API has completed, if a
CPFA313 E Command buffer already contains an input
direct operation is specified. The parameter is not modi-
operation.
fied for an indirect operation and the value remains
CPFA31C E
unchanged from whatever was passed.
Incorrect value for control character byte &1.
Input buffer handle CPFA31E E
INPUT; BINARY(4) Required parameter &1 omitted.
CPFA326 E Screen must be redrawn.
A handle for the input buffer that receives the result of
CPFA331 E Buffer handle incorrect.
the input operation if a direct operation is specified.
CPFA334 E Low level environment handle incorrect.
The result can be queried using the input buffer query
CPFA343 E Output operation not done.
operations. See “Retrieve Pointer to Field Data
CPFA344 E The file &2 in library &3 is not valid.
(QsnRtvFldDta) API” on page 23-16 and “Retrieve
CPFA345 E The invite active flag is not valid.
Length of Field Data in Buffer (QsnRtvFldDtaLen) API”
on page 23-13.

Command buffer handle Read Modified Fields (QsnReadMDT) API

INPUT; BINARY(4)
A handle for the command buffer in which to store the
command. Required Parameter Group:

Low-level environment handle 1 Control character byte 1 Input Char(1)

INPUT; BINARY(4) 2 Control character byte 2 Input Char(1)

The low-level environment that the operation applies to. Omissible Parameter Group:
If this parameter is omitted or given with a value of zero,
the default low-level environment is used. 3 Field count Output Binary(4)
4 Input buffer handle Input Binary(4)
Error code 5 Command buffer handle Input Binary(4)
I/O; CHAR(*) 6 Low-level environment Input Binary(4)
handle
The structure in which to return error information. For 7 Error code I/O Char(*)
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Returned Value:
and escape messages are issued to the application.
Field count Output Binary(4)

Returned Value Service Program: QSNAPI

Threadsafe: No

24-10 AS/400 System API Reference V4R4

 Read Modified Fields (QsnReadMDT) API

The Read Modified Fields (QsnReadMDT) API reads the described in “Put Input Command (QsnPutInpCmd) API” on
contents of all modified fields on the screen requiring an page 24-4. See “Control Characters” on page 21-2 for a
AID-generating key to be pressed. The command buffer description of the control character values. The format of the
handle or input buffer handle parameter must be specified as data returned is:

Cursor AID Code SBA Field Field Data SBA Field Field Data
Row/ Column 1 byte X'11' Row/ Column X'11' Row/ Column
2 bytes 2 bytes 2 bytes

The information returned depends on the state of the MDT Restrictions

bit for each field (see “Modified Data Tag (MDT) Bit” on
page 21-5) and the AID-generating key used. If no bits are Some control units, like those emulated by the Client Access
set, the input returned consists of the cursor address and an program, do not support a control character associated with
AID code only. If at least one bit is set, the input may also input commands. For such units, the control character speci-
include field data. In each case, the returned cursor address fied would be ignored. A program could cause further
indicates the location of the cursor when the AID-generating actions to be suspended if, for example, the control character
key was pressed and the AID code for the AID-generating byte 2 specified to unlock the keyboard and this action was
key the operator used. not specified elsewhere in the data stream. If the underlying
control unit does not support a control character with input
Field data is returned only when one of the following commands, you must specify the action to perform using the
AID-generating keys is used: QsnWTD API.
Roll Up
Roll Down Authorities and Locks
Enter/Auto Record Advance None
An unmasked command function key

The field data, when returned, consists of the row and Required Parameter Group
column address and the contents of each field that has an Control character byte 1
MDT bit on as they appear on the display, unless rese- INPUT; CHAR(1)
quencing has been specified. (See “Resequencing” on
page 21-5.) The input buffer query routines “Retrieve The operation for the display to perform after the read
Number of Fields Read (QsnRtvFldCnt) API” on page 23-14 operation has been serviced. See “Control Characters”
and “Retrieve Field Information (QsnRtvFldInf) API” on on page 21-2 or a description of the control character
page 23-11 can be used to retrieve the value for each field. values.
(To interpret the data directly, QsnRtvDta can be used to Control character byte 2
obtain a pointer for the data portion of the input buffer. The INPUT; CHAR(1)
first data byte will be the SBA order for the first field as
defined in the 5250 data stream documentation.) The operation for the display to perform after the read
operation and control character byte 1 have been ser-
Data for nontransparent fields is formatted as follows: viced. See “Control Characters” on page 21-2 for a
description of the control character values.
Ÿ Leading and embedded nulls within the field are trans-
lated to blanks, and trailing nulls are stripped off. Only
the field's address is returned for fields whose MDT bit is Omissible Parameter Group
on but which consist entirely of nulls.
Field count
Ÿ If the specified field is a signed numeric field: OUTPUT; BINARY(4)
– The last character of the field is stripped off unless it The variable that contains the number of input fields
was previously stripped because it was null. read after the QsnReadMDT API has completed if a
– The last location of the field is checked for a nega- direct operation is specified. The parameter is not modi-
tive sign. If detected, the zone portion of the fied for an indirect operation and the value remains
second to last character of the field is changed to a unchanged from whatever was passed.
X'D'.
Input buffer handle
Ÿ If the field is a transparent field, no formatting is per- INPUT; BINARY(4)
formed.
A handle for the input buffer that receives the result of
If a field is both transparent and signed numeric, unpredict- the input operation if a direct operation is specified. The
able results can occur in the field data. result can be queried using the input buffer query oper-
ations. See “Retrieve Pointer to Field Data
This command corresponds directly to the 5250 Read MDT
Fields command.

Chapter 24. Screen Input APIs 24-11

Read Modified Immediate Alternate (QsnReadMDTImmAlt) API

(QsnRtvFldDta) API” on page 23-16 and “Retrieve

Length of Field Data in Buffer (QsnRtvFldDtaLen) API” Read Modified Immediate Alternate
on page 23-13. (QsnReadMDTImmAlt) API
Command buffer handle
INPUT; BINARY(4) Omissible Parameter Group:
A handle for the command buffer in which to store the
command. 1 Field count Output Binary(4)
2 Input buffer handle Input Binary(4)
Low-level environment handle 3 Command buffer handle Input Binary(4)
INPUT; BINARY(4) 4 Low-level environment Input Binary(4)
handle
The low-level environment that the operation applies to. 5 Error code I/O Char(*)
If this parameter is omitted or given with a value of zero,
the default low-level environment is used. Returned Value:

Error code Field count Output Binary(4)

I/O; CHAR(*)
Service Program: QSNAPI
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Threadsafe: No
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
The Read Modified Immediate Alternate
(QsnReadMDTImmAlt) API reads the contents of all modified
Returned Value fields on the display without requiring an AID-generating key
Field count to be pressed. Processing for this API is the same as for the
OUTPUT; BINARY(4) Read Immediate (QsnReadImm) API, except that data is
returned only for those fields that have the MDT bit on. The
This API returns the value for the field count parameter if format of the data returned is the same as for the Read Mod-
a direct operation was specified, or -1 if an error occurs ified Alternate (QsnReadMDTAlt) API.
during processing. If this is an indirect operation, this
API returns zero if successful, or -1 otherwise. See “Read Immediate (QsnReadImm) API” on page 24-5
and “Read Modified Alternate (QsnReadMDTAlt) API” on
page 24-9 for details.
Error Messages
CPF24B4 E Severe error while addressing parameter list. This command corresponds directly to the 5250 Read MDT
CPF3CF1 E Immediate Alternate command.
Error code parameter not valid.
CPF3CF2 E
Restrictions
Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full. This command is not supported by all control units. A
CPFA302 E Command buffer or input buffer parameters CPFA306 error occurs if an attempt is made to issue this
required. command to a control unit that does not support it.
CPFA304 E Data-stream error &1 reported for screen I/O
operation.
CPFA305 E Cannot add operation to command buffer. Authorities and Locks
CPFA309 E Invalid cursor position in command buffer.
CPFA313 E Command buffer already contains an input None
operation.
CPFA31C E Omissible Parameter Group
Incorrect value for control character byte &1.
CPFA31E E Field count
Required parameter &1 omitted. OUTPUT; BINARY(4)
CPFA326 E Screen must be redrawn. The variable that contains the number of input fields
CPFA331 E Buffer handle incorrect. read after the QsnReadMDTImmAlt API has completed if
CPFA334 E Low level environment handle incorrect. a direct operation is specified. The parameter is not
CPFA343 E Output operation not done. modified for an indirect operation and the value remains
CPFA344 E The file &2 in library &3 is not valid. unchanged from whatever was passed.
CPFA345 E The invite active flag is not valid.

24-12 AS/400 System API Reference V4R4

 Read Screen (QsnReadScr) API

Input buffer handle

INPUT; BINARY(4) Read Screen (QsnReadScr) API
A handle for the input buffer that receives the result of
the input operation if a direct operation is specified. The Omissible Parameter Group:
result can be queried using the input buffer query oper-
ations. See “Retrieve Pointer to Field Data 1 Number of data bytes Output Binary(4)
(QsnRtvFldDta) API” on page 23-16 and “Retrieve read
Length of Field Data in Buffer (QsnRtvFldDtaLen) API” 2 Input buffer handle Input Binary(4)
on page 23-13. 3 Command buffer handle Input Binary(4)
4 Low-level environment Input Binary(4)
Command buffer handle handle
INPUT; BINARY(4) 5 Error code I/O Char(*)

A handle for the command buffer in which to store the Returned Value:
command.
Number of data bytes Output Binary(4)
Low-level environment handle read
INPUT; BINARY(4)
Service Program: QSNAPI
The low-level environment that the operation applies to.
If this parameter is omitted or given with a value of zero, Threadsafe: No
the default low-level environment is used.

Error code
The Read Screen (QsnReadScr) API reads the contents of
I/O; CHAR(*)
the entire screen without requiring an AID-generating key to
The structure in which to return error information. For be pressed. The command buffer handle or input buffer
the format of the structure, see “Error Code Parameter” handle parameter must be specified as described in “Put
on page 2-6. If this parameter is omitted, diagnostic Input Command (QsnPutInpCmd) API” on page 24-4.
and escape messages are issued to the application.
The data returned consists of the contents of the entire
display, including the attributes. No formatting or conversion
Returned Value is done. The data will be available in the data portion of the
Field count input buffer. The result of this operation can be queried using
OUTPUT; BINARY(4) the “Retrieve Length of Data in Input Buffer (QsnRtvDtaLen)
API” on page 23-12 and the “Retrieve Pointer to Data in
This API returns the value for the field count parameter if Input Buffer (QsnRtvDta) API” on page 23-15.
a direct operation was specified, or -1 if an error occurs
during processing. If this is an indirect operation, this This command corresponds directly to the 5250 Read Screen
API returns zero if successful, or -1 otherwise. command.

Error Messages Authorities and Locks

CPF24B4 E Severe error while addressing parameter list.
None
CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E Restrictions
Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full. The same restrictions apply as for the “Read Immediate
CPFA302 E Command buffer or input buffer parameters (QsnReadImm) API” on page 24-5. In addition, this
required. command cannot be issued if the control unit supports
CPFA304 E Data-stream error &1 reported for screen I/O ideographic data types. A CPFA306 error occurs if an
operation. attempt is made to issue this command to a control unit that
CPFA305 E Cannot add operation to command buffer. supports ideographic data types.
CPFA306 E Command not supported by current device.
CPFA309 E Invalid cursor position in command buffer.
Omissible Parameter Group
CPFA313 E Command buffer already contains an input
operation. Number of data bytes read
CPFA331 E Buffer handle incorrect. OUTPUT; BINARY(4)
CPFA334 E Low level environment handle incorrect.
The variable that contains the number of data bytes
CPFA343 E Output operation not done.
returned after the QsnReadScr API has completed if a
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.

Chapter 24. Screen Input APIs 24-13

Read Screen (QsnReadScr) API

direct operation is specified. The parameter is not modi- Returned Value

fied for an indirect operation and the value remains
unchanged from whatever was passed. Number of data bytes read
OUTPUT; BINARY(4)
Input buffer handle
INPUT; BINARY(4) This API returns the value for the number of data bytes
read parameter if a direct operation was specified, or -1
A handle for the input buffer that receives the result of if an error occurs during processing. If this is an indirect
the input operation if a direct operation is specified. operation, this API returns zero if successful, or -1 other-
The result can be queried using the input buffer query wise.
operations. See “Retrieve Pointer to Field Data
(QsnRtvFldDta) API” on page 23-16 and “Retrieve
Length of Field Data in Buffer (QsnRtvFldDtaLen) API” Error Messages
on page 23-13. CPF24B4 E Severe error while addressing parameter list.
Command buffer handle CPF3CF1 E
INPUT; BINARY(4) Error code parameter not valid.
CPF3CF2 E
A handle for the command buffer in which to store the Error(s) occurred during running of &1 API.
command. CPFA301 E Command buffer is full.
Low-level environment handle CPFA302 E Command buffer or input buffer parameters
INPUT; BINARY(4) required.
CPFA304 E Data-stream error &1 reported for screen I/O
The low-level environment that the operation applies to. operation.
If this parameter is omitted or given with a value of zero, CPFA305 E Cannot add operation to command buffer.
the default low-level environment is used. CPFA309 E Invalid cursor position in command buffer.
Error code CPFA313 E Command buffer already contains an input
I/O; CHAR(*) operation.
CPFA331 E Buffer handle incorrect.
The structure in which to return error information. For CPFA334 E Low level environment handle incorrect.
the format of the structure, see “Error Code Parameter” CPFA343 E Output operation not done.
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

24-14 AS/400 System API Reference V4R4

 Delete Field ID Definition (QsnDltFldId) API

Chapter 25. Screen Output APIs

Screen Output APIs—Introduction

Required Parameter:
The screen output APIs are used to define fields and write
1 Field ID Input Binary(4)
data and other information to the screen.
Omissible Parameter:
The screen output interfaces comprise the following:
Delete Field ID Definition 2 Error code I/O Char(*)
(QsnDltFldId) deletes a field ID definition.
Generate a Beep Returned Value:
(QsnBeep) generates a beep. Return code Output Binary(4)
Insert Cursor (QsnInsCsr) sets the insert cursor address.
Pad between Two Screen Addresses Service Program: QSNAPI
(QsnWrtPadAdr) pads the screen with charac-
ters between two points. Threadsafe: No
Pad for N Positions
(QsnWrtPad) pads the screen for a specified
The Delete Field ID Definition (QsnDltFldId) API deletes a
number of characters.
field ID definition. The screen appearance, including the
Put Output Command
fields defined on the screen, are not affected by this
(QsnPutOutCmd) writes a data stream
command.
command.
Set Cursor Address
(QsnSetCsrAdr) sets the position of the cursor Authorities and Locks
on the screen.
Set Error State None
(QsnSetErr) places the keyboard into prehelp
error state and optionally places a string on
the error line with cursor positioning support.
Required Parameter
Set Field (QsnSetFld) defines an input field on the Field ID
screen at a given row and column. INPUT; BINARY(4)
Set Output Address
The ID for the field definition to be deleted. Subsequent
(QsnSetOutAdr) sets the current display
references to this field ID result in a CPFA33C error.
address.
This parameter must be specified with a nonzero valid
Write Data (QsnWrtDta) writes data to the display at a
field value.
given row and column with standard attributes.
Write to Display
(QsnWTD) issues a Write to Display Omissible Parameter
command.
Write Structured Field Major Error code
(QsnWrtSFMaj) writes the major structure of a I/O; CHAR(*)
structured field. The structure in which to return error information. For
Write Structured Field Minor the format of the structure, see “Error Code Parameter”
(QsnWrtSFMin) writes the minor structure of a on page 2-6. If this parameter is omitted, diagnostic
structured field. and escape messages are issued to the application.
Write Transparent Data
(QsnWrtTDta) writes transparent data to the
display at a given row and column. Returned Value
Return code
The detailed API descriptions are presented in alphabetical
OUTPUT; BINARY(4)
order.
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
Delete Field ID Definition (QsnDltFldId) API or -1 otherwise.

Error Messages
CPF24B4 E Severe error while addressing parameter list.

 Copyright IBM Corp. 1998, 1999 25-1

Insert Cursor (QsnInsCsr) API

CPF3CF1 E If this parameter is omitted or given with a value of zero,

Error code parameter not valid. the default low-level environment is used.
CPF3CF2 E
Error code
Error(s) occurred during running of &1 API.
I/O; CHAR(*)
CPFA33C E
Undefined field ID &1. The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Generate a Beep (QsnBeep) API and escape messages are issued to the application.

Returned Value
Omissible Parameter Group:
Return code
1 Command buffer handle Input Binary(4) OUTPUT; BINARY(4)
2 Low-level environment Input Binary(4)
handle A return code indicating the result of the operation. The
3 Error code I/O Char(*) value returned will be 0 if the operation was successful,
or -1 otherwise.
Returned Value:

Return code Output Binary(4) Error Messages

CPF24B4 E Severe error while addressing parameter list.
Service Program: QSNAPI
CPF3CF1 E
Threadsafe: No Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
The Generate a Beep (QsnBeep) API generates a beep. CPFA301 E Command buffer is full.
The display address is not affected by this command. CPFA304 E Data-stream error &1 reported for screen I/O
operation.
This command corresponds directly to the 5250 Write to CPFA305 E Cannot add operation to command buffer.
Display (WTD) command with control character 1 equal to CPFA31E E
X'00' and control character 2 equal to X'04'. If this is an Required parameter &1 omitted.
indirect operation, this API issues a new WTD command to CPFA331 E Buffer handle incorrect.
the command buffer. CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done.
Authorities and Locks CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
None

Restrictions Insert Cursor (QsnInsCsr) API

The same restrictions apply as for the Write Data

(QsnWrtDta) API (see “Restrictions” on page 25-19). Omissible Parameter Group:

1 Field ID Input Binary(4)

Omissible Parameter Group 2 Cursor row Input Binary(4)
3 Cursor column Input Binary(4)
Command buffer handle 4 Command buffer handle Input Binary(4)
INPUT; BINARY(4) 5 Low-level environment Input Binary(4)
handle
A handle for the command buffer in which to store the 6 Error code I/O Char(*)
command. If this parameter is omitted or specified as 0,
this is a direct operation and the beep is generated Returned Value:
immediately. Otherwise, this is an indirect operation and
the command is stored in the command buffer without Return code Output Binary(4)
an I/O operation taking place.
Service Program: QSNAPI
Low-level environment handle
INPUT; BINARY(4) Threadsafe: No
The low-level environment that the operation applies to.

25-2 AS/400 System API Reference V4R4

 Insert Cursor (QsnInsCsr) API

The Insert Cursor (QsnInsCsr) API sets the insert-cursor Cursor column
address. The insert-cursor address specifies the home- INPUT; BINARY(4)
cursor address. (The position of the cursor when the host
The column at which to position the insert cursor. The
system unlocks the keyboard and the display station operator
column parameter must refer to a column no greater
presses the Home key.) The display address is not affected
than the current screen or window mode width (if
by this command if this is an indirect operation and the target
window mode is on). The actual screen column used for
command buffer contains an active Write to Display (WTD)
a screen I/O operation is calculated using the formula
command. Otherwise, a WTD command is inserted that
base+offset=actual. The base is the column location of
resets the display address to row 1 column 1.
the left window border (0 for full screen) if offset is pos-
itive, or the column location of the right window border
If bit 1 of the associated Write to Display command is set to
(screen width plus 1 for full screen) if offset is negative.
0 (which is the default), the cursor will be moved on the
The offset is the column parameter value specified,
screen when the QsnInsCsr API is called. To prevent the
and actual is the actual screen column to be used. A
cursor from being moved, the control character byte 2 bit
CPFA307 error occurs if an incorrect column value is
should be set to 1 and the Write to Display (QsnWTD) opera-
specified.
tion should be explicitly issued to a command buffer used by
the QsnInsCsr API. Command buffer handle
INPUT; BINARY(4)
This command corresponds indirectly to the 5250 Write to
Display (WTD) command with an Insert Cursor order. (For A handle for the command buffer in which to store the
an indirect operation, a WTD is placed in the command command. If this parameter is omitted or specified as 0,
buffer only if one does not already exist in that buffer.) this is a direct operation and the insert cursor is posi-
tioned at the specified location immediately. Otherwise,
this is an indirect operation and the command is stored
Authorities and Locks in the command buffer without an I/O operation taking
place.
None
Low-level environment handle
INPUT; BINARY(4)
Restrictions
The low-level environment that the operation applies to.
The same restrictions apply as for the Write Data If this parameter is omitted or given with a value of zero,
(QsnWrtDta) API. the default low-level environment is used.

Error code
Omissible Parameter Group I/O; CHAR(*)
Field ID The structure in which to return error information. For
INPUT; BINARY(4) the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
The field ID indicating the field at which to set the
and escape messages are issued to the application.
display address. If this parameter is specified with a
nonzero value, the row and column parameters are
ignored and the row and column values corresponding to Returned Value
the field ID are used to set the display address. Either
the field ID or the row and column parameters must be Return code
specified. OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
Cursor row
value returned will be 0 if the operation was successful,
INPUT; BINARY(4)
or -1 otherwise.
The row at which to position the insert cursor. The row
parameter must refer to a row no greater than the
current screen or window mode height (if window mode Error Messages
is enabled). The actual screen row used for a screen CPF24B4 E Severe error while addressing parameter list.
I/O operation is calculated using the formula CPF3CF1 E
base+offset=actual. The base is the row location of the Error code parameter not valid.
top window border (0 for full screen) if offset is posi- CPF3CF2 E
tive, or the row location of the bottom window border Error(s) occurred during running of &1 API.
(screen height plus 1 for full screen) if offset is nega- CPFA301 E Command buffer is full.
tive. The offset is the row parameter value specified, CPFA304 E Data-stream error &1 reported for screen I/O
and actual is the actual screen row to be used. A operation.
CPFA307 error occurs if an incorrect row value is speci- CPFA305 E Cannot add operation to command buffer.
fied.

Chapter 25. Screen Output APIs 25-3

Pad between Two Screen Addresses (QsnWrtPadAdr) API

CPFA307 E Screen position &1, &2 outside of display or Restrictions

window area.
CPFA31E E The same restrictions apply as for the Write Data
Required parameter &1 omitted. (QsnWrtDta) API.
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect.
CPFA33C E Required Parameter Group
Undefined field ID &1. Pad character
CPFA343 E Output operation not done. INPUT; CHAR(1)
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. The character to pad the screen with.

To row
INPUT; BINARY(4)
Pad between Two Screen Addresses The row at which to write the last pad character. If the
(QsnWrtPadAdr) API position to pad to is less than the position to pad from, a
CPFA31B error is issued. The row parameter must refer
to a row no greater than the current screen or window
Required Parameter Group: mode height (if window mode is enabled). The actual
screen row used for a screen I/O operation is calculated
1 Pad character Input Char(1)
using the formula base+offset=actual. The base is the
2 To row Input Binary(4)
3 To column Input Binary(4) row location of the top window border (0 for full screen)
if offset is positive, or the row location of the bottom
Omissible Parameter Group: window border (screen height plus 1 for full screen) if
offset is negative. The offset is the row parameter
4 From row Input Binary(4) value specified, and actual is the actual screen row to
5 From column Input Binary(4) be used. A CPFA307 error occurs if an incorrect row
6 Command buffer handle Input Binary(4)
value is specified.
7 Low-level environment Input Binary(4)
handle To column
8 Error code I/O Char(*)
INPUT; BINARY(4)
Returned Value: The column at which to write the last pad character.
The column parameter must refer to a column no greater
Return code Output Binary(4) than the current screen or window mode width (if
window mode is on). The actual screen column used for
Service Program: QSNAPI
a screen I/O operation is calculated using the formula
Threadsafe: No base+offset=actual. The base is the column location of
the left window border (0 for full screen) if offset is pos-
itive, or the column location of the right window border
The Pad between Two Screen Addresses (QsnWrtPadAdr) (screen width plus 1 for full screen) if offset is negative.
API pads the display repeatedly with a selected character The offset is the column parameter value specified,
between two positions on the screen. The current display and actual is the actual screen column to be used. A
address is set to the position given by the to-row and to- CPFA307 error occurs if an incorrect column value is
column values plus one. Padding may occur outside the specified.
logical window area defined by the low-level environment
window mode setting.
Omissible Parameter Group
This command corresponds indirectly to the 5250 Write to From row
Display (WTD) command with a Set Buffer Address order (if INPUT; BINARY(4)
the from row and from column parameters are specified) and
a Repeat to Address order. (For an indirect operation, a The row at which to write the first pad character. The
WTD is placed in the command buffer only if one does not row parameter must refer to a row no greater than the
already exist in that buffer.) current screen or window mode height (if window mode
is enabled). The actual screen row used for a screen
I/O operation is calculated using the formula
Authorities and Locks base+offset=actual. The base is the row location of the
top window border (0 for full screen) if offset is posi-
None
tive, or the row location of the bottom window border
(screen height plus 1 for full screen) if offset is nega-
tive. The offset is the row parameter value specified,

25-4 AS/400 System API Reference V4R4

 Pad for N Positions (QsnWrtPad) API

and actual is the actual screen row to be used. A Error Messages

CPFA307 error occurs if an incorrect row value is speci-
fied. CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
If both the from-row and from-column parameters are Error code parameter not valid.
omitted, the pad characters are written starting at the CPF3CF2 E
current display address. If the command is a direct Error(s) occurred during running of &1 API.
operation or the buffer specified does not contain a pre- CPFA301 E Command buffer is full.
ceding output operation that sets the display address, CPFA304 E Data-stream error &1 reported for screen I/O
the current display address is set to row 1, column 1, operation.
prior to writing the pad characters. Both the from-row CPFA305 E Cannot add operation to command buffer.
and from-column parameters must be specified, or both CPFA307 E Screen position &1, &2 outside of display or
parameters must be omitted. window area.
From column CPFA308 E Attempt to write data past end of display.
INPUT; BINARY(4) CPFA31B E
From position &1, &2 greater than to position
The column at which to write the first pad character. &3, &4.
The column parameter must refer to a column no greater CPFA31D E
than the current screen or window mode width (if Attempt to write outside of window area.
window mode is on). The actual screen column used for CPFA31E E
a screen I/O operation is calculated using the formula Required parameter &1 omitted.
base+offset=actual. The base is the column location of CPFA331 E Buffer handle incorrect.
the left window border (0 for full screen) if offset is pos- CPFA334 E Low level environment handle incorrect.
itive, or the column location of the right window border CPFA335 E Screen address parameter error.
(screen width plus 1 for full screen) if offset is negative. CPFA33C E
The offset is the column parameter value specified, Undefined field ID &1.
and actual is the actual screen column to be used. A CPFA343 E Output operation not done.
CPFA307 error occurs if an incorrect column value is CPFA344 E The file &2 in library &3 is not valid.
specified. CPFA345 E The invite active flag is not valid.
Command buffer handle
INPUT; BINARY(4)
A handle for the command buffer in which to store the
Pad for N Positions (QsnWrtPad) API
command. If this parameter is omitted or specified as 0,
this is a direct operation and the screen is padded with
the character specified between the positions specified Required Parameter Group:
inclusively. Otherwise, this is an indirect operation and 1 Pad character Input Char(1)
the command is stored in the command buffer without 2 Number of bytes Input Binary(4)
an I/O operation taking place.
Omissible Parameter Group:
Low-level environment handle
INPUT; BINARY(4) 3 Field ID Input Binary(4)
4 From row Input Binary(4)
The low-level environment that the operation applies to.
5 From column Input Binary(4)
If this parameter is omitted or given with a value of zero, 6 Command buffer handle Input Binary(4)
the default low-level environment is used. 7 Low-level environment Input Binary(4)
handle
Error code
8 Error code I/O Char(*)
I/O; CHAR(*)
The structure in which to return error information. For Returned Value:
the format of the structure, see “Error Code Parameter”
Return code Output Binary(4)
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Service Program: QSNAPI

Threadsafe: No
Returned Value
Return code
OUTPUT; BINARY(4) The Pad for N Positions (QsnWrtPad) API pads the display
with the given pad character for the specified number of
A return code indicating the result of the operation. The bytes. Padding starts at the row and column specified, or at
value returned will be 0 if the operation was successful,
or -1 otherwise.

Chapter 25. Screen Output APIs 25-5

Pad for N Positions (QsnWrtPad) API

the current display address if these parameters are omitted. row parameter must refer to a row no greater than the
To allow the QsnWrtPad operation to insert a group of char- current screen or window mode height (if window mode
acters without overwriting the ending screen attribute, the fol- is enabled). The actual screen row used for a screen
lowing conditions must be satisfied: I/O operation is calculated using the formula
base+offset=actual. The base is the row location of the
Ÿ The operation is an indirect operation.
top window border (0 for full screen) if offset is posi-
Ÿ The row and column parameters are omitted. tive, or the row location of the bottom window border
Ÿ The low-level environment description does not indicate (screen height plus 1 for full screen) if offset is nega-
that DBCS data is being used. tive. The offset is the row parameter value specified,
and actual is the actual screen row to be used. A
Ÿ The previous command saved in the command buffer
CPFA307 error occurs if an incorrect row value is speci-
was a Write Data (QsnWrtDta) operation.
fied.
If the row and column parameters are omitted and the If both the from-row and from-column parameters are
command is either a direct operation or the buffer specified omitted, the pad characters are written starting at the
does not contain a preceding output operation that sets the current display address. If this is the case and the
display address, then the current display address is set to command is a direct operation, or the buffer specified
row 1, column 1, prior to writing the pad characters. does not contain a preceding output operation that sets
the display address, the current display address is set to
If the from-row and from-column parameters are specified, row 1, column 1, prior to writing the pad characters.
this command corresponds indirectly to the 5250 Write to Both the from-row and from-column parameters must be
Display (WTD) command with a Set Buffer Address order. specified, or both parameters must be omitted.
(For an indirect operation, a WTD is placed in the command
buffer only if one does not already exist in the buffer.) From column
INPUT; BINARY(4)

Authorities and Locks The column at which to write the first pad character.
The column parameter must refer to a column no greater
None than the current screen or window mode width (if
window mode is on). The actual screen column used for
a screen I/O operation is calculated using the formula
Restrictions base+offset=actual. The base is the column location of
the left window border (0 for full screen) if offset is pos-
The same restrictions apply as for the Write Data
itive, or the column location of the right window border
(QsnWrtDta) API.
(screen width plus 1 for full screen) if offset is negative.
The offset is the column parameter value specified,
Required Parameter Group and actual is the actual screen column to be used. A
CPFA307 error occurs if an incorrect column value is
Pad character specified.
INPUT; CHAR(1)
Command buffer handle
The pad character to pad the screen with.
INPUT; BINARY(4)
Number of bytes A handle for the command buffer in which to store the
INPUT; BINARY(4) command. If this parameter is omitted or specified as 0,
The number of bytes to pad the screen for. this is a direct operation and the pad characters are
written to the screen at the current display address.
Otherwise, this is an indirect operation and the
Omissible Parameter Group command is stored in the command buffer without an I/O
Field ID operation taking place.
INPUT; BINARY(4) Low-level environment handle
The field ID indicating the field at which to set the INPUT; BINARY(4)
display address. If this parameter is specified with a The low-level environment that the operation applies to.
nonzero value, the row and column parameters are If this parameter is omitted or given with a value of zero,
ignored and the row and column values corresponding to the default low-level environment is used.
the field ID are used to set the display address. If
neither the field ID or row and column parameters are Error code
specified, the current display address is used. I/O; CHAR(*)

From row The structure in which to return error information. For

INPUT; BINARY(4) the format of the structure, see “Error Code Parameter”

The row at which to write the first pad character. The

25-6 AS/400 System API Reference V4R4

 Put Output Command (QsnPutOutCmd) API

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

and escape messages are issued to the application. 1 Command Input Char(1)

Omissible Parameter Group:

Returned Value
2 Command data Input Char(*)
Return code
3 Command Data Length Input Binary(4)
OUTPUT; BINARY(4) 4 Command buffer handle Input Binary(4)
A return code indicating the result of the operation. The 5 Low-level environment Input Binary(4)
value returned will be 0 if the operation was successful, handle
6 Error code I/O Char(*)
or -1 otherwise.
Returned Value:
Error Messages Return code Output Binary(4)
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Service Program: QSNAPI
Error code parameter not valid.
CPF3CF2 E Threadsafe: No
Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full. The Put Output Command (QsnPutOutCmd) API is used to
CPFA303 E Error occurred for screen I/O operation. issue data stream commands that are not directly supported
CPFA304 E Data-stream error &1 reported for screen I/O through a DSM API. An escape (X'04') character is
operation. inserted in the stream directly before the command itself for
CPFA305 E Cannot add operation to command buffer. both direct and indirect operations.
CPFA307 E Screen position &1, &2 outside of display or
window area. Note: The Write Data (QsnWrtDta) API should be used for
CPFA308 E Attempt to write data past end of display. issuing Write to Display command orders such as the Write
CPFA31D E Extended Attributes order.
Attempt to write outside of window area.
This operation corresponds to an escape character followed
CPFA31E E
by the specified command.
Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect.
CPFA333 E Parameter &1 not positive integer value. Authorities and Locks
CPFA334 E Low level environment handle incorrect.
CPFA335 E Screen address parameter error. None
CPFA33C E
Undefined field ID &1.
CPFA343 E Output operation not done.
Required Parameter
CPFA344 E The file &2 in library &3 is not valid. Command
CPFA345 E The invite active flag is not valid. INPUT; CHAR(1)
The 1-byte character code for the output command to be
issued. For example, to issue a Restore Partial Screen,
Put Output Command (QsnPutOutCmd) the command data should contain X'13', the command
API data will contain the restore data length followed by the
restore data, and the command data length will be 2
plus the restore data length.

Omissible Parameter Group

Command data
INPUT; CHAR(*)
The data for the command to be issued.

Command data length

INPUT; BINARY(4)
The length of the command data parameter. If 0 is
specified, the command data parameter is ignored. Oth-
erwise, the command data parameter is required.

Chapter 25. Screen Output APIs 25-7

Set Cursor Address (QsnSetCsrAdr) API

Command buffer handle

INPUT; BINARY(4) Omissible Parameter Group:
A handle for the command buffer in which to store the
command. If this parameter is omitted or specified as 0, 1 Field ID Input Binary(4)
2 Cursor row Input Binary(4)
this is a direct operation and the command is sent to the
3 Cursor column Input Binary(4)
display. If the command being sent is an input 4 Command buffer handle Input Binary(4)
command, you must specify a command buffer and then 5 Low-level environment Input Binary(4)
use the Put Command Buffer and Perform Get handle
(QsnPutGetBuf) API to issue the command and retrieve 6 Error code I/O Char(*)
the resulting input. Otherwise, this is an indirect opera-
tion and the command is stored in the command buffer Returned Value:
without an I/O operation taking place.
Return code Output Binary(4)
Low-level environment handle
INPUT; BINARY(4) Service Program: QSNAPI

The low-level environment that the operation applies to. Threadsafe: No

If this parameter is omitted or given with a value of zero,
the default low-level environment is used.
The Set Cursor Address (QsnSetCsrAdr) API sets the posi-
Error code tion of the cursor on the screen. The display address is not
I/O; CHAR(*) affected by this command if this is an indirect operation and
The structure in which to return error information. For the target command buffer contains an active Write to
the format of the structure, see “Error Code Parameter” Display (WTD) command. Otherwise, a WTD command will
on page 2-6. If this parameter is omitted, diagnostic be inserted that resets the display address to row 1 column
and escape messages are issued to the application. 1.

This command corresponds indirectly to the 5250 Write to

Returned Value Display command (WTD) with an Insert Cursor or Move
Cursor order. (For an indirect operation, a WTD is placed in
Return code the command buffer only if one does not already exist in that
OUTPUT; BINARY(4) buffer.) The Move Cursor order is used if the control unit
A return code indicating the result of the operation. The supports it (based on the 5250 Query command). Otherwise,
value returned will be 0 if the operation was successful, the Insert Cursor order is used.
or -1 otherwise.
If the Move Cursor order is supported, this API sets the
cursor without modifying the home address and without
Error Messages regard to the state of the keyboard. Otherwise, the behavior
CPF24B4 E Severe error while addressing parameter list. is the same as that of the Insert Cursor (QsnInsCsr) API.
CPF3CF1 E
If multiple QsnSetCsrAdr operations are applied to the same
Error code parameter not valid.
command buffer, only the last QsnSetCsrAdr operation is in
CPF3CF2 E
effect. The last QsnSetCsrAdr or QsnInsCsr operation deter-
Error(s) occurred during running of &1 API.
mines the cursor position. If the Move Cursor order is used,
CPFA301 E Command buffer is full.
the QsnSetCsrAdr negates any previous QsnInsCsr com-
CPFA303 E Error occurred for screen I/O operation.
mands in the command buffer, except for the last QsnInsCsr,
CPFA304 E Data-stream error &1 reported for screen I/O
which sets the home position. If the Insert Cursor order is
operation.
used, it negates any previous QsnInsCsr operations. If the
CPFA305 E Cannot add operation to command buffer.
Move Cursor order is supported, you can set the home posi-
CPFA31E E
tion and then move the cursor by issuing a QsnInsCsr first,
Required parameter &1 omitted.
followed by a QsnSetCsrAdr operation.
CPFA331 E Buffer handle incorrect.
CPFA333 E Parameter &1 not positive integer value.
CPFA334 E Low level environment handle incorrect. Authorities and Locks
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. None
CPFA345 E The invite active flag is not valid.
Restrictions
Set Cursor Address (QsnSetCsrAdr) API The same restrictions apply as for the Write Data
(QsnWrtDta) API.

25-8 AS/400 System API Reference V4R4

 Set Error State (QsnSetErr) API

Omissible Parameter Group indirect operation and the command is stored in the
command buffer without an I/O operation taking place.
Field ID
INPUT; BINARY(4) Low-level environment handle
INPUT; BINARY(4)
The field ID indicating the field at which to set the
display address. If this parameter is specified with a The low-level environment that the operation applies to.
nonzero value, the row and column parameters are If this parameter is omitted or given with a value of zero,
ignored and the row and column values corresponding to the default low-level environment is used.
the field ID are used to set the display address. Either Error code
the field ID or the row and column parameters must be I/O; CHAR(*)
specified.
The structure in which to return error information. For
Cursor row the format of the structure, see “Error Code Parameter”
INPUT; BINARY(4) on page 2-6. If this parameter is omitted, diagnostic
The row at which to position the cursor. The row param- and escape messages are issued to the application.
eter must refer to a row no greater than the current
screen or window mode height (if window mode is Returned Value
enabled). The actual screen row used for a screen I/O
operation is calculated using the formula Return code
base+offset=actual. The base is the row location of the OUTPUT; BINARY(4)
top window border (0 for full screen) if offset is posi- A return code indicating the result of the operation. The
tive, or the row location of the bottom window border value returned will be 0 if the operation was successful,
(screen height plus 1 for full screen) if offset is nega- or -1 otherwise.
tive. The offset is the row parameter value specified,
and actual is the actual screen row to be used. A
CPFA307 error occurs if an incorrect row value is speci- Error Messages
fied. CPF24B4 E Severe error while addressing parameter list.
Cursor column CPF3CF1 E
INPUT; BINARY(4) Error code parameter not valid.
CPF3CF2 E
The column at which to position the cursor. The column Error(s) occurred during running of &1 API.
parameter must refer to a column no greater than the CPFA301 E Command buffer is full.
current screen or window mode width (if window mode is CPFA304 E Data-stream error &1 reported for screen I/O
on). The actual screen column used for a screen I/O operation.
operation is calculated using the formula CPFA305 E Cannot add operation to command buffer.
base+offset=actual. The base is the column location of CPFA307 E Screen position &1, &2 outside of display or
the left window border (0 for full screen) if offset is pos- window area.
itive, or the column location of the right window border CPFA31E E
(screen width plus 1 for full screen) if offset is negative. Required parameter &1 omitted.
The offset is the column parameter value specified, CPFA331 E Buffer handle incorrect.
and actual is the actual screen column to be used. A CPFA334 E Low level environment handle incorrect.
CPFA307 error occurs if an incorrect column value is CPFA33C E
specified. Undefined field ID &1.
Command buffer handle CPFA343 E Output operation not done.
INPUT; BINARY(4) CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
A handle for the command buffer in which to store the
command. If this parameter is omitted or specified as 0,
this is a direct operation and the cursor is positioned at
the specified location immediately. Otherwise, this is an
Set Error State (QsnSetErr) API

Chapter 25. Screen Output APIs 25-9

Set Error State (QsnSetErr) API

other devices. A CPFA310 error is issued if the

Omissible Parameter Group: message data is too long.

Message length
1 Message Input Char(*)
2 Message length Input Binary(4)
INPUT; BINARY(4)
3 Field ID Input Binary(4) The number of bytes of message data to be displayed.
4 Cursor row Input Binary(4)
5 Cursor column Input Binary(4) Field ID
6 Starting monochrome Input Char(1) INPUT; BINARY(4)
attribute
7 Ending monochrome attri- Input Char(1) The field ID indicating the field at which to set the
bute display address. If this parameter is specified with a
8 Starting color attribute Input Char(1) nonzero value, the row and column parameters are
9 Ending color attribute Input Char(1) ignored and the row and column values corresponding to
10 Command buffer handle Input Binary(4) the field ID are used to set the display address.
11 Low-level environment Input Binary(4)
handle Cursor row
12 Error code I/O Char(*) INPUT; BINARY(4)

Returned Value: The row at which to position the cursor when the
message is displayed. The row parameter must refer to
Return code Output Binary(4) a row no greater than the current screen or window
mode height (if window mode is enabled). The actual
Service Program: QSNAPI screen row used for a screen I/O operation is calculated
using the formula base+offset=actual. The base is the
Threadsafe: No row location of the top window border (0 for full screen)
if offset is positive, or the row location of the bottom
The Set Error State (QsnSetErr) API places the keyboard window border (screen height plus 1 for full screen) if
into prehelp error state and optionally places a string on the offset is negative. The offset is the row parameter
error line. To place the keyboard in the prehelp error state, value specified, and actual is the actual screen row to
you must follow this API with an AID-associated read API be used. A CPFA307 error occurs if an incorrect row
such as QsnReadInp. value is specified.
If both the field ID and the row and column parameters
Either the cursor or the message parameters must be speci- are omitted, the cursor is not moved. The row and
fied to make the command valid. If neither of these are column parameters must be specified together, or both
used, a CPFA305 error is issued. If a cursor position is parameters must be omitted.
specified, the cursor is moved immediately to the location
given. This does not affect the cursor address set by the Cursor column
Insert Cursor (QsnInsCsr) API. INPUT; BINARY(4)
The column at which to position the cursor when the
When the operator presses the Help key (prehelp error state
message is displayed. The column parameter must
only) in response to the error condition, the message No
refer to a column no greater than the current screen or
help text is available is displayed.
window mode width (if window mode is on). The actual
This command corresponds directly to the 5250 Write Error screen column used for a screen I/O operation is calcu-
Code command. lated using the formula base+offset=actual. The base
is the column location of the left window border (0 for full
screen) if offset is positive, or the column location of
Authorities and Locks the right window border (screen width plus 1 for full
screen) if offset is negative. The offset is the column
None parameter value specified, and actual is the actual
screen column to be used. A CPFA307 error occurs if
Omissible Parameter Group an incorrect column value is specified.

Message Starting monochrome attribute

INPUT; CHAR(*) INPUT; CHAR(1)

The message to be displayed. This parameter is The initial screen attribute for monochrome displays. If
required if the message length parameter is specified as this parameter is omitted or specified as X'00', a
a nonzero value. The message data, including the starting attribute of high intensity blink is inserted. See
screen attributes, must not exceed 132 characters for “Screen Attribute Characters” on page 21-3 for a
devices that are in 27x132 mode, or 80 characters for all description of the screen attribute values. The starting
attribute is selected as for the QsnWrtDta API.

25-10 AS/400 System API Reference V4R4

 Set Field (QsnSetFld) API

Ending monochrome attribute CPFA304 E Data-stream error &1 reported for screen I/O
INPUT; CHAR(1) operation.
CPFA305 E Cannot add operation to command buffer.
The ending screen attribute for monochrome displays. If
CPFA307 E Screen position &1, &2 outside of display or
this parameter is omitted or specified as X'00', an
window area.
ending attribute of nondisplay is inserted. The ending
CPFA30D E
attribute is selected as for the QsnWrtDta API.
Invalid screen attribute.
Starting color attribute CPFA30F E
INPUT; CHAR(1) Required parameter not specified.
CPFA310 E Error message data/screen attributes exceed
The initial screen attribute for color displays. If this
display width.
parameter is omitted and color attributes are to be used,
CPFA31E E
no initial attribute is written to the display for the data.
Required parameter &1 omitted.
Ending color attribute CPFA331 E Buffer handle incorrect.
INPUT; CHAR(1) CPFA333 E Parameter &1 not positive integer value.
CPFA334 E Low level environment handle incorrect.
The ending screen attribute for color displays. If this
CPFA335 E Screen address parameter error.
parameter is omitted and color attributes are to be used,
CPFA33C E
no ending attribute is written to the display for the data.
Undefined field ID &1.
Command buffer handle CPFA33F E
INPUT; BINARY(4) Error occurred during data conversion.
CPFA343 E Output operation not done.
A handle for the command buffer in which to store the
CPFA344 E The file &2 in library &3 is not valid.
command. If this parameter is omitted or specified as 0,
CPFA345 E The invite active flag is not valid.
this is a direct operation and the error state is entered,
the cursor is moved to the specified position, and the
message, if specified, is displayed. Otherwise, this is an
indirect operation and the command is stored in the Set Field (QsnSetFld) API
command buffer without an I/O operation taking place.

Low-level environment handle Omissible Parameter Group:

INPUT; BINARY(4)
1 Field ID Input Binary(4)
The low-level environment that the operation applies to.
2 Field length Input Binary(4)
If this parameter is omitted or given with a value of zero,
3 Row Input Binary(4)
the default low-level environment is used. 4 Column Input Binary(4)
5 Field format word (FFW) Input Char(2)
Error code
6 Field control words Input Char(*)
I/O; CHAR(*) (FCW)
The structure in which to return error information. For 7 Number of field control Input Binary(4)
the format of the structure, see “Error Code Parameter” words
8 Monochrome attribute Input Char(1)
on page 2-6. If this parameter is omitted, diagnostic
9 Color attribute Input Char(1)
and escape messages are issued to the application.
10 Command buffer handle Input Binary(4)
11 Low-level environment Input Binary(4)
handle
Returned Value 12 Error code I/O Char(*)
Return code
OUTPUT; BINARY(4) Returned Value:

A return code indicating the result of the operation. The Return code Output Binary(4)
value returned will be 0 if the operation was successful,
or -1 otherwise. Service Program: QSNAPI

Threadsafe: No
Error Messages
CPF24B4 E Severe error while addressing parameter list. The Set Field (QsnSetFld) API defines an input field on the
CPF3CF1 E screen at the given row and column. The following occurs
Error code parameter not valid. when this command is issued to the control unit as a direct
CPF3CF2 E operation or when the buffer containing the command is
Error(s) occurred during running of &1 API. written out:
CPFA301 E Command buffer is full.
CPFA303 E Error occurred for screen I/O operation. Ÿ Any outstanding AID requests are cleared.

Chapter 25. Screen Output APIs 25-11

Set Field (QsnSetFld) API

Ÿ The keyboard is locked. using the current field definition values for those omitted
parameters.
Ÿ If there is an entry in the format table whose starting
address is equal to the address for this field, then that If this field is omitted or specified with a value of zero,
entry is modified. The FFW of the existing entry is then no field ID is associated with this field description.
replaced by the new FFW and the previous screen
Field length
starting attribute is overlaid with the new screen starting
INPUT; BINARY(4)
attribute. The ending screen attribute is not rewritten.
All FCWs and the length parameter are ignored. See The length of the field being defined. If no field ID is
the 5250 data stream documentation for details. specified, the length must be a positive integer value
greater than 1 for signed numeric fields and greater than
Ÿ If no entry can be found in the table for the field being
0 for all other field types. The entire field must fit on the
defined, a new entry will be added to the end of the
display. If a field ID is specified with a nonzero value,
table. However, the address must be greater than the
the length may be 0, in which case a field will not be
ending address of the field currently defined last in the
defined on the screen; however, this will associate the
format table or an error will occur. If the new entry is
field definition with the specified field ID.
valid, it will contain the field's FFW, the optional FCWs,
and the field's starting and ending address. An error will Row
occur if an attempt is made to define too many fields on INPUT; BINARY(4)
the screen (see the 5250 data stream documentation for
The row at which to define the field. The row parameter
details).
must refer to a row no greater than the current screen or
The display address after this operation will be the starting window mode height (if window mode is enabled). The
field address minus 1 if row and column are specified as actual screen row used for a screen I/O operation is cal-
valid positive integers or if this is the first field specified culated using the formula base+offset=actual. The
within the current WTD command. Otherwise, the display base is the row location of the top window border (0 for
address will be one position past the ending screen attribute. full screen) if offset is positive, or the row location of
the bottom window border (screen height plus 1 for full
This command corresponds indirectly to the 5250 Write to screen) if offset is negative. The offset is the row
Display (WTD) command with a Set Buffer Address order parameter value specified, and actual is the actual
and a Start of Field order if the row and column parameters screen row to be used. A CPFA307 error occurs if an
are specified. (For an indirect operation, a WTD is placed in incorrect row value is specified.
the command buffer only if one does not already exist in that
The starting field address will be the row and column
buffer.)
locations given if both parameters are specified. Other-
wise, it will be the current display address plus 1. If this
Authorities and Locks is the case and the command is a direct operation, or
the buffer specified does not contain a preceding output
None operation that sets the display address, the current
display address is set to row 1, column 1, prior to writing
the initial screen attribute and the field definition. The
Restrictions ending field address for this field is the starting field
The same restrictions apply as for the Write Data address plus the field length.
(QsnWrtDta) API, with the exception that the trailing field If a field ID is supplied along with a row and column, the
attribute can be written past the end of the screen. (It will be row and column parameters will be stored as specified.
suppressed by the control unit.) These parameters will be used as relative or actual
screen positions on a subsequent operation, depending
upon the window mode setting for the environment sup-
Omissible Parameter Group plied with that operation.
Field ID If a previously undefined field ID is supplied with this
INPUT; BINARY(4) operation, the row and column parameters must be
The field ID to be associated with this field. The value specified. Also, the row and column parameters must
specified can be any nonzero integer value. For APIs both be specified or omitted; one cannot be specified if
that accept a field ID parameter, this value can be sub- the other is omitted. A CPFA307 error occurs if an
sequently used instead of the row and column parameter incorrect cursor position is specified. On some devices,
to specify a screen address. If the given ID is already row and column can both be specified as 1, which will
defined, this operation will redefine that field ID with the cause the field to be defined at row 1, column 1, with a
values specified. To remove a field ID definition, use the screen attribute of normal (X'20'). If this is the case,
QsnDltFldId API. then any initial screen attribute parameters specified are
ignored. This is only supported by certain devices.
If a previously defined field ID is supplied and some or
all of the parameters are omitted, the field is defined

25-12 AS/400 System API Reference V4R4

 Set Field (QsnSetFld) API

Whether or not this is supported can be determined by attributes are to be used, X'20' is assumed. The initial
the Query 5250 (QsnQry5250) API. screen attribute is written one position to the left of the
starting field address. The ending screen attribute
Column
(X'20') is supplied by the controller and written at the
INPUT; BINARY(4)
end-of-field address plus 1.
The column at which to write the data. The column
The monochrome attribute and color attribute parame-
parameter must refer to a column no greater than the
ters consist of 1 byte that will be used as the screen
current screen or window mode width (if window mode is
attribute for a monochrome or a color display, respec-
on). The actual screen column used for a screen I/O
tively. One of these parameters will be selected based
operation is calculated using the formula
on the underlying display type, and the other will be dis-
base+offset=actual. The base is the column location of
carded. See “Screen Attribute Characters” on
the left window border (0 for full screen) if offset is pos-
page 21-3 for a description of the screen attribute
itive, or the column location of the right window border
values.
(screen width plus 1 for full screen) if offset is negative.
The offset is the column parameter value specified, Color attribute
and actual is the actual screen column to be used. A INPUT; CHAR(1)
CPFA307 error occurs if an incorrect column value is
The initial screen attribute for color displays. A screen
specified.
attribute is required for defining a field on the screen; if
Field format word (FFW) this parameter is omitted and color attributes are to be
INPUT; CHAR(2) used, X'20' is assumed. See “Screen Attribute
Characters” on page 21-3 for a description of the screen
The field format word is a 2-byte value that controls the
attribute values.
type of the field being defined. Figure 25-1 shows the
field types, and the corresponding bit to be set for each Command buffer handle
type. To omit this parameter, specify X'00' in both INPUT; BINARY(4)
characters of the parameter. You must specify this
A handle for the command buffer in which to store the
parameter to define an input field, and it is required if a
command. If this parameter is omitted or specified as 0,
field control word is specified.
this is a direct operation and the starting field address
Field control words (FCW) will be the supplied location. Otherwise, this is an indi-
INPUT; CHAR(*) rect operation and the command is stored in the
command buffer without an I/O operation taking place.
An array of 2-byte field control words. The field control
words are 2-byte values that request certain functions to Low-level environment handle
be performed. Figure 25-2 on page 25-16 shows the INPUT; BINARY(4)
valid field control word values, their function, and mne-
The low-level environment that the operation applies to.
monics for those values. FCWs will not be checked to
If this parameter is omitted or given with a value of zero,
see if they are formatted correctly or to see if the func-
the default low-level environment is used.
tion requested is valid for the current device. Errors of
this nature may be detected and reported when the Error code
FCW is required during subsequent command and key- I/O; CHAR(*)
stroke processing. See the 5250 data stream documen-
The structure in which to return error information. For
tation for further details about the meaning and use of
the format of the structure, see “Error Code Parameter”
these functions.
on page 2-6. If this parameter is omitted, diagnostic
Number of field control words and escape messages are issued to the application.
INPUT; BINARY(4)
The number of control words in the field control word Returned Value
array. Omitting this parameter or specifying it with a
Return code
value of 0 indicates that no field control words are speci-
OUTPUT; BINARY(4)
fied with the FCW parameter. If this parameter is speci-
fied with a nonzero value, the FCW parameter is A return code indicating the result of the operation. The
required; if the FCW parameter is omitted, a CPFA31E value returned will be 0 if the operation was successful,
error is issued. or -1 otherwise.

Monochrome attribute
INPUT; CHAR(1) Format of the Field Format Word
The initial screen attribute for monochrome displays. A The following table shows the field types and the bits to set
screen attribute is required for defining a field on the for each type for the field format word (FFW).
screen; if this parameter is omitted and monochrome

Chapter 25. Screen Output APIs 25-13

Set Field (QsnSetFld) API

Figure 25-1 (Page 1 of 3). Field Format Words

Field Type Bit To Set Mnemonic Description
0-15 QSN_NO_FFW If bits 0 to 15 are set to 0, then no FFW is used. The field
will be defined as an output field and its contents will not be
returned by operations such as the Read Input Fields
(QsnReadInp) API.
0-1 The first two bits of a field format word must be 01. The
mnemonic for every other field type includes this setting.
Bypass 2 QSN_FFW_BYPASS If this bit is set, this is a bypass field and entries are not
allowed in it. If the operator tries to enter something in this
field, an error results.
Dup Enable 3 QSN_FFW_DUP If this bit is set, duplication is allowed in the field. The con-
troller repeats X'1C' from the cursor position to the end of
the field when the operator presses the Dup key; this shows
on the display as an overstruck asterisk.
Modified data tag 4 QSN_FFW_MDT Setting this bit sets the modified data tag for this field. The
(MDT) field will then be read with the Read Modified Fields
(QsnReadMDT) API (see “Read Modified Fields
(QsnReadMDT) API” on page 24-10) as if the operator had
modified it.
Field Shift/ Edit Bits 5-7 Mnemonic Description
Specification
Alphabetic shift 000 QSN_FFW_ALPHA_SHIFT The field accepts all characters. The shift keys are acknowl-
edged. The characters on the lower symbol of each key are
valid.
Alphabetic only 001 QSN_FFW_ALPHA_ONLY The field accepts only characters A-Z (both uppercase and
lowercase) plus the comma (,), period (.), minus (-), space,
and DUP (if the DUP-enable bit is on in the associated Field
Format Word (FFW)). Other characters cause operator
errors. Some special characters for world trade countries are
also acceptable (see the 5250 data stream documentation).
Numeric shift 010 QSN_FFW_NUM_SHIFT The field accepts all characters from all keys.
Numeric only 011 QSN_FFW_NUM_ONLY The field accepts only characters 0-9 and the comma (,),
period (.), minus (-), plus (+), space, and DUP (if the
DUP-enable bit is on in the associated Field Format Word
(FFW)). Other characters cause operator errors.
The unit position of this field will carry the sign digit for the
field. If the field is exited with the Field - key, the last char-
acter in the field will be 'D' zoned, unless the last character in
the field is a '+', '-', ',', '.', or space, in which case an error will
be posted. In a right-adjusted field, the field will be right-
adjusted before any 'D' zoning or testing of the sign character
is performed. When a negative field (from the Field - key) is
returned, the units digit will have a 'D' zone.
Katakana shift 100 QSN_FFW_KATA This is the same as the alphabetic shift except that the key-
board is placed in the Katakana shift on the Japan Katakana
data entry, typewriter, and G keyboards. This reverses the
order of the cursor direction with respect to the screen. If the
display is in bidirectional mode, this changes the cursor direc-
tion to left to right; otherwise, it changes the cursor direction
to right to left.
Digits only 101 QSN_FFW_DIGIT_ONLY The field allows keys 0-9 and DUP (if the DUP-enable bit is
on in the associated Field Format Word (FFW)).

25-14 AS/400 System API Reference V4R4

 Set Field (QsnSetFld) API

Figure 25-1 (Page 2 of 3). Field Format Words

I/O 110 QSN_FFW_IO This field will not accept any data keys from the keyboard.
An operator error is posted if keystrokes are entered in this
field. The operator may move the cursor into and out of this
field similar to operation in any non-bypass input field (that is,
Field Advance will position the cursor to the start of the field).
This field can be used for input from feature devices such as
a magnetic stripe reader of selector light pen while data input
from the keyboard is excluded.
The Field +, Field Exit, and Dup keys are valid for this field
and performance is the same as that for any non-bypass
input field.
Signed Numeric 111 QSN_FFW_SIGNED_NUMERIC The field allows keys 0-9 and DUP (if the DUP-enable bit is
on in the associated Field Format Word (FFW)). Typing any
other character will cause an operator error display.
This field reserves the right-hand position for a sign display (-
for negative and null for positive); therefore, the largest
number of characters that can be entered into this field is one
less than the field length. A signed numeric field less than 2
characters long will cause an error to be flagged.
No digit may be keyed into the rightmost position; however,
the cursor can be positioned there by using the cursor move-
ment keys and then followed by the F+ or F- key. This allows
changing the sign without affecting the rest of the field.
If this field is not a mandatory fill or right-adjust field, it is still
handled as if it were specified as a right-adjust blank fill field.
If the Field - key is used to exit this field, the field will be
right-adjusted and a negative sign placed in the rightmost
position of the field. The Field Exit or Field + key will insert a
blank in the rightmost position and right-adjust this field.
Before this field is returned on an input operation, it is
changed as follows:
Ÿ If the rightmost character is a negative sign, the zone of
the low order digit is set to a X'D'.
Ÿ If the rightmost character is not a negative sign, the low
order digit is not changed.
In either case, the rightmost sign position is not sent to the
host.
Field Type Bit to Set Mnemonic Description
Auto Enter 8 QSN_FFW_AUTO_ENTER If this bit is set, this is an auto enter field. The auto enter
function occurs only for valid Field Exit/Field +, Field -, and
Dup exit keys, or if the last data character position is typed
into the auto enter field. After any required right-adjust, man-
datory fill, data duplicating, or check digit operations are suc-
cessfully performed, the auto enter function causes the panel
to be sent to the host as if the Enter key had been pressed.
Field Exit Required 9 QSN_FFW_AUTO_FER If this bit is set, a nondata key must be typed to leave the
field. When the last data character is typed into the last posi-
tion of the field, the cursor will remain under the character
and blink, signifying the controller is waiting for an exit key.
Any nondata key will satisfy the exit requirement (including
cursor movement or function keys).
Monocase 10 QSN_FFW_AUTO_MONOCASE If this bit is set, then regardless of the shift state of the type-
writer keyboard, only the uppercase A-Z is entered into the
field being typed (that is, if a lowercase a is typed, the upper-
case A is entered). All other characters are unaffected.
Certain characters on some world trade typewriter keyboards
will also be translated to uppercase (see the 5250 data
stream documentation).

Chapter 25. Screen Output APIs 25-15

Set Field (QsnSetFld) API

Figure 25-1 (Page 3 of 3). Field Format Words

Reserved 11
Mandatory Enter 12 QSN_FFW_ME If this bit is set, the operator must enter something in the field
before the controller allows the Enter key to be active. The
controller recognizes the state of these fields by checking the
MDT bit for the field. If the operator tries to bypass the field
using a Field +, Field -, or Field Exit key, an error occurs.
Right-Adjust/ Manda- Bits 13-15 Mnemonic Description
tory Fill
No adjust specified 000 QSN_FFW_NOADJUST No field adjustment occurs.
Reserved 001
Reserved 010
Reserved 011
Reserved 100
Right-adjust, zero fill 101 QSN_FFW_RA_ZERO All leftmost unoccupied positions of a field are filled with zero.
Characters are right-adjusted and spaces are zero-filled. The
fill character will appear on the display.
Right-adjust is only activated by keying the Field Exit, Field +,
or Field - keys. The field is right-adjusted from the first non-
null character to the left of the cursor when one of these keys
is depressed. If a right-adjust field is left through cursor
movement keys, the field will remain as is (not right-adjusted).
Right-adjust fields longer than 15 characters might cause a
slow response that would result in a keyboard overrun. A
right-adjust specified field has an implied field exit required
function.
The Dup key will fill a right-adjust field from the cursor to the
end of the field with the Dup character (X'1C'), but the field
will not be right-adjusted. After typing the first character into
a right adjust field, but prior to exiting the field (using cursor
movement or exit keys), the Enter key will cause an operator
error to be posted; that is, Enter is invalid from an active
right-adjust field.
Right-adjust, blank fill 110 QSN_FFW_RA_BLANK The field behavior is the same as for right-adjust, zero fill, but
the fill character is blank instead of zero.
Mandatory fill 111 QSN_FFW_MF Once any data has been entered into the field, the field must
be completely filled before exiting it. Any attempt to leave an
unfilled field causes an error. The cursor may pass into and
out of a mandatory fill field as a result of cursor movement
keys without fill-checking or error posting by the controller, as
long as no data is entered into the field.
The Dup key will fill the field from the cursor to the end of
field with the Dup characters X'2C', and then the entire field
will be checked for any nulls (an error is posted if a null is
found). A mandatory fill field with nulls can be returned under
the following conditions:
1. The field was initialized with nulls and with the MDT bit
on.
2. The Erase Input, Field Exit, or Field + key is used from
the first position of the field. The field is filled with nulls
and the MDT bit is set on.
The above fields, with no further entry, can be returned with
all data as blanks on a Read Input Fields (QsnReadInp) oper-
ation or as a null field on a Read Modified Fields
(QsnReadMDT) operation.

Format of the Field Control Word

25-16 AS/400 System API Reference V4R4

 Set Output Address (QsnSetOutAdr) API

Figure 25-2. Field Control Words

FCW Value Mnemonic Description
X'80nn' QSN_FCW_RESEQ Entry field resequencing (used in the Read Input Fields (QsnReadInp) and Read Modi-
fied Fields (QsnReadMDT) APIs, and so forth). The nn specifies the next entry field in
the sequence (nn can be X'00' to X'80'). See “Resequencing” on page 21-5.
X'8101' QSN_FCW_MSR Magnetic stripe reader entry field.
X'8102' QSN_FCW_SLP Selector light pen entry field.
X'8103' QSN_FCW_MSR_SLP Magnetic stripe reader and selector light pen entry field.
X'8106' QSN_FCW_SLP_SA Selector light pen and selectable attention entry field.
X'8200' QSN_FCW_DBCS_ONLY DBCS only entry field.
X'8220' QSN_FCW_DBCS_PURE DBCS Graphic DBCS entry field.
X'8240' QSN_FCW_DBCS_EITHER DBCS Either entry field.
X'8280' or QSN_FCW_DBCS_OPEN or DBCS open entry field.
X'82C0' QSN_FCW_DBCS_OPEN_C0
X'84??' QSN_FCW_TRANSPARENT Transparency entry field (used in the Read Input Fields (QsnReadInp) and Read Modi-
fied Fields (QsnReadMDT) APIs, and so forth). The ?? indicates that these values are
ignored.
X'8501' QSN_FCW_FET Forward edge trigger entry field. This provides the same function as Auto Enter speci-
fied in the FFW, except a unique AID is returned to the host when the field is exited.
The state on the Auto Enter flag in the FFW is ignored.
X'8601' QSN_FCW_CONT_FIRST Continued entry field first segment.
X'8602' QSN_FCW_CONT_LAST Continued entry field last segment.
X'8603' QSN_FCW_CONT_MIDDLE Continued entry field middle segment.
X'88nn' QSN_FCW_CP Cursor progression entry field.
X'89nn' QSN_FCW_HL Highlighted entry field.
X'8Ann' QSN_FCW_PDS Pointer device selection entry field.
X'B140' QSN_FCW_MOD11 Self Check Modulus 11 entry field.
X'B1A0' QSN_FCW_MOD10 Self Check Modulus 10 entry field.

Error Messages CPFA30E E

Invalid field format word.
CPF24B4 E Severe error while addressing parameter list.
CPFA314 E Memory allocation error.
CPF3CF1 E
CPFA31D E
Error code parameter not valid.
Attempt to write outside of window area.
CPF3CF2 E
CPFA31E E
Error(s) occurred during running of &1 API.
Required parameter &1 omitted.
CPFA301 E Command buffer is full.
CPFA331 E Buffer handle incorrect.
CPFA304 E Data-stream error &1 reported for screen I/O
CPFA332 E Incorrect field control word.
operation.
CPFA333 E Parameter &1 not positive integer value.
CPFA305 E Cannot add operation to command buffer.
CPFA334 E Low level environment handle incorrect.
CPFA307 E Screen position &1, &2 outside of display or
CPFA335 E Screen address parameter error.
window area.
CPFA33D E
CPFA308 E Attempt to write data past end of display.
Invalid screen attribute.
CPFA30A E
CPFA343 E Output operation not done.
Field length &1 not valid.
CPFA344 E The file &2 in library &3 is not valid.
CPFA30B E
CPFA345 E The invite active flag is not valid.
Invalid starting address for field.
CPFA30C E
Maximum allowable number of fields exceeded.
CPFA30D E Set Output Address (QsnSetOutAdr) API
Invalid screen attribute.

Chapter 25. Screen Output APIs 25-17

Write Data (QsnWrtDta) API

Command buffer handle

Omissible Parameter Group: INPUT; BINARY(4)
A handle for the command buffer in which to store the
1 Field ID Input Binary(4) command. If this parameter is omitted or specified as 0,
2 Row Input Binary(4)
this is a direct operation and the display address is set
3 Column Input Binary(4)
4 Command buffer handle Input Binary(4) to the specified location. Otherwise, this is an indirect
5 Low-level environment Input Binary(4) operation and the command is stored in the command
handle buffer without an I/O operation taking place.
6 Error code I/O Char(*)
Low-level environment handle
Returned Value: INPUT; BINARY(4)
The low-level environment that the operation applies to.
Return code Output Binary(4)
If this parameter is omitted or given with a value of zero,
Service Program: QSNAPI the default low-level environment is used.

Error code
Threadsafe: No
I/O; CHAR(*)
The structure in which to return error information. For
The Set Output Address (QsnSetOutAdr) API sets the the format of the structure, see “Error Code Parameter”
current display address. Subsequent output operations that on page 2-6. If this parameter is omitted, diagnostic
do not reset the display address use this address. If multiple and escape messages are issued to the application.
Set Output Address (QsnSetOutAdr) operations are applied
to the same command buffer, only the last QsnSetOutAdr
operation is in effect. Returned Value
This command corresponds indirectly to the 5250 Write to Return code
Display command (WTD) with a Set Buffer Address order. OUTPUT; BINARY(4)
(For an indirect operation, a WTD is placed in the command A return code indicating the result of the operation. The
buffer only if one does not already exist in that buffer.) value returned will be 0 if the operation was successful,
or -1 otherwise.
Authorities and Locks
Error Messages
None
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Omissible Parameter Group Error code parameter not valid.
CPF3CF2 E
Field ID
Error(s) occurred during running of &1 API.
INPUT; BINARY(4)
CPFA301 E Command buffer is full.
The field ID indicating the field at which to set the CPFA303 E Error occurred for screen I/O operation.
display address. If this parameter is specified with a CPFA304 E Data-stream error &1 reported for screen I/O
nonzero value, the row and column parameters are operation.
ignored and the row and column values corresponding to CPFA305 E Cannot add operation to command buffer.
the field ID are used to set the display address. Either CPFA307 E Screen position &1, &2 outside of display or
the field ID or the row and column parameters must be window area.
specified. CPFA31E E
Required parameter &1 omitted.
Row
CPFA331 E Buffer handle incorrect.
INPUT; BINARY(4)
CPFA334 E Low level environment handle incorrect.
The row at which to set the display address. This CPFA335 E Screen address parameter error.
parameter is required if the field ID is not specified. CPFA33C E
Undefined field ID &1.
Column
CPFA343 E Output operation not done.
INPUT; BINARY(4)
CPFA344 E The file &2 in library &3 is not valid.
The column at which to set the display address. This CPFA345 E The invite active flag is not valid.
parameter is required if the field ID is not specified.

Write Data (QsnWrtDta) API

25-18 AS/400 System API Reference V4R4

 Write Data (QsnWrtDta) API

Required Parameter Group

Required Parameter Group:
Data
1 Data Input Char(*) INPUT; CHAR(*)
2 Data length Input Binary(4) The data to be written to the screen. If the data being
passed is graphic DBCS, the data must be enclosed by
Omissible Parameter Group:
extended ideographic attributes. (Use the Write Data
3 Field ID Input Binary(4) (QsnWrtDta) API to specify the data stream Write
4 Row Input Binary(4) Extended Attribute order. See the 5250 Functions Ref-
5 Column Input Binary(4) erence for further details.)
6 Starting monochrome Input Char(1)
attribute Data length
7 Ending monochrome attri- Input Char(1) INPUT; BINARY(4)
bute
8 Starting color attribute Input Char(1)
The number of characters contained in the data param-
9 Ending color attribute Input Char(1) eter.
10 Command buffer handle Input Binary(4)
11 Low-level environment Input Binary(4)
handle Omissible Parameter Group
12 Error code I/O Char(*)
Field ID
INPUT; BINARY(4)
Returned Value:
The field ID indicating the field at which to set the
Return code Output Binary(4) display address. If this parameter is specified with a
nonzero value, the row and column parameters are
Service Program: QSNAPI
ignored and the row and column values corresponding to
Threadsafe: No the field ID are used to set the display address. If
neither the field ID nor the row and column parameters
are specified, the current display address is used.
The Write Data (QsnWrtDta) API writes data to the display at
a given row and column using standard attributes. If a Row
command buffer is specified that does not contain a previous INPUT; BINARY(4)
or current WTD command, one is implicitly added to the The row at which to write the data. The row parameter
buffer using the control characters QSN_CC1_NULL and must refer to a row no greater than the current screen or
QSN_CC2_UNLOCKBD. The display address after this window mode height (if window mode is enabled). The
operation will be one position past the last data byte written actual screen row used for a screen I/O operation is cal-
to the screen (including the ending screen attribute, if any). culated using the formula base+offset=actual. The
base is the row location of the top window border (0 for
This command corresponds indirectly to the 5250 Write to full screen) if offset is positive, or the row location of
Display command (WTD) with a Set Buffer Address order if the bottom window border (screen height plus 1 for full
the row and column are specified. (For an indirect operation, screen) if offset is negative. The offset is the row
a WTD is placed in the command buffer only if one does not parameter value specified, and actual is the actual
already exist in that buffer.) screen row to be used. A CPFA307 error occurs if an
incorrect row value is specified.
Restrictions If both the field ID and the row and column parameters
are omitted, the data is written starting at the current
If window mode is not set and the data (including attributes) display address. If this is the case and the command is
exceeds the length of a row, the data will be wrapped to the a direct operation, or the buffer specified does not
next line. If bottom-to-top wrapping is not supported, a contain a preceding output operation that sets the
CPFA308 error occurs when the data (including attributes) display address, the current display address is set to row
exceeds the last row on the screen. If window mode is set, 1, column 1 prior to writing the data.
data that exceeds the width of the window will not be trun-
cated or wrapped within the window, but will wrap across Row and column must both be specified or omitted; one
screen rows. cannot be specified if the other is omitted.

Column
Authorities and Locks INPUT; BINARY(4)
The column at which to write the data. The column
None parameter must refer to a column no greater than the
current screen or window mode width (if window mode is
on). The actual screen column used for a screen I/O

Chapter 25. Screen Output APIs 25-19

Write Data (QsnWrtDta) API

operation is calculated using the formula this is a direct operation and the data is written to the
base+offset=actual. The base is the column location of screen at the specified location. Otherwise, this is an
the left window border (0 for full screen) if offset is pos- indirect operation and the command is stored in the
itive, or the column location of the right window border command buffer without an I/O operation taking place.
(screen width plus 1 for full screen) if offset is negative.
Low-level environment handle
The offset is the column parameter value specified,
INPUT; BINARY(4)
and actual is the actual screen column to be used. A
CPFA307 error occurs if an incorrect column value is The low-level environment that the operation applies to.
specified. If this parameter is omitted or given with a value of zero,
the default low-level environment is used.
Starting monochrome attribute
INPUT; CHAR(1) Error code
I/O; CHAR(*)
The initial screen attribute for monochrome displays. If
this parameter is omitted and monochrome attributes are The structure in which to return error information. For
to be used, no initial attribute is written to the display for the format of the structure, see “Error Code Parameter”
the data. on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
The monochrome and color attributes parameters are
the initial and ending screen attributes: an initial and
ending screen attribute to be used for a monochrome or Returned Value
a color display, respectively. One of these parameters
will be selected based on the underlying display type, Return code
and the other will be discarded. Any of the attributes OUTPUT; BINARY(4)
can be specified as a special value, X'00', indicating A return code indicating the result of the operation. The
that no screen attribute should be written to the display. value returned will be 0 if the operation was successful,
If the initial screen attribute is specified as an actual or -1 otherwise.
attribute, the data column, if specified, must be greater
than or equal to 2. The initial screen attribute, if not
X'00', will be written to the screen at the column pre- Error Messages
vious to the first data character if row and column are CPF24B4 E Severe error while addressing parameter list.
specified, otherwise to the current display address. The CPF3CF1 E
ending screen attribute, if not X'00', will be written at Error code parameter not valid.
the column directly after the last data character. See CPF3CF2 E
“Screen Attribute Characters” on page 21-3 for a Error(s) occurred during running of &1 API.
description of the screen attribute values. CPFA301 E Command buffer is full.
CPFA303 E Error occurred for screen I/O operation.
Ending monochrome attribute
CPFA304 E Data-stream error &1 reported for screen I/O
INPUT; CHAR(1)
operation.
The ending screen attribute for monochrome displays. If CPFA305 E Cannot add operation to command buffer.
this parameter is omitted, and monochrome attributes CPFA307 E Screen position &1, &2 outside of display or
are to be used, no ending attribute is written to the window area.
display for the data. CPFA308 E Attempt to write data past end of display.
CPFA30D E
Starting color attribute
Invalid screen attribute.
INPUT; CHAR(1)
CPFA31D E
The initial screen attribute for color displays. If this Attempt to write outside of window area.
parameter is omitted and color attributes are to be used, CPFA31E E
no initial attribute is written to the display for the data. Required parameter &1 omitted.
CPFA331 E Buffer handle incorrect.
Ending color attribute
CPFA333 E Parameter &1 not positive integer value.
INPUT; CHAR(1)
CPFA334 E Low level environment handle incorrect.
The ending screen attribute for color displays. If this CPFA335 E Screen address parameter error.
parameter is omitted and color attributes are to be used, CPFA33C E
no ending attribute is written to the display for the data. Undefined field ID &1.
CPFA33F E
Command buffer handle
Error occurred during data conversion.
INPUT; BINARY(4)
CPFA343 E Output operation not done.
A handle for the command buffer in which to store the CPFA344 E The file &2 in library &3 is not valid.
command. If this parameter is omitted or specified as 0, CPFA345 E The invite active flag is not valid.

25-20 AS/400 System API Reference V4R4

 Write Structured Field Major (QsnWrtSFMaj) API

Write Structured Field Major Restrictions

(QsnWrtSFMaj) API If window mode is not set and the data (including attributes)
exceeds the length of a row, the data will be wrapped to the
next line. If bottom-to-top wrapping is not supported, a
Required Parameter Group: CPFA308 error occurs when the data (including attributes)
exceeds the last row on the screen.
1 Major structure Input Char(*)
2 Major structure length Input Binary(4) Not all structured field types are supported by all devices. A
negative response code is issued if an attempt is made to
Omissible Parameter Group: write a type to a device that does not support it.
3 Field ID Input Binary(4)
4 Row Input Binary(4) Required Parameter Group
5 Column Input Binary(4)
6 Command buffer handle Input Binary(4) Major structure
7 Low-level environment Input Binary(4) INPUT; CHAR(*)
handle
8 Error code I/O Char(*) The major structure to be written to the screen. The
data must consist of the entire major structure as docu-
Returned Value: mented in the 5494 Remote Control Unit Functions Ref-
erence.
Return code Output Binary(4)
Major structure length
Service Program: QSNAPI INPUT; BINARY(4)

Threadsafe: No The length of the major structure parameter. This is the

length only and does not include any associated minor
structure lengths.
The Write Structured Field Major (QsnWrtSFMaj) API writes
the major structure of a structured field, setting the display
address to the given row and column. If a command buffer
Omissible Parameter Group
is specified that does not contain a previous or current WTD Field ID
operation, one is implicitly added to the buffer using the INPUT; BINARY(4)
control characters QSN_CC1_NULL and
The field ID indicating the field at which to set the
QSN_CC2_UNLOCKBD.
display address. If this parameter is specified with a
Use this API in conjunction with the Write Structured Field nonzero value, the row and column parameters are
Minor (QsnWrtSFMin) API to construct a structured field ignored and the row and column values corresponding to
operation. For indirect operations, the length contained in the field ID are used to set the display address. If
the minor structure data parameter is added to the stored neither the field ID nor the row and column parameters
length for this major structure for every indirect QsnWrtSFMin are specified, the current display address is used.
operation encountered directly after this operation. In this Row
way, you need only calculate the length of each individual INPUT; BINARY(4)
structure for constructing a structured field operation. See
the 5494 Remote Control Unit Functions Reference for more The row at which to write the structure. The row param-
information regarding structured fields. eter must refer to a row no greater than the current
screen or window mode height (if window mode is
This command corresponds indirectly to the 5250 Write to enabled). The actual screen row used for a screen I/O
Display (WTD) command with a Set Buffer Address and a operation is calculated using the formula
Write to Display Structured Field order if the row and column base+offset=actual. The base is the row location of the
are specified. (For an indirect operation, a WTD is placed in top window border (0 for full screen) if offset is posi-
the command buffer only if one does not already exist in the tive, or the row location of the bottom window border
buffer.) (screen height plus 1 for full screen) if offset is nega-
tive. The offset is the row parameter value specified,
and actual is the actual screen row to be used. A
Authorities and Locks CPFA307 error occurs if an incorrect row value is speci-
None fied.
If both the field ID and the row and column parameters
are omitted, the data is written starting at the current
display address. If this is the case and the command is
a direct operation, or the buffer specified does not

Chapter 25. Screen Output APIs 25-21

Write Structured Field Minor (QsnWrtSFMin) API

contain a preceding output operation that sets the CPFA301 E Command buffer is full.
display address, the current display address is set to row CPFA303 E Error occurred for screen I/O operation.
1, column 1 prior to writing the data. CPFA304 E Data-stream error &1 reported for screen I/O
operation.
Row and column must both be specified or omitted; one
CPFA305 E Cannot add operation to command buffer.
cannot be specified if the other is omitted.
CPFA307 E Screen position &1, &2 outside of display or
Column window area.
INPUT; BINARY(4) CPFA308 E Attempt to write data past end of display.
CPFA31D E
The column at which to write the data. The column
Attempt to write outside of window area.
parameter must refer to a column no greater than the
CPFA31E E
current screen or window mode width (if window mode is
Required parameter &1 omitted.
on). The actual screen column used for a screen I/O
CPFA331 E Buffer handle incorrect.
operation is calculated using the formula
CPFA333 E Parameter &1 not positive integer value.
base+offset=actual. The base is the column location of
CPFA334 E Low level environment handle incorrect.
the left window border (0 for full screen) if offset is pos-
CPFA335 E Screen address parameter error.
itive, or the column location of the right window border
CPFA33C E
(screen width plus 1 for full screen) if offset is negative.
Undefined field ID &1.
The offset is the column parameter value specified,
CPFA341 E Length &2 of structure incorrect.
and actual is the actual screen column to be used. A
CPFA343 E Output operation not done.
CPFA307 error occurs if an incorrect column value is
CPFA344 E The file &2 in library &3 is not valid.
specified.
CPFA345 E The invite active flag is not valid.
Command buffer handle
INPUT; BINARY(4)
A handle for the command buffer in which to store the Write Structured Field Minor
command. If this parameter is omitted or specified as 0, (QsnWrtSFMin) API
this is a direct operation and the data is written to the
screen at the specified location. Otherwise, this is an
indirect operation and the command is stored in the Required Parameter Group:
command buffer without an I/O operation taking place.
1 Minor structure Input Char(*)
Low-level environment handle 2 Minor structure length Input Binary(4)
INPUT; BINARY(4) 3 Command buffer handle Input Binary(4)
The low-level environment that the operation applies to. Omissible Parameter Group:
If this parameter is omitted or given with a value of zero,
the default low-level environment is used. 4 Low-level environment Input Binary(4)
handle
Error code 5 Error code I/O Char(*)
I/O; CHAR(*)
The structure in which to return error information. For Returned Value:
the format of the structure, see “Error Code Parameter” Return code Output Binary(4)
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Service Program: QSNAPI

Threadsafe: No
Returned Value
Return code
The Write Structured Field Minor (QsnWrtSFMin) API writes
OUTPUT; BINARY(4)
the minor structure of a structured field, incrementing the
A return code indicating the result of the operation. The length field in the corresponding major structure by the length
value returned will be 0 if the operation was successful, of this minor structure. The QsnWrtSFMin API must directly
or -1 otherwise. follow a QsnWrtSFMaj or QsnWrtSFMin operation to the
given command buffer.
Error Messages Use this API in conjunction with the Write Structured Field
CPF24B4 E Severe error while addressing parameter list. Major (QsnWrtSFMaj) API to construct a structured field
CPF3CF1 E operation. For indirect operations, the length contained in
Error code parameter not valid. the minor structure data parameter is added to the stored
CPF3CF2 E length for this major structure for every indirect QsnWrtSFMin
Error(s) occurred during running of &1 API. operation encountered directly after this operation. In this

25-22 AS/400 System API Reference V4R4

 Write to Display (QsnWTD) API

way, you need only calculate the length of each individual Error Messages
structure for constructing a structured field operation. See
the 5494 Remote Control Unit Functions Reference for more CPF24B4 E Severe error while addressing parameter list.
information regarding structured fields. CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Authorities and Locks Error(s) occurred during running of &1 API.
CPFA301 E Command buffer is full.
None CPFA303 E Error occurred for screen I/O operation.
CPFA304 E Data-stream error &1 reported for screen I/O
Restrictions operation.
CPFA305 E Cannot add operation to command buffer.
Not all structured field types are supported by all devices. A CPFA307 E Screen position &1, &2 outside of display or
negative response code is issued if an attempt is made to window area.
write a type to a device that does not support it. CPFA308 E Attempt to write data past end of display.
CPFA30D E
Invalid screen attribute.
Required Parameter Group CPFA31D E
Minor structure Attempt to write outside of window area.
INPUT; CHAR(*) CPFA31E E
Required parameter &1 omitted.
The minor structure to be written to the screen. The CPFA331 E Buffer handle incorrect.
data must consist of the entire minor structure as docu- CPFA333 E Parameter &1 not positive integer value.
mented in the 5494 Remote Control Unit Functions Ref- CPFA334 E Low level environment handle incorrect.
erence. CPFA335 E Screen address parameter error.
Minor structure length CPFA33B E
INPUT; BINARY(4) Incorrect operation before QsnWrtSFMin.
CPFA33C E
The length of the minor structure. Undefined field ID &1.
Command buffer handle CPFA341 E Length &2 of structure incorrect.
INPUT; BINARY(4) CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
A handle for the command buffer in which to store the CPFA345 E The invite active flag is not valid.
command. The last operation stored in this command
buffer must have been either a QsnWrtSFMaj or
QsnWrtSFMin operation.
Write to Display (QsnWTD) API
Omissible Parameter Group
Required Parameter Group:
Low-level environment handle
INPUT; BINARY(4) 1 Control character byte 1 Input Char(1)
The low-level environment that the operation applies to. 2 Control character byte 2 Input Char(1)
If this parameter is omitted or given with a value of zero,
Omissible Parameter Group:
the default low-level environment is used.
3 Command buffer handle Input Binary(4)
Error code
4 Low-level environment Input Binary(4)
I/O; CHAR(*) handle
The structure in which to return error information. For 5 Error code I/O Char(*)
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Returned Value:
and escape messages are issued to the application. Return code Output Binary(4)

Service Program: QSNAPI

Returned Value
Return code Threadsafe: No
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The The Write to Display (QsnWTD) API issues a Write to
value returned will be 0 if the operation was successful, Display (WTD) command. A WTD command is used to indi-
or -1 otherwise.

Chapter 25. Screen Output APIs 25-23

Write to Display (QsnWTD) API

cate the beginning of a series of output operations. For most Required Parameter Group
of the DSM screen output operations, the control unit
requires that a WTD be issued prior to the actual operation Control character byte 1
itself, in the same I/O operation. Multiple output operations INPUT; CHAR(1)
can be sent with a given WTD command by using a The operation for the display to perform prior to pro-
command buffer. For direct operations, such output APIs, cessing the Write to Display command. See “Control
implicitly issue a WTD command. For indirect operations, a Characters” on page 21-2 for a description of the control
WTD is added to the buffer if one does not exist already. character values.
Each time a WTD command is received, the control unit
implicitly sets the display address to row 1, column 1, prior to Control character byte 2
issuing the operation. INPUT; CHAR(1)
The operation for the display to perform after the Write
For example, if two direct QsnWrtDta operations are per-
to Display command has been processed. See “Control
formed in succession and the second operation does not
Characters” on page 21-2 for a description of the control
specify the row and column parameters, the data is written to
character values.
row 1, column 1, and not the display address following the
first QsnWrtDta operation. If two indirect QsnWrtDta oper-
ations are issued to an empty command buffer, the first Omissible Parameter Group
QsnWrtDta operation causes a WTD command to be added
to the buffer, but the second QsnWrtDta operation can use Command buffer handle
the existing command. In this case, if no row and column INPUT; BINARY(4)
are specified, the display address used for the second opera- A handle for the command buffer in which to store the
tion will be the one after the first operation is issued. If an command. If this parameter is omitted or specified as 0,
intervening operation that does not require a WTD, such as a this is a direct operation and the command is sent to the
QsnClrScr or a QsnSetErr, is added to the command buffer display. Otherwise, this is an indirect operation and the
between two operations that do require a WTD command, a command is stored in the command buffer without an I/O
second WTD command is added to the buffer for the second operation taking place.
operation.
Low-level environment handle
The screen output APIs that require a WTD command and INPUT; BINARY(4)
that correspond to the WTD command orders (as described The low-level environment that the operation applies to.
in 5250 Functions Reference) are as follows: If this parameter is omitted or given with a value of zero,
Set Output Address (QsnSetOutAdr) the default low-level environment is used.
Write Data (QsnWrtDta) Error code
Write Transparent Data (QsnWrtTDta) I/O; CHAR(*)

Pad for N Positions (QsnWrtPad) The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Pad between Two Screen Addresses (QsnWrtPadAdr) on page 2-6. If this parameter is omitted, diagnostic
Set Field (QsnSetFld) and escape messages are issued to the application.
Set Cursor Address (QsnSetCsrAdr)
Insert Cursor (QsnInsCsr) Returned Value
Return code
The cursor position is not affected if the keyboard is
OUTPUT; BINARY(4)
unlocked when command processing begins and is not
locked during command processing, or if a parameter error is A return code indicating the result of the operation. The
detected. If specified by control character byte 1, the cursor value returned will be 0 if the operation was successful,
will be moved to the insert cursor or default location when or -1 otherwise.
the keyboard is unlocked.

This operation corresponds directly to the 5250 Write to Error Messages

Display command. If this is an indirect operation, this opera- CPF24B4 E Severe error while addressing parameter list.
tion will issue a new WTD command to the command buffer. CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Authorities and Locks Error(s) occurred during running of &1 API.
None CPFA301 E Command buffer is full.
CPFA303 E Error occurred for screen I/O operation.

25-24 AS/400 System API Reference V4R4

 Write Transparent Data (QsnWrtTDta) API

CPFA304 E Data-stream error &1 reported for screen I/O Transparent Data order. (For an indirect operation, a WTD is
operation. placed in the command buffer only if one does not already
CPFA305 E Cannot add operation to command buffer. exist in that buffer.)
CPFA31C E
Incorrect value for control character byte &1.
CPFA31E E
Authorities and Locks
Required parameter &1 omitted. None
CPFA331 E Buffer handle incorrect.
CPFA334 E Low level environment handle incorrect.
CPFA343 E Output operation not done. Restrictions
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. This command is not supported by all control units. A
CPFA306 error occurs if an attempt is made to issue this
command to a control unit that does not support it. Addi-
tional restrictions apply as for the Write Data (QsnWrtDta)
Write Transparent Data (QsnWrtTDta) API
API.

Required Parameter Group: Required Parameter Group

1 Data Input Char(*) Data
2 Data length Input Binary(4) INPUT; CHAR(*)

Omissible Parameter Group: The data to be written to the screen.

Data length
3 Field ID Input Binary(4)
4 Row Input Binary(4) INPUT; BINARY(4)
5 Column Input Binary(4) The number of bytes of data to be written.
6 Starting monochrome Input Char(1)
attribute
7 Ending monochrome attri- Input Char(1) Omissible Parameter Group
bute
8 Starting color attribute Input Char(1) Field ID
9 Ending color attribute Input Char(1) INPUT; BINARY(4)
10 Command buffer handle Input Binary(4)
11 Low-level environment Input Binary(4)
The field ID indicating the field at which to set the
handle display address. If this parameter is specified with a
12 Error code I/O Char(*) nonzero value, the row and column parameters are
ignored and the row and column values corresponding to
Returned Value: the field ID are used to set the display address. If
neither the field ID nor the row and column parameters
Return code Output Binary(4)
are specified, the current display address is used.
Service Program: QSNAPI Row
INPUT; BINARY(4)
Threadsafe: No
The row at which to write the data. The row parameter
must refer to a row no greater than the current screen or
The Write Transparent Data (QsnWrtTDta) API writes n bytes window mode height (if window mode is enabled). The
of transparent data to the display. actual screen row used for a screen I/O operation is cal-
culated using the formula base+offset=actual. The
This command allows transmission of data with any value base is the row location of the top window border (0 for
(X'00' to X'FF') to the display screen. If the data destina- full screen) if offset is positive, or the row location of
tion is a 5250 display, and if the data X'04', X'11', or the bottom window border (screen height plus 1 for full
X'FF' is transmitted, unpredictable results occur. Note that screen) if offset is negative. The offset is the row
if DBCS characters are included in the data, the host system parameter value specified, and actual is the actual
does not perform IGC extension character processing. screen row to be used. A CPFA307 error occurs if an
However, SI/SO characters will be processed correctly. incorrect row value is specified.
The display address after this operation is one position past If both the field ID and the row and column parameters
the last data byte written to the screen. are omitted, the data is written starting at the current
display address. If this is the case and the command is
This command corresponds indirectly to the 5250 Write to a direct operation, or the buffer specified does not
Display (WTD) command with a Set Buffer Address and a contain a preceding output operation that sets the

Chapter 25. Screen Output APIs 25-25

Low-Level Services Examples

display address, the current display address is set to row is a direct operation; the data is written to the screen at
1, column 1, prior to writing the data. Row and column the specified location.
must both be specified or omitted; one cannot be speci-
Low-level environment handle
fied if the other is omitted.
INPUT; BINARY(4)
Column
The low-level environment that the operation applies to.
INPUT; BINARY(4)
If this parameter is omitted or given with a value of zero,
The column at which to write the data. The column the default low-level environment is used.
parameter must refer to a column no greater than the
Error code
current screen or window mode width (if window mode is
I/O; CHAR(*)
on). The actual screen column used for a screen I/O
operation is calculated using the formula The structure in which to return error information. For
base+offset=actual. The base is the column location of the format of the structure, see “Error Code Parameter”
the left window border (0 for full screen) if offset is pos- on page 2-6. If this parameter is omitted, diagnostic
itive, or the column location of the right window border and escape messages are issued to the application.
(screen width plus 1 for full screen) if offset is negative.
The offset is the column parameter value specified,
and actual is the actual screen column to be used. A
Returned Value
CPFA307 error occurs if an incorrect column value is Return code
specified. OUTPUT; BINARY(4)
Starting monochrome attribute A return code indicating the result of the operation. The
INPUT; CHAR(1) value returned will be 0 if the operation was successful,
or -1 otherwise.
The initial screen attribute for monochrome displays. If
this parameter is omitted and monochrome attributes are
to be used, no initial attribute is written to the display for Error Messages
the data. See “Screen Attribute Characters” on
CPF24B4 E Severe error while addressing parameter list.
page 21-3 for a description of the screen attribute
CPF3CF1 E
values. The attribute parameters are specified with the
Error code parameter not valid.
same effect as for the QsnWrtDta operation.
CPF3CF2 E
Ending monochrome attribute Error(s) occurred during running of &1 API.
INPUT; CHAR(1) CPFA301 E Command buffer is full.
CPFA304 E Data-stream error &1 reported for screen I/O
The ending screen attribute for monochrome displays. If
operation.
this parameter is omitted and monochrome attributes are
CPFA305 E Cannot add operation to command buffer.
to be used, no ending attribute is written to the display
CPFA306 E Command not supported by current device.
for the data.
CPFA307 E Screen position &1, &2 outside of display or
Starting color attribute window area.
INPUT; CHAR(1) CPFA31E E
Required parameter &1 omitted.
The initial screen attribute for color displays. If this
CPFA31D E
parameter is omitted and color attributes are to be used,
Attempt to write outside of window area.
no initial attribute is written to the display for the data.
CPFA31E E
Ending color attribute Required parameter &1 omitted.
INPUT; CHAR(1) CPFA331 E Buffer handle incorrect.
CPFA333 E Parameter &1 not positive integer value.
The ending screen attribute for color displays. If this
CPFA334 E Low level environment handle incorrect.
parameter is omitted and color attributes are to be used,
CPFA335 E Screen address parameter error.
no ending attribute is written to the display for the data.
CPFA33C E
Command buffer handle Undefined field ID &1.
INPUT; BINARY(4) CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
A handle for the command buffer in which to store the
CPFA345 E The invite active flag is not valid.
command. If this parameter is specified, this is an indi-
rect operation; the command is stored in the command
buffer without an I/O operation taking place. If this
parameter is omitted or specified with a zero value, this Low-Level Services Examples

25-26 AS/400 System API Reference V4R4

 Low-Level Services Example—3

#include <stdlib.h>
Low-Level Services Example—1 #include <stdio.h>
#include <string.h>
#include "qsnapi.h"
The sample ILE C program in Figure 25-3 on page 25-27
#define TRUE 1
shows how to use the Write Data (QsnWrtDta), Get AID #define FALSE ð
(QsnGetAID), and Roll Up (QsnRollUp) APIs. The program
int main(void)
writes a line at the bottom of the screen and if F3 is not {
pressed, rolls the screen up and writes a new line at the Qsn_Qry_525ð_T qry525ð;
Qsn_WSC_display_T \dsp = (Qsn_WSC_display_T \)(qry525ð.WSC_display);
bottom of the screen. The roll area for the QsnRollUp API char s[1ðð];
Q_Bin4 row;
is defined to be from row 1 to 24 and one line is rolled up. If Qsn_Cmd_Buf_T buf;
F3 is pressed, the program ends. A partial screen display is
QsnQry525ð(&qry525ð, sizeof(qry525ð), NULL);
shown in Figure 25-4. buf = QsnCrtCmdBuf(1ðð, 2ð, ð, NULL, NULL);
QsnClrScr('ð', buf, Q_NO_HANDLE, NULL);
#include <stdlib.h> sprintf(s, "Query status is %c, num input fields: %d, color: %c, wide: %c",
qry525ð.query_status, qry525ð.num_input_capable,
#include <stdio.h> (QsnQryColorSup(NULL, Q_NO_HANDLE, NULL) == TRUE ? 'Y' : 'N'),
#include <string.h> (dsp->scr_size == 3 ? 'Y' : 'N'));
#include "qsnapi.h" QsnWrtDta(s, strlen(s), ð, row=5, 5, QSN_SA_NORM, QSN_SA_NORM,
QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
int main(void) sprintf(s, "GUI display: %d, GUI support: %d",
{ dsp->GUI_display, dsp->GUI_support);
QsnWrtDta(s, strlen(s), ð, row+=2, 5, QSN_SA_NORM, QSN_SA_NORM,
long i; QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
char s[1ðð]; sprintf(s, "Move cursor: %d, Row1/Col1: %d, ReadMDTImmAlt: %d",
dsp->move_csr_order, dsp->row1_col1, dsp->Read_MDT_Imm_Alt);
QsnClrScr('ð', ð, ð, NULL); QsnWrtDta(s, strlen(s), ð, row +=2, 5, QSN_SA_NORM, QSN_SA_NORM,
for (i = 1; ; ++i) { QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
sprintf(s, "Line %2.d. Press Enter to roll, F3 to quit.", i); sprintf(s, "Extended primary attributes: %d, DBCS: %x",
dsp->extended_pri_atr_DP, dsp->DBCS);
QsnWrtDta(s, strlen(s), ð, 24, 2, QSN_SA_NORM, QSN_SA_NORM, QsnWrtDta(s, strlen(s), ð, row +=2, 5, QSN_SA_NORM, QSN_SA_NORM,
QSN_SA_NORM, QSN_SA_NORM, ð, ð, NULL); QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
if (QsnGetAID(NULL, ð, NULL) == QSN_F3) sprintf(s, "Wide mode on: %c",
break; QsnRtvMod(NULL, Q_NO_HANDLE, NULL) == QSN_DSPð4 ? 'y' : 'n');
QsnRollUp(1, 1, 24, ð, ð, NULL); QsnWrtDta(s, strlen(s), ð, row +=2, 5, QSN_SA_NORM, QSN_SA_NORM,
} QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
sprintf(s, "Wide mode allowed: %c",
} QsnQryModSup(QSN_DSPð4, NULL, Q_NO_HANDLE, NULL) ==
TRUE ? 'y' : 'n');
Figure 25-3. Program to Roll Text on Screen QsnWrtDta(s, strlen(s), ð, 13, 5, QSN_SA_NORM, QSN_SA_NORM,
QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL);
QsnPutBuf(buf, Q_NO_HANDLE, NULL);
QsnGetAID(NULL, Q_NO_HANDLE, NULL);
à ð }

Figure 25-5. Program Using the Query 5250 (QsnQry5250) API

à ð
Query status is 1, num input fields: 5ðð, color: Y, wide: Y
Line 1. Press Enter to roll, F3 to quit.
Line 2. Press Enter to roll, F3 to quit. GUI display: 1, GUI support: 1
Line 3. Press Enter to roll, F3 to quit.
Line 4. Press Enter to roll, F3 to quit. Move cursor: ð, Extended primary attributes: ð
Line 5. Press Enter to roll, F3 to quit.
Line 6. Press Enter to roll, F3 to quit. Wide mode on: n
Line 7. Press Enter to roll, F3 to quit.
Line 8. Press Enter to roll, F3 to quit. Wide mode allowed: y

á ñ
Figure 25-4. Screen Output from Roll Text Program

Low-Level Services Example—2 á ñ

Figure 25-5 shows how to use the Query 5250 Figure 25-6. Screen Output from QsnQry5250 API Program
(QsnQry5250) API. A sample display is shown in
Figure 25-6.
Low-Level Services Example—3
The sample program in Figure 25-7 on page 25-28 shows
how to use the Read Modified Fields (QsnReadMDT) API in
conjunction with the buffer query APIs. The resulting screen
display before and after the input operations is shown in
Figure 25-8 on page 25-28 and Figure 25-9 on page 25-28,
respectively.

Chapter 25. Screen Output APIs 25-27

Low-Level Services Example—3

#include <stdlib.h> QsnRtvReadInf(inpbuf, &rdqry, sizeof(rdqry), ð, NULL);

#include <stdio.h> sprintf(msg, "Read information:");
#include <string.h>
QsnWrtDta(msg, strlen(msg), ð, t2=1ð, t3=2, norm, norm,
#include "qsnapi.h"
norm, norm, cmdbuf, ð, NULL);
#define TRUE 1 QsnWrtPadAdr(pad, -1, -1, t2, t3, cmdbuf2, ð, NULL);
#define FALSE ð sprintf(msg, "Bytes returned %d, available: %d",
rdqry.bytes_returned, rdqry.bytes_available);
int main(void) QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+2, norm, norm,
{
norm, norm, cmdbuf, ð, NULL);
Q_Bin4 i, t1, t2, t3, numflds;
const Q_Uchar cc1=QSN_CC1_MDTALL_CLRALL, cc2=QSN_CC2_UNLOCKBD; sprintf(msg, "First data byte: %p", rdqry.dta);
const Q_Uchar nosa = QSN_NO_SA, norm = QSN_SA_NORM, saul = QSN_SA_UL; QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+2, norm, norm,
char pad = ' '; norm, norm, cmdbuf, ð, NULL);
Qsn_Cmd_Buf_T cmdbuf, cmdbuf2; sprintf(msg, "First field byte: %p", rdqry.fld_dta);
Qsn_Inp_Buf_T inpbuf; QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+4, norm, norm,
Qsn_Fld_Inf_T fldqry;
norm, norm, cmdbuf, ð, NULL);
Qsn_Read_Inf_T rdqry;
char msg[1ðð]; sprintf(msg, "Diff: %d", rdqry.fld_dta-rdqry.dta);
Q_Fdbk_T fdbk = { sizeof(Q_Fdbk_T) }; QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+4, norm, norm,
norm, norm, cmdbuf, ð, NULL);
cmdbuf = QsnCrtCmdBuf(1ðð, 5ð, ð, NULL, NULL); sprintf(msg,
cmdbuf2 = QsnCrtCmdBuf(1ðð, 5ð, ð, NULL, NULL); "Read len: %d, data len: %d, field data len: %d,\
inpbuf = QsnCrtInpBuf(2ðð, 5ð, ð, NULL, NULL);
num fields: %d",
QsnClrScr('ð', ð, ð, NULL);
QsnWTD(cc1, cc2, cmdbuf, ð, NULL); rdqry.read_len, rdqry.dta_len, rdqry.fld_dta_len,
while (TRUE) { rdqry.num_flds);
QsnSetFld(ð, 1ð, 3, 2, QSN_FFW_ALPHA_SHIFT, NULL, ð, saul, QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+2, norm, norm,
saul, cmdbuf, ð, NULL); norm, norm, cmdbuf, ð, NULL);
QsnSetFld(ð, 1ð, 5, 2, QSN_FFW_ALPHA_SHIFT, NULL, ð, saul, sprintf(msg, "Read row: %d, col: %d, aid: %x",
saul, cmdbuf, ð, NULL);
rdqry.read_row, rdqry.read_col, rdqry.AID);
QsnSetFld(ð, 1ð, 7, 2, QSN_FFW_ALPHA_SHIFT, NULL, ð, saul,
saul, cmdbuf, ð, NULL); QsnWrtDta(msg, strlen(msg), ð, ++t2, t3+2, norm, norm,
numflds = QsnReadMDT(QSN_CC1_NULL, QSN_CC1_NULL, NULL, norm, norm, cmdbuf, ð, NULL);
inpbuf, cmdbuf, ð, NULL); }
if (QsnRtvReadAID(inpbuf, NULL, NULL) == QSN_F3) }
break;
QsnPutBuf(cmdbuf2, ð, NULL); Figure 25-7 (Part 2 of 2). Program Using Read Modified Fields
QsnClrBuf(cmdbuf2, NULL);
QsnClrBuf(cmdbuf, NULL);
(QsnReadMDT) API
QsnWTD(cc1, cc2, cmdbuf, ð, NULL);
sprintf(msg, "Num Fields Change: %d", numflds);
QsnWrtDta(msg, strlen(msg), ð, 2, 3ð, norm, norm, norm, norm,
cmdbuf, ð, NULL);
for (i = 1; i <= numflds; i++) {
à ð
fldqry.len = ð;
field 1
if (QsnRtvFldInf(inpbuf, i, &fldqry, sizeof(fldqry),
ð, &fdbk) != QSN_FAIL) { field 2
sprintf(msg,
field 3
"Field# %d, row %d, col %d, len %d, value %.\s",
i, fldqry.row, fldqry.col, fldqry.len,
fldqry.len, fldqry.data);
QsnWrtDta(msg, t1=strlen(msg), ð,
t2=i+3, t3=3ð, norm, norm, norm, norm,
cmdbuf, ð, NULL);
QsnWrtPad(pad, t1, ð, t2, t3, cmdbuf2, ð, NULL);
} else {
sprintf(msg, "Field query failed");
QsnWrtDta(msg, t1=strlen(msg), ð,
t2=4, t3=3ð, norm, norm, norm, norm,
cmdbuf, ð, NULL);
QsnWrtPad(pad, t1, ð, t2, t3, cmdbuf2, ð, NULL);
}
} á ñ
Figure 25-7 (Part 1 of 2). Program Using Read Modified Fields
(QsnReadMDT) API Figure 25-8. Display Screen before Input Operation

à ð
Num Fields Change: 3
__________
Field# 1, row 3, col 2, len 7, value field 1
__________ Field# 2, row 5, col 2, len 9, value field 2
Field# 3, row 7, col 2, len 7, value field 3
__________

Read information:
Bytes returned 8ð, available: 8ð
First data byte: SPP:ðððð :1aefQPADEVðð1ðJENNIFER ðð26ðð :19b:ð:d42
First field byte: SPP:ðððð :1aefQPADEVðð1ðJENNIFER ðð26ðð :19e:1:d42
Diff: 3
Read len: 35, data len: 35, field data len: 32, num fields: 3
Read row: 3, col: 2, aid: f1

á ñ
Figure 25-9. Display Screen after Input Operation

25-28 AS/400 System API Reference V4R4

 Performance Considerations

int main(void)
Low-Level Services Example—4 {
create_window_major win;
The sample program in Figure 25-10 on page 25-29 shows create_window_border_minor win_border;
create_window_title_minor win_title;
how to use the QsnWrtSFMaj and QsnWrtSFMin APIs to Qsn_Cmd_Buf_T cmdbuf;
display a window on the screen using the 5250 Create Q_Uchar c1;
Window command. See the 5494 Remote Control Unit char title_text[] = "Title";
Functions Reference, SC30-3533, for more information. cmdbuf = QsnCrtCmdBuf( 3ðð, 2ð, ð, NULL, NULL);

#include <stdlib.h> /\ setup Create window command major structure \/

#include <stdio.h> win.length = sizeof(win);
#include <string.h>
#include "qsnapi.h"
win.class = STRUCTURED_FIELD;
win.type = CREATE_WIN_STRUCTURED_FIELD;
#define STRUCTURED_FIELD '\xd9' win.flag1 = WINDOW_CURSOR_RESTRICT;
#define CREATE_WIN_STRUCTURED_FIELD '\x51' win.flag2 = '\xðð';
#define WINDOW_CURSOR_RESTRICT '\x8ð' win.reserved = '\xðð';
#define WINDOW_PULL_DOWN '\x4ð' win.num_rows = 1ð;
#define WINDOW_BORDER_MINOR '\xð1'
#define WINDOW_TITLE_MINOR '\x1ð'
win.num_cols = 1ð;

typedef _Packed struct { /\ write Create window command major structure to command buffer \/
Q_Bin2 length; QsnWrtSFMaj((char \)(&win), sizeof(win), ð, 9, 22, cmdbuf, ð, NULL);
Q_Uchar class;
Q_Uchar type; /\ setup border presentation minor structure \/
Q_Uchar flag1;
Q_Uchar flag2;
win_border.length = sizeof(win_border);
Q_Uchar reserved; win_border.type = WINDOW_BORDER_MINOR;
Q_Uchar num_rows; win_border.flag1 = '\xðð';
Q_Uchar num_cols; win_border.mono_attr = QSN_SA_RI;
} create_window_major; win_border.color_attr = QSN_SA_PNK;
win_border.ul = '+';
typedef _Packed struct {
Q_Uchar length;
win_border.top = '\';
Q_Uchar type; win_border.ur = '+';
Q_Uchar flag1; win_border.left = '-';
Q_Uchar mono_attr; win_border.right = '|';
Q_Uchar color_attr; win_border.ll = '+';
Q_Uchar ul; win_border.bottom = '\';
Q_Uchar top;
Q_Uchar ur;
win_border.lr = '+';
Q_Uchar left;
Q_Uchar right; /\ write border presentation minor structure to command buffer \/
Q_Uchar ll; QsnWrtSFMin((char \)(&win_border), sizeof(win_border), cmdbuf, ð, NULL);
Q_Uchar bottom;
Q_Uchar lr; /\ setup window title minor structure \/
} create_window_border_minor;
win_title.length = sizeof(win_title) + strlen(title_text);
typedef _Packed struct { win_title.type = WINDOW_TITLE_MINOR;
Q_Uchar length; win_title.flag1 = '\xðð';
Q_Uchar type; win_title.mono_attr = QSN_SA_BL;
Q_Uchar flag1; win_title.color_attr = QSN_SA_RED;
Q_Uchar mono_attr; win_title.reserved = '\xðð';
Q_Uchar color_attr;
Q_Uchar reserved;
} create_window_title_minor; /\ write window title minor structure to command buffer \/
QsnWrtSFMin((char \)(&win_title), sizeof(win_title), cmdbuf, ð, NULL);
Figure 25-10 (Part 1 of 2). Program Using Read QsnWrtSFMaj
and QsnWrtSFMin APIs /\ write title text to command buffer \/
QsnWrtDta(title_text, strlen(title_text), ð, ð, ð,
QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, cmdbuf, ð, NULL);

/\ write command buffer to screen and wait for key-press \/

QsnPutBuf(cmdbuf, ð, NULL);
QsnGetAID(NULL, ð, NULL);
}
Figure 25-10 (Part 2 of 2). Program Using Read QsnWrtSFMaj
and QsnWrtSFMin APIs

Performance Considerations
The following operations can incur overhead and adversely
affect the performance of your application:
Ÿ QsnCrtEnv
Specifying translation of x'3f' to x'1f' can incur overhead,
because all outgoing data must be checked for this
value. This option should be specified only if CDRA is
on and translation between the code pages will result in
a x'3f' occurrence in data to be displayed.

Chapter 25. Screen Output APIs 25-29

Limitations and Restrictions

Ÿ QsnSavScr support will be determined based on the device type if

the 5250 Query command is not supported.
This operation results in the entire contents of the
screen being read, which can adversely affect response Ÿ In order for the Retrieve Display Mode (QsnRtvMod)
time. This is typically about 3KB, but could be up to operation to correctly report the current state of the
28KB. display, all commands that affect this state (like a Clear
Unit or Clear Unit Alternate) must occur as the first
Ÿ QsnRstScr
command in any command stream written to the display.
This operation writes the result of a save screen back to This is because the work station control unit inspects the
the device, which can adversely affect response time. first command in the stream to determine if a state
Ÿ If you have GUI support, you can put additional com- change is taking place. Most AS/400 programs,
mands after the QsnSavScr or QsnRstScr APIs to including the DSM APIs, only send these commands at
reduce I/O operations and improve performance. the beginning of a stream. If you write a stream in
which such commands do not appear at the beginning of
Ÿ Deleting structures associated with handles, such as
the stream, the result of the Retrieve Display Mode
command buffers, prior to exiting a program will improve (QsnRtvMod) operation may not be accurate.
performance for the programs that use APIs that create
handles. Ÿ When conversions are performed, they are performed
only after a Read Input Fields (QsnReadInp), Read Mod-
ified Fields (QsnReadMDT), Read Modified Alternate
(QsnReadMDTAlt), Read Immediate (QsnReadImm), or
Limitations and Restrictions
Read Modified Immediate Alternate
The following limitations or restrictions apply to the low-level (QsnReadMDTImmAlt) operation. They are performed
interfaces: on all incoming field data, including transparent and
numeric data. You must turn conversion on and off. To
Ÿ Certain functions are supported by control units that do prevent certain data from being converted, you explicitly
not support the 5250 Query command. If the Query set the conversion options on the QsnCrtEnv and
command is not supported, it is assumed that the partic- QsnChgEnv APIs. The conversions that are affected by
ular function is not supported either. These functions this are CDRA conversion based on the job CCSID and
are transparent data support and move cursor order conversions of X'1F' in the incoming data stream to
support. Device attributes such as wide mode and color X'3F'.

25-30 AS/400 System API Reference V4R4

 Introduction to the Window Services APIs

Chapter 26. Introduction to the Window Services APIs

The window services APIs consist of two functional groups: Ÿ A border
the window builder and window manager services. The
If a window is defined with no border, no extra space is
window builder APIs provide the services needed to create,
used on the display for the border characters or their
delete, move, and resize windows. The window builder ser-
attributes (L and B in Figure 26-1 on page 26-2). An
vices include the window manipulation and query APIs, and
area of the screen is cleared starting from the specified
the window I/O APIs. The window manager APIs provide the
location for the upper left corner of the window and con-
services needed to manage multiple windows, support I/O to
tinues for the number of rows and columns given as the
several active windows, and switch between windows.
window size. Figure 26-2 on page 26-2 shows an
example of a window with no border.
A window is created using a window and a low-level environ-
ment description. The window description provides the Note: In discussions throughout the DSM sections that
window attributes, a pointer to data that is specified by the refer to window borders, this should be taken to mean
using application, and several exit routines that the window the top/bottom window row or left/right window column
module calls when a window is moved, resized, or deleted so for a window with no borders.
the using program can perform the appropriate actions. The
Ÿ Window border attributes
low-level environment description is the same as that used
on the Create Low-Level Environment (QsnCrtEnv) API to If a window is defined with no border attributes (L and B
create a low-level environment. A window is implemented as in Figure 26-1 on page 26-2), no extra space for these
a low-level environment where the user data pointer is used on the display. Figure 26-3 on page 26-2
describes the window itself. Thus, a window can be manipu- shows a window with no border attributes.
lated through the low-level APIs or through the window APIs Ÿ Leading window attribute
by using the same window handle. This implementation is
The leading window attribute (A in Figure 26-1 on
similar to the concept of inheritance in object-oriented pro-
page 26-2) is part of the addressable window area. If
gramming languages. DSM window support uses graphical
specified, this attribute takes up an extra screen char-
user interface (GUI) when the underlying control unit sup-
acter and does not reduce the size of the window area.
ports it.
Figure 26-4 on page 26-2 shows a window defined with
Each window has the low-level environment window mode no leading window attribute. The window text directly
enabled. The low-level environment window area is set to follows the window border character. Attribute charac-
the usable area in the window, which consists of the area ters can be written inside the window if desired.
inside the border and attributes that can be accessed by Ÿ Right continuation attribute
screen I/O services. (It does not include the message line.)
Use relative coordinates when specifying a row and column If the right continuation attribute (R in Figure 26-1 on
on an I/O API. The upper left corner of the usable area is page 26-2) is specified on a window description, DSM
(1,1). To use absolute coordinates with a window, disable determines the appropriate attribute to use, based on the
the low-level environment window mode with the Set Low- screen image underlying the window. If the window is
Level Environment Window Mode (QsnSetEnvWinMod) API. not a GUI window, right-continuation-attribute correction
is performed for display-screen and presentation screen
Figure 26-1 on page 26-2 shows the components of a DSM DBCS-only attributes. (No correction is performed for
window. The window in this example has a specified depth extended primary attributes and DBCS data types).
of 13 rows and a width of 19 columns. When a window is placed on a screen that supports
extended attributes, all extended attributes are cleared
The attributes of a DSM window are similar to those of a prior to displaying the window. To have the right contin-
data description specifications (DDS) window. The initial size uation attribute handle extended attributes, you must use
and location of a DSM window are specified using the a display that supports GUI windows and specify GUI
location of the upper-left window border character and the window support on the window description.
number of rows and columns within the window. For DSM
Ÿ Message line
windows, the leading window attribute, right continuation attri-
bute, or message line can be specified separately. Unlike a Specifying a message line on a window description
DDS window, a DSM window does not require the following: decreases the number of lines in the window area by 1,
as shown in Figure 26-1 on page 26-2.

 Copyright IBM Corp. 1998, 1999 26-1

Introduction to the Window Services APIs

┌───Left border attribute AwwwwwwwwwwwwwwwwwwwR %─First window row

│┌───Left border AwwwwwwwwwwwwwwwwwwwR
││┌───Leading window attribute AwwwwwwwwwwwwwwwwwwwR
│││┌───First window column AwwwwwwwwwwwwwwwwwwwR
││││ AwwwwwwwwwwwwwwwwwwwR
││││ ┌────Last window column AwwwwwwwwwwwwwwwwwwwR
││││ │┌────Right border attribute AwwwwwwwwwwwwwwwwwwwR
││││ ││┌────Right border AwwwwwwwwwwwwwwwwwwwR
││││ │││┌────Right continuation attribute AwwwwwwwwwwwwwwwwwwwR
││││ ││││ AwwwwwwwwwwwwwwwwwwwR
││││ ││││ AwwwwwwwwwwwwwwwwwwwR
6666 6666 AwwwwwwwwwwwwwwwwwwwR %─Last window row
L.......................R %─Top border AmmmmmmmmmmmmmmmmmmmR %─Message line
L:AwwwwwwwwwwwwwwwwwwwB:R %─First window row
L:AwwwwwwwwwwwwwwwwwwwB:R Figure 26-2. DSM Window with No Border
L:AwwwwwwwwwwwwwwwwwwwB:R
L:AwwwwwwwwwwwwwwwwwwwB:R
L:AwwwwwwwwwwwwwwwwwwwB:R
L:AwwwwwwwwwwwwwwwwwwwB:R ......................R %─Top border
L:AwwwwwwwwwwwwwwwwwwwB:R :Awwwwwwwwwwwwwwwwwww:R %─First window row
L:AwwwwwwwwwwwwwwwwwwwB:R :Awwwwwwwwwwwwwwwwwww:R
L:AwwwwwwwwwwwwwwwwwwwB:R :Awwwwwwwwwwwwwwwwwww:R
L:AwwwwwwwwwwwwwwwwwwwB:R :Awwwwwwwwwwwwwwwwwww:R
L:AwwwwwwwwwwwwwwwwwwwB:R :Awwwwwwwwwwwwwwwwwww:R
L:AwwwwwwwwwwwwwwwwwwwB:R %─Last window row :Awwwwwwwwwwwwwwwwwww:R
L:AmmmmmmmmmmmmmmmmmmmB:R %─Message line :Awwwwwwwwwwwwwwwwwww:R
L:.....................:R %─Bottom border :Awwwwwwwwwwwwwwwwwww:R
:Awwwwwwwwwwwwwwwwwww:R
:Awwwwwwwwwwwwwwwwwww:R
Key:
:Awwwwwwwwwwwwwwwwwww:R
L Left border attribute :Awwwwwwwwwwwwwwwwwww:R %─Last window row
. Top and bottom border :Ammmmmmmmmmmmmmmmmmm:R %─Message line
:....................:R %─Bottom border
R Right continuation attribute
: Left and right border
A Leading window attribute
Figure 26-3. DSM Window with No Border Attributes
w Window area
m Message line L......................R %─Top border
B Right border attribute L:wwwwwwwwwwwwwwwwwwwB:R %─First window row
L:wwwwwwwwwwwwwwwwwwwB:R
Figure 26-1. DSM Window Layout L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R
L:wwwwwwwwwwwwwwwwwwwB:R %─Last window row
L:mmmmmmmmmmmmmmmmmmmB:R %─Message line
L:....................:R %─Bottom border

Figure 26-4. DSM Window with No Leading Window Attribute

26-2 AS/400 System API Reference V4R4

 Change Window (QsnChgWin) API

Chapter 27. Window Manipulation and Query APIs

Window Manipulation and Query

Required Parameter Group:
APIs—Introduction
1 Window handle Input Binary(4)
The window manipulation and query APIs are: 2 Window description Input Char(*)
Change Window 3 Length of window Input Binary(4)
description
(QsnChgWin) changes the description for a
window.
Omissible Parameter:
Create a Window
(QsnCrtWin) creates a window. 4 Error code I/O Char(*)
Initialize Window Description
(QsnInzWinD) initializes a window description Returned Value:
with default values.
Return code Output Binary(4)
Move Window
(QsnMovWin) moves a window to a new
Service Program: QSNAPI
screen location.
Move Window by User Threadsafe: No
(QsnMovWinUsr) moves a window to a new
screen location specified by the user.
Resize Window The Change Window (QsnChgWin) API changes the window
(QsnRszWin) changes the size of a window. description for the given window. The size cannot be
Resize Window by User changed for a window that contains DBCS data.
(QsnRszWinUsr) changes the size of a
window according to user-specified cursor
movements.
Authorities and Locks
Retrieve Window Data Exit Routine Authority
(QsnRtvWinDta) returns a pointer to the user *EXECUTE
data for the given window.
Retrieve Window Description
Required Parameter Group
(QsnRtvWinD) retrieves a copy of the descrip-
tion for a window. Window handle
Set Window Services Attributes INPUT; BINARY(4)
(QsnSetWinAtr) sets the default attributes for
A handle for the window that will have its description
the window services.
changed.
The detailed API descriptions are presented in alphabetical Window description
order. INPUT; CHAR(*)
The new window description for the given window. The
format of the window description is shown in “Format of
Change Window (QsnChgWin) API the Window Description” on page 27-3.

Length of window description

Input; BINARY(4)
The length of the window description parameter.

Omissible Parameter
Error code
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

 Copyright IBM Corp. 1998, 1999 27-1

Create a Window (QsnCrtWin) API

Returned Value The Create a Window (QsnCrtWin) API creates a window

and returns a handle for that window. The window must be
Return code deleted using the Delete Low-Level Environment (QsnDltEnv)
OUTPUT; BINARY(4) API. Whenever a window is made current, the window mode
A return code indicating the result of the operation. The is set to the usable area of the window.
value returned will be 0 if the operation was successful,
or -1 otherwise. Authorities and Locks
Exit Routine Authority
Error Messages *EXECUTE
CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E Required Parameter Group
Length specified in parameter &1 not valid.
CPF3CF1 E Window description
Error code parameter not valid. INPUT; CHAR(*)
CPF3CF2 E The window description defines the attributes for the
Error(s) occurred during running of &1 API. window. The format of the window description is shown
CPFA314 E Memory allocation error. in “Format of the Window Description” on page 27-3.
CPFA318 E Error calling exit routine.
CPFA31E E Length of window description
Required parameter &1 omitted. INPUT; BINARY(4)
CPFA340 E Operation not supported with double-byte data. The length of the window description parameter.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. Omissible Parameter Group
CPFA3A1 E
User extension information
Window description value is incorrect.
INPUT; CHAR(*)
CPFA3AA E
Window handle incorrect. The user extension information is used to associate data
and exit routines with the window. This parameter is
required if the length of user extension information
Create a Window (QsnCrtWin) API parameter is supplied. This essentially enables the
object-oriented programming concept of inheritance,
allowing the window to be extended in a natural way.
The user extension information cannot be changed once
Required Parameter Group:
the window has been created. The format of this param-
1 Window description Input Char(*) eter is shown in “Format of the Window User Extension
2 Length of window Input Binary(4) Information” on page 27-6.
description
Length of user extension information
Omissible Parameter Group: INPUT; BINARY(4)
The length of the user extension information parameter.
3 User extension informa- Input Char(*)
tion Start window
4 Length of user extension Input Binary(4)
Input; CHAR(1)
information
5 Start window Input Char(1) Whether the window should be displayed on the screen
6 Low-level environment Input Char(*) when it is allocated. The possible values are:
description
7 Length of low-level envi- Input Binary(4) 0 The window is not displayed on the
ronment description screen when it is allocated. You must
8 Window handle Output Binary(4) use the Start a Window (QsnStrWin) API
9 Error code I/O Char(*) to start the window.
1 The window is displayed on the screen
Returned Value:
when it is allocated. This is the default if
Window handle Output Binary(4) this parameter is omitted.

Low-level environment description

Service Program: QSNAPI
INPUT; CHAR(*)
Threadsafe: No The low-level environment description defines the oper-
ating environment for low-level operations used to create

27-2 AS/400 System API Reference V4R4

 Create a Window (QsnCrtWin) API

and manipulate the window. This parameter is required

Offset
if the length of the low-level environment description
parameter is supplied. The format of the low-level envi- Dec Hex Type Field
ronment description is shown in “Format of the Low- 8 8 BINARY(4) Number of rows within the
Level Environment Description” on page 22-4. If this window
parameter is omitted, a low-level environment will be 12 C BINARY(4) Number of columns within
created with default values. the window

Length of low-level environment description 16 10 BINARY(4) Minimum number of rows

INPUT; BINARY(4) within the window
20 14 BINARY(4) Minimum number of
The length of the low-level environment description
columns within the window
parameter.
24 18 BINARY(4) Maximum number of rows
Window handle within the window
OUTPUT; BINARY(4)
28 1C BINARY(4) Maximum number of
The variable containing the handle for the window columns within the window
created after the QsnCrtWin API has completed. This 32 20 CHAR(1) Full-screen flag for the
handle can be used across activation groups if the acti- window
vation group in which the handle was created is still 33 21 CHAR(3) Window display attributes
active. for a monochrome display
Error code 36 24 CHAR(3) Window display attributes
I/O; CHAR(*) for a color display

The structure in which to return error information. For 39 27 CHAR(1) Border flag for the window
the format of the structure, see “Error Code Parameter” 40 28 CHAR(1) Border attributes flag for the
on page 2-6. If this parameter is omitted, diagnostic window
and escape messages are issued to the application. 41 29 CHAR(1) Leading attribute flag for the
window
Returned Value 42 2A CHAR(1) Right continuation attribute
flag for the window
Window handle
43 2B CHAR(1) Message line flag for the
OUTPUT; BINARY(4) window
This API returns the value for the window handle param- 44 2C CHAR(1) Upper left border character
eter or a -1 if an error occurred during processing.
45 2D CHAR(1) Top border character
46 2E CHAR(1) Upper right border character
Restrictions
47 2F CHAR(1) Left border character
Windows where the associated low-level environment indi- 48 30 CHAR(1) Right border character
cates DBCS support cannot be resized. GUI windows must
49 31 CHAR(1) Lower left border character
fit within the screen boundary. This includes the leading left
border attribute and the right border continuation attribute. 50 32 CHAR(1) Bottom border character
GUI windows must have a border and the associated left and 51 33 CHAR(1) Lower right border character
right border attributes for the left and right borders. The 52 34 CHAR(1) GUI support flag for the
concept of current and noncurrent window border attributes window
does not apply to GUI windows. No error-checking is per-
53 35 CHAR(1) Flag byte 1 (GUI only)
formed for GUI-specific fields. The fields are passed to the
control unit, as specified, and any errors will be detected by 54 36 CHAR(1) Flag byte 2 (GUI only)
the control unit. 55 37 CHAR(1) Reserved (GUI only). The
default is X'00'.

Format of the Window Description 56 38 CHAR(1) Border flags (GUI only)

57 39 CHAR(1) Window title flags (GUI
Offset only)

Dec Hex Type Field 58 3A CHAR(1) Monochrome title attribute

0 0 BINARY(4) Row location of upper left 59 3B CHAR(1) Color title attribute

corner of window border 60 3C CHAR(1) Reserved (GUI only). The
4 4 BINARY(4) Column location of upper default is X'00'.
left corner of window border

Chapter 27. Window Manipulation and Query APIs 27-3

Create a Window (QsnCrtWin) API

If the window has a leading window attribute, the first window

Offset
column is two greater than the value specified in this field;
Dec Hex Type Field otherwise, it is one greater. This must be a positive integer
61 3D CHAR(3) Reserved. This field must value greater than or equal to 0. For GUI windows, the
be set to X'00'. minimum value must be 2. Otherwise, it must be a positive
64 40 BINARY(4) Offset to title text integer value greater than or equal to 0. For non-GUI
windows, if 0 or 1 is specified, the left border of the window
68 44 BINARY(4) Length of title text
or the leading border attribute, respectively, will not be dis-
72 48 BINARY(4) Reserved. This field must played on the screen unless the window is moved. The
be set to X'00'. default value is such that the maximum-sized window will be
* * CHAR(*) Title text displayed, with border and attributes, given the other window
description attributes (for example, window border attributes).
If the window is a full-screen window, this field is ignored.
Field Descriptions
Flag byte 1 (GUI only). Byte 5 of the GUI Create Window
In the following descriptions, the default value refers to the command major structure. The default is X'00'.
value set by the Initialize Window Description (QsnInzWinD)
API. Flag byte 2 (GUI only). Byte 6 of the GUI Create Window
command major structure. The default is X'00'.
The GUI-only fields in the following descriptions refer to fields
within the data stream for the Create Window command Full-screen flag for the window. Indicates whether or not
major and minor structures. See the 5494 Remote Control this is a full-screen window. (A full-screen window cannot be
Unit Functions Reference manual for details. moved or resized.) The possible values are:
0 Window is not a full-screen window. This is
Border attributes flag for the window. Whether or not the the default.
window border has left and right border attributes. (See 1 Window is a full-screen window.
Figure 26-1 on page 26-2.) The possible values are:
0 Window border has no attributes. GUI support flag for the window. This flag indicates
1 Window border has attributes. This is the whether or not GUI support should be used to build the
default. window if the underlying device supports it. GUI windows
always include a leading and trailing border attribute. The
For GUI windows, 1 must be specified. possible values are:
0 Do not use GUI support.
Border flag for the window. This flag indicates whether or
1 Use GUI support if the underlying device sup-
not the window has a border. (See Figure 26-1 on
ports it. This is the default.
page 26-2.) The possible values are:
0 Window has no border. Leading attribute flag for the window. This flag indicates
1 Window has a border. This is the default. whether or not the window has a leading attribute. (See
Figure 26-1 on page 26-2.) The possible values are:
If this field is set to 0, the border attributes are not written to
0 Window has no leading attribute byte.
the screen, regardless of the values of the other fields.
1 Window has a leading attribute byte. This is
For GUI windows, 1 must be specified. the default.

Border flags (GUI only). Determines if border presentation For GUI windows, 1 must be specified.
characters are used (byte 3 of the border presentation minor
Left border character. The character used for the left
structure of the GUI Create Window command). The default
border. The default is X'00' for all border characters. The
is X'80'.
default border character used for non-GUI windows is ':'. For
Bottom border character. The character used for the GUI windows, the default GUI character is used.
bottom border. The default is X'00' for all border charac-
Length of title text. The length of the title text. The default
ters. The default border character used for non-GUI
value is 0.
windows is '.'. For GUI windows, the default GUI character is
used. Lower left border character. The character used for the
lower left border. The default is X'00' for all border charac-
Color title attribute. The display attribute to precede the
ters. The default border character used for non-GUI
title on a color display. The default is X'20'. If this attribute
windows is ':'. For GUI windows, the default GUI character is
is not valid, it is ignored.
used.
Column location of upper left corner of window border.
The column number of the upper left corner of the window.

27-4 AS/400 System API Reference V4R4

 Create a Window (QsnCrtWin) API

Lower right border character. The character used for the Right border character. The character used for the right
lower right border. The default is X'00' for all border char- border. The default is X'00' for all border characters. The
acters. The default border character used for non-GUI default border character used for non-GUI windows is ':'. For
windows is ':'. For GUI windows, the default GUI character is GUI windows, the default GUI character is used.
used.
Right continuation attribute flag for the window. Whether
Maximum number of columns within the window. A or not the window has a right continuation attribute (see
value of 0, which is the default, indicates this value is the Figure 26-1 on page 26-2). The possible values are:
same as the maximum number of columns for the device in
0 Window has no right continuation attribute
its current mode. If the window is a full-screen window, this
byte.
field is ignored.
1 Window has a right continuation attribute byte.
This is the default. For GUI windows, 1 must
Maximum number of rows within the window. A value of
be specified.
0, which is the default, indicates this value is the same as
the maximum number of rows for the device in its current
The right continuation attribute used is X'20', which is green
mode. If the window is a full-screen window, this field is
for color displays and normal attribute for monochrome dis-
ignored.
plays.
Message line flag for the window. This flag indicates
Row location of upper left corner of window border. The
whether or not the window has a message line. (See
row number of the upper left corner of the window. The first
Figure 26-1 on page 26-2). The possible values are:
window row is one greater than the value specified in this
0 Window does not have a message line field. This must be a positive integer value greater than or
1 Window has a message line. This is the equal to 0. For GUI windows, the minimum value must be 1.
default. Otherwise, it must be a positive integer value greater than or
equal to 0. For non-GUI windows, if 0 is specified, the top
Minimum number of columns within the window. The border of the window will not be displayed on the screen
minimum value allowed is 1. This is the default. If the unless the window is moved. The default value is such that
window is a full-screen window, this field is ignored. the maximum-sized window will be displayed, with border
and attributes, given the other window description attributes
Minimum number of rows within the window. The
(for example, window border attributes). If the window is a
minimum value allowed is 1. This is the default. If the
full-screen window, this field is ignored.
window is a full-screen window, this field is ignored.
Title text. The text for the window title, which is written in
Monochrome title attribute. The display attribute to
the top border of the window. If the title text is too long to fit
precede the title on a monochrome display. The default is
in the window border, it is truncated. Otherwise, it is cen-
X'20'. If this attribute is not valid, it is ignored.
tered in the window border. You can add padding (extra
blanks beside the text) to specify left or right justification for
Number of columns within the window. The number of
the title. If an attribute is specified for the title text, the
columns in the window, from the first window column to the
window border attribute is placed after the title text. This
last. This excludes the left and right border, and the border
field is ignored if the window does not have a top border.
and window attributes. (See Figure 26-1 on page 26-2.) A
value of 0, which is the default, indicates this value is the
The default is no title text.
maximum number of columns that can be defined given the
other window description attributes (for example, window Top border character. The character used for the top
border attributes). The minimum allowed number of columns border. The default is X'00' for all border characters. The
is 1. If the window is a full-screen window, this field is default border character used for non-GUI windows is '.'. For
ignored. GUI windows, the default GUI character is used.

Number of rows within the window. The number of rows Upper left border character. The character used for the
in the window, from the first window row to the last. This upper left border. The default is X'00' for all border charac-
includes the message line, if specified. (See Figure 26-1 on ters. The default border character used for non-GUI
page 26-2.) A value of 0, which is the default, indicates this windows is '.'. For GUI windows, the default GUI character is
value is the maximum number of rows that can be defined used.
given the other window description attributes (for example,
window message line). The minimum allowed number of Upper right border character. The character used for the
rows is 1. If the window is a full-screen window, this field is upper right border. The default is X'00' for all border char-
ignored. acters. The default border character used for non-GUI
windows is '.'. For GUI windows, the default GUI character is
Offset to title text. The offset for the window title text. The used.
default value is 0.

Chapter 27. Window Manipulation and Query APIs 27-5

Create a Window (QsnCrtWin) API

Window display attributes for a color display. The

Offset
window display attributes for a color display. The first char-
acter is the attribute for the window border when the window Dec Hex Type Field
is not current, the second for when the window is current, 48 30 PTR(PP) Exit routine for QsnMovWin,
and the third for the leading window attribute. All bytes may Move Window by User
contain the same value. The special value X'00' can be (QsnMovWinUsr), Resize
used to indicate that no screen attribute should be used for Window (QsnRszWin), or
Resize Window by User
the given character. The first attribute is ignored for GUI
(QsnRszWinUsr) APIs
windows, which only use the second attribute. If X'00' is
specified as the second attribute for a GUI window, the 64 40 PTR(PP) Exit routine for Display
default GUI border attribute will be used. Both the current Window (QsnDspWin) API
and noncurrent border attributes must be either X'00' or a 80 50 PTR(PP) Exit routine for Set Current
valid attribute. For example, it is incorrect to specify the Window (QsnSetCurWin)
current attribute field X'00' and the noncurrent attribute field API
with a valid attribute.

The default values for these fields are those specified by the Field Descriptions
window services mode description (see “Format of the
Window Services Attribute Description” on page 27-14). Exit routine for Change Window (QsnChgWin) API. This
exit routine is called after the window is changed. If the
Window display attributes for a monochrome display. window is redrawn, it is called after the window is redrawn.
The window display attributes for a monochrome display.
The first character is the attribute for the window border Exit routine for Delete Low-Level Environment
when the window is not current, the second for when the (QsnDltEnv) API. The exit routine to call when a window is
window is current, and the third is for the leading window deleted using the Delete Low-Level Environment (QsnDltEnv)
attribute. All bytes may contain the same value. The special API.
value X'00' can be used to indicate that no screen attribute
Exit routine for Display Window (QsnDspWin) API. The
should be used for the given character. The first attribute is
exit routine to call immediately before the window is drawn or
ignored for GUI windows, which only use the second attri-
redrawn. The following APIs may cause the window to be
bute. If X'00' is specified as the second attribute for a GUI
redrawn: QsnCrtWin, QsnStrWin, QsnChgWin, QsnMovWin,
window, the default GUI border attribute will be used. Both
QsnMovWinUsr, QsnRszWin, QsnRszWinUsr, QsnDspWin,
the current and noncurrent border attributes must be either
and QsnSetCurWin.
X'00' or a valid attribute. For example, it is incorrect to
specify the current attribute field X'00' and the noncurrent Exit routine for move or resize window APIs. The exit
attribute field with a valid attribute. routine to call when window coordinates are changed using
the QsnMovWin, Move Window by User (QsnMovWinUsr),
The default values for these fields are those specified by the
Resize Window (QsnRszWin), or Resize Window by User
window services mode description (see “Format of the
(QsnRszWinUsr) APIs. This exit routine is called after the
Window Services Attribute Description” on page 27-14).
window is redrawn.
Window title flags (GUI only). Byte 3 of the window title
Exit routine for Set Current Window (QsnSetCurWin) API.
minor structure of the Create Window command. The default
The exit routine to call whenever a window is made current
is X'00'.
by one of the following APIs: QsnCrtWin, QsnStrWin, or
QsnSetCurWin. This exit routine is called after the window is
Format of the Window User Extension drawn or redrawn.
Information
User data associated with window. A pointer to any data
that the user wants to associate with this window.
Offset
Dec Hex Type Field
0 0 PTR(SPP) User data associated with
Window Exit Routines
window
Exit routines are user-supplied functions with a defined inter-
16 10 PTR(PP) Exit routine to call for face. The routines are called from certain APIs and allow the
Change Window programmer to attach additional function to those APIs. For
(QsnChgWin) API instance, if fields have been set up in a window, a Change
32 20 PTR(PP) Exit routine to call for Delete Coordinates exit routine could be supplied to move the fields
Low-Level Environment if the window is moved.
(QsnDltEnv) API

27-6 AS/400 System API Reference V4R4

 Create a Window (QsnCrtWin) API

Exit Routine Error Handling Change Window Coordinates Exit Routine Parameters
Window handle
If an exception occurs during the processing of an exit
INPUT; BINARY(4)
routine, the exception is ignored and processing continues.
A CPFA318 will be issued as a diagnostic message only. The window for which the coordinates were changed.
You can explicitly handle errors in an exit routine by adding
Top border offset
an exception handler to the routine.
INPUT; BINARY(4)
Change Window Exit Routine: This exit routine, if The offset, in screen rows, from the previous top window
specified on the user extension information, is called when border to the current top window border (after the
the window is changed. The following parameter is passed to window coordinates have been changed). It can be pos-
the exit routine: itive, negative, or zero, depending on how the top
window border was changed. For example, if the top
border was moved down two rows, this value would be
Parameter Passed to Exit Routine 2; if it was moved up 4 rows, this value would be -4; if
1 Window handle Input Binary(4)
the top row was not changed, this value would be 0.

Left border offset

INPUT; BINARY(4)
Change Window Exit Routine Parameter
The offset, in screen columns, from the previous left
Window handle window border to the current left window border (after
INPUT; BINARY(4) the window coordinates have been changed). It can be
positive, negative, or zero, depending on how the left
The window that was changed.
window border was changed. For example, if the left
Delete Window Exit Routine: This exit routine, if speci- border was moved two columns to the right, this value
fied on the user extension information, is called when the would be 2; if it was moved 4 columns to the left, this
window is deleted. The following parameter is passed to the value would be -4, and if the left column was not
exit routine: changed, this value would be 0.

Bottom border offset

Parameter Passed to Exit Routine INPUT; BINARY(4)
The offset, in screen rows, from the previous bottom
1 Window handle Input Binary(4) window border to the current bottom window border
(after the window coordinates have been changed). It
can be positive, negative, or zero, depending on how the
Delete Window Exit Routine Parameter bottom window border was changed. For example, if the
Window handle border was moved down two rows, this value would be
INPUT; BINARY(4) 2; if it was moved up 4 rows, this value would be -4; if
the bottom row was not changed, this value would be 0.
The window that was deleted.
Right border offset
Change Window Coordinates Exit Routine: This exit INPUT; BINARY(4)
routine, if specified on the user extension information, is The offset, in screen columns, from the previous right
called when the move or resize APIs are called, after the window border to the current right window border (after
window has been successfully moved or resized, but before the window coordinates have been changed). It can be
the window is drawn on the screen. For this reason, you positive, negative, or zero, depending on how the right
should not use this exit routine to draw anything in the window border was changed. For example, if the right
window. The draw exit routine is called when the window is border was moved two columns to the right, this value
moved or resized. The following parameters are passed to would be 2; if it was moved 4 columns to the left, this
the exit routine: value would be -4; if the right column was not changed,
this value would be 0.
Parameters Passed to Exit Routine
Draw Window Exit Routine: This exit routine, if speci-
1 Window handle Input Binary(4) fied on the user extension information, is called when the
2 Top border offset Input Binary(4) Display Window (QsnDspWin) API is called, before the
3 Left border offset Input Binary(4) window is drawn. Because the exit routine is called before
4 Bottom border offset Input Binary(4) the window is drawn, you should only write inside the window
5 Right border offset Input Binary(4) using the command buffer parameter. Direct operations
should not be used for the exit routine. The following param-
eters are passed to the exit routine:

Chapter 27. Window Manipulation and Query APIs 27-7

Initialize Window Description (QsnInzWinD) API

Additional errors may be generated by this API. They are

Parameters Passed to Exit Routine listed in “Error Messages” on page 22-7 under the Create
Low-Level Environment (QsnCrtEnv) API.
1 Window handle Input Binary(4)
2 Command buffer Input Binary(4)

Initialize Window Description

Draw Window Exit Routine Parameters (QsnInzWinD) API
Window handle
INPUT; BINARY(4) Required Parameter Group:
The window to be drawn.
1 Window description Output Char(*)
Command buffer 2 Length of window Input Binary(4)
INPUT; BINARY(4) description

The command buffer used to store the commands that Omissible Parameter:
re-create the window contents. The contents of the
command buffer are written to the screen along with the 3 Error code I/O Char(*)
window border. This allows the window and its contents
to be redrawn in a single I/O operation. Returned Value:

Return code Output Binary(4)

Current Window Exit Routine: This exit routine, if
specified on the user extension information, is called when Service Program: QSNAPI
the window is made current through the Set Current Window
(QsnSetCurWin) API. The following parameter is passed to Threadsafe: No
the exit routine:

The Initialize Window Description (QsnInzWinD) API initial-

Parameter Passed to Exit Routine izes a window description with default values. Unless other-
wise specified in the window description (see “Format of the
1 Window handle Input Binary(4) Window Description” on page 27-3), pointer fields are set to
the null pointer, numeric fields to 0, character flag fields to 0,
and other character fields to blanks. For example, the
Current Window Exit Routine Parameter default value for the border flag is 1, so this field will be set
Window handle to 1.
INPUT; BINARY(4)
A handle for the window that is made current. Authorities and Locks
Exit Routine Authority
Error Messages *EXECUTE

CPF24B4 E Severe error while addressing parameter list.

CPF3C1D E Required Parameter Group
Length specified in parameter &1 not valid.
Window description
CPF3CF1 E
OUTPUT; CHAR(*)
Error code parameter not valid.
CPF3CF2 E The window description to be initialized.
Error(s) occurred during running of &1 API.
Length of window description
CPFA314 E Memory allocation error.
INPUT; BINARY(4)
CPFA318 E Error calling exit routine.
CPFA327 E Low level environment description value incor- The length of the window description parameter.
rect.
CPFA31E E
Omissible Parameter Group
Required parameter &1 omitted.
CPFA343 E Output operation not done. Error code
CPFA344 E The file &2 in library &3 is not valid. I/O; CHAR(*)
CPFA345 E The invite active flag is not valid.
The structure in which to return error information. For
CPFA3A1 E
the format of the structure, see “Error Code Parameter”
Window description value is incorrect.
CPFA3AB E
The value for &1 must be '0' or '1'.

27-8 AS/400 System API Reference V4R4

 Move Window by User (QsnMovWinUsr) API

on page 2-6. If this parameter is omitted, diagnostic Required Parameter Group

and escape messages are issued to the application.
Window handle
INPUT; BINARY(4)
Returned Value
A handle for the window to be moved.
Return code
OUTPUT; BINARY(4) Upper left row
INPUT; BINARY(4)
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful, The absolute screen row for the new upper left corner of
or -1 otherwise. the window.

Upper left col

Error Messages INPUT; BINARY(4)

CPF24B4 E Severe error while addressing parameter list. The absolute screen column for the new upper left
CPF3C1D E corner of the window.
Length specified in parameter &1 not valid.
CPF3CF1 E Omissible Parameter
Error code parameter not valid.
CPF3CF2 E Error code
Error(s) occurred during running of &1 API. I/O; CHAR(*)
CPFA31E E The structure in which to return error information. For
Required parameter &1 omitted. the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Move Window (QsnMovWin) API
Returned Value
Required Parameter Group: Return code
OUTPUT; BINARY(4)
1 Window handle Input Binary(4)
2 Upper left row Input Binary(4) A return code indicating the result of the operation. The
3 Upper left column Input Binary(4) value returned will be 0 if the operation was successful,
or -1 otherwise.
Omissible Parameter:

4 Error code I/O Char(*) Error Messages

Returned Value: CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Return code Output Binary(4) Error code parameter not valid.
CPF3CF2 E
Service Program: QSNAPI Error(s) occurred during running of &1 API.
CPFA318 E Error calling exit routine.
Threadsafe: No
CPFA31E E
Required parameter &1 omitted.
The QsnMovWin API moves the window to the new upper CPFA343 E Output operation not done.
left coordinate (upper left row, upper left column) specified. CPFA344 E The file &2 in library &3 is not valid.
If the window can fit within the display at the location speci- CPFA345 E The invite active flag is not valid.
fied, it is moved to the new position. If a Change Window CPFA3A2 E
Coordinates exit routine is specified on the window descrip- Window does not fit on screen.
tion, it is called after the window is successfully moved. If CPFA3A4 E
the window is a full screen window, the API will complete Specified window is not active.
successfully, but the window will not be moved. CPFA3AA E
Window handle incorrect.

Authorities and Locks

None Move Window by User (QsnMovWinUsr)
API

Chapter 27. Window Manipulation and Query APIs 27-9

Resize Window (QsnRszWin) API

Error Messages
Required Parameter: CPF24B4 E Severe error while addressing parameter list.
1 Window handle Input Binary(4)
CPF3CF1 E
Error code parameter not valid.
Omissible Parameter: CPF3CF2 E
Error(s) occurred during running of &1 API.
2 Error code I/O Char(*) CPFA318 E Error calling exit routine.
CPFA31E E
Returned Value: Required parameter &1 omitted.
Return code Output Binary(4)
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
Service Program: QSNAPI CPFA345 E The invite active flag is not valid.
CPFA3A4 E
Threadsafe: No Specified window is not active.
CPFA3AA E
Window handle incorrect.
The Move Window by User (QsnMovWinUsr) API allows a
window to be moved on the screen to a new location speci-
fied by the user. The API positions the cursor at the upper
left corner of the window and prompts the user to move the
Resize Window (QsnRszWin) API
cursor to the new position for the upper left corner. The
prompt is displayed only if a message line has been defined.
If the window can fit within the display at the location speci- Required Parameter Group:
fied, it is moved to the new position. If a Change Window
1 Window handle Input Binary(4)
Coordinates exit routine is specified on the window descrip- 2 Number of rows Input Binary(4)
tion, it is called after the window is successfully moved. If 3 Number of columns Input Binary(4)
the window is a full screen window, the API will complete
successfully, but the window will not be moved. Omissible Parameter:

4 Error code I/O Char(*)

Authorities and Locks
Returned Value:
None
Return code Output Binary(4)

Required Parameter Service Program: QSNAPI

Window handle Threadsafe: No

INPUT; BINARY(4)
A handle for the window to be moved.
The Resize Window (QsnRszWin) API allows a window to be
resized. If a Change Window Coordinates exit routine is
Omissible Parameter specified on the window description, it is called after the
window is successfully resized. If the window is a full screen
Error code window, the API will complete successfully, but the window
I/O; CHAR(*) will not be moved. Windows where the associated low-level
The structure in which to return error information. For environment indicates DBCS support cannot be resized.
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Authorities and Locks
and escape messages are issued to the application.
None
Returned Value
Return code Required Parameter Group
OUTPUT; BINARY(4) Window handle
A return code indicating the result of the operation. The INPUT; BINARY(4)
value returned will be 0 if the operation was successful, A handle for the window to be resized.
or -1 otherwise.

27-10 AS/400 System API Reference V4R4

 Resize Window by User (QsnRszWinUsr) API

Number of rows
INPUT; BINARY(4) Required Parameter:
The new value for the number of rows in the window.
1 Window handle Input Binary(4)
Number of columns
INPUT; BINARY(4) Omissible Parameter:
The new value for the number of columns in the window. 2 Error code I/O Char(*)

Returned Value:
Omissible Parameter
Return code Output Binary(4)
Error code
I/O; CHAR(*) Service Program: QSNAPI
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Threadsafe: No
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. The Resize Window by User (QsnRszWinUsr) API allows a
window to be resized according to the cursor movements
Returned Value specified by the user. If the cursor is located on a border
when this API is called, then that border can be moved. If
Return code the cursor is located on a border corner, the two sides that
OUTPUT; BINARY(4) meet at that corner can be moved. If the user positions the
A return code indicating the result of the operation. The cursor to a new row/column for the horizontal or vertical
value returned will be 0 if the operation was successful, border, the border is moved to the new coordinate position
or -1 otherwise. and the window is resized accordingly. If the cursor is not on
the border when the API is called, then the cursor is moved
to the bottom right corner of the window and the user is
Error Messages prompted to move the cursor to the new position for the
CPF24B4 E Severe error while addressing parameter list. bottom right corner of the window. The prompt is displayed
CPF3CF1 E only if a message line has been defined. If the window is a
Error code parameter not valid. full screen window, the API will complete successfully, but
CPF3CF2 E the window will not be moved.
Error(s) occurred during running of &1 API.
A window can be made only as small (large) as the minimum
CPFA318 E Error calling exit routine.
(maximum) size allowed for the window. If the user moves
CPFA31E E
the cursor such that the resulting window will be smaller
Required parameter &1 omitted.
(larger) than the minimum (maximum) size allowed, the
CPFA340 E Operation not supported with double-byte data.
resulting window will be the minimum (maximum) size. If a
CPFA343 E Output operation not done.
Change Window Coordinates exit routine is specified on the
CPFA344 E The file &2 in library &3 is not valid.
window description, this routine is called after the window is
CPFA345 E The invite active flag is not valid.
successfully resized. Typically, this API would be called after
CPFA3A2 E
the user presses a particular function key. Windows where
Window does not fit on screen.
the associated low-level environment indicates DBCS support
CPFA3A4 E
cannot be resized.
Specified window is not active.
CPFA3A5 E
Window dimensions not within window limits. Authorities and Locks
CPFA3AA E
Window handle incorrect. None

Required Parameter
Resize Window by User (QsnRszWinUsr)
API Window handle
INPUT; BINARY(4)
A handle for the window to be resized.

Omissible Parameter

Chapter 27. Window Manipulation and Query APIs 27-11

Retrieve Window Description (QsnRtvWinD) API

Error code Authorities and Locks

I/O; CHAR(*)
The structure in which to return error information. For None
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic Required Parameter
and escape messages are issued to the application.
Window handle
INPUT; BINARY(4)
Returned Value
A handle for the window for which the user data should
Return code be returned.
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The Omissible Parameter Group
value returned will be 0 if the operation was successful,
or -1 otherwise. User data pointer
OUTPUT; PTR(SPP)

Error Messages A space pointer to the user data field supplied in the
user extension information when the window was
CPF24B4 E Severe error while addressing parameter list. defined. If no user data is associated with the window,
CPF3CF1 E the null pointer is returned.
Error code parameter not valid.
CPF3CF2 E Error code
Error(s) occurred during running of &1 API. I/O; CHAR(*)
CPFA31E E The structure in which to return error information. For
Required parameter &1 omitted. the format of the structure, see “Error Code Parameter”
CPFA340 E Operation not supported with double-byte data. on page 2-6. If this parameter is omitted, diagnostic
CPFA343 E Output operation not done. and escape messages are issued to the application.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
CPFA3A4 E Returned Value
Specified window is not active.
User data pointer
CPFA3AA E
OUTPUT; PTR(SPP)
Window handle incorrect.
This API returns the value for the user data pointer
parameter, or the null pointer if an error occurs.
Retrieve Window Data (QsnRtvWinDta) API
Error Messages
CPF24B4 E Severe error while addressing parameter list.
Required Parameter:
CPF3C1F E
1 Window handle Input Binary(4) Pointer is not on a 16 byte boundary.
CPF3CF1 E
Omissible Parameter Group: Error code parameter not valid.
CPF3CF2 E
2 User data pointer Output PTR(SPP) Error(s) occurred during running of &1 API.
3 Error code I/O Char(*)
CPFA318 E Error calling exit routine.
Returned Value: CPFA31E E
Required parameter &1 omitted.
User data pointer Output PTR(SPP) CPFA3AA E
Window handle incorrect.
Service Program: QSNAPI

Threadsafe: No
Retrieve Window Description
(QsnRtvWinD) API
The Retrieve Window Data (QsnRtvWinDta) API returns a
pointer to the user data for the given window.

27-12 AS/400 System API Reference V4R4

 Set Window Services Attributes (QsnSetWinAtr) API

Error code
Required Parameter Group: I/O; CHAR(*)
The structure in which to return error information. For
1 Window handle Input Binary(4) the format of the structure, see “Error Code Parameter”
2 Window description Output Char(*)
on page 2-6. If this parameter is omitted, diagnostic
3 Length of window Input Binary(4)
description and escape messages are issued to the application.

Omissible Parameter:
Returned Value
4 Error code I/O Char(*)
Return code
OUTPUT; BINARY(4)
Returned Value:
A return code indicating the result of the operation. The
Return code Output Binary(4) value returned will be 0 if the operation was successful,
or -1 otherwise.
Service Program: QSNAPI

Threadsafe: No Format of the Window Description

Returned
The Retrieve Window Description (QsnRtvWinD) API
retrieves a copy of the window description for the given Offset
window. Dec Hex Type Field
0 0 BINARY(4) Bytes returned
Authorities and Locks 4 4 BINARY(4) Bytes available

None 8 8 CHAR(*) Window description

Required Parameter Group Field Descriptions

Window handle Bytes available. The number of bytes of data available to
INPUT; BINARY(4) be returned. All available data is returned if enough space is
A handle for the window for which the window descrip- provided.
tion should be returned.
Bytes returned. The number of bytes of data returned.
Window description
OUTPUT; CHAR(*) Window description. The format of the remaining data
returned is shown in “Format of the Window Description” on
The window description for the given window. The
page 27-3.
format of the data returned is shown in “Format of the
Window Description Returned.”

Length of window description

Error Messages
INPUT; BINARY(4) CPF24B4 E Severe error while addressing parameter list.
CPF3C24 E
The length of the window description parameter. If the
Length of the receiver variable is not valid.
length is larger than the size of the receiver variable, the
CPF3CF1 E
results are not predictable. The minimum length is 8.
Error code parameter not valid.
The API returns as much information as it can fit in this
CPF3CF2 E
length. If the available information is longer, it is trun-
Error(s) occurred during running of &1 API.
cated. If the available information is shorter, the unused
CPFA31E E
output is unchanged; whatever is already stored in that
Required parameter &1 omitted.
space remains there. To determine how much informa-
CPFA3AA E
tion the API actually returns in response to this call, see
Window handle incorrect.
the bytes returned field. To determine how much infor-
mation the API could return if space were available, see
the bytes available field.
Set Window Services Attributes
(QsnSetWinAtr) API
Omissible Parameter

Chapter 27. Window Manipulation and Query APIs 27-13

Set Window Services Attributes (QsnSetWinAtr) API

Format of the Window Services Attribute

Required Parameter Group: Description
1 Window services attri- Input Char(*)
Offset
butes description
2 Length of window service Input Binary(4) Dec Hex Type Field
attributes description
0 0 CHAR(3) Monochrome window
display attributes
Omissible Parameter:
3 3 CHAR(3) Color window display attri-
3 Error code I/O Char(*) butes

Returned Value:

Return code Output Binary(4)

Field Descriptions
Color window display attributes. The window display attri-
Service Program: QSNAPI
butes for a color display. The first character is the attribute
Threadsafe: No for the window border when the window is not current, the
second for when the window is current, and the third for the
leading window attribute. The first attribute is ignored for
The Set Window Services Attributes (QsnSetWinAtr) API sets GUI windows, which only use the second attribute. All bytes
the default attributes for the window services. can contain the same value. The special value X'00' indi-
cates that no screen attribute is to be used for the given
character. Both the current and noncurrent border attributes
Authorities and Locks must be either X'00' or a valid attribute. For example, it is
None incorrect to specify the current attribute field X'00' and the
noncurrent attribute field with a valid attribute.

Required Parameter Group The default values for these fields are X'20' for green,
X'3A' for blue, and X'20' for green.
Window services attributes
INPUT; CHAR(*) Monochrome window display attributes. The window
Defines the attributes for the window services APIs. The display attributes for a monochrome display. The first char-
format of the window services attributes description is acter is the attribute for the window border when the window
shown in “Format of the Window Services Attribute is not current, the second for when the window is current,
Description.” and the third for the leading window attribute. The first attri-
bute is ignored for GUI windows, which only use the second
Length of window services attributes attribute. All bytes may contain the same value. The special
INPUT; BINARY(4) value X'00' indicates that no screen attribute is to be used
The length of the window services attributes parameter. for the given character. Both the current and noncurrent
border attributes must be either X'00' or a valid attribute.
For example, it is incorrect to specify the current attribute
Omissible Parameter field X'00' and the noncurrent attribute field with a valid attri-
bute.
Error code
I/O; CHAR(*) The default values for these fields are X'20' for normal attri-
The structure in which to return error information. For bute, X'22' for high intensity, and X'20' for normal attribute,
the format of the structure, see “Error Code Parameter” respectively.
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Error Messages
CPF24B4 E Severe error while addressing parameter list.
Returned Value CPF3C1D E
Return code Length specified in parameter &1 not valid.
OUTPUT; BINARY(4) CPF3CF1 E
Error code parameter not valid.
A return code indicating the result of the operation. The CPF3CF2 E
value returned will be 0 if the operation was successful, Error(s) occurred during running of &1 API.
or -1 otherwise. CPFA31E E
Required parameter &1 omitted.
CPFA343 E Output operation not done.

27-14 AS/400 System API Reference V4R4

 Set Window Services Attributes (QsnSetWinAtr) API

CPFA344 E The file &2 in library &3 is not valid. CPFA3AC E

CPFA345 E The invite active flag is not valid. Window services attributes description value is
incorrect.

Chapter 27. Window Manipulation and Query APIs 27-15

Set Window Services Attributes (QsnSetWinAtr) API

27-16 AS/400 System API Reference V4R4

 Clear Window Message (QsnClrWinMsg) API

Chapter 28. Window I/O APIs

Window I/O APIs—Introduction Authorities and Locks

None
The majority of window I/O operations are performed through
calls to the low-level services interfaces. If specified on the
window description or through an explicit call to the Set Low- Required Parameter
Level Environment Window Mode (QsnSetEnvWinMod) API,
the low-level interfaces can operate in a relative mode, Window handle
where operations such as Set Field (QsnSetFld) are per- INPUT; BINARY(4)
formed relative to the current window. See “Set Low-Level A handle for the window to be cleared.
Environment Window Mode (QsnSetEnvWinMod) API” on
page 22-22 for details.
Omissible Parameter
The APIs specific to window I/O operations are:
Error code
Clear Window I/O; CHAR(*)
(QsnClrWin) clears the window area.
The structure in which to return error information. For
Clear Window Message
the format of the structure, see “Error Code Parameter”
(QsnClrWinMsg) clears the message for a
on page 2-6. If this parameter is omitted, diagnostic
given window.
and escape messages are issued to the application.
Display Window
(QsnDspWin) draws the window border and
clears the window area. Returned Value
Put Window Message
(QsnPutWinMsg) puts a message on the Return code
message line for a given window. OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
The detailed API descriptions are presented in alphabetical value returned will be 0 if the operation was successful,
order. or -1 otherwise.

Clear Window (QsnClrWin) API Error Messages

CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Required Parameter: Error code parameter not valid.
CPF3CF2 E
1 Window handle Input Binary(4) Error(s) occurred during running of &1 API.
CPFA31E E
Omissible Parameter:
Required parameter &1 omitted.
2 Error code I/O Char(*) CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
Returned Value: CPFA345 E The invite active flag is not valid.
CPFA3A4 E
Return code Output Binary(4) Specified window is not active.
CPFA3AA E
Service Program: QSNAPI
Window handle incorrect.
Threadsafe: No

Clear Window Message (QsnClrWinMsg)

The Clear Window (QsnClrWin) API clears the window area API
for the given window. Any field definitions remain intact.
Use the Clear Field Table (QsnClrFldTbl) API to remove field
definitions.

 Copyright IBM Corp. 1998, 1999 28-1

Display Window (QsnDspWin) API

CPFA343 E Output operation not done.

Required Parameter: CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
1 Window handle Input Binary(4) CPFA3A4 E
Specified window is not active.
Omissible Parameter: CPFA3A7 E
Window does not have a message line.
2 Error code I/O Char(*)
CPFA3AA E
Returned Value: Window handle incorrect.

Return code Output Binary(4)

Display Window (QsnDspWin) API
Service Program: QSNAPI

Threadsafe: No
Required Parameter:

The Clear Window Message (QsnClrWinMsg) API clears the 1 Window handle Input Binary(4)
window message for the given window. This API is valid
Omissible Parameter:
only if the window has a message line specified for it.
2 Error code I/O Char(*)
Authorities and Locks Returned Value:
None Return code Output Binary(4)

Service Program: QSNAPI

Required Parameter
Window handle Threadsafe: No
INPUT; BINARY(4)
A handle for the window containing the message to be The Display Window (QsnDspWin) API draws the window
cleared. border for the current window and clears the window area.
The QsnDspWin API does not make a window current. It
simply redraws the window using the existing border attri-
Omissible Parameter butes. For overlapping windows, use this API only for the
Error code current window. If a Draw Window exit routine is specified
I/O; CHAR(*) on the window description, this routine is called after the
window is defined successfully and prior to actually drawing
The structure in which to return error information. For
the window.
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Authorities and Locks
None
Returned Value
Return code Required Parameter
OUTPUT; BINARY(4)
Window handle
A return code indicating the result of the operation. The INPUT; BINARY(4)
value returned will be 0 if the operation was successful,
or -1 otherwise. A handle for the window to be drawn.

Error Messages Omissible Parameter

CPF24B4 E Severe error while addressing parameter list. Error code
CPF3CF1 E I/O; CHAR(*)
Error code parameter not valid. The structure in which to return error information. For
CPF3CF2 E the format of the structure, see “Error Code Parameter”
Error(s) occurred during running of &1 API. on page 2-6. If this parameter is omitted, diagnostic
CPFA31E E and escape messages are issued to the application.
Required parameter &1 omitted.

28-2 AS/400 System API Reference V4R4

 Put Window Message (QsnPutWinMsg) API

Returned Value This API is valid only if the window has a message line spec-
ified for it.
Return code
OUTPUT; BINARY(4)
Authorities and Locks
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful, None
or -1 otherwise.

Required Parameter
Error Messages
Window handle
CPF24B4 E Severe error while addressing parameter list. INPUT; BINARY(4)
CPF3CF1 E
Error code parameter not valid. A handle for the window in which the message should
CPF3CF2 E be placed.
Error(s) occurred during running of &1 API.
CPFA318 E Error calling exit routine. Omissible Parameter Group
CPFA31E E
Required parameter &1 omitted. Message
CPFA343 E Output operation not done. INPUT; CHAR(*)
CPFA344 E The file &2 in library &3 is not valid. The message to be displayed. If the message does not
CPFA345 E The invite active flag is not valid. fit within the window, it is truncated to fit. If the message
CPFA3A4 E length parameter is specified as nonzero, the message
Specified window is not active. parameter is required. The message or the message ID
CPFA3AA E parameter must be specified. If the message parameter
Window handle incorrect. is specified, the message ID parameter is ignored and
no help key support is available for the message.

Put Window Message (QsnPutWinMsg) API Message length

INPUT; BINARY(4)
The number of bytes of message data to be displayed.
Required Parameter:
Lock keyboard
1 Window handle Input Binary(4) INPUT; CHAR(1)
Whether the keyboard should be placed in prehelp error
Omissible Parameter Group:
state of not. The possible values are:
2 Message Input Char(*) 0 Do not place the keyboard in prehelp
3 Message length Input Binary(4)
error state.
4 Lock keyboard Input Char(1)
5 Message identifier Input Char(7) 1 Place the keyboard in prehelp error state.
6 Qualified message file Input Char(20) If 1 is specified, the processing of this API
name follows that of the QsnSetErr API and the
7 Row Input Binary(4) QsnPutWinMsg API must be followed by
8 Column Input Binary(4) an AID-associated read API. This is the
9 Starting monochrome Input Char(1) default.
attribute
10 Ending monochrome attri- Input Char(1) Message identifier
bute INPUT; CHAR(7)
11 Starting color attribute Input Char(1)
12 Ending color attribute Input Char(1) The identifying code for the predefined message to be
13 Error code I/O Char(*) displayed. The first level text is displayed. If the user
moves the cursor to the message line and presses the
Returned Value: Help key, the message No help text available is dis-
played. This parameter is required if the message
Return code Output Binary(4)
parameter is omitted.
Service Program: QSNAPI Qualified message file name
INPUT; CHAR(20)
Threadsafe: No
The name of the message file from which to retrieve the
message information, and the library in which the
The Put Window Message (QsnPutWinMsg) API places an
error message on the message line for the given window.

Chapter 28. Window I/O APIs 28-3

Put Window Message (QsnPutWinMsg) API

message file resides. This parameter is required if the Starting color attribute
message parameter is omitted. INPUT; CHAR(1)
The format of this parameter is: The initial screen attribute for color displays. If this
parameter is omitted and color attributes are to be used,
Bytes Value
no initial attribute is written to the display for the data.
1-10 Message file name
See “Screen Attribute Characters” on page 21-3 for a
11-20 Message file library. This can be an
description of the screen attribute values.
actual library name or one of the special
values *CURLIB or *LIBL. Ending color attribute
INPUT; CHAR(1)
Row
INPUT; BINARY(4) The ending screen attribute for color displays. If this
parameter is omitted and color attributes are to be used,
The relative window row at which to position the cursor
no ending attributes are written to the display for the
when the message is displayed. To move the cursor,
data.
the API must be followed by an AID-associated read
API. Error code
I/O; CHAR(*)
If both row and column are omitted or specified with a
zero value, the cursor is not moved. Row and column The structure in which to return error information. For
must both be specified or omitted; one cannot be speci- the format of the structure, see “Error Code Parameter”
fied if the other is omitted. on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Column
INPUT; BINARY(4)
The relative window column at which to position the
Returned Value
cursor when the message is displayed. Return code
OUTPUT; BINARY(4)
Starting monochrome attribute
INPUT; CHAR(1) A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
The initial screen attribute for monochrome displays. If
or -1 otherwise.
this parameter is omitted and monochrome attributes are
to be used, no initial attribute is written to the display for
the data. Error Messages
The monochrome and color attributes parameters are CPF24B4 E Severe error while addressing parameter list.
the initial and ending screen attributes: an initial and CPF3CF1 E
ending screen attribute to be used for a monochrome or Error code parameter not valid.
a color display, respectively. One of these parameters CPF3CF2 E
will be selected based on the underlying display type, Error(s) occurred during running of &1 API.
and the other will be discarded. Any of the attributes CPFA307 E Screen position &1, &2 outside of display or
can be specified as a special value, X'00', indicating window area.
that no screen attribute should be written to the display. CPFA30D E
If the initial screen attribute is specified as an actual Invalid screen attribute.
attribute, the data column, if specified, must be greater CPFA31E E
than or equal to 2. The initial screen attribute, if not Required parameter &1 omitted.
X'00', will be written to the screen at the column pre- CPFA333 E Parameter &1 not positive integer value.
vious to the first data character if row and column are CPFA335 E Screen address parameter error.
specified, otherwise to the current display address. The CPFA343 E Output operation not done.
ending screen attribute, if not X'00', will be written at CPFA344 E The file &2 in library &3 is not valid.
the column directly after the last data character. CPFA345 E The invite active flag is not valid.
See “Screen Attribute Characters” on page 21-3 for a CPFA3A4 E
description of the screen attribute values. Specified window is not active.
CPFA3A7 E
Ending monochrome attribute Window does not have a message line.
INPUT; CHAR(1) CPFA3A8 E
The ending screen attribute for monochrome displays. If Error occurred retrieving message text.
this parameter is omitted and monochrome attributes are CPFA3AA E
to be used, no ending attribute is written to the display Window handle incorrect.
for the data. CPFA3AB E
The value for &1 must be '0' or '1'.

28-4 AS/400 System API Reference V4R4

 End a Window (QsnEndWin) API

Chapter 29. Window Manager Services APIs

The End a Window (QsnEndWin) API ends a currently active
Window Manager Services window that was started with the Start a Window
APIs—Introduction (QsnStrWin) API. The window is removed from the display
on the screen and from the active window list. The data
The window manager services APIs manage multiple
associated with the window is not deallocated.
windows, support I/O to several active windows, and allow
switching between windows. Much of the work of the
window manager services is performed implicitly through the Authorities and Locks
window builder routines.
None
Windows are managed on an activation-group basis. That is,
all windows that were started within a given activation group
will be managed as a unit. You can only switch to or end a
Required Parameter
window that was started within the current activation group. Window handle
If windows need to be redrawn, only those windows within INPUT; BINARY(4)
the current activation group will be redrawn. A window can
A handle for the window to be ended.
be created in one activation group and started in another
group. The activation group in which the window was started
will be the group to manage the window. Omissible Parameter Group
The window manager services APIs are: Restore screen
INPUT; CHAR(1)
End a Window
(QsnEndWin) ends an active, current window Indicates if the underlying display image should be
and removes it from the screen. restored when the window is ended. This parameter is
Retrieve Current Window ignored if the underlying display image was not saved.
(QsnRtvCurWin) returns the handle for the This option should be used if the screen will be
current window. refreshed by another application and does not need to
Set Current Window be refreshed when the window is removed. Perfor-
(QsnSetCurWin) makes the specified window mance can be improved by not restoring the display
current. image. However, the saved screen may not be restored
Start a Window properly if it is not restored by another application.
(QsnStrWin) starts a window by displaying it The possible values are:
and making it the current window.
0 Do not restore the screen when the
The detailed API descriptions are presented in alphabetical window is ended.
order. 1 Restore the screen, if saved, when the
window is ended. This is the default.

Error code
End a Window (QsnEndWin) API
I/O; CHAR(*)
The structure in which to return error information. For
Required Parameter: the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
1 Window handle Input Binary(4) and escape messages are issued to the application.

Omissible Parameter Group:

Returned Value
2 Restore screen Input Char(1)
3 Error code I/O Char(*) Return code
OUTPUT; BINARY(4)
Returned Value:
A return code indicating the result of the operation. The
Return code Output Binary(4) value returned will be 0 if the operation was successful,
or -1 otherwise.
Service Program: QSNAPI

Threadsafe: No Error Messages

CPF24B4 E Severe error while addressing parameter list.

 Copyright IBM Corp. 1998, 1999 29-1

Set Current Window (QsnSetCurWin) API

CPF3CF1 E Current window handle

Error code parameter not valid. OUTPUT; BINARY(4)
CPF3CF2 E
This API returns the value for the current window handle
Error(s) occurred during running of &1 API.
parameter. If there is no current window, this API
CPFA31E E
returns 0.
Required parameter &1 omitted.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Error Messages
CPFA345 E The invite active flag is not valid. CPF24B4 E Severe error while addressing parameter list.
CPFA3A4 E CPF3CF1 E
Specified window is not active. Error code parameter not valid.
CPFA3AA E CPF3CF2 E
Window handle incorrect. Error(s) occurred during running of &1 API.
CPFA3AB E
The value for &1 must be '0' or '1'.
Set Current Window (QsnSetCurWin) API
Retrieve Current Window (QsnRtvCurWin)
API Required Parameter:

1 Window handle Input Binary(4)

Omissible Parameter Group:
Omissible Parameter:
1 Current window handle Output Binary(4)
2 Error code I/O Char(*) 2 Error code I/O Char(*)

Returned Value: Returned Value:

Current window handle Output Binary(4) Return code Output Binary(4)

Service Program: QSNAPI Service Program: QSNAPI

Threadsafe: No
Threadsafe: No

The Retrieve Current Window (QsnRtvCurWin) API returns The Set Current Window (QsnSetCurWin) API makes the
the handle for the current window. given window the current window. The QsnSetCurWin API
draws the window with the current window border attribute, if
specified. The Current Window exit routine, if specified on
Authorities and Locks the window description, is called after the given window
becomes current. The current window overlays all other
None
windows on the display screen.

Omissible Parameter Group Authorities and Locks

Current window handle
OUTPUT; BINARY(4) None

The variable that contains the handle for the current

window when the QsnRtvCurWin API has completed. If Required Parameter
there is no current window, this parameter is set to 0.
Window handle
Error code INPUT; BINARY(4)
I/O; CHAR(*) A handle for the window that will become current.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Omissible Parameter
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Error code
I/O; CHAR(*)
Returned Value The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”

29-2 AS/400 System API Reference V4R4

 Start a Window (QsnStrWin) API

on page 2-6. If this parameter is omitted, diagnostic Required Parameter

and escape messages are issued to the application.
Window handle
INPUT; BINARY(4)
Returned Value
A handle for the window to be started.
Return code
OUTPUT; BINARY(4)
Omissible Parameter Group
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful, Save screen
or -1 otherwise. INPUT; CHAR(1)
Indicates if the underlying display image should be
Error Messages saved prior to drawing the window. This option should
be used only if the window will not be moved or resized
CPF24B4 E Severe error while addressing parameter list. over an existing display image. Performance can be
CPF3CF1 E improved by not saving the display image. However,
Error code parameter not valid. doing this limits the overlapping nature of the window. If
CPF3CF2 E an attempt is made to move or resize a window for
Error(s) occurred during running of &1 API. which the display image was not saved, the screen is
CPFA318 E Error calling exit routine. cleared and all windows are redrawn prior to moving the
CPFA31E E window.
Required parameter &1 omitted.
CPFA343 E Output operation not done. The possible values for this parameter are:
CPFA344 E The file &2 in library &3 is not valid. 0 Do not save the underlying display image
CPFA345 E The invite active flag is not valid. when the window is started.
CPFA3A4 E 1 Save the underlying display image when
Specified window is not active. the window is started. This is the default.
CPFA3AA E
Window handle incorrect. Error code
I/O; CHAR(*)
The structure in which to return error information. For
Start a Window (QsnStrWin) API the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Required Parameter:

1 Window handle Input Binary(4) Returned Value

Omissible Parameter Group: Return code
OUTPUT; BINARY(4)
2 Save screen Input Char(1)
A return code indicating the result of the operation. The
3 Error code I/O Char(*)
value returned will be 0 if the operation was successful,
Returned Value: or -1 otherwise.

Return code Output Binary(4)

Error Messages
Service Program: QSNAPI CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Threadsafe: No Error code parameter not valid.
CPF3CF2 E
The Start a Window (QsnStrWin) API starts a window Error(s) occurred during running of &1 API.
created with the Create a Window (QsnCrtWin) API. This CPFA318 E Error calling exit routine.
causes the window to be displayed on the screen and added CPFA31E E
to the active window list. If specified, the Draw Window exit Required parameter &1 omitted.
routine is called immediately before the window is drawn. CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
Authorities and Locks CPFA3AA E
Window handle incorrect.
None

Chapter 29. Window Manager Services APIs 29-3

Creating/Manipulating Windows Example

CPFA3AB E #include <stddef.h>

#include <stdlib.h>
The value for &1 must be '0' or '1'. #include <string.h>
#include <stdio.h>
#include "qsnapi.h"

Performance Considerations
void GenericDraw(const Qsn_Cmd_Buf_T \cbuf, const Qsn_Win_T \win)
{
You can improve the performance of window operations by char \msg1 = "F3: quit F4: move F5: resize";
doing the following: char \msg2 = "text no attribute";

Ÿ Do not save or restore the underlying screen image QsnWrtDta(msg2, strlen(msg2), ð, 2, 1, QSN_NO_SA, QSN_NO_SA,
when a window is started or ended with the Start a QSN_NO_SA, QSN_NO_SA, \cbuf, \win, NULL);
QsnWrtDta(msg1, strlen(msg1), ð, -1, 1, QSN_SA_HI, QSN_SA_NORM,
Window (QsnStrWin) or End a Window (QsnEndWin) QSN_SA_RED, QSN_SA_NORM, \cbuf, \win, NULL);
API, respectively. See pages 29-3 and 29-1. }

Ÿ For non-GUI windows, use the same color for current void Draw1(const Qsn_Win_T \win, const Qsn_Cmd_Buf_T \cbuf)
{
and noncurrent boundaries. char \txt = "window 1 (ul/blue)";
Ÿ Use a display station attached to a control unit that sup-
GenericDraw(cbuf, win);
ports an enhanced interface for a nonprogrammable QsnWrtDta(txt, strlen(txt), ð, 5, 5, QSN_SA_UL, QSN_SA_NORM,
work station, even if you are not using GUI windows. QSN_SA_BLU, QSN_SA_NORM, \cbuf, \win, NULL);
}
Ÿ Use GUI window support when the underlying control
void Draw2(const Qsn_Win_T \win, const Qsn_Cmd_Buf_T \cbuf)
unit supports this. {
char \txt = "window 2 (ul/red)";

GenericDraw(cbuf, win);
Creating/Manipulating Windows Example QsnWrtDta(txt, strlen(txt), ð, 5, 5, QSN_SA_UL, QSN_SA_NORM,
QSN_SA_RED, QSN_SA_NORM, \cbuf, \win, NULL);
}
The sample program in Figure 29-1 shows how to create
and manipulate several windows with exit routines. The void Draw3(const Qsn_Win_T \win, const Qsn_Cmd_Buf_T \cbuf)
program creates three windows– Window 1, Window 2, and {
char \txt = "window 3 (ul/pink)";
Window 3. Each time Enter is pressed, the next window is
made current; in which case, the Draw Window exit routine GenericDraw(cbuf, win);
QsnWrtDta(txt, strlen(txt), ð, 5, 5, QSN_SA_UL, QSN_SA_NORM,
for that window is called. If the user presses F4=Move or QSN_SA_PNK, QSN_SA_NORM, \cbuf, \win, NULL);
F5=Resize, the current window is moved or resized and the }
Draw Window exit routine is called again. The resulting Figure 29-1 (Part 1 of 2). Creating and Manipulating Windows
screen output is shown in Figure 29-2 on page 29-5.

29-4 AS/400 System API Reference V4R4

 Creating/Manipulating Windows Example

int main (void) {

int i;
char textffl1ðð“;
Qsn_Win_T win1, win2, win3, cur;
à Command Entry RCHASDðI
ð
Request level: 1
Qsn_Win_Desc_T win_desc; Pr ............................................
: :
Qsn_Win_Ext_Inf_T ext = { NULL, NULL, NULL, NULL, NULL, NULL }; : text no attr ......................................................
Q_Bin4 win_desc_length = sizeof(win_desc); : : :
: : text no attribute :
char aid; : window 1 : :
: : :
: ......... : window 3 (ul/pink) :
QsnInzWinD(&win_desc, win_desc_length, NULL); : : : :
win_desc.GUI_support = 'ð'; : : text no : :
: : : :
: : : :
/\ define and start window 1 \/ : F3 : win : :
: : : : ottom
win_desc.top_row = 3; Ty :... : : :
===> ca : : :
win_desc.left_col = 5; : F3: qui : F3: quit F4: move F5: resize :
win_desc.num_rows = 13; : : :
:........ :....................................................:
win_desc.num_cols = 4ð; F3=Exit F4=Prompt F9=Retrieve F1ð=Include detailed messages
ext.draw_fp = Draw1; F11=Display full F12=Cancel F13=Information Assistant F24=More keys
win1 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext),
'1', NULL, ð, NULL, NULL); á ñ
QsnGetAID(NULL, ð, NULL);
Figure 29-2. Display Screen
/\ define and start window 2 \/
win_desc.top_row = 1ð;
win_desc.left_col = 1ð;
win_desc.num_rows = 1ð;
win_desc.num_cols = 3ð;
ext.draw_fp = Draw2;
win2 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext),
'1', NULL, ð, NULL, NULL);
QsnGetAID(NULL, ð, NULL);

/\ define and start window 3 \/

win_desc.top_row = 5;
win_desc.left_col = 2ð;
win_desc.num_rows = 15;
win_desc.num_cols = 5ð;
ext.draw_fp = Draw3;
win3 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext),
'1', NULL, ð, NULL, NULL);
cur = win3;

for ( ;; ) {
if (( (aid=QsnGetAID(NULL, ð, NULL)) == QSN_F3))
break;
else if (aid == QSN_F4)
QsnMovWinUsr(cur, NULL);
else if (aid == QSN_F5)
QsnRszWinUsr(cur, NULL);
else {
/\ switch current window to next window \/
if (cur == win1) {
QsnSetCurWin(win2, NULL);
cur = win2;
} else if (cur == win2) {
QsnSetCurWin(win3, NULL);
cur = win3;
} else {
QsnSetCurWin(win1, NULL);
cur = win1;
}
}
}

}
Figure 29-1 (Part 2 of 2). Creating and Manipulating Windows

Chapter 29. Window Manager Services APIs 29-5

Creating/Manipulating Windows Example

29-6 AS/400 System API Reference V4R4

 Command Key Action Routines

Chapter 30. Introduction to the Session Services APIs

on the application. A session that uses the default attributes
Session Services APIs—Introduction has an input line underneath the scroller. You can allow the
size and location of the session attributes to default based on
The session services APIs provide a general scrolling I/O
the window size, or you can specify these explicitly. Up to
interface. They can be used to build a standard input-line
two lines of command key descriptions can appear below the
scrolling interface or an interface that has an output-only
scroller and can be managed by a session. For details on
scroll area (called a scroller) in a window. Sessions are
the session description see “Create a Session (QsnCrtSsn)
special cases of windows as supported by the window ser-
API” on page 31-2.
vices. A session is defined using a session, a window, and a
low-level environment description. The window and low-level When a window containing a session is moved or resized,
environment descriptions are the same as those used to the scroller and any automatically defined fields are redrawn
define a window directly with the window services APIs. The to reflect the new window positions and size. If any addi-
session description defines the structure of the session. The tional items have been added to the session through the low-
structure includes the coordinates of the scrolling portion, the level interface APIs, you must supply an exit program that
length of the input line, the amount to roll by, and so on. A will reposition such items explicitly. See “Create a Session
session is implemented as a window, where the window user (QsnCrtSsn) API” on page 31-2 for details on the exit
data pointer describes the session itself. Thus, a session program.
can be manipulated through the window and low-level inter-
faces by passing the session handler or through the session
interfaces. This implementation is similar to the concept of Line Mode and Character Mode I/O
inheritance in object-oriented programming languages.
Session I/O can be performed in a line mode or a character
Sessions are similar in concept to subfiles and can be used mode basis. In line mode, each call to the line-specific inter-
for any application that requires a scrolling line interface. faces operates on a complete line, either on input or output.
The session services APIs are divided into the following func- In character mode, I/O is performed a character at a time.
tional groups: This means that multiple I/O operations can be issued to
operate on the current line. For example, an output opera-
Ÿ Session manipulation and query APIs allow you to
tion could output several characters. Then a backspace
create, query, and manipulate sessions.
operation could be followed by input from the current cursor
Ÿ Session I/O APIs allow you to perform input and output position. (All input operations are still performed in block
operations to sessions. mode, where the input is not available until an
AID-generating key has been pressed.)

Session Details Line mode output is performed using the Write Line to
Scroller (QsnWrtSclLin) API. This API writes a line of data to
Figure 30-1 shows the default attributes provided by the the next session line and sets the active position (see “Active
DSM session description for a session. Position” on page 30-2) to the start of the next line after the
... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8 added line. For character output, the Write Characters to
┌───────────────────────────────────────────────────────────────────────────────┐
1│ │
Scroller (QsnWrtSclChr) API is used. This API outputs a
2│ .................................... │ string of characters starting at the active position. After this
3│ : ┌──────────────────────────────┐ : │
4│ : │ │ : │ operation completes, the active position is one position past
5│ : │ │ : │
6│ : │ │ : │ the last character written, or it is the position specified by a
7│ : │ SCROLLER │ : │
8│ : │ │ : │
control character sequence if this appears at the end of the
9│ : │ │ : │ data.
1ð│ : └──────────────────────────────┘ : │
11│ : : │
12│ : ===5 ___________________________ : │
13│ : ________________________________ : │
14│ : : │
15│ : F3=Exit F6=Print F9=Retrieve : │ Command Key Action Routines
16│ : F14=Move F15=Resize F22=Switch : │
17│ : : │
18│
19│
:..................................: │
│
Part of the session description is an array of command key
2ð│ │ actions. Each action is an exit routine that is specified as a
21│ │
22│ │ function pointer. When a command key is pressed during a
23│ │
24│ │ QsnReadSsnDta operation, if an action has been specified,
└───────────────────────────────────────────────────────────────────────────────┘ the appropriate exit routine is called. Otherwise, an Invalid
Figure 30-1. Session Attributes key pressed error message will be issued. DSM provides a
group of functions that can be called, or user-defined exit-
The main component of a session is the scrollable area, or routines can be specified. The action routines are specified
scroller, where output data can be displayed for the session. as an array of 24 function pointers in the session description.
A session may or may not have a data input line, depending

 Copyright IBM Corp. 1998, 1999 30-1

Active Position

(See “Create a Session (QsnCrtSsn) API” on page 31-2 for specified for each key you want to define, and in that action
details.) The default values for the action routines DSM calls routine query the input buffer to determine the command key
are: pressed and the appropriate action to take.
Cmd Key Action Routine
When an action routine is called, any data on the input line
1 will remain. You can use the QsnWTD API to clear the line.
2 However, if you write to the session or perform any action
3 that causes the session to be redrawn in the action routine,
4 the data on the input line will be lost.
5
6 Print Scroller Data (QsnPrtScl) If an exception occurs during the processing of an action
7 Roll Scroller Down (QsnRollSclDown) routine, it is ignored and processing continues. A CPFA3D9
8 Roll Scroller Up (QsnRollSclUp) will be issued as an exception from the QsnReadSsnDta API
9 Retrieve Session Input Line to Input Line when control returns from the action routine. You can handle
(QsnRtvSsnLin) exceptions explicitly by adding an exception handler to the
10 action routine.
11 Toggle Line Wrap/Truncate Mode
(QsnTglSclWrp)
12 Action Routine Parameters
13 Session handle
14 Move Window by User (QsnMovWinUsr) INPUT; BINARY(4)
15 Resize Window by User (QsnRszWinUsr)
16 The session currently active. If the action routine
17 Display Scroller Top (QsnDspSclT) causes the active session to change, this variable will be
18 Display Scroller Bottom (QsnDspSclB) changed to reflect the new session.
19 Shift Scroller Left (QsnShfSclL) Input buffer
20 Shift Scroller Right (QsnShfSclR) INPUT; BINARY(4)
21 Display Command Line Window (direct
mapping to QUSCMDLN API) The input buffer containing the results of the input oper-
22 ations that caused this exit routine to be called. The
23 input buffer can be queried using the low-level interface
24 routines. This is the buffer that was passed to
QsnReadSsnDta.
The default action routines for command keys 7, 8, 19, and
Returned action
20 (QsnRollSclDown, QsnRollSclUp, QsnShfSclL, and
OUTPUT; CHAR(1)
QsnShfSclR, respectively) will pass any numeric input to the
API when the command key is pressed. For example, to The variable containing the flag indicating if, following a
shift the scroller to the right by 10 columns, the value 10 successful return from this exit routine, control returns to
could be entered at the input line prior to pressing command the caller of the Read Data from Session
key 20. Non-numeric input is ignored. (QsnReadSsnDta) API or if QsnReadSsnDta handles the
next input operation. If an error occurs in the exit
When a user-defined action routine is called, it is passed the routine, control always returns to the caller. The pos-
following information: sible values are:

0 QsnReadSsnDta continues to handle the

Information Passed to the Action Routine next input operation. Control does not
return to the caller.
1 Session handle Input Binary(4)
1 QsnReadSsnDta returns control to the
2 Input buffer Input Binary(4)
3 Returned action Output Char(1) caller. The output parameters for
QsnReadSsnDta are filled in appropri-
ately.
When the specified command key is pressed, the action
routine for the command key is called. If you change the
default values to have a command key call a different DSM Active Position
API, you cannot specify the API directly because the action
routine is passed specific parameters. You must define an The active position in the scroller is the point at which data
action routine that can accept the action routine parameters will be written for character mode operations. The active
and then call the desired DSM API with the appropriate position is affected by output operations to the scroller,
parameters. You can define a generic action routine that is including the writing of data that contains EBCDIC display
control character sequences.

30-2 AS/400 System API Reference V4R4

 DBCS Considerations

EBCDIC Display Control Characters DBCS Considerations

The data written to the scroller may contain display control If the low-level environment description (see “Format of the
characters consisting of single byte EBCDIC values. If speci- Low-Level Environment Description” on page 22-4) for the
fied on the session description (see “Create a Session session specifies DBCS support, the session services will
(QsnCrtSsn) API” on page 31-2), the APIs for writing data to check for and handle DBCS data. DBCS data must be
the scroller will check for and interpret such control charac- enclosed by shift control (SO/SI) characters. The DBCS
ters. Each control character recognized in the output data is support field determines the type of the input field defined for
replaced by a call to a DSM API or internal routine that will the session, but does not affect the checking done for
perform the appropriate function. Figure 30-2 on page 30-3 session output data other than to indicate that DBCS data
shows the control characters that are recognized and the may be present. The scroller does not display data using
APIs that are called, where applicable. extended NLS attributes, regardless of the underlying display
device support.
Figure 30-2. EBCDIC Display Control Characters
If DBCS support is specified, the wrap indication for the
Hex
session description must always be set to 1. Also, line
Character Value Interpretation
retrieval is not supported for DBCS sessions.
HT 05 QsnSclTab
VT 0B QsnSclLF
FF 0C QsnSclFF
CR 0D QsnSclCR
NL 15 QsnSclNL
BS 16 QsnSclBS
BEL 2F QsnBeep

Chapter 30. Introduction to the Session Services APIs 30-3

DBCS Considerations

30-4 AS/400 System API Reference V4R4

 Change Session (QsnChgSsn) API

Chapter 31. Session Manipulation and Query APIs

Session Manipulation and Query

Required Parameter Group:
APIs—Introduction
1 Session handle Input Binary(4)
The session manipulation and query APIs are: 2 Session description Input Char(*)
Change Session 3 Length of session Input Binary(4)
description
(QsnChgSsn) changes the description for a
session.
Omissible Parameter:
Clear Scroller
(QsnClrScl) clears the scroller data. 4 Error code I/O Char(*)
Create a Session
(QsnCrtSsn) creates a session for subsequent Returned Value:
session I/O operations.
Return code Output Binary(4)
Display Scroller Bottom
(QsnDspSclB) shows the last line of scroller
Service Program: QSNAPI
data.
Display Scroller Top Threadsafe: No
(QsnDspSclT) shows the first line of scroller
data.
Initialize Session Description The Change Session (QsnChgSsn) API changes the session
(QsnInzSsnD) initializes a session description description for the given session. If the session contains
with default values. DBCS data, the input line or the number of columns in the
Query If Scroller in Line Wrap Mode scroller cannot be changed. If the session is currently dis-
(QsnQrySclWrp) queries if line wrap mode is played, it will be redrawn to reflect any changes.
on or off.
Retrieve Number of Columns to Shift Scroller
(QsnRtvSclNumShf) returns number of
Authorities and Locks
columns to shift scroller by. Exit Routine Authority
Retrieve Number of Rows to Roll Scroller *EXECUTE
(QsnRtvSclNumRoll) returns the number of
rows to roll scroller by.
Required Parameter Group
Retrieve Session Data
(QsnRtvSsnDta) returns a pointer to the user Session handle
data for a session. INPUT; BINARY(4)
Retrieve Session Description
A handle for the session for which the session descrip-
(QsnRtvSsnD) retrieves a copy of the descrip-
tion is to be changed.
tion for a session.
Roll Scroller Down Session description
(QsnRollSclDown) rolls the scroller down. INPUT; CHAR(*)
Roll Scroller Up
The new session description for the given session. The
(QsnRollSclUp) rolls the scroller up.
format of the session description is shown in “Format of
Shift Scroller Left
the Session Description” on page 31-4.
(QsnShfSclL) shifts the scroller to the left.
Shift Scroller Right Length of session description
(QsnShfSclR) shifts the scroller to the right. INPUT; BINARY(4)
Toggle Line Wrap/Truncate Mode
The length of the session description parameter.
(QsnTglSclWrp) toggles the session between
line wrap and truncation mode.
Omissible Parameter
The detailed API descriptions are presented in alphabetical
order. Error code
I/O; CHAR(*)
The structure in which to return error information. For
Change Session (QsnChgSsn) API the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

 Copyright IBM Corp. 1998, 1999 31-1

Create a Session (QsnCrtSsn) API

Returned Value Required Parameter

Return code Session handle
OUTPUT; BINARY(4) INPUT; BINARY(4)
A return code indicating the result of the operation. The A handle for the session to be cleared. All data in the
value returned will be 0 if the operation was successful, scroller will be cleared.
or -1 otherwise.
Omissible Parameter Group
Error Messages
Resize indication
CPF24B4 E Severe error while addressing parameter list. Input; CHAR(1)
CPF3C1D E
Whether the scroller buffer should be resized when it is
Length specified in parameter &1 not valid.
cleared.
CPF3CF1 E
Error code parameter not valid. 0 Maintain current buffer size and data.
CPF3CF2 E This is the default.
Error(s) occurred during running of &1 API. 1 Resize the buffer to the initial size given
CPFA314 E Memory allocation error. on the session description.
CPFA318 E Error calling exit routine.
CPFA340 E Operation not supported with double-byte data. Error code
CPFA31E E I/O; CHAR(*)
Required parameter &1 omitted. The structure in which to return error information. For
CPFA343 E Output operation not done. the format of the structure, see “Error Code Parameter”
CPFA344 E The file &2 in library &3 is not valid. on page 2-6. If this parameter is omitted, diagnostic
CPFA345 E The invite active flag is not valid. and escape messages are issued to the application.
CPFA3D1 E
Session description value is incorrect.
CPFA3D6 E Returned Value
Session handle is incorrect. Return code
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
Clear Scroller (QsnClrScl) API
value returned will be 0 if the operation was successful,
or -1 otherwise.
Required Parameter:
Error Messages
1 Session handle Input Binary(4)
CPF24B4 E Severe error while addressing parameter list.
Omissible Parameter Group: CPF3CF1 E
Error code parameter not valid.
2 Resize indication Input Char(1) CPF3CF2 E
3 Error code I/O Char(*) Error(s) occurred during running of &1 API.
CPFA314 E Memory allocation error.
Returned Value:
CPFA31E E
Return code Output Binary(4) Required parameter &1 omitted.
CPFA343 E Output operation not done.
Service Program: QSNAPI CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
Threadsafe: No CPFA3AB E
The value for &1 must be '0' or '1'.
CPFA3D6 E
The Clear Scroller (QsnClrScl) API clears the scroller data
Session handle is incorrect.
associated with a session and optionally resizes the scroller
buffer.

Create a Session (QsnCrtSsn) API

Authorities and Locks
None

31-2 AS/400 System API Reference V4R4

 Create a Session (QsnCrtSsn) API

tines with the session. This parameter is required if the

Required Parameter Group: user extension information length parameter is supplied.
This essentially enables the object-oriented programming
1 Session description Input Char(*) concept of inheritance, allowing the session to be
2 Length of session Input Binary(4) extended in a natural way. The user extension data
description cannot be changed once the session has been created.
The format of this parameter is shown in the section
Omissible Parameter Group: “Format of the Session User Extension Data” on
3 User extension informa- Input Char(*) page 31-6.
tion
Length of user extension information
4 Length of user extension Input Binary(4)
INPUT; BINARY(4)
information
5 Start session flag Input Char(1) The length of the user extension information parameter.
6 Window description Input Char(*)
7 Length of window Input Binary(4) Start session flag
description INPUT; CHAR(1)
8 Low-level environment Input Char(*)
description Whether or not the session should be displayed on
9 Length of low-level envi- Input Binary(4) screen when it is created. The possible values are:
ronment description
0 Do not display the session on the screen
10 Session handle Output Binary(4)
11 Error code I/O Char(*) when it is created. If you specify this
value, you must use the Start a Window
Returned Value: (QsnStrWin) API to display the session.
1 Display the session on the screen when it
Session handle Output Binary(4) is created. This is the default.
Service Program: QSNAPI Window description
INPUT; CHAR(*)
Threadsafe: No
The defined attributes for the window containing the
session. This parameter is required if the window
The Create a Session (QsnCrtSsn) API creates a session description length parameter is supplied. The format of
and returns a handle for the created session. The session the window description is shown in “Format of the
must be deleted using the Delete Low-Level Environment Window Description” on page 27-3. If this parameter is
(QsnDltEnv) API. omitted, a window will be created with default values.

Length of window description

Authorities and Locks INPUT; BINARY(4)
Exit Routine Authority The length of the window description parameter.
*EXECUTE
Low-level environment description
INPUT; CHAR(*)
Required Parameter Group The low-level environment description that defines the
Session description operating environment for low-level operations used to
INPUT; CHAR(*) create and manipulate the windows. This parameter is
required if the low-level environment description length
The defined attributes of the session to be created. It parameter is supplied. The format of the low-level envi-
must be declared aligned on a 16-byte boundary. The ronment description is shown in “Format of the Low-
format of the session description is shown in “Format of Level Environment Description” on page 22-4. If this
the Session Description” on page 31-4. parameter is omitted, a low-level environment will be
Length of session description created with default values.
INPUT; BINARY(4) Length of low-level environment description
The length of the session description parameter. INPUT; BINARY(4)
The length of the low-level environment description
Omissible Parameter Group parameter.

User extension information Session handle

INPUT; CHAR(*) OUTPUT; BIN(4)

Information that is used to associate data and exit rou- The variable containing a handle for the created session
after the QsnCrtSsn API has completed. This handle

Chapter 31. Session Manipulation and Query APIs 31-3

Create a Session (QsnCrtSsn) API

can be used across activation groups if the activation

Offset
group in which the handle was created is still active.
Dec Hex Type Field
Error code
434 1B2 CHAR(2) Reserved
I/O; CHAR(*)
436 1B4 BINARY(4) Offset to input line prompt
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” 440 1B8 BINARY(4) Length of input line prompt
on page 2-6. If this parameter is omitted, diagnostic 444 1BC BINARY(4) Offset to command key
and escape messages are issued to the application. description line 1
448 1C0 BINARY(4) Length of command key
description line 1
Returned Value
452 1C4 BINARY(4) Offset to command key
Session handle description line 2
OUTPUT; BINARY(4) 456 1C8 BINARY(4) Length of command key
This API returns the value for the session handle param- description line 2
eter or -1 if an error occurs during processing. 460 1CC CHAR(20) Reserved.
* * CHAR(*) Input line prompt1
Format of the Session Description * * CHAR(*) Command key description
line 11
Offset * * CHAR(*) Command key description
Dec Hex Type Field line 21

0 0 PTR(PP) [24] Array of command key Note: The three offset fields must be specified in the correct
actions order. The first offset specified must be contiguous with the end
of the fixed portion of the session descriptor; however, gaps are
384 180 BINARY(4) Top row of scroller allowed between subsequent offset fields.
388 184 BINARY(4) Left column of scroller
392 188 BINARY(4) Number of rows in scroller
Field Descriptions
396 18C BINARY(4) Number of columns in
scroller In the following descriptions, the default value refers to the
400 190 BINARY(4) Default number of rows to value set by the Initialize Session Description (QsnInzSsnD)
roll scroller by API.
404 194 BINARY(4) Default number of columns
to shift scroller by Array of command key actions. An array of 24 function
pointers, each corresponding to the action to be performed
408 198 BINARY(4) Scroller buffer initial size
when the associated command key is pressed. An element
412 19C BINARY(4) Scroller buffer maximum that is specified as a null pointer indicates that the command
size key is invalid. An element can also be set to the dummy
416 1A0 BINARY(4) Scroller buffer increment routine QsnSameAction, in which case the current action
420 1A4 BINARY(4) Number of rows for input
routine for that key is used. If a command key action is set
line to the dummy routine QsnDefaultAction, then the default
action for that key is used. The defaults for command key
424 1A8 CHAR(1) Reserved
actions and the parameters passed to the action routines are
425 1A9 CHAR(1) Wrap indication described in “Command Key Action Routines” on page 30-1.
426 1AA CHAR(1) Reserved The procedures are exported as part of the service program
that contains the DSM session services.
427 1AB CHAR(1) Display control characters
indication
Command key attribute for a color display. The default
428 1AC CHAR(1) Echo session input value is X'28' for red.
429 1AD CHAR(1) Scroller line display
Command key attribute for a monochrome display. The
430 1AE CHAR(1) Show scroller characters default value is X'20' for normal attribute.
431 1AF CHAR(1) Show command key
descriptions Command key description line 1. The text string for the
first line of command key descriptions.
432 1B0 CHAR(1) Command key attribute for
a monochrome display
Command key description line 2. The text string for the
433 1B1 CHAR(1) Command key attribute for second line of command key descriptions.
a color display

31-4 AS/400 System API Reference V4R4

 Create a Session (QsnCrtSsn) API

Default number of columns to shift scroller by. The Number of columns in scroller. This value must be a posi-
default number of columns to shift scroller by for the Shift tive integer no greater than the number of columns in the
Scroller Left (QsnShfSclL) and Shift Scroller Right session window. If 0 is specified, the default is the number
(QsnShfSclR) APIs. This value must be a positive integer of columns remaining in the window from the left column of
value. If 0 is specified, the default is the number of columns the scroller. This value includes the 2 bytes used for the
in the scroller less two (two scroller columns are reserved for prefix area to the left of the scroller input line.
the prefix area).
Number of rows for input line. The input line starts in the
Default number of rows to roll scroller by. The default row specified by the formula: last window row less the
number of rows to roll scroller by for the Roll Scroller Up number of rows required for input line less the number of
(QsnRollSclUp) and Roll Scroller Down (QsnRollSclDown) rows required for the function key descriptions. The input
APIs. This value must be a positive integer value. If 0 is line will start one column past the end of the input line
specified, the default is the number of rows in the scroller. prompt. If there is no input line prompt, then the input line
starts one byte to the right of the leftmost usable column of
Display control characters indication. Specifies whether the window. If this value is 0, then no input line is created.
or not scroller lines contain EBCDIC display control charac- The default is 1.
ters. If the data contains such control characters and this is
not indicated, unexpected results can occur. (See “EBCDIC Number of rows in scroller. This value must be a positive
Display Control Characters” on page 30-3 for details of the integer no greater than the number of rows in the session
control characters supported and their interpretation.) The window. If 0 is specified, the default is the number of rows
possible values are: remaining in the window from the top row of the scroller.
0 Scroller lines do not contain EBCDIC display Offset to command key description line 1. The offset
control characters. This is the default. from the beginning of the structure to the start of the
1 Scroller lines contain EBCDIC display control command key description line 1. This field is ignored if the
characters. If 1 is specified, any data written length of command key description line 1 field specifies no
to the session with a value below X'40' is command key description. The offset plus the length must
converted to blank. be less than the session description length.
Echo session input. Specifies whether lines entered at the Offset to command key description line 2. The offset
session command line are to be echoed to the scroller. The from the beginning of the structure to the start of the
possible values are: command key description line 2. This field is ignored if the
0 Do not echo session input lines to the scroller. length of command key description line 2 field specifies no
1 Echo session input lines to the scroller. This command key description. The offset plus the length must
is the default. be less than the session description length.

Input line prompt. The text string for the input line prompt. Offset to input line prompt. The offset from the beginning
of the structure to the start of the input line prompt. This
Left column of scroller. This position is relative to the left field is ignored if the length of input line prompt field specifies
of the window which is column 1. The default is 1. no prompt or the default prompt. The offset plus the length
must be less than the session description length.
Length of command key description line 1. This value
must not exceed the maximum number of columns in the Reserved. This field must be set to X'00'.
window. The default value is 0. No space is used in the
session for this line. If the description line cannot be dis- Scroller buffer increment. Specifies, in bytes, the amount
played completely within the window, it is truncated to fit. to increment the scroller buffer size by when the buffer is full
and the buffer-full action is to increment the buffer size. The
Length of command key description line 2. This value default value is 2000 bytes.
must not exceed the maximum number of columns in the
window. The default value is 0. No space is used in the If the scroller buffer cannot be incremented because of insuf-
session for this line. If the description cannot be displayed ficient resources, data at the beginning of the scroller will be
completely in the window, it is truncated to fit. removed to create space for the new data.

Length of input line prompt. This value must not exceed Scroller buffer initial size. The initial buffer size, in number
the maximum number of columns in the window. A value of of bytes, that will be allocated for storing the session scroller
0 specifies that there is no prompt. The default value is -1 lines. The default value is 2000 bytes.
and corresponds to the default input line prompt ===>.
Scroller buffer maximum size. The maximum buffer size,
If the input line cannot be displayed completely within the in bytes, that will be allocated for storing the session scroller
window, it is truncated to fit. The input line will continue on lines. The default value is 0, indicating no maximum size.
the next window line.

Chapter 31. Session Manipulation and Query APIs 31-5

Create a Session (QsnCrtSsn) API

Show command key descriptions. Whether or not the

Offset
function key description lines are to be shown. The possible
values are: Dec Hex Type Field
64 40 PTR(PP) Exit routine to call when
0 Do not show function key descriptions.
window is drawn
1 Show function key descriptions. This is the
default. 80 50 PTR(PP) Exit routine to call when this
window made current
Show scroller characters. Whether or not characters
written to the scroller in character mode are shown imme-
diately on the screen. You can use the scroller line and Field Descriptions
character display options together to specify that groups of
characters are not displayed immediately, but each complete Exit routine to call when session changed. The exit
line is. The possible values are: routine to call when a session is changed using the Change
Session (QsnChgSsn) API.
0 Do not show characters on the screen as they
are written. Use the Display Scroller Bottom Exit routine to call when window coordinates changed.
(QsnDspSclB) API to display the scroller data The exit routine to call when the window coordinates are
on the screen. This is the default. changed using the QsnMovWin, Move Window by User
1 Show scroller characters on the screen as (QsnMovWinUsr), Resize Window (QsnRszWin), or Resize
they are written. Window by User (QsnRszWinUsr), APIs.

Show scroller lines. Whether or not lines written to the Exit routine to call when window deleted. The exit routine
scroller are shown immediately on the screen. The possible to call when a window is deleted using the Delete Low-Level
values are: Environment (QsnDltEnv) API.
0 Do not show scroller lines on the screen as
Exit routine to call when window drawn. The exit routine
they are written. Use the Display Scroller
to call when a window is drawn using the Display Window
Bottom (QsnDspSclB) API to display the
(QsnDspWin) API.
scroller lines on the screen. This is the
default. Exit routine to call when window made current. The exit
1 Show scroller lines on the screen as they are routine to call when this window is made current using the
written. Set Current Window (QsnSetCurWin) API.
Top row of scroller. This position is relative to the top of User data associated with the session. This is a pointer
the window, which is row 1. The default is 1. to any data that the user wants to associate with this
session.
Wrap indication. How to handle lines that do not fit within
the session window. Possible values are:
0 Truncate lines that do not fit. The truncated Session Exit Routines
portion of the line may be viewed by scrolling
Exit routines are user-supplied functions with a defined inter-
to the right.
face. The routines are called from certain APIs and allow the
1 Wrap lines to the next line. This is the
programmer to attach additional function to those APIs. For
default. A value of 1 must be specified if the
instance, if fields have been set up in a window, a Change
session contains DBCS data.
Coordinates exit routine could be supplied to move the fields
if the window is moved.
Format of the Session User Extension
Data Change Session Exit Routine: This exit routine, if
specified on the user extension information, is called when
the session is changed. The following parameter is passed to
Offset
the exit routine:
Dec Hex Type Field
0 0 PTR(SPP) User data associated with
the session Parameter Passed to Exit Routine
16 10 PTR(PP) Exit routine to call when the
1 Session handle Input Binary(4)
session is changed
32 20 PTR(PP) Exit routine to call when
window is deleted
Change Session Exit Routine Parameter
48 30 PTR(PP) Exit routine to call when
window coordinates are
changed

31-6 AS/400 System API Reference V4R4

 Create a Session (QsnCrtSsn) API

Session handle Left border offset

INPUT; BINARY(4) INPUT; BINARY(4)
The session that was changed. The offset, in screen columns, from the previous left
session border to the current left session border (after
Delete Session Exit Routine: This exit routine, if speci- the session coordinates have been changed). It can be
fied on the user extension information, is called when the positive, negative, or zero, depending on how the left
session is deleted. The following parameter is passed to the session border was changed. For example, if the left
exit routine: border was moved two columns to the right, this value
would be 2; if it was moved 4 columns to the left, this
value would be -4, and if the left column was not
Parameter Passed to Exit Routine changed, this value would be 0.

1 Session handle Input Binary(4) Bottom border offset

INPUT; BINARY(4)
The offset, in screen rows, from the previous bottom
Delete Session Exit Routine Parameter session border to the current bottom session border
Session handle (after the session coordinates have been changed). It
INPUT; BINARY(4) can be positive, negative, or zero, depending on how the
bottom session border was changed. For example, if
The session that was deleted. the border was moved down two rows, this value would
be 2; if it was moved up 4 rows, this value would be -4;
Change Session Coordinates Exit Routine: This exit if the bottom row was not changed, this value would be
routine, if specified on the user extension information, is 0.
called when the move or resize APIs are called. It is called
after the session has been successfully moved or resized, Right border offset
but before the session is drawn on the screen. For this INPUT; BINARY(4)
reason, you should not use this exit routine to draw anything The offset, in screen columns, from the previous right
in the session. The draw exit routine will be called when the session border to the current right session border (after
session is moved or resized. The following parameters are the session coordinates have been changed). It can be
passed to the exit routine: positive, negative, or zero, depending on how the right
session border was changed. For example, if the right
border was moved two columns to the right, this value
Parameters Passed to Exit Routine would be 2; if it was moved 4 columns to the left, this
1 Session handle Input Binary(4)
value would be -4; if the right column was not changed,
2 Top border offset Input Binary(4) this value would be 0.
3 Left border offset Input Binary(4)
4 Bottom border offset Input Binary(4)
5 Right border offset Input Binary(4)
Exit Routine Error Handling
If an exception occurs during the processing of an exit
routine, the exception is ignored and processing continues.
Change Session Coordinates Exit Routine Parameters A CPFA318 will be issued as a diagnostic message only.
Session handle You can explicitly handle errors in an exit routine by adding
INPUT; BINARY(4) an exception handler to the routine.

The Session for which the coordinates were changed. Draw Session Exit Routine: This exit routine, if speci-
Top border offset fied on the user extension information, is called when the
INPUT; BINARY(4) Display Window (QsnDspWin) API is called, before the
session is drawn. Because the exit routine is called before
The offset, in screen rows, from the previous top session the session is drawn, you should only write inside the
border to the current top session border (after the session using the command buffer parameter. Direct oper-
session coordinates have been changed). It can be pos- ations should not be used for the exit routine. The following
itive, negative, or zero, depending on how the top parameters are passed to the exit routine:
session border was changed. For example, if the top
border was moved down two rows, this value would be
2; if it was moved up 4 rows, this value would be -4; if Parameters Passed to Exit Routine
the top row was not changed, this value would be 0.
1 Session handle Input Binary(4)
2 Command buffer Input Binary(4)

Chapter 31. Session Manipulation and Query APIs 31-7

Display Scroller Bottom (QsnDspSclB) API

Draw Session Exit Routine Parameters Error Category (API) Page Reference

Session handle Environment description 22-7

(QsnCrtEnv)
INPUT; BINARY(4)
Window description 27-2
The session to be drawn. (QsnCrtWin)

Command buffer
INPUT; BINARY(4)
Display Scroller Bottom (QsnDspSclB) API
The command buffer used to store the commands that
re-create the window contents. The contents of the
command buffer are written to the screen along with the Required Parameter:
window border. This allows the window and its contents
to be redrawn in a single I/O operation. 1 Session handle Input Binary(4)

Current Session Exit Routine: This exit routine, if Omissible Parameter:

specified on the user extension information, is called when
2 Error code I/O Char(*)
the session is made current through the Set Current Window
(QsnSetCurWin) API. The following parameter is passed to
Returned Value:
the exit routine:
Return code Output Binary(4)

Parameter Passed to Exit Routine Service Program: QSNAPI

1 Session handle Input Binary(4) Threadsafe: No

The Display Scroller Bottom (QsnDspSclB) API positions the

Current Session Exit Routine Parameter
scroller at the last line in the scroller area. As many lines
Session handle preceding the last line as can fit in the scroller area are dis-
INPUT; BINARY(4) played as well.
A handle for the session that is made current.
Authorities and Locks
Error Messages None
CPF24B4 E Severe error while addressing parameter list.
CPF3C1D E
Length specified in parameter &1 not valid.
Required Parameter
CPF3CF1 E Session handle
Error code parameter not valid. INPUT; BINARY(4)
CPF3CF2 E
A handle for the session to be manipulated.
Error(s) occurred during running of &1 API.
CPFA314 E Memory allocation error.
CPFA318 E Error calling exit routine. Omissible Parameter
CPFA327 E Low level environment description value incor-
rect. Error code
CPFA31E E I/O; CHAR(*)
Required parameter &1 omitted. The structure in which to return error information. For
CPFA343 E Output operation not done. the format of the structure, see “Error Code Parameter”
CPFA344 E The file &2 in library &3 is not valid. on page 2-6. If this parameter is omitted, diagnostic
CPFA345 E The invite active flag is not valid. and escape messages are issued to the application.
CPFA3A1 E
Window description value is incorrect.
CPFA3AB E Returned Value
The value for &1 must be '0' or '1'. Return code
CPFA3D1 E OUTPUT; BINARY(4)
Session description value is incorrect.
A return code indicating the result of the operation. The
Additional errors may be generated by this API. They are value returned will be 0 if the operation was successful,
listed under the applicable API as follows: or -1 otherwise.

31-8 AS/400 System API Reference V4R4

 Initialize Session Description (QsnInzSsnD) API

Error Messages Returned Value

CPF24B4 E Severe error while addressing parameter list. Return code
CPF3CF1 E OUTPUT; BINARY(4)
Error code parameter not valid.
A return code indicating the result of the operation. The
CPF3CF2 E
value returned will be 0 if the operation was successful,
Error(s) occurred during running of &1 API.
or -1 otherwise.
CPFA31E E
Required parameter &1 omitted.
CPFA343 E Output operation not done. Error Messages
CPFA344 E The file &2 in library &3 is not valid.
CPF24B4 E Severe error while addressing parameter list.
CPFA345 E The invite active flag is not valid.
CPF3CF1 E
CPFA3D6 E
Error code parameter not valid.
Session handle is incorrect.
CPF3CF2 E
Error(s) occurred during running of &1 API.
CPFA31E E
Display Scroller Top (QsnDspSclT) API Required parameter &1 omitted.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
Required Parameter: CPFA345 E The invite active flag is not valid.
CPFA3D6 E
1 Session handle Input Binary(4)
Session handle is incorrect.
Omissible Parameter:

2 Error code I/O Char(*) Initialize Session Description

Returned Value: (QsnInzSsnD) API
Return code Output Binary(4)
Required Parameter Group:
Service Program: QSNAPI
1 Session description Output Char(*)
Threadsafe: No 2 Length of session Input Binary(4)
description

The Display Scroller Top (QsnDspSclT) API positions the Omissible Parameter:
scroller at the first line in the scroller area. As many lines
following the first line as can fit in the scroller area are dis- 3 Error code I/O Char(*)
played as well.
Returned Value:

Authorities and Locks Return code Output Binary(4)

None Service Program: QSNAPI

Threadsafe: No
Required Parameter
Session handle The Initialize Session Description (QsnInzSsnD) API initial-
INPUT; BINARY(4) izes a session description with default values. Unless other-
wise specified in the session description (see “Format of the
A handle for the session to be manipulated.
Session Description” on page 31-4), pointer fields are set to
the null pointer, numeric fields to 0, character flag fields to 0,
Omissible Parameter and other character fields to blanks. For example, the
default value for the wrap indication is 1, so this field will be
Error code set to 1.
I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Authorities and Locks
on page 2-6. If this parameter is omitted, diagnostic Exit Routine Authority
and escape messages are issued to the application. *EXECUTE

Chapter 31. Session Manipulation and Query APIs 31-9

Query If Scroller in Line Wrap Mode (QsnQrySclWrp) API

Required Parameter Group

Required Parameter:
Session description
OUTPUT; CHAR(*) 1 Session handle Input Binary(4)
The session description to be initialized.
Omissible Parameter Group:
Length of session description
INPUT; BINARY(4) 2 Wrap indication Output Char(1)
3 Error code I/O Char(*)
The length of the session description parameter.
Returned Value:

Omissible Parameter Wrap indication Output Binary(4)

Error code Service Program: QSNAPI

I/O; CHAR(*)
The structure in which to return error information. For Threadsafe: No
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic The Query If Scroller in Line Wrap Mode (QsnQrySclWrp)
and escape messages are issued to the application. API queries if line wrap mode is set on or off for the given
session.
Returned Value
Return code Authorities and Locks
OUTPUT; BINARY(4)
None
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
or -1 otherwise. Required Parameter
Session handle
Error Messages INPUT; BINARY(4)

CPF24B4 E Severe error while addressing parameter list. A handle for the session to be queried.
CPF3C1D E
Length specified in parameter &1 not valid. Omissible Parameter Group
CPF3CF1 E
Error code parameter not valid. Wrap indication
CPF3CF2 E OUTPUT; CHAR(1)
Error(s) occurred during running of &1 API. Whether line wrap mode is on or off. The possible
CPFA31E E values are:
Required parameter &1 omitted.
0 Line wrap mode is off.
1 Line wrap mode is on.
Query If Scroller in Line Wrap Mode Error code
(QsnQrySclWrp) API I/O; CHAR(*)
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value
Wrap indication
OUTPUT; BINARY(4)
This API returns the value for the wrap indication param-
eter if the operation was successful, or -1 otherwise.

Error Messages
CPF24B4 E Severe error while addressing parameter list.

31-10 AS/400 System API Reference V4R4

 Retrieve Number of Rows to Roll Scroller (QsnRtvSclNumRoll) API

CPF3CF1 E Error code

Error code parameter not valid. I/O; CHAR(*)
CPF3CF2 E
The structure in which to return error information. For
Error(s) occurred during running of &1 API.
the format of the structure, see “Error Code Parameter”
CPFA31E E
on page 2-6. If this parameter is omitted, diagnostic
Required parameter &1 omitted.
and escape messages are issued to the application.
CPFA3D6 E
Session handle is incorrect.
Returned Value
Shift amount
Retrieve Number of Columns to Shift OUTPUT; BINARY(4)
Scroller (QsnRtvSclNumShf) API
Returns the value for the shift amount parameter if the
operation was successful, or -1 otherwise.
Required Parameter:
Error Messages
1 Session handle Input Binary(4)
CPF24B4 E Severe error while addressing parameter list.
Omissible Parameter Group: CPF3CF1 E
Error code parameter not valid.
2 Shift amount Output Binary(4) CPF3CF2 E
3 Error code I/O Char(*)
Error(s) occurred during running of &1 API.
CPFA31E E
Returned Value:
Required parameter &1 omitted.
Shift amount Output Binary(4) CPFA3D6 E
Session handle is incorrect.
Service Program: QSNAPI

Threadsafe: No
Retrieve Number of Rows to Roll Scroller
(QsnRtvSclNumRoll) API
The Retrieve Number of Columns to Shift Scroller
(QsnRtvSclNumShf) API returns the default number of
columns to shift the scroller by for the Shift Scroller Left Required Parameter:
(QsnShfSclL) and Shift Scroller Right (QsnShfSclR) APIs.
The default number of columns is specified on the session 1 Session handle Input Binary(4)
description. See “Create a Session (QsnCrtSsn) API” on
page 31-2 and “Change Session (QsnChgSsn) API” on Omissible Parameter Group:
page 31-1 for details. 2 Roll amount Output Binary(4)
3 Error code I/O Char(*)
Authorities and Locks Returned Value:
None Roll amount Output Binary(4)

Service Program: QSNAPI

Required Parameter
Session handle Threadsafe: No
INPUT; BINARY(4)
A handle for the session to be queried. The Retrieve Number of Rows to Roll Scroller
(QsnRtvSclNumRoll) API returns the default number of rows
to roll the scroller by for the Roll Scroller Up (QsnRollSclUp)
Omissible Parameter Group and Roll Scroller Down (QsnRollSclDown) APIs. The default
Shift amount number of rows is specified on the session description. See
OUTPUT; BINARY(4) “Create a Session (QsnCrtSsn) API” on page 31-2 and
“Change Session (QsnChgSsn) API” on page 31-1 for
The variable that contains the number of scroller
details.
columns to shift by when the QsnRtvSclNumShf API has
completed.

Chapter 31. Session Manipulation and Query APIs 31-11

Retrieve Session Data (QsnRtvSsnDta) API

Authorities and Locks

Required Parameter:
None
1 Session handle Input Binary(4)

Required Parameter Omissible Parameter Group:

Session handle 2 User data pointer Output PTR(SPP)
INPUT; BINARY(4) 3 Error code I/O Char(*)
A handle for the session to be queried.
Returned Value:

Omissible Parameter Group User data pointer Output PTR(SPP)

Roll amount Service Program: QSNAPI

OUTPUT; BINARY(4)
Threadsafe: No
The variable that contains the number of scroller rows to
roll by when the QsnRtvSclNumRoll API has completed.
The Retrieve Session Data (QsnRtvSsnDta) API returns a
Error code pointer to the user data for the given session. The user data
I/O; CHAR(*) is the pointer specified on the session description and con-
The structure in which to return error information. For sists of user-specified data that is associated with the
the format of the structure, see “Error Code Parameter” session. See “Format of the Session Description” on
on page 2-6. If this parameter is omitted, diagnostic page 31-4 for details.
and escape messages are issued to the application.
Authorities and Locks
Returned Value
None
Roll amount
OUTPUT; BINARY(4)
Required Parameter
This API returns the value for the roll amount parameter
if the operation was successful, or -1 otherwise. Session handle
INPUT; BINARY(4)

Error Messages A handle for the session for which the user data should
be returned.
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid. Omissible Parameter Group
CPF3CF2 E
User data pointer
Error(s) occurred during running of &1 API.
OUTPUT; PTR(SPP)
CPFA31E E
Required parameter &1 omitted. A pointer to the user data, as specified on the session
CPFA3D6 E description, for the given session.
Session handle is incorrect.
Error code
I/O; CHAR(*)

Retrieve Session Data (QsnRtvSsnDta) API The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.

Returned Value
User data pointer
OUTPUT; PTR(SPP)
This API returns the value for the user data pointer
parameter if the operation was successful, or the null
pointer if an error occurs.

31-12 AS/400 System API Reference V4R4

 Retrieve Session Description (QsnRtvSsnD) API

Error Messages Session handle

INPUT; BINARY(4)
CPF24B4 E Severe error while addressing parameter list.
CPF3C1F E A handle for the session for which the session descrip-
Pointer is not on a 16 byte boundary. tion should be returned.
CPF3CF1 E Session description
Error code parameter not valid. OUTPUT; CHAR(*)
CPF3CF2 E
Error(s) occurred during running of &1 API. The session description for the given session. The
CPFA31E E format of the data is shown in “Format of the Session
Required parameter &1 omitted. Description Returned.”
CPFA340 E Operation not supported with double-byte data. Length of session description
CPFA3A4 E INPUT; BINARY(4)
Specified window is not active.
CPFA3D6 E The length of the session description parameter.
Session handle is incorrect.
Omissible Parameter
Retrieve Session Description Error code
I/O; CHAR(*)
(QsnRtvSsnD) API
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Required Parameter Group: on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
1 Session handle Input Binary(4)
2 Session description Output Char(*)
3 Length of session Input Binary(4) Returned Value
description
Return code
Omissible Parameter: OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
4 Error code I/O Char(*)
value returned will be 0 if the operation was successful,
Returned Value: or -1 otherwise.

Return code Output Binary(4)

Format of the Session Description
Service Program: QSNAPI Returned
Threadsafe: No Offset
Dec Hex Type Field
The Retrieve Session Description (QsnRtvSsnD) API 0 0 BINARY(4) Bytes returned
retrieves a copy of the session description for the given
4 4 BINARY(4) Bytes available
session. The session description may be different from the
session description used when the Create a Session 8 8 CHAR(8) Reserved
(QsnCrtSsn) or the Change Session (QsnChgSsn) API is 16 10 CHAR(*) Session description. The
called. The following fields will have actual values replacing format of the remaining data
0 (if used) : returned is shown in
“Format of the Session
Number of rows in scroller Description” on page 31-4.
Number of columns in scroller
Default number of rows to roll scroller by
Error Messages
Default number of columns to shift scroller by
CPF24B4 E Severe error while addressing parameter list.
CPF3C24 E
Authorities and Locks Length of the receiver variable is not valid.
CPF3CF1 E
None Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
Required Parameter Group

Chapter 31. Session Manipulation and Query APIs 31-13

Roll Scroller Up (QsnRollSclUp) API

CPFA31E E the format of the structure, see “Error Code Parameter”

Required parameter &1 omitted. on page 2-6. If this parameter is omitted, diagnostic
CPFA3D6 E and escape messages are issued to the application.
Session handle is incorrect.
Returned Value
Roll Scroller Down (QsnRollSclDown) API Return code
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
Required Parameter: value returned will be 0 if the operation was successful,
or -1 otherwise.
1 Session handle Input Binary(4)

Omissible Parameter Group: Error Messages

2 Roll amount Input Binary(4) CPF24B4 E Severe error while addressing parameter list.
3 Error code I/O Char(*) CPF3CF1 E
Error code parameter not valid.
Returned Value: CPF3CF2 E
Return code Output Binary(4) Error(s) occurred during running of &1 API.
CPFA333 E Parameter &1 not positive integer value.
Service Program: QSNAPI CPFA31E E
Required parameter &1 omitted.
Threadsafe: No CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
The Roll Scroller Down (QsnRollSclDown) API rolls the
CPFA3D3 E
scroller down by the specified number of scroller rows. A
Scroller not printed.
scroller row is distinct from a scroller line in that a scroller
CPFA3D6 E
line consists of multiple scroller rows if line wrapping is set
Session handle is incorrect.
on and the line exceeds the width of the scroller.
CPFA3D8 E
Scroller display is not valid.
Authorities and Locks
None Roll Scroller Up (QsnRollSclUp) API

Required Parameter
Required Parameter:
Session handle
INPUT; BINARY(4) 1 Session handle Input Binary(4)

A handle for the session to be rolled. Omissible Parameter Group:

2 Roll amount Input Binary(4)

Omissible Parameter Group 3 Error code I/O Char(*)
Roll amount
Returned Value:
INPUT; BINARY(4)
The number of scroller rows to roll the scroller by. If this Return code Output Binary(4)
parameter is omitted or set to 0, the default value is
Service Program: QSNAPI
used. The default value can be queried using the
Retrieve Number of Rows to Roll Scroller Threadsafe: No
(QsnRtvSclNumRoll) API. If the roll amount would
cause the scroller to roll past its top, then the top of the
scroller will be displayed. The Roll Scroller Up (QsnRollSclUp) API rolls the scroller up
by the specified number of scroller rows. A scroller row is
Error code
distinct from a scroller line in that a scroller line consists of
I/O; CHAR(*)
multiple scroller rows if line wrapping is set on and the line
The structure in which to return error information. For exceeds the width of the scroller.

31-14 AS/400 System API Reference V4R4

 Shift Scroller Left (QsnShfSclL) API

Authorities and Locks Shift Scroller Left (QsnShfSclL) API

None

Required Parameter:
Required Parameter
1 Session handle Input Binary(4)
Session handle
INPUT; BINARY(4) Omissible Parameter Group:
A handle for the session to be rolled. 2 Shift amount Input Binary(4)
3 Error code I/O Char(*)
Omissible Parameter Group Returned Value:
Roll amount
Return code Output Binary(4)
INPUT; BINARY(4)
The number of scroller rows to roll the scroller by. If this Service Program: QSNAPI
parameter is omitted or set to 0, the default value is
used. The default value can be queried using the Threadsafe: No
Retrieve Number of Rows to Roll Scroller
(QsnRtvSclNumRoll) API. If the roll amount causes the The Shift Scroller Left (QsnShfSclL) API shifts the scroller to
scroller to roll past its bottom, then the bottom of the the left by the specified number of scroller columns. If line
scroller is displayed. wrap mode is on, shifting has no effect.
Error code
I/O; CHAR(*) Authorities and Locks
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” None
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. Required Parameter
Session handle
Returned Value INPUT; BINARY(4)
Return code A handle for the session to be shifted.
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The Omissible Parameter Group
value returned will be 0 if the operation was successful,
or -1 otherwise. Shift amount
INPUT; BINARY(4)

Error Messages The number of scroller columns to shift the scroller by.
If this parameter is omitted or set to 0, the default value
CPF24B4 E Severe error while addressing parameter list. is used. The default value can be queried using the
CPF3CF1 E Retrieve Number of Columns to Shift Scroller
Error code parameter not valid. (QsnRtvSclNumShf) API. The scroller is shifted by the
CPF3CF2 E minimum of the shift amount and the number of scroller
Error(s) occurred during running of &1 API. columns between the visible left column and the first
CPFA333 E Parameter &1 not positive integer value. column in the scroller.
CPFA31E E
Required parameter &1 omitted. Error code
CPFA343 E Output operation not done. I/O; CHAR(*)
CPFA344 E The file &2 in library &3 is not valid. The structure in which to return error information. For
CPFA345 E The invite active flag is not valid. the format of the structure, see “Error Code Parameter”
CPFA3D3 E on page 2-6. If this parameter is omitted, diagnostic
Scroller not printed. and escape messages are issued to the application.
CPFA3D6 E
Session handle is incorrect.
CPFA3D8 E Returned Value
Scroller display is not valid.

Chapter 31. Session Manipulation and Query APIs 31-15

Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) API

Return code Session handle

OUTPUT; BINARY(4) INPUT; BINARY(4)
A return code indicating the result of the operation. The A handle for the session to be shifted.
value returned will be 0 if the operation was successful,
or -1 otherwise.
Omissible Parameter Group
Shift amount
Error Messages
INPUT; BINARY(4)
CPF24B4 E Severe error while addressing parameter list.
The number of scroller columns to shift the scroller by.
CPF3CF1 E
If this parameter is omitted or set to 0, the default value
Error code parameter not valid.
is used. The default value can be queried using the
CPF3CF2 E
Retrieve Number of Columns to Shift Scroller
Error(s) occurred during running of &1 API.
(QsnRtvSclNumShf) API. The scroller is shifted by the
CPFA333 E Parameter &1 not positive integer value.
minimum of the shift amount and the number of scroller
CPFA31E E
columns between the visible right column and the last
Required parameter &1 omitted.
column (determined by the longest line currently visible)
CPFA340 E Operation not supported with double-byte data.
in the scroller.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Error code
CPFA345 E The invite active flag is not valid. I/O; CHAR(*)
CPFA3D6 E
The structure in which to return error information. For
Session handle is incorrect.
the format of the structure, see “Error Code Parameter”
CPFA3D8 E
on page 2-6. If this parameter is omitted, diagnostic
Scroller display is not valid.
and escape messages are issued to the application.

Shift Scroller Right (QsnShfSclR) API Returned Value

Return code
OUTPUT; BINARY(4)
Required Parameter:
A return code indicating the result of the operation. The
1 Session handle Input Binary(4) value returned will be 0 if the operation was successful,
or -1 otherwise.
Omissible Parameter Group:

2 Shift amount Input Binary(4) Error Messages

3 Error code I/O Char(*)
CPF24B4 E Severe error while addressing parameter list.
Returned Value: CPF3CF1 E
Error code parameter not valid.
Return code Output Binary(4) CPF3CF2 E
Error(s) occurred during running of &1 API.
Service Program: QSNAPI
CPFA333 E Parameter &1 not positive integer value.
Threadsafe: No CPFA31E E
Required parameter &1 omitted.
CPFA340 E Operation not supported with double-byte data.
The Shift Scroller Right (QsnShfSclR) API shifts the scroller CPFA343 E Output operation not done.
to the right by the specified number of scroller columns. Any CPFA344 E The file &2 in library &3 is not valid.
truncated data will become visible. If line wrap mode is on, CPFA345 E The invite active flag is not valid.
shifting has no effect. CPFA3D6 E
Session handle is incorrect.
CPFA3D8 E
Authorities and Locks Scroller display is not valid.
None

Toggle Line Wrap/Truncate Mode

Required Parameter (QsnTglSclWrp) API

31-16 AS/400 System API Reference V4R4

 Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) API

QsnTglSclWrp API has completed. The possible values

Required Parameter: are:

0 Line wrap mode is now off. Lines are

1 Session handle Input Binary(4)
truncated.
Omissible Parameter Group: 1 Line wrap mode is now on.

2 Wrap indication Output Char(1)

Error code
3 Error code I/O Char(*) I/O; CHAR(*)
The structure in which to return error information. For
Returned Value: the format of the structure, see “Error Code Parameter”
Wrap indication Output Binary(4) on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application.
Service Program: QSNAPI

Threadsafe: No Returned Value

Wrap indication
OUTPUT; BINARY(4)
The Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) API
toggles the session between line wrap and truncation mode. This API returns the value for the wrap indication param-
eter if the operation was successful, or -1 otherwise.

Authorities and Locks

Error Messages
None
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Required Parameter Error code parameter not valid.
CPF3CF2 E
Session handle Error(s) occurred during running of &1 API.
INPUT; BINARY(4) CPFA31E E
A handle for the session to be queried. Required parameter &1 omitted.
CPFA340 E Operation not supported with double-byte data.
CPFA343 E Output operation not done.
Omissible Parameter Group CPFA344 E The file &2 in library &3 is not valid.
Wrap indication CPFA345 E The invite active flag is not valid.
OUTPUT; CHAR(1) CPFA3D6 E
Session handle is incorrect.
Indicates whether line wrap mode is on or off when the

Chapter 31. Session Manipulation and Query APIs 31-17

Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) API

31-18 AS/400 System API Reference V4R4

 Backspace on Scroller Line (QsnSclBS) API

Chapter 32. Session I/O APIs

Session I/O APIs—Introduction

Required Parameter:
The session I/O APIs are:
1 Session handle Input Binary(4)
Backspace on Scroller Line
(QsnSclBS) sets the active position to the pre- Omissible Parameter:
vious position in the current scroller line.
2 Error code I/O Char(*)
Go to Next Tab Position in Scroller Line
(QsnSclTab) sets the active position to the
Returned Value:
next horizontal tab position.
Go to Start of Current Scroller Line Return code Output Binary(4)
(QsnSclCR) sets the active position to the
start of the current scroller line. Service Program: QSNAPI
Go to Start of Next Scroller Line (QsnSclNL)
(QsnSclNL) sets the active position to the start Threadsafe: No
of the next scroller line.
Print Scroller Data The Backspace on Scroller Line (QsnSclBS) API sets the
(QsnPrtScl) prints the scroller data. active position to the previous position on the current scroller
Read Data from Session line. If the active position is at the start of the line, this oper-
(QsnReadSsnDta) reads the data from a ation has no effect.
session.
Retrieve Session Line to Input Line
(QsnRtvSsnLin) retrieves the input line from Authorities and Locks
the scroller.
Start New Scroller Line at Current Position None
(QsnSclLF) sets the active position to the
current position on the next scroller line. Required Parameter
Start New Scroller Page
(QsnSclFF) starts a new scroller page. Session handle
Write Characters to Scroller INPUT; BINARY(4)
(QsnWrtSclChr) writes characters to the A handle for the session that the operation applies to.
scroller.
Write Line to Scroller
(QsnWrtSclLin) writes a data line to the Omissible Parameter
scroller.
Error code
The detailed API descriptions are presented in alphabetical I/O; CHAR(*)
order. The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Backspace on Scroller Line (QsnSclBS) and escape messages are issued to the application.
API
Returned Value
Return code
OUTPUT; BINARY(4)
A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
or -1 otherwise.

Error Messages
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid.

 Copyright IBM Corp. 1998, 1999 32-1

Go to Start of Current Scroller Line (QsnSclCR) API

CPF3CF2 E Return code

Error(s) occurred during running of &1 API. OUTPUT; BINARY(4)
CPFA31E E
A return code indicating the result of the operation. The
Required parameter &1 omitted.
value returned will be 0 if the operation was successful,
CPFA340 E Operation not supported with double-byte data.
or -1 otherwise.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. Error Messages
CPFA3D6 E CPF24B4 E Severe error while addressing parameter list.
Session handle is incorrect. CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Go to Next Tab Position in Scroller Line Error(s) occurred during running of &1 API.
(QsnSclTab) API CPFA31E E
Required parameter &1 omitted.
CPFA340 E Operation not supported with double-byte data.
Required Parameter: CPFA3D6 E
Session handle is incorrect.
1 Session handle Input Binary(4) CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
Omissible Parameter: CPFA345 E The invite active flag is not valid.
2 Error code I/O Char(*)

Returned Value: Go to Start of Current Scroller Line

Return code Output Binary(4)
(QsnSclCR) API

Service Program: QSNAPI

Required Parameter:
Threadsafe: No
1 Session handle Input Binary(4)

The Go to Next Tab Position in Scroller Line (QsnSclTab) Omissible Parameter:

API sets the active position to the next horizontal tab posi-
2 Error code I/O Char(*)
tion. Each tab interval is eight positions beyond the previous
one, starting at the leftmost column in the scroller.
Returned Value:

Return code Output Binary(4)

Authorities and Locks
Service Program: QSNAPI
None
Threadsafe: No
Required Parameter
Session handle The Go to Start of Current Scroller Line (QsnSclCR) API sets
INPUT; BINARY(4) the active position to the start of the current scroller line.
A handle for the session that the operation applies to.
Authorities and Locks
Omissible Parameter None
Error code
I/O; CHAR(*) Required Parameter
The structure in which to return error information. For
Session handle
the format of the structure, see “Error Code Parameter”
INPUT; BINARY(4)
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. A handle for the session that the operation applies to.

Returned Value Omissible Parameter

32-2 AS/400 System API Reference V4R4

 Print Scroller Data (QsnPrtScl) API

Error code The Go to Start of Next Scroller Line (QsnSclNL) API sets
I/O; CHAR(*) the active position to the start of the next scroller line.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Authorities and Locks
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. None

Returned Value Required Parameter

Return code Session handle
OUTPUT; BINARY(4) INPUT; BINARY(4)
A return code indicating the result of the operation. The A handle for the session that the operation applies to.
value returned will be 0 if the operation was successful,
or -1 otherwise.
Omissible Parameter
Error code
Error Messages
I/O; CHAR(*)
CPF24B4 E Severe error while addressing parameter list.
The structure in which to return error information. For
CPF3CF1 E
the format of the structure, see “Error Code Parameter”
Error code parameter not valid.
on page 2-6. If this parameter is omitted, diagnostic
CPF3CF2 E
and escape messages are issued to the application.
Error(s) occurred during running of &1 API.
CPFA31E E
Required parameter &1 omitted. Returned Value
CPFA340 E Operation not supported with double-byte data.
CPFA343 E Output operation not done. Return code
CPFA344 E The file &2 in library &3 is not valid. OUTPUT; BINARY(4)
CPFA345 E The invite active flag is not valid. A return code indicating the result of the operation. The
CPFA3D6 E value returned will be 0 if the operation was successful,
Session handle is incorrect. or -1 otherwise.

Go to Start of Next Scroller Line Error Messages

(QsnSclNL) API CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Error code parameter not valid.
Required Parameter: CPF3CF2 E
Error(s) occurred during running of &1 API.
1 Session handle Input Binary(4) CPFA31E E
Required parameter &1 omitted.
Omissible Parameter: CPFA340 E Operation not supported with double-byte data.
CPFA343 E Output operation not done.
2 Error code I/O Char(*)
CPFA344 E The file &2 in library &3 is not valid.
Returned Value: CPFA345 E The invite active flag is not valid.
CPFA3D6 E
Return code Output Binary(4) Session handle is incorrect.

Service Program: QSNAPI

Threadsafe: No
Print Scroller Data (QsnPrtScl) API

Chapter 32. Session I/O APIs 32-3

Read Data from Session (QsnReadSsnDta) API

CPFA3D3 E
Required Parameter: Scroller not printed.
CPFA3D6 E
1 Session handle Input Binary(4) Session handle is incorrect.

Omissible Parameter:

2 Error code I/O Char(*)

Read Data from Session (QsnReadSsnDta)
API
Returned Value:

Return code Output Binary(4)

Required Parameter Group:
Service Program: QSNAPI 1 Session handle Input Binary(4)
2 Input buffer handle Input Binary(4)
Threadsafe: No
Omissible Parameter Group:
The Print Scroller Data (QsnPrtScl) API prints the entire con- 3 Number of bytes read Output Binary(4)
tents of the scroller data to the default printer file. No printer 4 Error code I/O Char(*)
file is produced if the scroller is empty.
Returned Value:

Authorities and Locks Number of bytes read Output Binary(4)

None Service Program: QSNAPI

Threadsafe: No
Required Parameter
Session handle The Read Data from Session (QsnReadSsnDta) API is used
INPUT; BINARY(4) to read data from a session. A QsnReadInp operation is
A handle for the session that the operation applies to. implicitly performed to read any field data. If the session has
a DSM-defined input line, an implicit Clear Field Table
(QsnClrFldTbl) operation is issued prior to redefining the
Omissible Parameter session input line on each input operation. The data
Error code returned consists of only the data entered. That is, only the
I/O; CHAR(*) data from the cursor position within the field up to the last
nonblank input character when an AID generating key is
The structure in which to return error information. For pressed is returned. If the session does not have a
the format of the structure, see “Error Code Parameter” DSM-defined input line, data is read from any input fields
on page 2-6. If this parameter is omitted, diagnostic defined on the screen, and all data, including blanks, is
and escape messages are issued to the application. returned. In other respects, the processing of these user-
defined input fields will be equivalent with the processing of
Returned Value the DSM-defined input line.

Return code If an AID key is pressed for which a corresponding function

OUTPUT; BINARY(4) has been defined, this function will be called. Depending
upon the return action specified, control would then return to
A return code indicating the result of the operation. The
the caller or another input operation will occur. See
value returned will be 0 if the operation was successful,
“Command Key Action Routines” on page 30-1 for details.
or -1 otherwise.

Error Messages Authorities and Locks

CPF24B4 E Severe error while addressing parameter list. None
CPF3CF1 E
Error code parameter not valid.
CPF3CF2 E
Required Parameter Group
Error(s) occurred during running of &1 API. Session handle
CPFA31E E INPUT; BINARY(4)
Required parameter &1 omitted.
A handle for the session from which to read input. The
CPFA343 E Output operation not done.
session being read from must be the current window.

32-4 AS/400 System API Reference V4R4

 Retrieve Session Line to Input Line (QsnRtvSsnLin) API

You can use the Set Current Window (QsnSetCurWin)

API to change the current window. Retrieve Session Line to Input Line
(QsnRtvSsnLin) API
Input buffer handle
INPUT; BINARY(4)
A handle for the input buffer to receive the result of the Required Parameter:
input operations if a direct operation is specified. The
input buffer must have been created with the Create 1 Session handle Input Binary(4)
Input Buffer (QsnCrtInpBuf) API. The format of the data
Omissible Parameter:
returned is the same as that of the Read Input Fields
(QsnReadInp) API. 2 Error code I/O Char(*)

Returned Value:
Omissible Parameter Group
Return code Output Binary(4)
Number of bytes read
OUTPUT; BINARY(4) Service Program: QSNAPI
The number of bytes of data read. On a successful read
operation, this value is the same as that returned by the Threadsafe: No
Retrieve Length of Field Data in Buffer
(QsnRtvFldDtaLen) API if passed the input buffer The Retrieve Session Line to Input Line (QsnRtvSsnLin) API
resulting from this operation. retrieves the input line from the scroller that corresponds to
Error code the cursor position within the scroller. If the cursor is outside
I/O; CHAR(*) the scroller and the retrieve request directly follows another
retrieve with no intervening I/O operations, then the line
The structure in which to return error information. For before the line previously retrieved is returned. Otherwise,
the format of the structure, see “Error Code Parameter” the last input line is retrieved. If there is no input data, this
on page 2-6. If this parameter is omitted, diagnostic API still completes successfully.
and escape messages are issued to the application.

Authorities and Locks

Returned Value
None
Number of bytes read
OUTPUT; BINARY(4)
This API returns the value for the number of bytes read Required Parameter
parameter if the operation was successful, -1 if there Session handle
was a general failure, or -2 if the invite active flag is on INPUT; BINARY(4)
in the associated environment and the read from invited
device operation timed out. A handle for the session for which to retrieve the input
line.

Error Messages
Omissible Parameter
CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E Error code
Error code parameter not valid. I/O; CHAR(*)
CPF3CF2 E The structure in which to return error information. For
Error(s) occurred during running of &1 API. the format of the structure, see “Error Code Parameter”
CPFA31E E on page 2-6. If this parameter is omitted, diagnostic
Required parameter &1 omitted. and escape messages are issued to the application.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid. Returned Value
CPFA3A4 E
Return code
Specified window is not active.
OUTPUT; BINARY(4)
CPFA3D6 E
Session handle is incorrect. A return code indicating the result of the operation. The
CPFA3D9 E value returned will be 0 if the operation was successful,
Error calling the command key action routine. or -1 otherwise.

Chapter 32. Session I/O APIs 32-5

Start New Scroller Page (QsnSclFF) API

Error Messages Returned Value

CPF24B4 E Severe error while addressing parameter list. Return code
CPF3CF1 E OUTPUT; BINARY(4)
Error code parameter not valid.
A return code indicating the result of the operation. The
CPF3CF2 E
value returned will be 0 if the operation was successful,
Error(s) occurred during running of &1 API.
or -1 otherwise.
CPFA31E E
Required parameter &1 omitted.
CPFA3A4 E Error Messages
Specified window is not active.
CPF24B4 E Severe error while addressing parameter list.
CPFA3D6 E
CPF3CF1 E
Session handle is incorrect.
Error code parameter not valid.
CPF3CF2 E
Error(s) occurred during running of &1 API.
Start New Scroller Line at Current Position CPFA31E E
(QsnSclLF) API Required parameter &1 omitted.
CPFA340 E Operation not supported with double-byte data.
CPFA343 E Output operation not done.
Required Parameter: CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
1 Session handle Input Binary(4)
CPFA3D6 E
Session handle is incorrect.
Omissible Parameter:

2 Error code I/O Char(*)

Start New Scroller Page (QsnSclFF) API
Returned Value:

Return code Output Binary(4)

Required Parameter:
Service Program: QSNAPI
1 Session handle Input Binary(4)
Threadsafe: No
Omissible Parameter:

The Start New Scroller Line at Current Position (QsnSclLF) 2 Error code I/O Char(*)
API sets the active position to the current position on the
Returned Value:
next scroller line.
Return code Output Binary(4)

Authorities and Locks Service Program: QSNAPI

None Threadsafe: No

Required Parameter The Start New Scroller Page (QsnSclFF) API starts a new
Session handle scroller page. Any data currently on the session is rolled off
INPUT; BINARY(4) the top of the scroller, but can still be viewed by rolling the
scroller up.
A handle for the session that the operation applies to.

Authorities and Locks

Omissible Parameter
Error code None
I/O; CHAR(*)
The structure in which to return error information. For Required Parameter
the format of the structure, see “Error Code Parameter”
Session handle
on page 2-6. If this parameter is omitted, diagnostic
INPUT; BINARY(4)
and escape messages are issued to the application.
A handle for the session for which to start the new page.

32-6 AS/400 System API Reference V4R4

 Write Characters to Scroller (QsnWrtSclChr) API

Omissible Parameter control character sequence if it appears at the end of the

data. If the entire data string cannot fit in the scroller buffer,
Error code no portion of the string will be written.
I/O; CHAR(*)
The structure in which to return error information. For Authorities and Locks
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic None
and escape messages are issued to the application.

Required Parameter Group

Returned Value
Session handle
Return code INPUT; BINARY(4)
OUTPUT; BINARY(4)
A handle for the session to which the scroller characters
A return code indicating the result of the operation. The are to be written.
value returned will be 0 if the operation was successful,
or -1 otherwise. Data
Input; CHAR(*)
The characters to be written to the scroller. If the data
Error Messages does not fit within the width of the session window, it is
CPF24B4 E Severe error while addressing parameter list. wrapped across multiple lines or truncated, depending
CPF3CF1 E on the value of the wrap indication field on the session
Error code parameter not valid. description.
CPF3CF2 E
Error(s) occurred during running of &1 API. Data length
CPFA31E E Input; CHAR(*)
Required parameter &1 omitted. The length of the data parameter.
CPFA340 E Operation not supported with double-byte data.
CPFA343 E Output operation not done.
CPFA344 E The file &2 in library &3 is not valid. Omissible Parameter
CPFA345 E The invite active flag is not valid. Error code
CPFA3D6 E I/O; CHAR(*)
Session handle is incorrect.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Write Characters to Scroller and escape messages are issued to the application.
(QsnWrtSclChr) API
Returned Value
Required Parameter Group: Return code
1 Session handle Input Binary(4) OUTPUT; BINARY(4)
2 Data Input Char(*) A return code indicating the result of the operation. The
3 Data length Input Binary(4) value returned will be 0 if the operation was successful,
or -1 otherwise.
Omissible Parameter:

4 Error code I/O Char(*)

Error Messages
Returned Value: CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
Return code Output Binary(4) Error code parameter not valid.
CPF3CF2 E
Service Program: QSNAPI
Error(s) occurred during running of &1 API.
Threadsafe: No CPFA333 E Parameter &1 not positive integer value.
CPFA31E E
Required parameter &1 omitted.
The Write Characters to Scroller (QsnWrtSclChr) API writes CPFA340 E Operation not supported with double-byte data.
one or more characters to the scroller starting at the active CPFA343 E Output operation not done.
position. The active position following this operation is one CPFA344 E The file &2 in library &3 is not valid.
position past the last character written or that specified by a

Chapter 32. Session I/O APIs 32-7

Performance Considerations

CPFA345 E The invite active flag is not valid. Line data length
CPFA3D6 E Input; CHAR(*)
Session handle is incorrect.
The length of the line data parameter.
CPFA3D7 E
Data for scroller is too long. Note: The first 2 bytes of the scroller are reserved for
the prefix area to the left of the scroller line.

Write Line to Scroller (QsnWrtSclLin) API Omissible Parameter

Error code
Required Parameter Group: I/O; CHAR(*)
The structure in which to return error information. For
1 Session handle Input Binary(4) the format of the structure, see “Error Code Parameter”
2 Line data Input Char(*)
on page 2-6. If this parameter is omitted, diagnostic
3 Line data length Input Binary(4)
and escape messages are issued to the application.
Omissible Parameter:

4 Error code I/O Char(*) Returned Value

Return code
Returned Value:
OUTPUT; BINARY(4)
Return code Output Binary(4) A return code indicating the result of the operation. The
value returned will be 0 if the operation was successful,
Service Program: QSNAPI or -1 otherwise.
Threadsafe: No
Error Messages
The Write Line to Scroller (QsnWrtSclLin) API writes a line of CPD0024 E No matching shift-in character for shift-out char-
data, such as an informational message, to the scroller. The acter.
data is written starting at the first position on the next scroller CPF24B4 E Severe error while addressing parameter list.
line. The active position after this operation is the start of the CPF3CF1 E
next scroller line following the row containing the last data Error code parameter not valid.
character written, or specified by a control character CPF3CF2 E
sequence if one appears at the end of the data. If the entire Error(s) occurred during running of &1 API.
line cannot fit in the scroller buffer, no portion of the data will CPFA333 E Parameter &1 not positive integer value.
be written. CPFA31E E
Required parameter &1 omitted.
CPFA343 E Output operation not done.
Authorities and Locks CPFA344 E The file &2 in library &3 is not valid.
CPFA345 E The invite active flag is not valid.
None
CPFA3D6 E
Session handle is incorrect.
Required Parameter Group CPFA3D7 E
Data for scroller is too long.
Session handle CPG3264 D
INPUT; BINARY(4) DBCS character string does not have even
A handle for the session to which the scroller line is to length.
be written.

Line data
Input; CHAR(*)
Performance Considerations
The data to be written to the scroller. If the line does Specifying EBCDIC control-character options on the session
not fit within the width of the session window, it is description can incur overhead. Additional processing is
wrapped across multiple lines or truncated, depending required to handle these. Specifying the scroller line and
on the value of the wrap indication field on the session character display as immediate can incur additional over-
description. head. An output operation will occur for each line or group
Note: The first 2 bytes of the scroller are reserved for of characters written. If you need to write multiple lines to
the prefix area to the left of the scroller line. the scroller, you can achieve better performance by delaying
line display until all the lines are written. Then you can use

32-8 AS/400 System API Reference V4R4

 Create Session and Read Data—Example

the Display Scroller Bottom (QsnDspSclB) API to display the #include <stddef.h>
#include <stdlib.h>
data on the screen. #include <string.h>
#include <stdio.h>
#include "qsnapi.h"

Create Session and Read Data—Example #define TRUE 1

#define FALSE ð
The sample program in Figure 32-1 shows how to create #define PF1 "PF4 - Move PF5 - Resize"
and read data from a session. The resulting screen output is #define PF2 "PF6 - Print"
shown in Figure 32-2 on page 32-10. typedef struct {
Qsn_Ssn_Desc_T sess_desc;
char buffer[1ðð];
} storage_t;

int main (void)

{
Qsn_Inp_Buf_T ibuf = ð;
char \fld_dta;
int i;
char text[1ðð];
storage_t storage;

Qsn_Ssn_T session1;
Qsn_Ssn_Desc_T \sess_desc = (Qsn_Ssn_Desc_T \) &storage;
Qsn_Win_Desc_T win_desc;
Q_Bin4 win_desc_length = sizeof(win_desc);
char \pf1 = PF1;
Q_Bin4 pf1_len = sizeof(PF1) - 1;
char \pf2 = PF2;
Q_Bin4 pf2_len = sizeof(PF2) - 1;
Q_Bin4 sess_desc_length = sizeof(Qsn_Ssn_Desc_T) + pf1_len +
pf2_len;

/\ initialize and set up session and window descriptions \/

QsnInzSsnD( sess_desc, sess_desc_length, NULL);
QsnInzWinD( &win_desc, win_desc_length, NULL);

sess_desc->cmd_key_desc_line_1_offset = sizeof(Qsn_Ssn_Desc_T);
sess_desc->cmd_key_desc_line_1_len = pf1_len;
memcpy( storage.buffer, pf1, pf1_len );

sess_desc->cmd_key_desc_line_2_offset = sizeof(Qsn_Ssn_Desc_T) +
pf1_len;
sess_desc->cmd_key_desc_line_2_len = pf2_len;
memcpy( storage.buffer + pf1_len, pf2, pf2_len );

sess_desc->scl_line_dsp = '1';
sess_desc->scl_chr_dsp = '1';
sess_desc->num_input_line_rows = 2;
sess_desc->wrap = 'ð';

QsnCrtSsn( sess_desc, sess_desc_length, NULL, ð, '1',

&win_desc, win_desc_length, NULL, ð,
&session1, NULL);

if (ibuf == ð)
ibuf = QsnCrtInpBuf(1ðð, 5ð, ð, NULL, NULL);
while ( TRUE ) {
QsnReadSsnDta( session1, ibuf, NULL, NULL);
/\ check if any data read, then end if exit entered \/
if ( (fld_dta=QsnRtvFldDta(ibuf, NULL, NULL)) != NULL) {
if (strncmp(fld_dta, "exit", 4) == ð)
break;
}
}
}
Figure 32-1. Program for Creating a Session and Reading Data

Chapter 32. Session I/O APIs 32-9

Create Session and Read Data—Example

à ..............................................................................
ð
: > this is line 1 :
: > this is line 2 :
: > more lines :
: > more data :
: > another line :
: :
: :
: :
: :
: :
: :
: :
: :
: :
: :
: :
: ===> ___________________________________________________________________ :
: ________________________________________________________________________ :
: F4=Move F5=Resize :
: F6=Print :
: :
:............................................................................:

á ñ
Figure 32-2. Screen Output from Create Session Program

32-10 AS/400 System API Reference V4R4

 Edit Function

Part 10. Edit Function APIs

Chapter 33. Edit Function APIs . . . . . . . . . . 33-1 Required Parameter Group . . . . . . . . . . . . 33-3
Edit Function APIs—Introduction . . . . . . . . . . . 33-1 | Optional Parameter Group . . . . . . . . . . . . 33-3
Convert Edit Code (QECCVTEC) API . . . . . . . . 33-1 Error Messages . . . . . . . . . . . . . . . . . . 33-3
Authorities and Locks . . . . . . . . . . . . . . . 33-1 Edit (QECEDT) API . . . . . . . . . . . . . . . . . . 33-4
Required Parameter Group . . . . . . . . . . . . 33-1 Authorities and Locks . . . . . . . . . . . . . . . 33-4
Error Messages . . . . . . . . . . . . . . . . . . 33-2 Required Parameter Group . . . . . . . . . . . . 33-4
Convert Edit Word (QECCVTEW) API . . . . . . . . 33-2 Error Messages . . . . . . . . . . . . . . . . . . 33-4
Authorities and Locks . . . . . . . . . . . . . . . 33-3

 Copyright IBM Corp. 1998, 1999

Edit Function

AS/400 System API Reference V4R4

 Convert Edit Code (QECCVTEC) API

Chapter 33. Edit Function APIs

The Convert Edit Code (QECCVTEC) API translates an edit
Edit Function APIs—Introduction code specification into an edit mask, which is a byte string
used to format a numeric value into a readable character
This application program interface is used to create and use
string.
edit masks. An edit mask is a byte string that tells the edit
machine instruction or the Edit (QECEDT) API how to format
a numeric value into a readable character string. Authorities and Locks
An edit mask can format a numeric value so that languages User-Defined Edit Code Authority
that cannot directly use machine instructions can now take *USE
advantage of this function. The edit mask was previously User-Defined Edit Code Library Authority
defined by the Edit Code (EDTCDE) and Edit Word *EXECUTE
(EDTWRD) keywords in DDS.

An edit code is a standard description of how a number

Required Parameter Group
should be formatted. There are many standard edit codes Edit mask
defined by the system. Users can define several edit codes OUTPUT; CHAR(256)
the way they want with the use of the Create Edit Description
Returns the edit mask generated by this call. The actual
(CRTEDTD) command. For more information, see the
length of the edit mask is returned in the edit mask
description of the Edit Code (EDTCDE) keyword in the DDS
length parameter. The area beyond the actual length of
Reference book.
the edit mask is filled with hexadecimal zeros.
An edit word is a user-defined description of how a number The value returned to this parameter should be passed
should be formatted. An edit word is usually used when one to the Edit (QECEDT) API or the edit machine instruc-
of the standard edit codes or user-defined edit codes is not tion.
sufficient for a particular situation. For more information, see
the description of the Edit Word (EDTWRD) keyword in the Edit mask length
DDS Reference book. OUTPUT; BINARY(4)
The actual length of the edit mask.
The edit function APIs are presented in alphabetical order.
They are: The value returned in this parameter should be passed
to the QECEDT API or used to substring the value
Convert Edit Code returned in the edit mask in the edit machine instruction.
(QECCVTEC)
Convert Edit Word Receiver variable length
(QECCVTEW) OUTPUT; BINARY(4)
Edit (QECEDT) Returns the length of the output that is produced by the
returned edit mask when it is used.
The value returned in this parameter should be passed
Convert Edit Code (QECCVTEC) API
to the QECEDT API or used to substring the receiver
variable in the edit machine instruction.
Required Parameter Group: Zero balance fill character
OUTPUT; CHAR(1)
1 Edit mask Output Char(256)
2 Edit mask length Output Binary(4) Indicates how to perform the edit so that zero balance
3 Receiver variable length Output Binary(4) suppression is done correctly for those edit codes that
4 Zero balance fill character Output Char(1) have zero balance suppression.
5 Edit code Input Char(1)
6 Fill or Floating currency Input Char(1) The value returned in this parameter should be passed
indication to the QECEDT API or used to determine whether zero
7 Source variable precision Input Binary(4) suppression requires special handling before issuing the
8 Source variable decimal Input Binary(4) edit machine instruction.
positions
9 Error code I/O Char(*) Edit code
INPUT; CHAR(1)
Threadsafe: Yes
The edit code that is to be translated into an edit mask.
The valid values are:

 Copyright IBM Corp. 1998, 1999 33-1

Convert Edit Word (QECCVTEW) API

A–D Notes:
J–Q
1. Some high-level languages limit the maximum preci-
W
sion of packed and zoned numeric variables.
Y–Z
1–9 2. Because the precision of the source variable is so
important in creating the edit mask, an edit mask
For more information on edit codes, see the DDS Refer-
can only be used to edit variables of the exact preci-
ence book.
sion.
Fill or floating currency indication
Source variable decimal positions
INPUT; CHAR(1)
INPUT; BINARY(4)
Indicates how the output should be padded on the left.
The number of digits that the source variable precision
This parameter should be specified as follows:
parameter has placed after the decimal point in the
"" Blank fill: All suppressed zeros are edited output. The value must be less than or equal to
replaced with blanks. source variable precision, but greater than 0. The
"*" Asterisk fill: All suppressed zeros are normal value depends on the class of the source vari-
replaced with asterisks. able precision parameter:
Character Blank fill: The specified character is
Variable Decimal
used as a floating currency symbol and
Class Position
placed to the left of the first nonsup-
pressed digit. Characters are X'41' to
Packed The number of decimal positions for
which the variable was declared. For
X'FE'.
example, PACKED (8,4) has 4 decimal
Note: You can optionally specify asterisk fill or floating positions.
currency symbol with edit codes 1 through 4, A through Zoned The number of decimal positions for
D, and J through Q. which the variable was declared. For
example, ZONED (8,4) has 4 decimal
Source variable precision
positions.
INPUT; BINARY(4)
Binary(2) 0
The precision of the numeric variable that is edited with Binary(4) 0
the edit mask. Precision is the displayed length of a
Error code
field, not including the decimal point. The valid ranges
I/O; CHAR(*)
depend on the value specified for the edit code.
The structure in which to return error information. For
Edit Code Range
the format of the structure, see “Error Code Parameter”
W 5–8
on page 2-6.
Y 3–8
All others 1–31
Error Messages
The precision of the numeric variable depends on its
class: CPF2620 E Field longer than integer or fraction mask.
CPF2639 E Edit mask too large.
Variable CPF27B2 E Edit code not valid.
Class Precision CPF27B3 E Fill/floating currency indication not valid.
Packed The precision for which the variable was CPF27B4 E Source variable precision not valid.
declared. For example, PACKED(8,4) CPF27B5 E Source decimal position not valid.
has precision 8. CPF3C90 E
Zoned The precision for which the variable was Literal value cannot be changed.
declared. For example, ZONED(8,4) has CPF3CF1 E
precision 8. Error code parameter not valid.
Binary(2) 5 CPF9801 E Object &2 in library &3 not found.
Binary(4) 10 CPF9802 E Not authorized to object &2 in &3.
CPF9872 E Program or service program &1 in library &2
ended. Reason code &3.

Convert Edit Word (QECCVTEW) API

33-2 AS/400 System API Reference V4R4

 Convert Edit Word (QECCVTEW) API

character in the system value QCURSYM is treated as a

Required Parameter Group: currency symbol if it appears in the edit word.

Edit word length

1 Edit mask Output Char(256)
2 Edit mask length Output Binary(4)
INPUT; BINARY(4)
3 Receiver variable length Output Binary(4) The actual length of the edit word. The value passed
4 Edit word Input Char(*) must be from 1 through 256.
5 Edit word length Input Binary(4)
6 Error code I/O Char(*) Error code
I/O; CHAR(*)
| Optional Parameter Group:
The structure in which to return error information. For
| 7 Source length Input Binary(4) the format of the structure, see “Error Code Parameter”
| 8 Currency symbol Input Char(1) on page 2-6.

Threadsafe: Yes
| Optional Parameter Group
The Convert Edit Word (QECCVTEW) API translates an edit | Source length
word specification into an edit mask. This is useful when | INPUT; BINARY(4)
one of the standard or user-defined edit codes does not | The length of the source data to be edited. The length
provide the editing required. | used is the same as the value that would be used for
| the source variable precision parameter of the QECEDT
Authorities and Locks | API.
| An edit word may begin with a zero suppression char-
None | acter. If it does, two different edit word combinations
| can be provided:
Required Parameter Group | Ÿ The zero suppression character and the remaining
Edit mask | number of replacement characters equals the
OUTPUT; CHAR(256) | source length. This provides suppression of the
| leading zero only.
Returns the edit mask generated by this call. The actual
length of the edit mask is returned in the edit mask | Ÿ The zero suppression character plus the replace-
length parameter. The area beyond the actual length of | ment characters is one more than the source length.
the edit mask is filled with hexadecimal zeros. | This results in no zero suppression.

The value returned to this parameter should be passed | If the edit word provided is the second form, use this
to the Edit (QECEDT) API or the edit machine instruc- | parameter. Otherwise, an incorrect edit mask is gener-
tion. | ated because QECCVTEW assumes the first form of
| editing is intended.
Edit mask length
OUTPUT; BINARY(4) | Currency symbol
| INPUT; CHAR(1)
Returns the actual length of the edit mask parameter.
| The currency symbol to be placed in the edited output.
The value returned in this parameter should be passed
| If this value appears in the edit word, it is used as the
to the QECEDT API or used to substring the value
| currency symbol.
returned in the edit mask in the edit machine instruction.
| If the value passed for currency symbol is X'00' (HEX
Receiver variable length | zero), the API uses the system value QCURSYM as the
OUTPUT; BINARY(4) | currency symbol.
The actual length of the output that is produced by the
returned edit mask when it is used.
Error Messages
The value returned in this parameter should be passed
| CPF2620 E Field longer than integer or fraction mask.
to the QECEDT API or used to substring the value
CPF2639 E Edit mask too large.
returned in the receiver variable in the edit machine
| CPF265E E Number of parameters specified not valid.
instruction.
CPF27B6 E Edit word length not valid.
Edit word CPF3C90 E
INPUT; CHAR(*) Literal value cannot be changed.
CPF3CF1 E
| The edit word is translated into an edit mask. If the
Error code parameter not valid.
| optional currency symbol parameter is not used, the

Chapter 33. Edit Function APIs 33-3

Edit (QECEDT) API

Source variable precision

Edit (QECEDT) API INPUT; BINARY(4)
The precision of the numeric variable specified in the
source variable parameter. The value passed must be
Required Parameter Group: from 1 through 31.
1 Receiver variable Output Char(*) Variable
2 Receiver variable length Input Binary(4) Class Precision
3 Source variable Input *
Packed The precision for which the variable was
4 Source variable class Input Char(10)
5 Source variable precision Input Binary(4)
declared. For example, PACKED(8,4)
6 Edit mask Input Char(*) has precision 8.
7 Edit mask length Input Binary(4) Zoned The precision for which the variable was
8 Zero balance fill character Input Char(1) declared. For example, ZONED(8,4) has
9 Error code I/O Char(*) precision 8.
Binary(2) 5
Threadsafe: Yes Binary(4) 10

Note: Some high-level languages limit the maximum

The Edit (QECEDT) API uses an edit mask to transform a precision of packed and zoned numeric variables.
numeric from its internal format to a character form suitable
for displaying. Edit mask
INPUT; CHAR(*)
The edit mask used for this edit operation. This is the
Authorities and Locks
value returned in the edit mask parameter on the call to
None the QECCVTEC API or QECCVTEW API.

Edit mask length

Required Parameter Group INPUT; BINARY(4)

Receiver variable The length of the edit mask. The value passed must be
OUTPUT; CHAR(*) from 1 through 256. This is the value returned in the
edit mask length parameter on the call to the
Receives the edited output. The length of this area must QECCVTEC API or QECCVTEW API.
be passed in the receiver variable length parameter.
Zero balance fill character
Receiver variable length INPUT; CHAR(1)
INPUT; BINARY(4)
Indicates how to perform the edit operation so that zero
The length of the referenced area by the receiver vari- balance suppression is done correctly for those edit
able parameter. This value must be greater than 0. codes that have zero balance suppression.
This value was returned in the receiver variable length If the QECCVTEC API is used to create the edit mask,
parameter on the previous call to the Convert Edit Code this should be the value returned in the zero balance fill
(QECCVTEC) API or Convert Edit Word (QECCVTEW) character parameter; otherwise, unpredictable results
API; otherwise, CPF27AF is returned. may occur.
Source variable If the QECCVTEW API is used to create the edit mask,
INPUT; * X'00' should be specified for this parameter; otherwise,
The numeric value that is converted. The type is unpredictable results may occur.
defined by the source variable class parameter and the Error code
length is specified in the source variable precision I/O; CHAR(*)
parameter.
The structure in which to return error information. For
Source variable class the format of the structure, see “Error Code Parameter”
INPUT; CHAR(10) on page 2-6.
The type of numeric variable passed in the source vari-
able parameter. The types are: Error Messages
*BINARY CPF27AB E
*PACKED Source variable class not valid.
*ZONED CPF27AF E
Edit mask not valid.
CPF27B4 E Source variable precision not valid.

33-4 AS/400 System API Reference V4R4

 Edit (QECEDT) API

CPF27B7 E Receiver variable length not valid. CPF3CF1 E

CPF27B8 E Edit mask length not valid. Error code parameter not valid.
CPF3C90 E
Literal value cannot be changed.

Chapter 33. Edit Function APIs 33-5

Edit (QECEDT) API

33-6 AS/400 System API Reference V4R4

 File

Part 11. File APIs

Chapter 34. File APIs . . . . . . . . . . . . . . . . 34-1 Authorities and Locks . . . . . . . . . . . . . . . 34-12

File APIs—Introduction . . . . . . . . . . . . . . . . 34-1 Required Parameter Group . . . . . . . . . . . . 34-12
File Exit Program—Introduction . . . . . . . . . . . 34-2 Usage Notes . . . . . . . . . . . . . . . . . . . . 34-13
| Block EDRS Access (QxdaBlockEDRS) API . . . . . 34-2 Error Messages . . . . . . . . . . . . . . . . . . 34-13
| Authorities and Locks . . . . . . . . . . . . . . . 34-2 End SQL Database Monitor (QQQESDBM) API . . . 34-13
| Required Parameter Group . . . . . . . . . . . . 34-2 Authorities and Locks . . . . . . . . . . . . . . . 34-13
| BLKI0100 Format . . . . . . . . . . . . . . . . . 34-2 Required Parameter Group . . . . . . . . . . . . 34-13
| Field Descriptions . . . . . . . . . . . . . . . . . 34-3 Error Messages . . . . . . . . . . . . . . . . . . 34-13
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-3 | Find EDRS Job (QxdaFindEDRSJob) API . . . . . . 34-13
| Error Messages . . . . . . . . . . . . . . . . . . 34-3 | Authorities and Locks . . . . . . . . . . . . . . . 34-14
| Call Program (QxdaCallProgramEDRS) API . . . . . 34-3 | Required Parameter Group . . . . . . . . . . . . 34-14
| Authorities and Locks . . . . . . . . . . . . . . . 34-4 | QJBI0100 Format . . . . . . . . . . . . . . . . . 34-14
| Required Parameter Group . . . . . . . . . . . . 34-4 | Field Descriptions . . . . . . . . . . . . . . . . . 34-14
| Qxda_ParmInfo_t Format . . . . . . . . . . . . . 34-4 | Usage Notes . . . . . . . . . . . . . . . . . . . . 34-15
| Field Descriptions . . . . . . . . . . . . . . . . . 34-4 | Error Messages . . . . . . . . . . . . . . . . . . 34-15
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-4 List Database File Members (QUSLMBR) API . . . . 34-15
| Error Messages . . . . . . . . . . . . . . . . . . 34-4 Authorities and Locks . . . . . . . . . . . . . . . 34-15
| Check EDRS Block Status (QxdaCheckEDRSBlock) Required Parameter Group . . . . . . . . . . . . 34-15
| API . . . . . . . . . . . . . . . . . . . . . . . . . 34-4 Optional Parameter . . . . . . . . . . . . . . . . 34-16
| Authorities and Locks . . . . . . . . . . . . . . . 34-5 Format of the Generated Lists . . . . . . . . . . 34-16
| Required Parameter Group . . . . . . . . . . . . 34-5 Input Parameter Section . . . . . . . . . . . . 34-16
| BLKO0100 Format . . . . . . . . . . . . . . . . . 34-5 Header Section . . . . . . . . . . . . . . . . . 34-16
| Field Descriptions . . . . . . . . . . . . . . . . . 34-5 MBRL0100 List Data Section . . . . . . . . . 34-16
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-5 MBRL0200 List Data Section . . . . . . . . . 34-16
| Error Messages . . . . . . . . . . . . . . . . . . 34-5 MBRL0300 List Data Section . . . . . . . . . 34-17
Clear SQL Database Monitor Statistics (QQQCSDBM) Field Descriptions . . . . . . . . . . . . . . . 34-17
API . . . . . . . . . . . . . . . . . . . . . . . . . 34-6 | Usage Notes . . . . . . . . . . . . . . . . . . . . 34-18
Authorities and Locks . . . . . . . . . . . . . . . 34-6 Error Messages . . . . . . . . . . . . . . . . . . 34-18
Required Parameter Group . . . . . . . . . . . . 34-6 List Database Relations (QDBLDBR) API . . . . . . 34-18
Error Messages . . . . . . . . . . . . . . . . . . 34-6 Authorities and Locks . . . . . . . . . . . . . . . 34-18
| Commit EDRS Server (QxdaCommitEDRS) API . . . 34-6 Required Parameter Group . . . . . . . . . . . . 34-18
| Authorities and Locks . . . . . . . . . . . . . . . 34-7 Format of the Generated List . . . . . . . . . . . 34-19
| Required Parameter Group . . . . . . . . . . . . 34-7 Input Parameter Section . . . . . . . . . . . . 34-19
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-7 DBRL0100 Format (File) . . . . . . . . . . . . 34-19
| Error Messages . . . . . . . . . . . . . . . . . . 34-7 DBRL0200 Format (Member) . . . . . . . . . 34-20
| Connect to EDRS Server (QxdaConnectEDRS) API . 34-7 DBRL0300 Format (Record Format) . . . . . . 34-20
| Authorities and Locks . . . . . . . . . . . . . . . 34-7 Field Descriptions . . . . . . . . . . . . . . . 34-20
| Required Parameter Group . . . . . . . . . . . . 34-7 Error Messages . . . . . . . . . . . . . . . . . . 34-21
| CDBI0100 Format . . . . . . . . . . . . . . . . . 34-8 List Fields (QUSLFLD) API . . . . . . . . . . . . . . 34-21
| CDBO0100 Format . . . . . . . . . . . . . . . . 34-8 Authorities and Locks . . . . . . . . . . . . . . . 34-21
| Field Descriptions . . . . . . . . . . . . . . . . . 34-8 Required Parameter Group . . . . . . . . . . . . 34-21
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-9 Optional Parameter . . . . . . . . . . . . . . . . 34-22
| Error Messages . . . . . . . . . . . . . . . . . . 34-9 Format of the Generated List . . . . . . . . . . . 34-22
Create Database Hash (QCreateDatabaseHash) API 34-10 Input Parameter Section . . . . . . . . . . . . 34-22
Authorities and Locks . . . . . . . . . . . . . . . 34-10 Header Section . . . . . . . . . . . . . . . . . 34-22
Required Parameter Group . . . . . . . . . . . . 34-10 FLDL0100 List Data Section . . . . . . . . . . 34-22
Field Descriptions . . . . . . . . . . . . . . . . . 34-10 | FLDL0200 List Data Section . . . . . . . . . . 34-23
Returned Value . . . . . . . . . . . . . . . . . . 34-10 Field Descriptions . . . . . . . . . . . . . . . 34-23
Error Messages . . . . . . . . . . . . . . . . . . 34-11 Error Messages . . . . . . . . . . . . . . . . . . 34-26
| Disconnect from EDRS Server List Record Formats (QUSLRCD) API . . . . . . . . 34-27
| (QxdaDisconnectEDRS) API . . . . . . . . . . . . 34-11 Authorities and Locks . . . . . . . . . . . . . . . 34-27
| Authorities and Locks . . . . . . . . . . . . . . . 34-11 Required Parameter Group . . . . . . . . . . . . 34-27
| Required Parameter Group . . . . . . . . . . . . 34-11 Optional Parameter . . . . . . . . . . . . . . . . 34-27
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-11 Format of the Generated List . . . . . . . . . . . 34-27
| Error Messages . . . . . . . . . . . . . . . . . . 34-11 Input Parameter Section . . . . . . . . . . . . 34-28
Dump SQL Database Monitor (QQQDSDBM) API . . 34-11 Header Section . . . . . . . . . . . . . . . . . 34-28

 Copyright IBM Corp. 1998, 1999

 File

RCDL0100 List Data Section . . . . . . . . . . 34-28 Selection Field Subquery Operand

RCDL0200 List Data Section . . . . . . . . . . 34-28 (QDBQSOPS_T) . . . . . . . . . . . . . . . 34-57
RCDL0300 List Data Section . . . . . . . . . . 34-28 Selection Constant Operand (QDBQSOPC_T) 34-58
Field Descriptions . . . . . . . . . . . . . . . 34-28 Selection Operator Item (QDBQSOPR_T) . . . 34-60
Error Messages . . . . . . . . . . . . . . . . . . 34-29 Selection Operator Item Extension
| Process Command (QxdaProcessCommandEDRS) (QDBQSOP3_T) . . . . . . . . . . . . . . . 34-61
| API . . . . . . . . . . . . . . . . . . . . . . . . . 34-29 Order by Specification (QDBQK_T) . . . . . . 34-62
| Authorities and Locks . . . . . . . . . . . . . . . 34-29 Group by Specification (QDBQG_T) . . . . . . 34-62
| Required Parameter Group . . . . . . . . . . . . 34-30 Group-by-Selection Specification (QDBQGS_T) 34-63
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-30 Set Operation Specification (QDBQT_T) . . . . 34-63
| Error Messages . . . . . . . . . . . . . . . . . . 34-30 Set Item Specifications (QDBQTIT_T) . . . . . 34-64
Process Extended Dynamic SQL (QSQPRCED) API 34-30 Relative Number of Query Definition Template
Authorities and Locks . . . . . . . . . . . . . . . 34-30 (QDBQTOPC_T) . . . . . . . . . . . . . . . 34-64
Required Parameter Group . . . . . . . . . . . . 34-30 Set Operators (QDBQTOPR_T) . . . . . . . . 34-64
SQLP0100 Format . . . . . . . . . . . . . . . . . 34-31 Query Definition Template Offset Table
SQLP0200 Format . . . . . . . . . . . . . . . . . 34-31 (QDBQQDTS_T) . . . . . . . . . . . . . . . 34-64
SQLP0300 Format . . . . . . . . . . . . . . . . . 34-32 Array of Subquery Offsets (QDBQQDT_T) . . 34-65
SQLP0400 Format . . . . . . . . . . . . . . . . . 34-32 Format Definition Template (Qdb_Qddfmt_t) . 34-65
Field Descriptions . . . . . . . . . . . . . . . . . 34-33 User File Control Block (QDBUFCB_T)
Blocked INSERT Using SQLDA Setup Structure . . . . . . . . . . . . . . . . . . . 34-66
Requirements . . . . . . . . . . . . . . . . . . 34-37 Value for Query Variable Fields (QQQVALS_T)
Usage Notes . . . . . . . . . . . . . . . . . . . . 34-37 Structure . . . . . . . . . . . . . . . . . . . 34-69
Error Messages . . . . . . . . . . . . . . . . . . 34-37 | Usage Notes . . . . . . . . . . . . . . . . . . . . 34-71
| Process Immediate SQL Statement Error Messages . . . . . . . . . . . . . . . . . . 34-71
| (QxdaProcessImmediateEDRS) API . . . . . . . . 34-37 Query SQL Database Monitor (QQQQSDBM) API . . 34-71
| Authorities and Locks . . . . . . . . . . . . . . . 34-38 Authorities and Locks . . . . . . . . . . . . . . . 34-71
| Required Parameter Group . . . . . . . . . . . . 34-38 Required Parameter Group . . . . . . . . . . . . 34-71
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-38 Error Messages . . . . . . . . . . . . . . . . . . 34-72
| Error Messages . . . . . . . . . . . . . . . . . . 34-38 Retrieve Database File Description (QDBRTVFD) API 34-72
| Process Remote Extended Dynamic SQL Authorities and Locks . . . . . . . . . . . . . . . 34-72
| (QxdaProcessExtDynEDRS) API . . . . . . . . . . 34-38 Required Parameter Group . . . . . . . . . . . . 34-72
| Authorities and Locks . . . . . . . . . . . . . . . 34-38 Format of Generated Information . . . . . . . . . 34-74
| Required Parameter Group . . . . . . . . . . . . 34-38 File Definition Header (Qdb_Qdbfh) . . . . . . 34-75
| EXDO0100 Format . . . . . . . . . . . . . . . . 34-39 Physical File Specific Attributes
| Field Descriptions . . . . . . . . . . . . . . . . . 34-40 (Qdb_Qdbfphys) . . . . . . . . . . . . . . . 34-81
| Usage Notes . . . . . . . . . . . . . . . . . . . . 34-40 Trigger Description Area (Qdb_Qdbftrg) . . . . 34-82
| Error Messages . . . . . . . . . . . . . . . . . . 34-40 Constraint Definition Header
Query (QQQQRY) API . . . . . . . . . . . . . . . . 34-40 (Qdb_Qdbf_Constraint) . . . . . . . . . . . . 34-82
Authorities and Locks . . . . . . . . . . . . . . . 34-40 Constraint Definition Entries . . . . . . . . . . 34-83
Required Parameter Group . . . . . . . . . . . . 34-41 Constraint Keys (Qdb_Qdbf_Keyn) . . . . . . 34-83
Data Structures . . . . . . . . . . . . . . . . . . 34-41 Key Name Array (Qdb_Qdbf_Narray) . . . . . 34-83
Query Definition Template (QDBQH_T) . . . . 34-41 Referential Constraint Definition
Query Definition Header (QDBQH_T) . . . . . 34-42 (Qdb_Qdbf_Riafk_Afkd) . . . . . . . . . . . 34-84
Sequence, Tables, Names, and Parameters Check Constraint (Qdb_Qdbf_Chk_Cst) . . . . 34-84
(QQQNLSS_T) . . . . . . . . . . . . . . . . 34-50 | Datalink Header (Qdb_Qdbfdtalnk) . . . . . . 34-84
File Name Specification (QDBQF_T) . . . . . 34-51 | Datalink Column Entry (Qdb_Qdbfdlcole) . . . 34-85
File, Library, Member, and Format Array Record ID Codes (Qdb_Qdbfdrtb) . . . . . . . 34-85
(QDBQN_T) . . . . . . . . . . . . . . . . . . 34-52 Record ID Codes Array (Qdb_Qdbfdrae) . . . 34-85
Record Format Specification (QDBQR_T) . . . 34-53 Logical File Specific Attributes (Qdb_Qdbflogl) 34-86
Join Specification (QDBQJ_T) . . . . . . . . . 34-54 SQL View Area (Qdb_Qdbfv) . . . . . . . . . 34-87
Join Specification Array (QDBQJFLD_T) . . . 34-54 Join Specifications (Qdb_Qdbfj) . . . . . . . . 34-87
JREF Join Specification (QDBQ_JREF_T) . . 34-55 Join Specification Array (Qdb_Qdbfjfld) . . . . 34-88
JREF Join Entry (QDBQ_JREF_ENTRY_T) . . 34-55 Join Duplicate Sequence Specification Array
JREF Join Operand (Qdb_Qdbfjdup) . . . . . . . . . . . . . . . . 34-88
(QDBQ_JREF_OPERAND_T) . . . . . . . . 34-56 Alternative Collating Sequence Table
JREF Join Operator (Qdb_Qdbfacs) . . . . . . . . . . . . . . . . 34-89
(QDBQ_JREF_OPERATOR_T) . . . . . . . 34-56 IDDU/SQL Data Dictionary Area (Qdb_Qdbfdic) 34-89
Record Selection Specification (QDBQS_T) . . 34-56 SQL Long/Alias File Name Area
Selection Item Specifications (QDBQSIT_T) . . 34-56 (Qdb_Qdbflngn) . . . . . . . . . . . . . . . . 34-90
Selection Field Operand (QDBQSOPF_T) . . . 34-57 File Scope Array (Qdb_Qdbfb) . . . . . . . . . 34-90

AS/400 System API Reference V4R4

 File

Select/Omit Specification Array (Qdb_Qdbfss) . 34-91 Display-Record-Level Device-Dependent

Select/Omit Parameters (Qdb_Qdbfsp) . . . . 34-92 Section (QDFFRDPD) . . . . . . . . . . . 34-125
Key Specification Array (Qdb_Qdbfk) . . . . . 34-93 Display-Record-Level Device-Dependent
Distributed File Definition Section and Partition Section Extension Structure (QDFFXRDP) . 34-128
Key Array (Qdb_Qdbf_dis_pkeyarr) . . . . . 34-93 Subfile Control Record (QDFFSFCR) . . . . 34-129
Journal Information (Qdb_Qdbfjoal) . . . . . . 34-94 Subfile Control Entry (QDFFSFHR) . . . . . 34-130
Format Definition Header (Qdb_Qddfmt) . . . 34-95 Subfile Control Record Extension
Field Header (Qdb_Qddffld) . . . . . . . . . . 34-97 (QDFFSFCREXT) . . . . . . . . . . . . . . 34-131
Reference Information (Qdb_Qddfrefi) . . . . 34-102 Row-Column Table (QDFFRCTB) . . . . . . 34-131
Field Prompted Numeric Editing Information Row-Column Table Entry (QDFFRCTE) . . . 34-132
(Qdb_Qddfdfne) . . . . . . . . . . . . . . . 34-102 Field Name Table (QDFFNTB) . . . . . . . . 34-132
Edit Code/Edit Word Information Field Order Table (QDFFOT) . . . . . . . . 34-132
(Qdb_Qddfedcw) . . . . . . . . . . . . . . 34-104 Field Indexing Table (QDFFFITB) . . . . . . 34-132
Validity Checking Information (Qdb_Qddfvchk) 34-104 Field Formats . . . . . . . . . . . . . . . . . . 34-133
Validity Checking Entry (Qdb_Qddfvcst) . . . 34-104 Field Header Section (QDFFFINF) . . . . . . 34-133
Validity Checking Parameter (Qdb_Qddfvcpr) 34-105 Constant Field Header Table (QDFFFCON) . 34-134
| Complex Object Field Type Information Named Field Header Table (QDFFFNAM) . . 34-134
| (Qdb_Qddfcpli) . . . . . . . . . . . . . . . 34-105 Display-Field-Level Device-Dependent Section
Field Text (Qdb_Qddfftxt) . . . . . . . . . . 34-106 (QDFFFDPD) . . . . . . . . . . . . . . . . 34-135
Alias Name Structure (Qdb_Qddfalis) . . . . 34-106 Input-Capable Display Field-Level
Default Value Description Information Device-Dependent Section (QDFFFDIC) . . 34-135
(Qdb_Qddfdft) . . . . . . . . . . . . . . . . 34-106 Field-Dependent Extension Structure
Derived Field Description Information . . . . 34-106 (QDFFXFDP) . . . . . . . . . . . . . . . . 34-136
Derived Field Header (Qdb_Qddfderv) . . . . 34-107 Selection Table (QDFFSELT) . . . . . . . . 34-137
Derived Field Entry (Qdb_Qddfdvst) . . . . . 34-107 Selection Table Entry (QDFFSTBL) . . . . . 34-137
Field Operand Entry (Qdb_Qddfdvof) . . . . 34-107 Keyword Category Displacement String
Constant Operand Entry (Qdb_Qddfdvoc) . . 34-107 (QDFFCOSA) . . . . . . . . . . . . . . . . 34-138
Operator Entry (Qdb_Qddfdvo) . . . . . . . 34-108 Keyword Category Displacement String Entry
Derived Field Text Information (Qdb_Qddfdvtx) 34-112 (QDFFCCOA) . . . . . . . . . . . . . . . . 34-138
Column Heading Information (Qdb_Qddfcolh) 34-112 Keyword Formats . . . . . . . . . . . . . . . . 34-138
IDDU/SQL Dictionary Format Information Category 1 (File-Level Keywords) . . . . . . 34-138
(Qdb_Qddfdic) . . . . . . . . . . . . . . . 34-112 File-Level Keywords (QDFKFILK) . . . . . . 34-139
IDDU/SQL Dictionary Field Information File-Level Keyword with Parameters
(Qdb_Qddfdicf) . . . . . . . . . . . . . . . 34-113 (QDFKFLPM) . . . . . . . . . . . . . . . . 34-139
Translate Table Specification (Qdb_Qddfxl) . 34-113 Category 1 Parameter Entry (QDFKFLPP) . 34-139
Case Selection Specification (Qdb_Qddfcsl) . 34-113 MSGLOC Keyword Structure (QDFKFLSZ) . 34-139
| Function Name Specification IGCCNV Keyword Structure (QDFKICVP) . . 34-140
| (Qdb_Qddfunc_def) . . . . . . . . . . . . . 34-113 HLPRCD Keyword Structure (QDFKHARD) . 34-140
Key Information Header (Qdb_Qdbwh) . . . 34-116 HLPPNLGRP Keyword Structure (QDFKHXPS) 34-140
Record Format Key Information Array HLPDOC Keyword Structure (QDFKHDOC) . 34-140
(Qdb_Qdbwhrec) . . . . . . . . . . . . . . 34-116 HLPSCHIDX Keyword Structure (QDFKSIDX) 34-141
Key Field Description Array (Qdb_Qdbwhkey) 34-116 ALTNAME Keyword Structure (QDFKFALX) . 34-141
| Usage Notes . . . . . . . . . . . . . . . . . . . 34-117 ALTNAME Keyword Entry (QDFKFALK) . . . 34-141
Error Messages . . . . . . . . . . . . . . . . . 34-117 ERRSFL Keyword Structure (QDFKESFL) . 34-141
Retrieve Display File Description (QDFRTVFD) API 34-117 WDWBORDER Keyword Structure
Authorities and Locks . . . . . . . . . . . . . . 34-118 (QDFKBODR) . . . . . . . . . . . . . . . . 34-141
Required Parameter Group . . . . . . . . . . . 34-118 Category 2 (Record-Level Command Key
Format DSPF0100 . . . . . . . . . . . . . . . . 34-118 Keywords) . . . . . . . . . . . . . . . . . . 34-142
Base File Formats . . . . . . . . . . . . . . . . 34-119 Command Key Keyword Structure
Base File Section (QDFFBASE) . . . . . . . 34-119 (QDFKCKKW) . . . . . . . . . . . . . . . 34-142
Screen Size Table (QDFFSCRA) . . . . . . 34-120 Command Key Keyword Entries (QDFKCKKE) 34-142
Sort Sequence Table (QDFFSSEQ) . . . . . 34-120 Category 3 (OVERLAY-Related Keywords and
File Formats . . . . . . . . . . . . . . . . . . . 34-120 PUTRETAIN) . . . . . . . . . . . . . . . . 34-143
File Header Section (QDFFINFO) . . . . . . 34-121 OVERLAY Keyword Structure (QDFKOVRR) 34-143
Display-File-Level Device-Dependent Section Keyword Structure (QDFKOVRE) . . . . . . 34-143
(QDFFDPDD) . . . . . . . . . . . . . . . . 34-121 OVERLAY and PUTRETAIN-Related Keyword
Record Format Table (QDFARFTE) . . . . . 34-123 Structure (QDFKOVRP) . . . . . . . . . . 34-144
Sequence Number Table (QDFFSEQT) . . . 34-123 ERASE Keyword Structure (QDFKOLER) . . 34-144
Record Formats . . . . . . . . . . . . . . . . . 34-124 CLRL Keyword Structure (QDFKOLCL) . . . 34-144
Record Header Section (QDFFRINF) . . . . 34-124

Part 11. File APIs

File

Category 4 (Record-Level Miscellaneous Screen Attribute Keyword Structure

Keywords) . . . . . . . . . . . . . . . . . . 34-144 (QDFKSASA) . . . . . . . . . . . . . . . . 34-158
Miscellaneous Record-Level Keywords Screen Attribute Keyword Array (QDFKSAPM) 34-158
(QDFKMSRL) . . . . . . . . . . . . . . . . 34-145 Category 21 Keywords . . . . . . . . . . . . 34-158
Parameter Structure (QDFKMSAP) . . . . . 34-145 FFW and FCW Keyword Structure
Response Indicator Keyword Array (QDFKFFWR) . . . . . . . . . . . . . . . . 34-159
(QDFKMSCP) . . . . . . . . . . . . . . . . 34-145 FFW Keyword Structure (QDFKCHKP) . . . 34-159
CSRLOC Keyword Structure (QDFKMSK1) . 34-145 Category 22 (Miscellaneous Field-Level
INDARA Keyword Structure (QDFKMSK2) . 34-146 Keywords) . . . . . . . . . . . . . . . . . . 34-159
DSPMOD Keyword Structure (QDFKMSK3) . 34-146 Miscellaneous Field-Level Keyword Structure
RTNCSRLOC and RTNCSRLOC2 Keyword (QDFKMFDK) . . . . . . . . . . . . . . . . 34-159
Structure (QDFKMSCLN) . . . . . . . . . . 34-146 Field-Level Keyword Structure (QDFKMFDP) 34-160
MNUBARDSP Keyword Structure Response Indicator Structure (QDFKMFRS) 34-160
(QDFKMSMBDSP) . . . . . . . . . . . . . 34-147 ERRMSG and ERRMSGID Keyword Structure
Category 0B Keywords (File-Level Keywords (QDFKMFEM) . . . . . . . . . . . . . . . . 34-160
with Parameters) . . . . . . . . . . . . . . 34-147 ERRMSGID Keyword Structure (QDFKMFSI) 34-160
File-Level Keywords with Parameters Structure MSGID Keyword Common Structure
(QDFK0BPR) . . . . . . . . . . . . . . . . 34-147 (QDFKMFMV) . . . . . . . . . . . . . . . . 34-161
File-Level Keyword Structure (QDFK0BXWP) 34-148 Type Three MSGID Keyword Structure
GRDATR Parameter Structure (QDFKMFM3) . . . . . . . . . . . . . . . . 34-161
(QDFK0BGATR) . . . . . . . . . . . . . . 34-148 Type Four MSGID Keyword Structure
HLPSHELF Parameter Structure (QDFKMFM4) . . . . . . . . . . . . . . . . 34-162
(QDFKHBKPRM) . . . . . . . . . . . . . . 34-148 DSPATR Keyword Structure (QDFKDFLD) . 34-162
Category 17 (Record-Level Miscellaneous DATTIMFMT Keyword Structure
Keywords with Parameters) . . . . . . . . 34-148 (QDFK_DATTIM_Format) . . . . . . . . . . 34-162
Miscellaneous Record-Level Structure DATTIMSEP Keyword Structure
(QDFKMRPR) . . . . . . . . . . . . . . . . 34-149 (QDFK_DATTIM_Separator) . . . . . . . . 34-162
Miscellaneous Record-Level Keywords DATE Keyword Structure (QDFK_DATEP) . 34-162
(QDFKMRWP) . . . . . . . . . . . . . . . 34-149 MAPVAL Keyword Structure (QDFK_MAPVAL) 34-163
HLP Keyword Structure (QDFKHSTR) . . . . 34-149 Category 23 (DFT Keyword) . . . . . . . . . 34-163
HLP Keyword Entry Structure (QDFKHPRM) 34-149 Category 23 Keyword Structure (QDFKDFT) 34-163
HLPRCD Keyword Structure (QDFKHNMS) . 34-150 Category 23 Keyword Parameters
HLPPNLGRP Keyword Structure (QDFKHPS) 34-150 (QDFKDFPM) . . . . . . . . . . . . . . . . 34-163
HLPDOC Keyword Structure (QDFKHRDC) . 34-151 MSGCON Keyword Structure (QDFKDFMM) 34-164
HLPARA Keyword Structure (QDFKHARA) . 34-151 HTML Keyword Structure (QDFKDFHTML) . 34-164
HLPARA Keyword Enhanced Display Structure Category 24 (Field-Level Editing and Time
(QDFKHARX) . . . . . . . . . . . . . . . . 34-151 Keywords) . . . . . . . . . . . . . . . . . . 34-164
HLPSEQ Keyword Structure (QDFKHSEQ) . 34-152 EDIT Keyword Structure (QDFKEDTR) . . . 34-164
PRINT Keyword Structure (QDFKPRTR) . . 34-152 EDIT Keyword Structure (QDFKEDTP) . . . 34-164
Record-Level Print Parameters (QDFKPPRM) 34-152 Category 25 (GET Validation Keywords) . . 34-165
WDWBORDER Keyword Structure Validity Checking Keyword Structure
(QDFKBRDR) . . . . . . . . . . . . . . . . 34-152 (QDFKVAKW) . . . . . . . . . . . . . . . . 34-165
Window Data Array Structure (QDFKWDTA) 34-153 Validity Checking Keywords (QDFKVARL) . 34-165
Window Title Structure (QDFKWDWTTL) . . 34-154 CHKMSGID Keyword Structure (QDFKCKMI) 34-166
Mouse Button Structure (QDFKMB) . . . . . 34-155 Category 26 (Field-Level Keywords for CUA
Category 18 (SFL Control Keywords) . . . . 34-156 Constructs) . . . . . . . . . . . . . . . . . 34-166
SFL Keyword Structure (QDFKSCSF) . . . . 34-156 Field-Level CUA Keyword Structure
SFL Keyword Entry (QDFKSCCP) . . . . . . 34-156 (QDFKFCPR) . . . . . . . . . . . . . . . . 34-166
SFLMSG and SFLMSGID Keyword Structure Field-Level CUA Keywords (QDFKFC) . . . 34-167
(QDFKSCSM) . . . . . . . . . . . . . . . . 34-156 CHCFLD Keyword Structure (QDFKCHC) . . 34-167
SFLMSGID Keyword Structure (QDFKSCSI) 34-157 CHCFLD Keyword Header Expansion
SFLEND(*MORE) Keyword Structure Structure (QDFKCHCHDREXP) . . . . . . 34-167
(QDFKSFLM) . . . . . . . . . . . . . . . . 34-157 Choice Entry Structure (QDFKCHCE) . . . . 34-168
SFLEND(*SCRBAR) Keyword Structure Choice Text Structure (QDFKCTXT) . . . . . 34-169
(QDFKSFLS) . . . . . . . . . . . . . . . . 34-157 CHCACCEL Keyword Structure (QDFKCACC) 34-169
SFLCSRRRN Keyword Structure CHCCTL Keyword Structure (QDFKCMSG) . 34-170
(QDFKCSRRRN) . . . . . . . . . . . . . . 34-157 MNUBARSEP Keyword Structure
SFLMODE Keyword Structure (QDFKMODE) 34-158 (QDFKMBSEPS) . . . . . . . . . . . . . . 34-170
Category 20 (Screen-Attribute-Related Choice Keywords Structure (QDFKCHCX) . 34-171
Keywords) . . . . . . . . . . . . . . . . . . 34-158

AS/400 System API Reference V4R4

 File

ENTFLDATR Keyword Structure Error Messages . . . . . . . . . . . . . . . . . 34-193

(QDFKEFATR) . . . . . . . . . . . . . . . 34-171 Retrieve Short Name (QDBRTVSN) API . . . . . . 34-193
FLDCSRPRG Keyword Structure Authorities and Locks . . . . . . . . . . . . . . 34-193
(QDFKFLDCP) . . . . . . . . . . . . . . . 34-172 Required Parameter Group . . . . . . . . . . . 34-193
CNTFLD Keyword Structure (QDFKCNTFLD) 34-172 Error Messages . . . . . . . . . . . . . . . . . 34-194
EDTMSK Keyword Structure (QDFKEDTMSK) 34-172 | Roll Back EDRS Server (QxdaRollbackEDRS) API 34-194
EDTMSK Keyword Segment Structure | Authorities and Locks . . . . . . . . . . . . . . 34-194
(QDFKEDTSEG) . . . . . . . . . . . . . . 34-172 | Required Parameter Group . . . . . . . . . . . 34-194
SFLCHCCTL Message Structure | Usage Notes . . . . . . . . . . . . . . . . . . . 34-194
(QDFKSMSG) . . . . . . . . . . . . . . . . 34-173 | Error Messages . . . . . . . . . . . . . . . . . 34-194
Category 27 Keywords (Record-Level Grid Run Database Hash (QDBRUNHA) API . . . . . . 34-195
Keywords with Parameters) . . . . . . . . 34-173 Authorities and Locks . . . . . . . . . . . . . . 34-195
Record-Level Grid Keywords with Parameters Required Parameter Group . . . . . . . . . . . 34-195
Structure (QDFKGRPR) . . . . . . . . . . 34-173 Field Descriptions . . . . . . . . . . . . . . . . 34-195
Record-Level Grid Keywords (QDFKGRWP) 34-173 Error Messages . . . . . . . . . . . . . . . . . 34-195
GRDATR Parameters (QDFKGRDATR) . . . 34-174 Start SQL Database Monitor (QQQSSDBM) API . 34-195
GRDCLR Parameters Structure Authorities and Locks . . . . . . . . . . . . . . 34-196
(QDFKGRDCLR) . . . . . . . . . . . . . . 34-174 Required Parameter Group . . . . . . . . . . . 34-196
GRDBOX Parameters (QDFKGRDBOX) . . . 34-175 Usage Notes . . . . . . . . . . . . . . . . . . . 34-197
GRDBOX Parameter Entry Structure Error Messages . . . . . . . . . . . . . . . . . 34-197
(QDFKGBOXDFM) . . . . . . . . . . . . . 34-176 Syntax Check SQL Statement (QSQCHKS) API . . 34-197
GRDLIN Parameters Structure Authorities and Locks . . . . . . . . . . . . . . 34-197
(QDFKGRDLIN) . . . . . . . . . . . . . . . 34-176 Required Parameters . . . . . . . . . . . . . . 34-197
GRDLIN Parameter Entry Structure Format for Options . . . . . . . . . . . . . . . 34-198
(QDFKGLINDFM) . . . . . . . . . . . . . . 34-177 Field Descriptions . . . . . . . . . . . . . . . . 34-198
Where-Used Formats . . . . . . . . . . . . . . 34-178 Keys . . . . . . . . . . . . . . . . . . . . . . . 34-198
Where-Used File-Level Information Structure Field Descriptions . . . . . . . . . . . . . . . . 34-199
(QDFWFLEI) . . . . . . . . . . . . . . . . 34-178 Statement Information . . . . . . . . . . . . . . 34-199
Where-Used Record Information Structure Field Descriptions . . . . . . . . . . . . . . . . 34-200
(QDFWRCDI) . . . . . . . . . . . . . . . . 34-178 Error Messages . . . . . . . . . . . . . . . . . 34-200
Where-Used Field Information Structure SQL Client Integration Exit Program . . . . . . . . 34-201
(QDFWFLDI) . . . . . . . . . . . . . . . . 34-179 Restrictions . . . . . . . . . . . . . . . . . . . 34-201
Indicator Table Entry Structure (QDFWITBE) 34-179 Required Parameter Group . . . . . . . . . . . 34-201
Keyword Area Structure (QDFWKWDA) . . . 34-180 Input Format Structures . . . . . . . . . . . . . 34-206
Keyword Entry Structure (QDFWATTR) . . . 34-180 Format ARCN0100 (Connect Format) . . . . 34-206
Variable Length Structure (QDFWATYP) . . 34-181 Field Descriptions for Format ARCN0100 . . 34-206
Multiple Variable Length Structure Format ARDI0100 (Disconnect Format) . . . 34-207
(QDFWBTYP) . . . . . . . . . . . . . . . . 34-181 Field Descriptions for Format ARDI0100 . . . 34-207
Reference Information Structure (QDFWRSTR) 34-181 Format ARBB0100 (Begin Package Bind
Name Table Structure (QDFFNTBL) . . . . . 34-182 Format) . . . . . . . . . . . . . . . . . . . 34-207
Error Messages . . . . . . . . . . . . . . . . . 34-182 Field Descriptions for Format ARBB0100 . . 34-208
Retrieve File Override Information (QDMRTVFO) API 34-182 Format ARBS0100 (Bind Statement for
Required Parameter Group . . . . . . . . . . . 34-182 Package Creation Format) . . . . . . . . . 34-209
OVRL0100 Format . . . . . . . . . . . . . . . 34-183 Field Descriptions for Format ARBS0100 . . 34-209
Field Descriptions . . . . . . . . . . . . . . . . 34-183 Format AREB0100 (End of Package Bind
Error Messages . . . . . . . . . . . . . . . . . 34-183 Format) . . . . . . . . . . . . . . . . . . . 34-210
Retrieve Member Description (QUSRMBRD) API . 34-183 Field Descriptions for Format AREB0100 . . 34-210
Authorities and Locks . . . . . . . . . . . . . . 34-184 Formats ARPS0100 and ARPD0100 (Prepare
Required Parameter Group . . . . . . . . . . . 34-184 Format) . . . . . . . . . . . . . . . . . . . 34-210
Optional Parameter Group 1 . . . . . . . . . . 34-184 Field Descriptions for Formats ARPS0100 and
Optional Parameter Group 2 . . . . . . . . . . 34-185 ARPD0100 . . . . . . . . . . . . . . . . . 34-211
Format of the Generated Information . . . . . . 34-185 Formats ARXD0100 and ARXB0100 (Execute
MBRD0100 Format . . . . . . . . . . . . . . 34-186 Bound Statement) . . . . . . . . . . . . . 34-212
MBRD0200 Format . . . . . . . . . . . . . . 34-186 Field Descriptions for Formats ARXD0100 and
MBRD0300 Format . . . . . . . . . . . . . . 34-186 ARXB0100 . . . . . . . . . . . . . . . . . 34-212
Record Format and Based-On File List Entry 34-187 Format ARXP0100 (Execute Prepared
Constraint Indexes Information . . . . . . . . 34-187 Statement) . . . . . . . . . . . . . . . . . 34-214
Additional MBRD0200 Format Information . . 34-188 Field Descriptions for Format ARXP0100 . . 34-214
Field Descriptions . . . . . . . . . . . . . . . . 34-188 Format ARXI0100 (Execute Immediate
| Usage Notes . . . . . . . . . . . . . . . . . . . 34-193 Statement Format) . . . . . . . . . . . . . 34-215

Part 11. File APIs

File

Field Descriptions for Format ARXI0100 . . . 34-216 Field Descriptions for Output Connect Format 34-221
Format AROC0100 (Open Cursor Format) . 34-217 Output Execute Format . . . . . . . . . . . 34-221
Field Descriptions for Format AROC0100 . . 34-217 Field Descriptions for Output Execute Format 34-221
Format ARFC0100 (Fetch from a Cursor Output Open Cursor Format . . . . . . . . . 34-222
Format) . . . . . . . . . . . . . . . . . . . 34-218 Field Descriptions for Output Open Cursor
Field Descriptions for Format ARFC0100 . . 34-218 Format . . . . . . . . . . . . . . . . . . . 34-222
Format ARCC0100 (Close a Cursor Format) 34-219 Output Fetch Cursor Format . . . . . . . . . 34-222
Field Descriptions for Format ARCC0100 . . 34-220 Field Descriptions for Output Fetch Cursor
Format ARDS0100 (Describe a Statement Format . . . . . . . . . . . . . . . . . . . 34-222
Format) . . . . . . . . . . . . . . . . . . . 34-220 Activation Group . . . . . . . . . . . . . . . . . 34-222
Field Descriptions for Format ARDS0100 . . 34-220 Consistency Token . . . . . . . . . . . . . . . 34-223
Format ARDT0100 (Describe Object Format) 34-220 Section Number . . . . . . . . . . . . . . . . . 34-223
Field Descriptions for Format ARDT0100 . . 34-221 Query (Fetch) Data Format . . . . . . . . . . . 34-223
Output Format Structures . . . . . . . . . . . . 34-221 SQLDA . . . . . . . . . . . . . . . . . . . . . 34-224
Output Connect Format . . . . . . . . . . . 34-221 Commit APIs . . . . . . . . . . . . . . . . . . . 34-226

AS/400 System API Reference V4R4

 File APIs

Chapter 34. File APIs

List Database Relations
File APIs—Introduction (QDBLDBR) provides information on how files
and members are related to a specified data-
The file APIs retrieve specific information about OS/400 files.
base file.
These APIs also have the ability to get data and manipulate
List Fields (QUSLFLD) generates a list of fields within a
files.
specified file record format name.
This chapter presents the APIs in alphabetical order, followed List Record Formats
by a description of the file exit program. (QUSLRCD) generates a list of record formats
contained within a specified file.
The file APIs include the following: | Process Command
| (QxdaProcessCommand EDRS) is used to run
| Block EDRS Access
| a system command on the database server
| (QxdaBlockEDRS) provides functions to allow
| system.
| client jobs to be temporarily suspended or
Process Extended Dynamic SQL
| switched to a backup server system in a
(QSQPRCED) processes Structured Query
| client/server environment.
Language (SQL) extended dynamic state-
| Call Program (QxdaCallProgramEDRS) is used to call a
ments in an SQL package object.
| user-defined program on the database server
| Process Immediate SQL Statement
| system.
| (QxdaProcessImmediateEDRS) is used to run
| Check EDRS Block Status
| an SQL statement on the database server.
| (QxdaCheckEDRSBlock) returns information
| Process Remote Extended Dynamic SQL
| about the availability status of a server
| (QxdaProcessExtDynEDRS) is used to
| system.
| perform extended dynamic SQL operations on
Clear SQL Database Monitor Statistics
| the database server system.
(QQQCSDBM) clears and frees the associ-
Query (QQQQRY) gets a set of database records
ated memory area of the database monitor
that satisfy a database query request.
statistics.
Query SQL Database Monitor
| Commit EDRS Server
(QQQQSDBM) returns information about the
| (QxdaCommitEDRS) is used to commit trans-
activity of the SQL and the original database
| actions on the database server.
monitor.
| Connect to EDRS Server
Retrieve Database File Description
| (QxdaConnectEDRS) is used to initiate a con-
(QDBRTVFD) provides complete and specific
| nection to a server system.
information about a file on a local or remote
Create Database Hash
system.
(QCreateDatabaseHash) sets up the environ-
Retrieve Display File Description
ment to enable the Run Database Hash
(QDFRTVFD) allows you to get specific infor-
(QDBRUNHA) API for a physical file that has
mation about the data description specifica-
a uniquely keyed logical file built over it.
tions (DDS) definition used to create a display
| Disconnect from EDRS Server
file.
| (QxdaDisconnectEDRS) is used to end a con-
Retrieve File Override Information
| nection to a server system.
(QDMRTVFO) returns the name of the file,
Dump SQL Database Monitor
library, member, and final type of override that
(QQQDSDBM) dumps the SQL database
result from processing overrides for a speci-
monitor that has been gathered.
fied file name.
End SQL Database Monitor
Retrieve Member Description
(QQQESDBM) ends the memory-based SQL
(QUSRMBRD) returns specific information
database monitor.
about a single database file member.
| Find EDRS Job
Retrieve Short Name
| (QxdaFindEDRSJob) is used to find all jobs
(QDBRTVSN) allows you to get the
| with user-defined data associated with the
10-character name of a database file by
| Connect to EDRS Server
requesting the long file name of the database
| (QxdaConnectEDRS) API that matches the
file.
| data passed to this API.
| Roll Back EDRS Server
List Database File Members
| (QxdaRollbackEDRS) is used to roll back
(QUSLMBR) generates a list of database file
| transactions on the database server.
members and places the list in a user space.

 Copyright IBM Corp. 1998, 1999 34-1

 Block EDRS Access (QxdaBlockEDRS) API

Run Database Hash (QDBRUNHA)

allows the user to FETCH, UPDATE, | Block EDRS Access (QxdaBlockEDRS) API
DELETE, and INSERT data into existing data-
base files using an alternative access method.
Start SQL Database Monitor | Required Parameter Group:
(QQQSSDBM) starts the memory-based SQL
| 1 Input structure Input Char(*)
database monitor. | 2 Input structure format Input Char(8)
Syntax Check SQL Statement | 3 Error code I/O Char(*)
(QSQCHKS) calls the DB2 for AS/400 SQL
parser to check the syntax of an SQL state- | Library Name/Service Program: QSYS/QXDADBBK
ment.
| Threadsafe: Conditional; see Usage Notes
With the exception of QDBLDBR, QDFRTVFD, and
QSQPRCED, these APIs work with files that are either local
or remote. Local files are files that are on the AS/400 | The Block EDRS Access (QxdaBlockEDRS) API provides
system where the program is running. Remote files are files | functions to allow client jobs to be temporarily suspended or
on a target (remote) system that are accessed using a dis- | switched to a backup server system in a client/server envi-
tributed data management (DDM) file on a source (local) | ronment. This API does not physically block the system; all
system. DDM files provide the information needed for a local | access must be controlled using the functions provided by
system to locate a remote system and to access data in the | the EDRS APIs.
| remote system's database files. The QDBLDBR,
| QDFRTVFD, and QSQPRCED APIs work with local database | Authorities and Locks
files only.
| The user running the API must have *JOBCTL special
When you are calling these APIs from your high-level lan- | authority.
guage (HLL) program, you must specify whether or not to
use file override processing on your local or remote files. | Required Parameter Group
However, the QDBLDBR, QSQPRCED, and QDMRTVFO
APIs do not support overrides. | Input structure
| I/O; CHAR(*)
Some of the file APIs return character values that have an
| The structure to pass information about the function to
associated CCSID (coded character set identifier). If the
| perform and the systems involved. For the format of this
CCSID value for the job calling the API is not 65535, the
| parameter, see “BLKI0100 Format.”
character values are converted from their current CCSID to
the CCSID of the job. This conversion may cause some | Input structure format
data to be lost. The CCSID associated with the job is | INPUT; CHAR(8)
returned to the user. If the CCSID value for the job is 65535,
| The format of the input structure being used. The pos-
no conversions are performed on the character values. The
| sible value is:
character value CCSID stored in the file object is returned to
the user. | BLKI0100 Basic structure

The file APIs use the standard user space format for the lists | Error code
of information they return. If you are not yet familiar with this | I/O; CHAR(*)
format, see “User Space Format for List APIs” on page 2-4 | The structure in which to return error information. For
before using these APIs. | the format of the structure, see “Error Code Parameter”
| on page 2-6.
For information about the SQL call level interface API, see
the DB2 UDB for AS/400 SQL Call Level Interface book,
SC41-5806. | BLKI0100 Format
| The following table shows the information to pass in the
File Exit Program—Introduction | BLKI0100 format. For more details about the fields in this
| table, see “Field Descriptions” on page 34-3.
A database exit program provides additional (user-written)
functions for the database. | Offset
| Dec Hex Type Field
The SQL Client Integration exit program enables SQL appli-
cations to access data managed by a database management | 0 0 CHAR(1) Function
system other than the OS/400 relational database. | 1 1 CHAR(256) EDRS server system name

The description of the exit program follows the file APIs.

34-2 AS/400 System API Reference V4R4

 Call Program (QxdaCallProgramEDRS) API

| Length of job-suspension user data. The length of job-

| Offset
| suspension user data supplied.
| Dec Hex Type Field
| 257 101 CHAR(256) Backup EDRS server | Offset to job-suspension user data. The offset from the
| system name | beginning of the input structure to the job-suspension user
| data in the input structure, in bytes. This value must be set
| 513 201 CHAR(7) Reserved
| to 0 for functions 2 and 5, and is optional for all other func-
| 520 208 BINARY(4) Offset to job-suspension | tions.
| user data
| 524 20C BINARY(4) Length of job-suspension | Reserved. This value must be initialized to blanks.
| user data
| CHAR(*) Job-suspension user data | Usage Notes
| This function may be called from the initial thread of a job
| Field Descriptions | only.

| Backup EDRS server system name. The name of the | Error Messages
| system that will take over as the server system when func-
| CPF0001 E Error found on &1 command.
| tion 2 is called. This parameter is required for function 1,
| CPF180C E
| and must be set to blanks for other functions. The following
| Function &1 not allowed.
| special value is allowed:
| CPF222E E &1 special authority is required.
| *RESET This value should be specified on function 1 | CPF3C1E E
| when switching back to the original EDRS | Required parameter &1 omitted.
| server system. | CPF3C90 E
| Literal value cannot be changed.
| EDRS server system name. The name of the database | CPF9872 E Program or service program &1 in library &2
| server system. It is required for all functions. This should | ended. Reason code &3.
| always be the original server system name, even after a | CPFAE14 E
| backup has been associated with the system. | Cannot allocate &1 bytes.
| CPFB751 E Parameter &1 passed not correct.
| Function. The function to perform. The possible values
| CPFB752 E Internal error in &1 API.
| are:
| CPFB75A E
| 1 - QXDA_BLOCK | Function &1 not valid while system &2 is
| Block access to the server system specified. | blocked.
| 2 - QXDA_SWITCH_SERVER | CPFB75B E
| Associate the backup server system passed to | Function &1 not valid while system &2 is not
| function 1 with the original server system speci- | blocked.
| fied. | CPFB75C E
| 3 - QXDA_REGISTER_JOB | System name &1 is not valid.
| Register the current job to be notified when the | CPFB75D E
| specified server system is blocked. A job is noti- | Function &1 not allowed.
| fied by a SIGUSR1 signal being delivered to the | CPFB75E E
| job. | Job not removed.
| 4 - QXDA_REMOVE_JOB
| Remove the job from the list of jobs to be noti-
| fied of a server system block. | Call Program (QxdaCallProgramEDRS) API
| 5 - QXDA_UNBLOCK
| Allow access to the server system that was pre-
| viously blocked. This function is not allowed
| Required Parameter Group:
| when *RESET was specified as the backup
| system name to function 1. | 1 Connection handle Input Binary(4)
| 2 Qualified program name Input Char(20)
| Job-suspension user data. The data to associate with a | 3 Number of parameters Input Binary(4)
| job or a system that is used to determine which jobs on the | 4 Parameter information Input Char(*)
| client system should be blocked. If no job-suspension user | 5 Error code I/O Char(*)
| data is supplied, all jobs connected to the specified server
| system will be blocked. | Library Name/Service Program: QSYS/QXDAEDRS

| Threadsafe: Conditional; see Usage Notes

Chapter 34. File APIs 34-3

 Check EDRS Block Status (QxdaCheckEDRSBlock) API

| The Call Program (QxdaCallProgramEDRS) API is used to | Field Descriptions

| call a user-defined program on the database server system.
| All parameters are passed to the program by reference.
| Parameter address. The address where an input param-
| eter exists or where an output parameter should be returned.
| Authorities and Locks
| Any program *USE | Parameter length. The number of bytes allocated for the
| Library of the program | parameter.
| *EXECUTE
| Parameter type. The type of the parameter. The possible
| values are:
| Required Parameter Group | 1 - QXDA_BIN4
| Connection handle | The parameter at the address specified is a
| INPUT; BINARY(4) | BINARY(4) value.
| 2 - QXDA_CHAR
| The handle number of the connection on which to call | The parameter at the address specified is a
| the program. The connection handle must have been | character string.
| generated by the QxdaConnectEDRS API in the current
| job and activation group. | Parameter usage. The usage of the parameter. The pos-
| sible values are:
| Qualified program name
| INPUT; CHAR(20) | 0 - QXDA_INPUT
| The parameter is used for input only.
| The library and name of the program to call. The
| 1 - QXDA_OUTPUT
| special value *LIBL may be specified for the library
| The parameter is used for output only.
| name; however, the library list of the server job may
| 2 - QXDA_IN_OUT
| differ from that of the client job.
| The parameter is used for both input and output.
| Number of parameters
| INPUT; BINARY(4) | Reserved. Reserved field; it must be initialized to 0x00.

| The number of parameters to pass to the program.

| Usage Notes
| Parameter information
| INPUT; CHAR(*) | This function may be called from the initial thread of a job
| Information about each of the parameters. This should | only.
| be an array of type Qxda_ParmInfo_t, with one entry for
| each parameter. For the format of each array element, | Error Messages
| see “Qxda_ParmInfo_t Format.”
| CPF180C E
| Error code | Function &1 not allowed.
| I/O; CHAR(*) | CPF24B4 E Severe error while addressing parameter list.
| The structure in which to return error information. For | CPF3C90 E
| the format of the structure, see “Error Code Parameter” | Literal value cannot be changed.
| on page 2-6. | CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3.
| CPFAE14 E
| Qxda_ParmInfo_t Format | Cannot allocate &1 bytes.
| CPFB750 E Connection handle specified not valid.
| The following table shows the structure of the | CPFB752 E Internal error in &1 API.
| Qxda_ParmInfo_t format. For more details about the fields in | CPFB756 E Rollback operation performed.
| this table, see “Field Descriptions.” | CPFB757 E The connection is suspended.
| CPFB758 E The EDRS server system has been switched.
| Offset
| Dec Hex Type Field
| 0 0 PTR Parameter address | Check EDRS Block Status
| 16 10 BINARY(4) Parameter type | (QxdaCheckEDRSBlock) API
| 20 14 BINARY(4) Parameter length
| 24 18 BINARY(4) Parameter usage
| 28 1C CHAR(4) Reserved

34-4 AS/400 System API Reference V4R4

 Check EDRS Block Status (QxdaCheckEDRSBlock) API

| Offset
| Required Parameter Group: | Dec Hex Type Field
| 1 Receiver variable Output Char(*) | 0 0 BINARY(4) Bytes returned
| 2 Length of receiver variable Input Binary(4)
| 4 4 BINARY(4) Bytes available
| 3 Receiver variable format Input Char(8)
| 4 EDRS server system name Input Char(256) | 8 8 BINARY(4) EDRS server status
| 5 Error code I/O Char(*) | 12 12 CHAR(256) Backup server system name

| Library Name/Service Program: QSYS/QXDADBBK | 268 10C BINARY(4) Offset to job-suspension

| user data
| Threadsafe: Conditional; see Usage Notes | 272 110 BINARY(4) Length of job-suspension
| user data

| The Check EDRS Block Status (QxdaCheckEDRSBlock) API | CHAR(*) Job-suspension user data
| returns information about the availability status of a server
| system.
| Field Descriptions
| Authorities and Locks
| Backup server system name. The name of the system
| None.
| that is acting as the backup server system. This value will
| be set to blanks if the EDRS system is not blocked or
| Required Parameter Group | switched.
| Receiver variable | Bytes available. The length of the information available to
| I/O; CHAR(*) | the API to return, in bytes.
| The structure in which to return information about the
| availability status of the system specified. For the format | Bytes returned. The actual number of bytes returned to the
| of this parameter, see “BLKO0100 Format.” | caller of the API.

| Length of receiver variable | EDRS server status. The status of the server system. The
| INPUT; BINARY(4) | possible values are:
| The number of bytes that the calling program provides | 0 QXDA_UNBLOCKED: The EDRS system is not
| for the receiver variable. | blocked.
| 1 QXDA_BLOCKED: The EDRS server system is
| Receiver variable format | blocked.
| INPUT; CHAR(8) | 2 QXDA_SWITCHED: The backup system is
| The format of the receiver variable being used. The | acting as the EDRS server.
| possible value is:
| Job-suspension user data. The data associated with the
| BLKO0100 Basic structure | block.
| EDRS server system name | Length of job-suspension user data. The length of job-
| INPUT; CHAR(256) | suspension user data returned.
| The name of the database server system to check.
| Offset to job-suspension user data. The offset from the
| Error code | beginning of the receiver variable to the the job-suspension
| I/O; CHAR(*) | user data, in bytes.
| The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter” | Usage Notes
| on page 2-6.
| This function may be called from the initial thread of a job
| only.
| BLKO0100 Format
| The following table shows the information to pass in the | Error Messages
| BLKO0100 format. For more details about the fields in this
| CPF0001 E Error found on &1 command.
| table, see “Field Descriptions.”
| CPF3C1E E
| Required parameter &1 omitted.
| CPF3C90 E
| Literal value cannot be changed.

Chapter 34. File APIs 34-5

 Commit EDRS Server (QxdaCommitEDRS) API

| CPF9872 E Program or service program &1 in library &2 *RESET Clear and free all memory associated with
| ended. Reason code &3. all active or inactive database monitors.
| CPFB751 E Parameter &1 passed not correct. The *RESET option cannot be specified
| CPFB752 E Internal error in &1 API. on a specific job or memory handle.

Job or memory handle name

INPUT; CHAR(26)
Clear SQL Database Monitor Statistics
(QQQCSDBM) API This parameter depends on the value specified for the
memory area to clear parameter. If the value is:

*ALL This parameter must be set to blanks.

Required Parameter Group: *RESET This parameter must be set to blanks.
*NAMED The CHAR(10) name of a memory handle
1 Memory handle to clear Input Char(10)
whose data is to be cleared. Only the
2 Job or memory handle Input Char(26)
name
first 6 characters will be used for naming
3 Error code I/O Char(*) the memory handle, with the remaining
characters set to blanks.
Threadsafe: Yes *JOB The CHAR(26) qualified job name of a
job-specific monitor to dump. The quali-
fied job name has three parts:
The Clear SQL Database Monitor Statistics (QQQCSDBM) Job Name
API clears and frees the associated memory area of the CHAR(10). A specific job name, a
database monitor statistics. Associated APIs include the fol- generic name, or one of the fol-
lowing: lowing special values:
Ÿ Dump SQL Database Monitor (QQQDSDBM) * or *CURRENT
Only the job that this program
Ÿ End SQL Database Monitor (QQQESDBM)
is running in. The rest of the
Ÿ Query SQL Database Monitor (QQQQSDBM) qualified job name parameter
Ÿ Start SQL Database Monitor (QQQSSDBM) must be blank.
*ALL
All jobs. The rest of the job
Authorities and Locks name parameter must be
Current User Profile blank.
*JOBCTL User Name
CHAR(10). A specific user profile
name.
Required Parameter Group Job Number
CHAR(6). A specific job number.
Memory area to clear
INPUT; CHAR(10) Error code
The memory area to be cleared or freed. The possible I/O; CHAR(*)
values are: The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
*ALL Clear the monitor data associated with
on page 2-6.
the *ALL monitor (the monitor started
against ALL jobs). Memory areas associ-
ated with QQQSSDBM started on indi- Error Messages
vidual jobs will not be cleared. No
CPD0172 D
storage is freed.
Parameters passed on CALL do not match
*NAMED Clear the memory handle specified by the
those required.
job or memory handle name parameter
CPF222E E &1 special authority is required.
(and matches the name of a memory
CPF3CF1 E
handle specified on the QQQSSDBM
Error code parameter not valid.
API). No storage is freed. Only the first
6 characters will be used for naming the
memory handle.
*JOB Clear the job specific data associated with | Commit EDRS Server (QxdaCommitEDRS)
the job name specified in the job or | API
memory handle name parameter. No
storage is freed.

34-6 AS/400 System API Reference V4R4

 Connect to EDRS Server (QxdaConnectEDRS) API

| Error Messages
| Required Parameter Group: | CPF180C E
| 1 Connection handle Input Binary(4)
| Function &1 not allowed.
| 2 Additional commit options Input Binary(4) | CPF24B4 E Severe error while addressing parameter list.
| 3 SQL communications area Output Char(136) | CPF3C90 E
| 4 Error code I/O Char(*) | Literal value cannot be changed.
| CPF9872 E Program or service program &1 in library &2
| Library Name/Service Program: QSYS/QXDAEDRS | ended. Reason code &3.
| CPFB750 E Connection handle specified not valid.
| Threadsafe: Conditional; see Usage Notes | CPFB752 E Internal error in &1 API.
| CPFB757 E The connection is suspended.
| The Commit EDRS Server (QxdaCommitEDRS) API is used | CPFB758 E The EDRS server system has been switched.
| to commit transactions on the database server.

| Connect to EDRS Server

| Authorities and Locks
| (QxdaConnectEDRS) API
| None.

| Required Parameter Group | Required Parameter Group:

| Connection handle | 1 Input structure Input Char(*)

| INPUT; BINARY(4) | 2 Input structure format Input Char(8)
| 3 Receiver variable Output Char(*)
| The handle number of the connection on which to | 4 Length of receiver variable Input Binary(4)
| perform the commit operation. The connection handle | 5 Receiver variable format Input Char(8)
| must have been generated by the QxdaConnectEDRS | 6 Error code I/O Char(*)
| API in the current job and activation group.
| Library Name/Service Program: QSYS/QXDAEDRS
| Additional commit options
| INPUT; BINARY(4) | Threadsafe: Conditional; see Usage Notes
| The following are valid commit options, defined in the
| qxdaedrs.h header file: | The Connect to EDRS Server (QxdaConnectEDRS) API is
| 0 QXDA_COMMIT_WORK | used to initiate a connection to a server system. For non-
| 1 QXDA_COMMIT_WITH_HOLD | local connections, a corresponding "shadow" job is started on
| the server system. That shadow job is swapped to run under
| SQL communications area | the same user profile, using the same job description, coded
| OUTPUT; CHAR(136) | character set identifier (CCSID), and job priority as the client
| Returns diagnostic information. It includes the | system job. The user profile, user password, and job
| SQLCODE variable, indicating whether an error has | description for the user must be identical on both systems.
| occurred. If SQLCODE has a value of 0 after a call to
| For TCP/IP or UNIX domain sockets connections, a controller
| this API, the function was successful.
| job must be started on the server system before calling the
| The format of this structure is standard and is described | QxdaConnectEDRS API on the client system. The controller
| more completely in the DB2 UDB for AS/400 SQL Pro- | job can be started by using the STRTCPSVR command,
| gramming and the DB2 UDB for AS/400 SQL Reference | specifying the *EDRSQL server.
| books.
| For additional restrictions that apply to OptiConnect con-
| Error code | nections, see the OptiConnect API documentation.
| I/O; CHAR(*)
| The structure in which to return error information. For | The connection handle returned by this API is valid only in
| the format of the structure, see “Error Code Parameter” | the same job and activation group in which it was generated.
| on page 2-6. | A connection cannot span multiple jobs or activation groups.

| Usage Notes | Authorities and Locks

| None.
| This function may be called from the initial thread of a job
| only.
| Required Parameter Group

Chapter 34. File APIs 34-7

 Connect to EDRS Server (QxdaConnectEDRS) API

| Input structure
| Offset
| INPUT; CHAR(*)
| Dec Hex Type Field
| The structure in which to pass information about the
| connection. For the format of this parameter, see | 280 118 BINARY(4) Length of job-associated
| user data
| “CDBI0100 Format” on page 34-8.
| 284 11C BINARY(4) Offset to job-suspension
| Input structure format | user data
| INPUT; CHAR(8)
| 288 120 BINARY(4) Length of job-suspension
| The format of the input structure template being used. | user data
| The possible value is: | CHAR(*) Job-associated user data
| CDBI0100 Basic input structure | CHAR(*) Job-suspension user data

| Receiver variable
| OUTPUT; CHAR(*) | CDBO0100 Format
| The structure in which to return information about the
| connection. For the format of this parameter, see | The following table shows the information returned in the
| “CDBO0100 Format.” | CDBO0100 format. For more details about the fields in the
| following table, see “Field Descriptions.”
| Length of receiver variable
| INPUT; BINARY(4) | Offset
| The number of bytes that the calling program provides | Dec Hex Type Field
| for the receiver variable data.
| 0 0 BINARY(4) Bytes returned
| Receiver variable format | 4 4 BINARY(4) Bytes available
| INPUT; CHAR(8)
| 8 8 BINARY(4) Connection handle
| The format of the receiver variable template being used. | 12 C CHAR(10) Server job name
| The possible value is:
| 22 16 CHAR(10) Server job user name
| CDBO0100 | 32 20 CHAR(6) Server job number
| Basic receiver variable
| 38 26 CHAR(1) Connection type used
| Error code
| I/O; CHAR(*)
| The structure in which to return error information. For | Field Descriptions
| the format of the structure, see “Error Code Parameter”
| on page 2-6. | Allow job suspension. Whether or not to allow this job to
| be suspended or switched to run to a backup server if there
| CDBI0100 Format | is a server system failure or backup. The possible values
| are:
| The following table shows the information to pass in the | Y This job may be suspended or switched for
| CDBI0100 format. For more details about the fields in this | server system failures or backups. If this option
| table, see “Field Descriptions.” | is specified with a remote connection type and
| the server system has been switched to a
| Offset | backup by the QxdaBlockEDRS API, the con-
| Dec Hex Type Field | nection will be made to the backup system.
| N This job should not be suspended or switched.
| 0 0 CHAR(1) Connection type
| 1 1 CHAR(1) Commitment control | Bytes available. The length of the information available to
| 2 2 CHAR(10) Commit scope | the API to return, in bytes.
| 12 C CHAR(1) Allow job suspension | Bytes returned. The actual length of information returned
| 13 D CHAR(256) Server system name | to the caller of the API.
| 269 10D CHAR(3) Reserved
| Commit scope. The commitment definition scope. The
| 272 110 BINARY(4) SQLDA cache size | possible values are:
| 276 114 BINARY(4) Offset to job-associated | *JOB The job-level commitment definition is started for
| user data | the job.

34-8 AS/400 System API Reference V4R4

 Connect to EDRS Server (QxdaConnectEDRS) API

| *ACTGRP An activation-group-level commitment definition | Length of job-suspension user data. The length of the
| is started for the activation group associated with | job-suspension user data passed. This parameter must be
| the program issuing the command. This value is | set to 0 if the allow job suspension parameter is N.
| allowed for connection type L only. To simulate
| activation group commit scope in a remote envi- | Offset to job-associated user data. The offset from the
| ronment, multiple remote connections must be | beginning of the input structure to the job-associated user
| used. | data in the input structure, in bytes.

| Commitment control. The commit level to be used. The | Offset to job-suspension user data. The offset from the
| possible values are: | beginning of the input structure to the job-suspension user
| data in the input structure, in bytes. This value must be 0 if
| C *CHG: Every record read for update (for a file | the allow job suspension parameter is set to N.
| opened under commitment control) is locked. If
| a record is changed, added, or deleted, that | Reserved. Reserved field; it must be initialized to 0x00.
| record remains locked until the transaction is
| committed or rolled back. Records that are | Server job name. The job name of the database server job.
| accessed for update operations, but are released | If this is a local connection, this will be the current job name.
| without being changed, are unlocked.
| S *CS: Every record accessed for files opened | Server job number. The job number of the database server
| under commitment control is locked. A record | job. If this is a local connection, this will be the current job
| that is read, but not changed or deleted, is | number.
| unlocked when a different record is read.
| Server job user name. The user name of the database
| Records that are changed, added, or deleted are
| server job's initial user. If this is a local connection, this will
| locked until the transaction is committed or rolled
| be the current job's initial user.
| back.
| A *ALL: Every record accessed for files opened | Server system name. The name of the system to which to
| under commitment control is locked until the | connect. For connection type O, this is the current system
| transaction is committed or rolled back. | name as displayed on the Display Network Attributes
| N *NONE: Commitment control should not be | (DSPNETA) display on the server system. For connection
| started. | type T, this is the server system name as displayed in the
| TCP/IP host table. It must be initialized to blanks for all
| Connection type. The communications type to use for the
| other connection types. If the server system name is the
| connection. The possible values are:
| local system, the connection actually will be made locally.
| L Local connection: Only one local connection per
| job may be open at a time. If a second local | SQLDA cache size. The number of SQL descriptor areas
| connection is attempted in the job, the con- | to store for later reuse. An improvement in performance will
| nection actually will be made over UNIX domain | be seen if an SQL descriptor area can be reused.
| sockets.
| O OptiConnect
| T TCP/IP sockets
| Usage Notes
| U UNIX domain sockets | This function may be called from the initial thread of a job
| only.
| Connection type used. The connection type that was actu-
| ally used for the connection.
| Error Messages
| Connection handle. A unique handle number for the con-
| nection. The maximum number of connections per job that | CPF180C E
| may be open at one time is defined in the qxdaprced.h | Function &1 not allowed.
| header file. | CPF24B4 E Severe error while addressing parameter list.
| CPF3C21 E
| Job-associated user data. Data to associate with the | Format name &1 is not valid.
| server job that allows the job to be found using the | CPF3C90 E
| QxdaFindJob API. | Literal value cannot be changed.
| CPF9872 E Program or service program &1 in library &2
| Job-suspension user data. Data associated with the | ended. Reason code &3.
| current job to allow the job to be suspended independent of | CPFAE14 E
| an entire system suspension. | Cannot allocate &1 bytes.
| CPFB751 E Parameter &1 passed not correct.
| Length of job-associated user data. The length of the job- | CPFB752 E Internal error in &1 API.
| associated data passed. | CPFB753 E Required OptiConnect support not installed.
| CPFB754 E Unable to open connection.

Chapter 34. File APIs 34-9

 Create Database Hash (QCreateDatabaseHash) API

| CPFB757 E The connection is suspended. Logical file library

| CPFB758 E The EDRS server system has been switched. INPUT; CHAR(10)
The name of the library where the logical file resides.

Create Database Hash Expression

(QCreateDatabaseHash) API INPUT; CHAR(64)
A valid mathematical expression that uses all the key
values of a uniquely keyed logical file to determine the
Required Parameter Group: hash value for a particular record. The special value of
*DFT can be used to allow the API to create an
1 Hash name Input Char(10) expression based on expected cardinalities (number of
2 Physical file Input Char(10) expected unique values for each key) of the keys in the
3 Physical file library Input Char(10)
logical file. Possible values are:
4 Logical file Input Char(10)
5 Logical file library Input Char(10) *DFT The system default expression is used
6 Expression Input Char(64) (requires the use of the number of keys
7 Number-of-keys Input Binary(4)
parameter and the key ranges param-
8 Key ranges Input Char(*)
eter).
Threadsafe: No expression The user-defined expression is used. For
example: (where K1, K2, ... K5 are the
Service Program: QDBCRTHA names of the key fields used in the logical
file)

The Create Database Hash (QCreateDatabaseHash) API Number of keys

sets up the environment to enable the Run Database Hash INPUT; BINARY(4)
(QDBRUNHA) API for a physical file that has a uniquely The number of keys used in the logical file.
keyed logical file built over it. The logical file may have up to
five integer keys associated with it. It is called as a function Key ranges
call of the form 'xx = Qcrtdbha(parameter-list)', where xx is a INPUT; CHAR(*)
long integer and the parameter list is as defined here. The A two-value structure with up to five occurrences, con-
value of xx is set to a return code as defined in the taining the names of the key fields followed by the
“Returned Value” topic. expected cardinality of the key. For more details, see
“Field Descriptions.”
Authorities and Locks
Offset
HASH User Space in Library QUSRSYS
*OBJOPR, *READ, and *UPDATE Dec Hex Type Field
CHAR(10) Name of key

Required Parameter Group BINARY(4) Cardinality

Hash name
INPUT; CHAR(10) Field Descriptions
The hash name to be created. A unique name must be
Name of key. The name of the key field that is used in the
selected for each hash function that will be used on the
logical file, which is referenced in this API. The names are
system.
for documentation purposes only.
Physical file
INPUT; CHAR(10) Cardinality. The number of sequential values expected to
be used for each key, respectively. The cardinality values
The name of the physical file that will be accessed using are required if *DFT has been specified for the value of the
the hash. expression parameter.
Physical file library
INPUT; CHAR(10) Returned Value
The name of the library where the physical file resides.
The returned value contains a numeric indication as to what
Logical file took place during the request to add a hash function. The
INPUT; CHAR(10) possible values are:
The name of the logical file that will be used to build the 0 No errors.
hash. The logical file must be uniquely keyed.

34-10 AS/400 System API Reference V4R4

 Dump SQL Database Monitor (QQQDSDBM) API

-2 The physical file has multiple formats. The | 0 - QXDA_DISCONNECT_COMMIT

create database hash function cannot be com- | Commit all uncommitted database work
pleted. | when the connection is ended.
-3 The logical file is not uniquely keyed. The | 1 - QXDA_DISCONNECT_ROLLBACK
create database hash function cannot be com- | Roll back all uncommitted database work
pleted. | when the connection is ended.
-4 The logical file does not correlate to the phys-
| Error code
ical file specified. The create database hash
| I/O; CHAR(*)
function cannot be completed.
-5 The wrong number of keys was specified for | The structure in which to return error information. For
the logical file. The create database hash | the format of the structure, see “Error Code Parameter”
function cannot be completed. | on page 2-6.
-99 Another error was encountered and ignored.
See job log for details.
| Usage Notes
Error Messages | This function may be called from the initial thread of a job
| only.
Only the error conditions listed in the “Returned Value” on
page 34-10 are monitored. No error messages other than
the value of the return code parameter are returned.
| Error Messages
| CPF180C E
| Function &1 not allowed.
| Disconnect from EDRS Server | CPF24B4 E Severe error while addressing parameter list.
(QxdaDisconnectEDRS) API | CPF3C90 E
|
| Literal value cannot be changed.
| CPF9872 E Program or service program &1 in library &2
| ended. Reason code &3.
| Required Parameter Group:
| CPFB750 E Connection handle specified not valid.
| 1 Connection handle Input Binary(4) | CPFB752 E Internal error in &1 API.
| 2 Additional disconnection Input Binary(4) | CPFB756 E Rollback operation performed.
| options | CPFB757 E The connection has been suspended.
| 3 Error code I/O Char(*)

| Library Name/Service Program: QSYS/QXDAEDRS

Dump SQL Database Monitor
| Threadsafe: Conditional; see Usage Notes (QQQDSDBM) API

| The Disconnect from EDRS Server (QxdaDisconnectEDRS) Required Parameter Group:

| API is used to end a connection to a server system.
1 Memory handle to dump Input Char(10)
2 Job or memory handle Input Char(26)
| Authorities and Locks name
| None. 3 Number of types to dump Input Binary(4)
4 Subtypes and files array Input Array(*) of
Char(30)
| Required Parameter Group 5 Error code I/O Char(*)

| Connection handle Threadsafe: Conditional; see Usage Notes.

| INPUT; BINARY(4)
| The handle number of the connection to end. The con-
The Dump SQL Database Monitor (QQQDSDBM) API dumps
| nection handle must have been generated by the
the SQL database monitor that has been gathered. The data
| QxdaConnectEDRS API in the current job and activation
that is gathered will be all data that has been committed (if
| group.
the job is under commitment control) or based on a 5-minute
| Additional disconnection options timer. Associated APIs include the following:
| INPUT; BINARY(4) Ÿ Clear SQL Database Monitor Statistics (QQQCSDBM)
| The following are valid disconnection options, defined in Ÿ End SQL Database Monitor (QQQESDBM)
| the qxdaedrs.h header file:
Ÿ Query SQL Database Monitor (QQQQSDBM)
Ÿ Start SQL Database Monitor (QQQSSDBM)

Chapter 34. File APIs 34-11

Dump SQL Database Monitor (QQQDSDBM) API

Authorities and Locks *ALL

All jobs. The rest of the job
Current User Profile name parameter must be
*JOBCTL blank.
Library Authority for New File User name
*ADD and *READ CHAR(10). A specific user profile
Library Authority for Existing File name.
*EXECUTE Job number
Existing File *CHANGE and *OBJALTER CHAR(6). A specific job number.

Number of types to dump

Required Parameter Group INPUT; BINARY(4)
Memory area to dump The number of types passed in the subtypes and files
INPUT; CHAR(10) array.
Memory area to dump. The possible values are: Subtypes and files array
*ALL Dump the monitor data associated with INPUT; Array(*) of CHAR(30)
the *ALL monitor (the monitor started The list of all subtypes to dump and their associated
against all jobs). The Start SQL Data- receiving files. The format of each array element is:
base Monitor (QQQSSDBM) must have
been started with job name *ALL. CHAR(10). Key to Dump.
*NAMED Dump the memory handle named by the The possible choices are:
job or memory handle name parameter KEYT_3000 Summary: Arrival sequence
(and matches the name of a memory KEYT_3001 Summary: Index used
handle specified on the QQQSSDBM KEYT_3002 Summary: Index created
API). Only the first 6 characters will be KEYT_3003 Summary: Sort
used for naming the memory handle. If KEYT_3004 Summary: Temporary file
QQQSSDBM started the monitor with KEYT_3007 Summary: Optimizer time-out or all
*JOB, you can also name the job to be access paths considered
dumped with this parameter by giving the KEYT_3008 Summary: Subselect processing
6-character memory handle that contains KEYT_3010 Summary: Host variable values
the job number. KEYT_TEXT SQL statement text
*JOB Dump the job-specific data associated KEYT_QRYI Summary: General SQL information
with the job named by the job or memory including statement count, maximum
handle name parameter. runtime, time last used, and so
forth.
Job or memory handle name
This subtype is always monitored
INPUT; CHAR(26)
because it is required for monitoring
This parameter depends on the value specified for the all other subtypes. Although it is
memory area to dump parameter. If the value is: always monitored, it will not be
dumped unless requested.
*ALL This parameter is ignored.
CHAR(20). File name.
*NAMED The CHAR(6) name of a memory handle
The name of the file to receive the data. The first
whose data is to be dumped. Only the
10 characters contain the file name, and the
first 6 characters will be used for naming
second 10 characters contain the library name. A
the memory handle.
member name of *FIRST is assumed. The fol-
*JOB The CHAR(26) qualified job name of a
lowing special values can be used for the library
job-specific monitor to dump. The quali-
name:
fied job name has three parts:
*CURLIB The job's current library
Job name
*LIBL The library list
CHAR(10). A specific job name, a
generic name, or one of following If the file already exists, it will be cleared prior to
special values: dumping the data.
* or *CURRENT The files will be created with authority of
Only the job that this program owner(*ALL) and PUBLIC(*CHANGE), and they are
is running in. The rest of the owned by the profile of the job calling
qualified job name parameter QQQDSDBM.
must be blank.

34-12 AS/400 System API Reference V4R4

 Find EDRS Job (QxdaFindEDRSJob) API

Note: If a subtype is specified multiple times, only the Ÿ Dump SQL Database Monitor (QQQDSDBM)
first occurrence of the subtype and the associated file
Ÿ Query SQL Database Monitor (QQQQSDBM)
name is honored. The duplicates are ignored.
Ÿ Start SQL Database Monitor (QQQSSDBM)
Error code
I/O; CHAR(*)
Authorities and Locks
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” Current User Profile
on page 2-6. *JOBCTL

Usage Notes Required Parameter Group

Qualified job name
This function is threadsafe but not thread enabled. Database
INPUT; CHAR(26)
monitor data is collected in the threaded process but summa-
rized at the job level. The job to end monitoring on. The qualified job name
has three parts:
The QQQDSDBM API does not force a clear operation
(QQQCSDBM) of the memory. Data will continue to be Job name
added to memory until the QQQCSDBM or QQQESDBM API CHAR(10). A specific job name, a generic name,
is called. or one of the following special values:
* or *CURRENT
Only the job that this program is
Error Messages running in. The rest of the qualified
CPD0172 D job name parameter must be blank.
Parameters passed on CALL do not match *ALL All jobs. The rest of the job name
those required. parameter must be blank.
CPF222E E &1 special authority is required. User name
CPF3012 E File &1 in library &2 not found. CHAR(10). A specific user profile name.
CPF3084 E Error clearing member &3 in file &1. Job number
CPF3130 E Member &2 already in use. CHAR(6). A specific job number.
CPF3CF1 E
Error code
Error code parameter not valid.
I/O; CHAR(*)
CPF9822 E Not authorized to file &1 in library &2.
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6.
End SQL Database Monitor (QQQESDBM)
API
Error Messages
CPD0172 D
Required Parameter Group: Parameters passed on CALL do not match
those required.
1 Qualified job name Input Char(26)
2 Error code I/O Char(*) CPF1321 E Job &1 user &2 job number &3 not found.
CPF3CF1 E
Threadsafe: Yes Error code parameter not valid.
CPF436D E
Job specified is not being monitored.
The End SQL Database Monitor (QQQESDBM) API ends the CPF436E E Job &1 user &2 job number &3 is not active.
memory-based SQL database monitor. Associated APIs
include the following:
Ÿ Clear SQL Database Monitor Statistics (QQQCSDBM) | Find EDRS Job (QxdaFindEDRSJob) API

Chapter 34. File APIs 34-13

 Find EDRS Job (QxdaFindEDRSJob) API

| Receiver variable format

| Required Parameter Group: | INPUT; CHAR(8)
| The format of the structure in which to return information
| 1 Connection handle Input Binary(4) | about the jobs found. The possible value is:
| 2 Job-associated user data Input Char(*)
| 3 Length of job-associated Input Binary(4) | QJBI0100 Basic receiver variable structure.
| user data
| 4 Receiver variable Output Char(*) | Number of jobs found
| 5 Length of receiver variable Input Binary(4) | OUTPUT; BINARY(4)
| 6 Receiver variable format Input Char(8)
| 7 Number of jobs found Output Binary(4) | The number of jobs found with associated user data that
| 8 Number of jobs returned Output Binary(4) | matches the user data passed in. This is the total
| 9 Error code I/O Char(*) | number found, even if the information for all the jobs
| cannot fit in the space provided.
| Library Name/Service Program: QSYS/QXDAEDRS
| Number of jobs returned
| Threadsafe: Conditional; see Usage Notes | OUTPUT; BINARY(4)
| The actual number of jobs for which information was
| The Find EDRS Job (QxdaFindEDRSJob) API is used to find | returned.
| all jobs with user-defined data associated with the Connect to | Error code
| EDRS Server (QxdaConnectEDRS) API that matches the | I/O; CHAR(*)
| data passed to this API.
| The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter”
| Authorities and Locks | on page 2-6.
| None.
| QJBI0100 Format
| Required Parameter Group
| The following table shows the structure of the QJBI0100
| Connection handle | format. For more details about the fields in this table, see
| INPUT; BINARY(4) | “Field Descriptions.”
| The handle number of the connection in which to find
| jobs. The connection handle must have been generated | Offset
| by the Connect to EDRS Server (QxdaConnectEDRS) | Dec Hex Type Field
| API in the current job and activation group.
| 0 0 BINARY(4) Process ID
| Job-associated user data | 4 4 CHAR(10) Job name
| INPUT; CHAR(*)
| 14 E CHAR(10) Job user name
| User data that also was passed to the Connect to EDRS | 24 18 CHAR(6) Job number
| Server (QxdaConnectEDRS) API. This may be the com-
| plete user data or only a part of it. If it is only part, it | 30 1E CHAR(16) Internal job identifier
| must be the beginning of the user data string. | 46 2E CHAR(2) Reserved

| Length of job-associated user data

| INPUT BINARY(4) | Field Descriptions
| The length of the user data to compare.

| Receiver variable | Internal job identifier. The internal job identifier. This
| OUTPUT; CHAR(*) | value is sent to other APIs to speed the process of locating
| the job on the system.
| Space for the job information to be returned. This infor-
| mation is returned as an array of QJBI0100 structures, | Job name. The name of the job found.
| one for each job found. For the format of each array
| element, see “QJBI0100 Format.” | Job number. The number of the job found.
| Length of receiver variable | Job user name. The name of the initial user of the job
| INPUT; BINARY(4) | found.
| Length (in bytes) of the receiver variable provided to
| return information about the jobs found. | Process ID. The process ID (PID) of the job found.

| Reserved. Reserved field; it must be initialized to 0x00.

34-14 AS/400 System API Reference V4R4

 List Database File Members (QUSLMBR) API

| Usage Notes needs of your application. For example, if you want to

selectively retrieve member descriptions for a subset of
| This function may be called from the initial thread of a job the member list, you might want to use both the
| only. QUSLMBR and QUSRMBRD APIs.
Ÿ Ensure that the last date the source was changed
| Error Messages matches the date of the source used to create the
object.
| CPF180C E
| Function &1 not allowed.
| CPF24B4 E Severe error while addressing parameter list. Authorities and Locks
| CPF3C90 E User Space Authority
| Literal value cannot be changed. *CHANGE
| CPF9872 E Program or service program &1 in library &2 Library Authority
| ended. Reason code &3. *USE
| CPFB750 E Connection handle specified not valid. File Authority *OBJOPR
| CPFB752 E Internal error in &1 API. User Space Lock
| CPFB756 E Rollback operation performed. *EXCLRD
| CPFB757 E The connection is suspended. File Lock *SHRRD
| CPFB758 E The EDRS server system has been switched.

Required Parameter Group

List Database File Members (QUSLMBR) Qualified user space name
API INPUT; CHAR(20)
The user space that is to receive the created list. The
first 10 characters contain the user space name, and the
Required Parameter Group: second 10 characters contain the name of the library
1 Qualified user space name Input Char(20) where the user space is located. You can use these
2 Format name Input Char(8) special values for the library name:
3 Qualified database file Input Char(20)
name
*CURLIB The job's current library
4 Member name Input Char(10) *LIBL The library list
5 Override processing Input Char(1)
Format name
Optional Parameter: INPUT; CHAR(8)
The content and format of the information returned for
6 Error code I/O Char(*) each member. The possible format names are:
| Threadsafe: Conditional; see Usage Notes. MBRL0100 Member name
MBRL0200 Member name and source information
This format requires more processing
The List Database File Members (QUSLMBR) API generates
than the MBRL0100 format.
a list of database file members and places the list in a speci-
MBRL0310 Member name and basic description.
fied user space. When you specify a generic member name,
The member information is the same as
you can generate a subset of the member list. You can use
that generated by the Retrieve Member
the QUSLMBR API with database file types *PF, *LF, and
Description (QUSRMBRD) API using
*DDMF. The generated list replaces any existing information
format MBRD0100. This format requires
in the user space. The file members listed in the user space
more system processing and takes longer
are not in any predictable order. To retrieve additional infor-
to produce than the MBRL0200 format.
mation about each member in the list, see “Retrieve Member
MBRL0320 Member name and expanded description.
Description (QUSRMBRD) API” on page 34-183.
The member information is the same as
You can use the QUSLMBR API to: that generated by the Retrieve Member
Description (QUSRMBRD) API using
Ÿ List members more quickly than by using the *MBRLIST format MBRD0200. The additional infor-
value on the TYPE parameter of the Display File mation requires more system processing
Description (DSPFD) command. and takes longer to produce than the
Ÿ Retrieve information for all of the members of a data- MBRL0310 format.
base file more quickly and easily than by multiple calls to MBRL0330 Member name and full description. The
the Retrieve Member Description (QUSRMBRD) API. It member information is the same as that
is your discretion to decide which API best suits the generated by the Retrieve Member

Chapter 34. File APIs 34-15

List Database File Members (QUSLMBR) API

Description (QUSRMBRD) API using – MBRL0300 format

format MBRD0300. The additional infor-
mation requires more system processing The MBRL0300 list data section is generated if MBRL0310,
and takes longer to produce than the MBRL0320, or MBRL0330 is specified as the format name
MBRL0320 format. parameter.

For more information, see “MBRL0100 List Data For details about the user area and generic header, see
Section,” “MBRL0200 List Data Section,” or “MBRL0300 “User Space Format for List APIs” on page 2-4. For details
List Data Section” on page 34-17. about the remaining items, see the following sections. For
detailed descriptions of the fields in the list returned, see
Qualified database file name
“Field Descriptions” on page 34-17.
INPUT; CHAR(20)
The name of the database file whose member names When you retrieve list entry information from a user space,
are to be placed in the list. The first 10 characters you must use the entry size returned in the generic header
contain the database file name, and the second 10 char- as a displacement to the next list entry. The size of each
acters contain the name of the library where the file is entry may be padded at the end. If you do not use the entry
located. size, the result may not be valid. For examples of how to
process lists, see Appendix A, “Examples.”
You can use these special values for the library name:

*CURLIB The job's current library Input Parameter Section

*LIBL The library list
Offset
Member name
Dec Hex Type Field
INPUT; CHAR(10)
0 0 CHAR(10) User space name
A specific member name, a generic member name, or
this special value: 10 A CHAR(10) User space library name
20 14 CHAR(8) Format name
*ALL All members
28 1C CHAR(10) File name specified
Override processing
38 26 CHAR(10) File library name specified
INPUT; CHAR(1)
48 30 CHAR(10) Member name specified
Whether overrides are to be processed. The following
character values are used: 58 3A CHAR(1) Override processing

0 No override processing Header Section

1 Override processing
Offset
Optional Parameter Dec Hex Type Field
Error code 0 0 CHAR(10) File name used
I/O; CHAR(*) 10 A CHAR(10) File library name used
The structure in which to return error information. For 20 14 CHAR(10) File attribute
the format of the structure, see “Error Code Parameter”
30 1E CHAR(50) File text description
on page 2-6. If this parameter is omitted, diagnostic
and escape messages are issued to the application. 80 50 BINARY(4) Total number of members in
file
84 54 CHAR(1) Source file
Format of the Generated Lists
85 55 CHAR(3) Reserved
The file member list consists of: 88 58 BINARY(4) File text description CCSID
Ÿ A user area
Ÿ A generic header MBRL0100 List Data Section
Ÿ An input parameter section Offset
Ÿ A header section Dec Hex Type Field
Ÿ A list data section: 0 0 CHAR(10) Member name used
– MBRL0100 format
– MBRL0200 format MBRL0200 List Data Section

34-16 AS/400 System API Reference V4R4

 List Database File Members (QUSLMBR) API

File library name specified. The name of the library con-

Offset
taining the file whose member names are to be placed in the
Dec Hex Type Field list.
0 0 CHAR(10) Member name used
File library name used. The name of the library containing
10 A CHAR(10) Source type
the file whose member names are placed in the list.
20 14 CHAR(13) Creation date and time
33 21 CHAR(13) Last source change date
File name specified. The name of the file specified in the
and time call to the API.
46 2E CHAR(50) Member text description File name used. The name of the file whose member
96 60 BINARY(4) Member text description names are placed in the list.
CCSID
File text description. The description of the file.
MBRL0300 List Data Section: The MBRL0300 format File text description CCSID. The CCSID for the file text
provides an offset to a retrieved member description. The description. The job default CCSID of the current process
member descriptions have the same format as those gener- will be used to translate the text. For more information about
ated by the Retrieve Member Description (QUSRMBRD) API. CCSID, see the National Language Support.
The following relationship exists between the QUSLMBR
format name and the QUSRMBRD member descriptions: Format name. The content and format of the information
Ÿ MBRL0310 generates an MBRD0100 description. returned for each member.

Ÿ MBRL0320 generates an MBRD0200 description. Last source change date and time. The date and time that
Ÿ MBRL0330 generates an MBRD0300 description. this source member was last changed. This field is in the
CYYMMDDHHMMSS format where the format is the same
For more information about the member description formats, as for the creation date and time field.
see “Retrieve Member Description (QUSRMBRD) API” on
page 34-183. Member name specified. The name of the member speci-
fied in the call to the API.
Offset
Member name used. The name of a member found in the
Dec Hex Type Field
file.
0 0 CHAR(10) Member name used
10 A CHAR(2) Reserved Member text description. Description of the member found
in the file.
12 C BINARY(4) Offset to member descrip-
tion information Member text description CCSID. The CCSID for the
16 10 CHAR(16) Reserved member text description. The job default CCSID of the
current process will be used to translate the text. For more
Field Descriptions: information about CCSID, see the National Language
Support.
Creation date and time. The date and time the member
was created. The format of this field is in the Offset to member description information. The number of
CYYMMDDHHMMSS as follows: bytes from the beginning of the user space to the beginning
of the retrieved member description.
C Century, where 0 indicates years 19xx and 1
indicates years 20xx. Override processing. Whether overrides are to be pro-
YY Year cessed. The possible values are:
MM Month
0 No override processing
DD Day
1 Override processing
HH Hour
MM Minute Reserved. An ignored field.
SS Second
Source file. Whether the file is a source file or a data file.
File attribute. The type of file found: The possible values are:
PF Physical file 0 Data file
LF Logical file 1 Source file
DDMF Distributed data management file
Source type. The type of source member if this is a source
file. Some possible values are:
Ÿ CL

Chapter 34. File APIs 34-17

 List Database Relations (QDBLDBR) API

Ÿ COBOL
Ÿ RPG Required Parameter Group:
Ÿ TXT 1 Qualified user space name Input Char(20)
2 Format Input Char(8)
Total number of members in file. The total number of 3 Qualified file name Input Char(20)
members in the file specified. 4 Member Input Char(10)
5 Record format Input Char(10)
User space library name. The name of the library that con- 6 Error code I/O Char(*)
tains the user space that is to receive the generated list.
Threadsafe: No
User space name. The name of the user space that is to
receive the generated list.
The List Database Relations (QDBLDBR) API gives relational
information about database files. The information identifies
| Usage Notes the physical and logical files that are dependent on a specific
file, files that use a specific record format, or file members
| In multithreaded jobs, this API is not threadsafe and fails for that are dependent on a specific file member. The informa-
| distributed data management (DDM) files of type *SNA. tion is placed in a user space specified by you.

Error Messages Similar in function to the Display Database Relations

(DSPDBR) command, this API allows more input parameter
CPF24B4 E Severe error while addressing parameter list. values than does the command. Also, your program can
CPF3CF1 E have more direct access to the information put in the user
Error code parameter not valid. space by this API than when the command places similar
CPF3C20 E information in an output file.
Error found by program &1.
CPF3C21 E The information generated by this API replaces any existing
Format name &1 is not valid. information in the user space. It does not append informa-
CPF3C22 E tion to any information already in the user space. If the
Cannot get information about file &1. space is bigger than needed, the contents of the remainder
CPF3C23 E of the space are not changed. If the space is not big
Object &1 is not a database file. enough, it is extended.
CPF3C25 E
Value &1 for file override parameter is not valid.
CPF3C27 E
Authorities and Locks
Cannot get information about member &3 from User Space Authority
file &1. *CHANGE
CPF3C36 E User Space Library Authority
Number of parameters, &1, entered for this API *USE
was not valid. User Space Lock
CPF3C90 E *EXCLRD
Literal value cannot be changed. File Authority *USE
CPF8100 E All CPF81xx messages could be returned. xx is File Library Authority
from 01 to FF. *USE
CPF9800 E All CPF98xx messages could be signaled. xx is File Lock *SHRNUPD
from 01 to FF.
Required Parameter Group
List Database Relations (QDBLDBR) API Qualified user space name
INPUT; CHAR(20)
The user space that is to receive the database relations
information. The first 10 characters contain the user
space name, and the second 10 characters contain the
name of the library where the user space is located.
You can use these special values for the library name:

*CURLIB The job's current library

*LIBL The library list

34-18 AS/400 System API Reference V4R4

 List Database Relations (QDBLDBR) API

Format This input is ignored for formats DBRL0100 and

INPUT; CHAR(8) DBRL0200.
The content and format of the information to be returned Error code
about the specified file, member, or record format. One I/O; CHAR(*)
of the following format names must be used:
The structure in which to return error information. For
DBRL0100 File information the format of the structure, see “Error Code Parameter”
DBRL0200 Member information on page 2-6.
DBRL0300 Record format information

For more information, see “DBRL0100 Format Format of the Generated List
(File),” “DBRL0200 Format (Member)” on page 34-20 ,
or “DBRL0300 Format (Record Format)” on page 34-20. The database relations list consists of an input parameter
section and one of three possible formats for the list data
Qualified file name section. The three formats are determined by the kind of
INPUT; CHAR(20) information you are looking for. The format names are:
The name of the file for which database relations infor- DBRL0100 Database relations (file)
mation is to be extracted. The first 10 characters DBRL0200 Database relations (member)
contain the file name, and the second 10 characters DBRL0300 Database relations (record format)
contain the name of the library where the file is located.
The file name cannot be a DDM file. The layout of the contents of the user space is determined
by the format used. The following tables show how the con-
The file name can be a specific file name, a generic
tents of the input parameter section and the data format
name, or the following special value:
sections are organized. For descriptions of each field, see
*ALL All files “Field Descriptions” on page 34-20.

You can use these special values for the library name: Input Parameter Section
*ALL All libraries in the system
*ALLUSR All nonsystem libraries Offset
*CURLIB The job's current library Dec Hex Type Field
*LIBL The library list
0 0 CHAR(10) User space name
*USRLIBL Libraries listed in the user portion of the
library list 10 A CHAR(10) User space library name
20 14 CHAR(8) Format name
Member
INPUT; CHAR(10) 28 1C CHAR(10) File name specified
38 26 CHAR(10) File library name specified
The name of the member to be used for retrieving data-
base relations for format DBRL0200. This value can be 48 30 CHAR(10) Member name specified
a specific member name, a generic member name, or 58 3A CHAR(10) Record format name speci-
one of the following special values: fied

*FIRST Information about the first member (in the

order created) in the specified file or files DBRL0100 Format (File): The structure of the informa-
is to be provided. tion returned is determined by the value specified for the
*LAST Information about the last member (in the format name. The DBRL0100 format includes information on
order created) in the specified file or files files dependent on the file specified. The following table
is to be provided. shows how this information is organized. For detailed
*ALL Information about all members in the descriptions of the fields in the list, see “Field Descriptions”
specified files is to be provided. on page 34-20.

This parameter is ignored for formats DBRL0100 and Offset

DBRL0300.
Dec Hex Type Field
Record format 0 0 CHAR(10) File name used
INPUT; CHAR(10)
10 A CHAR(10) File library name used
The name of the record format to be used for retrieving
20 14 CHAR(10) Dependent file name
database relations for format DBRL0300. This value can
be a specific record format, a generic record format, or 30 1E CHAR(10) Dependent library name
the following special value: 40 28 CHAR(1) Dependency type
*ALL All record formats in the specified file

Chapter 34. File APIs 34-19

List Database Relations (QDBLDBR) API

Offset Field Descriptions:

Dec Hex Type Field Constraint library name. The name of the library con-
41 29 CHAR(3) Reserved taining the file to which the constraint applies.
44 2C BINARY(4) Join reference number Constraint name. The name of the constraint. This only
48 30 CHAR(10) Constraint library name applies when the dependency type is C.
58 3A BINARY(4) Constraint name length
Constraint name length. The length of the constraint
62 3E CHAR(258) Constraint name name. Delimited names can be a maximum of 258 charac-
ters and non-delimited names a maximum of 128 characters.
DBRL0200 Format (Member): The structure of the
information returned is determined by the value specified for Dependency type. How a file or member is related to the
the format name. The DBRL0200 format includes informa- file or member specified with the QDBLDBR API. Possible
tion on files and members dependent on the file member values are:
specified. The following table shows how this information is blank No dependent files or members were found
organized. For detailed descriptions of the fields in the list, for the specified file.
see “Field Descriptions.” C Constraint.
D The dependent file or member is dependent
Offset on the data in the specified file or member
Dec Hex Type Field that was extracted.
I The dependent file member is sharing the
0 0 CHAR(10) File name used
access path of the file that the information
10 A CHAR(10) File library name used was extracted from.
20 14 CHAR(10) Member name used O If an access path is shared, one of the file
members is considered the owner. The owner
30 1E CHAR(10) Dependent file name
of the access path is charged with the storage
40 28 CHAR(10) Dependent library name used for the access path. If the member dis-
50 32 CHAR(10) Dependent member name played is designated the owner, one or more
file members are designated with an I for
60 3C CHAR(1) Dependency type
access path sharing.
61 3D CHAR(3) Reserved V The SQL view or member is dependent on the
64 40 BINARY(4) Join reference number specified SQL view.
68 44 BINARY(4) Join file number
Dependent file name. The name of the file that is
72 48 CHAR(10) Constraint library name dependent on the file specified using the QDBLDBR API. If
82 52 BINARY(4) Constraint name length no dependent files are found for the file specified, the
dependent file name is *NONE.
86 56 CHAR(258) Constraint name
Dependent library name. The name of the library that the
DBRL0300 Format (Record Format): The structure of dependent file is in. If there are no dependent files found for
the information returned is determined by the value specified the file specified, the dependent library name is blank.
for the format name. The DBRL0300 format includes infor-
mation on files dependent on the record format specified. Dependent member name. The name of the file member
The following table shows how this information is organized. that is dependent on the file member specified using the
For detailed descriptions of the fields in the list, see “Field QDBLDBR API. If no dependent members are found for the
Descriptions.” member specified, the dependent member name is *NONE.

File library name specified. The name of the library con-

Offset
taining the file for which the database relations information is
Dec Hex Type Field requested.
0 0 CHAR(10) File name used
File library name used. The name of the library containing
10 A CHAR(10) File library name used
the file used to extract the database relations information in
20 14 CHAR(10) Record format name used this list entry.
30 1E CHAR(10) Dependent file name
File name specified. The name of the file for which the
40 28 CHAR(10) Dependent library name database relations information is to be extracted.

File name used. The name of the file used to extract the
database relations information in this list entry.

34-20 AS/400 System API Reference V4R4

 List Fields (QUSLFLD) API

Format name. The name of the format in which the data-

base relations information is returned to the user space. List Fields (QUSLFLD) API

Join file number. If the file for which database relations

information is being extracted is a join logical file, this is the Required Parameter Group:
ordinal number of the file in the JFILE to which the depend-
ency relates. The join file number is zero if either of the fol- 1 Qualified user space name Input Char(20)
2 Format name Input Char(8)
lowing are correct:
3 Qualified file name Input Char(20)
Ÿ No dependent files are found for the file specified. 4 Record format name Input Char(10)
5 Override processing Input Char(1)
Ÿ The file for which the information is being extracted is
not a join file. Optional Parameter:
Join reference number. If the dependent file listed is a join 6 Error code I/O Char(*)
logical file, this is the ordinal number of the file in the JFILE
to which this dependency relates. The join reference number Threadsafe: No
is zero if either of the following are correct:
Ÿ No dependent files are found for the file specified. The List Fields (QUSLFLD) API generates a list of fields
Ÿ The dependent file is not a join file. within a specified file record format name. The list of fields is
placed in a specified user space. The generated list
Member name specified. The name of the member for replaces any existing information in the user space. You can
which the information is extracted. use the QUSLFLD API only with database file types, such as
*PF, *LF, and *DDMF, and device file types, such as *ICFF
Member name used. The name of the member used to and *PRTF.
extract the database relations information in this list entry.
You can use the QUSLFLD API to:
Record format name specified. The name of the record
Ÿ Generate a list of field format names.
format for which the information is displayed.
Ÿ Gather additional information about specific field formats.
Record format name used. The name of the record format
Ÿ Create a product similar to the Structured Query Lan-
used to extract the database relations information in this list
guage (SQL) using the Open Query File (OPNQRYF)
entry.
command.
Reserved. An ignored field. Ÿ Create applications similar to the data file utility (DFU).

User space library name. The name of the library that con- Ÿ Create a compiler supporting externally described data.
tains the user space that receives the database relations Ÿ Create applications that use data defined to the system.
information requested.

User space name. The name of the user space that Authorities and Locks
receives the database relations information requested. User Space Authority
*CHANGE
Error Messages Library Authority
*USE
CPF3CF2 E File Authority *OBJOPR
Error(s) occurred during running of &1 API. User Space Lock
CPF3C21 E *EXCLRD
Format name &1 is not valid. File Lock *SHRRD
CPF3C23 E
Object &1 is not a database file.
CPF3C90 E Required Parameter Group
Literal value cannot be changed.
Qualified user space name
CPF326C E
INPUT; CHAR(20)
File name &1 not valid special value.
CPF326D E The name of the user space that is to receive the
Member name &1 not valid special value. created list, and the library in which it is located. The
CPF326E E Record format name &1 not valid special value. first 10 characters contain the user space name, and the
CPF9872 E Program or service program &1 in library &2 second 10 characters contain the library name.
ended. Reason code &3. You can use these special values for the library name:

*CURLIB The job's current library

Chapter 34. File APIs 34-21

 List Fields (QUSLFLD) API

*LIBL The library list about the remaining items, see the following sections. For
descriptions of each field in the list returned, see “Field
Format name
Descriptions” on page 34-23.
INPUT; CHAR(8)
The format of the information returned. You must use When you retrieve list entry information from a user space for
the following format name: format FLDL0100, you must use the entry size returned in
the generic header as a displacement to the next list entry.
FLDL0100 Field information The size of each entry may be padded at the end. If you do
| FLDL0200 Field and default value information | not use the entry size, the result may not be valid. When
For more information, see “Format of the Generated | you retrieve list entry information from a user space for
List.” | format FLDL0200, you must use the length provided at the
| beginning of format FLDL0200 as a displacement to the next
Qualified file name | list entry. If you do not use the length provided in
INPUT; CHAR(20) | FLDL0200, the result may not be valid. For examples of how
The file whose member names are to be placed in the to process lists, see Appendix A, “Examples.”
list, and the library in which it is located. The first 10
Input Parameter Section
characters contain the file name, and the second 10
characters contain the library name.
Offset
You can use these special values for the library name:
Dec Hex Type Field
*CURLIB The job's current library 0 0 CHAR(10) User space name
*LIBL The library list
10 A CHAR(10) User space library name
Record format name 20 14 CHAR(8) Format name
INPUT; CHAR(10)
28 1C CHAR(10) File name specified
The record format name whose fields are to be returned.
38 26 CHAR(10) File library name specified
Override processing 48 30 CHAR(10) Record format name speci-
INPUT; CHAR(1) fied
Whether overrides are to be processed. The possible 58 3A CHAR(1) Override processing
values are:

0 No override processing Header Section

1 Override processing
Offset
Dec Hex Type Field
Optional Parameter
0 0 CHAR(10) File name used
Error code
10 A CHAR(10) File library name used
I/O; CHAR(*)
20 14 CHAR(10) File type
The structure in which to return error information. For
the format of the structure, see “Error Code Parameter” 30 1E CHAR(10) Record format name used
on page 2-6. If this parameter is omitted, diagnostic 40 28 BINARY(4) Record length
and escape messages are issued to the application. 44 2C CHAR(13) Record format ID
57 39 CHAR(50) Record text description
Format of the Generated List 107 6B CHAR(1) Reserved

The field list consists of: 108 6C BINARY(4) Record text description
CCSID
Ÿ A user area
112 70 CHAR(1) Variable length fields in
Ÿ A generic header format indicator
Ÿ An input parameter section 113 71 CHAR(1) Graphic fields indicator
Ÿ A header section 114 72 CHAR(1) Date and time fields indi-
cator
| Ÿ The FLDL0100 or FLDL0200 list data section
115 73 CHAR(1) Null-capable fields indicator
For details about the user area and generic header, see
“User Space Format for List APIs” on page 2-4. For details FLDL0100 List Data Section

34-22 AS/400 System API Reference V4R4

 List Fields (QUSLFLD) API

Offset Offset
Dec Hex Type Field Dec Hex Type Field
0 0 CHAR(10) Field name | 445 1BD CHAR(1) Datalink write permission
10 A CHAR(1) Data type | 446 1BE CHAR(1) Datalink recovery
11 B CHAR(1) Use | 447 1BF CHAR(1) Datalink unlink control
12 C BINARY(4) Output buffer position
16 10 BINARY(4) Input buffer position | FLDL0200 List Data Section
20 14 BINARY(4) Field length in bytes
| Offset
24 18 BINARY(4) Digits
| Dec Hex Type Field
28 1C BINARY(4) Decimal position
| 0 0 BINARY(4) Length of FLDL0200 format
32 20 CHAR(50) Field text description
| 4 4 BINARY(4) Offset to default value
82 52 CHAR(2) Edit code
| 8 8 BINARY(4) Length of default value
84 54 BINARY(4) Edit word length
| 12 C All fields defined by
88 58 CHAR(64) Edit word | FLDL0100 format
152 98 CHAR(20) Column heading 1 | 454 1C6 CHAR(*) Default value
172 AC CHAR(20) Column heading 2
192 C0 CHAR(20) Column heading 3 Field Descriptions:
212 D4 CHAR(10) Internal field name Alternative field name. The alternative name of the field
222 DE CHAR(30) Alternative field name the entry describes. This is the DDS keyword ALIAS.
252 FC BINARY(4) Length of alternative field
name
Column heading 1. The description of the first column
heading for this field. It contains blanks if the heading is not
256 100 BINARY(4) Number of DBCS charac- defined.
ters
260 104 CHAR(1) Null values allowed Column heading 2. The description of the second column
261 105 CHAR(1) Host variable indicator
heading for this field. It contains blanks if the heading is not
defined.
262 106 CHAR(4) Date and time format
266 10A CHAR(1) Date and time separator Column heading 3. The description of the third column
heading for this field. It contains blanks if the heading is not
267 10B CHAR(1) Variable length field indi-
cator (overlay for MI
defined.
mapping)
Data type. The type of field:
268 10C BINARY(4) Field text description CCSID
A Alphanumeric (character)
272 110 BINARY(4) Field data CCSID B Binary
276 114 BINARY(4) Field column headings D Digits only
CCSID E Either DBCS or alphanumeric
280 118 BINARY(4) Field edit words CCSID F Floating point
G Graphic data type
284 11C BINARY(4) UCS-2 displayed field length
H Hexadecimal
| 288 120 BINARY(4) Field data encoding scheme I Inhibit entry
| 292 124 BINARY(4) Maximum large object field J Double-byte character set (DBCS) data only
| length L Date
| 296 128 BINARY(4) Pad length for large object M Numeric only
N Numeric shift
| 300 12C BINARY(4) Length of user-defined type
O (Open) Both DBCS and alphanumeric
| name
P Packed decimal
| 304 130 CHAR(128) User-defined type name S Zoned decimal
| 432 1B0 CHAR(10) User-defined type library T Time
| name W Katakana
| 442 1BA CHAR(1) Datalink link control X Alphabetic only (character)
Y Numeric only
| 443 1BB CHAR(1) Datalink integrity
Z Timestamp
| 444 1BC CHAR(1) Datalink read permission | 1 Binary large object (BLOB)

Chapter 34. File APIs 34-23

 List Fields (QUSLFLD) API

| 2 Character large object (CLOB) Date and time fields indicator. Whether this format con-
| 3 Graphic data large object (DBCLOB) tains date and time fields. The possible values are:
| 4 Datalink
0 The format does not contain date and time
fields.
| Datalink integrity. How the control of the file is handled.
| This value applies to datalink fields. A datalink is a field
1 The format contains date and time fields.
| data type that is used to point to another object that contains
Date and time format. This value applies to date, time, and
| the data for that field. If the datalink link control field is 0 (no
timestamp fields. It also may apply to packed decimal, zoned
| link control), this field is not applicable. The possible values
decimal, and character fields in a logical file. The possible
| are:
values are:
| 0 All linked files are under control of the data-
*USA IBM USA standard (mm/dd/yyyy, hh:mm a.m.,
| base.
hh:mm p.m.)
| 1 All linked files are under selective database
*ISO International Standards Organization (yyyy-
| control if the server has the Datalink File
mm-dd, hh.mm.ss)
| Manager installed.
*EUR IBM European Standard (dd.mm.yyyy,
hh.mm.ss)
| Datalink link control. Whether the file should be linked by
| the Datalink File Manager. The Datalink File Manager is a
*JIS Japanese Industrial Standard Christian Era
(yyyy-mm-dd, hh:mm:ss)
| function that tracks which files are linked to a specific data-
| base file. This value applies to datalink fields. The possible
*SAA SAA timestamp
| values are:
*MDY Month/day/year (mm/dd/yy)
*DMY Day/month/year (dd/mm/yy)
| 0 No link control. *YMD Year/month/day (yy/mm/dd)
| 1 File link control. *JUL Julian (yy/ddd)
*HMS Hour/minute/second (hh:mm:ss)
| Datalink read permission. The check that is done to read
MDYY Month/day/year (mm/dd/yyyy)
| the file. This value applies to datalink fields. If the datalink
DMYY Day/month/year (dd/mm/yyyy)
| link control field is 0 (no link control), this field is not appli-
YYMD Year/month/day (yyyy/mm/dd)
| cable. The possible values are:
JUL4 Long Julian (yyyy/ddd)
| 0 The database controls whether a user has CMDY Century/month/day/year (c/mm/dd/yy)
| read authority. CDMY Century/day/month/year (c/dd/mm/yy)
| 1 The file system controls whether a user has CYMD Century/year/month/day (c/yy/mm/dd)
| read authority. *MY Month/year (mm/yy)
*YM Year/month (yy/mm)
| Datalink recovery. Whether file recovery is done. This *MYY Month/year (mm/yyyy)
| value applies to datalink fields. If the datalink link control *YYM Year/month (yyyy/mm)
| field is 0 (no link control), this field is not applicable. The
| possible values are: Date and time separator. This value applies only to date or
time fields. The possible values are:
| 0 Recovery is not done.
| 1 Recovery is done. / Slash separator
- Dash separator
| Datalink unlink control. The action that is done to a file . Period separator
| during an unlink operation. This value applies to datalink , Comma Separator
| fields. If the datalink link control field is 0 (no link control) or : Colon separator
| the datalink write permission field is 1 (File system control), (blank) Blank separator
| this field is not applicable. The possible values are:
Note: If the date and time separator field returns a blank,
| 0 Restore the file owner and file authorities that the separator may have been determined by the default for
| existed prior to the file link when an unlink the specified value of the date and time format field.
| operation occurs.
| 1 Delete the file when an unlink operation Decimal position. The number of decimal positions. This
| occurs. entry is zero if the field is not numeric.

| Datalink write permission. The check that is done to write | Default value. The default value for this field. The default
| to the file. This value applies to datalink fields. If the | value is defined by the DFT or DFTVAL keyword used in
| datalink link control field is 0 (no link control), this field is not | DDS, or by the WITH DEFAULT clause of the CREATE
| applicable. The possible values are: | TABLE SQL statement. Some examples of returned data
| are:
| 0 The file is blocked from accepting writing.
| 1 The file system controls whether a user has
| write authority.

34-24 AS/400 System API Reference V4R4

 List Fields (QUSLFLD) API

File library name used. The name of the library that con-
| SQL clause DDS keyword Returned by API:
| WITH DEFAULT DFT(value), tained the file.
| value, where where value is:
| value is: File name specified. The file specified in the call to the
API.
| 'ABC' 'ABC' 'ABC'
| +999 +999 +999 File name used. The name of the file where the member
list was found.
| 999 +999
| 999 999 File type. The type of file found.
| -999 -999 -999 BSCF Binary synchronous communications (BSC)
| USER USER file
| Note: This value
CMNF Communications file
| means to use the DDMF Distributed data management file
| User ID as the DKTF Diskette file
| value DSPF Display file
| COCODE ( 'ABC' COCODE ( 'ABC' ICFF Intersystem communications function file
| ) ) LF Logical file
MXDF Mixed file
PF Physical file
Digits. The number of digits. this entry is zero if the field is
PRTF Printer file
not numeric.
SAVF Save file
Edit code. The field edit code. TAPF Tape file

Edit word. The field edit word. Format name. The content and format of the information
returned for each field. The only possible value is:
Edit word length. The length of the edit word used. FLDL0100 Field information
Field column headings CCSID. Graphic fields indicator. Whether this format contains
0 There are no field column headings. graphic fields. The possible values are:
1–65,535 The CCSID for the field column headings. 0 The format does not contain graphic fields.
1 The format does contain graphic fields.
Field data CCSID.
0 There is no field data. Host variable indicator. Whether a query has been defined
1–65,535 The CCSID for the field data. with a host variable or a parameter marker in place of a com-
parison operand (for example, FIELDA > :hostvar) or an
| Field data encoding scheme. The encoding scheme asso- arithmetic operand (for example, FIELDA * 10). Possible
| ciated with the field data CCSID. values follow:

Field edit words CCSID 0 The query definition does not contain a host
variable or a parameter marker.
0 There are no field edit words. 1 The query definition does contain a host vari-
1–65,535 The CCSID for the field edit words. able or a parameter marker.
Field length in bytes. The number of bytes the field occu- Input buffer position. The field’s position within the input
pies. record.
Field name. The name of the field the entry describes. Internal field name. The internal name used to identify the
field the entry describes.
Field text description. The description of the field.
Length of alternative field name. The length of the alterna-
Field text description CCSID.
tive field name definition.
0 There is no field text description.
1–65,535 The CCSID for the field text description. | Length of default value. The length of the default value for
| this field. If the field has no default value, this field is zero.
Record text description CCSID.
| Length of FLDL0200 format. The combined length of all
0 There is no record text description.
| data returned in format FLDL0200. Use this value to access
1–65,535 The CCSID for the record text description.
| the next list data entry.
File library name specified. The library specified in the call
to the API.

Chapter 34. File APIs 34-25

 List Fields (QUSLFLD) API

| Length of user-defined type name. The length of the user- not contain UCS-2 data. For information about UCS-2, see
| defined type name. If the field has no user-defined type, this the International Application Development book.
| field is zero.
| User-defined type name. The name of the user-defined
| Maximum large object field length. The maximum length | type object.
| of data that can be contained for this field. This value
| applies to fields with the BLOB, CLOB or DBCLOB data type. | User-defined type library name. The library containing the
| user-defined type object.
Null-capable fields indicator. Whether this format contains
null-capable fields. The possible values are: Use. How the field is used:

0 The format does not contain null-capable I Input

fields. O Output
1 The format contains null-capable fields. B Both input and output
N Neither
Null values allowed. Whether the result of this field can be
Note: Use is from the program point of view and not neces-
the null value. The possible values are:
sarily the use specified in the DDS that created the file. For
0 The field does not allow the null value. example, *DSPF subfile record fields return "B" even if the
1 The field does allow the null value. field is "O" in the DDS.

Number of DBCS characters. The number of DBCS char- User space library name. The name of the library that con-
acters this field can contain if the field type is graphic data tains the user space that is to receive the generated list.
type. This value does not include the 2 bytes for the variable
length portion of the field. User space name. The name of the user space that is to
receive the generated list.
| Offset to default value. The offset from the beginning of
| format FLDL0200 to the start of the default value for this Variable length field indicator (overlay for MI mapping).
| field. If the field has no default value, this value is zero. Whether the field has been defined as *VARCHAR,
VARLEN, or *VARGRF. Possible values are:
Output buffer position. The field’s position within the
0 The field is not variable length.
output record.
1 The field is variable length.
Override processing. Whether overrides are to be pro-
Variable length fields in format indicator. Whether this
cessed. The possible values are:
format contains variable length fields. The possible values
0 No override processing are:
1 Override processing
0 The format does not contain variable length
fields.
| Pad length for large object. This value applies fields with
| the BLOB, CLOB or DBCLOB data type. This value is the
1 The format contains variable length fields.
| pad length of the buffer for this field.
Error Messages
Record format ID. The record format identifier.
CPF24B4 E Severe error while addressing parameter list.
Record format name specified. The record format speci- CPF3CF1 E
fied in the call to the API. Error code parameter not valid.
CPF3C20 E
Record format name used. The name of this record Error found by program &1.
format. CPF3C21 E
Format name &1 is not valid.
Record length. The length of this record format. CPF3C22 E
Cannot get information about file &1.
Record text description. The text description of this record
CPF3C25 E
format.
Value &1 for file override parameter is not valid.
Record text description CCSID. CPF3C28 E
Record format &3 in file &1 not found.
0 There is no record text description. CPF3C36 E
1–65,535 The CCSID for the record text description. Number of parameters, &1, entered for this API
was not valid.
Reserved. An ignored field.
CPF3C90 E
UCS-2 displayed field length. The display length of a field Literal value cannot be changed.
containing UCS-2 data. This value is zero if the field does

34-26 AS/400 System API Reference V4R4

 List Record Formats (QUSLRCD) API

CPF8100 E All CPF81xx messages could be returned. xx is RCDL0100 Record format name only.
from 01 to FF. RCDL0200 Record format name and additional infor-
CPF9800 E All CPF98xx messages could be signaled. xx is mation. This format requires more
from 01 to FF. system paging and takes longer to
produce than the RCDL0100 format.
RCDL0300 Record format name and device file infor-
List Record Formats (QUSLRCD) API mation. This format requires more
system paging and takes longer to
produce than the RCDL0100 format. This
Required Parameter Group: format is only applicable to device file
types.
1 Qualified user space name Input Char(20)
2 Format name Input Char(8) For more information, see “RCDL0100 List Data Section”
3 Qualified file name Input Char(20) on page 34-28, “RCDL0200 List Data Section” on
4 Override processing Input Char(1) page 34-28 or “RCDL0300 List Data Section” on
page 34-28
Optional Parameter:
Qualified file name
5 Error code I/O Char(*) INPUT; CHAR(20)
The name of the file whose record format names are
Threadsafe: No
placed in the list, and the library in which it is located.
The first 10 characters contain the file name, and the
The List Record Formats (QUSLRCD) API generates a list of second 10 characters contain the library name. You can
record format information contained within the specified file use these special values for the library name:
and places the list in a specified user space. The created list
*CURLIB The job's current library
replaces any existing information in the user space.
*LIBL The library list
You can use the QUSLRCD API with database file types, Override processing
such as *PF, *LF, and *DDMF, and device file types, such as INPUT; CHAR(1)
*DSPF, *TAPF, *DKTF, *PRTF, *SAVF, and *ICFF.
Whether overrides are to be processed. The possible
values are:
Authorities and Locks
0 No override processing
User Space Authority 1 Override processing
*CHANGE
Library Authority
*USE Optional Parameter
File Authority *OBJOPR
Error code
User Space Lock
I/O; CHAR(*)
*EXCLRD
File Lock *SHRRD The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
on page 2-6. If this parameter is omitted, diagnostic
Required Parameter Group and escape messages are issued to the application.
Qualified user space name
INPUT; CHAR(20) Format of the Generated List
The name of the user space that is to receive the gener-
ated list, and the library in which it is located. The first The record format list consists of:
10 characters contain the user space name, and the Ÿ A user area
second 10 characters contain the library name. You can
Ÿ A generic header
use these special values for the library name:
Ÿ An input parameter section
*CURLIB The job's current library
*LIBL The library list Ÿ A header section
Ÿ A list data section
Format name
INPUT; CHAR(8) For details about the user area and generic header, see
“User Space Format for List APIs” on page 2-4. For details
The format of the information returned. The possible
about the other items, see the following sections. For
format names are:

Chapter 34. File APIs 34-27

List Record Formats (QUSLRCD) API

descriptions of each field, see “Field Descriptions” on RCDL0300 List Data Section
page 34-28.
Offset
When you retrieve list entry information from a user space,
you must use the entry size returned in the generic header Dec Hex Type Field
as a displacement to the next list entry. The size of each 0 0 CHAR(10) Record format name
entry may be padded at the end. If you do not use the entry 10 A CHAR(2) Lowest response indicator
size, the result may not be valid. For examples of how to
12 C BINARY(4) Buffer size
process lists, see Appendix A, “Examples.”
16 10 CHAR(20) Record format type
Input Parameter Section 36 24 CHAR(1) Starting line number
37 25 CHAR(1) Separate indicator area
Offset
present
Dec Hex Type Field
0 0 CHAR(10) User space name Field Descriptions:
10 A CHAR(10) User space library name
Buffer size. The user buffer size.
20 14 CHAR(8) Format name
28 1C CHAR(10) File name specified Record text description CCSID.
38 26 CHAR(10) File library name specified 0 There is no record text description.
48 30 CHAR(1) Override processing
1–65,535 The CCSID for the record text description.

File creation date. The date of the file in the format

Header Section CYYMMDDHHMMSS as follows:
C Century, where 0 indicates years 19xx and 1
Offset
indicates years 20xx.
Dec Hex Type Field YY Year
0 0 CHAR(10) File name used MM Month
DD Day
10 A CHAR(10) File library name used
HH Hour
20 14 CHAR(10) File type MM Minute
30 1E CHAR(50) File text description SS Second
80 50 BINARY(4) File text description CCSID File library name specified. The name of the file library
84 54 CHAR (13) File creation date specified in the call to the API.

File library name used. The name of the library that con-
RCDL0100 List Data Section
tained the file. If the library requested was *LIBL or
*CURLIB, this field contains the name of the library where
Offset
the system found the file.
Dec Hex Type Field
File name specified. The name of the file specified in the
0 0 CHAR(10) Record format name
call to the API.

RCDL0200 List Data Section File name used. The name of the file whose record formats
are listed. If override processing was requested, this is the
Offset actual file.
Dec Hex Type Field
File text description. The text description of the file.
0 0 CHAR(10) Record format name
10 A CHAR(13) Record format ID
File text description CCSID.

23 17 CHAR(1) Reserved 0 There is no file text description.

1–65,535 The CCSID for the file text description.
24 18 BINARY(4) Record length
28 1C BINARY(4) Number of fields File type. The type of file found:
32 20 CHAR(50) Record text description BSCF Binary synchronous communications (BSC)
82 52 CHAR(2) Reserved file
CMNF Communications file
84 54 BINARY(4) Record text description
DSPF Display file
CCSID

34-28 AS/400 System API Reference V4R4

 Process Command (QxdaProcessCommandEDRS) API

DDMF Distributed data management file 0 Starting line number is not specified.
DKTF Diskette file 1 Starting line number is specified.
ICFF Intersystem communications function file
LF Logical file User space library name. The name of the library that con-
MXDF Mixed file tains the user space that is to receive the generated list.
PF Physical file
User space name. The name of the user space that is to
PRTF Printer file
receive the generated list.
SAVF Save file
TAPF Tape file
Error Messages
Lowest response indicator. The lowest response indicator
in the file. The possible values are: CPF24B4 E Severe error while addressing parameter list.
CPF3CF1 E
00 No response indicators in the file or response Error code parameter not valid.
indicators are not applicable CPF3CF2 E
01–99 Response indicator Error(s) occurred during running of &1 API.
CPF3C20 E
Number of fields. The number of fields contained in this
Error found by program &1.
record format. You can use the List Field Description
CPF3C21 E
(QUSLFLD) API to retrieve field information about this
Format name &1 is not valid.
record.
CPF3C22 E
Override processing. Whether overrides are to be pro- Cannot get information about file &1.
cessed. The possible values are: CPF3C25 E
Value &1 for file override parameter is not valid.
0 No override processing CPF3C36 E
1 Override processing Number of parameters, &1, entered for this API
was not valid.
Record format name. The name of the format used to list
CPF3C90 E
records. The possible values are:
Literal value cannot be changed.
RCDL0100 Record format name only CPF8100 E All CPF81xx messages could be returned. xx is
RCDL0200 Record format name and additional informa- from 01 to FF.
tion CPF9800 E All CPF98xx messages could be signaled. xx is
RCDL0300 Record format name and device information from 01 to FF.
CPF9872 E Program or service program &1 in library &2
Record format name. The name of this record format. ended. Reason code &3.
Record length. The length of this record format.

Record text description. The text description of this record | Process Command
format. | (QxdaProcessCommandEDRS) API
Reserved. An ignored field.

Record format type. The type of this record format. The | Required Parameter Group:
possible values are:
| 1 Connection handle Input Binary(4)
Normal Normal record | 2 Command Input Char(*)
SFL Subfile record | 3 Length of command Input Binary(4)
SFLMSGRCD | 4 Error code I/O Char(*)
Subfile message record
| Library Name/Service Program: QSYS/QXDAEDRS
SFLCTL Subfile control record
USRDFN User-defined record | Threadsafe: Conditional; see Usage Notes
WINDOW Window record

Separate indicator area present. The existence of a sepa- | The Process Command (QxdaProcessCommandEDRS) API
rate indicator area. The possible values are: | is used to run a system command on the database server
0 No indicator area | system. The command is called exactly as passed, without
1 Indicator area | coded character set identifier (CCSID) conversion.

Starting line number. A starting line number was specified

for this record format. The possible values are:
| Authorities and Locks

Chapter 34. File APIs 34-29

 Process Extended Dynamic SQL (QSQPRCED) API

| Any command
| *USE Required Parameter Group:
| Library of the command
| *EXECUTE 1 SQL communications area Output Char(136)
2 SQL descriptor area Input Char(*)
3 Function template format Input Char(8)
| Required Parameter Group 4 Function template Input Char(*)
5 Error code I/O Char(*)
| Connection handle
| INPUT; BINARY(4) Threadsafe: Conditional; see Usage Notes.
| The handle number of the connection on which to call
| the command. The connection handle must have been
The Process Extended Dynamic SQL (QSQPRCED) API pro-
| generated by the QxdaConnectEDRS API in the current
vides functions to process extended dynamic SQL state-
| job and activation group.
ments in an SQL package object. In particular, this API
| Command provides the user with the only way to do blocked INSERT
| INPUT CHAR(*) using SQLDA.
| The command you want to run entered as a character
| string. If the command contains blanks, it must be Authorities and Locks
| enclosed in apostrophes. The maximum length of the
| string is 32702 characters. There are no authorities or locks for the Process Extended
Dynamic SQL (QSQPRCED) API. Using an existing SQL
| Length of command package requires that you have *OBJOPR and *READ
| INPUT BINARY(4) authority to the package. To use the PREPARE function of
| The length of the command to run. the API, you must have *OBJOPR and *ADD authority to the
package. To use a sort sequence table, you must have
| Error code *USE authority to the table and *USE authority to the library
| I/O; CHAR(*) containing the table.
| The structure in which to return error information. For
| the format of the structure, see “Error Code Parameter”
| on page 2-6.
Required Parameter Group
SQL communications area
OUTPUT; CHAR(136)
| Usage Notes
This is used for returning diagnostic information. It
| This function may be called from the initial thread of a job includes the SQLCODE variable, indicating whether an
| only. error has occurred. If SQLCODE has a value of 0 after
a call to this API, the function was successful.
| Error Messages You should have this space declared in the program that
calls this API. This parameter is considered output
| CPF180C E
because the API uses the space to pass back informa-
| Function &1 not allowed.
tion. The format of the structure is standard and can be
| CPF24B4 E Severe error while addressing parameter list.
included using the INCLUDE SQLCA statement in an
| CPF3C90 E
SQL program. It is described more completely in the
| Literal value cannot be changed.
DB2 UDB for AS/400 SQL Programming and DB2 UDB
| CPF9872 E Program or service program &1 in library &2
for AS/400 SQL Reference books.
| ended. Reason code &3.
| CPFAE14 E SQL descriptor area
| Cannot allocate &1 bytes. INPUT; CHAR(*)
| CPFB750 E Connection handle specified not valid.
This is used for you to pass information about the vari-
| CPFB752 E Internal error in &1 API.
ables being used on a specific SQL statement. The
| CPFB756 E Rollback operation performed.
SQLDA is used for passing the address, data type,
| CPFB757 E The connection is suspended.
length, and coded character set identifier (CCSID) for
| CPFB758 E The EDRS server system has been switched.
variables on an OPEN, EXECUTE, FETCH, or
| xxxnnnn E Any escape message issued by any command
DESCRIBE function.
| may be returned.
The format of the structure is standard and can be
included using the INCLUDE SQLDA statement in an
Process Extended Dynamic SQL SQL program. It is described more completely in the
(QSQPRCED) API

34-30 AS/400 System API Reference V4R4

 Process Extended Dynamic SQL (QSQPRCED) API

DB2 UDB for AS/400 SQL Programming and DB2 UDB

Offset
for AS/400 SQL Reference books.
Dec Hex Type Field
Function template format
83 53 CHAR(1) Date separator
INPUT; CHAR(8)
84 54 CHAR(3) Time format
The format of the function template being used. The
possible values are: 87 57 CHAR(1) Time separator
88 58 CHAR(3) Naming option
SQLP0100 Basic template
SQLP0200 Template for using scrollable cursors or 91 5B CHAR(1) Decimal point
blocked INSERT 92 5C BINARY(2) Blocking factor
SQLP0300 Template for options that may improve 94 5E BINARY(2) Statement length
query performance
96 5F CHAR(*) Statement text
SQLP0400 Template for specifying additional options
that apply to package creation.

For more information, see “SQLP0100 Format,” SQLP0200 Format

“SQLP0200 Format,” “SQLP0300 Format” on
page 34-32, or “SQLP0400 Format” on page 34-32. The following shows the format of the function template
parameter for the SQLP0200 format. For detailed descrip-
Function template tions of the fields in the table, see “Field Descriptions” on
INPUT; CHAR(*) page 34-33.
A structure that determines the function to perform, the
requested statement to process, and the SQL package Offset
to be used. This also contains the text of the statement, Dec Hex Type Field
which is required for the PREPARE function. For the
0 0 CHAR(1) Function
format of this parameter, see “SQLP0100 Format,”
“SQLP0200 Format,” “SQLP0300 Format” on 1 1 CHAR(10) SQL package name
page 34-32, or “SQLP0400 Format” on page 34-32. 11 B CHAR(10) SQL package library name

Error code 21 15 CHAR(10) Main program name

I/O; CHAR(*) 31 1F CHAR(10) Main program library name
The structure in which to return error information. For 41 29 CHAR(18) Statement name
the format of the structure, see “Error Code Parameter” 59 3B CHAR(18) Cursor name
on page 2-6.
77 4D CHAR(1) Open options
78 4E CHAR(1) Using clause for describe
SQLP0100 Format
79 4F CHAR(1) Commitment control
The following shows the format of the function template 80 50 CHAR(3) Date format
parameter for the SQLP0100 format. For detailed descrip-
83 53 CHAR(1) Date separator
tions of the fields in the table, see “Field Descriptions” on
page 34-33. 84 54 CHAR(3) Time format
87 57 CHAR(1) Time separator
Offset 88 58 CHAR(3) Naming option
Dec Hex Type Field 91 5B CHAR(1) Decimal point
0 0 CHAR(1) Function 92 5C BINARY(2) Blocking factor
1 1 CHAR(10) SQL package name 94 5E BINARY(2) Scrollable option
11 B CHAR(10) SQL package library name 96 60 BINARY(2) Position option
21 15 CHAR(10) Main program name 98 62 BINARY(4) Relative record
31 1F CHAR(10) Main program library name 102 66 BINARY(4) Number of rows to insert
41 29 CHAR(18) Statement name 106 6A BINARY(2) Statement length
59 3B CHAR(18) Cursor name 108 6C CHAR(*) Statement text
77 4D CHAR(1) Open options
78 4E CHAR(1) Using clause for describe
79 4F CHAR(1) Commitment control
80 50 CHAR(3) Date format

Chapter 34. File APIs 34-31

Process Extended Dynamic SQL (QSQPRCED) API

SQLP0300 Format SQLP0400 Format

The following shows the format of the function template The following shows the format of the function template
parameter for the SQLP0300 format. For detailed descrip- parameter for the SQLP0400 format. For detailed descrip-
tions of the fields in the table, see “Field Descriptions” on tions of the fields in the table, see “Field Descriptions” on
page 34-33. page 34-33.

Offset Offset
Dec Hex Type Field Dec Hex Type Field
0 0 CHAR(1) Function 0 0 CHAR(1) Function
1 1 CHAR(10) SQL package name 1 1 CHAR(10) SQL package name
11 B CHAR(10) SQL package library name 11 B CHAR(10) SQL package library name
21 15 CHAR(10) Main program name 21 15 CHAR(10) Main program name
31 1F CHAR(10) Main program library name 31 1F CHAR(10) Main program library name
41 29 CHAR(18) Statement name 41 29 CHAR(18) Statement name
59 3B CHAR(18) Cursor name 59 3B CHAR(18) Cursor name
77 4D CHAR(1) Open options 77 4D CHAR(1) Open options
78 4E CHAR(1) Using clause for describe 78 4E CHAR(1) Using clause for describe
79 4F CHAR(1) Commitment control 79 4F CHAR(1) Commitment control
80 50 CHAR(3) Date format 80 50 CHAR(3) Date format
83 53 CHAR(1) Date separator 83 53 CHAR(1) Date separator
84 54 CHAR(3) Time format 84 54 CHAR(3) Time format
87 57 CHAR(1) Time separator 87 57 CHAR(1) Time separator
88 58 CHAR(3) Naming option 88 58 CHAR(3) Naming option
91 5B CHAR(1) Decimal point 91 5B CHAR(1) Decimal point
92 5C BINARY(2) Blocking factor 92 5C BINARY(2) Blocking factor
94 5E BINARY(2) Scrollable option 94 5E BINARY(2) Scrollable option
96 60 BINARY(2) Position option 96 60 BINARY(2) Position option
98 62 BINARY(4) Relative record 98 62 BINARY(4) Relative record
102 66 BINARY(4) Number of rows to insert 102 66 BINARY(4) Number of rows to insert
106 6A CHAR(1) Direct map 106 6A CHAR(1) Direct map
107 6B CHAR(1) Reuse SQLDA 107 6B CHAR(1) Reuse SQLDA
108 6C CHAR(1) Name check 108 6C CHAR(1) Name check
109 6D CHAR(1) Use pointers 109 6D CHAR(1) Use pointers
110 6E CHAR(1) WITH HOLD 110 6E CHAR(1) WITH HOLD
111 6F CHAR(18) User-defined field 111 6F CHAR(18) User-defined field
129 81 CHAR(10) Close file name 129 81 CHAR(10) Close file name
139 8B CHAR(10) Close library name 139 8B CHAR(10) Close library name
149 95 CHAR(1) Reopen 149 95 CHAR(1) Reopen
150 96 CHAR(1) Use performance area 150 96 CHAR(1) Use performance area
151 97 CHAR(5) Reserved 151 97 CHAR(5) Reserved
156 9C BINARY(4) Statement text CCSID 156 9C BINARY(4) Statement text CCSID
160 A0 PTR(SYP) SQL-package system 160 A0 PTR(SYP) SQL-package system
pointer pointer
176 B0 PTR(SYP) Main-program system 176 B0 PTR(SYP) Main-program system
pointer pointer
192 C0 BINARY(2) Statement length 192 C0 CHAR(10) Sort sequence table name
194 C2 CHAR(*) Statement text

34-32 AS/400 System API Reference V4R4

 Process Extended Dynamic SQL (QSQPRCED) API

Ÿ May reduce the amount of time required

Offset
to retrieve the first row of data for a
Dec Hex Type Field query.
202 CA CHAR(10) Sort sequence library name
Ÿ Stops the database manager from
212 D4 CHAR(10) Language identifier retrieving a block of data rows that is not
222 DE CHAR(1) Allow copy of data used by the program when only the first
few rows of a query are retrieved before
223 DF CHAR(1) Allow blocking
the query is closed.
224 E0 BINARY(2) Statement length
Ÿ Can degrade the overall performance of a
226 E2 CHAR(*) Statement text query that retrieves a large number of
rows.

Field Descriptions L *ALLREAD: Rows are blocked for read-only

cursors if N or C is specified on the commit-
Allow copy of data. Whether a copy of the data can be ment control field. All cursors in a program
used in a SELECT statement. The valid values follow: that are not explicitly able to be updated are
opened for read-only processing even though
A A copy of the data is used only when neces-
EXECUTE or EXECUTE IMMEDIATE state-
sary.
ments may be in the program.
S The system determines whether to use the
data retrieved directly from the database or to If you specify L, the following occurs:
use a copy of the data. The decision is based Ÿ Allows record blocking under commitment
on which method provides the best perfor- control level C in addition to the blocking
mance. If commitment control level is C or S allowed for S.
and the Allow Blocking field is not L, or if the
commitment control level is A or R, then a Ÿ Can improve the performance of almost
copy of the data is used only when it is neces- all read-only cursors in programs, but
sary to run the query. limits queries in the following ways:
N A copy of the data is not allowed. If a tempo- – A ROLLBACK statement or
rary copy of the data is required to perform ROLLBACK HOLD SQL statement
the query, an error message is returned. does not reposition a read-only
cursor when L is specified.
The allow copy of data value is required for function 1. It is
ignored for other functions. – Dynamic running of a positioned
UPDATE or DELETE statement (for
Allow blocking. Whether the database manager can use example, using EXECUTE IMME-
record blocking, and the extent to which blocking can be DIATE) cannot be used to update a
used for read-only cursors. The valid values follow: row in a cursor unless the DECLARE
statement for the cursor includes the
S *READ: Records are blocked for read-only
FOR UPDATE clause.
retrieval of data for cursors the following con-
ditions are met:
The allow blocking value is required for function 1. It is
Ÿ N is specified for the commitment control ignored for other functions.
field, which indicates that commitment
control is not used. Blocking factor. The number of records to be passed on a
Ÿ The cursor is declared with a FOR blocked FETCH request. The same number should be used
FETCH ONLY clause or there are no on the OPEN and the FETCH request. The blocking factor is
dynamic statements that could run a posi- required for functions 4 and 5. It is ignored for other func-
tioned UPDATE or DELETE statement for tions.
the cursor.
Close file name. The name of the file for which all pseudo-
You can specify S to improve the overall per- closed open data paths should be closed. The file name
formance of queries that meet the above con- must be the system file name. It cannot be an SQL long
ditions and retrieve a large number of records. table name. If all pseudo-closed open data paths for the job
F *NONE: Rows are not blocked for retrieval of are to be closed, the close file name and the close library
data for cursors. If you specify F, the fol- name should be specified as *ALL. The close file name is
lowing occurs: required for function B. It is ignored for other functions.

Ÿ Guarantees that the data retrieved is If the close library name is *NUMBER or *THRESHOLD, then
current. the first 4 bytes of close file name should contain an integer
value. For *NUMBER, the value indicates the number of

Chapter 34. File APIs 34-33

Process Extended Dynamic SQL (QSQPRCED) API

pseudo-closed cursors to close. For *THRESHOLD, the Decimal point. The decimal point for numeric constants in
value indicates the threshold of pseudo-closed cursors that SQL statements. The valid values are:
should remain following the closing of pseudo-closed cursors.
. Period separator
Close library name. The library of the close file name. If
, Comma separator
the close file name is specified as *ALL, the close library
The decimal point is required for function 1. It is ignored for
name should be *ALL as well. The close library name is
other functions.
required for function B. It is ignored for other functions.
Direct map. Whether the data that is retrieved is to be
*NUMBER indicates to close a specified number of pseudo-
moved directly into the user area. The possible values
closed cursors. *THRESHOLD indicates to continue closing
follow:
pseudo-closed cursors until a specified threshold is reached.
Y Map the data to the user's area by using a
Commitment control. The commit level to be used. The single move operation. SQL obtains the
possible values are: address for the beginning of the user's area
from the first SQLDATA entry of the SQLDA.
C *CHG
The SQLDA must be set up correctly for all
S *CS
fields in the results list in case the direct map
A *ALL
cannot be performed.
N *NONE
N Use the SQLDA definitions to map the data to
The commitment control value is required for function 1. It is the user's area.
ignored for other functions.
The direct map field is optional for function 5. The default
Cursor name. The name of the SQL cursor. The cursor value for direct map is N. It is ignored for all other functions.
name is required for functions 4, 5, 6, and 8. It is ignored for
Function. The function being requested. The possible
other functions.
values follow:
Date format. The format used when accessing date result 1 Build a new package into the specified library.
columns. All output date fields are returned in the format you 2 Prepare a statement into the specified
specify. For input date strings, the value you specify is used package.
to determine whether the date is a valid format. The valid 3 Execute a statement from the specified
values are: package.
USA IBM USA standard (mm.dd.yyyy, hh:mm a.m., 4 Open a cursor defined by a prepared state-
hh:mm p.m.) ment in a package.
ISO International Standards Organization (yyyy- 5 Fetch data from an open cursor.
mm-dd, hh.mm.ss) 6 Close an open cursor.
EUR IBM European Standard (dd.mm.yyyy, 7 Describe a prepared statement in a package.
hh.mm.ss) 8 Close an open cursor and delete the open
JIS Japanese Industrial standard Christian Era data path
(yyyy-mm-dd, hh:mm:ss) 9 Prepare and describe in one step.
MDY Month/day/year (mm/dd/yy) A Inquire as to whether or not a specified state-
DMY Day/month/year (dd/mm/yy) ment has been prepared in the specified
YMD Year/month/day (yy/mm/dd) package.
JUL Julian (yy/ddd) B Actually close pseudo-closed cursors.

The date format is required for function 1. It is ignored for Language identifier. The language identifier to be used
other functions. when *LANGIDUNQ or *LANGIDSHR is specified for the sort
sequence table name. The valid values follow:
Date separator. The separator used when accessing date
*JOB The language identifier for the job is retrieved
result columns. The valid values are:
when the package is created.
/ Slash separator *JOBRUN The language identifier for the job is retrieved
. Period separator when the program is run.
, Comma separator language-id The language identifier to be used by the
- Dash separator program.
blank Blank separator
The language identifier value is required for function 1 when
The date separator is required for function 1. It is ignored for a sort sequence value of *LNGIDUNQ or *LNGIDSHR is
other functions. specified. It is ignored for other functions.

34-34 AS/400 System API Reference V4R4

 Process Extended Dynamic SQL (QSQPRCED) API

Main program library name. The library of the main Bit(2) Update
program. Bit(3) Delete

Main program name. The name of the program repre- For example, if a cursor is only for FETCH statements, the
senting the top program in the SQL application. When this bit pattern should be '10000000'B or hex 80. If update
program completes, all cursors are closed and the SQL envi- capability is needed, the bit pattern should be '10100000'B.
ronment goes away. This program must be on the stack or The syntax in the SQL statement takes precedence over the
an error will occur (SQL0901). The main program name is open options. This means that the FOR UPDATE OF and
required for all functions except 1. This allows you to control FOR FETCH ONLY clauses will be honored, even if they do
the boundary of the application. If you want to scope to an not coincide with the requested open options. The open
activation group, as opposed to the main program name, this options are required for functions 2 and 4. They are ignored
can be done by specifying *ENDACTGRP for the main for other functions.
program name. This special value is only allowed for func-
tion 1. For all other functions, specify the actual main Position option. The positioning option that is used for a
program name. FETCH statement. For options other than NEXT, the cursor
must have been opened as a scrollable cursor. The valid
Main-program system pointer. A system pointer that has options are:
been resolved to point to the main program. This field is
0 FETCH NEXT
ignored if the use pointers field has not been set to Y. If the
1 FETCH PRIOR
use pointers field is specified, this field is used in place of the
2 FETCH FIRST
main program name and main program library name.
3 FETCH LAST
Name check. Whether the statement names and cursor
4 FETCH BEFORE
names are to be completely checked for valid name syntax.
5 FETCH AFTER
The possible values follow:
6 FETCH CURRENT
7 FETCH RELATIVE
Y Check the names for valid name syntax.
N Do not check the names for valid syntax. The position option is required for function 5. It is ignored for
other functions.
The name check field is optional. The default value for name
check is Y. It is ignored for functions 1 and B. Relative record. The number of rows forward or backward
to move before retrieving data. A positive number means
Naming option. The naming convention used for naming forward and a negative number, backward. This is required
objects in SQL statements. The valid values are: when using function 5 (FETCH) with a position option of
SYS library/file syntax FETCH RELATIVE. It is ignored for other options.
SQL collection/table syntax
Reopen. Whether to allow a cursor that is currently open to
The naming option is required for function 1. It is ignored for be reopened. A reopen operation implicitly closes and opens
other functions. the cursor. If a reopen operation is requested on a cursor
that is currently closed, only an open operation is performed
Number of rows to insert. When you request an INSERT (no implicit close takes place). The valid values follow:
statement, this value indicates how many rows are being
0 Do not allow an open cursor to be reopened.
inserted. Blocked INSERT using SQLDA is similar to
1 Allow an open cursor to be reopened.
blocked FETCH using SQLDA. Refer to the DB2 UDB for
AS/400 SQL Reference book for instructions on how to set The reopen field is optional for function 4 with a default of 0.
up the SQLDA to do blocked FETCH. Refer to “Blocked It is ignored for all other functions.
INSERT Using SQLDA Setup Requirements” on page 34-37
for blocked INSERT requirements that are different from Use performance area. Use a performance area internally
blocked FETCH. to store information about the invocation environment. This
option is beneficial in environments where statements are run
The prepared INSERT statement must be a blocked INSERT repeatedly. The valid values follow:
with a parameter marker specified for the number of rows.
0 Do not use the internal performance area.
The number of rows to insert is required for function 3 but is The default value is 0.
used only when the statement is an INSERT. It is ignored 1 Use the internal performance area.
for all other functions.
Reserved. An ignored field.
Open options. The open options used on an SQL cursor.
Reuse SQLDA. Whether the SQLDA is being used again
These are specified using the following bits:
without changes. The possible values follow:
Bit(0) Read
Bit(1) Write
Y SQLDA is being reused without changes. Do
not validate the SQLDA.

Chapter 34. File APIs 34-35

Process Extended Dynamic SQL (QSQPRCED) API

N SQLDA is not being reused. Validate the created through the Create SQL Package (CRTSQLPKG) or
SQLDA. the Create SQL xxx (CRTSQLxxx) commands. Attempted
use of a distributed SQL package results in SQL0827. The
The reuse SQLDA field is optional for functions 3, 4, and 5. SQL package name is required for all functions.
The default value for reuse SQLDA is N. It is ignored for all
other functions. SQL-package system pointer. A system pointer that has
been resolved to point to the SQL package. This option is
Scrollable option. Specified if the cursor is scrollable. The ignored if the use pointers field has not been set to Y. If the
cursor must be opened as scrollable if any FETCH options use pointers field is specified, this field is used in place of the
other than FETCH NEXT are used. The valid values are: SQL package name and SQL package library name.
0 Cursor is not scrollable
Statement length. The length of the SQL statement text
1 Cursor is scrollable
that follows. The statement length is required for function 2.
The scrollable option is required for function 4. It is ignored It is ignored for other functions.
for other functions.
Statement name. The name of the prepared SQL state-
Sort sequence table name. The sort sequence table name ment. The statement name is required for functions 2, 3, 4,
to be used for string comparisons in SQL statements. The 7, 9, and A. It is ignored for other functions.
possible values follow:
Statement text. The SQL statement text that will be pre-
*JOB The sort sequence value for the job is pared. The statement text is required for function 2. It is
retrieved when the package is created. ignored for other functions.
*JOBRUN The sort sequence value for the job is
retrieved when the program is run. Statement text CCSID. The CCSID of the SQL statement
*LANGIDUNQ text that will be prepared in this package. The statement text
The unique-weight sort table for the language CCSID is optional for function 1. It is ignored for other func-
that is specified on the language identifier field tions. If the SQLP0100 or SQLP0200 formats are specified
is used. or if statement text CCSID is 0, the job CCSID is used.
*LANGIDSHR
The shared-weight sort table for the language Time format. The format used when accessing time result
that is specified on the language identifier field columns. All output time fields are returned in the format you
is used. specify. For input time strings, the value you specify is used
*HEX A sort sequence table is not used. The to determine whether the time is a valid format. The valid
hexadecimal values of the characters are values are:
used to determine the sort sequence. HMS Hour/minute/second (hh:mm:ss)
table-name The name of the sort sequence table to be USA IBM USA standard (mm.dd.yyyy, hh:mm a.m.,
used. hh:mm p.m.)
ISO International Standards Organization (yyyy-
The sort sequence table name value is required for function
mm-dd, hh.mm.ss)
1. It is ignored for other functions.
EUR IBM European Standard (dd.mm.yyyy,
hh.mm.ss)
Sort sequence library name. The name of the sort
sequence table can be qualified by one of the following
JIS Japanese Industrial standard Christian Era
(yyyy-mm-dd, hh:mm:ss)
library values:
*LIBL All libraries in the job's library list are searched The time format is required for function 1. It is ignored for
until the first match is found. other functions.
*CURLIB The current library for the job is searched. If
no library is specified as the current library for Time separator. The separator used when accessing time
the job, the QGPL library is used. result columns. The valid values are:
library-name The name of the library to be searched. : Colon separator
. Period separator
The sort sequence library name value is required for function
, Comma separator
1 when a table name is specified for the sort sequence table
blank Blank separator
name value. It is ignored for other functions.
The time separator is required for function 1. It is ignored for
SQL package library name. The library of the package.
other functions.
SQL package name. The name of the SQL package used
Use pointers. Whether the system pointers should be used
as the repository for the extended dynamic SQL statements.
to locate the main program and the SQL package instead of
The SQL package must not be a distributed SQL package
the symbolic names. The possible values follow:

34-36 AS/400 System API Reference V4R4

 Process Immediate SQL Statement (QxdaProcessImmediateEDRS) API

0 Do not use pointers to the main program and Blocked INSERT Using SQLDA Setup
the SQL package. The symbolic names are
Requirements
used to resolve to the objects.
1 Use the main-program and SQL-package Just as in the case of blocked FETCH, the support for
system pointers instead of symbolic names. If blocked INSERT with SQLDA expects the users to have two
1 is specified, the pointers must address the contiguous areas. One is for the data and the other is for the
main program and SQL package. The sym- indicators. The former contains rows of data (the number of
bolic names are ignored. If 1 is specified, rows is given on function 3 calls), and the latter contains
both pointers must be set. rows of indicators.
The use pointers field is optional for all functions. The If none of the columns is null capable, there is no need to
| default value for the use pointers field is 0. have an indicator area. If any of the columns is null capable,
all the columns should be turned into null capable (that is,
User-defined field. Up to 18 bytes of user-defined data that
sqltype in all the sqlvar entries should be an odd number),
is inserted into the database performance monitor table. The
and the row indicator area should have as many indicators
data is only written to the table if you are collecting database
per row as there are columns.
performance monitor statistics by using the Start Database
Monitor (STRDBMON) or the Start Performance Monitor In the SQLDA, the pointer sqldata in all the sqlvar entries
(STRPFRMON) command. The user-defined field is optional should be pointing at the data elements for the first row. Sim-
for all functions. If this field is desired when you collect data, ilarly, the pointer sqlind in all the sqlvar entries should be
you should use it consistently for all functions. pointing at the indicators for the first row, except in the case
where there are no null-capable columns at all.
Using clause for describe. The value to assign to each
SQLNAME variable in the SQLDA. The possible values are:
N Column names Usage Notes
L Column labels
This function is not threadsafe when called in the following
B Both (SQLDA must be allocated for twice as
way:
many entries)
A Any labels that exist Ÿ Using a Data Definition Language (DDL) SQL statement,
for example: CREATE, DROP or ALTER.
These are explained more completely in the DB2 UDB for
AS/400 SQL Reference book. The using clause is required
for functions 7 and 9. It is ignored for other functions. Error Messages
CPF24B4 E Severe error while addressing parameter list.
DLYPRP (delay PREPARE) is an option on an SQL precom- CPF3C21 E
pile operation that cannot be specified on the creation of a Format name &1 is not valid.
package (function 1). DLYPRP(*NO) is used as the default. CPF3C90 E
Literal value cannot be changed.
Refer to the DB2 for AS/400 documentation for a full descrip-
CPF9872 E Program or service program &1 in library &2
tion of all the options.
ended. Reason code &3.
WITH HOLD. Whether the WITH HOLD SQL option should SQL0204 E
be applied to the statement. The possible values follow: &1 in &2 type &3 not found.
SQL0516 E
Y The cursor is not closed as a consequence of Prepared statement &2 not found.
a commit operation. The commit operation SQL0901 E
commits all the changes in the current unit of SQL system error.
work but releases only locks that are not SQL7023 E
required to maintain the cursor. Parameter value not valid.
N The cursor is closed at the time of commit.

The WITH HOLD field is optional for functions 2 and 9. The

default for WITH HOLD is N. It is ignored for all other func- | Process Immediate SQL Statement
tions. | (QxdaProcessImmediateEDRS) API

Chapter 34. File APIs 34-37

 Process Remote Extended Dynamic SQL (QxdaProcessExtDynEDRS) API

| Usage Notes
| Required Parameter Group:
| This function may be called from the initial thread of a job
| 1 Connection handle Input Binary(4) | only.
| 2 SQL statement Input Char(*)
| 3 Length of SQL statement Input Binary(4)
| 4 SQL communications area Output Char(136) | Error Messages
| 5 Error code I/O Char(*)
| CPF180C E
| Library Name/Service Program: QSYS/QXDAEDRS | Function &1 not allowed.
| CPF24B4 E Severe error while addressing parameter list.
| Threadsafe: Conditional; see Usage Notes | CPF3C90 E
| Literal value cannot be changed.
| CPF9872 E Program or service program &1 in library &2
| The Process Immediate SQL Statement | ended. Reason code &3.
| (QxdaProcessImmediateEDRS) API is used to run an SQL | CPFB750 E Connection handle specified not valid.
| statement on the database server. The statement is pro- | CPFB752 E Internal error in &1 API.
| cessed exactly as provided, without coded character set | CPFB756 E Rollback operation performed.
| identifier (CCSID) conversion. | CPFB757 E The connection is suspended.
| CPFB758 E The EDRS server system has been switched.
| Authorities and Locks
| None.
| Process Remote Extended Dynamic SQL
| (QxdaProcessExtDynEDRS) API
| Required Parameter Group
| Connection handle
| INPUT; BINARY(4) | Required Parameter Group:

| The handle number of the connection on which to | 1 Connection handle Input Binary(4)
| process the SQL statement. The connection handle | 2 SQL descriptor area Input Char(*)
| must have been generated by the QxdaConnectEDRS | 3 SQL communications area Output Char(136)
| API in the current job and activation group. | 4 QSQPRCED function tem- Input Char(8)
| plate format
| SQL statement | 5 QSQPRCED function tem- Input Char(*)
| INPUT; CHAR(*) | plate
| 6 Receiver variable Output Char(*)
| The SQL statement to process. | 7 Length of receiver variable Input Binary(4)
| 8 Receiver variable format Input Char(8)
| Length of SQL statement | 9 Additional options Input Binary(4)
| INPUT; BINARY(4) | 10 Error code I/O Char(*)
| The length of the SQL statement passed.
| Library Name/Service Program: QSYS/QXDAEDRS
| SQL communications area
| OUTPUT; CHAR(136) | Threadsafe: Conditional; see Usage Notes
| Returns diagnostic information. It includes the
| SQLCODE variable, indicating whether an error has
| The Process Remote Extended Dynamic SQL
| occurred. If SQLCODE has a value of 0 after a call to
| (QxdaProcessExtDynEDRS) API is used to perform extended
| this API, the function was successful.
| dynamic SQL operations on the database server system.
| The format of this structure is standard and is described | The SQL operations are performed by the Process Extended
| more completely in the DB2 UDB for AS/400 SQL Pro- | Dynamic SQL (QSQPRCED API). For more information, see
| gramming and the DB2 UDB for AS/400 SQL Reference | the Process Extended Dynamic SQL (QSQPRCED) API doc-
| books. | umentation.
| Error code
| I/O; CHAR(*) | Authorities and Locks
| The structure in which to return error information. For | See the Process Extended Dynamic SQL (QSQPRCED) API
| the format of the structure, see “Error Code Parameter” | documentation for authorities required.
| on page 2-6.
| Required Parameter Group

34-38 AS/400 System API Reference V4R4

 Process Remote Extended Dynamic SQL (QxdaProcessExtDynEDRS) API

| Connection handle | Receiver variable format

| INPUT; BINARY(4) | INPUT; CHAR(8)
| The handle number of the connection on which to | The format of the receiver variable template being used.
| perform the extended dynamic SQL operation. The con- | The possible value is:
| nection handle must have been generated by the
| QxdaConnectEDRS API in the current job and activation
| EXDO0100
| Basic receiver variable
| group.
| Additional options
| SQL descriptor area
| INPUT BINARY(4)
| INPUT; CHAR(*)
| The following are valid options, defined in the
| Passes information about the variables being used on a
| qxdaedrs.h header file. The binary OR operation can
| specific SQL statement. The SQLDA is used for passing
| be used to use more than one of these options together.
| the address, data type, length, and CCSID for variables
| on an OPEN, EXECUTE, FETCH, or DESCRIBE func- | 0x00000000 - 0 - QXDA_EXTDYN_NOOPTS
| tion.
| The format of the structure is standard and is described | 0x00000001 - 1 - QXDA_CREATE_OBJECTS
| more completely in the DB2 UDB for AS/400 SQL Pro- | When preparing a statement into an SQL
| gramming and the DB2 UDB for AS/400 SQL Reference | package, create the library and SQL
| books. | package if they do not already exist. This
| option is valid only for QSQPRCED func-
| SQL communications area | tions 2 and 9; it is ignored for all other func-
| OUTPUT; CHAR(136) | tions. When this option is specified, all
| Returns diagnostic information. It includes the | parameters required by the Process
| SQLCODE variable, indicating whether an error has | Extended Dynamic SQL (QSQPRCED) API
| occurred. If SQLCODE has a value of 0 after a call to | for function 1 must be provided in the
| this API, the function was successful. | QSQPRCED function template.
| 0x00000010 - 16 - QXDA_DEFER_OPEN
| The format of this structure is standard and is described
| Defer the open until a fetch is performed,
| more completely in the DB2 UDB for AS/400 SQL Pro-
| when possible. The system will determine if
| gramming and the DB2 UDB for AS/400 SQL Reference | the open can be deferred. This option is
| books.
| valid only for QSQPRCED function 4, and
| QSQPRCED function template format | only when using a remote connection type.
| INPUT; CHAR(8) | It is ignored in all other cases. It will cause
| a failure at fetch time if the fetch imme-
| The format of the function template being used. For
| diately following an open using this option is
| possible values, see the Process Extended Dynamic
| not from the same cursor as the open.
| SQL (QSQPRCED) API documentation. The SQLP0100
| 0x00000100 - 256 - QXDA_FIND_STMT
| and SQLP0200 QSQPRCED formats are not supported
| If this option is specified and the statement
| by this API.
| name parameter of the QSQPRCED func-
| QSQPRCED function template | tion template is blank, a search will be per-
| INPUT; CHAR(*) | formed to see if there is already a prepared
| statement in the specified library and
| Determines the function to perform, the requested state-
| package with the same statement text as
| ment to process, and the SQL package to be used. It
| the current text. If not, a unique statement
| also contains the text of the statement, which is required
| name will be generated and returned in the
| for the PREPARE function. For the format of this
| statement name field of the receiver vari-
| parameter, see the Process Extended Dynamic SQL
| able.
| (QSQPRCED) API documentation.
| Error code
| Receiver variable
| I/O; CHAR(*)
| OUTPUT; CHAR(*)
| The structure in which to return error information. For
| The structure in which to return information about the
| the format of the structure, see “Error Code Parameter”
| connection. For the format of this parameter, see
| on page 2-6.
| “EXDO0100 Format.”

| Length of receiver variable | EXDO0100 Format

| INPUT; BINARY(4)
| The number of bytes that the calling program provides | The following table shows the information returned in the
| for the receiver variable data. | EXDO0100 format. For more details about the fields in this
| table, see “Field Descriptions” on page 34-40.

Chapter 34. File APIs 34-39

 Query (QQQQRY) API

The Query (QQQQRY) API gets a set of database records

| Offset
that satisfies a database query request. Using this API you
| Dec Hex Type Field can do all the things you could do with the Open Query File
| 0 0 BINARY(4) Bytes returned (OPNQRYF) command. You can also perform subqueries,
| 4 4 BINARY(4) Bytes available perform unions, and use SQL host variables.

| 8 8 CHAR(18) Statement name The QQQQRY API can be used to do any combination of the
following database functions:
Ÿ Join records from more than one file, member, and
| Field Descriptions
record format. The join operation that is performed may
be equal or nonequal in nature.
| Bytes available. The length of the information available to Ÿ Calculate new field values by using numeric and char-
| the API to return, in bytes. acter operations on field values and constants.
| Bytes returned. The actual number of bytes returned. Ÿ Group records by like values of one or more fields, and
calculate aggregate functions, such as minimum field
| Statement name. The statement name generated when the value and average field value, for each group.
| QXDA_FIND_STMT option is specified.
Ÿ Select a subset of the available records. Selection can
be done both before and after grouping the records.
| Usage Notes Ÿ Arrange result records by the value of one or more key
fields.
| This function may be called from the initial thread of a job
| only. You can use this API to run a query, create an access plan,
or get information from the query definition template (QDT).
| Error Messages When you run the query, the API uses the information you
provide with the query definition template to extract informa-
| CPF180C E tion and data from the database. Creating an access plan
| Function &1 not allowed. makes it possible to run the query with better performance.
| CPF24B4 E Severe error while addressing parameter list. Checking the query definition template allows you to validate
| CPF3C21 E the values in this query definition template.
| Format name &1 is not valid.
| CPF3C90 E The format definition is part of the query definition template
| Literal value cannot be changed. and can be created and saved with extracted information by
| CPF9872 E Program or service program &1 in library &2 the Retrieve Database File Description (QDBRTVFD) API.
| ended. Reason code &3. When you are finished using the QQQQRY API, you should
| CPFAE14 E close the file (using the Close File (CLOF) command) to free
| Cannot allocate &1 bytes. up resources.
| CPFB750 E Connection handle specified not valid.
| CPFB752 E Internal error in &1 API. Another part of the query definition template is the access
| CPFB756 E Rollback operation performed. plan for the query. Using this API with the Create Query
| CPFB757 E The connection is suspended. Access Plan (CRTQAP) value of the query option requested
| CPFB758 E The EDRS server system has been switched. parameter, you can build an access plan to more efficiently
| CPFB759 E Cursor not valid for operation. run a query more than once. You can then use the access
plan control block parameter to point to the access plan.
This greatly improves the time it takes to perform subsequent
Query (QQQQRY) API runs of this query using this API and the RUNQRY option.
Every time a query is run, the system first checks to see if an
access plan has been specified. If one has, that is what is
Required Parameter Group: used to get the data requested by the query. If no access
plan has been specified, a new one is built dynamically.
1 Query option requested Input Char(10)
2 User file control block I/O Char(*) DCVF section “Defining Queries” on page A-15 provides
3 Query definition template I/O Char(*) several examples that use the QQQQRY API.
4 Literal values I/O Char(*)
5 Access plan control block I/O Char(48)
6 Error code I/O Char(*) Authorities and Locks
User Space Authority
| Threadsafe: Conditional; see Usage Notes.
*CHANGE
Library Authority
*EXECUTE

34-40 AS/400 System API Reference V4R4

 Query (QQQQRY) API

File Authority *OBJOPR the CRTQAP query option. The format for this param-
User Space Lock eter is:
*SHRRD
PTR(SPP) A space pointer that indicates the area of
storage that contains the access plan.
Required Parameter Group This area must begin on a 16-byte
boundary and be all zeros.
Query option requested
Bin(4) The size of storage needed to contain the
INPUT; CHAR(10)
access plan.
One of three options to be used: Char(28) Reserved.
RUNQRY Run query Error code
CRTQAP Create query access plan I/O; CHAR(*)
CHKQDT Check query definition templates
The structure in which to return error information. For
User file control block the format of the structure, see “Error Code Parameter”
I/O; CHAR(*) on page 2-6.
One or more selected options for input and output of the
specified query. This parameter need only be used Data Structures
along with the RUNQRY query option. See “User File
Control Block (QDBUFCB_T) Structure” on page 34-66 The QQQQRY API uses information in four structures to
for a list of available options. carry out a query. All structures are used together to
perform the function you have selected using the query
Query definition template option requested parameter. The names of these structures
I/O; CHAR(*) are:
The information required to create objects that are used QDBQH_T Query definition template
to query a database. It contains feedback information Qdb_Qddfmt_t
from the creation of objects. If a pointer to the access Format definition template
plan is specified, the corresponding query definition tem- QDBUFCB_T User file control block
plates must also be specified. QQQVALS_T Values for query variable fields
Literal values The following sections show you in a general way how this
I/O; CHAR(*) information is structured.
This parameter is used to put into effect SQL host vari-
Query Definition Template (QDBQH_T): The query
ables. When SQL host variables are used, this is a list
definition template provides information about the query that
of constant values used to run a query. If this parameter
is to be performed. Figure 34-1 on page 34-42 shows the
is to be ignored, a null pointer can be specified for the
general layout of this format.
parameter. Once the literal value is specified on a call,
it must always be specified. Notice the box marked with a .1/ in Figure 34-1 on
Access plan control block page 34-42. The topic “Format Definition Template
I/O; CHAR(48) (Qdb_Qddfmt_t)” on page 34-65 provides the layout of the
entire record format specification.
A string of bytes that point to the access plan control
block and give the size the access plan requires. This The offsets and descriptions of all the fields contained in this
parameter must be specified for the RUNQRY query structure are shown in the following tables. You can see this
option when you want to specify an access plan and for source in member QQQQRY in the QSYSINC library.

Chapter 34. File APIs 34-41

 Query (QQQQRY) API

| ┌──────────────┐
Query Definition Header (QDBQH_T): This is the first
| │ File │ structure and is located at offset zero.
| ┌───────────────────────────┤ Name │
| │ │Specification │
| │ │ (QDBQF_T) │
| │ └──────────────┘
| │ ┌──────────────┐
| │ │ Format │
| │ ┌───────────────────────┤ Definition │
| │ │ │Specification │ .1/
| │ │ │(Qdb_Qddfmt_t)│
| │ │ └──────────────┘
| │ │ ┌──────────────┐
| │ │ │ Join │
| │ │ ┌───────────────────┤Specification │
| │ │ │ │ (QDBQJ_T) │
| │ │ │ │ │
| │ │ │ └──────────────┘
| │ │ │ ┌─────────────┐
| │ │ │ │ JREF JOIN │
| │ │ │ ┌────────┤Specification│
| │ │ │ │ │(QDBQ_JREF_T)│
| │ │ │ │ └─────────────┘
| ┌─┴───┴───┴─┐ │ ┌─────────────┐
| │ ├────────┘ │ Record │
| │ │ │ Selection │
| │ Query ├─────────────────┤Specification│
| │ │ │ (QDBQS_T) │
| │ │ └─────────────┘
| │ │ ┌─────────────┐
| │ │ │ Order │
| │Definition ├─────────────────┤ By │
| │ │ │Specification│
| │ │ │ (QDBQK_T) │
| │ │ └─────────────┘
| │ │ ┌─────────────┐
| │ Header │ │ Group │
| │ ├─────────────────┤ By │
| │ (QDBQH_T) │ │Specification│
| │ │ │ (QDBQG_T) │
| └─┬───┬───┬─┘ └─────────────┘
| │ │ │ ┌─────────────┐
| │ │ │ │ Group By │
| │ │ └───────────────────┤ Selection │
| │ │ │Specification│
| │ │ │ (QDBQGS_T) │
| │ │ └─────────────┘
| │ │ ┌─────────────┐
| │ │ │ Set │
| │ └───────────────────────┤ Operation │
| │ │Specification│
| │ │ (QDBQT_T) │
| │ └─────────────┘
| │ ┌─────────────┐
| │ │Query Defini-│
| └───────────────────────────┤tion Template│
| │Offset Table │
| │(QDBQQDTS_T) │
| └─────────────┘
| Figure 34-1. QDBQH_T Format

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqfilo Offset to file, library, format, and member specifications.
4 4 BIN(4) qdbqfldo Offset to the record specifications. 0 indicates that the record specifica-
tions should be taken from the file format. 0 is not valid if there are
multiple files in the file specification and this is not a group-by query.
8 8 BIN(4) qdbqjoio Offset to join specifications. 0 indicates that this is not a join query.
12 C BIN(4) qdbqselo Offset to the record selection specifications. 0 indicates that no record
selection is to occur.
16 10 BIN(4) qdbqkeyo Offset to the order by specifications. 0 indicates that the records are
returned in the file's access path order. If this is a join, the access path
order of the first file in the file array is used. -1 indicates that the result
records are returned in no guaranteed order; running the same query
twice may produce a different result order.
20 14 BIN(4) qdbqgrpo Offset to the group-by-selection specifications. 0 indicates that no
group by is to occur.

34-42 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
24 18 CHAR(4) qdbqdt_1 Reserved.
28 1C BIN(4) qdbqgpso Offset to the group by selection specifications. 0 indicates that no
group by selection is to occur. If field qdbqgrpo is 0, this offset is
ignored.
32 20 CHAR(1) qdbqfin Query completion indicator.
A Query need not be completed before returning. The database
attempts to minimize the entire query and retrieval time.
Selection may be done at I/O time.
F Query need not be complete before returning. The database
attempts to minimize the time to get the first buffer of results.
Selection may be done at I/O time.
M Query need not be complete before returning; however, selection
at I/0 time should be minimized so that long waits for the next
selected records are minimized.
C Query must be completed before returning. If this is a join, the
records must be put in a temporary file.
33 21 CHAR(1) qdbqtem Query temporary result indicator.
N Temporary results should be prohibited.
O Temporary results are allowed but should be used only if neces-
sary to do the query. If a read previous operation can be
requested, then O must be used.
T Temporary results are allowed but should be used only if neces-
sary to do the query. However, if temporary results are used,
then use the last TSORT method, which reads directly from its
sort. This option cannot be specified if a read previous operation
is to be used.
A Temporary results are allowed and should be used if better per-
formance can be achieved by using a temporary result. Use A
when the user does not request previous records to be read.
34 22 CHAR(2) qdbqattr Query attributes.
34 22 0 BIT(1) qdbqnst Status messages. Status messages are never sent for batch jobs.
0 Do not send status messages.
1 Send status messages during query and I/O processing.
34 22 1 BIT(1) qdbqdist Distinct records.
0 Do not produce distinct records.
1 Eliminate duplicate records from the query result.
34 22 2 BIT(1) qdbqpgmd Program-defined files.
0 Ignore interactive data definition utility (IDDU) data definitions for
program-described files.
1 Use IDDU data definitions for program-described files.
34 22 3 BIT(1) qdbqterr Tolerate decimal data errors.
0 Decimal data errors result in an exception being issued.
1 Decimal data errors are ignored.
34 22 4 BIT(1) qdbqdt_2 Reserved.
34 22 5 BIT(1) qdbqintd Integer division.
0 Do not perform integer division.
1 Perform integer division. Division of two integer (binary) numbers
produces a zero precision result.
34 22 6 BIT(1) qdbqdt_3 Reserved.
34 22 7 BIT(1) qdbqchgx Changed files exception.
0 No exception requested.
1 Send an exception when a queried file has changed since cre-
ation of the input access plan.

Chapter 34. File APIs 34-43

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
35 23 0 BIT(1) qdbqsaap Precision reduction (SAA)
0 Allow precision reduction.
1 Disallow reduction of the precision of a derived result. Instead,
reduce significant digits when necessary.
35 23 1 BIT(1) qdbqddmx Distributed data management (DDM) files exception.
0 No exception requested.
1 Send an exception when a queried file is a DDM file.
35 23 2 BIT(1) qdbqraut Resolve authority.
0 Normal authority checking. User must have corresponding data
authority for each open option.
1 Check for at least one data authority (read, add, update, or
delete) regardless of the open options.
35 23 3 BIT(1) qdbqsqlb SQL definition of binary.
0 Binary fields have digits as known by the database.
1 Binary fields in SQL tables and views have 11 digits if the binary
is large and 5 digits if it is small.
35 23 4 BIT(1) qdbqaltc Alternate computation.
0 Do not use alternate computation.
1 Use alternate computation. Some derivations do not overflow as
fast when no precision reduction (SAA) is allowed (qdbqsaap=1).
Also, use the user-defined result field size for one-operation deri-
vations (+, -, *, /).
35 23 5 BIT(1) qdbqsubq The query definition template contains at least one subquery. This
does not span across unions.
35 23 6 BIT(1) qdbqsubx Subcharacters exception. This field specifies what to do if, during
CCSID compatibility processing, a conversion occurs on the data such
that information may be lost or misinterpreted.
0 Allow the query to finish. Information messages are returned if
this condition occurs.
1 Send an exception.
For literals and host variable values, the exception is sent during
the open operation; check the query definition template or create
an access plan of the query if subcharacters were used during
the conversion of the value.
For fields and conversion tables, the error occurs during I/O oper-
ations on the query if subcharacters are used.
35 23 7 BIT(1) qdbqdt_4 Reserved.
36 24 BIN(2) qdbqkunum The NODUPKEY number of key fields. The database does not return
any records with duplicate keys and determines this by using this
number of key fields as a comparison length. -1 indicates that all the
key fields are used as a comparison length. This field is not applicable
if field qdbqkeyo is -1.
38 26 BIN(4) qdbqnumrcd The number of candidate records to process. This number is the
number of records processed before selection. Only the first n records
in the file are processed. The use of this field is for sampling results.
Note that no results may be returned if none of the candidates are
selected. If this is a join, the number of candidates consists of join
records after the join operation. ð indicates that all the records should
be processed.
42 2A BIN(4) qdbqnxqo Offset to next query definition template. This value is 0 if this is the
only query definition template or if this is the last query definition tem-
plate.

34-44 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
46 2E BIN(4) qdbqtoso Offset to the set operation specifications. The set operation specifica-
tions can only be specified on the last query definition template. ð indi-
cates that no set operation is to occur. If only one query definition
query template is specified, this offset is ignored.
50 32 CHAR(4) qdbqdt_5 Reserved.
54 36 BIN(4) qdbqqdto Offset to the query definition template table containing offsets to all
query definition templates between unions.
58 3A CHAR(8) qdbqdt_6 Reserved.
66 42 CHAR(1) qdbqdfmt Date format used as the preferred format for validity checking a date
string or when mapping a character field to a date.
X'FE' Job default format
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'17' MDY format
X'18' DMY format
X'19' YMD format
X'1A' JUL format
When the value of this field is X'FE', the preferred format is obtained
from the job attributes, which have the value X'17', X'18', X'19', or
X'1A'.
67 43 CHAR(1) qdbqdsep Date separator used as the preferred format for validity checking a date
string or when mapping a character field to a date. It is only set when
field qdbqdfmt is X'FE', X'17', X'18', X'19', or X'1A'.
X'00' Job default separator
X'EE'
Implied separator
/ Slash separator
- Dash separator
. Period separator
, Comma separator
Blank Blank separator
When the value of this field is X'00', the preferred separator is
obtained from the job attributes, which are one of the previously defined
values except X'00' and X'EE'. When the value of this field is
X'EE', the implied separator for the format is used.
68 44 CHAR(1) qdbqtfmt The time format used as the preferred format when validity checking a
time string or when mapping a character field to a time.
X'FE'
Job default format
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'1B'
HMS format
When the value of this field is X'FE', the preferred format is obtained
from the job attributes, which will have the value X'1B'.

Chapter 34. File APIs 34-45

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
69 45 CHAR(1) qdbqtsep The time separator used as the preferred separator when validity
checking a time string or when mapping a character field to a time. It is
only set when field qdbqtfmt is X'FE' or X'1B'.
X'00' Job default separator
X'EE'
Implied separator
. Period separator
, Comma separator
Blank Blank separator
: Colon separator
When the value of this field is X'00', the preferred separator is
obtained from the job attributes, which are one of the values previously
defined except X'00' and X'EE'. When the value of this field is
X'EE', the implied separator for the format is used.
70 46 BIN(2) qdbqcsdc The coded character set identifier (CCSID) constant tag. If nonzero,
this specifies the CCSID with which the literals in the query definition
template should be tagged. If this field specifies a single-byte character
set (SBCS) CCSID and a literal has double-byte character set (DBCS)
data, the associated mixed CCSID of the SBCS CCSID is used for the
literal. Conversely, if the literal is SBCS and this field specifies a mixed
or DBCS CCSID, the associated SBCS CCSID is used for the literal.
72 48 CHAR(2) qdbqdt_7 More flags.
72 48 0 BIT(1) qdbqvlit Variable length literal.
0 No
1 Yes
72 48 1 BIT(5) qdbqdt_8 Reserved.
72 48 6 BIT(1) qdbqopta Optimize all indexes over the query files.
0 The optimizer determines how many indexes to consider when
optimizing the query. The optimizer “times out” if the time spent
optimizing becomes significant when compared to the time it
takes for the query to run.
1 Optimize all indexes built over the query files. This may increase
the time it takes for the optimization of the query to occur.
72 48 7 BIT(1) qdbqmapbd Reserved.
73 49 0 BIT(7) qdbqdt_9 Reserved.
73 49 7 BIT(1) qdbq_force Force query records to a temporary result. Note that this is only
_temp honored if set on for the last, outermost (that is, non-subquery) QDT of
a union. It is ignored for all other QDTs of the query.
0 Normal processing.
1 Force results of entire query into a temporary result.
74 4A CHAR(2) QDBQDT_10 Reserved.
76 4C qdbqfbk Query feedback. The following information is returned on successful
completion of the query.
76 4C CHAR(2) qdbqqtyp_t Query status indicators.
76 4C 0 BIT(1) qdbqtemp Temporary result.
0 No temporary result.
1 Temporary result created.
76 4C 1 BIT(1) qdbqcomp Selection completion.
0 Selection is not complete.
1 Selection is complete.
If selection is complete, the open feedback area contains the number of
selected records. If selection is not complete, record selection may be
performed while reading the records and the open feedback may indi-
cate more records than are ultimately selected.

34-46 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
76 4C 2 BIT(1) qdbqdt_11 Reserved.
76 4C 3 BIT(1) qdbqacpi Access plan indicator.
0 No access plan present.
1 Query definition template is or is part of an access plan.
76 4C 4 BIT(1) qdbqsreg This field is set on if the query definition template contains special regis-
ters CURRENT USER, CURRENT SERVER, or CURRENT TIMEZONE.
76 4C 5 BIT(1) qdbqsubw Subcharacters warning. This field specifies whether during CCSID com-
patibility processing, subcharacters are used in the query.
0 No subcharacters are used.
1 Subcharacters are used in the query.
76 4C 6 BIT(1) qdbqsqlt SQL tables.
0 Not all SQL tables.
1 All SQL tables.
76 4C 7 BIT(1) qdbqlblst The library list was used to determine the referenced table. This is pos-
sible due to the use of the Override with Database File (OVRDBF)
command.
77 4D 0 BIT(1) qdbqcurdt The query definition template contains CURRENT DATE, CURRENT
TIME, or CURRENT TIMESTAMP.
77 4D 1 BIT(7) qdbqdt_12 Reserved.
78 4E CHAR(28) qdbqdt_13 Length of query definition structure.
78 4E BIN(4) qdbqdtln Length of query definition.
82 52 CHAR(24) qdbqdt_14 Reserved.
106 6A CHAR(1) qdbqdofmt Date format for output date fields.
X'FE'
Job default format
X'FF'
Format specified with based-on field.
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'17' MDY format
X'18' DMY format
X'19' YMD format
X'1A'
JUL format
If the data type Qddfftyp (see page 34-97) is unknown (X'FFFF') and
this field is X'FF', the format and separator are taken from those speci-
fied with the based-on field. If the data type Qddfftyp is date
(X'000B'), the format and separator are taken from the extension of
record formats Qddfdttf (see page 34-99) and Qddfdtts (see page
34-100). However, if Qddfdttf is X'FF', the format and separator are
taken from qdbqdofmt and qdbqdosep. If either of these fields are not
valid, it is an error. When the value of qdbqdofmt is X'FE', the format
is obtained from the job attributes, which will have the value X'17',
X'18', X'19', or X'1A'.
Qddfftyp, Qddfdttf, and Qddfdtts are part of the QDBRTVFD include.

Chapter 34. File APIs 34-47

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
107 6B CHAR(1) qdbqdosep Date separator used as the output separator for fields. It is only set
when qdbqdofmt is X'FE', X'17', X'18', X'19', or X'1A'.
X'00' Job default separator
X'EE'
Implied separator
/ Slash separator
- Dash separator
. Period separator
, Comma separator
Blank Blank separator
When the value of this field is X'00', the separator is obtained from the
job attributes (any of the preceding values except X'00' and X'EE').
When the value of this field is X'EE', the implied separator for the
format is used.
108 6C CHAR(1) qdbqtofmt Time format for output time fields.
X'FE'
Job default format
X'FF'
Format specified with based-on field.
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'1B'
HMS format
If the data type Qddfftyp (see page 34-97) is unknown (X'FFFF') and
this field is X'FF', the format and separator are taken from those speci-
fied with the based-on field. If the data type Qddfftyp is time
(X'000C'), the format and separator are taken from the extension of
record formats Qddfdttf (see page 34-99) and Qddfdtts (see page
34-100). However, if Qddfdttf is X'FF', the format and separator are
taken from qdbqtofmt and qdbqtosep. If either of these fields are not
valid, it is an error. When the value of qdbqtofmt is X'FE', the format
is obtained from the job attributes, which have the value X'1B'.
Qddfftyp, Qddfdttf, and Qddfdtts are part of the QDBRTVFD include.
109 6D CHAR(1) qdbqtosep Time separator used as the output separator for fields. It is only set
when qdbqtofmt is X'FE' or X'1B'.
X'00' Job default separator
X'EE'
Implied separator
. Period separator
, Comma separator
: Colon separator
When the value of this field is X'00', the separator is obtained from the
job attributes (any of the above values except X'00' and X'EE').
When the value of this field is X'EE', the implied separator for the
format is used.

34-48 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
110 6E CHAR(1) qdbqtsofmt Timestamp format for output timestamp fields.
X'FE'
Job default format
X'FF'
Format specified with based-on field
X'09' SAA timestamp format
If the data type Qddfftyp (see page 34-97) is unknown (X'FFFF') and
this field is X'FF', the format and separator are taken from those speci-
fied with the based-on field. If the data type Qddfftyp is timestamp
(X'000D'), the format and separator are taken from the extension of
record formats Qddfdttf (see page 34-99 and Qddfdtts (see page
34-100). However, if Qddfdttf is X'FF', the format and separator are
taken from qdbqtsofmt and qdbqtsosep. If qdbqtsofmt contains a format
that is not valid, it is an error.
Qddfftyp, Qddfdttf, and Qddfdtts are part of the QDBRTVFD include.
111 6F CHAR(1) qdbqdt_15 Reserved.
112 70 BIN(4) qdbq_optmrows Optimization option. This field tells the optimizer that the user does not
intend to retrieve more than n records from the query result. n can be
any integer as long as it fits in a BIN(4) type. If the optimizer optimizes
for n records, this could improve performance. Specifying a number
does not mean the user cannot retrieve more than n records. It just
tells the optimizer to optimize for only n records. For more information
about the OPTIMIZE clause, see the DB2 UDB for AS/400 SQL Refer-
ence.
116 74 CHAR(12) qdbqdt_16 Reserved.
128 80 BIN(4) qdbq_jrefo Offset to JREF Join specification.
132 84 CHAR(44) qdbqdt_65 Reserved.
176 B0 CHAR(2) qdbq_posnopts The ORed byte containing an indicator for every scrolling option that is
_t used for this query. Scrolling option of next is always assumed.
176 B0 0 BIT(1) qdbq_posnopts Scrolling to previous record is used.
_prior
176 B0 1 BIT(1) qdbq_posnopts Scrolling to first record is used.
_first
176 B0 2 BIT(1) qdbq_posnopts Scrolling to last record is used.
_last
176 B0 3 BIT(1) qdbq_posnopts Scrolling to before the first record is used.
_before
176 B0 4 BIT(1) qdbq_posnopts Scrolling to after the last record is used.
_after
176 B0 5 BIT(1) qdbq_posnopts Retrieval of the current record is used.
_current
176 B0 6 BIT(1) qdbq_posnopts Scrolling to a record relative to the current record is used.
_relative
176 B0 7 BIT(9) qdbqdt_17 Reserved.
178 B2 CHAR(1) qdbq_ext_bits Miscellaneous bits in the query definition header.
178 B2 0 BIT(1) qdbq_ctlblk An indicator that the caller will be control record blocking; therefore,
ignore SEQONLY() overrides.
178 B2 1 BIT(1) qdbq_norolb Rollback HOLD can leave the position of this cursor as unknown.
178 B2 2 BIT(1) qdbq_stream The user of this query attempts to read records from this query as fast
_cursor as possible.
178 B2 3 BIT(4) qdbqdt_54 Reserved.
| 178 B2 7 BIT(1) qdbqdt_18 Reserved.

Chapter 34. File APIs 34-49

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
| 179 B3 CHAR(1) qdbq_ext_bits2 Miscellaneous bits in the query definition header.
| 179 B3 0 BIT(2) qdbqdt_57 Reserved.
179 B3 2 BIT(1) qdbq_trust Trust scrolling option
_posn
0 Query optimizer assumes that any type of cursor positioning may
be done.
1 Settings of qdbq_posnopts can be trusted. The user that built
this QDT has knowingly set the options and could experience
problems if cursor positioning not indicated is attempted. This bit
should be set on with qdbq_posnopts set to '0000'X to give the
query optimizer more flexibility in choosing the best data access
method and also to enable symmetric multiprocessing (SMP)
methods such as parallel table scan and hash join.
179 B3 3 BIT(5) qdbqdt_58 Reserved.
| 180 B4 CHAR(1) qdbq_ext_bits3 Miscellaneous bits in the query definition header.
| 180 B4 0 BIT(1) qdbqdt_62 Reserved.
| 180 B4 1 BIT(1) qdbq_searched_update Indicator if this is a searched UPDATE QDT.
| 180 B4 2 BIT(1) qdbq_searched_delete Indicator if this is a searched DELETE QDT.
| 180 B4 3 BIT(2) qdbqdt_63 Reserved.
| 180 B4 5 BIT(1) qdbq_drvtbl Indicates that this QDT is part of a derived table QDT.
| 180 B4 6 BIT(2) qdbqdt_64 Reserved.
| 181 B5 CHAR(15) qdbqdt_19 Reserved.
196 C4 CHAR(10) qdbpopnid Optional OPENID to identify this query. *FILE indicates the name of
first or only file specified in the file specification. You can also specify a
name to associate with opened query file.
206 CE BIN(4) qdbspcsize API users specify size for space containing all API query definition tem-
plates.
210 D2 BIN(4) qdbqnlss Displacement to QQQNLSS_T structure (page 34-50) used for sort
sequence information. This is an offset from the beginning of the query
definition template. 0 indicates no QQQNLSS_T structure was passed.
For nonviews, if this is a union or subquery, this field is ignored unless
it is the first query definition template (for unions), or the outermost
query definition template (for subqueries).
214 D6 BIN(2) qdbqsrts Sort sequence indicator. Possible values for this field follow. When
you use value 2 or 3, you must include the QQQNLSS_T structure
(page 34-50) at offset qdbqnlss.
0 *HEX
2 The table or CCSID passed in structure QQQNLSS_T.
3 The sort sequence and language identifier passed in structure
QQQNLSS_T.
216 D8 CHAR(5) qdbqdt_53 Reserved.
221 DD CHAR(1) qdbqic Whether query allows index creation.
N Index creation is not allowed.
Y or X'00' Index creation is allowed.
222 DE CHAR(178) qdbqdt_20 Reserved.

Sequence, Tables, Names, and Parameters

(QQQNLSS_T): Sequence, tables, names, and parame-
ters structure. The displacement to this structure from the
beginning of structure QDBQH_T is an entry in the table at
variable qdbqnlss, page 34-50.

34-50 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(42) qqqstb1 Sequence table name, library name, and language identifier.
0 0 CHAR(10) qqqresv2 Reserved.
10 A CHAR(20) qqsrtseq Sort sequence.
10 A CHAR(10) qqqstbnm Table name. Possible special values are:
*JOB The sort sequence of the job.
*LANGIDUNQ
The unique-weight sort sequence table that is associated
with the language identifier requested parameter.
*LANGIDSHR
The shared-weight sort sequence table that is associated
with the language identifier requested parameter.
*HEX The sort sequence according to the hexadecimal value of
the characters.
20 14 CHAR(10) qqqstbnl Library name. Possible special values are:
*LIBL The library list.
*CURLIB The job's current library.
30 1E CHAR(10) qqqlangid Language identifier. Possible values are:
*JOB The language identifier of the job.
xxx 3-character language identifier. Refer to the “Language
and Country Identifiers” in the book International Applica-
tion Development for a complete list of language identi-
fiers supported.
Blank If blank, field qqqsrtseq cannot be *JOB, *LANGIDUNQ,
or *LANGIDSHR.
40 28 CHAR(2) qqqresv3 Reserved.
42 2A CHAR(38) qqqstb2 Reserved.
42 2A CHAR(2) qqqresv4 Reserved.
44 2C CHAR(10) qqqtbnm Reserved.
54 36 CHAR(10) qqqlbnm Reserved.
64 40 CHAR(14) qqqresv5 Reserved.
78 4E BIN(2) qqqtbl_ccsid Sequence table CCSID. This field is only used when either qqqtbl is
specified or qqqstboff is set for a DBCS sort sequence table.
80 50 CHAR(10) qqqstbe1 User-specified DBCS sort sequence information.
80 50 CHAR(1) qqqstbtyp Type of DBCS sort sequence table.
X'00' UCS-2 sort sequence table
81 51 CHAR(1) qqqstbloc Location of DBCS sort sequence table.
X'00' Table is stored at qqqtbl.
X'01' Table is stored at the DBCS sort sequence table offset
(qqqstboff).
82 52 BIN(4) qqqstblen Length of DBCS sort sequence table. If an SBCS sort sequence table
is specified, qqqstblen must be zero.
86 56 BIN(4) qqqstboff Offset to the DBCS sort sequence table from qqqstb1.
90 5A CHAR(22) qqqresv1 Reserved.
112 70 CHAR(256) qqqtbl User-specified sort sequence table.

File Name Specification (QDBQF_T): File name spec-

ification. This structure defines the files, member, and
formats that are used in the query. This structure is
required.

Chapter 34. File APIs 34-51

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 qdbqfhdr File specification header.
0 0 BIN(2) qdbqfilnum The number of files, libraries, formats, and members.
2 2 CHAR(1) qdbqmfop Multiple file option. This field is only applicable if the qdbqfilnum field is
greater than one.
J Inner join. No default values are supplied if a join value does not
exist and no record is returned.
C Partial outer join (file chaining). Default values are supplied if a
join value does not exist.
E Exception join. Default values are supplied if a join value does
not exist. Only records with default values are returned.
3 3 CHAR(1) qdbqmfor Multiple file order option. This field is only applicable if field qdbqfilnum
is greater than one, field qdbqmfop equals J, and there is no file-distinct
processing. For each file specified in the file specifications, qdbqfdst
equals 1. Partial-outer join, exception join, and file-distinct processing
implies no join reordering.
A Join the files in any order. The result order may vary even when
rerunning the same query.
N Join the files in the order they are specified.
4 4 CHAR(1) qdbqdt_21 Flags.
4 4 BIT(1) qdbqmfio Multiple file I/O options allowed through this query.
0 Only allow read operations against the first file in the array
(always read-only for secondary files).
1 Allow insert, update, or delete operations against the first file.
4 4 1 BIT(1) qdbqmfjn Join clause exists. An SQL JOIN clause syntax exists in this query.
4 4 2 BIT(6) qdbqdt_22 Reserved.
5 5 CHAR(11) qdbqdt_23 Reserved.
16 10 ARRAY(32) qdbqn File, library, member, and format array. This structure is defined at
OF QDBQN_T on page 34-52.
CHAR(64)

File, Library, Member, and Format Array

(QDBQN_T): File, library, member and format names
array. This structure defines the file, library, member, and
format names that are used in the query. This structure is
required.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(40) qdbqflmf File, library, member, and record format names.
0 0 CHAR(10) qdbqfile File name. If an override is in effect to another file, the actual file name
is returned in this field.
10 A CHAR(10) qdbqlib Library name. If the special value *LIBL is used, the actual library
name is resolved and returned in this field.
20 14 CHAR(10) qdbqmbr Member name. If the special values *FIRST or *LAST are used, the
actual member name is resolved and returned in this field.
30 1E CHAR(10) qdbqfmt Format name. If the special value *ONLY is used, the actual format
name is resolved and returned in this field.
40 28 CHAR(1) qdbqfflg File specification flags.

34-52 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
40 28 0 BIT(1) qdbqfdst File-distinct flag. This field specifies, for the records that make up the
join secondaries for a join query, whether only the first record or all
records that satisfy the join conditions should participate in the join.
This flag only applies to join secondary files (files 2 through n, where n
equals the number of files in the join).
0 All records participate.
1 Only the first record participates.
40 28 1 BIT(1) qdbqfujn Unique join fanout. This field specifies whether the number of join
records found can exceed 1. This field only applies to join secondary
files (files 2 through n, where n equals the number of files in the join).
0 Multiple join records are allowed.
1 Only one join-to record may be found for this file.
40 28 2 BIT(1) qdbqfgna Reserved.
40 28 3 BIT(1) qdbqfngn Reserved.
40 28 4 BIT(1) qdbqnmch Name change indicator
0 The library, file, or member name in the specified query definition
template (at offset qdbqfilo in structure qdbqh_t, page 34-42) did
not change as a result of an override.
1 The library, file, or member name in the specified query definition
template (at field qdbqfilo, page 34-42) changed due to an over-
ride.
40 28 5 BIT(1) qdbqflbo Library name overridden.
0 The library name in the specified query definition template (at
offset qdbqfilo in structure qdbqh_t, page 34-42) did not change
as a result of an override.
1 The library name in the specified query definition template (at
offset qdbqfilo, page 34-42) changed to *LIBL due to an override,
and the file was found using *LIBL as the library name.
This bit is a feedback bit. The user of the query definition tem-
plate should not set it.
40 28 6 BIT(1) qdbqf_nldft Null or default. The type of values to be returned for unmatched
records of a partial outer or exception join.
0 Return default values
1 Return NULL values
40 28 7 BIT(1) qdbqdt_24 Reserved.
41 29 CHAR(1) qdbqmfvw Reserved.
42 2A CHAR(1) qdbqmfvw_spc Reserved.
| 43 2B BIN(2) qdbqf_qdtnum Index into the array of subquery offsets (QDBQQDT_T) for the derived
| table QDT.
| 45 2D CHAR(19) QDBQDT_25 Reserved.

Record Format Specification (QDBQR_T): Record

format specification. This structure defines the fields that are
used in the query. The structure Qdb_Qddfmt_t is mapped
by member QDBRTVFD in the QSYSINC library. If join is
specified, this specification is required.

Offset
Dec Hex Bit Type Variable Name Field
CHAR(*) QDBQR Record specifications.

Chapter 34. File APIs 34-53

Query (QQQQRY) API

Join Specification (QDBQJ_T): Join specification. specifications can be derived from the record selection spec-
This structure defines how the files are joined by the query. ifications, Cartesian product is used to do the join.
One join specification exists for the entire query definition. A
join specification entry consists of a from-field, a join oper- All join specifications can be given in the record selection
ator, and a to-field. The join specification entries can be specifications. In this case, it is not necessary to provide a
inserted in any order with respect to the file specifications. join specification.

If this is an inner join (the qdbqmfop field equals J, see If this is a partial-outer or exception join (qdbqmfop equals
page 34-52) and no join specifications are given for a partic- C or E) and no join specifications are given for a particular
ular to-file, the system searches the record selection specifi- to-file, the system uses Cartesian product to do the join. In
cations for any possible implied join specifications. If no join addition, only one join operator can be specified for a partic-
ular to-file.

Offset
Dec Hex Bit Type Variable Name Field
0 0 qdbqjhdr Join specifications header.
0 0 BIN(4) qdbqjln Length of this join specification.
4 4 BIN(2) qdbqjknum Number of from-join and to-join field specifications.
6 6 CHAR(10) qdbqdt_26 Reserved.
16 10 ARRAY(1) qdbqjfld Join specification array. Array of fields that define the from and to fields
OF to use when joining. The structure is defined at QDBQJFLD_T on page
CHAR(96) 34-54.
112 70 CHAR(*) QDBQJNXT Join field pair arrays. Displacement to join specifications array from
structure QDBQJ_T (see structure QDBQJFLD_T on page 34-54).

Join Specification Array (QDBQJFLD_T): Join spec-

ification array. This structure is an array of fields that define
the from and to fields to use when joining.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(30) qdbqjfnm Join from field name.
30 1E BIN(2) qdbqjfnum Field join reference number. 0 indicates that the QDBQR_T format (see
page 34-53) is searched for the external field name. If the field is not
found, the formats of the files in the file specification are searched. A
value in this field indicates that the external field name is to be found in
the file format referenced by using this value as an index into the file
name specification structure, qdbqf_t, (see page 34-51). In any case,
the field found must exist in a file joined prior to this file.
32 20 CHAR(2) qdbqdt_27 Reserved.
34 22 CHAR(2) qdbqjop Join option.
EQ Equal
GT Greater than
LT Less than
NE Not equal
GE Greater than or equal
LE Less than or equal
36 24 CHAR(30) qdbqjtnm Join to field name. Note that only character and any DBCS fields may
be joined to character and any DBCS fields, and only numeric fields
may be joined to numeric fields. The lengths of the two fields need not
be the same. However, if they are different, a warning is sent to the
user indicating that padding occurred.

34-54 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
66 42 BIN(2) qdbqjtnum Field join reference number. 0 indicates that the QDBQR_T format (see
page 34-53) is searched for the external field name.
If the field is found, it must have been completely derived from the file
associated with this join specification. If the field is not found, the
format of the file associated with this join specification is searched.
A value in this field indicates that the external field name is to be found
in the file format referenced by using this value as an index into the file
list. This value must reference the file associated with this join specifi-
cation.
68 44 CHAR(1) qdbqjpfmt Reserved.
69 45 CHAR(1) qdbqjpsep Reserved.
70 46 BIT(1) qdbqjfprf Reserved.
70 46 1 BIT(1) qdbqjvw Reserved
70 46 2 BIT(1) qdbqj_type_sup Join type specified. The type of join is specified in field qdbqj_type.
70 46 3 BIT(5) qdbqdt_oj Reserved.
71 47 CHAR(1) qdbqj_type Type of join.
J Inner join
C Partial outer join
E Exception join
72 48 CHAR(24) qdbqdt_28 Reserved.

JREF Join Specification (QDBQ_JREF_T): JREF

Join specification. This structure can be used to define the
order in which the files are to be joined. It can also be used
to specify any join selection needed to implement the join.
Two files (or join results) are specified along with the appro-
priate join type to be used to join together the two operands.
An offset can also be specified to the Selection Specifica-
tions (QDBQS) that will define the join criteria that applies to
the operands.

Offset
Dec Hex Bit Type Variable Name Field
0 0 qdbq_jref_hdr JREF Join specifications header.
0 0 BIN(4) qdbq_jref_len Length of this JREF join specification.
4 4 BIN(2) qdbq_jref# Number of JREF Join entries.
6 6 CHAR(10) qdbqdt_66 Reserved.
16 10 CHAR(*) qdbq_jref_spec Start of the JREF Join entries. The structure is defined at
QDBQ_JREF_ENTRY_T on page 34-55.

JREF Join Entry (QDBQ_JREF_ENTRY_T): JREF

Join Entry.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qdbq_jref_entry_type JREF Join entry type.
0 Join operand
2 Join operator
2 2 CHAR(*) qdbq_jref_item JREF Join items. The structure is defined at
QDBQ_JREF_OPERAND_T and QDBQ_JREF_OPERATOR_T on page
34-55.

Chapter 34. File APIs 34-55

Query (QQQQRY) API

JREF Join Operand (QDBQ_JREF_OPERAND_T):

JREF Join entry operand.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qdbq_jref_file# JREF Join reference number. The value in this field is used to identify
the entry in the QDBQN array associated with this file.
2 2 CHAR(8) qdbqdt_67 Reserved.

JREF Join Operator (QDBQ_JREF_OPERATOR_T):

JREF Join entry operator.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbq_jref_jselo JREF Join entry offset. Offset to the join selection for this JREF Join
predicate. The join selection is defined by the Selection Specifications
(QDBQS).
4 4 CHAR(1) qdbq_jref_jtype JREF Join type. Type of the join specified for this JREF Join predicate.
J Inner join
C Left partial outer join
E Exception join
5 5 CHAR(5) qdbqdt_68 Reserved.

Record Selection Specification (QDBQS_T): Record

selection specification. This structure defines the selection
specifications for the files being queried. Selection on the file
is done before grouping. If selection is desired on group by
results, see structure QDBQGS_T on page 34-63.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqsl Selection specifications length. This is the total length of all selection
specifications.
4 4 BIN(2) qdbqsnum Number of selection specifications.
6 6 CHAR(10) qdbqdt_29 Reserved.
16 10 CHAR(*) qdbqspec Start of selection specifications. Displacement to selection item specifi-
cations array from structure QDBQS_T (see structure QDBQSIT_T on
page 34-56).

Selection Item Specifications (QDBQSIT_T):

Selection item specifications. This structure is defined at
field qdbqspec in structure QDBQS_T (page 34-56).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqslen Selection item length. This length includes the length (QDBQSIT_T)
plus the length of the selection item structure.

34-56 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
4 4 BIN(2) qdbqsitt Selection item type.
0 Field operand
1 Constant operand
2 Operator
3 Subquery operand
4 Null operand (SAA). This operand is used for is null and is
not null functions. Only equal and not equal operators are
allowed.
6 6 CHAR(*) qdbqsitm Selection item. This field is overlaid by the sequence of selection field
structures.

Selection Field Operand (QDBQSOPF_T): Selection

field operand. This structure overlays field qdbqsitm in struc-
ture QDBQSIT_T (page 34-57).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(30) qdbqsofn Field name. The field name must be an external name.
30 1E BIN(2) qdbqsofj Field join reference number. 0 indicates that the QDBQR_T format (see
page 34-53) is searched for the external field name. If the field is not
found, the formats of the files in the file specification are searched. If
the field name is found in more than one file format, an error is sig-
naled.
A value in this field indicates that the external field name is to be found
in the file format referenced by using this value as an index into the file
list.
32 20 BIN(2) qdbqsoqt Index into the query-definition-template table for the correlated field's
associated query definition template. Use zero for noncorrelated fields.
34 22 CHAR(24) qdbqdt_30 Reserved.

Selection Field Subquery Operand

(QDBQSOPS_T): Selection field subquery operand. This
structure overlays field qdbqsitm in structure QDBQSIT_T
(page 34-57).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qdbqssub Index into the query-definition-template offset table for the subquery's
query definition template.
2 2 CHAR(1) qdbqstyp Subquery operator qualifier.
X'00'
Use the qdbqsop field only (see page 34-60)
X'01'
ALL
X'02'
ANY or SOME
Valid values for qdbqsop when qdbqstyp equals 00 are:
Basic predicate 0001–0006
Exists 0045
In 0046
Valid values for qdbqsop when qdbqstyp is not equal to 00 are:
Operator 0001–0006
3 3 CHAR(23) qdbqdt_31 Reserved.

Chapter 34. File APIs 34-57

Query (QQQQRY) API

Selection Constant Operand (QDBQSOPC_T):

Selection Constant Operand. This structure overlays field
qdbqsitm in structure QDBQSIT_T (page 34-57).

Offset
Dec Hex Bit Type Variable Name Field
CHAR qdbqsoch Constant operand header.
(32793)
0 0 BIN(4) qdbqsocl Constant operand byte length. This only includes the length of the con-
stant in field qdbqsovl including apostrophes (see page 34-60).
4 4 CHAR(1) qdbqdt_32 Constant attributes.
4 4 0 BIT(1) qdbqsoci DBCS open constant.
0 This constant is not a DBCS-open literal.
1 This constant is a DBCS-open literal.
4 4 1 BIT(1) qdbqdt_33 Reserved.
4 4 2 BIT(1) qdbqsocc Character constant type.
0 Character string in apostrophes. The character constant is brack-
eted by apostrophes and any imbedded apostrophes must be
represented by two apostrophes.
1 Character string not in apostrophes. The character constant is
not bracketed by apostrophes.
If it is determined during query processing that the constant should be
numeric and if field qdbqsoac in this table is 0, this bit is ignored.
4 4 3 BIT(1) qdbqsoac Character constant.
0 Do not assume that this is a character constant. Determination of
the type of constant is made during query processing.
1 Assume that this is a character constant.
4 4 4 BIT(1) qdbqsoco DBCS-only constant.
0 This constant is not DBCS-only.
1 This constant is DBCS-only.
4 4 5 BIT(1) qdbqsosr Special register.
0 This constant operand is not a special register.
1 This constant operand is a special register, defined by the
qdbqsorc field.
4 4 6 BIT(1) qdbqsonl SAA NULL indicator.
0 This constant operand is not a NULL literal.
1 This constant operand is a NULL literal.
The query definition template is synchronized with the format descrip-
tion.
4 4 7 BIT(1) qdbqdt_34 Reserved.
5 5 CHAR(1) qdbqsorc Special register constant. This field is defined by special register con-
stants declared in the record format definition. This field can only be
specified if field qdbqsosr is on.
X'01' User
X'02' Current date
X'03' Current time
X'04' Current timestamp
X'05' Current time zone
X'06' Current server

34-58 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
6 6 CHAR(1) qdbqsoft Date, time, timestamp, format attribute. This field applies only to date,
time, or timestamp literals.
X'FE' Job default
X'FF' Determine format
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'09' SAA timestamp
X'17' MDY format
X'18' DMY format
X'19' YMD format
X'1A' JUL format
X'1B' HMS format
X'1D' YYYYNNN format
X'1E' YYYYMMDDHHMMSS format
When the value of this field is X'FF', the format and separator speci-
fied in the query-definition-template header (either the qdbqdfmt field,
page 34-45, or the qdbqtfmt field, page 34-45, and either the qdbqdsep
field, page 34-45, or the qdbqtsep field, page 34-45,) for a date or time
literal is used first in determining the format and separator of the literal.
When the value of this field is X'FE' for a date or time literal, the
format and separator are determined using the job attributes. The
format value may be X'17', X'18', X'19', X'1A', or X'1B'. The sep-
arator specified for qddfdvsp (see page 34-108) is used first in deter-
mining the format and separator.
When the value of this field is X'FE' for a timestamp literal, the SAA
timestamp format is used as the format of the literal.
7 7 CHAR(1) qdbqsosp Date and time separator. This field applies only to date or time literals.
It should only be set when the qdbqsoft field is X'FE', X'17', X'18',
X'19', X'1A', or X'1B'.
X'00' Job default separator
X'EE' Implied separator
/ Slash separator
- Dash separator
. Period separator
, Comma separator
Blank Blank separator
: Colon separator
When the value of this field is X'00', the separator is obtained from the
job attributes, which will be one of the preceding values except X'00'
or X'EE'. When the value of this field is X'EE', the implied separator
for the format is used.
8 8 CHAR(2) qdbqdt_35 Reserved.
10 A BIN(2) qdbqsocd CCSID value for this literal. If not set to zero, the literal will be tagged
with this CCSID. Otherwise, the literal will be tagged with the CCSID
specified in the query-definition-template header (see page 34-42) or
the job default, in that order. This field is only valid for character,
DBCS-open, DBCS-only, DBCS-graphic, and UCS-2 literals.
12 C CHAR(1) qdbqdt_36 Reserved.
12 C 0 BIT(2) qdbqdt_37 Reserved.
12 C 2 BIT(1) qdbqglit An indicator that the constant is a DBCS-graphic or UCS-2 literal. If
this field is a UCS-2 literal, qdbqsocd must be set to a valid UCS-2
CCSID, or qdbqsocd must be zero and qdbqcsdc (see “Query Definition
Header (QDBQH_T)” on page 34-42) must be set to a valid UCS-2
CCSID.
12 C 3 BIT(5) qdbqdt_38 Reserved.

Chapter 34. File APIs 34-59

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
13 D CHAR(29) QDBQDT_39 Reserved.
42 2A CHAR qdbqsovl Operand value. The operand value must be in external form.
(32751)

Selection Operator Item (QDBQSOPR_T): Selection

Operator Item. This structure overlays field qdbqsitm in
structure QDBQSIT_T (page 34-57).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(2) qdbqsop Operators.
Relational operators:
X'0001' Equal
X'0002' Not equal
X'0003' Greater than or equal
X'0004' Less than or equal
X'0005' Greater than
X'0006' Less than
X'0007' Range (inclusive)
X'0041' Scan
X'0042' Wildcard scan
X'0043' Values
X'0045' Exists
X'0046' In
Boolean operators:
X'000B' OR
X'000C' XOR
X'000D' AND
X'000E' NOT
Case selection operators:
X'0018' WHEN
X'001B' ELSE
Case operators are only valid when specified as part of a case selection
specification.
2 2 CHAR(1) qdbqswc1 Wildcard value for any single character. This character indicates the
value in the character string operand that should be interpreted as
matching any single character. This field is only applicable if the
qdbqsop field is a wildcard scan.
3 3 CHAR(1) qdbqswc2 Wildcard value for any number of characters. This character indicates
the value in the character string operand that should be interpreted as
matching any number of characters. This field is only applicable if the
qdbqsop field is a wildcard scan.
4 4 BIN(2) qdbqvalcnt Values operand count. This count reflects the number of selection con-
stant operands (values) associated with the values operator. This count
must be set if the operator is values and is ignored for all other opera-
tors.
6 6 CHAR(1) qdbqdt_55 Selection operator flags.
6 6 0 BIT(1) qdbqescp Wildcard escape character indicator. This field is valid only for wildcard
scan.
0 There is no escape character.
1 There is an escape character specified for the wildcard scan
operator by using the third operand.
6 6 1 BIT(1) qdbqdt_56 Reserved.

34-60 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
6 6 2 BIT(1) qdbqsopr_ext Selection operator extension area indicator.
0 Operator extension area (QDBQSOP3_T) does not exist.
1 Operator extension area (QDBQSOP3_T) exists.
6 6 3 BIT(5) qdbqdt_60 Reserved.
7 7 CHAR(3) qdbqdt_40 Reserved.
Note: The following fields are not present in a query definition restored from a System/38.
10 A CHAR(14) qdbqsop2 Wildcard value for double-byte characters
10 A CHAR(2) qdbqsdbl Wildcard value for any one double-byte character. This value indicates
the value in the DBCS string operand that should be interpreted as
matching any one double-byte character. This field is only applicable if
field qdbqsop is a wildcard scan and string operand is a DBCS or
graphic pattern.
12 C CHAR(2) qdbqsdb2 Wildcard value for any number of double-byte characters. This value
indicates the value in the double-byte string operand that should be
interpreted as matching any number of double-byte or single-byte char-
acters. This field is only applicable if field qdbqsop is a wildcard scan
and the string operand is a DBCS or graphic pattern.
14 E CHAR(3) qdbqdt_41 Reserved.
17 11 CHAR(2) qdbqsuo1 Half-width wildcard value for any one double-byte UCS-2 character.
This value indicates what value in the UCS-2 operand matches any one
double-byte UCS-2 character. This field is only applicable if qdbqsop is
a wildcard scan and the pattern is a UCS-2 parameter marker, host var-
iable value, or constant.
19 13 CHAR(2) qdbqsuo2 Full-width wildcard value for any one double-byte UCS-2 character.
This value indicates what value in the UCS-2 operand matches any one
double-byte UCS-2 character. This field is only applicable if qdbqsop is
a wildcard scan and the pattern is a UCS-2 parameter marker, host var-
iable value, or constant.
21 15 CHAR(2) qdbqsum1 Half-width wildcard value for any number of double-byte UCS-2 charac-
ters. This value indicates what value in the UCS-2 operand matches
any number of double-byte UCS-2 characters. This field is only appli-
cable if qdbqsop is a wildcard scan and the pattern is a UCS-2 param-
eter marker, host variable value, or constant.
23 17 CHAR(2) qdbqsum2 Full-width wildcard value for any number of double-byte UCS-2 charac-
ters. This value indicates what value in the UCS-2 operand matches
any number of double-byte UCS-2 characters. This field is only appli-
cable if qdbqsop is a wildcard scan and the pattern is a UCS-2 param-
eter marker, host variable value, or constant.
25 19 CHAR(1) qdbqdt_59 Reserved.

Selection Operator Item Extension

(QDBQSOP3_T): Selection Operator Item Extension.
This structure overlays field qdbqsitm in structure
QDBQSIT_T (page 34-57) by following QDBQSOPR_T and
is only present if qdbqsopr_ext is set to '1'.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qdbqswc_ccsid CCSID of wildcard character values that are specified in qdbqswc1,
qdbqswc2, qdbqsdb1, and qdbqsdb2. The appropriate associated
CCSID is determined depending on the CCSID of the pattern. If
needed, this CCSID is used to convert the relevant wildcard characters
to the CCSID of the pattern. If set to zero, it is assumed that the
wildcard values are in the same CCSID as that of the pattern.

Chapter 34. File APIs 34-61

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
2 2 BIN(2) qdbqswc_ccsid_ucs2 CCSID of wildcard character values that are specified in qdbqsuo1,
qdbqsuo2, qdbqsum1, and qdbqsum2. If needed, this CCSID is used to
convert the relevant wildcard characters to the CCSID of the pattern. If
this field is set to 0, it is assumed that the wildcard values are in the
same CCSID as the pattern. If this field is specified, it must be a valid
UCS-2 CCSID.
4 4 CHAR(28) qdbqdt_61 Reserved.

Order by Specification (QDBQK_T): Order by specifi-

cation. This structure contains a description of how the
results of the query should be ordered. Up to 10 000 bytes
may be used in ordering.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(16) qdbqkh Order by header.
0 0 BIN(2) qdbqknum The number of key positions in the order by specifications.
2 2 CHAR(1) qdbqkt Key field ordering type.
U Unique key fields
D Duplicate key fields
F FIFO duplicate key fields
L LIFO duplicate key fields
C FCFO duplicate key fields
A, X'00' Any key field is considered.
This field is only used as a guide when considering indexes. Field
qdbqopta (see page 34-46) should be set to on to consider that all
indexes build over the query files.
3 3 CHAR(13) qdbqdt_42 Reserved.
16 10 ARRAY(1) qdbqkf Key specifications of 10 000.
OF
CHAR(64)
16 10 CHAR(30) qdbqkfld Key field name. The field name must be an external field name from
the QDBQR_T format (unless QDBQR_T is not specified, in which case
the field is an external field name from the file format). For the
QDBQR_T structure, see page 34-53. Field Qddffiob (see page 34-98)
must not be X'04' (neither input nor output) for a key field.
36 24 CHAR(1) qdbqksq Key field sequencing attributes.
36 24 0 BIT(1) qdbqksad Ascending or descending sequencing indicator.
0 Ascending sequence
1 Descending sequence
36 24 1 BIT(1) qdbqdt_43 Reserved.
36 24 2 BIT(1) qdbqkabs Absolute value sequence indicator. This bit is ignored for character key
fields.
0 Numeric sequence
1 Absolute value sequence
36 24 3 BIT(5) qdbqdt_44 Reserved.
37 25 CHAR(33) qdbqdt_45 Reserved.

Group by Specification (QDBQG_T): Group by spec-

ification. This structure contains a description of how the
record results of the query should be grouped. All records
for which equal values exist in the defined fields are grouped
together. Up to 2000 bytes may be used.

34-62 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(16) qdbqgh Group by header.
0 0 BIN(2) qdbqgfnum The number of group by fields. If the number of group fields is 0, all
the records are processed as one group.
2 2 CHAR(14) qdbqdt_46 Reserved.
16 10 ARRAY(120) qdbqgf Group field specification. Up to 120 fields are allowed.
OF
CHAR(64)
16 10 CHAR(30) qdbqgfld Group field name.
46 2E BIN(2) qdbqgflj Field-join reference number. 0 indicates that the QDBQR_T format
(page 34-53) is searched for the external field name. If the field is not
found, the formats of the files in the file specification are searched. If
the field name is found in more than one file format, an error is sig-
naled. A value in this field indicates that the external field name is
found in the file format referred to by using this value as an index into
the file list.
48 30 CHAR(32) qdbqdt_47 Reserved.

Group-by-Selection Specification (QDBQGS_T):

Group-by-selection specification. This structure defines the
selection specifications for the group by results. Selection on
the group results is performed after the selection on the
record is complete and the grouping has been completed.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(*) QDBQGS_T Group-by-selection specification structure. See page 34-56.
CHAR(*) QDBQGSIT_T The group by selection item specification structure (see page 34-56).

Set Operation Specification (QDBQT_T): Set opera-

┌──────────┐
tion specification. This structure defines the operation spec-
│ QDT │
ifications being performed for each set of results generated ├──────────┤
from each query definition template. These specifications │ .... │
are only valid when more than one query definition template │ QDBQNXQO │────5 ┌──────────┐
is specified. The set operation specifications must only be │ .... │ │ QDT │
specified on the last query definition template. └──────────┘ ├──────────┤
│ .... │
│ QDBQNXQO │────5 ┌───────────┐
The specification structure is a stack of operands and opera- │ .... │ │ QDT │
tors in reverse notation. Operands are constant literals that └──────────┘ ├───────────┤
identify the relative position of a query definition template │ .... │
among others in the query-definition-template chain. Opera- │ QDBQNXQO │
tors are set operators such as union. For example, given the │ .... │
following query definition templates: └───────────┘
Set
operation
specifications

The following operations can be performed:

(1st QDT) UNION (2nd QDT) UNION ALL (3rd QDT)

The above can be specified in the set operation specification

(in reverse notation) as:
1 2 UNION 3 UNION ALL

Chapter 34. File APIs 34-63

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqtl Set specifications length. This is the total length of all set specifica-
tions.
4 4 BIN(2) qdbqtnum Number of set specifications.
6 6 CHAR(10) qdbqdt_48 Reserved.
16 10 CHAR(*) qdbqtspc Start of set specifications.

Set Item Specifications (QDBQTIT_T): Set item spec-

ifications. This structure overlays field qdbqtspc in structure
QDBQT_T (page 34-64).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqtlen Set item length. This length includes the length (QDBQTIT_T) plus the
length of the set item structure.
4 4 BIN(2) qdbqtitt Set item type.
1 Constant operand
2 Operator
6 6 CHAR(10) qdbqtitm Set item. Use either table QDBQTOPC_T or QDBQTOPR_T.

Relative Number of Query Definition Template

(QDBQTOPC_T): Relative number of query definition
template. This structure overlays field qdbqtitm in structure
QDBQTIT_T (page 34-64).

Offset
Dec Hex Bit Type Variable Name Field
BIN(2) qdbqtqdt Relative number of query definition template.
CHAR(8) qdbqdt_49 Reserved.

Set Operators (QDBQTOPR_T): Set operators. This

structure overlays field qdbqtitm in structure QDBQTIT_T
(page 34-64).

Offset
Dec Hex Bit Type Variable Name Field
CHAR(2) qdbqtop Set operators.
X'0001' Union
X'0002' Union all
CHAR(8) qdbqdt_50 Reserved.

Query Definition Template Offset Table

(QDBQQDTS_T): Query definition template offset table.
This structure is set for each unioned outermost query defi-
nition template that contains subqueries. This offset table
contains offsets for addressability to each query definition
template within a union.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(16) qdbqqhdr Header.

34-64 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qdbqqdtnum Number of subqueries defined with offsets.
2 2 CHAR(14) qdbqdt_51 Reserved.
16 10 ARRAY(32) qdbqqdt Array of subquery offsets. See structure QDBQQDT_T (page 34-65) for
OF the layout.
CHAR(16)

Array of Subquery Offsets (QDBQQDT_T): Array of

subquery offsets.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(4) qdbqo Offset to QDT from start of first QDT in the union.
4 4 CHAR(12) qdbqdt_52 Reserved.

Format Definition Template (Qdb_Qddfmt_t): The Database File Description (QDBRTVFD) API” on
format definition (Qdb_Qddfmt_t) for the QQQQRY API is the page 34-72.
same structure that is used by the Retrieve Database File
Description (QDBRTVFD) API called FILD0200. Figure 34-2 The description and offsets are also in the include source
on page 34-66 shows how this information is organized. supplied on the AS/400 system. You can see this source in
When more than one entry can appear, the figure indicates member QDBRTVFD in the QSYSINC library.
this as in .2/. For a description of the fields in
The QQQQRY API builds the format definition if it was not
Qdb_Qddfmt_t and their respective offsets, see “FILD0200
created prior to the query.
Format (Qdb_Qddfmt Structure)” on page 34-94 in “Retrieve

Chapter 34. File APIs 34-65

Query (QQQQRY) API

┌──────────────────┐
│ Format │
│ Definition │
│ Header │
│ (Qdb_Qddfmt) │
└────┬───┬──┬───┬──┘
│ │ │ └───────────────────────────────────────────┐
┌──────────────────────────────┘ │ └───────────────────────┐ │
│ │ ┌─────────┴───────┐ ┌───────┴──────┐
│ │ │Translation Table│ │Case Selection│
│ ├─┐ │ Specification │ │Specification │
│ ┌───────┼─┴─────────┐ │ (Qdb_Qddfxl) │ │(Qdb_Qddfcsl) │
┌────────┴─────────┐ ┌┴───────┴──────────┐│ └─────────┬───────┘ └───────┬──────┘
│ IDDU/SQL Dict. │ │ ││ │ │
│ Format Info │ │ Field Header ││ │ ├─┐ .6/
│ (Qdb_Qddfdic) │ │ (Qdb_Qddffld) ├┘ ├─┐ ┌───┼─┴─────┐
└──────────────────┘ └┬─┬─┬─┬─┬─┬─┬─┬─┬─┬┘ ┌─────┼─┴──────┐ +──┴───┴──────┐│
│ │ │ │ │ │ │ │ │ │ ┌─┴─────┴───────┐│ │ Selection ││
│ │ │ │ │ │ │ │ │ │ │Translate Table├┘ │Specification├┘
│ │ │ │ │ │ │ │ │ │ │ (Qddfxtbl) │ │ (QDBQS_T) │
│ │ │ │ │ │ │ │ │ │ └───────────────┘ └─────────────┘
│ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────┐
┌────────────────────────────────────────────┘ │ │ │ │ │ │ │ └───────────────────────────────────────────┐ │
│ ┌─────────────────────────────────┘ │ │ │ │ │ └───────────────────────────────┐ │ │
│ │ ┌──────────────────────┘ │ │ │ └────────────────────┐ │ │ │
│ │ │ ┌───────────┘ │ └─────────┐ │ │ │ │
│ │ │ │ │ │ │ │ │ │
┌─────┴─────┐┌─────┴─────┐┌─────┴─────┐┌─────┴─────┐┌──────┴────┐┌─────┴─────┐┌─────┴─────┐┌─────┴─────┐┌──────┴────┐┌──────┴────┐
│ Reference ││ Field ││Edit Code/ ││ Validity ││Field Text ││Alias Name ││ Default ││ Derived ││ IDDU/SQL ││ Column │
│Information││ Prompted ││Edit Word ││Checking Hd││ (Qdb_ ││Information││ Value ││ Field Hdr ││ Dict Field││ Heading │
│ (Qdb_ ││ Numeric ││Information││ (Qdb_ ││ Qddfftxt) ││ (Qdb_ ││Information││ (Qdb_ ││Information││Information│
│ Qddfrefi) ││ Editing ││ (Qdb_ ││ Qddfvchk) │└───────────┘│ Qddfalis) ││ (Qdb_ ││(Qddfderv) ││ (Qdb_ ││ (Qdb_ │
└───────────┘│Information││ Qddfedcw) │└─────┬─────┘ └───────────┘│ Qdbfdft) │└──┬─────┬──┘│ Qddfdicf) ││ Qddfcolh) │
│ (Qdb_ │└───────────┘ ├─┐ └───────────┘ │ │ └───────────┘└───────────┘
│ Qddfdfne) │ ┌───────┼─┴───────┐ │ └──────┐
└───────────┘ ┌┴───────┴────────┐│ ┌─────┘ ├─┐
│Validity Checking││ │ ┌───────┼─┴─────────┐
│ Entry ││ ┌─────────┴────────┐┌┴───────┴──────────┐│
│ (Qdb_Qddfvcst) ├┘ │Derived Field Text││Derived Field Entry││
└────────┬────────┘ │ (Qdb_Qddfdvtx) ││ (Qdb_Qddfdvst) ├┘
├─┐ └──────────────────┘└───────────────────┘
┌──┼─┴─────┐
┌┴──┴──────┐│
│ Validity ││
│ Checking ││
│ Parameter││
│ (Qdb_ ││
│ Qddfvcpr)├┘
└──────────┘

Figure 34-2. Qdb_Qddfmt_t Format

User File Control Block (QDBUFCB_T) Structure: Ÿ AS/400 system environment

User file control block. This structure holds information from Ÿ Null-capable fields
the user file control block (UFCB). It contains selected
Ÿ File dependency
options for the input and output of the specified query. The
options available include: Ÿ Level check
Ÿ Sequence only Ÿ Record format specifications
Ÿ Commitment control Ÿ Secure
Ÿ Block records Ÿ Shared
Ÿ Keyed feedback Ÿ Open scope
Ÿ Record length In addition, some validity checking is done for this UFCB.
Ÿ Open options CPF4297 is issued if any reserved space in the header of
the QDBUFCB_T format is not zero.
Ÿ Release number
Ÿ Version number The offsets and a description of all the fields contained in this
structure are shown in the following table. You can see this
Ÿ Invocation mark count or activation group number
source in member QQQQRY in the QSYSINC library.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR qufcb Query base UFCB. A character view of the entire user file control
(1962) block.

34-66 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(174) reserved1 Reserved.
174 AE CHAR(1) shr_secure Share and secure flags.
174 AE 0 BIT(3) flglrsva Reserved.
174 AE 3 BIT(1) flglshr Share specified.
0 No type of share was specified on the UFCB.
1 SHARE(YES) or SHARE(NO) was specified on the
UFCB.
174 AE 4 BIT(1) flglshsw Share value.
0 Not share
1 Share
174 AE 5 BIT(1) flglsecr Secure specified.
174 AE 6 BIT(1) flglud Secure value.
0 Not secure
1 Secure
174 AE 7 BIT(1) flglsvb Reserved.
175 AF CHAR(1) open Open flags.
175 AF 0 BIT(2) flagrsva Reserved.
175 AF 2 BIT(1) flagui Open input.
175 AF 3 BIT(1) flaguo Open output.
175 AF 4 BIT(1) flaguu Open update.
175 AF 5 BIT(1) flagud Delete.
175 AF 6 BIT(2) flagsvb Reserved.
176 B0 CHAR(4) relver Release and version.
176 B0 CHAR(2) release Release number. This value must be set to 01.
178 B2 CHAR(2) version Version number. This value must be set to 00.
180 B4 BIN(4) invmkcnt Mark counter of call or activation group. Set this field to the call mark
count when scoping the open to the default activation group. For this
case, a ð indicates a permanent open, and any value greater than 0
indicates a temporary open. Set this field to the activation group mark
count when scoping the open to an activation group.
Note: Setting this field to the default activation group is the same as
specifying a call mark of 0 for a permanent open.
184 B8 CHAR(1) markcnt Mark count and blocked record.
184 B8 0 BIT(1) flg2mkcp Mark counter option.
0 The mark counter specified by the invmkcnt field is not
used.
1 The mark counter specified by the invmkcnt field is used.
184 B8 1 BIT(1) flg2rsvl Reserved.
184 B8 2 BIT(1) flg2brcd Blocked records.
0 There are no blocked records.
1 There are blocked records.
184 B8 3 BIT(5) flg2rsv2 Reserved.
185 B9 CHAR(1) reserved2 Reserved.
186 BA CHAR(1) invact Mark count usage.
186 BA 0 BIT(1) flg4rsvl Reserved.

Chapter 34. File APIs 34-67

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
186 BA 1 BIT(1) flg4iact Mark counter usage.
0 The mark counter specified by the invmkcnt field contains
a call mark.
1 The mark counter specified by the invmkcnt field contains
an activation group number.
186 BA 2 BIT(6) flg4rsv2 Reserved.
187 BB CHAR(1) reserved2a Reserved.
188 BC CHAR(1) native AS/400 environment and process NULLS.
188 BC 0 BIT(2) flg3rsvl Reserved.
188 BC 2 BIT(1) flg3ntve This field must be set to 1.
188 BC 3 BIT(3) flg3rsv2 Reserved.
188 BC 6 BIT(1) flg3null Process null-capable fields.
188 BC 7 BIT(1) flg3rsv3 Reserved.
189 BD CHAR(2) reserved3a Reserved.
191 BF CHAR(1) opnscp Open scope.
A Open is scoped to the specified activation group, or if this
is the default activation group and a call mark is speci-
fied, the open is scoped to the program at the call mark
specified.
J Open is scoped to the job.
X'00' Not specified. The value A is assumed.
192 BE CHAR(16) reserved3 Reserved.
Note: The parameter field through the ufcbend field are repeated in the variable-length data area for each parameter.
208 D0 CHAR(73) parameter Variable parameters.
208 D0 BIN(2) primrlnl Primary record length. Initialize to -1 to deactivate.
210 D2 BIN(2) primrlnv The user-specified record length.
212 D4 BIN(2) filedep File-dependent I/O. Initialize to -3 to deactivate.
214 D6 0 BIT(1) fildonoff File-dependent option.
On This is file dependent.
Off This is not file dependent.
214 D6 1 BIT(7) fldrsvl Reserved.
215 D7 BIN(2) lvlchk Level-check option. Initialize to -6 to deactivate.
217 D9 0 BIT(1) lvlonoff Level-check option.
On Perform level checking
Off Do not perform level checking
217 D9 1 BIT(7) lvlrsvl Reserved.
218 DA BIN(2) recfmts Record format sequence numbers for level checking.
220 DC BIN(2) maximum The maximum number of formats.
222 DE BIN(2) curnum The current number of formats.
224 E0 ARRAY(75) formats Array of format names and sequence numbers
of
CHAR(23)
224 E0 CHAR(10) name The format name.
234 EA CHAR(13) number The format sequence number.
1949 79D BIN(2) keyfdbk Key feedback. Initialize to -53 to deactivate.
1951 79F 0 BIT(1) keyonoff Key feedback option.
On Provide feedback
Off Do not provide feedback

34-68 AS/400 System API Reference V4R4

 Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
1951 79F 1 BIT(7) keyrsvl Reserved.
1952 7A0 BIN(2) seqonly Sequential processing. Initialize to -58 to deactivate.
1954 7A2 0 BIT(1) seqonoff Sequential processing option.
On Use Fast sequence processing
Off Use standard sequence processing
1954 7A2 1 BIT(1) numonoff Fast sequential processing option.
On Number of records to transfer to or from the I/O buffers
for fast sequential processing is specified.
Off The number of records to transfer to or from the I/O
buffers is not specified.
1954 7A2 2 BIT(6) seqrsvl Reserved.
1955 7A3 BIN(2) numrecs The number of records to transfer to or from the I/O buffers for fast
sequential processing.
1957 7A5 BIN(2) commitc Commitment control. Initialize to -59 to deactivate.
1959 7A7 CHAR(1) control Commitment control and optional record-locking level. Possible values
are:
X'00' Do not place the member under commitment control
when it is opened. This would be the same as specifying
the Start Commitment Control command as STRCMTCLT
COMMIT(*NO).
X'80' Place the member under commitment control when it is
opened, and use the record-locking level default used on
the Start Commitment Control command, that is,
STRCMTCTL COMMIT (*YES).
X'82' Place the member under commitment control when it is
opened and use record-locking level *CHG, that is,
STRCMTCTL COMMIT (*YES,*CHG).
X'86' Place the member under commitment control when it is
opened and use record-locking level *CS, that is,
COMMIT *YES,*CS).
X'87' Place the member under commitment control when it is
opened and use record-locking level *ALL, that is,
COMMIT (*YES,*ALL).
1960 7A8 BIN(2) ufcbend This field must be set to 32767, the end of the variable area parame-
ters. Set this field to ENDLIST.
1962 7AA BIN(4) dummy Dummy pointer to force boundary alignment for the user file control
block structure.

Value for Query Variable Fields (QQQVALS_T)

Structure: The structure is used to supply the values for
the variable fields used by the QQQQRY API. The offsets
and a description of all the fields contained in this structure
are shown in the following table. You can see this source in
member QQQQRY in the QSYSINC library.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(2) qqqvvalnum Number of values in list.
2 2 CHAR(30) qqqvals_l Reserved.
32 20 ARRAY(1) qqqvlst List of variable field values referenced by field Qddfvarx. See page
OF 34-99 for the Qddfvarx field.
CHAR(48)
32 20 Pointer qqqvsptr Space pointer to the host variable value. The value must be in internal
form.

Chapter 34. File APIs 34-69

Query (QQQQRY) API

Offset
Dec Hex Bit Type Variable Name Field
48 30 CHAR(7) qqqvattr Attributes of value.
48 30 0 CHAR(1) qqqvatyp Scalar type
X'00' Binary
X'01' Floating point
X'02' Zoned decimal
X'03' Packed
X'04' Character
X'06' Graphic
X'07' DBCS-only
X'08' DBCS-either
X'09' DBCS-open
X'0B' Date
X'0C' Time
X'0D' Timestamp
49 31 CHAR(2) qqqvalen Scalar length for character, binary, floating point, only, either, or open.
For graphic, this is also the number of bytes (not characters).
49 31 CHAR(1) qqqvadec Fractional digits for zoned or packed.
50 32 CHAR(1) qqqvatot Total digits for zoned or packed.
51 33 CHAR(4) qqqvaary Container for precision and digits for binary values.
51 33 CHAR(1) qqqvbind Fractional digits for binary value.
52 34 CHAR(1) qqqvbint Total digits for binary value.
53 35 CHAR(2) qqqvals_2 Reserved.
55 37 CHAR(1) qqqvals_3 Field attributes.
55 37 0 BIT(1) qqqvvlen Variable length host variable field.
0 The host variable field is not variable length.
1 The host variable field is variable length.
55 37 1 BIT(1) qqqvnulll The form of field qqqvsptr (page 34-69). If on, qqqvsptr is ignored and
the literal is the null value. If off, the literal pointed to by qqqvsptr is
used.
55 37 2 BIT(1) qqqvzerol The length of field qqqvsptr. If on, qqqvsptr is ignored and the literal is
zero length. If off, the literal pointed to by qqqvsptr is used.
55 37 3 BIT(5) qqqvals_4 Reserved.
56 38 CHAR(1) qqqvdvft Date, time, and timestamp format attribute. This field applies to date,
time, or timestamp values only, where the field qqqvatyp in this struc-
ture is date, time, or timestamp.
X'00' Job default
X'FF' Determine format
X'01' USA format
X'03' ISO format
X'05' EUR format
X'07' JIS format
X'09' SAA timestamp
X'17' MDY format
X'18' DMY format
X'19' YMD format
X'1A' JUL format
X'1B' HMS format
X'1D' YYYY NNN format
X'1E' YYYY MM DDDD HH MM SS format
These formats are optional. If the value is X'FF', the format is in the
query definition template header and that format is used first in deter-
mining the format. See field qdbqdfmt on page 34-45 or field qdbqtfmt
on page 34-45 if the format is in the query definition template header.
57 39 CHAR(1) qqqvdvsp Date, time, and timestamp separator. This field is only set when field
qqqvdvft in this structure is X'17', X'18', X'19', X'1A', or X'1B'.

34-70 AS/400 System API Reference V4R4

 Query SQL Database Monitor (QQQQSDBM) API

Offset
Dec Hex Bit Type Variable Name Field
58 3A BIN(2) qqqvcsid CCSID of value.
59 3C CHAR(20) qqqvals_5 Reserved.

| Usage Notes Query SQL Database Monitor

| In multithreaded jobs, this command is not threadsafe for dis- (QQQQSDBM) API
| tributed files and fails for distributed files that use relational
| databases of type *SNA. This command also is not
| threadsafe and fails for Distributred Data Management Required Parameter Group:
| (DDM) files of type *SNA.
1 Qualified job name Input Char(26)
2 Number of active monitors Output Binary(4)
Error Messages 3 Size of active monitors Input Binary(4)
array
CPF2114 E Cannot allocate object &1 in &2 type *&3. 4 Type of active monitors Output Array(*) of
CPF2115 E Object &1 in &2 type *&3 damaged. array Char(10)
CPF2169 E Job's sort sequence information not available. 5 Memory handle Output Char(10)
CPF24B4 E Severe error while addressing parameter list. 6 Error code I/O Char(*)
CPF2619 E Table &1 not found.
Threadsafe: Yes
CPF3BCC E
Language identifier &1 not valid.
CPF3BC6 E The Query SQL Database Monitor (QQQSSDBM) API
Sort sequence &1 not valid. returns information about the activity of the SQL and the ori-
CPF3BC7 E ginal database monitor. Associated APIs include the fol-
CCSID &1 outside of valid range. lowing:
CPF3BC8 E
Conversion from CCSID &1 to CCSID &2 is not Ÿ Clear SQL Database Monitor Statistics (QQQCSDBM)
supported. Ÿ Dump SQL Database Monitor (QQQDSDBM)
CPF3BC9 E
Ÿ End SQL Database Monitor (QQQESDBM)
Conversion from CCSID &1 to CCSID &2 is not
defined. Ÿ Start SQL Database Monitor (QQQSSDBM)
CPF3C90 E
Literal value cannot be changed.
Authorities and Locks
CPF3CF1 E
Error code parameter not valid. None
CPF3FC0 E
Language identifier is not valid.
CPF4000 E All CPF40XX messages could be returned. XX Required Parameter Group
is from 01 to FF.
Qualified job name
CPF4100 E All CPF41xx messages could be returned. xx is
INPUT; CHAR(26)
from 01 to FF.
CPF4200 E All CPF42xx messages could be returned. xx is The job for which status is being requested. The quali-
from 01 to FF. fied job name has three parts:
CPF4300 E All CPF43xx messages could be returned. xx is
Job name
from 01 to FF.
CHAR(10). A specific job name, a generic name,
CPF5000 E All CPF50XX messages could be returned. XX
or one of the following special values:
is from 01 to FF.
* or *CURRENT
CPF5100 E All CPF51xx messages could be returned. xx is
Only the job that this program is running in.
from 01 to FF.
The rest of the qualified job name parameter
CPF5200 E All CPF52xx messages could be returned. xx is
must be blank.
from 01 to FF.
*ALL
CPF5300 E All CPF53xx messages could be returned. xx is
All jobs. The rest of the job name parameter
from 01 to FF.
must be blank.
CPF8133 E Table &4 in &9 damaged.
User name
CPF9800 E All CPF98xx messages could be signaled. xx is
CHAR(10). A specific user profile name.
from 01 to FF.

Chapter 34. File APIs 34-71

Retrieve Database File Description (QDBRTVFD) API

Job number
CHAR(6). A specific job number. Required Parameter Group:
Number of active monitors
1 Receiver variable Output Char(*)
OUTPUT; BINARY(4) 2 Length of receiver vari- Input Binary(4)
The number of active database monitors. If the number able
of active monitors is greater than the size of the type of 3 Qualified returned file Output Char(20)
name
active monitors array allocated by the user, the type of
4 Format name Input Char(8)
active monitors array is truncated to the size allocated
5 Qualified file name Input Char(20)
by the user. 6 Record format name Input Char(10)
7 Override processing Input Char(1)
Size of active monitors array
8 System Input Char(10)
INPUT; BINARY(4) 9 Format type Input Char(10)
The amount of storage (number of character(10) array 10 Error code I/O Char(*)
entries) allocated by the caller for the type of active
monitors array parameter. | Threadsafe: Conditional; see Usage Notes.

Type of active monitors array

OUTPUT; Array(*) of CHAR(10) The Retrieve Database File Description (QDBRTVFD) API
allows you to get complete and specific information about a
The types of database monitors that are active. The file on a local or remote system. The information is returned
values may include: to a receiver variable in either a file definition template or a
*FILE The file-based database monitor format definition mapping. The file definition template pro-
(STRDBMON) is active vides more complete information about a database file than
*SQLMEMORY the Display File Description (DSPFD) command. The format
The SQL memory-based database definition provides complete information on the record
monitor (QQQSSDBM) is active. formats of the file.

Memory handle The format definition is used with the Query (QQQQRY) API
OUTPUT; CHAR(10) to get data from a file. You can run the QDBRTVFD API to
build a format definition that is later used to run a query.
The memory handle used for the specified job if the
This format definition can be used several times to extract
memory-based monitor is active. Only the first 6 charac-
information from a database, making the Query API run
ters will be used for naming the memory handle.
faster. If the format definition is not created prior to running
This field is blank if the SQL memory-based database a query, the QQQQRY API must create one when it runs.
monitor is not active.

Error code Authorities and Locks

I/O; CHAR(*)
Library Authority
The structure in which to return error information. For *EXECUTE
the format of the structure, see “Error Code Parameter” File Authority *OBJOPR
on page 2-6. File Lock *SHRNUP

Error Messages Required Parameter Group

CPD0172 D Receiver variable
Parameters passed on CALL do not match OUTPUT; CHAR(*)
those required.
CPF1321 E Job &1 user &2 job number &3 not found. The receiver variable that is to receive the information
CPF3CF1 E requested. You can specify the size of the area smaller
Error code parameter not valid. than the format requested as long as you specify the
CPF436E E Job &1 user &2 job number &3 is not active. length of receiver variable parameter correctly. As a
result, the API returns only the data the area can hold.

Length of receiver variable

Retrieve Database File Description INPUT; BINARY(4)
(QDBRTVFD) API 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
program. If the length of receiver variable parameter
specified is larger than the allocated size of the receiver

34-72 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

variable specified in the user program, the results are on either a local or remote system, or both. The pos-
not predictable. The minimum length is 8 bytes. sible values are:

Qualified returned file name *LCL The information returned is about local
OUTPUT; CHAR(20) files only.
The actual qualified file name from which the file
*RMT The information returned is about remote
files only.
description has been extracted. If an override is active
this file and library name may be different from the one
*FILETYPE The information returned is about files on
both the local and remote systems. For
entered with the API.
DDM files, the information returned is
Format name about the remote file that was named on
INPUT; CHAR(8) the RMTFILE parameter of the Create
DDM File (CRTDDMF) command.
The content and format of the information to be returned
about the specified file, member, or format. You can Format type
use the following format names: INPUT; CHAR(10)
FILD0100 File definition template Whether the logical formats returned are internal or
FILD0200 Format definition template external. (This parameter is used only with format
FILD0300 Key field information template FILD0200.) A description and examples of the internal
(*INT) and external (*EXT) formats follow:
See “Format of Generated Information” on page 34-74
for a description of these formats. *EXT The formats returned are external. If the
specified file is a logical file, the format
Qualified file name
returns data for the logical fields defined
INPUT; CHAR(20)
in the logical record format. If the speci-
The name of the file about which the information is to be fied file is a physical file, the internal and
extracted and the library in which it is located. The first external field names are the same.
10 characters contain the file name, and the second 10 *INT The formats returned are internal. If the
characters contain the library name. specified file is a logical file, the format
returns data for the fields on which the
You can use the following special values for the library
logical fields are based. If the specified
name:
file is a physical file, the internal and
*CURLIB The job's current library external field names are the same.
*LIBL The library list
The following are DDS, *EXT, and *INT format type
Record format name examples: For a logical file definition of .1/ that is
INPUT; CHAR(10) based on a physical file definition of .2/, a format type
of *EXT would return .3/ and a format type of *INT
The name of the record format in the specified file that is
would return .4/.
to be used to generate the file description. (This param-
eter is used only with format FILD0200.)
You can use the following special value for the record Format Type Example DDS
format name Logical file definition .1/:
*FIRST The first record format found R CONCAT1 PFILE(PF1)
LFLD1 RENAME(FLD1)
Override processing
FLD2
INPUT; CHAR(1)
CATFLD CONCAT(FLD1 FLD2 FLD3)
Whether overrides are to be processed. The following K CATFLD
values are used:
Physical file definition .2/:
0 No override processing
1 Override processing FLD1 5A
FLD2 10A
System FLD3 5A
INPUT; CHAR(10) K FLD1

Whether the information that is returned is about a file

Chapter 34. File APIs 34-73

Retrieve Database File Description (QDBRTVFD) API

Error code
Format Type *EXT Example I/O; CHAR(*)
.3/ The structure in which to return error information. For
the format of the structure, see “Error Code Parameter”
Record format name CONCAT1 on page 2-6.
Record length 35
Number of fields 3
Internal field name 1 FLD1 Format of Generated Information
External field name 1 LFLD1
Length of field 1 5 The QDBRTVFD API can be used to provide information in
Internal field name 2 FLD2
the following formats:
External field name 2 FLD2
Length of field 2 10 FILD0100 File definition template
Internal field name 3 FLD1 FILD0200 Format definition template
External field name 3 CATFLD FILD0300 Key field information template
Length of field 3 20
The following sections provide an overview of each of these
formats. If an offset equals zero in the returned information,
there is no corresponding structure associated with it.
Format Type *INT Example
.4/ The asterisk (*) in the Field column represents a reserved
field. No variable is associated with these reserved fields.
Record format name CONCAT1
Record length 35 FILD0100 Format (File Definition Template (FDT)
Number of fields 5 header): FILD0100 provides detailed information about how
Internal field name 1 FLD1 the file is built. Figure 34-3 on page 34-75 shows how this
External field name 1 LFLD1 information is organized. When more than one entry can
Length of field 1 5 appear, the figure indicates this as in .5/.
Internal field name 2 FLD2
External field name 2 FLD2 Descriptions of the fields in this structure follow Figure 34-3
Length of field 2 10
on page 34-75. The include source is supplied on the
Internal field name 3 FLD1
External field name 3 CATFLD
AS/400 system, in source file H, member name QDBRTVFD,
Length of field 3 5 in the QSYSINC library. The field names in the following
Internal field name 4 FLD2 tables apply only to the ILE C include. Refer to “Data Struc-
External field name 4 CATFLD tures and the QSYSINC Library” on page 2-2 for the names
Length of field 4 10 of the OPM and ILE RPG and COBOL includes.
Internal field name 5 FLD3
External field name 5 CATFLD
Length of field 5 5

34-74 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

| Figure 34-3. FILD0100 Format

File Definition Header (Qdb_Qdbfh): This is the first

structure and is located at offset zero of the returned data.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbfyret Length of the data returned in bytes.
4 4 BINARY(4) Qdbfyavl Number of bytes provided for the file definition data.

Chapter 34. File APIs 34-75

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
8 8 BIT(16) Qdbfhflg Attributes bytes.
8 8 0 BIT(2) Reserved_1 Reserved.
8 8 2 BIT(1) Qdbfhfpl Type of file. If on, the file is a logical database file. If off, a physical
database file.
8 8 3 BIT(1) Reserved_2 Reserved.
8 8 4 BIT(1) Qdbfhfsu File type (FILETYPE). If on, the file is a source file (*SRC). If off, a
data file (*DATA).
8 8 5 BIT(1) Reserved_3 Reserved.
8 8 6 BIT(1) Qdbfhfky Access path. If on, the file has a keyed sequence access path. If off,
an arrival sequence access path.
8 8 7 BIT(1) Reserved_4 Reserved.
9 9 0 BIT(1) Qdbfhflc Record format level check (LVLCHK). If on, the record format level
identifiers are checked when the file is opened (*YES) if off, they are
not checked when the file is opened (*NO).
9 9 1 BIT(1) Qdbfkfso Select/omit. If on, the file is a select/omit logical file.
9 9 2 BIT(4) Reserved_5 Reserved.
9 9 6 BIT(1) Qdbfigcd Double-byte character set (DBCS) or Graphic data. If on, the file's
record format(s) contains DBCS or Graphic data fields.
9 9 7 BIT(1) Qdbfigcl Double-byte character set (DBCS) or Graphic literals. If on, the file's
record format(s) contains DBCS or Graphic literals.
10 A CHAR(4) Reserved_7 Reserved.
14 E BINARY(2) Qdbflbnum Number of data members. 0 indicates an externally described physical
file or a program described physical file that is not linked to a data dic-
tionary. 1 through 32 indicates the number of data dictionary record
formats for a program described physical file that is linked to a data
dictionary or the number of based-on physical records for a logical file.
16 10 CHAR(13) Qdbfkdat Keyed sequence access path description. If this file has an arrival
sequence access path, these fields are not applicable.
16 10 BINARY(2) Qdbfknum Number of key fields for the file. 1 through 120.
18 12 BINARY(2) Qdbfkmxl Maximum key length for the file. 1 through 2000.
20 14 CHAR(1) Qdbfkflg Keyed sequence access path attributes.
20 14 0 BIT(1) Reserved_8 Reserved
20 14 1 BIT(1) Qdbfkfcs Alternate collating sequence (ALTSEQ). If on, an alternate collating
sequence table is specified for the file.
20 14 2 BIT(4) Reserved_9 Reserved.
20 14 6 BIT(1) Qdbfkfrc Force keyed access path (FRCACCPTH). If on, the access path and
changed records are forced to auxiliary storage when the access path is
changed (*YES).
20 14 7 BIT(1) Qdbfkflt Floating point key indicator. If on, the access path for the file contains
floating point keys.
21 15 CHAR(1) Qdbfkfdm Access path maintenance (MAINT).
I Immediate maintenance (*IMMED)
D Delayed maintenance (*DLY)
R Rebuild maintenance (*REBLD)
22 16 CHAR(8) Reserved_10 Reserved.

34-76 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
30 1E CHAR(10) Qdbfhaut Public authority (AUT).
*CHANGE Public change authority
*ALL Public all authority
*USE Public use authority
*EXCLUDE Public exclude authority
authorization-list-name
The name of the authorization list whose authority is
used for the file. This is the original public authority that
the file was created with, not the current public authority
for the file.
40 28 CHAR(1) Qdbfhupl Preferred storage unit (UNIT).
X'00' The storage space and its members can be allocated on
the available auxiliary storage unit (*ANY).
X'01' through X'FF'
The unit identifier of an auxiliary storage unit on the
system.
41 29 BINARY(2) Qdbfhmxm Maximum members (MAXMBRS).
0 No maximum is specified, 32,767 is used (*NOMAX).
1 through 32,767
The maximum number of members the file can have.
43 2B BINARY(2) Qdbfwtfi Maximum file wait time (WAITFILE).
-1 The default wait time specified in the class description is
used (*CLS).
0 The program does not wait for the file, an immediate allo-
cation is required (*IMMED).
1 through 32,767
The number of seconds a program waits for the file.
45 2D BINARY(2) Qdbfhfrt Records to force a write (FRCRATIO).
0 There is force write ratio.
1 through 32,767
The number of inserted, updated, or deleted records that
are explicitly forced to storage.
47 2F BINARY(2) Qdbfhmnum Number of members, 0 through 32,767.
49 31 CHAR(9) Reserved_11 Reserved.
58 3A BINARY(2) Qdbfbrwt Maximum record wait time (WAITRCD).
-2 The default wait time allowed by the system is used
(*NOMAX).
-1 The program does not wait for the record, an immediate
allocation is required (*IMMED).
1 through 32,767
The number of seconds a program waits for the record.
60 3C CHAR(1) Qaaf Additional attribute flags.
60 3C 0 BIT(7) Reserved_12 Reserved
60 3C 7 BIT(1) Qdbfpgmd Program described file indicator. If on, the file is program described.
61 3D BINARY(2) Qdbffmtnum Total number of record formats, 1 through 32.
63 3F CHAR(2) Qdbfhfl2 Additional attribute flags
63 3F 0 BIT(1) Qdbfjnap Access path journaled.
63 3F 1 BIT(1) Reserved_13 Reserved.
63 3F 2 BIT(4) File capability/operation flags.
63 3F 2 BIT(1) Qdbfrdcp Allow read operation. If on, records are not allowed to be read from the
file.
63 3F 3 BIT(1) Qdbfwtcp Allow write operation. If on, records are not allowed to be written to the
file.

Chapter 34. File APIs 34-77

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
63 3F 4 BIT(1) Qdbfupcp Allow update operation (ALWUPD). If on, records are not allowed to be
updated in the file (*NO).
63 3F 5 BIT(1) Qdbfdlcp Allow delete operation (ALWDLT). If on, records are not allowed to be
deleted from the file (*NO).
63 3F 6 BIT(9) Reserved_14 Reserved.
64 40 7 BIT(1) Qdbfkfnd Null values cause duplicates indicator (UNIQUE). Only valid if Qdbfpact
is equal to 'KU'. If on, null values do not cause duplicate keys in the file
access path(s) (*EXCNULL).
65 41 BINARY(2) Qdbfvrm First supported version release modification level. New database
support is used in the file that will prevent it from being saved and
restored to a prior version, release, and modification level.
X'0000' Pre-Version 2 Release 1 Modification 0 file.
X'1500' Version 2 Release 1 Modification 0 V2R1M0 file.
X'1501' Version 2 Release 1 Modification 1 V2R1M1 file.
X'1600' Version 2 Release 2 Modification 0 V2R2M0 file.
X'1700' Version 2 Release 3 Modification 0 V2R3M0 file.
X'1F00' Version 3 Release 1 Modification 0 V3R1M0 file.
X'2000' Version 3 Release 2 Modification 0 V3R2M0 file.
X'2400' Version 3 Release 6 Modification 0 V3R6M0 file.
X'2500' Version 3 Release 7 Modification 0 V3R7M0 file.
X'2900' Version 4 Release 1 Modification 0 V4R1M0 file.
X'2A00' Version 4 Release 2 Modification 0 V4R2M0 file.
X'2B00' Version 4 Release 3 Modification 0 V4R3M0 file.
| X'2C00' Version 4 Release 4 Modification 0 V4R4M0 file.
67 43 CHAR(2) Qaaf2 Additional attribute flags.
67 43 0 BIT(1) Qdbfhmcs Multiple coded character set identifier indicator (CCSID). If on, the file
has more than one CCSID for its input and output character type fields.
If the file has no character type fields, this bit is off.
67 43 1 BIT(1) Reserved_15 Reserved.
67 43 2 BIT(1) Qdbfknll Allow null value key indicator (ALWNULL). If on, null value keys are
allowed.
67 43 3 BIT(1) Qdbf_nfld Allow null value data (ALWNULL). If on, the file record format(s) allow
null value fields.
67 43 4 BIT(1) Qdbfvfld Variable length data (VARLEN). If on, the file record format(s) contain
variable length fields.
67 43 5 BIT(1) Qdbftfld Date/time/timestamp data. If on, the file record format(s) contain date,
time, or timestamp fields.
67 43 6 BIT(1) Qdbfgrph Graphic data. If on, the file record formats contain graphic fields.
67 43 7 BIT(1) Qdbfpkey Primary key (*PRIKEY). If on, the access path for the file is a primary
key.
68 44 0 BIT(1) Qdbfunqc Unique constraint (*UNQCST). If on, the access path for the file is a
unique constraint.
68 44 1 BIT(2) Reserved_118 Reserved.
68 44 3 BIT(1) Qdbfapsz Access path size (ACCPTHSIZ). If on (*MAX1TB), all access paths
associated with this file will be allowed to occupy a maximum of 1
terabyte (1 099 511 627 776 bytes) of auxiliary storage. If off
(*MAX4GB), all access paths associated with this file will be allowed to
occupy a maximum of 4 gigabytes (4 294 966 272 bytes) of auxiliary
storage.
68 44 4 BIT(1) Qdbfdisf Distributed file. If on, the file is a distributed file.
68 44 5 BIT(1) Reserved_68 Reserved.
68 44 6 BIT(1) Reserved_69 Reserved.
68 44 7 BIT(1) Reserved_70 Reserved.

34-78 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
69 45 CHAR(13) Qdbfhcrt File level identifier. The date of the file in internal standard format
(ISF), CYYMMDDHHMMSS.
82 52 CHAR(52) Qdbfhtx File text description.
82 52 CHAR(2) Reserved_18 Reserved.
84 54 CHAR(50) Qdbfhtxt Text description (TEXT)
134 86 CHAR(13) Reserved_19 Reserved.
147 93 CHAR(30) Qdbfsrc Source file fields. Must be hexadecimal zeros if there is no source file
information.
147 93 CHAR(10) Qdbfsrcf Source file name.
157 9D CHAR(10) Qdbfsrcm Source file member name.
167 A7 CHAR(10) Qdbfsrcl Source file library name.
177 B1 CHAR(1) Qdbfkrcv Access path recovery (RECOVER).
A The file access path is built after the IPL is completed
(*AFTIPL).
N The file access path is built when the file is next opened
(*NO).
S The file access path is built during the IPL (*IPL).
178 B2 CHAR(23) Reserved_20 Reserved.
201 C9 BINARY(2) Qdbftcid Coded character set identifier (CCSID) for text description.
0 There is no file text description.
1 through 65,535
The file text description CCSID.
203 CB CHAR(2) Qdbfasp Auxiliary storage pool (ASP).
X'0000' The file is located on the system auxiliary storage pool.
X'0002' through X'0010'
On which user auxiliary storage pool the file resides.
| 205 CD CHAR(1) Qdbfnbit Complex objects flags.
| 205 CD 0 BIT(1) Qdbfhudt If on, the file record format has a user-defined type field.
| 205 CD 1 BIT(1) Qdbfhlob If on, the file record format has a large object field.
| 205 CD 2 BIT(1) Qdbfhdtl If on, the file record format has a datalink field. A datalink is a field
| data type that is used to point to another object that contains the data
| for that field.
| 205 CD 3 BIT(1) Qdbfhudf If on, the file uses a user-defined function.
| 205 CD 4 BIT(1) Qdbfhlon If on, the file has a datalink field with FILE LINK CONTROL.
| 205 CD 5 BIT(1) Qdbfhlop If on, the file is a logical file without any large object fields, but the
| based-on physical file has a large object field.
| 205 CD 6 BIT(1) Qdbfhdll If on, the file is a logical file without any datalink fields, but the based-on
| physical file has a datalink field.
| 205 CD 7 BIT(1) Reserved_21 Reserved.

206 CE BINARY(2) Qdbfmxfnum Maximum number of fields, 1 through 8000. Indicates the number of
fields in the file's record format that contains the largest number of
fields.
208 D0 CHAR(76) Reserved_22 Reserved.
284 11C BINARY(4) Qdbfodic Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the IDDU/SQL Data Dictionary area, Qdbfdic (page 34-89).
288 120 CHAR(14) Reserved_23 Reserved.
302 12E BINARY(2) Qdbffigl File generic key length, 0 through 2000. The length of the key before
the first *NONE key field for the file. If this file has an arrival sequence
access path, this field is not applicable.

Chapter 34. File APIs 34-79

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
304 130 BINARY(2) Qdbfmxrl Maximum record length, 1 through 32,766. The length of the record in
the file's record format that contains the largest number of bytes.
306 132 CHAR(8) Reserved_24 Reserved.
314 13A BINARY(2) Qdbfgkct File generic key field count, 0 through 120. The count of the number of
key fields before the first *NONE key field for the file. If this file has an
arrival sequence access path, this field is not applicable.
316 13C BINARY(4) Qdbfos Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the file scope array, Qdbfb (page 34-90).
320 140 CHAR(8) Reserved_25 Reserved.
328 146 BINARY(4) Qdbfocs Offset from the start of the FDT header, Qdb_Qdbfh, to the alternative
collating sequence table section, Qdbfacs.
332 14C CHAR(4) Reserved_26 Reserved.
336 150 CHAR(2) Qdbfpact Access path type.
AR Arrival sequence access path.
KC Keyed sequence access path with duplicate keys
allowed. Duplicate keys are accessed in first-changed-
first-out (FCFO) order.
KF Keyed sequence access path with duplicate keys
allowed. Duplicate keys are accessed in first-in-first-out
(FIFO) order.
KL Keyed sequence access path with duplicate keys
allowed. Duplicate keys are accessed in last-in-first-out
(LIFO) order.
KN Keyed sequence access path with duplicate keys
allowed. No order is guaranteed when accessing dupli-
cate keys.
KU Keyed sequence access path with no duplicate keys
allowed (UNIQUE).
EV Encoded vector with a 1-, 2-, or 4-byte vector.
338 152 CHAR(6) Qdbfhrls File version, release, and modification level. VxRyMz, where x is the
version, y the release, and z the modification level.
344 158 CHAR(20) Reserved_27 Reserved.
364 16C BINARY(4) Qdbpfof Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the physical file specific attributes section, Qdbfphys (page 34-81).
368 170 BINARY(4) Qdblfof Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the logical file specific attributes section, Qdbflogl (page 34-86).
372 174 CHAR(6) Qdbfssfp Sort sequence table.
372 174 CHAR(1) Qdbfnlsb Flags.
372 174 0 BIT(3) Qdbfsscs Sort sequence table (SRTSEQ) indicators.
B'000' No sort sequence table for the file; however, an alternate
collating sequence table was specified.
B'010' No sort sequence table is used for the file, and the
hexadecimal value of the characters will be used to
determine the sort sequence (*HEX).
B'100' A sort sequence table was specified for the file.
372 174 3 BIT(5) Reserved_103 Reserved.
373 175 CHAR(3) Qdbflang Language identifier (LANGID).
376 178 CHAR(2) Qdbfcnty Country identifier (CNTRYID).
378 17A BINARY(4) Qdbfjorn Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the journal section, Qdbfjoal (page 34-94).
382 17E BINARY(4) Qdbfevid Initial number of distinct values an encoded vector access path was
allowed at creation.
386 182 CHAR(14) Reserved_28 Reserved.

34-80 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Physical File Specific Attributes (Qdb_Qdbfphys):

You can locate this section with the offset Qdbpfof (page
34-80), in the FDT header section.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(2) Qdbfpalc Allocate/contiguous storage (ALLOCATE and CONTIG)
DN New members added to the file allow the system to
determine storage space that is allocated for the member
(ALLOCATE(*NO))
IC New members added to file use the initial number of
records to determine storage space that is allocated for
the member (ALLOCATE(*YES)) and the storage
attempted to be allocated contiguously (CONTIG(*YES)).
IN New members added to file use the initial number of
records to determine storage space that is allocated for
the member (ALLOCATE(*YES)) and storage is not
attempted to be allocated contiguously (CONTIG(*YES)).
2 2 CHAR(1) Qdbfcmps Maximum percentage of deleted records allowed (DLTPCT).
X'00' The number of deleted records is not checked when the
member is closed (*NONE).
X'01' through X'64'
The largest percentage of deleted records the member
should have.
3 3 CHAR(8) Reserved_29 Reserved.
11 B BINARY(4) Qdbfprnum Initial number of records (SIZE).
0 The number of records that can be inserted into each
member is not limited by the user. The system deter-
mines the maximum member size (*NOMAX)
1 through 2,147,483,646
The number of records that can be inserted before an
automatic extension occurs.
15 F BINARY(2) Qdbfpri Increment number of records (SIZE).
0 through 32,767
The maximum number of records that can inserted into
the member after an automatic extension occurs.
17 11 BINARY(2) Qdbfprinum Maximum number of increments (SIZE).
0 through 32,767
The maximum number of increments that can be auto-
matically added to the member.
19 13 BINARY(4) Qdbforid Offset from the start of FDT header, Qdb_Qdbfh (page 34-75), to the
Record ID Codes for program described physical files, Qdbforid.
23 17 CHAR(1) Qflags Flags.
23 17 0 BIT(1) Qdbfrdel Reuse deleted records (RESUEDLT). If on, deleted member record
space is reused by the system on write (insert) requests (*YES).
23 17 1 BIT(3) Reserved_30 Reserved.
23 17 4 BIT(1) Qdbfsqlt SQL table indicator. If on, the file is a SQL table.
23 17 5 BIT(3) Reserved_31 Reserved.
24 18 BINARY(4) Qdbfotrg Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the trigger description area, Qdbftrg (page 34-82).
28 1C BINARY(2) Qdbftrgn Number of triggers.
30 1E BINARY(4) Qdbfofcs Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the constraint definition area, Qdbf_Constraint (page 34-82).
34 22 BINARY(4) Qdbfcstn Number of constraints for the file.

Chapter 34. File APIs 34-81

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
| 38 26 BINARY(4) Qdbfodl Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
| the datalinks area, Qdb_Qdbfdtalnk (page 34-84).
| 42 2A CHAR(6) Reserved_32 Reserved.

Trigger Description Area (Qdb_Qdbftrg): You can

locate this section with the offset Qdbfotrg (page 34-81) in
the Physical File Specific Attributes section. This section is
repeated by the number of triggers, Qdbftrgn.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(1) Qdbftrgt Trigger time.
1 Run the trigger after the change operation.
2 Run the trigger before the operation.
1 1 CHAR(1) Qdbftrge Trigger event.
1 An insert operation.
2 An delete operation.
3 An update operation.
2 2 CHAR(10) Qdbftpgm Trigger program name.
12 C CHAR(10) Qdbftplb Trigger program library name.
22 16 CHAR(1) Qdbftupd Trigger update condition.
1 Always call the trigger program when updating the file.
2 Call the trigger program only when the updated values
are changed.
This field is ignored for insert and delete operations.
23 17 CHAR(1) Qdbftrgf Trigger flags.
23 17 0 BIT(1) Qdbfalrc Allow repeated change indicator. If on, repeated changes are allowed.
| 23 17 1 BIT(2) Qdbftths Trigger threadsafe indicator.
| B'00' Not known.
| B'10' Not threadsafe.
| B'11' Threadsafe.
| 23 17 3 BIT(2) Qdbftmta Multithreaded job action indicator.
| B'01' Run, send diagnostic.
| B'10' Do not run, send escape.
| B'11' Run, do not send message.
| 23 17 5 BIT(1) Qdbftqmt QMLTTHDACN system value use. If on, the system value was used to
| determine Qdbftmta.
| 23 17 6 BIT(2) Reserved_200 Reserved.
24 18 CHAR(24) Reserved_201 Reserved.

Constraint Definition Header

(Qdb_Qdbf_Constraint): You can locate this section
with the offset Qdbfofcs located in the physical file specific
attributes section, Qdbfphys.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbf_csto Offset from Qdbf_Constraint to the next section for this constraint.
4 4 BINARY(4) Qdbf_hlen Constraint entry header length in bytes.

34-82 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
8 8 CHAR(1) Qdbf_type Constraint type (TYPE)
F Referential constraint
P Primary unique constraint
U Unique constraint.
C Check constraint.
9 9 CHAR(1) Qdbf_chkpd Check pending attribute.
N The constraint is not in check pending.
Y The constraint is in check pending.
10 A CHAR(1) Qdbf_state Constraint state.
D The constraint is defined.
E The constraint is established.
11 B CHAR(1) Qdbf_abled Constraint enablement.
D The constraint is disabled.
E The constraint is enabled.
12 C CHAR(13) Qdbf_add_ts Constraint date. The date is in the internal standard format (ISF),
CYYMMDDHHMMSS.
25 19 CHAR(10) Qdbf_cst_lin Constraint library name.
35 23 BINARY(4) Qdbf_cst_lp2 Constraint name (delimited) length
39 27 CHAR(25) Reserved_54 Reserved.
64 40 CHAR(258) Qdbf_cst_name Constraint name (CST).

Constraint Definition Entries: The number of con- Ÿ A primary unique constraint, type P, has one Qdbf_Keyn
straint definition entries depends on the type of constraint. structure.
Ÿ A referential constraint, type F, has three structures in Ÿ A check constraint, type C, has one Qdbf_Chk_Cst
this sequence: structure.
1. Qdbf_Keyn for parent file
Constraint Keys (Qdb_Qdbf_Keyn): This section is
2. Qdbf_Keyn for dependent file located with the offset Qdbf_Hlen in the constraint definition
header, Qdbf_Constraint (page 34-82). When the constraint
3. Qdbf_Riafk_Afkd
is referential constraint, the offset to the next section is
Ÿ A unique constraint, type U, has one Qdbf_Keyn struc- located with the offset Qdbf_Kslen in this structure.
ture.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbf_kslen Constraint key structure length. The length, in bytes, of this constraint
key structure. This is also the offset to from Qdbf_Keyn (page 34-83) to
the next structure for this constraint.
4 4 BINARY(4) Qdbf_nokys Number of keys, 1 through 120. The number of key fields for the con-
straint key.
8 8 BINARY(4) Qdbf_klen Constraint key length.
12 C CHAR(52) Revcst_7 Reserved.
64 40 Array of Qdbf_narray Key name array.
CHAR(32)

Key Name Array (Qdb_Qdbf_Narray): This array

follows the constraint keys structure, Qdbf_Keyn (page
34-83). The number of constraint key name array entries is
in field Qdbf_nokys in the constraint keys structure.

Chapter 34. File APIs 34-83

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbf_kname Key name (PRNKEY KEY)
10 A CHAR(22) Revcst_6 Reserved.

Referential Constraint Definition

(Qdb_Qdbf_Riafk_Afkd): You can locate this section
with the offset, Qdbf_kslen, in the constraint keys structure,
Qdbf_Keyn (page 34-83), that precedes this structure. This
structure exists only if the constraint is a referential con-
straint.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(64) Parent file (PRNFILE).
0 0 CHAR(10) Qdbf_riafk_pkfn Parent file name.
10 A CHAR(10) Qdbf_riafk_pkln Parent file library name.
20 14 CHAR(44) Revcst_3 Reserved.
64 40 CHAR(1) Qdbf_riafk_fkcdr Delete rule (DLTRULE).
C *CASCADE
D *SETDFT
L *SETNULL
N *NOACTION (default value)
R *RESTRICT
65 41 CHAR(1) Revcst_4 Reserved
66 42 CHAR(1) Qdbf_riafk_fkcur Update rule (UPDRULE)
N *NOACTION (default value)
R *RESTRICT
67 43 CHAR(61) Revcst_5 Reserved.

Check Constraint (Qdb_Qdbf_Chk_Cst): This section

is located with the offset Qdbf_Hlen in the constraint defi-
nition header, Qdbf_Constraint. This structure exists only if
the constraint is a check constraint.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbf_chkcst_len Check constraint structure length. The length, in bytes, of the check
constraint structure Qdb_Qdbf_Chk_Cst.
4 4 BINARY(4) Qdbf_chkexpr_len Check constraint expression length. The length of the check constraint
expression Qdbf_chkexpr.
8 8 CHAR(24) Revcst_8 Reserved.
32 20 CHAR(*) Qdbf_chkexpr Check constraint expression.

| Datalink Header (Qdb_Qdbfdtalnk): This section is

| the header for the datalink columns that have linked servers.
| There will be one header and one or more datalink column
| entries defined by the Qdb_Qdbfdlcole structure (page
| 34-85). You can locate this structure with the offset,
| Qdbfodl, in the Physical File Specific Attributes structure,
| Qdbfphys (page 34-81).

34-84 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

| Offset
| Dec Hex Bit Type Field Description
| 0 0 BINARY(4) Qdbfdlcoln Number of datalink columns with links to servers.
| 4 4 BINARY(4) Qdbfdlocole Offset from the start of Qdb_Qdbfdtalnk to the first datalink column
| entry, Qdb_Qdbfdlcole (page 34-85).
| 8 8 CHAR(1) Qdbfdllnkp Link pending attribute. Link pending is a state that indicates to the
| user the file has one or more datalink field values (under the file link
| control attribute) where the system does not know whether or not the
| field is really linked to a file on the DataLink File Manager server. The
| Datalink File Manager is a function that tracks which files are linked to
| a specific database file.
| N The file is not in link pending.
| Y The file is in link pending.
| 9 9 CHAR(23) Revdl_1 Reserved.

| Datalink Column Entry (Qdb_Qdbfdlcole): This

| section repeats for the number of columns (Qdbfdlcoln)
| defined in structure Qdb_Qdbfdtalnk (page 34-84). You can
| locate the first column entry using offset Qdbfdlocole in struc-
| ture Qdb_Qdbfdtalnk (page 34-84). Since Qdb_Qdbfdlcole is
| a varying length structure, use length Qdbfdlcelen to get to
| the next column entry.

| Offset
| Dec Hex Bit Type Field Description
| 0 0 BINARY(4) Qdbfdlcelen Length of this datalink column entry. Use this length to get to the next
| datalink column entry.
| 4 4 BINARY(4) Qdbfdlsevn Number of servers linked for this column.
| 8 8 CHAR(10) Qdbfdlcolnm Column name.
| 18 12 CHAR(14) Revdl_2 Reserved.
| 32 20 Array of Qdbfdlsevnm Array of server names linked to the datalink column. The number of
| CHAR(254) array entries is defined by Qdbfdlsevn.

Record ID Codes (Qdb_Qdbfdrtb): This section

describes the record ID codes for program described phys-
ical files. The record ID code information is an array with
variable length entries. You can locate this section with the
offset, Qdbforid, located in the physical file specific attributes
section, Qdbfphys (page 34-81).

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(16) Record ID code header.
0 0 BINARY(2) Qdbfdrnum Number of record ID code array entries, 0 through 70.
2 2 BINARY(4) Qdbfdrtl Size of this record ID code table in bytes, 0 through 256.
6 6 CHAR(10) Reserved_33 Reserved.
16 10 Array of Qdbfdrae Record ID code array entry.
CHAR(32)

Record ID Codes Array (Qdb_Qdbfdrae): This array

follows the record ID codes structure, Qdb_Qdbfdrtb (page
34-85). The number of record ID code array entries is in
Qdbfdrnum.

Chapter 34. File APIs 34-85

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(4) Reserved_34 Reserved.
4 4 CHAR(10) Qdbfdrnm External name.
14 E BINARY(2) Qdbfdrrp Relative field position, 1 through 8000. The relative position of the field
in the record format.
16 10 CHAR(2) Qdbfdrco Comparison operator.
EQ Compare equal.
NE Compare not equal.
ZN Compare zone.
NZ Compare not zone.
DG Compare digit.
ND Compare not digit.
18 12 BINARY(2) Qdbfdrln Length of test value. Test value length must be 1.
20 14 CHAR(1) Qdbfdrtv Test value.
21 15 CHAR(1) Qdbfdrao AND/OR/last operator.
0 Last operator entry.
1 AND with next array entry.
2 OR with next array entry.
22 16 CHAR(10) Reserved_35 Reserved.

Logical File Specific Attributes (Qdb_Qdbflogl):

You can locate this section with the offset, Qdbflfof, located
in the FDT header section, Qdb_Qdbfh.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbfoj Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the join specifications, Qdbfj (page 34-87).
4 4 BINARY(2) Qdbfscsn Total number of select/omit statements for all record formats, 1 through
32,767.
6 6 CHAR(10) Qdbflxp Record format selector program (FMTSLR)
X'00' No record format selector program (*NONE).
16 10 CHAR(10) Qdbflxl Record format selector program library (FMTSLR)
X'00' No record format selector program (*NONE).
26 1A BINARY(4) Qdbfovw Offset from the start of the FDT header, Qdb_Qdbfh (page 34-87), to
the SQL view area, Qdb_Qdbfv (page 34-87).
30 1E CHAR(1) Qlfa Logical file attributes
30 1E 0 BIT(2) Reserved_36 Reserved.
30 1E 2 BIT(1) Qdbfjoin Join logical file indicator (JFILE). If on, the file is a join logical file.
30 1E 3 BIT(1) Qdbfdyns Dynamic selection indicator (DYNSLT). If on, the selection and omis-
sion tests specified for the file are done when the file is read. If off,
when the access path is updated.
30 1E 4 BIT(1) Qdbfsqlv SQL view indicator. If on, the file is an SQL view.
30 1E 5 BIT(1) Qdbfsqli SQL index indicator. If on, the file is an SQL index.
30 1E 6 BIT(2) Reserved_37 Reserved.
31 1F CHAR(1) Qdbfjtyp Join file type.
I An inner join. Default entries are not supplied if a join
value does not exist.
P A partial outer join. Default values are supplied if a join
value does not exist.

34-86 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
32 20 BINARY(2) Qdbfsrcd Coded character set identifier (CCSID) for select/omit constants.
0 There are no select/omit constants for the file.
1 through 65,535
The CCSID.
34 22 CHAR(1) Qdbfwchk With check option.
C The with-check option was specified with cascade.
L The with-check option was specified with local.
N No with-check option was specified.
The value N is set for all logical files. The values C and L only apply to
SQL views.
35 23 CHAR(13) Reserved_38 Reserved.

SQL View Area (Qdb_Qdbfv): The SQL view area

contains the SQL select statement. You can locate this
section with the offset, Qdbfovw, located in the logical file
specific attributes section, Qdbflogl (page 34-86).

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(56) SQL view area header.
0 0 CHAR(56) Reserved_39 Reserved.
56 38 SQL select statement structure
56 38 BINARY(4) Qdbfvssl Select statement length.
60 3C CHAR(*) Qdbfvsst SQL select statement.

Join Specifications (Qdb_Qdbfj): The join specifica-

tions are a linked list. There is an entry in the linked list for
each join to-file. Each entry defines the join logical file's
based on physical files and the fields in the from-file and the
to-file used to join the based on physical file.

You can locate this section with the offset, Qdbfoj, located in
the FDT header section, Qdb_Qdbfh (page 34-75).

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbfjnho Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the join specifications, Qdbfj (page 34-87), for the next join to-file.
4 4 CHAR(4) Reserved_40 Reserved.
8 8 BINARY(2) Qdbfjknum Number of join field specifications (JFLD), 1 through 32,767.
10 A BINARY(2) Qdbfjdnum Number of join duplicate sequence specifications (JDUPSEQ), 1
through 32,767.
12 C BINARY(2) Qdbfjffnum Join from-file number (JOIN), 1 through 31. This number indicates
which based on physical file to join the to-file from.
14 E BINARY(2) Qdbfjtfnum Join to-file number (JOIN), 2 through 32. This number indicates which
based on physical to-file this join specification relates to.
16 10 CHAR(24) Reserved_41 Reserved.
40 28 BINARY(4) Qdbfjsao Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the join specification array, Qdbfjfld (page 34-88), for this join to-file.

Chapter 34. File APIs 34-87

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
44 2C BINARY(4) Qdbfjdao Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the join duplicate sequence array, Qdbfjdup (page 34-88), for this join
to-file.

Join Specification Array (Qdb_Qdbfjfld): You can

locate this section with the offset, Qdbfjsao (page 34-87),
located in the join header section, Qdbfj. The number of join
specification array entries may be up to one less than the
number of data members, Qdbflbnum (page 34-76), located
in the FDT header section, Qdb_Qdbfh.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbfjfnm Join from-field-name (JFLD)
10 A BINARY(2) Qdbfjfnum Join from-field reference number.
0 Join from-field is a field in the join logical file's record
format.
1 through 31 The number of the base on physical from-file corre-
sponding with its position in the JFILE statement that
contains this join from-field.
12 C CHAR(2) Reserved_42 Reserved.
14 E CHAR(2) Qdbfjop Join operation. This is always set to 'EQ'.
16 10 CHAR(10) Qdbfjtnm Join to-field name (JFLD).
26 1A BINARY(2) Qdbfjtnum Join to-field reference number.
0 The join to-field is a field in the logical file's record
format.
2 through 32 The number of the based on physical to-file corre-
sponding with its position in the JFILE statement that
contains this join to-field.
28 1C CHAR(20) Reserved_43 Reserved.

Join Duplicate Sequence Specification Array

(Qdb_Qdbfjdup): You can locate this section with the
offset, Qdbfjdao (page 34-87), in the join section, Qdbfj. The
number of join specification array entries may be up to one
less than the number of data members, Qdbflbnum (page
34-76), located in the FDT header section, Qdb_Qdbfh.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbfjdnm Join specification field name (JDUPSEQ).
10 A BINARY(2) Qdbfjdjnum Join sequence field name reference number.
0 The join sequencing field name is a file in the join logical
file's record format.
2 through 32 The number of the based on physical to-file corre-
sponding with its position in the JFILE statement that
contains this sequencing field name.
12 C CHAR(1) Qjsfna Join sequencing field name attributes.
12 C 0 BIT(1) Qdbfjdd Ascending/descending sequence indicator. If on, indicates a
descending field (*DESCEND).
12 C 1 BIT(7) Reserved_44 Reserved.
13 D CHAR(19) Reserved_45 Reserved.

34-88 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Alternative Collating Sequence Table

(Qdb_Qdbfacs): You can locate this section with the
offset, Qdbfocs (page 34-80) in the FDT header section,
Qdb_Qdbfh. This section is also referred to as the Sort
Sequence Table. A sort sequence table can be either single-
byte or UCS-2. If the UCS-2 table length,
Qdbf_UCS2_Srtseq_Len, is non-zero, then it is a UCS-2 sort
sequence table and the single-byte table, Qdbfacst, will be
cleared.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(256) Qdbfacst Alternative collating sequence table or single-byte sort sequence
(ALTSEQ/STRSEQ) table.
256 100 BINARY(2) Qdbfccsd Coded character set identifier (CCSID) for the single-byte table.
258 102 CHAR(20) qdbfsrts Sort sequence table.
258 102 CHAR(10) Qdbftbln Sort sequence table name.
268 10C CHAR(10) Qdbftbll Sort sequence table library name.
278 116 CHAR(1) Qdbfsrtf Sort sequence table attributes.
278 116 0 BIT(1) Qdbfwght Sort sequence table weight indicator for the single-byte table. If on,
indicates the sort sequence table is unique weighted. If off, it is share
weighted.
278 116 1 BIT(1) Qdbfsubc Sort sequence table substitution character indicator for the single-byte
table. If on, indicates the sort sequence table has substitution char-
acter.
278 116 2 BIT(1) Qdbf_UCS2_Wght Sort sequence table weight indicator for the UCS-2 table. If on, indi-
cates the sort sequence table is unique weighted. If off, it is share
weighted.
278 116 3 BIT(5) Reserved_104 Reserved.
279 117 BINARY(4) Qdbf_UCS2 Length of the UCS-2 sort sequence table, Qdbf_UCS2_Srtseq, in bytes.
_Srtseq_Len
283 11B BINARY(2) Qdbf_UCS2_Ccsd Coded character set identifier (CCSID) for the UCS-2 table.
285 11D CHAR(19) Reserved_101 Reserved.
304 130 CHAR(*) Qdbf_UCS2 UCS-2 sort sequence table. The table exists if the length,
_Srtseq Qdbf_UCS2_Srtseq_Len, is greater than zero.

IDDU/SQL Data Dictionary Area (Qdb_Qdbfdic):

You can locate this section with offset Qdbfodic (page 34-79)
in the FDT header section, Qdb_Qdbfh.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(1) Qdbfdilk Data dictionary link status.
L The file is linked to the a data dictionary.
U The file is not linked to the a data dictionary.
1 1 CHAR(10) Qdbfinm Data dictionary library name.
11 B CHAR(10) Qdbfifd Data dictionary file definition name.
21 15 CHAR(11) Qdbfdiid Data dictionary internal file definition identifier. This field maps to
ZONED(11,0).
32 20 CHAR(4) Reserved_46 Reserved.
36 24 BINARY(4) Qdbfdicl Data dictionary file definition comment length.

Chapter 34. File APIs 34-89

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
40 28 BINARY(2) Qdbfdicc Data dictionary file definition comment CCSID.
0 There is no comment for the file.
1 through 65,535
The CCSID of the comment.
42 2A BINARY(4) Qdbfolng Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the SQL long/alias file names area, Qdbflngn (page 34-90).
46 2E BINARY(2) Qdbflnnum Number of long/alias file names for the file.
48 30 CHAR(16) Reserved_47 Reserved.
64 40 CHAR(*) Qdbfdict Data dictionary file definition comment text.

SQL Long/Alias File Name Area (Qdb_Qdbflngn):

The SQL long/alias file name area contains the files alternate
names that can be used to access the file when using the
system's SQL interfaces. You can locate this section with
the offset, Qdbfolng (page 34-90), in the IDDU/SQL data dic-
tionary section.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qdbflnel Long/alias file name entry length in bytes. The length of this entry.
This is also the offset from Qdbflnen to the next long/alias entry.
2 2 CHAR(1) Qdbflnfl Long/alias file name flags.
2 2 0 BIT(1) Qdbflndl Long/alias file name input delimited indicator. If on, indicates the
long/alias file name was delimited when input.
2 2 1 BIT(7) Reserved_111 Reserved
3 3 BINARY(2) Qdbflnlg Long/alias file name (non-delimited) length.
5 5 CHAR(11) Reserved_112 Reserved.
16 10 CHAR(*) Qdbflnam Long/alias file name (non-delimited).

File Scope Array (Qdb_Qdbfb): A file scope array is Non-join logical files have one entry for each based on phys-
present for all database files. The number of data members, ical file. The entry names the based on physical file and
Qdbflbnum (page 34-76), contains the number of file scope describes the logical file record format to use with that file.
array entries. Each entry contains a based on physical file
name and, optionally, a record format name. Join logical files have one entry for each based on physical
file. The entry names the based on physical file. Only the
Externally described physical files have one entry that names first entry describes the logical file record format.
the physical file record format. The entry's file name portion
is not used. SQL view logical files have one entry for each based on
physical file. The entry names the based on physical file that
Program described physical files have one entry for each will be either an externally described physical file or another
data dictionary record format. The entry names the data dic- view logical file. Only the first entry describes the logical file
tionary record format. The entry's file name portion is not record format.
used.
You can locate this section with the offset, Qdbfos (page
34-80), in the FDT header section, Qdb_Qdbfh.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(48) Reserved_48 Reserved.
48 30 CHAR(10) Qdbfbf Based on physical file name.
58 3A CHAR(10) Qdbfbfl Based on physical file library name.

34-90 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
68 44 CHAR(10) Qdbft Record format name.
78 4E CHAR(37) Reserved_49 Reserved.
115 73 BINARY(2) Qdbfbgky Record format generic key field count, 0 through 120. If this file has an
arrival sequence access path, this field is not applicable.
117 75 CHAR(2) Reserved_50 Reserved.
119 77 BINARY(2) Qdbfblky Record format maximum key length, 1 through 2000. If this file has an
arrival sequence access path, this field is not applicable.
121 79 CHAR(2) Reserved_51 Reserved.
123 7B BINARY(2) Qdbffogl Record format generic key length, 1 through 2000. If this file has an
arrival sequence access path, this field is not applicable.
125 7D CHAR(3) Reserved_52 Reserved.
128 80 BINARY(2) Qdbfsoon Number of select/omit statements, 1 through 32,767.
130 82 BINARY(4) Qdbfsoof Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the select/omit specification array, Qdbfss (page 34-91).
134 86 BINARY(4) Qdbfksof Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the key specification array, Qdbfk (page 34-93).
138 8A BINARY(2) Qdbfkyct Record format full key field count, 0 through 120. If this file has an
arrival sequence access path, this field is not applicable.
140 8C BINARY(2) Qdbfgenf Generic key field count for all record formats with this record format
name, 0 through 120. If this file has an arrival sequence access path,
this field is not applicable.
142 8E BINARY(4) Qdbfodis Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75) to the
distributed file definition section.
146 92 CHAR(14) Reserved_53 Reserved.

Select/Omit Specification Array (Qdb_Qdbfss): array. The first scope array entry for the join logical file con-
The select/omit specification array entries describe the record tains the offset to the select/omit specification array.
format fields to which the select/omit statement refer.
You can locate this section with the offset Qdbfsoof (page
Non-join logical files can have one select/omit specification 34-91) in the scope array entry section.
array for each file scope array entry.

Join logical files can have only one select/omit specification

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(2) Reserved_54 Reserved.
2 2 CHAR(1) Qdbfssso Select/omit statement rule.
A A select/omit ANDed statement.
O A select/omit omit statement.
S A select/omit select statement.
3 3 CHAR(2) Qdbfssop Select/omit statement comparison (ALL COMP VALUES)
AL Statement comparison for all (ALL).
EQ Statement comparison for equal to (COMP EQ).
GE Statement comparison for greater than or equal to
(COMP GE).
GT Statement comparison for greater than (COMP GT).
LE Statement comparison for less or equal to (COMP LE).
LT Statement comparison for less than (COMP LT).
NE Statement comparison for not equal to (COMP NE).
NG Statement comparison for not greater than (COMP NG).
NL Statement comparison for not less than (COMP NL).
VA Statement comparison for values (VALUES).

Chapter 34. File APIs 34-91

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
5 5 CHAR(10) Qdbfssfn Select/omit statement field name.
15 F BINARY(2) Qdbfsspnum Number of select/omit statement parameters, 1 through 32,767.
17 11 CHAR(1) Qsosaf Select/omit statement attribute flags.
17 11 0 BIT(7) Reserved_55 Reserved.
17 11 7 BIT(1) Qdbfssfi Select/omit statement external or internal name indicator. If on, indi-
cates the statement is field name is an external record format name.
18 12 BINARY(2) Qdbfssfj Select/omit statement join reference number (JREF), 1 through 32. If
this is not a join logical file, this field is not applicable.
20 14 CHAR(8) Reserved_56 Reserved.
28 1C BINARY(4) Qdbfsoso Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the select/omit parameters, Qdbfsp (page 34-92), for this select/omit
statement.

Select/Omit Parameters (Qdb_Qdbfsp): This is a

linked list of parameter descriptions. This section describes
the parameter values for this particular select/omit statement.
The parameters are either a compare value or another
record format field.

You can locate this section with the offset Qdbfsoso (page
34-92), in the select/omit array section, Qdbfss.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qdbfspno Offset from the start of the FDT header, Qdb_Qdbfh (page 34-75), to
the next select/omit parameter for this select/omit statement.
4 4 BINARY(2) Qdbfspln Select/omit parameter length, 1 through 32,767.
6 6 CHAR(1) Qdbfspin Select/omit parameter attribute indicator.
X'00' The parameter is a compare value.
X'01' The parameter is a internal record format field.
X'02' The parameter is an external record format field.
7 7 CHAR(1) Qasopaf Select/omit attribute flags.
7 7 0 BIT(1) Qdbfsigc Double-byte character set (DBCS) and/or graphic data indicator. If on,
indicates the non-field compare value contains DBCS or graphic data.
7 7 1 BIT(1) Qdbfshex Hexadecimal data indicator. If on, indicates the non-field compare
value is hexadecimal data.
7 7 2 BIT(1) Qdbfsnul Null value indicator. If on, indicates the non-field compare value is the
null value.
7 7 3 BIT(5) Reserved_57 Reserved.
8 8 BINARY(2) Qdbfsppj Select/omit parameter join reference number (JREF), 1 through 32.
This field is not applicable if this file is not a join logical file or the
compare value is a non-field value.
10 A CHAR(10) Reserved_58 Reserved.
20 14 CHAR(*) Qdbfspvl Select/omit parameter compare value or the record format field name.
This is the compare value when Qdbfspin contains X'00'. This is the
record format field name when Qdbfspin contains X'01' or X'02'.

34-92 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Key Specification Array (Qdb_Qdbfk): The key The first scope array entry for the join logical file contains the
specification array entries describe the record format fields offset to the file's key specification array.
used in defining the file access path.
You can locate this section with the offset Qdbfksof (page
Non-join logical files can have one key specification array for 34-91) in the scope array entry section, Qdbfb.
each file scope array entry.

Join logical files can have only one key specification array.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbfkfld Key statement field name. X'40's indicate the key statement is a
*NONE key field.
10 A CHAR(3) Reserved_59 Reserved.
13 D CHAR(1) Qdbfksq Key statement sequencing attribute flags.
13 D 0 BIT(1) Qdbfksad Ascending/descending sequence indicator. If on, indicates the
descending sequence (*DESCEND).
13 D 1 BIT(2) Qdbfksn Numeric key field sequencing indicators.
B'00' The numeric key field sequences as a string of unsigned
binary data (UNSIGNED).
B'01' The numeric key field ignores the sign of the field and
sequences as absolute value data (ABSVAL).
B'10' The numeric key field considers the sign of the field and
sequences as signed value data (SIGNED).
13 D 3 BIT(1) Reserved_60 Reserved.
13 D 4 BIT(1) Qdbfksac Alternate collating sequence indicator (ALTSEQ). If on, indicates the
alternate collating sequence table applies to this key field.
13 D 5 BIT(1) Qdbfkszf Force zone sequencing indicator. If on, indicates the zone portion of
the key field is zeroed so only the digit portion (furthest right four bits) is
used in key sequencing (DIGIT). If off, the zone portion is not zeroed.
13 D 6 BIT(1) Qdbfksdf Force digit sequencing indicator. If on, indicates the digit portion of the
key field is zeroed so only the zone portion (furthest left four bits) is
used in key sequencing (ZONE). If off, the digit portion is not zeroed.
13 D 7 BIT(1) Qdbfkft Key statement external or internal name indicator. If on, indicates the
field name is the external record format name.
14 E CHAR(18) Reserved_61 Reserved.

Distributed File Definition Section and Partition Key

Array (Qdb_Qdbf_dis_pkeyarr): The distributed file
definition section and partition key array contains the node
group name and library name for the distributed file and the
record format fields used in defining the partition key for each
scope entry.

You can locate this section with the offset Qdbfodis (page
34-91) in the scope array entry section, Qdbfb.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbf_dis_ndgpn Distributed file node group name.
10 A CHAR(10) Qdbf_dis_ndgpl Distributed file node group library name.
20 14 BINARY(4) Qdbf_dis_nkyn Number of partition key fields for this scope entry.
24 18 CHAR(40) Reserved_121 Reserved.

Chapter 34. File APIs 34-93

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
64 40 ARRAY Qdbf_dis_pkeyarr Distributed file partition key array.
of
CHAR(32)
64 40 CHAR(10) Qdbf_dis_kname Partition key field name.
74 4A CHAR(22) Reserved_122 Reserved.

Journal Information (Qdb_Qdbfjoal): This section

contains the journal information for the physical file. You can
locate this section with offset Qdbfjorn (page 34-80) in the
FDT header section, Qdb_Qdbfh (page 34-75).

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Qdbfojrn Journal name.
10 A CHAR(10) Qdbfolib Journal library name.
20 14 CHAR(1) Qdbfojpt Journaling options.
20 14 0 BIT(1) Reserved_106 Reserved.
20 14 1 BIT(1) Qdbfjbim Before image indicator. If on, indicates the before images are being
journaled.
20 14 2 BIT(1) Qdbfjaim After image indicator. If on, indicates the after images are being jour-
naled.
20 14 3 BIT(1) Reserved_107 Reserved.
20 14 4 BIT(1) Qdbfjomt Omit journal entries indicator. If on, indicates the open and close
entries are being omitted from the journal.
20 14 5 BIT(3) Reserved_108 Reserved.
21 15 CHAR(1) Qdbfjact Journaling options.
0 The file is not being journaled.
1 The file is being journaled.
22 17 CHAR(13) Qdbfljrn Last journaling date stamp. This is the date that corresponds to the
most recent time that journaling was started. The date is in internal
standard format (ISF), CYYMMDDHHMMSS.
35 23 CHAR(29) Reserved_105 Reserved.

FILD0200 Format (Qdb_Qddfmt Structure): FILD0200 offsets of the fields in this structure are in the tables imme-
provides the format used by the records of the specified file. diately following Figure 34-4 on page 34-95.
This structure is also used by the QQQQRY API to get data
from the named file. Figure 34-4 on page 34-95 shows how The descriptions and offsets are available in the include
this information is organized. When more than one entry can source supplied on the AS/400 system. You can see this
appear, the figure indicates this as in .6/. Descriptions and source in source file H, member name QDBRTVFD, in the
QSYSINC library.

34-94 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

| Figure 34-4. FILD0200 Format

Format Definition Header (Qdb_Qddfmt): This

section is always located at the beginning of the returned
data area.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qddbyrtn Bytes returned. The total length, in bytes, of the data returned.
4 4 BINARY(4) Qddbyava Bytes available. The total length, in bytes, of the format.
8 8 CHAR(24) Reserved_62 Reserved.

Chapter 34. File APIs 34-95

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
32 20 0 CHAR(1) Qddfmtf Record format DBCS flags.
32 20 0 BIT(1) Qddfrity Double byte character set and/or graphic data. If on, indicates the
format contains DBCS or graphic data.
32 20 1 BIT(1) Qddfrilt Double byte character set and/or graphic literals. If on, indicates the
format contains DBCS or graphic literals.
32 20 2 BIT(1) Qddfritx Double byte character set record format text description. If on, indi-
cates the text description contains DBCS data.
32 20 3 BIT(1) Qddfrmep Mapping error possible. If on, indicates the format contains fields that
may return mapping errors.
32 20 4 BIT(1) Qddfrdrv Derived fields (logical files only). If on, indicates the format contains
fields derived from fields in the physical file on which the logical file is
based, or from fields in this logical file.
32 20 5 BIT(1) Qddfrni Neither or input-only files (logical files only). If on, indicates the format
contains fields that cannot be used for input or output operations, or
fields that can be used for input operations only.
32 20 6 BIT(1) Qddfrdfi Default values (physical files only). If on, indicates the format contains
fields with default values (DFT).
32 20 7 BIT(1) Qddfcato Concatenated fields (logical files only). If on, indicates the format con-
tains fields that are concatenations of two or more fields from the phys-
ical file.
33 21 BINARY(4) Qddfxlto Offset from the start the Qdb_Qddfmt (page 34-95) header to the trans-
late table specifications, Qddfxl (page 34-113).
37 25 BINARY(4) Qddfrcao Offset from the start of the Qdb_Qddfmt (page 34-95) header to the
case selection specifications, Qddfcsl (page 34-113).
41 29 BINARY(4) Qddfdico Offset from the start of the Qdb_Qddfmt (page 34-95) header to the
IDDU/SQL dictionary format information, Qddfdic (page 34-112).
45 2D BINARY(2) Qddfrcid Common coded character set identifier. Before using this field, see if
Qddfrsid (page 34-97) is zero. If it is zero, not all character fields in the
format use the same CCSID and this field is not valid.
47 2F BINARY(2) Qddfsrcd Source file coded character set identifier. The CCSID for the character
portion of the source file containing the DDS used to create the format.
49 31 BINARY(2) Qddfrtcd Format text coded character set identifier. The CCSID for the informa-
tion about the text description.
51 33 BINARY(2) Qddfrlcd Long comment coded character set identifier. The CCSID for the infor-
mation about the format content and purpose.
53 35 CHAR(7) Reserved_64 Reserved.
60 3C CHAR(1) Qddftflgs Format flags.
60 3C 0 BIT(1) Qddfr12 Reserved.
60 3C 1 BIT(1) Qddfucsd If on, the format contains UCS-2 fields.
| 60 3C 2 BIT(1) Qddfdlnk If on, the format contains datalink fields.
| 60 3C 3 BIT(1) Qddfdudt If on, the format contains user-defined type fields.
| 60 3C 4 BIT(1) Qddfdlob If on, the format contains large object fields.
60 3C 5 BIT(3) Reserved_114 Reserved.
61 3D CHAR(1) Qddflgs Flags
61 3D 0 BIT(1) Reserved_65 Reserved.
61 3D 1 BIT(1) Qddfrvar Variable length fields. If on, indicates the format contains variable
length fields (VARLEN).
61 3D 2 BIT(1) Qddfrgph Graphic fields. If on, indicates the format contains graphic data fields.
61 3D 3 BIT(1) Qddfrdtt Date, time, or timestamp fields. If on, indicates the format contains
data, time, or timestamp fields.

34-96 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
61 3D 4 BIT(1) Qddfrnul Null capable fields. If on, indicates the format contains null capable
fields.
61 3D 5 BIT(1) Qddfrsid Common coded character set identifier flag. If on, indicates all char-
acter fields use the same CCSID.
61 3D 6 BIT(1) Qddfesid Explicit coded character set identifier flag. If on, indicates a CCSID was
specified for the format file or for one or more fields in the format.
61 3D 7 BIT(1) Reserved_66 Reserved.
62 3E CHAR(4) Reserved_67 Reserved.
66 42 BINARY(4) Qddfrlen Record length. The sum of the lengths of all format fields excluding
neither fields.
70 46 CHAR(10) Qddfname Record format name.
80 50 CHAR(13) Qddfseq Level identifier. The modification level identifier of the format, used to
verity the format has not changed since compile time, if LVLCHK(*YES)
is requested.
93 5D CHAR(50) Qddftext Text description (TEXT)
143 8F BINARY(2) Qddffldnum Number of fields. The number of fields in the format. There is one field
header for each field.
145 91 CHAR(111) Reserved_68 Reserved.
256 100 Array of Qddffldx Start of field definition array (Qdb_Qddffld).
CHAR(*)

Field Header (Qdb_Qddffld): This section is located

immediately after the Qdb_Qddfmt (page 34-95) header.
The number of entries in this structure is defined by variable
Qddffldnum (page 34-97) in the Qdb_Qddfmt header. This
structure is to be defined at variable Qddffldx (page 34-97) in
the Qdb_Qddfmt header.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qddfdefl Length of field header structure. The length of each occurrence of the
field header structure, including all subsections.
4 4 CHAR(30) Qddffldi Internal field name. The name of the physical format field. If this is a
logical format, the name of the physical field on which the logical field is
based.
34 22 CHAR(30) Qddfflde External field name. If this is a logical format, the logical format field
name. If this is a physical format, the internal name is a duplicate of
Qddfflde.

Chapter 34. File APIs 34-97

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
64 40 CHAR(2) Qddfftyp Data type.
X'0000' BINARY
X'0001' FLOAT
X'0002' ZONED DECIMAL
X'0003' PACKED DECIMAL
X'0004' CHARACTER
| X'8004' VAR CHARACTER
| X'0005' GRAPHIC
| X'8005' VAR GRAPHIC
| X'0006' DBCS-CAPABLE
| X'8006' VAR DBCS-CAPABLE
| X'000B' DATE
| X'000C' TIME
| X'000D' TIMESTAMP
| X'4004' BLOB/CLOB
| X'4005' DBCLOB
| X'4006' CLOB-OPEN
| X'8044' DATALINK-CHAR
| X'8046' DATALINK-OPEN
| X'FFFF' NULL
66 42 CHAR(1) Qddffiob Usage
X'01' The field can be used for input only.
X'02' Output only.
X'03' Both input and output.
X'04' Neither input nor output.
X'FF' The usage is unknown.
67 43 BINARY(4) Qddffobo Output buffer offset. The offset of this field from the start of the output
buffer.
71 47 BINARY(4) Qddffibo Input buffer offset. The offset of this field from the start of the input
buffer.
75 4B BINARY(2) Qddffldb Length. The length of the field. For character fields: the number of
characters. For float fields: 4 for single, 8 for double. For variable
length fields: the maximum the field can be plus 2. For date, time, or
timestamp fields: the length of the formatted data. For graphic data
fields: the number of bytes. For LOB fields: the number of bytes in the
buffer.
77 4D BINARY(2) Qddffldd Number of digits. The number of digits in the field. For numeric fields:
the number of digits. For graphic data fields: the number of DBCS
characters the field can contain.
79 4F BINARY(2) Qddffldp Decimal positions. The number of position to the right of the decimal
point.
81 51 CHAR(1) Qddffkbs Keyboard shift (RESHIFT) The keyboard shift attribute of the field.
X Alphabetic only.
A Alphameric shift.
N Numeric shift.
S Signed numeric.
Y Numeric only.
D Digits only.
M Numeric only character.
W Katakana.
H Hexadecimal.
I Inhibit keyboard entry.
J DBCS only.
E DBCS either.
O DBCS open.
X'00' No shift expected.
82 52 CHAR(1) Qddffldst Field status byte 1

34-98 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
82 52 0 BIT(1) Qddffiat Double-byte character set (DBCS) alternate type field. If on, indicates
the alternate type for this field contains DBCS data.
82 52 1 BIT(1) Qddffitx Double-byte character set (DBCS) field text description. If on, indicates
the text description contains DBCS data.
82 52 2 BIT(1) Qddffich Double-byte character set (DBCS) column headings. If on, indicates
the column headings contains DBCS data.
82 52 3 BIT(1) Qddffivc Double-byte character set (DBCS) validity checking literals. If on, indi-
cates the compare, range, or values literals contain DBCS data.
82 52 4 BIT(1) Qddffrnd Rounding. Rounding method for the field. If on, indicates round insig-
nificant decimal digits. If off, indicates truncate insignificant decimal
digits.
82 52 5 BIT(1) Qddffcid Character identifier flag. If on, indicates a character identifier was spec-
ified.
82 52 6 BIT(2) Reserved_62 Reserved.
83 53 BINARY(2) Qddfjref Join reference (JREF) (logical files only). For fields whose names are
specified in more than one physical file, this values identifies which
physical file contains the field.
85 55 CHAR(1) Qddffldst2 Field status byte 2.
85 55 0 BIT(1) Qddffnul Allow null value (ALWNULL). If on, indicates the null value is allowed
for this field.
85 55 1 BIT(1) Qddffdft Column default value. If on, indicates the column does not have a
default value.
85 55 2 BIT(1) Qddffvar If on, indicates the column is a variable length field.
85 55 5 BIT(5) Reserved_70 Reserved.
86 56 CHAR(1) Qddflgs2 Flags.
86 56 0 BIT(1) Qddfcorr Correlated field. If on, indicates this is a correlated field.
86 56 1 BIT(1) Qddffrrn File relative record number. If on, indicates this is a relative record
number field.
86 56 2 BIT(5) Reserved_71 Reserved.
86 56 7 BIT(1) Qddffmep Mapping errors possible. If on, indicates the field may return data
mapping errors.
87 57 BINARY(2) Qddfvarx Variable field index. Index into the list of all variable field values for the
query.
89 59 CHAR(2) Reserved_72 Reserved.
91 5B BINARY(2) Qddflalc Allocated length. The number of bytes allocated for the field in the fixed
portion of the file.
Or:
Date/time/timestamp length. The number of bytes the based on field
occupies.

Chapter 34. File APIs 34-99

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
93 5D CHAR(1) Qddfdttf Date format (DATFMT) or time format (TIMFMT), depending on the use
of the field. This field is not valid unless Qddfftyp (page 34-97) is
X'000B', X'000C', or X'000D' except for the following cases. DATFMT
and TIMFMT are valid on '0002'X type logical file fields having based-on
physical file fields that are '000B'X and '000C'X. DATFMT is valid on
'0003'X and '0004'X type logical file fields having based-on physical file
fields that are '000B'X. Some DATFMTs are valid only for the the
'0002'X, '0003'X, and '0004'X fields having based-on physical file
'000B'X fields and are identified (by pseudo date) below.
X'FE' The format associated with the job.
X'FF' The format associated with the QDT.
X'01' The *USA format.
X'03' The *ISO format.
X'05' The *EUR format.
X'07' The *JIS format (date only).
X'09' The SAA timestamp.
X'17' The *MDY format (date only).
X'18' The *DMY format (date only).
X'19' The *YMD format (date only).
X'1A' The *JUL format (date only).
X'1B' The *HMS format (time only).
X'25' The *CMDY format (pseudo date).
X'26' The *CDMY format (pseudo date).
X'27' The *CYMD format (pseudo date).
X'28' The *MDYY format (pseudo date).
X'29' The *DMYY format (pseudo date).
X'2A' The *YYMD format (pseudo date).
X'2B' The *YM format (pseudo date).
X'2C' The *MY format (pseudo date).
X'2D' The *YYM format (pseudo date).
X'2E' The *MYY format (pseudo date).
X'30' The *LONGJUL format (pseudo date).
94 5E CHAR(1) Qddfdtts Date separator (DATSEP) or Time separator (TIMSEP) This field is not
valid unless Qddfftyp (page 34-97) is X'000B', X'000C', or X'000D'.
X'00' The separator associated with the job.
X'EE' The implied separator is used.
'/' The slash is used.
'-' The dash is used.
'.' The period is used.
'' The blank is used.
':' The colon is used.
95 5F BINARY(2) Qddfcsid Common coded character set identifier (CCSID).
00000 The CCSID associated with the job is used.
65535 No data translation is done.
nnnnn The CCSID.
97 61 BINARY(2) Qddftsid Text description common coded character set identifier.
00000 The CCSID associated with the job is used.
65535 No data translation is done.
nnnnn The CCSID.
99 63 BINARY(2) Qddfhsid Column heading common coded character set identifier.
00000 The CCSID associated with the job is used.
65535 No data translation is done.
nnnnn The CCSID.
101 65 BINARY(2) Qddflsid Long comment common coded character set identifier.
00000 The CCSID associated with the job is used.
65535 No data translation is done.
nnnnn The CCSID.

34-100 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
103 67 CHAR(1) Qddfldur Labeled duration. The type of labeled duration this field defines.
X'00' The field not a labeled duration.
X'0D' Year/years.
X'0E' Month/months.
X'0F' Day/days.
X'10' Hour/hours.
X'11' Minute/minutes.
X'12' Second/seconds.
X'13' Microsecond/microseconds.
104 68 CHAR(1) Reserved_73 Reserved.
105 69 BINARY(2) Qddfwsid Edit word common coded character set identifier.
00000 The CCSID associated with the job is used.
65535 No data translation is done.
nnnnn The CCSID.
| 107 6B CHAR(1) Reserved_61 Reserved.
| 108 6C CHAR(1) Reserved_62 Reserved.
| 109 6D BIN(2) Reserved_63 Reserved.
| 111 6F CHAR(1) Qddflagco Flags.
| 111 6F 0 BIT(3) Reserved_64 Reserved.
| 111 6F 3 BIT(1) Qddffucs If on, indicates the column is a UCS-2 field.
| 111 6F 4 BIT(1) Qddfudt If on, indicates the column is a user-defined type field.
| 111 6F 5 BIT(3) Reserved_65 Reserved.
| 112 70 CHAR(68) Reserved_74 Reserved.
| 180 B4 BINARY(4) Qddfcplx Offset from the start of the field header to the field information if the
| field was a user-defined type, datalink, or large object. See structure
| Qdb_Qddfcpli.
| 184 B8 BINARY(4) Qddfbmaxl Maximum length of the large object field.
| 188 BC BINARY(2) Qddfbpadl Pad length of the large object field.
190 BE BINARY(4) Qddfdicd Offset from the start of the field header to the IDDU/SQL dictionary field
information, Qddfdicf (page 34-113).
194 C2 BINARY(4) Qddfdftd Offset from the start of the field header to the default value description,
Qddfdft (page 34-106).
198 C6 BINARY(4) Qddfderd Offset from the start of the field header to the derived field description
(or to the concatenated field description if its file is externally
described), Qddfderv (page 34-106).
202 CA CHAR(6) Reserved_75 Reserved.
208 D0 BINARY(4) Qddftxtd Offset from the start of the field header to the field text description,
Qddfftxt (page 34-106).
212 D4 CHAR(2) Reserved_102 Reserved.
214 D6 BINARY(4) Qddfrefd Offset from the start of the field header to the field reference informa-
tion, Qddfrefi (page 34-102).
218 DA BINARY(2) Qddfedtl Length of the edit code/edit word for the field.
220 DC BINARY(4) Qddfedtd Offset from the start of the field header to the edit code/edit word infor-
mation, Qddfedcw (page 34-104).
224 E0 BINARY(2) Reserved_76 Reserved.
226 E2 BINARY(4) Qddfchd Offset from the start of the field header to the column heading informa-
tion, Qddfcolh (page 34-112).
230 E6 BINARY(2) Qddfvckl Length of validity checking data present for the field.
232 E8 BINARY(4) Qddfvckd Offset from the start of the field header to the validity checking data,
Qddfvchk (page 34-104).

Chapter 34. File APIs 34-101

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
236 EC BINARY(4) Qddfxals Offset from the start of the field header to the alias name entry.
240 F0 BINARY(4) Qddffpnd Offset from the start of the field header to the field prompted numeric
editing information, Qddfdfne (page 34-102).
244 F4 CHAR(8) Reserved_77 Reserved.
252 FC CHAR(*) Qddfvpx Start of the variable portion of the field description.

Reference Information (Qdb_Qddfrefi): You can

locate this section with the offset Qddfrefd (page 34-101) in
the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(1) Qddfrcde Modification flags.
0 0 0 BIT(1) Qddfdupe Modifications. If on, indicates the field has been modified.
0 0 1 BIT(1) Qddfnmec Name modification. If on, indicates the name of the field has been
modified.
0 0 2 BIT(1) Qddftypc Data type modification. If on, indicates the data type of the field has
been modified.
0 0 3 BIT(1) Qddflenc Field length modification. If on, indicates the length of the field has
been modified.
0 0 4 BIT(1) Qddfdecc Precision modification. If on, indicates the precision of the field has
been modified.
0 0 5 BIT(1) Qddfedtc Edit information modification. If on, indicates the edit information of the
field has been modified.
0 0 6 BIT(1) Qddfvc Validity checking information modification. If on, indicates the validity
checking information of the field has been modified.
0 0 7 BIT(1) Qddfothr Other modification. If on, indicates other information of the field has
been modified.
1 1 CHAR(10) Qddfrfil Reference file name.
11 B CHAR(10) Qddfrlib Reference file library.
21 15 CHAR(10) Qddfrfmt Referenced record format.
31 1F CHAR(30) Qddfrfld Referenced field.
61 3D CHAR(19) Reserved_78 Reserved.

Field Prompted Numeric Editing Information

(Qdb_Qddfdfne): You can locate this section with the
offset Qddffpnd (page 34-102) in the field header section,
Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(2) Reserved_80 Reserved.
2 2 CHAR(1) Qddfddts Date separator (DATSEP) or Time separator (TIMSEP).
X'00' This is not a date or time field.
1 The period (.).
2 The slash (/).
3 The colon (:).
4 The dash (-).
5 The comma (,).

34-102 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
3 3 CHAR(1) Qddfddpc Decimal point character. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
1 The period (.).
2 The comma (,).
3 The colon (:).
4 The dollar ($).
5 No decimal point is used.
4 4 CHAR(1) Qddfdtsc Thousands separator character. This field is not valid unless Qddfddts
(page 34-102) contains X'00'.
1 The period (.).
2 The comma (,).
3 The apostrophe (').
4 The blank ( ).
5 No thousands separator is used.
5 5 CHAR(13) Qnsi Negative sign information.
5 5 CHAR(1) Qddfdnsc Display negative sign. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
1 The negative sign is displayed for negative values.
2 The negative is not displayed for negative values.
6 6 CHAR(6) Qddfdnsl Left negative sign value. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
12 C CHAR(6) Qddfdnsr Right negative sign value. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
18 12 CHAR(13) Qcsi Currency symbol information.
18 12 CHAR(1) Qddfdcsv Display currency symbol. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
1 The currency symbol is displayed.
2 The currency symbol is not displayed.
19 13 CHAR(6) Qddfdcsl Left currency symbol value. This field is not valid unless Qddfddts
(page 34-102) contains X'00'.
25 19 CHAR(6) Qddfdcsr Right currency symbol value. This field is not valid unless Qddfddts
(page 34-102) contains X'00'.
31 1F CHAR(1) Qddfdpzv Print zero value. This field is not valid unless Qddfddts (page 34-102)
contains X'00'.
1 A zero value is displayed.
2 A zero value is not displayed.
32 20 CHAR(1) Qddfdrlz Replace leading zeros. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
1 Leading zeros are replaced.
2 Leading zeros are not replaced.
33 21 CHAR(1) Qddfdrlv Leading zero replacement value. This field is not valid unless Qddfddts
(page 34-102) contains X'00'.
1 Blanks ( ).
2 Asterisks (*).
3 Blanks ( ) and the left currency symbol is shifted right.
34 22 CHAR(1) Qddfdlzo Single leading zero. This field is not valid unless Qddfddts (page
34-102) contains X'00'.
1 A zero is displayed to the left of the decimal point when
there are no significant digits to the left of the decimal.
2 A zero is not displayed to the left of the decimal point.
35 23 CHAR(29) Reserved_81 Reserved.

Chapter 34. File APIs 34-103

Retrieve Database File Description (QDBRTVFD) API

Edit Code/Edit Word Information (Qdb_Qddfedcw):

You can locate this section with the offset Qddfedtd (page
34-101) in the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(2) Qddfecdi Edit code information.
0 0 CHAR(1) Qddfecde Edit code (EDTCDE). Edit code for the field when it is referred to
during display or print file creation.
1 1 CHAR(1) Qddfecdx Floating currency symbol.
* Asterisk protection: asterisks are displayed to the left of
significant digits.
A currency symbol indicates the symbol displayed to the left the signif-
icant digits.
2 2 CHAR(14) Reserved_79 Reserved
16 10 CHAR(*) Qddfewd Edit word (EDTWRD). The form in which the field values are displayed.

Validity Checking Information (Qdb_Qddfvchk):

You can locate this section with the offset Qddfvckd (page
34-101) in the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfvcnume Number of validity check entries.
2 2 CHAR(14) Reserved_82 Reserved.
16 10 CHAR(*) Qddfvcen Validity checking entry array.

Validity Checking Entry (Qdb_Qddfvcst): The first

validity checking entry starts at Qddfvcen in the validity
checking information section, Qddfvchk (page 34-104).

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(1) Qddfvccd DDSI keyword identifier.
X'63' CHKMSGID
X'64' CHECK(ME)
X'66' CHECK(FE)
X'67' CHECK(MF)
X'71' RANGE
X'72' VALUES
X'73' COMP(GT)
X'74' COMP(GE)
X'75' COMP(EQ)
X'76' COMP(NE)
X'77' COMP(LE)
X'78' COMP(LT)
X'79' COMP(NL)
X'7A' COMP(NG)
X'A0' CHECK(M10)
X'A1' CHECK(M11)
X'A2' CHECK(VN)
X'A3' CHECK(AB)
X'A5' CHECK(VNE)
X'A6' CHECK(M10F)
X'A7' CHECK(M11F)
1 1 BINARY(2) Qddfvcnump Number of parameters.

34-104 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
3 3 BINARY(2) Qddfvcel Length of this validity checking entry.
5 5 CHAR(11) Reserved_83 Reserved.
16 10 CHAR(*) Qddfvcpm Validity checking parameter array.

Validity Checking Parameter (Qdb_Qddfvcpr): The

first validity checking parameter starts at Qddfvcpm (page
34-105) in the validity checking entry section, Qddfvcst.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfvcpl Length of validity checking parameter Qddfvcpv.
2 2 CHAR(14) Reserved_84 Reserved.
16 10 CHAR(*) Qddfvcpv Validity checking parameter value.

| Complex Object Field Type Information

| (Qdb_Qddfcpli): You can locate this section with the
| offset Qddfcplx (page 34-101) in the field header section,
| Qddffld.

| Offset
| Dec Hex Bit Type Field Description
| 0 0 BINARY(4) Qddflenu Length of the user-defined type name.
| 4 4 CHAR(128) Qddfnudt User-defined type name.
| 132 84 CHAR(10) Qddfludt User-defined type library name.
| 142 8E CHAR(1) Qddfdlink Link control.
| N No link control.
| F File link control.
| 143 8F CHAR(1) Qddfdinte Link integrity. Linked files are under control of the database if the field is
| a datalink.
| A All under control.
| S Selective control. This value is not supported yet.
| 144 90 CHAR(2) Qddfdrper Read permission. The file system controls authority to read a file if the
| field is a datalink.
| FS File system.
| DB Database.
| 146 92 CHAR(2) Qddfdwper Write permission. The file system controls authority to write to a file if
| the field is a datalink.
| FS File system.
| BL Blocked.
| 148 94 CHAR(1) Qddfdreco Recovery. The database manager will recover the file if the field is a
| datalink.
| Y Yes. This value is not supported yet.
| N No.
| 149 95 CHAR(1) Qddfdunlk On unlink. The database manager will either restore the file owner on
| an unlink, or delete the file when unlinking the file.
| R Restore the owner.
| D Delete the file.
| 150 96 CHAR(10) Reserved_150 Reserved.

Chapter 34. File APIs 34-105

Retrieve Database File Description (QDBRTVFD) API

Field Text (Qdb_Qddfftxt): You can locate this section

with the offset Qddftxtd (page 34-101) in the field header
section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(50) Qddfftxt Text (TEXT). Text description of the field.

Alias Name Structure (Qdb_Qddfalis): You can

locate this section with the offset Qddfxals located in the field
header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfalsl Length of alternative name Qddfalsn (page 34-106).
2 2 CHAR(14) Reserved_85 Reserved.
16 10 CHAR(30) Qddfalsn Alternative name (ALIAS).

Default Value Description Information

(Qdb_Qddfdft): You can locate this section with the
offset Qddfdftd (page 34-101) in the field header section,
Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfdftl Length of default information.
2 2 CHAR(1) Qddfdfta Default attributes.
2 2 0 BIT(1) Qddfdfig DBCS or graphic default. If on, indicates the default is a DBCS or
graphic literal.
2 2 1 BIT(1) Qddfdfhx Hex default. If on, indicates the default is a hexadecimal literal.
2 2 2 BIT(1) Qddfndft Null default. If on, indicates the default is null.
2 2 3 BIT(2) Reserved_86 Reserved.
2 2 5 BIT(1) Qddfdcur DATE, TIME, or TIMESTAMP default. On indicates the default is
CURRENT_DATE, CURRENT_TIME, or CURRENT_TIMESTAMP.
2 2 6 BIT(1) Reserved_109 Reserved.
2 2 7 BIT(1) Qddfdftk DFT or DFTVAL keyword. If on, indicates the DFTVAL keyword was
specified.
3 3 CHAR(13) Reserved_87 Reserved.
16 10 CHAR(*) Qddfdftv Default (DFT) or (DFTVAL). A value of USER indicates that the default
value for this field is the job's current user.

Derived Field Description Information: The derived Numeric operands and character operands cannot be mixed
field structure is a stack of operators and operands in postfix in one derived field description. If numeric operands are
notation. Postfix notation is a method of forming math- specified, the resulting field attributes must be numeric. If
ematical expressions in which each operator is preceded by character operands are specified, the resulting field attributes
its operands and indicates the operation to be performed on must be character or DBCS. Character and DBCS only
the operands or the intermediate results that precede it. For fields cannot be mixed in one derived field description.
example:
Substringing DBCS fields is allowed, although the data is
A + B treated as character data, that is, there is no true double-byte
would be:
substring support. This applies to query formats only.
A B +

34-106 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Derived Field Header (Qdb_Qddfderv): You can

locate this section with the offset Qddfderd (page 34-101) in
the field header section, Qdb_Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qddfdvtl Length of derived field information Qddfderv (page 34-106).
4 4 BINARY(2) Qddfdvnume Number of derived field entries. 0 indicates it is a concatentated field.
6 6 BINARY(4) Qddfdvot Offset from the start of this header to the derived field text (or to the
concatenated field text), Qddfdvtx (page 34-112).
10 A CHAR(6) * Reserved.
16 10 CHAR(*) Qddfdven Derived field entry.

Derived Field Entry (Qdb_Qddfdvst)

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Qddfdvln Length of derived field entry, Qddfdvst.
4 4 BINARY(2) Qddfdtyp Derived field entry type.
0 A field operand.
1 A constant operand.
2 An operator.
6 6 CHAR(*) Qddfdv The union of the Field operand (Qdddvof), Constant operand
(Qddffvoc), and Operator entry (Qddfdvo).

Field Operand Entry (Qdb_Qddfdvof)

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(30) Qddfdvon Field name.
30 1E BINARY(2) Qddfdvjr Join reference (JREF). Relative file number of the physical file con-
taining the external file referenced.
0 The fields previously defined in this format are searched
for the field name.
If the field is not found, the based on file formats are
searched. If the field name is found in more than one file
format, an error is signalled.
n The file containing the field name.
32 20 BINARY(2) Qddfdv01 Starting position. The starting position in the field of the substring
(SST) specified.
34 22 BINARY(2) Qddfdvo2 Ending position. The ending position in the field of the substring (SST)
specified.
36 24 BINARY(2) Qddfqdtnum Qdt from which this correlated field originates (only applicable for SQL
subqueries.
38 26 CHAR(20) * Reserved.

Constant Operand Entry (Qdb_Qddfdvoc)

Offset
Dec Hex Bit Type Field Description
0 0 * Qddfdvoh Constant operand header.
0 0 BINARY(4) Qddfdvol Length of constant Qddfdvov (page 34-108).

Chapter 34. File APIs 34-107

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
4 4 CHAR(1) Qca Constant attributes.
4 4 0 BIT(1) Qddfdvci DBCS constant. If on, indicates the constant is a DBCS-open literal.
4 4 1 BIT(1) Reserved_90 Reserved.
4 4 2 BIT(1) Qddfdvcc Character constant type. If on, indicates the constant is an unquoted
character string not bracketed by single quotes. Imbedded quotes are
represented with a single quote. If off, indicates it is quoted, bracketed
by single quotes. Imbedded quotes are represented with two single
quotes.
4 4 3 BIT(1) Qddfdvac Assume character constant. If on, indicates the system assumes this is
a character constant.
4 4 4 BIT(1) Qddfdvco DBCS-only literal. If on, indicates the constant is a DBCS-only literal.
This attribute is not valid if the DBCS constant attribute, Qddfdvci, is off.
4 4 5 BIT(1) Qddfdvsr Special register. If on, indicates this constant is a special register
defined by Qddfdvrc.
4 4 6 BIT(1) Qddfdvnl Null indicator. If on, indicates the constant is a null literal.
4 4 7 BIT(1) Reserved_91 Reserved.
5 5 CHAR(1) Qddfdvrc Special register constant. Defined by special register constants, can
only be specified if Qddfdvsr is on.
6 6 CHAR(1) Qddfdvft Date constant format (DATFMT) or Time constant format (TIMFMT)
X'FE' Format associated with the job is used.
X'FF' Format associated with QDT is used.
X'01' The *USA format.
X'03' The *ISO format.
X'05' The *EUR format.
X'07' The *JIS format.
X'09' The SAA timestamp format.
X'17' The *MDY date format.
X'18' The *DMY date format.
X'19' The *YMD date format.
X'1A' The *JUL date format.
X'1B' The *HMS time format.
7 7 CHAR(1) Qddfdvsp Date constant separator (DATSEP) or Time constant separator
(TIMSEP)
X'00' Default separator associated with job is used.
X'EE' The implied separator is used.
'/' The slash.
'-' The dash.
'.' The period.
',' The comma.
'' The blank.
':' The colon.
8 8 CHAR(2) Reserved_92 Reserved.
10 A BINARY(2) Qddfdvcd Constant coded character set identifier (CCSID).
13 C CHAR(1) Qddfcflg Constant flags.
13 C 0 BIT(2) Reserved_93 Reserved.
13 C 2 BIT(1) Qddfglit Graphics literal. If on, indicates this is a graphics literal.
13 C 3 BIT(5) Reserved_94 Reserved.
14 E CHAR(29) Reserved_95 Reserved.
43 2B CHAR(*) Qddfdvov Derived constant. The external form of the constant.

Operator Entry (Qdb_Qddfdvo)

34-108 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(1) Qddfdvop Derived operator.
Operators requiring three operands:
X'27' Substring
Operators requiring two operands:
X'01' Concatenation
X'04' Addition
X'05' Subtraction
X'06' Multiplication
X'07' Division
X'08' Minimum
X'09' Maximum
X'1A' X to the Y power
X'1B' Binary OR
X'1C' Binary XOR
X'1D' Binary AND
X'24' Strip leading
X'25' Strip tailing
X'26' Strip both
X'35' Compute
X'41' String position
X'80' Remainder

Chapter 34. File APIs 34-109

Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
Operators requiring one operand:
X'02' Map
X'03' Direct map
X'0A' Absolute value
X'0B' Translate
X'0C' Natural logarithm
X'0D' Exponential
X'0E' Sine
X'0F' Cosine
X'10' Tangent
X'11' Cotangent
X'12' Arc sine
X'13' Arc cosine
X'14' Arc tangent
X'15' Hyperbolic sine
X'16' Hyperbolic cosine
X'17' Hyperbolic tangent
X'18' Hyperbolic arctangent
X'19' Square root
X'1E' Binary NOT
X'1F' Negation
X'23' Length
X'29' Year
X'2A' Month
X'2B' Day
X'2C' Days.
X'2D' Hour
X'2E' Minute
X'2F' Second
X'30' Microsecond
X'31' Date
X'32' Time
X'34' Hex
X'36' Test translate CCSID
X'37' Translate monocase
X'3C' Node number
X'3D' Cast
X'47' Partition
X'48' Node name
X'83' Log (base 10)
X'84' Anti log (base 10)
X'85' Digits
X'86' Char
X'8F' Graphic representation of character
X'90' Character representation of graphic
Label duration operators:
X'87' Year
X'88' Month
X'89' Day
X'8A' Hour
X'8B' Minute
X'8C' Second
X'8D' Microsecond
Operators requiring one to many operands:
X'3A' Hash function
Operators requiring two to many operands:
X'28' Null values
X'3E' Case Expression

34-110 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
Operators requiring one or two operands:
X'33' Timestamp
Group by operators: All require one operand except count that
requires one or two.
X'A1' Count
X'A3' Sum
X'A4' Minimum
X'A5' Maximum
X'B0' Average
X'B1' Standard deviation
X'B2' Variance
1 1 CHAR(2) Qddfdvxnum Translate table index or case selection specification index. This field is
valid only if Qddfdvop (page 34-108) is X'OB' or X'3E'.
1 1 CHAR(1) Qddfdvdtfmt Operator date format index.
1 1 CHAR(1) Qddfdvdtsep Operator date separator index.
3 3 CHAR(1) Qddfdvfm Operator date format (DATFMT) or Operator time format (TIMFMT).
X'FE' Format associated with the job is used.
X'FF' Format associated with QDT is used.
X'01' The *USA format.
X'03' The *ISO format.
X'05' The *EUR format.
X'07' The *JIS format.
X'09' The SAA timestamp format.
X'17' The *MDY date format.
X'18' The *DMY date format.
X'19' The *YMD date format.
X'1A' The *JUL date format.
X'1B' The *HMS time format.
4 4 CHAR(1) Qddfdvsa Operator date separator (DATSEP) or Operator time separator
(TIMSEP)
X'00' Default separator associated with job is used.
X'EE' The implied separator is used.
'/' The slash.
'-' The dash.
'.' The period.
',' The comma.
'' The blank.
':' The colon.
5 5 BINARY(2) Qddfdvno Number of operands.
7 7 CHAR(1) Qoa Operator attributes.
7 7 0 BIT(1) Reserved_96 Reserved.
7 7 1 BIT(1) Qddfdvdttm Operator date format and separator source. If on, indicates
Qddfdvdtfmt and Qddfdvdtsep are used as the date format and sepa-
rator with the CHAR operator. Qddfdvfm and Qddfdvsa are used as the
time format and separator with the CHAR operator.
7 7 2 BIT(1) Reserved_n Reserved.
7 7 3 BIT(1) Qddfdvdf Group operators. If on, do not include duplicate field values in group by
operation. If off, include duplicate field values in group by operation.
7 7 4 BIT(1) Reserved_97 Reserved.
7 7 5 BIT(1) Qddffunc_char Number of characters option. If on, the result of the operator is based
on the number of characters. If off, the result of the operator is based
on the number of bytes. This field is only applicable when Qddfdvop is
POSSTR(X'41'), LENGTH(X'23'), or SUBSTRING(X'27).
7 7 6 BIT(2) Reserved_115 Reserved.

Chapter 34. File APIs 34-111

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
8 8 CHAR(2) Reserved_98 Reserved.
10 A CHAR(1) Qddfd_decptchar The character to use for the decimal point. Only applicable if Qddfdvop
is a CAST(X'3D') and one of the operands is numeric and the other is
character, or if Qddfdvop is a CHAR(X'86') and the first operand is
packed decimal.
| 11 B BIN(4) Qddfdo_func_def Offset from the beginning of this derived field entry (Qdb_Qddfdvst) to
| the Function Name Specification section, Qddfunc_def (page 34-113).
| If this offset is specified, then the function is resolved to using the name
| in the Function Name Specification section. If the Function Name
| section is specified, all entries in this operator section are ignored
| except for the number of operands for the function, Qddfdvno, which is
| required to be set, and the duplicate field values indicator, Qddfdvdf,
| which can be optionally set. decimal.
| 15 F CHAR(11) Reserved_101 Reserved.

Derived Field Text Information (Qdb_Qddfdvtx):

You can locate this section with the offset Qddfdvot (page
34-107) in the Derived Field Header section, Qdb_Qddfderv.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfdvlt Length of derived field text information or concatenated field text infor-
mation.
2 2 CHAR(*) Qddfdtxt Derived field text description or concatenated field text description.

Column Heading Information (Qdb_Qddfcolh): You

can locate this section with the offset Qddfchd (page 34-101)
in the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(20) Qddfch1 Column heading #1. The first column heading specified on the
COLHDG DDS keyword without the quotes.
20 14 CHAR(20) Qddfch2 Column heading #2. The second column heading specified on the
COLHDG DDS keyword without the quotes.
40 28 CHAR(20) Qddfch3 Column heading #3. The third column heading specified on the
COLHDG DDS keyword without the quotes.

IDDU/SQL Dictionary Format Information

(Qdb_Qddfdic): You can locate this section with the
offset Qddfdico (page 34-96) in the field header section,
Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(32) Reserved_100 Reserved.
32 20 Qddfdicm Format definition long comment information.
32 20 BINARY(2) Qddfdilt Length of format definition long comment information, Qddfdicm.
34 22 CHAR(*) Qddfditx Format definition long comment.

34-112 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

IDDU/SQL Dictionary Field Information

(Qdb_Qddfdicf): You can locate this section with the
offset Qddfdicd located in the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(16) * Reserved.
16 10 Qddfdfco Field definition long comment.
16 10 BINARY(2) Qddffcl Length of field definition long comment Qddfdfco.
18 12 CHAR(*) Qddfdfct Field definition comment text.

Translate Table Specification (Qdb_Qddfxl): You

can locate this section with the offset Qddfxlto (page 34-96)
in the field header section, Qddffld.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfxlnum Number of elements in the translate table array.
2 2 Qddfxarr Translate table array.
2 2 CHAR(10) Qddfxtnm Translate table name.
12 C CHAR(10) Qddfxtln Translate table library name.
22 16 BINARY(2) Qddfxcid Translate table constant coded character set identifier.
24 18 CHAR(10) Reserved_99 Reserved.
34 22 CHAR(256) Qddfxtbl Translate table.

Case Selection Specification (Qdb_Qddfcsl): You

can locate this section with the offset Qddfrcao (page 34-96)
in the field header section, Qddffld. For a description of
selection specifications, see QDBQS in QQQQRY API.

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(2) Qddfcsnum Number of elements in the case selection specification array.
2 2 BINARY(4) Qddfcln Length of this plus the length of all the selection specifications.
6 6 CHAR(10) Reserved Reserved.
16 10 Array of Qddfcao Offset to the selection specification. Offset is from the start of
BINARY(4) Qdb_qdffcsl.

| Function Name Specification (Qdb_Qddfunc_def): | existing built-in functions provided by the database or to
| You can locate this section with the offset Qddfdo_func_def | user-defined functions defined in the SYSROUTINE SQL
| (page 34-112) in the derived operator entry section, Qddfdvo. | catalog in the QSYS2 library. Resolution is based on function
| name, number of parameters, compatible parameters and
| This section can only be specified when used in conjunction | library list, in that order.
| with the QQQQRY API.
| See the DB2 UDB for AS/400 SQL Reference book for more
| This section can be used to reference a function by name | information on user-defined functions and the SYSROUTINE
| rather than opcode qddfdvop. It can be used to resolve to | catalog.

| Offset
| Dec Hex Bit Type Field Description
| 0 0 CHAR(20) Reserved Reserved.

Chapter 34. File APIs 34-113

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
| 20 14 CHAR(10) Qddfunc_libname Library where function can be found. Special values follow.
| '' Blank. Use the path (library list) to find the function.
| 'QSYS2' Use the built-in operator provided by the database.
| 30 1E BIN(2) Qddfunc_namelen Length of function name in Qddfunc_funcname.
| 32 20 CHAR(128) Qddfunc_funcname Name of function to resolve.
| Built-in functions provided by the database in library QSYS2:
| '+' Addition. Two operands
| '-' Subtraction. Two operands
| '*' Multiplication. Two operands
| '/' Division. Two operands
| 'ABS' Absolute value. One operand
| 'ACOS' Arc cosine. One operand
| 'ANTILOG' Antilog. One operand
| 'ASIN' Arc sine. One operand
| 'ATAN' Arc tangent. One operand
| 'ATANH' Hyperbolic arc tangent. One operand
| 'AVG' Average. One operand
| 'CHAR' Character. One to two operands
| 'COALESCE' First non-null value. Two to N operands
| 'CONCAT' Concatenation. Two operands
| 'COS' Cosine. One operand
| 'COSH' Hyperbolic cosine. One operand
| 'COT' Co-tangent. One operand
| 'COUNT' Count. One operand
| 'CURDATE' Current date. Zero operand
| 'CURTIME' Current time. Zero operand
| 'DATE' Date. One operand
| 'DAY' Day. One operand
| 'DAYOFMONTH'
| Day of month. One operand
| 'DAYOFWEEK'
| Day of week. One operand
| 'DAYOFYEAR'
| Day of year. One operand
| 'DAYS' Days. One operand
| 'DECIMAL' Decimal of operand. One operand
| 'DEGREES' Degrees. One operand
| 'DIGITS' Character form of number. One operand
| 'DOUBLE' Double precision. One operand
| 'EXP' Natural log to the power. One operand
| Built-in functions (continued)
| 'FLOAT' Floating point. One operand
| 'FLOOR' Integer. One operand
| 'HASH' Hash value. One to N operands
| 'HEX' Hex value. One operand
| 'HOUR' Hour. One operand
| 'IFNULL' First non-null value. Two operands
| 'INT' Integer. One operand
| 'LAND' Logical AND. Two operands
| 'LCASE' Lower case. One operand
| 'LEFT' Left N characters. Two operands
| 'LENGTH' Length. One operand
| 'LN' Natural log. One operand
| 'LNOT' Logical NOT. One operand
| 'LOCATE' Search string in source string. Two to three operands
| 'LOG' Base 10 log. One operand
| 'LOR' Logical OR. Two operands
| 'LOWER' Lower case. One operand
| 'LTRIM' Remove leading blanks. One operand

34-114 AS/400 System API Reference V4R4

 Retrieve Database File Description (QDBRTVFD) API

Offset
Dec Hex Bit Type Field Description
| Built-in functions (continued)
| 'MAX' Max. One operand
| 'MAX' Max. Two to N operands
| 'MICROSECOND'
| Microsecond. One operand
| 'MIN' Min. One operand
| 'MIN' Min. Two to N operands
| 'MINUTE' Minute. One operand
| 'MOD' Modulo. Two operands
| 'MONTH' Month. One operand
| 'NOW' Current timestamp. Zero operands
| 'POSSTR' Search string in source string. Two operands
| 'POWER' Raise to power of. Two operands
| 'QUARTER' Quarter. One operand
| 'REAL' Single precision float. One operand
| 'RTRIM' Trim trailing blanks. One operand
| 'SECOND' Second. One operand
| 'SIN' Sine. One operand
| 'SINH' Hyperbolic sine. One operand
| 'SMALLINT' Small integer. One operand
| 'SQRT' Square root. One operand
| 'STDDEV' Standard deviation. One operand
| 'SUBSTR' Substr. Two to three operands
| 'SUM' Sum. One operand
| Built-in functions (continued)
| 'TAN' Tangent. One operand
| 'TANH' Hyperbolic tangent. One operand
| 'TIME' Time. One operand
| 'TIMESTAMP'
| Timestamp. One to two operands
| 'TRANSLATE'
| Translate. One to four operands
| 'UCASE' Uppercase. One operand
| 'UPPER' Uppercase. One operand
| 'VALUE' First non-null value. Two to N operands
| 'VARCHAR' Varchar. One to three operands
| 'VARGRAPHIC'
| Vargraph. One to three operands
| 'VARIANCE' Variance. One operand
| 'WEEK' Week. One operand
| 'XOR' Logical exclusive OR. Two operands
| 'YEAR' Year. One operand
| 'ZONED' Zoned. One to four operands

FILD0300 Format (Key Field Information): FILD0300 pro- source supplied on the AS/400. An offset to the key field
vides detailed information for key fields of each record format information array of each record format is provided in the
of the specified file. This structure is used by the QQQQRY record format information structure. If 0 is returned for this
API to get data from the named file. Figure 34-5 on offset, this record format has no key field. If -1 is returned
page 34-116 shows how this information is organized. for this offset, the size of the receiver provided is insufficient
When more than one entry can appear, the figure indicates to hold the returned data. You can see this source in source
this as in .7/. To get a description of all the fields contained file H, member name QDBRTVFD, in the QSYSINC library.
in this structure and to determine the offsets, see the include

Chapter 34. File APIs 34-115

Retrieve Database File Description (QDBRTVFD) API

┌─────────────────┐
│ Key Field │ Key Information Header (Qdb_Qdbwh): This section
│ Information │ is always located at the beginning of the returned data area.
│ Header │
│ (Qdb_Qdbwh) │
└────────┬────────┘
│
│
├──┐ .7/
┌──────┴──┴────────┐
┌─┴───────────────┐ │
│ Record Format │ │
│ Information │ │
│ Array │ │
│ (Qdb_Qdbwhrec) ├──┘
└────────┬────────┘
│
│
├──┐
┌──────┴──┴────────┐
┌─┴───────────────┐ │
│ Key Field │ │
│ Description │ │
│ Array │ │
│ (Qdb_Qdbwhkey) ├──┘
└─────────────────┘
Figure 34-5. FILD0300 Format

Offset
Dec Hex Bit Type Field Description
0 0 BINARY(4) Byte_Ret Bytes returned. The total length, in bytes, of the data returned.
4 4 BINARY(4) Byte_Avail Bytes available. The total length, in bytes, of the key information.
8 8 BINARY(2) Max_Key_Len Maximum key length. The maximum length, in bytes, of any of the
keys.
10 A BINARY(2) Key_Count File generic key field count.
12 C CHAR(10) Reserved Reserved.
22 16 BINARY(2) Fmt_Counts Number of formats for the file.

Record Format Key Information Array

(Qdb_Qdbwhrec): This section is located immediately
after the Qdb_Qdbwh (page 34-116) header. This is a linked
list. There is a format record for each format. The number
of formats is stored in Fmt_Counts (page 34-116) in the
Qdb_Qdbwh header.

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Rec_Name Record format name. The name of this particular record format for the
file.
10 A CHAR(2) Reserved Reserved.
12 C BINARY(2) Num_Of_Keys Number of record format key fields.
14 E CHAR(14) Reserved Reserved.
28 1C BINARY(4) Key_Info_Offset Offset to the key field description array for this record format.

Key Field Description Array (Qdb_Qdbwhkey):

You can locate this section with the offset Key_Info_Offset
(page 34-116) in the Qdb_Qdbwhrec (page 34-116) array
member. This is a linked list. There is a key field informa-
tion array member for each key in the record format. The
number of key fields is stored in Num_Of_Keys (page
34-116) in the Qdb_Qdbwhrec array member.

34-116 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Field Description
0 0 CHAR(10) Int_Field_Name Internal key field name. If this is a logical format, this name is the
name of the field in the logical format. If this is a physical format, this
name is the same as the external field name.
10 A CHAR(10) Ext_Field_Name External key field name. If this is a physical format, this is the name of
the field in the physical format. If this is a logical format, this name is
the name of the field in a physical format on which this format is based.
20 14 BINARY(2) Data_Type The data type of this key field.
22 16 BINARY(2) Field_Len The length of this key field.
24 18 BINARY(2) Num_Of_Digs The number of digits in this key field. For numeric fields, this is the
number of digits. For graphic data fields, this is the number of DBCS
characters the field can contain. This field is applicable only to numeric
and graphic fields.
26 1A BINARY(2) Dec_Pos The number of decimal positions for this key field.
28 1C 0 CHAR(1) Qdb_Qdbwhkattr_t Key field attributes flags.
28 1C 0 BIT(1) Descending Descending/ascending sequence indicator.
28 1C 1 BIT(2) Numeric Numeric key field sequencing indicator.
28 1C 3 BIT(1) Reserved Reserved.
28 1C 4 BIT(1) Alt_Collating Alternative collating sequence indicator.
28 1C 5 BIT(1) Force_Zone Force zone sequence indicator.
28 1C 6 BIT(1) Force_Digit Force digit sequence indicator.
28 1C 7 BIT(1) Statement_Format Key statement external or internal name indicator.
29 1D BINARY(2) Alt_Name_Len Length of the alternative name.
31 1F CHAR(30) Alt_Name Alternative name (Alias).
61 3D CHAR(1) Reserved Reserved.
62 3E 0 CHAR(1) Qdb_Qdbwhkatt1_t Additional key field attribute flags.
62 3E 0 BIT(1) Null_Value Allow null value (ALNULL) indicator.
62 3E 1 BIT(7) Reserved Reserved.
63 3F CHAR(1) Reserved Reserved.

| Usage Notes CPF3C24 E

Length of the receiver variable is not valid.
| In multithreaded jobs, this API is not threadsafe and fails for CPF3C25 E
| distributed data management (DDM) files of type *SNA. Value &1 for file override parameter is not valid.
CPF3C90 E
Literal value cannot be changed.
Error Messages CPF3021 E File &1 not allowed with SYSTEM(*RMT).
CPF24B4 E Severe error while addressing parameter list. CPF3025 E File &1 not allowed with SYSTEM(*LCL).
CPF3CF1 E CPF325F E Conversion of the text failed.
Error code parameter not valid. CPF327A E Value &1 for format type parameter is not valid.
CPF3C19 E CPF3270 E Keyed file operation not allowed for file &1.
Error occurred with receiver variable specified. CPF9872 E Program or service program &1 in library &2
CPF3C21 E ended. Reason code &3.
Format name &1 is not valid.
CPF3C22 E
Cannot get information about file &1. Retrieve Display File Description
CPF3C23 E
(QDFRTVFD) API
Object &1 is not a database file.

Chapter 34. File APIs 34-117

Retrieve Display File Description (QDFRTVFD) API

Qualified file name

Required Parameter Group: INPUT; CHAR(20)
The name of the file about which the information is to be
1 Receiver variable Output Char(*) extracted and the library in which it is located. The first
2 Length of receiver vari- Input Binary(4)
10 characters contain the file name. The second 10
able
3 Format name Input Char(8) characters contain the library name.
4 Qualified file name Input Char(20) The special values for the library name follow:
5 Error code Output Char(*)
*CURLIB The job’s current library
Threadsafe: No *LIBL The library list

Error code
The Retrieve Display File Description (QDFRTVFD) API I/O; CHAR(*)
allows you to get specific information about the data descrip-
The structure in which to return error information. For
tion specifications (DDS) definition used to create a display
the format of the structure, see “Error Code Parameter”
file.
on page 2-6.
If the returned data does not fill the receiver variable, the
contents of the remainder of the variable are not changed. Format DSPF0100
Format DSPF0100 provides detailed information about how
Authorities and Locks display files are built. The various structures that comprise
Library Authority the display file information format are organized in the fol-
*USE lowing manner:
File Authority *OBJOPR
Ÿ Base file formats (see page 34-119)
File Lock *EXCLRD
Ÿ File formats (see page 34-120)

Required Parameter Group Ÿ Record formats (see page 34-124)

Ÿ Field formats (see page 34-133)
Receiver variable
OUTPUT; CHAR(*) Ÿ Keyword formats (see page 34-138)
The receiver variable that receives the information Ÿ Where-used formats (see page 34-178)
requested. You can specify the size of the area smaller
than the format requested as long as you specify the The structures for each format follow Figure 34-6. The
length of receiver variable parameter correctly. As a structures include the variable names, field information, and
result, the API returns only the data the area can hold. offsets. Unlike many APIs, which use an offset from the
beginning of the variable, most QDFRTVFD offsets are rela-
Length of receiver variable tive to the start of a base structure. To determine how to
INPUT; BINARY(4) arrive at the data, see the introduction to each structure.
The length of the receiver variable. If the data available
The use of the term optioned in the tables refers to an indi-
is larger than the length of the receiver variable, the
cator that controls whether the DDS keyword is in effect or
result is truncated. The minimum length is 8 bytes. The
not. For more information about option indicators, see the
actual length of the structure is returned in variable
DDS Reference book.
WDFFSIZE in structure QDFFBASE (see the “Base File
Section (QDFFBASE)” on page 34-119). The asterisk (*) in the Variable Name column represents a
Format name reserved field. No variable is associated with these reserved
INPUT; CHAR(8) fields.

The content of the information to be returned about the Figure 34-6 on page 34-119 provides an overview of format
specified display file. You can use the following format DSPF0100 by showing how this information is organized.
name: The abbreviated names in the figure correspond to the struc-
ture names of the tables. The formats are shown by section
DSPF0100 Display file information
(for example, base file, file header, record header, and so
See “Format DSPF0100” for a description of these forth). The keyword formats do not appear in the figure.
formats.

34-118 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

┌───────────────────┐ │ │
│ Base File Section │ ┌─────────┴──────────┐ │
│ (QDFFBASE) │ │Field Header Section│ │
└───────┬───────────┘ │(QDFFFINF) │ │
┌────────────────┴───┐ └─────────┬──────────┘ │
┌────────┴──────────┐ │ ┌────────┬─────────────────┬─┴───────────────────┬─────────────┐ │
│Sort Sequence Table│ │ │ ┌──────┴───────┐ ┌───────┴───────────┐ ┌───────┴───────────┐ │ │
│(QDFFSSEQ) │ │ │ │Constant Field│ │Display-Field-Level│ │Input-Capable │ │ │
└───────────────────┘ │ │ │Header Table │ │Device-Dependent │ │Display-Field-Level│ │ │
│ │ │(QDFFFCON) │ │Section (QDFFFDPD) │ │Device-Dependent │ │ │
┌───────────┴───────┐ │ └──────────────┘ └───────┬───────────┘ │Section (QDFFFDIC) │ │ │
│File Header Section│ ┌┴───────────┐ ┌───────┴───────────┐ └───────────────────┘ │ │
│(QDFFINFO) │ │Named Field │ │Field-Dependent │ ┌───────────────┴─┐ │
└───────────┬───────┘ │Header Table│ │Extension Structure│ │Keyword Category │ │
┌───────────────────┬──────┴──────┬───────┬──────────────────┐ │(QDFFFNAM) │ │(QDFFXFDP) │ │Displacement │ │
│ │ │ │ │ └────────────┘ └───────────────────┘ │String (QDFFCOSA)│ │
┌───────┴──────────┐ ┌──────┴───────────┐ │ ┌─────┴─────────────┐ │ └─────────────────┘ │
│Display-File-Level│ │Sequence Number │ │ │Record Format Table│ │ │
│Device-Dependent │ │Table (QDFFSEQT) │ │ │(QDFARFTE) │ │ ┌───────────────────────────────────┘
│Section (QDFFDPDD)│ └──────────────────┘ │ └───────────────────┘ │ ┌──────────┴─────────┐
└───────┬──────────┘ │ │ │Where-Used File- │
┌──────┴──────────┐ │ │ │Level Information │
│Keyword Category │ │ │ │Structure (QDFWFLEI)│
│Displacement │ │ │ └──────────┬─────────┘
│String (QDFFCOSA)│ │ │ ┌────────────────┴───┬─────────────────┬─────────────┐
└─────────────────┘ │ │ ┌─────────┴──────────┐ │ ┌─────┴──────┐ │
│ │ │Where-Used Record │ │ │Name Table │ │
│ │ │Information │ │ │Structure │ │
┌───────┴───────┐ │ │Structure (QDFWRCDI)│ │ │(QDFFNTBL) │ │
│Record Header │ │ └─────────┬──────────┘ └────────┐ └────────────┘ │
│Section │ │ └───────┬───────────┬───────┐ │ │
│(QDFFRINF) │ │ ┌─────────┴──────────┐│┌──────┴─┴──────┐ │
└──────┬────────┘ │ │Where-Used Field │││Indicator Table│ │
│ │ │Information │││Entry Structure│ │
┌──────────────────────┬─────┴──────────────┬───────────┐│ │Structure (QDFWFLDI)│││(QDFWITBE) │ │
│ │ │ ││ └─────────┬──────────┘│└───────────────┘ │
┌───────┴────────────┐ ┌──────┴──────────┐ ┌──────┴────────┐ ││ └─────┐ │ ┌──────────────────────────┘
│Display-Record-Level│ │Subfile Control │ │Selection Table│ ││ ┌──┴─────┴─────┴─────┐
│Device-Dependent │ │Record (QDFFSFCR)│ │(QDFFSELT) │ ││ │Keyword Area │
│Section (QDFFRDPD) │ └────────────┬────┘ └───────────────┘ ││ │Structure (QDFWKWDA)│
└───────┬────────────┘ │ ││ └──────┬─────────────┘
├───────────────────────┐ └──────────────┐ ││ ┌──────┴─────────────┐
┌───────┴────────────┐ ┌───────┴────────┐ ┌──────┴────────┐ ││ │Keyword Entry │
│Display-Record-Level│ │Row-Column Table│ │Subfile Control│ ││ │Structure (QDFWATTR)├─────────┐
│Device-Dependent │ │(QDFFRCTB) │ │Record │ ││ └──────┬─────────────┘ │
│Section Extension │ └────────────────┘ │Extension │ ││ ┌──────┴─────────────┐ ┌───────┴───────┐
│Structure (QDFFXRDP)│ │(QDFFSFCREXT) │ ││ │Multiple Variable │ │Variable Length│
└────────┬───────────┘ └───────────────┘ ││ │Length Structure ├─┤Structure │
│ ││ │(QDFWBTYP) │ │(QDFWATYP) │
┌───┴───────────────┬───────────────────┐ ││ └────────────────────┘ └───────┬───────┘
┌───────┴─────────┐ ┌──────┴─────────┐ ┌──────┴──────────┐ ││ ┌───────┴────────────┐
│Keyword Category │ │Field Name Table│ │Field Order Table│ ││ │Reference │
│Displacement │ │(QDFFNTB) │ │(QDFFOT) │ ││ │Information │
│String (QDFFCOSA)│ └────────────────┘ └─────────────────┘ ││ │Structure (QDFWRSTR)│
└─────────────────┘ ││ └────────────────────┘
┌─────────────────────┬──────────────┘│
┌─────────┴──────────┐ ┌───────┴───────┐ │
│Field Indexing Table│ │Selection Table│ │ Figure 34-6 (Part 2 of 2). DSPF0100 Format
│(QDFFFITB) │ │(QDFFSELT) │ │
└─────────┬──────────┘ └───────────────┘ │
│ │
Figure 34-6 (Part 1 of 2). DSPF0100 Format
Base File Formats
Base File Section (QDFFBASE): Base file structure.
This is the first structure and is located at offset zero of the
returned data.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFRETN Length of the returned data.
4 4 BIN(31) WDFFSIZE Size of the display file description.
8 8 BIN(15) WDFFINOF Displacement to file header section (see structure QDFFINFO, page
34-121).
10 A BIN(15) WDFFRCS Number of record formats specified. This number includes internally
generated record formats.
12 C CHAR(1) WDFFDPAT Display attribute bits.
12 C 0 BIT(1) WDFFSEPI If on, INDARA keyword is specified.

Chapter 34. File APIs 34-119

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
12 C 1 BIT(1) WDFFDESF If on, ERRSFL keyword is specified.
Note: The ERRSFL keyword generates additional internal records
(*ERRSFL).
12 C 2 BIT(6) * Reserved.
13 D BIN(15) WDFFSCR Number of valid file screen sizes (see structure QDFFSCRA, page
34-120).
15 F BIN(15) WDFFSRSQ Displacement to sort sequence table (see structure QDFFSSEQ, page
34-120).
17 11 CHAR(2) WDFFACCSID CCSID of source member used to create the device file.
19 13 CHAR(*) WDFFSCRS Screen size table. This area defines the screen sizes valid for
externally defined files. This is specified by the DSPSIZ keyword.
When not specified, a default DSPSIZ(*DS3) is generated. Structure
QDFFSCRA (page 34-120) defines the entries. The elements are in the
sequence that the DSPSIZ keywords are specified.

Screen Size Table (QDFFSCRA): Screen ID array.

The number of entries in this structure is defined by variable
WDFFSCR in structure QDFFBASE. This structure is
defined at variable WDFFSCRS (page 34-120) in structure
QDFFBASE. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFFSCIA Screen ID. X'03' is defined as *DS3; X'04' is defined as *DS4.
1 1 CHAR(4) * Reserved.

Sort Sequence Table (QDFFSSEQ): Sort sequence

table information used for the ALTSEQ keyword. The dis-
placement to this structure from the beginning of structure
QDFFBASE is at variable WDFFSRSQ (page 34-120) in
QDFFBASE.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(256) WDFFSST Sort sequence table.
256 100 BIN(16) WDFFSSC CCSID associated with the table.
258 102 CHAR(10) WDFFSSN Table name.
268 10C CHAR(10) WDFFSSL Library name.
278 116 CHAR(2) WDFFSSFL Indicator flags.
278 116 0 BIT(1) WDFFSSUS Weighted indicator. 0 is defined as shared weighted; 1 is defined as
unique weighted.
278 116 1 BIT(1) WDFFSSSB Substitution characters indicator. 0 is defined as having no substitution
characters; 1 is defined as having substitution characters.
278 116 2 BIT(14) * Reserved.
280 118 CHAR(26) * Reserved.

File Formats
Figure 34-7 on page 34-121 shows the file section of the
overview figure (Figure 34-6 on page 34-119).

34-120 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

┌───────────────────┐
│File Header Section│ File Header Section (QDFFINFO): File header struc-
│(QDFFINFO) │ ture. The displacement to this structure from the beginning
└─────────┬─────────┘
│ of structure QDFFBASE is at variable WDFFINOF (see page
┌───────────────────┼─────────────────────┐ 34-119) in structure QDFFBASE.
│ │ │
┌───────┴──────────┐ ┌──────┴───────────┐ ┌─────┴─────────────┐
│Display-File-Level│ │Sequence Number │ │Record Format Table│
│Device-Dependent │ │Table (QDFFSEQT) │ │(QDFARFTE) │
│Section (QDFFDPDD)│ └──────────────────┘ └───────────────────┘
└───────┬──────────┘
┌──────┴──────────┐
│Keyword Category │
│Displacement │
│String (QDFFCOSA)│
└─────────────────┘

Figure 34-7. File Header Section

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFDFLO Length of the file header section. This includes the display-file-level
device-dependent section. This is also the displacement from structure
QDFFINFO to the record format table (see structure QDFARFTE, page
34-123).
4 4 BIN(31) WDFFWUOF Displacement to the where-used file-level information structure from
structure QDFFINFO (see structure QDFWFLEI, page 34-178).
8 8 BIN(31) WDFFFMWU Length of file header section and the where-used file-level information
structure.
12 C BIN(31) WDFFSEQO Displacement from structure QDFFINFO to the sequence number table
defined by structure QDFFSEQT (see page 34-123). 0, if not present.
16 10 BIN(15) WDFFSFL Maximum number of entries in the selection tables defined by structure
QDFFSTBL (see page 34-137) at the record and field levels.
18 12 BIN(15) WDFFSCE Maximum number of entries in the selection tables for this file (structure
QDFFSTBL, page 34-137) at the record levels.
20 14 CHAR(2) WDFFFFLG File level flag.
20 14 0 BIT(1) * Reserved.
20 14 1 BIT(1) WDFFGRPH If on, the file contains at least one field with a graphic (G) data type.
20 14 2 BIT(14) * Reserved.
22 16 CHAR(12) * Reserved.
34 22 BIN(15) WDFFXDOF Displacement to display-file-level device-dependent section from struc-
ture QDFFINFO (see structure QDFFDPDD, page 34-121).

Display-File-Level Device-Dependent Section

(QDFFDPDD): Display device dependent section. The
displacement to this structure from the beginning of structure
QDFFINFO is at variable WDFFXDOF (page 34-121) in
QDFFINFO.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(8) * Reserved.
8 8 CHAR(2) WDFFFKWD Miscellaneous keyword indicator.
8 8 0 BIT(1) WDFFOPEN If on, OPENPRT keyword specified in file.
8 8 1 BIT(1) WDFFCLRL If on, CLRL keyword specified in some record format in this file.
8 8 2 BIT(1) WDFFFICV If on, IGCCNV keyword specified in file.
Note: The IGCCNV keyword generates additional internal records
(*IGCFMT).

Chapter 34. File APIs 34-121

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
8 8 3 BIT(1) WDFFAGPH If on, ALWGPH keyword specified on at least one record format in file.
8 8 4 BIT(1) WDFFXHRD If on, file-level HLPRCD keyword is specified.
8 8 5 BIT(1) WDFFUDMT If on, USRDSPMGT keyword is specified.
8 8 6 BIT(1) WDFFPRPG If on, PRINT(*PGM) keyword is specified.
8 8 7 BIT(1) WDFFHSIO If on, file-level HLPSCHIDX keyword is specified.
9 9 0 BIT(1) WDFFXHTL If on, file-level HLPTITLE keyword is specified.
9 9 1 BIT(1) WDFFXUIM If on, file-level HLPPNLGRP keyword is specified.
9 9 2 BIT(1) WDFFXHDC If on, file-level HLPDOC keyword is specified.
9 9 3 BIT(1) * Reserved.
9 9 4 BIT(1) WDFFALTN If on, at least one ALTNAME keyword is specified in file.
9 9 5 BIT(1) WDFFHFUL If on, HLPFULL keyword is specified in file.
9 9 6 BIT(1) WDFFESFL If on, ERRSFL keyword is specified in file.
Note: The ERRSFL keyword generates additional internal records
(*ERRSFL).
9 9 7 BIT(1) WDFFWDW If on, WINDOW keyword is specified in file.
10 A CHAR(2) * Reserved.
12 C CHAR(1) WDFFSHB1 Start-of-header (SOH) bits.
12 C 0 BIT(1) WDFFSHCS If on, CHECK(RLTB) keyword is specified.
12 C 1 BIT(1) * Reserved.
12 C 2 BIT(1) WDFFAUTO If on, DSPRL keyword is specified.
12 C 3 BIT(5) * Reserved.
13 D CHAR(2) * Reserved.
15 F CHAR(1) WDFFSHRA Row address of the message line for primary display size.
16 10 CHAR(1) WDFFCKY1 File-level CA keys 17 through 24.
16 10 0 BIT(1) WDFFCK24 If on, CA key 24 is specified.
16 10 1 BIT(1) WDFFCK23 If on, CA key 23 is specified.
16 10 2 BIT(1) WDFFCK22 If on, CA key 22 is specified.
16 10 3 BIT(1) WDFFCK21 If on, CA key 21 is specified.
16 10 4 BIT(1) WDFFCK20 If on, CA key 20 is specified.
16 10 5 BIT(1) WDFFCK19 If on, CA key 19 is specified.
16 10 6 BIT(1) WDFFCK18 If on, CA key 18 is specified.
16 10 7 BIT(1) WDFFCK17 If on, CA key 17 is specified.
17 11 CHAR(1) WDFFCKY2 File-level CA keys 9 through 16.
17 11 0 BIT(1) WDFFCK16 If on, CA key 16 is specified.
17 11 1 BIT(1) WDFFCK15 If on, CA key 15 is specified.
17 11 2 BIT(1) WDFFCK14 If on, CA key 14 is specified.
17 11 3 BIT(1) WDFFCK13 If on, CA key 13 is specified.
17 11 4 BIT(1) WDFFCK12 If on, CA key 12 is specified.
17 11 5 BIT(1) WDFFCK11 If on, CA key 11 is specified.
17 11 6 BIT(1) WDFFCK10 If on, CA key 10 is specified.
17 11 7 BIT(1) WDFFCK9 If on, CA key 9 is specified.
18 12 CHAR(1) WDFFCKY3 File-level CA keys 1 through 8.
18 12 0 BIT(1) WDFFCK8 If on, CA key 8 is specified.
18 12 1 BIT(1) WDFFCK7 If on, CA key 7 is specified.

34-122 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
18 12 2 BIT(1) WDFFCK6 If on, CA key 6 is specified.
18 12 3 BIT(1) WDFFCK5 If on, CA key 5 is specified.
18 12 4 BIT(1) WDFFCK4 If on, CA key 4 is specified.
18 12 5 BIT(1) WDFFCK3 If on, CA key 3 is specified.
18 12 6 BIT(1) WDFFCK2 If on, CA key 2 is specified.
18 12 7 BIT(1) WDFFCK1 If on, CA key 1 is specified.
19 13 CHAR(1) WDFFMKWD Miscellaneous keyword indicators.
19 13 0 BIT(1) WDFFBRDR If on, file-level WDWBORDER keyword is specified.
19 13 1 BIT(1) * Reserved.
19 13 2 BIT(1) WDFFRTCR If on, RTNCSRLOC keyword is specified.
19 13 3 BIT(1) WDFFFFCP If on, FLDCSRPRG keyword is specified.
19 13 4 BIT(1) WDFFDSPP If on, DSPATR program-to-system field is specified in file.
19 13 5 BIT(1) WDFFHBKS If on, HLPSHELF keyword is specified in file.
19 13 6 BIT(1) WDFFINLYF If on, CSRINPONLY keyword is specified in file.
19 13 7 BIT(1) WDFFDBCSCNFLD If on, CNTFLD keyword is used on a DBCS field in the file.
20 14 CHAR(1) WDFFMKW2 More miscellaneous keywords.
20 14 0 BIT(1) WDFFHTML If on, the HTML keyword was specified in the file.
20 14 1 BIT(7) * Reserved.
21 15 CHAR(3) * Reserved.
24 18 BIN(15) WDFFXDOC Displacement to keyword category displacement string from structure
QDFFINFO (see structure QDFFCOSA, page 34-138). 0, if no file
keyword categories.

Record Format Table (QDFARFTE): Record format

table array. The number of entries in this structure is defined
by variable WDFFRCS in structure QDFFBASE. The dis-
placement to this structure from the beginning of structure
QDFFINFO is at variable WDFFDFLO (page 34-121) in
QDFFINFO. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFARFNM Record format name. Names that begin with * are internally generated
record formats.
10 A BIN(15) WDFARCND Miscellaneous record contents.
10 A 0 BIT(1) WDFFRECD If on, RECID keyword specified on this format.
10 A 1 BIT(15) * Reserved.
12 C BIN(31) WDFARFOF Displacement to the record header section (see structure QDFFRINF,
page 34-124) from structure QDFFINFO.

Sequence Number Table (QDFFSEQT): Sequence

number table. The number of entries in this structure is
defined by variable WDFFRCS in structure QDFFBASE. The
displacement to this structure from the beginning of structure
QDFFINFO is at variable WDFFSEQO (page 34-121) in
QDFFINFO. The structure is ARRAY(*).

Chapter 34. File APIs 34-123

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(13) WDFFSEQ Level-check number for format. There is a one-to-one correspondence
between this array and the entries in the record format table.
13 D CHAR(3) * Reserved.

Record Formats Record Header Section (QDFFRINF): Record header

section. The displacement to this structure from the begin-
Figure 34-8 shows the record section of the overview figure ning of structure QDFFINFO is at variable WDFARFOF
(Figure 34-6 on page 34-119). (page 34-123) in structure QDFARFTE.
┌───────────────┐
│Record Header │
│Section │
│(QDFFRINF) │
└──────┬────────┘
│
┌──────────────────────┬─────┴──────────────┬───────────┐
│ │ │ │
┌───────┴────────────┐ ┌──────┴──────────┐ ┌──────┴────────┐ │
│Display-Record-Level│ │Subfile Control │ │Selection Table│ │
│Device-Dependent │ │Record (QDFFSFCR)│ │(QDFFSELT) │ │
│Section (QDFFRDPD) │ └────────────┬────┘ └───────────────┘ │
└───────┬────────────┘ │ │
├───────────────────────┐ └──────────────┐ │
┌───────┴────────────┐ ┌───────┴────────┐ ┌──────┴────────┐ │
│Display-Record-Level│ │Row-Column Table│ │Subfile Control│ │
│Device-Dependent │ │(QDFFRCTB) │ │Record │ │
│Section Extension │ └────────────────┘ │Extension │ │
│Structure (QDFFXRDP)│ │(QDFFSFCREXT) │ │
└────────┬───────────┘ └───────────────┘ │
│ │
┌───┴───────────────┬───────────────────┐ │
┌───────┴─────────┐ ┌──────┴─────────┐ ┌──────┴──────────┐ │
│Keyword Category │ │Field Name Table│ │Field Order Table│ │
│Displacement │ │(QDFFNTB) │ │(QDFFOT) │ │
│String (QDFFCOSA)│ └────────────────┘ └─────────────────┘ │
└─────────────────┘ │
┌─────────────────────┬──────────────┘
┌─────────┴──────────┐ ┌───────┴───────┐
│Field Indexing Table│ │Selection Table│
│(QDFFFITB) │ │(QDFFSELT) │
└────────────────────┘ └───────────────┘

Figure 34-8. Record Header Section

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFRDDO Length of the record header section. This length includes the device-
dependent sections (that is, it is the displacement to structure
QDFFFINF for the first field in that record format).
4 4 BIN(31) WDFFOFIT The displacement from structure QDFFRINF to the field indexing table
defined by structure QDFFFITB (see page 34-132).
8 8 BIN(31) WDFFSTBO The displacement from structure QDFFRINF to the selection table
defined by structure QDFFSELT (see page 34-137). 0, if no selection
table present.
12 C BIN(31) WDFFRFLG Miscellaneous record contents.
12 C 0 BIT(1) WDFFUDDS If on, USRDFN keyword is specified.
12 C 1 BIT(1) WDFFSFL If on, SFL keyword is specified (next record is SFLCTL).
12 C 2 BIT(1) WDFFSFLC If on, SFLCTL keyword is specified (previous record is SFL).
12 C 3 BIT(1) WDFFMSGR If on, SFLMSGRCD keyword is specified.
12 C 4 BIT(1) WDFFRICV If on, IGCCNV record is specified.
Note: The IGCCNV keyword generates additional internal records.
12 C 5 BIT(3) * Reserved.
13 D 0 BIT(1) WDFFALLH If on, all fields in format are hidden.
13 D 1 BIT(1) * Reserved.

34-124 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
13 D 2 BIT(1) WDFFREXC If on, DBCS data that can be processed is specified in record. This
occurs when the O, J, or E data type is specified; when DBCS literals
are specified on a DFT, DFTVAL, SFLMSG, RECID, ERRMSG, or
RTGCON keyword.
13 D 3 BIT(1) WDFFRIDV If on, format requires a DBCS device.
13 D 4 BIT(1) WDFFREXT If on, extractable DBCS data is in format.
13 D 5 BIT(1) WDFFRALT If on, at least one field in format was specified as IGCALTTYP.
13 D 6 BIT(1) WDFFMEMF If on, CHECK(ME) or CHECK(MF) specified in at least one field in
record.
13 D 7 BIT(1) WDFFNDLC If on, ALWENDLOC keyword is specified in record.
14 E 0 BIT(1) WDFFRGPH If on, graphic fields are specified in record.
14 E 1 BIT(1) WDFFRCL If on, RTNCSRLOC keyword is specified in record.
14 E 2 BIT(1) WDFFMBAR If on, MNUBAR keyword is specified in record.
14 E 3 BIT(1) WDFFPULL If on, PULLDOWN keyword is specified in record.
14 E 4 BIT(1) WDFFPLSI Selection indicators on PULLDOWN keyword. 0 is defined as
*NOSLTIND; 1 is defined as *SLTIND (default).
14 E 5 BIT(1) WDFFFCPF If on, FLDCSRPRG specified on field in record.
14 E 6 BIT(1) WDFFCNTMCFFLD If on, CNTFLD, MLTCHCFLD, or SNGCHCFLD keyword is specified on
a field within this record.
14 E 7 BIT(1) WDFFEDTMSK If on, EDTMSK keyword is specified in record.
15 F 0 BIT(1) WDFFGRIDREC If on, GRDRCD keyword is specified in record.
15 F 1 BIT(7) * Reserved.
16 10 BIN(15) WDFFFLD Number of fields in this record.
18 12 CHAR(4) * Reserved.
22 16 BIN(15) WDFFINDO If INDARA keyword is specified and response indicators are in this
record, this is the displacement from structure QDFFRINF to the
response indicator keyword array (see structure QDFKMSCP, page
34-145) in category 4. 0 means the INDARA keyword is not specified
or if INDARA is specified, there are no response indicators.
24 18 CHAR(4) * Reserved.
28 1C BIN(15) WDFFRAOF Displacements to display-record-level device-dependent section and
subfile control record from structure QDFFRINF (see structures
QDFFRDPD, page 34-125, and QDFFSFCR, page 34-129).

Display-Record-Level Device-Dependent Section

(QDFFRDPD): Display device-dependent section for
nonsubfile records. Structure QDFFSFCR (page 34-129) is
used when subfiles are specified. The displacement to this
structure from the beginning of structure QDFFRINF is an
entry in the table at variable WDFFRAOF (page 34-125) in
QDFFRINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFDRCO Displacement to first row-column table (QDFFRCTB) from structure
QDFFRINF. One row-column table exists for each display size (see
variable WDFFSCR, page 34-120, in structure QDFFBASE). The fol-
lowing may be used to access the correct table: let n = index into
screen size array QDFFSCRA. (WDFFDRCO + (n - 1) * (WDFFFLD *
LENGTH(WDFFRC)) + LENGTH(WDFFFRTO) ) from QDFFRINF.
4 4 BIN(15) WDFFINCP Number of input-capable fields (that is, total input, both, and hidden).

Chapter 34. File APIs 34-125

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
6 6 BIN(15) WDFFIBF Number of input and both fields.
8 8 BIN(15) WDFFOIS Number of option indicators.
10 A CHAR(2) * Reserved.
12 C CHAR(4) WDFACKYS Indicates if a CA or CF key is specified. To determine which key (CA or
CF) is specified, check the corresponding WDFFCKnn bit in structure
QDFFDPDD (see page 34-121).
12 C CHAR(1) WDFACKY1 Keys 1 through 8 without option indicators.
12 C 0 BIT(1) WDFACK1 If on, CA/CF key 1 is specified.
12 C 1 BIT(1) WDFACK2 If on, CA/CF key 2 is specified.
12 C 2 BIT(1) WDFACK3 If on, CA/CF key 3 is specified.
12 C 3 BIT(1) WDFACK4 If on, CA/CF key 4 is specified.
12 C 4 BIT(1) WDFACK5 If on, CA/CF key 5 is specified.
12 C 5 BIT(1) WDFACK6 If on, CA/CF key 6 is specified.
12 C 6 BIT(1) WDFACK7 If on, CA/CF key 7 is specified.
12 C 7 BIT(1) WDFACK8 If on, CA/CF key 8 is specified.
13 D CHAR(1) WDFACKY2 Keys 9 through 16 without option indicators.
13 D 0 BIT(1) WDFACK9 If on, CA/CF key 9 is specified.
13 D 1 BIT(1) WDFACK10 if on, CA/CF key 10 is specified.
13 D 2 BIT(1) WDFACK11 If on, CA/CF key 11 is specified.
13 D 3 BIT(1) WDFACK12 If on, CA/CF key 12 is specified.
13 D 4 BIT(1) WDFACK13 If on, CA/CF key 13 is specified.
13 D 5 BIT(1) WDFACK14 If on, CA/CF key 14 is specified.
13 D 6 BIT(1) WDFACK15 If on, CA/CF key 15 is specified.
13 D 7 BIT(1) WDFACK16 If on, CA/CF key 16 is specified.
14 E CHAR(1) WDFACKY3 Keys 17 through 24 without option indicators.
14 E 0 BIT(1) WDFACK17 If on, CA/CF key 17 is specified.
14 E 1 BIT(1) WDFACK18 If on, CA/CF key 18 is specified.
14 E 2 BIT(1) WDFACK19 If on, CA/CF key 19 is specified.
14 E 3 BIT(1) WDFACK20 If on, CA/CF key 20 is specified.
14 E 4 BIT(1) WDFACK21 If on, CA/CF key 21 is specified.
14 E 5 BIT(1) WDFACK22 If on, CA/CF key 22 is specified.
14 E 6 BIT(1) WDFACK23 If on, CA/CF key 23 is specified.
14 E 7 BIT(1) WDFACK24 If on, CA/CF key 24 is specified.
15 F CHAR(1) WDFFCMDK Other command keys without option indicators.
15 F 0 BIT(1) WDFFRLUP If on, ROLLUP keyword is specified.
15 F 1 BIT(1) WDFFRLDN If on, ROLLDOWN keyword is specified.
15 F 2 BIT(1) WDFFPRNT If on, PRINT keyword is specified.
15 F 3 BIT(1) WDFFHOME If on, HOME keyword is specified.
15 F 4 BIT(1) WDFFCLR If on, CLEAR keyword is specified.
15 F 5 BIT(1) WDFFHELP If on, HELP keyword is specified.
15 F 6 BIT(2) * Reserved.
16 10 CHAR(2) WDFFPUTK Miscellaneous PUT conditions.
16 10 0 BIT(1) WDFFFSEL If on, field selection.
16 10 1 BIT(1) WDFFPUTR If on, PUTRETAIN keyword is specified on some fields for this format.

34-126 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
16 10 2 BIT(1) WDFFVSLN If on, SLNO(*VAR) keyword is specified.
16 10 3 BIT(1) WDFFALRL If on, ALWROL keyword is specified.
16 10 4 BIT(1) WDFFNOCO Currently set for records containing floating point fields or DBCS data
that requires a DBCS device (refer to WDFFRIDV).
16 10 5 BIT(1) WDFFALGP If on, unconditioned ALWGPH keyword is specified.
16 10 6 BIT(1) WDFFRDMD If on, DSPMOD keyword is specified.
16 10 7 BIT(1) WDFFRMID If on, MSGID keyword is specified on field in record.
17 11 0 BIT(1) WDFFRKEY If on, RETKEY keyword is specified.
17 11 1 BIT(1) WDFFRCKY If on, RETCMDKEY keyword is specified.
17 11 2 BIT(1) WDFFRDVL If on, DFTVAL keyword is specified on field.
17 11 3 BIT(1) WDFFVSL1 If on, SLNO(*VAR) keyword is specified and a field in row 1, column 1
is specified for at least one display size.
17 11 4 BIT(1) WDFFMSGA If on, unconditioned MSGALARM keyword is specified.
17 11 5 BIT(1) WDFFRLST If on, unconditioned RETLCKSTS keyword is specified.
17 11 6 BIT(1) WDFFURDS If on, unconditioned USRRSTDSP keyword is specified.
17 11 7 BIT(1) WDFFRMVW If on, unconditioned RMVWDW keyword is specified
18 12 CHAR(2) WDFFGETK Miscellaneous get conditions.
18 12 0 BIT(1) * Reserved.
18 12 1 BIT(1) WDFFLOGN If on, LOGINP keyword is specified.
18 12 2 BIT(1) WDFFINZR If on, INZRCD keyword is specified.
18 12 3 BIT(1) WDFFRTND If on, RTNDTA keyword is specified.
18 12 4 BIT(1) WDFFUNLK If on, UNLOCK keyword is specified.
18 12 5 BIT(1) WDFFRSET If on, UNLOCK(*MDTOFF) keyword specified or UNLOCK keyword
specified with GETRETAIN.
18 12 6 BIT(1) WDFFEARS If on, UNLOCK(*ERASE) keyword specified or UNLOCK keyword speci-
fied without GETRETAIN.
18 12 7 BIT(1) WDFFASUM If on, ASSUME keyword is specified.
19 13 0 BIT(1) WDFFKEEP If on, KEEP keyword is specified.
19 13 1 BIT(1) * Reserved.
19 13 2 BIT(1) WDFFWDWR If on, WINDOW keyword specified in record.
19 13 3 BIT(1) WDFFQILE If on, SFLPGMQ(276) keyword is specified.
19 13 4 BIT(1) WDFFSFLCHCCTL If on, SFLCHCCTL keyword is specified.
19 13 5 BIT(3) * Reserved.
20 14 BIN(15) WDFFERRM Index to first field in index table with either ERRMSG or ERRMSGID
keyword. 0, if record has no field with either keyword. See structure
QDFFFITB, page 34-132.
22 16 CHAR(1) WDFFBITS Miscellaneous flags.
22 16 0 BIT(1) WDFFERIN If on, unconditioned ERASEINP(*MDTON) keyword is specified and
ERASEINP(*ALL) is not specified.
22 16 1 BIT(1) WDFFMDTO If on, unconditioned MDTOFF(*UNPR) is specified and MDTOFF(*ALL)
is not specified.
22 16 2 BIT(6) * Reserved.
23 17 CHAR(1) WDFFBITF Miscellaneous flags.
23 17 0 BIT(2) * Reserved.

Chapter 34. File APIs 34-127

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
23 17 2 BIT(2) WDFFBLKC Blink flags. X'00' is defined as reserved; X'01' is defined as blink
cursor and keyword BLINK unconditioned; X'10' is defined as reset
blink cursor and no keyword BLINK; X'11' is defined as reserved.
23 17 4 BIT(1) WDFFNOLK If on, no unconditioned lock. 0 is defined as lock unconditioned (do not
unlock keyboard); 1 is defined as no LOCK keyword or conditioned lock
(unlock keyboard).
23 17 5 BIT(1) WDFFALRM If on, ALARM keyword unconditioned.
23 17 6 BIT(2) * Reserved.
24 18 BIN(15) WDFFCGRI Response indicator for record-level CHANGE keyword. For files with
INDARA keyword, this is the response indicator minus 1. For those
without INDARA keyword, this is the response indicator input buffer dis-
placement. -1 shows keyword is not present.
26 1A CHAR(2) WDFFHFLG Help flags.
26 1A 0 BIT(1) WDFFHSEQ If on, HLPSEQ keyword on record.
26 1A 1 BIT(1) WDFFHLP If on, help specifications on record.
26 1A 2 BIT(1) WDFFNHLP If on, record cannot be used as help text. It contains one of the
keywords USRDFN, SFL, or SFLCTL.
26 1A 3 BIT(1) WDFFHRTN If on, HLPRTN keyword on record.
26 1A 4 BIT(1) WDFFHTLE If on, HLPTITLE keyword on record.
26 1A 5 BIT(1) WDFFHCLR If on, HLPCLR keyword on record.
26 1A 6 BIT(1) WDFFCHNG If on, no parameter for CHANGE keyword.
26 1A 7 BIT(1) WDFFRPGM If on, PRINT keyword on record level with *PGM.
27 1B 0 BIT(1) WDFFHLPC If on, HLPCMDKEY keyword on record.
27 1B 1 BIT(1) WDFFRSTCSR If on, *RSTCSR parameter is specified on the PULLDOWN keyword on
the record.
27 1B 2 BIT(1) WDFFINLY If on, CSRINPONLY keyword is specified and is unoptioned.
27 1B 3 BIT(1) WDFFNOSEP If on, *NOSEPARATOR parameter is specified on the MNUBAR
keyword on this record.
27 1B 4 BIT(4) * Reserved.
28 1C BIN(15) WDFFXRDO Displacement to display-record-level device-dependent extension struc-
ture from structure QDFFRINF (see structure QDFFXRDP, page
34-128).
30 1E CHAR(2) * Reserved.
32 20 BIN(15) WDFFRDOC Displacement to keyword category displacement string from structure
QDFFRINF. (See structure QDFFCOSA, page 34-138.) 0, if no
keyword categories.

Display-Record-Level Device-Dependent Section

Extension Structure (QDFFXRDP): Extension struc-
ture. The displacement to this structure from the beginning
of structure QDFFRINF is at variable WDFFXRDO (page
34-128) in structure QDFFRDPD.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFOTO Displacement to field order table from structure QDFFRINF (see struc-
ture QDFFOT, page 34-132).

34-128 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
4 4 BIN(31) WDFFNRCO Displacement to first field name in row-column order table (see variable
WDFFDRCO in structure QDFFRDPD, page 34-125). For every row-
column table, there is a corresponding field name in row-column order
in the field name table (see structure QDFFNTB, page 34-132).
8 8 CHAR(4) * Reserved.
12 C BIN(15) WDFFNUMOFSEGS Number of segments in record for CNTFLD and EDTMSK.
14 E CHAR(2) * Reserved.
16 10 BIN(15) WDFFSFLCHCTLO Buffer displacement to the field containing control for selection list.
18 12 CHAR(6) * Reserved.

Subfile Control Record (QDFFSFCR): Display device-

dependent section for records specifying subfiles. This struc-
ture replaces structure QDFFRDPD when subfiles are
specified (variable WDFFSFLC in structure QDFFRINF is set
on, page 34-124). The displacement to this structure from
the beginning of structure QDFFRINF is an entry in the table
at variable WDFFRAOF (page 34-125) in QDFFRINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(34) WDFFSFLG Display-record-level device-dependent section (structure QDFFRDPD,
page 34-125) is mapped here.
34 22 CHAR(1) WDFFSFEN Command key associated with SFLENTER keyword. X'00' indicates
the keyword is not present.
35 23 CHAR(1) WDFFSFDR Command key associated with SFLDROP or SFLFOLD keyword.
X'00' indicates neither keyword is specified (see WDFFSFFD in this
table).
36 24 CHAR(1) WDFFSFLFLG Subfile flags.
36 24 0 BIT(1) WDFFSFLSNGCHC If on, SFLSNGCHC keyword is specified.
36 24 1 BIT(1) WDFFSFLMLTCHC If on, SFLMLTCHC keyword is specified.
36 24 2 BIT(1) WDFFSFLSELRSC If on, *RSTCSR parameter is specified on SFLMLTCHC or
SFLSNGCHC keyword.
36 24 3 BIT(1) WDFFSFLSELSND If on, *SLTIND parameter is specified on SFLMLTCHC or SFLSNGCHC
keyword.
36 24 4 BIT(1) WDFFSFLSELAST If on, *AUTOSLT parameter is specified on SFLSNGCHC keyword.
36 24 5 BIT(1) WDFFSFLSCRBAR If on, SFLEND(*SCRBAR) keyword is specified.
36 24 6 BIT(1) WDFFSFLRTNSEL If on, SFLRTNSEL keyword is specified.
36 24 7 BIT(1) WDFFSFLSCROLL If on, SFLSCROLL keyword is specified.
37 25 CHAR(1) WDFFSFST Miscellaneous flags.
37 25 0 BIT(1) WDFFSFNA If on, SFLRNA keyword is specified.
37 25 1 BIT(1) WDFFSFCU If on, SFLRCDNBR(CURSOR) keyword is specified.
37 25 2 BIT(1) WDFFSFDM If on, DSPMOD keyword is specified.
37 25 3 BIT(1) WDFFSFFD 0 indicates the initial display is fold; 1 indicates the initial display is
drop. If WDFFSFDR equals X'00', there is no SFLDROP or SFLFOLD
keyword, and this value equals 0. If WDFFSFDR does not equal
X'00', either this value equals 0 (SFLFOLD) or 1 (SFLDROP).
Note: Also refer to comments for variable WDFFSFDR in this struc-
ture.

Chapter 34. File APIs 34-129

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
37 25 4 BIT(1) WDFFSFFDI 0 indicates that SFLDROP or SFLFOLD are not optioned; use
WDFFSFFD to determine which one to use. 1 indicates that SFLDROP
and SFLFOLD are optioned; use indicators.
Note: Also refer to comments for variable WDFFSFDR in this struc-
ture.
37 25 5 BIT(1) WDFFSFEM If on, SFLEND(*MORE) keyword is specified.
37 25 6 BIT(1) WDFFSFLRCDTOP If on, SFLRCDNBR(*TOP) keyword is specified.
37 25 7 BIT(1) WDFFSFLSELSTE If on, *AUTOSLTENH parameter is specified on SFLSNGCHC keyword.
38 26 BIN(15) WDFFSFPQ Contains the value specified for the SFLPGMQ keyword.
40 28 BIN(15) WDFFSFVL SFLROLVAL field length. 0 indicates that the keyword is not specified.
42 2A BIN(15) WDFFSFVO Displacement in input buffer to SFLROLVAL.
44 2C BIN(15) WDFFSFFI Index into field indexing table of field with SFLROLVAL.
46 2E BIN(15) WDFFSFL SFLRCDNBR field length. 0 indicates that the keyword is not specified.
48 30 BIN(15) WDFFSFO Displacement in output buffer to SFLRCDNBR.
50 32 BIN(15) WDFFSFLEXTOFF Displacement to the QDFFSFCREXT extension structure (see page
34-131) from this structure.
52 34 CHAR(1) WDFFSFLNOFL Miscellaneous bits.
52 34 CHAR(1) WDFFSFNOFL Miscellaneous flags.
52 34 0 BIT(1) WDFFSFLSELNRS If on, *NORSTCSR parameter is specified on SFLMLTCHC or
SFLSNGCHC keyword.
52 34 1 BIT(1) WDFFSFLSELNST If on, *NOAUTOSLT parameter is specified on SFLSNGCHC keyword.
52 34 2 BIT(6) * Reserved
53 35 CHAR(1) * Reserved.
54 36 CHAR(*) WDFFSFPM SFL parameter values (see structure QDFFSFHR, page 34-130). One
entry is present for each specified display size (see WDFFSCRS, page
34-120, in structure QDFFBASE). The order of this array is the same
as structure QDFFSCRA (page 34-120).

Subfile Control Entry (QDFFSFHR): Subfile control

entry in the subfile control record. This structure is defined
at variable WDFFSFPM (page 34-130) in structure
QDFFSFCR. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFSFSZ SFLSIZ.
2 2 BIN(15) WDFFSFPG SFLPAG. If this is a field selection subfile, this is the number of lines
occupied by subfile. If this is a nonfield selection subfile, this is the
maximum number of subfile records on the screen.
4 4 CHAR(2) * Reserved.
6 6 BIN(15) WDFFSFT Number of fields not dropped, that is, the number of fields on first line of
SFL record with SFLDROP specified.
8 8 BIN(15) WDFFSFR1 Subfile start row.
8 8 CHAR(1) * Reserved.
9 9 CHAR(1) WDFFSFSR Subfile start row. For SFLMSGRCD, this is line number.
10 A BIN(15) WDFFSFR2 Subfile end row.
10 A CHAR(1) * Reserved.
11 B CHAR(1) WDFFSFER Subfile end row.

34-130 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
12 C CHAR(4) WDFFSFLN Horizontal subfile (SFLLIN). 0 is defined as not horizontal subfile.
12 C BIN(15) WDFFSFH1 Number of horizontal records per line.
14 E BIN(15) WDFFSFH2 Number of characters from field 1, record n to field 1, record n+1.
16 10 BIN(15) WDFFSFF Number of fields per record.
18 12 CHAR(6) * Reserved.

Subfile Control Record Extension

(QDFFSFCREXT): Subfile control record extension entry
in the subfile control record (see structure QDFFSFCR, page
34-129). Variable WDFFSFLEXTOFF (page 34-130) con-
tains the displacement to this structure from structure
QDFFSFCR.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFSFLSCRLLO Displacement to the field with the SFLSCROLL keyword.
2 2 BIN(15) WDFFSFLSIZSFO Displacement to the field specified on the SFLSIZ keyword. -1 indicates
a number was specified.
4 4 BIN(15) WDFFSFLSELOFF Displacement to the field specified on the SFLMLTCHC keyword that is
used to tell the application the number of selections made from the
selection list.
6 6 CHAR(1) WDFFSFLSELCH1 Primary character to be used to indicate a selection list item has been
selected.
7 7 CHAR(1) WDFFSFLSELCH2 Secondary character to be used to indicate a selection list item has
been selected.
8 8 CHAR(8) * Reserved.

Row-Column Table (QDFFRCTB): Row-column table,

one table per screen size. The displacement to this structure
from the beginning of structure QDFFRINF is at variable
WDFFDRCO (page 34-125) in structure QDFFRDPD.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFFFRRO From row of attribute of first field in format.
1 1 CHAR(1) WDFFFRCO From column of attribute of first field in format.
2 2 CHAR(1) WDFFTORO To row of last data character of last field in format (excluding trailing
attribute).
3 3 CHAR(1) WDFFTOCO To column of last data character of last field in format (excluding trailing
attribute).
4 4 CHAR(1) WDFFRBIT Miscellaneous flags.
4 4 0 BIT(1) WDFFMDF Multiple defined fields (MDF) present for this screen size. MDF fields
are defined to be a group of fields that have the same beginning row-
column, and the first field in the group must have field selection.
4 4 1 BIT(1) WDFFFRC1 First field in the record has attribute in column 1 for this screen size.
4 4 2 BIT(1) WDFFTRAT If on, the trailing attribute for this screen size was in column one.
4 4 3 BIT(1) WDFFR1C1 First field in record begins in row 1, column 1 for this screen size.
4 4 4 BIT(1) WDFFR2C1 First field in record begins in row 2, column 1 for this screen size and
the SLNO(nn) keyword.

Chapter 34. File APIs 34-131

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
4 4 5 BIT(3) * Reserved.
5 5 CHAR(1) * Reserved.
6 6 CHAR(*) WDFFRC Row-column table, one entry per field (see structure QDFFRCTE, page
34-132).

Row-Column Table Entry (QDFFRCTE): Row-column

table with one table entry per field. The number of entries in
this structure is defined by variable WDFFFLD (page 34-125)
in structure QDFFRINF. This structure is defined at variable
WDFFRC (page 34-132) in structure QDFFRCTB. The struc-
ture is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFFSROW Starting row. X'FF' indicates that the location for the secondary
display size was *NOLOC, or was a hidden field, a program field, or a
message line.
1 1 CHAR(1) WDFFSCOL Starting column. X'FF' indicates that the location for the secondary
display size was *NOLOC, or was a hidden field, a program field, or a
message line.

Field Name Table (QDFFNTB): Field name table with

one field name entry per field. This structure is present
when the RTNCSRLOC keyword is specified in the DDS.
The number of entries in this structure is defined by variable
WDFFFLD (page 34-125) in structure QDFFRINF. The dis-
placement to this structure from the beginning of structure
QDFFRINF is at variable WDFFNRCO (page 34-128) in
structure QDFFXRDP. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFFNAM Field name entry.

Field Order Table (QDFFOT): Field order table with

one field order entry per field. This structure is present when
the USRDFNMGT keyword is specified in the DDS. The
number of entries in this structure is defined by variable
WDFFFLD (page 34-125) in structure QDFFRINF. The dis-
placement to this structure from the beginning of structure
QDFFRINF is at variable WDFFOTO (page 34-128) in struc-
ture QDFFXRDP. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFLD Order of field in DDS source.

Field Indexing Table (QDFFFITB): Field indexing

table. The number of entries in this structure is defined by
variable WDFFFLD (page 34-125). The displacement to this
structure from the beginning of structure QDFFRINF is at
variable WDFFOFIT (page 34-124) in QDFFRINF. The
structure is ARRAY(*).

34-132 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFFOFS Displacement from the record header (structure QDFFRINF) to this
field’s header section (see structure QDFFFINF, page 34-133).
4 4 BIN(15) WDFFSELI Index to the entry in the selection table (see variable WDFFSTE, page
34-137, in structure QDFFSELT) for the condition selecting this field. 1
represents no field selection.
6 6 BIN(15) WDFFDLEN Display length. Edited field length and UCS-2 displayed field length.
For floating point edited fields, this value is the significand plus 7. For
nonfloating-point edited fields when the FLTFIXDEC keyword is speci-
fied, this value is the length specified for the field plus 2. When the
FLTFIXDEC keyword is not specified, this value is 7 plus the length
specified for the field.

Field Formats Field Header Section (QDFFFINF): Field header

declare. The displacement to this structure from the begin-
Figure 34-9 shows the field section of the overview figure ning of structure QDFFRINF is at variable WDFFFOFS (page
(Figure 34-6 on page 34-119). 34-132) in structure QDFFFITB.
┌────────────────────┐
│Field Header Section│
│(QDFFFINF) │
└─────────┬──────────┘
┌────────┬─────────────────┬─┴───────────────────┬─────────────┐
│ ┌──────┴───────┐ ┌───────┴───────────┐ ┌───────┴───────────┐ │
│ │Constant Field│ │Display-Field-Level│ │Input-Capable │ │
│ │Header Table │ │Device-Dependent │ │Display-Field-Level│ │
│ │(QDFFFCON) │ │Section (QDFFFDPD) │ │Device-Dependent │ │
│ └──────────────┘ └───────┬───────────┘ │Section (QDFFFDIC) │ │
┌┴───────────┐ ┌───────┴───────────┐ └───────────────────┘ │
│Named Field │ │Field-Dependent │ ┌───────────────┴─┐
│Header Table│ │Extension Structure│ │Keyword Category │
│(QDFFFNAM) │ │(QDFFXFDP) │ │Displacement │
└────────────┘ └───────────────────┘ │String (QDFFCOSA)│
└─────────────────┘

Figure 34-9. Field Header Section

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFFLEN Length of this declare, including all the device-dependent sections.
2 2 CHAR(1) WDFFFIOA Field attribute. X'01' indicates Constant (see structure QDFFFCON,
page 34-134), X'02' indicates Output (O), X'03' indicates Message
(M), X'04' indicates Input (I), X'05' indicates Both (B), X'06' indicates
Hidden (H), and X'07' indicates Program to System (P).
3 3 CHAR(1) WDFFBFLG Miscellaneous flags.
3 3 0 BIT(1) WDFFDATE If on, DATE keyword is specified.
3 3 1 BIT(1) WDFFDATY If on, DATEY keyword is specified.
3 3 2 BIT(1) WDFFTIME If on, TIME keyword is specified.
3 3 3 BIT(1) WDFFFOLD If on, BLKFOLD keyword is specified.
3 3 4 BIT(1) WDFFEDIT If on, EDTCDE or EDTWRD keyword is specified.
3 3 5 BIT(1) WDFFINBT If on, field is either input or both.
3 3 6 BIT(1) WDFFDFT If on, DFT or DFTVAL keyword is specified.
3 3 7 BIT(1) WDFFFALT If on, IGCALTTYP keyword is specified.
4 4 CHAR(1) WDFFFBIT Miscellaneous flags.
4 4 0 BIT(1) WDFFIGCC If on, DBCS literals are specified on DFT or DFTVAL keyword.
4 4 1 BIT(1) WDFFFCSO If on, first character of DFT or DFTVAL keyword is shift out (SO).
4 4 2 BIT(1) WDFFOPDV If on, optioned DFTVAL keyword is specified.

Chapter 34. File APIs 34-133

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
4 4 3 BIT(1) WDFFALWE If on, ALWENDLOC applies to field. Trailing attribute byte should be
truncated for at least one display size.
4 4 4 BIT(1) WDFFUSER If on, USER keyword is specified.
4 4 5 BIT(1) WDFFSYSN If on, SYSNAME keyword is specified.
4 4 6 BIT(1) WDFFEDFT If on, EDTWRD was generated due to the DATE or TIME keyword, or
due to the L, T, or Z edit code.
4 4 7 BIT(1) WDFF_EDTCDE_Y If on, the edit code specified on the EDTCDE keyword is used for for-
matting dates. The edit code is either a W or a Y.
5 5 CHAR(1) * Reserved.
6 6 CHAR(*) WDFFFTBE Field header table entries. Use structure QDFFFCON (page 34-134) for
constant fields and structure QDFFFNAM (page 34-134) for named
fields.

Constant Field Header Table (QDFFFCON): Field

header declare for constant fields. This structure is defined
at variable WDFFFTBE (page 34-134) in structure
QDFFFINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(2) * Reserved.
2 2 BIN(15) WDFFFAOC Displacement for constant fields to field-level device-dependent sections
(structure QDFFFDPD, page 34-135) from structure QDFFFINF (page
34-133).

Named Field Header Table (QDFFFNAM): Field

header declare for named fields. This structure is defined at
variable WDFFFTBE (page 34-134) in structure QDFFFINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFINPO Input buffer displacement. -1 indicates no buffer location.
2 2 BIN(15) WDFFOUTO Output buffer displacement. -1 indicates no buffer location.
4 4 BIN(15) WDFFPLEN Program length. User’s program field length for floating point fields indi-
cates precision 4 is defined as *SINGLE; 8 is defined as *DOUBLE.
6 6 CHAR(1) WDFFDEC Decimals (X'00' through X'1F'). X'FF' indicates field is character or
DBCS-capable.
7 7 CHAR(1) WDFFKBDT Keyboard shift and data type. X'00' indicates Alpha shift/character (A),
X'01' indicates Alpha only (X), X'02' indicates Numeric shift (N),
X'03' indicates Numeric only (Y), X'04' indicates Katakana (K), X'05'
indicates Digits only (D), X'06' indicates Inhibit keyboard (I), X'07'
indicates Signed numeric/zoned (S), X'08' indicates Binary (B), X'09'
indicates Packed (P), X'0A' indicates Floating (F), X'0B' indicates
DBCS (J), X'0C' indicates Open (O), X'0D' indicates Either (E),
X'0E' indicates Numeric-only character (M), X'0F' indicates Graphic
(G), X'10' indicates Date (L), X'11' indicates Time (T), and X'12'
indicates Timestamp (Z).
8 8 CHAR(2) * Reserved.
10 A BIN(15) WDFFFAOF Displacement for nonconstant (named) fields to display-field-level
device-dependent section (structure QDFFFDPD, page 34-135) from
structure QDFFFINF (page 34-133).

34-134 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Display-Field-Level Device-Dependent Section

(QDFFFDPD): Display device-dependent section. The
displacement to this structure from the beginning of structure
QDFFFINF is an entry in the table at variable WDFFFAOF
(page 34-134) in structure QDFFFNAM.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFFFLGS Miscellaneous flags.
0 0 0 BIT(1) WDFFDSPC If on, unconditioned DSPATR(PC) keyword is specified.
0 0 1 BIT(1) WDFFUCND If on, unconditioned DSPATR(ND) keyword is specified.
0 0 2 BIT(1) WDFFFXDC If on, FLTFIXDEC keyword is specified.
0 0 3 BIT(1) WDFFIACV If on, IGCANKCNV keyword is specified.
0 0 4 BIT(1) WDFFCSCP If on, CHRID keyword is specified.
0 0 5 BIT(1) WDFFMGID If on, MSGID keyword is specified.
0 0 6 BIT(1) WDFFDPNR If on, DUP keyword is specified without a response indicator on a
numeric field.
0 0 7 BIT(1) WDFFDSPN Field’s base cursor position. If on, the field is input-capable and no
unoptioned DSPATR(PR) or no unoptioned DSPATR(PC) is in any field
in the record.
1 1 CHAR(1) WDFFSA Default screen attribute byte for workstation.
1 1 0 BIT(3) * Reserved. Always B'001'.
1 1 3 BIT(1) WDFFCLOS If on, unconditioned DSPATR(CS) keyword is specified.
1 1 4 BIT(1) WDFFBLNK If on, unconditioned DSPATR(BL) keyword is specified.
Note: If the following three bits are on, unconditioned DSPATR(ND) is specified.
1 1 5 BIT(1) WDFFUDLN If on, unconditioned DSPATR(UL) keyword is specified.
1 1 6 BIT(1) WDFFHILI If on, unconditioned DSPATR(HI) keyword is specified.
1 1 7 BIT(1) WDFFRVIM If on, unconditioned DSPATR(RI) keyword is specified.
2 2 BIN(15) WDFFXFDO Displacement to field-dependent extension structure from QDFFFINF
(see structure QDFFXFDP, page 34-136). 0 indicates no extension
structure is present.
4 4 BIN(15) WDFFFDOC Displacement to keyword category displacement string from structure
QDFFFINF (see structure QDFFCOSA, page 34-138). 0, if no keyword
categories.
6 6 CHAR(*) WDFFFICE Input-capable display field-level device-dependent section entries (see
structure QDFFFDIC, page 34-135). Only used for types X'04' (input)
and X'05' (both); see variable WDFFFIOA, page 34-133, in structure
QDFFFINF.

Input-Capable Display Field-Level Device-

Dependent Section (QDFFFDIC): Input-capable display
device-dependent section. This structure is used for types
X'04' (input) and X'05' (both); see variable WDFFFIOA,
page 34-133, in structure QDFFFINF. This structure is
defined at variable WDFFFICE (page 34-135) in structure
QDFFFDPD.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(2) WDFFFWFW Miscellaneous flags.
0 0 0 BIT(2) * Reserved.
0 0 2 BIT(1) WDFFFWPR If on, unconditioned DSPATR(PR) keyword is specified.

Chapter 34. File APIs 34-135

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 3 BIT(1) WDFFFWDP If on, unconditioned DUP keyword is specified.
0 0 4 BIT(1) WDFFFWMD If on, unconditioned DSPATR(MDT) keyword is specified.
0 0 5 BIT(3) WDFFFWSF Keyboard shift. B'000' indicates alpha shift, B'001' indicates alpha
only, B'010' indicates numeric shift (also floating point), B'011' indi-
cates numeric only (also numeric-only character keyboard shift), B'100'
indicates Katakana/CHECK(RL), B'101' indicates digits only, B'110'
indicates inhibit keyboard, B'111' indicates signed numeric.
1 1 0 BIT(1) WDFFFWRA If on, unconditioned AUTO(RA) keyword is specified.
1 1 1 BIT(1) WDFFFWFE If on, CHECK(FE) keyword is specified.
1 1 2 BIT(1) WDFFFWLW Lowercase (not monocase). 0 indicates lowercase; 1 indicates not low-
ercase (uppercase).
1 1 3 BIT(1) * Reserved.
1 1 4 BIT(1) WDFFFWME If on, unconditioned CHECK(ME) keyword is specified.
1 1 5 BIT(3) WDFFFWAJ Adjustments. B'000' indicates no adjustment, B'101' indicates
AUTO(RAZ), B'110' indicates AUTO(RAB), B'111' indicates
CHECK(MF).
2 2 CHAR(1) WDFFSSKW Keywords present.
2 2 0 BIT(1) WDFFBLKS If on, BLANKS keyword is specified.
2 2 1 BIT(1) WDFFSSCH If on, CHANGE keyword is specified.
2 2 2 BIT(1) WDFFSSDR If on, DUP keyword is specified with a response indicator.
2 2 3 BIT(1) WDFFSSDP If on, DUP keyword is specified with or without a response indicator.
2 2 4 BIT(1) WDFFSSAB If on, CHECK(AB) keyword is specified.
2 2 5 BIT(1) WDFFDSOD If on, DSPATR(OID) keyword is specified.
2 2 6 BIT(1) WDFFDSSP If on, DSPATR(SP) keyword is specified.
2 2 7 BIT(1) WDFFVLCK If on, validity checking keywords specified in category 25, page 34-165
(that is, category 25 is present).
3 3 CHAR(1) WDFFCHKB Miscellaneous flags.
3 3 0 BIT(1) WDFFCM10 If on, CHECK(M10) keyword is specified.
3 3 1 BIT(1) WDFFCM11 If on, CHECK(M11) keyword is specified.
3 3 2 BIT(1) WDFFM10F If on, CHECK(M10F) keyword is specified.
3 3 3 BIT(1) WDFFM11F If on, CHECK(M11F) keyword is specified.
3 3 4 BIT(4) * Reserved.

Field-Dependent Extension Structure

(QDFFXFDP): Field-dependent extension structure. The
displacement to this structure from the beginning of structure
QDFFFINF is at variable WDFFXFDO (page 34-135) in struc-
ture QDFFFDPD.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(2) WDFFKFLG Miscellaneous flag.
0 0 0 BIT(1) WDFFNOBA If on, field has no beginning attribute.
0 0 1 BIT(1) WDFFNOEA If on, field has no ending attribute.
0 0 2 BIT(1) * Reserved.
0 0 3 BIT(1) WDFFFDCP If on, this field is referenced by another field using the FLDCSRPRG
keyword.
0 0 4 BIT(1) WDFFSFCP If on, SFLCSRPRG keyword specified on field.

34-136 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 5 BIT(1) WDFFMLTC If on, MLTCHCFLD keyword is specified.
0 0 6 BIT(1) WDFFSNGC If on, SNGCHCFLD or PSHBTNFLD keyword is specified.
0 0 7 BIT(1) WDFFCNTF If on, CNTFLD keyword is specified.
1 1 0 BIT(1) WDFFENFA If on, ENTFLDATR keyword is specified.
1 1 1 BIT(1) WDFFFCRP If on, FLDCSRPRG keyword is specified.
1 1 2 BIT(1) WDFFEDTM If on, EDTMSK keyword is specified.
1 1 3 BIT(1) WDFFPFLD If on, field has associated program-to-system field.
1 1 4 BIT(1) WDFFNOCC If on, NOCCSID keyword is specified.
1 1 5 BIT(1) WDFFPUSHBTN If on, PSHBTNFLD keyword is specified.
1 1 6 BIT(1) WDFFCHCHDHEXP If on, structure QDFKCHC (page 34-167) has an extension structure
appended to it.
1 1 7 BIT(1) WDFFWRDWRAP If on, WRDWRAP keyword is specified.
2 2 BIN(15) WDFFFLDINX Field index of current field.
4 4 CHAR(1) WDFFXLFLGS Miscellaneous flags.
4 4 0 BIT(1) WDFFVALNUM If on, VALNUM keyword is specified.
4 4 2 BIT(7) * Reserved.
5 5 BIN(16) WDFF_UCS2_CCSID The UCS-2 CCSID specified on the CCSID keyword.
7 7 CHAR(1) * Reserved.

Selection Table (QDFFSELT): Selection table. The

table entries are defined in structure QDFFSTBL (page
34-137). The entries in the where-used section (page
34-178) are stored in the same order as the selection table.
The displacement to this structure from the beginning of
structure QDFFRINF is at variable WDFFSTBO (page
34-124) in structure QDFFRINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(31) WDFFSTLN Selection table length.
4 4 BIN(15) WDFFSTT Total number of table entries used by the display to resolve record- and
field-level selection entries.
6 6 CHAR(2) * Reserved.
8 8 CHAR(*) WDFFSTE Selection table entries (see structure QDFFSTBL, page 34-137).

Selection Table Entry (QDFFSTBL): Selection table

entry. The number of entries in this structure is defined by
variable WDFFSTT (page 34-137) in structure QDFFSELT.
This structure is defined at variable WDFFSTE (page 34-137)
in structure QDFFSELT. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFSTEL Length of this table entry.
2 2 BIN(15) WDFFCND Number of conditions in the entry.

Chapter 34. File APIs 34-137

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
4 4 ARRAY(*) WDFFSELM Array of selection table indicators. The number of entries in this struc-
OF ture is defined by variable WDFFCND in this table. Each character con-
CHAR(1) tains a displacement into the output buffer for an option indicator. An
entry is used to designate whether the indicator must be on (X'F1') or
off (X'F0'). If an entry is on, the indicator must be on; if it is off, the
indicator must be off. The value X'7F' in this field designates the end
of the entry.

Keyword Category Displacement String QDFFRINF at variable WDFFRDOC (page 34-128) in struc-
(QDFFCOSA): Category displacement string. This struc- ture QDFFRDPD. For field-level sections, the displacement
ture occurs for each display file-, record-, or field-level to this structure is from the beginning of structure QDFFFINF
section that has keyword structures. For file-level sections, at variable WDFFFDOC (page 34-135) in structure
the displacement to this structure is from the beginning of QDFFFDPD.
structure QDFFINFO at variable WDFFXDOC (page 34-123)
in structure QDFFDPDD. For record-level sections, the dis-
placement to this structure is from the beginning of structure

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFFCCT Number of entries in the category displacement string.
2 2 CHAR(*) WDFFCCOS Category displacement string (see structure QDFFCCOA, page 34-138).

Keyword Category Displacement String Entry

(QDFFCCOA): Category displacement string array. Each
keyword category type that is present in the file, record, or
field section has an entry. The number of entries in this
structure is defined by variable WDFFCCT (page 34-138) in
structure QDFFCOSA. This structure is defined at variable
WDFFCCOS (page 34-138) in structure QDFFCOSA. The
structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFFCAID Category ID (X'01' through X'FF').
1 1 BIN(15) WDFFCAOF Displacement to category from the start of each section header (see
structure QDFFINFO on page 34-121 for file-level keywords, structure
QDFFRINF on page 34-124 for record-level keywords, or structure
QDFFFINF on page 34-133 for field-level keywords).

Keyword Formats Category 1 (File-Level Keywords): The following table

shows the keyword ID that corresponds to the file-level
keywords. Not all keywords require a structure. There are
no structures for keyword IDs X'01', X'03', and X'0D'.
The text associated with the HLPTITLE keyword is contained
in variable WDFKFLNM (page 34-139) in structure
QDFKFLPP.

ID Keyword ID Keyword
X'01' PASSRCD X'07' HLPDOC
X'02' MSGLOC X'08' HLPSCHIDX
X'03' PRINT X'09' HLPTITLE
X'04' IGCCNV X'0A' ALTNAME
X'05' HLPRCD X'0B' ERRSFL
X'06' HLPPNLGRP X'0C' WDWBORDER

34-138 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

File-Level Keywords (QDFKFILK): File-level keywords.

The displacement to this structure from the beginning of the
appropriate section (file, record, or field) is from variable
WDFFCAOF (page 34-138) in structure QDFFCCOA.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKFIL Number of keywords to follow.
0 0 CHAR(*) WDFKFILE File-level keyword with parameters (see structure QDFKFLPM, page
34-139).

File-Level Keyword with Parameters (QDFKFLPM):

File-level keyword with parameters. The number of entries in
this structure is defined by variable WDFKFIL (page 34-139)
in structure QDFKFILK. This structure is defined at variable
WDFKFILE (page 34-139) in structure QDFKFILK. The
structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKFLID Keyword ID.
1 1 BIN(15) WDFKFLST Index into selection table (see structure QDFFSELT, page 34-137). 1
indicates not optioned.
3 3 BIN(15) WDFKFLRS Response indicator minus one for files with INDARA keyword.
Response indicator input buffer displacement for those without INDARA
keyword. In either case, -1 represents no response indicator specified.
5 5 BIN(15) WDFKFLP Number of parameters to follow.
7 7 CHAR(*) WDFKFLEX Category 1 keyword parameter entries.

Category 1 Parameter Entry (QDFKFLPP): Param-

eter entries for category 1. The number of entries in this
structure is defined by variable WDFKFLP (page 34-139) in
structure QDFKFLPM. This structure is defined at variable
WDFKFLEX (page 34-139) in structure QDFKFLPM. The
structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKFLLN Length of the following keyword parameter entry.
2 2 CHAR(*) WDFKFLNM Keyword parameter structure.

MSGLOC Keyword Structure (QDFKFLSZ):

MSGLOC keyword structure. Use this structure for the cate-
gory 1 keyword that has a keyword ID of X'02' in structure
QDFKFLPM (page 34-139). The number of entries in this
structure is defined by variable WDFFSCR (page 34-120) in
structure QDFFBASE. This structure is defined at variable
WDFKFLNM (page 34-139) in structure QDFKFLPP. The
structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKFLML MSGLOC values.
2 2 CHAR(4) * Reserved.

Chapter 34. File APIs 34-139

Retrieve Display File Description (QDFRTVFD) API

IGCCNV Keyword Structure (QDFKICVP): IGCCNV

keyword structure. Use this structure for the category 1
keyword that has a keyword ID of X'04' in structure
QDFKFLPM (page 34-139). This structure is defined at vari-
able WDFKFLNM (page 34-139) in structure QDFKFLPP.
Note: The IGCCNV keyword generates additional internal
records.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKICVN IGCCNV format line number.
2 2 BIN(15) WDFKICVK IGCCNV format CF key.
4 4 BIN(15) WDFKICVT Index to internally generated record in the record format table.

HLPRCD Keyword Structure (QDFKHARD):

HLPRCD keyword structure. Use this structure for the cate-
gory 1 keyword that has a keyword ID of X'05' in structure
QDFKFLPM (page 34-139). This structure is defined at vari-
able WDFKFLNM (page 34-139) in structure QDFKFLPP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHRFM Record format name.
10 A CHAR(10) WDFKHFIL File name.
20 14 CHAR(10) WDFKHLIB File library name.

HLPPNLGRP Keyword Structure (QDFKHXPS):

HLPPNLGRP keyword structure. Use this structure for the
category 1 keyword that has a keyword ID of X'06' in struc-
ture QDFKFLPM (page 34-139). This structure is defined at
variable WDFKFLNM (page 34-139) in structure QDFKFLPP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHXHG Help panel group.
10 A CHAR(10) WDFKHXHL Help panel group library name.
20 14 BIN(15) WDFKHXML Length of module name.
22 16 CHAR(*) WDFKHXMN Help module name.

HLPDOC Keyword Structure (QDFKHDOC):

HLPDOC keyword structure. Use this structure for the cate-
gory 1 keyword that has a keyword ID of X'07' in structure
QDFKFLPM (page 34-139). This structure is defined at vari-
able WDFKFLNM (page 34-139) in structure QDFKFLPP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHDLA Help text label name.
10 A CHAR(12) WDFKHDDO Document name.
22 16 BIN(15) WDFKHDFL Length of folder name.
24 18 CHAR(*) WDFKHDFD Folder name.

34-140 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

HLPSCHIDX Keyword Structure (QDFKSIDX):

HLPSCHIDX keyword structure. Use this structure for the
category 1 keyword that has a keyword ID of X'08' in struc-
ture QDFKFLPM (page 34-139). This structure is defined at
variable WDFKFLNM (page 34-139) in structure QDFKFLPP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKSIOB Search index object name.
10 A CHAR(10) WDFKSILB Search index object library name.

ALTNAME Keyword Structure (QDFKFALX):

ALTNAME keyword structure. Use this structure for the cate-
gory 1 keyword that has a keyword ID of X'0A' in structure
QDFKFLPM. This structure is defined at variable
WDFKFLNM (page 34-139) in structure QDFKFLPP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKALT Count of ALTNAME keywords.
2 2 CHAR(*) WDFKAARY Alternative names (see structure QDFKFALK, page 34-141).

ALTNAME Keyword Entry (QDFKFALK): ALTNAME

keyword entry. This structure is defined at variable
WDFKAARY (page 34-141) in structure QDFKFALX.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKANME ALTNAME keyword value (excluding apostrophes).
10 A BIN(15) WDFKAINX Index to record format in record format table.

ERRSFL Keyword Structure (QDFKESFL): ERRSFL

keyword structure. Use this structure for the category 1
keyword that has a keyword ID of X'0B' in structure
QDFKFLPM (page 34-139). This structure is defined at vari-
able WDFKFLNM (page 34-139) in structure QDFKFLPP.
Note: The ERRSFL keyword generates additional internal
records.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKESCR Subfile control record name.

WDWBORDER Keyword Structure (QDFKBODR):

WDWBORDER keyword structure. Use this structure for the
category 1 keyword that has a keyword ID of X'0C' in struc-
ture QDFKFLPM (page 34-139). This structure is defined at
variable WDFKFLNM (page 34-139) in structure QDFKFLPP.

Chapter 34. File APIs 34-141

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKCLOR Values for *COLOR. X'00' indicates not specified, X'3A' indicates
BLU, X'20' indicates GRN, X'22' indicates WHT, X'28' indicates
RED, X'30' indicates TRQ, X'32' indicates YLW, X'38' indicates
PNK.
1 1 CHAR(1) WDFKDATR Values for *DSPATR. Combination of two or more of these values:
X'00' indicates no attribute X'30' indicates (*DSPATR CS), X'28'
indicates (*DSPATR BL), X'24' indicates (*DSPATR UL), X'22' indi-
cates (*DSPATR HI), X'21' indicates (*DSPATR RI), and X'27' indi-
cates (*DSPATR ND).
2 2 CHAR(8) WDFKCHRS WDWBORDER characters in the following order: top-left corner, top
horizontal, top-right corner, left vertical, right vertical, bottom-left corner,
bottom horizontal, bottom-right corner. If not specified, eight entries of
X'00' will occur.

Category 2 (Record-Level Command Key

Keywords): The following table shows the keyword ID
that corresponds to the record-level command-key keywords.
Use structure QDFKCKKE for category 1 keyword IDs X'01'
through X'21'. No structures are required for keyword IDs
X'22', X'23', X'24', X'25', and X'30'.

ID Keyword ID Keyword ID Keyword

X'01' CA/CF01 X'0E' CA/CF14 X'1A' ROLLDOWN
X'02' CA/CF02 X'0F' CA/CF15 X'1B' PRINT
X'03' CA/CF03 X'10' CA/CF16 X'1C' HOME
X'04' CA/CF04 X'11' CA/CF17 X'1D' CLEAR
X'05' CA/CF05 X'12' CA/CF18 X'1E' HELP
X'06' CA/CF06 X'13' CA/CF19 X'20' HLPRTN
X'07' CA/CF07 X'14' CA/CF20 X'21' VLDCMDKEY
X'08' CA/CF08 X'15' CA/CF21 X'22' ALTHELP
X'09' CA/CF09 X'16' CA/CF22 X'23' ALTPAGEUP
X'0A' CA/CF10 X'17' CA/CF23 X'24' ALTPAGEDW
X'0B' CA/CF11 X'18' CA/CF24 X'25' MNUBARSW
X'0C' CA/CF12 X'19' ROLLUP X'30' MNUCNL
X'0D' CA/CF13

Command Key Keyword Structure (QDFKCKKW):

Structure for command key keywords. The displacement to
this structure from the beginning of the appropriate section
(file, record, or field) is at variable WDFFCAOF (page
34-138) in structure QDFFCCOA.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKCKS Number of entries in the array.
2 2 CHAR(*) WDFKCKCM Command key keyword entries (see structure QDFKCKKE, page
34-142).

Command Key Keyword Entries (QDFKCKKE):

Command key keyword array. The number of entries in this
structure is defined by variable WDFKCKS in structure
QDFKCKKW. This structure is defined at variable
WDFKCKCM (page 34-142) in structure QDFKCKKW. The
structure is ARRAY(*).

34-142 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKCKID Keyword ID.
1 1 BIN(15) WDFKCKIN Index into selection table. 1 indicates not optioned.
3 3 BIN(15) WDFKCKRS Response indicator minus one for files with INDARA keyword.
Response indicator input buffer displacement for those without INDARA.
-1 indicates no response indicator is specified.
5 5 CHAR(4) WDFKCKMA Key mask (ignored for VLDCMDKEY and HLPRTN keywords). The OR
values for the key mask follow: X'80000000' CA/CF01, X'40000000'
CA/CF02, X'20000000' CA/CF03, X'10000000' CA/CF04,
X'08000000' CA/CF05, X'04000000' CA/CF06, X'02000000'
CA/CF07, X'01000000' CA/CF08, X'00800000' CA/CF09,
X'00400000' CA/CF10, X'00200000' CA/CF11, X'00100000'
CA/CF12, X'00080000' CA/CF13, X'00040000' CA/CF14,
X'00020000' CA/CF15, X'00010000' CA/CF16, X'00008000'
CA/CF17, X'00004000' CA/CF18, X'00002000' CA/CF19,
X'00001000' CA/CF20, X'00000800' CA/CF21, X'00000400'
CA/CF22, X'00000200' CA/CF23, X'00000100' CA/CF24,
X'00000080' ROLLUP, X'00000040' ROLLDOWN, X'00000020'
PRINT, X'00000010' HOME, X'00000008' CLEAR, X'00000004'
HELP.

Category 3 (OVERLAY-Related Keywords and

PUTRETAIN): The following table shows the keyword ID
that corresponds to the OVERLAY-related keywords and
PUTRETAIN. Not all keywords require a structure. There
are no structures for keyword IDs X'02', X'03', X'04',
X'05', X'06', X'08', and X'09'.

ID Keyword ID Keyword
X'01' OVERLAY X'07' PUTRETAIN
X'02' PUTOVR X'08' PROTECT
X'03' ERASEINP(*MDTON) X'09' INZINP
X'04' MDTOFF(*UNPR) X'10' ERASE
X'05' ERASEINP(*ALL) X'11' CLRL
X'06' MDTOFF(*ALL)

OVERLAY Keyword Structure (QDFKOVRR):

OVERLAY-related keywords. This structure is used if the
keyword ID in structure QDFKFLPM (page 34-139) is X'01'.
The displacement to this structure from the beginning of the
appropriate section (file, record, and field) is at variable
WDFFCAOF (page 34-138) in structure QDFFCCOA.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKOLS Number of keyword entries to follow.
2 2 CHAR(*) WDFKOVRT Array of keyword entries. Entries are contained in structure
QDFKOVRE (page 34-143) or QDFKOVRP (page 34-144).

Keyword Structure (QDFKOVRE): Array structure for

keywords. Use this structure for category 3 keywords that
have a keyword ID of X'02', X'03', X'04', X'05', X'06',
X'08', or X'09'. This structure is defined at variable
WDFKOVRT (page 34-143) in structure QDFKOVRR. The
structure is ARRAY(*).

Chapter 34. File APIs 34-143

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKOLAD Keyword ID.
1 1 BIN(15) WDFKOLAN Index into selection table. 1 indicates not optioned.

OVERLAY and PUTRETAIN-Related Keyword Struc-

ture (QDFKOVRP): Structure for OVERLAY and
PUTRETAIN-related keywords. Use this structure for cate-
gory 3 keywords that have a keyword ID of X'01', X'07',
X'10', or X'11'. This structure is defined at variable
WDFKOVRT (page 34-143) in structure QDFKOVRR. The
structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKOLID Keyword ID.
1 1 BIN(15) WDFKOLIN Index into selection table. 1 indicates not optioned.
3 3 CHAR(*) WDFKOLEX Extra remaining portion of this category for ERASE and CLRL.

ERASE Keyword Structure (QDFKOLER): ERASE

keyword structure. Use this structure for the category 3
keyword that has a keyword ID of X'10'. This structure is
defined at variable WDFKOLEX (page 34-144) in structure
QDFKOVRP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKOLE Number of bytes to follow.
2 2 ARRAY(*) WDFKOLAR Indexes to the record format table for the format to be erased. 0, if
OF format does not exist.
BIN(15)

CLRL Keyword Structure (QDFKOLCL): CLRL

keyword structure. Use this structure for the category 3
keyword that has a keyword ID of X'11'. This structure is
defined at variable WDFKOLEX (page 34-144) in structure
QDFKOVRP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKOLC Number of bytes to follow (always 2).
2 2 BIN(15) WDFKOLCN Clear line number.

Category 4 (Record-Level Miscellaneous

Keywords): The following table shows the keyword ID
that corresponds to the record-level miscellaneous keywords.
Not all keywords require a structure. There are no structures
for keyword IDs X'01', X'02', X'03', X'04', X'05', X'06',
X'07', X'08', and X'09'.
Note: Keywords INDARA2 and RTNCSRLOC2 are inter-
nally generated.

34-144 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

ID Keyword ID Keyword
X'01' LOCK X'09' RMVWDW
X'02' ALARM X'0F' DSPMOD
X'03' BLINK X'10' CSRLOC
X'04' LOGOUT X'11' INDARA
X'05' ALWGPH X'13' SETOFF
X'06' MSGALARM X'15' RTNCSRLOC
X'07' RETLCKSTS X'16' MNUBARDSP
X'08' USRRSTDSP

Miscellaneous Record-Level Keywords

(QDFKMSRL): Miscellaneous record-level keywords. The
displacement to this structure from the beginning of the
appropriate section (file, record, or field) is at variable
WDFFCAOF (page 34-138) in structure QDFFCCOA.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKMSS Number of keywords to follow.
2 2 CHAR(*) WDFKMSKW Array of keyword entries. Entries are contained in structure
QDFKMSAP (page 34-145).

Parameter Structure (QDFKMSAP): Array structure for

keywords with simple parameters. This structure is defined
at variable WDFKMSKW (page 34-145) in structure
QDFKMSRL. The structure is ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
2 2 CHAR(1) WDFKMSAD Keyword ID.
3 3 BIN(15) WDFKMSAN Index into selection table. 1 indicates not optioned.

Response Indicator Keyword Array (QDFKMSCP):

Miscellaneous record-level keywords. Use this structure for
category 4 keywords that have a keyword ID of X'10',
X'11', X'0F', or X'13'. The displacement to this structure
from the beginning of structure QDFFRINF is at variable
WDFFINDO (page 34-125) in structure QDFFRINF.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKMSID Keyword ID.
1 1 BIN(15) WDFKMSIN Index into selection table. 1 indicates keyword is not optioned. For
SETOFF, this contains the response indicator displacement.
3 3 CHAR(*) WDFKMSEX Additional structures for CSRLOC, INDARA, DSPMOD, and
MNUBARDSP keywords. (See structures QDFKMSK1 on page 34-145,
QDFKMSK2 on page 34-146, QDFKMSK3 on page 34-146, and
QDFKMSMBDSP on page 34-147.)

CSRLOC Keyword Structure (QDFKMSK1):

Remaining portion of CSRLOC keyword. Use this structure
for a category 4 keyword that has a keyword ID of X'10'.
This structure is defined at variable WDFKMSEX (page
34-145) in structure QDFKMSCP.

Chapter 34. File APIs 34-145

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKMSLC Length of data follows.
2 2 CHAR(1) * Reserved.
3 3 BIN(15) WDFKMSRW Output buffer displacement for row value field.
5 5 BIN(15) WDFKMSCL Output buffer displacement for column value field.
7 7 BIN(31) WDFKMSFA Index into name table for line number field.
11 B BIN(31) WDFKMSFB Index into name table for position number field.

INDARA Keyword Structure (QDFKMSK2):

Remaining portion of INDARA keyword. Use this structure
for a category 4 keyword that has a keyword ID of X'11'.
This structure is defined at variable WDFKMSEX (page
34-145) in structure QDFKMSCP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKMSLN Length of data that follows. Length may be zero.
2 2 ARRAY(*) WDFKMSRI List of response indicators that are referred to in this record (including
OF SETOFF). The value is the indicator displacement (that is, the indicator
BIN(15) number minus one). If an indicator is only an option indicator (and not
a response indicator), this value is -1.

DSPMOD Keyword Structure (QDFKMSK3):

Remaining portion of DSPMOD keyword. Use this structure
for a category 4 keyword that has a keyword ID of X'0F'.
This structure is defined at variable WDFKMSEX (page
34-145) in structure QDFKMSCP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKMSDM Index into display size array (valid values are 1 through 4).

RTNCSRLOC and RTNCSRLOC2 Keyword Structure

(QDFKMSCLN): Remaining portion of RTNCSRLOC and
RTNCSRLOC2 keywords. Use this structure for a category 4
keyword that has a keyword ID of X'15'. This structure is
defined at variable WDFKMSEX (page 34-145) in structure
QDFKMSCP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKMSCRO Displacement into input buffer to the hidden field that contains the name
of the record that the cursor is on. Valid for RTNCSRLOC keyword or
for the *RECNAME parameter of the RTNCSRLOC2 keyword.
0 0 BIN(15) WDFKRCLR Displacement into input buffer to the hidden field that contains the row
number the cursor is on. Valid for *WINDOW or *MOUSE parameter of
RTNCSRLOC2 keyword.
2 2 BIN(15) WDFKMSCFO Displacement into input buffer to the hidden field that contains the name
of the field that the cursor is on. Valid for RTNCSRLOC keyword or for
the *RECNAME parameter of the RTNCSRLOC2 keyword.

34-146 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
2 2 BIN(15) WDFKRCLC Displacement into input buffer to the hidden field that contains the
column number the cursor is on. Valid for *WINDOW or *MOUSE
parameter of RTNCSRLOC2 keyword.
4 4 BIN(15) WDFKMSCLO Displacement into input buffer to the hidden field that contains the rela-
tive position into the field that the cursor is on. Valid for RTNCSRLOC
keyword or for the *RECNAME parameter of the RTNCSRLOC2
keyword.
4 4 BIN(15) WDFKCLWR Displacement into input buffer to the hidden field that contains the row
of the cursor relative to the active window or to the location of the
cursor after the mouse button action has been processed. Valid for
*WINDOW or *MOUSE parameter of RTNCSRLOC2 keyword.
6 6 BIN(15) WDFKRCLWC Displacement into input buffer to the hidden field that contains the
column of the cursor relative to the active window or to the location of
the cursor after the mouse button action has been processed. Valid for
*WINDOW or *MOUSE parameter of RTNCSRLOC2 keyword and does
not exist for the RTNCSRLOC keyword.
8 8 CHAR(1) WDFKRCTYPE The type of RTNCSRLOC format specified. X'00' indicates
*RECNAME is specified, X'01' indicates *WINDOW is specified, and
X'02' indicates *MOUSE is specified. This section is only valid for the
RTNCSRLOC2 keyword and does not exist for the RTNCSRLOC
keyword.
9 9 CHAR(1) WDFKRCFLGS Miscellaneous flags for the RTNCSRLOC2 keyword. This section is
only valid for the RTNCSRLOC2 keyword and does not exist for the
RTNCSRLOC keyword.
9 9 0 BIT(1) WDFKRCLFMT2 1 indicates this is returning row-column information. 0 indicates this is
returning record name and field name information. This section is only
valid for the RTNCSRLOC2 keyword and does not exist for the
RTNCSRLOC keyword.
9 9 1 BIT(7) * Reserved.

MNUBARDSP Keyword Structure

(QDFKMSMBDSP): Remaining portion of MNUBARDSP.
Use this structure for a category 4 keyword that has a
keyword ID of X'16'. This structure is defined at variable
WDFKMSEX (page 34-145) in structure QDFKMSCP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKMBDRCN The name of the menu bar record that the MNUBARDSP keyword
wants to display. If MNUBARDSP is on a MNUBAR keyword record,
this field contains hexadecimal zeros.
10 A BIN(15) WDFKMBDCFO Displacement into input buffer to the hidden field that contains the
number of the CHOICE specified by the user. -1, if not used.
12 C BIN(15) WDFKMBDPIO If the PULLDOWN contains only the SNGCHCFLD keyword, this is the
displacement into the input buffer to the hidden field that contains the
input from the PULLDOWN. -1, if not used.

Category 0B Keywords (File-Level Keywords with File-Level Keywords with Parameters Structure
Parameters): The following table shows the keyword ID (QDFK0BPR): File-level keywords with parameters. The
that corresponds to category 0B keywords. Both of these displacement to this structure from the beginning of the
keyword IDs require a structure. appropriate section (file, record, or field) is at variable
WDFFCAOF (page 34-138) in structure QDFFCCOA.
ID Keyword
X'01' GRDATR
X'02' HLPSHELF

Chapter 34. File APIs 34-147

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFK0BPCT Number of keywords to follow.
2 2 CHAR(*) WDFK0BKW File-level keyword entries. See structure QDFK0BXWP (page 34-148).

File-Level Keyword Structure (QDFK0BXWP): File-

level keyword structure. This structure is defined at variable
WDFK0BKW (page 34-148) in structure QDFK0BPR.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFK0BPID Keyword ID.
1 1 BIN(15) WDFK0BPIN Index into selection table. 1 indicates keyword is not optioned.
3 3 BIN(15) WDFK0BPLN Length of parameter for keyword.
5 5 CHAR(*) WDFK0BPEX Extra remaining portion for keywords. The actual length is in variable
WDFKMPLN (page 34-149) in structure QDFKMRWP.

GRDATR Parameter Structure (QDFK0BGATR):

GRDATR parameter structure. Use this structure for cate-
gory 0B keywords that have a keyword ID of X'01'. The
structure is defined at variable WDFK0BPEX (page 34-148)
in structure QDFK0BXWP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFK0BCLR Color parameter. X'FE' indicates not specified.
1 1 CHAR(1) * Reserved.
2 2 CHAR(1) WDFK0BLT Line type. X'FE' indicates not specified.
3 3 CHAR(1) * Reserved.

HLPSHELF Parameter Structure (QDFKHBKPRM):

Structure for HLPSHELF parameters. Use this structure for
category 0B keywords that have a keyword ID of X'02'.
The structure is defined at variable WDFK0BPEX (page
34-148) in structure QDFK0BXWP.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(8) WDFKHBKNAM Bookshelf name.

Category 17 (Record-Level Miscellaneous

Keywords with Parameters): The following table shows
the keyword ID that corresponds to the record-level miscella-
neous keywords with parameters. Not all keywords require a
structure. There are no structures for keyword IDs X'03',
X'04', and X'05'.
Note: HLP is an internal keyword generated when an
H-specification is specified.

34-148 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

ID Keyword ID Keyword
X'01' HLP X'05' TIMER
X'02' HLPSEQ X'06' PRINT
X'03' HLPTITLE X'07' WDWBORDER
X'04' HLPCLR X'08' WINDOW

Miscellaneous Record-Level Structure

(QDFKMRPR): Miscellaneous record-level with parame-
ters. The displacement to this structure from the beginning
of the appropriate section (file, record, or field) is at variable
WDFFCAOF (page 34-138) in structure QDFFCCOA.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKRPS Number of keywords to follow
2 2 CHAR(*) WDFKRPKW Record-level keyword entries (see structure QDFKMRWP, page
34-149).

Miscellaneous Record-Level Keywords

(QDFKMRWP): Miscellaneous record-level keywords.
This structure is defined at variable WDFKRPKW (page
34-149) in structure QDFKMRPR. The structure is
ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKMPID Keyword ID.
1 1 BIN(15) WDFKMPIN Index into selection table. 1 indicates keyword is not optioned.
3 3 BIN(15) WDFKMPLN Length of parameter for keyword.
5 5 CHAR(*) WDFKMPEX Extra remaining portion for keywords. Actual length of parameter is
specified in variable WDFKMPLN in this structure.

HLP Keyword Structure (QDFKHSTR): Remaining

portion of H-specification. Use this structure for a category
17 keyword that has a keyword ID of X'01'. This structure
is defined at variable WDFKMPEX (page 34-149) in structure
QDFKMRWP.
Note: HLP is an internal keyword generated when an
H-specification is specified.

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKH Count of H-specifications.
2 2 CHAR(*) WDFKHV Variable part of parameter.

HLP Keyword Entry Structure (QDFKHPRM): Entry

for the internal HLP keyword. The total number of entries is
contained in variable WDFKH (page 34-149) in structure
QDFKHSTR. This structure is defined at variable WDFKHV
(page 34-149) in structure QDFKHSTR. Displacements to
subsequent entries are calculated using variable
WDFKHOFS in structure QDFKHSTR. The structure is
ARRAY(*).

Chapter 34. File APIs 34-149

Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 BIN(15) WDFKHOFS Length of this H-specification.
2 2 BIN(15) WDFKHFLG Flags for H-specification.
2 2 0 BIT(1) WDFKHBDY If on, HLPBDY keyword is specified.
2 2 1 BIT(1) WDFKHPRD If on, HLPRCD keyword is specified. Structure QDFKHNMS (page
34-150) is defined at variable WDFKHVAR of this structure.
2 2 2 BIT(1) WDFKHPNL If on, HLPPNLGRP keyword is specified. Structure QDFKHPS (page
34-150) is defined at variable WDFKHVAR.
2 2 3 BIT(1) WDFKHPDC If on, HLPDOC keyword is specified. Structure QDFKHRDC (page
34-151) is defined at variable WDFKHVAR.
2 2 4 BIT(1) WDFKDFHR If on, file name on HLPRCD keyword is the default.
2 2 5 BIT(1) WDFKHEXC If on, HLPEXCLD keyword is specified.
2 2 6 BIT(1) WDFKENPT If on, CHOICE, MNUBAR, or PULLDOWN help was specified in this
H-specification. This indicates enhanced display structure QDFKHARX
(page 34-151) is mapped at variable WDFKHEXT (page 34-151) in
structure QDFKHARA.
2 2 7 BIT(9) * Reserved.
4 4 BIN(15) WDFKHSRO Displacement to structure containing help source information. (See
structure QDFKHNMS on page 34-150, QDFKHPS on page 34-150, or
QDFKHRDC on page 34-151.)
6 6 BIN(15) WDFKHCRD Selection string for help source on HLPRCD, HLPDOC, and
HLPPNLGRP keywords. 1 indicates not specified or no indicator on
keyword.
8 8 BIN(15) WDFKHCBY Selection string for HLPBDY keyword. 1 indicates keyword not speci-
fied or no indicator on keyword.
10 A BIN(15) WDFKHARO Displacement to HLPARA information (see structure QDFKHARA, page
34-151).
12 C BIN(15) WDFKHCEX Selection string for HLPEXCLD. 1 indicates keyword not specified or
no indicator on keyword.
14 E CHAR(3) * Reserved.
17 11 CHAR(*) WDFKHVAR Variable length parameters.

HLPRCD Keyword Structure (QDFKHNMS):

HLPRCD keyword structure. This structure is present only if
variable WDFKHPRD in structure QDFKHPRM is set on.
This structure is defined at variable WDFKHVAR (page
34-150) in structure QDFKHPRM.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHRCD Record format name.
10 A CHAR(10) WDFKHFLE File name.
20 14 CHAR(10) WDFKHRLB File library name. If file and library were not specified, these are the
display file and library names. If file but not library is specified, the
library name is *LIBL.

HLPPNLGRP Keyword Structure (QDFKHPS):

HLPPNLGRP keyword structure. This structure is present
only if variable WDFKHPNL in structure QDFKHPRM is set
on. This structure is defined at variable WDFKHVAR (page
34-150) in structure QDFKHPRM.

34-150 AS/400 System API Reference V4R4

 Retrieve Display File Description (QDFRTVFD) API

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHPNN Help panel group name.
10 A CHAR(10) WDFKHPLB Help panel group library name. If library was not specified, the library
name is *LIBL.
20 14 BIN(15) WDFKHMLN Length of help module name.
22 16 CHAR(*) WDFKHMN Help module name.

HLPDOC Keyword Structure (QDFKHRDC):

HLPDOC keyword structure. This structure is present only if
variable WDFKHPDC in structure QDFKHPRM is set on.
This structure is defined at variable WDFKHVAR (page
34-150) in structure QDFKHPRM.

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(10) WDFKHRLA Help text label name.
10 A CHAR(12) WDFKHRDO Document name.
22 16 BIN(15) WDFKHRFL Length of folder name.
24 18 CHAR(*) WDFKHRFD Folder name.

HLPARA Keyword Structure (QDFKHARA):

HLPARA keyword structure. This structure is repeated for
each display size specified. The number of display sizes is
defined by variable WDFFSCR in structure QDFFBASE.
This structure is defined at variable WDFKHARO (page
34-150) in structure QDFKHPRM. The structure is
ARRAY(*).

Offset
Dec Hex Bit Type Variable Name Field
0 0 CHAR(1) WDFKHFRO From row.
1 1 CHAR(1) WDFKHFCO From column.
2 2 CHAR(1) WDFKHTRO To row.
3 3 CHAR(1) WDFKHTCO To column.
4 4 CHAR(*) WDFKHEXT Enhanced display extension (see structure QDFKHARX, page 34-151).
This field is present only if variable WDFKENPT (page 34-150) in struc-
ture QDFKHPRM is on.

HLPARA Keyword Enhanced Display Structure

(QDFKHARX): HLPARA enhanced display mapping. This
structure is present only if variable WDFKHPRD (page
34-150) in structur