Valid Setting Codes and Variables

The following table summarizes the setting codes that may be used in the EDASET and EDAINSPECT method calls. The following applies:

• Variable names start with EDA_VAR_.
• Most variables can be inspected using EDAINSPECT.
• Variables that can be set are set using EDASET.

Code	Description	Local/ Global	Variable Name	Settable	Reference
0	Database Engine	L	EDA_VAR_ ENGINE	Yes	Database Engine Settings.
1	Output Format	L	EDA_VAR_ FORMAT	Yes	Output Format.
2	Major Version	G	EDA_VAR_MAJOR	No	API Version.
3	Minor Version	G	EDA_VAR_MINOR	No	API Version.
5	Trace Mode	G	EDA_VAR_TRACE	Yes	Tracing.
10	Read Limit	L	EDA_VAR_ READLIMIT	Yes	Read, Record, and Output Limit.
11	Record Limit	L	EDA_VAR_ RECLIMIT	Yes	Read, Record, and Output Limit.
12	All	L	EDA_VAR_ALL	Yes	ALL.
13	Resource Governor	L	EDA_VAR_ SMARTMODE	Yes	Resource Governor.
14	Message Queue Depth	G	EDA_VAR_ QDEPTH	Yes	Message Queue Depth.
15	Auto Purge	L	EDA_VAR_ AUTOPURGE	Yes	Auto Purge.
16	Auto Commit	G	EDA_VAR_ AUTOCOMMIT	Yes	Auto Commit.
18	Server Count	G	EDA_VAR_ SERVERCOUNT	No	Server Count.
19	Quit All	L	EDA_VAR_QUIT_ ALL	Yes	Quit All.
20	Hard Disconnect	G	EDA_VAR_HARD_ DISCONNECT	Yes	Hard Disconnect.
22	SLIM Setting	G/L	EDA_VAR_SLIM_ VALUE	Yes	SLIM.
26	Attachment Name	L	EDA_VAR_ATT_ NAME	No	Attachment Name.
27	Attachment Class	L	EDA_VAR_ATT_ CLASS	No	Attachment Class.
28	Prealloc	L	EDA_VAR_ PREALLOC	Yes	Prealloc.
29	Quit Break	L	EDA_VAR_QUIT_ BREAK	Yes	Quit Break.
30	Server Name	L	EDA_VAR_ SERVER_NAME	Yes	Server Name.
31	Node Information	L	EDA_VAR_NODE_ INFO	Yes	Node Information.
32	Hold File	L	EDA_VAR_HOLD_ FILE	Yes	Hold File
33	As File	L	EDA_VAR_AS_ FILE	Yes	As File
34	Found	L	EDA_VAR_IWAY_ FOUND	Yes	Found.
35	Path	L	EDA_VAR_IWAY_ PATH	Yes	Path.
36	Step Version	L	EDA_VAR_STEP	Yes	API Version.
37	Message List		EDA_VAR_ MSGLIST
120	Alignment Variables	G	EDA_VAR_ ALIGN4	Yes	Alignment Variables.
121	Alignment Variables	G	EDA_VAR_ ALIGN8	Yes	Alignment Variables.
122	SET XRETRIEVAL ON/OFF	L	EDA_VAR_ XRETRIEVE	Yes	XRETRIEVAL.
123	Inspect for CD Notation Support	L	EDA_VAR_ CDNOTATION	No	Continental Decimal Notation.
124	Inspect for DBCS Support	L	EDA_VAR_ DBCSCHECK	No	Double-Byte Character Support.
125	Inspect for Server Major Release Number	L	EDA_VAR_ SERVEMAJOR	No	Major Release Level of the Server.
126	Inspect for Server Minor Release Number	L	EDA_VAR_ SERVEMINOR	No	Minor Release Level of the Server.
127	Set Multiplexing OFF	G	EDA_VAR_NO_ MPLEX	Yes	Multiplexing.
128	Full Duplex		EDA_VAR_ FULLDUPLEX
129	Query ID		EDA_VAR_ QUERY_ID
130	Subquery ID		EDA_VAR_ SUBQUERY_ID
132	Server Capability Information	G	EDA_VAR_NO_ CATALOG	Yes	Server Capability Information.
134	Service Name		EDA_VAR_ SERVICE_NAME
136	Inspect for Default Engine	L	EDA_VAR_ DEFAULT_ ENGINE	No	Inspect for Default Engine.
137	Engine Release		EDA_VAR_ ENGINE_REL
139	Set to Turn OFF Filtering of Messages	L	EDA_VAR_ NOFILTER_MSGS	Yes	Message Filtering.
140	Start up		EDA_VAR_ STARTUP
141	Close		EDA_VAR_ CLOSEDOWN
147	Alternate Memory Allocation Scheme	G	EDA_VAR_NO_ FRAGMENT	Yes	Alternate Memory Allocation.
148	ColInfo Array Pointer	L	EDA_VAR_ COLINFO_PTR	Yes	ColInfo Array Pointer.
149	ColInfo Array Size	L	EDA_VAR_ COLINFO_SIZE
150	Retrieve SCB Type	L	EDA_VAR_ SCBTYPE	No	Retrieve SCB Type.
151	Trace State Table Transition Information	G	EDA_VAR_ STATE_TRACE	Yes	Trace State Table Transition Information.
152			EDA_VAR_ NOSIGVER
153	Application Debugging Trace	G	EDA_VAR_LOG	Yes	Application Traces.
154	Communication Timing Control (Time Out)	G	EDA_VAR_ RCVTIME	Yes	Communication Timing Control (Timeout).
155	Trace ID	G	EDA_VAR_LOGID	Yes	Trace ID.
156	Link ID		EDA_VAR_ LINKID
157	Link Handle		EDA_VAR_ LINKHDL
158	Save Area of Memory	G	EDA_VAR_ USERAREA	Yes	Save Area of Memory.
159	Set Passivating	L	EDA_VAR_ PASSIVATE	Yes	Set Passivating.
160	To Passivate	L	EDA_VAR_CAN_ PASSIVATE	Yes	To Passivate.
161	Extended Security Messages	G	EDA_VAR_ EXTENDSEC	Yes	Extended Security Messages.
162	XA Switch		EDA_VAR_ XASWITCH
163			EDA_VAR_ NLSCTX
303	Retrieve Last Unit of Work (UOW) ID	L	EDA_VAR_ASYID	No	Retrieve Last Unit of Work (UOW) ID.
304	No Block Mode	L	EDA_VAR_NO_ BLOCK	Yes	No Block Mode.
305	Thread Safety		EDA_VAR_ AUTOLOCK

