Click above to get retro games delivered to your door ever month!

N_TBEGIN()


Returns

Logical true if the transaction was started successfully, or false if 
it was not.

Note  If this is a standalone system, N_TBEGIN() will return true.


Description

Begins an explicit TTS transaction. This function must be called before 
any updates are made to transactional files.

Note  Although NetWare's documentation indicates that implicit 
transaction tracking is available for all database applications, that 
is not the case for most xBase applications that, like Clipper, do not 
use physical byte range locking. If you want to be able to back out of 
an aborted transaction, you must initiate explicit transaction 
tracking.

The files for which you want to track transactions must have the 
transactional attribute set On. The transactional attribute can be set 
with the NetWare FLAG command:

FLAG H:\DATA\EMPLOYEE.DBF +T

Or you can set the attribute from within your application by using 
NetLib's N_FATTRSET() function:

N_FATTRSET('H:DATA\EMPLOYEE.DBF', 'TRANSACTION', .T.)

When you mark a data file as transactional, remember to do the same for 
all files that will be involved in the transaction, including any 
associated DBT and NTX files. If the data file is marked transactional 
but the DBT and NTX files are not, a subsequent transaction rollback 
may be incomplete.

Note  A file that has the transactional attribute set On cannot be 
deleted or renamed. The transactional attribute must be set Off before 
a delete or rename operation. This also applies to operations that 
attempt to overwrite an existing file, such as INDEX ON or COPY TO.

We recommend that you conduct transactions by issuing commands in this 
sequence:

1.  Issue N_TSTATUS() at least one time at the start of the application 
    (after the first N_READY(), and before any transactional files 
    are opened). This has the dual effect of informing your program if 
    TTS is active, as well as enabling explicit TTS transactions, which 
    Clipper requires.

2.  Begin the transaction by calling N_TBEGIN().

3.  Lock any records involved in the transaction.

4.  After any changes have been written to disk ( i.e., COMMITted ) 
    release the locks.

5.  End the transaction by calling N_TCOMMIT() or N_TROLLBACK().


Example

N_READY()
N_TIMEOUT(10)
IF !('A' $ N_TSTATUS())
   @ 24, 0 SAY 'Transaction tracking is not active.'
   BREAK
ELSEIF !TranUse('CUSTOMER', 'SHARED')    ;
  .OR. !TranUse('STOCK', 'SHARED')       ;
  .OR. !TranUse('BACKORD', 'EXCLUSIVE')  ;
  .OR. !TranUse('INVOICES', 'EXCLUSIVE') ;
  .OR. !TranUse('ORDERS', 'SHARED')
   BREAK
ENDIF
SET RELATION TO CustID INTO Customer, ;
                PartNo INTO Stock
DO WHILE !EOF()
   DO WHILE !N_TBEGIN()         // Start transaction
   ENDDO
   DO WHILE !RLOCK()            // Lock records
   ENDDO
   DO WHILE !Customer->(RLOCK())
   ENDDO
   DO WHILE !Stock->(RLOCK())
   ENDDO
   nInStock = Stock->Quantity - Orders->Quantity
   IF nInStock >= 0
      SELECT Invoices
      APPEND BLANK
      /*
         Prepare invoice, adjust inventory, and
         place transaction date in customer record
      */
   ELSE
      SELECT BackOrd
      APPEND BLANK
      /*
         Prepare backorder, flag inventory record, and
         place transaction date in customer record
      */
   ENDIF
   COMMIT                       // Write to disk
   UNLOCK ALL                   // Unlock records
   N_TCOMMIT()                  // End Transaction
   /*
      Note that we do not need to wait for the server
      to finish before beginning a new transaction
   */
   SELECT Orders
   SKIP                         // Get another record
ENDDO

FUNCTION TranUse( cDatabase, cMode )
   LOCAL lTryAgain := .T., lSuccess := .F.
   // Check transactional file attribute
   IF TranAttrOn(cDatabase)
      // Try to use the file in the mode specified
      N_BLIP('Opening file ' + cDatabase, 1, 0)
      DO WHILE lTryAgain
         IF N_USE(cDatabase + ' ' + cMode + ' NEW')
            lSuccess = .T.
            lTryAgain = .F.
         ELSE
            // file is not available
            WhoHasIt(cDatabase, cMode)
            @ 5, 0 SAY 'Try again? ' ;
                   GET lTryAgain PICTURE 'Y'
            READ
         ENDIF
      ENDDO
      N_BLIP("")
   ENDIF
RETURN (lSuccess)

FUNCTION TranAttrOn( cFileSpec )
   LOCAL  lTryAgain := .T., lSuccess =: .F.
   IF (N_FATTRGET(cFileSpec, 'TRANSACTION'))
      // Transactional attribute is On
      lSuccess = .T.
   ELSE
      // Attribute is Off
      DO WHILE lTryAgain
         // Try to set it On
         IF N_FATTRSET(cFileSpec, 'TRANSACTION', .T.)
            lSuccess = .T.
            lTryAgain = .F.
         ELSE
            // Set failed, so file is in use
            WhoHasIt(cFileSpec, 'EXCLUSIVE')
            @ 5, 0 SAY 'Try again? ';
                   GET lTryAgain PICTURE 'Y'
            READ
         ENDIF
      ENDDO
   ENDIF
RETURN (lSuccess)

PROCEDURE WhoHasIt( cFileSpec, cMode )
   LOCAL cStations
   IF cMode = 'EXCLUSIVE'
      // Find out who is using the file
      cStations = N_CHECKU(cFileSpec)
   ELSE
      // Find out who has the file locked
      cStations = N_CHECKF(cFileSpec)
   ENDIF
   @ 2, O SAY 'file ' + cFileSpec + ;
   ' is in use or locked by station(s) '
   FOR i = 1 TO LEN(cStations)
      @ 2, COL() + 2 SAY ASC(SUBSTR(cStations, i, 1)
   NEXT
RETURN