Progress
Open Client
Developer’s Guide
Passing TEMP-TABLE And TABLE-HANDLE Parameters
4GL procedures can pass TEMP-TABLE or TABLE-HANDLE parameters to an AppServer. This is a convenient and efficient way to pass relational data between the client and the AppServer code. The Open Client environment provides the same capability using result sets. A result set is an object that provides access to relational data in an Open Client application. An Open Client passes a 4GL TEMP-TABLE parameter using a result set parameter that is mapped to the specified TEMP-TABLE.
TABLE–HANDLE parameters allow the transfer of TEMP–TABLE objects between Open Clients and the AppServer without requiring a complete, static definition of the table on each side of the transfer (as with TEMP-TABLE parameters). The TEMP-TABLE and TABLE-HANDLE parameters also use a result set parameter.
INPUT TEMP-TABLE and TABLE-HANDLE Parameters
When the client application passes a static TEMP–TABLE as an INPUT parameter, the client provides an object that contains data for the table. For a Java client, this object is a ja
va.sql.ResultSet
and for an ActiveX client, this object is an ADO, DAO orIClientTempTable
. In this instance, the proxy already knows the schema (metadata) for the table. Therefore, the client application does not need to supply the schema.When the client application passes a TABLE–HANDLE parameter, the proxy does not know the schema (metadata) for the table. The client must provide both the schema and the data t for the TABLE–HANDLE parameters. If the application does not provide metadata, the method call fails.
For more information about how metadata is provided to the a specific client type, see:
- Java Open Clients — "Programming Java Clients"
- ActiveX Open Clients — "Programming ActiveX Controller Clients"
OUTPUT TEMP-TABLE and TABLE-HANDLE Parameters
An application uses the same model when working with an OUTPUT TABLE–HANDLE parameter or a TEMP–TABLE parameter, by having the client pass a holder object. For Java this is a
ResultSetHolder
, and for ActiveX, this is an instance ofProTempTable
.On return from the method, the holder has access to the output result set data and the metadata. In Java, the data is returned through a
ResultSet
object from which a metadata object can be obtained. In ActiveX, the data and metadata is returned throughProTempTable
.Although the model is the same, TABLE–HANDLEs are different in that they can be Unknown or undefined. As a result, you must ensure that the client can handle these cases.
INPUT-OUTPUT TEMP-TABLE and TABLE-HANDLE Parameters
INPUT–OUTPUT TEMP-TABLE and TABLE-HANDLE parameters are a combination of INPUT and OUTPUT parameters. For Java, the input
ResultSet
is stored in aResultSetHolder
and the holder is passed as the parameter rather than passing theResultSet
directly. For ActiveX, the input side is the same for both INPUT and INPUT–OUTPUT because the client must set theDataSource
forProTempTable
in both instances.TEMP-TABLE and TABLE-HANDLE Call-back Sequence
Open Client support for TEMP-TABLE and TABLE-HANDLE parameters depends on a call-back mechanism used by both the client application and the proxy code. Therefore, either the client application or the proxy must always requests data from the opposite side, rather than having the opposite side set or send the data. As a result, the client application calls back to the proxy for output parameters and the proxy calls back to the client application for input parameters.
Table 4–2 shows how the call-back sequence works when passing an INPUT TEMP-TABLE or TABLE-HANDLE parameter.
Table 4–3 shows how the call-back sequence works when passing an OUTPUT TEMP-TABLE or TABLE-HANDLE parameter.
Table 4–4 shows how the call-back sequence works when passing an INPUT-OUTPUT TEMP-TABLE Or TABLE-HANDLE parameter.
The input result set object is an object that is written by the Java or ActiveX client application. This can also be a standard result set object available from each respective environment as the result of an SQL query (a
java.sql.ResultSet
in Java, or a DAO or ADORecordset
object in Visual Basic). In contrast, the output result set object is always provided by the generated proxy.Input Result Sets
For input (or the input side of input/output parameters), all the data must be available before the proxy method call is made. The methods of the input result set object (that feed the input data to the proxy) may not call any other AppServer methods on the proxy that share the same connection. If they do, an error results.
Output Result Sets
On output (or the output side of input/output parameters), the result set is not necessarily finished being transmitted to the client by the time the method call returns. The proxy buffers data for the result set and makes it available sequentially to the client.
This process of buffering an output result set from the AppServer and making it sequentially available to the client is called streaming. An AppServer connection that is streaming a result set is said to be in a STREAMING state. This STREAMING state remains in effect until all data has been received by the client or the result set is closed.
When the method containing an output result set parameter returns, the client gets an object that it can use to call back for more data. However, the client cannot make any other AppServer method calls while the connection is in the STREAMING state. To determine whether a connection is in the streaming state, you can invoke the
_isStreaming()
method (Java client) or theOC_IsStreaming()
method (ActiveX client) for any proxy object using the connection.While both types of Open Clients handle output result sets using streaming, you must make special provisions for streaming in a multi-threaded Java client. For more information on managing streaming in Java clients, see the information on multi-threaded applications in Programming Java Clients."
Order of Access For Output Result Sets
This stream of data can be thought of as a one-directional tape. It must be read in sequence and there is no way to get the same data more than once or to go backwards. When getting the data from a single TEMP-TABLE or TABLE-HANDLE the data for each row and each field in that row must be requested in sequence and no request can be repeated. Also, if there is more than one output TEMP-TABLE or TABLE-HANDLE parameter for a method, they must be perused in sequence. Data from the first must be completely fetched or the result set closed before any data can be retrieved from the second TEMP-TABLE or TABLE-HANDLE parameter, and so forth. It is possible however to skip data. For example, you can fetch the value of field 1 and then the value of field 10. However, you cannot then reverse and obtain the values for fields 2 through 9.
Closing Output Result Sets
To close an output result set, you generally execute the close method on the result set as appropriate for your Java or ActiveX Open Client. However, you can also close the result set by executing the release method on all proxy objects running over the same AppServer connection that returned the result set. Releasing the last such AppObject, SubAppObject, or ProcObject, disconnects the Open Client from the AppServer and closes any output result sets that it provides.
For more information on the close and release methods for your type of Open Client, see for:
- Java Open Clients — "Programming Java Clients"
- ActiveX Open Clients — "Programming ActiveX Controller Clients"
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |