MqContextC_HighApi_C_API

MqContextC - User friendly replacement for the MqContextC_SendApi_C_API and the MqContextC_ReadApi_C_API … More...

Collaboration diagram for MqContextC_HighApi_C_API:

Functions
MQ_EXTERN enum MkErrorE	MqSend_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_STRN cstr,...)
	user friendly replacement for the MqContextC_SendApi_C_API …
MQ_EXTERN enum MkErrorE	MqSendVL2_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_STRN cstr, va_list var_list)
	A version of MqSend with va_list support …

size of internal buffer to store strings for \e MqSend
#define	MQ_SEND_TRANSACTION_TOKEN_SIZE   10
#define	MQ_SEND_TOKEN_SIGNATURE_SIZE   50

type cast \e short to \e long
#define	MqHigh_O   BOL
#define	MqHigh_Y   I8
#define	MqHigh_S   I16
#define	MqHigh_I   I32
#define	MqHigh_W   I64
#define	MqHigh_H   HDL
#define	MqHigh_F   FLT
#define	MqHigh_D   DBL
#define	MqHigh_C   STR
#define	MqHigh_B   BIN
#define	MqHigh_U   BUF
#define	MqHigh_L   BFL
#define	MqHigh_A   BAC

MqContextC - MqContextC_HighApi_High_C_API - overload
#define	MqSend_NULL(...)
#define	MqSend(...)
#define	MqSend_E(...)
#define	MqSend_C(...)
#define	MqSendVL2_NULL(...)
#define	MqSendVL2(...)
#define	MqSendVL2_E(...)
#define	MqSendVL2_C(...)

Detailed Description

MqContextC - User friendly replacement for the MqContextC_SendApi_C_API and the MqContextC_ReadApi_C_API …

User Friendly mean, replacing many lines of code by a single line of code.
The basic idea is, to use a format-signature to identify the additional command-line-arguments (args…).

The pseudo syntax is:

MqSend( "CALL-SIGNATUR",call-args …,"TOKEN-SIGNATURE",send-args …,read-args …);
 
CALL-SIGNATUR     = "[E|W|C|S|T|R|t|r]" or ?call-args?
 
  E               =   MqSendEND                           ?t-arg = 0?
  W               =   MqSendEND_AND_WAIT,                 ?t-arg = MK_TIMEOUT_DEFAULT?
  C               =   MqSendEND_AND_CALLBACK,     c-arg,  ?t-arg = MK_TIMEOUT_DEFAULT?
  S               =   MqSendEND_AND_SUB,          c-arg,  ?t-arg = MK_TIMEOUT_DEFAULT?
  T               =   MqSendEND_AND_TRANSACTION,  i-arg,  ?t-arg = MK_TIMEOUT_DEFAULT?
  R               =   MqSendRETURN
 
  t               =   expect timeout value as t-arg in call-arg
  r               =   switch 'rpc-flag' on to enable 'rpc' style parsing of the TOKEN-SIGNATURE 
 
  call-args       =   ?c-arg?, ?i-arg?, ?t-arg?
    ?c-arg?       =     callback ... function, service
    ?i-arg?       =     ident ...... MQ_TOK service-identifer to receive the result
    ?t-arg?       =     timeout .... MK_TIME_T in seconds
 
TOKEN-SIGNATUR    = "service-ident:send-signature@read-signature"
 
  service-ident   =   MQ_TOK service identifier to call a remote service
  send-signature  =   ?(…)? or multiple [Y|O|S|I|F|W|D|G|C|B|U|L] or […]
    ?(…)?         =     only as FIRST arg, only for MqSendEND_AND_TRANSACTION
      (           =       MqSendT_START
      )           =       MqSendT_END
    [             =     MqSendL_START
    ]             =     MqSendL_END
    Y             =     MqSendI8
    O             =     MqSendBOL
    S             =     MqSendI16
    I             =     MqSendI32
    F             =     MqSendFLT
    W             =     MqSendI64
    D             =     MqSendDBL
    G             =     MqSendLONG
    C             =     MqSendSTR
    B             =     MqSendBIN
    U             =     MqSendBUF
    L             =     MqSendBFL
  read-signature  =   multiple [Y|O|S|I|F|W|D|G|C|B|U|L] or . or * or […]
    .             =     MqReadBUF
    *             =     MqReadALL
    [             =     MqReadL_START
    ]             =     MqReadL_END
    Y             =     MqReadI8
    O             =     MqReadBOL
    S             =     MqReadI16
    I             =     MqReadI32
    F             =     MqReadFLT
    W             =     MqReadI64
    D             =     MqReadDBL
    G             =     MqReadLONG
    C             =     MqReadSTR
    B             =     MqReadBIN
    U             =     MqReadBUF
    L             =     MqReadBFL

