Skip to main content
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].

  • IrisCallExecuteFunc — Performs the $Xecute() function after the command string has been pushed onto the stack by IrisPushExecuteFuncA[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.

  • IrisExecuteArgs — Executes a command string with arguments.

  • 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.

  • IrisPushExecuteFuncA[W][H] — Pushes the $Xecute() command string onto the stack in preparation for a call by IrisCallExecuteFunc.

  • 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)
Copy code to clipboard
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);
Copy code to clipboard

IrisAcquireLock

int IrisAcquireLock(int nsub, int flg, int tout, int * rval)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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.

IrisCallExecuteFunc

int IrisCallExecuteFunc(int numargs)
Copy code to clipboard
Arguments

numargs Number of arguments pushed onto the stack.
Description

Calls the $Xecute() function with arguments. The function command string must have been pushed onto the argument stack by IrisPushExecuteFuncA[W][H], followed by pushing the arguments. The number of arguments may be 0. The result of the function will be left on the argument stack.

Return Values for IrisCallExecuteFunc

IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_BADARG Invalid call argument.
IRIS_STRTOOLONG String is too long.
IRIS_ERPARAMETER Xecute string is not expecting arguments
IRIS_SUCCESS The operation was successful.
IRIS_FAILURE An unexpected error has occurred.

IrisChangePasswordA

Variants: IrisChangePasswordW, IrisChangePasswordH

int IrisChangePasswordA(IRIS_ASTRP username, IRIS_ASTRP oldpassword, IRIS_ASTRP newpassword)
Copy code to clipboard
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 or delegated authentication is used. It is not valid for LDAP, 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

Variants: IrisChangePasswordA, IrisChangePasswordW

int IrisChangePasswordH(IRISHSTRP username, IRISHSTRP oldpassword, IRISHSTRP newpassword)
Copy code to clipboard
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 or delegated authentication is used. It is not valid for LDAP, 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

Variants: IrisChangePasswordA, IrisChangePasswordH

int IrisChangePasswordW(IRISWSTRP username, IRISWSTRP oldpassword, IRISWSTRP newpassword)
Copy code to clipboard
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 or delegated authentication is used. It is not valid for LDAP, 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)
Copy code to clipboard
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()
Copy code to clipboard
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();
Copy code to clipboard

IrisConvert

int IrisConvert(unsigned long type, void * rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisCtrl

int IrisCtrl(unsigned long flags)
Copy code to clipboard
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);
Copy code to clipboard

IrisCvtExStrInA

Variants: IrisCvtExStrInW, IrisCvtExStrInH

int IrisCvtExStrInA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtExStrInA, IrisCvtExStrInH

int IrisCvtExStrInW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtExStrInA, IrisCvtExStrInW

int IrisCvtExStrInH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtExStrOutW, IrisCvtExStrOutH

int IrisCvtExStrOutA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtExStrOutA, IrisCvtExStrOutH

int IrisCvtExStrOutW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtExStrOutA, IrisCvtExStrOutW

int IrisCvtExStrOutH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Copy code to clipboard
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

Variants: IrisCvtInW, IrisCvtInH

int IrisCvtInA(IRIS_ASTRP src, IRIS_ASTRP tbl, IRIS_ASTRP res)
Copy code to clipboard
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

Variants: IrisCvtInA, IrisCvtInH

int IrisCvtInW(IRIS_ASTRP src, IRISWSTRP tbl, IRISWSTRP res)
Copy code to clipboard
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

Variants: IrisCvtInA, IrisCvtInW

int IrisCvtInH(IRIS_ASTRP src, IRISHSTRP tbl, IRISHSTRP res)
Copy code to clipboard
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

Variants: IrisCvtOutW, IrisCvtOutH

int IrisCvtOutA(IRIS_ASTRP src, IRIS_ASTRP tbl, IRIS_ASTRP res)
Copy code to clipboard
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

Variants: IrisCvtOutA, IrisCvtOutH

int IrisCvtOutW(IRISWSTRP src, IRISWSTRP tbl, IRIS_ASTRP res)
Copy code to clipboard
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

