com.ibm.di.function
Class UserFunctions

java.lang.Object
  extended by com.ibm.di.function.UserFunctions

public class UserFunctions
extends Object

This class contains a number of convenience methods widely used by the scripting environment. An instance of this class is available in scripts, with the scripting name of system.


Field Summary
static char[] INVALID_XML_CHARS
           
 Exception lastError
          The Exception object set by the last call in this library.
 RSInterface server
           
 
Constructor Summary
UserFunctions()
           
UserFunctions(RSInterface server)
           
 
Method Summary
 void abortAssemblyLine(String reason)
          Throws an AbortALException to instruct the AssemblyLine to terminate.
 String arrayToString(byte[] array)
          Converts a ByteArray to a string.
static byte[] base64Decode(String str)
          base64Decode: Obtain Byte Array from a Base 64 encoded String.
static String base64Encode(byte[] b)
          base64Encode: Obtain Base 64 encoded String from a binary Byte Array
 String binaryGUIDtoString(byte[] binaryData)
          Generates the hexadecimal String representation of an Active Directory GUID based on its 128-bit binary representation.
 boolean chdir(String directory)
          Change Java runtime working directory (Sets the "user.dir" property which not always works!!).
static boolean containsIC(String first, String second)
          Returns true if the second String is a substring of the first, ignoring case.
 void continueLoop()
          Throws a ContinueloopException to tell the AssemblyLine to continue with the next value in the loop.
 void continueLoop(String name)
          Throws a ContinueLoopException to tell the AssemblyLine to continue with the next value in the named loop.
 boolean copyBinaryFile(String fromPath, String toPath, boolean overwrite)
           
 void copyDirectory(String source, String target, boolean recursive, boolean overwrite, Log log)
           
 boolean copyFile(String oldFile, String newFile)
          Copy a File.
 boolean copyFile(String fromPath, String toPath, boolean overwrite)
          Copy file.
 AssemblyLinePool createALPool(String assemblyLine, Log log)
          Creates an AssemblyLine Pool object from the specified AssemblyLine name.
static IDispatch createCOMInstance(String progID)
           
 boolean deleteFile(String filePath)
          This method deletes a file.
 Object deletePersistentObject(String key)
          This method deletes a named object in the default system property store.
static void deletePipe(String pipeName)
          Deletes specified pipe from default instance Drops the associated table in System Store with the specified memory queue (if it’s a persistent queue).
static void deletePipe(String instName, String pipeName)
          Deletes the specified pipe from the specified instance.
 String dtSeconds()
          Returns the number of milliseconds since Jan 1 1970 as a string.
 void dumpEntry(Entry e)
          Dumps an entry to the console log.
 boolean dumpJavaClass(String className)
          Dumps the public methods for a Java class.
static String encodeToHexstring(byte[] data)
          encodeToHexstring: Obtain HexString from a byte array.
static boolean endsWithIC(String first, String second)
          Returns true if the first String ends with the second String, ignoring case If at least one if the Strings are null, returns false.
 String entry2LDIF(Entry e)
          Converts an Entry object to an LDIF string.
 void exitBranch()
          Throws an ExitBranchException that tells the AssemblyLine to exit the current branch/loop.
 void exitBranch(String name)
          Throws an ExitBranchException that tells the AssemblyLine to exit the named branch/loop.
 void exitFlow()
          Throws an ExitBranchException that tells the AssemblyLine to not execute any more of the Flow Section components.
 void exitFlow(boolean skipResponse)
          Throws an ExitBranchException that tells the AssemblyLine to not execute any more of the Flow Section components.
 String formatDate(Date date, String format)
          This method formats a java.util.Date object using the provided template.
 ConnectorInterface getConnector(String name)
          Load a connector.
 String getcwd()
          Returns the current working directory.
 Object getExternalProperty(String propName)
          Get external property using delegator object
 Object getExternalProperty(String extObj, String propName)
          Get external property from specific extprop object
 ExternalPropertiesConfig getExtProp(String name)
          Returns a named extprop object.
 FTPBean getFTP()
          Returns an instance of the FTP object.
 FunctionInterface getFunction(String name)
          Loads a function from the function library.
 String getJavaProperty(String prop)
          Returns the value for a system property.
 String getOSName()
          Returns the name of the operating system.
 ParserInterface getParser(String name)
          Load a parser.
 Object getPersistentObject(String key)
          This method retrieves a named object from the default system property store.
static MemBufferQ getPipe(String instName, String pipeName)
          This method returns a handle to a pipe with the specified instName and pipeName (if it already exists).
 String getRacfPassword(byte[] pwbytes, String recipientKeystore, String recipientKeystorePW, String recipientCertAlias, String recipientCertPW, String signerKeystore, String signerKeystorePW, String signerCertAlias)
          This method returns the String representation of the decrypted password from the RACF PasswordEnvelope
 RacfPassword getRacfPasswordObject(byte[] pwbytes, String recipientKeystore, String recipientKeystorePW, String recipientCertAlias, String recipientCertPW, String signerKeystore, String signerKeystorePW, String signerCertAlias)
          This method returns a RacfPassword object containing the decrypted RACF password envelope
 String getRacfPasswordObjectDump(byte[] pwbytes, String recipientKeystore, String recipientKeystorePW, String recipientCertAlias, String recipientCertPW, String signerKeystore, String signerKeystorePW, String signerCertAlias)
          This method returns the String representation of the decrypted racfpasswordenvelope The syntax for the String is: Password: <password>, Version: <version>, Change Time: <timestamp>, Language: <language>, Expired: <true/false>
 String getRsaDecrypted(String cipherText, String ksPath, String ksPassword, String certificateAlias, String certificatePassword)
          getRsaDecrypted: Obtain plain ascii text for encrypted ciphertext specified.
 String getRsaEncrypted(String plainText, String ksPath, String ksPassword, String certificateAlias)
          getRsaEncrypted: Obtain encrypted (and ascii-encoded) value for plaintext specified, null strings are not processed and will be returned as null.
static Vector getRunningALs()
          This method returns a Vector containing all AssemblyLines that were running when the function was called
static Vector getRunningALs(String name)
          This method returns a Vector containing all AssemblyLines with the given name that were running when the function was called
static Vector getRunningEHs()
          This method returns a Vector containing all EventHandlers that were running when the function was called.
