Syntax:
com.ibi.agents.XDSREGAgent
Description:
This service sets one or more Special Registers (SREGs) under program control. The SREGs can be set to any of the supported scopes (Message, Flow, or Thread) and can belong to any defined category (Header, User, or Document).
Setting SREGs above the Message scope requires specification of a lock to avoid race conditions in a multithreading situation.
Parameters:
Parameter |
Description |
---|---|
Type of variable |
Type of variable (headers appear in emitted documents as header values). Select one of the following options from the drop-down list:
|
Scope of variable |
For process flows, scope can be for all nodes or only nodes forward on this edge. Select one of the following options from the drop-down list:
Flow- and message-scoped variables have one shared copy for the entire process flow. Therefore, a change made to the variable will be seen on all parallel paths. Unless various points of the parallel process flows are synchronized, the results that are written to a global variable may leave the variable with an unpredictable value. Flow-scoped variables are deleted at the termination of the process flow (or sub-flow) in which they are declared. If you need a variable to be available to the calling process flow (parent flow) or to subsequent components, such as outlets and emitters, select Message as the scope. Thread-scoped variables are duplicated for each parallel document path, allowing independent manipulation of each copy. After parallel paths converge at a Join object, the value of the thread is undefined. Channel-scoped variables are at the protocol level and can be used in a metric to keep information across workers. Registers with a channel scope require a lock. Server-scoped variables are above the channel level and can keep metrics across the entire server. Registers with a server scope require a lock. |
Lock |
A lock is a name that applies to one or more metrics being updated or referenced as a whole. This allows synchronous values to be retained. For example, if metrics A and B are updated, it is a good practice to keep their settings in the same relationship to one another. You do not want to change them in such a way that metrics A and B are no longer related. |
Automatic evaluation |
Causes contents to be evaluated to hold functions. Select one of the following options from the drop-down list:
To summarize, if you select false, the expression is not evaluated upon storage into the SREG. If you select true, the contents of the SREG are evaluated every time it is retrieved. For expressions that have different results at different times, this offers more functionality than storing the result once (for example, an expression that formats a timestamp saved to an SREG). However, if the Automatic evaluation parameter is set to true for _flatof(), XPATH, or other operations that pertain to the document itself, the result will always be NULL because access to “the document” is not available. |
Call at EOS? |
In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false. |
Edges:
The following table lists the available line edges for the SREG Service (com.ibi.agents.XDSREGAgent).
Line Edge |
Description |
---|---|
OnError |
Error |
OnSuccess |
Success |
OnFailure |
Failure |
OnCustom |
|
Example:
The SREG Service can be used to save a state of the current document or a document specific parameter, such as an XPath value. For example, you need to run a transformation on a document, but also want to capture the document first by saving it in a SREG value. In the event of an error during the transformation, you can provide the original document that caused the error.
The service can be invoked using the typical parameter values, as shown in the following image:
The user-defined parameters pane is where the SREGs must be defined, as shown in the following image:
The SREGs are evaluated in the order they are defined in the pane. Therefore, one SREG can refer to the value in another. For example:
one |
_xpath(/root/coms/@port) |
two |
_sreg(one)+1 |
three |
_sreg(two)+1 |
Evaluation ordering applies only when using a Service object of type SREG Agent in a process flow.
The following SREG types are supported:
Note: Register names must conform to the requirements used for XML element names. The names are further restricted for HDR registers if the register will be used to form a message header for a protocol that itself has restricted character conventions. Use of the namespace designator '.' is supported for registers in which such namespaces are meaningful.