TCPLISTEN - Start Listening on TCP Port

Topic: DMD0072

Help File Version: 2.10.0.636

TCPLISTEN - Start Listening on TCP Port

The Start Listening on TCP Port (TCPLISTEN) instruction is used to Run a user-created Program when an external TCP Client establishes a connection to the specified TCP Server Device. Powerflow into the instruction controls whether or not the instruction is actively listening for connections; it has no effect on the ability of the 'On Connect' 'Program to run or not.

Note: this instruction is NOT used to communicate via Modbus/TCP protocol. This instruction is used to implement a custom communication protocol over a TCP/IP connection. Use the built-in Modbus/TCP Server to communicate via Modbus/TCP protocol.

Parameters:

Note: Use the F9 key or click the 'three dot box' at the right edge of the parameter field to open the Default Element Selection Tool (the Element Picker or the Element Browser) or use the Down-Arrow key (Auto-Complete) on any parameter field to see a complete list of the memory locations that are valid for that parameter of the instruction.

Device selects which preconfigured TCP Server device to open.

no devices available indicates that there are no TCP Server devices that can execute this instruction. The most likely causes are the CPU does not have an on-board Ethernet port, or a TCP Server Device has not been configured.

Select the create device option to open the Device Configuration dialog of the System Configuration to create a new TCP Server device.

On connect, run is the name of the Program that will be run whenever a connection request is received from a TCP Client, and that connection is successfully established. This can be an existing program or follow the steps below to create a new Program to run. Be aware that choosing to create a new Program will change the System Configuration, changes to the System Configuration can only be written to the CPU when it is in PROGRAM mode. Additional Run mode updates can not be performed until these System Configuration changes have been saved to the CPU.

If a name was entered that is NOT an existing Program, this Create Program message box will be displayed:

Click Yes to create a new Program using the name provided. This does NOT create the code-block, this is only the heap item. The code-block can be created in the next step. Click No to return to the Editor for the TCPLISTEN instruction so that a different name can be entered. If Yes is selected, you will be prompted to create the code-block associated with the Program that was just created.

Click Yes to create the code-block at this time. The associated code-block will be created and the Code-block Configuration dialog will then be displayed where the user can configure the runtime settings and the code-block protection. Click No to create the Program code-block at a later time. The code-block for this Program must be created before the project can be downloaded to the CPU.

If an existing TCPLISTEN instruction is being edited and the Program name is changed to a Program that does not exist, a different Create Program message box will be displayed. Again, this could have happened because the Program name was misspelled, or because you want to create a new Program.

Click Yes to create a new Program using the name provided in the Program field. Click No to return to the Editor for the TCPLISTEN instruction so that a different name can be entered.

Status Display:

The red triangle in the upper left corner of the status display indicates this is a Fully Asynchronous instruction.

The following structure fields will be shown in the status display:

.RanThisScan will be ON if the Program ran on the current scan and OFF if the Program did not run on the current scan.

.Done will be ON if the Program has run to completion at least one time. It will be OFF if the Program is currently running or has not yet been run.

Structure Memory:

The TCP Server has an associated structure that is used by the TCPLISTEN instruction. The syntax for using them is <TCP Device>.<flag name>.

The following fields of a Stream structure can be used in the project:

.InQueue (Read / write) - a 16-bit unsigned value that is the number of bytes of data in the Input Buffer.

.OutQueue (Read / write) - a 16-bit unsigned value that is the number of bytes of data are in the Output Buffer.

.Open (Read-only) - this Bit location will be ON if a TCPLISTEN has been executed and a corresponding CLOSE has not been executed .

.Connected (Read-only) - this Bit location will be ON if the TCP Server is currently connected to a TCP Client .

.CTS (Read-only) - not used.

.RTS - not used.

Note: if Connected is ON, you can use the DEVCLEAR - Clear Device instruction to clear the .InQueue and .OutQueue structure members as needed.