Skip to main content

Using the Callin Functions

This section provides a quick summary of the Callin functions, with links to the full description of each function. The following categories are discussed:

  • Process Control

    These functions start and stop a Callin session, and control various settings associated with the session.

  • Functions and Routines

    These functions execute function or routine calls. Stack functions are provided for pushing function or routine references.

  • Transactions and Locking

    These functions execute the standard InterSystems IRIS® transaction commands (TSTART, TCOMMIT, and TROLLBACK) and the LOCK command.

  • Managing Objects

    These functions manipulate the Oref counter, perform method calls, and get or set property values. Stack functions are also included for Orefs, method references, and property names.

  • Managing Globals

    These functions call into InterSystems IRIS to manipulate globals. Functions are provided to push globals onto the argument stack.

  • Managing Strings

    These functions translate strings from one form to another, and push or pop string arguments.

  • Managing Simple Datatypes

    These stack functions are used to push and pop arguments that have int, double, $list, or pointer values.

The following sections discuss the individual functions in more detail.

Process Control

These functions start and stop a Callin session, control various settings associated with the session, and provide a high-level interface for executing ObjectScript commands and expressions.

Session Control

These functions start and stop a Callin session, and control various settings associated with the session.

Session control functions
IrisAbort Tells InterSystems IRIS to terminate the current request.
IrisChangePasswordA[W][H] Changes the user's password if InterSystems authentication is used. Must be called before a Callin session is initialized.
IrisContext Returns an integer indicating whether you are in a $ZF callback session, in the InterSystems IRIS side of a Callin call, or in the user program side.
IrisCtrl Determines whether or not InterSystems IRIS ignores CTRL-C.
IrisEnd Terminates an InterSystems IRIS session and, if necessary, cleans up a broken connection. (Calls into InterSystems IRIS).
IrisEndAll Disconnects all Callin threads and waits until they terminate.
IrisOflush Flushes any pending output.
IrisPromptA[W][H]

Returns a string that would be the Terminal.

IrisSetDir Dynamically sets the name of the manager's directory (IrisSys\Mgr) at runtime. On Windows, the shared library version of InterSystems IRIS requires this function.
IrisSignal Reports a signal detected by the user program to InterSystems IRIS for handling.
IrisSecureStartA[W][H]

Initiates an InterSystems IRIS process.

IrisStartA[W][H] (Deprecated. Use IrisSecureStart instead) Initiates an InterSystems IRIS process.

Running ObjectScript

These functions provide a high-level interface for executing ObjectScript commands and expressions.

ObjectScript command functions
IrisExecuteA[W][H]

Executes an ObjectScript command. (Calls into InterSystems IRIS).

IrisEvalA[W][H]

Evaluates an ObjectScript expression. (Calls into InterSystems IRIS).

IrisConvert Returns the value of the InterSystems IRIS expression returned by IrisEval.
IrisType Returns the datatype of an item returned by IrisEval.
IrisErrorA[W][H]

Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.

IrisErrxlateA[W][H]

Returns the InterSystems IRIS error string associated with error number returned from a Callin function.

Functions and Routines

These functions call into InterSystems IRIS to perform function or routine calls. Functions are provided to push function or routine references onto the argument stack.

Functions for performing function and routine calls
IrisDoFun Perform a routine call (special case). (Calls into InterSystems IRIS).
IrisDoRtn Perform a routine call. (Calls into InterSystems IRIS).
IrisExtFun Perform an extrinsic function call. (Calls into InterSystems IRIS).
IrisPop Pops a value off argument stack.
IrisUnPop Restores the stack entry from IrisPop
IrisPushFunc[W][H] Pushes an extrinsic function reference onto the argument stack.
IrisPushFuncX[W][H] Push an extended function reference onto argument stack
IrisPushRtn[W][H] Push a routine reference onto argument stack
IrisPushRtnX[W][H] Push an extended routine reference onto argument stack

Transactions and Locking

These functions execute the standard InterSystems IRIS transaction commands (TSTART, TCOMMIT, and TROLLBACK) and the LOCK command.

Transactions

The following functions execute the standard InterSystems IRIS transaction commands.

Transaction functions
IrisTCommit Executes a TCommit command.
IrisTLevel Returns the current nesting level ($TLEVEL) for transaction processing.
IrisTRollback Executes a TRollback command.
IrisTStart Executes a TStart command.

Locking

These functions execute various forms of the InterSystems IRIS LOCK command. Functions are provided to push lock names onto the argument stack for use by the IrisAcquireLock function.

