Serial Communication Library and components for rs-232, tcp/ip communication. Data transfer and file transfer protocols ZMODEM, YMODEM, KERMIT, MODBUS, 3964, RK512, LSV2. Supporting Visual Studio NET, C#, VB Net, class library, Delphi, C++ Builder, Visual Basic.

Data transfer and file transfer protocols ZMODEM, YMODEM, KERMIT, MODBUS, 3964, RK512, LSV2. Supporting Visual Studio NET, C#, VB Net, class library, Delphi, C++ Builder, Visual Basic. Serial Communication Library and components for rs-232, tcp/ip communication.

Data Filtering, Data Monitoring, Data Trigger, Data Packets, File Transmission Queue

This section presents some concepts of the SuperCom Software that considerably speeds up the software development process. The result is a reliable solution developed much faster than with regular tools.

As it's common practise in SuperCom software, the following samples can be used without changes over the supported communication links (e.g. serial, TCP/IP or ISDN).

Data Packets
A very common problem in data transmission is receiving data packets according to some specifications (lookup strings). For this often complex operation SuperCom provides easy to use functions. The lookup strings is sometimes used to provide login information (e.g. "UserName:", "Password:" lines expected when connecting to servers on remote PC or mainframes) or to catch complete telegrams in data links. The following sample presents a simple data packet defined between STX and ETX captured by the SuperCom function:

