HOWTO Do A Service Call ?

HOWTO "send" the data

A data-package is send in two different scenarios:

on a client to call a service on the server
on a server to answer a service call from the client

Sending data is an active task. Active mean, that the sending have to be triggered by the software-workflow.

Sending data is a sequence of commands to prepare a data-package and one command to send this package.

on a client

MqSendSTART (ctx);
MqSendI (ctx, myInteger);
MqSendC (ctx, "myString");
MqErrorCheck (MqSendEND (ctx, "IDNT", NULL));

on a server

MqSendSTART (ctx);
MqSendI (ctx, myInteger);
MqSendC (ctx, "myString");
MqErrorCheck (MqSendRETURN (ctx));

using javamsgque, csmsgque, and ccmsgque code:

on the client:

ctx.SendSTART();
ctx.SendI(myInteger);
ctx.sendC(myString);
ctx.SendEND("IDNT");

on the server:

ctx.SendSTART();
ctx.SendI(myInteger);
ctx.sendC(myString);
ctx.SendRETURN();

using pymsgque and vbmsgque code:

on the client:

ctx.SendSTART()
ctx.SendI(myInteger)
ctx.sendC(myString)
ctx.SendEND("IDNT")

on the server:

ctx.SendSTART()
ctx.SendI(myInteger)
ctx.sendC(myString)
ctx.SendRETURN()

using tclmsgque code:

on the client:

$ctx SendSTART
$ctx SendI myInteger
$ctx sendC myString
$ctx SendEND IDNT

on the server:

$ctx SendSTART
$ctx SendI myInteger
$ctx sendC myString
$ctx SendRETURN

using perlmsgque code:

on the client:

$ctx->SendSTART
$ctx->SendI myInteger
$ctx->sendC myString
$ctx->SendEND IDNT

on the server:

$ctx->SendSTART
$ctx->SendI myInteger
$ctx->sendC myString
$ctx->SendRETURN

Important in the code from above is the last command MqSendEND because this is just one of three possibilities:

command	description	C	C++	C#	java	python	tcl	perl	VB.NET
MqSendEND	Do a service-call without return data	YES	YES	YES	YES	YES	YES	YES	YES
MqSendEND_AND_WAIT	Do a synchronous service-call with return data	YES	YES	YES	YES	YES	YES	YES	YES
MqSendEND_AND_CALLBACK	Do a asynchronous service-call with return data	YES	YES	YES	YES	YES	YES	YES	YES

To send a data-package is one task, to send it to the right receiver is an other one. The right receiver is identified with the token parameter argument. This parameter have to be a 4 character string. You'll probably ask "why 4?" the answer is that this string have should be "human" readable and easy to "compare". As solution this string is mapped to a 4 byte integer used to find the proper key/value entry in the service-hash-table on the server. (in short: to search an integer is much faster as to search a string)

HOWTO "read" the data

A data-package is read in two different scenarios:

on a server to serve an incoming service-call from the client
on a client to process the return-data from a previous service-call

Reading data is a passive task in opposite to sending data which is an active task. Passive mean that the read is triggered by an incoming data-package and not by the software-workflow.

To setup a passive task two requirements are necessary:

adding the service
start the event-loop to listen on the incoming packages

To add a service the following code is necessary:

using libmsgque code:

on a server:

MqErrorCheck (MqServiceCreate (ctx, "ECUL", Ot_ECUL, NULL, NULL)) ;

on a client:

MqErrorCheck (MqSendEND_AND_CALLBACK(ctx, "ECUL", RET_ECUL, NULL, NULL));

using ccmsgque code:

on a server:

ctx.ServiceCreate("ECUL", CallbackF(&MyClass::CNFG)); or
ctx.ServiceCreate("ECUL", static_cast<IService*>(MyObject));

on a client:

ctx.SendEND_AND_CALLBACK("ECUL", CallbackF(&MyClass::RET_ECUL())); or
ctx.SendEND_AND_CALLBACK("ECUL", static_cast<IService*>(MyObject));

using csmsgque code:

on a server:

ctx.ServiceCreate("ECUL", new Ot_ECUL()); or
ctx.ServiceCreate("ECUL", Ot_ECUL_delegeate));

on a client:

ctx.SendEND_AND_CALLBACK("ECUL", new RET_ECUL()); or
ctx.SendEND_AND_CALLBACK("ECUL", RET_ECUL_delegate);

using javamsgque code:

on a server:

ctx.ServiceCreate("ECUL", new Ot_ECUL());

on a client:

ctx.SendEND_AND_CALLBACK("ECUL", new RET_ECUL());

using pymsgque code:

on a server:
```
ctx.ServiceCreate("ECUL", Ot_ECUL) 
```

on a client:

ctx.SendEND_AND_CALLBACK("ECUL", RET_ECUL)

using tclmsgque code:

on a server:
```
$ctx ServiceCreate ECUL Ot_ECUL 
```
on a client:
```
$ctx SendEndAndCallback ECUL RET_ECUL
```

using perlmsgque code:

on a server:
```
$ctx->ServiceCreate("ECUL", Ot_ECUL);
```

on a client:

$ctx->SendEND_AND_CALLBACK("ECUL", \&RET_ECUL);

using vbmsgque code:

on a server:

ctx.ServiceCreate("ECUL", AddressOf Ot_ECUL)

on a client:

ctx.SendEND_AND_CALLBACK("ECUL", AddressOf RET_ECUL)

To start the event-loop and wait for 10 seconds for the return message the following code is used:

using libmsgque code:

MqErrorCheck (MqProcessEvent (msgque, 10, MQ_WAIT | MQ_WAIT_FOREVER));

using ccmsgque code:
```
ctx.ProcessEvent(10, MQ_WAIT_FOREVER);
```

using csmsgque code:

ctx.ProcessEvent(10, MqS.WAIT.FOREVER);

using javamsgque code:

ctx.ProcessEvent(10, MqS.WAIT.FOREVER);

using pymsgque code:

ctx.ProcessEvent(timeout=10, wait="FOREVER")

using tclmsgque code:

$ctx ProcessEvent -timeout 10 -wait FOREVER

using perlmsgque code:

$ctx->ProcessEvent({timeout => 10, wait => "FOREVER"});

using tclmsgque code:
```
ctx.ProcessEvent(10, MqS.WAIT.FOREVER)
```

Finally to read the package-data the following code is necessary:

using libmsgque code:

MqErrorCheck (MqReadI (ctx, &myInteger));
MqErrorCheck (MqReadC (ctx, &myString));

using javamsgque, csmsgque, and ccmsgque code:

myInteger = ctx.ReadI();
myString = ctx.ReadC();

using pymsgque and vbmsgque code:

myInteger = ctx.ReadI()
myString = ctx.ReadC()

using tclmsgque code:

set myInteger [$ctx ReadI]
set myString [$ctx ReadC]

using perlmsgque code:

myInteger = $ctx->ReadI();
myString = $ctx->ReadC();

The libmsgque API is type-save and create an error if the requested type like MqReadI is not compatible with the next available type in the data-package.