DataStage Functions used in pipelines Expression Builder
Use these DataStage functions in Orchestration Pipelines code editors, for example, to define a user variable or build an advanced condition.
Syntax for Expression Builder functions
In the syntax for arguments, brackets indicate that an argument is optional.
A parameter might accept data of any type. You can input an argument of type string, int, float, null, and other types. For example, the function IsNull(input (any)) accepts the following parameter types, but is not exclusive to
the following types:
ds.IsNull(1)
ds.IsNull("try null")
ds.IsNull(1.78)
ds.IsNull(null)
The Expression Builder uses these categories for coding functions:
Conversion functions
Converts a single data element format to another.
Ascii
Converts the values of characters in a string from EBCDIC to ASCII format.
Syntax
ds.Ascii(input (string))
returns: the EDBCDI string converted to a resulting ASCII string of format string.
Example
The following code returns "65 66 67":
ds.Ascii("193 194 195")
Char
Returns an ASCII character from its numeric code value.
Syntax
ds.Char(code (uint8))
returns: the corresponding character of format char.
Example
The following example outputs the ASCII code 65 as the character A.
ds.Char(65)
Checksum
Returns a cyclic redundancy code value for a string.
Syntax
ds.Checksum(input (string))
returns: the checksum value of a format string that is cyclic redundancy code.
Example
The following code returns 57158:
ds.Checksum("This is any arbitrary string value")
CRC32
Uses the CRC32 function to return a 16-bit cyclical redundancy code.
Syntax
ds.CRC32(input (string))
returns: the result of format decimal.
Example
The following code returns 57158:
ds.CRC32("This is any arbitrary string value")
DateToString
Returns the string representation of the date. The default format string for dates is "%yyyy%mm%dd", so, for example, the date 2009-08-25 is stored as the decimal number 20090825. However, you can optionally specify a format string that sets how the date is stored in the decimal number. Format strings must specify a format that contains numbers only. For example, you cannot specify a format string such as "%yyyy-%mm-%dd", because the hyphen character (-) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%yyyy (four-digit year)
%yy (two-digit year)
%NNNNyy (two-digit year with cutoff)
%mm (two-digit month)
%dd (two-digit day of month)
%ddd (three-digit day of year)
The literal digits 0 to 9 are also valid.
Syntax
ds.DateToString(date (date), [format (string)])
returns: the date in string format.
Example
If mylink.mydate contains the date 18th August, 2009, then the following code returns the string "2009-08-18":
ds.DateToString(mylink.mydate)
The following example outputs the date that is contained in the column mylink.mydate to a string with the format dd:mm:yyyy. If mylink.mydate contained the date 18th August, 2009, then the following
code returns the string "18:08:2009":
ds.DateToString(mylink.mydate, "%dd:%mm:%yyyy")
DateToDecimal
Returns the given date as a packed decimal value. The default format string for dates is "%yyyy%mm%dd", so, for example, the date 2009-08-25 is stored as the decimal number 20090825. However, you can optionally specify a format string that sets how the date is stored in the decimal number. Format strings must specify a format that contains numbers only. For example, you cannot specify a format string such as "%yyyy-%mm-%dd", because the hyphen character (-) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%yyyy (four-digit year)
%yy (two-digit year)
%NNNNyy (two-digit year with cutoff)
%mm (two-digit month)
%dd (two-digit day of month)
%ddd (three-digit day of year)
The literal digits 0 to 9 are also valid.
Syntax
ds.DateToDecimal(basedate (date), [format (string)])
returns: the date in decimal number format.
Example
If mylink.basedate contains the date 2012-08-18, then the following function stores the date as the decimal number 18082012:
ds.DateToDecimal(mylink.basedate, "%dd%mm%yyyy")
If mylink.basedate contains the date 2012-08-18, then the following function stores the date as the decimal number 20120818:
ds.DateToDecimal(mylink.basedate)
DecimalToDate
Returns the given packed decimal as a date. Both the sign and the scale of the decimal number are ignored when it is converted to a date. The default format string is "%yyyy%mm%dd", so, for example, the date 2009-08-25 is stored as the decimal number 20090825. However, you can optionally specify a format string that sets how the date is stored in the decimal number. Format strings must specify only a format that contains numbers. For example, you cannot specify a format string such as "%yyyy-%mm-%dd", because the hyphen character (-) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%yyyy (four-digit year)
%yy (two-digit year)
%NNNNyy (two-digit year with cutoff)
%mm (two-digit month)
%dd (two-digit day of month)
%ddd (three-digit day of year)
The literal digits 0 to 9 are also valid.
Syntax
ds.DecimalToDate(basedec (decimal), [format (string)])
returns: the decimal number in date format.
Example
If mylink.mydecdata contains the value 18082012, then the following function returns the date 2012-08-18:
ds.DecimalToDate(mylink.basedate, "%dd%mm%yyyy")
If mylink.mydecdata contains the value -201208.18, then the following function returns the date 2012-08-18:
ds.DecimalToDate(mylink.basedate)
DecimalToDecimal
Returns the given decimal in decimal representation. The argument rtype optionally specifies a rounding type, and is set to one of the following values:
ceil: Rounds the source field toward positive infinity. For example, 1.4 -> 2, -1.6 -> -1.
floor: Rounds the source field toward negative infinity. For example, 1.6 -> 1, -1.4 -> -2.
round_inf: Rounds or truncate the source field toward the nearest representable value, breaking ties by rounding positive values toward positive infinity and negative values toward negative infinity. For example, 1.4 -> 1,
1.5 -> 2, -1.4 -> -1, -1.5 -> -2.
trunc_zero: Discard any fractional digits to the right of the rightmost fractional digit supported in the destination, regardless of sign. For example, if the destination is an integer, all fractional digits are truncated. If
the destination is another decimal with a smaller scale, it rounds or truncates to the scale size of the destination decimal. For example, 1.6 -> 1, -1.6 -> -1.
Syntax
ds.DecimalToDecimal(decimal (decimal), [rtype (string)])
returns: the resulting decimal number.
Example
If mylink.mydec contains the decimal number 2.5345, the following function returns the decimal number 2.54:
ds.DecimalToDecimal(mylink.mydec,"ceil")
If mylink.mydec contains the decimal number 2.5345, the following function returns the decimal number 2.53.
ds.DecimalToDecimal(mylink.mydec,"floor")
If mylink.mydec contains the decimal number 2.5345, the following function returns the decimal number 2.53.
ds.DecimalToDecimal(mylink.mydec,"trunc_zero")
If mylink.mydec contains the decimal number 2.5345, the following function returns the decimal number 2.53.
ds.DecimalToDecimal(mylink.mydec,"round_inf")
DecimalToDFloat
Returns the given decimal in dfloat representation. The optional argument fix_zero specifies that all zero decimal values are regarded as valid (by default, decimal numbers that contain all zeros are treated as invalid).
Syntax
ds.DecimalToDFloat(decimal (decimal), ["fix_zero"])
returns: the decimal number in dfloat format.
Examples
If mylink.mydec contains the decimal number 00000004.00, the following function returns the dfloat number 4.
ds.DecimalToDFloat(mylink.mydec,"fix_zero")
If mylink.mydec contains the decimal number 00012344.00, the following function returns the dfloat number 12344.
ds.DecimalToDFloat(mylink.mydec,"fix_zero")
If mylink.mydec contains the decimal number 00012344.120, the following function returns the dfloat number 12344.12.
ds.DecimalToDFloat(mylink.mydec,"fix_zero")
If mylink.mydec contains the decimal number 00012344.120, the following function returns the dfloat number 12344.12.
ds.DecimalToDFloat(mylink.mydec)
If mylink.mydec contains the decimal number 00012344.000, the following function returns the dfloat number 12344.
ds.DecimalToDFloat(mylink.mydec)
DecimalToString
Returns the given decimal as a string. The argument fix_zero optionally specifies that all zero decimal values are regarded as valid (by default, decimal numbers that contain all zeros are treated as invalid). This covers the
case where the sign bits of the packed decimal representation are all 0 and all the content digits. This cast is not considered valid unless fix_zero is true.
Syntax
ds.DecimalToString(decimal (decimal), ["fix_zero"])
returns: the decimal number in string format.
Examples
If mylink.mydec contains the decimal number 00000004.00, the following function returns the string "4":
ds.DecimalToString(mylink.mydec,"suppress_zero")
If mylink.mydec contains the decimal number 00000004.00, the following function returns the string "0000000000000000000000000004.0000000000":
ds.DecimalToString(mylink.mydec,"fix_zero")
If mylink.mydec contains the decimal number 00000004.00, the following function returns the string "4":
ds.DecimalToString(mylink.mydec)
DecimalToTime
Returns the given packed decimal as a time. You can optionally specify a format string that specifies how the time is stored in the decimal number. The default format string is "%hh%nn%ss", so, for example, the time 14:03:22 is stored as the decimal number 140322. Format strings must specify a format that contains numbers only. For example, you cannot specify a format string such as "%hh:%nn:%ss", because the colon character (:) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%hh (two-digit hours that use 24-hour clock)
%nn (two-digit minutes)
%ss (two-digit seconds)
%ss.N (two-digit seconds, plus the number of fractional digits allowed. The number of fractional digits is from 1 - 6 inclusive).
The literal digits 0 to 9 are also valid.
If your specified format includes microseconds (for example, %ss.4), then the position of the decimal point is inferred in the decimal value. The position of the decimal point does not have to coincide with the specified scale of the decimal (for example, scale = 4).
Syntax
ds.DecimalToTime(decimal (decimal), [format (string)])
returns: The decimal in time format.
Example
If mylink.mytimedec contains the decimal value 200658, then the following function returns the time 20:06:58:
ds.DecimalToTime(mylink.mytimedec)
If the column mylink.mytimedec contains the decimal value 580620, then the following function returns the time 20:06:58:
ds.DecimalToTime(mylink.mytimedec, "%ss%nn%hh")
DecimalToTimestamp
Returns the given packed decimal as a timestamp. You can optionally specify a format string that specifies how the timestamp is stored in the decimal number. The default format string is "%hh%nn%ss", so, for example, the timestamp 2009-08-25 14:03:22 is stored as the decimal number 20090825140322. Format strings must specify a format that contains numbers only. For example, you cannot specify a format string such as "%yyyy/%mm/%dd%hh:%nn:%ss", because the slash character (/) and the colon character (:) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%yyyy (four-digit year)
%yy (two-digit year)
%NNNNyy (two-digit year with cutoff)
%mm (two-digit month)
%dd (two-digit day of month)
%ddd (three-digit day of year)
%hh (two-digit hours that use 24-hour clock)
%nn (two-digit minutes)
%ss (two-digit seconds)
%ss.N (two-digit seconds, plus the number of fractional digits allowed. The number of fractional digits is from 1 - 6 inclusive).
The literal digits 0 to 9 are also valid.
If your specified format includes microseconds (for example, %ss.4), then the position of the decimal point is inferred in the decimal value. The position of the decimal point does not have to coincide with the specified scale of the decimal (for example, scale = 4).
Syntax
ds.DecimalToTimestamp(decimal (decimal), [format (string)])
returns: The decimal in timestamp format.
Example
If mylink.mytimestampdec contains the value 19580818200658, then the following function returns the timestamp 1958-08-18 20:06:58:
ds.DecimalToTimestamp(mylink.mytimestampdec)
If link.mytimestampdec contains the decimal value 200658220818, then the following function returns the timestamp 2022-08-18 20:06:58:
ds.DecimalToTimestamp(mylink.mytimestampdec, "%hh%nn%ss%yy%mm%dd")
DFloatToDecimal
Returns the given dfloat in decimal representation. The argument rtype optionally specifies a rounding type, and is set to one of the following values:
ceil: Rounds the source field toward positive infinity. For example, 1.4 -> 2, -1.6 -> -1.
floor: Rounds the source field toward negative infinity. For example, 1.6 -> 1, -1.4 -> -2.
round_inf: Rounds or truncate the source field toward the nearest representable value, breaking ties by rounding positive values toward positive infinity and negative values toward negative infinity. For example, 1.4 -> 1,
1.5 -> 2, -1.4 -> -1, -1.5 -> -2.
trunc_zero: Discard any fractional digits to the right of the rightmost fractional digit supported in the destination, regardless of sign. For example, if the destination is an integer, all fractional digits are truncated. If
the destination is another decimal with a smaller scale, it rounds or truncates to the scale size of the destination decimal. For example, 1.6 -> 1, -1.6 -> -1.
Syntax
ds.DFloatToDecimal(number (dfloat), [rtype (string)])
returns: the decimal in dfloat format.
Examples
If mylink.myfloat contains the dfloat number 2.534, the following function returns the decimal number 2.54:
ds.DFloatToDecimal(mylink.mydec,"ceil")
If mylink.myfloat contains the dfloat number 2.534, the following function returns the decimal number 2.53:
ds.DFloatToDecimal(mylink.mydec,"floor")
If mylink.myfloat contains the dfloat number 2.534, the following function returns the decimal number 2.53:
ds.DFloatToDecimal(mylink.mydec,"trunc_zero")
If mylink.myfloat contains the dfloat number 2.534, the following function returns the decimal number 2.53:
ds.DFloatToDecimal(mylink.mydec,"round_inf")
DfloatToStringNoExp
Returns the given dfloat in its string representation with no exponent, by using the specified scale.
Syntax
ds.DfloatToStringNoExp(number (dfloat), scale (string))
returns: the dfloat number in string format.
Examples
If mylink.myfloat contains the dfloat number 2.534, then the following function returns the string "2.5":
ds.DfloatToStringNoExp(mylink.myfloat, "2")
Dtx
Converts a decimal integer to hexadecimal.
Syntax
ds.Dtx(number (int32), size(int8))
returns: the result of format string.
Example
The following code returns "002F":
ds.Dtx(47,4)
Ebcdic
Converts each character of an expression from its ASCII representation value to its EBCDIC representation value.
Syntax
ds.Ebcdic(input (string))
returns: the ASCII string converted to a resulting EDBCDII string.
Example
The following code returns "193 194 195 64 241 242 243":
ds.Ebcdic("ABC 123")
Iconv
Converts a string to an internal storage format.
Syntax
ds.Iconv(string (string), code (string))
returns: the internal storage format in string format.
Example
The following code returns 10740:
ds.Iconv("27 MAY 97", "D2")
The following code returns 10740:
ds.Iconv("1997 5 27", "D YMD")
IntToBool
Convert integer to bool type. Returns true for any nonzero value, and false for 0.
Syntax
ds.IntToBool(integer (int))
returns: the Boolean value of true or false.
Example
The value of 2 returns true.
ds.IntToBool(2)
IsValid
Returns whether the given string is valid for the given type.
Valid types are "date", "decimal", "dfloat", "sfloat", "int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "string", "time", "timestamp".
For data types of date, time, and timestamp, you can optionally specify a format string. The format string describes the format that your input data uses when it differs from the default formats for date, time, or timestamp. The default format for date is "%yyyy-%mm-%dd". The default format for time is "%hh:%mm:%ss". The default format for timestamp is "%yyyy-%mm-%dd %hh:%mm:%ss". This function does not log warnings.
Syntax
ds.IsValid(type (string), teststring (string), [format (string)])
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Example
If mylink.mystring contains the string "1", then the following function returns the value 1:
ds.IsValid("int8", mylink.mystring)
If mylink.mystring contains the string "380096.06", then the following function returns the value 0:
ds.IsValid("int8", mylink.mystring)
IsValidDate
Returns whether the given value is valid for the type date. This function logs warnings.
Syntax
ds.IsValidDate(testdate (date))
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
If mylink.mydate contains the date 2011-09-13, then the following function returns the value 1.
ds.IsValidDate(mylink.mydate)
If mylink.mydate contains the string "380096.06", then the following function returns the value 0, because the converted string is not a valid date.
ds.IsValidDate(mylink.mydate)
IsValidDecimal
Returns whether the given value is valid for the type decimal. If the allzerosflag is set to 0, then an all-zeros representation is not valid. The allzerosflag is set to 0 by default.
Syntax
ds.IsValidDecimal(testvalue (decimal), [allzerosflag (uint8)])
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Examples
If mylink.mynum contains the value 310007.65, then the following function returns the value 1.
ds.IsValidDecimal(mylink.mynum)
IsValidTime
Returns whether the given time is valid for the type time.
Syntax
ds.IsValidTime(testtime (time))
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Examples
If mylink.mytime contains the time 23:09:22, then the following function returns the value 1:
ds.IsValidTime(mylink.mytime)
IsValidTimestamp
Returns whether the given timestamp is valid for the type timestamp.
Syntax
ds.IsValidTimestamp(testtimestamp (timestamp))
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Examples
If mylink.mytimestamp contains the time 2011-09-13 23:09:22, then the following function returns the value 1:
ds.IsValidTimestamp(mylink.mytimestamp)
Oconv
Converts an expression to an output format.
Syntax
ds.Oconv(expression (string), conversion (string))
returns: the result to an output format of format string.
Example
The following code returns 1997-147:
ds.Oconv(10740, "D-YJ")
The following code returns 27 MAY 97:
ds.Oconv(10740, "D DMY, [A3,2]")
RawNumAt
Returns the integer value at the specified index value in the specified raw field. The index starts at 0.
Syntax
ds.RawNumAt(rawfield (string), index (int32))
returns: the integer value at the index in int32 format.
Examples
If the column mylink.myraw contains a raw value that is derived from the string "hello" (which is "{ 0x68 0x65 0x6C 0x6C 0x6F }"), then the following function returns the integer 104 (the ASCII code for the
character h):
ds.RawNumAt(mylink.myraw, 0)
If mylink.myraw contains a raw value that is derived from the string "hello" (which is "{ 0x68 0x65 0x6C 0x6C 0x6F }"), then the following function returns 0 because the specified index is out of range:
ds.RawNumAt(mylink.myraw, 12)
RawToString
Returns the given raw value as a string representation. You must ensure that the raw input value contains a sequence of bytes that are valid as characters in the target character set in which the output string is used.
For example, the raw value { 0xE0 0x41 0x42 } is not a valid sequence of UTF-8 characters, since the lead byte, 0xE0, is supposed to be followed by a byte in the range [0x80..0xBF].
If a raw value { xE0 x41 x42 } is passed to the RawToString function, an error might occur if the output string is then accessed as if it were encoded in UTF-8.
Syntax
ds.RawToString(rawfield (string))
returns: the given raw value as a string.
Examples
If mylink.myraw contains the value { 0x31 0x31 0x30 0x35 0x32 0x32 0x30 0x39 }, then the following function returns the string "11052209".
ds.RawToString(mylink.myraw)
Seq
Generates a numeric code value from an ASCII character. You can optionally specify the allow8bits argument to convert 8-bit ASCII values.
Syntax
ds.Seq(seq (char))
returns: the ASCII character numeric code.
Examples
The following example outputs the character A as the ASCII code 65.
ds.Seq("A")
SeqAt
Returns the numeric code point value of the character at the specified position in the given string. The index starts at 0. If the specified index is out of range, the function returns 0.
Syntax
ds.SeqAt(basestring (string), index (int32))
returns: numeric code point value of the character at the specified position in the given string in int32 format.
Examples
If mylink.mystring contains the string "horse", then the following function returns the value 0x6F (that is, the ASCII value of the character o).
ds.SeqAt(mylink.mystring, 1)
StringToBool
Converts string to bool type. Return false for empty string, return true for any other value.
Syntax
ds.StringToBool(string (string))
returns: the Boolean value of true or false.
Example
An empty string returns false.
ds.StringToBool("")
StringToDate
Returns a date from the given string in the specified format. You do not have to specify a format string if your string contains a date in the default format yyyy-mm-dd.
Syntax
ds.StringToDate(string (string), [format (string)])
returns: the string to date in the specified format.
Examples
If mylink.mystring contains the string "1958-08-18", then the following function returns the date 1958-08-18.
ds.StringToDate(mylink.mystring)
If mylink.mystring contains the string "18:08:1958", then the following function returns the date 1958-08-18.
ds.StringToDate(mylink.mystring,"%dd:%mm:%yyyy")
StringToDecimal
Returns the given string as a decimal representation. The argument rtype optionally specifies a rounding type, and is set to one of the following values:
ceil: Rounds the source field toward positive infinity. For example, 1.4 -> 2, -1.6 -> -1.
floor: Rounds the source field toward negative infinity. For example, 1.6 -> 1, -1.4 -> -2.
round_inf: Rounds or truncate the source field toward the nearest representable value, breaking ties by rounding positive values toward positive infinity and negative values toward negative infinity. For example, 1.4 -> 1,
1.5 -> 2, -1.4 -> -1, -1.5 -> -2.
trunc_zero: Discard any fractional digits to the right of the rightmost fractional digit supported in the destination, regardless of sign. For example, if the destination is an integer, all fractional digits are truncated. If
the destination is another decimal with a smaller scale, it rounds or truncates to the scale size of the destination decimal. For example, 1.6 -> 1, -1.6 -> -1.
Syntax
ds.StringToDecimal(string (string), [rtype (string)])
returns: the string in decimal format.
Examples
If mylink.mystring contains the string "19982.22", then the following function returns the decimal 19982.22.
ds.StringToDecimal(mylink.mystring)
If mylink.mystring contains the string "19982.2276", then the following function returns the decimal 19982.23.
ds.StringToDecimal(mylink.mystring,"ceil")
StringToRaw
Returns a string as its raw code value.
Syntax
ds.StringToRaw(string (string))
returns: the corresponding raw code value of the string.
Examples
If mylink.mystring contains the string "hello", then the following function returns the value "{0x68 0x65 0x6C 0x6C 0x6F}".
ds.StringToRaw(mylink.mystring)
StringToTime
Returns a time representation of the given string.
Syntax
ds.StringToTime(string (string), [format (string)])
returns: the string in time value.
Examples
If mylink.mystring contains the string "20:06:58", then the function returns a time of 20:06:58.
ds.StringToTime(mylink.mystring)
If mylink.mystring contains the string "20: 6:58", then the function returns a time of 20:06:58.
ds.StringToTime(mylink.mystring,"%(h,s):%(n,s):%(s,s)")
StringToTimestamp
Returns the given string in timestamp format.
Syntax
ds.StringToTimestamp(string (string), [format (string)])
returns: the string in timestamp format.
Examples
If mylink.mystring contains the string "1958-08-08 20:06:58", then the function returns the timestamp 1958-08-08 20:06:58.
ds.StringToTimestamp(mylink.mystring)
If mylink.mystring contains the string "8/ 8/1958 20: 6:58", then the function returns the timestamp 1958-08-08 20:06:58.
ds.StringToTimestamp(mylink.mystring, "%(d,s)/%(m,s)/%yyyy%(h,s):%(n,s):%(s,s)")
StringToUstring
Returns a ustring from the given string, optionally by using the specified map (otherwise, it uses project default).
Syntax
ds.StringToUstring(string (string), [mapname (string)])
returns: the string in ustring format.
Examples
If mylink.mystring contains the string "11052009", then the following function returns the ustring "11052009".
ds.StringToUstring(mylink.mystring)
TimestampToDate
Returns a date from the given timestamp.
Syntax
ds.TimestampToDate(timestamp (timestamp))
returns: the resulting date of the timestamp.
Examples
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the following function returns the date 1958-08-18:
ds.TimestampToDate(mylink.mytimestamp)
TimestampToDecimal
Returns the given timestamp as a packed decimal. The default format string is " %yyyy%mm%dd%hh%nn%ss". For example, the timestamp 2009-08-25 14:03:22 is stored as the decimal number 20090825140322. However, you can optionally specify a format string that sets how the date is stored in the decimal number. Format strings must specify a format that contains numbers only. For example, you cannot specify a format string such as "%yyyy/%mm/%dd%hh:%nn:%ss", because the slash character (/) and the colon character (:) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%yyyy (four-digit year)
%yy (two-digit year)
%NNNNyy (two-digit year with cutoff)
%mm (two-digit month)
%dd (two-digit day of month)
%ddd (three-digit day of year)
%hh (two-digit hours that use 24-hour clock)
%nn (two-digit minutes)
%ss (two-digit seconds)
%ss.N (two-digit seconds, plus the number of fractional digits allowed. The number of fractional digits is from 1 - 6 inclusive).
The literal digits 0 to 9 are also valid.
If your specified format includes microseconds (for example, %ss.4), then the position of the decimal point is inferred in the decimal value. The position of the decimal point does not have to coincide with the specified scale of the decimal (for example scale = 4).
Syntax
ds.TimestampToDecimal(timestamp (timestamp), [format (string)])
returns: the resulting timestamp in decimal format.
Examples
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the following function returns the decimal value 19580818200658:
ds.TimestampToDecimal(mylink.mytimestamp)
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the following function returns the decimal value 200658580818:
ds.TimestampToDecimal(mylink.mytimestamp, "%hh%nn%ss%yy%mm%dd")
TimestampToString
Returns the given timestamp as a string format.
Syntax
ds.TimestampToString(timestamp (timestamp), [format (string)])
returns: the resulting timestamp in string format.
Examples
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the function returns the string "1958-08-18 20:06:58".
ds.TimestampToString(mylink.mytimestamp)
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the function returns the string "18/08/1958 20:06:58":
ds.TimestampToString(mylink.mytimestamp, "%dd/%mm/%yyyy %hh:%nn:%ss")
TimestampToTime
Returns the given timestamp as the time format.
Syntax
ds.TimestampToTime(timestamp (timestamp), [format (string)])
returns: the resulting timestamp in time format.
Examples
If mylink.mytimestamp contains the timestamp 1958-08-18 20:06:58, then the function returns the time 20:06:58:
ds.TimestampToTime(mylink.mytimestamp)
TimeToString
Returns a string from the given time.
Syntax
ds.TimeToString(timestamp (timestamp), [format (string)])
returns: the result in time format.
Examples
If mylink.mytime contains the time 20:06:58, then the following function returns the string "20:06:58":
ds.TimeToString(mylink.mytime)
If mylink.mytime contains the time 20:06:58, then the following function returns the string "58:06:20":
ds.TimeToString(mylink.mytime, "%ss:%nn:%hh")
TimeToDecimal
Returns the given time as a packed decimal. The default format string is " %hh%nn%ss", so, for example, the time 14:03:22 is stored as the decimal number 140322. However, you can optionally specify a format string that specifies how the time is stored in the decimal number. Format strings can only specify a format that contains numbers. For example, you cannot specify a format string such as "%hh:%nn:%ss", because the colon character (:) cannot be stored in a packed decimal value. The following tokens are valid for conversions to or from decimal values:
%hh (two-digit hours that use 24-hour clock)
%nn (two-digit minutes)
%ss (two-digit seconds)
%ss.N (two-digit seconds, plus the number of fractional digits allowed. The number of fractional digits is from 1 - 6 inclusive).
The literal digits 0 to 9 are also valid.
If your specified format includes microseconds (for example, %ss.4), then the position of the decimal point is inferred in the decimal value. The position of the decimal point does not have to coincide with the specified scale of the decimal (for example scale = 4).
Syntax
ds.TimeToDecimal(time (time), [format (string)])
returns: the time in decimal format.
Examples
If mylink.mytime contains the time 20:06:58, then the following function returns the decimal value 200658:
ds.TimeToDecimal(mylink.mytime)
If mylink.mytime contains the time 20:06:58, then the following function returns the decimal value 580620:
ds.TimeToDecimal(mylink.mytime, "%ss%nn%hh")
UniChar
Generates a single Unicode character based on a decimal value, in the range 0 to 65535.
Syntax
ds.UniChar(expression (int32))
returns: the result of format string.
Example
The following code returns "õ":
ds.UniChar(0x00F5)
UniSeq
Generates a decimal value based on a single Unicode character.
Syntax
ds.UniSeq(expression (string))
returns: the corresponding decimal to the Unicode character of the format int32.
Example
The following code returns 195:
ds.UniSeq("ä")
UstringToString
Returns a string from the given ustring, optionally by using the specified map (otherwise uses the project default map).
Syntax
ds.UstringToString(string (ustring), [mapname(string)])
returns: the result in string format.
Examples
If mylink.myustring contains the ustring "11052009", then the following function returns the string "11052009":
ds.UstringToString(mylink.myustring)
Xtd
Converts a hexadecimal string to decimal.
Syntax
ds.Xtd(hexadecimal (string))
returns: the corresponding decimal value to the hexidecimal string.
Example
The following code returns 48879:
ds.Xtd("beef")
Int
Returns the integer portion of an expression. Any arithmetic operations that are specified are calculated by using the full accuracy of the system. The fractional portion of the value is truncated, not rounded, and the integer that remain is returned.
Syntax
ds.Int(expression (dfloat))
returns: the decimal value that is rounded and converted to type int64.
Example
The following code returns 454:
ds.Int(454.95)
The following code returns 2:
ds.Int(2.35)
Date and time functions
Use these functions for data and time functions in an expression.
Functions that specify dates, times, or timestamps in the arguments use strings with specific formats:
- For a date, the format is
%yyyy-%mm-%dd - For a time, the format is
%hh:%nn:%ss. If extended to include microseconds, the format is%hh:%nn:%ss.xwhere x gives the number of decimal places seconds is given to. - For a timestamp, the format is the date format followed by the time format.
Functions that have the days of the week in the argument take a string that specifies the day of the week. The day is specified as a three-letter abbreviation, or the full name. For example, the strings "thu" and "thursday" are both valid.
CurrentDate
Returns the date that the job runs.
Syntax
ds.CurrentDate()
returns: the current date in date format.
Examples
Use this function to get the current date.
ds.CurrentDate()
CurrentTime
Returns the time at which the job runs.
Syntax
ds.CurrentTime()
returns: the current time in time format.
Examples
Use this function to get the current time.
ds.CurrentTime()
CurrentTimeMS
Returns the time, including microseconds, at which the job runs.
Syntax
ds.CurrentTimeMS()
returns: the current time in time format, including microseconds.
Examples
Use this function to retrieve the current time and output the data.
ds.CurrentTimeMS()
CurrentTimestamp
Returns a timestamp that gives the date and time that the job runs.
Syntax
ds.CurrentTimestamp()
returns: the current timestamp in timestamp format.
Examples
Use this function to retrieve the current timestamp to the output data.
ds.CurrentTimestamp()
CurrentTimestampMS
Returns a timestamp, including microseconds, that gives the date and time that the job runs.
Syntax
ds.CurrentTimestampMS()
returns: the current timestamp in timestamp format.
Examples
Use this function to retrieve the current timestamp to the output data.
ds.CurrentTimestampMS()
Date
Returns a single numeric value of days that are elapsed between the internal system date and December 31, 1967, which is Day 0. All dates after are positive numbers that represent the number of days that are elapsed since Day 0. All dates before are negative numbers that represent the number of days before Day 0.
Syntax
ds.Date()
returns: the resulting date of format int.
Examples
If the current date is November 15, 1967, the following code returns -46. If the current date is February 15, 1968, the following code returns 46:
ds.Date()
DateFromDaysSince
Returns a date by adding an integer to a baseline date. The integer can be negative to return a date that is earlier than the baseline date.
Syntax
ds.DateFromDaysSince(number (int32), [baseline_date_object (string)])
returns: a date by adding an integer to a baseline date that the user enters.
Examples
If mylink.myintcol contains the integer 18250, and mylink.mydatecol contains the date 1958-08-18, then the three following functions are equivalent, and return the date 2008-08-05:
ds.DateFromDaysSince(18250,"1958-08-18")
ds.DateFromDaysSince(mylink.myintcol,"1958-08-18")
ds.DateFromDaysSince(mylink.myintcol,mylink.mydatecol)
If mylink.mynegintcol contains the integer -1, and mylink.mydatecol contains the date 1958-08-18, then the following three functions are equivalent, and return the date 1958-08-17:
ds.DateFromDaysSince(-1,"1958-08-18")
ds.DateFromDaysSince(mylink.mynegintcol,"1958-08-18")
ds.DateFromDaysSince(mylink.mynegintcol,mylink.mydatecol)
DateFromDaysSince2
Returns a date by adding an integer to a baseline date. The integer can be negative to return a date that is earlier than the baseline date.
Syntax
ds.DateFromDaysSince2(number (int32), [baseline_date_object (date)])
returns: a date by adding an integer to a baseline date that the user enters.
Examples
If mylink.myint contains the integer 18250, and mylink.mydate contains the date 1958-08-18, then the three following functions are equivalent, and return the date 2008-08-05:
ds.DateFromDaysSince2(18250,"1958-08-18")
ds.DateFromDaysSince2(mylink.myint,"1958-08-18")
ds.DateFromDaysSince2(mylink.myint, mylink.mydate)
If mylink.mynegint contains the integer -1, and mylink.mydate contains the date 1958-08-18, then the following three functions are equivalent, and return the date 1958-08-17:
ds.DateFromDaysSince2(-1,"1958-08-18")
ds.DateFromDaysSince2(mylink.mynegint,"1958-08-18")
ds.DateFromDaysSince2(mylink.mynegint, mylink.mydate)
DateFromComponents
Returns a date from the given years, months, and day of month that is given as three separate values.
Syntax
ds.DateFromComponents(years (int32), months (int32), dayofmonth (int32))
returns: a single date with the specified values.
Examples
If mylink.year contains the value 2010, mylink.month contains the value 12, and mylink.dayofmonth contains the value 2, then the two following functions are equivalent, and return the date 2010-12-02.
ds.DateFromComponents(2010, 12, 2)
ds.DateFromComponents(mylink.year, mylink.month, mylink.dayofmonth)
DateFromJulianDay
Returns a date from the given Julian day number.
Syntax
ds.DateFromJulianDay(julianday (uint32))
returns: the date of the Julian day value given.
Examples
If mylink.myjul contains the value 2454614, then the two following functions are equivalent, and return the date 2008-05-27.
ds.DateFromJulianDay(2454614)
ds.DateFromJulianDay(mylink.myjul)
DateOffsetByComponents
Returns the given date, with offsets applied from the given year offset, month offset, and day of month offset, given as three separate values. The offset values can each be positive, zero, or negative.
Syntax
ds.DateOffsetByComponents(basedate (date), year_offset (int32), month_offset (int32), dayofmonth_offset (int32))
returns: The given date offset of format date.
Examples
If mylink.basedate contains 2011-08-18 and mylink.yearos contains the value 2, mylink.monthos contains the value 0, and mylink.dayofmonthosol contains the value 0, then the two following
functions are equivalent, and return the date 2013-08-18.
ds.DateOffsetByComponents("2011-08-18", 2, 0, 0)
ds.DateOffsetByComponents(mylink.basedate, mylink.yearos, mylink.monthos, mylink.dayofmonthos)
If mylink.basedate contains 2011-08-18 and mylink.yearos contains the value -2, mylink.monthos contains the value 0, and mylink.dayofmonthosol contains the value 0, then the two following
functions are equivalent, and return the date 2009-08-18.
ds.DateOffsetByComponents("2011-08-18", -2, 0, 0)
ds.DateOffsetByComponents(mylink.basedate, mylink.yearos, mylink.monthos, mylink.dayofmonthos)
Day
Returns day of the month from the system date.
Syntax
ds.Day()
returns: day of the month in int format.
Examples
If the current date is 1967-12-31, the following code returns 31.
ds.Day()
DaysSinceFromDate
Takes a given date of type date and a source date of type string, and returns the number of days from the source date to the given date.
Syntax
ds.DaysSinceFromDate(given_date (date), source_date_string (string))
returns: the difference in days between the two given dates of type int32.
Examples
If mylink.mysourcedate contains the date 1958-08-18 and mylink.mygivendate contains the date 2008-08-18, then the two following functions are equivalent, and return the integer value 18263.
ds.DaysSinceFromDate(mylink.mygivendate, mylink.mysourcedate)
ds.DaysSinceFromDate("2008-08-18","1958-08-18")
DaysSinceFromDate2
Takes a given date of type date and a source date of type date, and returns the number of days from the source date to the given date.
Syntax
ds.DaysSinceFromDate2(given_date (date), source_date_object (date))
returns: the difference in days between the two given dates in int32 format.
Examples
If mylink.mysourcedate contains the date 1958-08-18 and mylink.mygivendate contains the date 2008-08-18, then the two following functions are equivalent, and return the integer value 18263.
ds.DaysSinceFromDate2(mylink.mygivendate, mylink.mysourcedate)
ds.DaysSinceFromDate2("2008-08-18","1958-08-18")
DaysInMonth
Returns the number of days in the month in the given base date.
Syntax
ds.DaysInMonth(basedate (date))
returns: the number of days in the month in int32 format.
Examples
If mylink.mysourcedate contains the date 1958-08-18, then the two following functions are equivalent, and return the integer value 31.
ds.DaysInMonth(mylink.mysourcedate)
ds.DaysInMonth("1958-08-18")
DaysInYear
Returns the number of days in the year in the given base date.
Syntax
ds.DaysInYear(basedate (date))
returns: the number of days in the year in int32 format.
Examples
If mylink.mysourcedate contains the date 2012-08-18, then the two following functions are equivalent, and return the integer value 366.
ds.DaysInYear(mylink.mysourcedate)
ds.DaysInYear("2012-08-18")
If mylink.mysourcedate contains the date 2011-08-18, then the two following functions are equivalent, and return the integer value 365.
ds.DaysInYear(mylink.mysourcedate)
ds.DaysInYear("2011-08-18")
DateOffsetByDays
Returns the given date offset by the given number of days. The offset value can be positive, zero, or negative.
Syntax
ds.DateOffsetByDays(basedate (date), dayoffset (int32))
returns: the date object with the corresponding offset.
Examples
If mylink.basedate contains 2011-08-18 and mylink.dayoffset contains the value 2, then the two following functions are equivalent, and return the date 2011-08-20.
ds.DateOffsetByDays("2011-08-18", 2)
ds.DateOffsetByDays(mylink.basedate, mylink.dayoffset)
If mylink.basedate contains 2011-08-18 and mylink.dayoffset contains the value -31, then the two following functions are equivalent, and return the date 2011-07-18.
ds.DateOffsetByDays("2011-08-18", -31)
ds.DateOffsetByDays(mylink.basedate, mylink.dayoffset)
HoursFromTime
Returns the hours portion of a time.
Syntax
ds.HoursFromTime(time (time))
returns: the hours value in int8 format.
Examples
If mylink.mytime contains the time 22:30:00, then the following two functions are equivalent, and return the integer value 22.
ds.HoursFromTime(mylink.mytime)
ds.HoursFromTime("22:30:00")
JulianDayFromDate
Returns a Julian day number from the given date.
Syntax
ds.JulianDayFromDate(time (time))
returns: the Julian day number in int32 format, of the specified date.
Examples
If mylink.mydate contains the date 2008-05-27, then the two following functions are equivalent, and return the value 2454614.
ds.JulianDayFromDate("2008-05-27")
ds.JulianDayFromDate(mylink.mydate)
MicroSecondsFromTime
Returns the microsecond portion of a time.
Syntax
ds.MicroSecondsFromTime(time (time))
returns: the microsecond value of the time, in int32 format.
Examples
If mylink.mytime contains the time 22:30:00.32, then the following function returns the value 320000:
ds.MicroSecondsFromTime(mylink.mytime)
MidnightSecondsFromTime
Returns the number of seconds from midnight to the given time.
Syntax
ds.MidnightSecondsFromTime(time (time))
returns: the second value from midnight to the time, in int8 format.
Examples
If mylink.mytime contains the time 00:30:52, then the two following functions are equivalent, and return the value 1852:
ds.MidnightSecondsFromTime("00:30:52")
ds.MidnightSecondsFromTime(mylink.mytime)
MinutesFromTime
Returns the minutes portion of a time.
Syntax
ds.MinutesFromTime(time (time))
returns: the minutes value of the time, in int8 format.
Examples
If mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the value 30:
ds.MinutesFromTime("22:30:52")
ds.MinutesFromTime(mylink.mytime)
MonthDayFromDate
Returns the day of the month from the given date.
Syntax
ds.MonthDayFromDate(date (date))
returns: the day of the month from the given date in int8 format.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 18:
ds.MonthDayFromDate("2008-08-18")
ds.MonthDayFromDate(mylink.mydate)
MonthFromDate
Returns the month number from the given date.
Syntax
ds.MonthFromDate(date (date))
returns: the number of the month of format int8.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions both return the value 8:
ds.MonthFromDate("2008-08-18")
ds.MonthFromDate(mylink.mydate)
WeekdayFromDate
Returns the day number of the week since the given date. You can specify the day that is regarded as the first in the week, and if not specified, it is Sunday by default.
Syntax
ds.WeekdayFromDate(date (date), [origin_day (string)])
returns: the day of the week since the given date in int8 format.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 1:
ds.WeekdayFromDate("2008-08-18")
ds.WeekdayFromDate(mylink.mydate)
If mylink.mydate contains the date 2008-08-18, and mylink.origin_day contains "saturday", then the following functions are equivalent, and return the value 2:
ds.WeekdayFromDate("2008-08-18", "saturday")
ds.WeekdayFromDate("2008-08-18", "sat")
ds.WeekdayFromDate(mylink.mydate, mylink.origin_day)
NextWeekdayFromDate
Returns the date of the specified day of the week soonest after the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, "thu".
Syntax
ds.NextWeekdayFromDate(sourcedate (date), day_of_week (string))
returns: the day of the month from the given date.
Examples
If mylink.mysourcedate contains the date 2008-08-18 and the day of the week that is specified is Thursday, then the two following functions are equivalent, and return the value 2008-08-21:
ds.NextWeekdayFromDate("2008-08-18", "thursday")
ds.NextWeekdayFromDate(mylink.mysourcedate, "thu")
NthWeekdayFromDate
Returns the date of the specified day of the week offset by the specified number of weeks from the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, thu. The offset values can be positive, negative, or zero.
Syntax
ds.NthWeekdayFromDate(basedate (date), day_of_week (string), week_offset (int32))
returns: the date of the specified weekday offset by weeks from the specified date.
Examples
If mylink.mydate contains the date 2009-08-18 and Thursday is specified with an offset of 1, then the two following functions are equivalent, and return the value 2009-08-20. The first occurrence of Thursday is returned. In
the proceeding example, the Thursday occurs in the same week as the date 2009-08-18. The date 2009-08-18 is a Tuesday.
ds.NthWeekdayFromDate("2009-08-18", "thursday", 1)
ds.NthWeekdayFromDate(mylink.mydate, "thu", 1)
If mylink.mydate contains the date 2009-08-18 and Thursday is specified with an offset of -2, then the two following functions are equivalent, and return the value 2009-08-06. The occurrence of the Thursday that is two Thursdays
past is returned.
ds.NthWeekdayFromDate("2009-08-18", "thursday", -2)
ds.NthWeekdayFromDate(mylink.mydate, "thu", -2)
PreviousWeekdayFromDate
Returns the date of the specified day of the week that is the most recent day before the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, "thu".
Syntax
ds.PreviousWeekdayFromDate(sourcedate (date), day_of_week (string))
returns: the date of the most recent weekday from the specified date.
Examples
If mylink.mysourcedate contains the date 2008-08-18 and Thursday is specified, then the two following functions are equivalent, and return the value 2008-08-14:
ds.PreviousWeekdayFromDate("2008-08-18", "thursday")
ds.PreviousWeekdayFromDate(mylink.mysourcedate, "thu")
SecondsFromTime
Returns the second portion of a time.
Syntax
ds.SecondsFromTime(time (time))
returns: the second value of the time in dfloat format.
Examples
If mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the value 52:
ds.SecondsFromTime("22:30:52")
ds.SecondsFromTime(mylink.mytime)
SecondsSinceFromTimestamp
Returns the number of seconds between two timestamp objects.
Syntax
ds.SecondsSinceFromTimestamp(timestamp (timestamp), timestamp_base_string (string))
returns: the second value in dfloat format.
Examples
If mylink.mytimestamp contains the timestamp 2008-08-18 22:30:52, and mylink.mytimestamp_base contains the timestamp 2008-08-19 22:30:52, then the two following functions are equivalent, and return the value -86400:
ds.SecondsSinceFromTimestamp("2008-08-18 22:30:52","2008-08-19 22:30:52")
ds.SecondsSinceFromTimestamp(mylink.mytimestamp, mylink.mytimestamp_base)
SecondsSinceFromTimestamp2
Returns the number of seconds between two timestamp objects.
Syntax
ds.SecondsSinceFromTimestamp2(timestamp (timestamp), timestamp_base_object (timestamp))
returns: the second value in dfloat format.
Examples
If mylink.mytimestamp contains the timestamp 2008-08-18 22:30:52, and mylink.mytimestamp_base contains the timestamp 2008-08-19 22:30:52, then the two following functions are equivalent, and return the value -86400:
ds.SecondsSinceFromTimestamp2("2008-08-18 22:30:52","2008-08-19 22:30:52")
ds.SecondsSinceFromTimestamp2(mylink.mytimestamp, mylink.mytimestamp_base)
Time
Returns a string value that expresses the internal time of day. The internal time is the number of seconds that passed since midnight to the nearest thousandth of a second (local time).
Syntax
ds.Time()
returns: the resulting time of format string.
Examples
If the current time is 11:17:43:19, the following code returns 40663.842:
ds.Time()
TimeDate
Returns the system time and date as a formatted string.
Syntax
ds.TimeDate()
returns: the system time and date in string format.
TimeFromComponents
Returns a date type time from the given hours, minutes, seconds, and microseconds as int32.
Syntax
ds.TimeFromComponents(hours (int32), minutes (int32), seconds (int32), microseconds (int32))
returns: the time in date type.
Examples
If mylink.hourcol contains the value 10, mylink.mincol contains the value 12, mylink.seccol contains the value 2, and mylink.mseccol contains 0, then the two following functions are equivalent, and return the time
10:12:02:
ds.TimeFromComponents(10, 12, 2, 0)
ds.TimeFromComponents(mylink.hourcol, mylink.mincol, mylink.seccol, mylink.mseccol)
TimeFromMidnightSeconds
Returns the system time in time format.
Syntax
ds.TimeFromMidnightSeconds(seconds (time))
returns: the seconds since midnight in time format.
Examples
If mylink.mymidnightseconds contains the value 240, then the two following functions are equivalent, and return the value 00:04:00:
ds.TimeFromMidnightSeconds(240)
ds.TimeFromMidnightSeconds(mylink.mymidnightseconds)
TimeOffsetByComponents
Returns the time, with offsets applied from the base time with hour offset, minute offset, and second offset, each given as separate values. The seconds offset can include partial seconds.
Syntax
ds.TimeOffsetByComponents(basetime (time), hour_offset (int32), minute_offset (int32), second_offset (dfloat))
returns: the time offset by specified values.
Examples
If mylink.basetime contains 14:05:29 and mylink.houros contains the value 2, mylink.minos contains the value 0, mylink.secos contains the value 20, then the two following functions are
equivalent, and return the time 16:05:49.
ds.TimeOffsetByComponents("14:05:29", 2, 0, 20)
ds.TimeOffsetByComponents(mylink.basetime, mylink.houros, mylink.minos, mylink.secos)
TimeOffsetBySeconds
Returns the given time, with offsets applied from the base time with seconds offset. The seconds offset can include partial seconds.
Syntax
ds.TimeOffsetBySeconds(basetime (time), second_offset (dfloat))
returns: the time with seconds offset by the specified value.
Examples
If mylink.basetime contains 14:05:29.30 and mylink.secos contains the value 2.5, then the two following functions are equivalent, and return the time 14:05:31.
ds.TimeOffsetBySeconds("14:05:29.30", 2.5)
ds.TimeOffsetBySeconds(mylink.basetime, mylink.secos)
TimestampFromDateTime
Returns a timestamp from the given date and time.
Syntax
ds.TimestampFromDateTime(date (date), time (time))
returns: the timestamp of the given date and time.
Examples
If mylink.mydate contains the date 2008-08-18 and mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the timestamp 2008-08-18 22:30:52:
ds.TimestampFromDateTime("2008-08-18","22:30:52")
ds.TimestampFromDateTime(mylink.mydate, mylink.mytime)
TimestampFromSecondsSince
Returns a timestamp that is derived from the number of seconds from the base timestamp object.
Syntax
ds.TimestampFromSecondsSince(seconds (dfloat), [base_timestamp_object (string)])
returns: the timestamp that is derived from the given value of seconds.
Examples
If mylink.myseconds contains the value 2563 and mylink.timestamp_base contains the timestamp 2008-08-18 22:30:52, then the two following functions are equivalent, and return the timestamp 2008-08-18 23:13:35:
ds.TimestampFromSecondsSince(2563,"2008-08-18 22:30:52")
ds.TimestampFromSecondsSince(mylink.myseconds,mylink.timestamp_base)
TimestampFromSecondsSince2
Returns a timestamp that is derived from the number of seconds from the base timestamp object.
Syntax
ds.TimestampFromSecondsSince2(seconds (dfloat), [base_timestamp_object (timestamp)])
returns: the timestamp that is derived from the given value of seconds.
Examples
If mylink.myseconds contains the value 2563 and mylink.timestamp_base contains the timestamp 2008-08-18 22:30:52, then the two following functions are equivalent, and return the timestamp 2008-08-18 23:13:35:
ds.TimestampFromSecondsSince2(2563,"2008-08-18 22:30:52")
ds.TimestampFromSecondsSince2(mylink.myseconds, mylink.timestamp_base)
TimestampFromTimet
Returns a timestamp from the given UNIX time_t string value.
Syntax
ds.TimestampFromTimet(timet_string (int32))
returns: the timestamp that is derived from the given value of seconds.
Examples
If mylink.mytimet contains the value 1234567890, then the two following functions are equivalent, and return the timestamp 2009-02-13 23:31:30:
ds.TimestampFromTimet(1234567890)
ds.TimestampFromTimet(mylink.mytimet)
TimestampFromTime2
Returns a timestamp from the given time and timestamp objects. The value in the time object overwrites the time value in the timestamp object so that only the date part is used from the timestamp.
Syntax
ds.TimestampFromTime2(time (time), timestamp (timestamp))
returns: the timestamp from the given time and timestamp objects.
Examples
If mylink.mytime contains the time 12:03:22 and mylink.mytimestamp contains the timestamp 2008-08-18 22:30:52, then the two following functions are equivalent, and return the timestamp 2008-08-18 12:03:22:
ds.TimestampFromTime2("12:03:22", "2008-08-18 22:30:52")
ds.TimestampFromTime2(mylink.mytime, mylink.mytimestamp)
TimestampOffsetByComponents
Returns the timestamp, with offsets applied from the base timestamp with year offset, month offset, day offset, hour offset, minute offset, and second offset, each given as separate values. The seconds offset can include microseconds.
Syntax
ds.TimestampOffsetByComponents(basetimestamp (timestamp), year_offset (int32), month_offset (int32), dayofmonth_offset (int32), hour_offset (int32), minute_offset (int32), second_offset (dfloat))
returns: the timestamp offset by specified values.
Examples
If mylink.basetimestamp contains 2009-08-18 14:05:29 and mylink.yearos contains 0, mylink.monthos contains the value 2, mylink.dayos contains the value -4, mylink.houros contains
the value 2, mylink.minos contains the value 0, mylink.secos contains the value 20, then the two following functions are equivalent, and return the timestamp 2009-10-14 16:05:49.
ds.TimestampOffsetByComponents("2009-08-18 14:05:29", 0, 2, -4, 2, 0, 20)
ds.TimestampOffsetByComponents(mylink.basetimestamp, mylink.houros,
mylink.minos, mylink.secos)
TimestampOffsetBySeconds
Returns the timestamp, with offsets applied from the base timestamp with seconds offset. The seconds offset can include microseconds.
Syntax
ds.TimestampOffsetBySeconds(basetimestamp (timestamp), second_offset (dfloat))
returns: the timestamp offset by specified values in timestamp format.
Examples
If mylink.basetimestamp contains 2009-08-18 14:05:29 and mylink.secos contains the value 32760, then the two following functions are equivalent, and return the timestamp 2009-08-18 23:11:29:
ds.TimestampOffsetBySeconds("2009-08-18 14:05:29", 32760)
ds.TimestampOffsetBySeconds(mylink.basetimestamp, mylink.secos)
TimetFromTimestamp
Returns a UNIX time_t value from the given timestamp.
Syntax
ds.TimetFromTimestamp(timestamp (timestamp))
returns: the UNIX time_t by given timestamp in int32 format.
Examples
If mylink.mytimestamp contains the value 2009-02-13 23:31:30, then the two following functions are equivalent, and return the value 1234567890:
ds.TimetFromTimestamp("2009-02-13 23:31:30")
ds.TimetFromTimestamp(mylink.mytimestamp)
YeardayFromDate
Returns the day number in the year from the given date.
Syntax
ds.YeardayFromDate(date (date))
returns: the day number in int16 format.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 231:
ds.YeardayFromDate("2008-08-18")
ds.YeardayFromDate(mylink.mydate)
YearFromDate
Returns the year from the given date.
Syntax
ds.YearFromDate(date (date))
returns: the year number in int16 format.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 2008:
ds.YearFromDate("2008-08-18")
ds.YearFromDate(mylink.mydate)
YearweekFromDate
Returns the week number in the year from the given date.
Syntax
ds.YearweekFromDate(date (date))
returns: the week number in int16 format.
Examples
If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 33:
ds.YearweekFromDate("2008-08-18")
ds.YearweekFromDate(mylink.mydate)
Month
Returns the current month.
Syntax
ds.Month()
returns: the current month.
Examples
The following code returns the current month in int format.
ds.Month()
Year
Returns the current year.
Syntax
ds.Year()
returns: the current year in int format.
Examples
The following code returns the current year.
ds.Year()
Operator functions
The operator functions compare two objects and returns a boolean value (true or false):
Equal to
Compares if two objects are the same.
Syntax
ds.EQ(object1 (any), object2 (any))
returns: true if the object value is equal, false otherwise.
Examples
The following expressions return true:
ds.EQ(null,null)
ds.EQ(true,true)
ds.EQ("1",1)
ds.EQ("1",1.0)
The following expressions return false:
ds.EQ(1,null)
ds.EQ(false,true)
ds.EQ("a","b")
Not equal to
Compares if two objects are not the same.
Syntax
ds.NE(object1 (any), object2 (any))
returns: true if the object value is not equal, false otherwise.
Examples
The following expressions return true:
ds.NE(1,null)
ds.NE(true,false)
ds.NE(false,true)
ds.NE("a","b")
The following expressions return false:
ds.NE(null,null)
ds.NE(true,true)
ds.NE(false,false)
ds.NE("a","a")
Less than
Takes two objects as parameters and returns true if the first object is less than the second.
Syntax
ds.LT(object1 (any), object2 (any))
returns: true if the first object is less than the second, false otherwise.
Examples
The following expressions return true:
ds.LT("a","b")
The following expressions return false:
ds.LT("a","a")
ds.LT("a","b")
ds.LT("202310071855","20380727")
Greater than
Takes two objects as parameters and returns true if the first object is greater than the second.
Syntax
ds.GT(object1 (any), object2 (any))
returns: true if the first object is greater than the second, false otherwise.
Examples
The following expressions return true:
ds.GT("b","a")
The following expressions return false:
ds.GT("a","a")
ds.GT("5.12","5.123")
Greater than or equal
Takes two objects as parameters and returns true if the first object is greater than or equal to the second.
Syntax
ds.GE(object1 (any), object2 (any))
returns: true if the first object is greater than or equal to the second, false otherwise.
Examples
The following expressions return true:
ds.GE(2, 1)
ds.GE("a","a")
Less than or equal
Takes two objects as parameters and returns true if the first object is less than or equal to the second.
Syntax
ds.LE(object1 (any), object2 (any))
returns: true if the first object is less than or equal to the second, false otherwise.
Examples
The following expressions return true:
ds.GE(1, 2)
ds.LE("a","a") == true
Logical functions
The logical functions perform bit operations.
BitAnd
Returns the bitwise AND of the two integer arguments.
Syntax
ds.BitAnd(number1 (uint64), number2 (uint64))
returns: the bitwise AND in uint64 format.
Examples
If mylink.mynumber1 contains the number 352 and mylink.mynumber2 contains the number 400, then the following two functions are equivalent, and return the value 256:
ds.BitAnd(352,400)
ds.BitAnd(mylink.mynumber1, mylink.mynumber2)
BitCompress
Returns the integer made from the string argument, which contains a binary representation of "1"s and "0"s.
Syntax
ds.BitCompress(string (string))
returns: the resulting number represented by binaries of the format uint64.
Examples
If mylink.mynumber1 contains the string "0101100000", then the following two functions both return the number 352.
ds.BitCompress("0101100000")
ds.BitCompress(mylink.mynumber)
BitExpand
Returns a string containing the binary representation in "1"s and "0"s of the given integer.
Syntax
ds.BitExpand(number (uint64))
returns: a string containing the binary representation of the integer.
Examples
If mylink.mynumber1 contains the number 352, then the following two functions are equivalent, and return the string "101100000".
ds.BitExpand(352)
ds.BitExpand(mylink.mynumber)
BitOr
Returns the bitwise OR of the two integer arguments.
Syntax
ds.BitOr(number1 (uint64), number2 (uint64))
returns: the bitwise OR of the two integer arguments.
Examples
If mylink.mynumber1 contains the number 352 and mylink.mynumber2 contains the number 400, then the following two functions are equivalent, and return the value 496:
ds.BitOr(352,400)
ds.BitOr(mylink.mynumber1, mylink.mynumber2)
BitXOr
Returns the bitwise Exclusive OR of the two integer arguments.
Syntax
ds.BitXOr(number1 (uint64), number2 (uint64))
returns: the Exclusive OR in uint64 format.
Examples
If mylink.mynumber1 contains the number 352 and mylink.mynumber2 contains the number 400, then the following two functions are equivalent, and return the value 240:
ds.BitXOr(352,400)
ds.BitXOr(mylink.mynumber1, mylink.mynumber2)
Not
Returns the complement of the logical value of an expression. If the value of the expression is true, the Not function returns a value of false (0). If the value of the expression is false, the NOT function returns
a value of true (1). A numeric expression that evaluates to 0 is a logical value of false. A numeric expression that evaluates to anything else, other than the null value, is a logical true. An empty string is logically false. All other
string expressions, including strings that include an empty string, spaces, or the number 0 and spaces, are logically true.
Syntax
ds.Not()
returns: the value of complement in int8 format.
Examples
If mylink.myexpression contains the expression 5-5, then the following two functions are equivalent, and return the value 1:
ds.Not(5-5)
ds.Not(mylink.myexpression)
If mylink.myexpression contains the expression 5+5, then the following two functions are equivalent, and return the value 0:
ds.Not(5+5)
ds.Not(mylink.myexpression)
SetBit
Returns an integer with specific bits set to a specific state, where origfield is the input value to perform the action on, bitlist is a string containing a list of comma-separated bit numbers to set the state of,
and bitstate is either 1 or 0, indicating which state to set those bits.
Syntax
ds.SetBit(origfield (uint64), bitlist (string), bitstate (uint8))
returns: the number with the bits set to the specified state in uint64 format.
Examples
If mylink.origfield contains the number 352, mylink.bitlist contains the list "2,4,8", and mylink.bitstate contains the value 1, then the following two functions are equivalent, and return
the value 494:
ds.SetBit(356,"2,4,8",1)
ds.SetBit(mylink.origfield, mylink.bitlist, mylink.bitstate)
True
Returns the true value of 1.
Syntax
ds.True()
returns: the integer 1.
Examples
The following code returns 1:
ds.True()
False
Returns the false value of 0.
Syntax
ds.False()
returns: the integer 0.
Examples
The following code returns 0:
ds.False()
Mathmatical functions
The mathematical functions perform mathematical operations.
Abs
Returns the absolute value of any numeric expression. The absolute value of an expression is its unsigned magnitude.
Syntax
ds.Abs(numeric_expression (int32))
returns: the absolute value of the numeric expression in dfloat format.
Examples
If mylink.number1 contains the number 12 and mylink.number2 contains the number 34, then the following two functions are equivalent, and return the number 22:
ds.Abs(12-34)
ds.Abs(mylink.mynumber1-mylink.mynumber2)
If mylink.number1 contains the number 34 and mylink.number2 contains the number 12, then the following two functions are equivalent, and return the number 22:
ds.Abs(34-12)
ds.Abs(mylink.mynumber1-mylink.mynumber2)
Acos
Calculates the trigonometric arc-cosine of an expression. The expression must be a numeric value. The result is expressed in radians.
Syntax
ds.Acos(numeric_expression (dfloat))
returns: the resulting radian in dfloat format.
Examples
If mylink.number contains the number 0.707106781, then the following two functions are equivalent, and return the value 0.7854:
ds.Acos(0.707106781)
ds.Acos(mylink.mynumber)
ACOS
Returns the trigonometric arc-cosine of expression. The input must be a numeric value. The result is expressed in degrees.
Syntax
ds.ACOS(expression (float64))
returns: the angle in degrees, of float64 format.
Examples
The following code returns the value 45:
ds.ACOS(0.707106781)
Asin
Calculates the trigonometric arc-sine of an expression. The expression must be a numeric value. The result is expressed in radians.
Syntax
ds.Asin(numeric_expression (dfloat))
returns: the radian result in dfloat format.
Examples
If mylink.number contains the number 0.707106781, then the following two functions are equivalent, and return the value 0.7854:
ds.Asin(0.707106781)
ds.Asin(mylink.mynumber)
ASIN
Returns the trigonometric sine of an expression. Input is the angle that is expressed in degrees.
Syntax
ds.ASIN(expression(float64))
returns: the angle in degrees, of float64 format.
Examples
The following code returns the value 45:
ds.ASIN(0.707106781)
Atan
Calculates the trigonometric arc-tangent of an expression. The expression must be a numeric value. The result is expressed in radians.
Syntax
ds.Atan(numeric_expression (dfloat))
returns: the radian result in dfloat format.
Examples
If mylink.number contains the number 135, then the following two functions are equivalent, and return the value 1.5634, which is the angle that has an arc tangent of 135:
ds.Atan(135)
ds.Atan(mylink.mynumber)
ATAN
Returns the trigonometric arc-tangent of the expression. The input must be a numeric value. The result is expressed in degrees.
Syntax
ds.ATAN(expression(float64))
returns: the angle in degrees, of dfloat format.
Examples
The following code returns the value 45:
ds.ATAN(1)
Atan2
Calculates the trigonometric arc-tangent of the two inputs by using the signs of the two inputs to determine the quadrant of the result. The inputs must be numeric values. The result is expressed in radians.
Syntax
ds.Atan2(numeric_expression (dfloat, dfloat))
returns: the radian result in dfloat format.
Examples
If mylink.number1 contains the number 10.0 and mylink.number2 contains the number -10.0, then the following two functions are equivalent, and return the value 2.3562:
ds.Atan2(10.0, -10.0)
ds.Atan2(mylink.mynumber1, mylink.mynumber2)
Ceil
Calculates the smallest integer value greater than or equal to the given decimal value.
Syntax
ds.Ceil(number (dfloat))
returns: the smallest integer value in int32.
Examples
If mylink.number contains the number 2355.66, then the following two functions are equivalent, and return the value 2356:
ds.Ceil(2355.66)
ds.Ceil(mylink.mynumber)
Cos
Calculates the trigonometric cosine of an expression. The expression must be a numeric value. The expression must produce a numeric value that is the angle in radians.
Syntax
ds.Cos(radians (dfloat))
returns: the angle in radians, of dfloat format.
Examples
If mylink.number contains the number 0.785398, then the following two functions are equivalent, and return the value 0.7071:
ds.Cos(0.785398)
ds.Cos(mylink.mynumber)
COS
Returns the trigonometric cosine of an angle. The expression is an angle as a value in degrees.
Syntax
ds.COS(expression(float64))
returns: the angle in degrees, of float64 format.
Examples
The following code returns the value 0.7071:
ds.COS(45)
Cosh
Calculates the hyperbolic cosine of an expression. The expression must be a numeric value.
Syntax
ds.Cosh(number (dfloat))
returns: the resulting cosine in dfloat format.
Examples
If mylink.number contains the number 2, then the following two functions are equivalent, and return the value 3.7622:
ds.Cosh(2)
ds.Cosh(mylink.mynumber)
Div
Calculates the hyperbolic cosine of an expression. The expression must be a numeric value.
Syntax
ds.Div(dividend (dfloat), divisor (dfloat))
returns: the resulting cosine in dfloat format.
Examples
If mylink.dividend contains the number 100, and mylink.divisor contains the number 25, then the following two functions are equivalent, and return the value 4:
ds.Div(100,25)
ds.Div(mylink.dividend, mylink.divisor)
Exp
Calculates the result of base e raised to the power designated by the value of the expression. The value of e is approximately 2.71828. The expression must evaluate to a numeric value.
Syntax
ds.Exp(number (dfloat))
returns: the resulting e raised to the specified power in dfloat format.
Examples
If mylink.number contains the number 5, then the following two functions are equivalent, and return the value 54.5982:
ds.Exp(5-1)
ds.Exp(mylink.number-1)
Fabs
Calculates the absolute value of the given float value.
Syntax
ds.Fabs(number (dfloat))
returns: the absolute value of the float number.
Examples
If mylink.number contains the number -26.53, then the following two functions are equivalent, and return the value 26.53:
ds.Fabs(-26.53)
ds.Fabs(mylink.number)
Floor
Calculates the largest integer value less than or equal to the given decimal value.
Syntax
ds.Floor(number (dfloat))
returns: the largest integer less than or equal to the decimal value in the int32 format.
Examples
If mylink.number contains the number 203.25, then the following two functions are equivalent, and return the value 203:
ds.Floor(203.25)
ds.Floor(mylink.number)
Ldexp
Returns a dfloat value from multiplying the mantissa by 2 raised to the power of the exponent.
Syntax
ds.Ldexp(mantissa (dfloat), exponent (int32))
returns: the resulting mantissa in dfloat format.
Examples
If mylink.mantissa contains the number 2, and mylink.exponent contains the number 3, then the following two functions are equivalent, and return the value 16:
ds.Ldexp(2,3)
ds.Ldexp(mylink.mantissa, mylink.exponent)
Llabs
Calculates the absolute value of the given integer value.
Syntax
ds.Llabs(number (integer))
returns: the absolute value of the given integer as an unsigned integer.
Examples
If mylink.number contains the number -26, then the following two functions are equivalent, and return the value 26.
ds.Llabs(-26)
ds.Llabs(mylink.number)
Ln
Calculates the natural logarithm of an expression in base e. The value of e is approximately 2.71828. The expression must evaluate to a numeric value greater than 0.
Syntax
ds.Ln(number (dfloat))
returns: the resulting logarithm of the e based expression.
Examples
If mylink.number contains the number 6, then the following two functions are equivalent, and return the value 1.7918:
ds.Ln(6)
ds.Ln(mylink.number)
Log10
Returns the logarithm in base 10 of the given value.
Syntax
ds.Log10(number (dfloat))
returns: the resulting base 10 logarithm in dfloat format.
Examples
If mylink.number contains the number 6, then the following two functions are equivalent, and return the value 1.7782:
ds.Log10(6)
ds.Log10(mylink.number)
Max
Returns the greater of the two argument values.
Syntax
ds.Max(number1 (int32), number2(int32))
returns: the greater of the two integers in int32 format.
Examples
If mylink.number1 contains the number 6, and mylink.number1 contains the number 101, then the following two functions are equivalent, and return the value 101:
ds.Max(6,101)
ds.Max(mylink.number1, mylink.number2)
Min
Returns the minimum of the two argument values.
Syntax
ds.Min(number1 (int32), number2(int32))
returns: the lesser of the two integers.
Examples
If mylink.number1 contains the number 6, and mylink.number1 contains the number 101, then the following two functions are equivalent, and return the value 6:
ds.Min(6,101)
ds.Min(mylink.number1, mylink.number2)
Mod
Calculates the modulo (the remainder) of two expressions (dividend, divisor).
Syntax
ds.Mod(dividend (int32), divisor (int32))
returns: the resulting modulo in int32 format.
Examples
If mylink.dividend contains the number 115, and mylink.divisor contains the number 25, then the following two functions are equivalent, and return the value 15:
ds.Mod(115,25)
ds.Mod(mylink.dividend, mylink.divisor)
Neg
Negates a number.
Syntax
ds.Neg(number (dfloat))
returns: the resulting negated number in dfloat format.
Examples
If mylink.number contains the number 123, then the following two functions are equivalent, and return the value -123:
ds.Neg(123)
ds.Neg(mylink.number)
Pwr
Calculates the value of an expression when raised to a specified power (expression, power).
Syntax
ds.Pwr(expression (dfloat), power (dfloat))
returns: the resulting number that is raised to the specified power in dfloat format.
Examples
If mylink.expression contains the number 2, and mylink.power contains the number 3, then the following two functions are equivalent, and return the value 8:
ds.Pwr(2,3)
ds.Pwr(mylink.expression, mylink.power)
Rand
Returns a pseudorandom integer between 0 and 232-1.
Syntax
ds.Rand()
returns: the resulting random integer in uint32 format.
Examples
Use this function to generate a pseudorandom number:
ds.Rand()
Random
Returns a pseudorandom integer between 0 and 232-1.
Syntax
ds.Random()
returns: the resulting random integer in uint32 format.
Examples
Use this function to generate a random number:
ds.Random()
Rnd
Generates any positive or negative random integer or 0. Takes the total number of integers as input, including 0, from which the random number can be selected. That is, if n is the value of numeric_expression, the random number is generated from the numbers 0 through (n - 1).
Syntax
ds.Rnd(numeric_expression (int))
returns: a random number from 0 to (numeric_expression - 1) in int format.
Examples
The following code returns a random number from 0-19.
ds.Rnd(20)
Sin
Calculates the trigonometric sine of an expression. The expression must be a numeric value. The expression must produce a numeric value that is the angle in radians.
Syntax
ds.Sin(radians (dfloat))
returns: the resulting angle in dfloat format.
Examples
If mylink.number contains the number 0.785398, then the following two functions are equivalent, and return the value 0.7071:
ds.Sin(0.785398)
ds.Sin(mylink.mynumber)
SIN
Returns the trigonometric sine of an expression. Input is the angle that is expressed in degrees.
Syntax
ds.SIN(expression(float64))
returns: the angle in degrees, of dfloat format.
Examples
The following code returns the value 0.7071:
ds.SIN(45)
Sinh
Calculates the hyperbolic sine of an expression. The expression must be a numeric value.
Syntax
ds.Sinh(number (dfloat))
returns: the resulting sine in dfloat format.
Examples
If mylink.number contains the number 2, then the following two functions are equivalent, and return the value 3.6269:
ds.Sinh(2)
ds.Sinh(mylink.mynumber)
Sqrt
Calculates the square root of a number.
Syntax
ds.Sqrt(number (dfloat))
returns: the resulting square root of the number in dfloat format.
Examples
If mylink.number contains the number 450, then the following two functions are equivalent, and return the value 21.2132:
ds.Sqrt(450)
ds.Sqrt(mylink.mynumber)
Tan
Calculates the trigonometric tangent of an expression. The expression must produce a numeric value that is the angle in radians.
Syntax
ds.Tan(radians (dfloat))
returns: the resulting tangent in dfloat format.
Examples
If mylink.number contains the number 0.7853981, then the following two functions are equivalent, and return the value 1:
ds.Tan(0.7853981)
ds.Tan(mylink.mynumber)
TAN
Returns the TAN function to return the trigonometric tangent of the input. The input represents an angle that is expressed in degrees.
Syntax
ds.TAN(expression(float64))
returns: the angle in degrees, of float64 format.
Examples
The following code returns the value 1:
ds.TAN(45)
ATAN
Returns the trigonometric arc-tangent of the expression. The input must be a numeric value. The result is expressed in degrees.
Syntax
ds.ATAN(expression(float64))
returns: the angle in degrees, of float64 format.
Examples
The following code returns the value 45:
ds.ATAN(1)
Tanh
Calculates the hyperbolic tangent of an expression. The expression must be a numeric value.
Syntax
ds.Tanh(number (dfloat))
returns: the resulting tangent in dfloat format.
Examples
If mylink.number contains the number 2, then the following two functions are equivalent, and return the value 0.964028:
ds.Tanh(2)
ds.Tanh(mylink.mynumber)
Number functions
Use the number functions to extract the mantissa from a decimal or floating point number. The Number category in the expression editor also contains the type casting functions, which you can use to cast numbers as double, float, or integer data types.
The transformer functions AsDouble(), AsFloat(), and AsInteger() behave differently than other transformer data conversions functions when they are used in derivations where the result is a string. The
behavior is because the transformer compiler does not convert the function results for these functions to a string.
AsDouble
Treat the given number as a double.
Syntax
ds.AsDouble(number (int, float and so on))
returns: the number in double format.
Examples
In the following expression, the input mynumber contains an integer, but the function outputs a double. If mylink.mynumber contains the value 56, then the following two functions are equivalent, and return the value
12.963:
ds.AsDouble(56/4.32)
ds.AsDouble(mylink.mynumber/4.32)
AsFloat
Treat the given number as a float.
Syntax
ds.AsFloat(number (int, double and so on))
returns: the number in float format.
Examples
In the following expression, the input mynumber contains an integer, but the function outputs a float. If mylink.mynumber contains the value 56, then the following two functions are equivalent, and return the value
12.963:
ds.AsFloat(56/4.32)
ds.AsFloat(mylink.mynumber/4.32)
AsInteger
Treat the given number as an integer. But there is a difference in behavior when a decimal is assigned to an integer versus a float or a double being assigned to an integer. If the conversion is from float or a double to an integer, it is
a simple assignment to an integer. In the case of decimal AsInteger(), function is started and rounds the output toward nearest value.
Syntax
ds.AsInteger(number (float, double and so on))
returns: the number in integer format.
Examples
In the following expression, the input value 12.962963 has a type Double. Though the value is of type Double, the function outputs an integer. Hence it is a simple assignment to an integer function and returns the value 12:
ds.AsInteger(12.962963)
In the following expression, the calculations like (56/4.32) are treated as a type Decimal and AsInteger() function call started rounds toward the nearest value and returns the value 13:
ds.AsInteger(56/4.32)
FIX
Converts a numeric value to a floating-point number with a specified precision number. If number evaluates to the null value, null is returned. The precision value is a numerical value that corresponds to the number of digits of precision in the floating-point number. The default precision is 4. The mode value is a flag that specifies how excess digits are handled. If mode is either 0 or not specified, excess digits are rounded off. If mode is anything other than 0, excess digits are truncated.
Syntax
ds.FIX(numeric_expression (string), precision (int8), mode (int32))
returns: the converted number of format dfloat.
Examples
The following code returns the number 37.7363.
ds.FIX("37.73629273")
MantissaFromDecimal
Returns the mantissa from the given decimal.
Syntax
ds.MantissaFromDecimal(number (decimal))
returns: the mantissa in dfloat format.
Examples
If mylink.number contains the number 243.7675, then the following two functions are equivalent, and return the value 7675:
ds.MantissaFromDecimal(243.7675)
ds.MantissaFromDecimal(mylink.mynumber)
MantissaFromDFloat
Returns the mantissa from the given dfloat.
Syntax
ds.MantissaFromDFloat(number (dfloat))
returns: the mantissa in dfloat format.
Examples
If mylink.number contains the number 1.234412000000000010E+4, then the following function returns the value 1:
ds.MantissaFromDFloat(mylink.mynumber)
Real
Converts a number in a string to type floating-point without loss of accuracy.
Syntax
ds.Real(numeric_expression (string))
returns: the converted number of format dfloat.
Examples
The following code returns the number 1.23.
ds.Real("1.23")
Raw functions
Use the Raw function to obtain the length of the data in a column that contains raw data.
RawLength
Returns the length of a raw string.
Syntax
ds.RawLength(input string (string))
returns: the length of the raw string in int32 format.
Examples
If mylink.rawdata contains the raw data from a bitmap, then the following function returns the size of the bitmap in bytes:
ds.RawLength(mylink.rawdata)
String functions
Use these functions for string-related functions in an expression.
AlNum
Checks whether the given string contains only alphanumeric characters.
Syntax
ds.AlNum(string (string))
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Example
If mylink.mystring1 contains the string "OED_75_9*E", then the following function would return the value 0 (false).
ds.AlNum(mylink.mystring1)
If mylink.mystring2 contains the string "12redroses", then the following function would return the value 1 (true).
ds.AlNum(mylink.mystring2)
Alpha
Checks whether the given string contains only alphabetic characters.
Syntax
ds.Alpha(string (string))
returns: a result of int8 type, 1 if the input is valid for the given type, and 0 otherwise.
Examples
If mylink.mystring1 contains the string "12redroses", then the following function would return the value 0 (false).
ds.Alpha(mylink.mystring1)
If mylink.mystring2 contains the string "twelveredroses", then the following function would return the value 1 (true).
ds.Alpha(mylink.mystring2)
Cats
Concatenates two strings.
Syntax
ds.Cats(str1 (string), str2 (string))
returns: the resulting concatenated string.
Examples
The following code returns "ABC123".
ds.Cats("ABC", "123")
Change
Replaces the given substring in an expression with a replacement string.
If the substring argument is an empty string, the value of the expression argument is returned.
If the value of the replacement argument is an empty string, all occurrences of the substring starting from the position that is indicated by the value of the begin argument are removed. If the value of the occurrence argument is less than or equal to 0, all occurrences that start from the position that is indicated by the value of the begin argument are replaced. Otherwise, the number of occurrences that are replaced is indicated by the value of the occurrence argument, starting from the position that is indicated by the value of the begin argument. If the value of the begin argument is less than or equal to 1, the replacement starts from the first occurrence. Otherwise, the replacement starts from the position that is indicated by the value of thebegin argument.
Syntax
ds.Change(expression (string), substring (string), replacement (string), [occurrence (int32), [begin (int32)]])
returns: the new string with all substrings replaced.
Examples
If mylink.mystring contains the expression "aaabbbcccbbb", then the following function returns the string "aaaZZZcccZZZ".
ds.Change(mylink.mystring,"bbb","ZZZ")
If mylink.mystring contains the expression "ABC" and the substring is empty, then the following function returns the string "ABC".
ds.Change(mylink.mystring,"","ZZZ")
If mylink.mystring contains the expression "aaabbbcccbbb" and the replacement is empty, then the following function returns the string "aaaccc".
ds.Change(mylink.mystring, "bbb", "")
CompactWhiteSpace
Returns the string after reducing all consecutive white space to a single space.
Syntax
ds.CompactWhiteSpace(string (string))
returns: the resulting string with reduced white spaces.
Examples
If mylink.mystring contains the string "too many spaces", then the following function returns the string "too many spaces":
ds.CompactWhiteSpace(mylink.mystring)
Compare
Compares two strings for sorting. The comparison can be left-aligned (the default) or right-aligned. A right-aligned comparison compares numeric substrings within the specified strings as numbers.
The numeric strings must occur at the same character position in each string. For example, a right-aligned comparison of the strings AB100 and AB99 indicates that AB100 is greater than AB99 since 100 is greater than 99. A left-aligned comparison of the strings AC99 and AB100 indicates that AC99 is greater since C is greater than B.
Syntax
ds.Compare(string1 (string), string2 (string), [justification ("L" or "R")])
returns: a result of int8 type, -1 if string1 is less than string2, 0 if both strings are the same, 1 if string1 is greater than string2.
Examples
If mylink.mystring1 contains the string "AB99" and mylink.mystring2 contains the string "AB100", then the following function returns the result 1.
ds.Compare(mylink.mystring1, mylink.mystring2, "L")
If mylink.mystring1 contains the string "AB99" and mylink.mystring2 contains the string "AB100", then the following function returns the result -1.
ds.Compare(mylink.mystring1, mylink.mystring2, "R")
CompareNoCase
Compares two strings for sorting, ignoring their cases.
Syntax
ds.CompareNoCase(string1 (string), string2 (string))
returns: a result of int8 type, -1 if string1 is less than string2, 0 if both strings are the same, and 1 if string1 is greater than string2.
Examples
If mylink.mystring1 contains the string "Chocolate Cake" and mylink.mystring2 contains the string "chocolate cake", then the following function returns the result 0.
ds.CompareNoCase(mylink.mystring1, mylink.mystring2)
CompareNum
Compares the first n characters of two strings, n being specified by the user.
Syntax
ds.CompareNum(string1 (string), string2 (string), length (int16))
returns: a result of int8 type, -1 if string1 is less than string2, 0 if both strings are the same, 1 if string1 is greater than string2.
Examples
If mylink.mystring1 contains the string "Chocolate" and mylink.mystring2 contains the string "Choccy Treat", then the following function returns the result 0.
ds.CompareNum(mylink.mystring1, mylink.mystring2,4)
CompareNumNoCase
Compares the first n characters of two strings, ignoring their case, n being specified by the user.
Syntax
ds.CompareNumNoCase(string1 (string), string2 (string), length (int16))
returns: a result of int8 type, -1 if string1 is less than string2, 0 if both strings are the same, 1 if string1 is greater than string2.
Examples
If mylink.myraw contains the string "chocolate" and mylink.mystring2 contains the string "Choccy Treat", then the following function returns the result 0.
ds.CompareNumNoCase(mylink.mystring1, mylink.mystring2,4)
Conversion
Converts a string to a specified internal or external storage format. The string expression evaluates the string to be converted.
The following table shows the values that you can specify for the conversion. The conv_code specifies types of storage formats that are involved in the conversion, and conv_mode specifies which format is used for
input or output. If you specify "I" for conv_mode, the ICONV() function is used for the conversion. If you specify "O" for conv_mode, the OCONV() function is used for
the conversion.
Table for conversion values
conv_code |
conv_mode |
Description |
|---|---|---|
| MX | I | Converts the input string from hexadecimal to decimal. |
| MB | I | Converts the input string from binary to decimal. |
| MX0C | I | Converts the input string from hexadecimal to an ASCII character string. |
| MB0C | I | Converts the input string from binary to ASCII character string. |
| MX | O | Converts the input string from decimal to hexadecimal. |
| MB | O | Converts the input string from decimal to binary. |
| MX0C | O | Converts the input string from ASCII character string to hexadecimal. |
| MB0C | O | Converts the input string from ASCII character string to binary. |
Syntax
ds.Conversion(string (string), conv_code (string), conv_mode (string))
returns: the converted string.
Examples
If mylink.mystring contains the string "1111", then the following function returns the value 15.
ds.Conversion(mylink.mystring,"MB", "I")
If mylink.mystring contains the string "CDE", then the following function returns the value 434445.
ds.Conversion(mylink.mystring,"MX0C", "O")
Convert
Converts the characters in the string that is designated in the given expression. Converts the characters that are specified in one list to the characters specified in another list.
Syntax
ds.Convert(fromlist (string), tolist (string), expression (string))
returns: the string with the converted designated characters.
Examples
If mylink.mystring1 contains the string "NOW IS THE TIME", then the following function returns the string "NOW YS XHE XYME".
ds.Convert("TI","XY", mylink.mystring1)
Count
Counts the number of times a substring occurs in a string.
Syntax
ds.Count(string (string), substring (string))
returns: the number of substring occurrences in int32 format.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars", then the following function returns 3.
ds.Count(mylink.mystring1, "choc")
Dcount
Counts the number of delimited fields in a string.
Syntax
ds.Dcount(string (string), delimiter (string))
returns: the number of delimited fields in int32 format.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars", then the following function returns 3.
ds.Dcount(mylink.mystring1,",")
DownCase
Changes all uppercase letters in a string to lowercase letters.
Syntax
ds.DownCase(string (string))
returns: the resulting string in all lowercase.
Examples
If mylink.mystring1 contains the string "CaMel cAsE", then the following function returns the string "camel case".
ds.DownCase(mylink.mystring1)
DQuote
Encloses a string in double quotation marks.
Syntax
ds.DQuote(string (string))
returns: the resulting string enclosed in double quotation.
Examples
If mylink.mystring1 contains the string needs quotations, then the following function returns the string "needs quotations".
ds.DQuote(mylink.mystring1)
Ereplace
Replaces a substring in an expression with replacement string.
If the substring argument is an empty string, the value of the replacement argument is prefixed with the value of the expression argument. If the replacement argument is an empty string, all occurrences of the substring that start from the position that is indicated by the value of the begin argument are removed. If the value of the occurrence argument is less than or equal to 0, all occurrences that start from the value of the begin argument are replaced. Otherwise, the number of occurrences that are replaced is indicated by the value of the occurrence argument, starting from the position indicate by the value of the begin argument. If value of the begin argument is less than or equal to 1, the replacement starts from the first occurrence. Otherwise, the replacement starts from the position that is indicated by the value of the begin argument.
Syntax
ds.Ereplace(expression (string), substring (string), replacement (string), [occurrence (int32), [begin (int32)]])
returns: the resulting string with all occurrences of the substring replaced.
Examples
If mylink.mystring contains the expression "ABC" and the substring is empty, the following function returns the value "ZZZABC".
ds.Ereplace(mylink.mystring,"","ZZZ")
If mylink.mystring contains the expression "aaabbbcccbbb" and the replacement is empty, the following function returns the value "aaaccc".
ds.Ereplace(mylink.mystring, "bbb", "")
Exchange
Replaces a character in a string.
Syntax
ds.Exchange(str (string), findStr (string), replaceStr (string))
returns: the resulting string with replaced characters.
Examples
The following code returns: ".B.BC".
ds.Exchange("ABABC", "41", "2E")
EXTRACT
Access the data contents of a specified field, value, or subvalue from a dynamic array. The function similarly to REMOVE.
The input dynamic array must have only CHAR(254), CHAR(253), CHAR(252) as delimiters, and their hierarchy as afore written. Respectively, they can be retrieved by AM or FM, VM, SM, or SVM functions. FM is delimiter to the strings' fields, VM is delimiter to the strings' values, and SM is delimiter to the strings' subvalues.
To learn more about EXTRACT, please see EXTRACT function.
Syntax
ds.EXTRACT(str (string), field (int64), [value (int64), subvalue (int64)])
returns: the resulting extracted string of format string.
Examples
The following codes both return: "9ü3ü5". The dynamic array contains 3 fields that are separated by FM/AM, 2 values in the first field, 1 subvalue in the first value, and so on.
ds.EXTRACT("1" + ds.FM() + "4" + ds.VM() + "9" + ds.SM() + "3" + ds.SM() + "5" + ds.FM() + "1" + ds.VM() + "0" + ds.SM() + "7" + ds.SM() + "3", 2, 2)
ds.EXTRACT("1" + ds.AM() + "4" + ds.VM() + "9" + ds.SM() + "3" + ds.SM() + "5" + ds.AM() + "1" + ds.VM() + "0" + ds.SM() + "7" + ds.SM() + "3", 2, 2)
The following code returns an empty string, as there are only 3 fields and not 10 or more.
ds.EXTRACT("1" + ds.FM() + "4" + ds.VM() + "9" + ds.SM() + "3" + ds.SM() + "5" + ds.FM() + "1" + ds.VM() + "0" + ds.SM() + "7" + ds.SM() + "3", 10, 0, 0)
Field
Returns one or more substrings that are located between specified delimiters in a string. The argument occurrence specifies which occurrence of the delimiter is to be used as a terminator. The argument number optionally specifies how many substrings to return.
Syntax
ds.Field(string (string), delimiter (string), occurrence (int32), [number (int32)])
returns: the corresponding string between the delimiters.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars, chocolate dippers", then the following function returns the string " chocolate ice cream".
ds.Field(mylink.mystring1,",",2)
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars, chocolate dippers", then the following function returns the string " chocolate ice cream, chocolate bars".
ds.Field(mylink.mystring1,",",2,2)
FieldStore
Modifies character strings by inserting, deleting, or replacing fields separated by a specified delimiters string. The delimiters string denotes the string to be modified and can be any single ASCII character. The function also takes parameters
start (the position of the input string where the modification starts), and number which is the number of times a new string is inserted in the input string.
Syntax
ds.FieldStore(str (string), delimiter (string), start (int8), number (int8), new_fields (string))
returns: the modified string of format string.
Examples
The following code returns the string A#B#C#D#5:
ds.FieldStore("1#2#3#4#5", "#", 1, 4, "A#B#C#D")
Fmt
Uses the FMT function or a format expression to format data for output. Any BASIC expression can be formatted for output by following it with a format expression. For details on the syntax of the Fmt function, see FMT function.
Syntax
ds.Fmt(string (string), format (string))
returns: the resulting formatted data of format string.
Examples
The following code returns the string "23-69-86":
ds.Fmt("236986","R##-##-##")
The following code returns the number "*****$555,666,898.00":
ds.Fmt("555666898","20*R2$,")
FmtDP
Converts a multibyte character set of type string to the target format. If globalization (globalization) is not enabled, the FmtDP function works like an equivalent Fmt function. For details on the syntax of the FmtDP function, see FmtDP function.
Syntax
ds.FmtDP(string (string), format (string), [mapname (string)])
returns: the converted string of format string.
Examples
The following code returns the number 56789:
ds.FmtDP("123456789","R#5")
Fold
Folds strings to create substrings. string is the string to be folded. length is the length of the substrings in characters.
ds.Fold(str (string), length (int8))
returns: the resulting folded string.
The following code returns "THISþIS AþTESTþFOLDEþD STRþING".
ds.Fold("THIS IS A TEST FOLDED STRING", 5)
Folddp
In globalization (globalization) mode, folds strings to create substrings that use character display positions.
Syntax
ds.Folddp(str (string), length (int), opmap (string))
returns: the resulting folded string.
Examples
The following code returns: "这里需要þUNICOþDE STþRING".
ds.Folddp("这里需要 UNICODE STRING", 5, "0")
Index
Finds the starting character position of a substring. The argument occurrence specifies which occurrence of the substring is to be located.
Syntax
ds.Index(string (string), substring (string), occurrence (int32))
returns: the result in int32 format of the number of occurrences.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars, chocolate dippers", then the following function returns the value 18.
ds.Index(mylink.mystring1,"chocolate",2)
Left
Returns the leftmost n characters of a string.
Syntax
ds.Left(string (string) number (int32))
returns: the leftmost n characters of the string.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars, chocolate dippers", then the following function returns the string "chocolate".
ds.Left(mylink.mystring1,9)
Len
Returns the length of a string in characters.
Syntax
ds.Len(string (string))
returns: the length of the string in int32 format.
Examples
If mylink.mystring1 contains the string "chocolate", then the following function returns the value 9.
ds.Len(mylink.mystring1)
Lendp
In globalization (globalization) mode, returns the length of a string with its total display positions.
Syntax
ds.Lendp(str (string), opmap (string))
returns: the length of the string of format int64.
Examples
The following code returns: 19.
ds.Lendp("这里需要 UNICODE STRING", "0")
Match
Synonymous to MATCHES. Used to compare a string expression with a pattern. To learn more about Match syntax, please see Match Operator.
Syntax
ds.Match(str (string), pattern (string))
returns: the result of whether the pattern matches the input string, of format Boolean.
Examples
The following code returns false:
ds.Match("XYZ123AB", "3X3N")
The following code returns true:
ds.Match("XYZ123AB", "3X3N...")
MatchField
Searches a string and returns the part of it that matches the input pattern parameter. To learn more about MatchField syntax, please see MATCH Operator.
Syntax
ds.MatchField(str (string), pattern (string), field (int))
returns: the result of format string.
Examples
The following code returns the string "XYZ":
ds.MatchField("XYZ123AB", "3X3N...", 1)
Num
Returns 1 if the string can be converted to a number, or returns 0 otherwise.
Syntax
ds.Num(string (string))
returns: 1 if the string can be converted to a number, or returns 0 otherwise, in int32 format.
Examples
If mylink.mystring1 contains the string "22", then the following function returns the value 1.
ds.Num(mylink.mystring1)
If mylink.mystring1 contains the string "twenty two", then the following function returns the value 0.
ds.Num(mylink.mystring1)
PadString
Returns the string padded with the specified number of pad characters.
Syntax
ds.PadString(string (string) padstring (string) padlength (int32))
returns: the resulting padded string.
Examples
If mylink.mystring1 contains the string "AB175", then the following function returns the string "AB17500000".
ds.PadString(mylink.mystring1,"0",5)
REMOVE
Extracts and returns dynamic array elements that are separated by system delimiters, and to indicate which system delimiter was found. It accepts one CHAR as a delimiter and returns the corresponding number as to which delimiter is found.
| Number | Delimiter Type |
|---|---|
| 0 | End of string |
| 1 | Item mark ASCII CHAR(255) |
| 2 | Field mark ASCII CHAR(254) |
| 3 | Value mark ASCII CHAR(253) |
| 4 | Subvalue mark ASCII CHAR(252) |
| 5 | Text mark ASCII CHAR(251) |
| 6 | ASCII CHAR(250) (Not available in PIOPEN flavor) |
| 7 | ASCII CHAR(249) (Not available in PIOPEN flavor) |
| 8 | ASCII CHAR(248) (Not available in PIOPEN flavor) |
For more information on the REMOVE function, see REMOVE function.
Syntax
ds.REMOVE(str (string))
returns: the resulting string with delimiters removed of format string list, and the number that corresponds to the delimiter found.
Examples
The following code returns ["3","12"].
ds.REMOVE("12" + ds.VM() + "12" + ds.VM())
Right
Returns the rightmost n characters of a string.
Syntax
ds.Right(string (string) number (int32))
returns: the rightmost n characters of a string.
Examples
If mylink.mystring1 contains the string "chocolate drops, chocolate ice cream, chocolate bars, chocolate dippers", then the following function returns the string "dippers".
ds.Right(mylink.mystring1,7)
Soundex
Returns a code that identifies a set of words that are (roughly) phonetically alike based on the standard, open algorithm for SOUNDEX evaluation.
Syntax
ds.Soundex(string (string))
returns: the code that identifies a set of phonetically alike words.
Examples
If mylink.mystring1 contains the string "Griffin", then the following function returns the code "G615".
ds.Soundex(mylink.mystring1)
If mylink.mystring1 contains the string "Griphin" then the following function also returns the code "G615".
ds.Soundex(mylink.mystring1)
Space
Returns a string of n space characters.
Syntax
ds.Space(length (int32))
returns: a string of white spaces with specified length.
Examples
If mylink.mylength contains the number 100, then the following function returns a string that contains 100 space characters.
ds.Space(mylink.mylength)
SQuote
Encloses a string in single quotation marks.
Syntax
ds.SQuote(string (string))
returns: the string enclosed in single quotation marks.
Examples
If mylink.mystring1 contains the string needs quotations, then the following function returns the string 'needs quotations'.
ds.SQuote(mylink.mystring1)
Str
Repeats a string the specified number of times.
Syntax
ds.Str(string (string), repeats (int32))
returns: the resulting string repeated n times.
Examples
If mylink.mystring1 contains the string needs "choc", then the following function returns the string "chocchocchocchocchoc".
ds.Str(mylink.mystring1,5)
StripWhiteSpace
Returns the string after you remove all white space characters from it.
Syntax
ds.StripWhiteSpace(string (string))
returns: the string without white spaces.
Examples
If mylink.mystring contains the string "too many spaces", then the following function returns the string "toomanyspaces":
ds.StripWhiteSpace(mylink.mystring)
Substring
Returns the specified substring.
When n is specified, the function gets the last n characters of a string.
When start and length is specified, the function gets the characters with length equal to length starting from the start position of a string.
When a delimiter is specified, the function gets one or more substrings that are located between specified delimiters in a string. occu is the number of delimiters and num is the length of the substring between delimiters in the resulting substring.
Syntax
ds.Substring(string (string), n (int8))
ds.Substring(string (string), start (int8), length (int8))
ds.Substring(string (string), delimiter (string), occu (int8), num (int8))
returns: the resulting substring array of format string.
Examples
The following code returns "ab.cd".
ds.Substring("ab.cd", ".", 1, 2)
Substrings
Creates a dynamic array, of which all elements are substrings of the corresponding elements of the input dynamic array.
Syntax
ds.Substrings(str (string), start (int8), length (int8))
returns: the resulting dynamic array with substrings corresponding to the input array, of string format.
Examples
The following code returns "NESýITHþ23üý50ü".
ds.Substrings("JONESýSMITHþ1.23ü20ý2.50ü10", 3, 20)
Trim
Removes all leading and trailing spaces and tabs. The function also reduces the internal occurrences of spaces or tabs to one.
The argument stripchar optionally specifies a character other than a space or a tab. The argument options specifies the type of trim operation to be performed and contains one or more of the following values:
-
A: Remove all occurrences of stripchar.
-
B Remove both leading and trailing occurrences of stripchar.
-
D Remove leading, trailing, and redundant white-space characters.
-
E Remove trailing white-space characters.
-
F Remove leading white-space characters.
-
L Remove all leading occurrences of stripchar.
-
R Remove leading, trailing, and redundant occurrences of stripchar.
-
T Remove all trailing occurrences of stripchar.
Syntax
ds.Trim(string (string), [stripchar (string)], [options (string)])
returns: the trimmed string.
Examples
If mylink.mystring contains the string " String with white space ", then the following function returns the string "String with white space":
ds.Trim(mylink.mystring)
If mylink.mystring contains the string "..Remove..redundant..dots....", then the following function returns the string "Remove.redundant.dots":
ds.Trim(mylink.mystring,".")
If mylink.mystring contains the string "Remove..all..dots....", then the following function returns the string "Removealldots":
ds.Trim(mylink.mystring,".","A")
If mylink.mystring contains the string "Remove..trailing..dots....", then the following function returns the string "Remove..trailing..dots":
ds.Trim(mylink.mystring,".","T")
TrimB
Removes all trailing spaces and tabs from a string.
Syntax
ds.TrimB(string (string))
returns: the trimmed string.
Examples
If mylink.mystring contains the string "too many trailing spaces ", then the following function returns the string "too many trailing spaces":
ds.TrimB(mylink.mystring)
TrimF
Removes all leading spaces and tabs from a string.
Syntax
ds.TrimF(string (string))
returns: the trimmed string.
Examples
If mylink.mystring contains the string " too many leading spaces", then the following function returns the string "too many leading spaces":
ds.TrimF(mylink.mystring)
TrimLeadingTrailing
Removes all leading and trailing spaces and tabs from a string.
Syntax
ds.TrimLeadingTrailing(string (string))
returns: the trimmed string.
Examples
If mylink.mystring contains the string " too many spaces ", then the following function returns the string "too many spaces":
ds.TrimLeadingTrailing(mylink.mystring)
UpCase
Changes all lowercase letters in a string to uppercase.
Syntax
ds.UpCase(string (string))
returns: the resulting string in all uppercase.
Examples
If mylink.mystring1 contains the string "CaMel cAsE", then the following function returns the string "CAMEL CASE":
ds.UpCase(mylink.mystring1)
IM
Returns CHAR(255). Works the same as AM.
Syntax
ds.IM()
returns: the resulting CHAR(255).
Examples
The following code returns 'ÿ'.
ds.IM()
FM
Returns CHAR(254).
Syntax
ds.FM()
returns: the resulting CHAR(254).
Examples
The following code returns 'þ'.
ds.FM()
AM
Returns CHAR(254). Works the same as FM.
Syntax
ds.AM()
returns: the resulting CHAR(254).
Examples
The following code returns 'þ'.
ds.AM()
VM
Returns CHAR(253).
Syntax
ds.VM()
returns: the resulting CHAR(253).
Examples
The following code returns 'ý'.
ds.VM()
SM
Returns CHAR(252). Works the same as SVM.
Syntax
ds.SM()
returns: the resulting CHAR(252).
Examples
The following code returns 'ü'.
ds.SM()
SVM
Returns CHAR(252). Works the same as SM.
Syntax
ds.SVM()
returns: the resulting CHAR(252).
Examples
The following code returns 'ü'.
ds.SVM()
TM
Returns CHAR(251).
Syntax
ds.TM()
returns: the resulting CHAR(251).
Examples
The following code returns 'û'.
ds.TM()
Utility functions
The utility functions specify various purposes that are related to retrieving information about specific DataStage functions.
ElementAt
Returns the element in the list that is specified by the index.
Syntax
ds.ElementAt(list (object))
returns: the element index of format object.
Examples
The following code returns 'b':
ds.ElementAt(["a","b","c"], 1)
The following code returns 2:
ds.ElementAt([1,2,3], 1)
GetCommandName
Takes the node ID of a "Run Bash Script activity" and the retrieves the command name of the Run bash script activity.
Syntax
ds.GetCommandName(tasks.activity_id (string))
returns: the command name of format string.
Examples
The following code returns the command name of the task run_bash_script_5:
ds.GetCommandName(tasks.run_bash_script_5)
GetCommandOutput
Takes the node ID of a "Run Bash Script activity" and retrieves its standard output. It is equivalent to the CEL expression:
tasks.<activity_id>.results.standard_output
Syntax
ds.GetCommandOutput(tasks.activity_id (string))
returns: the standard output of format string.
Examples
The following code returns the standard output of the task run_bash_script_5:
ds.GetCommandOutput(tasks.run_bash_script_5)
GetErrorMessage
Used in the task in an exception handler only, the output is the text of the message that are logged as a warning when the exception is raised.
Syntax
ds.GetErrorMessage()
returns: the resulting message of format string.
Examples
The following code returns the error message of a failed task:
ds.GetErrorMessage()
GetErrorNumber
Used in the task in an exception handler only, the output is the integer, which indicates the type of error that is started. Either 1 or -1.
1 indicates that the task ran a job that was cancelled, and no specific handler is set up.
-1 indicates that the task failed to run for other reasons.
Syntax
ds.GetErrorNumber()
returns: the resulting integer of format int.
Examples
The following code returns the error number of the type of exception handler activity:
ds.GetErrorNumber()
GetErrorSource
Used in the task in an exception handler only, the output is the stage name of the activity stage that raised the exception.
Syntax
ds.GetErrorSource()
returns: the resulting value of the task of format string.
Examples
The following code returns the task that failed:
ds.GetErrorSource()
GetJobName
Returns the job name of the Run DataStage activity at the time that the function is run. It is equivalent to the CEL expression:
tasks.<activity_id>.results.job_name
Syntax
ds.GetJobName(tasks.activity_id (string))
returns: the job name of format string.
Examples
The following code returns the job name of the task run_datastage_flow_1:
ds.GetJobName(tasks.run_datastage_flow_1)
GetJobNameWithInvocationId
Returns the job name of the Run DataStage activity at the time that the function is run with a suffix invocation id if the job was run in multiple instances and the job invocation id is not empty.
Syntax
ds.GetJobNameWithInvocationId(tasks.nodeId)
returns: the job name of format string, suffixed with the invocation ID if available.
Examples
The following code returns rowGenPeekJob.bigloop1 with the task name rowGenPeekJob and the invocation ID of bigloop1:
ds.GetJobNameWithInvocationId(tasks.rowGenPeekJob)
GetJobStatus
Takes the node ID of a "Run DataStage activity" and retrieves its job status for <activity_name>.$JobStatus. It is equivalent to the following cel expression:
((tasks.<activity_id>.results.status == 'Completed') ? 1 : ((tasks.<activity_id>.results.status == 'CompletedWithWarnings') ? 2 : ((tasks.<activity_id>.results.status == 'Cancelled') ? 96 : 3)))
Syntax
ds.GetJobStatus(tasks.activity_id (string))
returns: the job status of format int.
Examples
The following code returns the status of the task run_datastage_flow_1:
ds.GetJobStatus(tasks.run_datastage_flow_1)
GetListCounter
Used in the task in a loop with a list counter only, the output is the current value of the counter variable.
Syntax
ds.GetListCounter()
returns: the resulting value of the counter of format string.
Examples
The following code returns the current value of the loop.
ds.GetListCounter()
GetNumericCounter
Used in the task in a loop with a numeric counter only, the output is the current value of the counter variable of the loop.
Syntax
ds.GetNumericCounter()
returns: the resulting value of the counter of format int.
Examples
The following code returns the current value of the loop.
ds.GetNumericCounter()
GetOutputArg
Returns the specified value of a key from an input of JSON of type string.
Syntax
ds.GetOutputArg(JSON (string), key_value (string))
returns: The value of the property field.
Examples
The following code returns the string value "tom":
ds.GetOutputArg("{"name":"tom"}", "name")
GetReturnValue
Takes the node ID of a "Run Bash Script activity" and returns the value of the Run Bash Script activity. It is equivalent to the following CEL expression:
tasks.<activity_id>.results.return_value
Syntax
ds.GetReturnValue(tasks.activity_id (string))
returns: the resulting value of the task of format int.
Examples
The following code returns the value of the task tasks.run_bash_script_5:
ds.GetReturnValue(tasks.run_bash_script_5)
GetUserStatus
Takes the ID of a DataStage flow task and returns the status of the DataStage flow task in the sequence job. The function does not work if run in parallel job. It is equivalent to the CEL expression:
tasks.<activity_id>.results.user_status
Syntax
ds.GetUserStatus(tasks.run_datastage_id (string))
returns: the status of the DataStage flow task ID of format string.
Examples
The following code returns the value of task ID run_datastage_5:
ds.GetUserStatus(tasks.run_datastage_5)
LogName
Returns the login name of the current user.
Syntax
ds.LogName()
returns: the login name of the current user of format string.
Examples
The following code returns the login name of the current user.
ds.LogName()
Path
Returns the path name of the current user.
Syntax
ds.Path()
returns: the path name of the current user of format string.
Examples
The following code returns the path name of the current user.
ds.Path()
Schema
Returns the schema name of the current user.
Syntax
ds.Schema()
returns: the schema name of the current user of format string.
Examples
The following code returns the schema name of the current user.
ds.Schema()
UserNo
Returns the user number of the current user.
Syntax
ds.UserNo()
returns: the user information of the current user of format int.
Examples
The following code returns the user number of the current user.
ds.UserNo()
Who
Returns the current user.
Syntax
ds.Who()
returns: the current user of format string.
Examples
The following code returns the current user.
ds.Who()
Null handling functions
Functions that do null handling.
IsNull
Returns true when the input expression evaluates to the null value.
Syntax
ds.IsNull(input (any))
returns: the result of whether the expression evaluates to null, of format Boolean.
Examples
The following code returns true.
ds.IsNull(null)
The following code returns false.
ds.IsNull(0)
IsNotNull
Returns true when the input expression does not evaluate to the null value.
Syntax
ds.IsNotNull(input (any))
returns: the result of whether the expression does not evaluate to null, of format Boolean.
Examples
The following code returns false.
ds.IsNotNull(null)
The following code returns true.
ds.IsNotNull(0)
Null
Returns the null value.
Syntax
ds.Null()
returns: the null value.
Examples
The following code returns null.
ds.Null()
NullToEmpty
Returns an empty string if the input is null, otherwise returns the input column value.
Syntax
ds.NullToEmpty(input (any))
returns: an empty string or the input value.
Examples
The following code returns "AA".
ds.NullToEmpty("AA")
The following code returns "".
ds.NullToEmpty(null)
NullStr
Returns the null string CHAR(128).
Syntax
ds.NullStr()
returns: the null string CHAR(128).
Examples
The following code returns €.
ds.NullStr()
NullToValue
Returns the specified value if the input is null, otherwise returns the input column value.
Syntax
ds.NullToValue(input (any), default (any))
returns: the specified value or the input value.
Examples
The following code returns "test".
ds.NullToValue("test", "default")
The following code returns "default".
ds.NullToValue(null, "default")
The following code returns 1.
ds.NullToValue(null, 1)
NullToZero
Returns 0 if the input is null, otherwise returns the input column value.
Syntax
ds.NullToZero(input (any))
returns: 0 or the input value.
Examples
The following code returns 88.
ds.NullToZero(88)
The following code returns 0.
ds.NullToZero(null)
SetNull
Assigns a null value to the target column.
Syntax
ds.SetNull()
returns: sets the target to the null value.
Examples
The following code returns null.
ds.SetNull()
Macros functions
Functions that handle retrieval of a set of project metadata related to DataStage sequence jobs.
JobName
Returns the sequencer job name.
Syntax
ds.JobName
returns: the sequencer job name of format string.
Examples
The following code returns the sequencer job name.
ds.JobName
JobStartDate
Returns the sequencer job start date.
Syntax
ds.JobStartDate
returns: the sequencer job start date of the format string.
Examples
The following code returns the sequencer job start date.
ds.JobStartDate
JobStartTime
Returns the sequencer job start time.
Syntax
ds.JobStartTime
returns: the sequencer job start time of format string.
Examples
The following code returns the sequencer job start time.
ds.JobStartTime
JobStartTimestamp
Returns the sequencer job start timestamp.
Syntax
ds.JobStartTimestamp
returns: the sequencer job start timestamp of format timestamp.
Examples
The following code returns the sequencer job start timestamp.
ds.JobStartTimestamp
HostName
Returns the host name of DataStage server.
Syntax
ds.HostName
returns: the sequencer job InvocationId of format string.
Examples
The following code returns the sequencer job InvocationId.
ds.HostName
ProjectName
Returns the project name of the running sequencer job
Syntax
ds.ProjectName
returns: the project name of the running sequencer job.
Examples
The following code returns the project name of the running sequencer job.
ds.ProjectName
ProjectId
Returns the project ID of the running sequencer job.
Syntax
ds.ProjectId
returns: the project ID of the running sequencer job.
Examples
The following code returns the project ID of the running sequencer job.
ds.ProjectId
JobId
Returns the job ID of the running sequencer job.
Syntax
ds.JobId
returns: the job ID of the running sequencer job.
Examples
The following commands returns the job ID of the running sequencer job.
ds.JobId
JobController
Returns the pipeline flow name of the running sequencer job.
Syntax
ds.JobController
returns: the pipeline flow name of the running sequencer job.
Examples
The following commands returns the pipeline flow name of the running sequencer job.
ds.JobController
Parent topic: Adding conditions to a pipeline