Variants: IrisCvtOutA, IrisCvtOutW

int IrisCvtOutH(IRISHSTRP src, IRISHSTRP tbl, IRIS_ASTRP res)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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()
Copy code to clipboard
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();
Copy code to clipboard

IrisEndAll

int IrisEndAll()
Copy code to clipboard
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();
Copy code to clipboard

IrisErrorA

Variants: IrisErrorW, IrisErrorH

int IrisErrorA(IRIS_ASTRP msg, IRIS_ASTRP src, int * offp)
Copy code to clipboard
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);
Copy code to clipboard

IrisErrorH

Variants: IrisErrorA, IrisErrorW

int IrisErrorH(IRISHSTRP msg, IRISHSTRP src, int * offp)
Copy code to clipboard
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);
Copy code to clipboard

IrisErrorW

Variants: IrisErrorA, IrisErrorH

int IrisErrorW(IRISWSTRP msg, IRISWSTRP src, int * offp)
Copy code to clipboard
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);
Copy code to clipboard

IrisErrxlateA

Variants: IrisErrxlateW, IrisErrxlateH

int IrisErrxlateA(int code, IRIS_ASTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisErrxlateH

Variants: IrisErrxlateA, IrisErrxlateW

int IrisErrxlateH(int code, IRISHSTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisErrxlateW

Variants: IrisErrxlateA, IrisErrxlateH

int IrisErrxlateW(int code, IRISWSTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisEvalA

Variants: IrisEvalW, IrisEvalH

int IrisEvalA(IRIS_ASTRP volatile expr)
Copy code to clipboard
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);
Copy code to clipboard

IrisEvalH

Variants: IrisEvalA, IrisEvalW

int IrisEvalH(IRISHSTRP volatile expr)
Copy code to clipboard
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);
Copy code to clipboard

IrisEvalW

Variants: IrisEvalA, IrisEvalH

int IrisEvalW(IRISWSTRP volatile expr)
Copy code to clipboard
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);
Copy code to clipboard

IrisExecuteA

Variants: IrisExecuteW, IrisExecuteH

int IrisExecuteA(IRIS_ASTRP volatile cmd)
Copy code to clipboard
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,"set $namespace = \"USER\""); /* changes namespace */
command.len = strlen(command.str);
rc = IrisExecuteA(&command);
Copy code to clipboard

IrisExecuteH

Variants: IrisExecuteA, IrisExecuteW

int IrisExecuteH(IRISHSTRP volatile cmd)
Copy code to clipboard
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);
Copy code to clipboard

IrisExecuteW

Variants: IrisExecuteA, IrisExecuteH

int IrisExecuteW(IRISWSTRP volatile cmd)
Copy code to clipboard
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);
Copy code to clipboard

IrisExecuteArgs

int IrisExecuteArgs(int numargs)
Copy code to clipboard
Arguments

numargs Number of arguments pushed onto the stack.
Description

Executes a command string with arguments. The command string must have been pushed onto the argument stack with normal push string functions, followed by pushing the arguments. The number of arguments may be 0.

Return Values for IrisExecuteArgs

IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_BADARG Invalid call argument.
IRIS_STRTOOLONG String is too long.
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS The operation was successful.

IrisExStrKill

int IrisExStrKill(IRIS_EXSTRP obj)
Copy code to clipboard
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

Variants: IrisExStrNewW, IrisExStrNewH

unsigned char * IrisExStrNew(IRIS_EXSTRP zstr, int size)
Copy code to clipboard
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

Variants: IrisExStrNew, IrisExStrNewH

unsigned short * IrisExStrNewW(IRIS_EXSTRP zstr, int size)
Copy code to clipboard
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

Variants: IrisExStrNew, IrisExStrNewW

unsigned short * IrisExStrNewH(IRIS_EXSTRP zstr, int size)
Copy code to clipboard
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)
Copy code to clipboard
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()
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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( )
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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()
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisPopExStrW, IrisPopExStrH

int IrisPopExStr(IRIS_EXSTRP sstrp)
Copy code to clipboard
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

