- Index

< Previous |  | Next >

# WITS Adapter

## Introduction

The TIBCO StreamBase® Adapter for WITS allows for receiving of WITS data from the serial comm port. All the adapters sharing a configuration work together on the same underlying connection; see the section below about shared configurations for more information.

The number of output ports on this adapter are defined by its setup. See the Adapter Properties section for more information.

## Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

### General Tab

Name: Use this required field to specify or change the component's name, which must be unique in the current module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to `true`, this instance of this adapter starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to `false`, the adapter instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), or until you start the component with StreamBase Manager.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

### Operator Properties Tab

Property | Type | Description
--- | --- | ---
Adapter Configuration | Drop-down list | The adapter configuration from the configuration file to use with this adapter.
Record Types | String List | This option allows you to specify which record types this WITS adapter instance will handle for the selected configuration. The configuration must include a dictionary file, and that dictionary file will contain one or more record types to handle. This list allows you to specify one or more of those records that this adapter will handle. Only a single instance of the WITS adapter can handle a specific record type per configuration.

### Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

### Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

## Shared Adapter Configuration

This section describes the shared adapter configuration block found in the `sbd.sbconf` file.

### Shared Adapter Location

Each shared adapter configuration must be under an element called adapter-configuration with a name attribute of WitsAdapters. Following that, an element named section with a name attribute of WitsAdapter is required.

In the example below, long lines wrap for legibility.

The `adapter-configurations.xml` must reside in your project's `src/main/resources` directory.

#### Example Shared Adapter Configuration

    <adapter-configurations>
       <adapter-configuration name="WitsAdapters">
          <section name="WitsAdapter">
             <setting name="id" val="Wits"/> <!-- The ID that will show in the drop
                down list of options on the adapter -->
             <setting name="dictionary" val="WITSDictionary.json"/> <!-- The
                dictionary to use -->
             <setting name="connectOnStartup" val="false"/> <!-- A flag to determine
                if the serial connection should connected at startup.  If false the
                control port of the controller must be used to start -->
             <setting name="packetHeader" val="&amp;&amp;"/> <!-- The packet header
                -->
             <setting name="packetFooter" val="!!"/> <!-- The packet footer -->
             <setting name="lineSeparator" val="&#13;&#10;"/> <!-- The value to send
                as the heart beat, please include all line terminators.  NOTE XML
                 format rules apply, for example ampersand values must be escaped  -->
             <setting name="serialPortName" val="COM1"/> <!-- The name of the serial
                port to use -->
             <setting name="serialPortAppName" val="WITS"/> <!-- The name of the
                serial port to use -->
             <setting name="baudRate" val="9600"/> <!-- The baud rate to set the for
                serial port -->
             <setting name="dataBits" val="8"/> <!-- The data bits to set the for
                serial port -->
             <setting name="stopBits" val="1"/> <!-- The stop bits to set the for
                serial port -->
             <setting name="parity" val="0"/> <!-- The parity to set the for serial
                port -->
             <setting name="stringNullValue" val="null"/> <!-- The value to use if a
                string field is missing from a packet (The value of "null" means to
                set null, blank or empty string means to set the string value empty) -->
             <setting name="intNullValue" val="-999"/> <!-- The value to use if a
                integer field is missing from a packet (blank means actually leave null) -->
             <setting name="doubleNullValue" val="-999.95"/> <!-- The value to use if
                a double field is missing from a packet (blank means actually leave null
                ) -->
             <setting name="heartBeatInterval" val="30"/> <!-- The number of seconds
                between heart beats.  If less than or equal to 0 then no heart beat is
                sent -->
             <setting name="heartBeatValue" val="&amp;&amp;&#13;&#10;0111-9999&#13;&#1
                0;!!&#13;&#10;"/> <!-- The value to send as the heart beat, please
                include all line terminators.  NOTE XML format rules apply, for example
                ampersand values must be escaped  -->
             <setting name="timeField" val="TIME"/> <!-- The field for each record that
                contains the TIME field -->
             <setting name="dateField" val="DATE"/> <!-- The field for each record that
                contains the DATE field -->
             <setting name="wellIdField" val="WELLID"/> <!-- The field for each record
                that contains the WELLID field -->
             <setting name="timeExpression" val="to_seconds(time(now()))"/> <!-- If none
                empty this StreamBase expression will be used to replace the value of the
                TIME field if the TIME field is found and is null or contains the
                doubleNullValue  -->
             <setting name="dateExpression" val="to_seconds(date(now()))"/> <!-- If none
                empty this StreamBase expression will be used to replace the value of
                the DATE field if the DATE field is found and is null or contains the
                doubleNullValue  -->
             <setting name="wellIdExpression" val="'Well1'"/> <!-- If none empty this
                StreamBase expression will be used to replace the value of the WELLID
                field if the WELLID field is found and is null or contains the stringNull
                Value -->
             <setting name="timestampFieldName" val="RecordTime"/> <!-- If none empty
                this field name will be added to each record and will use the timestampExpression
                to combine the two fields into a single StreamBase timestamp  -->
             <setting name="timestampExpression" val="from_unixtime(DATE) + from_unixtime
                (TIME)"/> <!-- The StreamBase expression to use when combining the DATE and
                TIME field together into the timestampFieldName -->
            </section>
        </adapter-configuration>
    </adapter-configurations>

