Script Parser

The Script Parser enables you to write your own Parser using JavaScript.

To operate, a Script Parser must implement a few functions. The functions do not use parameters.

Passing data between the hosting Connector and the script is done by using predefined objects. One of these predefined objects is the result object which is used to communicate status information. Upon entry into either function, the status field is set to normal which causes the hosting Parser to continue calls. Signaling end-of-input or errors is done by setting the status and message fields in this object. The entry object is populated on calls to writeEntry and is expected to be populated in the readEntry function. When reading entries you have the inp BufferedReader object available for reading character data from a stream. When writing entries you have the out BufferedWriter object available for writing character data to a stream.

You can add your own parameters to the configuration and obtain these by using the parser object.

Objects

Common objects (these are the same as for an AssemblyLine):

main

The Config Instance (RS object) that is running.

task

The AssemblyLine this Parser is a part of.

system

A UserFunctions object.

config

The configuration for this element, that is, this Parser.

The following objects are the only ones accessible to the script Parser:

The result object

setStatus

code

• 0 - End of Input
• 1 - Status OK
• 2 - Error

setMessage

text

The entry object

addAttributeValue (name, value)

Adds a value to an attribute.

getAttribute (name)

Returns the named attribute.

A complete list of available methods, including parameters and return values, can be found in the Javadocs (TDI_install_dir/docs/api/com/ibm/di).

The inp object

read()

Returns next character from stream.

readLine()

Returns next CRLF-stopped line from the input stream.

The out object

write (str)

Writes a string to the output stream.

writeln (str)

Writes a string followed by CRLF to the output stream.

The parser object

getParam(str)

Returns the parameter value associated with parameter name str

setParam(str, value)

Sets the parameter str to value value

logmsg(str)

Writes the parameter str in the log file

A complete list of methods can be found in the installation package.

The connector object

For more information, see the JavaDocs material included in the installation package.

Functions (methods)

The Parser should supply the following functions, where relevant for the intended usage in IBM® Tivoli® Directory Integrator:

readEntry()

Read the next logical entry from the input stream and populate the entry object. This function is not required for Parsers called in add_only situations only.

writeEntry()

Write the contents of the entry object to the output stream. This function is not required for Parsers that are only used for reading.

closeParser ( )

The closeParser function, if implemented, will be called when Connector.close is called. For example:

function closeParser ( )
{
  task.logmsg("CLOSE CALLED.");
}

flush()

The flush function will be called if the Parser's flush is called via the connector.getParser( ).flush( ) method. Implementing these methods in effect overrides the Parser's methods. For example:

function flush ( )
{
  task.logmsg("FLUSH CALLED.");
}

querySchema()

The querySchema function is called by the Parser's parent, that is the Connector into which this Parser has been configured. It is used to discover the Schema of the underlying data source, to populate the Input and Output maps. See Schema for more information.

Configuration

The Parser has the following parameters:

External Files

If you want to include external script files at runtime, specify them here, one file on each line. These files are run before your script.

Include Global Scripts

Include scripts from the Script Library.

Character Encoding

Character Encoding to be used. Also see Character Encoding conversion.

Detailed Log

If this parameter is checked, more detailed log messages are generated.

Script

The user-defined script to run.

Schema

A sample querySchema function is provided in the configuration parameter Script. It assumes the default case where we read from a text file one line at a time; hence, the schema returned from this function has only one field named 'line' of type java.lang.String. If you want specific behavior, you must override this function.

In it there are two predefined objects which are accessible from these two script objects:

list

This is a Vector object. The querySchema(Object) function should add Entry objects to this Vector.

Source

This is an Object parameter passed to the querySchema(Object) function when it is called.

For building a meaningful query schema you must populate the predefined list object with entries containing at least one attribute called "name" and optional attributes: "syntax" or "extsyntax". This can be done by creating an Entry object and calling its addAttributeValue function to set the desired values to the attributes.

According to the success in retrieving schema you can set three different types of exit codes, calling the predefined result object's function setStatus(int) with one of the following values:

• 0 - End of Input
• 1 - Status OK
• 2 - Error

For setting more detailed information about the result you can use the setMessage(String) function which takes one textual parameter. Only if the exit code is 1 a schema is returned by the querySchema(Object) function, otherwise null is returned.

Example

Go to the TDI_install_dir/examples/script_parser directory of your IBM Tivoli Directory Integrator installation.

See also