de.stz.bt.fnd
Class FND_Datagram

java.lang.Object
  extended byde.stz.bt.fnd.FND_Datagram

public class FND_Datagram
extends java.lang.Object

Object Oriented representation of a FND-Datagram.

Version:
$Id: FND_Datagram.html,v 1.3 2004/11/08 08:10:45 jseitter Exp $
Author:
Lars Heineken, J. Seitter

Field Summary
(package private)  FND_DataPointContext context
           
static byte D_R_ACK
           
static byte D_R_CMD
           
static byte D_R_RSP
           
static byte D_R_USM
           
(package private)  byte[] data
           
(package private)  int dataLen
           
static byte DP_TAB_0
           
static byte DP_TAB_1
           
static byte DP_TAB_1_2
           
static byte DP_TAB_2
           
static int FND10
           
static int FND20
           
static byte IMPLICIT_FCT
           
static byte MODIFY_FCT
           
static byte MPR_HIGH
           
static byte MPR_IMPORTANT
           
static byte MPR_NORMAL
           
static byte MPR_URGENT
           
static byte READ_FCT
           
static byte SEG_FIRST
           
static byte SEG_LAST
           
static byte SEG_NEXT
           
static byte SEG_NO
           
(package private)  java.net.InetAddress sender
           
static byte TAG_ERROR
           
static byte TAG_NORMAL
           
static byte TAG_REJECT
           
 
Constructor Summary
FND_Datagram()
           
 
Method Summary
 byte[] getApplicationControl()
          Returns applicationControl.
 byte[] getCentralControl()
          Returns CentralControlID and centralControlSubID.
 FND_DataPointContext getContext()
           
 byte[] getDatagramHeader()
           
 byte getDatagramSegmentType()
           
 byte getDatagramTag()
           
 byte getDatagramType()
           
 byte[] getDataPart()
          Returns DateTime.
 byte[] getDataPointID()
          Returns dataPointID.
 byte getDatapointType()
           
 byte[] getDateTime()
          Returns DateTime.
 byte[] getFndDatagramByteArray()
          Returns raw byte array of the FND_Datagram.
 byte[] getInfoCode()
          Returns InfoCode.
 byte[] getInfoEvent()
          Returns InfoEvent.
 boolean[] getInfoEventBits()
          returns the InfoEvent field as an array of boolean values
 byte getInvokeID()
          Returns Datagrams invoke ID.
 byte[] getIslandControl()
          Returns islandControlID and islandControlSubID.
 byte getLen()
           
 byte[] getMask()
          Returns Mask.
 byte[] getOperationsCode()
          Returns operationsCode.
 int getProtocolVersion()
           
 byte getSegmentNr()
          Returns Datagrams segment number.
 java.net.InetAddress getSender()
           
 byte[] getTransportControl()
          Used to get the four values of the transport-control byte.
 void setApplicationControl(byte prd, byte rpr, byte emq)
          These settings are used to implement acces rights and access priorities.
 void setCentralControl(byte centralControlID, byte centralControlSubID)
          This information is used to indentify the central control associated with the datagram
 void setContext(FND_DataPointContext context)
           
 void setDatagramSegmentType(byte dgramsegtype)
           
 void setDatagramTag(byte dgramattr)
           
 void setDatagramType(byte dgramtype)
           
 void setDataPart(byte[] data)
          Put raw byte data into the data-part of the FND_Datagram.
 void setDataPointID(byte[] dataPointID)
          The DataPoint ID is a unique ID assigned to every datapoint.
 void setDatapointType(byte dpointtype)
           
 void setDateTime(byte year, byte month, byte day, byte hour, byte minute, byte second)
          Date and time the datagram was created.
 void setInfoCode(byte exc_1, byte exc_2)
          If the parameter "tag" from the transport control byte is 1, the datagram has been rejected.
 void setInfoEvent(byte info, byte event)
          These Settings are used to specify additional information about the data-point and wich events occured.
 void setInvokeID(byte invokeID)
          The invode ID is used as an internal flow control and securing mechanism.
 void setIslandControl(byte islandControlID, byte islandControlSubID)
          This information is used to indentify the island control associated with the datagram
 void setLen(byte len)
          Set Length of Datagram.
 void setMask(byte val, byte apr, byte mis, byte msk)
          These settings are used to specify permissions and the message surpression of a datapoint.
 void setOperationsCode(byte fct_id, byte tab_id, byte dp_type, byte dp_subtype)
          Sets all parameters of the operations code.
 void setSegmentNr(byte segNr)
          Used to set the segment number.
 void setSender(java.net.InetAddress address)
           
 void setTransportControl(byte d_r, byte tag, byte mpr, byte seg)
          Creates the transport control byte by combining all the function parameters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FND10

