RPC_CALL

RPC_CALL is a logiccloud extension to Structured Text. It lets a POU invoke a remote procedure — typically an HTTP endpoint exposed through a REST-RPC connection — over the runtime’s internal messaging layer, and map the response straight back into a program variable.

It is not part of the IEC 61131-3 standard library; it is one of the platform standard functions.

Signature

RESULT_VALUE := RPC_CALL(
    TOPIC          := 'my-connection',     // STRING  — target connection
    COMMAND        := 'https://api.example.com/v1/measure',  // STRING — endpoint
    PARAMS         := requestStruct,        // ANY     — request payload
    TIMEOUT        := T#5S,                 // TIME    — max wait
    FALLBACK_VALUE := defaultResult,        // ANY     — returned on any non-success
    ASYNC          := FALSE,                // BOOL    — sync vs async
    RESULT         => callResult            // INT     — status code (output)
);

Parameter	Type	Direction	Meaning
`TOPIC`	`STRING`	in	Name of the target connection (see mapping).
`COMMAND`	`STRING`	in	The endpoint to invoke within that connection.
`PARAMS`	`ANY`	in	The request payload passed to the remote call.
`TIMEOUT`	`TIME`	in	Maximum time to wait for the response (sync mode).
`FALLBACK_VALUE`	`ANY`	in	Value returned when the call does not succeed. Its type determines the return type of `RPC_CALL`.
`ASYNC`	`BOOL`	in	`FALSE` = synchronous (wait for result), `TRUE` = fire-and-forget.
`RESULT`	`INT`	out	Status code — see the result-code table.

The return value of RPC_CALL has the same type as FALLBACK_VALUE. On success it carries the (cast) remote response; on any failure it carries FALLBACK_VALUE unchanged, so a call is always safe to assign.

How TOPIC and COMMAND map

RPC_CALL does not address a URL directly. It publishes a request onto the messaging layer; every configured connector inspects it and the matching one services it:

TOPIC selects the connection. It is matched (case-insensitive, whitespace-trimmed) against a connection’s Name. For a REST-RPC connection named weather-api, pass TOPIC := 'weather-api'.
COMMAND selects the endpoint. For REST-RPC it is matched against the endpoint’s full URL (the connection Base URL + the endpoint Path). A connection-level handler ignores commands that resolve to one of its own declared endpoints, so COMMAND should name the specific endpoint you want to call.

If no connector recognises the TOPIC/COMMAND pair (e.g. a typo, or the connection is not deployed), the request is simply never answered and the call ends in -2 (failed / no connector) or -1 (timeout).

See REST-RPC connections for how to configure the Name, Base URL, endpoint Path, authentication, headers and payload mapping.

Synchronous vs asynchronous

Synchronous (ASYNC := FALSE) — the call blocks the scan until the response arrives or TIMEOUT elapses. The return value and RESULT reflect the actual outcome (0 on success, or a negative error code). Use this when the program needs the remote result before continuing.
Asynchronous (ASYNC := TRUE) — the request is dispatched and the function returns immediately with RESULT := 0 and the FALLBACK_VALUE as its return value. The real response is delivered out-of-band and does not flow back into this RPC_CALL return. Use this for fire-and-forget notifications where you do not need the answer inline.

Result codes

RESULT is an INT; 0 means success and every negative value is a distinct failure mode. The return value holds FALLBACK_VALUE for any non-zero code.

`RESULT`	Name	Meaning
`0`	Succeeded	Call completed; the return value holds the remote response. (Also returned immediately for an async dispatch.)
`-1`	Timeout	No response within `TIMEOUT`.
`-2`	Failed	The call failed — no connector handled the `TOPIC`/`COMMAND`, the request was invalid, or the remote call errored.
`-3`	Cancelled	The request was cancelled, e.g. the runtime is shutting down / stopping.
`-4`	Suspended	RPC is suspended — the runtime is in an update wave; the request is rejected without being sent.
`-5`	Cast error	A response arrived but could not be converted to the type of `FALLBACK_VALUE` (return type mismatch).

Settings and behavior that affect RPC_CALL

Timeout

TIMEOUT bounds how long a synchronous call waits. On expiry the call returns FALLBACK_VALUE with RESULT := -1. The underlying connector may also apply its own per-endpoint timeout (REST-RPC endpoints default to 15000 ms) — the effective wait is the shorter of the two.

Update-wave suspension

During a deployment / update wave the runtime suspends RPC processing. While suspended, any RPC_CALL returns immediately with RESULT := -4 (suspended) and the FALLBACK_VALUE; the request is not dispatched.

Worked example

Call a REST-RPC connection named weather-api, endpoint https://api.example.com/v1/temperature, with a 3-second timeout and a sane fallback, then act on the status code:

VAR
    request   : ST_WeatherRequest;   // mapped to the endpoint request payload
    temperature : REAL := -999.0;    // FALLBACK_VALUE -> also the return type
    callResult  : INT;
END_VAR

request.city := 'Berlin';

temperature := RPC_CALL(
    TOPIC          := 'weather-api',
    COMMAND        := 'https://api.example.com/v1/temperature',
    PARAMS         := request,
    TIMEOUT        := T#3S,
    FALLBACK_VALUE := -999.0,
    ASYNC          := FALSE,
    RESULT         => callResult
);

CASE callResult OF
    0:   ;                       // success: use `temperature`
    -1:  diag := 'RPC timeout';
    -2:  diag := 'RPC failed / no connector';
    -4:  diag := 'runtime updating, retry later';
ELSE
    diag := 'RPC error';
END_CASE;