Built-In Namespace String

Method Summary
Method Attributes	Method Name and Description
	convertIP(radix) Converts an IP address in a number of input forms into the standard dotted-quad notation used by Sentinel.
	hash(format, algo) This method calculates the one-way hash of an input string, and returns the hash.
	insert(start, num, ins) Inserts a string at a specified character position, replacing that character
	parseBase64() This method converts the string from Base64 encoding to a regular string.
	parseEmail() This method converts a standard RFC822 e-mail address to normalized form.
	parseHost() This method converts a fully qualified domain (DNS) name into a normalized form.
	parseLDAP() Converts an LDAP-formatted string into an object with separate attributes to contain the CN and the rest of the directory structure.
	parseNTDomainUser() This method converts the string from Base64 encoding to a regular string.
	parseNVP(pairSep, NVSep, quote) The parseNVP() function converts a string in name-value pair format into a hash where each value can be retrieved by its name.
	parsePath() Converts a standard path into a normalized form.
	parseSyslog() Parse a Syslog string.
	safesplit(delim, quote) Splits a string into substrings based on a delimiter character.
	trim() Removes whitespace from the beginning and end of the string.

Method Detail

{String} convertIP(radix)

Converts an IP address in a number of input forms into the standard dotted-quad notation used by Sentinel.
Defined in: utils.js.

Parameters:
{Number} radix: The radix of the input; 16 for hex, 8 for octal, etc. Default is 10 for decimal.

Returns:: {String} The converted IP address in normalized, dotted-quad form (network order)

{String} hash(format, algo)

This method calculates the one-way hash of an input string, and returns the hash. This method is used to calculate the one-way hash of an input string, which can then be used to ensure that strings are not modified, for anonymization, or for any other purpose for which hashes are useful. At this time, the only supported hash algorithm is SHA-1, but parameters are supplied for future extensions.
Defined in: utils.js.

var string="This is my messge.";
var hash=string.hash();

Parameters:
{String} format: Output format for the hash ('HEX' or 'B64' for hex (default) and base64, respectively)
{String} algo: Algorithm to be used to calculate the hash value ('SHA-1' is the default, and only supported method at this time)

Returns:: {String} A string representing the hash value calculated from the source string.

{String} insert(start, num, ins)

Inserts a string at a specified character position, replacing that character
Defined in: utils.js.

var str = "this is a string";
var newstr = str.insert(8, 1, "my");

Parameters:
{Number} start: Character position in the string at which the inserted string should be placed.
{Number} num: Number of characters to consume while inserting string
{String} ins: String to insert into this

Returns:: {String}

parseBase64()

This method converts the string from Base64 encoding to a regular string. Note that in general you should only attempt to decode strings; decoding binary data may cause issues.
Defined in: utils.js.

var string="SGVsbG8sIHdvcmxk";
var outstring=string.parseBase64();

{Hash} parseEmail()

This method converts a standard RFC822 e-mail address to normalized form. This method will take a normal RFC822 e-mail address like "user@netiq.com" and convert it into an object with separate attributes for the user name and the domain name. The returned object has two fields:

username: The user name or alias in the e-mail address (e.g. "user")
domain: The DNS fully-qualified domain name within which that user resides (e.g. "netiq.com")

Example:

var myemail = "user@netiq.com";
rec.userobj = myemail.parseEmail();
// In Rec2Evt.map, insert the following:
TargetUserName,userobj.username
TargtUserDomain,userobj.domain

Defined in: utils.js.

Returns:: {Hash} Two-attribute object with username and domain from email string

{Hash} parseHost()

This method converts a fully qualified domain (DNS) name into a normalized form. This method will take a normal fully-qualified domain (DNS) name like "www.netiq.com" and convert it into an object with separate attributes for the host name and the domain name. The returned object has two fields:

basename: The localized host name of the host referenced (e.g. "www")
domain: The DNS domain within which that host resides (e.g. "netiq.com")

Note that if you pass an IP to this method, it will return the attribute ip instead of hostname and domain - you should check if ip is set if there's any concern that this condition might occur.

