Chapter Fifteen

Extending Tango Functionality

Script and External Actions

The Script action provides an interface within Tango for executing JavaScript code at the server. The script executed can return to Tango a value you can access using Results HTML.

The External action calls an executable invoked using a command line, a Dynamic Link Library (DLL), or a Java class file to perform processing and, if desired, return results. Under Mac OS, the External action can also send a specified Apple Event with parameters to a specified application and retrieve the results, or use Apple Event actions to communicate with applications you write in AppleScript.

This chapter covers the following topics:

• setting up and executing a Script action
• configuring a DLL call or a Java action
• using a command line
• assigning variables to action parameters
• assigning action attributes
• deleting action parameters
• executing an External action.

[back to top]

Executing JavaScript

The Script action provides an interface for executing core JavaScript code at the server. The script executed can return a value to Tango, which is accessible using Results HTML.

Tango is JavaScript 1.2 compatible, meaning it includes the official JavaScript Reference implementation from Netscape, and conforms to version 1.2 of the language.

Note: Tango supports the general purpose core of the language. The objects representing the Web browser and its contents are not supported, because the scripts are executed at the server where these objects do not exist. For your convenience, a JavaScript HTML reference is provided with the Tango HTML help.

Setting Up a Script Action

The JavaScript object and variable scope parameter defines the lifetime of the objects and functions declared in the script. This is a concept similar to the scope of variables in Tango. The drop-down menu has two choices:

• Local (the default) specifies that anything defined in the script can be referenced in another script in the same application file execution.
• Immediate specifies that the objects and functions go away immediately after the action is executed.

For information on using the script text area, see "HTML Editing Window", and "The SQL Query Window".

You enter the text script to be executed in the JavaScript script text area. The script may contain meta tags. All meta tags in the script are substituted before the script is executed.

The script text area functions the same as HTML text editing windows.

When you right click the script text area, the same context sensitive menu for the SQL text area of a Direct DBMS action appears.

Executing a Script Action

Tango Server executes the Script action in a similar way it executes the <@SCRIPT> meta tag.

For more information, see "<@SCRIPT> in the Meta Tags and Configuration Variables manual.

Any value returned by a script is accessible in the Results HTML by using <@COL 1> inside a <@ROWS> block. The action's result set (a 1 x 1 array) is also stored automatically in a local variable, resultSet.

[back to top]

Using an External Action

Setting Up an External Action

The standard External action type is based on the current platform, in this case, DLL. You can also specify Java, command line execution or Apple Event.

From the Type drop-down list, select the type of action you want to execute.

Note: If you specify parameters for one type and then change to another type, Tango attempts to transfer the current parameters to the new type.

See the Tango Enterprise User's Guide (Mac OS) for a description of the Apple Event External action.

This User's Guide gives a description of each type of External action. The DLL, Command Line and Java externals are available if you plan to deploy your application file on Windows. Command Line and Java are available for Unix, and an Apple Event action can only be used with the Mac OS version of Tango Server.

Configuring a DLL Call

To configure a DLL call

1. From the Type drop-down list, select DLL, if it is not already selected.

   The External action editing window for the DLL type appears.

2. In the DLL field, type the fully qualified path to the DLL you want to call, for example,

   C:\Program Files\Tango3\externals\Test.dll.

   This path may contain meta tags.

   ---

   Note: The DLL called by the External action must be written to conform to the API described in Appendix B.

   ---

3. Insert a new parameter row by doing one of the following:
   • From the Edit menu, choose Insert.
   • On the main toolbar, click the Insert icon.

     

   • Right click the parameters area, and choose Insert from the context-sensitive menu that appears.

   A new parameter row appears. The parameters are numbered for easy identification.

   ---

   Tip: You may re-order parameters by dragging them within the list.

   ---

4. In the Value field, type a parameter value.

   Parameter values may include any value-returning Tango meta tags, which are substituted when the action is executed.

Using a Command Line

External actions allow you to run any executable file (for example, batch file, shell or Perl script, C application) and, if desired, retrieve results. Values are passed from Tango to the executable by means of environment variables. Results are retrieved by Tango from text that the external action has written to the standard output stream (stdout). Rows and columns are delimited with tabs and returns, respectively.

To configure a command line External action

1. From the Type drop-down list, select Command Line.

   The External action editing window for the Command Line type appears.

2. In the Command field, specify the executable file name.

   The file must be the fully qualified file name (for example, c:\temp\dir.bat). This path may contain meta tags.

   You may include command line switches here as well.

   ---

   Note: A command line containing a DOS-like command (for example, dir) will not work because it is not a file. Commands calling other command processors (shell) also will not work. If you want to execute an operating system command, you should create a batch file.

   ---

3. Insert a new environment variable row by doing one of the following:
   • From the Edit menu, choose Insert.
   • On the main toolbar, click the Insert icon.

     

   • Right click the environment variables area, and choose Insert from the context-sensitive menu that appears.

   A new environment variable row appears. The row is numbered for easy identification.

4. In the Name field, enter the name of an environment variable to create for the process. This value is passed on the command line to the External action.

   ---

   Note: The name of an environment variable is case sensitive.

   ---

5. In the Value field, enter the value to assign to the named environment variable.

For more information, see "Assigning Attributes".

Environment variables may include any value-returning Tango meta tags, which are substituted when the action is executed.

Tip: You may re-order variable rows by dragging them within the list.

Appendix C provides additional information on calling Java classes from Tango.

Configuring a Java Action

Tango ships with its own Java server. The Java server is on the same machine as Tango Server. The Java type external action allows you to connect to the Java server.

To configure a Java external action

1. From the Type drop-down list, select Java.

   The External action editing window for the Java type appears.

