Media Share 9/MEDIASHARE_09.ISO/clarion/array.zip/ARRAY.DOC

Text File | 1993-03-23 | 13KB | 315 lines

               DATA ENTRY OF ARRAYS IN DESIGNER

March 23, 1993
Author :DANIEL CHILTON

        ABSTRACT - Three methods are presented, which allow
applications to exploit the many benefits of using arrays, while
only using the Clarion's normal FORM Procedure to accomplish data
entry.

        One of the four examples in the APP requires that the
ARRAY.CLA source code to be edited by deleting exactly 1 character,
but requires no hand coding in Editor. See Fig 1

               ***

        DESIGNER does not support array data entry directly. Numbers
and strings may be displayed and edited as ENTRY FIELDs, but not
arrays, or array elements.

        Designing a solution to this limitation requires that ENTRY
FIELDS be setup to display the array elements and permit editing.

        The design must create a correspondence between these
variables and the array elements to be entered or edited. These
ENTRY FIELDS must be the same type as the array.

        The design must also assure that the values which are
displayed and edited, properly represent the values in the array.

        METHOD 1:  ' 1 to 1 with the OVER attribute '
                                      99 44/100 % Pure Designer

        This is the simplest and fastest executing method. It is
implemented almost entirely in DESIGNER , and requires only a
minuscule source code change.

        The first steps of this method create a '1 to correspondence
between each array element, and variables which represent them. EG:

        The variable           JAN corresponds to  MONTH[1]

                               FEB corresponds to  MONTH[2]

                               ...

                               DEC corresponds to  MONTH[12]

1.      Use DESIGNER to create the variables, and a file which
        contains them.

        They must appear in the same sequence as the corresponding
        array elements. In this case we are using a one dimensional
        array to represent monthly data, so the correct sequence for
        this example, is the common sense one as above.

        In multi-dimension arrays, the sequence of variables must
        match the order in which CLARION assigns array elements in
        memory, and the programmers intentions.

        For example a two dimensional array representing months in
        financial quarters might be set up as a 4 by 3 array. CLARION
        assigns the elements to memory in the 'natural order.' ie
        MONTH[1,1]  is first (JANUARY) , MONTH[1,2] is second
        (FEBRUARY) ... MONTH [4,3] is last (DECEMBER.)

2.      Create a group structure that contains the variables.

3.      Create another group in the same file that contains the array.
        It must match the first group's data type and number of
        elements. (Twelve longs, for example.)

        In Designer use: ",OVER(GROUP1) ! Delete 1st ! " as the
DESCRIPTION of this group.

        This description appears beside the array declaration in the
source code preceded by an exclamation point, and is therefore
treated as a comment. Delete the first '!' in this line , and the
'comment' will be treated as code. The code in this example invokes
the OVER attribute. The OVER attribute tells the CLARION COMPILER
to use the same memory for the variables as the array. In this way
the variable names and the corresponding array elements become
identical. The programmer is free to use the variable name or array
element name, for the same datum.


4.      Design a table and form. Let DESIGNER populate the form with
the variables.

5.      Through-out the application, use the array or variables as you
        like. They  will be IDENTICAL.

6.      After the .APP is created, but before compiling, invoke the
        OVER attribute in the source code containing the GROUP data
        structures. The over attribute should specify that the second
        group is OVER the first.

Fig 1 Edit ARRAY.CLA

        Before:
GROUPA2                 GROUP         ! ,OVER(GROUPA1) !delete 1st !

        After:
GROUPA2                 GROUP          ,OVER(GROUPA1)  !DELETED 1ST !


        This trick - Deleting the '!' - reduces the coding in EDITOR,
and helps the programmer use DESIGNER almost entirely. Using it,
the programmer can continue to use DESIGNER to change applications
without requiring significant programming in EDITOR with each
change in the application.

        Some programmers may wish to totally eliminate unnecessary use
of EDITOR while developing their application. Doing so may avoid
continually editing new code generated by DESIGNER as changes are
made there. Finally when the application is finished, a slower
executing 'ALL DESIGNER' method can be replaced by this faster ' 1
to 1 OVER ' method by a simple code change.

        METHOD 2: 1 to 1 GROUP EQUATE METHOD - 100% Pure Designer

        As in the 1-1 OVER method groups are created to contain the
array and the variables to which they correspond.

        The Group Equate Method requires that data be moved to and
from the array and the corresponding variables. As the name
suggests a Group assignment statement makes the groups EQUAL in
value .

        Instead of making them IDENTICAL at compile time using the
OVER attribute, this method makes them EQUAL during execution of
the program.

        The Group assignment statement is syntactically identical to
variable assignment statements. EG

        MEM:GROUPA = FIL:GROUPB

        They should be placed in the setup procedure of forms, to make
the variables equal to the array, and in computed fields to make
the array equal to the variables. In this way the variables ( on
the screen ) will always be equal to the corresponding array
elements ( in the record ) .

        The steps for this method are:

1.      Define variables in MEMory, and contain them in a group, just
        as in the previous method.

2.      Define the corresponding array and contain it in a group. It
        should be defined in your file. As before , the array should
        match the number and type of variables in the previous group.


