Introduction

The IMTdvCmdProtocol5 is a component which sends and receives command strings through TCP/IP. The component gives events when it receives commands and values.

The TCP/IP transport layer for the component is provided by the ActiveX component Internet Messenger from TORDIVEL SOFTWARE SOLUTIONS.

There is a companion ActiveX component called RS232TdvCmdProtocol with the same interface working over RS-232 as its transport layer.

This IMTdvCmdProtocol5 is a part of the TORDIVEL SOFTWARE SOLUTIONS.

IMTdvCmdProtocol5 is copyright of TORDIVEL AS 2002.

23 May 2002, Oslo, Norway.

Help Index

•	The Package

•	Properties

•	Methods

•	Events

•	Protocol

•	Using the test program


The Package

The package consists of

•	IMTdvCmdProtocol5.ocx (the component)

•	ReadMe.txt (read me file)

•	IMTdvCmdProtocol5.hlp (help file)

•	IM4TestApp.exe (test program)


Properties

Name	Type	RW	Description
ConfigXML	WideString	RW	The complete configuration in SPB-XML format.
Timeout	Integer	RW	The time the component waits before the data is deemed lost. Default: 20 s
Checksum	WordBool	RW	This property has no effect, but is included to make the interface equal to the one of RS232TdvCmdProtocol. Default: FALSE
Separator	Byte	RW	The character that separates multiple commands in one data string. Default: ‘;’
PortOpen	WordBool	R	Indicates whether the port is open
Mode	Integer	RW	Three values are valid: 0: Normal 1: Simulator 2: Disable


Methods

Name	Parameters	Return Value	Description
Send	Command: WideString		Sends Command
SetPortNo	PortNo: integer		Sets the port number for the communication. Default: 8700
GetPortNo		Integer	Gets the port number
SetPortParametres	Parametres; WideString		Sets the name and port of the remote computer. The syntax is “computer:port”, e.g. “localhost:8701” or “127.0.0.1:8701”
GetPortParametres		WideString	Gets the name and port of the remote computer
SetLicence	LicenceKey: WideString
AboutBox			Shows the About box


Events

Name	Parameters	Description
OnCommand	Command: WideString	Occurs when a command is received
OnValue	Name, Value; WideString	Occurs when a value is received
OnError	Id: Integer; Error: WideString	An error has occurred: Id = 1: Port already open Id = 2: Port not open Id = 3: Invalid port number Id = 4: No port selected Id = 5: No configuration file is defined Id = 6: Parametres error Id = 7: Timeout Id = 8: Checksum error
OnConfigureChange		Occurs when the configuration changes
OnPacketStart	Source: WideString	Occurs when a packet is being received
OnPacketEnd	Source: WideString	Occurs when a complete packet has been received
OnRequest	Command: WideString Values: OleVariant	Occurs when a command and several values are received. If the received message contains more than one command, this event occurs for each command. The Values parameter is normally a two dimensional array, with the value’s name in the first column and its value in the second


Protocol

The TDVCmdProtocol is a simple text-format where commands and values are separated with the ‘;’-character. A command is defined as a string and a value is defined by a tag and a value separated with an ‘=’ character.

A typical message consists of a command and a couple of values:

example : watch;program=scorpion;value=on

Using a text protocol where values are identified with tags and commands are commands means that application protocols can be defined and extended without having the receiving parser to fail even if command or values are unknown when received.

The IMTDVCmdProtocol uses transport layer defined by Internet Messenger to securely transmit the messages over TCP/IP. This protocol is simple and text-based to make it easy to implement.

The Internet Messenger 4 Network Protocol is pure text with the following properties:

•	No restriction on message size

•	A message has the following format:

•	Header – format is <ip>:<port>:

•	zero-terminated ASCII string

•	Each message is acknowledge by sending a lf-character to the client in the open socket

Procedure to send a message to an Internet Messenger server is:

1.	Open a socket

2.	Format Header with requester 193.69.239.12:80:

3.	Concat the header and the zero-terminated message string:
“193.69.239.12:80: watch;program=scorpion;value=on<null>”

4.	Send the package over the open socket

5.	Wait for an acknowledge

6.	Close the socket.

The ip –format is 193.69.239.10.

The complete ASCII table


Using the test program

The purpose of this program is to test and demonstrate the IMTdvCmdProtocol5 component.

The program consists of the following tabs:

•	IMTdvCmdProtocol5, which shows the component’s GUI

•	SimpleScheduler3, which lets you enable automatic sending of stings

•	About


IMTdvCmdProtocol5

Commands and values which are received are listed in the log, along with any warnings and error messages. You can configure the log to show what you want to see and how you want to see it.

The messages are listed according to the table below:

Message	Level	In\out	Normal	Raw data
STX	2	In	‘Packet start’	‘<STX>’
ETX	2	In	‘Packet end’	‘<ETX>’
ACK	2	In	‘Acknowledged’	‘<ACK>’
Command	1	In\out	Command	Command
Value	1	In\out	Value	Value
If then Raw data check box is checked all messages are shown as they are sent or received.

You can choose between three different modes:

1.	Normal

•	The port is open.

•	Messages are sent and received, events are generated and messages are shown in the log according to the Show in / out messages checkboxes.

2.	Simulator

•	The port is open

•	Received messages are shown in the log, but no events are generated

•	Sent messages are shown in the log, but are not physically sent.

3.	Disable

•	The port is closed.

•	No messages are sent or received, and nothing is shown in the log.

From the panel which appears when ticking the Show simulator checkbox you can simulate sending and receiving messages.


Log configuration

By right clicking in the log you get a menu as shown below. Here you can set which levels you want to display, you can set the log’s size, empty it, delete it, and by choosing Configuration you can set more advanced options.


Advanced Log Configuration

In this dialog you can customize the log’s layout, - e.g. set the columns’ captions, fonts and colors.

You can also set the format to display date/time information, where

H: hour

N: minute

S: second

Z: ms

D: day

M: month

Y: year

Example:

hh:nn:ss.zz DD/MMM/YYYY yields 16:34:52.22 30/JAN/2001


Normal mode

In normal mode the strings are actually sent when pressing the Send button and the From application checkbox is ticked.


Simulator mode


Disable mode


SimpleScheduler3

Press the SimpleScheduler3 tab to enable automatic sending of strings.


About


The Complete ASCII table


TORDIVEL SOFTWARE SOLUTIONS

TORDIVEL AS Software House is developing a portfolio of Windows NT/2000 software components and solutions with the following properties:

•	Simple and easy to use

•	Very high quality

•	Requirements from real use cases

•	Easy to deploy

•	"Simply working"

•	Network applications building blocks

Important keywords are: HTTP, TCP/IP, XML, and stateless servers.

These components and solutions are divided into two categories:

•	Professional Software Components

•	Freeware Components Library

We distribute the components and solutions to promote the skills of the experienced developers working at TORDIVEL and want to establish links to developers and companies all over the world.

If you have comments/suggestions your feedback is more than appreciated. Please contact us.

Storgata 20 N-0184 OSLO NORWAY
Telefax +47 2315 8701 Telephone +47 2315 8700
E-mail: office@tordivel.com Web: http://www.tordivel.com


Copyright Notice

(c) 2002 IMTdvCmdProtocol5 is copyright of

Storgata 20 N-0184 OSLO NORWAY
Telefax +47 2315 8701 Telephone +47 2315 8700
E-mail: office@tordivel.com Web: http://www.tordivel.com