### Shared Adapter Configuration Options

If a value is not present, the default is used. Those values listed without a default are required.

Property | Type | Default | Description
--- | --- | --- | ---
id | string |  | This is the name that will link the adapters together and is displayed in the drop-down list on each adapters property configuration.
dictionary | string |  | This is the filename of the WITS dictionary file that will be for WITS Records.
connectOnStartup | boolean | true | A flag to determine whether the serial connection should connected at startup. If false, the control port of the controller must be used to start.
packetHeader | string | && | The value to use when determining the start of a packet of data. This value must be XML encoded in the configuration file.
packetFooter | string | !! | The value to use when determining the end of a packet of data. This value must be XML encoded in the configuration file.
lineSeparator | string | \r\n | The value to use when determining the line separator. This value must be XML encoded in the configuration file.
serialPortName | string | COM1 | The name of the serial port to use.
serialPortAppName | string | WITS | The name to assign to the serial port usage.
baudRate | int | 9600 | The baud rate to set the for serial port.
dataBits | int | 8 | The data bits to set the for serial port.
stopBits | int | 1 | The stop bits to set the for serial port.
parity | int | 0 | The parity to set the for serial port.
stringNullValue | string |  | The value to use if a string field is missing from a packet (The value of `null` means to set null; blank or empty string means to set the string value empty).
intNullValue | int |  | The value to use if a integer field is missing from a packet (blank means actually leave null).
doubleNullValue | double |  | The value to use if a double field is missing from a packet (blank means actually leave null).
heartBeatInterval | int | 30 | The number of seconds between heart beats. If less than or equal to 0, then no heart beat is sent.
heartBeatValue | int | &&\r\n0111-9999\r\n!!\r\n | The value to send as the heart beat. Please include all line terminators. NOTE XML format rules apply. For example, ampersand values must be escaped.
timeField | string | TIME | The field for each record that contains the TIME field. This matches the actual StreamBase schema field name.
dateField | string | DATE | The field for each record that contains the DATE field. This matches the actual StreamBase schema field name.
wellIdField | string | WELLID | The field for each record that contains the WELLID field. This matches the actual StreamBase schema field name.
timeExpression | string |  | If the value is none/empty, this StreamBase expression is used to replace the value of the TIME field if the TIME field is found and is null or contains the doubleNullValue.
dateExpression | string |  | If the value is none/empty, this StreamBase expression is used to replace the value of the DATE field if the DATE field is found and is null or contains the doubleNullValue.
wellIdExpression | string |  | If the value is none/empty, this StreamBase expression is used to replace the value of the WELLID field if the WELLID field is found and is null or contains the stringNullValue.
timestampFieldName | string |  | If the value is none/empty, this field name will be added to each record and will use the timestampExpression to combine the two fields into a single StreamBase timestamp.
timestampFieldName | string |  | The StreamBase expression to use when combining the DATE and TIME field together into the timestampFieldName.

