Table of Contents


NxCoreSystem

The structure NxCoreSymbol is defined in NxCoreAPI.h as:


struct NxCoreSystem {
    int             UserData;
    int             DLLVersion;
    NxDate          nxDate;
    NxTime          nxTime;
    int             ClockUpdateInterval;
    int             Status;
    int             StatusData;
    const char*     StatusDisplay;
    const char*     TapeDisplay;
    void*           Module;
    void*           ThreadInstance;
    const char*     PermissionSet;
    NxAccessStatus* pNxAStatus;
};

UserData

The first data member of NxCoreSystem is an int named UserData. The value of UserData is set to the value passed as the 4th argument to the NxCoreAPI function NxCoreProcessTape. Recall from Chapter 1:


nxcore.ProcessTape("20050104.AA.nxc", 0, 0, 123, OnNxCoreCallback);

Note that the 4th parameter has the value of 123 in our example code. When nxapiProcessTape is called, NxCoreAPI.dll immediately stores the 4th parameter inNxCoreSystem.UserData, and never references or changes the value. This feature is especially useful when processing multiple NxCore Tape's simultaneously, and also for passing instance data to your callback function (a pointer to your class for example).

There is one exception to rule #1, and that is you may change the value of the UserData member in the NxCoreSystem structure. The data member UserData is never used by NxCoreAPI, and is reserved for your exclusive use. In order to change the value, you simply need to cast pNxCoreSystem to a pointer that isn't const as shown in this example:


