Input output parameters

Input and output parameters to request handlers

Parameters are name/value pairs that are global in scope within a request. The value can be set directly, and obtained in a local variable. The parameters serve a purpose of sharing data between different parts of a request implementation, including as input and output parameters to handlers. Each parameter can be both an input and output parameter.

get-param (either as a standalone statement or as a clause in call-handler and begin-handler) can be used to get

handler's input parameters into its local variables, and
handler's output parameters into caller's local variables.

Similarly, set-param (either as a standalone statement or as a clause in call-handler) can be used to set

handler's input parameters in the caller, and
handler's output parameters.

Global nature with local data

The parameters can serve as a functional equivalent of an "input/output parameter" notion. Note that parameters are of global scope within a single request; however, once obtained with "get-param" in a handler they are stored in local variables which makes them the same as a typical input parameter in many languages (see Types discussion in get-param as to which types are copied by value and which by reference).

The same parameter (i.e. of the same name) can be used in any number of handlers, assuming the type is the same everywhere. The global nature of parameters means their value can be obtained anywhere during the processing of the same request; their values are reset with each new request.

Seamless sharing of data

This approach makes the data sharing within a single request seamless. For instance, using some value several handler calls down no longer necessitates passing this value down via parameters; it can be simply used by name and delivered to a local variable and either changed without affecting the original or update the original. This approach uses the best of enapsulation and data sharing, with less code and more clarity.

The reason for this is to both provide the same input/output parameter paradigm that's omnipresent in most programming languages, and at the same time to facilitate simpler and clearer sharing of data anywhere during the request processing (thus alleviating the need for classic global variables). In addition, it provides for the same treatment of input parameters regardless of whether a handler is called locally or remotely across servers.

Examples

In this example, "set-param" is used to set input parameters "pp1" and "pp2" in call-handler, and "get-param" is used to get those input parameters in begin-handler ("%%" for short). Conversely, "set-param" is used to set output parameters "res1" and "res2" in "/req/sub-req" handler implementation, and "get-param" is used to get the those output parameters in call-handler:

%% /req/sub-req get-param pp1 type number, pp2 type number
    print-out "Input is ", pp1, ", ", pp2 new-line
    set-param res1=pp1+pp2, res2=pp1*pp2
%%

// Call the above /req/sub-req request handler 
%% /req public
    call-handler "/req/sub-req" set-param pp1=10, pp2=20 get-param res1 type number, res2 type number
    print-out "Result is ", res1, " and ", res2 new-line
%%

Copied!

The result in "/req" will be 30 for "res1" variable, and 200 for "res2".

- Getting and setting parameters anywhere
One of the advantages of parameters mentioned above, is the ability to use them anywhere, even when "skipping" encapsulation layers. For example, in this example, the main handler ("/req") is calling subhandler ("/req/sub-req"), which is calling sub-subhandler ("/req/sub/sub-req"), and the input and output parameters can be obtained and set in the sub-subhandler, completely bypassing the subhandler. This illustrates the semantics of parameters - they are not global variables but rather global parameters:

%% /req/sub/sub-req get-param pp1 type number, pp2 type number
    print-out "Input is ", pp1, ", ", pp2 new-line
    set-param res1=pp1+pp2, res2=pp1*pp2
%%

%% /req/sub-req
    call-handler "/req/sub/sub-req"
%%

// Call the above /req/sub-req request handler
%% /req public
    call-handler "/req/sub-req" set-param pp1=10, pp2=20 get-param res1 type number, res2 type number
    print-out "Result is ", res1, " and ", res2 new-line
%%

Copied!