Database Engine Settings

The EDA database engine variable, variable 0, controls how SQL requests are handled against the given SCB. If the variable setting is zero (0), which indicates NOENGINE, then the server invokes the SQL Translator to process SQL requests (except for Relational Gateways; servers configured as Relational Gateways do not use SQL Translation).

If the variable is not zero (0), the server routes SQL requests directly to the specified native DBMS for processing. The SQL engine that receives calls using this mechanism is indicated by the database engine variable.

Reference: Settings for Relational DBMSs

A chart of permissible settings for relational DBMSs follows:

Variable Setting	Database Engine
0	EDA
1	DB2
2	Oracle
3	Teradata
4	SQL/DS
5	Sharebase
6	Microsoft SQL Server
7	Supra
8	Ingres
9	Sybase
10	RDB
11	Informix
12	Unify
13	EDA (Internal)
14	DB2/2 or DBM
15	SQL400
16	NonStop SQL
17	Allbase
18	Progress
19	Red Brick
20	UniVerse
21	Datacom
22	InfoAccess
23	IDMS
24	STORHOUSE
25	ODBC
26	MSQ
27	Nucleus
28	MS Access
29	MYSQL

EDASET constrains all database engine assignments to the above values (or currently defined engine codes), but does no error checking. Should the application program specify an engine that is inaccessible to the server, the API will return a -19 status code.

The SQL received by the server for a single RDBMS will be subject to dialect translation. The SQL will be passed through directly to the RDBMS if the RDBMS is known to support the SQL syntax unchanged. Certain SQL clauses will be manipulated into a format supported by the RDBMS if the SQL is not supported in the form passed from the client. Complete SQL translation will take place only if the SQL contains constructs that require translation to Data Manipulation Language (DML). The need for a direct passthru setting at the client is therefore less likely for connections to a server.

Note: To retrieve a list of currently available engines within an application, use EDABROWSE. For details, see Method Reference.

Output Format

The API provides several output formats. The user requiring special formatting must set the output format variable, variable 1, to a non-zero value.

Reference: Output Format Settings

The following settings indicate output formats:

Variable Setting	Output Format
0	ALPHA (This is the default HOLD FILE format, which returns rows in a fixed, alpha format.)
1	DIF
2	LOTUS PRN
3	SYLK
4	IXF
5	HTML
6	Excel
7	WP
8	DOC
9	Binary
10	Post SC (postscript)
11	PS
12	HTMTAB
13	Comma
14	GIF
15	BMP
16	FXF
17	Viewer
18	Chip
19	RTF
20	PDF
21	EXL4
22	EXL2K
23	Notes

