IODeviceControl
Provides control of individual I/O devices. You might need to call this function several times. If you use incompatible values for the various options of this function, you might get unpredictable results.
This function can only be used if the I/O Server is on the current machine. When the I/O Server is not in the calling process, this function will become blocking and cannot be called from a foreground task. In this case, the return value will be undefined and a Cicode hardware alarm will be raised.
Syntax
IODeviceControl(IODevice, Type, Data [, ClusterName] [, ServerName] )
IODevice:
The number or name of the I/O device. If you call this function from an I/O server, you can use the I/O device name. If you call this function from a client, you may use either the I/O device number or name. To specify all I/O devices, use "*" (asterisk) or -1.
Type:
The type of control action:
0 - No longer supported.
1 - Enable/Disable the I/O device on the I/O server. If disabled, attempts to read and write from the I/O device are ignored. (If another I/O device is configured as a standby I/O server, CitectSCADA switches communications to that I/O device.) The I/O server does not attempt to communicate with the I/O device until it is re-enabled. When the I/O device is re-enabled, the I/O server attempts to re-establish communication immediately. Mode 1 can only be called by the I/O Server which is associated with this device.
2 - No longer supported. An invalid argument error is returned if this option is specified.
3 - No longer supported. An invalid argument error is returned if this option is specified.
4 - The data in the associated I/O device cache is flushed. This allows flushing of the data from the I/O device without waiting for the aging time. This is useful when you have long cache time and you want to force a read from the I/O device.
The Data value is ignored with this mode.
5 - (For scheduled and remote I/O devices). The I/O device is added to the bottom of the list of I/O devices to be contacted. I/O devices already in the list (already waiting to be contacted) are given priority over this I/O device.
6 - (For scheduled and remote I/O devices). The I/O device is added to the top of the list of I/O devices to be contacted; it is given high priority. If there are already I/O devices at the top of the list with high priority, then this I/O device will be added to the list after them (that is it will be contacted after them). For dial-up remote I/O devices, if the modem is already in use - connected to another I/O device - this I/O device will not be dialled until that connection has been terminated.
7 - (For scheduled and remote I/O devices). The I/O device is added to the top of the list of I/O devices to be contacted, and it is given top priority. For dial-up remote I/O devices, if the modem is currently connected to another I/O device, the connection will be cancelled, and the top priority I/O device will be dialled. It will also stay connected until manually disconnected with another call to IODeviceControl().
Note: This mode will not attempt to disconnect any other persistent connections. Persistent connections can only be disconnected using mode 8.
8 - (For scheduled and remote I/O devices). Disconnect an I/O device. Current requests will be completed before the I/O device is disconnected.
9 - (For scheduled I/O devices). The communication schedule for the I/O device is disabled. This is to minimize the likelihood that the I/O device will be contacted when its scheduled dial-time occurs.
10 - (For scheduled I/O devices). Puts the I/O device into Write On Request mode. That is, as soon as a write request is made, the I/O device will be added to the list of I/O devices to be contacted. It is given priority over existing read requests, but not over existing write requests.
In this situation, there will be a delay while the I/O device is contacted. Do not mistake this pause for inactivity (for example, do not continually execute a command during this delay).
11 - Change the I/O device cache timeout. If the I/O Server is restarted, the cache timeout will return to its original value. (For scheduled I/O devices, this value can be checked using the Kernel Page Unit command. For all other I/O devices, this value is configured in the Cache Time field at the I/O Devices Properties form.)
12 - The time of day at which to add the I/O device to the list of I/O devices to be contacted. Set the time in Data in seconds from midnight (for example, specify 6 p.m. as 18 * 60 * 60). Use Type 12 to specify a one-timecommunication.
13 - The communication period (the time between successive communication attempts). The value you specify represents different periods, depending on what type of schedule you are using (that is daily, weekly, monthly, or yearly. This is set using Type 15.). You can choose to specify the communication period either in seconds from midnight, day of week (0 to 6, Sunday = 0), month (1 to 12), or year. Enter the value in Data. For example, if your schedule is weekly, and you set Data = 3, you are specifying each Wednesday. If your schedule is monthly, Data = 3 indicates March. For daily communication, set the period in Data in seconds from midnight; for example, set Data to 6 * 60 * 60 to contact the I/O device every 6 hours.
14 - The time at which the I/O Server will first attempt to communicate with the I/O device. Set the time in Data in seconds from midnight, for example, to synchronize at 10a.m., set Data to 10 * 60 * 60.
15 - Type of schedule. Set Data to one of the following:
16 - (For remote I/O devices) Read all tags from the I/O device. Data is unused - set it to 0 (zero).
18 - Set Control Inhibit (Control Mode) for all tags of the I/O device.
Data:
Data for the control operation*:
1:
0:
* For Type 5-8, Data is ignored; enter 0 (zero).
ClusterName:
Specifies the name of the cluster in which the I/O Server resides. This is optional if you have one cluster or are resolving the I/O server via the current cluster context. The argument is enclosed in quotation marks "".
ServerName:
Specifies the name of the the I/O Server. This parameter is only required if you are running more than one I/O server process from the same cluster on the same computer and need to instruct the system which process to redirect to. The argument is enclosed in quotation marks "".
Return Value
0 (zero) if successful, otherwise an error is returned.
Related Functions
IODeviceInfo, IODeviceStats, TagReadEx, TagWrite
Example
IODeviceControl(4, 1, 1); ! Disable I/O device 4
See Also