Clarion Community Help

POSITION( sequence )

POSITION returns a STRING which identifies a record's unique position within the sequence. POSITION returns the position of the last record accessed in the file or VIEW. The POSITION procedure is used with RESET to temporarily suspend and resume sequential processing.

FILE usage

The value contained in the returned STRING and the length of that STRING are dependent on the file driver. As a general rule, for file systems that have record numbers, the size of the STRING returned by POSITION(file) is 4 bytes. The return string from POSITION(key) is 4 bytes plus the sum of the sizes of the fields in the key. For file systems that do not have record numbers, the size of the STRING returned by POSITION(file) is generally the sum of the sizes of the fields in the Primary Key (the first KEY on the FILE that does not have the DUP or OPT attribute). The return string from POSITION(key) is the sum of the sizes of the fields in the Primary Key plus the sum of the sizes of the fields in the key.

VIEW usage

The return string for POSITION(view) contains all the information required by the underlying file system to reset to the one specific position within the record set currently in the VIEW. It also contains the file system's POSITION return value for the primary file key and all secondary file linking keys. This allows POSITION(view) to accurately define a position for all related records in the VIEW.

QUEUE usage

POSITION(queue) returns a pointer to the first queue record with a matching key value (for current active sort order). If an exact match is not found, a pointer to the next entry greater to one given in the current queue buffer is returned. If all entries in the queue have a lower key, RECORDS(queue)+1 is returned.

Errors Posted:

Return Data Types:

Example of (POSITION(VIEW)):

ViewO VIEW(Customer)  !Declare VIEW structure
      PROJECT(Cus:AcctNumber,Cus:Name)
       JOIN(Hea:AcctKey,Cus:AcctNumber) !Join Header file
       PROJECT(Hea:OrderNumber)
        JOIN(Dtl:OrderKey,Hea:OrderNumber) !Join Detail file
        PROJECT(Det:Item,Det:Quantity)
         JOIN(Pro:ItemKey,Dtl:Item) !Join Product file
         PROJECT(Pro:Description,Pro:Price)
         END
        END
       END
      END
RecordQue  QUEUE,PRE(Que)
AcctNumber  LIKE(Cus:AcctNumber)
Name        LIKE(Cus:Name)
OrderNumber LIKE(Hea:OrderNumber)
Item        LIKE(Det:Item)
Quantity    LIKE(Det:Quantity)
Description LIKE(Pro:Description)
Price       LIKE(Pro:Price)
          END
SavPosition STRING(260)
  CODE
  OPEN(Customer,22h)
  OPEN(Header,22h)
  OPEN(Detail,22h)
  OPEN(Product,22h)
  SET(Cus:AcctKey)
  OPEN(ViewOrder)                    !Top of file in keyed sequence
  LOOP                               !Read all records in file
   NEXT(ViewOrder)                   !read a record sequentially
   IF ERRORCODE()  
      DO DisplayQue                  !Display the queue
      BREAK
   END
   RecordQue :=: Cus:Record          !Move record into queue
   RecordQue :=: Hea:Record          !Move record into queue
   RecordQue :=: Dtl:Record          !Move record into queue
   RecordQue :=: Pro:Record          !Move record into queue
   ADD(RecordQue)                    !and add it
   ASSERT(~ERRORCODE())
   IF RECORDS(RecordQue) = 20        !20 records in queue?
      DO DisplayQue                  !Display the queue
   END
  END
 
DisplayQue ROUTINE
  SavPosition = POSITION(ViewOrder)!Save record position
  DO ProcessQue                    !Display the queue
  FREE(RecordQue)                  !and free it
  RESET(ViewOrder,SavPosition)     !Reset the record pointer
  NEXT(ViewOrder)                  !and get the record again

Example (POSITION(QUEUE)):

TaxQ   QUEUE
LowPay      DECIMAL(9,2)
HighPay     DECIMAL(9,2)
TaxAmount   DECIMAL(9,2)
PlusPercent DECIMAL(5,2)
      END
Bracket     LONG,AUTO `
  CODE
  SORT(TaxQ, TaxQ.HighPay)         !Set sort order
  TaxQ.HighPay = PayCheck.GrossPay !Initialize QUEUE key field
  Bracket = POSITION(TaxQ)         !Find pay bracket 
  !If Queue was not SORTed, an ERRORCODE 30 will be posted here.
  IF Bracket > RECORDS(TaxQ)       !If value exceeds number of records
     Bracket = RECORDS(TaxQ)       !in QUEUE, set to highest value in QUEUE
  END
  GET(TaxQ,Bracket)                !read QUEUE entry
  Paycheck.Tax = TaxAmount + |     !calculation based on QUEUE entry
    (Paycheck.Gross-TaxQ.LowPay)*TaxQ.PlusPercent

See Also:

RESET

REGET