Skip to main content

System Macros

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

Making These Macros Accessible

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:

#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)

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

EMBEDSC(sc1, sc2)

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

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

The ERROR macro 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,...)

The FormatMessage macro 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, ...)

The FormatText macro 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, ...)

The FormatTextHTML macro 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, ...)

The FormatTextJS macro 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)

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

GETERRORMESSAGE(sc,num)

The GETERRORMESSAGE macro 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)

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

ISOK(sc)

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

OK

The OK macro creates a %Status code for successful completion. This macro requires %occStatus.inc.

Text(text, domain, language)

The Text macro is used for localization. It 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)

The TextHTML macro is used for localization. It 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)

The TextJS macro is used for localization. It 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)

The ThrowOnError macro 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)

The THROWONERROR macro 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)

The ThrowSQLCODE macro 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)

The ThrowSQLIfError macro 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)

The ThrowStatus macro 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.

FeedbackOpens in a new tab