## WITS Dictionary

This section describes WITS dictionaries and how they are used with the adapters to handle WITS record types and items.

Dictionary files are in JSON format and are cumulative, in that you can include more dictionary files inside of other dictionary files to keep them organized and less complex.

### WITS Standard Dictionary

The WITS sample that comes with StreamBase includes a `WITSDictionary.json` file that includes the standard WITS record types and items. This base dictionary includes all the required information for the WITS adapters to perform based on the WITS specification and shows the standard WITS record and item types to get the adapters up and running. If your WITS connection has non-standard record types or items then this dictionary file should be modified to include those extensions.

### Dictionary Schema

The following shows the schema to which each dictionary must conform:

    {
       "$schema":"http://json-schema.org/draft-04/schema#",
       "type":"object",
       "properties":{
          "IncludeDictionary":{
            "type":"array",
             "items":{
                "type":"object",
                "properties":{
                   "File":{
                      "type":"string"
                   }
                },
                "required":[
                   "File"
                ]
             }
          },
          "Records":{
             "type":"array",
             "items":{
                "type":"object",
                "properties":{
                   "Rec":{
                      "type":"integer"
                   },
                   "Name":{
                      "type":"string"
                   },
                   "Description":{
                      "type":"string"
                   },
                   "Items":{
                      "type":"array",
                      "items":{
                         "type":"object",
                         "properties":{
                            "Item":{
                               "type":"integer"
                            },
                            "Description":{
                               "type":"string"
                            },
                            "LongMnemonic":{
                               "type":"string"
                            },
                            "ShortMnemonic":{
                               "type":"string"
                            },
                            "Type":{
                               "type":"string"
                            },
                            "Length":{
                               "type":"integer"
                            },
                            "MetricUnits":{
                               "type":"string"
                            },
                            "FPSUnits":{
                               "type":"string"
                            },
                         },
                         "required":[
                            "Item",
                            "LongMnemonic",
                            "ShortMnemonic",
                            "Type"
                         ]
                      }
                   }
                },
                "required":[
                   "Rec",
                   "Items"
                ]
             }
          }
       },
       "required":[
          "Records"
       ]
    }

### Dictionary Layout

The following are the major categories of the dictionary file and an overview of their usage.

#### includeDictionary

The includeDictionary section is an array of files that allows one dictionary file to include another dictionary file. This enables you to organize your dictionaries and combine them into a single dictionary.

- file — The relative path to the linked dictionary file to include.

#### Records

The records section allows you to add any record types that are not currently present in the WITS dictionary. Each record type (based on Rec integer) can only appear once in the entire dictionary file.

- Rec — An integer value representing the record type. This value is left 0 padded and used to match the packets record type.

  Name — (Optional) The name associated with this record type.

  Description — (Optional) The description of this record type.

  Items — An array of items associated with this record type:

  - Item — The integer item value representing the item. This value is left 0 padded and used to match the packets item type.

  - Description — (Optional) The description of this item.

  - LongMnemonic — The long mnemonic name of this item. This value is used as the StreamBase field name in the output schema produced. Using spaces and special characters is not recommended with this value.

  - ShortMnemonic — The short mnemonic name of this item.

  - Type — The type of this item. Valid values are:

    - A — Alphanumeric, which is converted to a StreamBase String.

    - L — 32 bit 2's complement signed integer, which is converted to a StreamBase Int.

    - S — 16 bit 2's complement signed integer, which is converted to a StreamBase Int.

    - F — 32 bit IEEE single precision floating point, which is converted to a StreamBase Double.

  - Length — (Optional) The integer size of the items type. This value is currently not used, but will display in the output schema description.

  - MetricUnits — (Optional) The metric unit of the item. This value is currently not used, but will display in the output schema description.

  - FPSUnits — (Optional) The FPS unit type of the item. This value is currently not used, but will display in the output schema description.