Loading...
Searching...
No Matches
MqContextC_SendApi_Basics_C_API

MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-serviceMore...

+ Collaboration diagram for MqContextC_SendApi_Basics_C_API:

Functions

MQ_EXTERN enum MkErrorE MqSendEND_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout)
 MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service
 
MQ_EXTERN enum MkErrorE MqSendSTART_RT (MK_RT const mkrt, MQ_CTX const ctx)
 initialize the send-data-package. …
 
MQ_EXTERN enum MkErrorE MqSendEND_AND_WAIT_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout)
 finish the send-data-block, call the remote service and wait for result…
 
MQ_EXTERN enum MkErrorE MqSendEND_AND_TRANSACTION_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MQ_TOK const callback, MK_TIME_T timeout)
 finish the send-data-block, call the remote service to do a longterm-transaction-call
 
MQ_EXTERN enum MkErrorE MqSendEND_AND_SUB_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T timeout)
 finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback
 
MQ_EXTERN enum MkErrorE MqSendEND_AND_CALLBACK_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T const timeout)
 finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback
 
MQ_EXTERN enum MkErrorE MqSendSYNC_RT (MK_RT const mkrt, MQ_CTX const ctx)
 garantee that all pending asynchronous-service-calls are processed. …
 

MqContextC - MqContextC_SendApi_Basics_C_API - overload

#define MqSendEND_NULL(...)
 
#define MqSendEND(...)
 
#define MqSendEND_2(ctx, token)
 
#define MqSendEND_E(...)
 
#define MqSendEND_C(...)
 
#define MqSendEND_AND_CALLBACK_NULL(...)
 
#define MqSendEND_AND_CALLBACK(...)
 
#define MqSendEND_AND_CALLBACK_E(...)
 
#define MqSendEND_AND_CALLBACK_C(...)
 
#define MqSendEND_AND_SUB_NULL(...)
 
#define MqSendEND_AND_SUB(...)
 
#define MqSendEND_AND_SUB_E(...)
 
#define MqSendEND_AND_SUB_C(...)
 
#define MqSendEND_AND_TRANSACTION_NULL(...)
 
#define MqSendEND_AND_TRANSACTION(...)
 
#define MqSendEND_AND_TRANSACTION_3(ctx, token, callback)
 
#define MqSendEND_AND_TRANSACTION_E(...)
 
#define MqSendEND_AND_TRANSACTION_C(...)
 
#define MqSendEND_AND_WAIT_NULL(...)
 
#define MqSendEND_AND_WAIT(...)
 
#define MqSendEND_AND_WAIT_2(ctx, token)
 
#define MqSendEND_AND_WAIT_E(...)
 
#define MqSendEND_AND_WAIT_C(...)
 
#define MqSendSTART_NULL(...)
 
#define MqSendSTART(...)
 
#define MqSendSTART_E(...)
 
#define MqSendSTART_C(...)
 
#define MqSendSYNC_NULL(...)
 
#define MqSendSYNC(...)
 
#define MqSendSYNC_E(...)
 
#define MqSendSYNC_C(...)
 

Detailed Description

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

calling a remote service and wait timeout seconds for an result. If timeout == 0 it is an asynchronous-service-call and if the timeout > 0 it is a synchronous-service-call.

service-call blocking timeout
synchronous yes timeout > 0
asynchronous no timeout == 0

blocking mean waiting max timeout seconds to finishing the service-call:

If an error was raised on the server during the service-processing… the following error-handling will be available

  1. on a synchronous-service-call the error will be the result of the service-call
  2. on a asynchronous-service-call with callback the error will be the result of the callback
  3. on a asynchronous-service-call without callback the error will be send asynchronous from the server to the client . On the client the error will be raised on the NEXT event-handlng-command or as background-error if the MqSetupS::BgError function was defined.
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=0)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
See also
MqSendSYNC

Macro Definition Documentation

◆ MqSendEND

#define MqSendEND ( ...)
Value:
#define MK_RT_CALL
MQ_EXTERN enum MkErrorE MqSendEND_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout)
MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service …

Definition at line 634 of file msgque_overload_mq.h.

◆ MqSendEND_2

#define MqSendEND_2 ( ctx,
token )
Value:
MK_TIMEOUT_DEFAULT
#define MqSendEND(...)

Definition at line 635 of file msgque_overload_mq.h.

◆ MqSendEND_AND_CALLBACK

#define MqSendEND_AND_CALLBACK ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendEND_AND_CALLBACK_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T const timeout)
finish the send-data-block, call the remote service, do not-wait for the result but expect the result...

