com.softplc
Class RemoteDataTable

java.lang.Object
  |
  +--com.softplc.DataTable
        |
        +--com.softplc.RemoteDataTable

All Implemented Interfaces:

java.io.Serializable

public class RemoteDataTable

extends DataTable

implements java.io.Serializable

Provide simple services for reading and writing words, and writing bits to a SoftPLC datatable via a TCP/IP connection.

A DataTable object represents a SoftPLC datatable. A DataTable is used to read or write to datatable words.

This class is like class DataTable, except that it works over a TCP/IP connection (remotely). So it can be used nicely in Client Applets and Client or SoftPLC Applications, when you need to read or write process data to a SoftPLC over a TCP/IP connection. No special server side support is needed, since the command set used is the one that is built into a SoftPLC for MMI and TOPDOC support.

Most of the DataTable methods take a special argument called a "handle". A handle must be constructed by the DataTable itself from a file (section) number, element number, and optional word number. A handle is simply a Java long that is used for fast access to a datatable value. A handle is not a machine pointer, but is like a pointer. It always points to the same logical datatable location. The actual values of two different handles pointing to adjacent datatable values will differ by a fixed offset. That offset is subject to change from one release to another. Your code should not hard code dependencies on this offset. You may however, use the DataTable constants ELEM_UNIT, and WORD_UNIT in your calculations. You could use these values to scoot through a datatable file with an ascending handle value.

Since there is some time associated in constructing handles, they should normally be constructed once in advance of their use.

A RemoteDataTable handle can be created for any legal datatable address, and the process of creating the remote handle will verify the existence of that memory within the target SoftPLC. However, at some time after handle creation, it is possible for the associated SoftPLC datatable memory to be destroyed due to PROGRAM mode editing. SoftPLC datatable may be expanded or contracted in PROGRAM mode, so the validity of a handle can change even during the lifetime of your program. Normally there will be an ArrayIndexOutOfBoundsException thrown when using an invalid handle.

Since memory allocation is expensive (somewhat slow) in Java, it is helpful for improved runtime performance if you can avoid creating new Java objects while in run mode. The DataTable class was designed consistent with this philosophy. Rather than returning new Java Objects, the DataTable methods either return a Java primitive, or will fill in or use an existing array Object. Array Objects should be re-used over and over again, rather than creating a new instance for each Datatable method invocation. Array Objects are always used in conjunction with a separate "count" argument, so that array Objects can be created on a worst case size basis, and then only a part of this array need be used as given by "count".

Since:

October 1996

See Also:

DataTable, Serialized Form

Field Summary

static int	MAXELEM The maximum SoftPLC element number within a file.
static int	MAXFILE The maximum datatable file number within the DataTable
static int	MAXWORD The maximum word number within an element.

Fields inherited from class com.softplc.DataTable

ELEM_UNIT, WORD_UNIT

Constructor Summary

RemoteDataTable(java.net.InetAddress localInterface, java.net.InetAddress remote, int timeout)
Construct a RemoteDataTable that has access to a particular PLC, given by the remote argument.

Method Summary

void	finalize() Close the connection if open.
int	getFileSize(long handle) Get the number of elements in the datatable section referenced by the given handle.
int	getFileType(long handle) Get the type of datatable section the given handle is referencing
float	getFloat(long handle) Fetch the current float value of a datatable word.
int	getInt(long handle) Fetch the current value of a datatable word.
long	handle(int file, int element) Make a handle for accessing the datatable word or element given by file:element.
long	handle(int file, int element, int word) Make a handle for accessing the datatable word or element given by file:element:word.
long	handle(java.lang.String address) Make a handle for accessing the datatable word or element given by a datatable address string such as I:000, N7:0, or T4:22.ACC.
boolean	isFloat(long handle) Determine if the datatable word referred to by a handle is a float.
boolean	isValid(long handle) Determine if the datatable memory referred to by a handle exists.
void	putBits(long handle, int andMask, int orMask) Do a read/modify/write operation on the given word.
void	putFloat(long handle, float value) Write a new value into the datatable word at handle.
void	putInt(long handle, int value) Write a new value into the datatable word at handle.
void	read(long handleOfFirst, int count, float[] block) Read a block of floats from a contiguous datatable block into the float array block.
void	read(long handleOfFirst, int count, int[] block) Read a block of ints from a contiguous datatable block into the int array block.
void	write(long handleOfFirst, int count, float[] block) Write a block of float words from array "block" into a given contiguous datatable region.
void	write(long handleOfFirst, int count, int[] block) Write a block of int words from array "block" into a given contiguous datatable region.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAXELEM

public static final int MAXELEM

The maximum SoftPLC element number within a file.

MAXFILE

public static final int MAXFILE

The maximum datatable file number within the DataTable

MAXWORD

public static final int MAXWORD

The maximum word number within an element. This limit pertains is dictated by the PID section.

Constructor Detail

