eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ExternalLong':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ExternalLong


Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ExternalBytes
                  |
                  +--ExternalLong

Package:
stx:libbasic2
Category:
System-Support-External Memory
Version:
rev: 1.21 date: 2023/05/28 10:09:20
user: cg
file: ExternalLong.st directory: libbasic2
module: stx stc-classLibrary: libbasic2

Description:


mostly added for odbc, which uses instances of me as container in which values
(pointers) are returned. 
The name is very misleading: it should be ExternalPointer,
because on machines where sizeof(long) != sizeof(void *), that makes a difference.
However, over time, others started to use this class, 
and renaming it would break some code.

copyright

COPYRIGHT (c) 1998 by eXept Software AG All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

Class protocol:

instance creation
o  new
allocate some memory usable for data;
the memory is controlled by the garbage collector.
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).

Usage example(s):

     ExternalLong new

o  protectedNew
allocate some memory usable for data;
the memory is not controlled by the garbage collector.
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).

Use this, if you have to pass a block of bytes to some
external destination (such as a C function) which does not copy the
data, but instead keeps a reference to it. For example, many functions
which expect strings simply keep a ref to the passed string - for those,
an ST/X string-pointer is not the right thing to pass, since ST/X objects
may change their address.

DANGER ALERT: the memory is NOT automatically freed until it is either
MANUALLY freed (see #free) or the returned externalBytes object
is unprotected or the classes releaseAllMemory method is called.

Usage example(s):

     |m|

     m := ExternalLong protectedNew.
     m free.
     m inspect.

o  unprotectedNew
allocate some memory usable for data;
the memory is under the control of the garbage collector.
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).

DANGER ALERT: the memory block as allocated will be automatically freed
as soon as the reference to the returned externalBytes object
is gone (by the next garbage collect).
If the memory has been passed to a C-function which
remembers this pointer, bad things may happen ....


Instance protocol:

accessing
o  asBoolean

o  asExternalBytes
(ExternalLong new value:10) asExternalBytes
(ExternalLong new value:0) asExternalBytes

o  asInteger
warning: retrieves a signed integer with the size of the native machine's
pointer (i.e. either 32 or 64bit)

Usage example(s):

     ExternalLong new value:10
     (ExternalLong new value:16rFFFFFF) asInteger

o  asNullStatus
cg: whoever added this here should move it to the sql package

o  asPointer
fetch my cell's pointer value
(use this if you passed me to a C function as out parameter, to fetch the returned value)

Usage example(s):

     (ExternalLong new value:10) asPointer

o  asUnsignedInteger
warning: retrieves an integer with the size of the native machine's
pointer (i.e. either 32 or 64bit)

Usage example(s):

     (ExternalLong new value:10) asUnsignedInteger

o  boolean: bool

o  value
(ExternalLong new value:10) value

o  value: anInteger
self doubleWordAt:1 put:anInteger

printing & storing
o  printOn: aStream
(comment from inherited method)
append a user readable representation of the receiver to aStream.
The text appended is not meant to be read back for reconstruction of
the receiver. Also, this method limits the size of generated string.



ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 26 May 2024 12:46:26 GMT