The P2 CGate library consists of the following components:

All these components are required for development using the P2 CGate library.

To begin development, it is necessary to install the components by the installer corresponding to your operation system. Depending on the operation system, the libraries and the header file will be installed either into default locations or into locations specified during installation process. In further instructions the installation folder will be specified as ‘CGATE_HOME’.

Building and running examples may be performed to verify whether installation has finished correctly and the system is ready for development. To do this, it is necessary to perform the following steps:

make_c_samples.sh

make_java_samples.sh

The library introduces a set of objects which are used to get access to different functions of the system. The main objects are:

The Listener and Publisher objects are tied to particular connections. You may use numerous connections, numerous listeners and publishers depending on the architecture of your application; usually, connections for receiving updates of market information are separated from connections for sending orders.

The general scheme of the library objects within the client program is the following:

General environment may include several connections; each connection contains arbitrary number of listeners and publishers and each of them has a certain number of messages. In actual practice, the purpose of each connection and listeners and publishers linked with this connection usually depends on actual demands of the application.

Each Cgate object (connection, listener and publisher) has a special parameter in its URL settings, which is responsible for naming object within the system. The object name must be unique, otherwise the system will return the 'CG_ERR_INVALIDARGUMENT' error message. The 'name' parameter is not mandatory; by default, Cgate names object as 'noname_%d', where %d is a number. It is recommended to users to name the objects for ease of reading Cgate logs.

In Cgate, users are responsible for lifetimes of all objects. The '_new' methods allow to create an object, while the '_destroy' methods allow to destroy them. In order to prevent memory and system recourses leaks, it is recommended to use a conjugate destroying method.

All functions in Cgate are reenterable, except the following ones:

The 'lsn_close' and 'conn_close' functions can be called only after receiving the 'CG_MSG_OPEN' message.

If there is the 'mq reply' publisher is used, then it should be opened first. Otherwise, we may receive the 'mq' message trying opening a listener without any opened publisher.

To start work with the library, it is required to perform initialization of environment. Initialization is performed via the ‘env_open’ function:

The function accepts string that describes parameters of the system. The string is a set of ‘KEY=VALUE’ pairs separated by a semicolon. The following parameters are available:

Failure of initialization may indicate a configuration error: the configuration file may be missed or installation integrity may be corrupted, etc. In case of this failure, there is no use trying to perform re-initialization of libraries; instead of this, you should shutdown your program and check the configuration.

If initialization fails or was not performed, it is not possible to work with the other functions of the library.

Initialization code of the system may look like:

result = cg_env_open("ini=ini/settings.ini;key=72395823576");
if (result != CG_ERR_OK)
{
    // display an error message and exit the program
    ...
    return;
}

Which means successful initialization of the library with the ‘configuration ini/settings.ini' file and the application key '72395823576'. The 'ini/settings.ini' file should be accessible via the specified path relatively to the current work directory at the moment of program start.

Deinitialization is performed before exiting the program by calling the 'env_close' function:

The function performs deinitialization of sub-systems and closure of the operating log. This function must be always called in the end of program operation.

[p2syslog]
logfile=./log/send.log // path to log file;
traceini=./log/send.trace.ini //file name to add traces into
logfileperday=0 // new file per day
logfilenametype=1
logtime=2  // time output format
logfilecache=1024  // file cash size;
logtoconsole=0  // output to comsole;
logtosyslog=0  // log into 'syslog';
logasync=1  // non-synchronous logging;
addthreadid=1  // add 'id thread' ( a new thread is added for 'logasync=1',
for IO operations with disk).

The ‘Connection’ object provides interaction with the Plaza-2 router for sending and receiving messages. These objects may be created in any quantity at any time during program operation with initialized environment; nevertheless, it is recommended to make connections at the start of program and to destroy them just before exiting.

Connection is created by calling ‘cg_conn_new’, for instance, in the following way:

cg_conn_t* conn;
result = cg_conn_new("p2tcp://127.0.0.1:4001;app_name=test", &conn);

In this example, a connection via the TCP/IP protocol with the Plaza-2 router on the port 4001 initiated on the same computer and with the application name ‘test’ created. Calling this function initializes connection object but doesn’t lead to actual establishment of connection.

Connection is established by calling the 'conn_open' function:

result = cg_conn_open(conn, 0);

, where ‘conn’ — the object initialized by the ‘cg_conn_new’ function call, and 0 (as the second parameter) means absence of connection opening call parameters.

Connection is closed by calling ‘conn_close’:

result = cg_conn_close(conn);

In this case, interaction with the Plaza-2 router is closed but the object remains initialized and may be reopened.

Object is destroyed by the ‘conn_destroy’ function:

result = cg_conn_destroy(conn);

Initialization of connection may fail when installation integrity is corrupted or when there is incorrect configuration, e.g. incorrect parameters have been specified. In this case, the best things to do are to shutdown program and analyze the configuration.

Opening of connection may fail with an error due to different reasons, e.g. the Plaza-2 router is not ready to service incoming connections, there is a failure in the communication channel, etc. Opening of connection should be performed in a cyclical manner since the next attempt of opening may become successful.

Example of the described behavior:

cg_conn_t* conn;
result = cg_conn_new("p2tcp://127.0.0.1:4001;app_name=test", &conn);
if (result != CG_ERR_OK) 
{
    // failure of connection initialization
    // further work is impossible
    // report on the error and exit the program
    return;
}

// initialized object conn exists in this place,
// this object may be worked with — get its status, open, close

while (haveToExit()) // main loop of the program
{
    uint32_t state;
    result = cg_conn_getstate(conn, state); // get a status of connection
    if (result != CG_ERR_OK) // error in getting the connection status
    {
        // report the error and exit the program
        return;
    }
    switch (state)
    {
    case CG_STATE_CLOSED: // connection is closed, try to open
        result = cg_conn_open(conn, 0);
        // make a report in case of error
        break;
    case CG_STATE_ERROR: // connection is in the error state, it should be closed
        result = cg_conn_close(conn);
        // make a report in case of error
        break;
    case CG_STATE_ACTIVE: // connection is active, it may be worked with
        ...
    }
    ...
}

