Make sure you have keyed your host message on the command name data item in the message definition. The script in the matching host message will be run when the host message is received. If you are having trouble with message matching, read the article on Message Matching.

As a quick test of message matching, enter a script which just prints out a simple message when the message is received, for example:

print("Received Host Message START");

This example uses the host command “STOP” as an example of message handling. The STOP command has no parameters for simplicity. The goal is to tell the control application that the STOP has been requested and send an S2F42 reply to the host with a code indicating whether or not the host command is accepted.

Here is how this STOP command is defined in TransSECS:

The highlighted node is the command name parameter with the value “STOP”. This is the “key” for the message matching. This parameter is also “published”. Publishing a parameter in the message allows access to the value using a “get” method or setting the value using a “set” method in a script. The name of the get or set method is the name of the parameter with get or set prepended. For example, to access the value of the Command parameter in the incoming message, use “getCommand()”.

print("Received Host Message STOP");
//write a flag to the device so that the control application knows that the STOP was received
/Devices/ModbusTCP_Severs/StopReceived->setIntValue(1);
 
//wait for the control application to reset this flag to "99" 
//we will wait up to 2 seconds (2000 ms), and check every 200 ms
 
//wait up to 2000 ms for the controller to acknowledge the STOP command and set the hcack
 
count=0;
flag=1; //when the flag changes to a different value, controller has finished processing
 
while ((flag==1) && (count<10)) { { //repeat up to 10 times for 2000 ms total
    java.lang.Thread.sleep(200);//wait 200 ms
    count++;
    flag=/Devices/ModbusTCP_Servers/StopReceived->getIntValue(); 
    //if flag is still 1, repeat wait, otherwise exit
 }
 
//get the hcack from the controller. 
 
if (flag!=1) { //controller acknowledged STOP command and calculated the hcack
  hcack=/Devices/ModbusTCP_Servers/StopCommandHCACK->getIntValue();
 } else {
 hcack=99; //controller timeout
}

The next step to handling the host command is to send the host command reply with the HCACK read from the device, or set to “99” if the controller timed out waiting for the message to be processed.

var TransSecsController = Java.type("com.ergotech.transsecs.secs.TransSecsController");
 
secsInterface=TransSecsController.findController("PLCTool"); 
//replace the parameter in findController with the name set for your tool in the TransSECS project
 
reply = secsInterface.getMessageBean("HostCommandReply"); 
//This will use the message defined in TransSECS called "HostMessageReply"
 
reply.setHCACK(Java.to([hcack],"byte[]")); //this sets the HCACK parameter in the HostMessageReply with the hcack read from the device (or "99" if the controller timed out)
 
//send the reply message
 
reply.sendMessage();

As an example, the host command START message in the PLCTool has a single parameter, PPID.

Here is how this message is defined:

The value of the PPID parameter, CPValue, is published so it can be obtained from the incoming message using “getCPValue()”.

Here is a script example of handling the incoming START command message:

secsInterface=TransSecsController.findController("PLCTool");
hostcommand=secsInterface.getMessageBean("HostCommandSTART"); //match exactly the name of the message as set in the TransSECS project
 
print("Received Host Message START");
 
//the CPValue data item of the message is the recipe name (PPID)
recipeName = hostcommand.getCPValue();
 
 
//set the incoming PPID in the controller so it can be processed
/Devices/ModbusTCP_Servers/RecipeName->setStringValue(recipeName);
 
 
//signal the controller that a START command has been received
/Devices/ModbusTCP_Severs/StartReceived->setIntValue(1);
 
//wait for the controller application to change this flag value
//we will wait up to 2 seconds (2000 ms), and check every 200 ms
 
//wait up to 2000 ms for the controller to acknowledge the STOP command and set the hcack
 
count=0;
flag=1; //when the flag changes to a different value, controller has finished processing
 
while ((flag==1) && (count<10)) { { //repeat up to 10 times for 2000 ms total
    java.lang.Thread.sleep(200);//wait 200 ms
    count++;
    flag=/Devices/ModbusTCP_Servers/StartReceived->getIntValue(); 
    //if flag is still 1, repeat wait, otherwise exit
 }
 
//get the hcack from the controller. 
 
if (flag!=1) { //controller acknowledged START command and calculated the hcack
  hcack=/Devices/ModbusTCP_Servers/StartCommandHCACK->getIntValue();
 } else {
 hcack=99; //controller timeout
}

The next step is to send the host command reply. This is done the same way as for the STOP command, see example above.

It may be necessary to send the host command reply with a bad parameter indicated. In the TransSECS message definition there is a message called “HostCommandRejectedBadParam”. Two parameters need to be set before this message can be sent. The first one is the bad parameter name and the second one is the bad parameter reason code from the SEMI E05 specification.

//send host command reply with a bad parameter name and reason code
 
secsInterface=TransSecsController.findController("PLCTool");
 
reply = secsInterface.getMessageBean("HostCommandRejectedBadParam");
reply.setHCACK(Java.to([3],"byte[]"));
reply.setCPName("PPID");
reply.setCPACK(Java.to([2],"byte[]"));//1=unknown parameter, 2=bad value, etc.
 
reply.sendMessage();

The script which handles the host command can optionally send a related event. Events are usually sent from the device by setting the device's tag which is connected to the CEID trigger. This script provides an optional way to send the same event.

//trigger the STARTED Event (as an example of triggering an event). The event will only 
//be triggered if the STARTED CEID has been enabled by the host and if the hcack is 0 or 4 (OK to execute command)
 
if (hcack==0 || hcack==4) {
startedEvent = secsInterface.getGemHandler().getServerForName("ceid.STARTED");
startedEvent.setIntValue(1); //triggers the event
}