TAA Tools
USRIDX          USER INDEX                             TAAIDXA

The User Index  tool provides an  interface to allow  reading, writing,
updating,  and  deleting entries  from  a user  index.   Several  other
tools  such as CRTUSRIDX also use  interfaces provided by USRIDX.  Only
keyed fixed  length  user indexes  are supported.    The maximum  entry
length is 2000 bytes including the key.

OPM and ILE  users may use a dynamic call to  TAAIDXAR5.  An externally
described  data  structure (TAAIDXAP)  is  the only  parameter  that is
passed which contains fields for  the operation requested and the  data
to be returned.

An  ILE  user  may also  use  a  bound  call.   A  service  program  is
provided.

User Index concepts
-------------------

The system  supports a *USRIDX object.   Both keyed and non-keyed types
are supported (similar to *DTAQ objects)  and the entries may be  fixed
or variable length.   APIs are used to create, read,  write, and delete
entries in a user index.

In some  applications, a program  must read an unknown  amount of data,
place  it into an array,  possibly update some of  the values, and then
sort the array to allow processing in sequence.

If an unknown  amount of data exists,  a typical solution is  to define
an array with  a large number of entries (the RPG  OPM limit is 9,999).
This  can make  functions like RPG's  LOKUP very  slow if  a value does
not exist.  Sorting  an array in  RPG must be  done by placing the  key
in the high order position of each element.

A  *USRIDX object  can simplify  this  type of  processing by  allowing
keyed  operations.   The  data  can  be written  randomly  to  the user
index.  If  updating is required,  random updates may  be made by  key.
To output  the  entries in  sequence, the  program only  needs to  read
sequentially by key.

From an  external perspective, you can consider a  *USRIDX object to be
similar  to a simple data base  work file.  The  key to the entry makes
up the first n  bytes of an entry.   When a user index is  created, you
define the length of the entry and the length of the key.

The system supports a single command to operate on user indexes:

            DLTUSRIDX       Delete user index

The TAA support of *USRIDX objects allows the following commands:

            CRTUSRIDX       Create user index (only keyed fix length)
            CVTUSRIDX       Convert user index entries
            RTVUSRIDXA      Retrieve user index attributes
            DSPUSRIDXA      Display user index attributes
            DSPUSRIDX       Display user index entries
            CLRUSRIDX       Clear user index

Also supported  by TAA are programs  which allow you  to interface from
a  HLL program to cause operations  such as read, write,  etc to a user
index.   This allows  a  typical RPG  programmer to  use a  user  index
without knowledge of the APIs.

For dynamic calls from OPM or ILE, use the TAAIDXAR5 program.

For bound calls from ILE, use the TAAIDXA *SRVPGM.

The TAA support is  limited to keyed fix length  entries and supports a
maximum entry  length of 2000 bytes.  The maximum  size of a user index
may be 4GB.

Sample OPM program
------------------

Sample OPM  programs  are  provided  that will  create  a  user  index,
write, read, update, and delete entries.  To run the programs, enter:

             CALL        PGM(TAAIDXAC6)

A spooled file will be displayed with the results.

The TAAIDXAC6 CL program  creates the MYUSRIDX user index  (*USRIDX) in
QTEMP  and calls  the  TAAIDXAR6 RPG  program.   The  program  writes 3
entries  to the  user index,  retrieves them  in keyed  order, randomly
retrieves an  entry, updates it,  deletes a  different entry, and  then
retrieves the  entries in keyed  order.  A  listing occurs to  show the
results.

After the programs run, you can try out the following commands:

             DSPUSRIDXA  USRIDX(QTEMP/MYUSRIDX)
             CLRUSRIDX   USRIDX(QTEMP/MYUSRIDX)

An  externally described  data  structure is  used to  pass information
the supplied program.   You can  display the format  of the  externally
described data structure with the command:

             DSPFMT      FILE(TAAIDXAP)

