IBM Systems - iSeries

iSeries Access for Windows: Programming Version 5 Release 4

IBM Systems - iSeries

iSeries Access for Windows: Programming Version 5 Release 4

Note Before using this information and the product it supports, read the information in Notices, on page 583.

Seventh Edition (February 2006)

This edition applies to version 5, release 4, modification 0 of IBM eServer iSeries Access for Windows (product number 5722-XE1) and to all subsequent releases and modifications until otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC) models nor does it run on CISC models.

Copyright International Business Machines Corporation 1999, 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

iSeries Access for Windows : Programming . . . . . . . . . . . . 1 Whats new . . . . . . . . . . . . . . . 1 Printable PDFs . . . . . . . . . . . . . . 2 iSeries Access for Windows C/C++ APIs . . . . . 2

iSeries Access for Windows C/C++ APIs overview 2 API groups, header files, import libraries, and DLLs . . . . . . . . . . . . . . . 2 Programmers Toolkit . . . . . . . . . 4

Install the Programmers Toolkit . . . . . 5 Launch the Programmers Toolkit . . . . 5

iSeries name formats for connection APIs . . . 5 OEM, ANSI, and Unicode considerations . . . 6

Use a single iSeries Access for Windows API type . . . . . . . . . . . . . . 8 Use mixed iSeries Access for Windows API types . . . . . . . . . . . . . . 8 Write a generic iSeries Access for Windows application . . . . . . . . . . . . 8

Obsolete iSeries Access for Windows APIs . . 9 Obsolete Communications APIs . . . . . 9 Obsolete Data Queues APIs . . . . . . 10 Obsolete Remote Command/Distributed Program Call APIs . . . . . . . . . 10 Obsolete Security APIs . . . . . . . 10 Obsolete Serviceability APIs . . . . . . 11 Obsolete System Object Access (SOA) API 12 Obsolete National Language Support (NLS) APIs . . . . . . . . . . . . . . 12 Obsolete Database APIs . . . . . . . 12

Return codes and error messages . . . . . 12 iSeries Access for Windows return codes that correspond to operating system errors . 13 iSeries Access for Windows return codes . 14 iSeries Access for Windowscomponent-specific return codes . . . . . . . . 21

iSeries Access for WindowsAdministration APIs 32 Administration APIs list . . . . . . . . 32

cwbAD_GetClientVersion . . . . . . . 32 cwbAD_GetProductFixLevel . . . . . . 33 cwbAD_IsComponentInstalled . . . . . 33 cwbAD_IsOpNavPluginInstalled . . . . 37

Example: Administration APIs . . . . . . 37 iSeries Access for Windows Communications and Security APIs . . . . . . . . . . . . . 42

System object attributes . . . . . . . . 43 System object attributes list . . . . . . 44

Communications and security: Create and delete APIs . . . . . . . . . . . . 47

cwbCO_CreateSystem . . . . . . . . 47 cwbCO_CreateSystemLike . . . . . . 48 cwbCO_DeleteSystem . . . . . . . . 49

Communications and security: Connect and disconnect APIs . . . . . . . . . . . 50

cwbCO_Connect . . . . . . . . . . 50

cwbCO_Disconnect . . . . . . . . . 51 cwbCO_GetConnectTimeout . . . . . . 53 cwbCO_GetPersistenceMode . . . . . . 53 cwbCO_IsConnected . . . . . . . . 54 cwbCO_SetConnectTimeout . . . . . . 55 cwbCO_SetPersistenceMode . . . . . . 56 cwbCO_Verify . . . . . . . . . . 57

Communication and security: Security validation and data APIs . . . . . . . . 58

cwbCO_ChangePassword . . . . . . . 58 cwbCO_GetDefaultUserMode . . . . . 60 cwbCO_GetFailedSignons . . . . . . 61 cwbCO_GetPasswordExpireDate . . . . 61 cwbCO_GetPrevSignonDate . . . . . . 63 cwbCO_GetPromptMode . . . . . . . 64 cwbCO_GetSignonDate . . . . . . . 64 cwbCO_GetUserIDEx . . . . . . . . 66 cwbCO_GetValidateMode . . . . . . 66 cwbCO_GetWindowHandle . . . . . . 67 cwbCO_HasSignedOn . . . . . . . . 68 cwbCO_SetDefaultUserMode . . . . . 69 cwbCO_SetPassword . . . . . . . . 70 cwbCO_SetPromptMode . . . . . . . 71 cwbCO_SetUserIDEx . . . . . . . . 72 cwbCO_SetWindowHandle . . . . . . 73 cwbCO_SetValidateMode . . . . . . . 74 cwbCO_Signon . . . . . . . . . . 75 cwbCO_VerifyUserIDPassword . . . . . 76

Communications and security: Get and set attribute APIs . . . . . . . . . . . . 78

cwbCO_CanModifyDefaultUserMode . . . 78 cwbCO_CanModifyIPAddress . . . . . 79 cwbCO_CanModifyIPAddressLookupMode 79 cwbCO_CanModifyPersistenceMode . . . 80 cwbCO_CanModifyPortLookupMode . . . 81 cwbCO_CanModifyUseSecureSockets . . . 82 cwbCO_GetDescription . . . . . . . 83 cwbCO_GetHostCCSID . . . . . . . 83 cwbCO_GetHostVersionEx . . . . . . 84 cwbCO_GetIPAddress . . . . . . . . 85 cwbCO_GetIPAddressLookupMode . . . 86 cwbCO_GetPortLookupMode . . . . . 87 cwbCO_GetSystemName . . . . . . . 87 cwbCO_IsSecureSockets . . . . . . . 88 cwbCO_SetIPAddress . . . . . . . . 89 cwbCO_SetIPAddressLookupMode . . . 90 cwbCO_SetPortLookupMode . . . . . 92 cwbCO_UseSecureSockets . . . . . . 93