Note:

• Output formats other than zero (0) cause the entire row to be treated as a single column. Only one EDAINFO column description will be available.
• The server determines support of a particular output format.
• The appropriate server licenses are required to use these options.

API Version

Each copy of the API has an associated major, minor, and step version number. Versions of the API differ functionally from their immediate predecessor. Versions may contain new method calls as well as new or augmented data structures.

An application program may determine whether it is running under the control of an appropriate API by using an EDAINSPECT method call to read the version number. As an example, use of eda_var_major, eda_var_minor, and eda_var_step may produce 7.0.1 as your current release.

Note:

• The information contained in these variables applies to the API, not to the server or any other component of the server.
• Version information is read-only; you are not permitted to assign new values to version settings.

Tracing

Reference: Trace Mode Settings ODIN Levels: Communication Tracing

The trace mode and other tracing variables are used in conjunction with EDACALLBACK to control tracing from within the application. The setting values are 1 for ON and 0 for OFF.

Note: A default API trace provided with each connector can be used to output all trace information. The variables below are only required when the application controls tracing itself. For information on how to start the default Trace Tool, see Tracing.

Reference: Trace Mode Settings

Setting	Variable Name	Trace Description
5	EDA_VAR_TRACE	Used to set tracing levels ON or OFF. Used to enable tracing.
6	EDA_VAR_TRACE_LVL1	Trace level 1. API entry/exit method calls. API Calls Entry/Exit and User Log (399). This trace level displays each entry to and exit from an API command and the parameter values processed. These calls are a result of the commands sent by the client application, as well as those called internally by the API.
7	EDA_VAR_TRACE_LVL2	Trace level 2. Application communication. Locking and Internal Flow. This trace level records communication calls made by an API client to the server and the status of these communication events as recorded by the API.
8	EDA_VAR_TRACE_LVL3	Trace level 3. Events such as SCB allocation. Errors. This trace level records API internal events.
9	EDA_VAR_TRACE_LVL4	Trace level 4. Represents internal API call sequences. Messages from EDASET. Results from EDASET commands.
151	EDA_VAR_STATE_TRACE	Trace State Table transition information.
153	EDA_VAR_VAR_LOG	Application tracing. See Application Traces.
12272	EDA_VAR_TRACE_LVL5	Trace level 5. Data to server. This trace level displays the data sent to the server in addition to the SQL being passed from the client.
12273	EDA_VAR_TRACE_LVL6	Trace level 6. Data from server. This trace level displays data entries being received by the client. This can be useful in determining whether the client is receiving the correct data.
12274	EDA_VAR_TRACE_LVL7	Trace level 7. API communication events such as memory allocation. Internal Logic including memory allocations. This trace level displays internal event tracing. Events such as memory allocation, spooling, and the receipt of Info Blocks are displayed at this level.
12275	EDA_VAR_TRACE_LVL8	Trace level 8. Communication detail. API use of communications. This permits communications trace messages that are further defined in ODIN Levels: Communication Tracing
12282	EDA_VAR_TRACE_DEF	Trace levels 1-6 and ODIN levels 1-3.

Reference: ODIN Levels: Communication Tracing

Setting	Variable Name	Trace Description
12277	EDA_VAR_ODIN_LVL1	Errors.
12278	EDA_VAR_ODIN_LVL2	Warnings.
12279	EDA_VAR_ODIN_LVL3	Information.
12280	EDA_VAR_ODIN_LVL4	Reserved for future use.
12281	EDA_VAR_ODIN_LVL5	Buffer Dump. This is extremely voluminous, and should not be used for normal situations.

Trace State Table Transition Information

The variable EDA_VAR_STATE_TRACE (151) enables the API's trace to include additional State Table transition information. Usually you will need this setting only when requested by software support.

Trace ID

Trace ID can contain a maximum of five (5) characters. You will use this feature when you need to differentiate activity on different contexts within the same output file.

Application Traces

The variable EDA_VAR_LOG (153) allows a user application to write up to 120 characters to the trace stream. This facility is provided to assist applications being debugged in environments that contain no application-level trace output. For example, CALLPGM applications may wish to use this service to put their debugging traces into the default trace displays.

Example: Writing to the Trace Stream (C Example)

long variable=EDA_VAR_LOG;
long result;
EDASET(&eid,NULL,&variable,"this is a trace line",&result);

Note: There is no equivalent EDAINSPECT.

Read, Record, and Output Limit