To  understand how  you  use the  TAA interface  to  manipulate a  user
index,  the following TXTnn  entries refer to  the corresponding values
within the TAAIDXAR6 RPG OPM source  test program.  You can print  this
program out and  refer to it as you  go thru the discussion.   To print
the code, use:

            DSPTAA    TAAARCMBR(TAAIDXAR6) OUTPUT(*PRINT)

  **   TXT010.    The externally  described  data structure  (TAAIDXAP)
       has  two  fields  which  are larger  than  the  RPG  OPM maximum
       length of 256  bytes.   These two fields  UIDATA and UIMSTX  are
       defined as  arrays to prevent compilation errors.   Using arrays
       requires  the use  of MOVEA when  the fields  are referenced (if
       using ILE  RPG, the arrays  would not  be needed  and the  MOVEA
       operations could be replaced with MOVEL).

  **   TXT020.  The  externally described data structure  (TAAIDXAP) is
       defined and given a name IDXDS.

  **   TXT030.   The sub program  described as USRIDX is  defined to be
       TAAIDXAR5.  This is the  TAA supplied program for programs  that
       will cause operations to  a user index by passing  an externally
       described data structure as the only parameter.

  **   TXT040.   The MSGDS  data structure of  512 bytes is  defined to
       allow use by the TAA Tool SNDDIAG.

  **   TXT050.   In the  TAAIDXAC6 CL program,  the MYUSRIDX user index
       object was created with a  length of 20 and a key length  of 10.
       If you  used the DSPUSRIDXA command  after the call to  the test
       program  (TAAIDXAC6)  you  would  see  this  information.    The
       definition means that each entry  will begin with a 10 byte  key
       and then  have 10 bytes  of data associated  with the key.   The
       MYDS data  structure is defined with  a key of 10  bytes in 1-10
       and data  in 11-20.   Thus  the key  is part  of  the entry  and
       always begins  in the  high order  for the  length defined  when
       the user index was created.

  **   TXT060.   The program moves the name of  the user index and user
       index   library  (MYUSRIDX  in  QTEMP)   to  fields  within  the
       TAAIDXAP  externally  described  data  structure.    The  *WRITE
       operation  code is  requested.   Each entry  to be  written then
       requires  a move of  a key  value and corresponding  data to the
       fields in  the MYDS  data structure.   The  WRITE subroutine  is
       used to write each entry to the user index.

  **   TXT070.   The  WRITE subroutine  moves  the data  from the  MYDS
       data structure  to the UIDATA field  in the externally described
       data structure.   This UIDATA field  is the entry  that will  be
       written to the user index.

       Note that  each time the  program writes to  the user index,  it
       moves  data from the  MYDS data  structure to the  UIDATA field.
       Similarly,  each time  a read occurs,  the returned  entry is in
       UIDATA and is moved  to the MYDS data structure  for processing.

       The  USRIDX program  (TAAIDXAR5) is  called and  the  IDXDS data
       structure  is  passed.   If an  error  occurs, the  UIMSID field
       will not  be  blank.    A  typical error  that  might  occur  is
       CPF3C74 meaning a duplicate key occurred.

  **   TXT080.   The  entries that  were written  will be  sequentially
       read and printed by the READ subroutine.

  **   TXT090.   The 'low value' is  placed into the key  field and the
       MYDS data structure is moved to UIDATA.

  **   TXT100.  The  operations are set  to *READ and  *GT.  Note  that
       you should  use a MOVEL  with padding when  placing data in  the
       UIOPCD and  UISCOD fields.  The call to  USRIDX ignores any data
       in  the data portion of UIDATA.   The key portion of UIDATA (now
       containing 'low  value')  is used  to  access the  first  record
       because *READ *GT was specified.

  **   TXT110.   The UIMSID field must  be checked after each  call.  A
       value  of TAA9891 means that  the entry was  not returned.  When
       a sequential read  is used, TAA9891 means  'end of entries'  and
       the program branches to the end of the subroutine.

       Any other error value causes the program to abort.

  **   TXT120.  If  the UIMSID field is  blank, it means that  an entry
       was placed  in the UIDATA field.  The data  is moved to the MYDS
       data structure for processing.

  **   TXT130.  After the  first entry is  returned, the program  loops
       back to  request the next  entry.  The  USRIDX program uses  the
       value in  the key portion  of the UIDATA field  to determine how
       to  request  the  next entry.    Since the  first  *READ request
       returns the  first  entry,  a request  for  *READ and  *GT  will
       cause the  second entry  by key  to be returned.   Each  time an
       entry is processed, this same loop occurs.

  **   TXT140.   A  random  request will  now be  made to  retrieve the
       '234'  key.   The  key  is  set  to  '234'  and  the  MYDS  data
       structure is moved to the UIDATA field.

  **   TXT150.  The  UIOPCD field is set  for *READ, and *EQ  is placed
       in  the UISCOD field requesting  an equal key.   Note that there
       is probably data  in bytes 11-20  of the UIDATA  field when  the
       call occurs.   This data will be  ignored by a *READ  request to
       the USRIDX program.

  **   TXT160.   The  UIMSID field is  checked for  errors.   Since the
       program  assumes the key  will exist, the  program will abort if
       the message field is non-blank.

  **   TXT170.   If  the UIMSID  field  is blank,  the entry  has  been
       placed  in the  UIDATA field.    It is  moved to  the MYDS  data
       structure for processing.

  **   TXT180.   The entry  that was just  read will be  changed in the
       data portion.   The new  value 'MILLER'  is moved  the the  DATA
       field and  the key ('234').   The  MYDS data structure  is moved
       to UIDATA.

  **   TXT190.   A  request is made  then for  *UPDATE of an  equal key
       (*EQ).

       Note that it  would not have  been necessary to  read the  entry
       first.  The update request requires that a key be named.

       Note there  is no  locking mechanism  to prevent  two jobs  from
       updating  the same  entry at  the same  time.   You  must ensure
       this  such as in  this example by  placing the user  index is in
       QTEMP.  You could  consider locking the user index  with ALCOBJ.

  **   TXT200.  A  check for errors occurs and if  UIMSID is not blank,
       the program will abort.

  **   TXT210.   A delete will now be requested  of key '456'.  The key
       is placed  in  MYDS  and the  data  structure is  moved  to  the
       UIDATA field.

  **   TXT220.  A request  for *DELETE with an *EQ key is  made and the
       USRIDX program  is called.  Note that  there is probably data in
       positions 11-20 of  the UIDATA  field, but this  is ignored  and
       only the key portion is used.

  **   TXT230.  A check  for errors occurs and if UIMSID  is not blank,
       the program will abort.

  **   TXT240.   The READ subroutine is used again  to list the entries
       in sequential order.

  **   TXT250.   The  USRIDX program  is kept  open after each  call to
       allow faster  processing.   To end  the  program with  LR on,  a
       *CLOSE request  is made and the  USRIDX program is  called.  The
       activation  group  used  for the  USRIDX  program  is destroyed.
       Any UIDATA value is  ignored and none is  passed back.  A  check
       for errors occurs  and if UIMSID is not blank,  the program will
       abort.

  **   TXT260.   The SNDERR routine is used any  time there is an error
       in the UIMSID  field that is  not handled by the  program.   For
       example,  the program  considered  a  TAA9891 value  as  meaning
       'end of  entries' when a *READ was  used to process sequentially
       by key.

       To  provide  for  feedback  relating  to  error  conditions, the
       current contents  of IDXDS  (the  data structure  passed to  the
       USRIDX program)  is moved to  the MSGDS data structure  which is
       512  bytes in  length.   The  SNDDIAG TAA  program is  called to
       send the text as  a diagnostic message.   The message will  thus
       describe the  first 512  bytes of the  data structure  last sent
       to the USRIDX program.

       The  SNDDIAG program  is  used again  to send  the  message text
       that was returned  by the  USRIDX program in  the UIMSTX  field.
       The message  will begin  with the  message ID  received from  an
       API (or created by USRIDX) followed by the message text.

       The  program  then  calls  the  TAA  ABORT  program  which  will
       abnormally   terminate  the  program   with  an  escape  message
       (TAA9861).