This cycle implements correct work with connection: if connection is closed, an attempt will be made to open it; if connection went to the error state, then it will be closed. Work with connection is performed when it is active.

This example uses the cg_conn_getstate function:

uint32_t state;
result = cg_conn_getstate(conn, state);

This function returns the state of the initialized ‘Connection’object. Messages may be sent and received only when the corresponding connection is in the ‘active’ state ('CG_STATE_ACTIVE').

Being in the active state, the connection requires periodical calling of the event processing the ‘conn_process’ function, which performs calling of user-defined callback functions and internal processing:

case CG_ACTIVE:
{
    result = cg_conn_process(conn, 0, 0);
    if (result != CG_ERR_OK && result != CG_ERR_TIMEOUT)
    {
        // connection work is broken 
        result = cg_conn_close(conn);
    }
    ...
    break;
}

The ‘conn_process’ function uses the second parameter as a time interval in milliseconds which is the time to wait for new event to take place within the connection framework. Awaiting the new calls, the ‘conn_process’ call is blocked. If there were no messages during the specified time interval, the function will return the ‘CG_ERR_TIMEOUT’ value — in this case, this value is not an error indicator and may be used, for instance, to indicate that there are no incoming messages and that program logics may pass to the next task. The third parameter is reserved.

Attention! If the second parameter value is 0, the lock mode will be off, and CPU load may reach 100%.

Data streams are received by means of the ‘Listener’ objects. The ‘Listener’ object is created linked to connection with ‘cg_lsn_new’ call:

result = cg_lsn_new(conn, "p2repl://FORTS_FUTTRADE_REPL", dataCB, user_data, &lsn);

In this example, ‘lsn’ is initialized by the ‘Listener’ object, which is set for receiving of the ‘FORTS_FUTINFO_REPL’ data stream via the connection conn. Messages on data updates and on other events of the stream life cycle will be passed to the user-defined ‘dataCB’ callback function. When creating a subscription, it is possible to set different parameters including the client replication scheme; in this case, initialization of the object will be performed in the following way:

result = cg_lsn_new(conn, 
               "p2repl://FORTS_FUTTRADE_REPL;scheme=|FILE|ini/futtrade.ini|FutTrade", 
               dataCB, user_data, &lsn);

, where the scheme description file path and the section name of the corresponding ini-file are set in the ‘scheme’ parameter by the string of a special format.

Upon successful calling of the ‘cg_lsn_new’ function, the object goes into the initialized but non-active state. In fact, the stream is opened by calling the ‘cg_lsn_open’ function:

result = cg_lsn_open(lsn, 0);

In this example, the data stream is opened without parameters, which means that it will be opened with default parameters:

Parameters are specified as a string:

result = cg_lsn_open(lsn, "mode=online");

In this case, the stream will be opened on the online mode which skips the initial snapshot stage. In the online mode, if connection is lost, data stream continuity will not be guaranteed. See description of the ‘cg_lsn_open’ function for detailed information on supported parameters.

The ‘cg_lsn_open’ function may return the error code in different cases: temporary unavailability of the stream, malfunction of the channel operation. For correct operation it is required to perform cyclical opening of flows.

The stream is closed by calling the ‘cg_lsn_close’ function:

result = cg_lsn_close(lsn);

In this case, the listener is disconnected from data receiving, and updates of this stream are no longer transmitted through the connection; the object itself remains initialized and may be reopened, including opening with different parameters.

The object is destroyed by calling ‘cg_lsn_destroy’:

result = cg_lsn_destroy(lsn);

After that, the ‘lsn’ object is released, and the further work with this object becomes impossible.

For correct receiving the data updates, the ‘Listener’ object must call the ‘conn_process’ function for the connection to the object it is tied to. Data receiving frequency does not exceed the frequency of the ‘conn_process’ function calling. Therefore, in order to provide maximum data receiving speed it is required to provide maximum possible frequency of the ‘conn_process’ function calling for desired connections. When the 'con_process' call is absent for connection within timeout = 3 time interval, the listener will be disconnected.

Receiving of data and occurrence of other events in the life cycle of the data stream is accompanied by calling of the user-defined ‘lsn_new’ callback function which looks like:

typedef CG_RESULT (*CG_LISTENER_CB)(cg_conn_t* conn, 
                                          cg_listener_t* listener, 
                                          struct cg_msg_t* msg, 
                                          void* data);

The following information is transferred to the callback function:

The ‘msg’ message which is transferred to the user-defined function is generally described by the following structure:

struct cg_msg_t
{
    uint32_t type;     // Message type
    size_t data_size;  // Amount of data
    void* data;        // Pointer to data
};

Any message, which is delivered to the user-defined function, has the listed fields in any case.

Particular message type is identified with the ‘type’ field analysis. The following message types are used when data stream is received:

When the ‘CG_MSG_P2REPL_DATA’ event occurs, the ‘msg’ parameter of the user-defined callback function contains pointer to the extended data structure:

struct cg_msg_streamdata_t 
{
    uint32_t type;   // Message type. Always CG_MSG_P2REPL_DATA for this message
    size_t data_size;  // Data amount
    void* data;        // Data indicator
    size_t msg_index;  // Number of the message description in the active scheme 
    uint32_t msg_id;   // Unique identifier of the message type
    const char* msg_name; // Message name in the active scheme
    int64_t rev;          // Record revision
    const uint8_t* nulls; // Byte array containing 1 for each field which is considered to be NULL.
};

The extended structure is accessed in the following way:

