Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File3.9  XBRA procedure                                                TOS

The XBRA procedure ("eXtended BRAner") is based on an idea by Moshe 
Braner, and should be used by all programs that redirect vectors.

The principle is that each vector-redirecting program places the 
following structure directly before its own entry address (i.e. just 
before the address to which the vector was set):

typedef struct
{
    int8_t  xb_magic[4];   /* "XBRA" = 0x58425241         */
    int8_t  xb_id[4];      /* ID of four ASCII characters */
    int32_t xb_oldvec;     /* Old value of the vectors    */
} XBRA;

The element xb_magic permits a positive identification of the XBRA 
structure; xb_id is the ID of the particular program that has 
redirected the vector.

With the aid of this procedure it is easy for a program to ascertain 
whether it is already installed (though this can be done also via the 
cookie jar), and to remove itself again from the vector chain. It is 
important, however, that all(!) programs adhere to this procedure, as 
otherwise the vector chain will be interrupted.

Note about MagiC: Programs that hook into any of the system vectors 
should also link themselves into the etv_term vector. If the program 
terminates abnormally, the operating system will jump first via the 
etv_term vector. In such a case one can then calmly draw back from all 
changed vectors; as MagiC uses its own etv_term vector for each 
application, this cannot lead to any collisions.

The XBRA procedure has won recognition over time, so that it's now 
considered bad programming style if one does not use it.

See also: Cookie jar   Cookie and XBRA list   Reset vector