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

Collaboration diagram for MqContextC_SendApi_C_API:

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

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

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

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

Functions
MQ_EXTERN enum MkErrorE	libmqmsgque::MqSendSetHandShake (MQ_CTX const ctx, enum MqHandShakeE handShake) MK_ATTR_HDL
	set the hand-shake of the send-data-package

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

◆ MqSendSetHandShake()

MQ_EXTERN enum MkErrorE libmqmsgque::MqSendSetHandShake	(	MQ_CTX const	ctx,
		enum MqHandShakeE	handShake )

set the hand-shake of the send-data-package

Parameters

[in]	ctx	the MqContextS instance to work on
[in]	handShake	the value to set

Topics

Functions

Detailed Description

Function Documentation

◆ MqSendSetHandShake()