2. In the Java Server field, type the IP address or hostname.domain of the machine running the Java server.

   The default server name is localhost (127.0.0.1), meaning that the Java server is on the same computer as Tango.

3. In the Port field, type the port number the Java server is listening on.
4. Select either Java Class or Java Bean to specify the type of Java file.
5. In the Path field, type the fully qualified path to the Java file. This path can contain meta tags.
6. Insert a new argument row by doing one of the following:
   • From the Edit menu, choose Insert.
   • On the main toolbar, click the Insert icon.

     

   • Right click the arguments area, and choose Insert from the context-sensitive menu that appears.

   A new argument row appears. The arguments are numbered for easy identification.

   ---

   Tip: You may re-order arguments by dragging them within the list.

   ---

7. In the Value field, type an argument value.

Arguments may include any value-returning Tango meta tags, which are substituted when the action is executed.

Configuring an Apple Event (Mac OS only)

To configure an Apple Event external action

To use External actions you should be familiar with Apple Events and know the event and parameter codes of applications with which you want to communicate. You can also use Apple Event actions to communicate with applications you write in AppleScript.

From the Type drop-down list, select Apple Event.

The External action editing window for the Apple Event type appears.

The Apple Event dialog box has the following components:

• Target Application. The path to the application to send the Apple Event to. The path must be colon (:) separated, for example: Mac HD:My Folder:My Script.
• Event Class Code. The case-sensitive, four-letter class code of the event to send to the target application.
• Event Code. The case-sensitive, four-letter code of the event to send to the target application.
• Event Parameters. Parameter keyword codes are all case-sensitive, four-letter values defined by the target application. To specify the direct parameter for an event, use four dashes, "----".

To add a parameter to the list, do either of the following:

• From the Edit menu, choose Insert.
• Place the cursor inside the Parameters area, right click, and choose Insert from the context-sensitive menu.

A blank row appears in the Parameters area.

The parameter values can be entered as fixed values, or you can use any Tango meta tags that return values.

Tango can send only text parameters and accepts only a string (or value that can be converted to a string), list of strings, or list of lists of strings as return values.

If you need to communicate with applications requiring non-string parameters or that return results in a format Tango cannot handle, you should use an intermediate AppleScript application.

Calling AppleScript Applications

For more information on Apple Events and AppleScripts, consult your Macintosh documentation.

AppleScript application handlers that are to be called from Tango require special subroutine names and parameter labels. Here is an example:

on «event TNGOTest» dir_param given «class arg1»:arg_1, «class arg2»:arg_2

set col_one to¬
"Here is argument 1, accessible with a <@COL 1> tag: " & arg_1
set col_two to¬
"Here is argument 2, accessible with a <@COL 2> tag: " & arg_2
set col_three to¬
with a <@COL 3> tag: "¬& dir_param

return {col_one, col_two, col_three}

end «event TNGOTest»

The first four letters of the AppleScript handler name (after the event keyword) make up the Event Class Code; the second four are the Event Code. In this example, the event class is TNGO and the event is Test.

Except for the direct parameter, which immediately follows the handler name, the parameters must be labeled with the class keyword and a unique four letter code. In this example there are three parameters: the direct parameter, "arg1", and "arg2".

As with any other applications Tango communicates with through Apple Events, results from an AppleScript application must be returned as a string, list of strings, or list of lists of strings. Here is an example of each:

• "value"
• {"value1", "value2", "value3"}
• {{"row1value1", "row1value2", "row1value3"}, {"row2value1", "row2value2", "row2value3"}}

Assigning Attributes

You can also assign the following attributes to an External action:

For a description of each attribute, see "Assigning Attributes to Actions" .

• Results HTML
• No Results HTML
• Error HTML.

You assign these attributes using the Attributes menu.

You can also right click the External action icon or name in the application file, or click the open External action editing window to display a context-sensitive menu of available attributes. The Properties command is also available in this menu.

If you right click an action parameter, the Edit command is active allowing you to edit the parameter value; otherwise, it is disabled (grayed).

Deleting Parameters

To delete an External action parameter

You can also right click the parameter, and choose Delete from the context-sensitive menu that appears.

1. Open the External action editing window.
2. Select the parameter row you want to delete, and do one of the following:
   • Click the Delete icon on the main toolbar.

     

   • From the Edit menu, choose Delete.
   • Press the Delete key.
3. When you are asked to confirm deletion of the selected row, choose OK.

Executing an External Action

When Tango Server executes an External action, the DLL, command line, Apple Event, or Java specified is called and the parameters specified are passed to it. Any data returned is accessible with <@COL> tags in a <@ROWS></@ROWS> block in the action's Results HTML. For example, if a row set with three columns is returned, all the results can be returned with the following Results HTML:

<@ROWS>
Row<@CURRROW>,Column1:<@COL 1><BR>
Row<@CURRROW>,Column2:<@COL 2><BR>
Row<@CURRROW>,Column3:<@COL 3><BR>
<HR>
</@ROWS>

For DLLs, rows and columns are determined by the interface defined in Appendix B. For the command line and Java options, the value returned is treated as tab and return delimited: a tab separates columns and a return separates rows.

Only textual data can be returned from an External action.

The entire result rowset from an External action is automatically assigned to a local array variable, resultSet.

If the External action generates no data, and you have specified No Results HTML for the action, that HTML is processed instead of the Results HTML.

[back to top]

Disabling JavaScript, Java and External Actions

For more information, see "Configuring Tango Server".

JavaScript, Java, and External actions are by default enabled in Tango. If you want to disable (or enable) these features, you can do so by changing the following options in the config.taf application file, in the Feature Switches screen:

javaScriptSwitch
javaSwitch
externalSwitch

For more information, see "Feature Switches".

Check or uncheck the checkboxes beside the options.