docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the Callin API  /  Callin Function Reference


Using the Callin API
Callin Function Reference
[Back] 
InterSystems: The power behind what matters   
Search:  


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:
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
int IrisAbort(unsigned long type)
Arguments
type Either of the following predefined values that specify how the termination occurs:
  • IRIS_CTRLC — Interrupts the InterSystems IRIS processing as if a CTRL-C had been processed (regardless of whether CTRL-C has been enabled with IrisCtrl). A connection to InterSystems IRIS remains.
  • IRIS_RESJOB — Terminates the Callin connection. You must then call IrisEnd and then IrisStart to reconnect to InterSystems IRIS.
Description
Tells InterSystems IRIS to cancel the current request being processed on the InterSystems IRIS side, when it is convenient to do so. This function is for use if you detect some critical event in an AST (asynchronous trap) or thread running on the Callin side. (You can use IrisContext to determine if there is an InterSystems IRIS request currently being processed.) Note that this only applies to Callin programs that use an AST or separate thread.
Return Values for IrisAbort
IRIS_BADARG The termination type is invalid.
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_NOTINCACHE The Callin partner is not in InterSystems IRIS at this time.
IRIS_SUCCESS Connection formed.
Example
rc = IrisAbort(IRIS_CTRLC);
IrisAcquireLock
int IrisAcquireLock(int nsub, int flg, int tout, int * rval)
Arguments
nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of IRIS_INCREMENTAL_LOCK and IRIS_SHARED_LOCK.
tout Number of seconds to wait for the lock command to complete. Negative for no timeout. 0 means return immediately if the lock is not available, although a minimum timeout may be applied if the lock is mapped to a remote system.
rval Optional pointer to an int return value: success = 1, failure = 0.
Description
Executes an InterSystems IRIS LOCK command. The lock reference should already be set up with IrisPushLock.
Return Values for IrisAcquireLock
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Successfully called the LOCK command (but the rval parameter must be examined to determine if the lock succeeded).
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERARGSTACK Argument stack overflow.
IrisBitFind
int IrisBitFind(int strlen, unsigned short *bitstr, int newlen, int srch, int revflg)
Arguments
strlen Data length of the bitstring.
bitstr Pointer to a Unicode bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:
1 — Search forward (left to right) from the position indicated by newlen.
0 — Search backward from the position indicated by newlen.
Description
Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.
This function is similar to InterSystems IRIS $BITFIND (also see General Information on Bitstring Functions).
Return Values for IrisBitFind
IRIS_SUCCESS The operation was successful.
IrisBitFindB
int IrisBitFindB(int strlen, unsigned char *bitstr, int newlen, int srch, int revflg)
Arguments
strlen Data length of the bitstring.
bitstr Pointer to a bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position.
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:
1 — Search forward (left to right) from the position indicated by newlen.
0 — Search backward from the position indicated by newlen.
Description
Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.
This function is similar to InterSystems IRIS $BITFIND (also see General Information on Bitstring Functions).
Return Values for IrisBitFindB
IRIS_SUCCESS The operation was successful.
IrisChangePasswordA
Variants: IrisChangePasswordW, IrisChangePasswordH
int IrisChangePasswordA(IRIS_ASTRP username, IRIS_ASTRP oldpassword, IRIS_ASTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordA
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.
IrisChangePasswordH
Variants: IrisChangePasswordA, IrisChangePasswordW
int IrisChangePasswordH(IRISHSTRP username, IRISHSTRP oldpassword, IRISHSTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordH
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.
IrisChangePasswordW
Variants: IrisChangePasswordA, IrisChangePasswordH
int IrisChangePasswordW(IRISWSTRP username, IRISWSTRP oldpassword, IRISWSTRP newpassword)
Arguments
username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description
This function can change the user's password if InterSystems authentication is used. It is not valid for LDAP, DELEGATED, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a IRIS_CHANGEPASSWORD error from IrisSecureStart. In such a case IrisChangePassword would be called to change the password, then IrisSecureStart would be called again.
Return Values for IrisChangePasswordW
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Password changed.
IrisCloseOref
int IrisCloseOref(unsigned int oref)
Arguments
oref Object reference.
Description
Decrements the system reference counter for an OREF.
Return Values for IrisCloseOref
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.
IrisContext
int IrisContext()
Description
Returns an integer as the function value.
If you are using an external Callin program (as opposed to a module that was called from a $ZF function) and your program employs an AST or separate thread, then IrisContext tells you if there is a request currently being processed on the InterSystems IRIS side of the connection. This information is needed to decide if you must return to InterSystems IRIS to allow processing to complete.
Return Values for IrisContext
-1 Created in InterSystems IRIS via a $ZF callback.
0 No connection or not in InterSystems IRIS at the moment.
1 In InterSystems IRIS via an external (i.e., not $ZF) connection. An asynchronous trap (AST), such as an exit-handler, would need to return to InterSystems IRIS to allow processing to complete.
Note:
The information about whether you are in a $ZF function from a program or an AST is needed because, if you are in an AST, then you need to return to InterSystems IRIS to allow processing to complete.
Example
rc = IrisContext();
IrisConvert
int IrisConvert(unsigned long type, void * rbuf)
Arguments
type The #define'd type, with valid values listed below.
rbuf Address of a data area of the proper size for the data type. If the type is IRIS_ASTRING, rbuf should be the address of a IRIS_ASTR structure that will contain the result, and the len element in the structure should be filled in to represent the maximum size of the string to be returned (in characters). Similarly, if the type is IRIS_WSTRING, rbuf should be the address of a IRISWSTR structure whose len element has been filled in to represent the maximum size (in characters).
Description
Converts the value returned by IrisEval into proper format and places in address specified in its return value (listed below as rbuf).
Valid values of type are:
Return Values for IrisConvert
IRIS_BADARG Type is invalid.
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE An unexpected error has occurred.
IRIS_NOCON No connection has been established.
IRIS_NORES No result whose type can be returned (no call to IrisEvalA preceded this call).
IRIS_RETTRUNC Success, but the type IRIS_ASTRING, IRIS_INT8, IRIS_UINT8 and IRIS_WSTRING resulted in a value that would not fit in the space allocated in retval. For IRIS_INT8 and IRIS_UINT8, this means that the expression resulted in a floating point number that could not be normalized to fit within 64 bits.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS Value returned by last IrisEval converted successfully.
Note:
InterSystems IRIS may perform division when calculating the return value for floating point types, IRIS_FLOAT and IRIS_DOUBLE, which have decimal parts (including negative exponents), as well as the 64-bit integer types (IRIS_INT8 and IRIS_UINT8). Therefore, the returned result may not be identical in value to the original. IRIS_ASTRING, IRIS_INT8, IRIS_UINT8 and IRIS_WSTRING can return the status IRIS_RETTRUNC.
Example
IRIS_ASTR retval;
/* define variable retval */

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

rc = IrisConvert(IRIS_ASTRING,&retval);
IrisCtrl
int IrisCtrl(unsigned long flags)
Arguments
flags Either of two #define'd values specifying how InterSystems IRIS handles certain keystrokes.
Description
Determines whether or not InterSystems IRIS ignores CTRL-C. flags can have bit state values of
Return Values for IrisCtrl
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.
Example
rc = IrisCtrl(IRIS_ENABCTRLC);
IrisCvtExStrInA
Variants: IrisCvtExStrInW, IrisCvtExStrInH
int IrisCvtExStrInA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the local 8-bit character string encoding used internally.
Return Values for IrisCvtExStrInA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisCvtExStrInW
Variants: IrisCvtExStrInA, IrisCvtExStrInH
int IrisCvtExStrInW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the 2–byte Unicode character string encoding used internally in InterSystems IRIS.
Return Values for IrisCvtExStrInW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisCvtExStrInH
Variants: IrisCvtExStrInA, IrisCvtExStrInW
int IrisCvtExStrInH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string with specified external character set encoding to the 4–byte Unicode character string encoding used internally in InterSystems IRIS.
Return Values for IrisCvtExStrInH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisCvtExStrOutA
Variants: IrisCvtExStrOutW, IrisCvtExStrOutH
int IrisCvtExStrOutA(IRIS_EXSTRP src, IRIS_ASTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 8-bit character string encoding used internally in an older InterSystems 8-bit product to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutA
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for Unicode.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisCvtExStrOutW
Variants: IrisCvtExStrOutA, IrisCvtExStrOutH
int IrisCvtExStrOutW(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 2–byte Unicode character string encoding used internally in InterSystems IRIS to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisCvtExStrOutH
Variants: IrisCvtExStrOutA, IrisCvtExStrOutW
int IrisCvtExStrOutH(IRIS_EXSTRP src, IRISWSTRP tbl, IRIS_EXSTRP res)
Arguments
src Address of a IRIS_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a IRIS_EXSTRP variable that will contain the result.
Description
Translates a string from the 4–byte Unicode character string encoding used internally in InterSystems IRIS to a string with the specified external character set encoding.
Return Values for IrisCvtExStrOutH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_ERRUNIMPLEMENTED Not available for 8–bit systems.
IRIS_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
IRIS_ERXLATE Input string could not be translated using the specified I/O translation table.
IRIS_NOCON No connection has been established.
IRIS_RETTRUNC Result was truncated because result buffer was too small.
IRIS_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
IRIS_SUCCESS Translation completed successfully.
IrisDoFun
int IrisDoFun(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushRtn[XW]
narg Number of call arguments pushed onto the argument stack. Target must have a (possibly empty) formal parameter list.
Description
Performs a routine call (special case).
Return Values for IrisDoFun
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisDoRtn
int IrisDoRtn(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushRtn[XW]
narg Number of call arguments pushed onto the argument stack. If zero, target must not have a formal parameter list.
Description
Performs a routine call.
Return Values for IrisDoRtn
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisEnd
int IrisEnd()
Description
Terminates an InterSystems IRIS process. If there is a broken connection, it also performs clean-up operations.
Return Values for IrisEnd
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_NOCON No connection has been established.
IRIS_SUCCESS InterSystems IRIS session terminated/cleaned up.
IrisEnd can also return any of the InterSystems IRIS error codes.
Example
rc = IrisEnd();
IrisEndAll
int IrisEndAll()
Description
Disconnects all threads in a threaded Callin environment, then schedules the threads for termination and waits until they are done.
Return Values for IrisEndAll
IRIS_SUCCESS InterSystems IRIS session terminated/cleaned up.
Example
rc = IrisEndAll();
IrisErrorA
Variants: IrisErrorW, IrisErrorH
int IrisErrorA(IRIS_ASTRP msg, IRIS_ASTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp An integer that specifies the offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorA
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR errmsg;
IRIS_ASTR srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorA(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);
IrisErrorH
Variants: IrisErrorA, IrisErrorW
int IrisErrorH(IRISHSTRP msg, IRISHSTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorH
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRISHSTRP errmsg;
IRISHSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorH(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);
IrisErrorW
Variants: IrisErrorA, IrisErrorH
int IrisErrorW(IRISWSTRP msg, IRISWSTRP src, int * offp)
Arguments
msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.
Return Values for IrisErrorW
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
IRIS_SUCCESS Connection formed.
Example
IRISWSTRP errmsg;
IRISWSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = IrisErrorW(&errmsg, &srcline, &offset)) != IRIS_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);
IrisErrxlateA
Variants: IrisErrxlateW, IrisErrxlateH
int IrisErrxlateA(int code, IRIS_ASTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRIS_ASTR variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateA
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateA(IRIS_ERSTORE,&retval);
IrisErrxlateH
Variants: IrisErrxlateA, IrisErrxlateW
int IrisErrxlateH(int code, IRISHSTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRISHSTRP variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateH
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRISHSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateH(IRIS_ERSTORE,&retval);
IrisErrxlateW
Variants: IrisErrxlateA, IrisErrxlateH
int IrisErrxlateW(int code, IRISWSTRP rbuf)
Arguments
code The error code.
rbuf Address of a IRISWSTR variable to contain the InterSystems IRIS error string. The len field should be loaded with the maximum string size that can be returned.
Description
Translates error code code into an InterSystems IRIS error string, and writes that string into the structure pointed to by rbuf
Return Values for IrisErrxlateW
IRIS_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest InterSystems IRIS error number.
IRIS_RETTRUNC The associated error string was truncated to fit in the allocated area.
IRIS_SUCCESS Connection formed.
Example
IRISWSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = IrisErrxlateW(IRIS_ERSTORE,&retval);
IrisEvalA
Variants: IrisEvalW, IrisEvalH
int IrisEvalA(IRIS_ASTRP volatile expr)
Arguments
expr The address of a IRIS_ASTR variable.
Description
Evaluates a string as if it were an InterSystems IRIS expression and places the return value in memory for further processing by IrisType and IrisConvert.
If IrisEvalA completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalA.
Caution:
The next call to IrisEvalA, IrisExecuteA, or IrisEnd will overwrite the existing return value.
Return Values for IrisEvalA
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either InterSystems IRIS generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String evaluated successfully.
IrisEvalA can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRIS_ASTR retval;
IRIS_ASTR expr;

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

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

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = IrisEvalW(&expr);
if (rc == IRIS_SUCCESS)
    rc = IrisConvert(ING,&retval);
IrisExecuteA
Variants: IrisExecuteW, IrisExecuteH
int IrisExecuteA(IRIS_ASTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
Caution:
The next call to IrisEvalA, IrisExecuteA, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteA
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteA can also return any of the InterSystems IRIS error codes.
Example
int rc;
IRIS_ASTR command;
sprintf(command.str,"ZN \"USER\""); /* changes namespace */
command.len = strlen(command.str);
rc = IrisExecuteA(&command);
IrisExecuteH
Variants: IrisExecuteA, IrisExecuteW
int IrisExecuteH(IRISHSTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
If IrisExecuteH completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalH.
Caution:
The next call to IrisEvalH, IrisExecuteH, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteH
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteH can also return any of the InterSystems IRIS error codes.
Example
int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
IRISHSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = IrisExecuteH(pcommand);
IrisExecuteW
Variants: IrisExecuteA, IrisExecuteH
int IrisExecuteW(IRISWSTRP volatile cmd)
Arguments
cmd The address of a IRIS_ASTR variable.
Description
Executes the command string as if it were typed in the Terminal.
If IrisExecuteW completes successfully, it sets a flag that allows calls to IrisType and IrisConvert to complete. These functions are used to process the item returned from IrisEvalW.
Caution:
The next call to IrisEvalW, IrisExecuteW, or IrisEnd will overwrite the existing return value.
Return Values for IrisExecuteW
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_NOCON No connection has been established.
IRIS_STRTOOLONG String is too long.
IRIS_SUCCESS String executed successfully.
IrisExecuteW can also return any of the InterSystems IRIS error codes.
Example
int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
IRISWSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = IrisExecuteW(pcommand);
IrisExStrKill
int IrisExStrKill(IRIS_EXSTRP obj)
Arguments
obj Pointer to the string.
Description
Releases the storage associated with an EXSTR string.
Return Values for IrisExStrKill
IRIS_ERUNIMPLEMENTED String is undefined.
IRIS_SUCCESS String storage has been released.
IrisExStrNew
Variants: IrisExStrNewW, IrisExStrNewH
unsigned char * IrisExStrNew(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 8–bit characters to allocate.
Description
Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.
Return Values for IrisExStrNew
Returns a pointer to the allocated string, or NULL if no string was allocated.
IrisExStrNewW
Variants: IrisExStrNew, IrisExStrNewH
unsigned short * IrisExStrNewW(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 2–byte characters to allocate.
Description
Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.
Return Values for IrisExStrNewW
Returns a pointer to the allocated string, or NULL if no string was allocated.
IrisExStrNewH
Variants: IrisExStrNew, IrisExStrNewW
unsigned short * IrisExStrNewH(IRIS_EXSTRP zstr, int size)
Arguments
zstr Pointer to a IRIS_EXSTR string descriptor.
size Number of 4–byte characters to allocate.
Description
Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.
Return Values for IrisExStrNewH
Returns a pointer to the allocated string, or NULL if no string was allocated.
IrisExtFun
int IrisExtFun(unsigned int flags, int narg)
Arguments
flags Routine flags from IrisPushFunc[XW].
narg Number of call arguments pushed onto the argument stack.
Description
Performs an extrinsic function call where the return value is pushed onto the argument stack.
Return Values for IrisExtFun
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_FAILURE Internal consistency error.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGetProperty
int IrisGetProperty()
Description
Obtains the value of the property defined by IrisPushProperty. The value is pushed onto the argument stack.
Return Values for IrisGetProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalData
int IrisGlobalData(int narg, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Data on the specified global.
Return Values for IrisGlobalData
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalGet
int IrisGlobalGet(int narg, int flag)
Arguments
narg Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns IRIS_ERUNDEF
  • 1 — returns IRIS_SUCCESS but the return value is an empty string.
Description
Obtains the value of the global reference defined by IrisPushGlobal and any subscripts. The node value is pushed onto the argument stack.
Return Values for IrisGlobalGet
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalGetBinary
int IrisGlobalGetBinary(int numsub, int flag, int *plen, Callin_char_t **pbuf)
Arguments
numsub Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns IRIS_ERUNDEF
  • 1 — returns IRIS_SUCCESS but the return value is an empty string.
plen Pointer to length of buffer.
pbuf Pointer to buffer pointer.
Description
Obtains the value of the global reference defined by IrisPushGlobal[W][H] and any subscripts, and also tests to make sure that the result is a binary string that will fit in the provided buffer. The node value is pushed onto the argument stack.
Return Values for IrisGlobalGetBinary
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalIncrement
int IrisGlobalIncrement(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Performs a $INCREMENT and returns the result on top of the stack.
Return Values for IrisGlobalIncrement
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_ERMAXINCR MAXINCREMENT system error
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalKill
int IrisGlobalKill(int narg, int nodeonly)
Arguments
narg Number of call arguments pushed onto the argument stack.
nodeonly A value of 1 indicates that only the specified node should be killed. When the value is 0, the entire specified global tree is killed.
Description
Performs a ZKILL on a global node or tree.
Return Values for IrisGlobalKill
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalOrder
int IrisGlobalOrder(int narg, int dir, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Order is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Order on the specified global.
Return Values for IrisGlobalOrder
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalQuery
int IrisGlobalQuery(int narg, int dir, int valueflag)
Arguments
narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Query is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description
Performs a $Query on the specified global.
Return Values for IrisGlobalQuery
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_ERPROTECT Protection violation.
IRIS_ERUNDEF Node has no associated value.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisGlobalRelease
int IrisGlobalRelease( )
Description
Release ownership of a retained global buffer, if one exists.
Return Values for IrisGlobalRelease
IRIS_SUCCESS The operation was successful.
IrisGlobalSet
int IrisGlobalSet(int narg)
Arguments
narg Number of subscript expressions pushed onto the argument stack.
Description
Stores the value of the global reference defined by IrisPushGlobal and any subscripts. The node value must be pushed onto the argument stack before this call.
Return Values for IrisGlobalSet
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisIncrementCountOref
int IrisIncrementCountOref(unsigned int oref)
Arguments
oref Object reference.
Description
Increments the system reference counter for an OREF.
Return Values for IrisIncrementCountOref
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.
IrisInvokeClassMethod
int IrisInvokeClassMethod(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Executes the class method call defined by IrisPushClassMethod[W] and any arguments. The return value is pushed onto the argument stack.
Return Values for IrisInvokeClassMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisInvokeMethod
int IrisInvokeMethod(int narg)
Arguments
narg Number of call arguments pushed onto the argument stack.
Description
Executes the instance method call defined by IrisPushMethod[W] and any arguments pushed onto the argument stack.
Return Values for IrisInvokeMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisOflush
int IrisOflush()
Description
Flushes any pending output.
Return Values for IrisOflush
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.
IrisPop
int IrisPop(void ** arg)
Arguments
arg Pointer to argument stack entry.
Description
Pops a value off argument stack.
Return Values for IrisPop
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IrisPopDbl
int IrisPopDbl(double * nump)
Arguments
nump Pointer to double value.
Description
Pops a value off argument stack and converts it to a double.
Return Values for IrisPopDbl
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IrisPopExStr
Variants: IrisPopExStrW, IrisPopExStrH
int IrisPopExStr(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a string in local 8–bit encoding.
Return Values for IrisPopExStr
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.
IrisPopExStrW
Variants: IrisPopExStr, IrisPopExStrH
int IrisPopExStrW(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a 2–byte Unicode string.
Return Values for IrisPopExStrW
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.
IrisPopExStrH
Variants: IrisPopExStr, IrisPopExStrW
int IrisPopExStrH(IRIS_EXSTRP sstrp)
Arguments
sstrp Pointer to standard string pointer.
Description
Pops a value off argument stack and converts it to a 4–byte Unicode string.
Return Values for IrisPopExStrH
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IRIS_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.
IrisPopInt
int IrisPopInt(int* nump)
Arguments
nump Pointer to integer value.
Description
Pops a value off argument stack and converts it to an integer.
Return Values for IrisPopInt
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IrisPopInt64
int IrisPopInt64(long long * nump)
Arguments
nump Pointer to long long value.
Description
Pops a value off argument stack and converts it to a 64–bit (long long) value.
Return Values for IrisPopInt64
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.
IrisPopList
int IrisPopList(int * lenp, Callin_char_t ** strp)
Arguments
lenp Pointer to length of string.
strp Pointer to string pointer.
Description
Pops a $LIST object off argument stack and converts it.
Return Values for IrisPopList
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPopOref
int IrisPopOref(unsigned int * orefp)
Arguments
orefp Pointer to OREF value.
Description
Pops an OREF off argument stack.
Return Values for IrisPopOref
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_ERNOOREF Result is not an OREF.
IRIS_SUCCESS The operation was successful.
IrisPopPtr
int IrisPopPtr(void ** ptrp)
Arguments
ptrp Pointer to generic pointer.
Description
Pops a pointer off argument stack in internal format.
Return Values for IrisPopPtr
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_BADARG The entry is not a valid pointer.
IRIS_SUCCESS The operation was successful.
IrisPromptA
Variants: IrisPromptW, IrisPromptH
int IrisPromptA(IRIS_ASTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptA
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE An unexpected error has occurred.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRIS_ASTR retval;      /* define variable retval */
retval.len = 5;         /* maximum return length of string */
rc = IrisPromptA(&retval);
IrisPromptH
Variants: IrisPromptA, IrisPromptW
int IrisPromptH(IRISHSTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptH
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE Request failed.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRISHSTRP retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = IrisPromptH( &retval);
IrisPromptW
Variants: IrisPromptA, IrisPromptH
int IrisPromptW(IRISWSTRP rbuf)
Arguments
rbuf The prompt string. The minimum length of the returned string is five characters.
Description
Returns a string that would be the Terminal (without the “>”).
Return Values for IrisPromptW
IRIS_CONBROKEN Connection has been broken.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_FAILURE Request failed.
IRIS_NOCON No connection has been established.
IRIS_RETTOOSMALL rbuf must have a length of at least five.
IRIS_SUCCESS Connection formed.
Example
IRISWSTR retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = IrisConvertW( &retval);
IrisPushClassMethod
Variants: IrisPushClassMethodW, IrisPushClassMethodH
int IrisPushClassMethod(int clen, const Callin_char_t * cptr,
                         int mlen, const Callin_char_t * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg
Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a class method reference onto the argument stack.
Return Values for IrisPushClassMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
IrisPushClassMethodH
Variants: IrisPushClassMethod, IrisPushClassMethodW
int IrisPushClassMethodH(int clen, const wchar_t * cptr,
                          int mlen, const wchar_t * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 4-byte Unicode class method reference onto the argument stack.
Return Values for IrisPushClassMethodH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushClassMethodW
Variants: IrisPushClassMethod, IrisPushClassMethodH
int IrisPushClassMethodW(int clen, const unsigned short * cptr,
                          int mlen, const unsigned short * mptr, int flg)
Arguments
clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 2-byte Unicode class method reference onto the argument stack.
Return Values for IrisPushClassMethodW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushDbl
int IrisPushDbl(double num)
Arguments
num Double value.
Description
Pushes a double onto the argument stack.
Return Values for IrisPushDbl
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushExStr
Variants: IrisPushExStrW, IrisPushExStrH
int IrisPushExStr(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a string onto the argument stack.
Return Values for IrisPushExStr
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushExStrW
Variants: IrisPushExStr, IrisPushExStrH
int IrisPushExStrW(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a Unicode string onto the argument stack.
Return Values for IrisPushExStrW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushExStrH
Variants: IrisPushExStr, IrisPushExStrW
int IrisPushExStrH(IRIS_EXSTRP sptr)
Arguments
sptr Pointer to the argument value.
Description
Pushes a 4–byte Unicode string onto the argument stack.
Return Values for IrisPushExStrH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushFunc
Variants: IrisPushFuncW, IrisPushFuncH
int IrisPushFunc(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                  int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tagptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes an extrinsic function reference onto the argument stack.
Return Values for IrisPushFunc
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushFuncH
Variants: IrisPushFunc, IrisPushFuncW
int IrisPushFuncH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                   int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4-byte Unicode extrinsic function reference onto the argument stack.
Return Values for IrisPushFuncH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushFuncW
Variants: IrisPushFunc, IrisPushFuncH
int IrisPushFuncW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                   int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2-byte Unicode extrinsic function reference onto the argument stack.
Return Values for IrisPushFuncW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushFuncX
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)
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)
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)
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)
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)
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)
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)
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)
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)
Arguments
nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2-byte Unicode extended global reference onto the argument stack.
Return Values for IrisPushGlobalXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTAC String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushIEEEDbl
int IrisPushIEEEDbl(double num)
Arguments
num Double value.
Description
Pushes an IEEE double onto the argument stack.
Return Values for IrisPushIEEEDbl
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushInt
int IrisPushInt(int num)
Arguments
num Integer value.
Description
Pushes an integer onto the argument stack.
Return Values for IrisPushInt
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushInt64
int IrisPushInt64(long long num)
Arguments
num long long value.
Description
Pushes a 64–bit (long long) value onto the argument stack.
Return Values for IrisPushInt64
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushList
int IrisPushList(int len, const Callin_char_t * ptr)
Arguments
len Number of characters in string.
ptr Pointer to string.
Description
Converts a $LIST object and pushes it onto the argument stack.
Return Values for IrisPushList
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a string element.
IrisPushLock
Variants: IrisPushLockW, IrisPushLockH
int IrisPushLock(int nlen, const Callin_char_t * nptr)
Arguments
nlen Length (in bytes) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLock
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushLockH
Variants: IrisPushLock, IrisPushLockW
int IrisPushLockH(int nlen, const wchar_t * nptr)
Arguments
nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLockH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushLockW
Variants: IrisPushLock, IrisPushLockH
int IrisPushLockW(int nlen, const unsigned short * nptr)
Arguments
nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
Description
Initializes a IrisAcquireLock command by pushing the lock name on the argument stack.
Return Values for IrisPushLockW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushLockX
Variants: IrisPushLockXW, IrisPushLockXH
int IrisPushLockX(int nlen, const Callin_char_t * nptr, int elen, const Callin_char_t * eptr)
Arguments
nlen Length (number of 8–bit characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockX
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushLockXH
Variants: IrisPushLockX, IrisPushLockXW
int IrisPushLockXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Arguments
nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockXH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushLockXW
Variants: IrisPushLockX, IrisPushLockXH
int IrisPushLockXW(int nlen, const unsigned short * nptr, int elen, const unsigned short * eptr)
Arguments
nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description
Initializes a IrisAcquireLock command by pushing the lock name and an environment string on the argument stack.
Return Values for IrisPushLockXW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushMethod
Variants: IrisPushMethodW, IrisPushMethodH
int IrisPushMethod(unsigned int oref, int mlen, const Callin_char_t * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes an instance method reference onto the argument stack.
Return Values for IrisPushMethod
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
IrisPushMethodH
Variants: IrisPushMethod, IrisPushMethodW
int IrisPushMethodH(unsigned int oref, int mlen, const wchar_t * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 4-byte Unicode instance method reference onto the argument stack.
Return Values for IrisPushMethodH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushMethodW
Variants: IrisPushMethod, IrisPushMethodH
int IrisPushMethodW(unsigned int oref, int mlen, const unsigned short * mptr, int flg)
Arguments
oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description
Pushes a 2-byte Unicode instance method reference onto the argument stack.
Return Values for IrisPushMethodW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushOref
int IrisPushOref(unsigned int oref)
Arguments
oref Object reference.
Description
Pushes an OREF onto the argument stack.
Return Values for IrisPushOref
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERBADOREF Invalid OREF.
IRIS_SUCCESS The operation was successful.
IrisPushProperty
Variants: IrisPushPropertyW, IrisPushPropertyH
int IrisPushProperty(unsigned int oref, int plen, const Callin_char_t * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a property reference onto the argument stack.
Return Values for IrisPushProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
IrisPushPropertyH
Variants: IrisPushProperty, IrisPushPropertyW
int IrisPushPropertyH(unsigned int oref, int plen, const wchar_t * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a 4-byte Unicode property reference onto the argument stack.
Return Values for IrisPushPropertyH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushPropertyW
Variants: IrisPushProperty, IrisPushPropertyH
int IrisPushPropertyW(unsigned int oref, int plen, const unsigned short * pptr)
Arguments
oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description
Pushes a 2-byte Unicode property reference onto the argument stack.
Return Values for IrisPushPropertyW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_BADARG Invalid call argument.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushPtr
int IrisPushPtr(void * ptr)
Arguments
ptr Generic pointer.
Description
Pushes a pointer onto the argument stack in internal format.
Return Values for IrisPushPtr
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushRtn
Variants: IrisPushRtnW, IrisPushRtnH
int IrisPushRtn(unsigned int * rflag, int tlen, const Callin_char_t * tptr,
                 int nlen, const Callin_char_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a routine reference onto the argument stack. See IrisPushRtnX for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtn
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
IrisPushRtnH
Variants: IrisPushRtn, IrisPushRtnW
int IrisPushRtnH(unsigned int * rflag, int tlen, const wchar_t * tptr,
                  int nlen, const wchar_t * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 4–byte Unicode routine reference onto the argument stack. See IrisPushRtnXH for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnH
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushRtnW
Variants: IrisPushRtn, IrisPushRtnH
int IrisPushRtnW(unsigned int * rflag, int tlen, const unsigned short * tptr,
                  int nlen, const unsigned short * nptr)
Arguments
rflag Routine flags for use by IrisDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description
Pushes a 2–byte Unicode routine reference onto the argument stack. See IrisPushRtnXW for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.
Return Values for IrisPushRtnW
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisPushRtnX
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)
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)
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)
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.
IrisPushUndef
int IrisPushUndef()
Description
Pushes an Undefined value on the argument stack. The value is interpreted as an omitted function argument.
Return Values for IrisPushUndef
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_SUCCESS The operation was successful.
IrisReleaseAllLocks
int IrisReleaseAllLocks( )
Description
Performs an argumentless InterSystems IRIS LOCK command to remove all locks currently held by the process.
Return Values for IrisReleaseAllLocks
IRIS_SUCCESS The operation was successful.
IrisReleaseLock
int IrisReleaseLock(int nsub, int flg)
Arguments
nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of IRIS_IMMEDIATE_RELEASE and IRIS_SHARED_LOCK.
Description
Executes an InterSystems IRIS LOCK command to decrement the lock count for the specified lock name. This command will only release one incremental lock at a time.
Return Values for IrisReleaseLock
IRIS_FAILURE An unexpected error has occurred.
IRIS_SUCCESS Successful lock.
IrisSecureStartA
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)
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:
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)
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:
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)
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:
Return Values for IrisSecureStartW
IRIS_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
IRIS_ALREADYCON Connection already existed. Returned if you call IrisSecureStartH from a $ZF function.
IRIS_CHANGEPASSWORD Password change required. This return value is only returned if you are using InterSystems authentication.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEnd has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
IrisSetDir
int IrisSetDir(char * dir)
Arguments
dir Pointer to the directory name string.
Description
Dynamically sets the name of the manager's directory (IrisSys\Mgr) at runtime. On Windows, the shared library version of InterSystems IRIS requires the use of this function to identify the managers directory for the installation.
Return Values for IrisSetDir
IRIS_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
IRIS_SUCCESS Control function performed.
IrisSetProperty
int IrisSetProperty( )
Description
Stores the value of the property defined by IrisPushProperty. The value must be pushed onto the argument stack before this call.
Return Values for IrisSetProperty
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_SUCCESS The operation was successful.
IrisSignal
int IrisSignal(int signal)
Arguments
signal The operating system's signal value.
Description
Passes on signals caught by user's program to InterSystems IRIS.
This function is very similar to IrisAbort, but allows passing of any known signal value from a thread or user side of the connection to the InterSystems IRIS side, for whatever action might be appropriate. For example, this could be used to pass signals intercepted in a user-defined signal handler on to InterSystems IRIS.
Example
rc = IrisSignal(CTRL_C_EVENT); // Windows response to Ctrl-C
rc = IrisSignal(CTRL_C_EVENT); // UNIX response to Ctrl-C
Return Values for IrisSignal
IRIS_CONBROKEN Connection has been broken.
IRIS_NOCON No connection has been established.
IRIS_NOTINIRIS The Callin partner is not in InterSystems IRIS at this time.
IRIS_SUCCESS Connection formed.
IrisSPCReceive
int IrisSPCReceive(int * lenp, Callin_char_t * ptr)
Arguments
lenp Maximum length to receive. Modified on return to indicate number of bytes actually received.
ptr Pointer to buffer that will receive message. Must be at least lenp bytes.
Description
Receive single-process-communication message. The current device must be a TCP device opened in SPC mode, or IRIS_ERFUNCTION will be returned.
Return Values for IrisSPCReceive
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERFUNCTION Current device is not TCP device or is not connected.
IRIS_SUCCESS The operation was successful.
IrisSPCSend
int IrisSPCSend(int len, const Callin_char_t * ptr)
Arguments
len Length of message in bytes.
ptr Pointer to string containing message.
Description
Send a single-process-communication message. The current device must be a TCP device opened in SPC mode, or IRIS_ERFUNCTION will be returned.
Return Values for IrisSPCSend
IRIS_CONBROKEN Connection has been closed due to a serious error.
IRIS_NOCON No connection has been established.
IRIS_ERSYSTEM Either the database engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
IRIS_ERFUNCTION Current device is not TCP device or is not connected.
IRIS_ERARGSTACK Argument stack overflow.
IRIS_ERSTRINGSTACK String stack overflow.
IRIS_SUCCESS The operation was successful.
Any InterSystems IRIS error From translating a name.
IrisStartA
Variants: IrisStartW, IrisStartH
int IrisStartA(unsigned long flags, int tout, IRIS_ASTRP prinp, IRIS_ASTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
Return Values for IrisStartA
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartA from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndA has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
IRIS_ASTR inpdev;
IRIS_ASTR outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartA(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);
IrisStartH
Variants: IrisStartA, IrisStartW
int IrisStartH(unsigned long flags,int tout,IRISHSTRP prinp,IRISHSTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
Return Values for IrisStartH
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartH from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndH has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartH(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);
IrisStartW
Variants: IrisStartA, IrisStartH
int IrisStartW(unsigned long flags,int tout,IRISWSTRP prinp,IRISWSTRP prout)
Arguments
flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for InterSystems IRIS. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description
Calls into InterSystems IRIS to set up an InterSystems IRIS process.
The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.
Valid values for the flags variable are:
Return Values for IrisStartW
IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartW from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndW has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.
The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.
Example
An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.
inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = IrisStartW(IRIS_TTALL|IRIS_TTNOUSE,0,inpdev,outdev);
IrisTCommit
int IrisTCommit( )
Description
Executes an InterSystems IRIS TCommit command.
Return Values for IrisTCommit
IRIS_SUCCESS TCommit was successful.
IrisTLevel
int IrisTLevel( )
Description
Returns the current nesting level ($TLEVEL) for transaction processing.
Return Values for IrisTLevel
IRIS_SUCCESS TLevel was successful.
IrisTRollback
int IrisTRollback(int nlev)
Arguments
nlev Determines how many levels to roll back, (all levels if 0, one level if 1).
Description
Executes an InterSystems IRIS TRollback command. If nlev is 0, rolls back all transactions in progress (no matter how many levels of TSTART were issued) and resets $TLEVEL to 0. If nlev is 1, rolls back the current level of nested transactions (the one initiated by the most recent TSTART) and decrements $TLEVEL by 1.
Return Values for IrisTRollback
IRIS_SUCCESS TStart was successful.
IrisTStart
int IrisTStart( )
Description
Executes an InterSystems IRIS TStart command.
Return Values for IrisTStart
IRIS_SUCCESS TStart was successful.
IrisType
int IrisType( )
Description
Returns the native type of the item returned by IrisEvalA, IrisEvalW, or IrisEvalH as the function value.
Return Values for IrisType
IRIS_ASTRING 8-bit string.
IRIS_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
IRIS_DOUBLE 64-bit floating point.
IRIS_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
IRIS_IEEE_DBL 64-bit IEEE floating point.
IRIS_INT 32-bit integer.
IRIS_NOCON No connection has been established.
IRIS_NORES No result whose type can be returned (no call to IrisEvalA or IrisEvalW preceded this call).
IRIS_OREF InterSystems IRIS object reference.
IRIS_WSTRING Unicode string.
Example
rc = IrisType();
IrisUnPop
int IrisUnPop( )
Description
Restores the stack entry from IrisPop.
Return Values for IrisUnPop
IRIS_NORES No result whose type can be returned has preceded this call.
IRIS_SUCCESS The operation was successful.