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

Collaboration diagram for MqContextC_High_PY_API:

Functions
OT_ProcRet	py_mqmsgque_MqContextC_Send (MqContextC_ARGS)
	`Python: ctx.Send(cstr:string, args:args...)` → C-API user friendly replacement for the MqContextC_SendApi_C_API …

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

The token-signature has the usage "service-ident : send-signature @ read-signature" and is used to identify the target-service and the required arguments.
The service-ident is identified by the MQ_TOK item followed by a [:] and the send-signature.
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.
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()

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

The token-signature has the usage "service-ident : send-signature @ read-signature" and is used to identify the target-service and the required arguments.
The service-ident is identified by the MQ_TOK item followed by a [:] and the send-signature.
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.
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()

Function Documentation

◆ py_mqmsgque_MqContextC_Send()

OT_ProcRet py_mqmsgque_MqContextC_Send ( MqContextC_ARGS )

Python: ctx.Send(cstr:string, args:args...) → C-API
user friendly replacement for the MqContextC_SendApi_C_API …

Functions

Detailed Description

High_CALL_SIGNATURE

High_TOKEN_SIGNATURE

High_CALL_SIGNATURE

High_TOKEN_SIGNATURE

Function Documentation

◆ py_mqmsgque_MqContextC_Send()