Version: 11.0

UBlend components

A UBlend component is an RDMI component that allows you to execute a USoft Blend script by calling a component.

note

You can also execute a sequence of multiple USoft Blend scripts through a single component method, using the same technique as with XSL Stylesheets components. However, with USoft Blend scripts, this is less obviously useful than with XSL stylesheets.

In USoft, UBlend components are typed as .NET components because they use .NET under the hood.

Why would you wrap a USoft Blend script in a component?

This allows you to invent a functional name which makes sense to a user and by which he can execute the script.
The script is easier to deliver because it is an integral part of your application, not an external file or a CLOB value in an application table.
Constraints and other SQL contexts that need to use the script become more compact.
The script automatically participates in tool features that all RDMI components participate in: SQL Objects cross-referencing, Find In Repository, and Object Shopping.

Defining a component for executing a USoft Blend script

To define a component for executing a USoft Blend script:

1. In USoft Definer, from the menu, choose Define, RDMI, dotNet Components, UBlend Components from the Define menu. The "UBlend Components" window opens.

2. Set any name for the component, e.g., PRINT_CLIPBOARD.

3. Paste the USoft Blend script code into the Program Source field. Save work.

4. Press the Check button in the top right corner. In the question box, choose the Yes button.

5. USoft has now generated an API for executing the Blend script in a variety of ways. Assuming that you have specified only 1 Blend script, the methods generated are as follows:

Method Name	Description
BLEND	Executes the Blend script, or all the Blend scripts specified.
BLEND0	Executes the first Blend script specified.*
BLEND2FILE	Executes the Blend script specified, or all the Blend scripts specified, and then writes the result value(s) to a file with the specified filepath.
BLEND2FILE0	Executes the first USoft Blend script specified and then writes the result value to a file with the specified filepath.*
PRINT_CLIPBOARD	Constructor method with the name that you set in the Name field for the component. This method may not may not be apparent in the list of generated methods and is for technical purposes only.

The "0" suffix in the method name is the 0-based index number of the Blend script, i.e, the first Blend script. Typically, you specify only 1 Blend script, in which case the net effect of calling this method is equivalent to calling the same method name without the "0".

tip

You can get the .NET code that USoft has generated by pressing the small 'copy' button immediately to the right of the Program Source prompt. The code is copied to clipboard:

tip

The built-in USCSXSL component underlies this API: which is, in turn, equivalent to:

You can view the signature (the parameter list) of each method in the Parameters box at the bottom of the window.

All BLEND... methods allow you to pass a list of input parameters (the args InListparameter listed). You can use this mechanism to pass values to Blend scripts that expect named input parameters. You can pass parameter values as name-value combinations in the following comma-separated syntax, as shown in Example 2 below:

*... variable, value* [, *variable, value* ... ]
*variable*    ::=    *type*:*name*
*type*        ::=    { string | document }

For each variable, a name and a value is required and a type prefix (followed by a colon) is optional. If you do not specify a type, a string value is expected.

Example 1

This example prints the current content of your clipboard. If the Name of the component is PRINT_CLIPBOARD, and the Program Source for the component is:

<Example xmlns:pc="Processing.Command">
   <pc:value-of select="clipboard:GetText()"/>
</Example>

and the current content of your clipboard is:

**Hello there**

then both these calls:

**INVOKE print_clipboard.blendSELECT print_clipboard.blend()**

yield this result:

<Example>Hello there</Example>

Example 2

This example shows input parameters (read the end of this section for a discussion). If the Name of the component is PRINT_VARIABLES, and the Program Source for the component is:

<Example xmlns:pc="Processing.Command">
   <pc:value-of select="concat( $myvar1, ' ', $myvar2 )"/>
</Example

then both these calls:

INVOKE   print_variables.blend WITH
SELECT   'myvar1'
,        'Hello'
,        'myvar2'
,        'there'

SELECT print_clipboard.blend( 'myvar1', 'Hello', 'myvar2', 'there' )

yield this result:

<Example>Hello there</Example>

As you can see, a USoft Blend script expects input parameters simply by containing variable references. If you prefer to declare expected input parameters at the top of the script, you can use one of the <pc:assign...> directives, for example, you can declare variables with <pc:assign-default>:

<Example xmlns:pc="Processing.Command">
   <pc:assign-default
      myvar1=""
      myvar2=""   />
   <pc:value-of select="concat( $myvar1, ' ', $myvar2 )"/>
</Example>

You can add error handling for mandatory input parameters:

<Example xmlns:pc="Processing.Command">
   <pc:assign-default
      myvar1=""
      myvar2=""   />
   <pc:terminate test="$myvar1=''" msg="Myvar1 must be specified."/>
   <pc:terminate test="$myvar2=''" msg="Myvar2 must be specified."/>
   <pc:value-of select="concat( $myvar1, ' ', $myvar2 )"/>
</Example>

Defining a component for executing a USoft Blend script​

Defining a component for executing a USoft Blend script