Leveraging SMAT API for Cloverleaf

Have you ever wanted to save messages to SMAT beyond the protocol thread inbound and outbound only? Now you can, in Cloverleaf v6.2 or higher.

In this blog, you'll learn how to leverage SMAT API to save messages in additional TPS contexts. Just like the traditional SMAT database, you can write messages to a SMAT database in other locations within the engine, not only on inbound and outbound protocol threads.

The user-defined SMAT database contains each of these features (compared to the traditional IB/OB SMAT database):

• Full operations
• Multiple writers
• Resend mapping
• Trace storage

These behaviors are shared between the two types of SMAT databases:

• The table schema is identical.
• The SMAT history and cycle logic match the configuration of the traditional IB/OB SMAT database.
• The encryption key is equivalent to that of the SMAT database (the site name).

Additional points:

• Tcl and Java TPS are supported by the SMAT API.
• External Tcl scripts, like Tcl in an hcitcl shell, are also supported.
• The Java TPS still exists within Tcl (not natively).
• xltp and jxltp are not supported.

Follow these three steps to Save Messages to Save files (SMAT database files):

1. Open the Save file.

smatdbopen smatdbName ?-e msgEncoding?

smatdbName = The name of the Save file you will write to.

-e msgEncoding = multibyte encoding permits the system to use Unicode character encoding effectively.

• Example: 
  • set smatHandle [ smatdbopen ${HciConnName}_${ctx}.smatdb ]

• Important reminder:
  • By default, the SMAT files will be created in the process execution directory.

2. Insert the message into the Save Message database.

smatdbinsert smatdbHandle  msgID ?saveContext?

smatHandle = The handle to the Save Message database.

msgId = The message handle you want to insert into the smatDB.

saveContext = The context you wish to save the Save Message into the database.

• Example: 
  • smatdbinsert $smatHandle $mh "tclsmat"

• Important reminders:
  
  • If the SMAT (Save file) file is not open, you must open the SMAT (Save file) before inserting the message.
  • Likewise, you cannot insert a message from the Tcl SMAT API into the traditional SMAT files.

3. Close an SMAT database.

First, close the samtDB:

smatdbclose SMATDBHandle

smatHandle = The handle to the Save Message database.

• Example: 
  • smatdbclose $smatHandle

Then, to cycle the smatDB file, run the following command:

smatdbcycle smatdbHandle

smatHandle = The handle to the Save Message database.

• Example: smatdbcycle $smatHandle

• Important reminders:
  • If the SMAT (Save file) is not open, you must open the SMAT (Save file) before cycling.
  • The SMAT handle will point to the new SMAT file.
  • You may only have one old SMAT (Save file) at a time.
  • SMAT history doesn't affect the Tcl SMAT API, so the old SMAT files should be archived.

Thank you for reading this blog on Cloverleaf SMAT API. More commands for SMAT API are available in the Cloverleaf documentation by searching for Tcl SMAT API.