Variants: IrisPopExStr, IrisPopExStrH

int IrisPopExStrW(IRIS_EXSTRP sstrp)
Copy code to clipboard
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

Variants: IrisPopExStr, IrisPopExStrW

int IrisPopExStrH(IRIS_EXSTRP sstrp)
Copy code to clipboard
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

Variants: IrisPopExStrCvtH

int IrisPopExStrCvtW(IRIS_EXSTRP sstr)
Copy code to clipboard
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

Variants: IrisPopExStrCvtW

int IrisPopExStrCvtW(IRIS_EXSTRP sstr)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisPopStrW, IrisPopStrH

int IrisPopStr(int * lenp, Callin_char_t ** strp)
Copy code to clipboard
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

Variants: IrisPopStr, IrisPopStrH

int IrisPopStrW(int * lenp, unsigned short ** strp)
Copy code to clipboard
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

Variants: IrisPopStr, IrisPopStrW

int IrisPopStrH(int * lenp, wchar_t ** strp)
Copy code to clipboard
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

Variants: IrisPromptW, IrisPromptH

int IrisPromptA(IRIS_ASTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisPromptH

Variants: IrisPromptA, IrisPromptW

int IrisPromptH(IRISHSTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisPromptW

Variants: IrisPromptA, IrisPromptH

int IrisPromptW(IRISWSTRP rbuf)
Copy code to clipboard
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);
Copy code to clipboard

IrisPushClassMethod

Variants: IrisPushClassMethodW, IrisPushClassMethodH

int IrisPushClassMethod(int clen, const Callin_char_t * cptr,
                         int mlen, const Callin_char_t * mptr, int flg)
Copy code to clipboard
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

Variants: IrisPushClassMethod, IrisPushClassMethodW

int IrisPushClassMethodH(int clen, const wchar_t * cptr,
                          int mlen, const wchar_t * mptr, int flg)
Copy code to clipboard
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

Variants: IrisPushClassMethod, IrisPushClassMethodH

int IrisPushClassMethodW(int clen, const unsigned short * cptr,
                          int mlen, const unsigned short * mptr, int flg)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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.

IrisPushExecuteFuncA

Variants: IrisPushExecuteFuncW, IrisPushExecuteFuncH

int IrisPushExecuteFuncA(int len, const unsigned char *ptr)
Copy code to clipboard
Arguments

len Length of command string
ptr Pointer to command string
Description

Pushes the $Xecute() command string onto the argument stack to prepare for a call by IrisCallExecuteFunc().

Return Values for IrisPushExecuteFuncA

IRIS_STRTOOLONG String is too long.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExecuteFuncW

Variants: IrisPushExecuteFuncA, IrisPushExecuteFuncH

int IrisPushExecuteFuncW(int len, const unsigned short *ptr)
Copy code to clipboard
Arguments

len Length of command string
ptr Pointer to command string
Description

Pushes the $Xecute() command string onto the argument stack to prepare for a call by IrisCallExecuteFunc().

Return Values for IrisPushExecuteFuncW

IRIS_STRTOOLONG String is too long.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExecuteFuncH

Variants: IrisPushExecuteFuncA, IrisPushExecuteFuncW

int IrisPushExecuteFuncH(int len, const wchar_t *ptr)
Copy code to clipboard
Arguments

len Length of command string
ptr Pointer to command string
Description

Pushes the $Xecute() command string onto the argument stack to prepare for a call by IrisCallExecuteFunc().

Return Values for IrisPushExecuteFuncH

IRIS_STRTOOLONG String is too long.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.

IrisPushExStr

Variants: IrisPushExStrW, IrisPushExStrH

int IrisPushExStr(IRIS_EXSTRP sptr)
Copy code to clipboard
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

Variants: IrisPushExStr, IrisPushExStrH

int IrisPushExStrW(IRIS_EXSTRP sptr)
Copy code to clipboard
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

Variants: IrisPushExStr, IrisPushExStrW

int IrisPushExStrH(IRIS_EXSTRP sptr)
Copy code to clipboard
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

Variants: IrisPushExStrCvtH

int IrisPushExStrCvtW(IRIS_EXSTRP sptr)
Copy code to clipboard
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

Variants: IrisPushExStrCvtW

int IrisPushExStrCvtH(IRIS_EXSTRP sptr)
Copy code to clipboard
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

Variants: IrisPushFuncW, IrisPushFuncH

int IrisPushFunc(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                  int nlen, const Callin_char_t * nptr)
Copy code to clipboard
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

Variants: IrisPushFunc, IrisPushFuncW

int IrisPushFuncH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                   int nlen, const wchar_t * nptr)
Copy code to clipboard
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

