Variables

You can create and use variables in during document processing. To use a variable, you can create it from the GUI or CLI or within XSLT or GatewayScript files. All approaches use a set variable type of action that creates the variable in a specific context and assigns a value. You can use variables in most contexts, except PIPE.

You can view the variable values for a transaction with the probe. Edit the service to enable the probe. After you enable the probe and record transactions, you can view variables and their values.

DataPower® processing supports the following distinct variable types. You can define each type in the slash var://URL format or dot notation format.

var://local/variable

Addresses the variable local variable in the default (current) context.

A local variable does not persist beyond the scope of the transaction. A transaction can include both a request component and a response component. A local variable cannot be accessed by any object outside the scope of the transaction. In other words, a service cannot read and use this variable.

A local context XSLT variable can be user-defined or based on an extension variable. Extension variables are not available in GatewayScript.

The following GatewayScript example assigns a local variable with a value from the session input context.

var myinputvar;
try {
  myinputvar = session.input.getVariable('myvar');
  }
catch (e) {
  session.output.write("error: localVariable 'myvar' not found."+e);
}

The following XSLT example transforms the document in the tmp1 context with a stylesheet. The stylesheet is referenced by the stylesheet-1 variable also in the tmp1 context and stores the transformed document in the tmp2 context.
```
xform tmp1 var://local/stylesheet-1 tmp2
```

var://context/context/variable

Addresses the variable context variable in the context named context. The value for the named context must be a single-word string of alphanumeric characters and the - and _ special characters.

A named context variable can be user-defined or can be based on an extension variable. The use of named context variables is the preferred approach. This form decouples the variable from the input and output contexts and allows the variable to be accessed from any action in this transaction.

A named context variable does not persist beyond the scope of the transaction. A transaction can include both a request component and a response component. A named context variable cannot be accessed by any object outside of the scope of the transaction. In other words, a service cannot read and use this variable.

The following example transforms the document in the tmp1 context with a stylesheet. The stylesheet is referenced by the stylesheet-1 variable in the apple context and stores the transformed document in the tmp2 context.

xform tmp1 var://context/apple/stylesheet-1 tmp2

var://service/variable

Addresses the variable service variable that is made available to a DataPower service that is attached to a session.

Many service variables are supported in XSLT and GatewayScript. For example, to use a variable to skip processing by the target, the XSLT form is var://service/mpgw/skip-backside and the GatewayScript form is mpgw.skipBackside. Slash notation refers to the XSLT form, and dot notation refers to the GatewayScript form.

Calls to GatewayScript variables support both forms. A GatewayScript file that uses dot notation uses a two-step process. The first step requires the service-metadata module to hold variables. The second step sets a variable to it value.

var sm = require ('service-metadata');
sm.mpgw.skipBackside = true;

For each variable that GatewayScript supports, the documentation assumes the establishment of access with a require statement (var sm=require ('service-metadata')). You must establish access to service metadata by using a require statement in your code (naming sm or other variable) to manipulate the service variable. The skipBackside variable call uses sm.

A GatewayScript program establishes access to an XSLT service variable by using the slash notation name form in getVar and setVar function calls.

var genPattern = sm.getVar("var://service/wsa/genpattern");

Both forms are listed in the documentation where both are supported. When the GatewayScript name form is not in the list, the GatewayScript form is not supported. GatewayScript checks the data type when a new value is assigned to a service variable. The getter method returns a value with the correct data type.

var://system/context/variable

Addresses the variable system variable that is available in all contexts. System variables, while globally accessible, must be defined within a specified context. System variables persist beyond the scope of request-response processing. When the content of a variable must be read or set outside the scope of request-response processing, use a system variable.

CAUTION:

System variables can introduce unexpected problems. Do not use system variables except under the direction of IBM Support.