MqContextC - construct an outgoing send-data-package … More...

Collaboration diagram for MqContextC_SendApi_CC_API:

Topics
	MqContextC_SendApi_Basics_CC_API
	MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service …

	MqContextC_SendApi_Atom_CC_API
	MqContextC - append a native PRIMITIVE TYPE value to the send-data-package …

	MqContextC_SendApi_Block_CC_API
	MqContextC - a wrapper to send a list-block or a transaction-block …

	MqContextC_SendApi_Return_CC_API
	MqContextC - finish the send-data-block on the server and optional return the results. …

MkBufferListC *	ccmqmsgque::MqContextC::SendVA (MK_STRN cstr, MqTokenF const fCall, MK_PTR data, MqDataFreeF fFree, va_list ap)

MkBufferListC *	ccmqmsgque::MqContextC::Send (MK_STRN cstr,...)
	`C++: ctx.Send(MK_STRN cstr, ... )` → C-API user friendly replacement for the MqContextC_SendApi_C_API … default MqTokenICB

MkBufferListC *	ccmqmsgque::MqContextC::Send (const std::string &str,...)

MkBufferListC *	ccmqmsgque::MqContextC::Send (MK_STRN cstr, MqTokenICB const callback,...)
	`C++: ctx.Send(MK_STRN cstr, ... )` → C-API user friendly replacement for the MqContextC_SendApi_C_API … default MqTokenICB

MkBufferListC *	ccmqmsgque::MqContextC::Send (const std::string &str, MqTokenICB const callback,...)

MkBufferListC *	ccmqmsgque::MqContextC::Send (MK_STRN cstr, MqTokenCCB const callback,...)
	`C++: ctx.Send(MK_STRN cstr, ... )` → C-API user friendly replacement for the MqContextC_SendApi_C_API … default MqTokenCCB

MkBufferListC *	ccmqmsgque::MqContextC::Send (const std::string &str, MqTokenCCB const callback,...)

MkBufferListC *	ccmqmsgque::MqContextC::Send (MK_STRN cstr, IService *const service,...)
	`C++: ctx.Send(MK_STRN cstr, ... )` → C-API user friendly replacement for the MqContextC_SendApi_C_API … default ccmqmsgque::IService

MkBufferListC *	ccmqmsgque::MqContextC::Send (const std::string &str, IService *const service,...)

Detailed Description

MqContextC - construct an outgoing send-data-package …

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 and the opposite of reading data, which is a passive task. Active means that the send process is triggered by the software workflow or by the user.
For each basic type defined in MkBufferC*, there is a send function and some help functions.

Send-Safe: Sending data is an atomic task and must not be interrupted between MqSendSTART and MqSendEND. The MqContextC HIGH API is uninterruptible by design.
Basic rule: process first and send all data last.

If timeout != 0 is used, the application enters the event loop and waits in the current process or thread for timeout seconds until the service call is finished.
While waiting for a result, the application can continue to work on other events that are in the same or in a different process or thread.

Recursion-Safe: If another-service-call arrives while waiting for a response from a previous-service-call, the previous-service-call will NOT end until processing of the other-service-call is complete.

Example-1: a service call, send and read a data-package

On a client: perform a service call

send the service-call	MqSendSTART → SendTT... → MqSendEND_AND_WAIT
read the result package	ReadTT... → ...

on a server: answer a service call

read the service-call	ReadTT... → ...
send the result package	MqSendSTART → SendTT... → MqSendRETURN

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

command	synchron	database	result
MqSendEND	no	no	no
MqSendEND_AND_WAIT	yes	no	single return data
MqSendEND_AND_SUB	yes	no	multiple return data
MqSendEND_AND_CALLBACK	no	no	single return data
MqSendEND_AND_TRANSACTION	no	yes	two return data

To send a data-package is one task, to send it to the right receiver is an other one. The right receiver is identified using 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 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)

Example-2: (in C) At the client, calling the service and wait for an answer

