Asynchronous request object handle

Maintains the status of an asynchronous request running on an OpenEdge application server or Web service.

Syntax

async-request-handle [ : attribute ]

async-request-handle

A handle variable that references an asynchronous request object. This object is instantiated when you execute an asynchronous remote procedure using the RUN statement specified with the ASYNCHRONOUS option. You can get the handle value by doing one of the following:

• Use the ASYNCHRONOUS SET option on the same RUN statement that instantiates the asynchronous request.
• Reference the LAST-ASYNC-REQUEST attribute on the server handle for the OpenEdge application server where the request is running. To ensure that you are referencing a specific request, you must reference the attribute after the associated RUN statement executes and before you instantiate another asynchronous request on the same OpenEdge application server connection.
• You can also locate the asynchronous request handle by walking the chain between the FIRST-ASYNC-REQUEST and LAST-ASYNC-REQUEST attributes of the associated server handle. Search on the PROCEDURE-NAME attribute of each request handle to identify the specific request.

attribute

An attribute of the asynchronous request handle.

Attributes

Events

Notes

• When the OpenEdge application server completes and returns the results of the asynchronous request associated with this handle, the client application that executed the request receives the PROCEDURE-COMPLETE event. This event triggers execution of the associated event procedure (if specified) in the context of an input-blocking statement, such as the WAIT-FOR statement, UPDATE statement, or a PROCESS EVENTS statement.
• You can access this handle anywhere in the client application that executes the associated request. However, it is especially useful for reference in the event procedure for the asynchronous request. In the associated event procedure, you can access this handle as the value of the SELF system handle.
• When checking for ERROR and STOP conditions raised from the application server in a PROCEDURE-COMPLETE event procedure, check the ERROR-OBJECT and STOP-OBJECT attributes (instead of the STOP and ERROR error attributes) to handle these conditions. For example:

  IF VALID-OBJECT(SELF:ERROR-OBJECT) THEN DO: // Perhaps display the error MESSAGE SELF:ERROR-OBJECT:GetMessage(1) VIEW-AS ALERT-BOX. END. /* That's probably sufficient unless you are using STOP-AFTER. It could also possibly be LockConflict, though that would normally be handled on the server side. If both are possible, check the type to know what it is. */ ELSE IF VALID-OBJECT(SELF:STOP-OBJECT) THEN DO: IF TYPE-OF(SELF:STOP-OBJECT, Progress.Lang.StopAfter) THEN . . . END.

  Note that references to all objects that implement the Progress.Lang.Error interface are returned using the ERROR-OBJECT attribute, including Progress.Lang.StopError. The STOP-OBJECT attribute returns only stop object references for Progress.Lang.Stop or one of its subclasses, such as Progress.Lang.StopAfter in the example.

• For more information on asynchronous requests, the PROCEDURE-COMPLETE event, and asynchronous request handles, see the Progress Application Server for OpenEdge: Application Migration and Development Guide and OpenEdge Application Server: Developing AppServer Applications.

See also

RUN statement, Server object handle, SELF system handle, WAIT-FOR statement (ABL only)