Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / Application Development / Using the Callin API / Callin Function Reference
Previous section   

Callin Function Reference

This reference chapter contains detailed descriptions of all InterSystems Callin functions, arranged in alphabetical order. For an introduction to the Callin functions organized by function, see Using the Callin Functions.
Note:
InterSystems Callin functions that operate on strings have both 8-bit and Unicode versions. These functions use a suffix character to indicate the type of string that they handle:
  • Names with an “A” suffix or no suffix at all (for example, IrisEvalA or IrisPopExStr) are versions for 8-bit character strings.
  • Names with a “W” suffix (for example, IrisEvalW or IrisPopExStrW) are versions for Unicode character strings on platforms that use 2–byte Unicode characters.
  • Names with an “H” suffix (for example, IrisEvalH or IrisPopExStrH) are versions for Unicode character strings on platforms that use 4–byte Unicode characters.
For convenience, the different versions of each function are listed together here. For example, IrisEvalA[W][H] or IrisPopExStr[W][H] .

Alphabetical Function List

This section contains an alphabetical list of all Callin functions with a brief description of each function and links to detailed descriptions.
  • IrisAbort — Tells InterSystems IRIS™ to cancel the current request being processed on the InterSystems IRIS side, when it is convenient to do so.
  • IrisAcquireLock — Executes an InterSystems IRIS LOCK command. The lock reference should already be set up with IrisPushLockX[W][H].
  • IrisChangePasswordA[W][H] — Changes the user's password if InterSystems authentication is used (not valid for other forms of authentication).
  • IrisBitFind[B] — Returns the position of specified bit values within a bitstring (similar to InterSystems IRIS $BITFIND).
  • IrisCloseOref — Decrements the system reference counter for an OREF.
  • IrisContext — Returns true if there is a request currently being processed on the InterSystems IRIS side of the connection when using an external Callin program.
  • IrisConvert — Converts the value returned by IrisEvalA[W][H] into proper format and places in address specified in its return value.
  • IrisCtrl — Determines whether or not InterSystems IRIS ignores CTRL-C.
  • IrisCvtExStrInA[W][H] — Translates a string with specified external character set encoding to the local 8-bit character string encoding used internally only in 8-bit versions of InterSystems IRIS.
  • IrisCvtExStrOutA[W][H] — Translates a string from the local 8-bit character string encoding used internally in the InterSystems IRIS 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of InterSystems IRIS.)
  • IrisCvtInA[W][H] — Translates string with specified external character set encoding to the local 8-bit character string encoding (used internally only in 8-bit versions of InterSystems IRIS) or the Unicode character string encoding (used internally in Unicode versions of InterSystems IRIS).
  • IrisCvtOutA[W][H] — Translates a string from the local 8-bit character string encoding used internally in the InterSystems IRIS 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of InterSystems IRIS.)
  • IrisDoFun — Performs a routine call (special case).
  • IrisDoRtn — Performs a routine call.
  • IrisEnd — Terminates an InterSystems IRIS process. If there is a broken connection, it also performs clean-up operations.
  • IrisEndAll — Disconnects all Callin threads and waits until they terminate.
  • 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] — Translates an integer error code into an InterSystems IRIS error string.
  • IrisEvalA[W][H] — Evaluates a string as if it were an InterSystems IRIS expression and places the return value in memory for further processing by IrisType and IrisConvert.
  • IrisExecuteA[W][H] — Executes a command string as if it were typed in the Terminal.
  • IrisExStrKill — Releases the storage associated with an EXSTR 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.
  • IrisExtFun — Performs an extrinsic function call where the return value is pushed onto the argument stack.
  • IrisGetProperty — Obtains the value of the property defined by IrisPushProperty[W][H]. The value is pushed onto the argument stack.
  • IrisGlobalData — Performs a $Data on the specified global.
  • 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.
  • 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 — Release ownership of a retained global buffer, if one exists.
  • IrisGlobalSet — Stores the value of the global reference defined by IrisPushGlobal[W][H] and any subscripts. The node value must be pushed onto the argument stack before this call.
  • IrisIncrementCountOref — Increments the system reference counter for an OREF.
  • IrisInvokeClassMethod — Executes the class method call defined by IrisPushClassMethod[W][H] and any arguments. The return value is pushed onto the argument stack.
  • IrisInvokeMethod — Executes the instance method call defined by IrisPushMethod[W][H] and any arguments pushed onto the argument stack.
  • IrisOflush — Flushes any pending output.
  • IrisPop — Pops a value off argument stack.
  • IrisPopCvtW[H] — Pops a local 8-bit string off argument stack and translates it to Unicode. Identical to IrisPopStr[W][H] for Unicode versions.
  • IrisPopDbl — Pops a value off argument stack and converts it to a double.
  • IrisPopExStr[W][H] — Pops a value off argument stack and converts it to a string.
  • IrisPopExStrCvtW[H] — Pops a value off argument stack and converts it to a long Unicode string.
  • IrisPopInt — Pops a value off argument stack and converts it to an integer.
  • IrisPopInt64 — Pops a value off argument stack and converts it to a 64-bit (long long) number.
  • IrisPopList — Pops a $LIST object off argument stack and converts it.
  • IrisPopOref — Pops an OREF off argument stack.
  • IrisPopPtr — Pops a pointer off argument stack in internal format.
  • IrisPopStr[W][H] — Pops a value off argument stack and converts it to a string.
  • IrisPromptA[W][H] — Returns a string that would be the Terminal.
  • IrisPushClassMethod[W][H] — Pushes a class method reference onto the argument stack.
  • IrisPushCvtW[H] — Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to IrisPushStr[W][H] for Unicode versions.
  • IrisPushDbl — Pushes a double onto the argument stack.
  • IrisPushExStr[W][H] — Pushes a string onto the argument stack.
  • IrisPushExStrCvtW[H] — Converts a Unicode string to local 8–bit encoding and pushes it onto the argument stack.
  • IrisPushFunc[W][H] — Pushes an extrinsic function reference onto the argument stack.
  • IrisPushFuncX[W][H] — Pushes an extended extrinsic function reference onto the argument stack.
  • IrisPushGlobal[W][H] — Pushes a global reference onto the argument stack.
  • IrisPushGlobalX[W][H] — Pushes an extended global reference onto the argument stack.
  • IrisPushIEEEDbl — Pushes an IEEE double onto the argument stack.
  • IrisPushInt — Pushes an integer onto the argument stack.
  • IrisPushInt64 — Pushes a 64-bit (long long) number onto the argument stack.
  • IrisPushList — Converts a $LIST object and pushes it onto the argument stack.
  • 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.
  • IrisPushMethod[W][H] — Pushes an instance method reference onto the argument stack.
  • IrisPushOref — Pushes an OREF onto the argument stack.
  • IrisPushProperty[W][H] — Pushes a property reference onto the argument stack.
  • IrisPushPtr — Pushes a pointer onto the argument stack in internal format.
  • IrisPushRtn[W][H] — Pushes a routine reference onto the argument stack.
  • IrisPushRtnX[W][H] — Pushes an extended routine reference onto the argument stack.
  • IrisPushStr[W][H] — Pushes a byte string onto the argument stack.
  • IrisPushUndef — pushes an Undefined value that is interpreted as an omitted function argument.
  • 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. This command will only release one incremental lock at a time.
  • IrisSecureStartA[W][H] — Calls into InterSystems IRIS to set up a process.
  • IrisSetDir — Dynamically sets the name of the manager's directory at runtime.
  • IrisSetProperty — Stores the value of the property defined by IrisPushProperty[W][H].
  • IrisSignal — Passes on signals caught by user's program to InterSystems IRIS.
  • IrisSPCReceive — Receive single-process-communication message.
  • IrisSPCSend — Send a single-process-communication message.
  • IrisStartA[W][H] — Calls into InterSystems IRIS to set up an InterSystems IRIS process.
  • IrisTCommit — Executes an InterSystems IRIS TCommit command.
  • IrisTLevel — Returns the current nesting level ($TLEVEL) for transaction processing.
  • IrisTRollback — Executes an InterSystems IRIS TRollback command.
  • IrisTStart — Executes an InterSystems IRIS TStart command.
  • IrisType — Returns the native type of the item returned by IrisEvalA[W][H], as the function value.
  • IrisUnPop — Restores the stack entry from IrisPop.

