System Macros

This topic describes how to use the most common system macros.

Making These Macros Accessible

Except where noted, the macros described on this page are available to all subclasses of %RegisteredObjectOpens in a new tab. To make these available in a routine or in a class that does not extend %RegisteredObjectOpens in a new tab, include the appropriate file:

For status-related macros, include %occStatus.inc.
For message-related macros, include %occMessages.inc

See each macro below for which include file it requires.

The syntax for such statements is as follows (notice that the .inc extension is omitted):

#include %occStatus

The names of these include files are case-sensitive. For more details on using externally defined macros, see Referring to External Macros (Include Files).

Macro Reference

Macro names are case-sensitive. Among the macros supplied with InterSystems IRIS are:

$$$ADDSC(sc1,sc2)

Appends a %Status code (sc2) to an existing %StatusOpens in a new tab code (sc1). This macro requires %occStatus.inc.

$$$EMBEDSC(sc1,sc2)

Embeds a %Status code (sc2) within an existing %StatusOpens in a new tab code (sc1). This macro requires %occStatus.inc.

$$$ERROR(errorcode,arg1,arg2,...)

Creates a %Status object using an object error code (errorcode) the associated text of which may accept some number of arguments of the form %1, %2, and so on. ERROR then replaces these arguments with the macro arguments that follow errorcode (arg1, arg2, and so on) based on the order of these additional arguments. This macro requires %occStatus.inc.

For a list of system-defined error codes, see General Error Messages.

$$$FormatMessage(language,domain,id,default,arg1,arg2,...)

Enables you to retrieve text from the Message Dictionary, and substitute text for message arguments, all in the same macro call. It returns a %StringOpens in a new tab.

Argument	Description
language	An RFC1766Opens in a new tab language code. Within a web application, you can specify %response.Language to use the default locale.
domain	The message domain. Within a web application, you may specify %response.Domain
id	The message ID.
default	The string to use if the message identified by language, domain, and id is not found.
arg1, arg2, and so on	Substitution text for the message arguments. All of these are optional, so you can use $$$FormatMessage even if the message has no arguments.

For information on the Message Dictionary, see String Localization and Message Dictionaries.

This macro requires %occMessages.inc.

Also see the FormatMessage() instance method of %Library.MessageDictionaryOpens in a new tab.

$$$FormatText(text,arg1,arg2,...)

Accepts an input text message (text) which may contain arguments of the form %1, %2, etc. FormatText then replaces these arguments with the macro arguments that follow the text argument (arg1, arg2, and so on) based on the order of these additional arguments. It then returns the resulting string. This macro requires %occMessages.inc.

$$$FormatTextHTML(text,arg1,arg2,...)

Accepts an input text message (text) which may contain arguments of the form %1, %2, etc. FormatTextHTML then replaces these arguments with the macro arguments that follow the text argument (arg1, arg2, and so on) based on the order of these additional arguments; the macro then applies HTML escaping. It then returns the resulting string. This macro requires %occMessages.inc.

$$$FormatTextJS(text,arg1,arg2,...)

Accepts an input text message (text) which may contain arguments of the form %1, %2, etc. FormatTextJS then replaces these arguments with the macro arguments that follow the text argument (arg1, arg2, and so on) based on the order of these additional arguments; the macro then applies JavaScript escaping. It then returns the resulting string. This macro requires %occMessages.inc.

$$$GETERRORCODE(sc)

Returns the error code value from the supplied %Status code (sc). This macro requires %occStatus.inc.

$$$GETERRORMESSAGE(sc,num)

Returns the portion of the error message value from the supplied %Status code (sc) as specified by num. For example, num=1 returns SQLCODE error number, num=2 returns the error message text. This macro requires %occStatus.inc.

$$$ISERR(sc)

Returns True if the supplied %Status code (sc) is an error code. Otherwise, it returns False. This macro requires %occStatus.inc.

$$$ISOK(sc)

Returns True if the supplied %Status code (sc) is successful completion. Otherwise, it returns False. This macro requires %occStatus.inc.

$$$LOWER(string)

Returns the lowercase form of the input string. Unlike the other macros listed here, this macro is automatically available in all class definitions. To include it in a routine, include the %systemInclude include file.

$$$OK

Creates a %Status code that represents successful completion. This macro requires %occStatus.inc.

$$$Text(text,domain,language)

Used for localization, this macro generates a new message at compile time and generates code to retrieve the message at runtime. This macro requires %occMessages.inc.

$$$TextHTML(text,domain,language)

Used for localization, this macro performs the same processing as the Text macro; it then additionally applies HTML escaping. It then returns the resulting string. This macro requires %occMessages.inc.

$$$TextJS(text,domain,language)

Used for localization, this macro performs the same processing as the Text macro; it then additionally applies JavaScript escaping. It then returns the resulting string. This macro requires %occMessages.inc.

$$$ThrowOnError(sc)

Evaluates the specified %Status code (sc). If sc represents an error status, ThrowOnError performs a THROW operation to throw an exception of type %Exception.StatusExceptionOpens in a new tab to an exception handler. This macro requires %occStatus.inc. For further details, see The TRY-CATCH Mechanism

$$$THROWONERROR(sc,expr)

Evaluates an expression (expr), where the expression’s value is assumed to be a %Status code; the macro stores the %StatusOpens in a new tab code in the variable passed as sc. If the %StatusOpens in a new tab code is an error, THROWONERROR performs a THROW operation to throw an exception of type %Exception.StatusExceptionOpens in a new tab to an exception handler. This macro requires %occStatus.inc.

$$$ThrowSQLCODE(sqlcode,message)

Uses the specified SQLCODE and Message to perform a THROW operation to throw an exception of type %Exception.SQLOpens in a new tab to an exception handler. This macro requires %occStatus.inc. For further details, see The TRY-CATCH Mechanism.

$$$ThrowSQLIfError(sqlcode,message)

Uses the specified SQLCODE and Message to perform a THROW operation to throw an exception of type %Exception.SQLOpens in a new tab to an exception handler. It throws this exception if SQLCODE < 0 (a negative number, indicating an error). This macro requires %occStatus.inc. For further details, see The TRY-CATCH Mechanism.

$$$ThrowStatus(sc)

Uses the specified %Status code (sc) to perform a THROW operation to throw an exception of type %Exception.StatusExceptionOpens in a new tab to an exception handler. This macro requires %occStatus.inc. For further details, see The TRY-CATCH Mechanism.

$$$UPPER(string)

Returns the uppercase form of the input string. Unlike the other macros listed here, this macro is automatically available in all class definitions. To include it in a routine, include the %systemInclude.inc include file.

System Flags and Qualifiers (qspec)

General System Limits