API Method Calls

The following table summarizes the API method calls:

API Method Call	Function	Syntax
EDAACCEPT	Accessing queued messages from a server.	EDAACCEPT (scb)
EDABROWSE	Displaying or manipulating data.	EDABROWSE (scb, table, selector, pselect, cmd)
EDACALLBACK	Specifying callback processing.	EDACALLBACK (eid, type, status, routine, block)
EDACOMMIT	Marking the end of a transaction.	EDACOMMIT (eid, yn, status)
EDACONNECT	Linking an application program to a server.	EDACONNECT (eid, scb, user, ln_user, password, ln_password, server_name, ln_server)
EDADESCRIBE	Building a table or file description.	EDADESCRIBE (scb, fname, flength)
EDAEXECUTE	Initiating a prepared SQL request.	EDAEXECUTE (scb, sth, est1, est2, dpassword, dlength)
EDAFETCH		EDAFETCH (scb, tuple, len, fmt)
EDAFIELD	Storing fields in a designated data area.	EDAFIELD (scb, column_nbr, data_area, len, fmt)
EDAFOCUS	Executing a FOCUS procedure	EDAFOCUS (scb, procstring, stringlength)
EDAINFO	Returning a column description.	EDAINFO (scb, column_nbr, work_area)
EDAINIT	Initializing a server.	EDAINIT (eid, status)
EDAINSPECT	Obtaining Information on the API.	EDAINSPECT (eid, scb, setting, value, status)
EDANEXT		EDANEXT (scb)
EDANULL	Checking for a null value in a specified field.	EDANULL (scb, column_nbr, null_ind)
EDAPINIT	Connecting to the server.	EDAPINIT (eid, pcount, pcb_type, proutine, pcb_block, status)
EDAPREPARE	Preparing an SQL string for execution.	EDAPREPARE (scb, sth, statement, slength)
EDAQUIT	Terminating result set processing.	EDAQUIT (scb)
EDARPC	Executing a remote stored procedure.	EDARPC (scb, rpcname, rlength, parms, plength)
EDASERVERS	Returning server names in a synchronous environment.	EDASERVERS (eid, bfr, bfrlen, status)
EDASET	Changing the values of internal variables.	EDASET (eid, scb, setting, value, status)
EDASQL	Passing an SQL statement to the server.	EDASQL (scb, statement, slength, est1, est2, dpassword, dlength, execute)
EDATERM	Terminating a connection.	EDATERM (eid, status)
EDATEST	Determining is the server is ready to return output.	EDATEST (scb, wait_ind)
EDAUSING	Furnishing parameters to prepared SQL statements.	EDAUSING (scb, sth, parm, vlu, vlulen, dtype, len, scale, endparm)
EDAWAIT	Suspending the application program until output arrives (DEPRECATED).	EDAWAIT (eid, timeout, session, status)
EDAXCONNECT	Deleting a connection.	EDAXCONNECT (scb)
EDAXPREPARE	Releasing all resources of a prepare statement.	EDAXPREPARE (scb, sth)

EDAACCEPT: Accessing Queued Messages From a Server

How to: Access Queued Messages From a Server Example: Checking for Messages Returned From a Server Reference: Usage Notes for EDAACCEPT

EDAACCEPT provides access to queued messages from the server.

Syntax: How to Access Queued Messages From a Server

EDAACCEPT (scb)

where:

scb (input, long)

Is an initialized session control block.

Reference: Usage Notes for EDAACCEPT

A transaction generates output streams comprised of messages, column description information, and elements (tuples) of result sets. Messages may be interleaved with tuples.

Note: These messages are not to be confused with messages produced when using MQ Series.

The API distinguishes between messages and other output in the stream. When EDATEST, EDAFETCH, EDANEXT, or EDAINFO is issued, the API processes the output stream and places the first message it encounters, if any, into the message area of the SCB.

Note: Each call to EDAACCEPT overlays the previous messages in the SCB.

Before issuing the EDAACCEPT command, an application should first check the SCB message type. A value other than zero (0) indicates that a message has been returned and should be processed. After processing the first message, the application should check the message pending indicator to see if more messages are available. If there are messages pending, then issue the EDAACCEPT.

If there is more than one message in the stream, the API sets the Message Pending indicator of the SCB to one (1). (The first message is free; that is, it does not depend on the Message Pending indicator to place this message.) Issue EDAACCEPT when the Message Pending indicator is 1 to place the next message information into the SCB. You can determine whether a message is currently available in the SCB by inspecting the Message Type field.

EDAACCEPT is normally part of a message processing loop placed after EDATEST, EDAFETCH, EDANEXT, and EDAINFO; it processes messages from a server. The loop should be performed until the Message Pending indicator is zero (0). For information on error processing, see Usage Considerations.

Example: Checking for Messages Returned From a Server

The following is an example in C:

if(scb->msg_type!=0)
{
  printMsg("%-8.8s%ld %-*.*s\n",scb->msg_org,scb->msg_code,scb->
       msg_len,scb->msg_len,scb->msg_text);
  while(scb->msg_pending)
  {
     EDAACCEPT(scb);
     printMsg("%-8.8s%ld %-*.*s\n",scb->msg_org,scb->msg_code,scb->
          msg_len,scb->msg_len,scb->msg_text);
  }
}

The following is an example in Visual Basic:

If scb.msg_type <> 0 Then
  sMsgText = Left(scb.msg_text, scb.msg_len)
     frmEDAx.txtResults.Text = frmEDAx.txtResults.Text + _
      "(" + scb.msg_org + Str(scb.msg_code) + ") " + sMsgText + vbNewLine
  Do While scb.msg_pending <> 0
  EDAACCEPT scb
     sMsgText = Left(scb.msg_text, scb.msg_len)
     frmEDAx.txtResults.Text = frmEDAx.txtResults.Text + _
      "(" + scb.msg_org + Str(scb.msg_code) + ") " + sMsgText + vbNewLine
  Loop
  frmEDAx.txtResults.Text = frmEDAx.txtResults.Text + _
    "-- End of Messages -- " + vbNewLine
End If

EDABROWSE: Displaying or Manipulating Data

How to: Display or Manipulate Data Example: Obtaining a Server Listing Connecting to an Internal EDABASE Error Table Structure to Get Status Description Reference: Usage Notes for EDABROWSE Engine Table Valid Subsets for the Engine Table Input Column Attributes for the Engine Table Output Server Table Valid Subsets for the Server Table Input Column Attributes for the Server Table Output Error Code Table Valid Subsets for the Error Code Table Input Column Attributes for the Error Code Table Output Message Table Valid Subsets for the Message Table Input Column Attributes for the Message Table Output The Tables Table Valid Subsets for the Tables Table Input Column Attributes for the Tables Table Output

EDABROWSE identifies a set of data and either materializes or manipulates it in some way. For example, EDABROWSE can return a result set consisting of one row for each accessible server. EDABROWSE also provides access to a set of data structures that contain metadata about the client environment. Any one of these data structures, called EDABASE tables, can be accessed by issuing the EDABROWSE method call with the appropriate table code and issuing an EDAFETCH or EDAFIELD on the results of the EDABROWSE query.

The following EDABASE tables are provided:

Table	Description
Engine	Pairs engine names and their numeric engine codes.
Server	Contains server names and attributes.
Error Code	Provides a test lookup function for API errors.
Message	Query and response messages for an asynchronous server connection.
Tables	Reachable synchronous servers.

Of these, the Engine Table, the Server Table, and the Error Code Table can be used both in synchronous and asynchronous applications. Since a connected SCB is a required parameter for EDABROWSE, there is an option on the EDACONNECT to create an SCB connected to SELF so these tables may be invoked without connecting to an actual server. To access the Message Table, EDABROWSE requires the SCB to be connected to an asynchronous server. The Tables Table is accessed by connecting to a synchronous server, where results in a result set are identical to that of Open Database Connectivity's (ODBC's) SQLTABLES().

Application programs can issue an EDAINFO call after EDABROWSE to get the column attributes of the selected EDABASE table. Each table has various subsets that can be accessed by specifying the subset desired with the selector and pselect parameters. These are described in detail with each EDABASE table.

Note: Columns may be added to these tables in the future. Programmers are cautioned not to base their logic on a possibly outmoded notion of what comprises the EDABASE data structures. EDAINFO provides up-to-date, dynamic metadata describing result sets. This information from EDAINFO is guaranteed to be correct for any given release of the API.

The caller establishes a set operand by supplying three EDABROWSE parameters. The first of these identifies a base table; the second and third restrict that table to a subset.

Syntax: How to Display or Manipulate Data

EDABROWSE (scb, table, selector, pselect, cmd)

where:

scb (input, long)

Is a session control block.

table (input, long)

Is one of the following numeric codes representing an EDABASE table:

1	EDABASE_TBL_ENGINES
2	EDABASE_TBL_SERVERS
3	EDABASE_TBL_ERRORS
4	EDABASE_TBL_MSGS
5	EDABASE_TBL_TABLES

selector (input, long)

Is a numeric code indicating the subset of the given EDABASE table.

pselect (input, long)

Is a value isolating the subset of selector data to be shown.

cmd (input, long)

Is a numeric code indicating the action to be performed on the subset (to either materialize or delete a result set from it) as shown by the following:

0	EDABASE_SELECT
1	EDABASE_DELETE

Note: Delete is valid only when the given EDABASE table is the Message Table.

Reference: Usage Notes for EDABROWSE

EDABROWSE can either query or delete from tables in the EDABASE database. The API maintains EDABASE, the local database consisting of several tables.

In query mode, EDABROWSE materializes result sets and makes them available to the caller. In this respect, it is similar to EDASQL, EDARPC, and EDAEXECUTE.

In delete mode, EDABROWSE deletes subsets of messages from the Message Table. See API Data Structures, for more information on tables.

EDABASE_TBL_SERVERS is restricted to providing a list of nodes within the configuration file. If using a cluster node, and you wish to know the alternate node you actually connected to, see EDA_VAR_SERVER_NAME in Environment Variables.

Reference: Engine Table

Table Code	Manifest Constant Table
1	EDABASE_TBL_ENGINES

Reference: Valid Subsets for the Engine Table Input

Selector Code	Manifest Constant Selector	pselect	Comments
0	EDABASE_SEL_ENGINES_ALL	Null	All engines.
1	EDABASE_SEL_ENGINES_NAME	The 16-byte name of the desired engine.	The engine specified by pselect.
2	EDABASE_SEL_ENGINES_TYPE	The code of the desired engine.	The engine specified by pselect.

Note: Manifest constants are defined in the EDA.H file. The application programs should use these manifest constants instead of the underlying values when calling the API methods because the underlying values may change in future releases.

Reference: Column Attributes for the Engine Table Output

The following are column attributes for the Engine Table. You can access this EDABASE table by issuing an EDABROWSE method call with the table manifest constant set to EDABASE_TBL_ENGINES. It describes the names of the available relational engines and their corresponding codes that may be used in an EDASET method call when an application needs to issue a particular dialect of SQL.

Attribute	Data Type	Description
EngineName	char[16]	The name of the relational engine.
EngineCode	long	The numeric code corresponding to the engine (for use with EDASET and EDAINSPECT).

Reference: Server Table

Table Code	Manifest Constant Table
2	EDABASE_TBL_SERVERS

Reference: Valid Subsets for the Server Table Input

Selector Code	Manifest Constant Selector	pselect	Comments
1	EDABASE_SEL_SERVERS_SYNC	Null	Synchronous servers.
2	EDABASE_SEL_SERVERS_ASYNC	Null	Messaging Adapters.
3	EDABASE_SEL_SERVERS_ALL	Null	All servers.
4	EDABASE_SEL_SERVERS_EXACT	The 8-byte name of the desired server.	The server specified by pselect.
8	EDABASE_SEL_SERVERS_DEFAULT	Null	The default server.

Reference: Column Attributes for the Server Table Output