RemoteDataTable

public RemoteDataTable(java.net.InetAddress localInterface,
                       java.net.InetAddress remote,
                       int timeout)
                throws java.io.IOException,
                       java.net.UnknownHostException

Construct a RemoteDataTable that has access to a particular PLC, given by the remote argument.

Parameters:

InetAddress - the local ethernet interface to use. You may pass null if you want the default interface.

InetAddress - the remote SoftPLC to connect to.

int - the number of msecs to wait for each transaction.

Throws:

java.net.UnknownHostException - if the local interface is not found.

java.io.IOException - if the remote host cannot be connected to.

Method Detail

handle

public long handle(int file,
                   int element)
            throws java.lang.ArrayIndexOutOfBoundsException

Make a handle for accessing the datatable word or element given by file:element. The resultant handle is good either for accessing the whole element or for accessing word 0 of the given element.

Overrides:

handle in class DataTable

Parameters:

int - the datatable file number.

int - the datatable element number.

Returns:

long - the handle

handle

public long handle(int file,
                   int element,
                   int word)
            throws java.lang.ArrayIndexOutOfBoundsException

Make a handle for accessing the datatable word or element given by file:element:word. The resultant handle is good for accessing the given word within an element.

Overrides:

handle in class DataTable

Parameters:

int - the datatable file number.

int - the datatable element number.

int - the datatable word number within a multi-word element.

Returns:

long - the handle

handle

public long handle(java.lang.String address)
            throws java.lang.ArrayIndexOutOfBoundsException,
                   java.text.ParseException

Make a handle for accessing the datatable word or element given by a datatable address string such as I:000, N7:0, or T4:22.ACC. The resultant handle is good for accessing the given word.

Overrides:

handle in class DataTable

Parameters:

String - the memory address string of a PLC word.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the address does not exist.

java.text.ParseException - if the address String is improperly formated.

getFileType

public int getFileType(long handle)
                throws java.lang.ArrayIndexOutOfBoundsException

Get the type of datatable section the given handle is referencing

Overrides:

getFileType in class DataTable

Parameters:

long - handle of any word in the datatable file.

Returns:

an element from interface DT

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the referenced file does not exist.

See Also:

DT

getFileSize

public int getFileSize(long handle)

Get the number of elements in the datatable section referenced by the given handle. The returned size is in elements, not words.

Overrides:

getFileSize in class DataTable

Parameters:

long - handle of any word in the datatable file.

Returns:

int the number of elements in the entire file or zero if the file does not exist.

isValid

public boolean isValid(long handle)

Determine if the datatable memory referred to by a handle exists.

Overrides:

isValid in class DataTable

Parameters:

long - a handle.

Returns:

boolean - true if the associated memory exists, else false.

isFloat

public final boolean isFloat(long handle)

Determine if the datatable word referred to by a handle is a float.

Overrides:

isFloat in class DataTable

Parameters:

long - a handle.

Returns:

boolean - true if the associated memory is float, else false it is int.

getInt

public int getInt(long handle)
           throws java.lang.ArrayIndexOutOfBoundsException

Fetch the current value of a datatable word. A 16 bit SoftPLC integer value is sign extended to 32 bits. If the handle points to a float datatable word, then the float is converted to a 32 bit int as if it were cast to a Java int in Java.

Overrides:

getInt in class DataTable

Parameters:

long - a handle.

Returns:

int - the value of the datatable word.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle is not currently valid.

See Also:

DataTable.getFloat(long), DataTable.read(long, int, int[])

getFloat

public float getFloat(long handle)
               throws java.lang.ArrayIndexOutOfBoundsException

Fetch the current float value of a datatable word. If the hanlde points to short word, then it is sign extended to a 32 bit int and then converted to a Java float. So a value of -23 becomes -23.0. If instead the handle points to a float datatable word, then the float value is returned unchanged.

Overrides:

getFloat in class DataTable

Parameters:

long - a handle.

Returns:

float - the value of the datatable word.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle is not currently valid.

See Also:

DataTable.getInt(long), DataTable.read(long, int, float[])

read

public void read(long handleOfFirst,
                 int count,
                 float[] block)
          throws java.lang.ArrayIndexOutOfBoundsException,
                 java.lang.NegativeArraySizeException

Read a block of floats from a contiguous datatable block into the float array block. The size of array block must be greater than or equal to count. If the count and/or the handleOfFirst cause a read to extend beyond the end of the actual datatable file, then throw an ArrayIndexOutOfBounds exception and read no words.

This method may be used to read from float datatable words or from int words. If the handle refers to an int file, then a conversion takes place as if each value were cast to float in Java, and this will be slightly slower as a result.

Overrides:

read in class DataTable

Parameters:

long - handle of first word to read. Contiguous words thereafter are read.

int - the number of words to read.

float[] - where to put the float words read.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle refers to datatable that does not have at least count words to the end of the file, or if the block array is not at least count elements in size.

