Building Distributed
Applications
Using the Progress AppServer


4GL for Programming AppServer Client Procedures

Table 5–1 lists the 4GL elements that are either valid only for accessing an AppServer connection or have special application in AppServer client programming. The remaining sections in this chapter explain how to use these elements.

Table 5–1: 4GL for Programming AppServer Procedures
4GL Element
Description
ASYNC-REQUEST-COUNT
1) An INTEGER attribute on the server object handle that returns the number of active asynchronous requests submitted to this server. 2) An INTEGER attribute on the procedure handle that returns the number of currently outstanding asynchronous requests for this procedure. Can be non-zero only if the PROXY and PERSISTENT attributes are both set to TRUE.
Asynchronous Request Object Handle
A type of handle that maintains the status of an asynchronous request in a 4GL client application. This handle provides methods and attributes that allow you to check the status of a remote procedure (internal or external) that is called asynchronously.
CANCELLED
A LOGICAL attribute on the asynchronous request object handle that indicates if the asynchronous request was cancelled using either the CANCEL-REQUESTS( ) method or the DISCONNECT( ) method on the associated server handle.
CANCEL-REQUESTS( )
A method on the server object handle that raises a STOP condition in the context of the currently running asynchronous request and purges the send queue of any asynchronous requests that have not been executed.
CLIENT-CONNECTION-ID
A CHARACTER attribute on the server object handle that returns the connection ID for the AppServer connection associated with this server handle.
COMPLETE
A LOGICAL attribute on the asynchronous request object handle that indicates if the asynchronous request is completed and its result is processed on the client.
CONNECT(
[ connection-parameters ]
[ , userid ]
[ , password ]
[ , appserver-info ] )
A method on the server object handle that connects and associates an AppServer instance with the server handle.
CONNECTED( )
A method on the server object handle that indicates if an AppServer is currently connected and associated with the server handle.
CREATE SERVER server-handle
A statement that creates a server object handle and stores it in a HANDLE variable.
DEFINE INPUT PARAMETER parameter
A statement for defining INPUT parameters within an event procedure. Each INPUT parameter must correspond to an OUTPUT or INPUT-OUTPUT parameter of the associated asynchronous remote procedure.
DELETE OBJECT handle
A statement that you can use to delete certain objects, including server objects, and persistent procedures (local and remote), and asynchronous request objects.
DELETE PROCEDURE procedure-handle
A statement that you can use to delete both local and remote procedure objects (persistent procedures).
DISCONNECT( )
A method on the server object handle that disconnects from and removes all reference to the Progress AppServer currently associated with the server handle. Any running or pending asynchronous requests submitted by this client are also cancelled.
ERROR
A LOGICAL attribute on the asynchronous request object handle that indicates that an ERROR condition was returned from the AppServer as a result of processing the request.
EVENT-PROCEDURE
A CHARACTER attribute on the asynchronous request object handle that contains the name of the internal procedure to be run as the event procedure for this asynchronous request.
EVENT-PROCEDURE-CONTEXT
A HANDLE attribute on the asynchronous request object handle that contains the procedure handle of the active procedure context where the event procedure for this asynchronous request is defined.
FIRST-ASYNC-REQUEST( )
A method on the server object handle that returns the first entry in the list of all current asynchronous request handles for the specified AppServer.
FIRST-PROCEDURE
A HANDLE attribute on the server object handle that returns the first entry in the list of remote persistent procedures running on the connected AppServer.
FIRST-SERVER
A HANDLE attribute on the SESSION system handle that returns the handle to the first entry in the chain of server handles for the session.
FUNCTION ... IN procedure-handle
A statement that declares a user-defined function. When procedure-handle is a proxy persistent procedure handle, the function is defined on the connected AppServer in the specified procedure object.
LAST-ASYNC-REQUEST( )
A method on the server object handle that returns the last entry in the list of all current asynchronous request handles for the specified AppServer.
LAST-PROCEDURE
A HANDLE attribute on the server object handle that returns the last entry in the list of remote persistent procedures running on the connected AppServer.
LAST-SERVER
A HANDLE attribute on the SESSION system handle that returns the handle to the last entry in the chain of server handles for the session.
NEXT-SIBLING
1) A HANDLE attribute on the server object handle that returns the next entry in the list of server handles created for the current Progress session. 2) A HANDLE attribute on the proxy persistent procedure handle that returns the next entry in the list of proxy persistent procedure handles. 3) A HANDLE attribute on the asynchronous request object handle that returns the next entry in the list of asynchronous request handles for asynchronous remote procedures submitted for execution on the same AppServer.
PERSISTENT
A LOGICAL attribute on procedure handles and the THIS-PROCEDURE system handle that is TRUE if the specified procedure is running persistently as a procedure object.
PERSISTENT-PROCEDURE
A HANDLE attribute on the asynchronous request object handle that returns the proxy persistent procedure handle to the remote persistent procedure that contains the internal procedure executed for the specified asynchronous request. If the request is for an external, rather than an internal, procedure, this attribute returns an invalid handle.
PREV-SIBLING
1) A HANDLE attribute on the server object handle that returns the previous entry in the list of server handles created for the current Progress session. 2) A HANDLE attribute on the proxy persistent procedure handle that returns the previous entry in the list of proxy persistent procedure handles. 3) A HANDLE attribute on the asynchronous request object handle that returns the previous entry in the list of asynchronous request handles for asynchronous remote procedures submitted for execution on the same AppServer.
PROCEDURE-COMPLETE
The event returned for an asynchronous request object handle that indicates the associated remote procedure has completed execution and, as a result, causes execution of the specified event procedure as specified by the EVENT-PROCEDURE and EVENT-PROCEDURE-CONTEXT attributes.
PROCEDURE-NAME
A CHARACTER attribute on the asynchronous request object handle that provides the name of the remote procedure executed to instantiate this asynchronous request handle.
PROCESS EVENTS
A statement that you can use to handle any pending PROCEDURE-COMPLETE events for asynchronous requests. You can also use any blocking I/O statement, such as the WAIT-FOR statement.
PROXY
A LOGICAL attribute on procedure handles that is TRUE if the procedure handle is a proxy handle for a persistent procedure running remotely in the context of an AppServer.
QUIT
A LOGICAL attribute on the asynchronous request object handle that indicates a QUIT condition was returned from the AppServer as a result of processing the request.
RUN ... [PERSISTENT ...]
  ON [SERVER] server-handle
  [TRANSACTION DISTINCT]
  [ASYNCHRONOUS ...] ...
