|Navigation: Language Reference > 3 - Variable Declarations > Data Types >====== ASTRING (atomic string) ======|
|label||ASTRING([stringtoken])||[,DIM()] [,NAME()] [,EXTERNAL] [,DLL] [,STATIC] [,THREAD]|
|[,AUTO] [,PRIVATE] [,PROTECTED]|
|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.
In the CLASS definition:
Match PROCEDURE(ASTRING DocumentToSearch, ASTRING SearchExp),BYTE
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.
SELF.NameQueue.FileName = SELF.TriggerQueue.FileName !SELF.TriggerQueue.FileName is ASTRING
More example prototypes:
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
AS2 = 'SoftVelocity' ! No new storage is allocated, the reference for
! AS1 now equals AS2 again
IF FLAG = 0
MESSAGE('AS1 is NULL')
MESSAGE('AS1 = ' & AS1)