OV_INDEXED_SPACE

LANSA

OV_INDEXED_SPACE

The Things that Make Up this ExampleTo Execute this ExampleBIF Descriptions


  
   DLL Required    : U_BIF989.DLL
   ------------

   Description     : Allows you to define and manipulate an indexed space.
   -----------       

   Availability    : Windows       -> YES
                     Unix          -> NO
                     OS/400        -> NO

   ARGUMENTS
   ---------

          Type  Required/                                   Length  Decimals
   Number  A/N  Optional Description                        Min Max Min Max
   ------  ---  -------- -----------                        ------- -------

     1     A     Req     Type of indexed space operation to   1  50
                         be performed.
                       
                         Pass as one of :

                         CREATE  : Create a new indexed space.
                         INSERT  : Unconditionally insert a new entry into an indexed space.
                         PUT     : Insert a new or update an existing entry in an indexed space.
                         GET     : Get an entry from an indexed space.
                         FIRST   : Get the first entry in an indexed space.
                         NEXT    : Get the next entry in an indexed space.
                         DESTROY : Destroy an indexed space and free associated system resources.


                         Note that this builtin only validates and acts upon the first character
                         of the requested index space operation (ie: C,I,P,G,F,N,D) but to
                         maximise RDML function readability it is recommended that you use the 
                         full words CREATE, INSERT, PUT, GET, FIRST, NEXT and DESTROY.


     2     A     Req     Definition string or indexed space   1 256
                         identifier (or handle). An identifier
                         (or handle) is the value returned to you
                         in argument 2 when you create a new indexed
                         space that uniquely identifies the indexed
                         space.
     
                         When Arg 1 is  Pass this argument as
                         -------------  ---------------------

                         CREATE         The indexed space definition string. See the following
                                        information for details of definition strings.

                         any other      The identifier (or handle) of the indexed space
                                        that is to be used by the requested operation
                                        (the identifier or handle is the value returned
                                        in return value 2 when a new index space is
                                        created. It uniquely identifies the indexed space
                                        which you wish to use).

     3     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     4     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     5     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     6     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     7     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     8     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

     9     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

    10     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.

    11     A     Opt     Definition string continuation.      1 256
                         Only valid for CREATE operations.
                         This value is ignored for other operations.


   RETURN VALUES
   -------------

          Type  Required/                                   Length  Decimals
   Number  A/N  Optional Description                        Min Max Min Max
   ------  ---  -------- -----------                        ------- -------

     1     A     Req     Standard Return Code                2    2
                         Returned as "OK" (completed
                         normally), "NR" (no record found)
                         or "ER" (error occurred).

     2     A     Opt     Returned indexed space identifier   10  10
                         or handle. This return value is
                         mandatory when argument 1 is passed 
                         as CREATE because it returns the
                         identifier (or handle) of the indexed
                         space that was created.



   INDEXED SPACES AND INDEXED SPACE DEFINITION STRINGS
   ---------------------------------------------------

   When an index space is being created (ie: CREATE is used in argument 1) then arguments
   2 through 11 must specify a definition string for the indexed space.

   Arguments 2 through 11 are concatenated (trailing blanks in each separate
   argument are ignored) to form a single definition string that must be formatted thus :



       name keyword(value), name keyword(value), name keyword(value), ....... name keyword(value)



   where :

     "name" is the name of a valid RDML field that is defined in, or referenced by, the
      RDML function that is creating the list.

     "keyword" specifies the use of the field specified in "name". It may be one of KEY, 
      DATA, AVG, MAX, MIN, COUNT and SUM. If a keyword is not specified then DATA is
      assumed as a default keyword.

     "value" specifies the name of a valid RDML field that is defined in, or referenced by,
     the RDML function defining the list. It is used to specify, for certain keyword values only,
     the field upon which the keyword activity should take place. Thus ".., A SUM(B), .." defines
     that indexed space field A is to contain the SUM (or total) of field B. Likewise, the
     string ".., X AVG(Y), .." defines that indexed space field X is to contain the average
     of field Y.

   The "keywords" AVG, MAX, MIN and SUM require associated "values" and thus must be formated
   as AVG(value), MAX(value), MIN(value) and SUM(value) where value is the name of a field defined
   in the invoking RDML function.

   The "keywords" KEY, DATA and COUNT do not require associated "values" and they should only be
   specified as KEY(), DATA() and COUNT().




   An indexed space is best visualised as a table or grid.

   The definition string defines what the columns in the indexed space are to be and how they
   should be used. The following examples illustrate this concept :

   Definition String : deptment key(), deptdes
   -----------------

   Can be visualised as :

           -------------------------------------
          | Department | Department Description |
          | (DEPTMENT) | (DEPTDESC)             |
          |------------|------------------------|
          |            |                        |
          |            |                        |
          |            |                        |
          |            |                        |
          |            |                        |
          |            |                        |
          |            |                        |
           -------------------------------------

     where DEPTMENT is the single key to each table or grid entry. Note that "deptdesc"
     adopts the default keyword "data()" in this example.


   Definition String : deptment key(), section key(), secdesc
   -----------------

   Can be visualised as :

           ----------------------------------------------
          | Department |  Section  | Section Description |
          | (DEPTMENT) | (SECTION) | (SECDESC)           |
          |------------|---------------------------------|
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
          |            |           |                     |
           ----------------------------------------------

     where DEPTMENT and SECTION form an aggregate to each table or grid entry. Note that
     "secdesc" adopts the default keyword "data()" in this example.


  Definition String : deptment key(), empasal avg(salary), empxsal max(salary), empmsal min(salary)
  -----------------

  Can be visualised as :

           ---------------------------------------------------------------
          | Department | Average Salary | Maximum Salary | Minimum Salary |
          | (DEPTMENT) |   (EMPASAL)    |    (EMPXSAL)   |   (EMPMSAL)    |
          |------------|----------------|----------------|----------------|
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
          |            |                |                |                |
           ---------------------------------------------------------------


   where DEPTMENT is the single key to each table or grid entry.


   NOTES / RULES / GUIDELINES FOR USAGE OF OV_INDEXED_SPACE
   --------------------------------------------------------

   * Indexed spaces have been primarily designed to support "batch" style functions that
     process large volumes of information. They have been designed to provide :
 
       -> An optimised way of accumulating aggregate multi-level summary information.

       -> An optimised way of randomly and repeatedly accessing large lists of information
          without the overhead of a database row access (ie: you can load the required
          information into an indexed space at the start of your function and then
          repeatedly (re)access the indexed space more efficiently than you can by
          accessing the DBMS directly).

      For examples of these types of usage please refer to the following examples.

   * An indexed space must have at least one key field/column defined.

   * An indexed space can have at most 20 key fields/columns defined.

   * An indexed space must have at least one non-key field/column defined.

   * An index space can have at most 100 non-key fields/columns defined.

   * The aggregate byte length of all key fields/columns in an indexed space definition
     cannot exceed 16K. Note that if you are coming even remotely close to this limit then
     you should consult your product vendor about application design.

   * The aggregate byte length of all non-key fields/columns in an indexed space definition
     entry cannot exceed 16K. Note that if you are coming even remotely close to this limit
     then you should consult your product vendor about application design.
  
   * The significance of defined keys decreases with the order of their definition.
     Thus the definition string "aaa key(), bbb key(), ccc key(), xxx data(), yyy data()" 
     defines "aaa" as the most significant key and "ccc" as the least significant key.

   * Key definitions can take place at any point in the definition string, but it is customary
     to place them at the beginning.

   * There is no effective limit to how many entries can be place into an indexed space, but
     you must REMEMBER AT ALL TIMES that indexed spaces use allocated system memory. The more
     entries that exist in an index space the more overhead you are placing on the consumption
     of a system resource. References in this section to "no effective limit" actually mean that
     you are effectively constrained by how much memory your system can viably allocate and use.

   * The operations FIRST and NEXT support sequential key order access, however they can only be
     used with indexed spaces where there are less than 32MB / 6 
     entries in the indexed space. This is because the storage of the indexed
     entry's key always takes 6 bytes (regardless of the actual aggregate length of the key fields).

     If you try to use FIRST/NEXT sequential processing on an indexed space that is too large
     to support it you will receive a specific error message and your application will be aborted.

     GET, PUT and INSERT operations are not subjected to this limitation and can be used with
     no effective limit on the number of entries in the indexed space.

   * An indexed space can only be used by the function that creates it. Although you can easily
     pass the identifier (or handle) of an indexed space to another function, any attempt
     by the other function to access the index space may lead to application failure and or
     unpredictable results. Do not attempt to do this. It will not work because when you CREATE
     an indexed space, a unique access plan to data fields stored in the creating function is
     formed. This access plan is unique to the creating function and cannot be effectively used
     by any other RDML function.

   * You should use the DESTROY operation in your functions. However, all indexed spaces created
     by an RDML function are automatically destroyed when it terminates.

   * If you are using multiple definition strings with a CREATE operation please remember that
     trailing blanks are ignored. Therefore :

           USE OV_INDEXED_SPACE (CREATE 'A KEY(), B KEY(), C ' 'KEY(), D DATA(), E DATA()')

     will cause a run time syntax error because the strings will be concatenated to form the
     definition string :

                       A KEY(), B KEY(), CKEY(), D DATA(), E DATA()

   * Indexed space key fields are treated (and sorted) as pure binary data. The indexed space
     has no sense of the definition of a field as alpha, packed, signed, DBCS, etc and will not
     account for this in any operation.

   * The PUT and INSERT operations are significantly different. A PUT operation checks whether
     an entry in the index exists with the specified key already. If it does, it is aggregated and
     updated as appropriate. If it does not exist, then a new entry is created. An INSERT operation
     does not check. It unconditionally creates a new entry.

     This means that if you wish to fill an indexed space from a DBMS table when you know you
     are creating unique entries, then using INSERT is substantially more efficient than using PUT.

   * You can put duplicate keys into an indexed space (ie: 2 or more entries that have exactly
     the same key values) by using the INSERT operation. However, the effects of doing this and/or 
     the order in which the duplicates are processed is unspecified and may vary from platform 
     to platform.

   * The aggregation operations AVG(), MAX(), MIN(), SUM() and COUNT() are all performed with
     a maximum of 15 significant digits of precision.

   * You must not use arrays or array indicies in indexed spaces.