DataStage Functions used in pipelines Expression Builder

Last updated: Nov 27, 2024

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
Date and time functions
Operator functions
Logical functions
Mathematical functions
Number functions
Raw functions
String functions
Utility functions
Null handling functions
Macros 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.

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.

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.

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.

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.

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.x where 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

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

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 2³²-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 2³²-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