Variables 10 and 11, which are read and record limit variables, are used to constrain the volume of data processed and may be assigned any positive integral value.

Reference: Read and Record Limit Variables

10 EDA_VAR_READLIMIT	Sets the maximum number of rows to be read from a table by the server.
11 EDA_VAR_RECLIMIT	Sets the maximum number of rows to be retrieved by the server from a table.

Initially, both variables are set to zero (0), indicating no interest on the part of the application program. However, if:

• Read limit is "n" (n > 0) at the time a method call is issued, the API will instruct the server to read no more than "n" records in the course of processing.
• Record limit is "m" (m > 0), the API will instruct the server to return no more than "m" rows in the result set.

Output limit is substituted for record limit if the server supports the output limit variable. The output limit variable is a more reliable limit than the record limit because it is imposed by the server on output rows to ensure that only the number of rows specified by the variable is returned. See the iWay Server Administration manual for your specific platform for more information.

Note: Read limit does not apply to FOCUS data sources.

ALL

Example: Setting ALL to ON Setting ALL to OFF Reference: ALL Variable Settings

You can use the ALL variable, EDA_VAR_ALL (12), to customize the retrieval plan for requests against multi-segment hierarchical data sources or multiple tables.

Note: The retrieval plans can now be better accomplished by using SQL outer and inner joins.

Reference: ALL Variable Settings

Variable Setting	Mode
1	ON
0	OFF

Example: Setting ALL to ON

When the ALL variable is set to ON, it indicates that all rows should be retrieved for the request, regardless of whether values exist for the complete row. (Retrieval will include parent values even if there is no corresponding child in the joined table or segment.)

If a request includes columns for employees and columns for courses that employees have attended, and if ALL is set to ON, the request will return all employees regardless of whether they have attended a course.

In the above scenario, if you issued the statement

SELECT EMPLOYEE, COURSE FROM EMPSTUFF;

Calvin and Hobbes display in the result set, even though Hobbes did not attend any courses.

Example: Setting ALL to OFF

When the ALL variable is set to OFF, rows will be retrieved only where instances exist for each of the segments or tables identified in the request. In the above example, therefore, only Calvin would display in the result set. OFF is the default for this setting.

Note: This setting is applicable to missing segments or instances. It does not apply to null values within a segment, table, or instance.

Resource Governor

The Resource Governor variable, EDA_VAR_SMARTMODE (13), causes the estimate for a query from Resource Governor to be written to the row count field in the SCB. This makes the value available to the application so that it may be analyzed before further processing.

The application can access the estimate cost of query execution and act on this information. When the Resource Governor monitor is present, it interrupts the normal flow of operation immediately before a query is executed. It then develops an estimated cost of the query based on past performance data. Finally, the monitor suppresses query execution if its estimate exceeds a threshold value. It also generates, as a by-product, cost estimate reports that can be accessed by the API application programs.

Example: Obtaining Cost Estimate Reports

To obtain cost estimate reports, set the Resource Governor variable-variable 13-to 1. Thereafter, the server will generate a message in the Message Text of the SCB in the form

(SMARTnn)<estimate><confidence><threshold>

whenever it actually attempts to execute a query. (The system rejects all queries containing syntax or semantic errors.)

The output format guarantees that when a Resource Governor report reaches the head of the message queue, the relevant SCB will contain "SMART" in the Message Origin field. A numeric value will display in the Message Code field:

1	Indicates that the query in question executed.
2	Indicates that the server-resident Resource Governor monitor aborted the query.

It is the programmer's responsibility to interpret the text of the message, which will consist of three integers separated by one or more spaces.

The first integer in the text of a Resource Governor message is an estimate. The second integer is a measure of the confidence the system has in that estimate (0-100). The third integer is the threshold value used to suppress query execution. See the Resource Governor and Resource Analyzer chapter in the iWay Server Administration manual and the Resource Governor/Resource Analyzer chapter in the configuration manual for your server platform.

Message Queue Depth

The API queues messages whenever a data access method call scans the output stream for something to process. Initially, there is no explicit limit placed on how many messages can be queued at a time. However, a limit can be imposed by setting the Message Queue Depth variable, EDA_VAR_QDEPTH (14). This variable allows the application to set a maximum limit to the number of messages that will be held in the message queue.

For example, the Message Queue Depth is three (3) and the server has returned a result set preceded by seven (7) messages. When it scans for the first tuple in the result set, the API will queue the first three (3) messages it encounters and discard the remaining four (4) before returning to the instruction following the user's EDAFETCH.