static Vector getRunningEHs(String name)
          This method returns a Vector containing all EventHandlers with the given name that were running when the function was called
 String getScriptText(String name)
          Returns the text from the Script Library.
 RSInterface getServer()
           
static ParameterSubstitution getTDIExpression(String pattern)
           
 TDIProperties getTDIProperties()
          Returns the TDIProperties object for the current configuration
 Object getTDIProperty(String name)
          Returns the value for a TDI property
 Object getTDIProperty(String propstore, String name)
          Returns the property value from a specific TDI property store "@param propstore The property store name
 String getX400Attribute(String x400, String sep, String attribute)
          Returns an attribute value from an X.400 address.
 org.apache.xpath.XPathAPI getXPathAPI()
          Returns the Apache XPathAPI
 Entry httpGet(String url)
          Posts file to a web server.
 Entry httpPost(String url, Object file)
           
 Entry httpRequest(String method, String contentType, String url, Object file)
           
 void ignoreEntry()
          Throws an IgnoreEntryException to tell the AssemblyLine to skip the current Connector and continue with the next Connector in the AssemblyLine.
 void ignoreEntry(String msg)
          Throws an IgnoreEntryException to tell the AssemblyLine to skip the current Connector and continue with the next Connector in the AssemblyLine.
 boolean isValidInt(String str)
          Returns true if a string holds a valid Integer.
 ConnectorInterface loadConnector(String connectorName)
          Load a connector.
static void loadJarFile(String path)
          Dynamically add jar file containing class definitions.
 String makeTitleCase(String in)
          Convert A String Into Title Case (Like This), using the current Locale.
 String mapString(String source, String fromSet, String toSet)
          Translates characters in a string.
 Attribute newAttribute(String name)
          Creates a new Attribute object.
 Entry newEntry()
          Creates a new Entry object.
 Object newObject(String className)
          Creates a new object.
static MemBufferQ newPipe(String instName, String pipeName, int watermark)
          This method create a new Memory Buffer Queue if it does not already exist.
static MemBufferQ newPipe(String instName, String pipeName, int watermark, int pagesize)
          This method create a new Memory Buffer Queue if it does not already exist.
 SearchCriteria newSearchCriteria()
          Creates a new rscSearchCriteira object.
 TaskCallBlock newTCB()
          Create an empty TaskCallBlock.
 TaskCallBlock newTCB(String assemblyLine)
          Create a TaskCallBlock with i/o specifications from an existing assemblyline.
 String normalizeX400(String value, String cursep, String newsep)
          Converts an X.400 address to a string using short form attribute names.
 BufferedWriter openFileForAppend(String path)
          Opens a file in append mode and returns the associated BufferedWriter object.
 BufferedReader openFileForInput(String path)
          Opens a file for input and returns the associated BufferedReader object.
 BufferedWriter openFileForOutput(String path)
          Opens a file in output mode and returns the associated BufferedWriter object.
 Date parseDate(String value, String format)
          Converts a String to a java.util.Date object.
 Entry parseObject(String parser, Object data)
          Use a parser to interpret data.
 String remove(String s, String source)
          Remove characters from a string.
