In this section: Reference: |
The API uses the following data structures to transmit information back to the application program:
The Session Control Block (SCB) is the most vital to application programs using the server. The SCB is the unit through which a server connection is managed. For more informations, see Session Control Block.
The metadata information block contains a description of a result set and is populated for all metadata requests that return a result set. For more informations, see Information Block.
The result set block represents the structure within an application that will be used to receive data requested from the server. The result set block has no fixed layout; it is dependent on the queries made by the application. For more information, see Result Set Block.
The column information block is an optional block that provides information about the row currently being processed in the result set. For more information, see Column Information.
An SCB monitors the remote execution of queries and subsequent processing of result sets. Although the SCB is defined in the user application space, the API, not the application program, maintains values in the SCB. The purpose of the SCB is to simplify the API and program interaction. The user specifies what is to be done by using the method call repertoire, and the API reports on its activities by filling in the relevant fields in the SCB. An SCB is established for each server connect request.
Each SCB contains the following information:
SCB Column Name |
Data Type |
Description |
EDA ID (EID) |
pointer |
A unique session identifier (handle) generated by the EDAINIT method call. It is moved into the SCB during the EDACONNECT call and remains unchanged throughout the session. The value is meaningful only for the duration of a single session and must not be changed by the application. In many cases, this parameter may be dealt with as long as it was in prior documentation. This works on computers where the pointer and a long are the same size, however, it does not work on OS/400 where a pointer is 16 bytes or on another anticipated 64-bit environment where there are differences in pointer size. |
Session ID (SID) |
long |
A unique identifier assigned by the API to a specific server connection. This field is initialized by EDACONNECT and remains unchanged until an EDAXCONNECT method is issued. |
Method Code |
char(12) |
Contains the name of the most recently issued API method. |
Status |
long |
Indicates the status returned by the last method call issued. 0 Represents successful completion. -n Represents fatal errors. +n Represents recoverable errors and warnings. The status field is reset by every API method possessing an SCB pointer in its calling sequence. For a complete list of possible status codes, see Status Codes. Note: The status reflects the success or failure of an API method call. It does not reflect the status of SQL processing. |
Column Count |
long |
Contains the number of columns in the result set. |
Alphanumeric Tuple Size |
long |
The size, in bytes, of a tuple or row of the result set in alphanumeric format. (See the EDAINFO method definition in Method Reference for an example of the difference between alphanumeric and binary format.) This field is reset by EDAFETCH, EDAINFO, EDANEXT, and EDATEST. |
Binary Tuple Size |
long |
The size, in bytes, of a tuple of the result set in binary format. This field is reset by EDAFETCH, EDAINFO, EDANEXT, and EDATEST. |
Count or Number of Rows Affected |
long |
Returns the row count or number of rows affected, if available. A value of -1 indicates that the row count is not known. |
Message Type |
long |
An SCB message type code. Possible values are: 0 No message. 1 Server error diagnostic. Indicates that this particular error analysis has been completed. 2 Other. 3 Internal message generated by the API, not from a server. This field reflects the message in the message text area. |
Message Origin |
char(8) |
Identifies the originator of the message. The current values are: EDA [FOC] Server errors or warnings. SMART Any statistics or messages generated from Resource Governor. XXXXXXXX Any 1-8 character code issued by a remote procedure (user-defined). See the iWay Stored Procedures Reference manual for more information. The origin field is reset when a new message is moved to the message text area. |
Message Code |
long |
A code associated with the message. For example, this could be a Remote Procedure Call return code or an error code. This field is reset when a new message is moved to the message text area. If Resource Governor is being used and the value in the Message Origin field is "SMART," the following Message Code values may display: 1 Indicates that the query has executed. 2 Indicates that the query exceeded the maximum threshold and was aborted by the server-resident Resource Governor monitor. 3 Indicates that the query was executed, but because it exceeded at least one of the established thresholds, it was more expensive than expected. That is, the query executed the lower resource limit established by the Resource Governor. |
Message Text |
char(136) |
The maximum length of text in this field is 132 characters, followed by a null terminator. The value is padded out to a word boundary of 136 bytes. This field is overwritten when EDAACCEPT, EDANEXT, EDATEST, or EDAFETCH is invoked. If Resource Governor is being used and the value in the Message Origin field is "SMART," a statement in the following format may display in the Message Text field. (SMARTnn)<estimate><rule#> where:
|
Message Length |
long |
Is the size of the message text. The maximum value of this field is 132. This field changes when EDAACCEPT, EDANEXT, EDATEST, or EDAFETCH is invoked. |
Message Pending |
long |
The following values indicate the status of messages: 0 No additional messages. 1 One or more messages are waiting to be processed. An EDAACCEPT will process the next awaiting message. This field changes when EDAACCEPT, EDANEXT, or EDAFETCH is invoked. |
Message Overflow |
long |
A true/false indicator. 0 No overflow. 1 The queue depth has been exceeded; some messages have been lost. The message queue depth is limited either by available memory or, if the application program sets the Queue Depth variable, to a specific number. This field is reset when the API makes the transition from active to processing states; it is also reset when the system accesses the next tuple in a result set. |
User Area |
char(8) |
An area reserved for the user (user-defined). Writable by the application and not maintained by the API. Users should avoid using this area because it may not be supported in a future release. |
Parm_count |
char |
Returns the number of value positions to the SCB when using an EDAPREPARE statement. |
Reserved |
char |
Reserved for future use. |
Xopen |
char(6) |
The standard Xopen code for the current operation. |
The Information Block (EDAINFO) describes the columns in a table or a result set.
Item Name |
Data Type |
Description |
Column Name |
char(68) |
The name of the designated column; a null-terminated character string. |
Column Length |
long |
The length of the column name field. |
Column Number |
long |
The position of the column in the result set. |
Alias |
char(68) |
For internal use only. |
Alias Length |
long |
For internal use only. |
Type |
long |
The data type of the column. See on page for the definition of data type codes. |
Alpha Length |
long |
The alpha length of the column in bytes. This is the length of the column when EDAFETCH and EDAFIELD are issued and the alpha format indication is set. This is used if the fetch type is alpha. |
Decimal Precision |
long |
The number of decimal places to the right of the decimal point (for example, scale). This field applies only to packed-decimal, floating-point, and double-precision floating-point numbers. |
Editing Options |
char(8) |
Defines the editing options for the column in date fields only. |
Binary Length |
long |
The binary length of the column in bytes; this value includes one position for sign (if numerical) and one position for decimal (if packed double-precision format). This is used if the fetch type is binary. |
Alpha Offset |
long |
The offset of the referenced column in the alphanumeric form of the tuple. This is used if the fetch type is alpha. |
Binary Offset |
long |
The offset of the referenced column in the binary form of the tuple. This is used if the fetch type is binary. |
Can Be Null |
long |
Indicates whether the designated column can contain null values: 1 True. 0 False. |
User Area |
char(16) |
Area reserved for the user (user-defined). Users are cautioned that this area may be eliminated in future releases of the API. |
iWay Software |