CG_RESULT dataCallback(rtscg_conn_t* conn, 
                           rtscg_listener_t* listener, 
                           struct rtscg_msg_t* msg, 
                           void* data)
{
    switch(msg->type)
    {
        case CG_MSG_STREAM_DATA:
        {
             // bringing the indicator to the extended structure
            cg_msg_streamdata_t* replmsg = (cg_msg_streamdata_t*)msg;
            // extended structure may be used here
            ...
        }
        ...
    }
}

This structure may be used to determine the table number and its name in the data scheme — this information is accessible in the ‘msg_index’ and ‘msg_name’ fields of the structure. For the Plaza-2 data stream, the ‘msg_id’ field is not used and its value is 0. The ‘rev’ field contains record revision (update number) in the table, and the ‘nulls’ field may contain the indicator of byte array which determines whether the record contains a particular field or not.

Data, which the ‘data’ message indicator refers to, are structured according to the data scheme applied in this subscription. See the next section for details on data schemes and access to desired record fields.

Life number is a scheme’s attribute, which allows to validate accuracy of data transmitted in a data stream. The scheme life number of server should be equal to that of the client. This equality is verified at opening of the replication stream; if two life numbers are not equal, it means that some previously received data are not fresh, and will be therefore deleted. After that, the special ‘CG_MSG_P2REPL_LIFENUM’ notification sends out, containing a new scheme life number.

The client scheme’s life number is specified in the ‘cg_lsn_open’ function parameters:

Please note, that it is prohibited to specify the life number values in both 'lifenum' and 'replstate' at the same time!

The life number value is always a decimal digit. Specifying a non-decimal digit as a life number value will cause the error at starting the listener.

After the client life number was successfully sent, the verification procedure starts. The three following results are possible:

It is also allowable to start listener without transmitting a life number. In this case, the listener will use the server life number with the ‘CG_MSG_P2REPL_LIFENUM’ notification.

Any data received or sent in the course of client program interaction with the trading system have a particular structure. Data schemes are used to describe the structure of particular messages.

Data scheme describes a set of possible messages for the selected data channel (subscription or publishing), fields and types of these messages and also define the rules of access to these data. A data scheme is described by the following structure:

struct cg_scheme_desc_t {
  // Scheme type
  uint32_t scheme_type;

  // Scheme features
  uint32_t features;
 
  // Number of messages in the scheme
  size_t num_messages;
 
  // Indicator of the messages description list
  struct cg_message_desc_t* messages;
};

The only one scheme type is currently available; this type corresponds to the identifier ‘1’ — data are stored in the binary form with the 4-byte alignment without support of optional fields.

The ‘features’ field describes available information in the scheme — this field may be used to determine whether default values were set for fields in this scheme, whether fields or messages have descriptions, etc. This is accomplished by the ‘CG_SCHEME_BIN_*’ constants.

The ‘num_messages’ field defines the number of messages in the scheme, and the ‘messages’ field indicates the first message. Messages represent the main object describing particular data structures and are used in all types of subscriptions and publishing; for instance, for the Plaza-2 replication, messages describe events of data updates in tables.

Each message is described by the following structure:

struct cg_message_desc_t {
    // indicator of the next message
    struct cg_message_desc_t* next;

    // message block size
    size_t size;

    // Number of fields in the message
    size_t num_fields;

    // Indicator of field descriptions array
    struct cg_field_desc_t* fields;

    // Message identifier
    // May be equal to 0, if the message has no identifier
    uint32_t id;

    // Message name indicator
    // May be NULL – in this case the message has no name
    char *name;

    // Message description indicator
    // May be NULL - in this case, the message has no description
    char *desc;

    // line with hints
    char* hints;

    // number of message indices
    size_t num_indices;

    // First index indicator
    struct cg_index_desc_t* indices;
};

The ‘next’ field indicates the next message in the scheme or contains the 'NULL' value, that indicates the last message. Therefore, messages are arranged in the linked list and may be accessed by the following cycle:

cg_scheme_desc_t* schemedesc; // initialized indicator of data schemes
for (cg_message_desc_t* msgdesc = schemedesc->messages;
     msgdesc; msgdesc = msgdesc->next)
{
    // here it is possible to work with message description
    // which is contained in msgdesc

    ...
}

The ‘size’ field of the message description structure specifies the block size in bytes, required for storing the entire message data. The ‘num_fields’ field indicates the number of fields in the message, and ‘fields’ indicates the first message field.

The ‘id, ‘name’ and ‘desc’ fields contain the message identifier along with its name and its description. The message may have no identifier, name or description if a particular scheme does not describe these values.

The ‘hints’ field contains parameters which may be used for automatic setting of the program for a particular type or method of data updating. At the present moment, the data scheme describing commands of the FORTS trading system contains the ‘request’ and ‘reply’ hints, advising the messages to be sent and the messages to be received. The ‘hints’ field may contain several hints separated by ‘;’ symbol.

The ‘num_indices’ field contains the number of indices, and the ‘indices’ field indicates the first index. The first index in the list is always the unique primary key.

Indices are described by the following structure:

struct cg_index_desc_t {
    // indicator of the next index
    struct cg_index_desc_t * next;

    // number of fields in the key
    size_t num_fields;

    // indicator of the first field description in the key
    struct cg_indexfield_desc_t* fields;

    // key name
    char* name;

    // key description
    char* desc;

    // line with hints
    char* hints;
};

The ‘next’ field indicates the next index in the scheme or contains the NULL value, indicating the last index.

The ‘num_fields’ field indicates the number of fields in the index.

The ‘fields’ field indicates the first field in the index.

The ‘name’ and ‘desc’ fields contain the index name and its description.

The ‘hints’ field contain hints for the index. For example, ‘unique’.

The index fields are described by the following structure:

struct cg_indexfield_desc_t {
    // indicator of the next key field description
    struct cg_indexfield_desc_t* next;

    // field indicator
    struct cg_field_desc_t* field;

    // sorting order
    uint32_t sort_order;
};

The ‘next’ field indicates the next field in the index or contains the ‘NULL’ value, indicating the last field.

The ‘field’ field indicates the structure describing the scheme fields.