DLL API

  char cStart=STX; // start sequence
  char cStop =ETX; // end sequence

     :

  if (DP_OK(RS_GetDataPacket(
                 szBuffer,
                 BufLen,       // len of buffer
                 cStart,       // Starts with
                 sizeof(cStart),
                 cStop,        // ends with
                 sizeof(cStop),
                 0, // ignore parameter, return what's received
                 &TimeOut))
  {
     :
  }

     :

  

  cStart:Array[0..0] Of Char=(STX); // start sequence
  cStop :Array[0..0] Of Char=(ETX); // end sequence

     :

  If (DP_OK(RS_GetDataPacket(
                 szBuffer,
                 BufLen,       // len of buffer
                 cStart,       // Starts with
                 SizeOf(cStart),
                 cStop,        // ends with
                 SizeOf(cStop),
                 0, // ignore parameter, return what's received
                 @TimeOut)) Then
  Begin
     :
  End;

     :

  

  Dim cStart As Byte  ' start sequence
  Dim cStop As Byte   ' end sequence

  cStart = STX
  cStop  = ETX

  If (SCOM_DP_OK(RS_GetDataPacket(
                 szBuffer,
                 BufLen,       ' len of buffer
                 cStart,       ' Starts with
                 LenB(cStart),
                 cStop,        ' ends with
                 LenB(cStop),
                 0, ' ignore parameter, return what's received
                 TimeOut)=True) Then

     :
   EndIf

     :
  

  char cStart=STX; // start sequence
  char cStop =ETX; // end sequence

     :

  if (DP_OK(RS_GetDataPacket(
                 szBuffer,
                 BufLen,       // len of buffer
                 cStart,       // Starts with
                 Marshal.SizeOf(cStart),
                 cStop,        // ends with
                 Marshal.SizeOf(cStop),
                 0, // ignore parameter, return what's received
                 TimeOut))
  {
     :
  }

     :

  

The parameter cStart, cStop define the rules a data packet must comply with (the lookup strings). When called the function receives a data packet according to the rules set or the requested amount of data received or the specified timeout occured. The parameter cStart and cStop are defining the expected start and stop sequence that makes a complete data packet or cannot be defined at all.

The parameter for Start and Stop can be a single data byte (character) or a sequence of data bytes.

WildCards
It's not uncommon that an expected data packet (string, etc.) is not completely defined e.g. a checksum in a specific position, a "LEN" byte etc. A Wildcard can here present the solution. A Wildcard is a character that substitutes for other character. For our purpose the Wildcard "\?" was defined. It uses two characters to define but substitutes one single character. Whenever a data byte in a specific position within the data packet is unknown it can be marked with the wildcard "\?". In the above sample the buffer of the parameter (cStart or cStop) "H\?llo" physically uses 6 bytes but it defines a start or stop sequence of 5 bytes. It will match for any combination of the second character e.g. "Hello", "Hallo".

This function is so flexible and reliable that many customers realize even fast protocols via this interface. It may save hundreds of hour spent on debugging the protocols synchronization. Once set it works reliable and returns the expected data packets.

Sample #2

     :
  char cBuffer[1024];
  DWORD dwDataCount=sizeof(cBuffer);
  TSYSTIME TimeOut=SEC_10;
     :

  sLineEnd = "\r\n"; // CRLF
  dwLen = (DWORD)strlen(pLineEnd);
  dwRes = RS_WaitString(Com,
                        cBuffer,      // buffer
                        &dwDataCount, // max bytes expected
                        sLineEnd,
                        dwLen,
                        &TimeOut,
                        WSCF_BINARY);
     :

  

     :

  Var cBuffer:Array[1..1024] Of Char;
      dwDataCount:DWORD=Sizeof(cBuffer);
      TimeOut:TSYSTIME=SEC_10;
     :

  sLineEnd = PCHAR(#13#10);
  dwLen = StrLen(sLineEnd);
  dwRes = RS_WaitString(Com,
                        cBuffer,      // buffer
                        dwDataCount,  // max bytes expected
                        sLineEnd,
                        dwLen,
                        @TimeOut,
                        WSCF_BINARY);
     :
  

     :

  cBuffer = Spaces(1024)
  dwDataCount=1024
  TimeOut=SEC_10
     :
  sLineEnd = vbCRLF;
  dwLen = Len(sLineEnd);
  dwRes = RS_WaitString(Com,
                        cBuffer,      ' buffer
                        dwDataCount,  ' max bytes expected
                        sLineEnd,
                        dwLen,
                        TimeOut,
                        WSCF_BINARY);
     :

  

     :

  byte[]   sLineEnd;
  byte[]   cBuffer     = new byte[1024];
  DWORD    dwDataCount = 1024
  TSYSTIME TimeOut     = SEC_10
  DWORD    dwLen = StringToBuffer("\r\n", sLineEnd); // custom function

  dwRes = SuperCom.RS_WaitString(Com,
                        cBuffer,      // buffer
                        dwDataCount,  // max bytes expected
                        sLineEnd,
                        dwLen,
                        TimeOut,
                        WSCF_BINARY);
     :

  

The function RS_WaitString demonstrates another way to receive complete strings or data packets. RS_WaitString waits until a complete line received. The line is defined to end with CRLF. If the line terminator is not received within the speficied Timeout the function returns with any received data in cBuffer.

Even easier does this the ActiveX API .

     GetBinary(&v, "a\\?\r\n", 4); // custom function
     m_SCom.SetDPStart(v);

     GetBinary(&v, "\r\n", 2); // custom function
     m_SCom.SetDPStop(v);

     m_SCom.SetDPTimeout(5*SEC_1);
     m_SCom.SetDPLimitLen(50);

     m_SCom.SetDPCollect(true);
  

     SCom1.DPStart := 'a\?'#13#10;
     SCom1.DPStop := #13#10;

     SCom1.DPTimeout := 5 * SEC_1;
     SCom1.DPLimitLen := 10;

     SCom1.DPCollect := 1;


  

     SCom1.DPStart = "a\?" & vbCr & vbLf
     SCom1.DPStop = vbCr & vbLf

     SCom1.DPTimeout = 3 * SEC_1
     SCom1.DPLimitLen = 10

     SCom1.DPCollect = True


  

     SCom1.DPStart = "a\\?\r\n";
     SCom1.DPStop = "\r\n";

     SCom1.DPTimeout = 3 * SEC_1;
     SCom1.DPLimitLen = 10;

     SCom1.DPCollect = true;


  

The properties DPStart, DPEnd, DPLimitLen and DPTimeout define the rules for the Data Packet and DPCollect activates the Data Packet Collector. From that point on the Data Packet Collector collects and reports data packets according to the rules (Start="a?"CRLF, End=CRLF, where '?'= any char). The Data Packet Collector is reporting the event through the event function OnDataPacket which also delivers the data packet.

The properties DPStart, DPEnd can be defined as needed or not (e.g. Start="a?"CRLF, End=CRLF, where '?'= any char). DPStart, DPEnd can contain a single data byte (character) or a sequence of data bytes.

WildCards
It's not uncommon that an expected data packet (string,...) is not completely defined (a checksum, a "LEN" byte). A Wildcard can here present the solution. A Wildcard is a character that substitutes for other character. For our purpose the Wildcard "\?" was defined. It uses two characters to define but substitutes one single character. Whenever a data byte in a specific position within the data packet is unknown it can be marked with the wildcard "\?".

In the above sample the buffer of DPStart was defined as "a\?"CRLF. It physically uses 5 bytes but it defines a start sequence of 4 bytes ("ax"CRLF). It will match for any combination of the second character e.g. "at"CRLF, "aT"CRLF, "ax"CRLF, etc.

The Data Packet Collector is executing completely in background. The application can now do other thinks until it receives events with the reported data packets. An automated data packet collector very simple activated!

Trigger
There are situations where the communication library is the one that should act fast on some special data received. The application can do other thinks until the received data require attention. The application will receive a data available event in order to act on.

As shown in the next sample SuperCom makes it realy easy to set and expect events on special data called Trigger. The used lookup string is sometimes used to provide login information (e.g. "UserName:", "Password:" used when connecting to servers on remote PC or on mainframes) or to inform about special sequemces of data when received. The following sample presents the setup of Trigger pair:

DLL API

     :

  pTrigger = "Username:|Password:";
  dwLen = (DWORD)strlen(pTrigger);
  dwRes = RS_WaitString(Com,
                        NULL, // ignored
                        NULL, // ignored
                        pTrigger,
                        dwLen,
                        NULL, // ignored
                        WSCF_TRIGGER_ADD);
     :
    // or do the same using the Trigger Helper API
  TriggerAdd(Com, pTrigger, dwLen);

  

     :

  pTrigger = PCHAR('Username:|Password:');
  dwLen = StrLen(pTrigger);
  dwRes = RS_WaitString(Com,
                        NIL, // ignored
                        NIL, // ignored
                        pTrigger,
                        dwLen,
                        NIL, // ignored
                        WSCF_TRIGGER_ADD);
     :
    // or do the same using the Trigger Helper API
  TriggerAdd(Com, pTrigger, dwLen);

  

     :

  sTrigger = "Username:|Password:";
  dwLen = Len(sTrigger);
  dwRes = RS_WaitString(Com,
                        0, ' ignored
                        0, ' ignored
                        sTrigger,
                        dwLen,
                        0, ' ignored
                        WSCF_TRIGGER_ADD);
     :
    // or do the same using the Trigger Helper API
  Call TriggerAdd(Com, Trigger)

  

     :

  byte[] Trigger;
  dwLen = StringToBuffer("Username:|Password:", Trigger); // custom function
  dwRes = SuperCom.RS_WaitString(Com,
                        null, // ignored
                        null, // ignored
                        Trigger,
                        dwLen,
                        null, // ignored
                        WSCF_TRIGGER_ADD);
     :
    // or do the same using the Trigger Helper API
  TriggerAdd(Com, Trigger, dwLen);

  

As Trigger the functions accepts a text string or a binary data packet.

A Trigger can be a single data byte (character) or a sequence of data bytes.

The function RS_WaitString is used to install one or more Trigger (in the above sample a multi-trigger). From now on SuperCom observes the received data stream and as soon SuperCom receives the string "UserName:" or "Password:" it will report the Trigger through an event. Since no other rules are set the data will be observed without restrictions to the character case.

WildCards
It's not uncommon that an expected data packet (string,...) is not completely defined e.g. one or more data bytes are unknown. A Wildcard can here present the solution. A Wildcard is a character that substitutes for other characters. For triggers purpose the Wildcard "\?" was defined. It uses two characters to define but substitutes one single character. Whenever a data byte in a specific position within the trigger is unknown it can be marked with the wildcard "\?". The buffer of the trigger "H\?llo" physically uses 6 bytes but it defines a trigger of 5 bytes. It will match for any combination of the second character e.g. "Hello", "Hallo". An extra small manual covers this powerfull Trigger Helper API and also presents some aspects of using triggers with protocols.

The Trigger mechanism is a real relief for the application. As soon SuperCom receives the awaited data it will report it. The Trigger event EV_TRIGGER is received by the application through the known UserEventProc.

ActiveX API

     :
   v = "Username:|Password:";
   m_SCom.SetTrigger(v);
   m_SCom.SetTriggerAction(SCOMM_TRIGGER_ADD);
     :
  

     :
   SCom.Trigger:='Username:|Password:';
   SCom.TriggerAction:=SCOMM_TRIGGER_ADD;
     :

  

     :
   SCom.Trigger="Username:|Password:"
   SCom.TriggerAction=SCOMM_TRIGGER_ADD
     :

  

     :
   SCom.Trigger="Username:|Password:";
   SCom.TriggerAction=SCOMM_TRIGGER_ADD;
     :

  

The property Trigger defines the trigger (lookup string) and the property TriggerAction defines the action to perform on the defined trigger (e.g. ADD = observe and report). From that point on "Trigger" events will get reported as soon SuperCom receives the string "UserName:" or "Password:".

As soon SuperCom receives a trigger it reports the event SCOMM_EV_TRIGGER to the OnComm event function. One can define any amount of triggers as needed and remove every single one using the above properties.

WildCards
For unknown data bytes (characters) the Wildcard "\?" can be used e.g. "H\?llo".

DataFilter
Some tasks require to inspect and/or change data while received or transmited. It's obvious that letting SuperCom do this is advantageous.

SuperCom supports low level data filtering functionality inside the library (DataFilter). Predefined data filter can perform within the library and custom filter using custom functions.

DLL API

     ComFilterInit(FLAG_DATA_FILTER_RX_STRIP_NULL |
                   FLAG_DATA_FILTER_TX_STRIP_NULL);
     :
  

     ComFilterInit(FLAG_DATA_FILTER_RX_STRIP_NULL OR
                   FLAG_DATA_FILTER_TX_STRIP_NULL);
     :
  

     Call ComFilterInit(FLAG_DATA_FILTER_RX_STRIP_NULL OR _
                        FLAG_DATA_FILTER_TX_STRIP_NULL);
     :
  

     SuperCom.ComFilterInit(FLAG_DATA_FILTER_RX_STRIP_NULL |
                            FLAG_DATA_FILTER_TX_STRIP_NULL);
     :
  

The function ComFilterInit activates the SuperCom data filter. The whole data filter mechanism is running at low level within the library. There exist many predefined filter that can be set using ComFilterInit. The application will always receive the data after all conversions done.

The SuperCom DLL API allows to install custom Rx and Tx functions in order to implement custom filtering algorithms. These functions are called by the SuperCom call stack at low level.

ActiveX API

     m_SCom.DataFilter(FLAG_DATA_FILTER_RX_STRIP_NULL);

  

     SCom1.DataFilter:=FLAG_DATA_FILTER_RX_STRIP_NULL;

  

     SCom1.DataFilter=FLAG_DATA_FILTER_RX_STRIP_NULL

  

     SCom1.DataFilter=FLAG_DATA_FILTER_RX_STRIP_NULL;

  

The property DataFilter defines one or more filtering rules from the default SuperCom filtering rules set and activates the data filering mechanism. There exist many pre-defined filter that can be set using DataFilter. The application will always receive the data after all conversions done.

The SuperCom DLL API allows to install low level custom Rx and Tx functions in order to implement custom filtering algorithms. These functions are called by the SuperCom call stack at low level.

Summarizing
The presented tools are offering different ways to complete the mission. Other combinations are also possible. The manual provides additional information and on specific questions our technical team surely can show additional solutions.

Intelligent functions can solve complex tasks. Exactly as one would expect from a professional Tool.

A DUAL API SuperCom software allows even better utilization of the presented tools. Among other things, it allows to call functions from the ActiveX API and DLL API as required.

Versatility
SuperCom is still the number one toolkit that supports different development environments providing extensive API support and samples. You're free to switch your compiler anytime and your are not bound to one and only. This saves a huge amount of time and costs of development.