The statement that executes an external (remote) procedure on a connected AppServer specified by server-handle, in a transaction that is distinct from the client. With the PERSISTENT option, it instantiates the procedure as a persistent procedure object. With the ASYNCHRONOUS option, the procedure executes asynchronously with respect to the client. This option also optionally specifies the associated asynchronous request handle and event procedure to handle results of the request. If server-handle is the SESSION system handle, the external procedure executes synchronously in the local session.
RUN ... IN procedure-handle
  [ASYNCHRONOUS ...] ...
The statement that executes an internal (remote) procedure on a connected AppServer, where procedure-handle specifies a remote persistent procedure that is instantiated on the AppServer and that defines the internal procedure. With the ASYNCHRONOUS option, the internal procedure executes asynchronously with respect to the client. This option also optionally specifies the associated asynchronous request handle and event procedure to handle results of the request. If procedure-handle is the handle to a local persistent procedure, the internal procedure executes synchronously in the local session.
SELF
A system handle that, in the context of an event procedure, returns the asynchronous request object handle of the completed request for which the event procedure is executing.
SERVER
1) A HANDLE attribute on a remote persistent procedure handle that returns the server object handle to the AppServer on which the specified remote persistent procedure runs. Valid only if the PROXY and PERSISTENT attributes are both TRUE. 2) A HANDLE attribute on the asynchronous request object handle that returns the server handle of the AppServer where this asynchronous request was submitted for execution. If the request is run in the local session (using the SESSION system handle), the attribute is set to SESSION.
Server Object Handle
A type of handle that provides a connection to an AppServer in a 4GL client application. This handle provides server object methods and attributes that allow you to connect and manage an AppServer.
STOP
A LOGICAL attribute on the asynchronous request object handle that indicates a STOP condition was returned from the AppServer as a result of processing the request.
TYPE
1) A CHARACTER attribute on the server object handle that returns the handle type, which is "SERVER" for a server object handle. 2) A CHARACTER attribute on the asynchronous request object handle that provides the handle type, which is "ASYNC-REQUEST" for an asynchronous request object handle
WAIT-FOR ...
A statement that you can use to handle any pending PROCEDURE-COMPLETE events for asynchronous requests. You can also use PROCESS EVENTS or any other blocking I/O statement, such as the PROMPT-FOR statement.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095