Definition at line 639 of file msgque_overload_mq.h.

◆ MqSendEND_AND_CALLBACK_C

#define MqSendEND_AND_CALLBACK_C ( ...)
Value:
if (MkErrorCheckI(MqSendEND_AND_CALLBACK(__VA_ARGS__)))
#define MqSendEND_AND_CALLBACK(...)

Definition at line 641 of file msgque_overload_mq.h.

◆ MqSendEND_AND_CALLBACK_E

#define MqSendEND_AND_CALLBACK_E ( ...)
Value:
MkErrorCheck(MqSendEND_AND_CALLBACK(__VA_ARGS__))

Definition at line 640 of file msgque_overload_mq.h.

◆ MqSendEND_AND_CALLBACK_NULL

#define MqSendEND_AND_CALLBACK_NULL ( ...)
Value:
#define MK_RT_CALL_NULL

Definition at line 638 of file msgque_overload_mq.h.

◆ MqSendEND_AND_SUB

#define MqSendEND_AND_SUB ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendEND_AND_SUB_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T timeout)
finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-r...

Definition at line 643 of file msgque_overload_mq.h.

◆ MqSendEND_AND_SUB_C

#define MqSendEND_AND_SUB_C ( ...)
Value:
if (MkErrorCheckI(MqSendEND_AND_SUB(__VA_ARGS__)))
#define MqSendEND_AND_SUB(...)

Definition at line 645 of file msgque_overload_mq.h.

◆ MqSendEND_AND_SUB_E

#define MqSendEND_AND_SUB_E ( ...)
Value:
MkErrorCheck(MqSendEND_AND_SUB(__VA_ARGS__))

Definition at line 644 of file msgque_overload_mq.h.

◆ MqSendEND_AND_SUB_NULL

#define MqSendEND_AND_SUB_NULL ( ...)
Value:

Definition at line 642 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION

#define MqSendEND_AND_TRANSACTION ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendEND_AND_TRANSACTION_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MQ_TOK const callback, MK_TIME_T timeout)
finish the send-data-block, call the remote service to do a longterm-transaction-call …

Definition at line 647 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION_3

#define MqSendEND_AND_TRANSACTION_3 ( ctx,
token,
callback )
Value:
#define MqSendEND_AND_TRANSACTION(...)

Definition at line 648 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION_C

#define MqSendEND_AND_TRANSACTION_C ( ...)
Value:
if (MkErrorCheckI(MqSendEND_AND_TRANSACTION(__VA_ARGS__)))

Definition at line 650 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION_E

#define MqSendEND_AND_TRANSACTION_E ( ...)
Value:
MkErrorCheck(MqSendEND_AND_TRANSACTION(__VA_ARGS__))

Definition at line 649 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION_NULL

#define MqSendEND_AND_TRANSACTION_NULL ( ...)
Value:

Definition at line 646 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT

#define MqSendEND_AND_WAIT ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendEND_AND_WAIT_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout)
finish the send-data-block, call the remote service and wait for result…

Definition at line 652 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT_2

#define MqSendEND_AND_WAIT_2 ( ctx,
token )
Value:
#define MqSendEND_AND_WAIT(...)

Definition at line 653 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT_C

#define MqSendEND_AND_WAIT_C ( ...)
Value:
if (MkErrorCheckI(MqSendEND_AND_WAIT(__VA_ARGS__)))

Definition at line 655 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT_E

#define MqSendEND_AND_WAIT_E ( ...)
Value:
MkErrorCheck(MqSendEND_AND_WAIT(__VA_ARGS__))

Definition at line 654 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT_NULL

#define MqSendEND_AND_WAIT_NULL ( ...)
Value:

Definition at line 651 of file msgque_overload_mq.h.

◆ MqSendEND_C

#define MqSendEND_C ( ...)
Value:
if (MkErrorCheckI(MqSendEND(__VA_ARGS__)))

Definition at line 637 of file msgque_overload_mq.h.

◆ MqSendEND_E

#define MqSendEND_E ( ...)
Value:
MkErrorCheck(MqSendEND(__VA_ARGS__))

Definition at line 636 of file msgque_overload_mq.h.

◆ MqSendEND_NULL

#define MqSendEND_NULL ( ...)
Value:

Definition at line 633 of file msgque_overload_mq.h.

◆ MqSendSTART

#define MqSendSTART ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendSTART_RT(MK_RT const mkrt, MQ_CTX const ctx)
initialize the send-data-package. …

Definition at line 657 of file msgque_overload_mq.h.

◆ MqSendSTART_C

