memptr (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.util.LazyUndoable
- - com.goldencode.p2j.util.BaseDataType
  - - com.goldencode.p2j.util.BinaryData
    - - com.goldencode.p2j.util.memptr

All Implemented Interfaces:

LargeObject, Undoable, java.io.Externalizable, java.io.Serializable, java.lang.Comparable
```
public class memptr
extends BinaryData
implements LargeObject
```
Implements the unique behavior of a Progress 4GL compatible MEMPTR data type which is backed by a native platform memory buffer (instead of being allocated on the Java heap). The contents of the buffer are mutable. All Progress 4GL language features are supported up to the 10.2B level.
Format string related processing is handled in method toString(String).
The following is the mapping of Progress language features to the corresponding feature in this class:
```
 Progress Function               Java Method
 -----------------------------   -----------------------
 get-byte-order                  getByteOrder()
 get-pointer-value               getPointerValue()
 get-size                        BinaryData.length(com.goldencode.p2j.util.BinaryData)

 Progress Language Statement     Java Method
 -----------------------------   -----------------------
 set-byte-order                  setByteOrder(int)
 set-pointer-value               setPointerValue(com.goldencode.p2j.util.NumberType)
 set-size                        setLength(long)
 
```
All of the above features are specific to the MEMPTR type (they do not work for RAW variables in the 4GL, such attempted usage will cause a compiler error). All other features are shared and are implemented in the common base class.
See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`memptr.memptrPointer` A data structure with the details about the 'pointer' referenced by this instance.
`private static class`	`memptr.WorkArea` Container for context-local data.

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BinaryData
BinaryData.RangeCheck

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BaseDataType
BaseDataType.Type, BaseDataType.WrapperHandler

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BIG_ENDIAN` Operations should use big endian byte order.
`private static ContextLocal<memptr.WorkArea>`	`ctxt` Stores context local instances of the remote memory manager proxy.
`static int`	`HOST_BYTE_ORDER` Operations should use the native byte order on the current machine.
`static int`	`LITTLE_ENDIAN` Operations should use little endian byte order.
`private static CentralLogger`	`LOG` Logger
`static int`	`LOWER_BOUND` Smallest value accepted in SET-SIZE() without generating an error.
`static int`	`NO_BYTE_ORDER` No byte order has been explicitly requested.
`private boolean`	`parameter` Flag indicating this is a parameter.
`private memptr.memptrPointer`	`pointer` Pointer structure shared between parameters and arguments.
`private boolean`	`srcWasUnknown` Flag indicating if the source argument for this parameter was unknown.
`static int`	`UPPER_BOUND` Largest value accepted in SET-SIZE() without generating an error.
`private memptr.WorkArea`	`workArea` The working area where this instance was created.

Fields inherited from class com.goldencode.p2j.util.BinaryData
unknown

Constructor Summary

Constructors
Constructor and Description
`memptr()` Default constructor, creates an instance that represents an uninitialized byte array (a `null` array).
`memptr(BaseDataType value)` This is a special c'tor which should be used only when converting the value returned by a function or method with polymorphic return type into the expected type (i.e.
`memptr(byte[] value)` Constructs an instance after copying the parameter's data into the internal representation of this class.
`memptr(memptr value)` Constructs an instance after copying the parameter's data into the internal representation of this class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected byte[]`	`asByteArray()` Return the entire contents of the current buffer as an array.
`byte[]`	`asByteArray(long pos, long len)` Return the entire contents of the current buffer as an array.
`protected void`	`asParameter(memptr src)` Setup this instance to act as a parameter; this shares the `pointer` with the source memptr.
`void`	`assign(BinaryData data)` Sets the state (data and unknown value) of this instance based on the state of the passed instance.
`private void`	`checkAddressSpace(long ptr)` When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
`private void`	`clearAddressSpace(long ptr, long size)` When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
`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 static int`	`compiledWordSize()` Returns the word size (the size of a pointer) for the native code as compiled.
`protected void`	`copyByteRange(memptr data, long pos, long len)` Copy the specified number of bytes from the source instance into the current instance at the given location.
`private void`	`copyPointer(memptr m)` Copy the pointer details from the specified instance.
`protected void`	`deallocate()` Release any resources associated with the instance.
`memptr`	`duplicate()` Does the same as standard `clone()` method but returns an instance of `BaseDataType` and doesn't throw the `CloneNotSupportedException`.
`protected 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 long`	`findNextNull(long pos)` Returns the next index position into the array which is the `null` byte, starting at a given index position.
`integer`	`getByteOrder()` Reports the byte order mode configured in this instance.
`(package private) static LowLevelBuffer`	`getMemoryManager()` Returns the low-level memory manager.
`int64`	`getPointerValue()` Method implementation of the GET-POINTER-VALUE 4GL built-in function which returns a 64-bit integer value representing the pointer used by the instance.
`BaseDataType.Type`	`getType()` Get the type
`BaseDataType`	`instantiateDefault()` Creates a new instance of the same type that represents the default initialized value.
`BaseDataType`	`instantiateUnknown()` Creates a new instance of the same type that is `unknown`.
`static memptr`	`instantiateUnknownMemptr()` Creates a new instance of the same type that represents `unknown`.
`protected long`	`internalLength()` The actual size of the buffer (in bytes).
`protected 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.
`boolean`	`isCharacterData()` Indicate whether this object manages character data (as opposed to binary data).
`protected boolean`	`isLengthLimited()` Determines if the array of binary data stored in an instance of this class must be limited in length.
`private boolean`	`isLittleEndian()` Report if the effective byte ordering mode is little endian.
`protected static boolean`	`isLittleEndianPlatform(memptr.WorkArea workArea)` Report if the byte ordering mode of the platform is little endian.
`protected boolean`	`isUndoable()` Check if this instance is undoable.
`boolean`	`isUninitialized()` Reports if this instance represents an uninitialized buffer.
`boolean`	`isUnknown()` Reports if this instance represents `unknown`.
`protected long`	`lengthLimit()` Determines the maximum length of the array of binary data stored in an instance of this class.
`private memptr.WorkArea`	`locate()` Resolve the context-local `workArea` variable (if not yet resolved) and return it.
`protected byte`	`readByte(long pos)` Read the byte at the given location.
`protected 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.
`private void`	`recordAddressSpace(long ptr, long size)` When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
`protected void`	`replaceContents(byte[] value)` Replace the entire contents of the current buffer with the given array.
`memptr`	`setByteOrder(int order)` Defines the byte ordering scheme to use when reading/writing certain data types into the memory buffer.
`void`	`setByteOrder(NumberType order)` Defines the byte ordering scheme to use when reading/writing certain data types into the memory buffer.
`BinaryData`	`setLength(long len)` Sets the array to a given length.
`memptr`	`setPointerValue(long ptr)` Sets the binary data to point to a memory address.
`memptr`	`setPointerValue(NumberType ptr)` Sets the binary data to point to a memory address.
`void`	`setUnknown()` Sets the state of this instance's `unknown` flag to `true`.
`java.lang.String`	`toString()` Creates a string representation of the instance data, since a memptr represents a 'pointer' it doesn't have a real string representation.
`java.lang.String`	`toString(java.lang.String fmt)` Creates a string representation of the instance data using the given format string, since a memptr represents a 'pointer' it doesn't have a real string representation and the format string is meaningless.
`java.lang.String`	`toStringExport()` Creates a string representation of the instance data using the 'export' format.
`java.lang.String`	`toStringMessage()` Creates a string representation of the instance data in a form that is compatible with the `MESSAGE` language statement.
`protected long`	`visibleLength()` The the length of the buffer as reported to P4GL application.
`void`	`write(boolean overlay, byte[] data, int offset, boolean trim)` Write the given byte data into the data managed by this object, overwriting the data that are at the given location, if any.
`protected void`	`writeByte(byte val, long pos)` Write the byte into the given location.
`protected void`	`writeByteRange(byte[] data, long pos, long len, boolean endian)` Write the bytes at the given location.
`void`	`writeExternal(java.io.ObjectOutput out)` Replacement for the default object writing method.

Methods inherited from class com.goldencode.p2j.util.BinaryData
assign, assign, assign, defaultFormatString, genIndexError, genLimitedLengthError, genUninitializedError, getByte, getByte, getByteArray, getBytes, getBytes, getBytes, getBytes, getDouble, getDouble, getFloat, getFloat, getInt64, getInt64, getLong, getLong, getShort, getShort, getString, getString, getString, getString, getString, getString, getUnprocessedDouble, getUnsignedLong, getUnsignedLong, getUnsignedShort, getUnsignedShort, hashCode, length, length, lengthOf, reverseBytes, setByte, setByte, setByte, setByte, setBytes, setBytes, setBytes, setDouble, setDouble, setDouble, setDouble, setFloat, setFloat, setFloat, setFloat, setInt64, setInt64, setInt64, setInt64, setLength, setLength, setLong, setLong, setLong, setLong, setShort, setShort, setShort, setShort, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setUnsignedLong, setUnsignedLong, setUnsignedLong, setUnsignedLong, setUnsignedShort, setUnsignedShort, setUnsignedShort, setUnsignedShort

Methods inherited from class com.goldencode.p2j.util.BaseDataType
assign, assign, calcFormatLength, createProxy, createProxy, deepCopy, elementsOfType, equals, fallback, formatLength, fromTypeName, generateDefault, generateUnknown, getAssigner, getSize, getTypeName, incompatibleTypesOnConversion, initialize, initializeDefaultExtent, instantiateDefaultExtent, invalidInitializer, isAllKnown, isAllKnown, isAssignDirect, isIncompatibleTypesOnConversion, isProxy, isUnknownValue, maximum, minimum, notUnknownValue, sameType, val, variable

Methods inherited from class com.goldencode.p2j.util.LazyUndoable
changed, checkUndoable, checkUndoable, checkUndoable, getTransLevel, isGlobal, markUndoable, popBlock, rollback, setGlobal

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.goldencode.p2j.util.LargeObject
_getCodePage, binaryEquals, getFieldReference, lengthOf, readBytes, readChars, setFieldReference, write

- Field Detail
  - LOG
```
private static final CentralLogger LOG
```
    Logger
  - NO_BYTE_ORDER
```
public static final int NO_BYTE_ORDER
```
    No byte order has been explicitly requested. This is the default state of a memptr.
    
    See Also:
    
    Constant Field Values
  - HOST_BYTE_ORDER
```
public static final int HOST_BYTE_ORDER
```
    Operations should use the native byte order on the current machine.
    
    See Also:
    
    Constant Field Values
  - BIG_ENDIAN
```
public static final int BIG_ENDIAN
```
    Operations should use big endian byte order.
    
    See Also:
    
    Constant Field Values
  - LITTLE_ENDIAN
```
public static final int LITTLE_ENDIAN
```
    Operations should use little endian byte order.
    
    See Also:
    
    Constant Field Values
  - LOWER_BOUND
```
public static final int LOWER_BOUND
```
    Smallest value accepted in SET-SIZE() without generating an error.
    
    See Also:
    
    Constant Field Values
  - UPPER_BOUND
```
public static final int UPPER_BOUND
```
    Largest value accepted in SET-SIZE() without generating an error.
    
    See Also:
    
    Constant Field Values
  - ctxt
```
private static final ContextLocal<memptr.WorkArea> ctxt
```
    Stores context local instances of the remote memory manager proxy.
  - workArea
```
private memptr.WorkArea workArea
```
    The working area where this instance was created. Caches costly access to context local. Lazy-initialized in locate() as it can't be initialized by the c'tor - when transported via the network, the Reader thread will not be able to access the context.
  - pointer
```
private memptr.memptrPointer pointer
```
    Pointer structure shared between parameters and arguments.
  - parameter
```
private boolean parameter
```
    Flag indicating this is a parameter.
  - srcWasUnknown
```
private boolean srcWasUnknown
```
    Flag indicating if the source argument for this parameter was unknown.
- Constructor Detail
  - memptr
```
public memptr()
```
    Default constructor, creates an instance that represents an uninitialized byte array (a null array).
  - memptr
```
public memptr(BaseDataType value)
```
    This is a special c'tor which should be used only when converting the value returned by a function or method with polymorphic return type into the expected type (i.e. DYNAMIC-FUNCTION()). In such cases, the 4GL does some automatic type conversion (see BinaryData.assign(BaseDataType)).
    
    Parameters:
    
    value - The value to be used for this instance.
  - memptr
```
public memptr(memptr value)
```
    Constructs an instance after copying the parameter's data into the internal representation of this class.
    If the parameter is unknown, this instance will be set to unknown.
    
    Parameters:
    
    value - The value to be used for this instance.
  - memptr
```
public memptr(byte[] value)
```
    Constructs an instance after copying the parameter's data into the internal representation of this class.
    If the parameter is null, the instance will be unknown.
    
    Parameters:
    
    value - The value to be used for this instance.
- Method Detail
  - instantiateUnknownMemptr
```
public static memptr instantiateUnknownMemptr()
```
    Creates a new instance of the same type that represents unknown.
    
    Returns:
    
    An instance that represents unknown.
  - getType
```
public BaseDataType.Type getType()
```
    Get the type
    
    Specified by:
    
    getType in class BaseDataType
    
    Returns:
    
    type
  - compareTo
```
public 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. This is the implementation of the 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.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable
    
    Overrides:
    
    compareTo in class BinaryData
    
    Parameters:
    
    obj - The instance to compare against.
    
    Returns:
    
    -1, 0 or 1 depending on if this instance is less than, equal to or greater (respectively) than the specified instance obj.
  - duplicate
```
public memptr duplicate()
```
    Does the same as standard clone() method but returns an instance of BaseDataType and doesn't throw the CloneNotSupportedException.
    
    Specified by:
    
    duplicate in class BaseDataType
    
    Returns:
    
    A clone of this instance.
  - instantiateUnknown
```
public BaseDataType instantiateUnknown()
```
    Creates a new instance of the same type that is unknown.
    
    Specified by:
    
    instantiateUnknown in class BaseDataType
    
    Returns:
    
    An instance that represents unknown.
  - instantiateDefault
```
public BaseDataType instantiateDefault()
```
    Creates a new instance of the same type that represents the default initialized value.
    
    Specified by:
    
    instantiateDefault in class BaseDataType
    
    Returns:
    
    An instance that represents the default value.
  - isUnknown
```
public boolean isUnknown()
```
    Reports if this instance represents unknown.
    
    Specified by:
    
    isUnknown in interface LargeObject
    
    Overrides:
    
    isUnknown in class BinaryData
    
    Returns:
    
    true if this instance is set to the unknown.
  - setUnknown
```
public void setUnknown()
```
    Sets the state of this instance's unknown flag to true.
    Warning: the data stored in this instance WILL BE deallocated after calling this method.
    
    Overrides:
    
    setUnknown in class BinaryData
  - getPointerValue
```
public int64 getPointerValue()
```
    Method implementation of the GET-POINTER-VALUE 4GL built-in function which returns a 64-bit integer value representing the pointer used by the instance. This is a real memory address for the first byte of the buffer that has been allocated. Of course, this is not only very dangerous, but it is also not portable. Yet, this is how the 4GL does it.
    
    Returns:
    
    The 64-bit integer value representing the location in memory of the instance's buffer. If unknown, the pointer will be unknown. If uninitialized, this will return 0.
  - setPointerValue
```
public memptr setPointerValue(NumberType ptr)
```
    Sets the binary data to point to a memory address. The current size is left unchanged and any current buffer is NOT deallocated. This is just how the 4GL implements it.
    If the instance is unknown, then this call silently fails. It does NOT change the pointer value, the instance will still be unknown. This is how the 4GL does it.
    
    Parameters:
    
    ptr - The 64-bit value representing the pointer to the memory address. This may be any value (negative, 0 or a positive number). Since the 4GL has no unsigned 64-bit data type, it is necessary negative numbers be supported since memory addresses are typically unsigned values. Even though most systems do not allocate valid memory at address 0 (so that 0 can be used as a well known invalid memory address), the 4GL does allow 0 to be used (perhaps it is needed on some systems). If this value is unknown, the method will silently return with no change to the pointer value. This is how the 4GL does it.
    
    Returns:
    
    The current instance.
  - setPointerValue
```
public memptr setPointerValue(long ptr)
```
    Sets the binary data to point to a memory address. The current size is left unchanged and any current buffer is NOT deallocated. This is just how the 4GL implements it.
    If the instance is unknown, then this call silently fails. It does NOT change the pointer value, the instance will still be unknown. This is how the 4GL does it.
    
    Parameters:
    
    ptr - The 64-bit value representing the pointer to the memory address. This may be any value (negative, 0 or a positive number). Since the 4GL has no unsigned 64-bit data type, it is necessary negative numbers be supported since memory addresses are typically unsigned values. Even though most systems do not allocate valid memory at address 0 (so that 0 can be used as a well known invalid memory address), the 4GL does allow 0 to be used (perhaps it is needed on some systems).
    
    Returns:
    
    The current instance.
  - getByteOrder
```
public integer getByteOrder()
```
    Reports the byte order mode configured in this instance. By default (and contrary to the Progress documentation), this is set to 0. This will remain 0 until setByteOrder(int) is called. Since setByteOrder can only ever be called with 3 values, those are the only possible values that can be returned from here. The only exception to this is that when the instance is unknown, then unknown will be returned, no matter what has been previously configured.
    The following are the possible return values:
```
 4GL Constant        Java Constant       Value
 ------------------  ------------------  ---------
 n/a                 NO_BYTE_ORDER       0
 HOST-BYTE-ORDER     HOST_BYTE_ORDER     1
 BIG-ENDIAN          BIG_ENDIAN          2
 LITTLE-ENDIAN       LITTLE_ENDIAN       3
 
```
    The fact that Progress returns 0 by default allows one can tell when this value has been explicitly configured, since it is never possible to set it back to 0 via setByteOrder. When set to 0 or to HOST_BYTE_ORDER, the result is the same. The native byte ordering of the current platform will be used.
    This value is interesting in another way: it does not change when an instance is de-allocated, re-allocated, set to unknown or assigned. The configuration value stays with the instance across all these events and thus it is not really associated with a specific memory buffer, but rather with the variable instance itself. Don't be fooled by the fact that this returns unknown when the instance is unknown. The byte order is still properly set (or defaulted) and when the instance is no longer unknown, that value will be returned.
    Returns:
    
    The byte-order setting of the instance.
  - setByteOrder
```
public memptr setByteOrder(int order)
```
    Defines the byte ordering scheme to use when reading/writing certain data types into the memory buffer. The following data types change behavior depending on byte ordering:
```
 DOUBLE
 FLOAT
 INT64
 LONG
 SHORT
 UNSIGNED-LONG
 UNSIGNED-SHORT
 
```
    For each of the above listed data types, both the get and the set will honor the byte ordering. This means that the only data types that do NOT honor byte ordering are BYTE (a single byte being read or written), BYTES (a sequence of bytes) and STRING (a sequence of characters).
    Any valid value set through this method is retained for the lifetime of the instance, even when it is set to unknown and/or de-allocated and then re-allocated. Interestingly, the value does not get copied to the target instance during assignment, so it is instance-specific. This is all compatible with how the 4GL works.
    The following are the only possible byte order modes that can be specified:
```
 4GL Constant        Java Constant       Value
 ------------------  ------------------  ---------
 HOST-BYTE-ORDER     HOST_BYTE_ORDER     1
 BIG-ENDIAN          BIG_ENDIAN          2
 LITTLE-ENDIAN       LITTLE_ENDIAN       3
 
```
    This method returns without any changes if the instance is unknown.
    Parameters:
    
    order - The new byte order mode.
    
    Returns:
    
    The current instance is returned.
  - setByteOrder
```
public void setByteOrder(NumberType order)
```
    Defines the byte ordering scheme to use when reading/writing certain data types into the memory buffer. The following data types change behavior depending on byte ordering:
```
 DOUBLE
 FLOAT
 INT64
 LONG
 SHORT
 UNSIGNED-LONG
 UNSIGNED-SHORT
 
```
    For each of the above listed data types, both the get and the set will honor the byte ordering. This means that the only data types that do NOT honor byte ordering are BYTE (a single byte being read or written), BYTES (a sequence of bytes) and STRING (a sequence of characters).
    Any valid value set through this method is retained for the lifetime of the instance, even when it is set to unknown and/or de-allocated and then re-allocated. Interestingly, the value does not get copied to the target instance during assignment, so it is instance-specific. This is all compatible with how the 4GL works.
    The following are the only possible byte order modes that can be specified:
```
 4GL Constant        Java Constant       Value
 ------------------  ------------------  ---------
 HOST-BYTE-ORDER     HOST_BYTE_ORDER     1
 BIG-ENDIAN          BIG_ENDIAN          2
 LITTLE-ENDIAN       LITTLE_ENDIAN       3
 
```
    If the parameter is unknown, then the instance itself will be set to unknown and the byte order will NOT be changed. Subsequent allocation of a new buffer will retain the same byte order setting. This is how the 4GL does it.
    This method returns without any changes if the instance is unknown.
    Parameters:
    
    order - The new byte order mode.
  - setLength
```
public BinaryData setLength(long len)
                     throws ErrorConditionException
```
    Sets the array to a given length. If set to 0, this de-allocates any currently allocated array (if no array is allocated, this does nothing). If set to a positive number, this will allocate a new array if no array is allocated, otherwise this method will do nothing.
    This method will try to emulate the allocation based on the current (-ly configured) OS. See EnvironmentOps.isUnderWindowsFamily():
    - On WIN32 platform will only accept positive values when allocating a new native memory buffer. If the buffer is already allocated and a negative value is passed then this is a no-op;
    - On UNIX will accept and apparently allocate abs(len) bytes.
    On 32-bit Linux platforms, the 4GL "real lower bound" is -7 and not 0 as one would expect. Since this is an obscure and platform-specific nonsense behavior which is unlikely to be needed in a real application, it is not honored at this time (which leaves this code simpler).
    Specified by:
    
    setLength in class BinaryData
    
    Parameters:
    
    len - New length of the array.
    
    Returns:
    
    The current instance.
    
    Throws:
    
    ErrorConditionException
  - isUninitialized
```
public boolean isUninitialized()
```
    Reports if this instance represents an uninitialized buffer. Being uninitialized is not the same as being of zero length. Rather it means that the buffer was never allocated. Being unknown is also different from being uninitialized.
    
    Specified by:
    
    isUninitialized in class BinaryData
    
    Returns:
    
    true if this instance is uninitialized.
  - toString
```
public java.lang.String toString()
```
    Creates a string representation of the instance data, since a memptr represents a 'pointer' it doesn't have a real string representation. If the instance represents unknown, a '?' will be returned, otherwise the empty string will be returned.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    The empty string or '?' if unknown.
  - toString
```
public java.lang.String toString(java.lang.String fmt)
```
    Creates a string representation of the instance data using the given format string, since a memptr represents a 'pointer' it doesn't have a real string representation and the format string is meaningless. If the instance represents unknown, a '?' will be returned, otherwise the empty string will be returned.
    
    Specified by:
    
    toString in class BaseDataType
    
    Parameters:
    
    fmt - The format string to use.
    
    Returns:
    
    The empty string or '?' if unknown.
  - toStringMessage
```
public java.lang.String toStringMessage()
```
    Creates a string representation of the instance data in a form that is compatible with the MESSAGE language statement. If the instance represents unknown, a '?' will be returned.
    This is equivalent to toString().
    
    Specified by:
    
    toStringMessage in interface LargeObject
    
    Specified by:
    
    toStringMessage in class BaseDataType
    
    Returns:
    
    The empty string or '?' if unknown.
  - toStringExport
```
public java.lang.String toStringExport()
```
    Creates a string representation of the instance data using the 'export' format. If the instance represents unknown, a '?' will be returned. Any other data is directly output into the string and no formatting or conversion of binary data is done.
    
    Specified by:
    
    toStringExport in class BaseDataType
    
    Returns:
    
    The binary data in the instance as a string.
  - readExternal
```
public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
```
    Replacement for the default object reading method. The latest state is read from the input source. The parent's state is read first.
    
    Specified by:
    
    readExternal in interface java.io.Externalizable
    
    Overrides:
    
    readExternal in class BinaryData
    
    Parameters:
    
    in - The input source from which fields will be restored.
    
    Throws:
    
    java.io.IOException - In case of I/O errors.
    
    java.lang.ClassNotFoundException - If payload can't be instantiated.
  - writeExternal
```
public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
```
    Replacement for the default object writing method. The latest state is written to the output destination. The parent's state is written first.
    
    Specified by:
    
    writeExternal in interface java.io.Externalizable
    
    Overrides:
    
    writeExternal in class BinaryData
    
    Parameters:
    
    out - The output destination to which fields will be saved.
    
    Throws:
    
    java.io.IOException - In case of I/O errors.
  - write
```
public void write(boolean overlay,
                  byte[] data,
                  int offset,
                  boolean trim)
```
    Write the given byte data into the data managed by this object, overwriting the data that are at the given location, if any.
    This implementation:
    - ignores the trim option (i.e., any existing bytes beyond the end of the write are left in place, regardless of the value of trim);
    - raises an error if the write goes past the end of the existing value.
    Specified by:
    
    write in interface LargeObject
    
    Parameters:
    
    overlay - Flag indicating if the OVERLAY option is used.
    
    data - Data to be assigned to this object.
    
    offset - Offset position (in characters) in the target large object.
    
    trim - true to truncate any remaining data in the target large object; false to leave remaining data alone. Ignored.
  - isCharacterData
```
public boolean isCharacterData()
```
    Indicate whether this object manages character data (as opposed to binary data).
    
    Specified by:
    
    isCharacterData in interface LargeObject
    
    Returns:
    
    false.
  - asByteArray
```
public byte[] asByteArray(long pos,
                          long len)
```
    Return the entire contents of the current buffer as an array. This may be a copy of the data, depending on the subclass' implementation. DO NOT MODIFY the data that is returned, since it is undefined as to whether the changes will or will not be reflected in the actual storage.
    
    Specified by:
    
    asByteArray in interface LargeObject
    
    Parameters:
    
    pos - Starting offset position.
    
    len - Length of range to return.
    
    Returns:
    
    The contents of the instance (possibly a copy). If the instance is uninitialized the returned value will be a 0 length array. If the instance is unknown or has an undefined size, then null will be returned.
  - assign
```
public void assign(BinaryData data)
```
    Sets the state (data and unknown value) of this instance based on the state of the passed instance.
    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.
    
    Overrides:
    
    assign in class BinaryData
    
    Parameters:
    
    data - The instance from which to copy state.
  - isLittleEndianPlatform
```
protected static boolean isLittleEndianPlatform(memptr.WorkArea workArea)
```
    Report if the byte ordering mode of the platform is little endian.
    
    Parameters:
    
    workArea - The optional context to obtain endian information. If not provided, the current context is used.
    
    Returns:
    
    true if the platform natively uses little endian byte ordering and false if it uses big endian.
  - compiledWordSize
```
protected static int compiledWordSize()
```
    Returns the word size (the size of a pointer) for the native code as compiled. This may be different than the word size of the operating system in the case where 32-bit code is run on a 64-bit system.
    
    Returns:
    
    This value will be either 32 or 64 depending on how the native library was compiled. If there was an error in inspecting this value, -1 will be returned.
  - asParameter
```
protected void asParameter(memptr src)
```
    Setup this instance to act as a parameter; this shares the pointer with the source memptr.
    
    Parameters:
    
    src - The source argument.
  - clearUnknown
```
protected void clearUnknown()
```
    Sets the state of this instance's unknown flag to false.
    
    Overrides:
    
    clearUnknown in class BinaryData
  - deallocate
```
protected void deallocate()
```
    Release any resources associated with the instance.
    
    Specified by:
    
    deallocate in class BinaryData
  - isLengthLimited
```
protected boolean isLengthLimited()
```
    Determines if the array of binary data stored in an instance of this class must be limited in length.
    
    Specified by:
    
    isLengthLimited in class BinaryData
    
    Returns:
    
    true if the length must be limited.
  - lengthLimit
```
protected long lengthLimit()
```
    Determines the maximum length of the array of binary data stored in an instance of this class.
    
    Specified by:
    
    lengthLimit in class BinaryData
    
    Returns:
    
    Always 0 (this class has no pre-determined limit on size).
  - isAutoExtend
```
protected 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. Such extensions will pad with null bytes.
    
    Specified by:
    
    isAutoExtend in class BinaryData
    
    Returns:
    
    true if the length must automatically extended.
  - extendBytes
```
protected void extendBytes(long len)
```
    Helper to create a new byte array with the same contents as the given byte array and the specified length. If the given target length is smaller than the source array length, the output array is truncated to the specified size. If the target length is larger than the source array length, the output array is extended to the given size and any additional bytes are initialized to '\0'.
    This is safe to use on 0 length arrays.
    
    Specified by:
    
    extendBytes in class BinaryData
    
    Parameters:
    
    len - The output array length.
  - replaceContents
```
protected void replaceContents(byte[] value)
```
    Replace the entire contents of the current buffer with the given array.
    The BinaryData.unknown flag is also cleared, only if value is not null and if the length is greater than 0.
    
    Specified by:
    
    replaceContents in class BinaryData
    
    Parameters:
    
    value - The new contents.
  - asByteArray
```
protected byte[] asByteArray()
```
    Return the entire contents of the current buffer as an array. This may be a copy of the data, depending on the subclass' implementation. DO NOT MODIFY the data that is returned, since it is undefined as to whether the changes will or will not be reflected in the actual storage.
    
    Specified by:
    
    asByteArray in class BinaryData
    
    Returns:
    
    The contents of the instance (possibly a copy). If the instance is uninitialized the returned value will be a 0 length array. If the instance is unknown or has an undefined size, then null will be returned.
  - internalLength
```
protected long internalLength()
```
    The actual size of the buffer (in bytes).
    
    Specified by:
    
    internalLength in class BinaryData
    
    Returns:
    
    The length or 0 if uninitialized.
  - visibleLength
```
protected long visibleLength()
```
    The the length of the buffer as reported to P4GL application.
    
    Specified by:
    
    visibleLength in class BinaryData
    
    Returns:
    
    The length or 0 if uninitialized.
  - findNextNull
```
protected long findNextNull(long pos)
```
    Returns the next index position into the array which is the null byte, starting at a given index position.
    
    Specified by:
    
    findNextNull in class BinaryData
    
    Parameters:
    
    pos - The 0-based index into the array at which to start searching.
    
    Returns:
    
    The next index into the array which is the null byte or the length of the array if no null byte exists.
  - readByte
```
protected byte readByte(long pos)
```
    Read the byte at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    readByte in class BinaryData
    
    Parameters:
    
    pos - The 0-based index position at which to read the byte.
    
    Returns:
    
    The byte at that location.
  - writeByte
```
protected void writeByte(byte val,
                         long pos)
```
    Write the byte into the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    writeByte in class BinaryData
    
    Parameters:
    
    val - The byte to write.
    
    pos - The 0-based index position at which to read the byte.
  - readByteRange
```
protected byte[] readByteRange(long pos,
                               long len,
                               boolean endian)
```
    Read the bytes at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    readByteRange in class BinaryData
    
    Parameters:
    
    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.
    
    Returns:
    
    The byte range at that location.
  - writeByteRange
```
protected void writeByteRange(byte[] data,
                              long pos,
                              long len,
                              boolean endian)
```
    Write the bytes at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    writeByteRange in class BinaryData
    
    Parameters:
    
    data - The bytes to write.
    
    pos - The 0-based index position at which to start writing the bytes.
    
    len - How many bytes should be written. -1 means write everything to the end of the array. This is the implementation of the BinaryData.writeByteRange(byte[], long, long, boolean) method. The len parameter was added to fix bug in the raw.writeByteRange(byte[], long, long, boolean). For the memptr is is intentionally ignored.
    
    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.
  - isUndoable
```
protected boolean isUndoable()
```
    Check if this instance is undoable. For memptr case, these instances can never be undoable.
    
    Overrides:
    
    isUndoable in class LazyUndoable
    
    Returns:
    
    Always false
  - copyByteRange
```
protected void copyByteRange(memptr data,
                             long pos,
                             long len)
```
    Copy the specified number of bytes from the source instance into the current instance at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    This method is implemented completely on the client side to avoid multiple (costly) round trips.
    
    Parameters:
    
    data - The source of data to copy.
    
    pos - The 0-based index position in the destination at which to write the bytes.
    
    len - The number of bytes to write.
  - getMemoryManager
```
static LowLevelBuffer getMemoryManager()
```
    Returns the low-level memory manager.
    
    Returns:
    
    see above.
  - isLittleEndian
```
private boolean isLittleEndian()
```
    Report if the effective byte ordering mode is little endian.
    
    Returns:
    
    true if the instance should use little endian byte ordering and false if the instance should use big endian.
  - copyPointer
```
private void copyPointer(memptr m)
```
    Copy the pointer details from the specified instance.
    
    Parameters:
    
    m - The memptr instance which needs to be duplicated.
  - locate
```
private memptr.WorkArea locate()
```
    Resolve the context-local workArea variable (if not yet resolved) and return it.
    
    Returns:
    
    The workArea.
  - checkAddressSpace
```
private void checkAddressSpace(long ptr)
```
    When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
    This method raises an ERROR condition if the context tries to set a pointer to an address which was not allocated in this context.
    
    Parameters:
    
    ptr - The memory address.
  - recordAddressSpace
```
private void recordAddressSpace(long ptr,
                                long size)
```
    When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
    This records the allocated address space in this context.
    
    Parameters:
    
    ptr - The memory address.
    
    size - The allocated size.
  - clearAddressSpace
```
private void clearAddressSpace(long ptr,
                               long size)
```
    When memptr is on server-side, allocated address spaces are recorded for each context, to prohibit cross-context usage of pointer addresses.
    This clears the allocated address space in this context.
    
    Parameters:
    
    ptr - The memory address.
    
    size - The allocated size.

Class memptr

Nested Class Summary

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BinaryData

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BaseDataType

Field Summary

Fields inherited from class com.goldencode.p2j.util.BinaryData

Constructor Summary

Method Summary

Methods inherited from class com.goldencode.p2j.util.BinaryData

Methods inherited from class com.goldencode.p2j.util.BaseDataType

Methods inherited from class com.goldencode.p2j.util.LazyUndoable

Methods inherited from class java.lang.Object

Methods inherited from interface com.goldencode.p2j.util.LargeObject

Field Detail

LOG

NO_BYTE_ORDER

HOST_BYTE_ORDER

BIG_ENDIAN

LITTLE_ENDIAN

LOWER_BOUND

UPPER_BOUND

ctxt

workArea

pointer

parameter

srcWasUnknown

Constructor Detail

memptr

memptr

memptr

memptr

Method Detail

instantiateUnknownMemptr

getType

compareTo

duplicate

instantiateUnknown

instantiateDefault

isUnknown

setUnknown

getPointerValue

setPointerValue

setPointerValue

getByteOrder

setByteOrder

setByteOrder

setLength

isUninitialized

toString

toString

toStringMessage

toStringExport

readExternal

writeExternal

write

isCharacterData

asByteArray

assign

isLittleEndianPlatform

compiledWordSize

asParameter

clearUnknown

deallocate

isLengthLimited

lengthLimit

isAutoExtend

extendBytes

replaceContents

asByteArray

internalLength

visibleLength

findNextNull

readByte

writeByte

readByteRange

writeByteRange

isUndoable

copyByteRange

getMemoryManager

isLittleEndian