Previous section   Next section

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® 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 the Functions description in the “Introducing ObjectScript” chapter of Using ObjectScript; for more information on defining your own functions, see User-Defined Code in Using ObjectScript.
To invoke a system function, use the form:
$name(parameters)
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).
parameters
One or more values to be passed to the function. Function arguments, or parameters, are always enclosed in parentheses and follow the function name. The parentheses are mandatory, even if the function has no parameters.
Multiple parameters are separated from each other by commas. The parameters are positional and must match the order of the parameters expected by the function. Missing parameters in this sequence can be indicated by supplying the appropriate number of commas; no trailing commas are required for parameters missing from the end of the parameter list.
Spaces are permitted anywhere in the parameter 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 parameters of the syntax are optional. This information is provided in the table of parameters immediately following the Synopsis.
The one exception is the ellipsis (...). An ellipsis following a comma indicates that the parameter (or parameter 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® 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.
  • $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 an InterSystems IRIS floating point value.
  • $DOUBLE – Returns a number converted to a 64-bit floating-point 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 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.
  • $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 replacement of a source string.
  • $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 – Absolute value function.
  • $ZARCCOS – Inverse (arc) cosine function.
  • $ZARCSIN – Inverse (arc) sine function.
  • $ZARCTAN – Inverse (arc) tangent function.
  • $ZBOOLEAN – Bitwise logical operation function.
  • $ZCONVERT – String conversion function.
  • $ZCOS – Cosine function.
  • $ZCOT – Cotangent function.
  • $ZCRC – Checksum function.
  • $ZCSC – Cosecant function.
  • $ZCYC – Cyclical-redundancy check for data integrity.
  • $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 InterSystems IRIS internal format.
  • $ZDCHAR – Converts a $DOUBLE floating point number to an eight-byte string.
  • $ZEXP – Exponential function (inverse of natural logarithm).
  • $ZF – Invokes non-ObjectScript programs or functions from ObjectScript routines.
  • $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.
  • $ZF(-4) – Provides utility functions used with $ZF(-5) and $ZF(-6).
  • $ZF(-5) – Executes a DLL function loaded using $ZF(-4).
  • $ZF(-6) – Executes a DLL function indexed using $ZF(-4).
  • $ZF(-100) – Executes an operating system command or program as a child process.
  • $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 a number to a 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 – Validates the specified name string as 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 a number to an 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 a number to a 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.
Previous section   Next section