4.5 Utility Functions (formula.util)

Replace an instance of one string within String s with another string.

JavaScript defines a replace function for any string that can be used similarly. For example:

var s = 'bill me'
writeln ( formula.util.searchAndReplace( s, 'me', 'you' ) )

It is possible to URL-encode a string to allow transmission as text. Operations Center distinguished names are components of URL-encoded strings.

JavaScript defines an encodeURL function that takes any string that can be used similarly. For example:

try { 
var baseDName = 'element.dname' // Assumes element in-scope
var className = 'Router:Cisco'
var dname = formula.util.encodeURL( className ) + '=' + formula.util.encodeURL( name ) + '/' + baseDName
}

It is possible to URL-decode a string to allow transmission as text. Operations Center distinguished names are components of URL-encoded strings.

JavaScript defines a decodeURL function that takes any string that can be used similarly. For example:

js> var s = 'String to encode: @#$%^&*'
js> var encoded = formula.util.encodeURL( s )
js> encoded
String+to+encode%3A+%40%23%24%25%5E%26*
js> formula.util.decodeURL( encoded )
String to encode: @#$%^&*
js>

It is possible to encode a string as allowed within an XML document. For example, XML documents cannot contain the & (ampersand) character. This function turns the & string into the string & which is suitable for an XML document fragment. For example:

js> var s = 'String to encode: &<>"'
js> formula.util.encodeXML( s )
String to encode: &amp;&lt;&gt;&quot;
js>

The breakOnTokens function subdivides one string and returns an array of strings. The tok parameter is a string representing the break pattern. For example:

