ObjectScript Functions
A function performs an operation and returns a value. This value may be the result of the operation, or an indicator that the operation completed successfully or failed. By convention, InterSystems IRIS® data platform functions that set a variable to a value set the variable, then return the value of that variable prior to the operation.
This document describes system functions (also known as intrinsic functions). System functions are identified by a $ character prefix to the name and parentheses following the name. The parentheses are not specified when referring to a function in documentation. You can supplement these system functions by creating user-supplied functions (also known as extrinsic functions). User-supplied functions are identified by a $$ prefix.
The names of ObjectScript special variables also begin with a $ character, but special variables have no parentheses.
For more information on ObjectScript functions generally, see Functions; for more information on defining your own functions, see User-Defined Code.
To invoke a system function, use the form:
$name(arguments)
Argument | Description |
---|---|
name | The name of the function. The preceding dollar sign ($) is required. Function names are shown here in all uppercase letters, but they are, in fact, not case-sensitive. You can abbreviate most function names. In the Synopsis for each function, the full name syntax is first presented, and below it is shown the abbreviated name (if one exists). |
arguments |
One or more values to be passed to the function. Function arguments are always enclosed in parentheses and follow the function name. The parentheses are mandatory, even if the function has no arguments. Multiple arguments are separated from each other by commas. The arguments are positional and must match the order of the arguments expected by the function. Missing arguments in this sequence can be indicated by supplying the appropriate number of commas; no trailing commas are required for arguments missing from the end of the argument list. Spaces are permitted anywhere in the argument list. No spaces are permitted between name and the open parenthesis character. |
The Synopsis for each function contains only literal syntactical punctuation. The Synopsis does not include punctuation for format conventions, such as what arguments of the syntax are optional. This information is provided in the table of arguments immediately following the Synopsis.
The one exception is the ellipsis (...). An ellipsis following a comma indicates that the argument (or argument group) preceding the comma can be repeated multiple times as a comma-separated list.
Any platform-specific function is marked with the name of the platform that supports it. Any function that is not marked with a platform abbreviation is supported by all InterSystems IRIS® data platform platforms.
- $ASCII – Converts a character to a numeric code.
- $BIT – Returns and or sets the bit value of a specified position in a bitstring.
- $BITCOUNT – Returns the number of bits in a bitstring.
- $BITFIND – Returns the position of the specified bit value within a bitstring.
- $BITLOGIC – Performs bit-wise operations on bitstrings.
- $CASE – Compares expressions and returns the value of the first matching case.
- $CHANGE – Returns a new string that consists of a string-for-string substring replacement from an input string.
- $CHAR – Converts the integer value of an expression to the corresponding ASCII or Unicode character.
- $CLASSMETHOD – Executes a named class method in the designated class.
- $CLASSNAME – Returns the name of a class.
- $COMPILE – Compiles source code, producing executable object code.
- $DATA – Checks if a variable contains data.
- $DECIMAL – Returns a number converted to a floating-point value, specifically an InterSystems decimal format value.
- $DOUBLE – Returns a number converted to a 64-bit floating-point value, specifically the InterSystems $DOUBLE format value.
- $EXTRACT – Extracts a substring from a character string by position, or replaces a substring by position.
- $FACTOR – Converts an integer to a $BIT bitstring.
- $FIND – Finds a substring by value and returns an integer specifying its end position in the string.
- $FNUMBER – Formats a numeric value with a specified format; optionally rounds or zero fills to a specified precision.
- $GET – Returns the data value of a specified variable.
- $INCREMENT – Adds a specified increment to the numeric value of a variable.
- $INUMBER – Validates a numeric value and converts it to internal format.
- $ISOBJECT – Returns 1 or 0 based on whether an expression is an object reference (OREF).
- $ISVALIDDOUBLE – Validates a $DOUBLE numeric value and returns a boolean; optionally provides range checking.
- $ISVALIDNUM – Validates a numeric value and returns a boolean; optionally provides range checking.
- $ISVECTOR – Validates a vector value and returns a boolean.
- $JUSTIFY – Right-aligns an expression within a specified width, rounding to a specified number of fractional digits.
- $LENGTH – Returns the number of characters or delimited substrings in a string.
- $LIST – Returns or replaces elements in a list.
- $LISTBUILD – Builds a list of elements from the specified expressions.
- $LISTDATA – Indicates whether the specified element exists and has a data value.
- $LISTFIND – Searches a specified list for the requested value.
- $LISTFROMSTRING – Creates a list from a string.
- $LISTGET – Returns an element in a list, or a specified default value if the requested element is undefined.
- $LISTLENGTH – Returns the number of elements in a specified list.
- $LISTNEXT – Retrieves elements sequentially from a list.
- $LISTSAME – Compares two lists and returns a boolean value.
- $LISTTOSTRING – Creates a string from a list.
- $LISTUPDATE – Updates a list by optionally replacing a specified list element or sequence of elements.
- $LISTVALID – Determines if an expression is a list.
- $LOCATE – Locates the first match of a regular expression in a string.
- $MATCH – Matches a regular expression to a string.
- $METHOD – Supports calls to an instance method.
- $NAME – Returns the name value of a variable or a portion of a subscript reference.
- $NCONVERT – Converts a number to a binary value encoded in a string of 8-bit characters.
- $NORMALIZE – Validates and returns a numeric value; rounds to a specified precision.
- $NOW – Returns the local date and time with fractional seconds for the current process.
- $NUMBER – Validates and returns a numeric value; optionally provides rounding and range checking.
- $ORDER – Returns the next local variable or the subscript of a local or global variable.
- $PARAMETER – Returns the value of the specified class parameter.
- $PIECE – Returns or replaces a substring, using a delimiter.
- $PREFETCHOFF – Ends pre-fetching of globals.
- $PREFETCHON – Establishes pre-fetch for specified globals.
- $PROPERTY – Supports reference to a particular property of an instance.
- $QLENGTH – Returns the number of subscript levels in a variable.
- $QSUBSCRIPT – Returns a variable name or a subscript name.
- $QUERY – Performs a physical scan of a local or global array.
- $RANDOM – Returns a pseudo-random integer value in the specified range.
- $REPLACE – Returns a new string that consists of a string-for-string substring replacement from an input string.
- $REVERSE – Returns the characters in a string in reverse order.
- $SCONVERT – Converts a binary encoded value to a number.
- $SELECT – Returns the value associated with the first true expression.
- $SEQUENCE – Increments a global variable shared by multiple processes.
- $SORTBEGIN – Initiates a sorting mode to improve performance of multiple sets to a global.
- $SORTEND – Concludes the sorting mode initiated by $SORTBEGIN.
- $STACK – Returns information about active contexts saved on the process call stack.
- $TEXT – Returns a line of source code found at the specified location.
- $TRANSLATE – Returns a new string that consists of character-for-character replacements of a source string.
- $VECTOR – Assigns, returns, and deletes vector data at specified positions
- $VECTORDEFINED – Determines if vector element at specified position is defined.
- $VECTOROP – Performs various operations on vectors defined through ObjectScript
- $VIEW – Returns the contents of memory locations.
- $WASCII – Returns the numeric code corresponding to a character, recognizing surrogate pairs.
- $WCHAR – Returns the character corresponding to a numeric code, recognizing surrogate pairs.
- $WEXTRACT – Extracts a substring from a character string by position, or replaces a substring by position, recognizing surrogate pairs.
- $WFIND – Finds a substring by value and returns an integer specifying its end position in the string, recognizing surrogate pairs.
- $WISWIDE – Returns a flag indicating whether a string contains surrogate pairs.
- $WLENGTH – Returns the number of characters in a string, recognizing surrogate pairs.
- $WREVERSE – Returns the characters in a string in reverse order, recognizing surrogate pairs.
- $XECUTE – Executes a specified command line.
- $ZABS – Returns the absolute value of the given argument.
- $ZARCCOS – Returns the inverse (arc) cosine of the given argument.
- $ZARCSIN – Returns the inverse (arc) sine of the given argument.
- $ZARCTAN – Returns the inverse (arc) tangent of the given argument.
- $ZBOOLEAN – Returns the result of a bitwise logical operation.
- $ZCONVERT – Returns a converted value of the given string, given a conversion mode and optional arguments.
- $ZCOS – Returns the cosine of the given argument.
- $ZCOT – Returns the cotangent of the given argument.
- $ZCRC – Returns the checksum of the given argument, using the specified checksum mode.
- $ZCSC – Returns the cosecant of the given argument.
- $ZCYC – Returns the cyclical-redundancy check value for the given string.
- $ZDASCII – Converts an eight-byte string to a $DOUBLE floating point number.
- $ZDATE – Validates a date and converts it from internal format to the specified display format.
- $ZDATEH – Validates a date and converts it from display format to InterSystems IRIS internal format.
- $ZDATETIME – Validates a date and time and converts it from internal format to the specified display format.
- $ZDATETIMEH – Validates a date and time and converts from display format to internal format.
- $ZDCHAR – Converts a $DOUBLE floating point number to an eight-byte string.
- $ZEXP – Returns the exponential function of the given argument (inverse of natural logarithm) — the number e to the given power.
- $ZF – Invokes non-ObjectScript programs or functions from ObjectScript routines. This function is a component of the Callout SDK.
- $ZF(-1) – Executes an operating system command or program as a child process, synchronously. (Deprecated).
- $ZF(-2) – Executes an operating system command or program as a child process, asynchronously. (Deprecated)
- $ZF(-3) – Loads a Dynamic-Link Library (DLL) and executes a library function. This function is a component of the Callout SDK.
- $ZF(-4) – Provides utility functions used with $ZF(-5) and $ZF(-6). This function is a component of the Callout SDK.
- $ZF(-5) – Executes a DLL function loaded using $ZF(-4). This function is a component of the Callout SDK.
- $ZF(-6) – Executes a DLL function indexed using $ZF(-4). This function is a component of the Callout SDK.
- $ZF(-100) – Executes an operating system command or program as a child process. This function is a component of the Callout SDK.
- $ZHEX – Converts a hexadecimal string to a decimal number and vice versa.
- $ZISWIDE – Checks whether a string contains any 16-bit wide characters.
- $ZLASCII – Converts a four-byte string to a number.
- $ZLCHAR – Converts an integer to the corresponding four-byte string.
- $ZLN – Returns the natural logarithm of the specified number.
- $ZLOG – Returns the base–10 logarithm value of the specified positive numeric expression.
- $ZNAME – Returns 1 or 0 based on whether the given argument is a legal identifier.
- $ZPOSITION – Returns the number of characters in an expression that can fit within a specified field width.
- $ZPOWER – Returns the value of a number raised to a specified power.
- $ZQASCII – Converts an eight-byte string to a number.
- $ZQCHAR – Converts an integer to the corresponding eight-byte string.
- $ZSEARCH – Returns the full file specification, pathname and filename, of a specified file.
- $ZSEC – Returns the trigonometric secant of the specified angle value.
- $ZSEEK – Establishes a new offset into the current sequential file.
- $ZSIN – Returns the trigonometric sine of the specified angle value.
- $ZSQR – Returns the square root of a specified number.
- $ZSTRIP – Removes types of characters and individual characters from a specified string.
- $ZTAN – Returns the trigonometric tangent of the specified angle value.
- $ZTIME – Validates a time and converts it from internal format to the specified display format.
- $ZTIMEH – Validates a time and converts it from display format to InterSystems IRIS internal format.
- $ZVERSION(1) – Returns the operating system type.
- $ZWASCII – Converts a two-byte string to a number.
- $ZWCHAR – Converts an integer to the corresponding two-byte string.
- $ZWIDTH – Returns the total width of the characters in an expression.
- $ZWPACK and $ZWBPACK – Packs two 8-bit characters into a single 16-bit character.
- $ZWUNPACK and $ZWBUNPACK – Unpacks a single 16-bit character to two 8-bit characters.
- $ZZENKAKU – Converts Japanese katakana characters from half-width to full-width.