The ‘sort_order’ field specifies the sorting order: 0 - ascending, 1 - descending.

The message fields are described by the following structure:

// Message field description
struct cg_field_desc_t {
    // pointer to the next field
    struct cg_field_desc_t* next;

    // Field identifier
	// Can be 0 in case there is no field id 
    uint32_t id;

    // Field name
	// Can be NULL - in this case field has no name
    char* name;

    // Field description
	// Can be NULL - in this case field has no description
    char* desc;

    // Field type
    char*  type;

    // Value size of this field
    size_t size;

    // Offset from the message beginning
    size_t offset;

    // Indicator of the default field value.
    // Indicates the buffer of the ‘size’ size which stores data in the ‘type’ format
    // If null, then there is no default value

    void* def_value;

    // Indicator of the list of field values
    struct cg_field_value_desc_t* values;
};

The ‘next’ field indicates description of the next message field or contains ‘NULL’ in case of the last field. The ‘id’, ‘name’ and ‘desc’ fields specify identifier, name and description of the field, respectively. In case of different message schemes, these fields may contain null values. The ‘type’ field contains the name of the field type, which may be used to determine the operating mode of this field. The most common field types are the following:

The ‘size’ field contains the field value size and the ‘offset’ field — offset of this field in bytes from the beginning of the data block. This information provides unambiguous identification of the desired field location and size in the data block of the message.

The ‘def_value’ field contains indicator of the default value. Type and size of the value completely coincide with the type and size of the field, therefore initialization of the field by the default value may be performed simply by copying. The ‘NULL’ value of the ‘def_value’ field indicates absence of the default value.

The ‘values’ field indicates the first value of the allowed values list. The ‘NULL’ value of the ‘values’ field indicates that the field may take any value from the type definition domain.

struct cg_field_value_desc_t {
    // indicator of the next value
    struct cg_field_value_desc_t* next;

    // value name
    char* name;

    // value description
    char* desc; 

    // indicator of the allowed value
    void* value; 

    // for fields of the integer type (i[1-8], u[1-8]), the mask 
    // determining the range of bytes taken by the value

    void* mask;
};

The ‘next’ field indicates the next value from the list of admissible field values or contains the NULL value, indicating the last value.

The ‘name’ and ‘desc’ fields contain name and description of the value.

The ‘value’ field indicates the field value; in this case, the size and type of the value coincide with the size and type of the field itself.

The ‘mask’ field is used for grouping of mutually exclusive values, in this case values with different masks may be combined.

Let’s suggest that we are dealing with subscription for receiving the Plaza-2 data stream with the following data scheme:

[dbscheme:FutTrade]
table=orders_log
table=heartbeat

[table:FutTrade:orders_log]
field=replID,i8
field=replRev,i8
field=replAct,i8
field=id_ord,i8
field=sess_id,i4

[table:FutTrade:heartbeat]
field=replID,i8
field=replRev,i8
field=replAct,i8
field=server_time,t

This format of schemes description in the form of ini-files is accepted in the Plaza-2 system.

This scheme describes two tables (two messages) with a certain set of fields in each of them. Let’s suggest that we are desired in getting application numbers from the table ‘orders_log’ and server time synchronization events from the ‘heartbeat’ table — these values are contained in the ‘id_ord’ field of the ‘orders_log’ message and the ‘server_time’ field of the ‘heartbeat’ message, accordingly.

There are two ways to analyze the received data — static, with application of pre-set data structures, and dynamic, with calculation of offsets in the desired fields as of the moment of the scheme receiving.

The static approach is based on the fact that at the stage of development data schemes which will be further used are fixed for the desired streams. After that, for the data schemes, descriptions of C language structures are generated manually or automatically, e.g. using the ‘schemetool’ tool — these descriptions correspond to formats of binary data blocks for each of the received messages (for Java or .NET languages, a code, which analyzes binary blocks of messages is generated instead of structures). In course of operation data of the received message are displayed to the structure corresponding to the message type, and then the necessary data processing is performed.

On the one hand, this approach allows to simplify development process; on the other hand, it fixes a certain format of data schemes which will require another preparation of data structures or of the binary block analysis code. In case of changes in data schemes, the old structures may be no longer displayed to the new message formats; in some cases, it may lead to hard-to-detect errors.

Pre-set data structures or the binary block analysis code may be generated with application of the ‘schemetool’ utility.

It may look like the following:

// Description of structures generated with
// the ‘schemetool’ utility


#pragma pack(push, 4)
// Scheme "FutTrade" description

    struct orders_log
    {
        signed long long replID;
        signed long long replRev;
        signed long long replAct;
        signed long long id_ord;
        signed int sess_id;
        
    };
    const int orders_log_index = 0;

    struct heartbeat
    {
        signed long long replID;
        signed long long replRev;
        signed long long replAct;
        struct cg_time_t server_time;
        
    };
    const int heartbeat_index = 1;

    
#pragma pack(pop)

// in the subscription handler

case CG_MSG_STREAM_DATA:
{
     cg_msg_streamdata_t* replmsg = (cg_msg_streamdata_t*)msg;
     if (replmsg->msg_index == orders_log_index)
     {
         orders_log* ordlog = (orders_log *)replmsg->data;
         printf ("Order ID = %lld\n", ordlog->id_ord);
     }
     else
     if (replmsg->msg_index == heartbeat_index)
     {
         heartbeat* hb = (heartbeat *)replmsg->data;
         printf ("Server time = %d:%d:%d.%d\n", 
                 hb->server_time.hour, hb->server_time.min, 
                 hb->server_time.sec, hb->server_time.ms);
     }
}

The dynamic approach suggests an absence of a clearly fixed data scheme, on the contrary — every time a data scheme is generated from the scheme source (for instance, from the replication server), and the user code analyzes it and performs search of desired messages and fields in these messages.

This approach enables to create a more universal system which will be able to overcome non-critical changes in data schemes; on the other hand, dynamic analysis of the scheme is more complicated in implementation.