Variants: IrisPushFunc, IrisPushFuncH

int IrisPushFuncW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                   int nlen, const unsigned short * nptr)
Copy code to clipboard
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

Variants: IrisPushFuncXW, IrisPushFuncXH

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)
Copy code to clipboard
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

Variants: IrisPushFuncX, IrisPushFuncXW

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)
Copy code to clipboard
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

Variants: IrisPushFuncX, IrisPushFuncXH

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)
Copy code to clipboard
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

Variants: IrisPushGlobalW, IrisPushGlobalH

int IrisPushGlobal(int nlen, const Callin_char_t * nptr)
Copy code to clipboard
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

Variants: IrisPushGlobal, IrisPushGlobalW

intIrisPushGlobalH(int nlen, const wchar_t * nptr)
Copy code to clipboard
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

Variants: IrisPushGlobal, IrisPushGlobalH

int IrisPushGlobalW(int nlen, const unsigned short * nptr)
Copy code to clipboard
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

Variants: IrisPushGlobalXW, IrisPushGlobalXH

int IrisPushGlobalX(int nlen, const Callin_char_t * nptr,
                     int elen, const Callin_char_t * eptr)
Copy code to clipboard
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

Variants: IrisPushGlobalX, IrisPushGlobalXW

int IrisPushGlobalXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Copy code to clipboard
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

Variants: IrisPushGlobalX, IrisPushGlobalXH

int IrisPushGlobalXW(int nlen, const unsigned short * nptr,
                      int elen, const unsigned short * eptr)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisPushLockW, IrisPushLockH

int IrisPushLock(int nlen, const Callin_char_t * nptr)
Copy code to clipboard
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

Variants: IrisPushLock, IrisPushLockW

int IrisPushLockH(int nlen, const wchar_t * nptr)
Copy code to clipboard
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

Variants: IrisPushLock, IrisPushLockH

int IrisPushLockW(int nlen, const unsigned short * nptr)
Copy code to clipboard
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

Variants: IrisPushLockXW, IrisPushLockXH

int IrisPushLockX(int nlen, const Callin_char_t * nptr, int elen, const Callin_char_t * eptr)
Copy code to clipboard
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

Variants: IrisPushLockX, IrisPushLockXW

int IrisPushLockXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Copy code to clipboard
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

Variants: IrisPushLockX, IrisPushLockXH

int IrisPushLockXW(int nlen, const unsigned short * nptr, int elen, const unsigned short * eptr)
Copy code to clipboard
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

Variants: IrisPushMethodW, IrisPushMethodH

int IrisPushMethod(unsigned int oref, int mlen, const Callin_char_t * mptr, int flg)
Copy code to clipboard
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

Variants: IrisPushMethod, IrisPushMethodW

int IrisPushMethodH(unsigned int oref, int mlen, const wchar_t * mptr, int flg)
Copy code to clipboard
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

Variants: IrisPushMethod, IrisPushMethodH

int IrisPushMethodW(unsigned int oref, int mlen, const unsigned short * mptr, int flg)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisPushPropertyW, IrisPushPropertyH

int IrisPushProperty(unsigned int oref, int plen, const Callin_char_t * pptr)
Copy code to clipboard
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

Variants: IrisPushProperty, IrisPushPropertyW

int IrisPushPropertyH(unsigned int oref, int plen, const wchar_t * pptr)
Copy code to clipboard
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

Variants: IrisPushProperty, IrisPushPropertyH

