ASTRING (atomic string)

Top  Previous  Next

 

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.

 

see also: TIE UNTIE TIED

 

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