The initial Message Queue Depth is zero (0), which indicates no explicit limit. It is possible that the server will assemble more consecutive messages than can be accommodated in the memory available to the API. In this scenario, the queue depth variable may be set to omit queuing of unnecessary messages, or to avoid reaching the memory limit on clients where available memory is limited.

This setting is designed for use in situations in which memory is limited. In virtual memory machines or machines with large available memory, use of this setting is discouraged.

Auto Purge

Under normal (default) circumstances, the API automatically purges the message queue when an EDAFETCH or an EDANEXT is issued. To override this feature, set the Auto Purge variable, EDA_VAR_AUTOPURGE (15), to zero (0).

Note: This variable is initially set to one (1).

Auto Commit

Auto Commit, EDA_VAR_AUTOCOMMIT (16), is a two-value variable.

Reference: Auto Commit Variable Settings

The following table lists the value settings for Auto Commit.

Variable	Mode
1	ON
0	OFF

If Auto Commit is set to ON in an environment that supports it, the API will then send an SQL COMMIT WORK after each transaction. If the application extends the length of the transaction and controls its own transaction processing, the Auto Commit behavior is set to OFF. This can be achieved by setting the Auto Commit variable to zero (0), using EDASET.

When Auto Commit is set to OFF, you must issue an explicit EDACOMMIT (or EDASQL with COMMIT WORK), to commit transactions and release outstanding table or record locks.

With Auto Commit OFF, it is possible to execute a prepared SQL INSERT, UPDATE, or DELETE request with a batch of parameter lists assembled by means of the EDAUSING method call. This allows multiple inserts, updates, and/or deletes within a single unit of work that can be committed or rolled back.

Failure to commit frequently can degrade system performance by causing contention between concurrently executing database users. The ability to initiate transactions of arbitrary duration should be used with caution.

Auto Commit is not a relevant setting for messaging or transaction adapters.

Server Count

When the API is initialized, it establishes how many synchronous servers may be accessed from this node in the network and sets the Server Count variable, EDA_VAR_SERVERCOUNT (18), accordingly. Server Count is a read-only variable, which is intended for use in conjunction with the EDASERVERS method call.

An EDAINSPECT for the number of accessible servers will return the number of synchronous server names to the application. This allows the application, using EDASERVERS, to set an appropriately sized buffer for the display of available server names. For more information on the EDASERVERS method call, see Method Reference

Since EDASERVERS returns only the names of synchronous servers, users may wish to use the appropriate EDABROWSE to obtain information about all defined servers.

Quit All

The Quit All variable, EDA_VAR_QUIT_ALL (19), is used to control the behavior of EDAQUIT. When Quit All is zero (0), EDAQUIT moves to the next result set (if any) in the output stream and returns to the caller. If Quit All is one (1), EDAQUIT eliminates the entire server result stream before returning. Quit All is reset to its default value of zero (0) following every execution of EDAQUIT. For more information on the EDAQUIT method call, see Method Reference.

Hard Disconnect

Setting this variable, EDA_VAR_HARD_DISCONNECT (20), to ON causes the next subsequent EDAXCONNECT from the API application to sever all communication lines to a particular server, along with any pending data.

Hard Disconnect enables the application to continue without having to wait for any requested data to be returned to the client, but the application must reconnect to the desired server before being able to process any further result sets. If there are multiple SCBs multiplexed to the same server connection, all of these SCBs will be abruptly disconnected. Therefore, the application developer should take care when setting this option.

Alternatively, advanced result set management options are available within the server. However, users are strongly discouraged from using this service.

These include:

• Controlled Data Transfer
• Query Interrupt

The Controlled Data Transfer setting enables the user to limit the amount of data returned to the client (see SLIM). Use of Query Interrupt will enable a particular server task to be canceled. (For more information, see Advanced Usage Considerations.) Use of these settings should eliminate the need for a Hard Disconnect.

SLIM

Setting this variable, EDA_VAR_SLIM (22), enables the user to override the SLIM set on the server. The setting is used to control the amount of data that will be transferred to the client at one time before allowing a server interrupt to occur.

When a connection is made to a server, the server informs the API of the default SLIM. The EDA_VAR_SLIM variable can be inspected (using EDAINSPECT) by the application to retrieve this value. Based on inspection, or on specific application requirements, this value can be changed using EDASET. Changing this value to zero (0) will prevent subsequent requests from utilizing the Controlled Data Transfer protocol. Changing it to a value greater than zero (0) will cause the API to utilize the new value to determine how many records are retrieved from the server at one time. This value, when greater than zero (0), will form the limit to the number of records that will be returned to the client for a single fetch request. Setting the value to -1 will return the SLIM to the server default.

