I/O hooks are the things that link [JSup tag|tags] with remote device items.
An I/O hook can be added to a [JSup tag|tag] by clicking ''Add'' button of the ''I/O hook'' table in the [JSup Tag dialog|Tag dialog].
The I/O hook dialog lets the user to:
* associate the I/O hook with a [JSup Channels|'''channel'''];
* define the '''item''' the I/O hook will be linked to within the remote device;
* specify some [JSup Drivers|driver] dependent information (if any);
* make the I/O hook to be read or write only.
* specify some [JSup Tag type|tag type] dependant configuration.
((([img:///img/JSup/IOHook.png])))
== I/O hook channel ==
An I/O hook belongs to a [JSup Channels|channel] that control when and how data are read/written from/to the remote device.
An I/O hook inherits some properties from it:
* the channel '''item prefix''' (if any) that will be prefixed to the I/O hook item to complete it.
* the remote device and the way it is read/written (timed/triggered, written on tag change).
* the [JSup Drivers|driver] used.
== Item ==
The ''item'' defines the '''address''' within the remote device to be read/written by the I/O hook.
The [JSup Channels|channel] can provide a prefix the all the items of the I/O hook that belong to it.
The format of this item is [JSup Drivers|driver] dependent.
=== Tag array element items ===
Items for I/O hooks of a [JSup Tag arrays|tag array] elements are calculated as a [JSup Math code|math expression] where indexes of the element are provided in i, j and k variables (for a single dimensional array only i, for two dimension array i and j only).
For example: "%mw"+(1000+i)
=== Programmatically calculated items ===
See also:
* [JavaCode function provided IOHooks|JavaCode function provided I/O Hooks]
'''Programmatically calculated''' items can be provided to I/O hooks, expecially useful for [JSup Structured tags|structured tag members] o [JSup Tag arrays|array] elements (see below for array special case).
If the item starts with the prefix "::=" the rest of the item is interpreted with the following special place holders that let Java method or JavaCodeFunction to be called to provide the item:
%JavaCodeFunctionForTag ''javaCodeFunctionName''%
Will be replaced with the value of the given [JavaCode functions], that must return a String value and must have a single [TagRef] parameter (a reference to the tag instance, or the array element). For example:
::=%JavaCodeFunctionForTag ifEntryOID%
Example of ifEntryOID( TagRef tag ) [JavaCode functions|JavaCode function]
TagRef structTag = tag.getStructTag();
String ifEntryChild = ((TagStructMemberRef)tag).getMemberDefinition().getProperty( "ifEntryChild" );
if( ifEntryChild == null ) ifEntryChild = "999";
return "1.3.6.1.2.1.2.2.1."
+ifEntryChild+"."
+structTag.getProperty( "ifIndex", "999" );
%JavaCodeFunctionForTagAndChannel''javaCodeFunctionName''%
Will be replaced with the value of the given [JavaCode functions], that must return a String value and must have two parameters:
1. [TagRef] a reference to the tag instance, or the array element.
2. [ChannelInfo] information about the [JSup Channels|channel] the item will be provided to.
%callForTag ''full.package.class.methodName''%
Will be replaced with the value of the given static Java functions, that must return a String value and must have a single [TagRef] parameter, where a reference to the tag instance (or array element). This can be useful to invoke library class methods defined in ''JavaCode imports'' (see [JSup Application properties])
To provide programmatically calculated items to an [JSup Tag arrays|array] element provide, as item [JSup Math code|math expression], a single double quoted string constant that starts with "::=", for example:
"::=%JavaCodeFunctionForTagAndChannel addressForDeviceTime%"
== Driver dependant info ==
Some driver require or allow to enter some extra configuration data.
Press the button (if enabled) to enter such data.
== Read/write only ==
It's a good practice to specify if an I/O hook is to be only read or written.
A '''read only''' I/O hook that belongs to a [JSup Channels|channel] that is both read and written will never be written to the remote device. It will be simply skipped when the [JSup Channels|channel] content is written to the remote device.
A '''write only''' I/O hook will be never read from the remote device even if the [JSup Channels|channel] is configured for read operations.
It's a '''good practice''' to specify if an I/O hook is to be only read or written, even if the [JSup Channels|channel] is configured only for read or write because:
* it will be useful to understand the way the [JSup application|application] communicates when looking the [JSup IOHook list|I/O hook list];
* it will save the [JSup application|application] from possible future errors, if the [JSup Channels|channel] configuration changes.
== Type dependent config ==
==== Boolean ====
A [JSup boolean tags|'''boolean''' tag] I/O hook can be '''reversed''' so when tag value of true corresponds to a 0 in the remote device, and a false tag value corresponds to a 1 in the remote device.
==== Numeric ====
A [JSup numeric tags|numeric tag] I/O hook can define a '''min/max raw''' range to '''scale''' the [JSup tag|tag] value within its EU min/max range. The EU min/max range can be defined using the [JSup Using tag properties|tag properties] or defining it within the [JSup Tag classes|tag class]. When no ''min'' (or ''max'') is given from tag [JSup Using tag properties|properties] the Java corresponding type minimum (or maximum) value is used (See [http://java.sun.com/javase/6/docs/api/java/lang/Byte.html#MIN_VALUE|Byte], [http://java.sun.com/javase/6/docs/api/java/lang/Short.html#MIN_VALUE|Short], [http://java.sun.com/javase/6/docs/api/java/lang/Integer.html#MIN_VALUE|Integer], [http://java.sun.com/javase/6/docs/api/java/lang/Long.html#MIN_VALUE|Long], [http://java.sun.com/javase/6/docs/api/java/lang/Float.html#MAX_VALUE|Float] and [http://java.sun.com/javase/6/docs/api/java/lang/Double.html#MAX_VALUE|Double]).
Please note that is always better to define the raw value min-max range withing [JSup Tag classes|tag class]. Use the I/O hook specific raw range only as exception (for example for a tag with multiple I/O hooks that need different scaling).
With a '''linear conversion''' (no ''square root'') for conversion formulas are
++v++**r** = (++v++**e** - ++min++**e**) * ((++max++**r** - ++min++**r**) / (++max++**e** - ++min++**e**)) + ++min++**r**
++v++**e** = (++v++**r** - ++min++**r**) * ((++max++**e** - ++min++**e**) / (++max++**r** - ++min++**r**)) + ++min++**e**
Where the subscript ''r'' means ''raw'' (remote device side), and ''e'' means ''engineering'' (JSup side)
When the '''square root''' flag the following formula is used to convert the raw numeric value (read from the remote device) into the tag value:
((([img:///img/JSup/IOHook_raw2eu.png])))
Where the subscript ''r'' means ''raw'' (remote device side), and ''e'' means ''engineering'' (JSup side).
And the formula to convert the tag value into the raw value to be written to the remote device is:
((([img:///img/JSup/IOHook_eu2raw.png])))
The '''raw value sign can inverted''' specifying a ''min raw'' greater than the ''max raw''. In this case, to perform calculations, the ''min/max raw'' values are swaped in the natural order, and the raw value sign is inverted.
== Multiple I/O ==
A [JSup tag|tag] can have '''more than one''' I/O hook. In this case the I/O hooks of a [JSup tag|tag] should belong to different [JSup Channels|channels] that should be triggered read/written: the trigger should be handled by some [JavaCode].
== I/O hook list ==
The complete '''list of I/O hooks''' defined in the [JSup application|application] can be viewed with the [JSup IOHook list|I/O hook list] window.