3.      In every form using the array you must:

        1.     Set the MEMory group to the array group in the SETUP
        PROCEDURE. This assures that the FORM will contain the proper
        values from the start.
        EG: MEM:GROUP = FIL:GROUP

        2.     Populate the form with variables from MEMory and the
        file.
               If the array is Very Large, you may want to let DESIGNER
        to populate the form with these MEMory variables. Do so by
        selecting MEMory as the File name when you create the Form.
        Then populate the form with the MEMory variables. Then select
        the correct File name, and edit the form, as necessary.

        3.     Create a computed field which sets the Array Group to the
        MEMory Group. This assures that the file's array always
        contains the new data as it gets typed in.

        EG:

               Computed Field
  Name        :SCR:SC1
  Picture     :@S1
  Expression  :' ';F2:GROUPB1=MEM:GROUP0


               This is my favorite way to get code into DESIGNER. The
        @S1 picture token assures that the field is represented by a
        visible '■' in Designer.

               This computed field is executed repeatedly as the
        variables change on the screen and in MEMory. It maintains the
        proper value of the array elements as these changes occur.

        Some applications using a '1 to 1' method may be difficult to
operate. Arrays with multiple dimensions or many elements will be
more difficult to work with. They may require many clicks to get
the cursor to some fields. So we need to consider more user
friendly methods. After all, we write programs for users. Right ?

        METHOD 3: '1 to Many'  using  Computed Assignment.

        The previous examples used a 1 to 1 correspondence between the
fields that appeared on the form , and the array elements.

        A '1 to many' correspondence can be set up to simplify data
entry, however it complicates the programming task.

        In this method the values of the array are displayed one-at-a-
time in a 'Value Field.' An 'Index Variable ', containing an index
to the array, determines which array element gets displayed and
edited in the 'Value Field.'

        More than one dimension can be handled by this method, but a
one dimensional array serves as a good example. Two or more indices
may be needed to handle the higher dimensions.

        Two ( or more ) MEMory fields can be set up to accomplish the
data entry for this method. Computations performed in the
edit_procedures of these MEMory fields move data to and from the
array, into and from  the 'Value field.'

        The steps for this method are:

1.      Define one integer variable for the 'Index Variable' in
        MEMory, and another variable for the 'Value Field.' The 'Value
        field' must be the same data type as the array elements. You
        should set upper and lower limits on the Index, which can be
        a 'SHORT ' data type.

2.      Create a file that contains the array. It need not contain a
        GROUP structure.

3.      For each form in which you want to edit the array, you must do
        the following:

        1: Initialize the Value field. Do this in the SETUP PROCEDURE
        of the form. You may also need to initialize the Index
        Variable.
        For example:

        MEM:NDX=1 ; MEM:VALUE=F2:ARRAY[1]

        The choice for the default for the Index Variable depends on
        your application. You may wish to allow the operator set it in
        an entry field in the table, just before using the form.


        2: Place an 'Index Field' in the form. This is optional. This
        method works as long as THERE IS an index value.
        In the EDIT PROCEDURE of this field, assign the array element
        specified by the new value of the Index field to the Value
        field. Use the DISPLAY statement to display this value.

        EG: MEM:VALUE = F2:ARRAY[MEM:NDX] ; DISPLAY

        3: Place the 'Value Field' in the form. In the EDIT PROCEDURE
        of the 'Value Field' , assign the 'Value Field' to the array
        element. The value of the Index field is used as the index to
        the array.

        EG:  F2:ARRAY[MEM:NDX] = MEM:VALUE  ; DISPLAY

        Variations on a theme:

        These three steps will work , but may be difficult for the
        operator to use. I recommend the addition of any of the
        following steps to enhance the ease of use and functionality
        of the application.

        4A:    In the edit procedure of the Value field, where n= limit
               of the index, increment the Index as follows:
                       Index = ( Index MOD N ) + 1
                       Set the Value field to this array element.
                       Use the DISPLAY statement to display these new
                       values.

        4B     Use SELECT() in the EDIT PROCEDURE of the Index field to
               move the cursor back to the Value field for more data
               entry. This helpful for repeated data entry. The
               keycode() is tested for keycode() = 257. (257 = ENTER)
               CTRL-ENTER ends data entry.

        4C     Use Alerted keys to increment the index. Page UP and Page
               Down are good choices. The cursor can stay in the Value
               field using SELECT(). In this case the Index field can be
               'Display Only' rather then 'Edit Field.'

        4D     Use COMPUTED FIELDS  OR  DISPLAY FIELDS to display other
               elements of the array.

        4E     Use a pointer to indicate which element is being edited.
               Display each array element. Along side each element put
               a CONDITIONAL FIELD which displays "==>" or "   "
               depending on the value of your index.


        Entry Field


Field Name    :MEM:VALUE          File Access Key :
Edit Procedure:
        F2:ARRAY[MEM:NDX]=MEM:VALUE;                  !* update array value
        IF KEYCODE()=257 THEN;                        !* test for ENTER KEY
        MEM:NDX=MEM:NDX % 12 +1;                      !* increment Index mod 12
        MEM:VALUE=F2:ARRAY[MEM:NDX];                  !* set variable to array value
        SELECT(3);END                                 !* move cursor to EDIT FIELD

     This EDITED Clarion Screen Shows the implementation of some of
these suggestions.


     The  subroutine used in the report example totals values in
the Array from START to FINISH 'wrapping around' if necessary.  EG:


From November - 11th month
     to March - 3rd month.
     ( 11+12+1+2+3 )