Introduction

XEP is a lightweight .NET API that provides high-performance .NET persistence technology for simple to medium complexity object hierarchies. XEP projects the data in .NET objects as persistent events (database objects that store a persistent copy of the data fields), accessing the Caché database over a TCP/IP link. XEP is optimized for transaction processing applications that require extremely high speed data persistence and retrieval.

Installation and Configuration

This section provides specifies requirements and provides instructions for installing Caché and configuring your environment to use XEP.

Requirements

The .NET Framework, versions 2.0, 3.0, or 4.0.
Caché 2012.2 or higher.
The Caché User namespace must exist and must be writable if your application uses XEP (see “Using XEP Event Persistence”).

Installation

When installing Caché in Windows, select the Setup Type: Development option.
If Caché has been installed with security level 2, open the Management Portal and go to System Administration > Security > Services, select %Service_CallIn, and make sure the Service Enabled box is checked.
If you installed Caché with security level 1 (minimal) it should already be checked.

Required Environment Variables

In order to run XEP applications, the following environment variable must be properly set:

Your PATH environment variable must include <install-dir>/bin.
If your PATH variable includes more than one <install-dir>/bin path (for example, if you have installed more than one instance of Caché) only the first one will be used, and any others will be ignored.

Required Files

Your .NET project must include references to the following files:

InterSystems.CacheExtreme.dll — located in <install-dir>/dev/dotnet/bin/v2.0.50727
InterSystems.Data.CacheClient.dll — is provided in three different versions, one for each supported release of the .NET Framework. The different versions are located in appropriately named subdirectories of <install-dir>/dev/dotnet/bin (for example, <install-dir>/dev/dotnet/bin/v4.0.30319 contains the file for .NET 4.0). Use the appropriate file for the release that will be used to compile your project.

XEP Samples

XEP sample files are in <install-dir>/dev/dotnet/samples/xep/ (see “Default Caché Installation Directory” for the location of <install-dir> on your system). To run them, compile the XEPTest40.csproj project, which includes the following components (located in subdirectory /xep/test/):

RunAll.cs — is a program that runs all of the other sample programs in sequence.
This program connects to Caché with a hard-coded superserver port value of 1972 (see “DefaultPort” in the Caché Parameter File Reference). If your system does not use this default value, change the port number in the first line of the program and recompile.
Coverage.cs — tests basic functionality such as connecting, importing a schema, storing, querying, updating and deleting XEP events. It also exercises most of the supported data types.
SingleString.cs — is the most basic XEP test program. It connects to the database, imports a simple class containing only one string field, then stores and loads a number of events corresponding to that class.
FlightLog.cs — is an example that demonstrates the XEP full inheritance model. It tracks airline flight information such as times, locations, personnel, and passengers.
Benchmark.cs — is a performance test for the XEP API.
IdKeys.cs — extends the Benchmark test by adding the composite IdKey feature.
Threads.cs — is a multithreaded XEP test program.

See the help file (<install-dir>/dev/dotnet/help/CacheExtreme.chm) for detailed documentation of these programs. Supporting files located in <install-dir>/dev/dotnet/samples/xep/samples/ provide test data for the sample programs. The xep.samples.SingleStringSample class is used by several examples in this book.