The EDASET for EDA_VAR_SLIM can be local or global. To set it locally, a valid SCB must be passed to EDASET. The setting will then take effect for transactions on that SCB only. If a null value is passed in the SCB parameter, the setting will become global and will take effect for all subsequent transactions on all SCBs.

SLIM enables Controlled Data Transfer. For more detail, see Advanced Usage Considerations.

Note: SLIM must be set to retrieve LOB (Large Object) data types from the server. In the absence of a server setting, an EDASET for EDA_VAR_SLIM (22) to a value greater than zero (0) should be deployed before attempting to retrieve LOB data.

Attachment Name

The EDA_VAR_ATT_NAME (26) variable can be inspected to provide the name of the current result set. This will reflect the name of the result set downloaded from the server. For prepared statements, it will be the prepare name; for non-prepared statements using Controlled Data Transfer, the statement identifier name will be returned. Otherwise, it will reflect either the name of the HOLD file created from an RPC or it will contain "HOLD" as the result set name for SQL statements that do not utilize Controlled Data Transfer.

For Direct Passthru requests without Controlled Data Transfer enabled, a name of SQLOUT will be returned.

The attachment name will be available after the first request that actually retrieves data from the server (for example, using EDAINFO, EDATEST that returns a wait_ind of zero (0), or EDAFETCH). A name will only be available if a result set is returned (even when the result set is empty).

The attachment name variable returns an eight (8) character, blank padded field at the location specified by the variable parameter. Operations that do not initiate data retrieval will not return an attachment name.

Attachment Class

The EDA_VAR_ATT_CLASS (27) variable can be inspected to provide the current result set type. For EDASQL and EDAEXECUTE, the answer type will be "MAS." However, by using EDARPC, non-standard result sets may be produced (such as those in HTML format, in which case the attachment class will contain an "HTM").

As with an attachment name, the attachment class will be available after the first request that retrieves data from the server (as long as a result set exists). An attachment class will only be available if a result set is returned.

The attachment class variable returns a three (3) character, blank padded field at the location specified by the variable parameter. Operations that do not initiate data retrieval will not return an attachment class.

Alignment Variables

EDA_VAR_ALIGN4 (120) and EDA_VAR _ ALIGN8 (121) enable the user to set alternate boundary checks.

For binary retrieval of data, the EDA_VAR_ALIGN4 and EDA_VAR_ALIGN8 variables specify the boundary size for API alignment checking. The EDA_VAR_ALIGN4 specifies the default boundary check for integer and float data types. The EDA_VAR_ALIGN8 specifies the default boundary check for double and decimal data types. These values are set to 4 and 8 by default, which is appropriate for most client platforms. If they are changed, the API will check the new alignment setting for the specified data type.

For example, on the NT platform, binary alignment of only 2 bytes may be preferable; however, on OS/400, an alignment setting of 8 may be preferable. If the client application attempts to retrieve data in binary format to a buffer that is not aligned on an appropriate boundary, an EDA_TUPLE_MISALIGN (-16) error will be returned. RISC machines are very sensitive to boundary alignments and may require adjustment to environment variables.

XRETRIEVAL

When the variable, EDA_VAR_XRETRIEVE (122), is set to one (1), it sends a method call to the server that will allow a request to be processed, but will not return any data. The file description will be returned to the server for inspection using EDAINFO, but no data will be returned. The default value for this is zero (0).

Most programmers prefer to use EDAPREPARE for this purpose.

Continental Decimal Notation

The Continental Decimal Notation (CDN) variable, EDA_VAR_CDNOTATION (123), indicates whether or not the server is expecting Continental (comma-delimited) Decimal Notation. However, note that conversion to CDN is the responsibility of the application. If the value of this variable is one (1), the server expects its input in comma-delimited notation, and will return its output in a comma-delimited format. This is a local variable.

Reference: Method Calls Affected by CDN Setting

The following table lists the method calls affected by this server setting (conversion to CDN is the responsibility of the application):

Method Call	Affects
EDASQL	Query contents.
EDAPREPARE	Query contents.
EDAUSING	Parameter values.
EDAFETCH	Fetching ALPHA formats and numbers.
EDAFIELD	Fetching ALPHA formats and numbers.

Double-Byte Character Support

The EDAINSPECT variable, EDA_VAR_DBCSCHECK (124), enables the application to find out if Double-Byte Character Support (DBCS) is available at the server.

Major Release Level of the Server

The server Major Release variable, EDA_VAR_SERVEMAJOR (125), returns the major release level of the server. This, in conjunction with the minor release level, can be useful in determining the availability of certain methods at the server (for example, Controlled Data Transfer support).