public static final int FND10
See Also:
Constant Field Values

FND20

public static final int FND20
See Also:
Constant Field Values

TAG_NORMAL

public static final byte TAG_NORMAL
See Also:
Constant Field Values

TAG_REJECT

public static final byte TAG_REJECT
See Also:
Constant Field Values

TAG_ERROR

public static final byte TAG_ERROR
See Also:
Constant Field Values

D_R_CMD

public static final byte D_R_CMD
See Also:
Constant Field Values

D_R_RSP

public static final byte D_R_RSP
See Also:
Constant Field Values

D_R_USM

public static final byte D_R_USM
See Also:
Constant Field Values

D_R_ACK

public static final byte D_R_ACK
See Also:
Constant Field Values

MPR_NORMAL

public static final byte MPR_NORMAL
See Also:
Constant Field Values

MPR_IMPORTANT

public static final byte MPR_IMPORTANT
See Also:
Constant Field Values

MPR_HIGH

public static final byte MPR_HIGH
See Also:
Constant Field Values

MPR_URGENT

public static final byte MPR_URGENT
See Also:
Constant Field Values

SEG_NO

public static final byte SEG_NO
See Also:
Constant Field Values

SEG_FIRST

public static final byte SEG_FIRST
See Also:
Constant Field Values

SEG_NEXT

public static final byte SEG_NEXT
See Also:
Constant Field Values

SEG_LAST

public static final byte SEG_LAST
See Also:
Constant Field Values

IMPLICIT_FCT

public static final byte IMPLICIT_FCT
See Also:
Constant Field Values

READ_FCT

public static final byte READ_FCT
See Also:
Constant Field Values

MODIFY_FCT

public static final byte MODIFY_FCT
See Also:
Constant Field Values

DP_TAB_0

public static final byte DP_TAB_0
See Also:
Constant Field Values

DP_TAB_1

public static final byte DP_TAB_1
See Also:
Constant Field Values

DP_TAB_2

public static final byte DP_TAB_2
See Also:
Constant Field Values

DP_TAB_1_2

public static final byte DP_TAB_1_2
See Also:
Constant Field Values

context

FND_DataPointContext context

sender

java.net.InetAddress sender

data

byte[] data

dataLen

int dataLen
Constructor Detail

FND_Datagram

public FND_Datagram()
Method Detail

setLen

public void setLen(byte len)
Set Length of Datagram. Has to be the complete length of FND_Datagram (in bytes) minus 2.

Parameters:
len - Length of FND_Datagram.

getLen

public byte getLen()
Returns:
lenght of FND_Datagram, in bytes, minus 2 .
See Also:
setLen(byte)

setTransportControl

public void setTransportControl(byte d_r,
                                byte tag,
                                byte mpr,
                                byte seg)
                         throws java.lang.IndexOutOfBoundsException
Creates the transport control byte by combining all the function parameters. The maximum value for every parameter is 3.

Parameters:
d_r - Direction and response bits.

tag - Type of Telegram.
0 = NORMAL-Datagram
1 = REJECT-Datagram
2 = ERROR-Datagram
3 = reserved

mpr - Datagram priority.
The higher the value the higher the priority.

seg - Segmentation status.
0 = no segementation
3 = segmentation: first element
2 = segmentation: following element
1 = segemantation: last element
Throws:
java.lang.IndexOutOfBoundsException - In case any parameter exceeds its maximum value this exception is thrown

getTransportControl

public byte[] getTransportControl()
Used to get the four values of the transport-control byte.

Returns:
transportControl[]
transportControl[0] = d_r
transportControl[1] = tag
transportControl[2] = mpr
transportControl[3] = seg
See Also:
setTransportControl(byte d_r, byte tag, byte mpr, byte seg)

setSegmentNr

public void setSegmentNr(byte segNr)
Used to set the segment number. If there is no segmentation, the value is zero. In case there is a segmentation this number needs to be a 0-based, continously increasing value, used in all fragments of the FND datagram.

Parameters:
segNr - Segment number.

getSegmentNr

public byte getSegmentNr()
Returns Datagrams segment number.

Returns:
Datagram's segment number.
See Also:
setSegmentNr(byte segNr)

setInvokeID

public void setInvokeID(byte invokeID)
The invode ID is used as an internal flow control and securing mechanism. It limits the number of currently pending request or processings by issueing a ticket (the invokeID) out of a limited pool. After completion of the request or process, the ticket is returned to the pool and can be issued again. If all avaialable tickets are in use no more request are accepted.

Parameters:
invokeID -

