API Status Code Descriptions

The following table lists the API status codes and their descriptions:

Status Code

Indicates

Description

0

Successful method execution.

This status code reflects the status of the API method call; it does not reflect the success (or otherwise) of the SQL or RPC sent to the server. An API method call may be sent to the server successfully, thus resulting in a zero (0) status code, but the server may report a syntax error. For complete error checking, the status code should be checked first. Then the message portion of the SCB should be interrogated once data is available from the server before processing continues.

1

No description found for specified column.

This error will be returned if an EDAINFO is issued for a column number that is greater than the number of columns available.

2

No field descriptions for this table.

This status code is issued in response to an EDAINFO, EDANEXT, EDAFETCH, or EDAFIELD method call when no result set has been delivered from the server. This may occur if an error has occurred that prevented the creation of a result set, or if an EDAINFO was issued after a request that did not return a result set (for example, after an EDARPC that issues an update request).

3

Process interruption.

EDAQUIT produces this error code. SCBs are operated on by another thread.

4

Field truncated, receiving field too small (EDAFETCH, EDAFIELD, EDASERVERS).

This status code is returned when an EDAFETCH is issued with an application buffer size that is too small to accommodate the resulting data. This indicates that the binary or alpha tuple size from the SCB was not used as the basis for sending this method call.

A +4 will also be issued if:

EDAFIELD is issued with insufficient space for the resulting field. The binary and alpha size required for a column value can be retrieved from EDAINFO.

EDAFIELD is issued as part of the normal processing of an LOB data type. With LOB data types, EDAFIELD is issued repeatedly until all the data has been retrieved. A status of 4 is returned while there is still more data to be retrieved. A status of zero (success) is issued once all of the data has been received.

EDASERVERS is issued when the buffer to hold the server names is not large enough. EDASERVERS should always be preceded by an EDAINSPECT for EDA_VAR_SERVERCOUNT (18), which will provide the number of servers for which space must be provided.

5

End-of-set indicator (EDAFETCH).

This status code is returned whenever an EDAFETCH or EDANEXT is issued after the last row has been retrieved from a result set. This is part of normal processing and should be used by the application to indicate that there are no more rows to be retrieved for this result set.

A 5 will also be issued:

On the first method call to EDAFETCH or EDANEXT when the result set is empty.

After an EDAFIELD or EDANULL, if the end of the result set has already been reached.

6

Timeout.

Setting MAXWAIT in the configuration file specifies to the API the allotted time to wait for a response to or from the server. This time has been reached.

7

End of transmission.

When multiple result sets are to be processed for an SCB, an EDAQUIT must be issued after each result set in order to proceed to the next result set. A 7 status code is returned after an EDAQUIT when there are no more result sets to be processed.

8

Field overflow.

This warning status indicates that the contents of a field value overflowed the space defined for the field. This might occur when aggregating numeric values.

9

Method not complete in non-block mode.

If the API is operating in non-block mode, this return code will arrive if the method was forced to block to complete its operation.

10

Default trace initialization failure.

Default trace initialization failure.

-1

Invalid EID.

This status code will occur if an API method call is made that references only an EID, as opposed to an SCB, that is incorrect. An EDATERM, EDACOMMIT, or EDAWAIT issued with an invalid EID reference will return a -1.

-2

Too many identifiers.

This error code is obsolete.

Note: The following explanation is for previous releases. An API application should only reference a single environment at a time. That is, EDAINIT or EDAPINIT can only be called once unless an intervening EDATERM is issued. A -2 status is returned when a call to EDAINIT is issued in an already initialized SQL environment.

The API does not force the limit of a single EDAINIT in a Windows environment. It is the responsibility of the application to ensure that only a single EDAINIT is active at one time.

-3

Invalid SID.

An SID is a session identifier that relates to an SCB. A -3 status code typically indicates that a method call referencing the SCB has been corrupted in some way.

-4

Too many SCBs allocated.

This status code will return when an attempt to allocate an SCB using EDACONNECT is unsuccessful.

-5

SCB not initialized.

This status code is returned if a method call is made that references an SCB that does not contain valid information. For example, the EID may be incorrect or the SCB may no longer be initialized. The -5 is returned to the status area of the SCB.

-6

SCB already initialized.

This status code should only be returned during an attempt to initialize an SCB that is already initialized. Since the provision of an SCB at EDACONNECT is the responsibility of the API, this should not occur unless an internal error in the API is encountered.

-7

Unable to initialize connector.

This status code indicates that the API was either unable to find or unable to read the communications configuration file. Check that the location of the correct configuration is the first one accessible using the PATH and ensure that the contents are readable and correct.

