Guidelines for using the I/O feature

Three options are available for the I/O Feature: Read (input), Write (output), and Read/Write (input/output).

Read

The Read option is used to read or copy a value from an external source (for example, a field controller) and place it in the Input attribute during each scan of the object. Generally, this option is used when only input functionality is required. If both read and write functionality are required, use the Read/Write option. The Read attribute runs before any custom scripts or custom logic within the object.

Write

The Write attribute is used to write a value from an attribute to an external destination (for example, a field controller). This attribute is used when write functionality is required. The write function can be configured to be performed every scan. By default, the write is performed only upon a change in value or quality of the attribute. The Write attribute runs after any custom scripts or custom logic within the object. Script logic within the extended object can manipulate the attribute, and the output will occur during the current scan period (since the script always runs before the Write attribute).

The last value that is set into the attribute while the host object is off-scan will be written to the field when the host object is placed back on-scan. The Write attribute does not output the initial value upon first deploy or upon a new startup of the hosting engine.

When an attribute is configured with a Write attribute and a write occurs, the initial value returned for the WriteStatus attribute is "Pending." Upon completion of the write (to the final output destination), the value of the WriteStatus attribute will be updated with the appropriate status. No writes for an attribute will occur on a subsequent scan if a previous scan still has a pending write. If multiple writes occur during a single scan, the last write controls the status.

If, during a single scan, an attribute of Boolean data type includes one or more transitions from TRUE to FALSE to TRUE (or vice-versa), and the first and last values written for the scan are the same (either both TRUE or both FALSE), the opposite of the last value will be written out to the field during the next scan. Then, the actual last value will be written out in the subsequent scan. This ensures that the transitions for pushbuttons in client applications are reflected.

Read/Write

The Read/Write option is used to read and write a value from and to an external address (for example, a field controller). The read function is performed every scan. The write function is performed only when the value or quality of the attribute that is extended changes, and the quality is GOOD or UNCERTAIN. The Read/Write option is the primary means of achieving a bidirectional connection to an external data source through a Feature and attributes.

You can configure the Read/Write option to reflect input to output. This is done when you want to read an input from one source, manipulate its value in a script, and send the manipulated value to a different destination address, all during a single scan of an object.

The read phase of the Read/Write option runs before any custom scripts or custom logic within the object. Therefore, scripts can use the current input value for their logic, since that value will be held in the attribute.

The write change detection determines whether to perform a write during a scan. This determination actually occurs prior to reading the value from the source and overwriting the attribute (so that the change request is not lost). If a change in value or quality has occurred, the new value to be written is placed in an attribute named WriteValue. Therefore, you could write a script to examine the attribute's WriteValue (as "me.<attribute>.writevalue") and perform validation or clamping on it. The WriteValue attribute is really the value that is "about to be written" when the script executes.

When an attribute is configured with the Read/Write option and a write occurs, the initial value returned for the WriteStatus attribute is "Pending." Upon completion of the write (to the final output destination), the value of the WriteStatus attribute will be updated with the appropriate status. No writes for an attribute will occur on a subsequent scan if a previous scan still has a pending write. If multiple writes occur during a single scan, the last write controls the status.

The following is an example of how an object handles values for an Read/Write attribute over the course of three scans.

Scan 0 ends:

• A value of 10 is requested to be written (for example, via a user request from InTouch).

Scan 1:

1. Execute the read phase:

   1. Since the current value of the attribute (10) is different than the previous value, set the WriteValue attribute to 10.

   2. Input a value (for example, 5) and copy the value of 5 into the attribute.

2. The script logic for the object runs. The current attribute value (5) is multiplied by 3 and is stored in another attribute named 'Multiply3,' so that the attribute value of 'Multiply3' becomes 15.

3. Execute the write phase:

   • Write the value in WriteValue (10).

Scan 2:

4. Execute the read phase:

   • Read a value. The value will probably be 10 (depending on timing), since that was the last value that was output during the last scan. Copy the value of 10 into the attribute.

5. The script logic for the object runs. The current attribute value (10) is multiplied by 3 and stored in another attribute called 'Multiply3,' so that the attribute value of 'Multiply3' becomes 30.

6. Execute the write phase:

   • No action.

When the Read/Write attributes are offscan:

• Values set into the attribute are written back into the attribute.

• Values written to the attribute are not buffered and written to the field when the attribute is set back onscan.

• The attribute is not updated to reflect values read in from field by the read portion of the Read/Write attribute.