getInvokeID

public byte getInvokeID()
Returns Datagrams invoke ID.

Returns:
Datagram's invoke ID.
See Also:
setInvokeID(byte invokeID)

setCentralControl

public void setCentralControl(byte centralControlID,
                              byte centralControlSubID)
This information is used to indentify the central control associated with the datagram

Parameters:
centralControlID -
Used to indetify the central control.
centralControlSubID -
Optional ID (default 0), connects the datagram with a corresponding internal Process.

getCentralControl

public byte[] getCentralControl()
Returns CentralControlID and centralControlSubID.

Returns:
centralControl[]
centralControl[0] = centralControlID
centralControl[1] = centralControlSubID
See Also:
setCentralControl(byte centralControlID, byte centralControlSubID)

setIslandControl

public void setIslandControl(byte islandControlID,
                             byte islandControlSubID)
This information is used to indentify the island control associated with the datagram

Parameters:
islandControlID -
Used to indetify the island control.
islandControlSubID -
Optional ID (default 0), connects the datagram with a corresponding Process.

getIslandControl

public byte[] getIslandControl()
Returns islandControlID and islandControlSubID.

Returns:
islandControlID[]
islandControlID[0] = islandControlID
islandControlID[1] = islandControlSubID
See Also:
setIslandControl(byte islandControlID, byte islandControlSubID)

setDataPointID

public void setDataPointID(byte[] dataPointID)
                    throws java.lang.IndexOutOfBoundsException
The DataPoint ID is a unique ID assigned to every datapoint.

Parameters:
dataPointID -
The DataPoint ID to be assigned to the datagram
Throws:
java.lang.IndexOutOfBoundsException -
If the datapoint ID is too large (more than 16 charcters) this exception is thrown.

getDataPointID

public byte[] getDataPointID()
Returns dataPointID.

Returns:
dataPoint[]
dataPointID[0] to dataPointID[15] = dataPointID.
See Also:
(byte[] dataPointID)

setOperationsCode

public void setOperationsCode(byte fct_id,
                              byte tab_id,
                              byte dp_type,
                              byte dp_subtype)
                       throws java.lang.IndexOutOfBoundsException
Sets all parameters of the operations code. It is used to determine wich operation is requested and wich DataPoint tables is to be modified.

Parameters:
fct_id -
One of three elementary funcions:
0 = Implizit (only valid for transferpoints, meaning has to specified)
1 = Read (Reading of DataPoint tables)
2 = Modify (Modifying of DataPoint tables)
tab_id -
One of four values, that determine the DataPoint table to be affected.
0 = DataPoint table 0
1 = DataPoint table 1
2 = DataPoint table 2
3 = DataPoint table 1 and 2
dp_type -
The datapoint type.
0 = Transferpoint
1 = Messagepoint
2 = Switchpoint
3 = Measurepoint
4 = Settingpoint
5 = Countingpoint
6 = Collectionpoint
dp_subtype -
The datapoint subtype.
Transferpoints are the only Datapoints using this parameter.
The possible values, depending on the DataPoint ID are specified as followed:
DataPoint type Datpoint subtype Comment
0 0 Adresspoint for transparent
data transfer
1 Adresspoint for error messages
2 Authentification point
Throws:
java.lang.IndexOutOfBoundsException - In Case any of the supplied parameters exceeds its maximum value, this exception is thrown.

getOperationsCode

public byte[] getOperationsCode()
Returns operationsCode.

Returns:
operationCode
operationCode[0] = fct_id
operationCode[1] = tab_id
operationCode[2] = dp_type
operationCode[3] = dp_subtype
See Also:
(byte fct_id, byte tab_id, byte dp_type, byte dp_subtype)

setApplicationControl

public void setApplicationControl(byte prd,
                                  byte rpr,
                                  byte emq)
                           throws java.lang.IndexOutOfBoundsException
These settings are used to implement acces rights and access priorities.
If creating a datagram that does not alter DP_#1 or DP_#2, prd and rpr have to be 0. Same goes for USM-datgrams. Respond- and ACK-datagrams need to copy the values of prd and rpr ,without modifications, from the datagram that belongs to that Respond- or ACK-datagram.

Parameters:
prd -
Identification. The higher the value, the more rights are assigned to the datagram. 0 = regular user
1 = privileged user
2 = super user
3 = administrator
rpr -
Access control. Sets the threshold that determines wich user is allowed to use the datapoint used by this datagram.
0 = regular user, priviledged user, super user and adiministrator has access rights to the datapoint
1 = priviledged user, super user and administrator has acces rights to the datapoint.
2 = super user and administrator has access rights to the datapoint.
3 = only administrator has access rights to the datapoint.
emq -
Event Modification Qualifier
Has a different meaning, depending on wether the datagram is used as command or message.

