Call (Imagine function)

Run Imagine code on the Transparency Broker (Imagine class)

[Introduced in Model 204 8.0 βeta]

This method calls code running in the Imagine Transparency broker for the current transaction.

Syntax

[%string =] %(Imagine):Call( name, [payload= string], [globals= boolean], - [globalImages= boolean], [recordMap= boolean], - [stringLists= stringListList], - [dollarLists= dollarListList], - [apsySuffix= string]) Throws BrokerLost, BrokerCallError

Syntax terms

%string	The value returned by the called Imagine function. This could be anything though JSON would be the most convenient format for passing data from Imagine to Model 204.
%(Imagine)	The class name in parentheses denotes a shared method. Call can also be invoked via a Imagine object variable, which may be Null.
name	A string that contains the name of the function to be called in the Imagine broker. The semantics of this value is under the control of the Imagine broker.
payload	A string that contains data passed to the Imagine function. This could be anything though JSON would be the most convenient format for passing data to the Imagine function. Thwe default value for this is an empty string.
globals	A Boolean value that indicates whether global strings ($setg/$getg) should be sent to Imagine. The default value of this argument is false.
globalImages	A Boolean value that indicates whether global images should be sent to Imagine. The default value of this argument is false.
recordMap	A Boolean value that indicates whether a map of (thread-specific) Model 204 record numbers to Imagine file and recordId should be sent to Imagine. This can be useful if one is passing Model 204 record numbers to the Imagine application. The default value of this argument is false.
stringLists	A StringListList (a NamedArraylist of Object Stringlist) whose entries are sent to the Imagine function as named Stringlists. Each Stringlist in the collection is sent together with its NamedArraylist item name, so the called code can refer to each list by name. The default is null (no Stringlists sent). If a Stringlist is bound to a server image via the NAMESAVE image attribute, each item is validated against the image's field-data length, and the image itself is sent so that Imagine can interpret the fields by name. Unbound Stringlists are sent with no image, and each item is sent with its actual length. After the call, Imagine can return updated versions of any subset of the supplied Stringlists, identified by their position (1-based ordinal) in the StringListList. The corresponding target Stringlist is emptied and refilled with the returned items, subject to the same image-binding validation that was applied on the send: items in an image-bound Stringlist must match the image's field-data length. This argument requires Imagine Transparency broker protocol version 4 or later. The list-name feature requires broker protocol version 8 or later; with an older broker, the lists are still sent in order but without their names.
dollarLists	A DollarListList (a NamedArraylist of Fixed) whose entries are $list identifiers sent to the Imagine function as named $lists. Each $list in the collection is sent together with its NamedArraylist item name, so the called code can refer to each $list by name. The default is null (no $lists sent). If a $list is bound to a server image via the NAMESAVE image attribute, each item is validated against the image's field-data length, and the image itself is sent so that Imagine can interpret the fields by name. Unbound $lists are sent with no image, and each item is sent with its actual length. After the call, Imagine can return updated versions of any subset of the supplied $lists, identified by their position (1-based ordinal) in the DollarListList. The corresponding target $list is emptied and refilled with the returned items, subject to the same image-binding validation that was applied on the send: items in an image-bound $list must match the image's field-data length. This argument requires Imagine Transparency broker protocol version 4 or later. The list-name feature requires broker protocol version 8 or later; with an older broker, the $lists are still sent in order but without their names.

Usage notes

In Imagine, a transaction includes both retrieval requests and updating requests.

Because Imagine Transparency files and transactions are automatically kept in synch with the corresponding files in Model 204 any updates in the Model 204 transaction are visible in the Imagine transaction and vice versa.

The stringLists and dollarLists arguments are designed for bulk transfer of structured data to and from the Imagine function in a single call. Stringlists and $lists carry essentially the same payload — a sequence of variable-length byte strings — but appear in User Language code as different types, so the two arguments let the caller use whichever form is more natural in the surrounding code. Mixing the two is allowed: both can be supplied in the same Call.

The pairing of a list with an image binding lets Imagine reach individual fields by name on its side. To use this, declare the bound image with the NAMESAVE attribute and bind the Stringlist (with BindImage) or $list (with $LstImg_Bind) before adding items. Items in an image-bound list must be exactly the image's field-data length; otherwise Call cancels the request with an "Item length mismatch" error. Lists with no image binding are sent as raw variable-length strings.

On return, Imagine may replace the contents of any of the supplied lists. Each returned list is identified by its position in the original StringListList or DollarListList; the target list is emptied first and then refilled with the items returned by the broker. The same image-binding rule applies to the returned items.

Examples

The following example sends a single Stringlist of order rows to an Imagine function and prints whatever items the broker writes back into that list:

%orders is object Stringlist %orderLists is object NamedArraylist of Object Stringlist %result is string len 256 %orders = New %orders:Add('order=1001 qty=2') %orders:Add('order=1002 qty=5') %orderLists = New %orderLists('orders') = %orders %result = %(Imagine):Call('processOrders', stringLists=%orderLists) For %i From 1 To %orders:Count Print %orders(%i) End For

See also

Imagine class	List of Imagine methods	Imagine methods syntax
Notation conventions for methods