Locking functions
IrisAcquireLock Executes a LOCK command.
IrisReleaseAllLocks Performs an argumentless InterSystems IRIS LOCK command to remove all locks currently held by the process.
IrisReleaseLock Executes an InterSystems IRIS LOCK — command to decrement the lock count for the specified lock name.
IrisPushLock[W][H] Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
IrisPushLockX[W][H] Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.

Managing Objects

These functions call into InterSystems IRIS to manipulate the Oref counter, perform method calls, and get or set property values. Stack functions are also included for Orefs, method references, and property names.

Orefs

Oref functions
IrisCloseOref Decrement the reference counter for an OREF. (Calls into InterSystems IRIS).
IrisIncrementCountOref Increment the reference counter for an OREF
IrisPopOref Pop an OREF off argument stack
IrisPushOref Push an OREF onto argument stack

Methods

Method functions
IrisInvokeMethod Perform an instance method call. (Calls into InterSystems IRIS).
IrisPushMethod[W][H] Push an instance method reference onto argument stack
IrisInvokeClassMethod Perform a class method call. (Calls into InterSystems IRIS).
IrisPushClassMethod[W][H] Push a class method reference onto argument stack

Properties

Property functions
IrisGetProperty Obtain the value for a property. (Calls into InterSystems IRIS).
IrisSetProperty Store the value for a property. (Calls into InterSystems IRIS).
IrisPushProperty[W][H] Push a property name onto argument stack

Managing Globals

These functions call into InterSystems IRIS to manipulate globals. Functions are provided to push globals onto the argument stack.

Functions for managing globals
IrisGlobalGet Obtains the value of the global reference defined by IrisPushGlobal[W][H] and any subscripts. The node value is pushed onto the argument stack.
IrisGlobalGetBinary Obtains the value of the global reference like IrisGlobalGet, and also tests to make sure that the result is a binary string that will fit in the provided buffer.
IrisGlobalSet Stores the value of the global reference. The node value must be pushed onto the argument stack before this call.
IrisGlobalData Performs a $Data on the specified global.
IrisGlobalIncrement Performs a $Increment and returns the result on top of the stack.
IrisGlobalKill Performs a ZKILL on a global node or tree.
IrisGlobalOrder Performs a $Order on the specified global.
IrisGlobalQuery Performs a $Query on the specified global.
IrisGlobalRelease Releases ownership of a retained global buffer, if one exists.
IrisPushGlobal[W][H] Pushes a global name onto argument stack
IrisPushGlobalX[W][H] Pushes an extended global name onto argument stack

Managing Strings

These functions translate strings from one form to another, and push or pop string arguments. These string functions may be used for both standard strings and legacy short strings. Functions are provided for local 8-bit encoding, 2–byte Unicode, and 4–byte Unicode.

String functions
IrisCvtExStrInA[W][H] Translates a string with specified external character set encoding to the character string encoding used internally by InterSystems IRIS.
IrisCvtExStrOutA[W][H] Translates a string from the character string encoding used internally in InterSystems IRIS to a string with the specified external character set encoding.
IrisExStrKill Releases the storage associated with a string.
IrisExStrNew[W][H] Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.
IrisPopExStr[W][H] Pops a value off argument stack and converts it to a string of the desired type.
IrisPushExStr[W][H] Pushes a string onto the argument stack

Managing Other Datatypes

These functions are used to push and pop argument values with datatypes such as int, double, $list, or pointer, and to return the position of specified bit values within a bitstring.

Other datatype functions
IrisPushInt Push an integer onto argument stack
IrisPopInt Pop a value off argument stack and convert it to an integer
IrisPushInt64 Push a 64–bit (long long) value onto argument stack
IrisPopInt64 Pop a value off argument stack and convert it to a 64–bit (long long) value
IrisPushDbl Push a double onto argument stack
IrisPushIEEEDbl Push an IEEE double onto argument stack.
IrisPopDbl Pops value off argument stack and converts it to a double
IrisPushList Translates and pushes a $LIST object onto argument stack
IrisPopList Pops a $LIST object off argument stack and translates it
IrisPushPtr Pushes a pointer value onto argument stack
IrisPopPtr Pops a pointer value off argument stack
IrisPushUndef Pushes an Undefined value that is interpreted as an omitted function argument.
IrisBitFind[B] Returns the position of specified bit values within a bitstring. Similar to InterSystems IRIS $BITFIND.
FeedbackOpens in a new tab