gnucash/src/doc/design/engine.texinfo

@node Engine, Register, Top Level, Top
@chapter Engine
@cindex The Engine

The Engine provides an interface to a financial engine with three basic
financial entities: Accounts, Transactions (known as Journal Entries in
accounting practice), and Splits (known as Ledger Entries). These three
entities are the central data structures of the GnuCash financial data
model.

In addition, the Engine provides the abstraction of Account Groups
(collections of releated accounts) and Sessions. A Session abstracts
a file-editing session allowing transparent support for locking and
implementation with other backends such as SQL.

The Engine code contains no GUI code whatsoever and is designed to
be created as a shared library for use by other programs.

@menu
* Engine Introduction::         
* Using and Extending the Engine API::  
* Globally Unique Identifiers::  
* Key-Value Pair Frames::       
* Splits::                      
* Transactions::                
* Accounts::                    
* Account Groups::              
* Sessions::                    
@end menu


@node Engine Introduction, Using and Extending the Engine API, Engine, Engine
@section Introduction

Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
accounting units. Each Split consists of a quantity (number of dollar
bills, number of shares, etc.), the price of that quantity (the price of
one dollar is 1.00 dollars, etc.), a Memo, a pointer to the parent
Transaction, a pointer to the debited Account, a reconciled flag and
timestamp, an "Action" field, and a key-value frame which can store
arbitrary data (@pxref{Key-Value Pair Frames}).

Transactions (@pxref{Transactions}) embody the notion of "double entry"
accounting. A Transaction consists of a date, a description, a number, a
list of one or more Splits, and a key-value frame. When double-entry
rules are properly enabled in the engine (they are settable with various
flags), the total value of the splits is forced to be zero.  Note that
if there is just one split, its value must be zero; this is useful
because a zero-valued split can store a price (useful for e.g. tracking
stocks). If there are two splits, then the value of one must be
positive, the other negative: this denotes that one account is credited,
and another is debited by an equal amount. Positive Split values are
'debits' and negative Split values are 'credits'. Forcing the Splits to
'add up' to zero causes a double-entry accounting system to always
balance.

Through various flags, forced double-entry can be disabled; this is
often desirable for novice, home-oriented users. As an alternative, it
may be better to leave double-entry enabled, but credit all dangling
splits to some dummy account, and then simply not show that dummy
account to the user.

Note the sum of the values of Splits in a Transaction is always computed
with respect to a currency; thus splits can be balanced even when they
are in different currencies, as long as they share a common currency.
The conversion price is simply the price stored in the Split. This
feature allows currency-trading accounts to be established.

Every Split must point at its parent Transaction, and that Transaction
must in turn include that Split in the Transaction's list of Splits. A
Split can belong to at most one Transaction. These relationships are
forced by the engine. The engine user cannnot accidentally destroy this
relationship as long as they stick to using the API and never access
internal structures directly.

Splits are grouped into Accounts (@pxref{Accounts}) which are also known
as "Ledgers" in accouting practice. Each Account consists of a list of
Splits that debit that Account. To ensure consistency, if a Split points
at an Account, then the Account must point at the Split, and vice-versa.
A Split can belong to at most one Account. Besides merely containing a
list of Splits, the Account structure also give the Account a name, a
code number, description and notes fields, a key-value frame, a pointer
to the currency that is used for all splits in this account, and a
pointer to the "security" used for all splits in this account. The
"security" can be the name of a stock (e.g. "IBM", "McDonald's"), or
another currency (e.g. "USD", "GBP").  The security is used during
Transaction balancing to enable trading between accounts denominated in
different currencies, or to, for example, move stocks from one Account
to another.

Accounts can be arranged in a hierarchical tree. The nodes of the tree
are called "Account Groups" (@pxref{Account Groups}). By accounting
convention, the value of an Account is equal to the value of all of its
Splits plus the value of all of its sub-Accounts.


@node Using and Extending the Engine API, Globally Unique Identifiers, Engine Introduction, Engine
@section Using and Extending the Engine API

