Embed Size (px)
Citation preview
Understanding Token Numbers in XA Records
Tuesday, August 11, 2009
Presenter: Charles Hood, CISTECH, Inc.
• 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 R7 Consideration
Overview
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. SLQNTY
7. MOTRAN
8. ITMPRC
9. OPENAR
10. ARHSTS
11. 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
002144F 000F 019F
(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. (I) Shutdown/process 8 chars
2. (O) Unique key token 15 chars
3. (O) Message ID 7 chars
4. (O) 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 MGDT1P
C*
C WRITESLQNTYSQ
Two “Gotchas”! (1)
• First “Gotcha” is due to the ability of modern fast iSeries 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:
XAR6 PTF 6943
XAR7 PTF 3640
Two “Gotchas”! (2)
• Second “Gotcha” can occur when the iSeries 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,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 R7 Consideration (1)• In most XA files which use tokens as key fields,
the token field is 15 characters alphanumeric; in the R7 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 SLQNTYL4 logical), the token comes into the user exit program as a 30 character alphanumeric field
Special R7 Consideration (2)• XA provides an API program PSVCHS1R which
will convert a “Hex” field to its alphanumeric equivalent
• A call to PSVCHS1R 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 R7 Consideration (3)• Sample Call to PSVCHS1R :
* - P#HXVL Value must be in X’cccc’ format
c Eval p#HXVL = ‘X’’’ + uTKENLQ + ‘’’’
c Call ‘PSVCHS1R'
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 SLQTNYL4
