Call handler

Purpose: Call another handler within the same process.

call-handler <request path> [ return-code  <return code> ] \
    [ set-param ( <name> [ = <value> ] ) , ... ] \
    [ get-param ( <name> [ type <type> ] [ default-value <value> ] ) , ... ]

Copied!

Calls another handler within the same request in the same process. You can call any handler within the same application. "Calling a handler" means executing it solely within the context of the top handler currently running; no before-handler or after-handler will execute for the called handler.

<request path> is the request path served by the handler being called. It can be a string variable or a constant.

Use set-param and get-param to pass parameters between the caller and callee handlers.

You can obtain a <return code> from the called handler <request path> by using "return-code" clause. See return-handler on how to return a code (i.e. a number value) from <request path> handler.

call-handler uses the same high-performance hash table used by a request to route requests by name; if <request path> is a constant string, then a hash table lookup is performed only once for the life of the process and all subsequent calls use a cached address of the request handler.

Parameters

You can set parameters before call-handler executes using "set-param" clause, which behaves the same way as if those parameters were set just before call-handler; see set-param for more details. You can also get parameters after call-handler executes using "get-param" clause, which behave the same way as if those parameters were to be obtained just after call-handler; see get-param for more details. For example:

call-handler "/handler" set-param inp=1, var="some data" get-param out, new_var type number

Copied!

is the same as:

set-param inp=1, var="some data"
call-handler "/handler"
get-param out, new_var type number

Copied!

Call depth

There is a limit on the call depth, including recursion in order to prevent application and system stability issues. See get-app and set-app with "stack-depth" clause for details and on how to change the defaults.

Examples

The following example demonstrate calling a call-handler twice, and also using its output inline in the caller. An input parameter is passed to it, and an output obtained:

Copy to file "callsub.rim":

%% /callsub public
    //
    // First call to call-handler
    //
    // Set input for call-handler
    set-param inp = "some string"
    (( s
    call-handler "/sub/service"
    ))
    // Get output from call-handler
    get-param out type string
    @<<print-out s>> with output [<<print-out out>>]

    //
    // Second call to call-handler
    //
    // Set input for call-handler called as inline code
    set-param inp = "new string"
    (( s
    @Output: <<call-handler "/sub/service">>
    ))
    // Get output from call-handler
    get-param out type string
    @<<print-out s>> with output [<<print-out out>>]
%%

Copied!

And in "sub/service.rim" file (meaning file "service.rim" in subdirectory "sub"):

%% /sub/service private
    @This is sub!
    get-param inp
    (( out
    @got input: <<print-out inp>>
    ))
    set-param out = out
%%

Copied!

Create and build an application:

rim -k subhandler
rim -q

Copied!

Run it:

rim -r --req="/callsub" --exec --silent-header

Copied!

The output:

This is sub! with output [got input: some string]
Output: This is sub! with output [got input: new string]

Copied!