IrisAbort

int IrisAbort(unsigned long type)
Arguments
type Either of the following predefined values that specify how the termination occurs:
  • IRIS_CTRLC — Interrupts the InterSystems IRIS processing as if a CTRL-C had been processed (regardless of whether CTRL-C has been enabled with IrisCtrl). A connection to InterSystems IRIS remains.
  • IRIS_RESJOB — Terminates the Callin connection. You must then call IrisEnd and then IrisStart to reconnect to InterSystems IRIS.
Description
Tells InterSystems IRIS to cancel the current request being processed on the InterSystems IRIS side, when it is convenient to do so. This function is for use if you detect some critical event in an AST (asynchronous trap) or thread running on the Callin side. (You can use IrisContext to determine if there is an InterSystems IRIS request currently being processed.) Note that this only applies to Callin programs that use an AST or separate thread.
Return Values for IrisAbort
IRIS_BADARG The termination type is invalid.
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_NOTINCACHE The Callin partner is not in InterSystems IRIS at this time.
IRIS_SUCCESS Connection formed.
Example
rc = IrisAbort(IRIS_CTRLC);

IrisAcquireLock

int IrisAcquireLock(int nsub, int flg, int tout, int * rval)
Arguments
nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of IRIS_INCREMENTAL_LOCK and IRIS_SHARED_LOCK.
tout Number of seconds to wait for the lock command to complete. Negative for no timeout. 0 means return immediately if the lock is not available, although a minimum timeout may be applied if the lock is mapped to a remote system.
rval Optional pointer to an int return value: success = 1, failure = 0.
Description
Executes an InterSystems IRIS LOCK command. The lock reference should already be set up with IrisPushLock.
Return Values for IrisAcquireLock
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Successfully called the LOCK command (but the rval parameter must be examined to determine if the lock succeeded).
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERARGSTACK Argument stack overflow.

IrisBitFind

int IrisBitFind(int strlen, unsigned short *bitstr, int newlen, int srch, int revflg)
Arguments
strlen Data length of the bitstring.
bitstr Pointer to a Unicode bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:
1 — Search forward (left to right) from the position indicated by newlen.
0 — Search backward from the position indicated by newlen.
Description
Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.
This function is similar to InterSystems IRIS $BITFIND (also see “General Information on Bitstring Functions”).
Return Values for IrisBitFind
IRIS_SUCCESS The operation was successful.

IrisBitFindB

int IrisBitFindB(int strlen, unsigned char *bitstr, int newlen, int srch, int revflg)
Arguments
strlen Data length of the bitstring.
bitstr Pointer to a bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position.
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:
1 — Search forward (left to right) from the position indicated by newlen.
0 — Search backward from the position indicated by newlen.
Description
Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.
This function is similar to InterSystems IRIS $BITFIND (also see “General Information on Bitstring Functions”).
Return Values for IrisBitFindB
IRIS_SUCCESS The operation was successful.

IrisChangePasswordA

