User Tools

Site Tools


astring_atomic_string_.htm
Navigation:  Language Reference > 3 - Variable Declarations > Data Types >====== ASTRING (atomic string) ====== Previous pageReturn to chapter overviewNext page
label ASTRING([stringtoken]) [,DIM()] [,NAME()] [,EXTERNAL] [,DLL] [,STATIC] [,THREAD]
[,AUTO] [,PRIVATE] [,PROTECTED]

blk2blue.jpg

ASTRING A reference to a character string.
stringtoken The initial string token of the ASTRING.
DIM Dimension the variable as an array.
OVER The ASTRING reference may share a memory location with another variable.
NAME Specify an alternate, “external” name for the field.
EXTERNAL Specify the variable is defined, and its memory is allocated, in an external library.
DLL Specify the variable is defined in a .DLL. This is required in addition to the EXTERNAL attribute.
STATIC Specifies the memory for the ASTRING reference variable is permanently allocated.
THREAD Specify memory for the variable is allocated once for each execution thread. Also implicitly adds the STATIC attribute on Procedure Local data.
AUTO Specify the variable has no initial string token.
PRIVATE Specify the variable is not visible outside the module containing the CLASS methods. Valid only in a CLASS.
PROTECTED Specify the variable is not visible outside base CLASS and derived CLASS methods. Valid only in a CLASS.

ASTRING (similar to a Win32 ATOM) declares a reference to a variable length string (string token) with a maximum size of 64k. Although the size of the string token may be up to a maximum of 64k, it is recommended for use on smaller strings. The storage space for an ASTRING is allocated dynamically as needed for the lifetime of the procedure in which it is created. However the allocated storage is never deallocated; it is instead reused for subsequent use of the same text values.

ASTRINGs are useful when a lot of the same text is being stored and compared. Each time a new ASTRING is created, an entry is created in a memory table. When an ASTRING is assigned a value that already exists in the table, the ASTRING simply points to the existing ASTRING. This saves memory and makes string comparison very fast.

ASTRINGs are not supported by any of the file drivers.

ASTRINGs may be passed as parameters to procedures by value or by reference. They may also be passed as an untyped value or untyped variable parameters. An ASTRING can be returned from a procedure only as a value.

Proper matching of ASTRING types when used in expressions, procedure parameters,and in queue processing is essential.

Regarding expressions, If one operand of the expression is an ASTRING, the other must also be an ASTRING. If that is not possible, the use of STRING and CSTRING types in expressions is faster and needs far less resources. Every string used as an initial value of ASTRING variables is allocated twice in memory as a minimum.

If the parameter prototype of procedure is declared as ASTRING, the actual parameter receiving the passed value should also be defined as an ASTRING type. Otherwise, the value of the actual parameter is added to the ASTRING's hash table.

see also:

TIE UNTIE TIED

PUSHASTRINGS

POPASTRINGS

Example:

In the CLASS definition:

Match PROCEDURE(ASTRING DocumentToSearch, ASTRING SearchExp),BYTE

PROCEDURE definition:

FuzzyClass.Match PROCEDURE(ASTRING Doc, ASTRING Query)

If a QUEUE has ASTRING fields defined, and the program wants to perform a GET by KEY from this queue, the values of any ASTRING fields used in the key must also be ASTRINGs. Otherwise, the value of the actual parameter is added to the ASTRING's hash table.

Example:

DbNameQueue  QUEUE,TYPE

FileName      ASTRING

FieldName     ASTRING

Ptr           USHORT

            END

NameQueue          &DbNameQueue,PROTECTED

SELF.NameQueue.FileName = SELF.TriggerQueue.FileName !SELF.TriggerQueue.FileName is ASTRING

GET(SELF.NameQueue,SELF.NameQueue.Filename)

More example prototypes:

   PROC1(ASTRING a)

   PROC2(*ASTRING a)

   PROC3(? a)

   PROC4(*? a)

   PROC5(),ASTRING

!Additional Example:

  PROGRAM

   MAP

   END

FLAG LONG

AS1  ASTRING,OVER(FLAG)

AS2  ASTRING

CODE

AS1 = 'SoftVelocity'   ! storage is allocated for the string 'SoftVelocity'

AS2 = 'SoftVelocity'   ! storage in not allocated again, instead AS1 and

                       ! AS2 share the same reference value.

AS2 = 'Hello'          ! new storage allocated for the new text string

                       ! Hello

AS2 = 'SoftVelocity'   ! No new storage is allocated, the reference for

                       ! AS1 now equals AS2 again

 IF FLAG = 0

  MESSAGE('AS1 is NULL')

 ELSE

  MESSAGE('AS1 = ' & AS1)

 END

astring_atomic_string_.htm.txt · Last modified: 2021/04/15 15:56 (external edit)