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.