int IrisPushPropertyW(unsigned int oref, int plen, const unsigned short * pptr)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisPushRtnW, IrisPushRtnH

int IrisPushRtn(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                 int nlen, const Callin_char_t * nptr)
Copy code to clipboard
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

Variants: IrisPushRtn, IrisPushRtnW

int IrisPushRtnH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                  int nlen, const wchar_t * nptr)
Copy code to clipboard
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

Variants: IrisPushRtn, IrisPushRtnH

int IrisPushRtnW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                  int nlen, const unsigned short * nptr)
Copy code to clipboard
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

Variants: IrisPushRtnXW, IrisPushRtnXH

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)
Copy code to clipboard
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

Variants: IrisPushRtnX, IrisPushRtnXW

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)
Copy code to clipboard
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

Variants: IrisPushRtnX, IrisPushRtnXH

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)
Copy code to clipboard
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

Variants: IrisPushStrW, IrisPushStrH

int IrisPushStr(int len, const Callin_char_t * ptr)
Copy code to clipboard
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

Variants: IrisPushStr, IrisPushStrH

int IrisPushStrW(int len, const unsigned short * ptr)
Copy code to clipboard
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

Variants: IrisPushStr, IrisPushStrW

int IrisPushStrH(int len, const wchar_t * ptr)
Copy code to clipboard
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()
Copy code to clipboard
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( )
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisSecureStartW, IrisSecureStartH

int IrisSecureStartA(IRIS_ASTRP username, IRIS_ASTRP password, IRIS_ASTRP exename,
                      unsigned long flags, int tout, IRIS_ASTRP prinp, IRIS_ASTRP prout)
Copy code to clipboard
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

Variants: IrisSecureStartA, IrisSecureStartW

int IrisSecureStartH(IRISHSTRP username, IRISHSTRP password, IRISHSTRP exename,
                      unsigned long flags, int tout, IRISHSTRP prinp, IRISHSTRP prout)
Copy code to clipboard
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

Variants: IrisSecureStartA, IrisSecureStartH

int IrisSecureStartW(IRISWSTRP username, IRISWSTRP password, IRISWSTRP exename,
                      unsigned long flags, int tout, IRISWSTRP prinp, IRISWSTRP prout)
Copy code to clipboard
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)
Copy code to clipboard
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( )
Copy code to clipboard
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)
Copy code to clipboard
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
Copy code to clipboard
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)
Copy code to clipboard
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)
Copy code to clipboard
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

Variants: IrisStartW, IrisStartH

int IrisStartA(unsigned long flags, int tout, IRIS_ASTRP prinp, IRIS_ASTRP prout)
Copy code to clipboard
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 principal 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 principal 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);
Copy code to clipboard

IrisStartH

Variants: IrisStartA, IrisStartW

int IrisStartH(unsigned long flags,int tout,IRISHSTRP prinp,IRISHSTRP prout)
Copy code to clipboard
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 principal 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 principal 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);
Copy code to clipboard

IrisStartW

Variants: IrisStartA, IrisStartH

int IrisStartW(unsigned long flags,int tout,IRISWSTRP prinp,IRISWSTRP prout)
Copy code to clipboard
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 principal 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 principal 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);
Copy code to clipboard

IrisTCommit

int IrisTCommit( )
Copy code to clipboard
Description

Executes an InterSystems IRIS TCommit command.

Return Values for IrisTCommit

IRIS_SUCCESS TCommit was successful.

IrisTLevel

int IrisTLevel( )
Copy code to clipboard
Description

Returns the current nesting level ($TLEVEL) for transaction processing.

Return Values for IrisTLevel

IRIS_SUCCESS TLevel was successful.

IrisTRollback

int IrisTRollback(int nlev)
Copy code to clipboard
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( )
Copy code to clipboard
Description

Executes an InterSystems IRIS TStart command.

Return Values for IrisTStart

IRIS_SUCCESS TStart was successful.

IrisType

int IrisType( )
Copy code to clipboard
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();
Copy code to clipboard

IrisUnPop

int IrisUnPop( )
Copy code to clipboard
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.