Command Mode: (Used as modification control)
To be abled to modify only a small part of the whole DP-table, the four bits of this parameter can be set individually, to specify that only those DP-table entries are beeing modified who's bit is set to 1.
The first bit (if set to 1) enables modification of the first DP-table entry
The second bit (if set to 1) enables modification of the second DP-table entry
...
The fourth bit (if set to 1) enables modification of the fourth DP-table entry.

Message Mode: (Used to indicate the reason for a spontanious message)
Seems like nonsense at first but in case the one reason for a sponatnious message is still there (a sensor malfunction for example) and a second reason for a spontanious message appears later, causing a second sponatnious message (a value has changed, for example), you need to specify wich reason caused the datagram. The second datagram would only set the emq-bit connected with the very reason of the spontanious message (the emq-bit connected to the event-bit for value changes, for example).
The first bit (if set to 1) indicates the first bit of event (last four bits of the byte info_event) was the reason for the spontanious message.
The second bit (if set to 1) indicates the second bit of event (last four bits of the byte info_event) was the reason for the spontanious message.
...
The second bit (if set to 1) indicates the first bit of event (last four bits of the byte info_event) was the reason for the spontanious message.
When creating an ACK-datagram the value must be copied from the REQ-datagram without any modifications.
Throws:
java.lang.IndexOutOfBoundsException - In Case any of the supplied parameters exceeds its maximum value, this exception is thrown.

getApplicationControl

public byte[] getApplicationControl()
Returns applicationControl.

Returns:
applicationControl[]
applicationControl[0] = prd
applicationControl[1] = rpr
applicationControl[2] = emq
See Also:
(byte id, byte rights, byte mec)

setMask

public void setMask(byte val,
                    byte apr,
                    byte mis,
                    byte msk)
             throws java.lang.IndexOutOfBoundsException
These settings are used to specify permissions and the message surpression of a datapoint.

mis and msk:
Island specific message surpression affects central-control message surpression. If messages are surpressed island-specific, they are surpressed central-control-specific, too.

val and apr:
Permissions are needed to make sure that information altering datagrams don't conflict with each other.
Command datagrams and datagrams for transferpoints have both val and apr set to 0.

Parameters:
val -
val Meaning
0 0 Central control exclusive:
Unrestricted modification by central control. Island control isn't allowed to modify anything at all.
0 1 Central control preference:
Highest priority (3) can only be set and changed by central control.
1 0 Island control preference:
Highest priority (3) can only be set and changed by island control.
0 0 Island control exclusive:
Unrestricted modification by Island control. Central control is allowed to change DP_#0 only.
apr - Access priority.
It's value represents the current access priority held by the datapoint at the moment. It can be used to decide wether sending a datagram to change options of the datapoint makes sense or would be blocked anyway.
mis -
Specifies the type of messages to be surpressed (island-specific).
0 = Nothing is surpressed.
1 = Operational Messages are surpressed.
2 = Operational and BTA-Error messages are surpressed.
3 = All Messages are surpressed.
msk -
Specifies the type of messages to be surpressed (central-control-specific).
0 = Nothing is surpressed.
1 = Operational Messages are surpressed.
2 = Operational and BTA-Error messages are surpressed.
3 = All Messages are surpressed.
Throws:
java.lang.IndexOutOfBoundsException - In Case any of the supplied parameters exceeds its maximum value, this exception is thrown.

getMask

public byte[] getMask()
Returns Mask.

Returns:
mask[]
mask[0] = val
mask[1] = apr
mask[2] = mis
mask[3] = msk
See Also:
(byte val, byte apr, byte mis, byte msk)

setInfoEvent

public void setInfoEvent(byte info,
                         byte event)
                  throws java.lang.IndexOutOfBoundsException
These Settings are used to specify additional information about the data-point and wich events occured. The possible parameter values depend on the type of the data point.

Parameters:
info - Specifies additional information about the data-point.
No cheking is done wether the supplied values are valid for the very datagram, as it depends on the datapoint-type.
event - Specifies wich events have occured.
The possible values depend on the datapoint-type.
Throws:
java.lang.IndexOutOfBoundsException - In case a parameter exceeds it's maximum value this exception is thrown.

getInfoEvent

public byte[] getInfoEvent()
Returns InfoEvent.

Returns:
infoEvent[]
infoEvent[0] = info
infoEvent[1] = event
See Also:
(byte info, byte event)

getInfoEventBits

public boolean[] getInfoEventBits()
returns the InfoEvent field as an array of boolean values

