Skip to main content

IrisStartA

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 principal device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for InterSystems IRIS. An empty string (prout.len == 0) implies using the principal device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into InterSystems IRIS to set up an InterSystems IRIS process.

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a connection, InterSystems IRIS does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • IRIS_PROGMODE — InterSystems IRIS should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by InterSystems IRIS results in closing the connection and returning error IRIS_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • IRIS_TTALL — Default. InterSystems IRIS should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • IRIS_TTCALLIN — InterSystems IRIS should initialize the terminal each time it is called but should restore it only when IrisEnd is called or the connection is broken.

  • IRIS_TTSTART — InterSystems IRIS should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • IRIS_TTNEVER — InterSystems IRIS should not alter the terminal's settings.

  • IRIS_TTNONE — InterSystems IRIS should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • IRIS_TTNOUSE — This flag is allowed with IRIS_TTALL, IRIS_TTCALLIN, and IRIS_TTSTART. It is implicitly set by the flags IRIS_TTNEVER and IRIS_TTNONE. It indicates that InterSystems IRIS Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for IrisStartA

IRIS_ALREADYCON Connection already existed. Returned if you call IrisStartA from a $ZF function.
IRIS_CONBROKEN Connection was formed and then broken, and IrisEndA has not been called to clean up.
IRIS_FAILURE An unexpected error has occurred.
IRIS_STRTOOLONG prinp or prout is too long.
IRIS_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want InterSystems IRIS to set terminal characteristics. The safest, but slowest, route is to have InterSystems IRIS set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter IRIS_TTNEVER requires the least overhead.

Example

An InterSystems IRIS process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for an InterSystems IRIS backup. Output appears on the terminal.

IRIS_ASTR inpdev;
IRIS_ASTR outdev;
int rc;

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

FeedbackOpens in a new tab