Re: User Index APIs - where find REAL reference material?

["Simon Coulter" <shc@xxxxxxxxxxxxxxxxx>]

Hello Dan,

This stuff isn't really that hard.  You do have to read a number of manuals 
because all the 
information isn't in a single place.  Read them, think about what they say, and 
practice.  
That's all.  You may find the following manuals useful:
        OS/400 Object APIs manual (for the User Index APIs of course)
        Machine Interface Functional Reference (explains how each of the MI 
instructions works 
which is helpful because the APIs are simply front-ends for the MI 
instructions.)
        C MI Library Reference (has examples of code using the APIs and MI 
instructions - in C 
but they are fairly clear examples -- C's not like Lisp or APL)

Also useful are the S/38 Functional Concepts and S/38 Functional Reference 
Manual if you can 
find them.  I think there used to be an AS/400 Functional Concepts Manual but I 
can't find a 
reference to it at the moment.

Now to your specific questions:

> Key Insertion: Whether or not the inserts to the index are by key.  The valid
> values are:
>      '0'  No insertion by key
>      '1'  Insertion by key
> 
> Is this asking whether I'll be loading the index in key sequence?  Am I
> confusing the term "insert" with "add"?  (as in "inserting" a new entry in the
> middle of the index vs. "adding" a new entry at the end of the index)

It is asking whether you will be designating part of the entry as the key used 
when inserting 
entries.  You can either treat the whole entry as a unique value or nominate a 
certain length 
from the first byte as the key.  The 'key insertion' creation attribute simply 
builds an index 
that understands the key component.  If you specify '0' you are limited to 
using an insert type 
of '1' when inserting entries with the QUSADDUI API or insinxen MI instruction. 
 If you specify 
'1' you are limited to using insert types '2' and '3'.

> Immediate Update:  Whether or not the updates to the index are written
> synchronously to auxiliary storage on each update to the index.  The valid
> values are:
>      0    No immediate update
>      1    Immediate update
>  Each update to the index is written to auxiliary storage after every insert 
>and
> remove operation.
> 
> What impact does this parameter have?  In the one application, the UI would be
> created and loaded with data.  It would not be updated, i.e., existing entries
> modified or entries added or deleted.

The impact is on performance and reliability.  If '1' is specifed then every 
entry you add to 
the index is forced to DASD therefore improving reliability (the entry won't be 
lost if the 
system fails) at the expense of performance (the DASD write is synchronous and 
your application 
waits until the write completes).  Since you seem to be loading the index from 
some external 
source (DB?) specifying '0' is probably what you require.

> Also, on the Add User Index Entries (QUSADDUI) API, it appears that you can 
>add
> up to 4095 index entries on one call.  Is this correct?  If so, would you
> typically use an array or a multiple-occurence data structure to pass the 
>data?

Yes, that is correct.  The second parameter on the API tells you how many 
entries were 
successfully added.  Since a MODS is currently implemented using contiguous 
storage it would 
work but an array is what is generally expected for fixed length entries.  If 
you are using 
variable length entries then you also must pass a structure of offsets and 
lengths used to 
parse the entry data.

> Those of you who have the answers, where did you learn this?  I certainly have
> failed to find out in the IBM softcopy manuals.

Well, my usual mantra of RTFM applies again.  The information is in the IBM 
manuals but needs 
to be nutted out.  Perhaps I find the IBM manuals easier to read than other 
people but they are 
intended for system programmer's.

Maybe I should write 'A Real Programmer's Guide to the AS/400'?  Any particular 
topics it 
should cover?

Regards,
Simon Coulter.

«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»
«» FlyByNight Software         AS/400 Tec
ical Specialists       «»
«» Eclipse the competition - run your business on an IBM AS/400.  «»
«»                                                                «»
«» Phone: +61 3 9419 0175      Mobile: +61 0411 091 400           «»
«» Fax:   +61 3 9419 0175      mailto: shc@flybynight.com.au      «»
«»                                                                «»
«» Windoze should not be open at Warp speed.                      «»
«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»
//--- forwarded letter -------------------------------------------------------
> Date: Wed, 28 Jul 99 17:37:20 -0400
> From: "Dan Bale" <dbale@genfast.com>
> To: MIDRANGE-L@midrange.com
> Reply-To: MIDRANGE-L@midrange.com
> Subject: User Index APIs - where find REAL reference material?

> I am trying to understand and create my own applications using user indexes, 
>but
> am relegated to using others' examples, which does not help me understand the
> intricacies of the APIs involved.

-------- Stuff deleted ------------------
> 
> TIA,
> Dan Bale
+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---