Minor Release Level of the Server

The server Minor Release variable, EDA_VAR_SERVEMINOR (126), returns the minor release level of the server and can be used in conjunction with the above setting to determine whether certain methods are available.

Multiplexing

The API, by default, will multiplex connections to the same server. The first EDACONNECT request to the server will establish a real, physical connection with the server and initiate a process. Subsequent connections to the same server will utilize the same physical connection and server process. This behavior can be turned off using EDASET with EDA_VAR_NO_MPLEX (127).

Users are cautioned that connections to multiplexed servers share in a single unit of work. A commit on any one will affect all. This can cause unexpected application results. Controlled multiplexing can be established by use of the semiplex option of EDACONNECT.

Using this setting may require substantially more resources at the server, so its effect should be carefully analyzed before deployment.

You must set this variable to OFF to utilize the user multiplexing feature. For further information, see Advanced Usage Considerations.

Server Capability Information

When an API connects to a server for the first time, it executes a request to query server capability information. This request returns a table to the API with capability information that the API then uses to populate certain variables mentioned above. This information also allows the API to refuse inappropriate requests to the server before sending the request through. If server capability information is not required (this includes SLIM, case sensitivity, LOB support, and Query Interrupt), the EDA_VAR_NO_CATALOG (132) may be used to suppress this interchange. This causes the API to assume default values appropriate for a basic server.

Turning on this variable improves initial connect time and may cause the API not to establish whether a connect attempt was successful until the first true request is sent from the client. Use of this setting may also render certain server capabilities unusable and, as such, should be used with extreme caution.

Note: Future releases may not support this ability.

Message Filtering

By default, the API filters a number of messages sent by the server. This reduces the number of unnecessary messages delivered to the client. The EDA_VAR_NOFILTER_MSGS (139) variable turns off this filtering. This feature is for very specific application requirements and is not recommended for general use.

Inspect for Default Engine

The EDAINSPECT variable, EDA_VAR_DEFAULT_ENGINE (136), returns the default engine setting at the server. This is useful for identifying a Relational Gateway. A DB2 Relational Gateway, for example, returns a value of one (1) for DB2.

Alternate Memory Allocation

Turning on this setting, EDA_VAR_NO_FRAGMENT (147), causes the API to reuse memory where possible, instead of freeing and reallocating memory (which may lead to fragmentation). Use of this setting is generally recommended.

Freeing and reallocating memory can cause the API to use less memory. For example, if an application requires a large amount of memory up-front, setting this variable to one (1) will cause the memory not to be freed. Doing so may therefore increase the total memory usage throughout the application.

ColInfo Array Pointer

Variable EDA_VAR_COLINFO_PTR (148) provides the API with an address at which to store column value information for use with LOB data types and null data values. This is set before EDAFETCH or EDANEXT. For more information, see API Data Structures.

Retrieve SCB Type

The SCB type inspect setting, EDA_VAR_SCBTYPE (150), can be used to determine the type of SCB being used.

Reference: SCB Types

The following table lists SCB types:

SCB Type	Description
-1	SCB type unknown.
1	SCB represents a synchronous connection.
2	SCB represents an asynchronous connection.
3	SCB represents a connection to the API only (connection to SELF).
4	SCB represents a connection to an asynchronous executor.
5	N/A
6	N/A
7	Transaction adapter.
8	Cluster node.

Communication Timing Control (Timeout)

EDA_VAR_RCVTIME controls the amount of time (in seconds) to wait for a communication event. Only the query time is supported with EDASET.

Syntax: How to Control Wait Time

MAXWAIT=query [, row]

where:

query

Is the time allowed for the initial query response (time to the first row).

row

Is the time allowed between rows.

Note:

• If <row> is omitted, the <query> time applies to both. The time is in units of seconds, unless the number ends with the character m, in which case the time is in minutes.
• MAXWAIT is the wait time for the first row [subsequent row] in milliseconds, with the supported suffixes, m and s, for minutes and seconds.
• The time allowed between rows is the same as the time allowed for the initial query response. Alternatively, the keyword, MAXWAIT, can be used in the node block of the communication configuration file (ODIN.CFG) to control the wait time allowed for a server to respond to the client.

Example: Setting Wait Time in the Communication Configuration File

MAXWAIT = 5m, 10s

Allows five (5) minutes to the first row and 10 seconds between rows.

Save Area of Memory

Associated with the new EDASET variable, USERAREA (158) enables an application to store information into the EDA_ID, which can be retrieved using EDAINSPECT. You are encouraged to store or assign a pointer to your own context information here, making this data available to callback routines. The callback block contains the EDA_ID for which the callback is being made.