#define MqSendSTART_C ( ...)
Value:
if (MkErrorCheckI(MqSendSTART(__VA_ARGS__)))
#define MqSendSTART(...)

Definition at line 659 of file msgque_overload_mq.h.

◆ MqSendSTART_E

#define MqSendSTART_E ( ...)
Value:
MkErrorCheck(MqSendSTART(__VA_ARGS__))

Definition at line 658 of file msgque_overload_mq.h.

◆ MqSendSTART_NULL

#define MqSendSTART_NULL ( ...)
Value:

Definition at line 656 of file msgque_overload_mq.h.

◆ MqSendSYNC

#define MqSendSYNC ( ...)
Value:
MQ_EXTERN enum MkErrorE MqSendSYNC_RT(MK_RT const mkrt, MQ_CTX const ctx)
garantee that all pending asynchronous-service-calls are processed. …

Definition at line 661 of file msgque_overload_mq.h.

◆ MqSendSYNC_C

#define MqSendSYNC_C ( ...)
Value:
if (MkErrorCheckI(MqSendSYNC(__VA_ARGS__)))
#define MqSendSYNC(...)

Definition at line 663 of file msgque_overload_mq.h.

◆ MqSendSYNC_E

#define MqSendSYNC_E ( ...)
Value:
MkErrorCheck(MqSendSYNC(__VA_ARGS__))

Definition at line 662 of file msgque_overload_mq.h.

◆ MqSendSYNC_NULL

#define MqSendSYNC_NULL ( ...)
Value:

Definition at line 660 of file msgque_overload_mq.h.

Function Documentation

◆ MqSendEND_AND_CALLBACK_RT()

MQ_EXTERN enum MkErrorE MqSendEND_AND_CALLBACK_RT ( MK_RT const mkrt,
MQ_CTX const ctx,
MQ_TOK const token,
MqServiceCallbackF const fCall,
MK_CBP callback,
MqDataFreeF fFree,
MK_TIME_T const timeout )

finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback

This function will never block and return immediately. Usually multiple MqSendEND_AND_CALLBACK are send and finally multiple MqProcessEvent are called to wait for the results.

Example from route_mq.c (C) call a service using a callback

int i;
int flag[MQ_ROUTE_CTX_MAX] = {0};
// call for a "routing" setup/check using all rrctx from "rr->list" in parallel.
// -> use "flag" to check if a callback was called.
for (i=0; i<rr->num; i++) {
MQ_CTX rrctx = rr->list[i];
MqSendSTART_E(rrctx);
MqSendSTR_E(rrctx,routeCUR);
MqSendSTR_E(rrctx,service);
MqSendBOL_E(rrctx,isCreate);
MqSendBOL_E(rrctx,overwrite);
if (MkErrorCheckI(MqSendEND_AND_CALLBACK(rrctx,"_ROU",sRouteTool_CB,&flag[i],NULL,MK_TIMEOUT_DEFAULT))) {
MqContextErrorCopy ( ctx,rrctx);
goto error;
}
}
// wait to finish all "calls" from obove - using "flag" to check if wait is still required.
for (i=0; i<rr->num; i++) {
MQ_CTX rrctx = rr->list[i];
while (flag[i] == 0) { // just be shure the CB is still "open=0"
if (MkErrorCheckI(MqProcessEvent(rrctx, MQ_WAIT_OWN, MK_TIMEOUT_DEFAULT))) {
MqContextErrorCopy ( ctx,rrctx);
goto error;
}
}
}

Be aware of the followig limitatitions if multiple MqSendEND_AND_CALLBACK are called with different ctx:

See also
MqRouteTraverse
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]fCallthe function to process the service-call results
[in]callbacka user defined additional data-argument for the callback function (C-API only)
[in]fFreethe function to free the data-argument after use (C-API only)
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT= 0)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Note
It is a good-practice to protect a bulk of asyncrone-service-calls with a MqSendSYNC or with a MqProcessEvent and MQ_WAIT_OWN .
MqSendEND_AND_CALLBACK : callback signature
1. The *service-ctx* is the *context* for which the service was defined.
callback-args := service-ctx:MqContextC[in]
[static] def callback ( callback-args )
[instance] class YYY:
def callback ( self, callback-args )
[class] class ZZZ:
@staticmethod
def callback ( callback-args )
read more at: Callback signature

◆ MqSendEND_AND_SUB_RT()

MQ_EXTERN enum MkErrorE MqSendEND_AND_SUB_RT ( MK_RT const mkrt,
MQ_CTX const ctx,
MQ_TOK const token,
MqServiceCallbackF const fCall,
MK_CBP callback,
MqDataFreeF fFree,
MK_TIME_T timeout )

finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback

The goal of this service-call is, to split a big data-block into multiple pieces. A typical solution would be a database-application doing a select and sending EVERY row as a ctx.SendRETURN_SUB(). At the end ONE final and EMPTY ctx.SendRETURN() is used to delete the open transaction and finish the service call.

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]fCallthe function to process the service-call results
[in]callbacka user defined additional data-argument for the callback function (C-API only)
[in]fFreethe function to free the data-argument after use (C-API only)
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Attention
By default, the callback for the last packet ( ctx.SendRETURN()) is only called if the packet contains a data-item or on an error. If the packet is empty, only the transaction is closed.
See also
MqSendEND_AND_WAIT MqSendEND_AND_CALLBACK MqSendRETURN_SUB MqSendRETURN
MqSendEND_AND_SUB : callback signature
1. The *service-ctx* is the *context* for which the service was defined.
callback-args := service-ctx:MqContextC[in]
[static] def callback ( callback-args )
[instance] class YYY:
def callback ( self, callback-args )
[class] class ZZZ:
@staticmethod
def callback ( callback-args )
read more at: Callback signature

◆ MqSendEND_AND_TRANSACTION_RT()

MQ_EXTERN enum MkErrorE MqSendEND_AND_TRANSACTION_RT ( MK_RT const mkrt,
MQ_CTX const ctx,
MQ_TOK const token,
MQ_TOK const callback,
MK_TIME_T timeout )

finish the send-data-block, call the remote service to do a longterm-transaction-call

A longterm-transaction is a service-call with guaranteed delivery. guaranteed mean that the transaction is using the MqContextC STORAGE API to keep every step persistent being able to recover a step if something unexpected happen.

To link the result with the calling-environment a private transaction-item is used to save the calling-environment to the local-storage. If the local-storage is persistent, the calling-environment will even survive an application restart.
If the result from the public service-call arrives, the transaction-item will be extracted from the result and the private calling-environment will be initialized from the local-storage.

To create a persistent-transaction the MqContextC STORAGE API have to be setup as persistent. By default, an in-memory MqContextC STORAGE API is used.

The longterm-transaction-call has TWO results…

  • the FIRST result is a acknowledge that the longterm-transaction was stored in the remote database
  • the SECOND result is the result of the service-call

In difference to MqSendEND_AND_WAIT and MqSendEND_AND_CALLBACK a longterm-transaction-call have to survive an application restart. To achieve this goal… two features have to be available to process the results:

transaction-item

The transaction-item is the entry-id from the local internal database and is the public handle of the private data. If the transaction-item-private-data should be persistent (survive an application restart) the internal database have to be persistent using the Storage option.
The transaction-item-private-data requires a MqSendT_STARTMqSendT_END at the beginning of the send-data-package.
The list of data-items in the transaction-item-private-data have to be provided by the programmer and is used to initialise the environment in the callback (for example an external database-entry-id).
In the transaction-callback the transaction-item-private-data have to be extracted with MqReadT_STARTMqReadT_END at the beginning of the read-data-package.

transaction-callback

The transaction-callback have to be a MqContextC_ServiceApi_Identifer defined with MqServiceCreate in the application setup code (like IServerSetup) and have to be available after an application restart.

If an error is raised on the server during the database-insert the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]callbackthe MqContextC_ServiceApi_Identifer of the MqContextC_ServiceApi_Callback
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Example from MyTransaction.py make a logterm-transaction-call using the LOW and the HIGH api

import sys
from pymkkernel import *
from pymqmsgque import *

def callback(ctx):
  ctx.ReadT_START()
  myPrivateHandle = ctx.ReadSTR()
  ctx.ReadT_END()
  myServiceResult = ctx.ReadI32()

  print(f"myPrivateHandle={myPrivateHandle}, myServiceResult={myServiceResult}")

ctx = MqContextC()
try:
  ctx.ConfigSetName("MyTransaction")

  # setup commandline arguments used for parsing
  args = MkBufferListC.CreateLA(sys.argv)

  # check if the '--token' option is available, default "SRVC"
  token = args.CheckOptionSTR("--token", "SRVC")

  # connect to the server
  ctx.LinkCreate(args)

  # register callback
  ctx.ServiceCreate("CLB1", callback)
   
  # send block using the LOW-Api
  ctx.SendSTART()
  ctx.SendT_START()
  ctx.SendSTR("Privat_Data_1")
  ctx.SendT_END()
  ctx.SendI32(11111)
  ctx.SendEND_AND_TRANSACTION(token, "CLB1")
   
  # send block using the HIGN-Api -> same as above, but shorter
  ctx.Send("T", "CLB1", f"{token}:(C)I", "Privat_Data_2", 22222)
   
  # now we wait for exact ONE result of the $ctx
  ctx.ProcessEvent(MqWaitOnEventE.OWN)