Engine API calls are named using a specific convention. For example,
the function to access the Memo field of a Split is
@code{xaccSplitGetMemo}.  The prefix @code{xacc} comes
first@footnote{The @code{xacc} prefix is a historical artifact. GnuCash
was derived from X-Accountant by Robin Clark.}, followed by the name of
the entity for which the API call applies (@code{Split}), followed by
the action performed by the call (@code{Get}), followed by the name of
the field being accessed (@code{Memo}). Future API calls should conform
to this naming convention.

The formal arguments to Engine API calls always begin with the entity to
which the call applies. Thus, the arguments to @code{xaccSplitSetMemo}
are the @code{Split} pointer followed by the pointer to a memo
string. Future API calls should also conform to this convention.

Engine API calls should be implemented to behave as gracefully as
possible with unexpected input. Specifically, public API calls should
gracefully handle @code{NULL} pointer arguments. User code should be
able to handle @code{NULL} return values from Engine calls as well.


@node Globally Unique Identifiers, Key-Value Pair Frames, Using and Extending the Engine API, Engine
@section Globally Unique Identifiers
@cindex Globally Unique Identifier
@tindex GUID

It is common for Engine structures to reference other Engine structures.
For example, an Account must reference its Splits, its parent Account
Group, and its child Account Group. Furthermore, other GnuCash modules
may need to reference Engine structures. For example, a GUI
implementation may wish to save a list of Accounts which the user has
open when the application exits in order to restore that same state upon
the next invocation.

One way to uniquely identify an Engine structure, at least while the
program is running, is using the C pointer which points to the
structure. C pointers have the advantage of speed, but also have some
disadvantages:

@itemize

@item
Pointers cannot be used in data files and are not persistant across
different program invocations.

@item
When an entity is destroyed, every other structure which references that
entity through a direct pointer must be immediately updated to prevent
illegal accesses.

@end itemize

The @dfn{GUID} (Globally Unique Identifier) provides a way to reference
Engine structures that is more flexible than C pointers. Each Engine
structure has an associated GUID which can be used to reference that
structure. Engine GUIDs have the following features:

@itemize

@item
The GUID is permanent, i.e., it persists between invocations of GnuCash.

@item
The GUID is guaranteed to be unique with the set of all Splits,
Transactions, and Accounts in the hierarchy of which the structure
is a member.

@item
With very high probability, the GUID is unique among all GUIDs
created by any invocation of GnuCash, all over the world.

@item
GUIDs can be efficiently encoded in a string representation.

@end itemize


@menu
* When to use GUIDs::           
* GUID Types::                  
* How to use GUIDs::            
* GUIDs and GnuCash Entities::  
* The GUID Generator::          
@end menu

@node When to use GUIDs, GUID Types, Globally Unique Identifiers, Globally Unique Identifiers
@subsection When to use GUIDs
@cindex When to use GUIDs

Although GUIDs are very flexible, the engine structures like Accounts
will probably continue to use C pointers for the forseeable future,
since they are much faster (and in certain respects more convenient)
than using GUIDs. In general, however, it is much safer to use GUIDs.
In particular, you should consider using GUIDs if any of the following
is true:

@itemize

@item
You need to save a reference to an engine structure in a file.

@item
You need to save a reference to an engine structure that could
be deleted in between accesses to the saved reference.

@end itemize


@node GUID Types, How to use GUIDs, When to use GUIDs, Globally Unique Identifiers
@subsection GUID Types
@tindex GNCIdType

The GUIDs in GnuCash are typed using the enum @code{GNCIdType}.
Possible values and their meanings for GUID types are:

@table @code

@item GNC_ID_NONE
The GUID does not currently refer to a GnuCash entity, though it
could refer to one in the future.

@item GNC_ID_NULL
The GUID does not, and never will, refer to a GnuCash entity.

@item GNC_ID_ACCOUNT
The GUID refers to an Account (@pxref{Accounts}).

@item GNC_ID_TRANS
The GUID refers to a Transation (@pxref{Transactions}).

@item GNC_ID_SPLIT
The GUID refers to a Split (@pxref{Splits}).

@end table

@deftypefun GNCIdType xaccGUIDType (const GUID * @var{guid})
Return the type associated with @var{guid}.
@end deftypefun

@deftypefun {const GUID *} xaccGUIDNull (void)
Return a GUID which is guaranteed to always have type @code{GNC_ID_NULL}.
@end deftypefun