Defines for cwbCO_Service . . . . . . . 94 Differences between cwbCO_Signon and cwbCO_VerifyUserIDPassword . . . . . . 95 Similarities between cwbCO_Signon and cwbCO_VerifyUserIDPassword . . . . . . 95 Communications: Create and delete APIs . . 95

cwbCO_CreateSysListHandle . . . . . 95 cwbCO_CreateSysListHandleEnv . . . . 96

Copyright IBM Corp. 1999, 2006 iii

cwbCO_DeleteSysListHandle . . . . . 97 cwbCO_GetNextSysName . . . . . . 97 cwbCO_GetSysListSize . . . . . . . 99

Communications: System information APIs . . 99 cwbCO_GetActiveConversations . . . . 99 cwbCO_GetConnectedSysName . . . . 100 cwbCO_GetDefaultSysName . . . . . 101 cwbCO_GetHostVersion . . . . . . . 102 cwbCO_GetUserID . . . . . . . . 103 cwbCO_IsSystemConfigured . . . . . 104 cwbCO_IsSystemConfiguredEnv . . . . 105 cwbCO_IsSystemConnected . . . . . 105

Communications: Configured environments information . . . . . . . . . . . . 106

cwbCO_GetActiveEnvironment . . . . 106 cwbCO_GetEnvironmentName . . . . 107 cwbCO_GetNumberOfEnvironments . . 108

Communications: Environment and connection information . . . . . . . . 108

cwbCO_CanConnectNewSystem . . . . 108 cwbCO_CanModifyEnvironmentList . . . 109 cwbCO_CanModifySystemList . . . . . 110 cwbCO_CanModifySystemListEnv . . . 110 cwbCO_CanSetActiveEnvironment . . . 111

Example: Using iSeries Access for Windows communications APIs . . . . . . . . . 111

iSeries Access for Windows Data Queues APIs 122 Data queues . . . . . . . . . . . . 123 Ordering data queue messages . . . . . 123 Work with data queues . . . . . . . . 123 Typical use of data queues . . . . . . . 124 Data Queues: Create, delete, and open APIs 125

cwbDQ_CreateEx . . . . . . . . . 125 cwbDQ_DeleteEx . . . . . . . . . 127 cwbDQ_OpenEx . . . . . . . . . 128

Data Queues: Accessing data queues APIs 130 cwbDQ_AsyncRead . . . . . . . . 130 cwbDQ_Cancel . . . . . . . . . . 131 cwbDQ_CheckData . . . . . . . . 132 cwbDQ_Clear . . . . . . . . . . 133 cwbDQ_Close . . . . . . . . . . 134 cwbDQ_Create . . . . . . . . . . 135 cwbDQ_Delete . . . . . . . . . . 136 cwbDQ_GetLibName . . . . . . . . 138 cwbDQ_GetQueueAttr . . . . . . . 138 cwbDQ_GetQueueName . . . . . . 139 cwbDQ_GetSysName . . . . . . . . 140 cwbDQ_Open . . . . . . . . . . 141 cwbDQ_Peek . . . . . . . . . . 142 cwbDQ_Read . . . . . . . . . . 143 cwbDQ_Write . . . . . . . . . . 145

Data Queues: Attributes APIs . . . . . . 146 cwbDQ_CreateAttr . . . . . . . . 146 cwbDQ_DeleteAttr . . . . . . . . 146 cwbDQ_GetAuthority . . . . . . . 147 cwbDQ_GetDesc . . . . . . . . . 148 cwbDQ_GetForceToStorage . . . . . . 148 cwbDQ_GetKeySize . . . . . . . . 149 cwbDQ_GetMaxRecLen . . . . . . . 150 cwbDQ_GetOrder . . . . . . . . . 150 cwbDQ_GetSenderID . . . . . . . . 151

cwbDQ_SetAuthority . . . . . . . . 152 cwbDQ_SetDesc . . . . . . . . . 153 cwbDQ_SetForceToStorage . . . . . . 153 cwbDQ_SetKeySize . . . . . . . . 154 cwbDQ_SetMaxRecLen . . . . . . . 155 cwbDQ_SetOrder . . . . . . . . . 155 cwbDQ_SetSenderID . . . . . . . . 156

Data Queues: Read and write APIs . . . . 157 cwbDQ_CreateData . . . . . . . . 157 cwbDQ_DeleteData . . . . . . . . 157 cwbDQ_GetConvert . . . . . . . . 158 cwbDQ_GetData . . . . . . . . . 158 cwbDQ_GetDataAddr . . . . . . . 159 cwbDQ_GetDataLen . . . . . . . . 160 cwbDQ_GetKey . . . . . . . . . 161 cwbDQ_GetKeyLen . . . . . . . . 161 cwbDQ_GetRetDataLen . . . . . . . 162 cwbDQ_GetRetKey . . . . . . . . 163 cwbDQ_GetRetKeyLen . . . . . . . 163 cwbDQ_GetSearchOrder . . . . . . . 164 cwbDQ_GetSenderInfo . . . . . . . 165 cwbDQ_SetConvert . . . . . . . . 166 cwbDQ_SetData . . . . . . . . . 166 cwbDQ_SetDataAddr . . . . . . . . 167 cwbDQ_SetKey . . . . . . . . . . 168 cwbDQ_SetSearchOrder . . . . . . . 169

Example: Using Data Queues APIs . . . . 169 iSeries Access for Windows Data Transformation and National Language Support (NLS) APIs . . 171

iSeries Access for Windows data transformation APIs . . . . . . . . . 171

iSeries Access for