ObjectScript Reference

  • About This Book
  • Symbols and Abbreviations
  • ObjectScript Commands
    • BREAK – Interrupts execution at a breakpoint. Enables or disables user interrupts.
    • CATCH – Identifies a block of code to execute when an exception occurs.
    • CLOSE – Closes a file or a device.
    • CONTINUE – Jumps to FOR, WHILE, or DO WHILE command and re-executes test and loop.
    • DO – Calls a routine.
    • DO WHILE – Executes code while a condition exists.
    • ELSE – Clause of block-oriented IF command.
    • ELSEIF – Clause of block-oriented IF command.
    • FOR – Executes a block of code repeatedly, testing at the beginning of each loop.
    • GOTO – Transfers control.
    • HALT – Terminates execution of the current process.
    • HANG – Suspends execution for a specified number of seconds.
    • IF – Evaluates an expression, then selects which block of code to execute based on the truth value of the expression.
    • JOB – Runs a process in background.
    • KILL – Deletes variables.
    • LOCK – Enables a process to apply and release locks to control access to data resources.
    • MERGE – Merges global nodes or subtrees from source into destination.
    • NEW – Creates empty local variable environment.
    • OPEN – Acquires ownership of a device or file for input/output operations.
    • QUIT – Terminates execution of a loop structure or a routine.
    • READ – Accepts input and stores it in a variable.
    • RETURN – Terminates execution of a routine.
    • SET – Assigns a value to a variable.
    • TCOMMIT – Marks the successful completion of a transaction.
    • THROW – Explicitly throws an exception to the next exception handler.
    • TROLLBACK – Rolls back an unsuccessful transaction.
    • TRY – Identifies a block of code to monitor for errors during execution.
    • TSTART – Marks the beginning of a transaction.
    • USE – Establishes a device as the current device.
    • VIEW – Reads and writes database blocks and modifies data in memory.
    • WHILE – Executes code while a condition is true.
    • WRITE – Displays output to current device.
    • XECUTE – Executes the specified commands.
    • ZKILL – Deletes a node while preserving the node’s descendants.
    • ZNSPACE – Sets the current namespace.
    • ZTRAP – Forces an error with a specified error code.
    • ZWRITE – Displays variable names and their values and/or expression values.
    • ZZDUMP – Displays an expression in hexadecimal dump format.
    • ZZWRITE – Displays the values of variables or expressions.
  • Routine and Debugging Commands
    • PRINT – Displays lines of code from the current routine on the current device.
    • ZBREAK – Sets a breakpoint or watchpoint.
    • ZINSERT – Inserts one or more lines of code into the current routine.
    • ZLOAD – Loads a routine into the current routine buffer.
    • ZPRINT – Displays lines of code from the current routine on the current device.
    • ZREMOVE – Deletes a line or a range of lines from the current routine, or unloads the current routine.
    • ZSAVE – Saves the current routine.
    • ZZPRINT – Displays one or more source code lines from a routine.
  • ObjectScript Functions
    • $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.
  • ObjectScript Special Variables
    • $DEVICE – Contains user-specified device status information.
    • $ECODE – Contains the current error code string.
    • $ESTACK – Contains the number of context frames saved on the call stack from a user-defined point.
    • $HALT – Contains a halt trap routine call.
    • $HOROLOG – Contains the local date and time for the current process.
    • $IO – Contains the ID of the current input/output device.
    • $JOB – Contains the ID of the current process.
    • $KEY – Contains the terminator character from the most recent READ.
    • $NAMESPACE – Contains the namespace for the current stack level.
    • $PRINCIPAL – Contains the ID of the principal I/O device.
    • $QUIT – Contains a flag indicating what kind of QUIT is required to exit the current context.
    • $ROLES – Contains the roles assigned to the current process.
    • $STACK – Contains the number of context frames saved on the call stack.
    • $STORAGE – Contains the number of bytes available for local variable storage.
    • $SYSTEM – Contains system information about system objects.
    • $TEST – Contains the truth value resulting from the last command using the timeout option.
    • $THIS – Contains the current class context.
    • $THROWOBJ – Contains the OREF from an unsuccessful THROW.
    • $TLEVEL – Contains the current nesting level for transaction processing.
    • $USERNAME – Contains the username for the current process.
    • $X – Contains the current horizontal position of the cursor.
    • $Y – Contains the current vertical position of the cursor.
    • $ZA – Contains the status of the last READ on the current device.
    • $ZB – Contains status information for the current I/O device.
    • $ZCHILD – Contains the ID of the last child process.
    • $ZEOF – Contains flag indicating whether end-of-file has been reached.
    • $ZEOS – Contains end-of-stream status when reading a compressed stream.
    • $ZERROR – Contains the name and location of the last error.
    • $ZHOROLOG – Contains the number of seconds elapsed since InterSystems IRIS startup.
    • $ZIO – Contains information about the current terminal I/O device.
    • $ZJOB – Contains job status information.
    • $ZMODE – Contains current I/O device OPEN parameters.
    • $ZNAME – Contains the current routine name.
    • $ZNSPACE – Contains the current namespace name.
    • $ZORDER – Contains the value of the next global node.
    • $ZPARENT – Contains the ID of the parent process of the current process.
    • $ZPI – Contains the value of pi.
    • $ZPOS – Contains the current file position during the reading of a sequential file.
    • $ZREFERENCE – Contains the current global reference.
    • $ZSTORAGE – Contains the maximum available memory for a process.
    • $ZTIMESTAMP – Contains the current date and time in Coordinated Universal Time format.
    • $ZTIMEZONE – Contains the time zone offset from the Greenwich meridian.
    • $ZTRAP – Contains the location of the current error trap handler.
    • $ZVERSION – Contains a string describing the current version of InterSystems IRIS.
  • Structured System Variables
    • ^$GLOBAL – Provides information about globals and process-private globals.
    • ^$JOB – Provides InterSystems IRIS process (job) information.
    • ^$LOCK – Provides lock name information.
    • ^$ROUTINE – Provides routine information.