...
enum MkErrorE MyServiceCall(MQ_CTX const ctx) {
  // ... do some work
    MqSendSTART_E(ctx);                     // init the Send-Buffer object
    MqSendI32_E(ctx,int_value);               // 1. argument: a MK_I32 value
    MqSendSTR_E(ctx,"num:01");                // 2. argument: a MK_STRN value
    MqSendBIN_E(ctx,mypicture,size);          // 3. argument: a MK_BIN picture of size length
    MqSendEND_AND_WAIT_E(ctx,"SRV1",60);    // call service "SRV1" and wait max 60sec for the results
  // ... get the results
    MK_I32 retI = MqReadI32_e(ctx);           // expect ONE integer as result
  // ... do some work
    return MK_OK;
  error:                                    // default error-handler
    return MkErrorStack_1X(ctx);              // on error, build up the error-stack
}

... or using the MqContextC HIGH API

...
enum MkErrorE MyServiceCall(MQ_CTX const ctx) {
  // ... do some work
    MqSend_E(ctx, "W", "SRV1:ICB", int_value, "num:01", mypicture, size);
  // ... get the results
    MK_I32 retI = MqReadI32_e(ctx);           // expect ONE integer as result
  // ... do some work
    return MK_OK;
  error:                                    // default error-handler
    return MkErrorStack_1X(ctx);              // on error, build up the error-stack
}

Example-3: (in C) At the server, answer the service call

...
static MkErrorE SRV1(MQ_CTX const ctx, MK_PTR data) {   // the name "SRV1" can be free chosen
  // ... do some work
    MK_I32 myInt = MqReadI32_e(ctx);          // read a MK_I32 value
    MK_STRN myStr = MqReadSTR_e(ctx);          // read a MK_STR value
    MK_BUF myPic = MqReadBUF_e(ctx);          // read a MkBuffer64S object to store the picture data
  // ... do some work
    MqSendSTART_E(ctx);                     // init the Send-Buffer object
    MqSendI32_E(ctx,int_ret);                 // return argument: a MK_I32 value
  error:                                    // something is wrong, error back
    return MqSendRETURN(ctx);                   // send the package as an answer of a previous service-call
}

... or using the MqContextC HIGH API

...
static MkErrorE SRV1(MQ_CTX const ctx, MK_PTR data) {   // the name "SRV1" can be free chosen
  // ... do some work
    MK_I32 myInt = MqReadI32_e(ctx);          // read a MK_I32 value
    MK_STRN myStr = MqReadSTR_e(ctx);          // read a MK_STR value
    MK_BUF myPic = MqReadBUF_e(ctx);          // read a MkBuffer64S object to store the picture data
  // ... do some work
  error:
    return MqSend(ctx, "R", "I", int_ret);  // send the package as an answer of a previous service-call
}

Function Documentation

◆ Send() [1/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	const std::string &	str,
		IService *const	service,
			... )

◆ Send() [2/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	const std::string &	str,
		MqTokenCCB const	callback,
			... )

◆ Send() [3/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	const std::string &	str,
		MqTokenICB const	callback,
			... )

◆ Send() [4/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	const std::string &	str,
			... )

Definition at line 148 of file MqHigh_cc.cc.

                                                            {
    MkBufferListC*   ret;
    va_list       va;
    va_start(va, str);
    try {
      ret = SendVA(str.c_str(), NULL, NULL, NULL, va);
    } catch (...) {
      va_end(va);
      throw;
    }
    va_end(va);
    return ret;
  }

◆ Send() [5/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	MK_STRN	cstr,
		IService *const	service,
			... )

C++: ctx.Send(MK_STRN cstr, ... ) → C-API
user friendly replacement for the MqContextC_SendApi_C_API … default ccmqmsgque::IService

◆ Send() [6/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	MK_STRN	cstr,
		MqTokenCCB const	callback,
			... )

C++: ctx.Send(MK_STRN cstr, ... ) → C-API
user friendly replacement for the MqContextC_SendApi_C_API … default MqTokenCCB

◆ Send() [7/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	MK_STRN	cstr,
		MqTokenICB const	callback,
			... )

C++: ctx.Send(MK_STRN cstr, ... ) → C-API
user friendly replacement for the MqContextC_SendApi_C_API … default MqTokenICB

◆ Send() [8/8]

MkBufferListC * ccmqmsgque::MqContextC::Send	(	MK_STRN	cstr,
			... )