Returns:
array of boolean representing bits 0..7 of InfoEvent byte

setInfoCode

public void setInfoCode(byte exc_1,
                        byte exc_2)
If the parameter "tag" from the transport control byte is 1, the datagram has been rejected. The info-code is used to specify the reason for the reject.
If the parameter "tag" from the transport control byte is 2, the datagram contains a syntactical error. The info-code parameter exc_1 points to the byte inside the data-part where the error occured. exc_2 contains additional information about the error.
When creating message or command datagrams both values have to be 0. Possible values for the two parameters exc_1 and exc_2:
exc_1 exc_2 Explanation
1 0 Recieved an unexpected datagram segment.
2 0 Recieved an unexpected datagram start segment, or an unsegmented datagram while trying to reassemble a fragmented datagram.
3 seg_exp Recieved a datagram segment with an unexpected segment number. "seg_exp" is the expected segment number.
4 0 "invoke_id" busy. Some other taks is still beeing processed.
5 0 DataPoint not accessable.
5 1 DataPoint served locally.
5 2 DataPoint locked.
6 0 DataPoint busy. Some other task is still beeing processed.
7 0 Central control not acessable.
8 0 Island control not accessable
9 apr No suficcent access rights. (prd < apr)
10 0 Authentification mechanism currently running.

Parameters:
exc_1 -
See above.
exc_2 -
See above.

getInfoCode

public byte[] getInfoCode()
Returns InfoCode.

Returns:
infoCode[]
infoCode[0] = exc_1
infoCode[1] = exc_2
See Also:
(byte exc_1, byte exc_2)

setDateTime

public void setDateTime(byte year,
                        byte month,
                        byte day,
                        byte hour,
                        byte minute,
                        byte second)
                 throws java.lang.IndexOutOfBoundsException
Date and time the datagram was created.

Parameters:
year -
Allowed values: 0-99.
month -
Allowed values: 1-12.
day -
Allowed values: 1-31.
hour -
Allowed values: 0-23.
minute -
Allowed values: 0-59.
second -
Allowed values: 0-59.
Throws:
java.lang.IndexOutOfBoundsException - In case any of the parameters exceeds its maximum value.

getDateTime

public byte[] getDateTime()
Returns DateTime.

Returns:
dateTime[]
dateTime[0] = year
dateTime[1] = month
dateTime[2] = day
dateTime[3] = hour
dateTime[4] = minute
dateTime[5] = second
See Also:
(byte year, byte month, byte day, byte hour, byte minute, byte second)

setDataPart

public void setDataPart(byte[] data)
                 throws java.lang.IndexOutOfBoundsException
Put raw byte data into the data-part of the FND_Datagram.

Parameters:
data -
The raw data. Maximum length is 128-38 = 90 byte.
Throws:
java.lang.IndexOutOfBoundsException -
In case the array supplied is too large.

getDataPart

public byte[] getDataPart()
Returns DateTime.

Returns:
dataPart[]
dataPart[0] to dataPart[89] (maximum)
See Also:
(byte[] data)

getFndDatagramByteArray

public byte[] getFndDatagramByteArray()
Returns raw byte array of the FND_Datagram.
This is needed for sending the FND_Datagram with i.e. UDP

Returns:
data[]

getContext

public FND_DataPointContext getContext()
Returns:
The current context for this datapoint

setContext

public void setContext(FND_DataPointContext context)
Parameters:
context - an Context object that is responsible for working with this datapoint

getDatagramHeader

public byte[] getDatagramHeader()
Returns:
the datagram header part (mainly used by error datagrams)

getDatapointType

public byte getDatapointType()
Returns:
the dp_type field of the datagram

setDatapointType

public void setDatapointType(byte dpointtype)
Parameters:
dpointtype - the new value for the dp_type field of the datagram

getDatagramSegmentType

public byte getDatagramSegmentType()

setDatagramSegmentType

public void setDatagramSegmentType(byte dgramsegtype)

getDatagramTag

public byte getDatagramTag()
Returns:
the tag field of the datagram This field describes if this is an NORMAL, ERROR or REJECT datagram

setDatagramTag

public void setDatagramTag(byte dgramattr)

getDatagramType

public byte getDatagramType()

setDatagramType

public void setDatagramType(byte dgramtype)

getProtocolVersion

public int getProtocolVersion()
Returns:
the ProtocolVersion as an Integer ( 0xF0 for FND 1.0)

getSender

public java.net.InetAddress getSender()
Returns:
the InetAddress Object of the socket receiving the datagram

setSender

public void setSender(java.net.InetAddress address)
Parameters:
address - sets the InetAdress object