int IrisChangePasswordA(IRIS_ASTRP username, IRIS_ASTRP oldpassword, IRIS_ASTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordA
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.

IrisChangePasswordH

int IrisChangePasswordH(IRISHSTRP username, IRISHSTRP oldpassword, IRISHSTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordH
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.

IrisChangePasswordW

int IrisChangePasswordW(IRISWSTRP username, IRISWSTRP oldpassword, IRISWSTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordW
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.

IrisCloseOref

int IrisCloseOref(unsigned int oref)
Arguments
oref Object reference.
Description
Decrements the system reference counter for an OREF.
Return Values for IrisCloseOref
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.

IrisContext

int IrisContext()
Description
Returns an integer as the function value.
If you are using an external Callin program (as opposed to a module that was called from a $ZF function) and your program employs an AST or separate thread, then IrisContext tells you if there is a request currently being processed on the InterSystems IRIS side of the connection. This information is needed to decide if you must return to InterSystems IRIS to allow processing to complete.
Return Values for IrisContext
-1 Created in InterSystems IRIS via a $ZF callback.
0 No connection or not in InterSystems IRIS at the moment.
1 In InterSystems IRIS via an external (i.e., not $ZF) connection. An asynchronous trap (AST), such as an exit-handler, would need to return to InterSystems IRIS to allow processing to complete.
Note:
The information about whether you are in a $ZF function from a program or an AST is needed because, if you are in an AST, then you need to return to InterSystems IRIS to allow processing to complete.
Example
rc = IrisContext();

IrisConvert

int IrisConvert(unsigned long type, void * rbuf)
Arguments
type The #define'd type, with valid values listed below.
rbuf Address of a data area of the proper size for the data type. If the type is IRIS_ASTRING, rbuf should be the address of a IRIS_ASTR structure that will contain the result, and the len element in the structure should be filled in to represent the maximum size of the string to be returned (in characters). Similarly, if the type is IRIS_WSTRING, rbuf should be the address of a IRISWSTR structure whose len element has been filled in to represent the maximum size (in characters).
Description
Converts the value returned by IrisEval into proper format and places in address specified in its return value (listed below as rbuf).
Valid values of type are:
  • IRIS_ASTRING — 8-bit character string.
  • IRIS_CHAR — 8-bit signed integer.
  • IRIS_DOUBLE — 64-bit floating point.
  • IRIS_FLOAT — 32-bit floating point.
  • IRIS_INT — 32-bit signed integer.
  • IRIS_INT2 — 16-bit signed integer.
  • IRIS_INT4 — 32-bit signed integer.
  • IRIS_INT8 — 64-bit signed integer.
  • IRIS_UCHAR — 8-bit unsigned integer.
  • IRIS_UINT — 32-bit unsigned integer.
  • IRIS_UINT2 — 16-bit unsigned integer.
  • IRIS_UINT4 — 32-bit unsigned integer.
  • IRIS_UINT8 — 64-bit unsigned integer.
  • IRIS_WSTRING — Unicode character string.
Return Values for IrisConvert
IRIS_BADARG Type is invalid.
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE An unexpected error has occurred.
IRIS_NOCON No connection has been established.
IRIS_NORES No result whose type can be returned (no call to IrisEvalA preceded this call).
IRIS_RETTRUNC Success, but the type IRIS_ASTRING, IRIS_INT8, IRIS_UINT8 and IRIS_WSTRING resulted in a value that would not fit in the space allocated in retval. For IRIS_INT8 and IRIS_UINT8, this means that the expression resulted in a floating point number that could not be normalized to fit within 64 bits.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS Value returned by last IrisEval converted successfully.
Note:
InterSystems IRIS may perform division when calculating the return value for floating point types, IRIS_FLOAT and IRIS_DOUBLE, which have decimal parts (including negative exponents), as well as the 64-bit integer types (IRIS_INT8 and IRIS_UINT8). Therefore, the returned result may not be identical in value to the original. IRIS_ASTRING, IRIS_INT8, IRIS_UINT8 and IRIS_WSTRING can return the status IRIS_RETTRUNC.
Example
IRIS_ASTR retval;
/* define variable retval */

retval.len = 20;
/* maximum return length of string */

rc = IrisConvert(IRIS_ASTRING,&retval);

IrisCtrl

int IrisCtrl(unsigned long flags)
Arguments
flags Either of two #define'd values specifying how InterSystems IRIS handles certain keystrokes.
Description
Determines whether or not InterSystems IRIS ignores CTRL-C. flags can have bit state values of
  • IRIS_DISACTRLC — InterSystems IRIS ignores CTRL-C.
  • IRIS_ENABCTRLC — Default if function is not called, unless overridden by a BREAK or an OPEN command. In InterSystems IRIS, CTRL-C generates an <INTERRUPT>.
Return Values for IrisCtrl
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.
Example
rc = IrisCtrl(IRIS_ENABCTRLC);

IrisCvtExStrInA

int IrisCvtExStrInA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the local 8-bit character string encoding used internally.
Return Values for IrisCvtExStrInA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtExStrInW

int IrisCvtExStrInW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the 2–byte Unicode character string encoding used internally in InterSystems IRIS.
Return Values for IrisCvtExStrInW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtExStrInH

int IrisCvtExStrInH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the 4–byte Unicode character string encoding used internally in InterSystems IRIS.
Return Values for IrisCvtExStrInH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtExStrOutA

int IrisCvtExStrOutA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 8-bit character string encoding used internally in an older InterSystems 8-bit product to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtExStrOutW

int IrisCvtExStrOutW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 2–byte Unicode character string encoding used internally in InterSystems IRIS to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtExStrOutH

int IrisCvtExStrOutH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 4–byte Unicode character string encoding used internally in InterSystems IRIS to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtInA

int IrisCvtInA(IRIS_ASTRP src, IRIS_ASTRP tbl, IRIS_ASTRP res)
Arguments
src The string in an external character set encoding to be translated (described using a counted character string buffer). The string should be initialized, for example, by setting the value to the number of blanks representing the maximum number of characters expected as output.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_ASTR variable that will contain the counted 8-bit string result.
Description
Translates string with specified external character set encoding to the local 8-bit character string encoding used internally only in 8-bit versions of InterSystems IRIS.
Return Values for IrisCvtInA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtInW

int IrisCvtInW(IRIS_ASTRP src, IRISWSTRP tbl, IRISWSTRP res)
Arguments
src The string in an external character set encoding to be translated (described using the number of bytes required to hold the Unicode string).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRISWSTR variable that will contain the counted Unicode string result.
Description
Translates string with specified external character set encoding to the Unicode character string encoding used internally in Unicode versions of InterSystems IRIS.
Return Values for IrisCvtInW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtInH

int IrisCvtInH(IRIS_ASTRP src, IRISHSTRP tbl, IRISHSTRP res)
Arguments
src The string in an external character set encoding to be translated (described using the number of bytes required to hold the Unicode string).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRISHSTRP variable that will contain the counted Unicode string result.
Description
Translates string with specified external character set encoding to the Unicode character string encoding used internally in Unicode versions of InterSystems IRIS.
Return Values for IrisCvtInH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtOutA

int IrisCvtOutA(IRIS_ASTRP src, IRIS_ASTRP tbl, IRIS_ASTRP res)
Arguments
src The string in the local 8-bit character string encoding used internally in the InterSystems IRIS 8-bit product (if a NULL pointer is passed, InterSystems IRIS will use the result from the last call to IrisEvalA or IrisEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description
Translates a string from the local 8-bit character string encoding used internally in the InterSystems IRIS 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of InterSystems IRIS.)
Return Values for IrisCvtOutA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtOutW

int IrisCvtOutW(IRISWSTRP src, IRISWSTRP tbl, IRIS_ASTRP res)
Arguments
src The string in the Unicode character string encoding used internally in the InterSystems IRIS Unicode product (if a NULL pointer is passed, InterSystems IRIS will use the result from the last call to IrisEvalA or IrisEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description
Translates a string from the Unicode character string encoding used internally in Unicode versions of InterSystems IRIS to a string with the specified external character set encoding. (This is only available with Unicode versions of InterSystems IRIS.)
Return Values for IrisCvtOutW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisCvtOutH

int IrisCvtOutH(IRISHSTRP src, IRISHSTRP tbl, IRIS_ASTRP res)
Arguments
src The string in the Unicode character string encoding used internally in the InterSystems IRIS Unicode product (if a NULL pointer is passed, InterSystems IRIS will use the result from the last call to IrisEvalA or IrisEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description
Translates a string from the Unicode character string encoding used internally in Unicode versions of InterSystems IRIS to a string with the specified external character set encoding. (This is only available with Unicode versions of InterSystems IRIS.)
Return Values for IrisCvtOutH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.

IrisDoFun

int IrisDoFun(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushRtn[XW]
narg Number of call arguments pushed onto the argument stack. Target must have a (possibly empty) formal parameter list.
Description
Performs a routine call (special case).
Return Values for IrisDoFun
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisDoRtn

int IrisDoRtn(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushRtn[XW]
narg Number of call arguments pushed onto the argument stack. If zero, target must not have a formal parameter list.
Description
Performs a routine call.
Return Values for IrisDoRtn
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisEnd

int IrisEnd()
Description
Terminates an InterSystems IRIS process. If there is a broken connection, it also performs clean-up operations.
Return Values for IrisEnd
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_NOCON No connection has been established.
IRIS_SUCCESS InterSystems IRIS session terminated/cleaned up.
IrisEnd can also return any of the InterSystems IRIS error codes.
Example
rc = IrisEnd();

IrisEndAll

int IrisEndAll()
Description
Disconnects all threads in a threaded Callin environment, then schedules the threads for termination and waits until they are done.
Return Values for IrisEndAll
IRIS_SUCCESS InterSystems IRIS session terminated/cleaned up.
Example
rc = IrisEndAll();

IrisErrorA

int IrisErrorA(IRIS_ASTRP msg, IRIS_ASTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp An integer that specifies the offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorA
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR errmsg;
IRIS_ASTR srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorA(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

IrisErrorH

int IrisErrorH(IRISHSTRP msg, IRISHSTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorH
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRISHSTRP errmsg;
IRISHSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorH(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

IrisErrorW

int IrisErrorW(IRISWSTRP msg, IRISWSTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorW
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRISWSTRP errmsg;
IRISWSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorW(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

IrisErrxlateA

int IrisErrxlateA(int code, IRIS_ASTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRIS_ASTR variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateA
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateA(IRIS_ERSTORE,&retval);

IrisErrxlateH

int IrisErrxlateH(int code, IRISHSTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRISHSTRP variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateH
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRISHSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateH(IRIS_ERSTORE,&retval);

IrisErrxlateW

int IrisErrxlateW(int code, IRISWSTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRISWSTR variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateW
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRISWSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateW(IRIS_ERSTORE,&retval);

IrisEvalA

Variants: IrisEvalW, IrisEvalH
int IrisEvalA(IRIS_ASTRP volatile expr)
Arguments
expr The address of a IRIS_ASTR variable.
Description
Evaluates a string as if it were an InterSystems IRIS expression and places the return value in memory for further processing by IrisType and IrisConvert.
If IrisEvalA completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalA.
Caution:
The next call to IrisEvalA, IrisExecuteA, or IrisEnd will overwrite the existing return value.
Return Values for IrisEvalA
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either InterSystems IRIS generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String evaluated successfully.
IrisEvalA can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRIS_ASTR retval;
IRIS_ASTR expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = IrisEvalA(&expr);
if (rc == IRIS_SUCCESS)
    rc = IrisConvert(IRIS_ASTRING,&retval);

IrisEvalH

Variants: IrisEvalA, IrisEvalW
int IrisEvalH(IRISHSTRP volatile expr)
Arguments
expr The address of a IRISHSTRP variable.
Description
Evaluates a string as if it were an InterSystems IRIS expression and places the return value in memory for further processing by IrisType and IrisConvert.
If IrisEvalH completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalA.
Caution:
The next call to IrisEvalH, IrisExecuteH, or IrisEnd will overwrite the existing return value.
Return Values for IrisEvalH
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRISW_ERSYSTEM Either InterSystems IRIS generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String evaluated successfully.
IrisEvalH can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRISHSTRP retval;
IRISHSTRP expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = IrisEvalH(&expr);
if (rc == IRIS_SUCCESS)
    rc = IrisConvert(ING,&retval);

IrisEvalW

Variants: IrisEvalA, IrisEvalH
int IrisEvalW(IRISWSTRP volatile expr)
Arguments
expr The address of a IRISWSTR variable.
Description
Evaluates a string as if it were an InterSystems IRIS expression and places the return value in memory for further processing by IrisType and IrisConvert.
If IrisEvalW completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalA.
Caution:
The next call to IrisEvalW, IrisExecuteW, or IrisEnd will overwrite the existing return value.
Return Values for IrisEvalW
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRISHW_ERSYSTEM Either InterSystems IRIS generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String evaluated successfully.
IrisEvalW can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRISWSTR retval;
IRISWSTR expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = IrisEvalW(&expr);
if (rc == IRIS_SUCCESS)
    rc = IrisConvert(ING,&retval);

IrisExecuteA

int IrisExecuteA(IRIS_ASTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
Caution:
The next call to IrisEvalA, IrisExecuteA, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteA
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteA can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRIS_ASTR command;
sprintf(command.str,"ZN \"USER\""); /* changes namespace */
command.len = strlen(command.str);
rc = IrisExecuteA(&command);

IrisExecuteH

int IrisExecuteH(IRISHSTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
If IrisExecuteH completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalH.
Caution:
The next call to IrisEvalH, IrisExecuteH, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteH
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteH can also return any of the InterSystems IRIS error codes.
Example
int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
IRISHSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = IrisExecuteH(pcommand);

IrisExecuteW

int IrisExecuteW(IRISWSTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
If IrisExecuteW completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalW.
Caution:
The next call to IrisEvalW, IrisExecuteW, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteW
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteW can also return any of the InterSystems IRIS error codes.
Example
int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
IRISWSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = IrisExecuteW(pcommand);

IrisExStrKill

int IrisExStrKill(IRIS_EXSTRP obj)
Arguments
obj Pointer to the string.
Description
Releases the storage associated with an EXSTR string.
Return Values for IrisExStrKill
IRIS_ERUNIMPLEMENTED String is undefined.
IRIS_SUCCESS String storage has been released.

IrisExStrNew

unsigned char * IrisExStrNew(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 8–bit characters to allocate.
Description
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.
Return Values for IrisExStrNew
Returns a pointer to the allocated string, or NULL if no string was allocated.

IrisExStrNewW

unsigned short * IrisExStrNewW(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 2–byte characters to allocate.
Description
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.
Return Values for IrisExStrNewW
Returns a pointer to the allocated string, or NULL if no string was allocated.

IrisExStrNewH

unsigned short * IrisExStrNewH(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 4–byte characters to allocate.
Description
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.
Return Values for IrisExStrNewH
Returns a pointer to the allocated string, or NULL if no string was allocated.

IrisExtFun

int IrisExtFun(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushFunc[XW].
narg Number of call arguments pushed onto the argument stack.
Description
Performs an extrinsic function call where the return value is pushed onto the argument stack.
Return Values for IrisExtFun
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGetProperty

int IrisGetProperty()
Description
Obtains the value of the property defined by IrisPushProperty. The value is pushed onto the argument stack.
Return Values for IrisGetProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalData

int IrisGlobalData(int narg, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Data on the specified global.
Return Values for IrisGlobalData
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalGet

int IrisGlobalGet(int narg, int flag)
Arguments
narg Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns IRIS_ERUNDEF
  • 1 — returns IRIS_SUCCESS but the return value is an empty string.
Description
Obtains the value of the global reference defined by IrisPushGlobal and any subscripts. The node value is pushed onto the argument stack.
Return Values for IrisGlobalGet
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalGetBinary

int IrisGlobalGetBinary(int numsub, int flag, int *plen, Callin_char_t **pbuf)
Arguments
numsub Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns IRIS_ERUNDEF
  • 1 — returns IRIS_SUCCESS but the return value is an empty string.
plen Pointer to length of buffer.
pbuf Pointer to buffer pointer.
Description
Obtains the value of the global reference defined by IrisPushGlobal[W][H] and any subscripts, and also tests to make sure that the result is a binary string that will fit in the provided buffer. The node value is pushed onto the argument stack.
Return Values for IrisGlobalGetBinary
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalIncrement

int IrisGlobalIncrement(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Performs a $INCREMENT and returns the result on top of the stack.
Return Values for IrisGlobalIncrement
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_ERMAXINCR MAXINCREMENT system error
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalKill

int IrisGlobalKill(int narg, int nodeonly)
Arguments
narg Number of call arguments pushed onto the argument stack.
nodeonly A value of 1 indicates that only the specified node should be killed. When the value is 0, the entire specified global tree is killed.
Description
Performs a ZKILL on a global node or tree.
Return Values for IrisGlobalKill
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalOrder

int IrisGlobalOrder(int narg, int dir, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Order is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Order on the specified global.
Return Values for IrisGlobalOrder
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalQuery

int IrisGlobalQuery(int narg, int dir, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Query is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Query on the specified global.
Return Values for IrisGlobalQuery
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisGlobalRelease

int IrisGlobalRelease( )
Description
Release ownership of a retained global buffer, if one exists.
Return Values for IrisGlobalRelease
IRIS_SUCCESS The operation was successful.

IrisGlobalSet

int IrisGlobalSet(int narg)
Arguments
narg Number of subscript expressions pushed onto the argument stack.
Description
Stores the value of the global reference defined by IrisPushGlobal and any subscripts. The node value must be pushed onto the argument stack before this call.
Return Values for IrisGlobalSet
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisIncrementCountOref

int IrisIncrementCountOref(unsigned int oref)
Arguments
oref Object reference.
Description
Increments the system reference counter for an OREF.
Return Values for IrisIncrementCountOref
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.

IrisInvokeClassMethod

int IrisInvokeClassMethod(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Executes the class method call defined by IrisPushClassMethod[W] and any arguments. The return value is pushed onto the argument stack.
Return Values for IrisInvokeClassMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisInvokeMethod

int IrisInvokeMethod(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Executes the instance method call defined by IrisPushMethod[W] and any arguments pushed onto the argument stack.
Return Values for IrisInvokeMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisOflush

int IrisOflush()
Description
Flushes any pending output.
Return Values for IrisOflush
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.

IrisPop

int IrisPop(void ** arg)
Arguments
arg Pointer to argument stack entry.
Description
Pops a value off argument stack.
Return Values for IrisPop
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.

IrisPopCvtW

Variants: IrisPopCvtH
int IrisPopCvtW(int * lenp, unsigned short ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Deprecated: The long string function IrisPopExStrCvtW should be used for all strings.
Pops a local 8-bit string off argument stack and translates it to 2–byte Unicode. Identical to IrisPopStrW in Unicode environments.
Return Values for IrisPopCvtW
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopCvtH

Variants: IrisPopCvtW
int IrisPopCvtH(int * lenp, wchar_t ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a local 8-bit string off argument stack and translates it to 4–byte Unicode. Identical to IrisPopStrH in Unicode environments.
Return Values for IrisPopCvtH
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopDbl

int IrisPopDbl(double * nump)
Arguments
nump Pointer to double value.
Description
Pops a value off argument stack and converts it to a double.
Return Values for IrisPopDbl
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.

IrisPopExStr

int IrisPopExStr(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a string in local 8–bit encoding.
Return Values for IrisPopExStr
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

IrisPopExStrW

int IrisPopExStrW(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a 2–byte Unicode string.
Return Values for IrisPopExStrW
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

IrisPopExStrH

int IrisPopExStrH(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a 4–byte Unicode string.
Return Values for IrisPopExStrH
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

IrisPopExStrCvtW

int IrisPopExStrCvtW(IRIS_EXSTRP sstr)
Arguments
sstr Pointer to long string pointer.
Description
Pops a local 8-bit string off the argument stack and translates it to a 2–byte Unicode string. On Unicode systems, this is the same as IrisPopExStrW.
Return Values for IrisPopExStrCvtW
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopExStrCvtH

int IrisPopExStrCvtW(IRIS_EXSTRP sstr)
Arguments
sstr Pointer to long string pointer.
Description
Pops a local 8-bit string off argument stack and translates it to a 4–byte Unicode string. On Unicode systems, this is the same as IrisPopExStrH.
Return Values for IrisPopExStrCvtH
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopInt

int IrisPopInt(int* nump)
Arguments
nump Pointer to integer value.
Description
Pops a value off argument stack and converts it to an integer.
Return Values for IrisPopInt
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.

IrisPopInt64

int IrisPopInt64(long long * nump)
Arguments
nump Pointer to long long value.
Description
Pops a value off argument stack and converts it to a 64–bit (long long) value.
Return Values for IrisPopInt64
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.

IrisPopList

int IrisPopList(int * lenp, Callin_char_t ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a $LIST object off argument stack and converts it.
Return Values for IrisPopList
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopOref

int IrisPopOref(unsigned int * orefp)
Arguments
orefp Pointer to OREF value.
Description
Pops an OREF off argument stack.
Return Values for IrisPopOref
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERNOOREF Result is not an OREF.
IRIS_SUCCESS The operation was successful.

IrisPopPtr

int IrisPopPtr(void ** ptrp)
Arguments
ptrp Pointer to generic pointer.
Description
Pops a pointer off argument stack in internal format.
Return Values for IrisPopPtr
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_BADARG The entry is not a valid pointer.
IRIS_SUCCESS The operation was successful.

IrisPopStr

int IrisPopStr(int * lenp, Callin_char_t ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a value off argument stack and converts it to a string.
Return Values for IrisPopStr
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.

IrisPopStrW

int IrisPopStrW(int * lenp, unsigned short ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a value off argument stack and converts it to a 2-byte Unicode string.
Return Values for IrisPopStrW
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPopStrH

int IrisPopStrH(int * lenp, wchar_t ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a value off argument stack and converts it to a 4-byte Unicode string.
Return Values for IrisPopStrH
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPromptA

int IrisPromptA(IRIS_ASTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptA
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE An unexpected error has occurred.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR retval;      /* define variable retval */
retval.len = 5;         /* maximum return length of string */
rc = IrisPromptA(&retval);

IrisPromptH

int IrisPromptH(IRISHSTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptH
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE Request failed.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRISHSTRP retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = IrisPromptH( &retval);

IrisPromptW

int IrisPromptW(IRISWSTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptW
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE Request failed.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRISWSTR retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = IrisConvertW( &retval);

IrisPushClassMethod

int IrisPushClassMethod(int clen, const Callin_char_t * cptr,
                         int mlen, const Callin_char_t * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg
Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a class method reference onto the argument stack.
Return Values for IrisPushClassMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.

IrisPushClassMethodH

int IrisPushClassMethodH(int clen, const wchar_t * cptr,
                          int mlen, const wchar_t * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 4-byte Unicode class method reference onto the argument stack.
Return Values for IrisPushClassMethodH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushClassMethodW

int IrisPushClassMethodW(int clen, const unsigned short * cptr,
                          int mlen, const unsigned short * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 2-byte Unicode class method reference onto the argument stack.
Return Values for IrisPushClassMethodW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushCvtW

Variants: IrisPushCvtH
int IrisPushCvtW(int len, const unsigned short * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Deprecated: The long string function IrisPushExStrCvtW should be used for all strings.
Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to IrisPushStrW for Unicode versions.
Return Values for IrisPushCvtW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating the string.

IrisPushCvtH

Variants: IrisPushCvtW
int IrisPushCvtH(int len, const wchar_t * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to IrisPushStrH for Unicode versions.
Return Values for IrisPushCvtH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating the string.

IrisPushDbl

int IrisPushDbl(double num)
Arguments
num Double value.
Description
Pushes a double onto the argument stack.
Return Values for IrisPushDbl
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExStr

int IrisPushExStr(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a string onto the argument stack.
Return Values for IrisPushExStr
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExStrW

int IrisPushExStrW(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a Unicode string onto the argument stack.
Return Values for IrisPushExStrW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExStrH

int IrisPushExStrH(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a 4–byte Unicode string onto the argument stack.
Return Values for IrisPushExStrH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExStrCvtW

int IrisPushExStrCvtW(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Translates a Unicode string to local 8-bit and pushes it onto the argument stack.
Return Values for IrisPushExStrCvtW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating the string.

IrisPushExStrCvtH

int IrisPushExStrCvtH(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Translates a 4–byte Unicode string to local 8-bit and pushes it onto the argument stack.
Return Values for IrisPushExStrCvtH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating the string.

IrisPushFunc

int IrisPushFunc(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                  int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tagptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes an extrinsic function reference onto the argument stack.
Return Values for IrisPushFunc
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushFuncH

int IrisPushFuncH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                   int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4-byte Unicode extrinsic function reference onto the argument stack.
Return Values for IrisPushFuncH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushFuncW

int IrisPushFuncW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                   int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2-byte Unicode extrinsic function reference onto the argument stack.
Return Values for IrisPushFuncW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushFuncX

int IrisPushFuncX(unsigned int * rflag, int tlen, const Callin_char_t * tptr, int off,
                   int elen, const Callin_char_t * eptr,
                   int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes an extended extrinsic function reference onto the argument stack.
Return Values for IrisPushFuncX
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushFuncXH

int IrisPushFuncXH(unsigned int * rflag, int tlen, const wchar_t * tptr, int off,
                    int elen, const wchar_t * eptr, int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4-byte Unicode extended function routine reference onto the argument stack.
Return Values for IrisPushFuncXH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushFuncXW

int IrisPushFuncXW(unsigned int * rflag, int tlen, const unsigned short * tptr, int off,
                    int elen, const unsigned short * eptr,
                    int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2-byte Unicode extended function routine reference onto the argument stack.
Return Values for IrisPushFuncXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushGlobal

int IrisPushGlobal(int nlen, const Callin_char_t * nptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
Description
Pushes a global reference onto the argument stack.
Return Values for IrisPushGlobal
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushGlobalH

intIrisPushGlobalH(int nlen, const wchar_t * nptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
Description
Pushes a 4-byte Unicode global reference onto the argument stack.
Return Values for IrisPushGlobalH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushGlobalW

int IrisPushGlobalW(int nlen, const unsigned short * nptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
Description
Pushes a 2-byte Unicode global reference onto the argument stack.
Return Values for IrisPushGlobalW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushGlobalX

int IrisPushGlobalX(int nlen, const Callin_char_t * nptr,
                     int elen, const Callin_char_t * eptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes an extended global reference onto the argument stack.
Return Values for IrisPushGlobalX
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushGlobalXH

int IrisPushGlobalXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4-byte Unicode extended global reference onto the argument stack.
Return Values for IrisPushGlobalXH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTAC String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushGlobalXW

int IrisPushGlobalXW(int nlen, const unsigned short * nptr,
                      int elen, const unsigned short * eptr)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2-byte Unicode extended global reference onto the argument stack.
Return Values for IrisPushGlobalXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTAC String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushIEEEDbl

int IrisPushIEEEDbl(double num)
Arguments
num Double value.
Description
Pushes an IEEE double onto the argument stack.
Return Values for IrisPushIEEEDbl
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushInt

int IrisPushInt(int num)
Arguments
num Integer value.
Description
Pushes an integer onto the argument stack.
Return Values for IrisPushInt
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushInt64

int IrisPushInt64(long long num)
Arguments
num long long value.
Description
Pushes a 64–bit (long long) value onto the argument stack.
Return Values for IrisPushInt64
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushList

int IrisPushList(int len, const Callin_char_t * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Converts a $LIST object and pushes it onto the argument stack.
Return Values for IrisPushList
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a string element.

IrisPushLock

int IrisPushLock(int nlen, const Callin_char_t * nptr)
Arguments
nlen Length (in bytes) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLock
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushLockH

int IrisPushLockH(int nlen, const wchar_t * nptr)
Arguments
nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLockH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushLockW

int IrisPushLockW(int nlen, const unsigned short * nptr)
Arguments
nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLockW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushLockX

int IrisPushLockX(int nlen, const Callin_char_t * nptr, int elen, const Callin_char_t * eptr)
Arguments
nlen Length (number of 8–bit characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockX
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushLockXH

int IrisPushLockXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Arguments
nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockXH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushLockXW

int IrisPushLockXW(int nlen, const unsigned short * nptr, int elen, const unsigned short * eptr)
Arguments
nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushMethod

int IrisPushMethod(unsigned int oref, int mlen, const Callin_char_t * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes an instance method reference onto the argument stack.
Return Values for IrisPushMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.

IrisPushMethodH

int IrisPushMethodH(unsigned int oref, int mlen, const wchar_t * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 4-byte Unicode instance method reference onto the argument stack.
Return Values for IrisPushMethodH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushMethodW

int IrisPushMethodW(unsigned int oref, int mlen, const unsigned short * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 2-byte Unicode instance method reference onto the argument stack.
Return Values for IrisPushMethodW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushOref

int IrisPushOref(unsigned int oref)
Arguments
oref Object reference.
Description
Pushes an OREF onto the argument stack.
Return Values for IrisPushOref
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.

IrisPushProperty

int IrisPushProperty(unsigned int oref, int plen, const Callin_char_t * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a property reference onto the argument stack.
Return Values for IrisPushProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.

IrisPushPropertyH

int IrisPushPropertyH(unsigned int oref, int plen, const wchar_t * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a 4-byte Unicode property reference onto the argument stack.
Return Values for IrisPushPropertyH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushPropertyW

int IrisPushPropertyW(unsigned int oref, int plen, const unsigned short * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a 2-byte Unicode property reference onto the argument stack.
Return Values for IrisPushPropertyW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushPtr

int IrisPushPtr(void * ptr)
Arguments
ptr Generic pointer.
Description
Pushes a pointer onto the argument stack in internal format.
Return Values for IrisPushPtr
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushRtn

int IrisPushRtn(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                 int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a routine reference onto the argument stack. See IrisPushRtnX for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtn
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushRtnH

int IrisPushRtnH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                  int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4–byte Unicode routine reference onto the argument stack. See IrisPushRtnXH for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushRtnW

int IrisPushRtnW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                  int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2–byte Unicode routine reference onto the argument stack. See IrisPushRtnXW for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushRtnX

int IrisPushRtnX(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                  int off, int elen, const Callin_char_t * eptr,
                  int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes an extended routine reference onto the argument stack. See IrisPushRtn for a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnX
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushRtnXH

int IrisPushRtnXH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                   int off, int elen, const wchar_t * eptr,
                   int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4–byte Unicode extended routine reference onto the argument stack. See IrisPushRtnH for a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnXH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushRtnXW

int IrisPushRtnXW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                   int off, int elen, const unsigned short * eptr,
                   int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2–byte Unicode extended routine reference onto the argument stack. See IrisPushRtnW for a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisPushStr

int IrisPushStr(int len, const Callin_char_t * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Pushes a byte string onto the argument stack.
Return Values for IrisPushStr
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushStrW

int IrisPushStrW(int len, const unsigned short * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Pushes a 2-byte Unicode string onto the argument stack.
Return Values for IrisPushStrW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushStrH

int IrisPushStrH(int len, const wchar_t * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Pushes a 4-byte Unicode string onto the argument stack.
Return Values for IrisPushStrH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the InterSystems IRIS engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushUndef

int IrisPushUndef()
Description
Pushes an Undefined value on the argument stack. The value is interpreted as an omitted function argument.
Return Values for IrisPushUndef
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.

IrisReleaseAllLocks

int IrisReleaseAllLocks( )
Description
Performs an argumentless InterSystems IRIS LOCK command to remove all locks currently held by the process.
Return Values for IrisReleaseAllLocks
IRIS_SUCCESS The operation was successful.

IrisReleaseLock

int IrisReleaseLock(int nsub, int flg)
Arguments
nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of IRIS_IMMEDIATE_RELEASE and IRIS_SHARED_LOCK.
Description
Executes an InterSystems IRIS LOCK command to decrement the lock count for the specified lock name. This command will only release one incremental lock at a time.
Return Values for IrisReleaseLock
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Successful lock.

IrisSecureStartA

int IrisSecureStartA(IRIS_ASTRP username, IRIS_ASTRP password, IRIS_ASTRP exename,
                      unsigned long flags, int tout, IRIS_ASTRP prinp, IRIS_ASTRP prout)
Arguments
username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up a process..
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisSecureStartA
IRIS_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
IRIS_ALREADYCON Connection already existed. Returned if you call IrisSecureStartH from a $ZF function.
IRIS_CHANGEPASSWORD Password change required. This return value is only returned if you are using InterSystems authentication.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEnd has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.

IrisSecureStartH

int IrisSecureStartH(IRISHSTRP username, IRISHSTRP password, IRISHSTRP exename,
                      unsigned long flags, int tout, IRISHSTRP prinp, IRISHSTRP prout)
Arguments
username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up a process..
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisSecureStartH
IRIS_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
IRIS_ALREADYCON Connection already existed. Returned if you call IrisSecureStartH from a $ZF function.
IRIS_CHANGEPASSWORD Password change required. This return value is only returned if you are using InterSystems authentication.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEnd has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.

IrisSecureStartW

int IrisSecureStartW(IRISWSTRP username, IRISWSTRP password, IRISWSTRP exename,
                      unsigned long flags, int tout, IRISWSTRP prinp, IRISWSTRP prout)
Arguments
username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up a process..
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisSecureStartW
IRIS_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
IRIS_ALREADYCON Connection already existed. Returned if you call IrisSecureStartH from a $ZF function.
IRIS_CHANGEPASSWORD Password change required. This return value is only returned if you are using InterSystems authentication.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEnd has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.

IrisSetDir

int IrisSetDir(char * dir)
Arguments
dir Pointer to the directory name string.
Description
Dynamically sets the name of the manager's directory (IrisSys\Mgr) at runtime. On Windows, the shared library version of InterSystems IRIS requires the use of this function to identify the managers directory for the installation.
Return Values for IrisSetDir
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.

IrisSetProperty

int IrisSetProperty( )
Description
Stores the value of the property defined by IrisPushProperty. The value must be pushed onto the argument stack before this call.
Return Values for IrisSetProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_SUCCESS The operation was successful.

IrisSignal

int IrisSignal(int signal)
Arguments
signal The operating system's signal value.
Description
Passes on signals caught by user's program to InterSystems IRIS.
This function is very similar to IrisAbort, but allows passing of any known signal value from a thread or user side of the connection to the InterSystems IRIS side, for whatever action might be appropriate. For example, this could be used to pass signals intercepted in a user-defined signal handler on to InterSystems IRIS.
Example
rc = IrisSignal(CTRL_C_EVENT); // Windows response to Ctrl-C
rc = IrisSignal(CTRL_C_EVENT); // UNIX response to Ctrl-C
Return Values for IrisSignal
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_NOTINIRIS The Callin partner is not in InterSystems IRIS at this time.
IRIS_SUCCESS Connection formed.

IrisSPCReceive

int IrisSPCReceive(int * lenp, Callin_char_t * ptr)
Arguments
lenp Maximum length to receive. Modified on return to indicate number of bytes actually received.
ptr Pointer to buffer that will receive message. Must be at least lenp bytes.
Description
Receive single-process-communication message. The current device must be a TCP device opened in SPC mode, or IRIS_ERFUNCTION will be returned.
Return Values for IrisSPCReceive
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERFUNCTION Current device is not TCP device or is not connected.
IRIS_SUCCESS The operation was successful.

IrisSPCSend

int IrisSPCSend(int len, const Callin_char_t * ptr)
Arguments
len Length of message in bytes.
ptr Pointer to string containing message.
Description
Send a single-process-communication message. The current device must be a TCP device opened in SPC mode, or IRIS_ERFUNCTION will be returned.
Return Values for IrisSPCSend
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERFUNCTION Current device is not TCP device or is not connected.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.

IrisStartA

int IrisStartA(unsigned long flags, int tout, IRIS_ASTRP prinp, IRIS_ASTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisStartA
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartA from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndA has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
IRIS_ASTR inpdev;
IRIS_ASTR outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartA(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);

IrisStartH

int IrisStartH(unsigned long flags,int tout,IRISHSTRP prinp,IRISHSTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisStartH
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartH from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndH has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartH(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);

IrisStartW

int IrisStartW(unsigned long flags,int tout,IRISWSTRP prinp,IRISWSTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)
  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.
  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.
  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.
  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.
  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.
  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.
Return Values for IrisStartW
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartW from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndW has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartW(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);

IrisTCommit

int IrisTCommit( )
Description
Executes an InterSystems IRIS TCommit command.
Return Values for IrisTCommit
IRIS_SUCCESS TCommit was successful.

IrisTLevel

int IrisTLevel( )
Description
Returns the current nesting level ($TLEVEL) for transaction processing.
Return Values for IrisTLevel
IRIS_SUCCESS TLevel was successful.

IrisTRollback

int IrisTRollback(int nlev)
Arguments
nlev Determines how many levels to roll back, (all levels if 0, one level if 1).
Description
Executes an InterSystems IRIS TRollback command. If nlev is 0, rolls back all transactions in progress (no matter how many levels of TSTART were issued) and resets $TLEVEL to 0. If nlev is 1, rolls back the current level of nested transactions (the one initiated by the most recent TSTART) and decrements $TLEVEL by 1.
Return Values for IrisTRollback
IRIS_SUCCESS TStart was successful.

IrisTStart

int IrisTStart( )
Description
Executes an InterSystems IRIS TStart command.
Return Values for IrisTStart
IRIS_SUCCESS TStart was successful.

IrisType

int IrisType( )
Description
Returns the native type of the item returned by IrisEvalA, IrisEvalW, or IrisEvalH as the function value.
Return Values for IrisType
IRIS_ASTRING 8-bit string.
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_DOUBLE 64-bit floating point.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_IEEE_DBL 64-bit IEEE floating point.
IRIS_INT 32-bit integer.
IRIS_NOCON No connection has been established.
IRIS_NORES No result whose type can be returned (no call to IrisEvalA or IrisEvalW preceded this call).
IRIS_OREF InterSystems IRIS object reference.
IRIS_WSTRING Unicode string.
Example
rc = IrisType();

IrisUnPop

int IrisUnPop( )
Description
Restores the stack entry from IrisPop.
Return Values for IrisUnPop
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
Previous section