@node How to use GUIDs, GUIDs and GnuCash Entities, GUID Types, Globally Unique Identifiers
@subsection How to use GUIDs

The Engine API functions which access the GUID for a specific entity
return a pointer to the GUID. @strong{Note:} Do not store the pointer
itself! Instead, store a copy of the GUID. Storing the pointer itself
would present some of the same problems as using the account pointer
directly. Example:

@example
@{
  GUID saved_guid;
  Account *account;

  account = < something to get an Account pointer >

  saved_guid = *xaccAccountGetGuid(account);

  ...

  account = xaccAccountLookup(&saved_guid);

  ...
@}
@end example

You can compare two GUIDs for equality with the following function.

@deftypefun gboolean guid_equal(const GUID * @var{guid_1}, const GUID * @var{guid_2})
Compare two guids and return TRUE if they are both non-NULL and equal.
@end deftypefun


You can encode and decode GUIDs and their string representations using the
next two functions.

@deftypefun {char *} guid_to_string(const GUID * @var{guid})
Return a null-terminated string encoding of @var{guid}. String encodings
of identifiers are hex numbers printed only with the characters @code{0}
through @code{9} and @code{a} through @code{f}.  The encoding will
always be @code{GUID_ENCODING_LENGTH} characters long. The returned
string should be freed when no longer needed.
@end deftypefun

@deftypefun gboolean string_to_guid(const char * @var{string}, GUID * @var{guid})
Given a string, decode an id into @var{guid} if @var{guid} is
non-NULL. The function returns TRUE if the string was a valid 32
character hexadecimal number. This function accepts both upper and lower
case hex digits. If the return value is FALSE, the effect on @var{guid}
is undefined.
@end deftypefun


@node GUIDs and GnuCash Entities, The GUID Generator, How to use GUIDs, Globally Unique Identifiers
@subsection GUIDs and GnuCash Entities

This section documents a low-level API for associating entities with
GUIDs. User code and general engine code should not use this API;
instead use the API documented in the sections for the specific GnuCash
entities such as Accounts and Transactions.

@deftypefun void xaccGUIDNew(GUID * @var{guid})
Generate a new guid. This function is guaranteed to return a guid that
is unique within the scope of all GnuCash entities being managed by the
the current invocation of GnuCash. GnuCash routines should always use
this function and not @code{guid_new}!
@end deftypefun

@deftypefun {void *} xaccLookupEntity(const GUID * @var{guid}, GNCIdType @var{entity_type})
Lookup an entity given an id and a type. If there is no entity
associated with the id, or if it has a different type, NULL is returned.
@end deftypefun

@deftypefun void xaccStoreEntity(void * @var{entity}, const GUID * @var{guid}, GNCIdType entity_type)
Store the given entity under the given id with the given type.
@end deftypefun

@deftypefun void xaccRemoveEntity(const GUID * @var{guid})
Remove any existing association between an entity and the given id. The
entity is not changed in any way.
@end deftypefun


@node The GUID Generator,  , GUIDs and GnuCash Entities, Globally Unique Identifiers
@subsection The GUID Generator
@cindex The GUID Generator

GUIDs are created by the GUID generator. The API for this generator is
low-level and should not be used by user-code.

@deftypefun void guid_init (void)
Initialize the GUID generator with a variety of random sources including
common system files and /dev/random.
@end deftypefun

@deftypefun void guid_init_with_salt (const void * @var{salt}, size_t @var{salt_len})
Initialize the GUID generator with guid_init() and with the given
sequence of arbitrary binary data.
@end deftypefun

@deftypefun void guid_init_only_salt (const void * @var{salt}, size_t @var{salt_len})
Initialize the GUID generator using only the given sequence of arbitrary
binary data. This provides a way to reliably obtain a given sequence of
GUIDs.
@end deftypefun

@deftypefun void guid_new (GUID * @var{guid})
Create a new GUID and store it in @var{guid}. This is a low-level function!
GnuCash code should use @code{xaccGUIDNew}.
@end deftypefun


@node Key-Value Pair Frames, Splits, Globally Unique Identifiers, Engine
@section Key-Value Pair Frames
@cindex Key-Value Pairs