The following parts from the MqContextC_SendApi_C_API will be replaced by the MqContextC_HighApi_C_API

API Function	Usage
MqSendSTART	-> start a service call or a answer
SendATOM	-> write a single argument into the data-package
SendEND	-> send the service-call to the receiver
ReadATOM	-> read a single argument from the data-package
SendRETURN	-> answer a service call

The replacement is defined by two parts, a High_CALL_SIGNATURE and a High_TOKEN_SIGNATURE. Both parts are strings and descripe a type or an action of a vararg argument.

Example: a typical code replacement in C looks like

MkErrorCheck( MqSend( ctx, "Wt", 15, "SUBI:IDC@D", 5, 6.3, "HALLO", &doubleVal ) );

and replaces the following commands...

MkErrorCheck( MqSendSTART( ctx ) );
MkErrorCheck( MqSendI32( ctx, 5 ) );
MkErrorCheck( MqSendDBL( ctx, 6.3 ) );
MkErrorCheck( MqSendSTR( ctx, "HALLO" ) );
MkErrorCheck( MqSendEND_AND_WAIT( ctx, "SUBI", 15 ) );
MkErrorCheck( MqReadDBL( ctx, &doubleVal ) );

High_CALL_SIGNATURE

The Call-Signature is a string of call-signature-char (CFC) starting with "E", "W", "C", "S" or "R" followed optional with "t"

CFC	Required	Reference	call-args	Default	Usage
E	yes	once	no	yes	MqSendEND
W	yes	once	no	no	MqSendEND_AND_WAIT
C	yes	once	function or service	no	MqSendEND_AND_CALLBACK
S	yes	once	function or service	no	MqSendEND_AND_SUB
T	yes	once	service-ident	no	MqSendEND_AND_TRANSACTION
R	yes	once	no	no	MqSendRETURN
t	no	W,S,T	seconds	MK_TIMEOUT_USER	set the TIMEOUT

High_TOKEN_SIGNATURE

1. The token-signature has the usage "service-ident : send-signature @ read-signature" and is used to identify the target-service and the required arguments.
2. The service-ident is identified by the MQ_TOK item followed by a [:] and the send-signature.
3. The send-signature has one type-identifer for every send-argument. The send-argument is identified by a arg-signature-char (ASC) and is defined in MkTypeE.
4. The MkTypeE is used in the MkBufferU and descripe the type of a vararg argument or action.

ASC	MkTypeE	Usage	Number of arguments required
"Y"	MK_I8	MkBufferAtomU.I8	1
"O"	MK_BOL	MkBufferAtomU.BOL	1
"S"	MK_I16	MkBufferAtomU.I16	1
"I"	MK_I32	MkBufferAtomU.I32	1
"F"	MK_FLT	MkBufferAtomU.FLT	1
"W"	MK_I64	MkBufferAtomU.I64	1
"D"	MK_DBL	MkBufferAtomU.DBL	1
"G"	MK_LONG	32bit=I, 64bit=W	1
"B"	MK_BIN	MkBufferU.B	1 -> MkBinaryR reference
"C"	MK_STR	MkBufferU.C	1
"U"	MK_BUF	MkBufferC .	1 -> typeless Buffer able to hold every kind of data
"L"	MK_BFL	MkBufferListC .	1 -> list of MkBufferC .
"."	MK_BUF	MkBufferC .	1 -> READ ONLY - like 'U' but return the Buffer-Value and not the MkBufferC .
"*"	MK_BFL	MkBufferListC .	1 -> READ ONLY - like 'L' but collect ALL remaining data as ONE MkBufferListC .
"["		MqSendL_START	0 -> Start of List
"]"		MqSendL_END	0 -> End of List
"("		MqSendT_START	0 -> Start of Transaction Object, only as FIRST parameter
")"		MqSendT_END	0 -> End of Transaction Object, only ONE supported
":"		END of SERVICE-IDENT	* -> next SEND_SIGNATURE
"@"		END of SEND-SIGN.	* -> next READ-SIGNATURE