Format of TAAIDXAP Externally Described Data Structure
------------------------------------------------------

   UINM          The User Index name.  10 bytes in positions 1-10.

   UILIB         The User Index  library name.   10 bytes in  positions
                 11-20.

   UIOPCD        The  Operation  code.   7  bytes  in positions  21-27.
                 The   following   are  valid   (some   operations  are
                 modified by the UISCOD field).

                      *READ - Reads one entry

                      *WRITE - Writes one entry

                      *UPDATE - Updates one entry

                      *DELETE - Deletes one entry

                      *CLEAR - Clears all entries

                      *CLOSE -  Closes the  processing program.    This
                      should be  used when  a program  calls TAAIXDAR5.
                      The    activation   group   for    TAAIXDAR5   is
                      destroyed.

   UISCOD        The Search code.   6  bytes in positions  28-33.   The
                 values  *EQ,  *GT,   *LT,  *GE,  *LE,   *FIRST  (first
                 entry),  and *LAST  (last entry)  are supported.   The
                 search  code is  used with  *READ, *ADD,  *UPDATE, and
                 *DELETE operations.

                 The value is ignored for *CLEAR and *CLOSE.

                 When *FIRST  or *LAST is  specified, the UIDATA  field
                 is ignored.

   UIDATA        The  entry data.    2000 bytes  in positions  34-2033.
                 The  length of the  key portion (high  order bytes) is
                 determined by  accessing the  attributes of  the  user
                 index.  The  length of the data  portion is determined
                 by  subtracting the length  of the key  from the entry
                 length defined for the user index.

                      For *READ  operations, only  the key  portion  is
                      used.   The  data  portion  is  ignored.   If  an
                      entry  is found, both  the key  and the  data are
                      returned.

                      For  *WRITE  operations,  both  the  key  and the
                      data portion are  used.  The  value of UIDATA  is
                      not changed.

                      For  *UPDATE operations,  both  the  key and  the
                      data  portion are used.   The value  of UIDATA is
                      not changed.   Note that it  is valid to  request
                      a  UISCOD value  such as  *GT in  which case  the
                      key  higher than  the  one specified  is updated.
                      The key  of the  entry that  was updated  is  not
                      returned.

                      For *DELETE operations,  only the key  portion is
                      used.  The value of UIDATA is not changed.

                      For  *CLEAR  operations,   the  UIDATA  value  is
                      ignored.

                      For   *CLOSE  operations,  the  UIDATA  value  is
                      ignored.

   UIMSID        The  message   ID  field.     7  bytes  in   positions
                 2034-2040.   This  field  must be  checked after  each
                 operation  to ensure  valid results.   The  user index
                 program does not return escape messages.

                 TAA9891 will be  returned if  no entry is  found on  a
                 *READ,  *UPDATE,  or  *DELETE operation.    Note  that
                 when  reading  sequentially,  TAA9891  means  no  more
                 entries exist ('end of entries').

                 Any error messages  sent from  the APIs  used will  be
                 returned.   For  example,  CPF3C74  is returned  if  a
                 duplicate key  is attempted to be written  by a *WRITE
                 request.

   UIMSDT        The  message  data  field.    256  bytes  in positions
                 2041-2296.   Any  message data  for an  error  message
                 will be placed in this field.

                 For  a *CLEAR  operation, the  number of  entries that
                 were  cleared is  placed in  the first  10 bytes  as a
                 zoned value.

   UIMSTX        The message  text  field.    512  bytes  in  positions
                 2297-2808.   The complete  text of  the message  if an
                 error occurs.

