RespondToRequest Method
The RespondToRequest method handles the frame's response to an explicit or simulated end user request.
This method has the following syntax:
integer = RequestManager.RespondToRequest([callingframe = FrameExec]
[, itemvarname = varchar(256)][, info = Object][, request = varchar(65)])
The method identifies the appropriate response (the type of handler to call), checks if the calling frame has such a handler coded and uses it, if so. Otherwise it invokes RequestManager's own built-in handler, if it has one.
The request typically takes the form of a display event (a click or key-press by the end user), or may be simulated in the 4GL code by a posted user event. In such cases the RespondToRequest method is invoked from the event block without parameters; it relies on information available from the triggering field, the frame, and their tagged value settings to determine how to respond and invoke the relevant processing.
Alternatively the method may be invoked with the following parameters providing it with the necessary information:
callingframe
Specifies the frame to which the response is to be made.
Default: the closest frame in the calling sequence
itemvarname
Specifies the name of a variable in the calling frame that references the item (user class object) being displayed.
By default this is assumed to be "this", which is the name used when the frame is based on active_display, and the display is generated using Display from User Class (see the Workbench User Guide). In such frames based on active_display, that name is specified in a macro variable at the top of the frame code and can be changed. If another name is used, the name must be specified using the itemvarname parameter.
info
Specifies additional handler-specific information needed for this response to be handled.
This can be of any complexity, provided it can be passed as a single object reference. The handler must know how to unpack and use this information.
The most convenient format is a taggedvalue object containing one or more items, since both the value and the items will be keyed, making the unpacking simpler and more robust.
request
Specifies the actual request, in the format:
category:action
where the standard categories are "frame", "data", "tbl", and "misc", and the actions are category-specific ones. Specific actions handled by the built-in RequestManager processing include:
• frame: close, resize, initialize, realize, fold, open, insert, delete, cut, copy, paste,
• data: new, open, next, previous, first, last, specified, filter, save, add, amend, delete
• tbl: sort, resize, open, insert, delete, deleteall, hide, unhide, cut, copy, paste, multi, copytable
Most of these are intended for specific use with the active_display template in frames where the display has been generated using Insert, Display from User Class. Their use in other situations is currently unsupported.
Additional categories and actions can be specified in your frame, provided the corresponding procedures and case blocks are added to the frame and the handlers to carry out the action. For sample code to illustrate how this is done, see the following example.
This method returns an integer indicating the status of the call: ER_OK or ER_FAIL.
The following code should be placed after the default code in the active_display template in the Workbench User Guide. It shows how to define a "misc" case.
/*
**~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
** Respond to handling requests for a particular <area>
**~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**
** Anything you define here overrides the default processing provided by
** the built-in handler "RequestManager".
**
** The default "areas" are:
**
** frame
** tbl
** data
** misc
**
** (You may define additional ones by following the same format.)
**
** For any of these areas where you need to overdefine some particular
** case locally:
** - Define the appropriately named procedure (for example, framerequest,
** tblrequest) using the following code format.
** - Define the case or cases you want to customize; all other cases will
** continue to be processed by the RequestManager.
**
** Code should have the following format:
*/
PROCEDURE MiscRequest(
action = varchar(32) NOT NULL;
trigger = FieldObject DEFAULT NULL;
info = Object DEFAULT NULL;
)=
DECLARE
rc = integer NOT NULL;
ENDDECLARE
BEGIN
CASE action OF
/*
** Respond to the request 'misc:tbd'
*/
'tbd': //to be done
{
//tbd - set rc to ER_OK or ER_FAIL to indicate outcome of processing
}
/*
** Pass "misc" requests not defined here over to the built-in handler
*/
default:
{
rc = ER_ROWNOTFOUND;
}
ENDCASE;
RETURN rc;
END;