Callin Programming Tips

Limits on the number of open files

Your program must ensure that it does not open so many files that it prevents InterSystems IRIS from opening the number of databases or other files it expects to be able to. Normally, InterSystems IRIS looks up the user's open file quota and reserves a certain number of files for opening databases, allocating the rest for the Open command. Depending on the quota, InterSystems IRIS expects to have between 6 and 30 InterSystems IRIS database files open simultaneously, and from 0 to 36 files open with the Open command.

Maximum Directory Length for Callin Applications

The directory containing any Callin application must have a full path that uses fewer than 232 characters. For example, if an application is in the C:\IrisApps\Accounting\AccountsPayable\ directory, this has 40 characters in it and is therefore valid.

Call IrisEnd after IrisStart before halting

If your connection was established by a call to IrisStart, then you must call IrisEnd when you are done with the connection. You can make as many Callin function calls in between as you wish.

You must call IrisEnd even if the connection was broken. The connection can be broken by a call to IrisAbort with the RESJOB parameter.

IrisEnd performs cleanup operations which are necessary to prepare for another call to IrisStart. Calling IrisStart again without calling IrisEnd (assuming a broken connection) will return the code IRIS_CONBROKEN.

Wait until ObjectScript is done before exiting

If you are going to exit your program, you must be certain ObjectScript has completed any outstanding request. Use the Callin function IrisContext to determine whether you are within ObjectScript. This call is particularly important in exit handlers and Ctrl-C or Ctrl-Y handlers. If IrisContext returns a non-zero value, you can invoke IrisAbort.

Maintaining Margins in Callin Sessions

While you can set the margin within a Callin session, the margin setting is only maintained for the rest of the current command line. If a program (as with direct mode) includes the line:

:Use 0:10 Write x

the margin of 10 is established for the duration of the command line.

Certain calls affect the command line and therefore its margin. These are the calls are annotated as "calls into InterSystems IRIS" in the function descriptions.

Avoid signal handling when using IrisStart()

IrisStart sets handlers for various signals, which may conflict with signal handlers set by the calling application.

Limitations on building Callin applications using the iris shared library (irisdb.dll)

When Callin applications are built using the shared library irisdb.dll, users who have large global buffer pools may see the Callin fail to initialize (in IrisStart) with an error:

<InterSystems IRIS Startup Error: Mapping shared memory (203)>

The explanation for this lies in the behavior of system DLLs loading in Windows. Applications coded in the Win 32 API or with the Microsoft Foundation Classes (the chief libraries that support Microsoft Visual C++ development) need to have the OS load the DLLs for that Windows code as soon as they initialize. These DLLs get loaded from the top of virtual storage (higher addresses), reducing the amount of space left for the heap. On most systems, there are also a number of other DLLs (for example, DLLs supporting the display graphics) that load automatically with each Windows process at locations well above the bottom of the virtual storage. These DLLs have a tendency to request a specific address space, most commonly 0X10000000 (256MB), chopping off a few hundred megabytes of contiguous memory at the bottom of virtual memory. The result may be that there is insufficient virtual memory space in the Callin executable in which to map the InterSystems IRIS shared memory segment.

Do not disable interrupt delivery on UNIX®

UNIX® uses interrupts. Do not prevent delivery of interrupts.

Avoid using reserved signals

On UNIX®, InterSystems IRIS uses a number of signals. If possible, application programs linked with InterSystems IRIS should avoid using the following reserved signals:

If your application uses these signals, you should be aware of how InterSystems IRIS deals with them. See Threads and UNIX® Signal Handling for details.