public abstract class BinaryData extends BaseDataType
The core idea of the class is to maximize the common code for subclasses, while allowing them to implement the actual storage allocation, deallocation, reading and writing using abstract workers. 4GL language features that are unique to a particular subclass are implemented in that subclass.
In addition to the implementation of many built-in functions and operators, this class hides
the representation and processing of unknown
.
The 4GL does not allow code to pass index positions or lengths as decimal
literals or expressions. Any such code will fail to compile. This means that all of the get
and set methods (including set-size and set-pointer-value) cannot take decimal
expressions (with the exception of the assigned data for the float/double getters/setters).
For this reason, all index and length parameters are long
so that there is no
loss of precision (using double
might result in such a precision loss even though
it would not result in a loss of magnitude).
Format string related processing is handled in the subclasses.
The following is the mapping of Progress language features to the corresponding feature in this class:
Progress Function Java Method --------------------------- ----------------------- get-bytegetByte(com.goldencode.p2j.util.NumberType)
get-bytesgetBytes(com.goldencode.p2j.util.NumberType, com.goldencode.p2j.util.NumberType)
get-doublegetDouble(com.goldencode.p2j.util.NumberType)
get-floatgetFloat(com.goldencode.p2j.util.NumberType)
get-int64getInt64(com.goldencode.p2j.util.NumberType)
get-longgetLong(long)
get-shortgetShort(com.goldencode.p2j.util.NumberType)
get-stringgetString(com.goldencode.p2j.util.NumberType)
get-unsigned-longgetUnsignedLong(com.goldencode.p2j.util.NumberType)
get-unsigned-shortgetUnsignedShort(com.goldencode.p2j.util.NumberType)
lengthlength(com.goldencode.p2j.util.BinaryData)
Progress Language Statement Java Method --------------------------- ----------------------- lengthsetLength(long)
put-bytesetByte(com.goldencode.p2j.util.NumberType, com.goldencode.p2j.util.NumberType)
put-bytessetBytes(com.goldencode.p2j.util.BinaryData, long)
put-doublesetDouble(double, long)
put-floatsetFloat(double, long)
put-int64setInt64(long, long)
put-longsetLong(long, long)
put-shortsetShort(long, long)
put-stringsetString(com.goldencode.p2j.util.character, com.goldencode.p2j.util.NumberType)
put-unsigned-longsetUnsignedLong(long, long)
put-unsigned-shortsetUnsignedShort(long, long)
Progress Operator Java Method --------------------------- ----------------------- = (assignment)assign(com.goldencode.p2j.util.BaseDataType, boolean)
comparisonscompareTo(java.lang.Object)
used byCompareOps
The following is the hierarchy for error/failure processing. The 4GL tests each of these in the listed order and the first one to fail will generate the described result, aborting any further checks. All reading and writing conforms to these rules.
Read checks:
unknown
, then unknown
will be
returned.
ErrorConditionException
will be thrown.
ErrorConditionException
will be thrown.
unknown
will be returned.
Write checks:
unknown
, then the write immediately returns without
changing anything.
ErrorConditionException
will be thrown.
ErrorConditionException
will be thrown.
setLong(long, long)
then the data being
written will be checked to ensure it is greater than or equal to -2147483648 and less
than or equal to 2147483647.
setUnsignedLong(long, long)
then the data
being written will be checked to ensure it is greater than or equal to 0 and less
than or equal to 4294967295.
isAutoExtend()
returns true
, will attempt to extend
its size automatically, up to the limit specified by lengthLimit()
. Subclasses
that do not auto-expand will throw an ErrorConditionException
.
Modifier and Type | Class and Description |
---|---|
protected static class |
BinaryData.RangeCheck
Encapsulates a range check and allows the execution of it to be delegated to other code.
|
Modifier and Type | Field and Description |
---|---|
protected boolean |
unknown
Stores the state of whether or not this instance represents the
unknown , independent of the state of this
instance's data. |
Constructor and Description |
---|
BinaryData()
Default constructor, creates an instance that is uninitialized.
|
BinaryData(byte[] value)
Constructor which creates an instance which is initialized based on
the given binary data.
|
Modifier and Type | Method and Description |
---|---|
protected abstract byte[] |
asByteArray()
Return the entire contents of the current buffer as an array.
|
void |
assign(BaseDataType data,
boolean force)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
void |
assign(BinaryData data)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
void |
assign(BinaryData data,
boolean force)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
void |
assign(byte[] data)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
void |
assign(Undoable value)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
protected void |
clearUnknown()
Sets the state of this instance's
unknown flag to false . |
int |
compareTo(java.lang.Object obj)
Compares this instance with the specified instance and returns a -1
if this instance is less than the specified, 0 if the two instances
are equal and 1 if this instance is greater than the specified
instance.
|
protected abstract void |
deallocate()
Release any resources associated with the instance.
|
java.lang.String |
defaultFormatString()
Return the default display format string for this type.
|
protected abstract void |
extendBytes(long len)
Helper to create a new byte array with the same contents as the given
byte array and the specified length.
|
protected abstract long |
findNextNull(long pos)
Returns the next index position into the array which is the
null byte,
starting at a given index position. |
private void |
genIndexError()
Generate the standard error message in the case where an invalid
index position (< 1) is used.
|
protected void |
genLimitedLengthError()
Generate the standard error message in the case where an access is
requested for a location past the end of an initialized
RAW variable. |
private void |
genOutOfBoundsError()
Generate the standard error message in the case where an access is
requested for a location past the end of an initialized
MEMPTR variable. |
private void |
genUninitializedError()
Generate the standard error message in the case where an access is
requested for an uninitialized variable.
|
private void |
genUnknownArgError()
Generate the standard error message in the case where a
unknown is passed to
GET or PUT. |
integer |
getByte(long pos)
Returns the byte at the given index position in the binary data.
|
integer |
getByte(NumberType pos)
Returns the byte at the given index position in the binary data.
|
byte[] |
getByteArray()
Accesses the state of this instance's binary data.
|
BinaryData |
getBytes(long pos,
long len)
Reads the given number of bytes starting at the given index position.
|
BinaryData |
getBytes(long pos,
NumberType len)
Reads the given number of bytes starting at the given index position.
|
BinaryData |
getBytes(NumberType pos,
long len)
Reads the given number of bytes starting at the given index position.
|
BinaryData |
getBytes(NumberType pos,
NumberType len)
Reads the given number of bytes starting at the given index position.
|
decimal |
getDouble(long pos)
Returns the 64-bit (8 byte) binary floating point data at the given position.
|
decimal |
getDouble(NumberType pos)
Returns the 64-bit (8 byte) binary floating point data at the given position.
|
decimal |
getFloat(long pos)
Returns the 32-bit (4 byte) binary floating point data at the given position.
|
decimal |
getFloat(NumberType pos)
Returns the 32-bit (4 byte) binary floating point data at the given position.
|
int64 |
getInt64(long pos)
Returns the signed 64-bit (8 byte) value from the given position.
|
int64 |
getInt64(NumberType pos)
Returns the signed 64-bit (8 byte) value from the given position.
|
private java.lang.Long |
getIntegerWorker(long pos,
int len,
boolean idxQuirk)
Returns a number using
len bytes at the pos position. |
integer |
getLong(long pos)
Returns the signed 32-bit (4 byte) value from the given position.
|
integer |
getLong(NumberType pos)
Returns the signed 32-bit (4 byte) value from the given position.
|
private boolean |
getMethodSetup(long first,
long len,
boolean idxQuirk)
Common worker to handle the error checking/processing with no triggering
of auto-expand features.
|
integer |
getShort(long pos)
Returns the signed 16-bit (2 byte) value from the given position.
|
integer |
getShort(NumberType pos)
Returns the signed 16-bit (2 byte) value from the given position.
|
character |
getString(long pos)
Gets the bytes at the given starting index position in the binary data up to but NOT the
including next
null byte or the complete contents of the given buffer,
whichever comes first. |
character |
getString(long pos,
long len)
Gets the bytes at the given starting index position in the binary data.
|
character |
getString(long pos,
NumberType len)
Gets the bytes at the given starting index position in the binary data.
|
character |
getString(NumberType pos)
Gets the bytes at the given starting index position in the binary data up to but NOT the
including next
null byte or the complete contents of the given buffer,
whichever comes first. |
character |
getString(NumberType pos,
long len)
Gets the bytes at the given starting index position in the binary data.
|
character |
getString(NumberType pos,
NumberType len)
Gets the bytes at the given starting index position in the binary data.
|
java.lang.Double |
getUnprocessedDouble(long pos)
Returns the 64-bit (8 byte) binary floating point data at the given position
without wrapping it in a decimal instance.
|
int64 |
getUnsignedLong(long pos)
Returns the unsigned 32-bit (4 byte) value from the given position.
|
int64 |
getUnsignedLong(NumberType pos)
Returns the unsigned 32-bit (4 byte) value from the given position.
|
integer |
getUnsignedShort(long pos)
Returns the unsigned 16-bit (2 byte) value from the given position.
|
integer |
getUnsignedShort(NumberType pos)
Returns the unsigned 16-bit (2 byte) value from the given position.
|
int |
hashCode()
Hash code implementation which is consistent with
BaseDataType.equals(java.lang.Object) . |
protected abstract long |
internalLength()
The actual size of the buffer (in bytes).
|
protected abstract boolean |
isAutoExtend()
Determines if the array of binary data stored in an instance of this
class must be automatically extended in length when operations
write past the current length.
|
protected abstract boolean |
isLengthLimited()
Determines if the array of binary data stored in an instance of this
class must be limited in length.
|
abstract boolean |
isUninitialized()
Reports if this instance represents an uninitialized buffer.
|
boolean |
isUnknown()
Reports if this instance represents
unknown . |
int64 |
length()
Returns the length this instance's data in bytes.
|
static int64 |
length(BinaryData bd)
Returns the length of the given instance in bytes.
|
protected abstract long |
lengthLimit()
Determines the maximum length of the array of binary data stored in an
instance of this class.
|
long |
lengthOf()
Returns the length this instance's data in bytes.
|
protected abstract byte |
readByte(long pos)
Read the byte at the given location.
|
protected abstract byte[] |
readByteRange(long pos,
long len,
boolean endian)
Read the bytes at the given location.
|
void |
readExternal(java.io.ObjectInput in)
Replacement for the default object reading method.
|
protected abstract void |
replaceContents(byte[] value)
Replace the entire contents of the current buffer with the given array.
|
protected byte[] |
reverseBytes(byte[] data)
Return a copy of the input array with the order of the byte reversed.
|
BinaryData |
setByte(long val,
long pos)
Sets the byte at the given index position in the binary data.
|
BinaryData |
setByte(long val,
NumberType pos)
Sets the byte at the given index position in the binary data.
|
BinaryData |
setByte(NumberType val,
long pos)
Sets the byte at the given index position in the binary data.
|
BinaryData |
setByte(NumberType val,
NumberType pos)
Sets the byte at the given index position in the binary data.
|
BinaryData |
setBytes(BinaryData data,
long pos)
Writes the given data into the specified location of the current instance.
|
BinaryData |
setBytes(BinaryData data,
NumberType pos)
Writes the given data into the specified location of the current instance.
|
BinaryData |
setDouble(double data,
long pos)
Write the decimal as a 64-bit (8 byte) binary floating-point value at the specified
location.
|
BinaryData |
setDouble(double data,
NumberType pos)
Write the decimal as a 64-bit (8 byte) binary floating-point value at the specified
location.
|
BinaryData |
setDouble(NumberType data,
long pos)
Write the decimal as a 64-bit (8 byte) binary floating-point value at the specified
location.
|
BinaryData |
setDouble(NumberType data,
NumberType pos)
Write the decimal as a 64-bit (8 byte) binary floating-point value at the specified
location.
|
BinaryData |
setFloat(double data,
long pos)
Write the decimal as a 32-bit (4 byte) binary floating-point value at the specified
location.
|
BinaryData |
setFloat(double data,
NumberType pos)
Write the decimal as a 32-bit (4 byte) binary floating-point value at the specified
location.
|
BinaryData |
setFloat(NumberType data,
long pos)
Write the decimal as a 32-bit (4 byte) binary floating-point value at the specified
location.
|
BinaryData |
setFloat(NumberType data,
NumberType pos)
Write the decimal as a 32-bit (4 byte) binary floating-point value at the specified
location.
|
BinaryData |
setInt64(long data,
long pos)
Writes the signed 64-bit (8 byte) value into the binary data starting at the given
position.
|
BinaryData |
setInt64(long data,
NumberType pos)
Writes the signed 64-bit (8 byte) value into the binary data starting at the given
position.
|
BinaryData |
setInt64(NumberType data,
long pos)
Writes the signed 64-bit (8 byte) value into the binary data starting at the given
position.
|
BinaryData |
setInt64(NumberType data,
NumberType pos)
Writes the signed 64-bit (8 byte) value into the binary data starting at the given
position.
|
private BinaryData |
setIntegerWorker(long data,
long pos,
int len,
BinaryData.RangeCheck range,
boolean idxQuirk)
Puts
len bytes from data into internal storage starting at
pos . |
abstract BinaryData |
setLength(long len)
Sets the length of the buffer/array to a given length.
|
BinaryData |
setLength(NumberType len)
Sets the length of the buffer/array to a given length.
|
BinaryData |
setLong(long data,
long pos)
Writes the signed 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setLong(long data,
NumberType pos)
Writes the signed 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setLong(NumberType data,
long pos)
Writes the signed 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setLong(NumberType data,
NumberType pos)
Writes the signed 32-bit (4 byte) value into the binary data starting at the given
position.
|
private boolean |
setMethodSetup(long first,
long len,
BinaryData.RangeCheck range,
boolean idxQuirk)
Common worker to handle the error checking/processing and the honoring of length/auto-expand
features.
|
BinaryData |
setShort(long data,
long pos)
Writes the signed 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setShort(long data,
NumberType pos)
Writes the signed 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setShort(NumberType data,
long pos)
Writes the signed 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setShort(NumberType data,
NumberType pos)
Writes the signed 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setString(character data,
long pos)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(character data,
long pos,
long len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(character data,
long pos,
NumberType len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(character data,
NumberType pos)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(character data,
NumberType pos,
long len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(character data,
NumberType pos,
NumberType len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
long pos)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
long pos,
long len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
long pos,
NumberType len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
NumberType pos)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
NumberType pos,
long len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
BinaryData |
setString(java.lang.String data,
NumberType pos,
NumberType len)
Sets the bytes at the given starting index position in the binary data to the partial or
complete contents of the given string.
|
void |
setUnknown()
Sets the state of this instance's
unknown flag to true . |
BinaryData |
setUnsignedLong(long data,
long pos)
Writes the unsigned 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedLong(long data,
NumberType pos)
Writes the unsigned 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedLong(NumberType data,
long pos)
Writes the unsigned 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedLong(NumberType data,
NumberType pos)
Writes the unsigned 32-bit (4 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedShort(long data,
long pos)
Writes the unsigned 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedShort(long data,
NumberType pos)
Writes the unsigned 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedShort(NumberType data,
long pos)
Writes the unsigned 16-bit (2 byte) value into the binary data starting at the given
position.
|
BinaryData |
setUnsignedShort(NumberType data,
NumberType pos)
Writes the unsigned 16-bit (2 byte) value into the binary data starting at the given
position.
|
protected abstract long |
visibleLength()
The length of the buffer as reported to P4GL application.
|
protected abstract void |
writeByte(byte val,
long pos)
Write the byte into the given location.
|
protected abstract void |
writeByteRange(byte[] data,
long pos,
boolean endian)
Write the bytes at the given location.
|
void |
writeExternal(java.io.ObjectOutput out)
Replacement for the default object writing method.
|
assign, calcFormatLength, deepCopy, duplicate, elementsOfType, equals, formatLength, generateDefault, generateUnknown, getTypeName, incompatibleTypesOnConversion, initializeDefaultExtent, instantiateDefault, instantiateDefaultExtent, instantiateUnknown, isUnknownValue, maximum, minimum, notUnknownValue, sameType, toString, toStringExport, toStringMessage
changed, checkUndoable, checkUndoable, checkUndoable, getTransLevel, isGlobal, isUndoable, markUndoable, popBlock, rollback, setGlobal
protected boolean unknown
unknown
, independent of the state of this
instance's data.public BinaryData()
public BinaryData(byte[] value)
value
- The binary data to be used as the contents or if
null
then the instance will represent the
unknown
.public boolean isUnknown()
unknown
.isUnknown
in class BaseDataType
true
if this instance is set to the
unknown
.public void setUnknown()
unknown
flag to true
.
Warning: the data stored in this instance WILL BE deallocated after calling this method.
setUnknown
in class BaseDataType
public java.lang.String defaultFormatString()
defaultFormatString
in class BaseDataType
public byte[] getByteArray()
null
if this instance is
unknown
. If uninitialized, the returned array will have 0
elements. If the instance is initialized but the runtime has no knowledge
of the buffer's size, null
will be returned.public void assign(BaseDataType data, boolean force)
If the value is of type BinaryData
, the result will be the same as calling
assign(BaseDataType,boolean)
. If the type is the unknown literal the instance
will be set to unknown value.
If the value is not of type BinaryData
an error condition will be thrown
because the 4GL does not support automatic type conversion for other BDT's
(even character and longchar are not accepted).
This variant is meant to handle the cases of built-in functions and methods in the 4GL which have polymorphic return types (e.g. DYNAMIC-FUNCTION()). This should NOT be used for non-polymorphic assignments.
assign
in class BaseDataType
data
- The instance from which to copy state.force
- Flag to indicate if a pending error should be ignored (see
ErrorManager.isPendingError()
and the assignment
forced regardless. Note that normal assignment silently
exits with no change if there is a pending error. If this
flag is true
, that check is bypassed and the
assignment will always be done.ErrorConditionException
- If the given data is not an instance of this class.public void assign(BinaryData data, boolean force)
If the given instance is null
or unknown
, the instance will be
set to unknown
. If the length of the given data is 0 OR if the length of the
an initialized buffer is indeterminate, then the instance will be reset as uninitialized
(including deallocation of any current buffer). If the length of the array is greater than
0, then any current buffer will be deallocated, a new buffer of the proper size will be
allocated and the data will be copied in. This is how the 4GL does it.
data
- The instance from which to copy state.force
- Flag to indicate if a pending error should be ignored (see
ErrorManager.isPendingError()
and the assignment is forced regardless.
Normal assignment silently exits with no change if there is a pending error. If
this flag is true
, that check is bypassed and the assignment will
always be done.public void assign(BinaryData data)
If the given instance is null
or unknown
, the instance will be
set to unknown
. If the length of the given data is 0 OR if the length of the
an initialized buffer is indeterminate, then the instance will be reset as uninitialized
(including deallocation of any current buffer). If the length of the array is greater than
0, then any current buffer will be deallocated, a new buffer of the proper size will be
allocated and the data will be copied in. This is how the 4GL does it.
This is a "no operation" in the case where silent error mode is active AND an error has
occurred in the current processing since the opening call to
ErrorManager.silentErrorEnable()
. This protection is needed to ensure that the state
of this instance does not change in this case. This will not affect undo because that
only occurs when silent error mode is disabled.
data
- The instance from which to copy state.public void assign(Undoable value)
If the given instance is null
or unknown
, the instance will be
set to unknown
. If the length of the given data is 0 OR if the length of the
an initialized buffer is indeterminate, then the instance will be reset as uninitialized
(including deallocation of any current buffer). If the length of the array is greater than
0, then any current buffer will be deallocated, a new buffer of the proper size will be
allocated and the data will be copied in. This is how the 4GL does it.
value
- The instance from which to copy state.public void assign(byte[] data)
If the given instance is null
or unknown
, the instance will be
set to unknown
. If the length of the given data is 0 OR if the length of the
an initialized buffer is indeterminate, then the instance will be reset as uninitialized
(including deallocation of any current buffer). If the length of the array is greater than
0, then any current buffer will be deallocated, a new buffer of the proper size will be
allocated and the data will be copied in. This is how the 4GL does it.
data
- The new contents.public int compareTo(java.lang.Object obj)
Comparable
interface.
The algorithm will fail to give meaningful results in the case where one tries to sort against other objects that do not represent compatible values.
obj
- The instance to compare against.obj
.public int hashCode()
BaseDataType.equals(java.lang.Object)
.
Performance is not stellar for large binary values. Likewise, distribution of hash codes is fairly weak, since a maximum of 33 samples are used from the underlying byte array to differentiate results. It is therefore recommended that large binary data values not be used within or as hashing keys.
hashCode
in class BaseDataType
public integer getByte(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTE
built-in function.
pos
- The 1-based index position to return, must be > 0.unknown
if this instance is unknown
or if the index position is greater
than the size of the binary data or if the given index position is
unknown
.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public integer getByte(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTE
built-in function.
pos
- The 1-based index position to return, must be > 0.unknown
if this instance is unknown
or if the index position is greater
than the size of the binary data.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setByte(NumberType val, NumberType pos) throws ErrorConditionException
unknown
or if the instance itself is unknown
, no change will
be made.
This is equivalent to the 4GL PUT-BYTE
language statement.
val
- The byte value to assign to the given position.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data.public BinaryData setByte(NumberType val, long pos) throws ErrorConditionException
unknown
or if the instance itself is unknown
, no change will
be made.
This is equivalent to the 4GL PUT-BYTE
language statement.
val
- The byte value to assign to the given position.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data.public BinaryData setByte(long val, NumberType pos) throws ErrorConditionException
unknown
or if the instance itself is unknown
, no change will
be made.
This is equivalent to the 4GL PUT-BYTE
language statement.
val
- The byte value to assign to the given position.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data.public BinaryData setByte(long val, long pos) throws ErrorConditionException
unknown
or if the instance itself is unknown
, no change will
be made.
This is equivalent to the 4GL PUT-BYTE
language statement.
val
- The byte value to assign to the given position.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data.public character getString(NumberType pos) throws ErrorConditionException
null
byte or the complete contents of the given buffer,
whichever comes first. The resulting bytes will be interpreted as characters and turned
into a text string.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public character getString(long pos) throws ErrorConditionException
null
byte or the complete contents of the given buffer,
whichever comes first. The resulting bytes will be interpreted as characters and turned
into a text string.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public character getString(long pos, NumberType len) throws ErrorConditionException
If the specified len
is negative, this method will copy up to but NOT
including the first null
byte or it will copy to the end of the string if no
null
byte exists. Otherwise, exactly the specified number of characters
will be copied, without regard to any embedded null
bytes.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <= the length of the
buffer.len
- The number of bytes to copy. Contrary to the 4GL documentation, all values less
than 1 are allowed. Use any negative value (not just -1) to copy up to but NOT
including the first null
byte. A 0 value will cause an empty string
to be returned.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range
or if the index plus len is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public character getString(NumberType pos, long len) throws ErrorConditionException
If the specified len
is negative, this method will copy up to but NOT
including the first null
byte or it will copy to the end of the string if no
null
byte exists. Otherwise, exactly the specified number of characters
will be copied, without regard to any embedded null
bytes.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <= the length of the
buffer.len
- The number of bytes to copy. Contrary to the 4GL documentation, all values less
than 1 are allowed. Use any negative value (not just -1) to copy up to but NOT
including the first null
byte. A 0 value will cause an empty string
to be returned.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range
or if the index plus len is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public character getString(NumberType pos, NumberType len) throws ErrorConditionException
If the specified len
is negative, this method will copy up to but NOT
including the first null
byte or it will copy to the end of the string if no
null
byte exists. Otherwise, exactly the specified number of characters
will be copied, without regard to any embedded null
bytes.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <= the length of the
buffer.len
- The number of bytes to copy. Contrary to the 4GL documentation, all values less
than 1 are allowed. Use any negative value (not just -1) to copy up to but NOT
including the first null
byte. A 0 value will cause an empty string
to be returned.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range
or if the index plus len is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public character getString(long pos, long len) throws ErrorConditionException
If the specified len
is negative, this method will copy up to but NOT
including the first null
byte or it will copy to the end of the string if no
null
byte exists. Otherwise, exactly the specified number of characters
will be copied, without regard to any embedded null
bytes.
This is equivalent to the 4GL GET-STRING
built-in function.
pos
- The 1-based index position to set, must be > 0 and <= the length of the
buffer.len
- The number of bytes to copy. Contrary to the 4GL documentation, all values less
than 1 are allowed. Use any negative value (not just -1) to copy up to but NOT
including the first null
byte. A 0 value will cause an empty string
to be returned.unknown
if the instance is unknown
,
or any input is unknown
or if the index position is out of range
or if the index plus len is out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setString(character data, NumberType pos) throws ErrorConditionException
null
byte or it will copy to the end of the string if no null
byte exists.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, NumberType pos) throws ErrorConditionException
null
byte or it will copy to the end of the string if no null
byte exists.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, long pos) throws ErrorConditionException
null
byte or it will copy to the end of the string if no null
byte exists.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(character data, long pos) throws ErrorConditionException
null
byte or it will copy to the end of the string if no null
byte exists.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, long pos, NumberType len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(character data, long pos, long len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, NumberType pos, long len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(character data, long pos, NumberType len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(character data, NumberType pos, long len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, NumberType pos, NumberType len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(character data, NumberType pos, NumberType len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setString(java.lang.String data, long pos, long len) throws ErrorConditionException
len
is -1, this
method will copy up to and including the first null
byte or it will copy to
the end of the string if no null
byte exists. Otherwise, exactly the specified
number of characters will be copied, without regard to any embedded null
bytes.
Implements auto-extend and length limitations for subclasses which require this support.
If the instance to be modified is unknown
or if any of the inputs are
unknown
, no change will be made.
This is equivalent to the 4GL PUT-STRING
language statement.
data
- Source string from which to copy.pos
- The 1-based index position to set, must be > 0.len
- The number of bytes to copy or -1 to copy up to and including the first
null
byte.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public integer getLong(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-LONG
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public integer getLong(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-LONG
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setLong(long data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-LONG
language statement.
data
- The 32-bit value to be written. As in the 4GL, this must be greater than or
equal to -2147483648 and less than or equal to 2147483647.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setLong(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setLong(long data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setLong(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public integer getShort(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public integer getShort(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setShort(long data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setShort(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setShort(long data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setShort(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public decimal getDouble(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-DOUBLE
built-in function.
pos
- The 1-based index position to read from, must be > 0 and <=
the length of the buffer.unknown
will be returned if the instance is
unknown
, if any input is unknown
or if any portion
of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public decimal getDouble(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-DOUBLE
built-in function.
pos
- The 1-based index position to read from, must be > 0 and <=
the length of the buffer.unknown
will be returned if the instance is
unknown
, or if any portion of the read bytes are in positions
that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public java.lang.Double getUnprocessedDouble(long pos) throws ErrorConditionException
pos
- The 1-based index position to read from, must be > 0 and <=
the length of the buffer.null
is returned if the instance is unknown
,
or if any portion of the read bytes are in positions that are out of range.ErrorConditionException
public BinaryData setDouble(double data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-DOUBLE
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setDouble(double data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-DOUBLE
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setDouble(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-DOUBLE
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setDouble(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-DOUBLE
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public decimal getFloat(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-FLOAT
built-in function.
pos
- The 1-based index position to read from, must be > 0 and <=
the length of the buffer.unknown
will be returned if the instance is
unknown
, if any input is unknown
or if any portion
of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public decimal getFloat(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-FLOAT
built-in function.
pos
- The 1-based index position to read from, must be > 0 and <=
the length of the buffer.unknown
will be returned if the instance is
unknown
, if any input is unknown
or if any portion
of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setFloat(double data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-FLOAT
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setFloat(double data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-FLOAT
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setFloat(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-FLOAT
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setFloat(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-FLOAT
language statement.
data
- The value to be written.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public int64 getInt64(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-INT64
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public int64 getInt64(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-INT64
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setInt64(long data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-INT64
language statement.
data
- The 64-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setInt64(long data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-INT64
language statement.
data
- The 64-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setInt64(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-INT64
language statement.
data
- The 64-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setInt64(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-INT64
language statement.
data
- The 64-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public integer getUnsignedShort(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-UNSIGNED-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public integer getUnsignedShort(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-UNSIGNED-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setUnsignedShort(long data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedShort(long data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedShort(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedShort(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-SHORT
language statement.
data
- The 16-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public int64 getUnsignedLong(NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL GET-UNSIGNED-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public int64 getUnsignedLong(long pos) throws ErrorConditionException
This is equivalent to the 4GL GET-UNSIGNED-SHORT
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setUnsignedLong(long data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-LONG
language statement.
data
- The 32-bit value to be written. As in the 4GL, this value must be greater than
or equal to 0 and less than or equal to 4294967295.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedLong(long data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedLong(NumberType data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setUnsignedLong(NumberType data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-UNSIGNED-LONG
language statement.
data
- The 32-bit value to be written.pos
- The 1-based index position, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData getBytes(NumberType pos, NumberType len) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTES
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.len
- The number of bytes to read.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData getBytes(long pos, NumberType len) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTES
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.len
- The number of bytes to read.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData getBytes(NumberType pos, long len) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTES
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.len
- The number of bytes to read.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData getBytes(long pos, long len) throws ErrorConditionException
This is equivalent to the 4GL GET-BYTES
built-in function.
pos
- The 1-based index position to set, must be > 0 and <=
the length of the buffer.len
- The number of bytes to read.unknown
will be returned if
the instance is unknown
, if any input is unknown
or if
any portion of the read bytes are in positions that are out of range.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1.public BinaryData setBytes(BinaryData data, long pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-BYTES
language statement.
data
- The binary data to be copied.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public BinaryData setBytes(BinaryData data, NumberType pos) throws ErrorConditionException
This is equivalent to the 4GL PUT-BYTES
language statement.
data
- The binary data to be copied.pos
- The 1-based index position to set, must be > 0.ErrorConditionException
- If the instance is uninitialized or if the index position is < 1. Subclasses
which don't auto-extend will also cause an exception when the index position
is past the end of the data or when the index position plus the length of the
data to be written exceed the end of the destination buffer.public static int64 length(BinaryData bd)
bd
- The instance to test.unknown
.public int64 length()
unknown
.public long lengthOf()
unknown
.public abstract BinaryData setLength(long len)
len
- New length of the buffer/array.public BinaryData setLength(NumberType len)
len
- New length of the buffer/array. If this is unknown
then the instance
will be set to unknown
.public void readExternal(java.io.ObjectInput in) throws java.io.IOException, java.lang.ClassNotFoundException
in
- The input source from which fields will be restored.java.io.IOException
- In case of I/O errors.java.lang.ClassNotFoundException
- If payload can't be instantiated.public void writeExternal(java.io.ObjectOutput out) throws java.io.IOException
out
- The output destination to which fields will be saved.java.io.IOException
- In case of I/O errors.public abstract boolean isUninitialized()
unknown
is also different from being uninitialized.true
if this instance is unininitialized.protected void clearUnknown()
unknown
flag to false
.protected byte[] reverseBytes(byte[] data)
data
- The input data to reverse.protected void genLimitedLengthError() throws ErrorConditionException
RAW
variable.ErrorConditionException
protected abstract void deallocate()
protected abstract boolean isLengthLimited()
true
if the length must be limited.protected abstract long lengthLimit()
protected abstract boolean isAutoExtend()
null
bytes.true
if the length must automatically extended.protected abstract void extendBytes(long len)
This is safe to use on 0 length arrays.
len
- The output array length.protected abstract void replaceContents(byte[] value)
The unknown
flag is also cleared, only if value
is not
null
and if the length is greater than 0.
value
- The new contents.protected abstract byte[] asByteArray()
unknown
, then null
will be returned.protected abstract long internalLength()
protected abstract long visibleLength()
protected abstract long findNextNull(long pos)
null
byte,
starting at a given index position.pos
- The 0-based index into the array at which to start searching.null
byte or the length
of the array if no null
byte exists.protected abstract byte readByte(long pos)
pos
- The 0-based index position at which to read the byte.protected abstract void writeByte(byte val, long pos)
val
- The byte to write.pos
- The 0-based index position at which to read the byte.protected abstract byte[] readByteRange(long pos, long len, boolean endian)
pos
- The 0-based index position at which to read the bytes.len
- The number of bytes to read.endian
- true
to force the returned data to be ordered by the endian-ness of the
instance.protected abstract void writeByteRange(byte[] data, long pos, boolean endian)
data
- The bytes to write.pos
- The 0-based index position at which to start writing the bytes.endian
- true
to honor the endian-ness of the instance. The data
array MUST be ordered in little-endian order if the endian flag is on.private boolean getMethodSetup(long first, long len, boolean idxQuirk) throws ErrorConditionException
first
- The 1-based index position of first access, must be > 0.len
- The number of bytes to be accessed starting at pos
, must be > 0
except for the "unspecified" length passed to GET-STRING, in which case this is
given as -1.idxQuirk
- true
if the caller disables boundary checking when the instance
is initialized with NEGATIVE indeterminate size (as opposed to size zero). This
occurs when SET-POINTER-VALUE is called without a subsquent call to SET-SIZE
which would establish the boundary. Only certain callers disable this checking
and when passed as false
then the normal checking applies. Since
the indeterminate size is always less than the first index position, this will
always generate an error.true
if no errors occurred and the caller should continue
processing. false
if the caller should immediately return
unknown
.ErrorConditionException
- When any of the tested failure conditions are encountered.private boolean setMethodSetup(long first, long len, BinaryData.RangeCheck range, boolean idxQuirk) throws ErrorConditionException
first
- The 1-based index position of first access, must be > 0.len
- The number of bytes to be accessed starting at pos
, must be > 0.range
- A caller-encoded range check or null
if no range check is needed.idxQuirk
- true
if the caller disables boundary checking when the instance
is initialized with NEGATIVE indeterminate size (as opposed to size zero). This
occurs when SET-POINTER-VALUE is called without a subsequent call to SET-SIZE
which would establish the boundary. Only certain callers disable this checking
and when passed as false
then the normal checking applies. Since
the indeterminate size is always less than the first index position, this will
always generate an error.true
if no errors occurred and the caller should continue
processing. false
if the caller should immediately return
unknown
.ErrorConditionException
- When any of the tested failure conditions are encountered.private void genIndexError() throws ErrorConditionException
ErrorConditionException
private void genUninitializedError() throws ErrorConditionException
ErrorConditionException
private void genOutOfBoundsError() throws ErrorConditionException
MEMPTR
variable.ErrorConditionException
private void genUnknownArgError() throws ErrorConditionException
unknown
is passed to
GET or PUT. The instance itself being unknown
is a different issue and does
not cause the GET or PUT to fail.ErrorConditionException
private BinaryData setIntegerWorker(long data, long pos, int len, BinaryData.RangeCheck range, boolean idxQuirk)
len
bytes from data
into internal storage starting at
pos
. This method is called for int64 (len = 8), long (len = 4) and short
(len = 2).data
- The bytes that need to be stored.pos
- The position in the storage.len
- The amount of bytes to be copied.range
- A caller-encoded range check or null
if no range check is needed.idxQuirk
- true
if the caller disables boundary checking when the instance
is initialized with NEGATIVE indeterminate size (as opposed to size zero). This
occurs when SET-POINTER-VALUE is called without a subsquent call to SET-SIZE
which would establish the boundary. Only certain callers disable this checking
and when passed as false
then the normal checking applies. Since
the indeterminate size is always less than the first index position, this will
always generate an error.private java.lang.Long getIntegerWorker(long pos, int len, boolean idxQuirk)
len
bytes at the pos
position. If there are
no such bytes available a null
object is returned. The caller is responsible
for returning unknown
when null
is returned.pos
- The position from where the bytes are user to compose the returning integer.len
- The amount of bytes to be used. Any amount of bytes can be specified limited only
by the 8 bytes of returning Long
, but practical values are 8, 4 and 2.idxQuirk
- true
if the caller disables boundary checking when the instance
is initialized with NEGATIVE indeterminate size (as opposed to size zero). This
occurs when SET-POINTER-VALUE is called without a subsquent call to SET-SIZE
which would establish the boundary. Only certain callers disable this checking
and when passed as false
then the normal checking applies. Since
the indeterminate size is always less than the first index position, this will
always generate an error.Long
that contains a number obtained from the specified bytes or
null
if specified bytes are not available.