Using an ILE bound program
--------------------------

The  TAAIDXAR98  and TAAIDXAR99  RPG  members contain  the  QUSEC error
data structure  and all  the  prototypes.   Use  CPYTAA as  follows  to
extract the source:

             CPYTAA       TAAARCMBR(TAAIDXAR98)
             CPYTAA       TAAARCMBR(TAAIDXAR99)

This places the source in the QATTRPG file in TAATOOL.

The following items should be in the users source.

       h bnddir('TAATOOL/TAADIXA')
       / copy taatool/qattrpg/TAAIDXAR98
       / copy taatool/qattrpg/TAAIDXAR99

All the  ILE functions are  provided by the  DoUsrIdxOp (do user  index
operation) subprocedure  using parameters for the  fields described for
the  TAAIDXAP data structure.   Note that you do  not need the TAAIDXAP
data structure.

Sample ILE  programs exist  that cause  3 entries  to be  written to  a
user index.  You may try these programs by:

             CALL     TAAIDXAC7

This  creates the  user  index object  and  calls the  RPG ILE  program
TAAIDXAR7.  The DSPUSRIDXA command is used to display the results.

You can review the code with the command:

             DSPTAA   TAAARCMBR(TAAIDXAR7)

Review and recommendations
--------------------------

  **   To  access by key,  you must place  the key in  the UIDATA field
       before doing a read.

  **   If  you  are  using  the  TAAIDXAP  externally   described  data
       structure in  either an  OPM or ILE  program, you  must remember
       to  move your  data (probably  a data  structure) to  the UIDATA
       field before  making  a write  request.   Conversely,  you  must
       remember to move  from the UIDATA  field to your  data (probably
       a data structure) after a successful read operation.

  **   If you  have decimal values,  you probably want to  keep them in
       zoned  format to simplify debugging.   This allows the DSPUSRIDX
       TAA command  to be used  normally without  requesting a  display
       by hex value.

  **   Assuming  you use  a data  structure for  your data,  it  can be
       helpful  to separate  the fields  by a  blank value  to simplify
       reviewing the data with DSPUSRIDX.

