Example: Producing a Message From a Remote Procedure Call Describing a Simple Remote Procedure With Result Set Processing |
EDARPC makes it possible for an application program running on a client machine to execute a named procedure residing on servers or accessible from a supported DBMS. Parameters may be passed from the client to the server; data may be passed from the server to the client.
A unit of information returned to the client machine may take the form of a result set or a message. Result sets returned from a remote procedure should be processed in the same way as result sets generated by the server. If an RPC generates multiple result sets, an EDAQUIT is required after each result set before the processing of a subsequent result set can continue.
This section explains how to process messages generated by remote procedures. What follows is intended not to instruct you in the use of the Dialogue Manager language, but to indicate the kind of processing it makes possible. For complete coverage of remote procedure calls, see the iWay Stored Procedures Reference manual.
The Dialogue Manager language is sufficiently general to support a wide variety of requirements, some of which entail returning result sets and some of which do not. A Dialogue Manager routine generates a data stream that may contain messages, a description of the columns of a result set (their data types, size, and so forth), and any number of output rows. When the data stream arrives at the client site, the API scans it, partitions it into its constituent parts, and returns tuples and messages to the client application upon demand.
There are two kinds of messages. One is generated by the server system, the other by remote procedures running within the system. Every message, regardless of its origin, is accessible to the application program being executed on the client machine.
The following procedure is designed to accept two parameters (an account number and an amount) and to generate a message indicating whether or not it was possible to update the amount field of the indicated account record in the database.
-DEFAULT &output = '(UPD0000)';
-TSO RUN UPDPROG, &acct, &amt, &output
-TYPE &output
This procedure may be called using the following code:
rpcname ='UPDATE'
rlength = 6
parms = 'acct=1234619,amt=1204.91', plength = 24
EDARPC(scb,rpcname,rlength,parms,plength);
This procedure establishes default message text and invokes the database updating program, UPDPROG, with two formal parameters, "acct" and "amt." ("Output" represents an output value string to be returned by UPDPROG.) The program attempts to update the database and then returns "(UPD0001)," indicating success or "(UPD0000)," indicating failure. Finally, the Dialogue Manager procedure emits the status information required by the client and terminates the procedure.
Assuming UPDPROG runs to completion, the Connector will receive a single message indicating success or failure. If UPDPROG aborts, the client will receive a server system message to that effect, in addition to the default result, "(UPD0000)."
Not all server application programs require access to every message in the output stream. In the absence of a Remote Procedure Call (RPC), for example, only system messages are present. The most significant system messages are reflected in the SCB automatically. However, programs issuing RPCs may have more stringent requirements.
Two items in the SCB play a crucial role in the implementation of RPCs: the message type field, which distinguishes system messages from user messages, and the message code field, which contains an integer often used to represent a return code. Suppose, for example, an RPC were used to establish a working environment for a series of planned SQL requests. It might, upon termination, issue a message containing only a return value (1 for success, 0 for failure). We can assume that there would be nothing else in the output stream. Thus, if the application program were to issue an EDATEST command at the appropriate time, the API would detect the user-type message and copy the return value into the message code field of the relevant SCB. The client application would then be able to examine the message type and code fields and act accordingly.
The following figure illustrates a flow diagram of the logic required to invoke a simple remote procedure that sends only messages to the client application.
The following figure illustrates a flow diagram of the logic required to invoke a simple remote procedure that sends a result set to the client application.
In the C programming language, the logic depicted in the figure illustrating a simple remote procedure with message processing in Auto Commit would be expressed as follows:
...
EDARPC(&scb1, rpcname, &rlength, parms, &plength);
if (scb1.status == 0)
{
/* The RPC has been issued. Wait for completion. */
scb1 = scb_addr_of(ses_id);
EDATEST(&scb1, NULL);
if (scb1.status != 0)
{
/* Error processing logic. */
}
if (scb.msg_type)
{
/* Return code received from server. */
if (scb1.msg_code == RPC_OK)
{
/* Return code indicates success. */
...
}
else
{
/* Bad return code. */
...
}
}
else
{
/* No message returned. */
}
}
Many RPCs can be satisfied by the exchange of a parameter list and a single return value. The server makes it possible for remote procedures to return a result set supplemented by any number of messages (limited only by the amount of available memory). The output stream can contain a result set, a return code, and an ad hoc mixture of administrative messages (numeric codes plus readable text).
The following loop would permit the application program to perform work locally while the remote procedure executes.
Wait_ind = TRUE;
while (wait_ind == TRUE)
{
/* Do something useful. */
...
/* Check if done */
EDATEST(&the_scb, &wait_ind);
}
/* Process the result set. */
Database Access Considerations
Servers or "databases" may exist at a variety of levels and on a variety of platforms. The API determines the capabilities of a particular server at connect time. If a request that is not supported by the server is sent, the API will report it by means of an EDA_UNAVAILABLE_FUNCTION (-19) return code.
Servers can also be configured as a Relational Gateway to a particular DBMS. In this scenario, the SQL passed to the server will be passed directly to the DBMS. Therefore, it is limited by the restrictions imposed by that DBMS. Some DBMSs, for example, do not support the SQL PREPARE request. Others do not utilize the standard parameter marker ("?") to delimit parameters within a request. A full-method server provides a standard interface across multiple DBMSs, but a Relational Gateway does not. The EDAINSPECT for EDA_VAR_DEFAULT_ENGINE provides information on the engine being utilized by servers. For information on variables, see Environment Variables.
| iWay Software |