The first step of this approach is to prepare information about desired fields — it is necessary to analyze the applied data stream scheme and to record numbers of desired messages and offsets of desired fields:

// variables which will contain information
// required for analysis of received data
size_t index_orders_log; // index of the ‘orders_log’ message in the scheme
size_t offset_id_ord; // offset of the ‘id_ord’ field in the block

size_t index_hearbeart; // index of the ‘heartbeat’ message in the scheme
size_t offset_server_time; // offset of the ‘server_time’ field in the block

This information is sufficient to identify the message type and to find the necessary field in the binary block at the moment of data receiving. These fields are filled-in in the following way:

cg_scheme_desc_t* scheme; // initialized description of the data scheme

size_t msgidx = 0;
for (cg_message_desc_t* msgdesc = schemedesc->messages;
     msgdesc; msgdesc = msgdesc->next, msgidx ++)
{
    size_t fieldindex = 0;
    if (strcmp(msgdesc->name, "orders_log") == 0)
    {
        index_orders_log = msgidx;
        for (cg_field_desc_t* fielddesc = msgdesc->fields;
             fielddesc; fielddesc = fielddesc->next, fieldidx ++)
            if (strcmp(fielddesc->name, "id_ord") == 0 && 
                strcmp(fielddesc->type, "i8") == 0)
                offset_id_ord = fieldidx;
    }
    if (strcmp(msgdesc->name, "heartbeat") == 0)
    {
        index_heartbeat = msgidx;
        for (cg_field_desc_t* fielddesc = msgdesc->fields;
             fielddesc; fielddesc = fielddesc->next, fieldidx ++)
            if (strcmp(fielddesc->name, "server_time") == 0 &&
                strcmp(fielddesc->type, "t") == 0)
                offset_server_time = fieldidx;
    }
}

The specified code is featured by a consistent search of all messages in the scheme and search of necessary fields for desired messages. This is accompanied by checking of field types for compliance with expectations.

The received data are processed in the following way:

// in the subscription handler

case CG_MSG_STREAM_DATA:
{
     cg_msg_streamdata_t* replmsg = (cg_msg_streamdata_t*)msg;

     // coercion to char* to be able to add offset in bytes correctly
     char* data = (char*)replmsg->data;
     if (replmsg->msg_index == index_orders_log)
     {
         int64_t id_ord = *((int64_t*)(data + offset_id_ord));
         printf ("Order ID = %lld\n", id_ord);
     }
     else
     if (replmsg->msg_index == index_heartbeat)
     {
         cg_time_t *srvtime = (cg_time_t*)(data + offset_server_time);
         printf ("Server time = %d:%d:%d.%d\n", 
                 srvtime->hour, srvtime->min, srvtime->sec, srvtime->ms);
     }
}

This example will display the application identifier upon delivery of data on changes in the application status and also the server time at the moment of the corresponding message delivery.

This example demonstrates the following useful practices for code generation:

Sending FORTS transactions and receiving replies on their running is performed via the ‘Publisher’ and ‘Listener’ objects. The created ‘Publisher’ object is tied to the connection by calling the ‘cg_pub_new’ function, e.g. in the following way:

result = cg_pub_new(conn, 
        "p2mq://FORTS_SRV;category=FORTS_MSG;"
        "name=PUB;scheme=|FILE|ini/forts_scheme_messages.ini|message ", 
        &pub);

In this example, ‘pub’ is initialized by the ‘Publisher’ object which is set for sending of FORTS transactions according to the scheme, which is stored in the ‘ini’ sub-directory with the ‘forts_scheme_messages.ini’ file name and the ‘message’ scheme name via the ‘conn’ connection. ‘Publisher’ was assigned with the ‘PUB’ name which will be referenced by ‘Listener’.

Upon successful calling of the ‘cg_pub_new’ function, the object turns into initialized state but still remains inactive. Further work with the publisher is possible only upon calling of the ‘cg_pub_open’ function:

result = cg_pub_open(pub, 0);

Opening parameters for the ‘Publisher’ object are not provided at the moment; therefore, a null pointer is transferred as the second parameter.

When the publisher has been created and opened, you may create and send transactions. To create a transaction, you may use the ‘cg_pub_msgnew’ function.

result = cg_pub_msgnew(pub, CG_KEY_NAME, “FutAddOrder”, &msgptr);

In this case, a message will be created for placing the FORTS order (‘FutAddOrder’ transaction) by name, and its indicator will be recorded into the ‘msgptr’ variable. The ‘cg_pub_msgnew’ function may also be used to create messages by the number in the active scheme and by the identifier.

A message is represented as a pointer to the ‘cg_msg_data_t’ structure:

struct cg_msg_data_t 
{
  uint32_t type;    // Message type = CG_MSG_P2REPL_DATA 
  size_t data_size; // Data size
  void* data;       // Data indicator

  size_t msg_index; // Message number in the active scheme
  uint32_t msg_id;  // Unique message identifier
  const char* msg_name; // Message name in the scheme

  uint32_t user_id; // User’s number of the message
  const char* addr; // Destination address
  struct cg_msg_data_t* ref_msg; // Reference message (not used now)
};

The ‘data’ field of the structure indicates the memory buffer of corresponding capacity, which should be filled according to the active scheme. The simplest way to do this is to bring the pointer to the correct structure. For instance, in the following way:

ord = (struct AddOrder*)msgptr->data;
strcpy(ord->broker_code, "HB00");

Description of the structure from the scheme may be created via the ‘schemetool’ utility.

When the message has been created and filled in, it must be sent out by the ‘cg_pub_post’ function:

 result = cg_pub_post(pub, msgptr, CG_PUB_NEEDREPLY);

The 'CG_PUB_NEEDREPLY' flag means that we want to receive replies to the corresponding ‘lsnreply’ listener.

When the message has been sent, it may be destroyed by means of the ‘cg_pub_msgfree’ function:

result = cg_pub_msgfree(pub, msgptr);

If you send more than one requests of the same type, it may be more effective to use the created message again.

The publisher is closed by calling the ‘cg_pub_close’ function:

result = cg_pub_close(pub);

This is accompanied by disconnection of the publisher from the ‘connection’ object; the object itself remains in the initialized state and may be re-opened. The object is destroyed by calling the ‘cg_pub_destroy’ function:

result = cg_pub_destroy(pub);

After that, the ‘pub’ object is released, and further work with this object is impossible.

The listener for receiving replies to commands is created in the following way:

result = cg_lsn_new(conn, “p2mqreply://;ref=PUB”, replyCB, user_data, &lsnreply);

This call initializes the ‘lsnreply’ variable with a special listener object in order to receive replies to the messages, which were sent by the publisher. Communication between the listener and the publisher is accomplished by name; in this case, this name is ‘PUB’, the ‘ref=PUB’ parameter of the initialization string creates this communication. One listener may be referenced to one publisher. Names of corresponding pairs should be unique. Messages containing replies to transactions and also information on other events of the publisher will be delivered to the ‘replyCB’ function. Life cycle of this ‘Listener’ object does not differ somehow from the life cycle of the replication listener, which is reviewed in the corresponding section except for the fact that ‘replyCB’ does not receive messages of the replication system but receives simple single 'MQ' messages, described by the ‘cg_msg_data_t’ structure. The ‘cg_msg_data_t’ structure is referenced to the data described by the scheme of the corresponding publisher, and there is also the ‘CG_MSG_P2MQ_TIMEOUT’ notification, if the time interval for waiting for the message reply was exceeded. When connection closes, all unreplied 'mq' requests will receive the 'CG_MSG_P2MQ_TIMEOUT' notification messages in reply. When there is an error returns from user's callback, the listener closes.

The 'p2mqreply' listener must be created after creation of the 'mq' publisher. Otherwise, there will be an invalid handle to the 'ref=PUB' object. Order of destruction of these linked object is not important.

The user’s reply handler may look like:

CG_RESULT ClientMessageCallback(cg_conn_t* conn, cg_listener_t* listener, struct cg_msg_t* msg, void* data)
{
  switch (msg->type)
  {
    case CG_MSG_DATA: 
    {
    uint32_t* data = msg->data;
    printf("Client received reply [id:%d, data: %d, user-id: %d, name: %s]\n", 
      ((struct cg_msg_data_t*)msg)->msg_id, 
      *((uint32_t*)msg->data), 
      ((struct cg_msg_data_t*)msg)->user_id,
      ((struct cg_msg_data_t*)msg)->msg_name);

    {
      struct scheme_desc_t* scheme;
      size_t bufSize;

      if (cg_lsn_getscheme(listener, &scheme) != CG_ERR_OK)
        scheme = 0;

      if (cg_msg_dump(msg, scheme, 0, &bufSize) == CG_ERR_BUFFERTOOSMALL)
      {
        char* buffer = malloc(bufSize+1);

        bufSize++;
        if (cg_msg_dump(msg, scheme, buffer, &bufSize) == CG_ERR_OK)
          printf("client dump: %s\n", buffer);
        free(buffer);

      }
    }
    break;
    }
  case CG_MSG_P2MQ_TIMEOUT: 
  {
    printf("Client reply TIMEOUT\n");
    break;
  }
  default:
    printf("Message 0x%X\n", msg->type);
  }
  return CG_ERR_OK;
}

This user’s handler either outputs the dump of messages by means of the auxiliary ‘cg_msg_dump’ function or, in case of the reply period exceeding, monitors this situation and displays the corresponding messages on the screen.

In order to link the sent messages and their replies, it is necessary to use the ‘user_id’ field of the ‘cg_msg_data_t’ structure: setting ‘user_id’ on the sent message provides receiving of the reply message with the same ‘user_id’.

When the p2sys connection is being established, the listener receives 2 messages of the CG_MSG_DATA' type:

In case of successful connection user will be able to send an outcoming authentication request. To do this, the user should create the 'RouterLogin (msgid = 1)' message of the 'CG_MSG_DATA' type. The data field of the message must contain the line "USERNAME=%user_name%;PASSWORD=%password%".

If the login and password pair is validated, the listener receives the 'RouterConnected (msgid = 1)' message containing user login as line. If authentication declined, the listener receives the 'RouterConnected (msgid = 5)' message containing operation status value 1 in the data field.

To disconnect from Plaza-II, you should send the 'RouterLogout (msgid = 2)' message. The data field value in this message is ignored. The system sends back the RouterDisconnected notification with the status value 1.

All objects should be closed down in the standard way, one by one: first publisher, then listener, and then connection.

Program interface of the library is structured with allowance for a number of agreements:

The objects accessed through the library have the life cycle described by the following scheme:

Throughout their life cycle, objects exist in the following states:

This scheme of states is used for the following objects:

The ‘CGate’ library may be used in the multithreading environment but it is not thread-safe. It means that in order to provide correct work with the multithreading library, it is necessary to follow the certain rules:

The ‘Connection’ object provides interaction with the Plaza-2 router for sending and receiving of messages. Any amount of these objects may be created at any time during program operation with initialized environment; nevertheless, it is recommended to create connections at the start of program and to stop them just before exiting.

const char* conn_str = "p2lrpcq://127.0.0.1:4001;app_name=myapp";
cg_conn_t* conn;

result = cg_conn_new(conn_str, *conn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to initialize connection: 0x%X\n", result);
    return;
}

p2lrpcq://127.0.0.1:4001;appName=example;timeout=2000;local_timeout=500;lrpcq_buf=0;name=p2lrpcq_example;
p2tcp://192.168.1.1:4003;appName=example2;timeout=2000;local_pass=123;name=p2tcp_example;
p2sys://127.0.0.1:4001;appName=example3;timeout=2000;name=p2sys_example;

cg_conn_t* conn; // indicator of the object initialized by calling ‘conn_new’

result = cg_conn_open(conn, NULL);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to open connection: 0x%X\n", result);
    // Try to reopen the connection
}