If an attempt is made to access an asynchronous message queue that cannot be reached, either during messaging initialization or during browse operations, the API will attempt to return an error code of -7

(EDA_DATA_RECEIVE_ERROR) instead of returning an internal error or end-of-set. This error can occur when the queue is made unavailable during forward fetch operations, so that it may be possible for a user to receive EDA_SUCCESS on previous fetches and receive the -12 error code. This is the equivalent of the connector losing its link to a remote server. The application cannot recover from this error. Recovery will require disconnecting from the server and reestablishing the connection.

-8

Unable to close connector.

This status code is returned if the API attempts to terminate a communication session but is unable to. Typically, a problem with communications is indicated prior to terminating a request and, as such, this status code is not common.

-9

Unable to connect to server.

This return code generally indicates either that the server or communications resources are unavailable, or that there is an error in the configuration. Ensure that the resources indicated in the connector configuration file are correct and available. Ensure that the server name indicated is correct and that it matches the service name on the server (for non-UNIX servers). Ensure that you can ping the host if TCP/IP is the protocol. Check to see if a connection to the server is possible from an alternate client. If this is successful, either the client configuration is incorrect or the communications resources are not available from that location. If this is not successful, ensure that the server is up and running and that it is not in an error state.

Note: The client should disconnect after receiving a -9 before attempting to reconnect.

-10

Unable to disconnect from server.

This status code is returned if the API attempts to disconnect a communications link to the server but is unable to. Typically a communications error will be indicated prior to the disconnect attempt.

-11

Data send failure.

This status code indicates that the API was in the process of sending a request to the server but was unsuccessful. This would occur after an initial successful connect to the server. Typically a problem in the communications has been encountered, but it is possible that the server has become unavailable either because it was terminated or it encountered an error state. If the server is still processing normally, the communications environment should be investigated. It is possible that a sporadic network problem was encountered. If this status code is encountered consistently for a particular request, it is possible that the size or character or the request is either causing a problem for the communications or for the server. Check to see if it occurs with the Test Tool provided. Examine the traces.

Note: The client should disconnect after receiving a -11 before attempting to reconnect.

-12

Data receive failure.

This status code indicates that a problem was encountered while the client was attempting to receive data from the server after an initial successful connection. Check the server status after receiving this error and check that the communications resources are intact. A -12 may occur for a specific request or for specific data retrieval. If this is the case, the same request should be attempted from the Test Tool.

Note: The client should disconnect after receiving a -12 (before attempting to reconnect).

-13

Operation not permitted in this context.

This status code indicates that an operation was attempted out of state. For example, an EDAFETCH issued prior to an EDASQL or EDARPC would return a -13. A -13 may also be returned if the application does not check and act on the status codes returned for each method call. An application may send an EDASQL, for example, that returns with a -12. If an EDAFETCH is issued without checking the previous status code, a -13 is returned. Similarly, any send operation after a -9, -11, or -12, all of which indicate a communications breakdown, will result in a -13.

An attempt to set a variable that is not settable, or not settable for a particular server, will also return a -13. For example, an attempt to set a read-only variable such as the API version or an attempt to set SLIM when the server does not support SLIM will return a -13. Attempted retrieval of a LOB data value with SLIM not set will also return a -13, as will an attempt to send an update request to an engine that is declared as read-only by the server.

A -13 will also be emitted if an EDAUSING is issued with invalid parameters, or if an invalid prepare handle is passed to an EDAUSING or an EDAEXECUTE.

-14

Insufficient memory available for this operation.

The API emits this status code if it is unable to allocate sufficient memory to complete the operation requested. When this error is encountered, run the application without anything else running. Use standard memory tools to analyze the memory usage at the client. Also check the application to ensure that it is freeing resources when possible. Prepares should be freed when finished with using the EDAXPREPARE method. Use of the EDASET for EDA_VAR_NO_FRAGMENT (147) may help if memory fragmentation is the issue.

-15

Invalid parameter value.

Every API method call is issued with a series of parameters that must all be provided, even if they are null. This status code indicates that either one of the parameter values was incorrect or that a parameter value was missing. A -15 status code will also be returned if an invalid column number is provided for the EDAFIELD method call.

-16

Tuple alignment error.

This status code may occur if an attempt to fetch data in binary form is made and the default boundary alignments are not adhered to by the application. For integer and float data types, the boundary alignment should be 4. For double-precision and decimal data types, it is 8 by default. These default values can be changed using the EDA_VAR_ALIGN4 and EDA_VAR_ALIGN8 EDASET variables. The desired setting of these variables will depend on the platform. For NT, a setting of 2 may suffice for all data types; for OS/400, a setting of 8 may be required.

