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


CANCELLED attribute	COMPLETE attribute	ERROR attribute
ERROR-OBJECT attribute	EVENT-HANDLER attribute	EVENT-HANDLER-OBJECT attribute
EVENT-PROCEDURE attribute	EVENT-PROCEDURE-CONTEXT attribute	HANDLE attribute
INSTANTIATING-PROCEDURE attribute	NAME attribute	NEXT-SIBLING attribute
PERSISTENT-PROCEDURE attribute	PREV-SIBLING attribute	PRIVATE-DATA attribute
PROCEDURE-NAME attribute	QUIT attribute	REQUEST-INFO attribute
RESPONSE-INFO attribute	SERVER attribute	STOP attribute
STOP-OBJECT attribute	TYPE attribute

Events


PROCEDURE-COMPLETE	–

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 or method (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 or method specified for the asynchronous request. In the associated event procedure or method, 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 or method, 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.`

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.

The EVENT-PROCEDURE and EVENT-PROCEDURE-CONTEXT attributes will return the Unknown value (?) if the EVENT-HANDLER-CONTEXT is specified as an object.

ABL Reference