cg_conn_t* conn; // indicator of the object initialized by calling ‘conn_new’

result = cg_conn_close(conn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to close connection: 0x%X\n", result);
    return;
}

cg_conn_t* conn; // of the object which was closed by the calling conn_close

result = cg_conn_destroy(conn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to destroy connection: 0x%X\n", result);
    return;
}

cg_conn_t* conn; // indicator of the active connection

// analysis of incoming messages in the cycle, but no more than 100 per iteration
for (int callidx = 0; callidx < 100; ++ callidx)
{
    result = cg_conn_process(conn, 0, NULL);

    if (result == CG_ERR_TIMEOUT) // no messages
        break; // proceed with further logic of program operation
    else
    if (result != CG_ERR_OK)
    {
        // failure of the attempt to process the connection
        // display the message and close the connection
        fprintf(stderr, "Failed to process connection: 0x%X\n", result);
        result = cg_conn_close(conn); // 
        if (result != CG_ERR_OK)
        {
            // failure to close the connection, exit the program
            fprintf(stderr, "Failed to close connection: 0x%X\n", result);
            return;
        }
        break;
    }
} 

The ‘Listener’ object provides receiving of messages via the specified connection. Rules of messages receiving depend on the listener type — these may be both peer-to-peer messages and publish-subscribe messages, such as replication.

Operations with the ‘Listener’ objects in API are performed via the ‘cg_listener_t*’ indicator.

CG_RESULT callback(cg_conn_t* conn, cg_listener_t* listener, struct cg_msg_t* msg, void* data);

cg_conn_t* conn; // indicator of the ‘Connection' initialized object

const char* lsn_str = "p2repl://FORTS_FUTINFO_REPL";
cg_listener_t* lsn; 

result = cg_lsn_new(conn, lsn_str, callback, 0, *lsn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to initialize listener: 0x%X\n", result);
    return;
}

cg_conn_t* conn; // indicator of the ‘Connection' initialized object

// command sending publisher initialization string
// the ‘name=TN1’ parameter is specified

const char* pub_str = "p2mq://FORTS_SRV;category=FORTS_MSG;name=TN1";
cg_publisher_t* pub; 

// reply receiving listener initialization string
// the ‘ref=TN1’ parameter is specified, it provides communication with the publisher
const char* lsn_str = "p2mqreply://;ref=TN1";
cg_listener_t* lsn; 

result = cg_lsn_new(conn, lsn_str, callback, 0, *lsn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to initialize listener: 0x%X\n", result);
    return;
}

cg_listener_t* lsn; // indicator of the object initialized by calling ‘cg_lsn_new’
const char* lsn_open_str = "mode=online";

result = cg_lsn_open(lsn, lsn_open_str);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to open listener: 0x%X\n", result);
    // Try to reopen the listener
}

cg_listener_t* lsn; // pointer to the opened listener

result = cg_lsn_close(lsn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to close listener: 0x%X\n", result);
    return;
}

cg_listener_t* lsn; // indicator of the object which was closed by calling cg_lsn_close

result = cg_lsn_destroy(lsn);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to destroy listener: 0x%X\n", result);
    return;
}

cg_listener_t* lsn; // Pointer to the listener object
uint32_t state; // Here status will be written

result = cg_lsn_getstate(lsn, &state);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to query listener state: 0x%X\n", result);
    return;
}

switch (state)
{
    case CG_STATE_ERROR: /* ... */
    case CG_STATE_CLOSED: /* ... */
}

cg_listener_t* lsn; // subscription object indicator
cg_scheme_desc_t* schemedesc; // Scheme description indicator will be recorded here

result = cg_lsn_getscheme(lsn, &schemedesc);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to query listener scheme: 0x%X\n", result);
    return;
}

// print the number of messages in the scheme
printf("Number of messages: %d\n", schemedesc->num_messages);

The ‘Publisher’ object provides sending of messages via the specified connection. Rules of messaging depend on the publisher type and connection.

Operations with the ‘Publisher’ objects in API are performed by using the ‘cg_publisher_t*’ pointer.

cg_conn_t* conn; // pointer to the initialized Connection object

const char* pub_str = "p2mq://FORTS_SRV;category=FORTS_MSG;name=TN1";
cg_publusher_t* pub; 

result = cg_pub_new(conn, pub_str, *pub);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to initialize publisher: 0x%X\n", result);
    return;
}

cg_publisher_t* pub; // indicator of the object initialized by calling ‘cg_pub_new’

result = cg_pub_open(pub, 0);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to open publisher: 0x%X\n", result);
    // Try to reopen the publisher
}

cg_publisher_t* pub; // indicator of the opened publisher

result = cg_pub_close(pub);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to close publisher: 0x%X\n", result);
    return;
}

p2sys://;name=p2sys_pub
p2mq://FORTS_SRV;category=FORTS_MSG;name=srvlink;timeout=5000;scheme=|FILE|forts_messages.ini|message

cg_publisher_t* pub; // indicator of the object which was closed by calling cg_pub_close

result = cg_pub_destroy(pub);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to destroy publisher: 0x%X\n", result);
    return;
}

cg_publisher_t* pub; // publisher object indicator
uint32_t state; // Status will be recorded here

result = cg_pub_getstate(pub, &state);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to query publisher state: 0x%X\n", result);
    return;
}

switch (state)
{
    case CG_STATE_ERROR: /* ... */
    case CG_STATE_CLOSED: /* ... */
}

cg_publisher_t* pub; // publisher object indicator
cg_scheme_desc_t* schemedesc; // Scheme description indicator will be recorded here

result = cg_pub_getscheme(pub, &schemedesc);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to query publisher scheme: 0x%X\n", result);
    return;
}

