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

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 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

on a synchronous-service-call the error will be the result of the service-call
on a asynchronous-service-call with callback the error will be the result of the callback
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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	timeout	in 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:

MqSendEND_RT(MK_RT_CALL __VA_ARGS__)

MK_RT_CALL

#define MK_RT_CALL

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 …

Definition at line 634 of file msgque_overload_mq.h.

◆ MqSendEND_2

#define MqSendEND_2	(		ctx,
			token )

Value:

MqSendEND(ctx,token,MK_TIMEOUT_DEFAULT)

MK_TIMEOUT_DEFAULT

MqSendEND

#define MqSendEND(...)

Definition msgque_overload_mq.h:634

Definition at line 635 of file msgque_overload_mq.h.

◆ MqSendEND_AND_CALLBACK

#define MqSendEND_AND_CALLBACK ( ... )

Value:

MqSendEND_AND_CALLBACK_RT(MK_RT_CALL __VA_ARGS__)

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...

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__)))

MqSendEND_AND_CALLBACK

#define MqSendEND_AND_CALLBACK(...)

Definition msgque_overload_mq.h:639

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:

MqSendEND_AND_CALLBACK_RT(MK_RT_CALL_NULL __VA_ARGS__)

MK_RT_CALL_NULL

#define MK_RT_CALL_NULL

Definition at line 638 of file msgque_overload_mq.h.

◆ MqSendEND_AND_SUB

#define MqSendEND_AND_SUB ( ... )

Value:

MqSendEND_AND_SUB_RT(MK_RT_CALL __VA_ARGS__)

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-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__)))

MqSendEND_AND_SUB

#define MqSendEND_AND_SUB(...)

Definition msgque_overload_mq.h:643

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:

MqSendEND_AND_SUB_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 642 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION

#define MqSendEND_AND_TRANSACTION ( ... )

Value:

MqSendEND_AND_TRANSACTION_RT(MK_RT_CALL __VA_ARGS__)

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 …

Definition at line 647 of file msgque_overload_mq.h.

◆ MqSendEND_AND_TRANSACTION_3

#define MqSendEND_AND_TRANSACTION_3	(	ctx,
		token,
		callback )

Value:

MqSendEND_AND_TRANSACTION(ctx,token,callback,MK_TIMEOUT_DEFAULT)

MqSendEND_AND_TRANSACTION

#define MqSendEND_AND_TRANSACTION(...)

Definition msgque_overload_mq.h:647

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:

MqSendEND_AND_TRANSACTION_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 646 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT

#define MqSendEND_AND_WAIT ( ... )

Value:

MqSendEND_AND_WAIT_RT(MK_RT_CALL __VA_ARGS__)

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…

Definition at line 652 of file msgque_overload_mq.h.

◆ MqSendEND_AND_WAIT_2

#define MqSendEND_AND_WAIT_2	(		ctx,
			token )

Value:

MqSendEND_AND_WAIT(ctx,token,MK_TIMEOUT_DEFAULT)

MqSendEND_AND_WAIT

#define MqSendEND_AND_WAIT(...)

Definition msgque_overload_mq.h:652

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:

MqSendEND_AND_WAIT_RT(MK_RT_CALL_NULL __VA_ARGS__)

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:

MqSendEND_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 633 of file msgque_overload_mq.h.

◆ MqSendSTART

#define MqSendSTART ( ... )

Value:

MqSendSTART_RT(MK_RT_CALL __VA_ARGS__)

MqSendSTART_RT

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__)))

MqSendSTART

#define MqSendSTART(...)

Definition msgque_overload_mq.h:657

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:

MqSendSTART_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 656 of file msgque_overload_mq.h.

◆ MqSendSYNC

#define MqSendSYNC ( ... )

Value:

MqSendSYNC_RT(MK_RT_CALL __VA_ARGS__)

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. …

Definition at line 661 of file msgque_overload_mq.h.

◆ MqSendSYNC_C

#define MqSendSYNC_C ( ... )

Value:

if (MkErrorCheckI(MqSendSYNC(__VA_ARGS__)))

MqSendSYNC

#define MqSendSYNC(...)

Definition msgque_overload_mq.h:661

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:

MqSendSYNC_RT(MK_RT_CALL_NULL __VA_ARGS__)

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:

If no error is available the callback is called with the ctx of the previous call to MqSendEND_AND_CALLBACK.
If an error is available the error is raised as result from the call to MqProcessEvent and NOT as result th the previous call to MqSendEND_AND_CALLBACK. The error-context is the context of the call to MqProcessEvent and not the context of the previous call to MqSendEND_AND_CALLBACK.

See also: MqRouteTraverse

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	fCall	the function to process the service-call results
[in]	callback	a user defined additional data-argument for the callback function (C-API only)
[in]	fFree	the function to free the data-argument after use (C-API only)
[in]	timeout	in 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.

2. If the *callback* is **not** an instance of the calling *context*, the *service-ctx* is added as an argument.