int processNxCoreSystem(const NxCoreSystem* pNxCoreSys)
{
                    pNxCoreSys->UserData  = 256;  // generates a compiler error.
    ((NxCoreSystem*)pNxCoreSys)->UserData = 256;  // cast tells compiler we know what we are doing.

The first attempt at changing UserData (or any member of pNxCoreSys) results in a compiler error. The last line illustrates how to cast pNxCoreSys to (NxCoreSystem*) without the const keyword: this casting tells the compiler we know what we are doing.

DLLVersion

The value stored in the data member DLLVersion contains the version of the NxCoreAPI.dll that is processing the NxCore file and calling your callback function. The DLLVersion will not change during the processing of an NxCore Tape.

nxDate and nxTime

The next two data members of NxCoreSystem, nxDate and nxTime, convey information on the most recent timestamp generated by the NxCore Feed Timestamp. The NxCore Feed Timestamp is added by the NxCore Feed Processor when it first receives Exchange data. These timestamps are created in regular intervals (currently at 25 milliseconds), but only update when other data messages are present or when 1 second elapses. During active trading, you will generally see a NxCore Feed Timestamp every 25 milliseconds. Overnight, you may one receive only one each second.

When processing the real-time stream, you can compare the NxCore Feed Timestamp values with your local clock to gauge connection characteristics, such as processing delays or bursting. NxCoreAccess in fact uses the NxCore Feed Clock for just such purposes. When processing a historic NxCore Tape, the timestamps will be the same values as when they were captured -- which allows you to precisely recreate time events during in the order they occurred during real-time processing. You can even simulate real-time down to a 25 millisecond resolution with little effort using NxCore Feed Timestamp.

The NxCore Feed Timestamps have the following characteristics:

The nxDate and nxTime members use the structures NxDate and NxTime respectively. These structures are also used in other structures in NxCoreAPI and are discussed in more detail at NxDate and NxTime.

ClockUpdateInterval

The data member ClockUpdateInterval is set to one of the following values to indicate the change of the NxCore Feed Timestamp since the last timestamp. From NxCoreAPI.h:

#define Value Comments
NxCLOCK_NOCHANGE 0 Indicates that the NxCore Feed Timestamp has not changed.
NxCLOCK_CLOCK 1 Indicates that the member nxTime.Millisecond has changed (but not Second, Minute, or Hour)
NxCLOCK_SECOND 2 Indicates that the member nxTime.Second has changed (as has Millisecond, but not Minute or Hour).
NxCLOCK_MINUTE 3 Indicates that the member nxTime.Minute has changed (as has Millisecond and Second, but not Hour).
NxCLOCK_HOUR 4 Indicates that the member nxTime.Hour has changed (as has Millisecond, Second, and Minute).

The ClockUpdateInterval indicates most significant member of the nxTime structure that changed. The members may have changed by one or more units. During inactive periods, for example, the millisecond value may change from 25 to 975 milliseconds (any more than 975 milliseconds, and the data member nxTime.Second would have changed). The ClockUpdateInterval provides for efficient scheduling code as illustrated:


int processNxCoreStatus(const NxCoreSystem* pNxCoreSys)
{
    if( pNxCoreSystem->ClockUpdateInterval >= NxCLOCK_ON_SECOND ) {

        processOneSecondAnalysis();

        if( pNxCoreSystem->ClockUpdateInterval >= NxCLOCK_ON_MINUTE ) {  // MINUTE or HOUR
            
            // 9:00,9:01,9:02,9:03.. 9:07 another minute elapsed.. run one minute analysis procedure.
            processOneMinuteAnalysis();

            if( pNxClock->nxTime.Minute % 5 == 0 ) { // on 5 minute interval. 9:00,9:05,9:10, etc
                processFiveMinuteAnalysis();
            }

            if( pNxCoreSystem->ClockUpdateInterval == NxCLOCK_ON_HOUR ) {  // HOUR
                processOneHourAnalysis();
            }
        }
    }
}

Status, StatusData and StatusDisplay

The three data members following UserData: Status, StatusData, and StatusDisplay are all related and tell you information about the Status of the system. The member Status will be set to one of the following values #defined below in NxCoreAPI.h, while StatusDisplay is simply text display combining Status and StatusData

#define Value Comments
NxCORESTATUS_RUNNING 0 Signals that processing is proceeding normally.
NxCORESTATUS_INITIALIZING 1 Signals that NxCoreAPI has started processing a real-time or historic tape. The first callback message is always NxMSG_STATUS with the Status member set to NxCORESTATUS_INITIALIZING. You will not get another message with this value unless recoverable errors are encountered by NxCoreAPI.
NxCORESTATUS_COMPLETE 2 Signals that NxCoreAPI has completed processing a tape. This is the last message callback you will receive regarding a tape. You will always get this message unless you abort processing by returning a value of NxCOREBACKRETURN_STOP in your callback.
NxCORESTATUS_SYNCHRONIZING 3 Synchronization reset detected in the tape, continuing processing
NxCORESTATUS_ERROR 4 Signals that an error was encountered by NxCoreAPI when processing a Tape. More information on the error encountered may be available in the members StatusData and StatusDisplay.
NxCORESTATUS_WAITFORACCESS 5 If NxCoreAccess is not present (perhaps it was temporarily stopped because you upgraded it, for example), system will wait for it to return at the point it left off and it will set the value of Status to this value at regular intervals. This allows your application to take special action, or terminate the processing of the NxCore Tape.
NxCORESTATUS_RESTARTING_TAPE 6 Signals that your callback returned NxCALLBACKRETURN_RESTART from a previous callback, and system is restarting the same tape from the beginning
NxCORESTATUS_LOADED_STATE 7 System is initialized from state
NxCORESTATUS_SAVING_STATE 8 System will capture the state after this message
NxCORESTATUS_SYMBOLSPIN 9 signals system symbol spin state: StatusData == 0 when starting, 1 when complete

If Status: StatusData:
NxCORESTATUS_RUNNING
#define Value Comments
NxCSRUNMODE_SRC_DISK_FILE 0 processing from a tape on disk
NxCSRUNMODE_SRC_ACCESS_FILE 1 processing from NxCoreAccess's file -- dll has not yet reached memory buffers
NxCSRUNMODE_SRC_ACCESS_MEMORY 2 processing from NxCoreAccess's memory buffers
NxCSRUNMODE_SRC_ACCESS_MB_OLDEST 2 processing oldest of NxCoreAccess's memory buffers
NxCSRUNMODE_SRC_ACCESS_MB_LOWER 3 processing older half of NxCoreAccess's memory buffers
NxCSRUNMODE_SRC_ACCESS_MB_UPPER 4 processing most recent half of NxCoreAccess's memory buffers
NxCSRUNMODE_SRC_ACCESS_MB_SECOND 5 processing 2nd most recent.
NxCSRUNMODE_SRC_ACCESS_MB_CURRENT 6 processing most recent of NxCoreAccess's memory buffers
NxCORESTATUS_INITIALIZING 0
NxCORESTATUS_COMPLETE 0
NxCORESTATUS_SYNCHRONIZING
NxCORESTATUS_ERROR
NxCORESTATUS_WAITFORACCESS 0
NxCORESTATUS_RESTARTING_TAPE 0
NxCORESTATUS_LOADED_STATE The size of the state in the specified file. Note that the file may be larger that the state if the user appends additional data to it as shown here
NxCORESTATUS_SAVING_STATE
#define Value Comments
NxCSSAVESTATE_CAPTURE 0 the core state will be captured after you return from this callback
NxCSSAVESTATE_COMPLETE 1 the save core state operation is complete
NxCSSAVESTATE_ERR_CREATEFILE -1 failed to open the specified tape filename
NxCSSAVESTATE_ERR_DISKSPACE -2 not enough disk space to complete the operation
NxCSSAVESTATE_ERR_MEMORY -3 insufficient memory to complete the operation
NxCORESTATUS_SYMBOLSPIN
#define Value Comments
NxCSSYMBOLSPIN_STARTING 0 the system symbol spin is starting -- note -- status will return NxCORESTATUS_RUNNING after this message
NxCSSYMBOLSPIN_COMPLETE 1 the system symbol spin has completed

The following code is our new function processNxCoreSystem with code that processes the Status member of


int processNxCoreStatus(const NxCoreSystem* pNxCoreSys)
{
    switch( pNxCoreSys->Status ) {
        case NxCORESTATUS_RUNNING:       // all is well.
            break;
        case NxCORESTATUS_INITIALIZING:  // start up code.
            break;
        case NxCORESTATUS_COMPLETE:      // tear down code.
            break;
        case NxCORESTATUS_ERROR:
            print("Error %s (%d)\n:", pNxCoreSys->StatusDisplay, pNxCoreSys->StatusData);
            return NxCALLBACKRETURN_STOP;// not required to return this
    }

    return NxCALLBACKRETURN_CONTINUE;
}

TapeDisplay

Text string from the header of the tape.

Module

Module of the dll for the calling process

ThreadInstance

ThreadInstance is used internally by NxCoreAPI when processing advanced functions.

PermissionSet

text of PermissionSet "AA", etc.

pNxAStatus

During real-time processing, status of NxCoreAccess. Updated once per second.