The following are column attributes for the Server Table. You can access this EDABASE table by issuing an EDABROWSE method call with the table manifest constant set to EDABASE_TBL_SERVERS. It is similar to the EDASERVERS method call, but provides more information for the user. This table lists the names of all available servers to which the application may connect. It also lists the server type, and if the server is asynchronous, the partner connection name (if provided in the ODIN communications configuration file: CLASS=ASYNC(partner_name) that allows access to the same database.

Attribute	Data Type	Description
SName	char[8]	The name of server.
Ecode	char	The type of server: "S" - Synchronous. "A" - Asynchronous. (MQ Message). "D" - Distributor (Cluster node).
Partner	char[8]	The server name of the partner connection.

Example: Obtaining a Server Listing

Private Sub cmbServers Dropdown ()
    Dim selfscb As eda scb
    Dim SName      As String * 8
    Dim sServer    As String * 512
    Dim servers    As Long
    Dim selector   As Long
    Dim cmd        As Long
 
    servers = EDABASE_TBL_SERVERS
    selector = EDABASE_SEL_SERVERS_ALL
    cmd = EDABASE_SELECT
 
    EDACONNECT eid, selfscb, " ", -1, " ", -1, " ", -5
    EDABROWSE selfscb, servers, selctor, 0&, cmd
    EDATEST selfscb, 0&
    Do While selfscb.status = EDA_SUCCESS
        EDANEXT selfscb
        If selfscb.status = EDA_SUCCESS Then
           EDAFIELD selfscb, 1, SName, 8, EDA_ALPHANUM
           frmEDAx.cmbServers.AddItem SName
        End If
    Loop
    EDAXCONNECT scb
End Sub

Reference: Error Code Table

Table Code	Manifest Constant Table
3	EDABASE_TBL_ERRORS

Reference: Valid Subsets for the Error Code Table Input

Selector Code	Manifest Constant Selector	pselect	Comments
0	EDABASE_SEL_ERRORS_ALL	Null	All errors.
1	EDABASE_SEL_ERRORS_CODE	The code of the desired error.	The error specified by pselect.

Reference: Column Attributes for the Error Code Table Output

The following are column attributes for the Error Code Table. You can access this EDABASE table by issuing an EDABROWSE method call with the table manifest constant set to EDABASE_TBL_ERRORS. It provides the English text associated with the API error codes.

Attribute	Data Type	Description
ErrorCode	long	The API error code.
ErrorText	char[64]	The text description corresponding to that error code.

Example: Connecting to an Internal EDABASE Error Table Structure to Get Status Description

long eErrorText(EDA_ID *pEid,long lStatus)
{
    EDA_scb scb;
    long       lErrors=EDABASE_TBL_ERRORS,
               lSelector      =EDABASE_SEL_ERRORS_CODE,
               lCmd           =EDABASE_SELECT,
               lSelf          =EDA_CONNECT_SELF,
               lNts           =EDA_NULL_DELIM,
               lColno         =2,
               lLen           =64,
               lFmt           =EDA_ALPHANUM;
     char             szErrorText[64]="?";
    EDACONNECT(pEid,&scb,"",&lNts,"",&lNts,"",&lSelf);
    EDABROWSE(&scb,&lErrors,&lSelector,&lStatus,&lCmd);
    EDATEST(&scb,NULL);
    EDANEXT(&scb);
       if(scb.status==EDA_SUCCESS)
          EDAFIELD(&scb,&lColno,szErrorText,&lLen,&lFmt);
    EDAXCONNECT(&scb);
    printMsg("(%ld) %-64.64s\n",lStatus,szErrorText);
    if(lStatus<EDA_SUCCESS)
        return(1);
    else
        return(0);
}

Reference: Message Table

Table Code	Manifest Constant Table
4	EDABASE_TBL_MSGS

Reference: Valid Subsets for the Message Table Input

Selector Code	Manifest Constant Selector	pselect	Comments
0	EDABASE_SEL_MSGS_ALL	Null	All messages.
1	EDABASE_SEL_MSGS_UOWID	The identifier of the desired UOW.	The messages having the correlation identifier.

Reference: Column Attributes for the Message Table Output

The following are the column attributes for the Message Table. You can access this EDABASE table by issuing an EDABROWSE method call with the table manifest constant set to EDABASE_TBL_MSGS. This EDABASE table is available only when connected to an asynchronous server. It lists the Units of Work for which a reply message has been received from the asynchronous server.

Note: Message Tables are snapshots of message queues. Unlike message queues (which reflect, in real-time, the status of every outstanding operation directed to a particular server), Message Tables are static objects. Applications requiring up-to-date status information must refresh them frequently by reissuing EDABROWSE method calls.

A message queue comprises zero (0), one (1), or more messages arranged in first-in, first-out order within priority. The connector maintains a local message queue for every addressable asynchronous server. It makes the contents of local queues accessible by materializing Message Table instances on demand.

Attribute	Data Type	Description
UOWId	binary[6]	The correlation identifier (the Unit of Work handle of the original request).
UserId	char[8]	The user ID of the originator of the UOW.
Status	integer	The completion status of the UOW. Manifest constants are: EDA_UOWSTATE_CONFIRM EDA_UOWSTATE_FAILED EDA_UOWSTATE_INDOUBT
MsgRc	integer	The return code from the Message Server. Manifest constants are: EDA_MSGRC_TIMEOUT EDA_MSGRC_NODEM EDA_MSGRC_NOENTRY EDA_MSGRC_TARGET EDA_MSGRC_PROTOCOL
Subcode	integer	The status code.
Error By	integer	The source of the error.
SentStamp	char[19]	The time and date the message was sent.
ProcStamp	char[19]	The time and date the message was processed.
Module	char[32]	The name of the target DLL that processed the message.
Content	ULOB	The ULOB identifier (the ALOB locator): When the ClassType is 1, the Content contains a handle to the original SQL request. When the ClassType is 2, the Content contains a handle to the returned attachments, which could be: an ALOB (metadata, result sets, and messages) and zero (0), one (1), or more BLOBs and CLOBs. This handle is used in a subsequent EDASQL call to retrieve the attachments returned from the asynchronous server. Note: The server supports the following large objects: 0 ALOBs (metadata, result sets, SCB-type messages) 1 CLOBs (SQL requests and long VARCHAR columns returned from the server). 2 BLOBs (large binary columns returned from the server). The Content column, declared here in nonstandard fashion as an unidentified large object (ULOB), contains an SQL request (CLOB) for ClassType=1 messages and one or more attachments for ClassType=2 messages: possibly metadata, a result set, and/or SCB-type messages (an ALOB), and one or more BLOBs and/or CLOBs if requested in the submitted SQL statement.
Request	ULOB	Access to original request message.
Comment	char[128]	User-supplied comment field.

Reference: The Tables Table

Table Code	Manifest Constant Table
5	EDABASE_TBL_TABLES

Reference: Valid Subsets for the Tables Table Input

Selector Code	Manifest Constant Selector	pselect	Comments
0	EDABASE_SEL_TABLES_ALL	Null	All Tables

Reference: Column Attributes for the Tables Table Output

The following column attributes are for the Tables Table. You can access this EDABASE table by issuing an EDABROWSE method call with the table manifest constant set to EDABASE_TBL_TABLES. This EDABASE table is available only when connected to a synchronous server. It lists all tables reachable on a synchronous server.

Attribute	Data Type	Description
TABLE_QUALIFIER	char[128]	Table qualifier identifier.
TABLE_OWNER	char[128]	Table owner identifier.
TABLE_NAME	char[128]	Table identifier.

EDACALLBACK: Specifying Callback Processing

How to: Specify Callback Processing Example: Setting Up the EDACALLBACK for Tracing Reference: Description of the Block Format in the Include File Usage Notes for EDACALLBACK

EDACALLBACK (and EDAPINIT) provide you with control over the operation of the API in specialized environments, such as under control of a task manager like CICS. The callback method allows you to provide appropriate program exit routines for performing such tasks as memory management, resource serialization, and debug tracing. Callback processing may not be amenable to all programming languages, since it deals specifically with addresses. The references below are for C.

To include the callback facilities in an application written in C, use the define statement "#define EDA_CALLBACKS" before the include statement in the EDA.H header file.

The most common callback use is to establish a trace routine. This enables trace messages to be intermixed with those of your application, affording a simpler analysis of the application's use of the server.

Syntax: How to Specify Callback Processing

EDACALLBACK (eid, type, status, routine, block)

where:

eid (input, long)

Is an application identifier.

type (input, long)

Is the callback routine that is being requested. Possible values are:

0	EDA_CB_TRACE	Trace callback routine.
1	EDA_CB_MEMORY	Memory callback routine.
2	EDA_CB_LOCK	Not used.
3	EDA_CB_UNLOCK	Not used.
4	EDA_CB MESSAGE	Access to messages received.
5	EDA_CB_NOTIFY	Communication layer notification.
6	EDA_CB_MASFILE	Raw metadata access.
7	EDA_CB_IOCOMPLETE	I/O completion signaling.

Of these types, the memory callbacks must always be established through the EDAPINIT method, since the services are required during connector initialization. Any other callback types can be established at any time.

status (output, long)

Is a status return code, which reflects whether or not the connector has been initialized correctly. Possible values are:

0 Represents a successful initialization.

-n Signifies that a fatal error occurred.

+n Is a warning.

routine (input, pointer)

Is the entry point of the callback routine. This is a method address as defined for your environment.

block (input, long)

Must be null.

Reference: Description of the Block Format in the Include File

The format of the block as it is described in the include file is as follows:

type (input, long)

Is a value equal to one (value = 1).

count (input, long)

Is a counter incremented before each callback.

scb_id (input, long)

Is a session ID for the governing scb.

status (output, long)

Is the most recent status code returned.

subcode (output, long)

Is for server use only.

callback

Is specific for the callback.

Reference: Usage Notes for EDACALLBACK

Under normal circumstances, the API manages all memory allocation requirements for data storage required by the API itself. EDAPINIT, in conjunction with EDACALLBACK, enables the application to take control of this management task. It also provides the application with the ability to control tracing.

The EDACALLBACK and EDAPINIT routines are assumed to be written in the C programming language, or in a language providing C calling conventions. The routines in this chapter are discussed in terms of the C language typedef's EDA_APIENTRY and EDAPTR, which are defined in the EDASYS.H include file, and vary among platforms. For any specific platform, these definitions must not be modified.

Example: Setting Up the EDACALLBACK for Tracing

The following code shows how to set up the EDACALLBACK for tracing:

 :
 :
#define EDA_CALLBACKS
#include "eda.h"
 :
 :
long eTraceSet(EDA_ID *pEid,long lTrace)
{
    long    lStatus,
            lEdaCbTrace         =EDA_CB_TRACE,
            lEdaVarLogid        =EDA_VAR_LOGID,
            lTraceVarOn         =EDA_VAR_ON,
            lTrace              =EDA_VAR_TRACE;
            lTraceLvl           =EDA_VAR_TRACE_DEF;
 
    /* setup callback tracing                                       */
    EDACALLBACK(pEid,&lEdaCbTrace,&lStatus,(EDA_ECALLBACK)eTraceOut,NULL);
    if(lStatus)
    {
        printf("Tracing CALLBACK Failed, status=%ld\n",lStatus);
        return(lStatus);
    }
 
    /* set trace line label                                         */
    EDASET(pEid,NULL,&lEdaVarLogid,"TRACE",&lStatus);
 
    /* enable EDA tracing                                           */
    EDASET(pEid,NULL,&lTrace,&lTraceVarOn,&lStatus);
    
    /* turn on default level tracing                                */
    EDASET(pEid,NULL,&lTraceLvl,&lTraceVarOn,&lStatus);
 
    return(lStatus);
}
/*
*---------------------------------------------------------
* Tracing callback routine setup by EDACALLBACK.
*---------------------------------------------------------
*/
EDA_APIENTRY eTraceOut(EDAPTR(struct EDA_CALLBACK_BLOCK)pcbEda)
{
       ...code to display or process tracing messages goes here...
}

EDACOMMIT: Marking the End of a Transaction

How to: Mark the End of a Transaction Reference: Usage Notes for EDACOMMIT

EDACOMMIT marks the successful end of a transaction for the given EDA ID.

A call to EDAINIT may be viewed as initiating the first in a series of database transactions. Each time EDACOMMIT is invoked, one transaction ends and a new one begins.

Syntax: How to Mark the End of a Transaction

EDACOMMIT (eid, yn, status)

where:

eid (input, long)

Is the application identifier.

yn (input, long)

Is used as the Commit flag. Possible values are:

1 All changes made to the database during the course of the transaction will be made permanent.

0 The DBMS will undo all such changes, rolling back the database to its state immediately before the current transaction began.

Note: The yn indicator does not influence the "transaction end/transaction begin" progression. Its sole purpose is to confirm or undo (rollback) sets of related changes to the database.

status (output, long)

Is the server status code.

Reference: Usage Notes for EDACOMMIT

The API supports the complete broadcast commit of a logical unit of work (LUW). That is, the API broadcasts to all connections opened during a session, enabling applications to completely control the scope of their transactions, even across multiple databases and servers. The server default behavior is to not auto commit, and to only commit on successful disconnection.

If an application generates a COMMIT WORK and sends it as an SQL statement to the server, everything on that server connection or on all multiplexed or semiplexed connections to that server will be committed. If an explicit EDACOMMIT is issued, all open transactions for all servers will be committed (or rolled back).

Important: An EDACOMMIT should not be called unless actions on all active statements have been completed. Issuing an EDACOMMIT will cause pending data on all open SCBs to be released.

For more information on transaction processing, see Usage Considerations. For information on multiplexing and transaction processing with controlled data transfer, see Advanced Usage Considerations.

EDACONNECT: Linking an Application Program to a Server

How to: Connect an Application Program to a Server Example: Adding a Check for an Expired Password and Changing Your Password Reference: Usage Notes for EDACONNECT Asynchronous Connection Semiplexed Connection Connection to SELF

EDACONNECT links a running API application program with a server, creating a session control block to:

• Connect to a synchronous server.
• Establish a semiplexed connection.
• Connect to a messaging server.
• Initialize an SCB without connecting to a server so the EDABASE data structures may be accessed. This is referred to as a connection to "SELF" because the accessed database is internal API information.

Use EDACONNECT to:

• Issue SQL statements.
• Request metadata descriptions.

Invoke remote procedures.

Syntax: How to Connect an Application Program to a Server

EDACONNECT (eid, scb, user, ln_user, password, ln_password, server_name, ln_server)

where:

eid (input, long)

Is an ID initialized by EDAINIT.

scb (output, long)

Is a server-connection identifier.

user (input, char)

Is the user identification; authentication.

ln_user (input, long)

Denotes the length of the user character string.

password (input, char)

Is the password; authentication.

ln_password (input, long)

Denotes the length of the password string.

server_name (input, char)

Has the following uses and purposes:

• It is a string containing the name of a synchronous or an asynchronous server to which the SCB will be connected. Node= in ODIN.CFG.
• It is a pointer to an already established SCB, to which the new SCB will be semiplexed.
• It is NULL when the application wishes to connect the SCB to "SELF" (the internal EDABASE data structures).

ln_server (input, long)

Indicates how the server_name parameter is to be treated. Its value:

• Denotes the length of the server character string if server_name is a pointer to a synchronous or an asynchronous server name.
• Is -1 (EDA_NULL_DELIM) if server_name is a null-delimited string.
• Is -4 (EDA_CONNECT_SEMIPLEX) if server_name is a pointer to an initialized SCB connected to a synchronous server.
• Is -5 (EDA_CONNECT_SELF) if server_name is NULL.

Reference: Usage Notes for EDACONNECT

The server_name string is an entry in the connector communications configuration file.

Password security is governed by the protocol in effect on the server or gateway to which the application program is connecting.

Upon successful completion of the EDACONNECT call, an SCB is established and the SCB error and status fields are set to zero (0).

Note: To change a password on the server, the password string should be sent as follows:

oldpassword,newpassword 

This may be reviewed by an application after an EDA_PASSWORD_EXPIRED (-20) return code.

Reference: Asynchronous Connection

To access a queue associated with an asynchronous server, the application calls EDACONNECT, supplying the asynchronous server name for that queue. Messaging servers are those servers in the Server Table whose Ecode attribute is "A." (For more information, see EDABROWSE: Displaying or Manipulating Data.)

The EDACONNECT call to an asynchronous server is issued in the same way as one issued to a synchronous server. However, upon successful execution of an EDACONNECT, there is no physical connection to a server. The SCB is merely initialized for creation of asynchronous Units of Work targeted to the server name specified by the server_name parameter. The API distinguishes synchronous server connection queries from asynchronous server connection requests and adjusts its behavior accordingly. An operation controlled by an asynchronous SCB does not always act exactly like the operation of the same name controlled by a synchronous SCB. Some methods, for example, EDAPREPARE, are prohibited in an asynchronous context. Other methods, for example, EDACONNECT, take on new shades of meaning.

To access the internal API EDABASE data structures the application calls EDACONNECT with a NULL server_name parameter and the ln_server parameter set to -5. This is particularly useful, for example, for applications to provide their users with the list of available servers, their types, and partner names from the Server Table, allowing them to select the server to which they wish to connect. Otherwise, an application may need to access the Engine Table or the Error Code Table without having an actual server connection. Once connected to "SELF," the application can materialize an EDABASE table instance by issuing an EDABROWSE request under control of the resulting SCB, and retrieve the table as it would any other result set. For information on tables, see API Data Structures.

Note: An SCB connected to "SELF" cannot access the Message Table. Only an SCB connected to an asynchronous server can access the Message Table.

Reference: Semiplexed Connection

Semiplexing allows an application to control the assignment of SCBs to servers. In effect, a semiplexed SCB acts as a statement handle. This is especially useful in situations in which several operations must be performed simultaneously to the same server, such as retrieving several output result sets in parallel.

To establish a semiplexed (user multiplexing) connection, you must specify the parameters to EDACONNECT as follows:

• User ID and password must be null.
• ln_user and ln_password must be zero (0).
• The server value must be cast to a pointer to the parent SCB (the SCB established by the initial EDACONNECT).
• The ln_server parameter must be set to EDA_CONNECT_SEMIPLEX(-4).

The connection mode allows the developer to control which connections are multiplexed and which are not multiplexed. For more information, see Advanced Usage Considerations.

Reference: Connection to SELF

It is possible to establish an SCB for communication with the API itself (as opposed to a server). You can then use the EDABROWSE command to retrieve various information stored locally by the API. (For details, see EDABROWSE: Displaying or Manipulating Data.) To establish such a connection, the parameters sent to EDACONNECT must be as follows:

• User ID and password must be null.
• ln_user and ln_password must be zero (0).
• The server value must be null.
• The ln_server parameter must be set to EDA_CONNECT_SELF(-5).

For more information, see Advanced Usage Considerations.

Example: Adding a Check for an Expired Password and Changing Your Password

The following is an example in C:

EDACONNECT(&eid
   ,&scb
   ,user
   ,&ln_user
   ,password
   ,&ln_password
   ,server
   ,&ln_server
   );

if (scb.status == EDA_PASSWORD_EXPIRED)
{
   strcpy(szNewPswdString,password);
   strcat(szNewPswdString,",");
   strcat(szNewPswdString,npswd.szNewPswd);  /* get new pswd from user */
 
   lcbAuthStr = EDA_NULL_DELIM;
 
   EDACONNECT(&eid
      ,&scb
      ,user
      ,&ln_user
      ,szNewPswdString
      ,&lcbAuthStr
      ,server
      ,&ln_server
      );

   if (scb.status == EDA_INVALID_NEW_PASSWORD)
   {
      return (scb.status);   /* signal error to user                   */
   }
}
 
return scb.status;

The following is an example in Cobol:

CALL "EDACONNECT"
USING EID, SCB, USER, LN_USER, PASSWORD,LN_PASSWORD, SERVER, LN_SERVER

The following is an example in Visual Basic:

EDACONNECT &eid, &scb, user$, Len(user$), password$, Len(password$), server$, Len(server$)

EDADESCRIBE: Building a Table or File Description

How to: Build a Table or File Description Example: Providing a List of Fields for a Table Reference: Usage Notes for EDADESCRIBE

EDADESCRIBE initiates a request to a server to build a description of a table or a file. The EDADESCRIBE call is completed when the server successfully initiates a task to process the request.

Note: EDADESCRIBE cannot be used in an asynchronous environment or with transaction adapters.

Syntax: How to Build a Table or File Description

EDADESCRIBE (scb, fname, flength)

where:

scb (input, long)

Is a session control block.

fname (input, char)

Is a fully-qualified file or table name.

flength (input, long)

Is the length of the fname string.

Reference: Usage Notes for EDADESCRIBE

EDADESCRIBE builds an internal API table description, the contents of which may be extracted by means of subsequent EDAINFO methods. It permits the caller to examine the composition of a table or a view without actually executing a query.

EDADESCRIBE applies only to named tables and files, not to result sets. EDASQL and EDAPREPARE automatically describe the format of their result sets to the system.

EDADESCRIBE may be used in situations where the application wishes to provide the user with column information before sending an SQL request. An appropriately placed series of calls to EDAINFO may be employed to extract this information. (For additional information, see EDAINFO: Returning a Column Description.)

Use of a

"SELECT * FROM table_name",

in an EDAPREPARE or an EDASQL statement with XRETRIEVAL set to OFF may be utilized as a valid alternative to this call.

Example: Providing a List of Fields for a Table

This coding example shows how to use the EDADESCRIBE function to provide a list of fields for a given table.

               :
               :
 
void getcolumns(EDA_scb *scb, char *pszTable)
{
    EDA_info_area   edainfoarea;
    long            lNts      =EDA_NULL_DELIM,
                    lRc       =0,
                    lColNo;
 
    EDADESCRIBE(scb,pszTable,&lNts);
    if(scb->status!=EDA_SUCCESS)
        ...process error...
    
    EDATEST(scb,NULL);
    if(scb->status!=EDA_SUCCESS)
        ...process error...
 
    for(lColNo=1;lColNo<=scb->nbrcols;lColNo++)
    {
      EDAINFO(scb,&lColNo,&edainfoarea);
      if(scb->status!=EDA_SUCCESS)
            ...process error...
        else
            printf("%s",edainfoarea.col_name);
    }
               :
               :
 
}

EDAEXECUTE: Initiating a Prepared SQL Request

How to: Initiate a Prepared SQL Request Execute a Prepared Statement With Multiple Parameter Lists Example: Binding Parameters for a Prepared Statement Reference: Usage Notes for EDAEXECUTE

EDAEXECUTE initiates the execution of a previously prepared SQL request on a server. An API application can repeatedly execute the same prepared SQL statement, without re-parsing it, provided that an intervening EDAXPREPARE, EDACOMMIT, or COMMIT WORK has not been issued.

Note: EDAEXECUTE cannot be used in an asynchronous environment or with transaction adapters.

Syntax: How to Initiate a Prepared SQL Request

EDAEXECUTE (scb, sth, est1, est2, dpassword, dlength)

where:

scb (input, long)

Is a session control block.

sth (input, long)

Identifies the statement.

est1 (input, long)

Is reserved for future use. Must be zero (0). This value may be utilized in a subsequent release.

est2 (input, long)

Is reserved for future use. Must be zero (0). This value may be utilized in a subsequent release.

dpassword (input, char)

Is the DBA password. (The string can be null if none is required.)

dlength (input, long)

Is the length of the dpassword string in bytes.

Reference: Usage Notes for EDAEXECUTE

You cannot invoke EDAEXECUTE until an associated EDAPREPARE has been completed. If a prepare was issued but failed, an EDA_EXECUTE_NOT_PREPARED (-25) error will be returned for the execute. Once the EDAPREPARE has been issued, the status should be checked and the EDAEXECUTE should not be issued until successful execution of the EDAPREPARE has been established. If the EDAPREPARE has failed for some reason, the SCB message area should be reviewed in order to find the reason for failure. Review the message queue before you issue the next command to establish the reason for prepare failure. Once the EDAEXECUTE is issued, this area will be overwritten. If the prepared statement contains parameters, you should assemble one or more parameter lists using the EDAUSING method before you issue the execute. Should an EDAUSING or EDAEXECUTE be issued after an EDAPREPARE without an intervening EDATEST, an internal EDATEST will be issued to verify the success of the EDAPREPARE.

EDAEXECUTE transmits an execution request to the server and returns to the calling program. The server makes the necessary parameter substitutions and activates the referenced SQL request.

When EDAEXECUTE returns control to the caller, the status field in the controlling SCB indicates whether or not the method executed correctly. A nonzero status code might indicate, for example, that one of the parameters in the calling sequence is incorrect or that the call was issued in an incorrect context. An EDA_SUCCESS (0) status code indicates that no errors of this sort were detected.

An EDA_SUCCESS (0) status code from EDAEXECUTE means that the API has sent a message to the server requesting action, not that the given SQL statement has been carried out. EDAEXECUTE performs whatever work it can do locally and returns at once so the application program can continue processing while remote database operations take place. The success or failure of the database activity triggered by the EDAEXECUTE call will be reflected in the SCB message area when a transition to the processing state occurs.

You can submit multiple parameter lists to prepared SELECT, UPDATE, INSERT, and DELETE statements using the EDAUSING parameter call. If "n" (where n >1) parameter lists have been accumulated for the given statement identifier, the SQL request will be repeated "n" times. This feature makes it possible to insert or update a group of database records in a single client/server interaction. If this technique is used with a SELECT statement, the application program must be prepared to process multiple result sets. To retrieve the next result set where multiple result sets are pending, an EDAQUIT must be issued after reading the first.

Procedure: How to Execute a Prepared Statement With Multiple Parameter Lists

1. Prepare the SQL statement using EDAPREPARE.

2. Issue one EDAUSING for each parameter in the prepared SQL statement and repeat with as many parameter lists as required.

3. Issue EDAEXECUTE to execute the statement.

Example: Binding Parameters for a Prepared Statement

for (i=0; i<countOfUsings;i++) 
{
long   parm;
long   edaparm = 0;
 
   parm = (long) i;
 
   if (i == countOfUsings-1)
      endparm = 1;                   /* reached high water mark of 
                                        parms                    */
 
   EDAUSING(&scb
      , &sth->EdaPrepHdl
      , &parm                        /* parameter number              */
      , (EDACPTR)theParm[i].vlu      /* string of value to EDA        */
      , &theParm[i].vlulen           /* length of param string        */
      , &theParm[i].dtype            /* EDA datatype                  */
      , &theParm[i].len              /* length or precision           */
      , &theParm[i].scale            /* scale of numeric parameter    */
      , &endparm
      );
}
 
EDAEXECUTE(&scb, &sth->EdaPrepHdl, &zero, &zero, NULL, &zero);

EDAFETCH

In this section: Boundary Alignment LOB Data Types Variable Length Character Data How to: Return a Row of Data From the Result Set Example: Fetching Result Set Data by Rows Reference: Usage Notes for EDAFETCH

EDAFETCH positions the cursor at the next available row and returns the row of data to the indicated work area. If every row in the result set has been processed, the end-of-set status code, EDA_END_OF_SET (5), will be returned; otherwise, the status code will be EDA_SUCCESS (0). Note that once EDA_END_OF_SET is returned, subsequent fetches return an error. EDAFETCH does not alter the designated work area if the end-of-set status code is returned.

Syntax: How to Return a Row of Data From the Result Set

EDAFETCH (scb, tuple, len, fmt)

where:

scb (input, long)

Is a session control block.

tuple (input, long)

Is the work area receiving the output tuple.

len (input, long)

Is the length of the receiving work area.

fmt (input, long)

Is a format indicator. It determines the format in which data will be delivered to the caller's working storage area. Possible values are:

0 The fields within the target tuple will be expressed in binary format. (For information on binary format, see EDAINFO: Returning a Column Description.)

1 The fields within the target tuple will be returned in alphanumeric format. (Recommended)

Note: When binary format is used, the receiving tuple must be aligned on an appropriate word boundary. If it is not, an error status value of EDA_TUPLE_MISALIGNED (-16) will be returned.

Reference: Usage Notes for EDAFETCH

EDAFETCH returns tuples from the result set, one at a time, in the order in which they are received from the server. It is not possible to set the cursor backward to re-access a tuple that has already been processed.

If the tuple length recorded in the SCB exceeds the length field (len) given in the EDAFETCH calling sequence, a nonzero status code, EDA_TRUNCATED (+4), will be generated and the tuple will be truncated to fit the receiving work area.

Note: The length of a tuple in binary format generally differs from its length in alphanumeric format. The difference is reflected in the alphanumeric and binary tuple size fields of the SCB.

When control returns from EDAFETCH, messages may be available for processing in the message area of the SCB. Server message processing should be performed after each EDAFETCH call.

Boundary Alignment

When binary format is used, the receiving tuple should be aligned on an appropriate word boundary. The API will use the sizeof() method to determine the size of a data type on a particular platform. For example, for floating-point data types a sizeof(float) method is used to retrieve the size used on that platform, and this is used for the alignment. If these alignment requirements are not adhered to by the application, an EDA_TUPLE_MISALIGNED (-16) status will be returned. These alignment checks can be changed using the EDA_VAR_ALIGN4 and EDA_VAR_ALIGN8 environment variables. For example, in the NT environment, if fetches are being issued in binary format, both of these variables might be set to 2. For an OS/400 client, these values might be set to 8 or the appropriate value for the platform.

Note: RISC machines are very sensitive to boundary alignments and may require adjustment to environment variables.

For platforms with no intrinsic alignment requirements, such as a mainframe, setting these variables to 1 turns off API alignment checking.

LOB Data Types

When an EDAFETCH is issued against a row that contains LOB data types, a 16-byte handle will represent the data. Actual LOB data will not be retrieved with the EDAFETCH; instead, an EDAFIELD should be issued to retrieve the data. For more information, see EDAFIELD: Storing Fields in a Designated Data Area and API Data Structures.

Example: Fetching Result Set Data by Rows

long            lRc             =0, 
                lSize,
                lFmtAlpha       =EDA_ALPHANUM;
char            szTup[BUFSIZ];  /* do not exceed tuple buffer size */
                lSize=sizeof(szTup);
if(scb->a_size<lSize)
  lSize=scb->a_size; /* Fetch and display all rows of the result set */
while(!scb->status)
{
    EDAFETCH(scb,szTup,&lSize,&lFmtAlpha);
    if(scb->status!=EDA_SUCCESS)
        lRc=eErrorText(eid,scb->status);
    else
        printMsg("%-*.*s\n",lSize,lSize,szTup);
}
printMsg("Rows Retrieved=%ld\n",scb->count);

Variable Length Character Data

When an EDAFETCH is issued against a row with a variable length character data column, the data for the column will have a 6-byte length value preceding the data (InfoArea -> type will be EDA_V_TYPE_CODE). If an EDAFIELD is not issued against the column, then the length must be removed before the data portion is processed.

EDAFIELD: Storing Fields in a Designated Data Area

How to: Store a Field in a Designated Data Area Example: Fetching Column Information Reference: Usage Notes for EDAFIELD

EDAFIELD stores the specified field of the current row in the designated data area.

Syntax: How to Store a Field in a Designated Data Area

EDAFIELD (scb, column_nbr, data_area, len, fmt)

where:

scb (input, long)

Is a session control block.

column_nbr (input, long)

Is the column number of the field to be placed into the data area.

Note: The number of the first field of any tuple is always one (1). The data formats and lengths of the columns in a result set can be determined by an EDAINFO method call. If the value specified for a column number is greater than the Column Count value in the SCB, the API will return an error status code.

data_area (input, char)

Identifies the work area for receiving the given field.

len (input, long)

Is the length of the receiving work area. The actual length of the field returned can be obtained using EDAINFO.

fmt (input, long)

Is a format indicator. It determines the format in which data will be delivered to the caller's working storage area. Possible values are:

0 The fields within the target tuple expressed in binary format (For more information on binary format, see EDAINFO: Returning a Column Description.)

1 The fields within the target tuple returned in alphanumeric format.

Note: When binary format is used, the receiving field buffer must be aligned on an appropriate boundary.

Reference: Usage Notes for EDAFIELD

For numeric fields, when EDAFIELD is specified using binary format it verifies that the alignment of the data area is compatible with the data type being returned. If the value is not correctly aligned, an error status of EDA_TUPLE_MISALIGNED (-16) will be returned. Most client platforms require that integer and floating-point data types are aligned on 4-byte boundaries and that double- or decimal-data data types are aligned on 8-byte boundaries. (The API uses the sizeof() method to determine which boundary alignment should be used for each data type on a particular platform.) These can be changed using the EDA_VAR_ALIGN4 and EDA_VAR_ALIGN8 environment variables. For example, for an NT client using binary retrieval, these variables might be set to 2 for 2-byte boundary checking.

An error status of EDA_TRUNCATED (+4) will result if the len parameter indicates that the length of the receiving field is insufficient to store the result.

If the value of a field may be null (this information can be retrieved using a call to EDAINFO), EDANULL should be called prior to EDAFIELD. If the field value is null, EDAFIELD should not be issued. Alternatively, a ColInfo array may be allocated using EDASET EDA_VAR_COLINFO_PTR (148). This setting provides the API with an address at which column value information can be stored. The array can then be read to determine whether or not the column value is null. The array should be checked to determine if a value is null before EDAFIELD is called. For related information, see EDANULL: Checking for a Null Value in a Specified Field.

If the column type is EDA_V_TYPE_CODE (variable length character data), then the length portion of the column is removed by calls to EDAFIELD and only the data portion is returned.

Large Object (LOB) data values can be retrieved only for the current row using EDAFIELD. LOBs are fetched in pieces; each EDAFIELD call returning data from an LOB field returns a full buffer and the truncated, EDA_TRUNCATED (+4), status. When the end of the field value is reached, a status code of EDA_SUCCESS (0) is returned.

Once an EDAFETCH or an EDANEXT is called to position to a new row, the remaining LOB data will no longer be available. If EDAFIELD is used to position to another column in the row, the position in a particular LOB is lost and must be completely reprocessed if additional data is required.

For detailed information on the retrieval of LOB data types, see Usage Considerations. For information on the use of the ColInfo array, see API Data Structures.

Example: Fetching Column Information

long   nts=EDA_NULL_DELIM;
long   column_nbr;
long   len=255;
long   fmt=EDA_ALPHANUM;
char   data_area[256];
EDA_INFO_AREA  info;
EDARPC(&scb,"RPC1",&nts,"",&nts);
if (scb.status != EDA_SUCCESS)
{
    printf("Error %ld\n", scb.status);
}
else
{
     for (;;)
     {
        EDANEXT(&scb);
        if (scb.status != EDA_SUCCESS)
        {
           if (scb.status == EDA_END_OF_SET)
           {
              printf("End of set\n");
              return;
           }
           else
           {
               printf("Error %ld\n", scb.status);
               return;
           }
        }
        for (column_nbr=1;column_nbr <= scb.nbrcols; column_nbr++)
        {
           EDAINFO(&scb,&column_nbr,&work_area);
           memset(szInput,0,256);
           EDAFIELD(&scb,&column_nbr,data_area,&len,&fmt);
           printf("Column %ld, name %s, value '%s'\n",
                column_nbr, info.col_name, data_area);
        }
     }
}

EDAFOCUS: Executing a FOCUS Procedure

How to: Execute a Local Stored Procedure Reference: Usage Notes for EDAFOCUS

EDAFOCUS provides the means of sending FOCUS procedure syntax to the server for execution. FOCUS syntax can perform any standard FOCUS operation desired at the server. This includes the ability to return SQL and non-SQL result sets (such as HTML files) to the application.

EDARPC is used to execute a FOCUS procedure syntax stored on the server as a FOCEXEC (.fex), and differs from EDAFOCUS in that with EDAFOCUS the procedure syntax can be stored on the local client computer and sent.

Syntax: How to Execute a Local Stored Procedure

EDAFOCUS (scb, procstring, stringlength)

where:

scb (input SCB handle)

Is a session control block.

procstring (input, char)

Is the string containing the FOCUS syntax to be executed.

stringlength (input, long)

Is the length of the string. If NULL, the string must be a C language \0 terminated string.

Reference: Usage Notes for EDAFOCUS

The FOCUS procedure syntax to be executed is stored in a string as a series of lines. Each line must end with a carriage return/line feed appropriate to the platform on which the application is operating. In a C language program this can be done by inserting \n characters into the string. For example:

Char  * fex = "table file car print car\non table pchold\nEND";

The EDAFOCUS function has the same state table semantics as EDASQL and EDARPC. Upon completion of the call, use EDATEST to test for completion, and then use EDAFETCH or EDANEXT/EDAFETCH to obtain results.

If your request returns an SQL result set, it is retrieved as explained elsewhere. If the format is non-SQL (for example, due to a "pchold format HTML"), the application is presented with an SQL-type result set of one column of appropriate length to hold any row. You can retrieve the complete results using EDAFETCH, checking for the length of each line in the ColInfo block element [1]. It is the responsibility of the application to process the results in an appropriate manner.

To return results to the client, your request must create hold files of type PCHOLD.

EDAINFO: Returning a Column Description

How to: Return a Column Description Example: Using the Issued Request to Obtain Metadata Information Reference: Usage Notes for EDAINFO

EDAINFO returns a description of a single column within a table or result set.

Syntax: How to Return a Column Description

EDAINFO (scb, column_nbr, work_area)

where:

scb (input, long)

Is a session control block.

column_nbr (input, long)

Is the column number.

work_area (output, char)

Is the data storage area that contains the column information. See the Information Block as described in API Data Structures.

Reference: Usage Notes for EDAINFO

Issue an EDAINFO call for each column in a table to obtain a complete definition of the format of either:

• A representative tuple returned after an EDAPREPARE, an EDAEXECUTE, or an EDARPC.
• A complete description of a table returned after an EDADESCRIBE.

To determine the number of columns, refer to the Column Count in the SCB. The SCB Column Count will be updated, indicating the number of times to issue the EDAINFO call when the EDATEST method call returns a value of EDA_SUCCESS (0) for wait_ind.

After EDADESCRIBE is issued, EDAINFO can be issued multiple times to obtain information about each column in a table.

The returned columns are numbered sequentially from left to right beginning with one (1). For table descriptions that are returned as the result of an EDADESCRIBE method call, the numbers correspond to the order of the fields in the table. For descriptions of tuples in a result set, the order corresponds to the columns of the select list issued by the previous EDAPREPARE, EDASQL, or EDARPC method call.

The structure of an output tuple can be determined from a complete collection of EDAINFO work areas identified by the column_nbr parameter.

To employ EDAFIELD, the application must designate sufficient space for storing the field value. The maximum length of a field value can be retrieved using a call to EDAINFO.

To employ EDAFETCH, the application program must designate an area capable of storing an entire tuple. The tuple length may be computed by repeated calls to EDAINFO or accessed from the tuple size field in the SCB.

The fact that a tuple can assume one of two distinct forms is reflected in the EDAINFO work area. For example, the alpha length entry refers to the length of a given field when it is expressed as a printable character string; the binary length entry contains the number of bytes occupied by the field when it assumes its binary form. Similarly, alpha offset is the offset of the field in an alphanumeric tuple and the binary offset is its offset in a binary tuple.

Note: Alphanumeric fields have the same alpha and binary length. The binary length differs from the alpha length only for numeric formats and dates.

The API converts numeric data to its maximal binary representation before delivering it to the caller (all integers, for example, are translated to 4-byte integer values). There are several possible data types for binary fields:

• 4-byte integer
• 4-byte floating-point
• 8-byte floating-point
• 8-byte packed decimal
• 4-byte dates**
• n-byte alphanumeric

Note: **Dates in their binary format contain the number of days from a base date. Since binary date formats must be translated by the application into real dates, it is strongly suggested that the application return dates in alpha format. Alpha format dates are returned as YYYYMMDD. Only dates sent from the server in this format are considered to be dates. Dates sent in any other format (such as YYQ) are considered to be character variables, and cannot be retrieved as binary values.

Field offsets may be rounded up to satisfy the alignment constraints of particular hardware platforms. Binary values may need to be aligned on a 2-byte, a 4-byte, or an 8-byte boundary, depending on the client platform. It is recommended that the rounded field offsets provided by the API be utilized, or that the application calculates its own offsets according to requirements.

For a chart of data type codes and edit options that the EDAINFO call returns, see API Data Structures.

Example: Using the Issued Request to Obtain Metadata Information

/* for this example, assume an RPC that returns a result set */
 
long   nts=EDA_NULL_DELIM;
long   column_nbr;
EDA_INFO_AREA  work_area;
 
EDARPC(&scb,
     "RPC1",&nts,
     "",&nts);
if (scb.status != EDA_SUCCESS)
{
    printf("Error %ld\n", scb.status);
    return;
}
else
{
     for (column_nbr=1;column_nbr <= scb.nbrcols; column_nbr++)
     {
        EDAINFO(&scb,&column_nbr,&work_area);
        printf("Column %ld, name %s\n",
             column_nbr, info.col_name);
     }
}

EDAINIT: Initializing the Server

How to: Initialize the Server Example: Initializing the Connector Environment Reference: Usage Notes for EDAINIT

EDAINIT is the first API call that an application program issues.

Syntax: How to Initialize the Server

EDAINIT (eid, status)

where:

eid (output, long)

Is the application identifier.

status (output, long)

Is a status return code. EDAINIT returns this code to reflect whether or not the server has been initialized correctly. Possible values are:

0 Represents success.

-n Signifies that a fatal error occurred.

+n Is a warning (for a list of status codes, see Status Codes).

Reference: Usage Notes for EDAINIT

EDAINIT creates a processing context, initializes the API, and returns a unique EDA identifier to the caller. The identifier is used to distinguish between simultaneous tasks in the operating system environment. It also represents the scope of a logical unit of work (LUW) once a connection to a server has been established.

• An alternate version of this method, EDAPINIT, is available for applications that are constrained to use nonstandard memory allocation routines, desire a complete callback trace, or require a more sophisticated startup. For more information, see EDAPINIT: Connecting to the Server.
• The API currently limits application programs to a single processing context. There may be no more than one call to EDAINIT during the execution of an application program.
• EDAINIT/EDAPINIT should be the first call made to the API, unless special circumstances require an EDASET to be issued before the API initialization.

Example: Initializing the Connector Environment

long  status;
 
EDA_ID   eid;
 
EDAINIT(&eid, &status);
   if (status != EDA_SUCCESS)
   {
       printf("can't initialize EDA, code %ld\n",status);
   }

EDAINSPECT: Obtaining Information on the API

How to: Obtain Information on the API Example: Retrieving the Number of Server Nodes in the ODIN.CFG File Reference: Usage Notes for EDAINSPECT

EDAINSPECT returns the values of the internal variables that either describe or control the behavior of the API.

Syntax: How to Obtain Information on the API

EDAINSPECT (eid, scb, setting, value, status)

where:

eid (input, long)

Is the EDA application identifier. The EID address defines the scope of the variable when the setting is global.

scb (input, long)

Is a session control block. The SCB address defines the scope of the variable when the setting is local.

setting (pointer)

Specifies the number of the variable to be inspected. The setting parameter tells the API what variable to address. For a list of valid setting codes, see Environment Variables.

value (output, long or void)

Identifies the field in which to store the value of the variable.

status (output, long)

Is a status return code. Possible values are:

0 Represents success.

-n Signifies that a fatal error occurred.

+n Is a warning.

Reference: Usage Notes for EDAINSPECT

If any one of the parameters passed to EDAINSPECT is incorrect, an error will be returned.

The status field of the referenced SCB is not modified by EDAINSPECT.

Example: Retrieving the Number of Server Nodes in the ODIN.CFG File

long  lServerCount;
long setting, value, status;
 
char * szServers;
 
setting=EDA_VAR_SERVERCOUNT;
 
EDAINSPECT(&eid,NULL,&setting,&value,&status);

EDANEXT

How to: Position to the Next Row Example: Using EDANEXT to Retrieve a Result Set Generated From a Prepare Reference: Usage Notes for EDANEXT

EDANEXT advances the cursor to the first or next row in the result set. An EDA_END_OF_SET (+5) status code indicates that every row of the result set has already been processed.

Syntax: How to Position to the Next Row

EDANEXT (scb)

where:

scb (input, long)

Is a session control block.

Reference: Usage Notes for EDANEXT

EDANEXT and EDAFIELD are typically used together as an alternative to EDAFETCH. EDANEXT is a "fetch" into system storage. It positions the cursor but does not return any data. EDAFIELD returns a single field from the row made current by EDANEXT but does not advance the cursor. The methods are designed for applications that must extract both binary and alphanumeric information from the columns of result sets.

Note: EDAFETCH causes an internal EDANEXT to be issued. Therefore, use of EDANEXT explicitly with EDAFETCH retrieves only every other row.

You can use EDAINFO and EDANULL to obtain information about fields in the current row.

When control returns from EDANEXT, messages may be available for processing. The SCB type field will indicate the existence of a message in the SCB. Once this message is processed, the message pending indicator should be analyzed to determine if there are further messages to process. Each subsequent message can be placed in the SCB from the message queue using EDAACCEPT. (For more information, see EDAACCEPT: Accessing Queued Messages From a Server.)

For more code examples, see EDAEXECUTE: Initiating a Prepared SQL Request and EDAFIELD: Storing Fields in a Designated Data Area.

Example: Using EDANEXT to Retrieve a Result Set Generated From a Prepare

/*edaprepare_and_edanext_sample  */
{
    long   nts=EDA_NULL_DELIM;
    long   est1=1;
    long   est2=1;
    long   parm=1;
    long   precision=0;
    long   scale=0;
    long   endparm=1;
    long   dtype=EDA_A_TYPE_CODE;
    long   lIndex;
    long   sth;
    long   lFieldLen=255;
    long   howToGet=EDA_ALPHANUM;
    char   szInput[256];
    EDA_INFO_AREA  info;
 
    EDAPREPARE(&scb,&sth
 
                    "select name from syscols when tabname=?",
                    &nts);
 
    if (scb.status != EDA_SUCCESS)
    {
       printf("Error %ld\n", scb.status);
    }
    else
    {
       EDAUSING(&scb, &sth,
                &parm,           /* parameter number */
                (EDACPTR)"car",  /* string of value to pass to EDA */
                &nts,            /* length of vlu string holding param */
                &dtype,          /* EDA datatype */
                &len,            /* precision */
                &scale,          /* scale of numeric parameter */
                &endparm);
       if (scb.status < EDA_SUCCESS)
       {
           return;
       }
 
       EDAEXECUTE(&scb, &sth,
                    &est1,&est2,
                    "", &nts);
 
         for (;;)
         {
            EDANEXT(&scb);
            if (scb.status != EDA_SUCCESS)
            {
               if (scb.status == EDA_END_OF_SET)
               {
                  printf("End of set\n");
                  return;
               }
               else
               {
                  printf("Error %ld\n", scb.status);
                  return;
            }
            }
            memset(szInput,0,256);            EDAFIELD(&scb,&column_nbr,data_area,&len,&fmt);
            printf("column name '%s'\n",   data_area);
         }
    }
}

EDANULL: Checking for a Null Value in a Specified Field

How to: Check for a Null Value in a Specified Field Example: Checking If the Value of the Column Is NULL Reference: Usage Notes for EDANULL

EDANULL checks whether the field specified by column_nbr in the current tuple is a null value.

Syntax: How to Check for a Null Value in a Specified Field

EDANULL (scb, column_nbr, null_ind)

where:

scb (input, long)

Is a session control block.

column_nbr (input, long)

Is the column number.

null_ind (input, long)

Is a null indicator. Possible values are:

0 The field is not null.

1 The field is null.

Reference: Usage Notes for EDANULL

If a column instance contains a null value (the application can verify this using EDAINFO), EDANULL should be called prior to EDAFIELD. If this returns a value of 1, the EDAFIELD should not be called.

An alternative to using EDANULL is the ColInfo array, which also provides information on whether or not a column value is null. To use this, an EDASET of EDA_VAR_COLINFO_PTR (148) must be issued by the application to provide an address for storing the ColInfo array. For more information on the use of the ColInfo array, see API Data Structures.

Example: Checking If the Value of the Column Is NULL

long  null_ind;
 
if (info.can_be_null)
{
   EDANULL(&scb
      , &column_nbr,
      , &null_ind
      );
 
      if (null_ind == EDA_IS_NULL)
   {
      ...  set up to return NULL ...
   }
}
else 
   {
      EDAFIELD(&scb,&colummn_nbr....
   }

EDAPINIT: Connecting to the Server

How to: Initialize and Set Up Callbacks Example: Using EDAPINIT

EDAPINIT is a specialized form of EDAINIT enabling the application to pass callbacks and some settings to the API during its startup phase. You MUST use EDAPINIT if you intend to supply a memory callback. The API needs memory to initialize, and will use the callback if supplied. Otherwise, standard memory services are used.

EDAPINIT adds four parameters to EDAINIT: a count of the number of operations to be performed and three array addresses. The array addresses point to the start of array count attributes; parallel elements of the arrays represent a single operation such as a callback or an EDASET value. All parameters are passed by reference.

Syntax: How to Initialize and Set Up Callbacks

EDAPINIT (eid, pcount, pcb_type, proutine, pcb_block, status)

where:

eid (output, long)

Is the application identifier.

pcount (input, long)

Is the number of callbacks supplied or sets provided.

pcb_type (input, long)

Is the address of an array containing callback types or EDASET setting.

proutine (input, long)

Is the address of an array of callback routine addresses or null for set value.

pcb_block (input, long)

Is the address of an array containing callback block pointers or the set value.

status (output, long)

Is the status return code. Possible values are:

0 Represents success.

-n Signifies that a fatal error occurred.

+n Is a warning.

Example: Using EDAPINIT

The following code is a demonstration routine to show EDAPINIT.

This demo sets up threading, tracing, and other options in a single pass.

               :
               :
 
 
#include "eda.h"
 
/* external reference to my EDA tracing callback                       */
EDA_APIENTRY  edatrace( EDAPTR( struct EDA_CALLBACK_BLOCK )pECB  );
 
/* EDASET variables for the 8 trace levels                             */
static int trace_name[8] =
{
    EDA_VAR_TRACE_LVL1,
    EDA_VAR_TRACE_LVL2,
    EDA_VAR_TRACE_LVL3,
    EDA_VAR_TRACE_LVL4,
    EDA_VAR_TRACE_LVL5,
    EDA_VAR_TRACE_LVL6,
    EDA_VAR_TRACE_LVL7,
    EDA_VAR_TRACE_LVL8
};
/* a little macro to make PINIT setup easier                           */
#define PINITSET(thing, val) pTypeArray[setcount] = thing; \
                        pValArray[setcount] = (long)val;   \
                        setcount++
 
int  DemonstratePINIT(EDA_ID * peid)
{
    int   doingTrace=0;   /* set ON if any traces wanted */
    long  lResult;
    int   i;
 
    EDA_ECALLBACK      pfnCallback ;
 
#define MAX_PINIT  16   /* how many possible array elements            */
 
    long pTypeArray[MAX_PINIT] = {0};
    EDA_ECALLBACK pRtnArray[MAX_PINIT] = {0};
    long pValArray[MAX_PINIT] = {0};
 
    long setcount = 0;  /* how many array elements have I used?        */
 
    /* now start to set up the EDAPINIT arrays                         */
    PINITSET(EDA_VAR_AUTOLOCK,1);     /* turn on threading             */
    PINITSET(EDA_VAR_NO_FRAGMENT,1);  /* fast memory manager           */
    PINITSET(EDA_VAR_NO_MPLEX, 1);    /* turn off multiplexing         */
 
 
    /* make the eda callback                                           */
 
    pTypeArray[setcount] =EDA_CB_TRACE ;
    pfnCallback =
        ( EDA_ECALLBACK ) edatrace ;  /* see callback example          */
    pRtnArray[setcount] = pfnCallback;
    setcount++;
 
    /* setup trace levels as needed by looking into cfg file info      */
    for (i=0; i<8; i++)
    {
        if (DoIWantTraceLevel(i))
        {
            doingTrace = 1;
            PINITSET(trace_name[i],1);
        }
    }
    if (doingTrace)
    {
        PINITSET(EDA_VAR_TRACE,1);
    }
 
    EDAPINIT(peid, &setcount, (long *)pTypeArray,
             pRtnArray, (void *)pValArray, &lResult);
    return(int) lResult; /* let caller handle the errors               */
}

EDAPREPARE: Preparing an SQL String for Execution

How to: Prepare an SQL String for Execution Example: Binding Parameters With EDAPREPARE and EDAEXECUTE Reference: Usage Notes for EDAPREPARE

EDAPREPARE prepares the given SQL string for subsequent execution and returns a statement identifier (sth) to the application program. The statement-a prototype SELECT, INSERT, DELETE, or UPDATE request-may contain an unspecified number of parameter insertion points, represented by question marks.

Once the EDAPREPARE has been executed the resulting status code should be checked before issuing the next command (EDAUSING or EDAEXECUTE). If the status indicates that the prepare was unsuccessful, the EDAEXECUTE should not be issued.

Note: EDAPREPARE cannot be used in an asynchronous environment or with a transaction adapter.

Syntax: How to Prepare an SQL String for Execution

EDAPREPARE (scb, sth, statement, slength)

where:

scb (input, long)

Is a session control block.

sth (output, long)

Is a statement identifier.

statement (input, char)

Is an SQL statement string.

slength (input, long)

Is the length of the statement string in bytes.

Reference: Usage Notes for EDAPREPARE

The server performs statement preparation and checks the syntax of the SQL request. Providing there are no errors, the server retains the request for subsequent execution. Having completed the prepare step, the server returns all applicable diagnostic messages and result set information to the client.

Upon successful execution of the EDAPREPARE method, the status and error fields of the controlling SCB will be EDA_SUCCESS (0) and will contain a unique statement identifier. A zero status code means that the statement string has been successfully transmitted to the server, not that the statement itself is necessarily correct. Errors detected by the server will become apparent when the application program attempts to execute the statement or describe its output. The API permits the user to invoke EDAINFO one or more times following an EDAPREPARE call to map the format of a result set before it is actually produced.

It is recommended that an EDAPREPARE call be followed by an EDATEST and/or an EDAINFO. These calls will cause any processed messages to become available in the SCB. These messages may indicate the success or failure of the prepare at the server. If the SCB is not checked for messages after an EDAPREPARE, these messages may be lost upon execution of the next method call.

EDAPREPARE, unlike EDASQL, which prepares and executes SQL requests as a single unit, must be used in conjunction with EDAEXECUTE. If parameter markers are used in the prepare statement, EDAUSING must be used to provide the parameter information and values. Issuance of an EDAEXECUTE after a failed prepare will result in an EDA_EXECUTE_NOT_PREPARED (-25) status.

Example: Binding Parameters With EDAPREPARE and EDAEXECUTE

/*edaprepare_and_edanext_sample                                     */
    long   nts=EDA_NULL_DELIM;
    long   est1=1;
    long   est2=1;
    long   parm=1;
    long   len=0;
    long   scale=0;
    long   endparm=1;
    long   dtype=EDA_A_TYPE_CODE;
    long   column_nbr;
    long   sth;
    long   FieldLen=255;
    long   fmt=EDA_ALPHANUM;
    char   data_area[256];
    EDA_INFO_AREA  info;
 
    EDAPREPARE(&scb,&sth,
                    "select name from car where country=?",
                    &nts);
 
    if (scb.status != EDA_SUCCESS)
    {
        printf("Error %ld\n", scb.status);
    }
else
    {
      EDAUSING(&scb, &sth,
               &parm,             /* parameter number               */
              (EDACPTR)"ENGLAND", /* string of value to pass to EDA */
              &nts,               /* length of vlu string holding param*/
              &dtype,             /* EDA datatype                   */
              &len,               /* precision                      */
              &scale,             /* scale of numeric parameter     */
              &endparm);
      if (scb.status < EDA_SUCCESS)
      {
          return;
      }
      EDAEXECUTE(&scb, &sth,
                    &est1,&est2,
                    "", &nts);
for (;;)
         {
            EDANEXT(&scb);
            if (scb.status != EDA_SUCCESS)
            {
               if (scb.status == EDA_END_OF_SET)
               {
                  printf("End of set\n");
                  return;
               }
               else
               {
                  printf("Error %ld\n", scb.status);
                  return;
               }
            }
            memset(data_area,0,256);
            EDAFIELD(&scb,&column_nbr,data_area,&FieldLen,&fmt);
            printf("column name '%s'\n",   data_area);
         }
    }

EDAQUIT: Terminating Result Set Processing

How to: Terminate Result Set Processing Example: Using EDAQUIT Reference: Usage Notes for EDAQUIT

EDAQUIT instructs the API to attempt termination on the processing of the current result set. EDAQUIT releases the resources associated with the current result set, possibly before all of its constituent rows have been fetched. This method returns an EDA_SUCCESS (0) status in the SCB if at least one result set remains in the output stream; otherwise, it returns an EDA_END_OF_TRAN (7).

Syntax: How to Terminate Result Set Processing

EDAQUIT (scb)

where:

scb (input, long)

Is a session control block.

Reference: Usage Notes for EDAQUIT

The Quit All option may be used to alter the behavior of EDAQUIT. When the Quit All variable, EDA_VAR_QUIT_ALL, is zero (0) (the default), EDAQUIT proceeds as described in Terminate Result Set Processing. When it is one (1), EDAQUIT abandons the entire output stream without searching for another result set. This feature is provided so resources may be relinquished quickly in a crisis. As a convenience, the API resets the Quit All variable to zero (0) immediately before returning from EDAQUIT. Therefore, the Quit All behavior must be issued before each EDAQUIT request intended to use this behavior.

The API executes an implicit EDAQUIT when an EDASQL, EDARPC, EDADESCRIBE, or EDAPREPARE call is issued on an established SCB. This causes the API to abandon the remainder of the output stream, even if it contains one or more unprocessed result sets. EDAQUIT should be invoked explicitly only to abandon a result set before all of its members and associated messages have been processed, or to allow a second result set from an RPC to be processed.

You can control the amount of data delivered to the client after an EDAQUIT. For details on controlled data transfer and the SLIM parameter, see Advanced Usage Considerations. In addition to the enhanced EDAQUIT behavior provided by controlled data transfer, a Query Interrupt option is provided. This option allows the API to cancel a task running on the server by establishing a separate thread. To invoke Query Interrupt processing whenever EDAQUIT is called, this feature must be set to ON at the server. See your server documentation for details.

Example: Using EDAQUIT

{
     /* quit the complete result set                            */
     long  action= 1;
     long  value= EDA_VAR_QUIT_ALL;
     long  status;
     EDASET(&eid,&scb,&setting,&value,&status);
 
     EDAQUIT(&scb);
}

When successful, EDAQUIT sets the SCB status to EDA_SUCCESS (0) if another result set remains to be processed, or to EDA_END_OF_TRAN (7) if no other result set remains to be processed. The provided sample code shows a subroutine that returns true, false, or error, depending upon whether the application needs to process a subsequent result set.

Note: EDAQUIT can be issued following receipt of EDA_END_OF_SET (5) by EDAFETCH or EDANEXT. In this case, the EDAQUIT applies to the immediately completed result set. In this way, EDAQUIT can properly check for the presence of a second result set following completion of retrieval for the first result set. EDAQUIT is required to process multiple result sets from a single call.

int IsAnotherAnswerSet(EDAPTR(EDA_ID) peid, EDAPTR(EDA_SCB) pscb) {
int       rc;
 /* use EDAQUIT to position to the next result set, if any */ EDAQUIT(pscb);
if (pscb->status == EDA_SUCCESS)
rc = 1;
else if (pscb->status == EDA_END_OF_TRAN)
rc = 0;
else
{
printf("Error checking for another result set: %ld",pscb->status); rc=(-1);
}
return rc;
}

EDARPC: Executing a Remote Stored Procedure

How to: Execute a Remote Stored Procedure Example: Issuing a Stored Procedure Reference: Usage Notes for EDARPC EDARPC Calls to the Server

EDARPC executes a remote stored procedure that is accessible to the server.

Syntax: How to Execute a Remote Stored Procedure

EDARPC (scb, rpcname, rlength, parms, plength)

where:

scb (input, long)

Is a session control block.

rpcname (input, char)

Is a fully-qualified name of the stored procedure.

rlength (input, long)

Is the length of the string referenced by rpcname.

parms (input, char)

Is a string containing the input variables for the procedure.

plength (input, long)

Is the length of the parameter string.

Reference: Usage Notes for EDARPC

Stored procedures are used to:

• Execute complex SQL queries.
• Execute non-SQL queries.
• Allocate files dynamically.
• Set up a customized processing environment for subsequent SQL method execution.
• Invoke external programs.

Stored procedures may be written using any combination of Dialogue Manager procedure language (TABLE, SQL, SQL Passthru, or FOCUS syntax). The input variables for the procedure must be coded according to the specifications of Dialogue Manager (variable=value, variable=value,...). If the Dialogue Manager variables are positional, (&1, &2,) they can be passed to the procedure, in order, without identification (value,value,...), by using commas as delimiters.

The EDARPC method supports parameter strings of up to 32K. However, use of long variable values may be subject to usage limitations within the stored procedure. For example, a variable substitution for a Dialogue Manager command line will still be subject to the maximum width of a command line (80 bytes on MVS, 132 on others). Large input values may be used as input to an external subroutine, or the parms parameter string may contain a number of smaller, comma-delimited variables.

Reference: EDARPC Calls to the Server

Remote procedure calls may return a result set to the client application. For this reason, EDARPC, like EDASQL, may be followed by a call to EDAINFO or EDAFETCH. Should either of these methods be invoked, the API will return an error status of EDA_NO_FIELD_INFO (+2) if there is no result set.

Remote procedures may be used as the mechanism for calling external programs. The calling of an external program is processed as if it were a subroutine of the procedure.

In the server, stored procedures that exist in a relational DBMS may also be invoked. For a detailed treatment of how client programs and remote procedures interact, see Usage Considerations. For details on the usage of remote procedure calls, see the iWay Stored Procedures Reference manual.

There is an alternative to using EDARPC for calling remote stored procedures within an RDBMS. You can use EDASQL with EXECUTE by using SQL Passthru. (This can only be used with an RDBMS that supports EXECUTE as a means of calling a shared procedure.)

Controlled data transfer using the SLIM parameter does not apply to EDARPC requests in the server.

See the iWay Stored Procedures Reference manual for information on using and coding stored procedures.

Example: Issuing a Stored Procedure

long  = EDA_NULL_DELIM;;
 
   EDARPC(&scb
      "tablist"
      ,&rlength,         /* take name of RPC as C-string */
    "",plength;          /* no parameters                */
 
   if (scb.status != EDA_SUCCESS)
   {
    return scb.status)
   }
   else ...

EDASERVERS: Returning Server Names in a Synchronous Environment

How to: Return Server Names in a Synchronous Environment Retrieve a List of Synchronous Server Nodes Example: Retrieving a List of Server Nodes

EDASERVERS returns an array of eight-character server names in a synchronous environment so an application can programmatically decide which server to connect to or allow a user to see a list of servers to choose from. The call attempts to return every available synchronous server name from the connector communications configuration file (ODIN.CFG). If the buffer is not large enough to accommodate the entire list, the list will be truncated and a status of EDATRUNCATED (4) will be returned.

Note: EDASERVERS will only contain a list of synchronous servers.

Syntax: How to Return Server Names in a Synchronous Environment

EDASERVERS (eid, bfr, bfrlen, status)

where:

eid (input, long)

Is the EDA application identifier.

bfr (input, char)

Is the work area receiving the server list.

bfrlen (input, long)

Is the length of bfr (described above).

status (output, long)

Is the status return code. Possible values are:

0 Indicates this method executed successfully.

4 Is a warning status to indicate a truncated result.

Procedure: How to Retrieve a List of Synchronous Server Nodes

You should allocate a buffer area sufficiently large to store all server names known to the system. The Count variable is provided to make this possible. The application program proceeds as follows:

1. Call EDAINSPECT to determine how many synchronous servers are present.

2. Allocate a suitable buffer area based on this information.

3. Invoke EDASERVERS.

If this procedure is followed, truncation will not occur.

Note: To retrieve a full list of both synchronous and asynchronous servers, the EDABROWSE method must be used.

Example: Retrieving a List of Server Nodes

long setting=EDA_VAR_SERVERCOUNT;
long value, status, bfrlen;
 
char szTemp[10];
char * bfr;
 
EDAINSPECT(&eid
   ,NULL
   ,&setting
   ,&value
   ,&status
   );
 
bfrlen = 8 * value;                       /* length of server string   */
 
   if (!value)
{
      printf("EDA can't detect servers.\n");
      return(FALSE)
}
bfr = calloc(1,(int)lTemp);
 
EDASERVERS(&eid
   ,bfr
   ,&bfrlen
   ,&status);
 
   if (status != EDA_SUCCESS)
      {
       printf("EDA can't detect servers.\n");
       return(FALSE);                     /* add an error message here */
      }
 
   for (i=0; i<value; i++)
      {
       memcpy(szTemp,bfr,8);
       szTemp[8]='\0';
       printf("Server %d is %s\n", i, szTemp);
       bfr+=8;
      }

EDASET: Changing the Values of Internal Variables

How to: Change the Values of Internal Variables Example: Enabling Tracing Reference: Usage Notes for EDASET

EDASET may be used to change the values of certain internal variables.

Syntax: How to Change the Values of Internal Variables

EDASET (eid, scb, setting, value, status)

where:

eid (input, long)

Is the EDA application identifier. The EID defines the scope of the setting for global variables.

scb (input, long)

Is a session control block. The SCB address defines the scope of the setting for local variables.

setting (input, long)

Specifies to the API what variable is to receive the value parameter. For valid setting codes, see Environment Variables.

value (input, long)

Identifies the value to which the variable will be set.

status (output, long)

Is the status return code. Possible values are:

0 Represents success.

-n Signifies that a fatal error occurred.

+n Is a warning.

Reference: Usage Notes for EDASET

EDASET does not alter the status field of the referenced SCB.

If any of the parameters passed to EDASET are incorrect, an EDA_BAD_PARM_VAL (-15) status code will be returned.

Example: Enabling Tracing

blong  setting= 1;
long  value= EDA_VAR_TRACE;
long  status;
EDASET(&eid,&scb,&setting,&value,&status);
if (status != EDA_SUCCESS)
{
   printf("Failed to set trace on, cause %ld\n",status);
}

EDASQL: Passing an SQL Statement to the Server

In this section: Asynchronous Connection How to: Pass an SQL Statement to the Server Example: Issuing an SQL Request in C Reference: Usage Notes for EDASQL Manifest Constants for the Execute Parameter Default Attributes

EDASQL passes the given SQL statement to the server specified by the SCB connection.

In the synchronous environment, EDASQL causes the statement to be issued immediately. In the asynchronous environment, the EDASQL method call may be used to:

• Build an asynchronous request.
• Execute the SQL statements in the stack.
• Retrieve a result set once the ULOB identifier has been determined using EDABROWSE.
• Cancel the SQL statements in the stack.

Syntax: How to Pass an SQL Statement to the Server

EDASQL (scb, statement, slength, est1, est2, dpassword, dlength, execute)

where:

scb (input, long)

Is a session control block.

statement (input, char)

Is an SQL statement string to be passed to the server. This may contain the following:

• A pointer to an SQL statement or part of an SQL statement.
• NULL, if the application wishes to transmit the buffer that was previously built by EDASQL or EDARPC requests.
• The binary ULOB identifier (Answerset Large Object [ALOB] locator) returned from EDABROWSE in the content column.

slength (input, long)

Is the length of the statement, a 4-byte string.

For an SQL statement, this is the length of the string in the statement, up to a maximum of 32,000. For an ALOB, the length value is 16.

est1 (input, long)

The only valid value is 0.

est2 (input, long)

The only valid value is 0.

dpassword (input, char)

Is a string containing the data password. (The string can be null if none is required.) It enables the API to take advantage of row or field-level security, should that be offered by the targeted DBMS using EDA DBA functionality.

dlength (input, long)

Contains the length of dpassword string in bytes.

execute (input, long)

Is a code to indicate what is to be done with the information in the statement.

Possible values are:

0	SQL statement should be added to the stack for execution.
1	SQL statement will be executed immediately.
2	Cancel all SQL statements in the stack.
3	Execute against ALOB. For more information, see Messaging and Queuing.

For synchronous execution, the only valid value is 1.

For asynchronous execution, you can build or append to an SQL statement, execute (transmit) an SQL statement, cancel the current build, or retrieve an ALOB.

For ALOB processing, the value of the statement is a binary ULOB identifier that the API retrieves from the message queue.

Reference: Usage Notes for EDASQL

When the server returns control to the caller, the status field in the controlling SCB indicates whether or not the method executed correctly. A nonzero status code might indicate, for example, that one of the parameters in the calling sequence was incorrect or that the call was issued in an invalid context. An EDA_SUCCESS (0) status code indicates that no errors of this sort were detected.

An EDA_SUCCESS (0) status return from the API indicates that the SQL request was passed to the server without incident, not that the request itself was processed correctly by the server. The API performs its method locally and returns at once to the application program so it can continue working while remote database operations take place. The success or failure of the DBMS operation is reflected in the SCB when a transition to the 'information available' state takes place.

From the programming point of view, this means that SQL requests must be checked twice, upon submission to the API and upon expected receipt of a result set.

The EDASQL method can be used to execute individual SQL statements directly, or to build a number of SQL statements that will then be sent together to the server. Use the execution flag to indicate which method of execution is to be used.

Note: Values other than 1 are only available in an asynchronous environment.

Asynchronous Connection

Once a connection is established to an asynchronous server, an application designed to transmit query messages invokes many of the same methods that a synchronous application does. However, there are slight differences in the parameters that are used. Some Messaging applications may be required to transmit many EDASQL statements-possibly very large, complex, and interspersed with one or more EDARPC requests-in a single Unit of Work. This can be achieved using EDASQL with the execute parameter.

Applications wishing to create messaging Units of Work containing more than a single SQL statement or a complex SQL statement exceeding 32,000 bytes, can build their Units of Work by issuing the EDASQL method call with the execute parameter set to zero. For more description see Manifest Constants for the Execute Parameter. When the query is built and the Unit of Work is complete, the application can invoke EDASQL with the execute parameter set to one (1) to transmit the request.

Note: In an asynchronous context, EDARPC is a build method. It must be followed by an EDASQL method call with the statement parameter set to NULL if the RPC is to be the last statement in the Unit of Work.

The caller invokes EDASQL to pass an SQL query to a synchronous or an asynchronous server. Although it may be possible to build and send an entire SQL request in a single step, many applications will find it more convenient to assemble long messages from component parts and then send them.

Reference: Manifest Constants for the Execute Parameter

Applications may compile messages by manipulating the execute parameter. API supports three manifest constants for this purpose.

Manifest Constant	Description
EDA_EXECUTE_BUILD	0 When execute=0, EDASQL appends the data described by the statement and slength parameters to the system message buffer, but it does not transmit the message.
EDA_EXECUTE_EXECUTE	1 When execute=1, EDASQL appends the data described by the statement and slength parameters to the system message buffer, transmits the message, and reinitializes the system buffer. A transmitted message represents a single Unit of Work.
EDA_EXECUTE_CANCEL	2 When execute=2, EDASQL reinitializes the system message buffer. This value enables the caller to cancel a partially constructed message.

Reference: Default Attributes

Application programs may invoke EDASQL to initiate a Unit of Work by setting the execute parameter to EDA_EXECUTE_EXECUTE. In this case, the system assigns the following default attributes to the outgoing message:

Attribute	Value
classType:	EDA_MSGTYPE_QUERY
priority:	EDA_UOWPRI_NORMAL
timeout:	Not supplied; defaults to normal setting.
szClass:	"EDA REQUEST"
szModule:	"EDADEM"
szEntry:	"EXECEDA"
szComment:	None, unless user-supplied.

An EDASQL method call executed in an asynchronous context can obtain access to the returned attachments (ALOBs) from a previously issued query. To process a result set returned by a remote server, the application first calls EDACONNECT, referencing the asynchronous server name. Using EDABROWSE, the application can then determine the ALOB locator that represents a result set from a Message table instance.

Note: The ALOB locator is the handle for the UOW that created the query. The Content column of the message entries that contain the ALOB locator will have a ClassType =2.

The application can then execute the EDASQL call supplying the ALOB locator of the desired result set in the statement parameter. The following manifest constant should be used for the execute parameter to access the result set (length in the statement parameter will be set to eight [8]; the execute parameter will be set to four [4]):

Manifest Constant	Description
EDA_EXECUTE_ALOB	4 When execute=4, EDASQL accesses the returned ALOB data from the message queue.

Having done this, the application can process the resulting ALOB, which may contain standard metadata, result sets, and SCB messages. The process here is the same as if performed in a synchronous context.

Example: Issuing an SQL Request in C

EDASQL (&scb1
   , statement
   , &slength
   , &est1
   , &est2
   , dpassword,
   , &dlength
   , &ONE
   );
if (scb1.status == 0)
{
   /*The query has been sent to the server.                   */
   /*Wait for the server to respond.                          */
   EDATEST (&scb1, NULL);
   if (scb1.status == 0)
 
   {
   /* The query produced a valid result set. Process it.      */
      ...
   }
¯
   else
   {
      /* The server rejected the SQL request. Failure at this
      level indicates that something is wrong with the query. */
      ...
   }
   }
else
   {
   /* API/SQL rejected the function Failure at this level
   could be caused by a communications error in the program. */
   ...
   }

EDATERM: Terminating a Connection

How to: Disconnect From the Server Example: Terminating a Connection Reference: Usage Notes for EDATERM

EDATERM signals the end of the context represented by the given identifier. In response to this method, the API disconnects all active client/server connections established on behalf of the identifier (EID) and relinquishes all related resources.

Syntax: How to Disconnect From the Server

EDATERM (eid, status)

where:

eid (input, long)

Is the application identifier.

status (output, long)

Is the status code, reflecting whether or not the server has been terminated correctly. Possible values are:

0 Represents success.

-n Signifies that a fatal error occurred.

+n Is a warning.

Reference: Usage Notes for EDATERM

EDATERM returns the application program to an uninitialized state. No method other than EDAINIT/EDAPINIT may be applied in the uninitialized state.

Application programs should always call EDATERM before terminating. This ensures that resources are released immediately.

If active connections exist within the API environment when EDATERM is called, they will be disconnected by the API.

Example: Terminating a Connection

EDATERM (&eid, &status);

EDATEST: Determining If the Server Is Ready to Return Output

How to: Determine If the SCB Is Waiting for Output Reference: Usage Notes for EDATEST

EDATEST determines whether or not the given SCB is waiting for output or if data has been returned (and then sets the output parameter appropriately).

It is also possible to call an EDATEST so it will wait for output on a particular SCB.

When data is present, EDATEST scans the output, possibly queuing messages for subsequent processing, and positions to the first row of the result set. (For information on message processing, see EDAACCEPT: Accessing Queued Messages From a Server.) It then returns control to the caller.

Note: EDATEST, like EDAQUIT, is limited to ALOB processing in an asynchronous environment and cannot be used to test a server connection, to check if a Unit of Work has been completed, or to see if data or messages are available. There is no limitation in a synchronous environment.

Syntax: How to Determine If the SCB Is Waiting for Output

EDATEST (scb, wait_ind)

where:

scb (input, long)

Is a session control block.

wait_ind (input/long, output)

Is a status indicating whether or not there is any output to be processed. Possible values are:

0 Output from the server is available for the given SCB. When EDATEST returns this indication, the user can continue with EDAINFO, EDAFETCH, or EDANEXT.

1 The API is waiting for the output.

If NULL is passed as an input parameter value for wait_ind, EDATEST will wait for output to be available for the specified SCB.

Reference: Usage Notes for EDATEST

If a no wait_ind parameter is supplied, EDATEST returns immediately to the calling application with a status indicating whether or not there is any output to be processed. EDATEST responds with a zero (0) if there is output available from the server, or one (1) if it is still waiting for a server response on that SCB. If a wait_ind of NULL is received by the API, it will then wait until output is available for the given SCB or until it times out.

When control returns from EDATEST, messages may be available for processing. If there are message(s) available, the message type indicates the SCB will be set to one (1) and the message read area will contain the first message. The existence of queued messages can be verified by checking the message pending field in the SCB. Use EDAACCEPT to move queued messages to the SCB (for more information, see EDAACCEPT: Accessing Queued Messages From a Server).

The status field of the given SCB will be zero (0) upon successful completion of this method; otherwise, it will contain an error code.

Note:

• If an EDATEST is issued for a request that returns no data, the API will respond with a wait_ind of zero (0). This behavior prevents the calling application from unnecessarily looping around EDATEST. A subsequent call to EDAFETCH will cause the API to respond with the appropriate end-of-set indicator, EDA_END_OF_SET (+5).
• EDA_NO_FIELD_INFO (+2) will be returned from EDATEST for requests that provide result sets that lack defining metadata.
• EDATEST may be called at any time, with one exception-an EDATEST should not be issued if a request to the server has not been made.

EDAUSING: Furnishing Parameters to Prepared SQL Statements

How to: Furnish Parameters to Prepared SQL Statements Example: Constructing an Isolated Three-Parameter List Sending Parameters to a Statement That Has Already Been Prepared Reference: Usage Notes for EDAUSING

EDAUSING provides a way to furnish parameters to prepared SQL statements. When invoked after an EDAPREPARE method, it places a single value into the current parameter list for the statement identified by sth. The method may be called as many times as required to fill one or more parameter lists with data.

Note: EDAUSING cannot be used in an asynchronous environment.

Syntax: How to Furnish Parameters to Prepared SQL Statements

EDAUSING (scb, sth, parm, vlu, vlulen, dtype, len, scale, endparm)

where:

scb (input, long)

Is a session control block.

sth (input, long)

Identifies the statement.

parm (input, long)

Is a parameter number. Individual parameter lists may be batched for block submission to the server. The parm argument specifies parameter position (1, 2, 3, ..., n). The parm and endparm parameters control parameter list construction.

vlu (input, char)

Is a character string in the application program containing the parameter value. Since the vlu parameter must eventually become a binary value before being used by the server, the caller-who alone knows what should be done with the string-is required to supply instructions for converting it. The content size of vlu is 32K.

vlulen (input, long)

Is the length of the vlu. Parameters may not be omitted, but they may be null. Null values are represented by zero (0) length strings. If value is null for any non-character field (integer, decimal, etc.), then vlulen needs to be 4 characters ('NULL').

dtype (input, long)

Is the data type code indicating required conversion.

len (input, long)

Is the length of the actual field, not the value being input.

scale (input, long)

Is the number of decimal places.

endparm (input, long)

Is the end of a parameter list indicator. Possible values are:

0	Adds a parameter and continues building the current list.
1	Adds a parameter and closes the current list.
2	Cancels the current list.
3	Cancels all lists pending against the given statement identifier.

Note: The purpose of the dtype, len, and scale arguments is to specify the form that the data will take when SQL parameter substitution occurs. For a definition of available data type codes, see API Data Structures.

Reference: Usage Notes for EDAUSING

The API performs some type checking. The first set of parameters-which must be given in order-establishes a pattern that must be followed by subsequent parameter lists. (That is, if parameter two in the first list is a double-precision floating-point number, parameter two in every list must be a double-precision floating-point number.)

The API requires that the number of parameters in a statement, or a multiple thereof, be present by the time a prepared SQL statement is executed. If EDAEXECUTE is invoked before a final parameter has been supplied for the current list, the system will reject the method. Avoiding such contingencies requires some care on the part of the application programmer.

If the variable type is character (EDA_VAR_A_TYPE_CODE), CLOB (EDA_VAR_CLOB_TYPE_CODE) or a BLOB (EDA_VAR_BLOB_TYPE_CODE), the vlu parameter must point to the start of the object. The entire object must be in memory at the time that the EDAEXECUTE is issued, and the area of memory pointed to be vlu must be occupied by the object at the time of EDAEXECUTE.

Example: Constructing an Isolated Three-Parameter List

An isolated three-parameter list can be constructed as follows:

EDAUSING (&scb1, &sth, &ONE, &p1, &p1_len, &p1_typ, &p1_tlen,
&p1_scale, &ZERO);
if (scb1.status != 0) process_the_error();
EDAUSING(&scb1, &sth, &TWO, &p2, &p2_len, &p2_typ, &p2_tlen,
&p2_scale, &ZERO);
if (scb1.status != 0) process_the_error();
EDAUSING(&scb1, &sth, &THR, &p3, &p3_len, &p3_typ, &p3_tlen,
&p3_scale, &ONE);
if (scb1.status != 0) process_the_error();

In this code example, the last endparm value, "ONE," closes off the list. To submit multiple parameter lists, the application program is required to complete each list in the group. For more information, see Sending Parameters to a Statement That Has Already Been Prepared.

Example: Sending Parameters to a Statement That Has Already Been Prepared

building = TRUE;
 
while (building)
{
   /* Prompt the user for 1st parameter value (p1).           */
   ...
 
   EDAUSING(&scb
          , &sth
          , &ONE
          , &vlu
          , &vlulen
          , &dtype,
          , &len
          , &scale
          , &ZERO
          );
   if (scb1.status != 0) process_the_error();
   /* Prompt the user for 2nd parameter value (p2).            */
   EDAUSING(&scb1
          , &sth
          , &TWO
          , &vlu
          , &vlulen
          , &dtype,
          , &len
          , &scale
          , &ZERO
          );
   if (scb1.status != 0) process_the_error();
   /* Prompt the user for final parameter value (p3).          */
   EDAUSING(&scb1
           , &sth
           , &THR
           , vlu
           , &vlulen
           , &dtype,
           , &len
           , &scale
           , &ONE
           );
   if (scb1.status != 0) process_the_error();
   /* Does user wish to continue? If not, set building = FALSE. */
   ...
}

In this code example, every recursion of the loop generates a complete three-element parameter list. When the program exits the loop, it is in a position to invoke EDAEXECUTE.

EDAWAIT: Suspending the Application Program Until Output Arrives (DEPRECATED)

How to: Suspend the Application Program Until Output Arrives Reference: Usage Notes for EDAWAIT

EDAWAIT waits for the occurrence of a communications event and suspends the application program until it senses the arrival of output from an active server.

Note: EDAWAIT cannot be used in an asynchronous environment. EDAWAIT is not recommended for use.

Syntax: How to Suspend the Application Program Until Output Arrives

EDAWAIT (eid, timeout, session, status)

where:

eid (input, long)

Is the application identifier.

timeout (input, long)

This parameter can represent a timeout for the wait in number of seconds. If zero (0) is specified, the method will wait indefinitely until an event is received.

session (output, long)

Is a return code that indicates which session, of possibly many, satisfied the wait condition (the value it contains is the same as the session ID field of the relevant SCB).

status (output, long)

Is a status code. Possible values are:

n	When EDAWAIT detects an invalid parameter, it copies a negative error code to the status field and returns immediately to the caller.
0	A communications event (the arrival of data) satisfied the wait condition.

Reference: Usage Notes for EDAWAIT

Note that EDAWAIT is a blocking call, which means it causes the application to wait until a result has been returned. An alternative to using EDAWAIT would be to use EDATEST periodically for an SCB or group of SCBs, while maintaining a timer internally within the application. For an example of how to do this, see Usage Considerations. If EDAWAIT is called when nothing is pending, an EDA_END_OF_SET (5) status will be issued.

If the intention of the wait is to wait for output on a single SCB, the EDATEST should be used with the wait_ind set to NULL. (For details, see EDATEST: Determining If the Server Is Ready to Return Output.)

EDAXCONNECT: Deleting a Connection

How to: Delete a Connection Reference: Usage Notes for EDAXCONNECT

EDAXCONNECT deletes a connection established by an earlier call to EDACONNECT, and releases all resources reserved on behalf of the given SCB. With the successful completion of this method, the status and error fields of the SCB referenced in the calling sequence will be set to zero (0) and no subsequent operations using it (other than EDACONNECT) will be permitted.

Syntax: How to Delete a Connection

EDAXCONNECT (scb)

where:

scb (input, long)

Is a session control block.

Reference: Usage Notes for EDAXCONNECT

SCB identifiers (SIDs) are reused following an EDAXCONNECT call, and all resources associated with the SCB are released.

Note:

• If there are outstanding transactions at this time, they will not be ended until the physical server connection is released. (For example, all SCBs connected to the same server are closed.) Therefore, it is important for the application to ensure that all transactions are completed before EDAXCONNECT is issued.
• Automatic commit occurs at EDAXCONNECT for the connection SCB.

EDAXPREPARE: Releasing All Resources of a Prepare Statement

How to: Release All Resources of a Prepare Statement Reference: Usage Notes for EDAXPREPARE

EDAXPREPARE causes the release of all resources associated with a prepare statement-without ending the current transaction. Once released, the prepare statement will not be available for subsequent execution.

Note: EDAXPREPARE cannot be used in an asynchronous environment.

Syntax: How to Release All Resources of a Prepare Statement

EDAXPREPARE (scb, sth)

where:

scb (input, long)

Is the address of a session control block.

sth (input, long)

Is the statement identifier.

Reference: Usage Notes for EDAXPREPARE

Issuing an EDAXPREPARE causes the API to:

• Send a PURGE of the associated prepare handle to the server, thus releasing resources the server.
• Release local prepare resources, making them available for use with the next prepare request.

Note:

• Local resources were not released. A maximum limit to the absolute number of prepare statements was thus imposed by memory availability.
• Only the number of simultaneously active prepare statements contribute to this limit.