ConstantClass Overview

Top  Previous  Next

The ConstantClass provides an easy, flexible, and efficient way to "loop through" constant data. That is, the ConstantClass parses structures like the following so you can access each (unlabeled) data item discretely:

Errors  GROUP,STATIC

Items    USHORT(40)                      !item count

        USHORT(Msg:RebuildKey)          !begin item 1

        BYTE(Level:Notify)

        PSTRING('Invalid Key')

        USHORT(Msg:RebuildFailed)       !begin item 2

        BYTE(Level:Fatal)

        PSTRING('Key was not built')

        !38 more USHORT,BYTE,PSTRING combinations

       END

ConstantClass Concepts

The ConstantClass parses and loads constant data such as error messages or translation text from the GROUP structure that declares the data into other data structures or memory variables (one item at a time). It can also write all the constant data into a QUEUE or a FILE.

The ConstantClass intelligently handles irregular data--you can declare the constant text data with a series of strings of varying lengths so that no space is wasted. The ConstantClass also handles a variety of numeric datatypes including BYTE, SHORT, USHORT, and LONG.

The ConstantClass provides several ways to stop processing the constant data, including a simple item count, a text match, and a read-to-the-end option.

A single ConstantClass object can process multiple GROUP structures with the same (or incremental) layouts.

Declaring the Data

To use the ConstantClass, you must declare the constant data within a GROUP structure. The GROUP structure may declare a single sequence using any combination of the permitted datatypes, or a series of such sequences (the GROUP repeats the combination of datatypes as many times as needed). The ConstantClass permits CSTRING, PSTRING, BYTE, SHORT, USHORT, and LONG datatypes. The GROUP structure may contain an initial BYTE or USHORT that specifies how many times a sequence of datatypes is repeated. For example:

Errors  GROUP,STATIC

Items     BYTE(2)                    !optional item count

         USHORT(Msg:RebuildKey)     !begin first item

         BYTE(Level:Notify)

         PSTRING('Invalid Key')     !end first item

         USHORT(Msg:RebuildFailed)  !begin second item

         BYTE(Level:Fatal)

         PSTRING('Key not built')   !end second item

       END

Here is another example of a structure the ConstantClass can handle:

Translation  GROUP,STATIC                       !no item count

             PSTRING('&Across')                !default text

             PSTRING('')                       !translation text

             PSTRING('Align all window Icons') !default text

             PSTRING('')                       !translation text

             PSTRING('Arrange Icons')          !default text

             PSTRING('')                       !translation text

           END

If the GROUP is declared within a procedure it must have the STATIC attribute. See the Language Reference for more information.

Describing the Data

The ConstantClass uses two methods to describe or understand the structure of the constant data it processes: the Init method and the AddItem method. The Init method (termination parameter) indicates whether or not the GROUP structure declares an item count as well as the datatype of the item count (see Init). The AddItem method identifies each repeating component of the GROUP structure as well as the target variable that receives the contents of the repeating component (see AddItem).

ConstantClass Relationship to Other Application Builder Classes

The TranslatorClass, ErrorClass, ToolbarClass, and PrintPreview classes all use the ConstantClass. These classes automatically instantiate the ConstantClass as needed.

ConstantClass ABC Template Implementation

All ABC Library references to the ConstantClass are encapsulated with ABC Library methods--the ABC Templates do not directly reference the ConstantClass.

ConstantClass Source Files

The ConstantClass source code is installed by default to the Clarion \LIBSRC. The specific ConstantClass source code and their respective components are contained in:

 

ABUTIL.INC

ConstantClass declarations

 

ABUTIL.CLW

ConstantClass method definitions

ConstantClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a ConstantClass object. The example loads translation pairs from a constant GROUP into two CSTRINGs, which are then passed as parameters to another TranslatorClass method. Note that the target CSTRINGs could just as easily be fields in a QUEUE or FILE buffer.

 INCLUDE('ABUTIL.INC')            !declare ConstantClass, TranslatorClass

Spanish   GROUP                    !declare constant data

Items     BYTE(50)                 !item count

      PSTRING('One')              !begin first item

      PSTRING('Uno')

      PSTRING('Two')              !begin second item

      PSTRING('Dos')

      !48 more PSTRING pairs

     END

 

LangQ  QUEUE

Text     CSTRING(50)

Repl     CSTRING(50)

Done     BYTE

      END

 

Const  ConstantClass                  !declare & instantiate Const object

Text     CSTRING(255),AUTO            !a variable to receive a constant value

Repl     CSTRING(255),AUTO            !a variable to receive a constant value

EndFlag  BYTE                         !terminator flag

 

CODE

!process items one-at-a-time:

Const.Init(Term:BYTE)                        !initialize the Const object,

                                             !the first BYTE contains item count

Const.AddItem(ConstType:PString, Text)       !Describe constant structure and

Const.AddItem(ConstType:PString, Repl)       ! variables to accept the values

Const.AddItem(ConstType:PString, EndFlag)

Const.TerminatorValue = 1                    ! terminate when endFlag =1

Const.TerminatorField = 50                   ! 50th field is the terminating field

Const.TerminatorInclude = True               ! include the terminating record

Const.Set(Spanish)                           !pass constant data to Const obj

LOOP WHILE Const.Next()= Level:Benign        !copy constant data one at a time

 !do something with Text and Repl            !to AddItem variables

END

Const.Kill                                   !shut down Const object

 

                                             !process all items at a time:

Const.Init(Term:BYTE)                        !re initialize the Const object,

                                             !the first BYTE contains item count

Const.ConstantClass()                        !reset to default property values

Const.AddItem(ConstType:PString,LangQ.Text)  !Describe constant structure and

Const.AddItem(ConstType:PString,LangQ.Repl)  ! variables to accept the values

Const.Set(Spanish)                           !pass constant data to Const obj

Const.Next(LangQ)                            !copy all const items to LangQ

Const.Kill                                   !shut down Const object