Example from server.py → in a service-call send the server-configuratien back to the client

  def CNFG (self):
    self.SendSTART()
    self.SendBOL(self.ConfigGetIsServer())
    self.SendBOL(self.LinkIsParent())
    self.SendBOL(self.SlaveIs())
    self.SendBOL(self.ConfigGetIsString())
    self.SendBOL(MkRuntimeC.GetIsSilent())
    self.SendBOL(self.LinkIsConnected())
    self.SendSTR(self.ConfigGetName())
    self.SendI32(MkRuntimeC.GetDebug())
    self.SendI32(self.LinkGetCtxId())
    self.SendSTR(self.ServiceTokenGet())
    self.SendRETURN()

Macro Definition Documentation

MQ_SEND_TOKEN_SIGNATURE_SIZE

#define MQ_SEND_TOKEN_SIGNATURE_SIZE   50

Definition at line 7957 of file LibMqMsgque_mq.h.

MQ_SEND_TRANSACTION_TOKEN_SIZE

#define MQ_SEND_TRANSACTION_TOKEN_SIZE   10

Definition at line 7956 of file LibMqMsgque_mq.h.

MqHigh_A

#define MqHigh_A   BAC

Definition at line 7974 of file LibMqMsgque_mq.h.

MqHigh_B

#define MqHigh_B   BIN

Definition at line 7971 of file LibMqMsgque_mq.h.

MqHigh_C

#define MqHigh_C   STR

Definition at line 7970 of file LibMqMsgque_mq.h.

MqHigh_D

#define MqHigh_D   DBL

Definition at line 7969 of file LibMqMsgque_mq.h.

MqHigh_F

#define MqHigh_F   FLT

Definition at line 7968 of file LibMqMsgque_mq.h.

MqHigh_H

#define MqHigh_H   HDL

Definition at line 7967 of file LibMqMsgque_mq.h.

MqHigh_I

#define MqHigh_I   I32

Definition at line 7965 of file LibMqMsgque_mq.h.

MqHigh_L

#define MqHigh_L   BFL

Definition at line 7973 of file LibMqMsgque_mq.h.

MqHigh_O

#define MqHigh_O   BOL

Definition at line 7962 of file LibMqMsgque_mq.h.

MqHigh_S

#define MqHigh_S   I16

Definition at line 7964 of file LibMqMsgque_mq.h.

MqHigh_U

#define MqHigh_U   BUF

Definition at line 7972 of file LibMqMsgque_mq.h.

MqHigh_W

#define MqHigh_W   I64

Definition at line 7966 of file LibMqMsgque_mq.h.

MqHigh_Y

#define MqHigh_Y   I8

Definition at line 7963 of file LibMqMsgque_mq.h.

MqSend

#define MqSend

(

...

)

Value:

MqSend_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 202 of file msgque_overload_mq.h.

MqSend_C

#define MqSend_C

(

...

)

Value:

if (MkErrorCheckI(MqSend(__VA_ARGS__)))

Definition at line 204 of file msgque_overload_mq.h.

MqSend_E

#define MqSend_E

(

...

)

Value:

MkErrorCheck(MqSend(__VA_ARGS__))

Definition at line 203 of file msgque_overload_mq.h.

MqSend_NULL

#define MqSend_NULL

(

...

)

Value:

MqSend_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 201 of file msgque_overload_mq.h.

MqSendVL2

#define MqSendVL2

(

...

)

Value:

MqSendVL2_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 206 of file msgque_overload_mq.h.

MqSendVL2_C

#define MqSendVL2_C

(

...

)

Value:

if (MkErrorCheckI(MqSendVL2(__VA_ARGS__)))

Definition at line 208 of file msgque_overload_mq.h.

MqSendVL2_E

#define MqSendVL2_E

(

...

)

Value:

MkErrorCheck(MqSendVL2(__VA_ARGS__))

Definition at line 207 of file msgque_overload_mq.h.

MqSendVL2_NULL

#define MqSendVL2_NULL

(

...

)

Value:

MqSendVL2_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 205 of file msgque_overload_mq.h.

Function Documentation

MqSend_RT()

MQ_EXTERN enum MkErrorE MqSend_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_STRN	cstr,
			... )

user friendly replacement for the MqContextC_SendApi_C_API …

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]	cstr	the High_CALL_SIGNATURE

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

See also

MqSendVL2

MqSendVL2_RT()

MQ_EXTERN enum MkErrorE MqSendVL2_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_STRN	cstr,
		va_list	var_list )

A version of MqSend with va_list support …

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]	cstr	the doc_mq_py_High_CALL_SIGNATURE
[in]	var_list	a variable argument list object

See also

MqSend