Understanding Token Numbers in XA Records Tuesday August

Understanding Token Numbers in XA Records Tuesday, August 11, 2009 Presenter: Charles Hood, CISTECH, Inc.

Overview • • Purpose of XA Token Fields XA Files which use a Token Field Data Elements packed into a Token Calling the Token-Generator API Two “Gotchas”! “Potential” Duplicates Special R 7 Consideration

Purpose of XA Token Fields • To ensure that XA applications are able to obtain unique key access to application data that is not necessarily unique • Typically, master files have application data which ensures unique key access, but transaction files may not

XA Files which use a Token Field (1) • Current list (subject to change in future releases) 1. MOMAST (token used in REP Schedules) 2. IMHIST 3. INVTXN 4. PCCTXN 5. OEITXN

XA Files which use a Token Field (2) 6. 7. 8. 9. 10. 11. SLQNTY MOTRAN ITMPRC OPENAR ARHSTS PURACT

Data Elements Packed into a Token (1) • Token fields are 15 character, alphanumeric • The “characters” in a Token field are hexadecimal values comprised of the following: 1. Date/Time 2. Sequence Number 3. System Job Number

Data Elements Packed into a Token (2) • More detail: 1. Date/Time is 13 digits packed into 7 positions 2. Sequence Number is 7 digits packed into 4 positions 3. System Job Number is 6 digits packed into 4 positions

Data Elements Packed into a Token (3) • Sample token from an ITMPRC record: ØbÉdè| jß| (Value in file) 0887854 0001 0954 002144 F 000 F 019 F (Dt/Tm) (Seq#)(Job#)

Calling the Token-Generator API (1) • API Program AMVLN generates tokens to uniquely identify records • A call to AMVLN requires four parameters: 1. 2. 3. 4. (I) (O) (O) Shutdown/process 8 Unique key token 15 Message ID 7 Message data 512 chars

Calling the Token-Generator API (2) • Expected Values for the “Shutdown/process” Input Paramter: 1. *PRC = Process with no program shutdown 2. *PRC_SHT = Process and shutdown 3. *SHT = No processing, just shutdown program

Calling the Token-Generator API (3) • Sample Call to AMVLN: C* CALL TOKEN GENERATOR PGM FOR TOKEN FOR SLQNTY C* C CLEARTKEN C CALL 'AMVLN' C PARM '*PRC 'SHD$P 8 C TKEN PARM *BLANKS TKEN$P 15 C PARM *BLANKS MGID$P 7 C PARM *BLANKS MGDT 1 P C* C WRITESLQNTYSQ

Two “Gotchas”! (1) • First “Gotcha” is due to the ability of modern fast i. Series processors to process a high volume of transactions. • When a U-job was ended and restarted within one second, duplicate tokens were generated because the sequence # was not saved. • This was resolved with a Program fix: XAR 6 PTF 6943 XAR 7 PTF 3640

Two “Gotchas”! (2) • Second “Gotcha” can occur when the i. Series system time is reset (DST, Sync with Atomic Clock, etc. ) • When resetting the system time, be careful! 1. All U-jobs must be ended 2. HLDJOBQ to prevent U-jobs starting 3. Get a Dedicated XA system • The post backup procedure is the best place for nightly updating the system time

“Potential” Duplicates • Currently, AMVLN could generate duplicate Tokens after one century of use • “Older” AMVLN could generate a duplicate key if system processing speed improves to the point that 9, 999 records can be added to a file in one second • “Newer” AMVLN includes the millisecond value in the Sequence Number portion – a theoretical possibility of duplicates still exists

Special R 7 Consideration (1) • In most XA files which use tokens as key fields, the token field is 15 characters alphanumeric; in the R 7 integrator, however, the token field is 30 characters, with a subtype of “Hex” • When a Business Object user exit is activated which uses a file containing a token field as a key field (like Item Location, which uses the SLQNTYL 4 logical), the token comes into the user exit program as a 30 character alphanumeric field

Special R 7 Consideration (2) • XA provides an API program PSVCHS 1 R which will convert a “Hex” field to its alphanumeric equivalent • A call to PSVCHS 1 R requires five parameters: 1. (I) Perform process? 8 chars 2. (I) Shutdown program? 8 chars 3. (I) Hexadecimal value 128 chars 4. (O) Character value 64 chars 5. (O) Message ID 7 chars

Special R 7 Consideration (3) • Sample Call to PSVCHS 1 R : * - P#HXVL Value must be in X’cccc’ format c Eval p#HXVL = ‘X’’’ + u. TKENLQ + ‘’’’ c Call ‘PSVCHS 1 R' c Parm ‘*YES’ P#PFPR 8 c Parm ‘*NO’ P#SHDN 8 c Parm P#HXVL 128 c Parm *blanks P#CHVL 64 c Parm *blanks P#MSID 7 * c Movel p#chvl keyfld 15 c slqnkey Chain SLQTNYL 4

THANK YOU! Charles Hood Charles. hood@cistech. net