The Callin Interface

8-bit String Data Types

Caché supports the following data types that use local 8-bit string encoding:

• CACHE_ASTR — counted string of 8-bit characters

• CACHE_ASTRP — Pointer to an 8-bit counted string

The type definition for these is:

#define CACHE_MAXSTRLEN 32767
typedef struct {
   unsigned short  len;
   Callin_char_t   str[CACHE_MAXSTRLEN];
} CACHE_ASTR, *CACHE_ASTRP;

The CACHE_ASTR and CACHE_ASTRP structures contain two elements:

• len — An integer. When used as input, this element specifies the actual length of the string whose value is supplied in the str element. When used as output, this element specifies the maximum allowable length for the str element; upon return, this is replaced by the actual length of str.

• str — A input or output string.

CACHE_MAXSTRLEN is the maximum length of a string that is accepted or returned. A parameter string need not be of length CACHE_MAXSTRLEN nor does that much space have to be allocated in the program.

2–byte Unicode Data Types

Caché supports the following Unicode-related data types on platforms that use 2–byte Unicode characters:

• CACHEWSTR — Unicode counted string

• CACHEWSTRP — Pointer to Unicode counted string

The type definition for these is:

typedef struct { 
   unsigned short len; 
   unsigned short str[CACHE_MAXSTRLEN]; 
} CACHEWSTR, *CACHEWSTRP;

The CACHEWSTR and CACHEWSTRP structures contain two elements:

• len — An integer. When used as input, this element specifies the actual length of the string whose value is supplied in the str element. When used as output, this element specifies the maximum allowable length for the str element; upon return, this is replaced by the actual length of str.

• str — A input or output string.

CACHE_MAXSTRLEN is the maximum length of a string that is accepted or returned. A parameter string need not be of length CACHE_MAXSTRLEN nor does that much space have to be allocated in the program.

On Unicode-enabled versions of Caché, there is also the data type CACHE_WSTRING, which represents the native string type on 2–byte platforms. CacheType returns this type. Also, CacheConvert can specify CACHE_WSTRING as the data type for the return value; if this type is requested, the result is passed back as a counted Unicode string in a CACHEWSTR buffer.

4–byte Unicode Data Types

Caché supports the following Unicode-related data types on platforms that use 4–byte Unicode characters:

• CACHEHSTR — Extended Unicode counted string

• CACHEHSTRP — Pointer to Extended Unicode counted string

The type definition for these is:

typedef struct {
   unsigned int len;
   wchar_t str[CACHE_MAXSTRLEN];
} CACHEHSTR, *CACHEHSTRP;

The CACHEHSTR and CACHEHSTRP structures contain two elements:

• len — An integer. When used as input, this element specifies the actual length of the string whose value is supplied in the str element. When used as output, this element specifies the maximum allowable length for the str element; upon return, this is replaced by the actual length of str.

• str — A input or output string.

CACHE_MAXSTRLEN is the maximum length of a string that is accepted or returned. A parameter string need not be of length CACHE_MAXSTRLEN nor does that much space have to be allocated in the program.

On Unicode-enabled versions of Caché, there is also the data type CACHE_HSTRING, which represents the native string type on 4–byte platforms. CacheType returns this type. Also, CacheConvert can specify CACHE_HSTRING as the data type for the return value; if this type is requested, the result is passed back as a counted Unicode string in a CACHEHSTR buffer.

System-neutral Symbol Definitions

The allowed inputs and outputs of some functions vary depending on whether they are running on an 8-bit system or a Unicode system. For many of the “A” (ASCII) functions, the arguments are defined as accepting a CACHESTR, CACHE_STR, CACHESTRP, or CACHE_STRP type. These symbol definitions (without the “A” , “W”, or “H”) can conditionally be associated with either the 8-bit or Unicode names, depending on whether the symbols CACHE_UNICODE and CACHE_WCHART are defined at compile time. This way, you can write source code with neutral symbols that works with either local 8-bit or Unicode encodings.

The following excerpt from callin.h illustrates the concept:

#if defined(CACHE_UNICODE) /* Unicode character strings */
#define   CACHESTR      CACHEWSTR
#define   CACHE_STR     CACHEWSTR
#define   CACHESTRP     CACHEWSTRP
#define   CACHE_STRP    CACHEWSTRP
#define   CACHE_STRING  CACHE_WSTRING

#elif defined(CACHE_WCHART)  /* wchar_t character strings */
#define   CACHESTR      CACHEHSTR
#define   CACHE_STR     CACHEHSTR
#define   CACHESTRP     CACHEHSTRP
#define   CACHE_STRP    CACHEHSTRP
#define   CACHE_STRING  CACHE_HSTRING

#else                  /* 8-bit character strings */
#define   CACHESTR      CACHE_ASTR
#define   CACHE_STR     CACHE_ASTR
#define   CACHESTRP     CACHE_ASTRP
#define   CACHE_STRP    CACHE_ASTRP
#define   CACHE_STRING  CACHE_ASTRING
#endif

Threads and UNIX® Signal Handling

On UNIX®, Caché uses a number of signals. If your application uses the same signals, you should be aware of how Caché deals with them. All signals have a default action specified by the OS. Applications may choose to leave the default action, or can choose to handle or ignore the signal. If the signal is handled, the application may further select which threads will block the signal and which threads will receive the signal. Some signals cannot be blocked, ignored, or handled. Since the default action for many signals is to halt the process, leaving the default action in place is not an option. The following signals cannot be caught or ignored, and terminate the process:

The actions that an application establishes for each signal are process-wide. Whether or not the signal can be delivered to each thread is thread-specific. Each thread may specify how it will deal with signals, independently of other threads. One thread may block all signals, while another thread may allow all signals to be sent to that thread. What happens when a signal is sent to the thread depends on the process-wide handling established for that signal.

Tips for All Callin Programs

Your external program must follow certain rules to avoid corrupting Caché data structures, which can cause a system hang.

• Limits on the number of open files

  Your program must ensure that it does not open so many files that it prevents Caché from opening the number of databases or other files it expects to be able to. Normally, Caché 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, Caché expects to have between 6 and 30 Caché 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:\CacheApps\Accounting\AccountsPayable\ directory, this has 40 characters in it and is therefore valid.

• Call CacheEnd after CacheStart before halting

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

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

  CacheEnd performs cleanup operations which are necessary to prepare for another call to CacheStart. Calling CacheStart again without calling CacheEnd (assuming a broken connection) will return the code CACHE_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 CacheContext to determine whether you are within ObjectScript. This call is particularly important in exit handlers and Ctrl-C or Ctrl-Y handlers. If CacheContext returns a non-zero value, you can invoke CacheAbort.

• 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 Caché" in the function descriptions.

• Avoid signal handling when using CacheStart()

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

Tips for Windows

These tips apply only to Windows.

• Limitations on building Callin applications using the cache shared library (cache.dll)

  If Callin applications are built using the shared library (cache.dll) rather that the static object (cache.obj), users who have large global buffer pools may see the Callin fail to initialize (in CacheStart) with an error:

  <Cache 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 Cache shared memory segment.

Tips for UNIX®, Linux, and Mac OS

These tips apply only to UNIX®, Linux, and Mac OS.

• Do not disable interrupt delivery on UNIX®

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

• Use the correct version of XCode

  Versions of Caché for Mac OS X (32–bit) previous to 2010.2 were built using the Xcode 2.5 compiler. Callin programs for these versions of Caché must be built using the same compiler. If your development platform is Mac OS X 10.5 (Leopard) or later, you would have to load and use Xcode 2.5 in place of the default Xcode 3.0 compiler.

• Avoid using reserved signals

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

  SIGABRT	SIGDANGER	SIGILL	SIGQUIT	SIGTERM	SIGVTALRM
  SIGALRM	SIGEMT	SIGINT	SIGSTOP	SIGTRAP	SIGXCPU
  SIGBUS	SIGFPE	SIGKILL	SIGSEGV	SIGUSR1	SIGXFSZ
  SIGCHLD	SIGHUP	SIGPIPE	SIGSYS	SIGUSR2

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