static String removeInvalidXMLChars(String aString)
           
 String removeStringChars(String source, String fromSet)
          Removes occurrences of characters from a string.
 boolean renameFile(String oldName, String newName)
          Rename a file.
 void restartEntry()
          Throws a RestartEntryException to tell the AssemblyLine to restart.
 void restartEntry(String msg)
          Throws a RestartEntryException to tell the AssemblyLine to restart, using the current work object.
 void retryEntry()
          Throws a RetryEntryException to tell the AssemblyLine to retry this Connector.
 org.w3c.dom.traversal.NodeIterator selectNodeIterator(Node contextNode, String str)
          Selects nodes using an XPath expression from an XML node.
 NodeList selectNodeList(Node contextNode, String str)
          Selects nodes using an XPath expression from an XML node.
 Node selectSingleNode(Node contextNode, String str)
          Selects a single node using an XPath expression from an XML node.
 String sendMail(String from, String recipient, String subject, String body, String attachment)
          Sends an email message.
 void setExternalProperty(String propName, Object value)
          Set external property using delegator object
 void setExternalProperty(String extObj, String propName, Object value)
          Set external property in a specific extprop object
 void setJavaProperty(String prop, String value)
          Sets the value of a property name.
 Object setPersistentObject(String key, Object value)
          This method stores a named object in the default system property store.
 void setTDIProperty(String name, Object value)
          Sets the property value for a property (store selection based on naming rules and order) "@param propstore The property store name
 void setTDIProperty(String propstore, String name, Object value)
          Sets the property value in a specific TDI property store "@param propstore The property store name
 ExecuteCommand shellCommand(String command)
          Executes a shell command.
 ExecuteCommand shellCommand(String command, Object args)
          Executes a shell command.
 void skipEntry()
          Throws a SkipEntryException to tell the AssemblyLine to skip the current Entry.
 void skipEntry(String msg)
          Throws a SkipEntryException to tell the AssemblyLine to skip the current Entry.
 void skipTo(String name)
          Throws a SkipToException to tell the AssemblyLine to skip to the named Connector/ScriptComponent.
 InterruptedException sleep(int seconds)
          Causes the current thread (e.g.
 boolean snmpTrap(String host, int port, String oid, String value)
          Sends an SNMP trap.
 boolean snmpTrap(String agentIP, String host, int port, String community, String enterprise, int genericTrap, int specificTrap, String oid, Object value)
          Sends an SNMP trap.
 String[] splitString(String source, String separators)
          Splits a string into an array of strings.
static boolean startsWithIC(String first, String second)
          Returns true if the first String starts with the second String, ignoring case.
static String substitute(String pattern, Map params)
          Performs a one-time parsing and substitution of pattern with the objects available in params.
static String substitute(String pattern, String[] names, Object[] objects)
          Performs a one-time parsing and substitution of pattern with named objects.
 void throwException(String message)
          Throws a generic java.lang.Exception.
 String toHex(String str)
          Converts a string to a hexadecimal string where each character is converted to a two-byte hex value.
 Integer toInt(String str)
          Convert a string to a java.lang.Integer object.
 String translateString(String str, String fromCharset, String toCharset)
          Translate a string from one character set to another.
 String trim(String str)
          Trims leading/trailing white-space from a string.
 void writeln(Writer w, String str)
          Writes a string plus a CRLF using a Writer object.
 String xslTransform(Object xsl, Object xml)
          Calls the XSLTransformer to transform an XML document using a given style sheet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

lastError

public Exception lastError
The Exception object set by the last call in this library.


server

public RSInterface server

INVALID_XML_CHARS

public static char[] INVALID_XML_CHARS
Constructor Detail

UserFunctions

public UserFunctions()

UserFunctions

public UserFunctions(RSInterface server)
Method Detail

getServer

public RSInterface getServer()

remove

public String remove(String s,
                     String source)
              throws Exception
Remove characters from a string. For example, if you want to remove all blanks from the string "J O P" then you would use remove (" ", "J O P"). The returned value would then be "JOP".
 var a = "A string with blanks and vowels";
 var b = system.remove ("AEIOUaeiou ", a);
 task.logmsg("Result: " + b);      // "strngwthblnksndvwls"
 

Parameters:
s - The characters to be removed
source - The string from which characters are removed
Throws:
Exception

trim

public String trim(String str)
Trims leading/trailing white-space from a string.

Parameters:
str - The string to trim
Returns:
The trimmed string

toInt

public Integer toInt(String str)
              throws Exception
Convert a string to a java.lang.Integer object.

Parameters:
str - The string with a number
Returns:
The Integer object
Throws:
Exception

isValidInt

public boolean isValidInt(String str)
Returns true if a string holds a valid Integer.

Parameters:
str - The string to test
Returns:
True if the string can be converted to an Integer

openFileForAppend

public BufferedWriter openFileForAppend(String path)
                                 throws Exception
Opens a file in append mode and returns the associated BufferedWriter object.
 var out = system.openFileForAppend("out.txt");
 out.write ("Hello world!");
 out.newLine ();
 out.close ();
 

Parameters:
path - The file path to open
Returns:
The BufferedWriter object
Throws:
Exception

openFileForOutput

public BufferedWriter openFileForOutput(String path)
                                 throws Exception
Opens a file in output mode and returns the associated BufferedWriter object.
 var out = system.openFileForOutput("out.txt");
 out.write ("Hello world!");
 out.newLine ();
 out.close ();
 

Parameters:
path - The file path to open (overwrites existing file)
Returns:
The BufferedWriter object
Throws:
Exception

openFileForInput

public BufferedReader openFileForInput(String path)
                                throws Exception
Opens a file for input and returns the associated BufferedReader object.
 var inp = system.openFileForInput ("inp.txt");
 var str = inp.readLine();
 if ( str == null )
  task.logmsg("End of file");
 inp.close ();
 

Parameters:
path - The file path to open
Returns:
The BufferedReader object
Throws:
Exception

writeln

public void writeln(Writer w,
                    String str)
             throws Exception
Writes a string plus a CRLF using a Writer object.

Parameters:
w - The writer object
str - The string to write
Throws:
Exception

sendMail

public String sendMail(String from,
                       String recipient,
                       String subject,
                       String body,
                       String attachment)
                throws Exception
Sends an email message. Make sure the mail.smtp.host Java property is configured with the hostname of a valid SMTP server.

Parameters:
from - The From field
recipient - A comma separated list of recipient addresses
subject - The Subject field
body - The message text
attachment - If specified a file-path that will be attached to the message
Returns:
If null, the message was sent. Otherwise, this is the error message.
Throws:
Exception

copyFile

public boolean copyFile(String fromPath,
                        String toPath,
                        boolean overwrite)
                 throws Exception
Copy file. This method copies fromPath to toPath. The overwrite flag specifies whether the destination file should be overwritten.

Parameters:
fromPath - The source file
toPath - The destination file
overwrite - Specify true if destination should be overwritten.
Returns:
true if file was copied, false if toPath exists and overwrite=false.
Throws:
Exception

copyBinaryFile

public boolean copyBinaryFile(String fromPath,
                              String toPath,
                              boolean overwrite)
                       throws Exception
Throws:
Exception

copyDirectory

public void copyDirectory(String source,
                          String target,
                          boolean recursive,
                          boolean overwrite,
                          Log log)
                   throws Exception
Throws:
Exception

newAttribute

public Attribute newAttribute(String name)
Creates a new Attribute object.

Parameters:
name - The attribute name
Returns:
The Attribute object

newSearchCriteria

public SearchCriteria newSearchCriteria()
Creates a new rscSearchCriteira object.

Returns:
The SearchCriteria object

newEntry

public Entry newEntry()
Creates a new Entry object.

Returns:
The Entry object

newObject

public Object newObject(String className)
Creates a new object. This method only works for Java objects that have empty constructors. It is a convenience method for scripting languages that cannot create Java objects directly.

Parameters:
className - The java class name
Returns:
The newly created object

skipEntry

public void skipEntry()
               throws SkipEntryException
Throws a SkipEntryException to tell the AssemblyLine to skip the current Entry. If used in an EventHandler, skip the remaining actions.

Throws:
SkipEntryException

skipEntry

public void skipEntry(String msg)
               throws SkipEntryException
Throws a SkipEntryException to tell the AssemblyLine to skip the current Entry. If used in an EventHandler, skip the remaining actions.

Parameters:
msg - - A message supplied by the user
Throws:
SkipEntryException

ignoreEntry

public void ignoreEntry()
                 throws IgnoreEntryException
Throws an IgnoreEntryException to tell the AssemblyLine to skip the current Connector and continue with the next Connector in the AssemblyLine. If used in an EventHandler, skip to the next action.

Throws:
IgnoreEntryException

ignoreEntry

public void ignoreEntry(String msg)
                 throws IgnoreEntryException
Throws an IgnoreEntryException to tell the AssemblyLine to skip the current Connector and continue with the next Connector in the AssemblyLine. If used in an EventHandler, skip to the next action.

Parameters:
msg - - A message supplied by the user
Throws:
IgnoreEntryException

restartEntry

public void restartEntry()
                  throws RestartEntryException
Throws a RestartEntryException to tell the AssemblyLine to restart. The AssemblyLine will continue at the first non-Iterator Connector in the AssemblyLine, using the current work object. If used in an EventHandler, skip to the first action.

Throws:
RestartEntryException

restartEntry

public void restartEntry(String msg)
                  throws RestartEntryException
Throws a RestartEntryException to tell the AssemblyLine to restart, using the current work object.

Parameters:
msg - - A message supplied by the user
Throws:
RestartEntryException
See Also:
restartEntry()

retryEntry

public void retryEntry()
                throws RetryEntryException
Throws a RetryEntryException to tell the AssemblyLine to retry this Connector. The AssemblyLine will perform the operation of the current Connector again, using the current work object.

Throws:
RetryEntryException

skipTo

public void skipTo(String name)
            throws SkipToException
Throws a SkipToException to tell the AssemblyLine to skip to the named Connector/ScriptComponent. If used in an EventHandler, skip to the named action. named by name.

Parameters:
name - - The name of the Connector to skip to.
Throws:
SkipToException

abortAssemblyLine

public void abortAssemblyLine(String reason)
                       throws AbortALException
Throws an AbortALException to instruct the AssemblyLine to terminate. The AssemblyLine will continue with the Epilog. If the Epilog is already executed, continue on to the next step (closing Connectors or "Epilog - After Close"). If used in an EventHandler, skip the remaining actions, and cause the EventHandler to terminate.

Parameters:
reason - Descriptive text why the AssemblyLine is terminated
Throws:
AbortALException

throwException

public void throwException(String message)
                    throws Exception
Throws a generic java.lang.Exception.

Parameters:
message - The Exception's message text
Throws:
Exception

exitBranch

public void exitBranch()
                throws ExitBranchException
Throws an ExitBranchException that tells the AssemblyLine to exit the current branch/loop.

Throws:
ExitBranchException

exitBranch

public void exitBranch(String name)
                throws ExitBranchException
Throws an ExitBranchException that tells the AssemblyLine to exit the named branch/loop. Some special values for name can also be used:
null - exit current (innermost) branch or loop
"Loop" - exit current Loop
"Branch" - exit current branch
"Cycle" - exit this cycle (jump to end of cycle), and begin the next cycle
"Flow" - jump to end of cycle, and send response if there is a Connector in Server mode. Then begin the next cycle
"AssemblyLine" - exit dataflow, jump to Epilog

Parameters:
name - - The name of the branch/loop to exit
Throws:
ExitBranchException - to tell the AssemblyLine to exit the named branch/loop

exitFlow

public void exitFlow()
              throws ExitBranchException
Throws an ExitBranchException that tells the AssemblyLine to not execute any more of the Flow Section components. In other words, the current cycle of the AL ends, and in the case of a Server mode Connector, the Response is carried out.

This behavior is identical to that caused by the following call:

system.exitBranch("Flow");

Throws:
ExitBranchException - to tell the AssemblyLine to exit the Flow Section

exitFlow

public void exitFlow(boolean skipResponse)
              throws ExitBranchException
Throws an ExitBranchException that tells the AssemblyLine to not execute any more of the Flow Section components. In other words, the current cycle of the AL ends.

If the skipResponse parameter pass is false, then in the case of a Server mode Connector, the Response is carried out. If skipResponse is true, no Response is sent.

Parameters:
skipResponse - Whether or not a Response should be sent if a Server mode Connector is feeding this AL.
Throws:
ExitBranchException - to tell the AssemblyLine to exit the Flow Section

continueLoop

public void continueLoop()
                  throws ContinueLoopException
Throws a ContinueloopException to tell the AssemblyLine to continue with the next value in the loop.

Throws:
ContinueLoopException

continueLoop

public void continueLoop(String name)
                  throws ContinueLoopException
Throws a ContinueLoopException to tell the AssemblyLine to continue with the next value in the named loop.

Parameters:
name - - The name of the loop
Throws:
ContinueLoopException

loadConnector

public ConnectorInterface loadConnector(String connectorName)
Load a connector. This method loads a connector from the current config file.

Parameters:
connectorName - The connector name as it appears in the configuration file
Returns:
The connector object

dtSeconds

public String dtSeconds()
Returns the number of milliseconds since Jan 1 1970 as a string.

Returns:
Number of milliseconds

sleep

public InterruptedException sleep(int seconds)
Causes the current thread (e.g. AssemblyLine, EventHandler etc..) to sleep for a number of seconds. If the sleep is interrupted the InterruptedException value is returned. If not, null is returned.

Parameters:
seconds - Number of seconds to sleep
Returns:
null if successful, exception object otherwise

removeStringChars

public String removeStringChars(String source,
                                String fromSet)
Removes occurrences of characters from a string.

Parameters:
source - The source string
fromSet - A string specifying characters to be removed from source
Returns:
The resulting string

makeTitleCase

public String makeTitleCase(String in)
Convert A String Into Title Case (Like This), using the current Locale.

Parameters:
in - The string to convert
Returns:
The converted string

mapString

public String mapString(String source,
                        String fromSet,
                        String toSet)
Translates characters in a string. The fromSet and toSet contains the characters used to perform substitution. The first character in fromSet is replace with the first character in toSet etc.

Parameters:
source - The source string
fromSet - The characters to be replaced
toSet - The characters to replace characters in fromSet
Returns:
The substituted string

translateString

public String translateString(String str,
                              String fromCharset,
                              String toCharset)
Translate a string from one character set to another.

Parameters:
str - The source string
fromCharset - The source character set
toCharset - The target character set
Returns:
The translated string

toHex

public String toHex(String str)
Converts a string to a hexadecimal string where each character is converted to a two-byte hex value.

Parameters:
str - The source string
Returns:
The hexadecimal string

getX400Attribute

public String getX400Attribute(String x400,
                               String sep,
                               String attribute)
Returns an attribute value from an X.400 address.

Parameters:
x400 - The X.400 address
sep - The separator used in the address ( typically "/" or ";" )
attribute - The X.400 attribute
Returns:
The value or null if no attribute was found

normalizeX400

public String normalizeX400(String value,
                            String cursep,
                            String newsep)
Converts an X.400 address to a string using short form attribute names. Attributes are sorted in order of significance.

Parameters:
value - The X.400 address
cursep - The separator used in value
newsep - The separator to be used in the result
Returns:
The reformatted X.400 address

parseDate

public Date parseDate(String value,
                      String format)
Converts a String to a java.util.Date object.

Parameters:
value - The date in string form
format - The format of value (e.g. "yyyy.MM.DD", "MM/DD/yy" etc ...) A complete list of format chanacters can be found at http://icu.sourceforge.net/apiref/icu4j/com/ibm/icu/text/SimpleDateFormat.html
Returns:
The Date object or null if an error occurred
See Also:
lastError

formatDate

public String formatDate(Date date,
                         String format)
This method formats a java.util.Date object using the provided template.

Parameters:
date - The date object
format - The format of value (e.g. "yyyy.MM.DD", "MM/DD/yy" etc ...) A complete list of format chanacters can be found at http://icu.sourceforge.net/apiref/icu4j/com/ibm/icu/text/SimpleDateFormat.html.
Returns:
The string representation or null if an error occurred
See Also:
lastError

splitString

public String[] splitString(String source,
                            String separators)
Splits a string into an array of strings.

Parameters:
source - The source string
separators - The word-separating characters
Returns:
Array of strings

getConnector

public ConnectorInterface getConnector(String name)
Load a connector. This method loads a connector from the current config file.

Parameters:
name - The connector name as it appears in the configuration file
Returns:
The connector object

getParser

public ParserInterface getParser(String name)
Load a parser. This method loads a parser from the current config file.

Parameters:
name - The parser name as it appears in the configuration file
Returns:
The parser object

parseObject

public Entry parseObject(String parser,
                         Object data)
Use a parser to interpret data. This method will either use the data object as-is if it is a reader or inputstream class, or it will create a StringReader from the string representation of the data obect and pass it to the parser. The parser will be called to interpret the byte stream and return an Entry. If the parse fails a null is returned.

Parameters:
parser - The parser name
data - Any object of type Reader, InputStream or object that has a toString method
Returns:
The parsed entry
See Also:
lastError

shellCommand

public ExecuteCommand shellCommand(String command)
Executes a shell command.

Parameters:
command - A String containing the shell command to execute. This String will be parsed with a simple StringTokenizer, to split the command and arguments.
Returns:
An ExecuteCommand object
See Also:
ExecuteCommand

shellCommand

public ExecuteCommand shellCommand(String command,
                                   Object args)
Executes a shell command.

Parameters:
command - The shell command to execute
args - The arguments to the command. E.g. a String array containing the arguments. In JavaScript you could have code like this:
 myArr = ["-c", "/bin/ls", "/mnt/cd rom"];
 cmd = system.shellCommand ("su", myArr);
 main.logmsg("The result was:\n" + cmd.getOutputBuffer() );
 
Returns:
An ExecuteCommand object
See Also:
ExecuteCommand

getOSName

public String getOSName()
Returns the name of the operating system.

Returns:
The OS name

getJavaProperty

public String getJavaProperty(String prop)
Returns the value for a system property.

Parameters:
prop - The property name
Returns:
The property value or null if no such property exists

setJavaProperty

public void setJavaProperty(String prop,
                            String value)
Sets the value of a property name.

Parameters:
prop - The property name
value - The property value

entry2LDIF

public String entry2LDIF(Entry e)
Converts an Entry object to an LDIF string.

Parameters:
e - The entry
Returns:
The LDIF string

getFTP

public FTPBean getFTP()
Returns an instance of the FTP object.

Returns:
The FTP object
See Also:
FTPBean

dumpEntry

public void dumpEntry(Entry e)
Dumps an entry to the console log.

Parameters:
e - The entry

getXPathAPI

public org.apache.xpath.XPathAPI getXPathAPI()
Returns the Apache XPathAPI

Returns:
XPathAPI object

selectSingleNode

public Node selectSingleNode(Node contextNode,
                             String str)
Selects a single node using an XPath expression from an XML node.

Parameters:
contextNode - The XML document node
str - The XPath search string
Returns:
XML Document node

selectNodeList

public NodeList selectNodeList(Node contextNode,
                               String str)
Selects nodes using an XPath expression from an XML node.

Parameters:
contextNode - The XML document node
str - The XPath search string
Returns:
A NodeList object

selectNodeIterator

public org.w3c.dom.traversal.NodeIterator selectNodeIterator(Node contextNode,
                                                             String str)
Selects nodes using an XPath expression from an XML node.

Parameters:
contextNode - The XML document node
str - The XPath search string
Returns:
A NodeIterator object

xslTransform

public String xslTransform(Object xsl,
                           Object xml)
Calls the XSLTransformer to transform an XML document using a given style sheet.

Parameters:
xsl - The XSL Style sheet (String, java.io.File, java.io.Reader )
xml - The XML document (String, java.io.File, java.io.Reader )
Returns:
The translated document

dumpJavaClass

public boolean dumpJavaClass(String className)
Dumps the public methods for a Java class.

Parameters:
className - The java class name
Returns:
True if dump succeeded
See Also:
lastError

chdir

public boolean chdir(String directory)
Change Java runtime working directory (Sets the "user.dir" property which not always works!!).

Parameters:
directory - File system directory
Returns:
True if directory exists, false if directory is not valid

getcwd

public String getcwd()
Returns the current working directory.

Returns:
Working directory

getScriptText

public String getScriptText(String name)
Returns the text from the Script Library.

Parameters:
name - The script name as it appears in the configuration.
Returns:
The script text or null if not found

snmpTrap

public boolean snmpTrap(String host,
                        int port,
                        String oid,
                        String value)
Sends an SNMP trap. This method only accepts a String as the value. If you need to send more complex data use the other snmpTrap() method in this library.

Parameters:
host - The IP host
port - The TCP port
oid - The OID
value - The value
Returns:
True if Trap was sent
See Also:
lastError

snmpTrap

public boolean snmpTrap(String agentIP,
                        String host,
                        int port,
                        String community,
                        String enterprise,
                        int genericTrap,
                        int specificTrap,
                        String oid,
                        Object value)
Sends an SNMP trap. This method allows you to set most of the attributes of the SNMP trap PDU. If oid is null, value must be an Entry. All Attribute names will be taken as oids, and the values of that Attribute will be the corresponding values. Sample script:

    importClass(Packages.com.ibm.di.protocols.SNMP);
    var entry = system.newEntry();
    entry.setAttribute("1.2.3.4.1", "MyString");
    entry.setAttribute("1.2.3.4.2", SNMP.createIPAddress("10.0.0.1") );
    entry.setAttribute("1.2.3.4.3", SNMP.createGauge(200) );
    
    if ( !system.snmpTrap( "192.1.1.1", targetIP, 162, "public", enterpriseOID, 0, 0, null, entry) ) {
      task.logmsg("Error sending trap: " + system.lastError);
    }
    
If oid is non-null, value should be a java.util.Vector, a javascript array or any other object. The conversion of the values to SNMP PDU values are as follows: If you provide an object whose class starts with "com.tivoli.snmp.data" the value is used asis (see com.ibm.di.protocols.SNMP on how to create these objects). If you provide an Integer then a com.tivoli.snmp.data.Counter object is created. In all other cases an OctetString object is created from the object value's toString() method. Sample script:

    importClass(Packages.com.ibm.di.protocols.SNMP);
    var varBind = [ "MyString", SNMP.createIPAddress("10.0.0.1"), SNMP.createGauge(200) ];
    if ( !system.snmpTrap( "192.1.1.1", targetIP, 162, "public", enterpriseOID, 0, 0, "1.2.3.4", varBind) ) {
      task.logmsg("Error sending trap: " + system.lastError);
    }
    

Parameters:
agentIP - The agent IP address or null to use the local host ip address (e.g. InetAddress.getLocalHost().getHostAddress())
host - The target IP host
port - The target TCP port
community - The SNMP community string
enterprise - The Enterprise OID
genericTrap - Trap type: coldStart(0), warmStart(1), linkDown(2), linkUp(3), authenticationFailure(4), egpNeighborLoss(5), enterpriseSpecific(6)
specificTrap - Used for enterpriseSpecific traps
oid - The OID for the values. If oid is null, value must be en Entry where the Attribute names will be used as OIDs
value - The value(s)
Returns:
True if Trap was sent, otherwise check the system.lastError object for the exception
See Also:
lastError

httpGet

public Entry httpGet(String url)
Posts file to a web server.

Parameters:
url - The URL to the web server
Returns:
The response from the server is encapsulated into an Entry object or NULL if an error occurred.
See Also:
lastError

httpPost

public Entry httpPost(String url,
                      Object file)

httpRequest

public Entry httpRequest(String method,
                         String contentType,
                         String url,
                         Object file)

arrayToString

public String arrayToString(byte[] array)
Converts a ByteArray to a string. For example, if you want to set a password(which is sometime a binary value) you could use this in the attribute mapping
 ret.value = system.arrayToString( work.getObject("userpassword"));
 

Parameters:
array - The byte array to be converted
Returns:
The String object created from byte array

deleteFile

public boolean deleteFile(String filePath)
                   throws Exception
This method deletes a file.

Parameters:
filePath - The name of the file to be deleted
Returns:
true if file was deleted, false if not deleted or if an error occurred.
Throws:
Exception
See Also:
lastError

renameFile

public boolean renameFile(String oldName,
                          String newName)
Rename a file.

Parameters:
oldName - The old name of the file
newName - The new name of the file
Returns:
true if the rename succeeded, false otherwise
See Also:
lastError

copyFile

public boolean copyFile(String oldFile,
                        String newFile)
Copy a File.

Parameters:
oldFile - The name of the file to copy
newFile - The name of the new file
Returns:
true if the copying succeeded, false if an exception occurred
See Also:
lastError

newTCB

public TaskCallBlock newTCB()
Create an empty TaskCallBlock.


newTCB

public TaskCallBlock newTCB(String assemblyLine)
Create a TaskCallBlock with i/o specifications from an existing assemblyline. The TCB will contain all input/output parameters as well as all connectors and their initial parameters and values.


getPersistentObject

public Object getPersistentObject(String key)
                           throws Exception
This method retrieves a named object from the default system property store.

Parameters:
key - The unique key
Throws:
Exception

setPersistentObject

public Object setPersistentObject(String key,
                                  Object value)
                           throws Exception
This method stores a named object in the default system property store.

Parameters:
key - The unique key
value - The object to store (must be java serializable)
Returns:
The old object if any
Throws:
Exception

deletePersistentObject

public Object deletePersistentObject(String key)
                              throws Exception
This method deletes a named object in the default system property store.

Parameters:
key - The unique key
Returns:
The old object if any
Throws:
Exception

getRunningALs

public static Vector getRunningALs()
This method returns a Vector containing all AssemblyLines that were running when the function was called

Returns:
a java.util.Vector containing the AssemblyLines

getRunningALs

public static Vector getRunningALs(String name)
This method returns a Vector containing all AssemblyLines with the given name that were running when the function was called

Parameters:
name - Find all AssemblyLines with this name. Only the last part of the name (after optional /) is used.
Returns:
a java.util.Vector containing the AssemblyLines

getRunningEHs

public static Vector getRunningEHs()
This method returns a Vector containing all EventHandlers that were running when the function was called.

Returns:
A java.util.Vector containing the EventHandlers

getRunningEHs

public static Vector getRunningEHs(String name)
This method returns a Vector containing all EventHandlers with the given name that were running when the function was called

Parameters:
name - Find all EventHandlers with this name. Only the last part of the name (after optional /) is used.
Returns:
a java.util.Vector containing the EventHandlers

getRacfPasswordObject

public RacfPassword getRacfPasswordObject(byte[] pwbytes,
                                          String recipientKeystore,
                                          String recipientKeystorePW,
                                          String recipientCertAlias,
                                          String recipientCertPW,
                                          String signerKeystore,
                                          String signerKeystorePW,
                                          String signerCertAlias)
                                   throws Exception
This method returns a RacfPassword object containing the decrypted RACF password envelope

Parameters:
pwbytes - the byte array containing the racfpasswordenvelope
recipientKeystore - the file path to the recipient's keystore file
recipientKeystorePW - the password for access to the recipient's keystore file
recipientCertAlias - String alias name of certificate for recipient
recipientCertPW - the password for access to the recipient's certificate
signerKeystore - the file path to the signer's keystore file (note: signer cert and recip cert keystore can be same file)
signerKeystorePW - the password for access to the recipient's keystore file
signerCertAlias - String alias name of certificate for recipient
Returns:
the decrypted RacfPassword object
Throws:
Exception

getRacfPassword

public String getRacfPassword(byte[] pwbytes,
                              String recipientKeystore,
                              String recipientKeystorePW,
                              String recipientCertAlias,
                              String recipientCertPW,
                              String signerKeystore,
                              String signerKeystorePW,
                              String signerCertAlias)
                       throws Exception
This method returns the String representation of the decrypted password from the RACF PasswordEnvelope

Parameters:
pwbytes - the byte array containing the racfpasswordenvelope
recipientKeystore - the file path to the recipient's keystore file
recipientKeystorePW - the password for access to the recipient's keystore file
recipientCertAlias - String alias name of certificate for recipient
recipientCertPW - the password for access to the recipient's certificate
signerKeystore - the file path to the signer's keystore file (note: signer cert and recip cert keystore can be same file)
signerKeystorePW - the password for access to the recipient's keystore file
signerCertAlias - String alias name of certificate for recipient
Returns:
the decrypted String version of the RacfPassword
Throws:
Exception

getRacfPasswordObjectDump

public String getRacfPasswordObjectDump(byte[] pwbytes,
                                        String recipientKeystore,
                                        String recipientKeystorePW,
                                        String recipientCertAlias,
                                        String recipientCertPW,
                                        String signerKeystore,
                                        String signerKeystorePW,
                                        String signerCertAlias)
                                 throws Exception
This method returns the String representation of the decrypted racfpasswordenvelope The syntax for the String is: Password: <password>, Version: <version>, Change Time: <timestamp>, Language: <language>, Expired: <true/false>

Parameters:
pwbytes - the byte array containing the racfpasswordenvelope
recipientKeystore - the file path to the recipient's keystore file
recipientKeystorePW - the password for access to the recipient's keystore file
recipientCertAlias - String alias name of certificate for recipient
recipientCertPW - the password for access to the recipient's certificate
signerKeystore - the file path to the signer's keystore file (note: signer cert and recip cert keystore can be same file)
signerKeystorePW - the password for access to the recipient's keystore file
signerCertAlias - String alias name of certificate for recipient
Returns:
String representing contents of decrypted RacfPassword object
Throws:
Exception

getRsaEncrypted

public String getRsaEncrypted(String plainText,
                              String ksPath,
                              String ksPassword,
                              String certificateAlias)
                       throws Exception
getRsaEncrypted: Obtain encrypted (and ascii-encoded) value for plaintext specified, null strings are not processed and will be returned as null.

Parameters:
plainText - String representing value to be encrypted using public key
ksPath - String representing file path to jks file
ksPassword - String representing password for jks file as specified by path
certificateAlias - String naming the alias of certificate in keystore file
Returns:
String representing encrypted format, null is returned if a null is passed in.
Throws:
java.langException - when underlying funtion fails
Exception

getRsaDecrypted

public String getRsaDecrypted(String cipherText,
                              String ksPath,
                              String ksPassword,
                              String certificateAlias,
                              String certificatePassword)
                       throws Exception
getRsaDecrypted: Obtain plain ascii text for encrypted ciphertext specified. Null strings are not processed and will be returned as received. Empty strings will be encoded/encrypted.

Parameters:
cipherText - String representing value to be decrypted using private key
ksPath - String representing file path to jks file
ksPassword - String representing password for jks file as specified by path
certificateAlias - String naming the alias of certificate in keystore file
certificatePassword - String representing password certificate
Returns:
String representing the decrypted format of the received string. Null is returned when a null is received.
Throws:
java.langException - when underlying funtion fails
Exception

createALPool

public AssemblyLinePool createALPool(String assemblyLine,
                                     Log log)
                              throws Throwable
Creates an AssemblyLine Pool object from the specified AssemblyLine name.

Parameters:
assemblyLine - The name of the assemblyline
log - The Log object to use or null to use the system logger
Throws:
Throwable

getFunction

public FunctionInterface getFunction(String name)
                              throws Exception
Loads a function from the function library.

Parameters:
name - The name of the function.
Returns:
The Function object
Throws:
Exception

base64Encode

public static String base64Encode(byte[] b)
base64Encode: Obtain Base 64 encoded String from a binary Byte Array

Parameters:
b - byte array containing binary data
Returns:
String containing the base64 encoded representation of the data.

base64Decode

public static byte[] base64Decode(String str)
base64Decode: Obtain Byte Array from a Base 64 encoded String.

Parameters:
str - String containing base64 Data.
Returns:
Byte array coantaining the decoded binary data.

encodeToHexstring

public static String encodeToHexstring(byte[] data)
encodeToHexstring: Obtain HexString from a byte array.

Parameters:
data - byte array containing binary data
Returns:
String containing the Hexadecimal representation of the data.

createCOMInstance

public static IDispatch createCOMInstance(String progID)

newPipe

public static MemBufferQ newPipe(String instName,
                                 String pipeName,
                                 int watermark)
                          throws Exception
This method create a new Memory Buffer Queue if it does not already exist. If the pipe already exists with the specified instaName and pipeName then a handle to the same pipe is returned. Paging is disabled in this case.

Parameters:
instName - name of the instance. Default instance will be used if this param is null.
pipeName - name of the pipe to be created
watermark - With Paging On, it is the threshold at which objects are persisted to the System Store With Paging Off, it is the maximum queue size
Returns:
MemBufferQ
Throws:
Exception

newPipe

public static MemBufferQ newPipe(String instName,
                                 String pipeName,
                                 int watermark,
                                 int pagesize)
                          throws Exception
This method create a new Memory Buffer Queue if it does not already exist. If the pipe already exists with the specified instaName and pipeName then a handle to the same pipe is returned. Paging is enabled in this case.

Parameters:
instName - name of the instance. Default instance will be used if this param is null.
pipeName - name of the pipe to be created
watermark - With Paging On, it is the threshold at which objects are persisted to the System Store With Paging Off, it is the maximum queue size
pagesize -
Returns:
MemBufferQ
Throws:
Exception

getPipe

public static MemBufferQ getPipe(String instName,
                                 String pipeName)
                          throws Exception
This method returns a handle to a pipe with the specified instName and pipeName (if it already exists). If the pipe does not exist, then this method throws an Exception.

Parameters:
instName - name of the instance. Default instance will be used if this param is null.
pipeName - name of the pipe to be returned
Returns:
MemBufferQ
Throws:
Exception

deletePipe

public static void deletePipe(String instName,
                              String pipeName)
                       throws Exception
Deletes the specified pipe from the specified instance. Drops the associated table in System Store with the specified memory queue (if it’s a persistent queue). This method throws an exception if the pipe name is invalid or does not exist.

Parameters:
instName - name of the instance. Default instance will be used if this param is null.
pipeName - name of the pipe to be deleted
Throws:
Exception

deletePipe

public static void deletePipe(String pipeName)
                       throws Exception
Deletes specified pipe from default instance Drops the associated table in System Store with the specified memory queue (if it’s a persistent queue). This method throws an exception if the pipe name is invalid or does not exist.

Parameters:
pipeName - name of the pipe to be deleted
Throws:
Exception

getExternalProperty

public Object getExternalProperty(String propName)
                           throws Exception
Get external property using delegator object

Throws:
Exception

setExternalProperty

public void setExternalProperty(String propName,
                                Object value)
                         throws Exception
Set external property using delegator object

Throws:
Exception

getExternalProperty

public Object getExternalProperty(String extObj,
                                  String propName)
                           throws Exception
Get external property from specific extprop object

Throws:
Exception

setExternalProperty

public void setExternalProperty(String extObj,
                                String propName,
                                Object value)
                         throws Exception
Set external property in a specific extprop object

Throws:
Exception

getExtProp

public ExternalPropertiesConfig getExtProp(String name)
                                    throws Exception
Returns a named extprop object.

Throws:
Exception

binaryGUIDtoString

public String binaryGUIDtoString(byte[] binaryData)
Generates the hexadecimal String representation of an Active Directory GUID based on its 128-bit binary representation. The String representation of a GUID has the form "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}". The digits used are the hexadecimal digits 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E and F.

Parameters:
binaryData - a 16-byte byte array, holding the 128-bit binary representation of the GUID.
Returns:
The hexadecimal String representation of the binary GUID.

removeInvalidXMLChars

public static String removeInvalidXMLChars(String aString)

loadJarFile

public static void loadJarFile(String path)
Dynamically add jar file containing class definitions. ITDI has a loader that finds all classes in jar files in the jars directory of the installation folder. If you want to dynamically add additional jar files, you can use this method. An alternative to dynamically loading additional jar files, is to set the "com.ibm.di.loader.userjars" property in global.properties.

Parameters:
path - The full path name of a jar file or a directory containing jar files
See Also:
IDILoader.addFiles(String)

getTDIProperties

public TDIProperties getTDIProperties()
                               throws Exception
Returns the TDIProperties object for the current configuration

Throws:
Exception

getTDIProperty

public Object getTDIProperty(String name)
                      throws Exception
Returns the value for a TDI property

Parameters:
name - The name of the property
Throws:
Exception

getTDIProperty

public Object getTDIProperty(String propstore,
                             String name)
                      throws Exception
Returns the property value from a specific TDI property store "@param propstore The property store name

Parameters:
name - The name of the property
Throws:
Exception

setTDIProperty

public void setTDIProperty(String name,
                           Object value)
                    throws Exception
Sets the property value for a property (store selection based on naming rules and order) "@param propstore The property store name

Parameters:
name - The name of the property "@param value The property value
Throws:
Exception

setTDIProperty

public void setTDIProperty(String propstore,
                           String name,
                           Object value)
                    throws Exception
Sets the property value in a specific TDI property store "@param propstore The property store name

Parameters:
name - The name of the property "@param value The property value
Throws:
Exception

startsWithIC

public static boolean startsWithIC(String first,
                                   String second)
Returns true if the first String starts with the second String, ignoring case. If at least one if the Strings are null, returns false.

Parameters:
first - The first String
second - The second String
Returns:
true if and only if the first String starts with the second String, ignoring case
Since:
6.1.1

endsWithIC

public static boolean endsWithIC(String first,
                                 String second)
Returns true if the first String ends with the second String, ignoring case If at least one if the Strings are null, returns false.

Parameters:
first - The first String
second - The second String
Returns:
true if and only if the first String ends with the second String, ignoring case
Since:
6.1.1

containsIC

public static boolean containsIC(String first,
                                 String second)
Returns true if the second String is a substring of the first, ignoring case. If at least one if the Strings are null, returns false. Examples:

 containsIC("abcde", "BCD"); // Returns true
 containsIC("abcde", "bd");  // Returns false
    

Parameters:
first - The first String
second - The second String
Returns:
true if and only if the first String contains the second String, ignoring case
Since:
6.1.1

getTDIExpression

public static ParameterSubstitution getTDIExpression(String pattern)
                                              throws Exception
Throws:
Exception

substitute

public static String substitute(String pattern,
                                Map params)
                         throws Exception
Performs a one-time parsing and substitution of pattern with the objects available in params. This method uses a Map object where you provide the available objects for pattern expansion. You should at least provide "mc=MetamergeConfig" or "config=BaseConfiguration" object, otherwise expansion of TDI-properties will not work. If you want to expand alcomponent parameters, you need to provide a "config=BaseConfiguration" object. Here is some sample code that uses this method:
     map = new java.util.HashMap();
     map.put("mc", main.getMetamergeConfig());
     map.put("work", work);
     result = system.substitute("{work.cn} {property.myprop}", map);
 

Parameters:
pattern - The pattern string to expand
params - The available objects (e.g. conn, work, task etc)
Returns:
The expanded string
Throws:
Exception

substitute

public static String substitute(String pattern,
                                String[] names,
                                Object[] objects)
                         throws Exception
Performs a one-time parsing and substitution of pattern with named objects. You should at least provide "mc=MetamergeConfig" or "config=BaseConfiguration" objects, otherwise expansion of TDI-properties will not work. If you want to expand alcomponent parameters, you need to provide a "config=BaseConfiguration" object. Here is some sample code that uses this method:
     result = system.substitute("{work.cn} {property.myprop}", ["mc", "work"], [main.getMetamergeConfig(), work]);
 

Parameters:
pattern - The pattern string to expand
names - The names of the available objects (e.g. "conn", "work", "task" etc)
objects - The available objects (e.g. conn, work, task etc)
Returns:
The expanded string
Throws:
Exception