js> s = 'one|two|three'
one|two|three
js> a = formula.util.breakOnTokens( s, '|' )
[Ljava.lang.String;@152c4d9
js> a[0]
one
js> a[1]
two
js>

The breakOnCommas function subdivides a string using the comma character as the token. For example:

js> s = 'one,two,three'
one,two,three
js> a = formula.util.breakOnCommas( s )
[Ljava.lang.String;@f99ff5
js> a[1]
two

This function uses the supplied command line to execute the supplied program and return the output as a java.io.InputStream. It provides an environment array for supplying environment variables to the program when it runs. For example:

var stream = formula.util.captureOutputStream( 'cmd /c echo %FOO%', [ 'foo=bar' ] )
writeln( new java.lang.String( formula.util.toByteArray( stream ) ) )

This function uses the supplied command line to execute the supplied program and return the output as a java.io.InputStream. For example:

var stream = formula.util.captureOutputStream( 'cmd /c echo %FOO%' )
writeln( new java.lang.String( formula.util.toByteArray( stream ) ) )

This function uses the supplied command line to execute the supplied program and return the output as a string. It provides an environment array for supplying environment variables to the program when it runs. For example:

js> var s = formula.util.captureOutputString( 'cmd /c echo %FOO%', [ 'foo=bar' ] )
js> s
bar

This function uses the supplied command line to execute the supplied program and return the output as a string. For example:

js> var s = formula.util.captureOutputString( 'cmd /c echo %FOO%' )
js> s
%FOO%

Regular expressions contain matching criteria, such as the period (.) and asterisk (*) characters. This function replaces these regular expression characters with escaped (\) string sequences to enable a literal match. For example:

js> s = 'dir *.*'
dir *.*
js> t = formula.util.escapeRegExp( s )
dir \*\.\*

This function copies one java.io.InputStream to an instance of a java.io.OutputStream. This function can throw a java.io.IOException, so place appropriate try/catch directives around its use. For example:

js> input = new java.io.FileInputStream( 'C:\\Config.Sys' )
java.io.FileInputStream@2d9c06
js> output = new java.io.FileOutputStream( 'C:\\Config.Sys.Copy' )
java.io.FileOutputStream@7b6889
js> formula.util.copyStream( input, output )
js> input.close()
js> output.close()

This function returns the contents of a java.io.InputStream as a byte array. A byte array can be a constructor argument to java.lang.String, so it is possible to use this function in combination to return the contents of a stream as a string. This function can throw a java.io.IOException, so place appropriate try/catch directives around its use. For example:

js> input = new java.io.FileInputStream( 'D://OperationsCenter_install_path/database//Adapters.ini' )
java.io.FileInputStream@99681b
js> ba = formula.util.toByteArray( input )
[B@181edf4
js> s = new java.lang.String( ba )

[Tivoli T/EC(r) on reason, iv]
AdapterInstanceId=3
ElementsTimeout=300
EventConsoleName=@Formula
AcknowlegeAvailable=true
SeedFile=
SyncClass=TEC_Sync
AlarmColumns=Status,Class,Description
AckAffectsCondition=true
Script.onInitialized=
SeverityMapping=Fatal=Critical;Critical=Critical;Minor=Minor;Warning=Major;Harmless=Informational;Unknown=Unknown
ClosedAlarmsTimeout=0
SuppressionTime=1800
CloseAvailable=true
HostsToMine=reason
TecORBPort=1576
Script.onStarted=
HierarchyFile=examples/TecHierarchy.xml
EventListenPort=54321
Script.onStopped=
StylesheetFile=
Class=com.mosol.Adapter.TEC.Adapter
MaxAlarms=500
WTDumperCommand=wtdumper -o DESC -dw "status<='20' AND severity>='20'"
SuppressAvailable=true
MiningLimit=2000
startOnStartup=false

This function uses the candidate file name to change the string contents to an allowed file system compatible string. For example:

js> s = 'Make A Good File For This: %^*()!@#$'
Make A Good File For This: %^*()!@#$
js> formula.util.nameToFile( s )
Make_A_Good_File_For_This__%^*()!@#$
js>

This function centers the supplied java.awt.* resource (window or derivative) on the screen. For example:

js> f = new java.awt.Frame( 'My Frame' )
java.awt.Frame[frame0,0,0,0x0,invalid,hidden,layout=java.awt.BorderLayout,title=My Frame,resizable,normal]
js> f.setSize( 600, 400 )
js> formula.util.center( f )
js> f.setVisible( true )
js> f.addWindowListener( new java.awt.event.WindowAdapter() {
   windowClosing: function( evt ) { f.setVisible( false ) } } )

Close this window by clicking the Close button in the title bar frame after it displays. This example also shows how to add a java/awt window listener by using the inner class analog in JavaScript.

This function manufactures a remote proxy for the supplied JavaScript object, suitable for sending to a remote target. Scripting uses this between client and server scripts to send callback and other remote reference code that can be accessed remotely. For example:

js> callback =
{
   callme: function() { writeln( 'Thanks for calling' ) }
}
[object Object]
js> remoted = formula.util.makeRemote( callback )
js>

JavaScript does not contain the concept of Java synchronization. Use this function to allow the standard notify method for any supplied object. For example:

var o = new java.lang.Object()
formula.util.notify( o )

JavaScript does not contain the concept of Java synchronization. Use this function to allow the standard notifyAll method for any supplied object. For example:

var o = new java.lang.Object()
formula.util.notifyAll( o )

JavaScript does not contain the concept of Java synchronization. Use this function to allow the standard notify method for any supplied object. The timeout is the wait time in milliseconds. Set it to –1 to indicate an infinite wait. For example:

var o = new java.lang.Object()
formula.util.wait( o , ‑1 )

This function sends an alphanumeric page to an SNPP (Simple Network Paging Protocol) paging gateway. Required arguments are pagerid and message. The host and port are the destination targets of the SNPP gateway. For more information about SNPP, go to http://www.snpp.info. For example:

formula.util.page( 3331122, 'Can you help me?', 'pagegw.net', 444 ) 

This is a property containing the name of the user who executes the script. For example:

writeln( formula.util.user )

UString is a helper class that obtains a unique string cached in a string pool. The getString() method obtains the string. Only one copy of the string exists in memory if this method is called. For example:

general = formula.util.UString.getString( 'general' )
class = formula.util.UString.getString( 'class' )

The ORB class is the utility class that wraps the CORBA ORB concept into a CORBA-portable abstraction. This generally is not used in scripts, except to stringify and destringify remote object references. These are standard methods of the CORBA binding for Java as defined by the OMG. For example:

s = formula.util.ORB.init().object_to_string( session )
writeln( s )

The Postemsg class sends a message to a Tivoli^* T/EC RIM. Construct the class with the argument signature (String serverName, String cls, String adapter).

An instance of the Postemsg class has properties that can be set or retrieved:

An instance of the Postemsg class that is set for sending goes to the RIM using the sendMessage() method. For example:

var postemsg = new formula.util.Postemsg( 'qasun', ‘LogFile_Base', 'Formula' )
postemsg.severity = 'HARMLESS'
postemsg.sendMessage( 'Something bad has happened; please check' )

The TelnetFrame class opens a telnet session directly to network management systems, where supported. The Administration > Server > Console Definitions > Default element uses the following code to define a Console menu option for applicable NMS elements.

var consoleFrame = formula.util.TelnetFrame(); 
var params = java.util.Hashtable(); 
params.put( "targetName", element.getName() ); 
params.put( "address", host.toString() ); 
params.put( "port", port.toString() ); 
params.put( "targetIcon",  element.getLabel().getIcon() ); 
consoleFrame.setParams( params ); 
consoleFrame;  

The ViewBuilder class allows an XML document that conforms to the Operations Center views DTD to be processed through the Operations Center console View generator gateway within Operations Center. The only methods of significance to an instance of this class are:

For example:

try  
{
   var vb = new formula.util.ViewBuilder()
   vb.buildFromFile( '/myviewbuilder.xml' )
}
catch( Exception )
{
   formula.log.error( 'Could not build from view builder: ' + Exception )
}