Note: The API only checks the tuple alignment for binary fetches.

-17

Invalid user ID or password.

This status code indicates that a connect attempt was made to a secure server and that the user ID and/or password details supplied were not authorized for that server. A -17 may also occur if the user ID and password do not pass security exit checks set up on the server. Should ID and password be correct, check trace file for error code 32066. This error indicates that there is a newly coined configuration file on the server (IP_RESTRICTED) and the IP address from the client is not found.

Note: Some servers are case-sensitive.

-18

Internal API error.

This status code is one that should not occur in normal processing. It is the status code issued by the API when an event occurs that is considered impossible in normal circumstances. Examples of situations that could result in a -18 include:

A call to EDASERVERS results in a communication error (other than -7).

An attempt to free the link buffer fails.

EDAWAIT returns an invalid SCB.

A non-resource related failure to allocate memory.

A failure to process the Enhanced Query Interrupt option in EDAQUIT.

-19

Method not available.

Server capability information is requested when the API first connects to a particular server. If a particular feature is not supported, and an attempt is made to use it, the API will return a -19 and will not attempt to send the request to the server.

A -19 will also be returned if you attempt to set passthru on for an engine that is not available at the server, update a read-only engine, or return Resource Governor information when Resource Governor is not available at the server.

A -19 will also be issued if text fields are retrieved in a result set. Some servers may map a varchar data type in a relational DBMS as a text field internally. This information can be retrieved from a full API trace.

-20

Expired password.

This status code is issued if a user attempts to connect to the server and the password is expired. The application should prompt the user for a new password, which can then be passed up to the server in the EDACONNECT method call.

-21

Invalid new password.

This status code is issued if a user sends up an invalid new password in an EDACONNECT method call. A -21 status code is placed in the SCB. The application should prompt the user for an alternate password, which can then be passed up in EDACONNECT.

-22

Encryption version mismatch.

This status code indicates that the client and server are not correctly configured to work with each other.

-23

Connection no longer valid.

If connections are multiplexed and either a hard disconnect is issued on one of the connections or a communications failure is reported on one of the connections. An attempt to utilize a different SCB on the same multiplexed connection will result in a -23 error indicating that the connection is no longer available (activity on a separate SCB has reported this or resulted in this condition).

-24

Invalid Server code page.

This status code indicates that a code page has been selected at the client that is not available at the server. Check the server configuration.

-25

Statement has not been prepared (EDAEXECUTE).

This return code will be issued if an attempt to execute a previous unsuccessfully prepared statement is issued.

-26

Invalid server.

This status code will be issued if an EDACONNECT request is made to a server that either does not exist in the configuration file or is not a valid type. Valid types are CLASS=CLIENT, CLASS=CLUSTER, and CLASS=ASYNC.

-27

Invalid statement.

Will be issued if a critical error is received from the server relating to a specific statement.

-28

Invalid Unit of Work.

This status code indicates that the Unit of Work cannot be handled. This may occur if an expected message is not found in the queue. This may be caused by an application programming error or by the queues being changed outside of the control of the connector (asynchronous processing only).

-29

Invalid message attachment.

Indicates that the connector cannot add a new attachment to the Unit of Work. This may be caused because there is an error in the underlying messaging system, not enough space to add the attachment, or because the queues are being changed outside of the connector control (asynchronous processing only).

-30

Invalid protocol.

This error indicates that the protocol being used for a message is not understood. This error (and its circumstances) should be reported because it may indicate a possible bug. Supported protocols are TCP/IP, LU6.2, HTTP, and MQIS.

-31

Cannot send message.

This error indicates that the message has been read successfully but cannot be sent. This may be due to an attempted commit on an invalid Unit of Work or an error in the underlying messaging system.

-32

User ID already in use.

A user is already logged in.

-33

User resource limit reached.

Servers are defined with a maximum number of users permitted access at the same time. This number has been reached.

-34

Communications timed out.

The allotted wait time for response between servers has been reached: hub to sub.

-35

Invalid user ID.

This status code indicates that a connect attempt was made to a secure server and that the user ID details supplied were not authorized for that server. Error code -35 differs slightly from -17. Specific instances require testing for the user ID only, error code -17 applies to both the user ID or the password.

-36

Revoked user.

A connect attempt was made to a secure server and the user ID privileges for a task are no longer valid.

-37

Communications failure.

Server to server communications cannot be established.

-38

Invalid license key.

Server reports invalid license key.

-39

Invalid Metadata

Server reports invalid Metadata.

-40

Invalid Service

Server reports invalid Service name on Connect.


iWay Software