The number and types of data items which are associated with the
financial abstractions (Accounts, Transactions, and Splits) can vary
widely. For example, an Account which represents a user's checking
account might need to store the bank name, a telephone number, and a
username for online banking purposes. Another Account representing the
user's ownership of a stock might need to store information about
retrieving price quotes online such as the ticker symbol and the
exchange.

To meet this need for varying data storage, the GnuCash accounting
entities use Key-Value Pair Frames (hereafter referred to as the
datatype @code{kvp_frame}). A @code{kvp_frame} is a set of associations
between character strings (keys) and @code{kvp_value} structures. A
@code{kvp_value} is a union with possible types enumerated in the
@code{kvp_value_t} enum which indicates the type of data stored in a
@code{kvp_value} object.

@menu
* Key-Value Policy::            
* kvp_frame::                   
* kvp_value::                   
* kvp_list::                    
@end menu


@node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
@subsection Key-Value Policy
@cindex Key-Value Policy

This section defines the policy that programmers should follow
when using key-value pairs to store information. Because of the
large amount of information which can potentially be stored using
this mechanism, it is important to follow these guidelines so
that order will be maintained.

The following rules should be followed for using key-value pairs:

@itemize

@item
The document @file{src/engine/kvp_doc.txt} should be used to document the
use of keys and values. Please consult this document before planning any
use of new keys.

@item
Key strings should be in all lower case with the '-' character
separating words. If possible, use only alphanumeric characters and
'-'. Example: @code{bank-info}. Because the '/' character is useful for
describing keys in sub-frames (@code{bank-info/routing-number}), do not
use the '/' character in key names.

@item
Favor longer, descriptive key strings over short ones. Example:
@code{online-banking-info} is better than @code{onln-bnk}.

@item
Make use of the fact that frames can be stored in frames. If a group
of keys are used for a related purpose, consider storing them together
in a sub-frame.

@item
Values should generally not be accessed directly through keys, but
should rather be accessed through specific API calls. The API calls
do not necessarily need to part a part of the Engine API. For example,
the GUI would probably define keys that the Engine does not need to
know about.

@item
The same key should not be used for different engine structures (Accounts,
Transactions, Splits), unless the key's value has the same type and the
same basic purpose.

@end itemize


@node kvp_frame, kvp_value, Key-Value Policy, Key-Value Pair Frames
@subsection kvp_frame
@tindex kvp_frame

A @code{kvp_frame} is the datatype used to associate key strings with
@code{kvp_value} objects (@pxref{kvp_value}).

@deftypefun kvp_frame* kvp_frame_new (void)
Create and initialize a new @code{kvp_frame} object and return
a pointer to it.
@end deftypefun

@deftypefun void kvp_frame_delete(kvp_frame * @var{frame})
Free all memory associated with @var{frame}.
@end deftypefun

@deftypefun kvp_frame* kvp_frame_copy(const kvp_frame * frame)
Return a deep copy of @var{frame}.
@end deftypefun

@deftypefun void kvp_frame_set_slot(kvp_frame * @var{frame}, const char * @var{key}, const kvp_value * @var{value})
Associate @var{key} with @var{value} in @var{frame}.
@end deftypefun

@deftypefun kvp_value* kvp_frame_get_slot(kvp_frame * @var{frame}, const char * @var{key})
Return the @code{kvp_value} object associated with @var{key}
in @var{frame} or return @code{NULL} if there is no association
for @var{key}. The value returned is not a copy.
@end deftypefun


@node kvp_value, kvp_list, kvp_frame, Key-Value Pair Frames
@subsection kvp_value
@tindex kvp_value
@tindex kvp_value_t

The @code{kvp_value} object stores the 'value' part of a key-value
association in a @code{kvp_frame} object.

@deftypefun void kvp_value_delete(kvp_value * @var{value})
Free all of the memory associated with @var{value}.
@end deftypefun

@deftypefun kvp_value* kvp_value_copy(const kvp_value * @var{value})
Return a deep copy of @var{value}.
@end deftypefun

@deftypefun kvp_value_t kvp_value_get_type(const kvp_value * @var{value})
Return the type of value stored in @var{value}.
@end deftypefun