// print number of messages in scheme 
printf("Number of messages: %d\n", schemedesc->num_messages);

struct cg_msg_data_t 
{
    // Message type. Always CG_MSG_DATA for this message
    uint32_t type; 
    // Amount of data
    size_t data_size;
    // Pointer to data
    void* data; 

    // Message description number in the active scheme 
    size_t msg_index;
    // Unique identifier of the message type
    uint32_t msg_id;
    // Message name in the active scheme
    const char* msg_name;

    // User ID of the message
    uint32_t user_id; 
    // Address of the opposite party 
    const char* addr;
    // Reference message indicator
    struct cg_msg_data_t* ref_msg; 
};

cg_publisher_t* pub; // publisher object indicator
cg_msg_data* msg;

result = cg_pub_msgnew(pub, CG_KEY_NAME, "FutDelOrder", &msg);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to allocate message: 0x%X\n", result);
}
else
{
    FutDelOrder* delord;
    if (msg->data_size != sizeof(*delord))
    {
        fprintf(stderr, "Block sizes do not match: %d expected, but got %d \n", 
                sizeof(*delord), msg->data_size);
    }
    else
    {
        delord = (FutDelOrder*)msg->data;
        delord->order_id = ...; // number of the deleting application

        result = cg_pub_post(pub, msg, CG_PUB_NEEDREPLY);
        if (result != CG_ERR_OK)
        {
            fprintf(stderr, "Failed to post message: 0x%X\n", result);
        }
    }
}

cg_publisher_t* pub; // publisher object indicator
cg_msg_data* msg; // initialized message indicator

result = cg_pub_post(pub, msg, CG_PUB_NEEDREPLY);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to post message: 0x%X\n", result);
}
cg_pub_msgfree(pub, msg);

cg_publisher_t* pub; // publisher object indicator
cg_msg_data* msg; // initialized message indicator

result = cg_pub_msgfree(pub, msg);
if (result != CG_ERR_OK)
{
    fprintf(stderr, "Failed to post message: 0x%X\n", result);
}

The p2sys protocol is used for user authentication purposes in Cgate. The protocol contains three objects: connection, listener and publisher.

cg_conn_t* conn;

result = cg_conn_new("p2sys://127.0.0.1:4001;app_name=test_p2sys", &conn);

result = cg_conn_open(conn, 0);

conn_close(conn);

listener_t* lsn = 0;

result = lsn_new(conn, "p2sys://;name=p2sys_lsn", &MessageCallback, 0, &lsn);

result = lsn_open(lsn, 0);

lsn_close(lsn);

publisher_t* pub = 0;

result = pub_new(conn, "p2sys://;name=p2sys_pub", &pub);

result = pub_open(pub, 0);

pub_close(pub);

The ‘schemetool’ utility is designed for working with data schemes.

At the present moment the system supports the function of data structures formation on programming languages corresponding to the format of data stream messages.

schemetool makesrc [options] [SOURCE SCHEME]

schemetool makesrc -o futinfo.h forts_scheme.ini FUTINFO

schemetool makesrc -o futinfo.pas --output-format pas forts_scheme.ini FUTINFO

schemetool makesrc -o futinfo.h --output-format c \
                   --conn p2tcp://localhost:4001;app_name=stool \
                   --stream FORTS_FUTINFO_REPL

schemetool makesrc -o messages.h forts_messages.ini message

The following interface libraries are included into the P2 CGate distribution kit:

Both libraries are developed according to similar rules and operate similar objects. Due to that, API description will be referred simultaneously for Java and .NET.

java -cp .;lib/cgate.jar -Dru.micexrts.cgate.name=libcgate_jni.so.1 -Dru.micexrts.cgate.path=. MyApp

The ‘Connection’ object provides access for the connection function (see Connection).

public Connection(String settings) throws CGateException

public Connection(string settings) 

public void dispose() throws CGateException

public void Dispose() 

public void open(String settings) throws CGateException

public void Open(string settings) 

public void close() throws CGateException

public void close() 

public int process(int timeout)

public int Process(int timeout) 

public int getState() throws CGateException

public State State { get; } 

The Listener object provides access to the set of listener functions (see Listener).

public Listener(Connection conn, String settings, ISubscriber subscriber) throws CGateException

public Listener(Connection conn, string settings) 

public interface ISubscriber {
    
    public int onMessage(Connection conn, Listener listener, Message message);
}

public void dispose() throws CGateException

public void Dispose() 

public void open(String settings) throws CGateException

public void Open(string settings) 

public void close() throws CGateException

public void close() 

public int getState() throws CGateException

public State State { get; } 

public Scheme getScheme() throws CGateException

public Scheme Scheme { get; } 

public MessageHandler Handler { get; set; } 

delegate int MessageHandler(Connection conn, Listener listener, Message msg);

The publisher object provides access to the publisher set of functions (see Publisher).

public Publisher(Connection conn, String settings) throws CGateException

public Publisher(Connection conn, string settings) 

public void dispose() throws CGateException

public void Dispose() 

public void open(String settings) throws CGateException

public void Open(string settings) 

public void close() throws CGateException

public void close() 

public int getState() throws CGateException

public State State { get; } 

public Scheme getScheme() throws CGateException

public Scheme Scheme { get; } 

public void newMessage(int idType, Object id) throws CGateException

public void NewMessage(MessageFlag idType, Object id) 

public void post(Message msg, int flags) throws CGateException

public void Post(Message msg, PublisherFlag flags) 

The Message pbject provides access to messages.

User is responsible for erasing the messages that were created for sending through explicit calling the ‘dispose()’ method. Messages that user receives to the subscription handler should not be deleted, since such messages are owned by P2 CGate library.

public void dispose() throws CGateException

public void Dispose() 

public int getType()

public MessageType Type { get; } 

public java.nio.ByteBuffer getData()

public System.IO.UnmanagedMemoryStream Data { get; } 

public String toString()

public string ToString()