java.lang.NegativeArraySizeException - if count < 0.

NullPointerException - if block is null.

See Also:

DataTable.getFloat(long)

read

public void read(long handleOfFirst,
                 int count,
                 int[] block)
          throws java.lang.ArrayIndexOutOfBoundsException,
                 java.lang.NegativeArraySizeException

Read a block of ints from a contiguous datatable block into the int array block. The size of array block must be greater than or equal to count. If the count and/or the handleOfFirst cause a read to extend beyond the end of the actual datatable file, then an ArrayIndexOutOfBounds exception is thrown and no words are read. This method may be used to read from float datatable words or from int words. If the handle refers to an float file, then a conversion takes place as if the value were cast to int in Java, and this will be slightly slower as a result.

Overrides:

read in class DataTable

Parameters:

long - handle of first word to read. Contiguous words thereafter are read.

int - the number of words to read.

int[] - where to put the int words read.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle refers to datatable that does not have at least count words to the end of the file, or if the block array is not at least count elements in size.

java.lang.NegativeArraySizeException - if count < 0.

NullPointerException - if block is null.

See Also:

DataTable.getInt(long)

putInt

public void putInt(long handle,
                   int value)
            throws java.lang.ArrayIndexOutOfBoundsException

Write a new value into the datatable word at handle. If the handle points to short word, then truncate the upper 16 bits of value. If the handle points to a float word, then first convert all 32 bits of value into a float. If the memory corresponding to handle does not exist, then throw an ArrayIndexOutOfBoundsException.

Overrides:

putInt in class DataTable

Parameters:

long - the handle of the datatable word to write to.

int - the value to write to the datatable word at handle.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle refers to datatable that does not exist.

See Also:

DataTable.putFloat(long, float), DataTable.write(long, int, int[])

putFloat

public void putFloat(long handle,
                     float value)
              throws java.lang.ArrayIndexOutOfBoundsException

Write a new value into the datatable word at handle. If the handle points to a short word, then first convert the float value to a Java int, and then the upper 16 bits of the value are truncated. Note that this conversion only works properly if

32767.0 >= value >= -32768.0. 

If the handle points to a float word, then simply copy the value unchanged. If the datatable memory corresponding to handle does not exist, then throw an ArrayIndexOutOfBoundsException.

Overrides:

putFloat in class DataTable

Parameters:

long - the handle of the datatable word to write to.

int - the value to write to the datatable word at handle.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle refers to datatable that does not exist.

write

public void write(long handleOfFirst,
                  int count,
                  int[] block)
           throws java.lang.ArrayIndexOutOfBoundsException

Write a block of int words from array "block" into a given contiguous datatable region. The size of array block must be greater than or equal to "count". If the count and/or the handleOfFirst cause a write to extend beyond the end of the actual datatable section, then throw an ArrayIndexOutOfBounds exception and do not write any values.

Overrides:

write in class DataTable

Parameters:

long - the handle of the first word to copy.

int - how many words to copy

int[] - source of the word values. Values will be truncated to 16 bits as needed.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if any part of the destination datatable does not exist or count is greater than the block array.

java.lang.NegativeArraySizeException - if count < 0.

write

public void write(long handleOfFirst,
                  int count,
                  float[] block)
           throws java.lang.ArrayIndexOutOfBoundsException

Write a block of float words from array "block" into a given contiguous datatable region. The size of array block must be greater than or equal to "count". If the count and/or the handleOfFirst cause a write to extend beyond the end of the actual datatable section, then throw an ArrayIndexOutOfBounds exception and do not write any values.

Overrides:

write in class DataTable

Parameters:

long - the handle of the first word to copy.

int - how many words to copy

float[] - source of the word values. Values will be truncated to 16 bits as needed.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if any part of the destination datatable does not exist or count is greater than the block array.

java.lang.NegativeArraySizeException - if count < 0.

putBits

public void putBits(long handle,
                    int andMask,
                    int orMask)
             throws java.lang.ArrayIndexOutOfBoundsException

Do a read/modify/write operation on the given word. The datatable word is set to the following expression:

word = (word & andMask) | orMask;

Only the lower 16 bits are used. If the handle points to a non-existent datatable value or to a value of type float, then an ArrayIndexOutOfBoundsException is thrown.

Example. Assume you want to turn off bit 0 and at the same time set bit 1 of a SoftPLC short word.

try {
SPLC.dt.putBits( handle, 0xFFFE, 2 );
} catch ( Exception e ) {}

Overrides:

putBits in class DataTable

Parameters:

long - which word to fiddle on

int - an andMask of bits that are ANDed with the current value.

int - an orMask of bits that are ORed with the current value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the handle refers to datatable that does not exist.

finalize

public void finalize()

Close the connection if open. public so it can be called by your code to force this to occur at a particular point in time, rather than waiting for the GC to call it.

Overrides:

finalize in class java.lang.Object