except Exception as ex:
  ctx.ErrorCatch(ex);
finally:
  ctx.Exit()

◆ MqSendEND_AND_WAIT_RT()

MQ_EXTERN enum MkErrorE MqSendEND_AND_WAIT_RT ( MK_RT const mkrt,
MQ_CTX const ctx,
MQ_TOK const token,
MK_TIME_T timeout )

finish the send-data-block, call the remote service and wait for result…

If an error is raised on the server during the service-processing the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.

See also
MqRouteTraverse
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

◆ MqSendEND_RT()

MQ_EXTERN enum MkErrorE MqSendEND_RT ( MK_RT const mkrt,
MQ_CTX const ctx,
MQ_TOK const token,
MK_TIME_T timeout )

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

calling a remote service and wait timeout seconds for an result. If timeout == 0 it is an asynchronous-service-call and if the timeout > 0 it is a synchronous-service-call.

service-call blocking timeout
synchronous yes timeout > 0
asynchronous no timeout == 0

blocking mean waiting max timeout seconds to finishing the service-call:

  • If the service-call is finished in less than timeout seconds… the results are available and can be processed.
  • If the service-call is NOT finished in timeout seconds… an timeout-error is created and the transaction will be canceled.

If an error was raised on the server during the service-processing… the following error-handling will be available

  1. on a synchronous-service-call the error will be the result of the service-call
  2. on a asynchronous-service-call with callback the error will be the result of the callback
  3. on a asynchronous-service-call without callback the error will be send asynchronous from the server to the client . On the client the error will be raised on the NEXT event-handlng-command or as background-error if the MqSetupS::BgError function was defined.
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
[in]tokenthe MqContextC SERVICE API to identify the service
[in]timeoutin seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=0)
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
See also
MqSendSYNC

◆ MqSendSTART_RT()

MQ_EXTERN enum MkErrorE MqSendSTART_RT ( MK_RT const mkrt,
MQ_CTX const ctx )

initialize the send-data-package. …

This function must be the first statement in a send-data-block.

If the socket is closed or failed, the connection is established with a MqLinkConnect.
Note that during MqLinkConnect the event-loop is called and your read-data-package may be invalid.

‍It is recommended to perform all READ operations first and then all SEND operations.

From MqSendSTART to MqSendEND is a send-data-block and no event-loop action is allowed between them.

‍The event-loop could modify the already started send-data-package and corrupt the data.

Note
  • There is only one send-data-package per context.
  • You should assume that any meta-function-call can enter the event-loop.
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]ctxthe MqContextS instance to work on
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

◆ MqSendSYNC_RT()

MQ_EXTERN enum MkErrorE MqSendSYNC_RT ( MK_RT const mkrt,
MQ_CTX const ctx )

garantee that all pending asynchronous-service-calls are processed. …

The asynchronous-service-call is defined at: MqContextC_ServiceApi_C_API.

All service-calls to a specific ctx are queued in a service-call-pipeleine. The synchronous-service-call is blocking the service-call-pipeleine until the synchronous-service-call is finished. The asynchronous-service-call does NOT blocking the pipeline and so all asynchronous-service-call are processed in parallel. The MqSendSYNC is used if multiple asynchronous-service-calls are done to a single ctx and this ctx should be blocked until all asynchronous-service-calls are finished. The MqSendSYNC is just an normal blocking synchronous-service-call which is only finished after all asynchronous-service-calls are finished.

Example from perfclient.c sending a bulk of asynchronous-sevice-requests

StatTimerSP itemT = StatCreate (mqctx,sec,num);
{
StatCtxSP stat = StatCtxCreate (mqctx, "--send");
// init
PerfSendPackageStart(mqctx,9999);
MqSendEND_E (mqctx, "RDUL", 0);
// test
StatInit (itemT);
// TEST: start as many as possible asyncron-service-calles in "itemT" intervall.
while (StatCheck(itemT)) {
PerfSendPackageStart(mqctx, StatCount(itemT));
MqSendEND_E (mqctx, "RDUL", 0);
}
// just sync with the server
StatCtxCalc (stat, itemT, -1);
StatCtxPrint (stat);
StatCtxDelete (&stat);
}

The last MqSendSYNC garantee the all previous asynchronous-service-calls are finished.