A @code{kvp_value_t} enum must have one of the following values:

@table @code

@item KVP_TYPE_NONE
Indicates the abscence of a value in a @code{kvp_frame}.

@item KVP_TYPE_INT64
A @code{gint64} value.

@item KVP_TYPE_FLOAT64
A @code{double} value.

@item KVP_TYPE_STRING
A @code{char *} value of arbitrary length.

@item KVP_TYPE_GUID
A @code{GUID} value. @xref{Globally Unique Identifiers}.

@item KVP_TYPE_BINARY
Arbitrary binary data.

@item KVP_TYPE_LIST
A @code{kvp_list} item which contains a list of @code{kvp_value} items.

@item KVP_TYPE_FRAME
A @code{kvp_frame} object. Thus, frames may contain other frames in a
recursive manner.

@end table

@subsubsection Value Constructors

The following functions create and return @code{kvp_value} objects with
particular values. In the case of pointer arguments, deep copies are
performed.

@deftypefun kvp_value* kvp_value_new_int64(gint64 @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_float64(double @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_string(const char * @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_guid(const GUID * @var{guid})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_binary(const void * @var{data}, int @var{datasize})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_list(const kvp_list * @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_frame(const kvp_frame * @var{value});
@end deftypefun

@subsubsection Value Accessors

The following functions access the value of a given @code{kvp_value}
object. If the type of the object does not correspond to that named
in the function, @code{NULL}, @code{0}, or @code{0.0} is returned
as appropriate.

@deftypefun gint64 kvp_value_get_int64(const kvp_value * @var{value})
@end deftypefun
@deftypefun double kvp_value_get_float64(const kvp_value * @var{value})
@end deftypefun
@deftypefun char* kvp_value_get_string(const kvp_value * @var{value})
@end deftypefun
@deftypefun GUID* kvp_value_get_guid(const kvp_value * @var{value})
@end deftypefun
@deftypefun void* kvp_value_get_binary(const kvp_value * @var{value}, int * @var{size_return})
@end deftypefun
@deftypefun kvp_list* kvp_value_get_list(const kvp_value * @var{value})
@end deftypefun
@deftypefun kvp_frame* kvp_value_get_frame(const kvp_value * @var{value})
@end deftypefun


@node kvp_list,  , kvp_value, Key-Value Pair Frames
@subsection kvp_list
@tindex kvp_list

A @code{kvp_list} object abstract a list of @code{kvp_value} objects.

@deftypefun kvp_list* kvp_list_new()
Return a newly allocated @code{kvp_list} object.
@end deftypefun

@deftypefun void kvp_list_delete(kvp_list * @var{list})
Free all memory associated with @var{list}, including the
@code{kvp_value} objects in @var{list}.
@end deftypefun

@deftypefun kvp_list* kvp_list_copy(const kvp_list * @var{list})
Return a deep copy of @var{list}.
@end deftypefun

@deftypefun gboolean kvp_list_null_p(const kvp_list * @var{list})
Return @code{TRUE} if @var{list} is the empty list.
@end deftypefun

@deftypefun kvp_value* kvp_list_car(kvp_list * @var{list})
If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
Otherwise, return the first @code{kvp_value} object in the list.
@end deftypefun

@deftypefun kvp_list* kvp_list_cdr(kvp_list * @var{list})
If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
Otherwise, return a @code{kvp_list} object consisting of @var{list}
with the first value removed. NOTE: the returned list is not a copy!
@end deftypefun

@deftypefun kvp_list* kvp_list_cons(kvp_value * @var{car}, kvp_list * @var{cdr})
If either @var{car} or @var{cdr} is @code{NULL}, return @code{NULL}. Otherwise,
return a @code{kvp_list} object consisting of the value of @var{car} followed
by the values of @var{cdr}. This function uses 'hand-over' semantics, i.e.,
the arguments @var{car} and @var{cdr} are no longer the responsibility of
the caller and should not be accessed after the function returns.
@end deftypefun


@node Splits, Transactions, Key-Value Pair Frames, Engine
@section Splits
@tindex Split

A Split is the Engine abstraction of an accounting entry in an Account
Ledger. In accounting terms, a Split is a Ledger Entry. As such, it
contains the following pieces of information:

@table @asis

@item A parent Account
The Account of which it is an entry.

@item A parent Transaction.
In accounting terms, this is the Journal Entry which this Ledger Entry
is linked to.

@item A 'share quantity'
This is the number of 'shares' which have been debited to the parent
Account. This quantity may be negative, in which case the Split
represents a 'credit'. Shares are given in units of the security of the
Account, unless the security field is blank, in which case shares are
given in units of the Account currency. @xref{Accounts}.

@item A 'price'
This represents the price of the shares. The price is a ratio of the
parent Account currency to the parent Account security. For most Accounts,
the security is blank, and thus the price is @code{1.0}, since the currency
effectively is the security. @xref{Accounts}.

@item A 'reconciled' flag
This flag represents the reconciled status of the Split. Possible
reconciliation states for a Split are:

  @table @asis

  @item Not Reconciled
  The Split has not been reconciled or cleared.

  @item Cleared
  The Split has been cleared, but not reconciled.

  @item Reconciled
  The Split has been reconciled with a statement.

  @item Frozen
  The Split has been frozen into the accounting period.

  @end table

@end table

In addition to the above, Splits contain a Memo field, an Action field,
and a key-value pair frame. The Memo and Action fields are for arbitrary
user input.


@menu
* General Split API::           
* Split Getters::               
* Split Setters::               
@end menu

@node General Split API, Split Getters, Splits, Splits
@subsection General Split API

@deftypefun {Split *} xaccMallocSplit (void)
Allocate, initialize, and return a new Split.
@end deftypefun

@deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
Return the GUID of @var{split}.
@end deftypefun 

@deftypefun {Split *} xaccSplitLookup (const GUID * @var{guid})
Return the split associated with @var{GUID}, or @code{NULL} if there is
no such split.
@end deftypefun

@deftypefun {kvp_value *} xaccSplitGetSlot(Split * @var{split}, const char * @var{key})
Return the @code{kvp_value} associated with @var{key} in @var{split}.
If there is none, @code{NULL} is returned.
@end deftypefun

@deftypefun void xaccSplitSetSlot(Split * @var{split}, const char * @var{key}, const kvp_value * @var{value})
Associate a copy of @var{value} with @var{key} in @var{split}.
@end deftypefun


@node Split Getters, Split Setters, General Split API, Splits
@subsection Split Getters

@deftypefun {Account *} xaccSplitGetAccount (Split * @var{split})
Return the parent Account of @var{split}.
@end deftypefun

@deftypefun {Transaction *} xaccSplitGetParent (Split * @var{split})
Return the parent Transaction of @var{split}.
@end deftypefun

@deftypefun double xaccSplitGetShareAmount (Split * @var{split})
Return the 'share quantity' of @var{split}.
@end deftypefun

@deftypefun double xaccSplitGetSharePrice (Split * @var{split})
Return the 'share price' of @var{split}.
@end deftypefun

@deftypefun double xaccSplitGetValue (Split * @var{split})
Return the value of @var{split}, which is equal to the share quantity
multiplied by the share price.
@end deftypefun

@deftypefun double xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
Return either the share quantity or the value of @var{split}, depending
upon whether @var{base_currency} matches the security or currency of the
parent Account, respectively. No other value for @var{base_currency} is
legal.
@end deftypefun

@deftypefun char xaccSplitGetReconcile (Split * @var{split})
Return the value of the reconcile flag in @var{split}. Possible
values for the flag are:

  @table @code

  @item NREC
  Not Reconciled

  @item CREC
  Cleared

  @item YREC
  Reconciled

  @item FREC
  Frozen

  @end table

@end deftypefun

@deftypefun void xaccSplitGetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
Fill @var{ts} with the reconciled date of @var{split}.
@end deftypefun

@deftypefun {const char *} xaccSplitGetMemo (Split * @var{split})
Return the Memo field of @var{split}.
@end deftypefun

@deftypefun {const char *} xaccSplitGetAction (Split * @var{split})
Return the Action field of @var{split}.
@end deftypefun

@deftypefun double xaccSplitGetBalance (Split * @var{split})
Return the balance of @var{split}'s parent Account up to and including
@var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun double xaccSplitGetClearedBalance (Split * @code{split})
Return the cleared balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun double xaccSplitGetReconciledBalance (Split * @code{split})
Return the reconciled balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun double xaccSplitGetShareBalance (Split * @var{split})
Return the share balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun double xaccSplitGetShareClearedBalance (Split * @code{split})
Return the share cleared balance of @var{split}'s parent Account up to
and including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun double xaccSplitGetShareReconciledBalance (Split * @code{split})
Return the share reconciled balance of @var{split}'s parent Account up
to and including @var{split}. See @ref{Accounts} for details.
@end deftypefun


@node Split Setters,  , Split Getters, Splits
@subsection Split Setters

@deftypefun void xaccSplitSetMemo (Split * @var{split}, const char * @var{memo})
Set the memo field of @var{split} to @var{memo}.
@end deftypefun

@deftypefun void xaccSplitSetAction (Split * @var{split}, const char * @var{action})
Set the action field of @var{split} to @var{memo}. The action field is
an arbitrary string, but is intended to be conveniently limited to a
menu of selections such as "Buy", "Sell", "Interest", etc.
@end deftypefun

@deftypefun void xaccSplitSetReconcile (Split * @var{split}, char @var{reconciled_flag})
Set the reconciled flag of @var{split} to @var{reconciled_flag}. For the
possible values and meanings of @var{reconciled_flag}, see @ref{Split Getters}.
@end deftypefun

@deftypefun void xaccSplitSetDateReconciledSecs (Split * @var{split}, time_t @var{time})
Set the reconciliation date of @var{split} to @var{time}.
@end deftypefun

@deftypefun void xaccSplitSetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
Set the reconciliation date of @var{split} to @var{ts}.
@end deftypefun

@deftypefun void xaccSplitSetShareAmount (Split * @var{split}, double amount)
Set the share quantity of @var{split} to @var{amount}.
@end deftypefun

@deftypefun void xaccSplitSetSharePrice (Split * @var{split}, double @var{price})
Set the share price of @var{split} to @var{price}.
@end deftypefun

@deftypefun void xaccSplitSetSharePriceAndAmount (Split * @var{split}, double @var{price}, double @var{amount})
Set both the share price and share quantity of @var{split}. This routine
is more efficent than calling @code{xaccSplitSetShareAmount} and
@code{xaccSplitSetSharePrice} in succesion, because the parent Transaction
is only rebalanced once. @xref{Transactions}.
@end deftypefun

@deftypefun void xaccSplitSetValue (Split * @var{split}, double @var{value})
Adjust the share quantity of @var{split} so that @var{split}'s value is
equal to @var{value}.
@end deftypefun

@deftypefun void xaccSplitSetBaseValue (Split * @var{split}, double @var{value}, const char * @var{base_currency})
Set either the share quantity or value of @var{split} depending upon
whether @var{base_currency} is the security or current of @var{split}'s
parent Account. @xref{Accounts}.
@end deftypefun


@node Transactions, Accounts, Splits, Engine
@section Transactions
@tindex Transaction

A Transaction is the Engine abstraction of an accounting entry in a
Journal. In accounting terms, a Transaction is a Journal Entry. As
such, it contains the following pieces of information:

@table @asis

@item A list of Ledger Entries, or Splits
The list of debits and credits which make up this Transaction. As in
accounting, a Transaction is balanced when the sum of the debits equals
the sum of the credits.

@item The entry date
The date the transaction was entered into GnuCash.

@item The post date
The date the transaction was posted. This is often the date the
transaction was recorded by the bank, or the date the user initiated
the transaction (i.e., wrote the check, made the ATM withdrawal).

@item A transaction number field
This field is intended to hold a transaction number, such as a
check number or an ID assigned by a bank to an electronic transfer.

@item A description
A textual description of the transaction.

@end table

In addition to the above, Transactions contain a key-value pair frame.


@subsection The Transaction Edit Cycle

The Engine supports (and, in fact, requires) a 2-phase commit/rollback
cycle for modifying Transactions and their constituent Splits. A Transaction
must be opened for editing using @code{xaccTransBeginEdit()} before any of
the following actions may be taken.

@itemize

@item
Modifying any field of a Transaction.

@item
Modifying any Split belonging to the Transaction. That includes
re-parenting a Split to a different Account or a different Transaction.
In the case of re-parenting to a new Transaction, both Transactions must
be opened for editing.

@item
Deleting any Split belonging to the Transaction.

@item
Adding a Split to the transaction.

@item
Deleting the Transaction.

@end itemize

After the desired changes have been made, they must either be committed
using @code{xaccTransCommitEdit()} or rolled back using
@code{xaccTransRollbackEdit()}. Rolling back a transaction will undo any
changes which have been made to it or to its Splits since it was opened
for editing.


@menu
* General Transaction API::     
* Transaction Getters::         
@end menu


@node General Transaction API, Transaction Getters, Transactions, Transactions
@subsection General Transaction API

@deftypefun {Transaction *} xaccMallocTransaction (void)
Allocate, initialize, and return a new Transaction.
@end deftypefun

@deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
Return the GUID of @var{trans}.
@end deftypefun 

@deftypefun {Transaction *} xaccTransLookup (const GUID * @var{guid})
Return the Transaction associated with @var{GUID}, or @code{NULL} if
there is no such Transaction.
@end deftypefun

@deftypefun {kvp_value *} xaccTransGetSlot(Transaction * @var{trans}, const char * @var{key})
Return the @code{kvp_value} associated with @var{key} in @var{trans}.
If there is none, @code{NULL} is returned.
@end deftypefun

@deftypefun void xaccTransSetSlot(Split * @var{trans}, const char * @var{key}, const kvp_value * @var{value})
Associate a copy of @var{value} with @var{key} in @var{trans}.
@end deftypefun


@node Transaction Getters,  , General Transaction API, Transactions
@subsection Transaction Getters

@deftypefun {Split *} xaccTransGetSplit (Transaction * @var{trans}, int @var{i})
Return the @var{I}th Split of @var{trans}.
@end deftypefun

@deftypefun {const char *} xaccTransGetNum (Transaction * @var{trans})
Return the number field of @var{trans}.
@end deftypefun

@deftypefun {const char *} xaccTransGetDescription (Transaction * @var{trans})
Return the description field of @var{trans}.
@end deftypefun

@deftypefun time_t xaccTransGetDate (Transaction * @var{trans})
Return the post date of @var{trans} as a @code{time_t} value.
@end deftypefun

@deftypefun {long long} xaccTransGetDateL (Transaction * @var{trans})
Return the post date of @var{trans} as a @code{long long} value.
@end deftypefun

@deftypefun void xaccTransGetDateTS (Transaction * @var{trans}, Timespec * @var{ts})
Return the post date of @var{trans} in @var{ts}.
@end deftypefun

@deftypefun void xaccTransGetDateEnteredTS (Transaction * @var{trans}, Timespec * @var{ts})
Return the entry date of @var{trans} in @var{ts}.
@end deftypefun

@deftypefun {char *} xaccTransGetDateStr (Transaction * @var{trans})
Return a string representing the post date of @var{trans}, or NULL if
@var{trans} is NULL. The string must be freed with @code{free()} after
use.
@end deftypefun

@deftypefun int xaccTransCountSplits (Transaction * @var{trans})
Return the number of Splits in @var{trans}.
@end deftypefun


@node Accounts, Account Groups, Transactions, Engine
@section Accounts
@tindex Account


@node Account Groups, Sessions, Accounts, Engine
@section Account Groups
@tindex AccountGroup


@node Sessions,  , Account Groups, Engine
@section Sessions
@tindex Session

The @dfn{Session} interface provides wrappers for initiating/concluding
a file-editing session. This class provides several important services:

@itemize

@item
Prevents multiple users from editing the same file at the same time,
thus avoiding lost data due to race conditions. Thus an open session
implies that the associated file is locked.

@item
Provides a search path for the file to be edited. This should simplify
install & maintenance problems for users who may not have a good grasp
of what a file system is, or where they want to keep their data files.

@end itemize

The current implementation assumes the use of files and file locks;
however, the API was designed to be general enough to allow the use
of generic URL's, and/or implementation on top of SQL or other
database/persistant object technology.