Set Passivating

In the API, the API application controls when the server passivates. An API application only passivates after completing the statement request. For example, if an SQL SELECT statement is issued, the application cannot passivate until the transaction completes fetching to the end of the set or an EDAQUIT is submitted. An error occurs when the server passivates out of state. For applications using the EDAPREPARE, passivating cannot take place unless an EDAXPREPARE is issued. Since PREPAREs are stored on the server and passivating destroys the server resources, the PREPARE is no longer available when the application reconnects. The application signals the server to passivate through the EDASET variable PASSIVATE (159) with one (1) for YES and zero (0) for NO.

Note: Passivating should be used in conjunction with commit and rollback.

To Passivate

When a client does not need to maintain a persistent connection to a server, the client application can automatically disconnect and reconnect to a server, without explicitly issuing disconnect and connect statements.

Syntax: How to Activate the Passivating Connection Option

In the API, set the EDASET variable CAN_PASSIVATE (160) to one (1) for Yes and zero (0) for No.

Extended Security Messages

Activation of extended security is performed by issuing EDASET with a setting of EXTENDSEC (161) and a value of 1.

Reference: Extended Security Error Codes

Code	Description
-17	Invalid Password
-35	Bad User ID
-36	Revoked User ID

Retrieve Last Unit of Work (UOW) ID

Variable EDA_VAR_ASYID (303) returns a Unit of Work ID for the last Unit of Work.

An asynchronous setting is available.

No Block Mode

Variable EDA_VAR_NO_BLOCK (304) causes the API to return immediately from a method call with a status indicating whether the method has completed. This provides effective use of the API in an asynchronous manner within a session context. That is, an application can make a call to the API, expect an immediate return and, then process other tasks before returning to see if the method call has completed. For example, the application may execute an EDAINFO method. With No Block Mode set ON, the API will return from the call immediately. Any subsequent call to EDAINFO on the same SCB will cause the API to either return with an EDA_SUCCESS, indicating that results may be ready for processing, or with an EDA_STILL_EXECUTING, indicating that results are not yet ready for processing.

Prealloc

Variable EDA_VAR_PREALLOC (28) is used as follows: issuing an EDAINSPECT with this variable returns you the value for prealloc (if any) assigned in the communications configuration file. The setting of EDA_VAR_PREALLOC creates a value that will override the inspected value for a single RPC request. This feature is for transaction-type servers only.

Quit Break

Variable EDA_VAR_QUIT_BREAK forces a heavy quit on the next quit done, either explicitly by the user or internally as part of some other function.

Server Name

Variable EDA_VAR_SERVER_NAME is used to determine the specific server connection when using cluster nodes.

Note: The use of EDABROWSE will provide a list of nodes defined in the communication configuration file (a cluster node may be one of these nodes).

Node Information

Variable EDA_VAR_NODE_INFO provides the values contained in keywords within the communication configuration file. Set the EDAINSPECT setting to EDA_VAR_NODE_INFO; then, in the value parameter, pass the node name and keyword you want to interrogate. The information you request will be returned in the value parameter.

Hold File

Variable EDA_VAR_HOLD_FILE is for internal use.

As File

Variable EDA_VAR_AS_FILE is for internal use.

Found

The EDA_VAR_IWAY_FOUND variable is set on if an iway.cfg file exists in the same directory as the edaapi. The file is created and maintained by the configurator. It is a hidden file; therefore, the only way for the user/application to know of its existence is to check this variable. If the file exists, then only the information in this file will be considered as valid paths to the communication configuration file, odin.cfg. The paths may be registry entries or URLs.

Path

The variable EDA_VAR_IWAY_PATH returns the URL address where the API has detected the location of the communication configuration file, odin.cfg, or the path uncovered in the registry entry. The iway.cfg file is read by the API until it successfully finds a registry entry or valid URL node, or reaches the end of the file. It is conceivable that this variable could be empty, even if the iway.cfg found variable is set, if all the paths in the file point to invalid entries.

The path variable means different things depending on whether it's pointing to a registry entry or a URL. If it's a registry entry, it behaves exactly like EDACS3, meaning when the iway.cfg file is read (before any attempt is made to communicate with an actual server), it stores the local path found in the registry, without verifying that the path points to an actual file. If the path is a URL address, then when the iway.cfg file is read in, the API confirms the existence of the remote odin.cfg, and the user is guaranteed that the communication configuration file has been successfully read into local storage as soon as the populated path variable is returned.