4

TRBEGIN

Contents


Trbegin is used to open tables in read/write mode, and defines the start of a transaction.

 

Syntax

   Trbegin decl_fic [ , decl_fic ]

 

Parameters

Element

Description

Restrictions

decl_fic

file

In one command, these descriptions may be mixed for different files.

file

Identification of a file in one of the following forms:
(1) nom_d'OBJet [ class ]
(2) string [ class ]
(4) '=' expr_c [ class ]
(5) class

class indicates the abbreviation for a file.
(5) File class the file must be open

string

Character string constant containing the name of the file.

The file must be accessible.

expr_c

Char type expression whose result is the name of the file.

None.

 

Examples

   # Declaration of the HISTORIQUE file with the abbreviation defined in the
   # parameters, and the CLIENT file with the abbreviation CLI.
    Trbegin HISTORIQUE, CLIENT [CLI]

   # Use of 2 account files from 2 accounting departments COMPTA1
   # and COMPTA2 are names of applications
    Trbegin "COMPTA1.COMPTES" [CPT1], "COMPTA2.COMPTES" [CPT2]

   # Declaration of the same file twice with different abbreviations
   # There can thus be 2 current records for one
   # file, allowing, for example, the file to have links to itself
    Trbegin COMPTES [CPT1], COMPTES [CPT2]

   # Declaration of files identified respectively by an
   # abbreviation (the TOTO file is therefore necessarily already open),
   # the name of an application (GESCOM), a path and a
   # character string type expression.
    Trbegin [TOTO], "GESCOM.CLIENTS", "/usr/adonix/table1", = FIC_SAISI

   # Declaration of 12 files already open.    
    
Trbegin [A1],[A2],[A3],[A4],[A5],[A6],[A7],[A8],[A9],[AA],[AB],[AC]

   # External file
    extfile(3) = "/usr/adonix/TEST"
    File EX3

   # Transaction: debits an account CPT_D and credits an account CPT_C
   # with the same TRANSFERT value. On return from the sub-programme,
   # SUCCES=1 if the operation was successful, otherwise SUCCES=0.

      TRANSFERT_SOMME
       File COMPTE [CPT]  #
   #   Start of transaction
       Trbegin [CPT]
   #
   #   The first account is debited
       Readlock [CPT]NOCPT = CPT_D
       If fstat : Goto ABANDON : Endif
       [CPT]SOLDE -= TRANSFERT
       Rewrite [CPT]
       If fstat : Goto ABANDON : Endif
   #
   #   The second account is credited
       Readlock [CPT]NOCPT = CPT_C
       If fstat : Goto ABANDON : Endif
       [CPT]SOLDE += TRANSFERT
       Rewrite [CPT]
       If fstat : Goto ABANDON : Endif
   #
   #   Validation of the transaction and return.
       Commit : SUCCES = 1
    Return
   #
   #   Transaction cancelled and return in the event of error
    ABANDON
       Rollback : SUCCES = 0
    Return

 

Description and comments

Trbegin is used to declare the tables used in read/write mode in a transaction and to start the transaction, that is a set of operations to update files and/or counters as well as for any lock/unlock operation to be validated globally by the Commit instruction, or cancelled globally by Rollback.

A file may be identified by:

·         its name;

·         the name of an application followed by the character '.' and the name of the table;

·         the abbreviation with which it has already been opened.

If the name is given, a search for the file is first performed in the current application, then if unsuccessful, in the reference applications in succession.

The abbreviation used during operations on this file will be as given in the parameters unless specified in the command. Trbegin.

 

Declaration of an open file (syntax 5)

The syntax Trbegin class is used to redeclare a file opened first with File; this allows the current record, the current selection, and if applicable, the new key to be retained.

 

Declaration of files

The instruction Trbegin creates variable classes [F] and [G] and updates the variables [S]fileabre and [S]filename.

The instruction Trbegin updates the list of tables open adding those defined in the instruction. The tables previously opened by File or Local File shall be "reopened" unless the syntax Trbegin class has been used. The effect of this "reopening" is:

·         to use a new "Adonix" channel. Adonix channels are limited by the adonix variable [S]adxmto that must not exceed 100.

·         to lose any selection operated on the file by a Where clause and any new key defined by an Order By clause.

·         to lose the current record.

But at the end of the transaction – whether finished by Commit or by Rollback, the situation returns as it was before Trbegin.

Warning: this "reopening" does not apply to the Filter instruction: a selection by Filter made on the file "reopened" by Trbegin, will continue to apply to the same file after Commit (or Rollback).

It is forbidden to initiate a transaction if there is one already in progress.

A transaction cannot be validated (or cancelled) except by the routine or sub-programme that initiated it. This applies particularly to a sub-programme called for an error (Onerrgo), in the event of an interrupt (Onintgo) or for disconnection (actihgup) the sub-programme will not be able to perform Commit or Rollback. It should be noted that if one of these routines ends the programme, the current transaction will be automatically cancelled (Rollback).

 

Comments

The table that is first in the instruction becomes the default table. This may be altered by the Default File instruction.

When using the syntax Trbegin nom_d'OBJet, Adonix first assumes that it is a filename then if unsuccessful, tries to find an entry of the same name in the file table.

Since the Oracle tables do not match Unix files, they cannot be opened with a path.

Opening a table takes a certain amount of time in the Oracle database. Thus only essential files shall be opened, and a file already opened shall not be reopened.

An Oracle table may only be opened if it is already connected to the Oracle database.

In Oracle, a table cannot – a priori – be accessed from a database (in the Oracle sense of the term) other than the current database. Conversely, there may be Oracle-specific access authorisation problems.

A transaction may not be initiated within a For… With Lock loop applying to one of the files scanned by the For, since in Oracle, this would immediately cause an exit from the loop.

To delete from memory tables opened by Trbegin, use Close File instructions. But the channels for these tables shall not be closed before the end of the transaction.

After Trbegin, it is deceptive to unlock (a file, a symbol or a record). Unlocks are only effective at the end of the transaction (whether by Commit or by Rollback), and take place automatically. The programmer must be aware that record locks are limited by a database parameter.

If the routine or sub-programme ends without the transaction having been validated or cancelled, it will be cancelled automatically (Rollback). The user will be warned of this.

The update of the database will only be effective when the transaction is validated – if applicable. The new or modified data is not visible to other users, but the deleted data remains.

In all cases, the data (records or counters) on which transactions apply (Write, Rewrite, Delete, Update and counter allocation) are automatically locked. For these reasons, transactions should be written as quickly as possible, and above all, no entry should be made within a transaction since it may remain on hold for an indefinite time.

After Trbegin, it is still possible – though not recommended – to declare new tables; it will then be done in Local mode. They will be automatically closed at the end of the transaction,

 

Associated errors

Error

Description

ERMODE (10)

The file name is not alphanumeric.

TROFIC (29)

Too many files opened at once.

PAFIC (20)

File not found.

ERCLAS ( 7)

Abbreviation not found.

ERREOP (28)

One table opened twice.

ERACCE (27)

File access error (unix rights).

DEJTRAN (49)

There is already a transaction in progress.

 

Associated key words

FILE - COMMIT - ROLLBACK - ADXMTO - DEFAULT - CLOSE - LOCK


CONTENTS


Copyright © Sage 1999 - 2007