Escape messages you can monitor for
-----------------------------------

None.

The call  to the  supplied programs  should  always complete  normally.
You  are responsible  for checking  the UIMSID  field.   If blank,  the
request was successful.

TAA9891  will be  returned  for a  *READ, *UPDATE,  or  *DELETE request
when the key does not  exist (such as no more  entries can be found  to
be read).

Other message IDs may be sent by the APIs used.

Restrictions
------------

Only fixed  length  keyed user  indexes are  supported  with a  maximum
length of 2000 bytes.

The maximum supported size is 4GB.

Prerequisites
-------------

The following TAA Tools must be on your system:

     ABORT           Abort
     CRTUSRIDX       Create user index
     DSPLSTSPLF      Display last spooled file
     DSPUSRIDXA      Display user index attributes
     SNDDIAG         Send diagnostic message
     SNDSTSMSG       Send status message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   TAAIDXAC6     *PGM       CLP         TAAIDXAC6     QATTCL
   TAAIDXAC7     *PGM       CLP         TAAIDXAC7     QATTCL
                            RPGLE       TAAIDXAR      QATTRPG
   TAAIDXAR4     *PGM       RPGLE       TAAIDXAR4     QATTRPG
   TAAIDXAR6     *PGM       RPG         TAAIDXAR6     QATTRPG
   TAAIDXAR7     *PGM       RPGLE       TAAIDXAR7     QATTRPG
   TAAIDXAR98                           TAAIDXAR98    QATTRPG
   TAAIDXAR99                           TAAIDXAR98    QATTRPG
   TAAIDXA       *SRVPGM                TAAIDXAR      QATTRPG
   TAAIDXA       *BNDDIR

TAAIXDAR creates a module for the TAAIDXA *SRVPGM.

The  test  programs  TAAIDXAC6,  TAAIDXAC7,  TAAIDXAR6,  and  TAAIDXAR7
require  the tool  commands (CRTUSRIDX, RTVUSRIDXA,  and DSPUSRIDXA) to
exist.   An escape  message occurs  during the  create if  they do  not
exist stating that  CRTTAATOOL should be used for the  3 tools and then
USRIDX again.
					

Added to TAA Productivity tools June 15, 2004


Home Page Up to Top