TAG I/O HOOKS (BOZZA)
------------------------------------------------------------------------------

Indice Argomenti

	    1. I/O hook channel
	    2. Item
	      2.1. Tag array element items
	      2.2. Programmatically calculated items
	    3. Driver dependant info
	    4. Read/write only
	    5. Type dependent config
	        5.1. Boolean
	        5.2. Numeric
	    6. Multiple I/O
	    7. I/O hook list


I/O hooks are the things that link [tags] with
remote device items. An I/O hook can be added to a
[tag] by clicking Add button of the I/O hook table
in the [Tag dialog]. The I/O hook dialog lets the
user to: * associate the I/O hook with a [channel];
* define the item the I/O hook will be linked to
within the remote device; * specify some [driver]
dependent information (if any); * make the I/O hook
to be read or write only. * specify some [tag type]
dependant configuration. ((())) 1. I/O hook channel
An I/O hook belongs to a [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 [driver] used. 2. Item The item
defines the address within the remote device to be
read/written by the I/O hook. The [channel] can
provide a prefix the all the items of the I/O hook
that belong to it. The format of this item is
[driver] dependent. 2.1. Tag array element items
Items for I/O hooks of a [tag array] elements are
calculated as a [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) 2.2. Programmatically calculated
items See also: * [JavaCode function provided I/O
Hooks] Programmatically calculated items can be
provided to I/O hooks, expecially useful for
[structured tag members] o [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
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" );
%JavaCodeFunctionForTagAndChanneljavaCodeFunctionName%
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. [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 [array] element provide, as item [math
expression], a single double quoted string constant
that starts with "::=", for example:
"::=%JavaCodeFunctionForTagAndChannel
addressForDeviceTime%" 3. Driver dependant info
Some driver require or allow to enter some extra
configuration data. Press the button (if enabled)
to enter such data. 4. 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 [channel] that is both read and written will
never be written to the remote device. It will be
simply skipped when the [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 [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 [channel]
is configured only for read or write because: * it
will be useful to understand the way the
[application] communicates when looking the [I/O
hook list]; * it will save the [application] from
possible future errors, if the [channel]
configuration changes. 5. Type dependent config
5.1. Boolean A [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. 5.2.
Numeric A [numeric tag] I/O hook can define a
min/max raw range to scale the [tag] value within
its EU min/max range. The EU min/max range can be
defined using the [tag properties] or defining it
within the [tag class]. When no min (or max) is
given from tag [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|Integ
er],
[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 [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     vr = (ve
- mine) * ((maxr - minr) / (maxe - mine)) + minr
    ve = (vr - minr) * ((maxe - mine) / (maxr - minr))
+ mine 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: ((())) 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: ((())) 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. 6. Multiple I/O A [tag] can have more
than one I/O hook. In this case the I/O hooks of a
[tag] should belong to different [channels] that
should be triggered read/written: the trigger
should be handled by some [JavaCode]. 7. I/O hook
list The complete list of I/O hooks defined in the
[application] can be viewed with the [I/O hook
list] window.