Data Structures

In this section:

Session Control Block

Information Block

Reference:

SCB Description

Work Area Format

The API uses the following data structures to transmit information back to the application program:

The session control block or statement control block.

The metadata information block.

The result set block.

The column information block.

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.

Top of page

Session Control Block

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.

Top of page

Reference: SCB Description

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#>
<thresholdexceeded>

where:

estimate

Indicates the value for a cost estimate for a particular application.

rule#

Indicates the value for the Resource Governor rule number being applied.

thresholdexceeded

Has a value of zero (0), if no threshold was exceeded.

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.

Top of page

Information Block

The Information Block (EDAINFO) describes the columns in a table or a result set.

Top of page

Reference: Work Area Format

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

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#> <thresholdexceeded> where: estimate Indicates the value for a cost estimate for a particular application. rule# Indicates the value for the Resource Governor rule number being applied. thresholdexceeded Has a value of zero (0), if no threshold was exceeded.
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.

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.