Topic: DMD0303

STREAMIN - Stream in Data from Device

The Stream in Data from Device (STREAMIN) instruction is used to retrieve data from a stream-capable input device (like a serial port) and store that data in either a String (if the data is ASCII text) or a numeric data block (if the data is binary).

 

 

The first time that a STREAMIN instruction is placed in a project this message will be displayed. This message alerts the user that the implementation will determine what type of internal storage will be required to store the data retrieved by the instruction.

 

The default memory configuration has STRINGs which can be used to store ASCII text, and blocks of Words and DWords that can be used to store integer and floating point data. But many communication protocols are constructed using Bytes and the Do-more controller does NOT have a pre-configured block of Unsigned Bytes. If a Byte buffer is needed, clicking Yes will open the Create Unsigned Byte Buffer Block dialog were one can be created.

 

Block Name (1 to 16 letters) - specifies the name of the data block to create, the default name STREAMINBuff can be changed if desired. Block names must be unique, and consist of 1 to 16 characters (A-Z, a-z; no numbers, no spaces).

 

Number of Bytes (multiple of 4) - specifies the size of the data block to create. Data blocks must be created on DWord (4-byte boundaries)

 

Block Range - displays the first and last element of the block that will be created based on the current entries for Block Name and Number of Bytes

 

Make data block retentive (retain values after power loss) - check this option to make the entire data block retentive which will preserve the contents of the block if the system power is lost.

Element References:

Note: Use the F9 key (Element Browser) or Down-Arrow key (Auto-Complete) at any time to see a complete list of the memory locations that are valid in the current field of the instruction.

 

Device - designates which of the configured Devices to read the data from. Before this instruction can select a Device, that Device must be configured to accept data from an external source. Part of the configuration for a device is assigning a name to the device. It is that name which will show up in the Device selection drop-down menu. For more information on configuring devices go to the Device Configuration Section under System Configuration.
 

  • Serial Port Devices - selects either the onboard serial port (@IntSerial), or one of the ports on a SERIO module.
     

  • Ethernet Devices - selects one of the Devices configured to use the onboard Ethernet port.
     

  • create device - indicates that there are no Stream Devices that have been configured to perform this instruction. Selecting this option will invoke the New Device configuration page of the System Configuration dialog where a suitable device can be created.

 

Complete When ... - this group of options sets the condition (or conditions) that are used to signal the completion of the Stream in Data from Device (STREAMIN) instruction. Any combination of the following three options can be used to signal the completion of the instruction:

 

  • Length - specifies the number of characters to receive in order to signal completion of the instruction. This can be any positive constant value or any readable numeric location.
     

  • Delimiters - specifies from one to three characters that signal the completion of the instruction
     

    • Exact Sequence - the specified characters must be receive in the order specified
       

    • Any One Delimiter - receipt of any of the specified characters will signal completion
       

    • Trim Delimiter(s) from Output String - specifies whether the delimiter character should be stored along with the input data, or removed from the input data before it's stored in the specified Output String
       

  • Network Timeout - specifies the maximum amount of time in milliseconds to allow the instruction to wait before signaling a completion. This value is a constant in the range of 1 to 65535. In the event that the Network Timeout causes the completion of the instruction, any input data that has been received will be discarded.

 

Advanced - the Advanced Settings dialog contains some optional post-processing operations that this instruction can perform on the input data before the data is stored in the destination location.

 

The Terminal Emulation Client Support allows the Stream in Data from Device (STREAMIN) instruction to perform some extra processing of the input data if the source of that data is a terminal emulator program. Enabling this option will cause the Stream in Data from Device (STREAMIN) instruction to perform a 'backspace' operation if a CTRL-H (0x08) character is received by removing the previous character in the input data buffer before the data buffer is stored in the destination location.

 

If this option left is disabled the Stream in Data from Device (STREAMIN) instruction will not post-process any of the data, it will leave both the previous character and the 'backspace' character (CTRL-H) in the input data buffer and both characters will be stored in the destination location.

 

Data Destination - selects where to store the data that has been read from the Stream Device. The option chosen will depend on the type of data that is received from the Stream Device. If the data is ASCII text the appropriate choice is String Structure. If the data is binary, or simple bytes of data the appropriate choice is a numeric block of bytes.

 

  • String Structure - designates a String where the data read from the Stream Device will be stored. This can be any of the system-defined Short Strings, or system-defined Long Strings, or any of the user-defined Strings.
     

  • Numeric Data Block - designates a memory block to store the data read from the Stream Device.

 

  • Create Byte Buffer - will invoke a dialog that allows the programmer to create a new data block of BYTEs to store the data
     

  • Start Address - the offset in an existing numeric data block to begin storing the data read from the Stream Device
     

  • Number of Bytes to Read - designates a location to store the number of bytes that were read from the Stream Device and stored in the designated location

 

Endian Settings - specifies optional processing to handle the Byte and Word ordering of the data
 

  • Swap Byte - swaps the Bytes in each Word of data
     

  • Swap Word - swaps the Words in each DWord of data
     

Note: select both options to swap the Bytes in each of the Words and swap the Words in each of the DWord elements

 

On Success: - designates one of the following two options if the Stream in Data from Device operation is successful:

 

  • SET BIT - The specific BIT location will be SET OFF when the Stream in Data from Device (STREAMIN) instruction is first enabled, and then SET ON if the operation is successful. This value can be any writable bit location.
     

  • JMP to Stage - JMP to the specified Stage. The target Stage must be in the same Program as the Stream in Data from Device (STREAMIN) instruction, you cannot specify a Stage in a different Program. This selection will function the same as a standalone Jump to Stage instruction. Click here for more information on the Jump To Stage instruction.

 

On Error: - designates one of the following two options if the Stream in Data from Device operation is unsuccessful:
 

  • SET BIT - The specific BIT location will be SET OFF when the Stream in Data from Device (STREAMIN) instruction is first enabled, and then SET ON if the operation is unsuccessful. This value can be any writable bit location.
     

  • JMP to Stage - JMP to the specified Stage. The target Stage must be in the same Program as the Stream in Data from Device (STREAMIN) instruction, you cannot specify a Stage in a different Program. This selection will function the same as a standalone Jump to Stage instruction. Click here for more information on the Jump To Stage instruction.

 

Status Display:

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

 

The gray triangle at the right end of an input leg indicates the input is edge triggered.

 

The Status display of the Stream In Data from Device instruction will only display as many of the characters of the destination location as will fit within the borders of the instruction, typically this is about 50 characters.

See Also:

 

Example Using Stages:

 

Rung Example: