libmsgque Tutorial

INDEX

INTRODUCTION
BUILD
SERVER
CLIENT
FILTER

INTRODUCTION

libmsgque is the C language binding of the libmsgque library.
The library was designed to simplify the client/server development using the following design rules:

1. programming language independent
2. operating system independent
3. processor hardware independent

The C language binding provide the following basic components:

• abstract class of the libmsgque object: struct MqS*
• interface: IServerSetup and or IServerCleanup to add server functionality
• interface: IFilterFTR and or IFilterEOF to add filter functionality
• interface: IFactory to create a new application instance
• interface: IBgError to act on asyncrone errors
• adding and removing services

BUILD

The build is different between UNIX and WINDOWS. On UNIX the automake (info automake) build environment is used and on WINDOWS the VisualExpress tools from Microsoft are used. The automake build on WINDOWS is possible but not supported.

UNIX

The example from the tutorial is using the automake build-environment from the libmsgque tool. An example automake configuration file is available in: example/C/Makefile.am

noinst_PROGRAMS = mulclient$(EXEEXT) mulserver$(EXEEXT) manfilter$(EXEEXT) \
                    testclient$(EXEEXT) testserver$(EXEEXT) \
                      MyClient$(EXEEXT) MyServer$(EXEEXT) \
                        Filter1$(EXEEXT) Filter2$(EXEEXT)

...

MyClient_SOURCES = MyClient.c
MyClient_LDADD = -lm ../../src/*.lo

MyServer_SOURCES = MyServer.c
MyServer_LDADD = -lm ../../src/*.lo

...

INCLUDES = -I$(srcdir)/../../src

WINDOWS

The VisualExpress build environment is located in the directory win.

SERVER

A libmsgque server requires the following setup:

1. file: example/C/MyServer.c
2. an instance of the abstract class struct MqS*
3. the interface IServerSetup and or IServerCleanup
4. the interface IFactory to create a new application instance

The minimal server looks like:

#include "string.h"
#include "msgque.h"
static enum MqErrorE MyFirstService (struct MqS *ctx, MQ_PTR data) {
  MqSendSTART(ctx);
  MqSendC(ctx, "Hello World");
  return MqSendRETURN(ctx);
}
static enum MqErrorE ServerSetup (struct MqS *ctx, MQ_PTR data) {
  return MqServiceCreate(ctx,"HLWO", MyFirstService, NULL, NULL);
}
int main (int argc, MQ_CST argv[]) 
{
  struct MqBufferLS * largv = MqBufferLCreateArgs(argc, argv);
  struct MqS * ctx = MqContextCreate(0, NULL);
  MqConfigSetName (ctx, "MyServer");
  MqConfigSetServerSetup (ctx, ServerSetup, NULL, NULL, NULL);
  MqConfigSetDefaultFactory (ctx);
  MqErrorCheck (MqLinkCreate (ctx, &largv));
  MqErrorCheck (MqCheckForLeftOverArguments(ctx, &largv));
  MqErrorCheck (MqProcessEvent(ctx,MQ_TIMEOUT,MQ_WAIT_FOREVER));
error:
  MqExit(ctx);
}

The server is started as network visible TCP server listen on PORT 2345 using a THREAD for every new connection request:

> MyServer --tcp --port 2345 --thread

If you are using UNIX and if you want to setup a high-performance local server then use the build-in UDS (Unix-Domain-Sockets) capability to listen on the FILE /path/to/any/file.uds instead on a network port:

> MyServer --uds --file /path/to/any/file.uds --thread

Three things are important:

1. the send style of functions
2. the MqServiceCreate(ctx,token,fService,data,fFree) function
3. a connected context of type struct MqS*

Sending data is done using a minimum of 2 steps:

1. First: start a data package with MqSendSTART(ctx)
2. Last: submit the a data package to the link target using one of:
   • MqSendEND(ctx,token)
   • MqSendEND_AND_WAIT(ctx,token,?timeout=MQ_TIMEOUT_USER?)
   • MqSendEND_AND_CALLBACK(ctx,token,fCallback,data,fFree)
   • MqSendRETURN(ctx)

The first three SendEND... functions are used to call a remote service and the last one is used to answer an incoming service call. In-between MqSendSTART(ctx) and MqSendEND(ctx,token) ... other SEND DATA style commands are available to fill the data package with data.

Services are created with the MqServiceCreate(ctx,token,fService,data,fFree) function. The first parameter is a 4 byte Token as public name. 4 byte is required because this string is mapped to a 4 byte integer for speed reason. The second parameter is an object providing the SERVICE CALLBACK interface.

The SERVICE CALLBACK function has one parameter of type struct MqS*. This parameter refer to the original object (in our case MyServer). If the service object (in our case MyFirstService) is a subclass of the original struct MqS* object class, the both statements SendSTART() and ctx.sendSTART() are identical.

CLIENT

A libmsgque client requires the following setup:

1. an instance of the abstract class struct MqS*

The minimal client looks like:

#include "string.h"
#include "msgque.h"
int main (int argc, MQ_CST argv[]) 
{
  struct MqBufferLS * largv = MqBufferLCreateArgs(argc, argv);
  struct MqS * ctx = MqContextCreate(0, NULL);
  MQ_CST c;
  MqConfigSetName(ctx, "MyClient");
  MqErrorCheck (MqLinkCreate (ctx, &largv));
  MqErrorCheck (MqCheckForLeftOverArguments(ctx, &largv));
  MqSendSTART(ctx);
  MqSendEND_AND_WAIT(ctx, "HLWO", 10);
  MqErrorCheck (MqReadC(ctx, &c));
  printf("%s\n", c);
error:
  MqExit(ctx);
}

To call a network visible TCP server listen on PORT 2345 use:

> MyClient --tcp --port 2345
> Hello World

To call a network visible UDP server listen on FILE /path/to/any/file.uds use:

> MyClient --udp --file /path/to/any/file.uds
> Hello World

To call a local server started by the client using PIPE communication use:

> MyClient @ MyServer
> Hello World

FILTER

A filter has to implement the IFilterFTR or the IFilterEOF interface which requires the following functions:

• IFilterFTR, a service function to act on filter data rows. Every filter input data is a list of filter data rows and every row is a list of filter data columns. Every row is send from one filter-command to the following filter-command as FTR service request
• IFilterEOF, a service function to act on End-Of-Filter data. This service is called after the whole filter data was send. Sometimes the filter data can not be served as filter data rows (example: sorting of the input rows need to read all rows before the data can be send to the next filter command) and the EOF function is used to continue send filter data rows

The minimal filter looks like:

• filter example