Example:

var myhost = "www.netiq.com";
rec.hostobj = myhost.parseHost();
// In Rec2Evt.map, insert the following:
SourceHostName,hostobj.basename
SourceHostDomain,hostobj.domain

Defined in: utils.js.

Returns:: {Hash} Two-attribute object with hostname and domain from host string

{Hash} parseLDAP()

Converts an LDAP-formatted string into an object with separate attributes to contain the CN and the rest of the directory structure. This method will take a normal LDAP string (CN=user1.OU=users.OU=engineering.O=novell) and convert it into an object with separate attributes for the base name and domain (in Sentinel parlance. This object has two fields:

basename: The base common name of the object (ex. "user1")
domain: the rest of the path for the object, in slash notation (ex. "\novell\engineering\users")

Example:

var ldapuser = "CN=user1.OU=users.OU=engineering.O=novell";
rec.ldapobj = ldapuser.parseLDAP();
// In Rec2Evt.map, modify the lines to say:
InitUserName,ldapobj.basename
InitUserDomain,ldapobj.domain

Defined in: utils.js.

Returns:: {Hash} Two-attribute object with basename and domain from LDAP string

parseNTDomainUser()

var string="DOMAINNAME\Username";
var outstring=string.parseBase64();

{Hash} parseNVP(pairSep, NVSep, quote)

The parseNVP() function converts a string in name-value pair format into a hash where each value can be retrieved by its name. For example, the string "name=value" would be converted to obj["name"] = value.

Note that in some cases you may need to pre-process your string to avoid confusion. Quoting in particular can be thorny, and you'll need to make sure there are no unquoted characters that look like separators but really aren't.

Example:

var input='a=1 b=2 c=hello d="one token"'
input.parseNVP(" ","=",'"')

Defined in: utils.js.

Parameters:
{char} pairSep: Character(s) that separate one entry pair from another
{char} NVSep: Character(s) that separate names from values in a single pair
{char} quote: Quote character used for values; if '[', '(', or '{' are used this function will look for the natural closing bracket to end a quoted section.

Returns:: {Hash} Map of names (attributes) to values

{Object} parsePath()

Converts a standard path into a normalized form. This method will take standard Unix and Windows paths and transform them into a normalized form. It returns this normalized form as an object containing two elements: this.object : the terminal element in the path, e.g. the name of the actual object this.context : the slash-separated path which defines the namespace in which that object is contained. Often these elements will ultimately be assigned to TargetDataName and TargetDataContainer in the output event.
Defined in: utils.js.

Returns:: {Object} Two-element object that contains an 'object' attribute and a 'context' attribute.

{Hash} parseSyslog()

Parse a Syslog string. Note that this method assumes strict RFC3164 compliance, namely: Mon DD HH:MM:SS (host) (message) Also: Syslog messages lack a year, so this method assumes that events were generated in the current year *except* if the month is December and the current month is January.
Defined in: utils.js.

Returns:: {Hash} Three-attribute object with date, host, and message from Syslog string

{String[]} safesplit(delim, quote)

Splits a string into substrings based on a delimiter character. The safesplit() method works like the split() method, except that it protects quoted text sections from being split at the delimiter. It will strip quotes from any token that ends up being an entire output token (and will de-escape embedded quotes); otherwise it will leave quotes and escapes intact.

Note: does not support the "howmany" argument from split().

Example:

var input1='token1,token2,"token3,including this",token4,token5\\"embedded quote'
var output1=input1.safesplit();
var input2="this (string) used (parentheses) as quote (chars) \(but not this one\)"
var output2=input2.safesplit(" ","(");

Defined in: utils.js.

Parameters:
{char} delim: The delimiter (n char substring) to split the string on - does NOT support empty string
{char} quote: The quote character; if '[', '(', or '{' are used this function will look for the natural closing bracket to end a quoted section.

Returns:: {String[]} An output array of token strings

{String} trim()

Removes whitespace from the beginning and end of the string.
Defined in: utils.js.

Returns:: {String} The trimmed string

Classes

Built-In Namespace String