callback-args := service-ctx:MqContextC[in]

[static] proc callback { callback-args ?additional-args...? } ...

[own] ::oo::class create XXX {

superclass MqContextC

method callback { ?additional-args...? } ...

[instance] ::oo::class create YYY {

method callback { callback-args ?additional-args...? } ...

[class] ::oo::class create ZZZ {

self method callback { callback-args ?additional-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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	fCall	the function to process the service-call results
[in]	callback	a user defined additional data-argument for the callback function (C-API only)
[in]	fFree	the function to free the data-argument after use (C-API only)
[in]	timeout	in 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.

2. If the *callback* is **not** an instance of the calling *context*, the *service-ctx* is added as an argument.

callback-args := service-ctx:MqContextC[in]

[static] proc callback { callback-args ?additional-args...? } ...

[own] ::oo::class create XXX {

superclass MqContextC

method callback { ?additional-args...? } ...

[instance] ::oo::class create YYY {

method callback { callback-args ?additional-args...? } ...

[class] ::oo::class create ZZZ {

self method callback { callback-args ?additional-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:

a transaction-callback as a service created with MqServiceCreate
a transaction-item as a environment created with MqSendT_START … MqSendT_END and stored into an internal database.

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_START … MqSendT_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_START … MqReadT_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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	callback	the MqContextC_ServiceApi_Identifer of the MqContextC_ServiceApi_Callback
[in]	timeout	in 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.tcl → make a logterm-transaction-call using the LOW and the HIGH api

package require tclmsgque::MqMsgque
namespace import tclmsgque::MqMsgque::*
namespace import tclmsgque::MkKernel::*

proc callback {ctx} {
  $ctx ReadT_START
  set myPrivateHandle [$ctx ReadSTR]
  $ctx ReadT_END
  set myServiceResult [$ctx ReadI32]

  puts "myPrivateHandle=$myPrivateHandle, myServiceResult=$myServiceResult"
}

# setup the client-context
set ctx [MqContextC new]

try {

  $ctx ConfigSetName "MyTransaction"

  # setup commandline arguments used for parsing
  set args [MkBufferListC CreateLA {*}$argv]

  # check if the '--token' option is available, default "SRVC"
  set 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 "$token:(C)I" "Privat_Data_2" 22222
   
  # now we wait for exact ONE result of the $ctx
  $ctx ProcessEvent MQ_WAIT_OWN

} on error {} {
  $ctx ErrorCatch
} 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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	timeout	in 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

on a synchronous-service-call the error will be the result of the service-call
on a asynchronous-service-call with callback the error will be the result of the callback
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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the MqContextS instance to work on
[in]	token	the MqContextC SERVICE API to identify the service
[in]	timeout	in 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]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ctx	the 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);
      MqSendSYNC_E (mqctx);
 
      // 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
        MqSendSYNC_E (mqctx);
      StatCtxCalc (stat, itemT, -1);
      StatCtxPrint (stat);
      StatCtxDelete (&stat);
    }

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

Functions

MqContextC - MqContextC_SendApi_Basics_C_API - overload

Detailed Description

Macro Definition Documentation

◆ MqSendEND

◆ MqSendEND_2

◆ MqSendEND_AND_CALLBACK

◆ MqSendEND_AND_CALLBACK_C

◆ MqSendEND_AND_CALLBACK_E

◆ MqSendEND_AND_CALLBACK_NULL

◆ MqSendEND_AND_SUB

◆ MqSendEND_AND_SUB_C

◆ MqSendEND_AND_SUB_E

◆ MqSendEND_AND_SUB_NULL

◆ MqSendEND_AND_TRANSACTION

◆ MqSendEND_AND_TRANSACTION_3

◆ MqSendEND_AND_TRANSACTION_C

◆ MqSendEND_AND_TRANSACTION_E

◆ MqSendEND_AND_TRANSACTION_NULL

◆ MqSendEND_AND_WAIT

◆ MqSendEND_AND_WAIT_2

◆ MqSendEND_AND_WAIT_C

◆ MqSendEND_AND_WAIT_E

◆ MqSendEND_AND_WAIT_NULL

◆ MqSendEND_C

◆ MqSendEND_E

◆ MqSendEND_NULL

◆ MqSendSTART

◆ MqSendSTART_C

◆ MqSendSTART_E

◆ MqSendSTART_NULL

◆ MqSendSYNC

◆ MqSendSYNC_C

◆ MqSendSYNC_E

◆ MqSendSYNC_NULL

Function Documentation

◆ MqSendEND_AND_CALLBACK_RT()

◆ MqSendEND_AND_SUB_RT()

◆ MqSendEND_AND_TRANSACTION_RT()

transaction-item

transaction-callback

◆ MqSendEND_AND_WAIT_RT()

◆ MqSendEND_RT()

◆ MqSendSTART_RT()

◆ MqSendSYNC_RT()