From: obelix.informix.com!johnl@emory.mathcs.emory.edu (Jonathan Leffler)
Newsgroups: comp.databases.informix
Subject: I4GL Modifications: Part 3 of 3
Date: 25 Jan 1993 10:28:12 -0500
Organization: Mailing List Gateway
Distribution: world
Reply-To: obelix.informix.com!johnl@emory.mathcs.emory.edu (Jonathan Leffler)
NNTP-Posting-Host: emory.mathcs.emory.edu
X-Informix-List-ID: <list.1817>

#!/bin/sh
# this is part 3 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file i4glmods continued
#
CurArch=3
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
     exit 1; fi
( read Scheck
  if test "$Scheck" != $CurArch
  then echo "Please unpack part $Scheck next!"
       exit 1;
  else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file i4glmods"
sed 's/^X//' << 'SHAR_EOF' >> i4glmods
X    the ENTRY or NOENTRY status of a field to be set, and the REQUIRED or
X    NOT REQUIRED status too.  In fact, most of the input attributes should
X    be settable dynamically (see also I4GL-I01).
X
X    I4GL-I02 was rated in class B because it would be very useful.
X
XI4GL-I03:
X    One correspondent (not from CDI) requested that it be made easier to
X    move from an INPUT statement to an INPUT ARRAY statement in a
X    master/detail type screen, the implication being that the user should
X    not have to hit the ACCEPT key to switch between the two.  This is
X    largely under the programmer's control because the INPUT statement can
X    have INPUT WRAP turned off and a function key can be trapped by ON KEY
X    clauses to switch between the two statements.  Unless someone can
X    clarify what is required, this is a non-request.
X
X    I4GL-I03 was rated in class F because it is not clear that there is a
X    requirement.
X
XI4GL-I04:
X    The I4GL help facility always takes over the entire screen when the
X    user invokes it.  It would often be useful if the help facility could
X    be programmed so that the information appeared in a window instead of
X    taking over the whole screen.  A suitable syntax might be:
X
X        COMMAND "Command"
X                "Explanation"
X                HELP 34 IN WINDOW w_winname
X
X        COMMAND "Command"
X                "Explanation"
X                HELP 34 IN WINDOW AT x, y WITH r ROWS, c COLUMNS BORDER
X
X    The first variant would use the currently open (but not current) window
X    w_winname to display the help message.  The second would create an
X    anonymous window simply to display the help message.  However, if this
X    was extended to a complete 6-option menu, the same information would
X    have to be written too many times.  Thus, it should be possible to add
X    a clause to the MENU statement itself.
X
X        MENU "Menuname" HELP 34 IN WINDOW AT x, y WITH r ROWS, c COLUMNS BORDER
X
X    The INPUT, INPUT ARRAY and DISPLAY ARRAY statements do not have this
X    problem; their help is written once.  But SHOWHELP needs to be aware of
X    the current help window so field-level help will appear in the same
X    window as the general help.
X
X    I4GL-I04 was rated in class D because it would not be particularly easy
X    to implement.
X
XI4GL-I05:
X    It should be possible to determine the current value of any OPTION.
X    The result should be able to be used to reset the OPTION later (see
X    I4GL-L28).  This allows library code to change an option to its own
X    value and then restore the value to what it was when the function was
X    called.  (You should look at a graphics library such as GKS; speaking
X    from memory, about 50% of the functions are queries, 40% are attribute
X    setting, and the other 10% or so do the real work.)
X
X    I4GL-I05 was rated in class C but it should have been done long ago.
X
XI4GL-I06:
X    A suggestion received from Adrian Flynn (adrianf@informix.com) was:
X    Include an AFTER UPDATE attribute on fields which executes if (a) the
X    cursor moves into a blank field enters a value and moves out of the
X    field leaving a value in the field, or (b) the cursor moves into a
X    field containing a value and leaves the field having changed the
X    original value.  Do not behave like field_touched() which is true even
X    if the user types the original value again.  You must still check to
X    determine whether the field actually changed.  Execute AFTER UPDATE
X    before AFTER FIELD.
X
X    Adding a whole new set of clauses to an INPUT or INPUT ARRAY statement
X    is probably not a good idea, but providing a function field_changed()
X    which does the job which field_touched() does half-heartedly would be
X    better, and could be added without any major problems.  It would be
X    used in the AFTER FIELD clause, and would only tell you if the value in
X    the field had changed from the value which was current when the cursor
X    entered the field.  If the user moved out of fieldA into fieldB having
X    changed the value in fieldA, then field_changed() would be true in
X    AFTER FIELD FieldA, but if the user moved the cursor out of FieldB back
X    into FieldA, and then moved back out of FieldA to FieldB again without
X    changing the value in FieldA, then field_changed() would be false on
X    the second time through the AFTER FIELD FieldA clause.
X
X    I4GL-I06 was rated in class C but it shouldn't be very difficult to do.
X
X----------------------------------------------------------------------
X
XDISPLAY ARRAY
X
XI4GL-D01:
X    See discussion for I4GL-I01.
X
XI4GL-D02:
X    It should be possible for the programmer to specify which row in the
X    program array should be the active row when the DISPLAY ARRAY starts.
X    This can be achieved by setting NEXT PROGRAM ROW in the BEFORE DISPLAY
X    block (see I4GL-D07).
X
X    I4GL-D02 was rated in class A because it should have been done long ago.
X
XI4GL-D03:
X    It should be possible for the programmer to specify which row in the
X    screen array should contain the cursor when the DISPLAY ARRAY starts.
X    This can be achieved by setting NEXT SCREEN ROW in the BEFORE DISPLAY
X    block (see I4GL-D07).
X
X    It would be possible for the programmer to make a mistake and specify
X    that screen row 3 should contain program row 1, thus leaving two blank
X    lines at the top of the displayed array.  This is not desirable, but
X    there are two possible ways of dealing with the trouble.  One (probably
X    the better one) is to report an error (inconsistent values of screen
X    row and program row); the other is to quietly ignore the request, and
X    in this case, the cursor would start in screen row 1 with program row 1
X    displayed in it.
X
X    I4GL-D03 was rated in class A because it should have been done long ago.
X
XI4GL-D04:
X    It should be possible for the programmer to specify which row in the
X    program array should be the next active row in the DISPLAY ARRAY.  This
X    can be achieved by setting NEXT PROGRAM ROW in an ON KEY or BEFORE ROW
X    or AFTER ROW (see I4GL-D08) block.  This is effectively equivalent to
X    I4GL-D02.
X
X    I4GL-D04 was rated in class A because it should have been done long ago.
X
XI4GL-D05:
X    It should be possible for the programmer to specify which row in the
X    screen array should be the next active row in the DISPLAY ARRAY.  This
X    can be achieved by setting NEXT SCREEN ROW in an ON KEY or BEFORE ROW
X    or AFTER ROW (see I4GL-D08) block.  This is effectively equivalent to
X    I4GL-D03.
X
X    I4GL-D05 was rated in class A because it should have been done long ago.
X
XI4GL-D06:
X    It should be possible to specify a HELP clause for a DISPLAY ARRAY.
X    There also ought to be a CONTINUE DISPLAY statement -- whenever there
X    is an EXIT XYZ statement, there should also be a CONTINUE XYZ
X    statement.  (One exception is EXIT PROGRAM, though a CONTINUE PROGRAM
X    (aka no-op) statement could be provided for complete consistency.)
X
X    I4GL-D06 was rated in class B but should have been done long ago too.
X
XI4GL-D07:
X    It should be possible to specify BEFORE DISPLAY and AFTER DISPLAY
X    clauses for a DISPLAY ARRAY.  These are necessary to provide full
X    support for moving dynamically around the array (see also I4GL-D08, and
X    I4GL-D02 .. I4GL-D05).  Both ARR_CURR() and SCR_LINE() should be
X    usable in these clauses.
X
X    I4GL-D07 was rated in class B but should have been done long ago.
X
XI4GL-D08:
X    It should be possible to specify BEFORE ROW and AFTER ROW clauses for a
X    DISPLAY ARRAY.  These are necessary to provide full support for moving
X    dynamically around the array (see also I4GL-D07, and I4GL-D02 ..
X    I4GL-D05).  Both ARR_CURR() and SCR_LINE() should be usable in these
X    clauses.
X
X    I4GL-D08 was rated in class B but should have been done long ago.
X
XI4GL-D09:
X    It has been requested that there should be some way to move around a
X    DISPLAY ARRAY faster than a row or page at a time.  One suggestion was
X    that there should be some sort of search facility.  The ON KEY, NEXT
X    PROGRAM ROW and NEXT SCREEN ROW options would allow the user to program
X    in any such search if desired.  If a search mechanism was built-in,
X    should it search down the first column only, or down any of the
X    columns?  It will be difficult to specify this generally.
X
X    I4GL-D09 was rated in class E because it is not clear whether it can be
X    implemented as a general facility.  The other improvements to DISPLAY
X    ARRAY probably make it redundant anyway.
X
XI4GL-D10:
X    It should be possible to have the current row highlighted without
X    having to write code to change it.  A suitable syntax might be:
X
X        DISPLAY ARRAY array_var TO scr_array
X            ATTRIBUTE (HIGHLIGHT CURRENT ROW)
X
X    I4GL-D10 was rated in class A because it should have been done long ago.
X
XI4GL-D11:
X    It should be possible to display a subset of the elements in each row
X    of the program array.  If the array elements have six fields, it should
X    be possible to specify that only 4 of the fields should be displayed,
X    and these need not be in the same order as they are stored in the
X    array.  This feature would be even more important to INPUT ARRAY
X    (I4GL-A13).  At the moment, if you need to maintain information off the
X    screen about the rows of data on the screen, you have to use a second
X    array in parallel with the first, and it is a real nuisance to have to
X    keep the parallel array synchronized with the array being used by the
X    INPUT ARRAY.
X
X    Given the advantages of using ARRAY[n] OF RECORD LIKE Table.*, it might
X    be beneficial if the specified elements could come from two separate
X    arrays.  This could be very tricky to implement, however.  At the very
X    least, the code would have to be aware that there were two independent
X    arrays.  This would be useful in conjunction with I4GL-A16.
X
X    I4GL-D11 was rated in class B because it should have been done long ago
X    but is not necessarily all that easy to do.  However, there is room to
X    suppose that the underlying C code always has supported the required
X    functionality, but it simply hasn't been made accessible to the I4GL
X    programmer.
X
X----------------------------------------------------------------------
X
XINPUT ARRAY
X
XI4GL-A01:
X    See discussion of I4GL-D10.
X
XI4GL-A02:
X    See discussion of I4GL-I01.
X
XI4GL-A03:
X    See discussion of I4GL-I02.
X
XI4GL-A04:
X    See discussion of I4GL-D02.
X
XI4GL-A05:
X    See discussion of I4GL-D03.
X
XI4GL-A06:
X    See discussion of I4GL-D04.
X
XI4GL-A07:
X    See discussion of I4GL-D05.
X
XI4GL-A08:
X    It should be possible for the programmer to enable or disable the
X    INSERT and DELETE keys independently of each other.  There are times
X    when the user should not be allowed to change the number of rows in the
X    data in the INPUT ARRAY, though some of the fields in the data may be
X    changed.  A suitable syntax would be:
X
X        INPUT ARRAY var_array WITHOUT DEFAULTS FROM scr_array
X            ATTRIBUTES (ENABLE INSERT KEY, DISABLE DELETE KEY)
X
X    I4GL-A08 was rated in class A because it should have been done long ago.
X
XI4GL-A09:
X    It is often the case that an array has to be declared big enough to
X    take the largest expected list of items (but see I4GL-L02), but the
X    user should not be allowed to extend the selected list of rows during
X    an update (INPUT ARRAY WIHOUT DEFAULTS).  Suppose the array was
X    dimensioned as 40 rows, but only 20 rows were selected.  The INSERT key
X    can be disabled (I4GL-A08), but the user can still move to the bottom
X    of the array and then extend the list.  I4GL should have a function
X    such as SET_MAX_COUNT which adjusts the effective size of the array.
X    Obviously, the programmer should not be allowed to do SET_MAX_COUNT(60)
X    for an array of 40 entries.
X
X    This functionality can be provided in C4GL fairly simply; it only
X    requires a small modification to a header file and adding an extra file
X    to the Informix libraries, but it cannot be done in R4GL.
X
X    I4GL-A09 was rated in class A because it should have been done long ago
X    and is trivial to do.
X
XI4GL-A10:
X    The program should be able to insert one or more rows of data into the
X    middle of the program array without having to program the moves manually.
X    Likewise, it should be able to remove data from the middle of the array.
X    The display should catch up appropriately.  This should probably be done
X    by a pair of routines:
X
X        CALL DELETE_ROWS(array, offset, count)
X
X        CALL INSERT_ROWS(src_array, src_offset, src_count,
X                            dst_array, dst_offset)
X
X    I4GL-A10 was rated in class A because it should have been done long ago.
X
XI4GL-A11:
X    The program should be able to override the use of the INSERT or DELETE
X    key, even when they are enabled.  There are circumstances where the
X    user may not delete certain rows in the data even though some rows can
X    be deleted, and there are other circumstances where a user may not
X    insert data before particular rows even though they may be able to
X    insert data before other rows.  The programmer should be able to
X    control this behaviour.  The BEFORE INSERT and BEFORE DELETE clauses
X    are where the control is needed (though BEFORE INSERT is also used when
X    the array is being extended); the appropriate syntax might be OVERRIDE
X    DELETE or it might be CANCEL INSERT.  Other suggestions welcome.
X
X    I4GL-A11 was rated in class A because it should have been done long ago.
X
XI4GL-A12:
X    See discussion of I4GL-D09.
X
XI4GL-A13:
X    See discussion of I4GL-D11.
X
XI4GL-A14:
X    It would be useful on occasion to be able to specify a unique key in a
X    screen array record, so that if the user enters a duplicate key, an
X    error will be generated.  This would mean that the developer doesn't
X    have to check for the uniqueness of keys after they are entered.  This
X    is typically performed in an AFTER FIELD clause using a loop to check
X    if there is a duplicate.  A suitable syntax might be:
X
X        INPUT ARRAY var_array WITHOUT DEFAULTS FROM scr_array
X            PRIMARY KEY col01, col02
X                { WITH | WITHOUT } DUPLICATE SUPPRESSION
X
X    I4GL-A14 was rated in class D because it is not clear how much call there
X    is for the feature.
X
XI4GL-A15:
X    During INPUT ARRAY, the user should be allowed to move up from the last
X    row of an array if it is blank (or perhaps from any blank row of an
X    array), even if the fields have REQUIRED attributes or the columns are
X    NOT NULL.  For example:
X
X            Customer No   Name
X          1 [123]         [Flynn      ]
X          2 [456]         [Leffler    ]
X          3 [   ]         [           ] <--- Cursor here (last row)
X          4 [   ]         [           ]
X
X    If the user moves onto row 3, the cursor cannot be moved back to row 2
X    if there are REQUIRED attributes on any of the fields or NOT NULL on
X    any of the columns.  Ideally, the cursor should not be allowed to move
X    onto row 4 until 3 is filled in.  Currently this functionality requires
X    excessive code.
X
X    The features for handling NEXT SCREEN ROW and NEXT PROGRAM ROW may be
X    sufficient to overcome this problem without much coding.
X
X    I4GL-A15 was rated in class C because it is not clear whether it is
X    really needed if all the other features are implemented instead.
X
XI4GL-A16:
X    It would be useful if there was a simple method of determining which
X    rows in the array were changed, deleted and inserted during INPUT ARRAY
X    WITHOUT DEFAULTS, with a view to making the database update operations
X    more efficent.  Currently most users DELETE everything and then INSERT
X    what is in the array as there is no change tracking mechanism.  The
X    overheads are too much for this method.
X
X    Tracking inserted and updated rows should be relatively simple using
X    I4GL-D11 to retain an extra column which marks the rows which are
X    inserted or deleted.  Tracking deleted rows is more difficult; the onus
X    might be on the programmer to copy the keys of the deleted rows into a
X    separate array which could be used afterwards to control the deletions.
X    The post-processing should probably delete the date, then insert the
X    data, then update the data, for who can tell whether the user deleted a
X    row and then re-keyed it.
X
X    I4GL-A16 was rated in class F because it is not clear how it could be
X    implemented, nor whether it is really necessary given the other
X    changes to INPUT ARRAY.
X
X----------------------------------------------------------------------
X
XCONSTRUCT
X
XI4GL-C01:
X    (The original mail message uses AUTOWRAP consistently; I think AUTONEXT
X    is intended).  David Vessell (dave@bradley.bradley.edu) asks: I would
X    like to see AUTONEXT capability restored to the CONSTRUCT statement.
X    Originally it was allowable, but Informix considered it a bug and fixed
X    it, which absolutely killed us here, because in our applications here
X    we do a lot of querying on fixed-length fields, one value at a time.
X    The users never use ranges of data or anything else like that.  Because
X    of this fix, every field now must be followed with a carriage return in
X    order to move to the next field.  I don't see why this should be an
X    either-or thing.  It should be definable in the screen form.  If you
X    need the query window at the bottom for larger-than-field search
X    criteria, specify it in the screen form.  But having AUTONEXT
X    capability restored would be a godsend to us.
X
X    If the users' queries are that simple, you could use INPUT to get the
X    relevant values (with AUTONEXT working a treat), and you could build
X    the query yourself (and it is not very hard to do it).  If AUTONEXT
X    were reinstated in CONSTRUCT, how could a more experienced user request
X    all the values in the range [A-E] in a single character field?  If it
X    is restored, it must be restored under control of an attribute, and the
X    default in the absence of the attribute should be the non-AUTONEXT
X    behaviour.  A suitable syntax for the field attribute might be:
X
X        { WITH | WITHOUT } CONSTRUCT BUFFER
X
X    I4GL-C01 was rated in class F because it is not clear that it is a good
X    idea.
X
XI4GL-C02:
X    This is another bug fix request.  The get_fldbuf() function should
X    retrieve all of the condition typed by the user and the DISPLAY in
X    BEFORE CONSTRUCT should restore all of it, assuming it was saved into a
X    long enough character string (and CHAR(78) should be big enough because
X    the window cannot be wider than that, in general).  In 4.10.UC1, if you
X    enter a date range into a field and save it and then restore it on the
X    next CONSTRUCT, the condition is typically not valid, so the user has
X    to retype it afeter all, which defeats 99% of the object of the
X    exercise!
X
X    I4GL-C01 was rated in class A because it is a bug fix.
X
X----------------------------------------------------------------------
X
XPICKLISTS
X
XI4GL-K01:
X    I4GL should provide a 4GL facility which allows a user to choose the
X    correct value from a list generated from some table in the database.
X    The discussion in CDI was definitely in favour of such a facility, but
X    was short on concrete suggestions about what should actually be
X    provided.  This section sets out some of the requirements which a
X    picklist facility should provide.
X
X    * A picklist should appear in a window.  The window will normally be
X      bordered.  The window will normally be positioned by the programmer.
X      The window should not need to be named by the programmer.
X
X    * Two modes of window sizing are desirable.  Mode-1 sizes the window to
X      suit the list of values which were retrieved.  Mode-2 fixes the size
X      of window.  (The discussion in CDI implied that Mode-1 was all that
X      was necessary; however, some customers prefer all the popup windows
X      to appear at the same place and to cover most of the screen, so
X      Mode-2 is also desirable.)  In Mode-1, there may be a maximum size
X      which the pogrammer wishes to use.  Normally, a single program will
X      either use Mode-1 or Mode-2 for all its picklists and not a mixture,
X      but a mixture should be allowed.
X
X    * It must be possible to specify other appropriate window attributes.
X      This would certainly include an option to specify that the current
X      row should be highlighted.
X
X    * There are two sets of characteristics describing the behaviour of the
X      picklist.  First, some picklists generate the list of values
X      unconditionally, whereas others should allow the user to perform some
X      sort of query to select the values to be displayed.  These might be
X      termed conditional and unconditional picklists.  Second, most
X      picklists should return a single value, but occasionally it is useful
X      to have the ability to select a list of values.  These might be
X      termed single-choice and multi-choice picklists.  A mechanism should
X      be devised to allow a list of values to be returned.
X
X    * For a conditional picklist, the columns on which the query can be
X      expressed should be definable.  These may not coincide with the
X      displayed columns, which suggests that the conditional picklist is
X      best implemented by the programmer providing the query facility in
X      ordinary I4GL and then invoking the standard picklist functionality
X      with the query so generated.  Conditional picklists are not given
X      further consideration.
X
X    * The picklist should have an optional title.  It should also contain a
X      user-definable message to indicate what the user should do next.  The
X      displayed columns may need to be annotated.
X
X    * The space needed to store the displayed values should not be a fixed
X      size array.  Indeed, the programmer should not have to manually
X      allocate the required space at all.  The programmer may specify an
X      upper bound on the number of rows available to the user.  If the list
X      is larger than this bound, it would be truncated.
X
X    * The data should be shown in some programmer-defined order.
X
X    * The table, the primary key column(s) to be returned, and the columns
X      to be displayed should be definable for a picklist.  The normal use
X      of a picklist is to look up values in a table with two relevant
X      columns -- a code and a description.  However, compound primary keys
X      and multiple description columns cannot be rules out.  Nor can the
X      possibility that the relevant display involves data from multiple
X      tables.  One way around that would be to use a view.  Views should be
X      supported as an alternative to a table without any changes being
X      necessary.  However, that may be too restrictive, and so a general
X      SELECT statement may be required.  This also allows for ordering to
X      be handled straight-forwardly.
X
X    * Should a picklist have to regenerate its data every time it is
X      invoked?  This is a non-trivial question.  If the data in the table
X      changes regularly, then the list should be regenerated afresh every
X      time it is used, but most picklists will be used on tables which are
X      essentially unchanging, and the cost of regenerating (and
X      re-ordering) the data may be non-negligible.  This suggests that
X      there should be an option to have a regeneratable list, but that the
X      default should be to re-use the list on subsequent invocations of the
X      picklist.
X
X    * The discussion in CDI implied (I think) that the all this should be
X      definable using a single statement which need not be in a separate
X      function (so it could be used in an AFTER FIELD clause of an INPUT
X      ARRAY, for example).  This is a laudable objective, though it seems
X      probable that good engineering practice would factor the statement
X      into a subroutine so that the same picklist could be use in more than
X      one place.
X
X    * Given these requirements, the syntax below could be used for a
X      picklist.  Although there is no obvious universal method for
X      returning a list of choices, the multi-choice picklist is supported
X      by this syntax; the features required to provide such support are
X      discussed below.
X
X        PICKLIST
X            HELP 999
X            WINDOW AT x, y WITH {MAX} r ROWS, c COLUMNS
X                CURRENT ROW HIGHLIGHTED,
X                NO BORDER,
X                COMMENT LINE LAST,
X                TITLE LINE FIRST + 1,
X                LABEL LINE FIRST + 3
X            CENTRE TITLE "Title of popup" REVERSE
X            COMMENT "Use arrow keys to find the required value "
X                    "and press the ACCEPT key"
X                    DIM
X            SELECTION "SELECT T1.Col01 Column1, T1.Col03 Column2,"
X                      " T2.Col19 Column3, T2.Col05 Column4, T2.Col01 Column5"
X                      " FROM TableA T1, TableB T2"
X                      " WHERE T1.Col02 = T2.Col04"
X                      " ORDER BY Column1, Column2, Column5"
X                REGENERATE
X                MAX SELECTED ROWS 100
X                AUTORETURN
X            DISPLAYING
X                Column1 USING "&&&&&",
X                Column2 WORDWRAP 30,
X                Column3 TRUNCATE 20,
X                Column4
X            LABELLED "Label1", "Label2", "Label3", "Label4"
X            PRIMARY KEY Column1, Column2
X            -- End of the "fixed" part of a PICKLIST
X
X            -- The returning clause is the simplest variable component
X            -- of the PICKLIST.  Other clauses are of the "traditional"
X            -- BEFORE PICKLIST, AFTER PICKLIST, BEFORE ROW, AFTER ROW,
X            -- ON KEY (keylist) types.  See the discussion below.
X            RETURNING variable1, variable2
X
X        END PICKLIST
X
X    * The SELECTION and PRIMARY KEY clauses are mandatory, and the
X      remainder are optional.  There must either be a RETURNING clause or
X      an ON KEY (KEY_SELECT) clause.
X
X    * The WINDOW section is optional.  If it is not specified, the window
X      defaults to a bordered window located at 2, 2 with unconstrained
X      Mode-1 sizing.  Mode-1 operation is supported when the MAX keyword is
X      used; Mode-2 operation is supported when it is omitted.  The WITH
X      clause is optional, and if it is omitted, then unconstrained Mode-1
X      operation is implied.
X
X    * Since the default behaviour is BORDER, the attribute NO BORDER is
X      needed to indicate that the window should not have a border
X      (I4GL-L32).  Using NO BORDER would be sensible if the PICKLIST was
X      located at 1, 1 and was as big as the whole screen.
X
X    * Since the language is fully regular (I4GL-L09), all the strings can
X      be replaced by character variables when required.  So, of course, can
X      the attributes (I4GL-???).  The COMMENT and SELECTION sections are
X      making use of the proposed string concatenation operation (I4GL-L31).
X
X    * The TITLE, COMMENT and LABELLED sections define the labelling for the
X      PICKLIST.  The title (if any) appears on the window's title line,
X      which defaults to FIRST.  The comment (if any) appears on the
X      window's comment line.  The labels appear on the LABEL LINE, which
X      defaults to TITLE LINE + 1, but would be specified using FIRST + n or
X      LAST - n notatation.  Multi-part titles are supported because you can
X      specify up to three parts to the title: LEFT TITLE "String1", CENTRE
X      TITLE "String2", RIGHT TITLE "String3", with unadorned TITLE "String"
X      being considered as CENTRE TITLE.  This would allow the date and
X      version control information to be displayed as well as the main
X      title, and would allow them to be displayed with different attributes
X      (DIM in contrast to REVERSE, perhaps).
X
X      Oh, and it would be nice if the product supported both spellings of
X      CENTRE and CENTER.  I4GL already does this with MAX and MAXIMUM, LINE
X      and LINES, and in a number of other places, so one more wouldn't hurt
X      either.
X
X    * The SELECTION section defines the data to be selected and the
X      ordering of this data (if any).  The names specified in the
X      DISPLAYING section are the display labels of the selected columns
X      (remembering that T1.Col01 has a default display label of Col01).
X      These names must be unambiguous (so it must meet the same constraints
X      as would be required if the SELECT statement were to be used with an
X      INTO TEMP clause).  The example uses a string to build the SELECT
X      statement; this is certainly desirable.  It might also be desirable to
X      allow a SELECT statement to be written out verbatim (not in a string),
X      though the benefit is marginal given I4GL-L31.
X
X      Note that some of the selected data might not be displayed, and some
X      of the returned data might not be displayed.  This would occur where
X      a serial column is used internally to identify an object, but the
X      user always identifies an object by a meaningful character string.
X      Consider a scenario where there are two tables defining ports and
X      countries.  The ports are internally referred to by Port_id, but the
X      user always uses Port_name to identify the port.  Each port is in a
X      country, identified by a country code.  The order in which the
X      countries are listed is defined by an ordering indicator, and within
X      a country, the order of the ports is defined by a second ordering
X      indicator.  The user would only see the port name and country name,
X      but the select statement would have to return Port_id, Port_name,
X      Country_name, Country_order, Port_order; the data would be ordered on
X      the last two columns, the first column would be returned to the
X      program, and the other two columns would be displayed to the user.
X
X      The REGENERATE attribute indicates that the data must be reselected
X      every time the PICKLIST is used.  If the SELECTION changes, the data
X      would be regenerated automatically, of course.  It should be possible
X      to declare WITHOUT REGENERATE (the default) as well as REGENERATE
X      (I4GL-L32).
X
X    * The MAX SELECTED ROWS clause is used to indicate that only the first
X      150 rows are to be used, even if the SELECT statement would return
X      more.
X
X    * The AUTORETURN attribute means that if the SELECT statement returns a
X      single row, the window is not displayed and the key is returned
X      automatically, and if no rows are returned, then the returned key is
X      all null.  The NO AUTORETURN attribute is the default.  If STATUS was
X      set to NOTFOUND when zero rows were found and was set to 0 when one
X      row was found), this would allow the two cases to be distinguished
X      adequately.
X
X      Given that the SELECT statement is a string, it could use "?" place
X      markers for variables, in which case the SELECTION clause would need
X      a USING sub-clause which defined which variables were to be
X      associated with which place markers.
X
X    * The DISPLAYING clause uses the display labels from the SELECTION to
X      define which fields which will be shown on the form and the order in
X      which they appear across the screen.  If there is a LABELLED clause,
X      then the Nth column in the DISPLAYING clause will be labelled with
X      the Nth string in the LABELLED clause.  It is an error if the number
X      of fields in the LABELLED clause differs from the number of items in
X      the DISPLAYING clause; if necessary, null labels must be supplied.
X      It is another run-time error if any of the columns listed in the
X      DISPLAYING clause is not produced by the SELECTION.
X
X      The fields will be sized automatically.  The WORDWRAP and TRUNCATED
X      options could be combined (so that a VARCHAR(255) field could be
X      truncated to 60 characters and wrapped in a width of 30), and other
X      options are needed so that the format of the display rows can be
X      defined precisely.  Additionally, each column should be able to have
X      display attributes (primarily colour) if required.
X
X      If there is no DISPLAYING clause, then all the selected columns will
X      be displayed in the order they appear in the selected data using
X      default formats.
X
X      If the data layout defined or implied by the DISPLAYING section will
X      not fit across the window defined in the window section, it is an
X      run-time error.  The layout cannot be fixed at compile time because
X      the actual data structure is not known until the SELECTION clause is
X      evaluated at run-time.
X
X    * The PRIMARY KEY clause defines the columns to be returned, again
X      using the display labels from the SELECTION.  Some thought needs to
X      be given to the type of the columns listed in the PRIMARY KEY
X      section, because the same values will have to be used elsewhere (see
X      the section on multi-choice picklists below).  It is probably best if
X      the names can be written either as literals which are converted to
X      strings automatically or as a string expression.  It would be a
X      compile-time error for two literals (be they literals or literal
X      string expressions) to be identical.  It would be a run-time error
X      for a string expression to evaluate to the same value as any of the
X      other columns, but the code need only check this if one or more of
X      the primary key columns is an expression.  It is another run-time
X      error if any of the columns listed in the PRIMARY KEY clause is not
X      produced by the SELECTION.
X
X    * The RETURNING clause terminates the statement when the user uses the
X      KEY_SELECT (aka ACCEPT KEY?) to indicate their choice.  It defines
X      the variables to receive the primary key values.  There must be as
X      many variables as there are columns specified in the PRIMARY KEY
X      clause, and the Nth variable in the RETURNING clause will be given
X      the value from the Nth column in the PRIMARY KEY clause.  A
X      multi-choice PICKLIST will not use this clause.
X
X    * If an error occurred while the window was being set up or the data
X      was being selected, the appropriate error indicators (STATUS and
X      possibly SQLCA) would be set as normal, and the statement would exit.
X      The values of the returned variables would be undefined.  If an
X      interrupt or quit signal occurred during a picklist operation, then
X      INT_FLAG or QUIT_FLAG would be set and the statement would exit
X      leaving the values of the returned variables undefined.
X
X    * Support for multi-choice picklists is provided by allowing the
X      various BEFORE/AFTER/ON constructs in place of (or as well as) the
X      RETURNING clause.  For example, an ON KEY (KEY_SELECT) clause could
X      be used to store the primary key values of the current row somewhere
X      where they could be got at after the PICKLIST was over.  This could
X      be an array of values, or some set of functions which provided a
X      container for a list of values.  There would need to be some way of
X      getting at the current values, which is non-trivial given that the
X      number and type of the values varies from picklist to picklist.  A
X      function such as:
X
X        LET variable = GET_CURRENT_VALUE(Column1)
X
X      would be needed.  The argument to this function is either a column
X      name from the PRIMARY KEY clause or a string expression which matches
X      one of the columns names specified in the PRIMARY KEY clause.
X
X      The EXIT PICKLIST and CONTINUE PICKLIST keywords would be needed.
X      For consistency, the BEFORE PICKLIST and AFTER PICKLIST sections
X      should be allowed, though it is not immediately obvious what they
X      would be used for.  Similarly, if BEFORE ROW and AFTER ROW are not
X      provided, someone is bound to miss them sooner rather than later.
X
X      The RETURNING clause equates with:
X
X        ON KEY (KEY_SELECT)
X            LET variable1 = GET_CURRENT_VALUE(Column1)
X            LET variable2 = GET_CURRENT_VALUE(Column2)
X            EXIT PICKLIST
X
X      The RETURNING clause is logically redundant because it can be
X      replaced by an appropriate ON KEY (KEY_SELECT) clause, but it has the
X      merit of being fully checkable (is the correct number of variables
X      set?), whereas if the user omitted one of the fields from the ON KEY
X      (KEY_SELECT) clause, the compiler could not know whether this was an
X      oversight or intentional and would have to deem it intentional.  The
X      END PICKLIST keyword could be added anyway, and other ON KEY clauses
X      (and BEFORE/AFTER clauses) could be supported anyway.
X
X    * It would be useful to be able to mark the rows which have been chosen
X      by the user in a multi-choice PICKLIST.  A syntax for this would have
X      to be added.  One relatively neat solution would be to have the
X      SELECT statement select a constant value (such as blank) as
X      Column0, and then to have support for:
X
X        CALL SET_CURRENT_VALUE(Column0) = "X"
X
X    * Note that if the compiler's lexical analyser regards compound
X      keywords such as END PICKLIST or TITLE LINE as a single symbol rather
X      than as two symbols, then there is no ambiguity in the grammar above:
X      the TITLE LINE attribute of the WINDOW clause cannot be confused with
X      the TITLE clause.
X
X    * This statement is very much like the INPUT and INPUT ARRAY
X      statements.  The minimal form of a PICKLIST is something like the
X      example below, which is pretty compact, but as more demands are made
X      on the appearance of the data and on the controls required over the
X      user, the statement can get very complex indeed.
X
X        PICKLIST
X            SELECTION "SELECT * FROM Simple_lookup"
X            PRIMARY KEY Column01
X            RETURNING variable01
X        END PICKLIST
X
X----------------------------------------------------------------------
X
XGosh, you're still with me.  I wish I could guarantee that your persistence
Xwould be rewarded, but I can't.  Anyway, I would like to receive your views
Xon what has been said here, especially if you disagree with something, or
Xif you think something is missing.  I will assume that if you say nothing
Xabout some item, you do not violently disagree with it.  I will assume
Xnothing about your response if you don't say anything.
X
XYou can email me at:
Xjohnl@obelix.informix.com or ...!uunet!pyramid!infmx!johnl
X
X----------------------------------------------------------------------
X
XPrepared by: Jonathan Leffler, Informix Software UK.  January 1993.
X@(#)i4glmods Version 1.6 Date 93/01/22
SHAR_EOF
echo "File i4glmods is complete"
chmod 0444 i4glmods || echo "$0: failed to restore i4glmods"
rm -f s2_seq_.tmp
echo "You have unpacked the last part"
echo All files extracted
exit 0