GnuCash  3.7-134-g71bdcdfa6+
Files | Macros | Functions

A good overview of transactions, splits and accounts can be found in the texinfo documentation, together with an overview of how to use this API. More...

Files

file  Split.h
 API for Transactions and Splits (journal entries)
 
file  Transaction.h
 API for Transactions and Splits (journal entries)
 

Macros

#define GNC_TYPE_SPLIT   (gnc_split_get_type ())
 
#define GNC_SPLIT(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_SPLIT, Split))
 
#define GNC_SPLIT_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_SPLIT, SplitClass))
 
#define GNC_IS_SPLIT(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_SPLIT))
 
#define GNC_IS_SPLIT_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_SPLIT))
 
#define GNC_SPLIT_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_SPLIT, SplitClass))
 
#define xaccSplitGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))
 
#define xaccSplitReturnGUID(X)   (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
 
#define GNC_TYPE_TRANSACTION   (gnc_transaction_get_type ())
 
#define GNC_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_TRANSACTION, Transaction))
 
#define GNC_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_TRANSACTION, TransactionClass))
 
#define GNC_IS_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_TRANSACTION))
 
#define GNC_IS_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_TRANSACTION))
 
#define GNC_TRANSACTION_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_TRANSACTION, TransactionClass))
 
#define GNC_IS_TRANS(obj)   GNC_IS_TRANSACTION(obj)
 
#define GNC_TRANS(obj)   GNC_TRANSACTION(obj)
 
#define RECONCILED_MATCH_TYPE   "reconciled-match"
 
#define xaccTransGetBook(X)   qof_instance_get_book (QOF_INSTANCE(X))
 
#define xaccTransGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))
 
#define xaccTransReturnGUID(X)   (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
 

Functions

GType gnc_split_get_type (void)
 
gnc_numeric xaccSplitConvertAmount (const Split *split, const Account *account)
 
GType gnc_transaction_get_type (void)
 

Split Reconciled field values

If you change these
be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and
associated functions
#define CREC   'c'
 The Split has been cleared.
 
#define YREC   'y'
 The Split has been reconciled.
 
#define FREC   'f'
 frozen into accounting period
 
#define NREC   'n'
 not reconciled or cleared
 
#define VREC   'v'
 split is void
 

Split general getters/setters

Split * xaccMallocSplit (QofBook *book)
 Constructor. More...
 
void xaccSplitReinit (Split *split)
 
gboolean xaccSplitDestroy (Split *split)
 Destructor. More...
 
void xaccSplitCopyOnto (const Split *from_split, Split *to_split)
 This is really a helper for xaccTransCopyOnto. More...
 
QofBook * xaccSplitGetBook (const Split *split)
 Returns the book of this split, i.e. More...
 
AccountxaccSplitGetAccount (const Split *split)
 Returns the account of this split, which was set through xaccAccountInsertSplit(). More...
 
void xaccSplitSetAccount (Split *s, Account *acc)
 
Transaction * xaccSplitGetParent (const Split *split)
 Returns the parent transaction of the split. More...
 
void xaccSplitSetParent (Split *split, Transaction *trans)
 
GNCLot * xaccSplitGetLot (const Split *split)
 Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn't belong to any. More...
 
void xaccSplitSetLot (Split *split, GNCLot *lot)
 Assigns the split to a specific Lot.
 
void xaccSplitSetMemo (Split *split, const char *memo)
 The memo is an arbitrary string associated with a split. More...
 
const char * xaccSplitGetMemo (const Split *split)
 Returns the memo string. More...
 
void xaccSplitSetAction (Split *split, const char *action)
 The Action is an arbitrary user-assigned string. More...
 
const char * xaccSplitGetAction (const Split *split)
 Returns the action string. More...
 

Split Date getters/setters

void xaccSplitSetReconcile (Split *split, char reconciled_flag)
 Set the reconcile flag. More...
 
char xaccSplitGetReconcile (const Split *split)
 Returns the value of the reconcile flag. More...
 
void xaccSplitSetDateReconciledSecs (Split *split, time64 time)
 Set the date on which this split was reconciled by specifying the time as time64. More...
 
time64 xaccSplitGetDateReconciled (const Split *split)
 Retrieve the date when the Split was reconciled. More...
 

Split amount getters/setters


'value' vs.

'amount' of a Split: The 'value' is the amount of the transaction balancing commodity (i.e. currency) involved, 'amount' is the amount of the account's commodity involved.

void xaccSplitSetAmount (Split *split, gnc_numeric amount)
 The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have. More...
 
gnc_numeric xaccSplitGetAmount (const Split *split)
 Returns the amount of the split in the account's commodity. More...
 
void xaccSplitSetValue (Split *split, gnc_numeric value)
 The xaccSplitSetValue() method sets the value of this split in the transaction's commodity. More...
 
gnc_numeric xaccSplitGetValue (const Split *split)
 Returns the value of this split in the transaction's commodity. More...
 
void xaccSplitSetSharePriceAndAmount (Split *split, gnc_numeric price, gnc_numeric amount)
 The xaccSplitSetSharePriceAndAmount() method will simultaneously update the share price and the number of shares. More...
 
gnc_numeric xaccSplitGetSharePrice (const Split *split)
 Returns the price of the split, that is, the value divided by the amount. More...
 
void xaccSplitSetBaseValue (Split *split, gnc_numeric value, const gnc_commodity *base_currency)
 Depending on the base_currency, set either the value or the amount of this split or both: If the base_currency is the transaction's commodity, set the value. More...
 
gnc_numeric xaccSplitGetBaseValue (const Split *split, const gnc_commodity *base_currency)
 Depending on the base_currency, return either the value or the amount of this split: If the base_curreny is the transaction's commodity, return the value. More...
 
gnc_numeric xaccSplitGetBalance (const Split *split)
 Returns the running balance up to and including the indicated split. More...
 
gnc_numeric xaccSplitGetClearedBalance (const Split *split)
 The cleared-balance is the currency-denominated balance of all transactions that have been marked as cleared or reconciled. More...
 
gnc_numeric xaccSplitGetReconciledBalance (const Split *split)
 Returns the reconciled-balance of this split. More...
 

Split utility functions

gboolean xaccSplitEqual (const Split *sa, const Split *sb, gboolean check_guids, gboolean check_balances, gboolean check_txn_splits)
 Equality. More...
 
Split * xaccSplitLookup (const GncGUID *guid, QofBook *book)
 The xaccSplitLookup() subroutine will return the split associated with the given id, or NULL if there is no such split. More...
 
GList * xaccSplitListGetUniqueTransactions (const GList *splits)
 
void xaccSplitAddPeerSplit (Split *split, const Split *other_split, const time64 timestamp)
 Add a peer split to this split's lot-split list. More...
 
gboolean xaccSplitHasPeers (const Split *split)
 Does this split have peers?
 
gboolean xaccSplitIsPeerSplit (const Split *split, const Split *other_split)
 Report if a split is a peer of this one. More...
 
void xaccSplitRemovePeerSplit (Split *split, const Split *other_split)
 Remove a peer split from this split's lot-split list. More...
 
void xaccSplitMergePeerSplits (Split *split, const Split *other_split)
 Merge the other_split's peer splits into split's peers. More...
 
Split * xaccSplitGetOtherSplit (const Split *split)
 The xaccSplitGetOtherSplit() is a convenience routine that returns the other of a pair of splits. More...
 
const char * xaccSplitGetType (const Split *s)
 The xaccIsPeerSplit() is a convenience routine that returns TRUE (a non-zero value) if the two splits share a common parent transaction, else it returns FALSE (zero). More...
 
void xaccSplitMakeStockSplit (Split *s)
 Mark a split to be of type stock split - after this, you shouldn't modify the value anymore, just the amount. More...
 
gint xaccSplitOrder (const Split *sa, const Split *sb)
 The xaccSplitOrder(sa,sb) method is useful for sorting. More...
 
gint xaccSplitOrderDateOnly (const Split *sa, const Split *sb)
 
int xaccSplitCompareAccountFullNames (const Split *sa, const Split *sb)
 Compare two splits by full name of account. More...
 
int xaccSplitCompareAccountCodes (const Split *sa, const Split *sb)
 Compare two splits by code of account. More...
 
int xaccSplitCompareOtherAccountFullNames (const Split *sa, const Split *sb)
 Compare two splits by full name of the other account. More...
 
int xaccSplitCompareOtherAccountCodes (const Split *sa, const Split *sb)
 Compare two splits by code of the other account. More...
 
char * xaccSplitGetCorrAccountFullName (const Split *sa)
 These functions take a split, get the corresponding split on the "other side" of the transaction, and extract either the name or code of that split, reverting to returning a constant "Split" if the transaction has more than one split on the "other side". More...
 
const char * xaccSplitGetCorrAccountName (const Split *sa)
 document me
 
const char * xaccSplitGetCorrAccountCode (const Split *sa)
 document me
 
#define xaccSplitLookupDirect(g, b)   xaccSplitLookup(&(g),b)
 

Split deprecated functions

void xaccSplitSetSharePrice (Split *split, gnc_numeric price)
 

Split voiding

gnc_numeric xaccSplitVoidFormerAmount (const Split *split)
 Returns the original pre-void amount of a split. More...
 
gnc_numeric xaccSplitVoidFormerValue (const Split *split)
 Returns the original pre-void value of a split. More...
 

Split Parameter names

Note, if you want to get the equivalent of "ACCT_MATCH_ALL" you need to create a search on the following parameter list: SPLIT->SPLIT_TRANS->TRANS_SPLITLIST->SPLIT_ACCOUNT_GUID.

If you do this, you might want to use the ACCOUNT_MATCH_ALL_TYPE as the override so the gnome-search dialog displays the right type.

#define SPLIT_DATE_RECONCILED   "date-reconciled"
 
#define SPLIT_BALANCE   "balance"
 
#define SPLIT_CLEARED_BALANCE   "cleared-balance"
 
#define SPLIT_RECONCILED_BALANCE   "reconciled-balance"
 
#define SPLIT_MEMO   "memo"
 
#define SPLIT_ACTION   "action"
 
#define SPLIT_RECONCILE   "reconcile-flag"
 
#define SPLIT_AMOUNT   "amount"
 
#define SPLIT_SHARE_PRICE   "share-price"
 
#define SPLIT_VALUE   "value"
 
#define SPLIT_TYPE   "type"
 
#define SPLIT_VOIDED_AMOUNT   "voided-amount"
 
#define SPLIT_VOIDED_VALUE   "voided-value"
 
#define SPLIT_LOT   "lot"
 
#define SPLIT_TRANS   "trans"
 
#define SPLIT_ACCOUNT   "account"
 
#define SPLIT_ACCOUNT_GUID   "account-guid"
 for guid_match_all
 
#define SPLIT_ACCT_FULLNAME   "acct-fullname"
 
#define SPLIT_CORR_ACCT_NAME   "corr-acct-fullname"
 
#define SPLIT_CORR_ACCT_CODE   "corr-acct-code"
 

Transaction Type field values

#define TXN_TYPE_NONE   '\0'
 No transaction type.
 
#define TXN_TYPE_INVOICE   'I'
 Transaction is an invoice.
 
#define TXN_TYPE_PAYMENT   'P'
 Transaction is a payment.
 
#define TXN_TYPE_LINK   'L'
 Transaction is a link between (invoice and payment) lots.
 

Transaction creation and editing

Transaction * xaccMallocTransaction (QofBook *book)
 
The xaccMallocTransaction() will malloc memory and initialize it. More...
 
void xaccTransDestroy (Transaction *trans)
 Destroys a transaction. More...
 
Transaction * xaccTransClone (const Transaction *t)
 
The xaccTransClone() method will create a complete copy of an existing transaction.
 
Transaction * xaccTransCloneNoKvp (const Transaction *t)
 
The xaccTransCloneNoKvp() method will create a complete copy of an existing transaction except that the KVP slots will be empty.
 
gboolean xaccTransEqual (const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
 Equality. More...
 
void xaccTransBeginEdit (Transaction *trans)
 The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of its component splits. More...
 
void xaccTransCommitEdit (Transaction *trans)
 The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are complete and should be made permanent. More...
 
void xaccTransRollbackEdit (Transaction *trans)
 The xaccTransRollbackEdit() routine rejects all edits made, and sets the transaction back to where it was before the editing started. More...
 
gboolean xaccTransIsOpen (const Transaction *trans)
 The xaccTransIsOpen() method returns TRUE if the transaction is open for editing. More...
 
Transaction * xaccTransLookup (const GncGUID *guid, QofBook *book)
 The xaccTransLookup() subroutine will return the transaction associated with the given id, or NULL if there is no such transaction. More...
 
Transaction * xaccTransCopyToClipBoard (const Transaction *from_trans)
 Copy a transaction to the 'clipboard' transaction using dupe_transaction. More...
 
void xaccTransCopyOnto (const Transaction *from_trans, Transaction *to_trans)
 Copy a transaction to another using the function below without changing any account information.
 
void xaccTransCopyFromClipBoard (const Transaction *from_trans, Transaction *to_trans, const Account *from_acc, Account *to_acc, gboolean no_date)
 This function explicitly must robustly handle some unusual input. More...
 
Split * xaccTransFindSplitByAccount (const Transaction *trans, const Account *acc)
 
void xaccTransScrubGains (Transaction *trans, Account *gain_acc)
 The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction, with the end-goal of setting up a consistent set of gains/losses for all the splits in the transaction. More...
 
guint gnc_book_count_transactions (QofBook *book)
 
#define xaccTransLookupDirect(g, b)   xaccTransLookup(&(g),b)
 

Transaction general getters/setters

gboolean xaccTransUseTradingAccounts (const Transaction *trans)
 Determine whether this transaction should use commodity trading accounts.
 
void xaccTransSortSplits (Transaction *trans)
 Sorts the splits in a transaction, putting the debits first, followed by the credits.
 
void xaccTransSetTxnType (Transaction *trans, char type)
 Set the Transaction Type. More...
 
char xaccTransGetTxnType (const Transaction *trans)
 Returns the Transaction Type. More...
 
void xaccTransSetNum (Transaction *trans, const char *num)
 Sets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
 
void xaccTransSetDescription (Transaction *trans, const char *desc)
 Sets the transaction Description.
 
void xaccTransSetAssociation (Transaction *trans, const char *assoc)
 Sets the transaction Association.
 
void xaccTransSetNotes (Transaction *trans, const char *notes)
 Sets the transaction Notes. More...
 
const char * xaccTransGetNum (const Transaction *trans)
 Gets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_get_num_action' and 'gnc_get_action_num' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
 
const char * xaccTransGetDescription (const Transaction *trans)
 Gets the transaction Description.
 
const char * xaccTransGetAssociation (const Transaction *trans)
 Gets the transaction association.
 
const char * xaccTransGetNotes (const Transaction *trans)
 Gets the transaction Notes. More...
 
void xaccTransSetIsClosingTxn (Transaction *trans, gboolean is_closing)
 Sets whether or not this transaction is a "closing transaction".
 
gboolean xaccTransGetIsClosingTxn (const Transaction *trans)
 Returns whether this transaction is a "closing transaction".
 
Split * xaccTransGetSplit (const Transaction *trans, int i)
 The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction. More...
 
int xaccTransGetSplitIndex (const Transaction *trans, const Split *split)
 Inverse of xaccTransGetSplit()
 
SplitListxaccTransGetSplitList (const Transaction *trans)
 The xaccTransGetSplitList() method returns a GList of the splits in a transaction. More...
 
SplitListxaccTransGetPaymentAcctSplitList (const Transaction *trans)
 The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits in a transaction that belong to an account which is considered a valid account for business payments. More...
 
SplitListxaccTransGetAPARAcctSplitList (const Transaction *trans, gboolean strict)
 The xaccTransGetAPARSplitList() method returns a GList of the splits in a transaction that belong to an AR or AP account. More...
 
gboolean xaccTransStillHasSplit (const Transaction *trans, const Split *s)
 
Split * xaccTransGetFirstPaymentAcctSplit (const Transaction *trans)
 The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an account which is considered a valid account for business payments. More...
 
Split * xaccTransGetFirstAPARAcctSplit (const Transaction *trans, gboolean strict)
 The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an AR or AP account. More...
 
void xaccTransSetReadOnly (Transaction *trans, const char *reason)
 Set the transaction to be ReadOnly by setting a non-NULL value as "reason". More...
 
void xaccTransClearReadOnly (Transaction *trans)
 
const char * xaccTransGetReadOnly (Transaction *trans)
 Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text. More...
 
gboolean xaccTransIsReadonlyByPostedDate (const Transaction *trans)
 Returns TRUE if this Transaction is read-only because its posted-date is older than the "auto-readonly" threshold of this book. More...
 
gboolean xaccTransInFutureByPostedDate (const Transaction *trans)
 Returns TRUE if this Transaction's posted-date is in the future.
 
int xaccTransCountSplits (const Transaction *trans)
 Returns the number of splits in this transaction. More...
 
gboolean xaccTransHasReconciledSplits (const Transaction *trans)
 FIXME: document me.
 
gboolean xaccTransHasReconciledSplitsByAccount (const Transaction *trans, const Account *account)
 FIXME: document me.
 
gboolean xaccTransHasSplitsInState (const Transaction *trans, const char state)
 FIXME: document me.
 
gboolean xaccTransHasSplitsInStateByAccount (const Transaction *trans, const char state, const Account *account)
 FIXME: document me.
 
gnc_commodity * xaccTransGetCurrency (const Transaction *trans)
 Returns the valuation commodity of this transaction. More...
 
void xaccTransSetCurrency (Transaction *trans, gnc_commodity *curr)
 Set the commodity of this transaction. More...
 
gnc_numeric xaccTransGetImbalanceValue (const Transaction *trans)
 The xaccTransGetImbalanceValue() method returns the total value of the transaction. More...
 
MonetaryList * xaccTransGetImbalance (const Transaction *trans)
 The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency for which the balance is not zero. More...
 
gboolean xaccTransIsBalanced (const Transaction *trans)
 Returns true if the transaction is balanced according to the rules currently in effect. More...
 
gnc_numeric xaccTransGetAccountValue (const Transaction *trans, const Account *account)
 The xaccTransGetAccountValue() method returns the total value applied to a particular account. More...
 
gnc_numeric xaccTransGetAccountAmount (const Transaction *trans, const Account *account)
 Same as xaccTransGetAccountValue, but uses the Account's commodity. More...
 
gboolean xaccTransGetRateForCommodity (const Transaction *trans, const gnc_commodity *split_com, const Split *split_to_exclude, gnc_numeric *rate)
 
gnc_numeric xaccTransGetAccountConvRate (const Transaction *txn, const Account *acc)
 
gnc_numeric xaccTransGetAccountBalance (const Transaction *trans, const Account *account)
 Get the account balance for the specified account after the last split in the specified transaction. More...
 
int xaccTransOrder (const Transaction *ta, const Transaction *tb)
 The xaccTransOrder(ta,tb) method is useful for sorting. More...
 
int xaccTransOrder_num_action (const Transaction *ta, const char *actna, const Transaction *tb, const char *actnb)
 The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting. More...
 
#define xaccTransAppendSplit(t, s)   xaccSplitSetParent((s), (t))
 Add a split to the transaction. More...
 

Transaction date setters/getters

void xaccTransSetDate (Transaction *trans, int day, int mon, int year)
 The xaccTransSetDate() method does the same thing as xaccTransSetDate[Posted]Secs(), but takes a convenient day-month-year format. More...
 
void xaccTransSetDatePostedGDate (Transaction *trans, GDate date)
 This method modifies posted date of the transaction, specified by a GDate. More...
 
void xaccTransSetDatePostedSecs (Transaction *trans, time64 time)
 The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)). More...
 
void xaccTransSetDatePostedSecsNormalized (Transaction *trans, time64 time)
 This function sets the posted date of the transaction, specified by a time64 (see ctime(3)). More...
 
void xaccTransSetDateEnteredSecs (Transaction *trans, time64 time)
 Modify the date of when the transaction was entered. More...
 
void xaccTransSetDateDue (Transaction *trans, time64 time)
 Dates and txn-type for A/R and A/P "invoice" postings.
 
time64 xaccTransGetDate (const Transaction *trans)
 Retrieve the posted date of the transaction. More...
 
time64 xaccTransRetDatePosted (const Transaction *trans)
 Retrieve the posted date of the transaction. More...
 
GDate xaccTransGetDatePostedGDate (const Transaction *trans)
 Retrieve the posted date of the transaction. More...
 
time64 xaccTransGetDateEntered (const Transaction *trans)
 Retrieve the date of when the transaction was entered. More...
 
time64 xaccTransRetDateEntered (const Transaction *trans)
 Retrieve the date of when the transaction was entered. More...
 
time64 xaccTransRetDateDue (const Transaction *trans)
 Dates and txn-type for A/R and A/P "invoice" postings.
 

Transaction voiding

void xaccTransVoid (Transaction *transaction, const char *reason)
 xaccTransVoid voids a transaction. More...
 
void xaccTransUnvoid (Transaction *transaction)
 xaccTransUnvoid restores a voided transaction to its original state. More...
 
Transaction * xaccTransReverse (Transaction *transaction)
 xaccTransReverse creates a Transaction that reverses the given tranaction by inverting all the numerical values in the given transaction. More...
 
Transaction * xaccTransGetReversedBy (const Transaction *trans)
 Returns the transaction that reversed the given transaction. More...
 
gboolean xaccTransGetVoidStatus (const Transaction *transaction)
 Retrieve information on whether or not a transaction has been voided. More...
 
const char * xaccTransGetVoidReason (const Transaction *transaction)
 Returns the user supplied textual reason why a transaction was voided. More...
 
time64 xaccTransGetVoidTime (const Transaction *tr)
 Returns the time that a transaction was voided. More...
 

Transaction Parameter names

#define TRANS_KVP   "kvp"
 
#define TRANS_NUM   "num"
 
#define TRANS_DESCRIPTION   "desc"
 
#define TRANS_DATE_ENTERED   "date-entered"
 
#define TRANS_DATE_POSTED   "date-posted"
 
#define TRANS_DATE_DUE   "date-due"
 
#define TRANS_IMBALANCE   "trans-imbalance"
 
#define TRANS_IS_BALANCED   "trans-balanced?"
 
#define TRANS_IS_CLOSING   "trans-is-closing?"
 
#define TRANS_NOTES   "notes"
 
#define TRANS_ASSOCIATION   "assoc"
 
#define TRANS_TYPE   "type"
 
#define TRANS_VOID_STATUS   "void-p"
 
#define TRANS_VOID_REASON   "void-reason"
 
#define TRANS_VOID_TIME   "void-time"
 
#define TRANS_SPLITLIST   "split-list" /* for guid_match_all */
 

Detailed Description

A good overview of transactions, splits and accounts can be found in the texinfo documentation, together with an overview of how to use this API.

Splits, or "Ledger Entries" are the fundamental accounting units. Each Split consists of an amount (number of dollar bills, number of shares, etc.), the value of that amount expressed in a (possibly) different currency than the amount, 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.

Transactions embody the notion of "double entry" accounting. A Transaction consists of a date, a description, an ID number, a list of one or more Splits, and a key-value frame. The transaction also specifies the currency with which all of the splits will be valued. When double-entry rules are enforced, the sum total value of the splits are zero. If there are only two splits, then the value of one must be positive, the other negative: this denotes that one account is debited, and another is credited by an equal amount. By forcing the value of the splits to always 'add up' to zero, we can guarantee that the balances of the accounts are always correctly balanced.

The engine does not enforce double-entry accounting, but provides an API to enable user-code to find unbalanced transactions and 'repair' them so that they are in balance.

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. This feature allows currency-trading accounts to be established.

Every Split must point to 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 enforced 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 which are also known as "Ledgers" in accounting practice. Each Account consists of a list of Splits that debit that Account. To ensure consistency, if a Split points to an Account, then the Account must point to 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 gives the Account a name, a code number, description and notes fields, a key-value frame, a pointer to the commodity that is used for all splits in this account. The commodity can be the name of anything traded and tradable: a stock (e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or anything added to the commodity table.

Accounts can be arranged in a hierarchical tree. The nodes of the tree are called "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.

Macro Definition Documentation

◆ xaccSplitGetGUID

#define xaccSplitGetGUID (   X)    qof_entity_get_guid(QOF_INSTANCE(X))
Deprecated:

Definition at line 544 of file Split.h.

◆ xaccSplitReturnGUID

#define xaccSplitReturnGUID (   X)    (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
Deprecated:

Definition at line 546 of file Split.h.

◆ xaccTransAppendSplit

#define xaccTransAppendSplit (   t,
 
)    xaccSplitSetParent((s), (t))

Add a split to the transaction.

The xaccTransAppendSplit() method will append the indicated split to the collection of splits in this transaction.

Note
If the split is already a part of another transaction, it will be removed from that transaction first.

Definition at line 361 of file Transaction.h.

◆ xaccTransGetBook

#define xaccTransGetBook (   X)    qof_instance_get_book (QOF_INSTANCE(X))
Deprecated:

Definition at line 771 of file Transaction.h.

◆ xaccTransGetGUID

#define xaccTransGetGUID (   X)    qof_entity_get_guid(QOF_INSTANCE(X))
Deprecated:

Definition at line 773 of file Transaction.h.

◆ xaccTransReturnGUID

#define xaccTransReturnGUID (   X)    (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
Deprecated:

Definition at line 775 of file Transaction.h.

Function Documentation

◆ gnc_book_count_transactions()

guint gnc_book_count_transactions ( QofBook *  book)
Warning
XXX FIXME gnc_book_count_transactions is a utility function, probably needs to be moved to a utility file somewhere.

Definition at line 2661 of file Transaction.c.

2662 {
2663  guint count = 0;
2664  xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
2665  counter_thunk, (void*)&count);
2666  return count;
2667 }
int xaccAccountTreeForEachTransaction(Account *acc, TransactionCallback proc, void *data)
Traverse all of the transactions in the given account group.

◆ xaccMallocSplit()

Split* xaccMallocSplit ( QofBook *  book)

Constructor.

Definition at line 527 of file Split.c.

528 {
529  Split *split;
530  g_return_val_if_fail (book, NULL);
531 
532  split = g_object_new (GNC_TYPE_SPLIT, NULL);
533  xaccInitSplit (split, book);
534 
535  return split;
536 }

◆ xaccMallocTransaction()

Transaction* xaccMallocTransaction ( QofBook *  book)


The xaccMallocTransaction() will malloc memory and initialize it.

Once created, it is usually unsafe to merely "free" this memory; the xaccTransDestroy() method should be called.

Definition at line 505 of file Transaction.c.

506 {
507  Transaction *trans;
508 
509  g_return_val_if_fail (book, NULL);
510 
511  trans = g_object_new(GNC_TYPE_TRANSACTION, NULL);
512  xaccInitTransaction (trans, book);
513  qof_event_gen (&trans->inst, QOF_EVENT_CREATE, NULL);
514 
515  return trans;
516 }
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:234

◆ xaccSplitAddPeerSplit()

void xaccSplitAddPeerSplit ( Split *  split,
const Split *  other_split,
const time64  timestamp 
)

Add a peer split to this split's lot-split list.

Parameters
other_splitThe split whose guid to add
timestampThe time to be recorded for the split.

Definition at line 1975 of file Split.c.

1977 {
1978  const GncGUID* guid;
1979 
1980  g_return_if_fail (split != NULL);
1981  g_return_if_fail (other_split != NULL);
1982 
1983  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
1984  xaccTransBeginEdit (split->parent);
1985  qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
1986  gnc_time(NULL), "peer_guid", guid_copy(guid));
1987  mark_split (split);
1988  qof_instance_set_dirty (QOF_INSTANCE (split));
1989  xaccTransCommitEdit (split->parent);
1990 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
GncGUID * guid_copy(const GncGUID *guid)
Returns a newly allocated GncGUID that matches the passed-in GUID.
Definition: guid.cpp:121
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:273
The type used to store guids in C.
Definition: guid.h:75

◆ xaccSplitCompareAccountCodes()

int xaccSplitCompareAccountCodes ( const Split *  sa,
const Split *  sb 
)

Compare two splits by code of account.

Returns similar to strcmp.

Definition at line 1642 of file Split.c.

1643 {
1644  Account *aa, *ab;
1645  if (!sa && !sb) return 0;
1646  if (!sa) return -1;
1647  if (!sb) return 1;
1648 
1649  aa = sa->acc;
1650  ab = sb->acc;
1651 
1652  return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
1653 }
const char * xaccAccountGetCode(const Account *acc)
Get the account's accounting code.
Definition: Account.cpp:3083
STRUCTS.

◆ xaccSplitCompareAccountFullNames()

int xaccSplitCompareAccountFullNames ( const Split *  sa,
const Split *  sb 
)

Compare two splits by full name of account.

Returns similar to strcmp.

Definition at line 1621 of file Split.c.

1622 {
1623  Account *aa, *ab;
1624  char *full_a, *full_b;
1625  int retval;
1626  if (!sa && !sb) return 0;
1627  if (!sa) return -1;
1628  if (!sb) return 1;
1629 
1630  aa = sa->acc;
1631  ab = sb->acc;
1632  full_a = gnc_account_get_full_name(aa);
1633  full_b = gnc_account_get_full_name(ab);
1634  retval = g_utf8_collate(full_a, full_b);
1635  g_free(full_a);
1636  g_free(full_b);
1637  return retval;
1638 }
STRUCTS.
gchar * gnc_account_get_full_name(const Account *account)
The gnc_account_get_full_name routine returns the fully qualified name of the account using the given...
Definition: Account.cpp:3035

◆ xaccSplitCompareOtherAccountCodes()

int xaccSplitCompareOtherAccountCodes ( const Split *  sa,
const Split *  sb 
)

Compare two splits by code of the other account.

Returns similar to strcmp. This function attempts to find the split on the other side of a transaction and compare on it.

Definition at line 1677 of file Split.c.

1678 {
1679  const char *ca, *cb;
1680  if (!sa && !sb) return 0;
1681  if (!sa) return -1;
1682  if (!sb) return 1;
1683 
1684  ca = xaccSplitGetCorrAccountCode(sa);
1685  cb = xaccSplitGetCorrAccountCode(sb);
1686  return g_strcmp0(ca, cb);
1687 }
const char * xaccSplitGetCorrAccountCode(const Split *sa)
document me
Definition: Split.c:1604

◆ xaccSplitCompareOtherAccountFullNames()

int xaccSplitCompareOtherAccountFullNames ( const Split *  sa,
const Split *  sb 
)

Compare two splits by full name of the other account.

Returns similar to strcmp. This function attempts to find the split on the other side of a transaction and compare on it.

Definition at line 1656 of file Split.c.

1657 {
1658  char *ca, *cb;
1659  int retval;
1660  if (!sa && !sb) return 0;
1661  if (!sa) return -1;
1662  if (!sb) return 1;
1663 
1664  /* doesn't matter what separator we use
1665  * as long as they are the same
1666  */
1667 
1670  retval = g_strcmp0(ca, cb);
1671  g_free(ca);
1672  g_free(cb);
1673  return retval;
1674 }
char * xaccSplitGetCorrAccountFullName(const Split *sa)
These functions take a split, get the corresponding split on the "other side" of the transaction...
Definition: Split.c:1588

◆ xaccSplitCopyOnto()

void xaccSplitCopyOnto ( const Split *  from_split,
Split *  to_split 
)

This is really a helper for xaccTransCopyOnto.

It doesn't reparent the 'to' split to from's transaction, because xaccTransCopyOnto is responsible for parenting the split to the correct transaction. Also, from's parent transaction may not even be a valid transaction, so this function may not modify anything about 'from' or from's transaction.

Definition at line 631 of file Split.c.

632 {
633  if (!from_split || !to_split) return;
634  xaccTransBeginEdit (to_split->parent);
635 
636  xaccSplitSetMemo(to_split, xaccSplitGetMemo(from_split));
637  xaccSplitSetAction(to_split, xaccSplitGetAction(from_split));
638  xaccSplitSetAmount(to_split, xaccSplitGetAmount(from_split));
639  xaccSplitSetValue(to_split, xaccSplitGetValue(from_split));
640  /* Setting the account is okay here because, even though the from
641  split might not really belong to the account it claims to,
642  setting the account won't cause any event involving from. */
643  xaccSplitSetAccount(to_split, xaccSplitGetAccount(from_split));
644  /* N.B. Don't set parent. */
645 
646  qof_instance_set_dirty(QOF_INSTANCE(to_split));
647  xaccTransCommitEdit(to_split->parent);
648 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.
Definition: Split.c:1241
void xaccSplitSetAction(Split *split, const char *actn)
The Action is an arbitrary user-assigned string.
Definition: Split.c:1716
void xaccSplitSetAmount(Split *s, gnc_numeric amt)
The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have...
Definition: Split.c:1205
void xaccSplitSetMemo(Split *split, const char *memo)
The memo is an arbitrary string associated with a split.
Definition: Split.c:1697
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.c:1890
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
const char * xaccSplitGetMemo(const Split *split)
Returns the memo string.
Definition: Split.c:1865
const char * xaccSplitGetAction(const Split *split)
Returns the action string.
Definition: Split.c:1871
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1884

◆ xaccSplitDestroy()

gboolean xaccSplitDestroy ( Split *  split)

Destructor.

The xaccSplitDestroy() method will update its parent account and transaction in a consistent manner, resulting in the complete unlinking of the split, and the freeing of its associated memory. The goal of this routine is to perform the removal and destruction of the split in an atomic fashion, with no chance of accidentally leaving the accounting structure out-of-balance or otherwise inconsistent.

If the deletion of the split leaves the transaction with no splits, then the transaction will be marked for deletion. (It will not be deleted until the xaccTransCommitEdit() routine is called.)

Returns
TRUE upon successful deletion of the split. FALSE when the parenting Transaction is a read-only one.

Definition at line 1439 of file Split.c.

1440 {
1441  Account *acc;
1442  Transaction *trans;
1443  GncEventData ed;
1444 
1445  if (!split) return TRUE;
1446 
1447  acc = split->acc;
1448  trans = split->parent;
1449  if (acc && !qof_instance_get_destroying(acc)
1450  && !qof_instance_get_destroying(trans)
1451  && xaccTransGetReadOnly(trans))
1452  return FALSE;
1453 
1454  xaccTransBeginEdit(trans);
1455  ed.node = split;
1456  ed.idx = xaccTransGetSplitIndex(trans, split);
1457  qof_instance_set_dirty(QOF_INSTANCE(split));
1458  qof_instance_set_destroying(split, TRUE);
1459  qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
1460  xaccTransCommitEdit(trans);
1461 
1462  return TRUE;
1463 }
STRUCTS.
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2475
gboolean qof_instance_get_destroying(gconstpointer ptr)
Retrieve the flag that indicates whether or not this object is about to be destroyed.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
int xaccTransGetSplitIndex(const Transaction *trans, const Split *split)
Inverse of xaccTransGetSplit()
Definition: Transaction.c:2226
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:234

◆ xaccSplitEqual()

gboolean xaccSplitEqual ( const Split *  sa,
const Split *  sb,
gboolean  check_guids,
gboolean  check_balances,
gboolean  check_txn_splits 
)

Equality.

Parameters
saFirst split to compare
sbSecond split to compare
check_guidsIf TRUE, try a guid_equal() on the GUIDs of both splits if their pointers are not equal in the first place.
check_balancesIf TRUE, compare balances between the two splits. Balances are recalculated whenever a split is added or removed from an account, so YMMV on whether this should be set.
check_txn_splitsIf the pointers are not equal, but everything else so far is equal (including memo, amount, value, kvp), then, when comparing the parenting transactions with xaccTransEqual(), set its argument check_splits to be TRUE.

Definition at line 759 of file Split.c.

763 {
764  gboolean same_book;
765 
766  if (!sa && !sb) return TRUE; /* Arguable. FALSE is better, methinks */
767 
768  if (!sa || !sb)
769  {
770  PINFO ("one is NULL");
771  return FALSE;
772  }
773 
774  if (sa == sb) return TRUE;
775 
776  same_book = qof_instance_get_book(QOF_INSTANCE(sa)) == qof_instance_get_book(QOF_INSTANCE(sb));
777 
778  if (check_guids)
779  {
780  if (qof_instance_guid_compare(sa, sb) != 0)
781  {
782  PINFO ("GUIDs differ");
783  return FALSE;
784  }
785  }
786 
787  /* If the same book, since these strings are cached we can just use pointer equality */
788  if ((same_book && sa->memo != sb->memo) || (!same_book && g_strcmp0(sa->memo, sb->memo) != 0))
789  {
790  PINFO ("memos differ: (%p)%s vs (%p)%s",
791  sa->memo, sa->memo, sb->memo, sb->memo);
792  return FALSE;
793  }
794 
795  if ((same_book && sa->action != sb->action) || (!same_book && g_strcmp0(sa->action, sb->action) != 0))
796  {
797  PINFO ("actions differ: %s vs %s", sa->action, sb->action);
798  return FALSE;
799  }
800 
801  if (qof_instance_compare_kvp (QOF_INSTANCE (sa), QOF_INSTANCE (sb)) != 0)
802  {
803  char *frame_a;
804  char *frame_b;
805 
806  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (sa));
807  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (sb));
808 
809  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
810 
811  g_free (frame_a);
812  g_free (frame_b);
813 
814  return FALSE;
815  }
816 
817  if (sa->reconciled != sb->reconciled)
818  {
819  PINFO ("reconcile flags differ: %c vs %c", sa->reconciled, sb->reconciled);
820  return FALSE;
821  }
822 
823  if (sa->date_reconciled != sb->date_reconciled)
824  {
825  PINFO ("reconciled date differs");
826  return FALSE;
827  }
828 
830  {
831  char *str_a;
832  char *str_b;
833 
836 
837  PINFO ("amounts differ: %s vs %s", str_a, str_b);
838 
839  g_free (str_a);
840  g_free (str_b);
841 
842  return FALSE;
843  }
844 
846  {
847  char *str_a;
848  char *str_b;
849 
852 
853  PINFO ("values differ: %s vs %s", str_a, str_b);
854 
855  g_free (str_a);
856  g_free (str_b);
857 
858  return FALSE;
859  }
860 
861  if (check_balances)
862  {
863  if (!xaccSplitEqualCheckBal ("", sa->balance, sb->balance))
864  return FALSE;
865  if (!xaccSplitEqualCheckBal ("cleared ", sa->cleared_balance,
866  sb->cleared_balance))
867  return FALSE;
868  if (!xaccSplitEqualCheckBal ("reconciled ", sa->reconciled_balance,
869  sb->reconciled_balance))
870  return FALSE;
871  }
872 
873  if (!xaccTransEqual(sa->parent, sb->parent, check_guids, check_txn_splits,
874  check_balances, FALSE))
875  {
876  PINFO ("transactions differ");
877  return FALSE;
878  }
879 
880  return TRUE;
881 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:256
gchar * gnc_numeric_to_string(gnc_numeric n)
Convert to string.
gboolean xaccTransEqual(const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
Equality.
Definition: Transaction.c:854
gboolean gnc_numeric_eq(gnc_numeric a, gnc_numeric b)
Equivalence predicate: Returns TRUE (1) if a and b are exactly the same (have the same numerator and ...
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.c:1890
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1884

◆ xaccSplitGetAccount()

Account* xaccSplitGetAccount ( const Split *  split)

Returns the account of this split, which was set through xaccAccountInsertSplit().

Definition at line 912 of file Split.c.

913 {
914  return s ? s->acc : NULL;
915 }

◆ xaccSplitGetAction()

const char* xaccSplitGetAction ( const Split *  split)

Returns the action string.

Rather than use this function directly, see 'gnc_get_num_action' and 'gnc_get_action_num'in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically

Definition at line 1871 of file Split.c.

1872 {
1873  return split ? split->action : NULL;
1874 }

◆ xaccSplitGetAmount()

gnc_numeric xaccSplitGetAmount ( const Split *  split)

Returns the amount of the split in the account's commodity.

Note that for cap-gains splits, this is slaved to the transaction that is causing the gains to occur.

Definition at line 1884 of file Split.c.

1885 {
1886  return split ? split->amount : gnc_numeric_zero();
1887 }

◆ xaccSplitGetBalance()

gnc_numeric xaccSplitGetBalance ( const Split *  split)

Returns the running balance up to and including the indicated split.

The balance is the currency-denominated balance. For accounts with non-unit share prices, it is correctly adjusted for share prices.

Returns the running balance up to & including the indicated split.

Definition at line 1270 of file Split.c.

1271 {
1272  return s ? s->balance : gnc_numeric_zero();
1273 }

◆ xaccSplitGetBaseValue()

gnc_numeric xaccSplitGetBaseValue ( const Split *  split,
const gnc_commodity *  base_currency 
)

Depending on the base_currency, return either the value or the amount of this split: If the base_curreny is the transaction's commodity, return the value.

If it is the account's commodity, return the amount. If it is neither print a warning message and return gnc_numeric_zero().

Definition at line 1343 of file Split.c.

1344 {
1345  if (!s || !s->acc || !s->parent) return gnc_numeric_zero();
1346 
1347  /* be more precise -- the value depends on the currency we want it
1348  * expressed in. */
1349  if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
1350  return xaccSplitGetValue(s);
1351  if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
1352  return xaccSplitGetAmount(s);
1353 
1354  PERR ("inappropriate base currency %s "
1355  "given split currency=%s and commodity=%s\n",
1356  gnc_commodity_get_printname(base_currency),
1359  return gnc_numeric_zero();
1360 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
const char * gnc_commodity_get_printname(const gnc_commodity *cm)
Retrieve the 'print' name for the specified commodity.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.c:1890
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account's commodity.
Definition: Account.cpp:3151
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1346
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1884

◆ xaccSplitGetBook()

QofBook* xaccSplitGetBook ( const Split *  split)

Returns the book of this split, i.e.

the entity where this split is stored.

Definition at line 1938 of file Split.c.

1939 {
1940  return qof_instance_get_book(QOF_INSTANCE(split));
1941 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.

◆ xaccSplitGetClearedBalance()

gnc_numeric xaccSplitGetClearedBalance ( const Split *  split)

The cleared-balance is the currency-denominated balance of all transactions that have been marked as cleared or reconciled.

It is correctly adjusted for price fluctuations.

Returns the running balance up to & including the indicated split.

Definition at line 1276 of file Split.c.

1277 {
1278  return s ? s->cleared_balance : gnc_numeric_zero();
1279 }

◆ xaccSplitGetCorrAccountFullName()

char* xaccSplitGetCorrAccountFullName ( const Split *  sa)

These functions take a split, get the corresponding split on the "other side" of the transaction, and extract either the name or code of that split, reverting to returning a constant "Split" if the transaction has more than one split on the "other side".

These were added for the transaction report, and is in C because the code was already written in C for the above functions and duplication is silly.

Note that this will only return a real value in case of a two-split transaction as that is the only situation in which a reliable value can be returned. In other situations "-- Split Transaction --" will be returned as Account Name or "Split" for Account Code.

Definition at line 1588 of file Split.c.

1589 {
1590  static const char *split_const = NULL;
1591  const Split *other_split;
1592 
1593  if (!get_corr_account_split(sa, &other_split))
1594  {
1595  if (!split_const)
1596  split_const = _("-- Split Transaction --");
1597 
1598  return g_strdup(split_const);
1599  }
1600  return gnc_account_get_full_name(other_split->acc);
1601 }
gchar * gnc_account_get_full_name(const Account *account)
The gnc_account_get_full_name routine returns the fully qualified name of the account using the given...
Definition: Account.cpp:3035

◆ xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled ( const Split *  split)

Retrieve the date when the Split was reconciled.

Definition at line 1789 of file Split.c.

1790 {
1791  return split ? split->date_reconciled : 0;
1792 }

◆ xaccSplitGetLot()

GNCLot* xaccSplitGetLot ( const Split *  split)

Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn't belong to any.

Definition at line 1850 of file Split.c.

1851 {
1852  return split ? split->lot : NULL;
1853 }

◆ xaccSplitGetMemo()

const char* xaccSplitGetMemo ( const Split *  split)

Returns the memo string.

Definition at line 1865 of file Split.c.

1866 {
1867  return split ? split->memo : NULL;
1868 }

◆ xaccSplitGetOtherSplit()

Split* xaccSplitGetOtherSplit ( const Split *  split)

The xaccSplitGetOtherSplit() is a convenience routine that returns the other of a pair of splits.

If there are more than two splits, it returns NULL.

Definition at line 2052 of file Split.c.

2053 {
2054  int i;
2055  Transaction *trans;
2056  int count, num_splits;
2057  Split *other = NULL;
2058  gboolean lot_split;
2059  gboolean trading_accts;
2060 
2061  if (!split) return NULL;
2062  trans = split->parent;
2063  if (!trans) return NULL;
2064 
2065  trading_accts = xaccTransUseTradingAccounts (trans);
2066  num_splits = xaccTransCountSplits(trans);
2067  count = num_splits;
2068  lot_split = qof_instance_has_slot(QOF_INSTANCE (split), "lot-split");
2069  if (!lot_split && !trading_accts && (2 != count)) return NULL;
2070 
2071  for (i = 0; i < num_splits; i++)
2072  {
2073  Split *s = xaccTransGetSplit(trans, i);
2074  if (s == split)
2075  {
2076  --count;
2077  continue;
2078  }
2079  if (qof_instance_has_slot (QOF_INSTANCE (s), "lot-split"))
2080  {
2081  --count;
2082  continue;
2083  }
2084  if (trading_accts &&
2086  {
2087  --count;
2088  continue;
2089  }
2090  other = s;
2091  }
2092  return (1 == count) ? other : NULL;
2093 }
Split * xaccTransGetSplit(const Transaction *trans, int i)
The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction.
Definition: Transaction.c:2216
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1013
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
Account used to record multiple commodity transactions.
Definition: Account.h:158
int xaccTransCountSplits(const Transaction *trans)
Returns the number of splits in this transaction.
Definition: Transaction.c:2317
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912

◆ xaccSplitGetParent()

Transaction* xaccSplitGetParent ( const Split *  split)

Returns the parent transaction of the split.

Definition at line 1800 of file Split.c.

1801 {
1802  return split ? split->parent : NULL;
1803 }

◆ xaccSplitGetReconcile()

char xaccSplitGetReconcile ( const Split *  split)

Returns the value of the reconcile flag.

Definition at line 1877 of file Split.c.

1878 {
1879  return split ? split->reconciled : ' ';
1880 }

◆ xaccSplitGetReconciledBalance()

gnc_numeric xaccSplitGetReconciledBalance ( const Split *  split)

Returns the reconciled-balance of this split.

The reconciled-balance is the currency-denominated balance of all transactions that have been marked as reconciled.

Returns the running balance up to & including the indicated split.

Definition at line 1282 of file Split.c.

1283 {
1284  return s ? s->reconciled_balance : gnc_numeric_zero();
1285 }

◆ xaccSplitGetSharePrice()

gnc_numeric xaccSplitGetSharePrice ( const Split *  split)

Returns the price of the split, that is, the value divided by the amount.

If the amount is zero, returns a gnc_numeric of value one.

Definition at line 1896 of file Split.c.

1897 {
1898  gnc_numeric amt, val, price;
1899  if (!split) return gnc_numeric_create(1, 1);
1900 
1901 
1902  /* if amount == 0 and value == 0, then return 1.
1903  * if amount == 0 and value != 0 then return 0.
1904  * otherwise return value/amount
1905  */
1906 
1907  amt = xaccSplitGetAmount(split);
1908  val = xaccSplitGetValue(split);
1909  if (gnc_numeric_zero_p(amt))
1910  {
1911  if (gnc_numeric_zero_p(val))
1912  return gnc_numeric_create(1, 1);
1913  return gnc_numeric_create(0, 1);
1914  }
1915  price = gnc_numeric_div(val, amt,
1918 
1919  /* During random checks we can get some very weird prices. Let's
1920  * handle some overflow and other error conditions by returning
1921  * zero. But still print an error to let us know it happened.
1922  */
1923  if (gnc_numeric_check(price))
1924  {
1925  PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
1926  G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
1927  gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
1928  return gnc_numeric_create(0, 1);
1929  }
1930 
1931  return price;
1932 }
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_div(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Division.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccSplitGetType()

const char* xaccSplitGetType ( const Split *  s)

The xaccIsPeerSplit() is a convenience routine that returns TRUE (a non-zero value) if the two splits share a common parent transaction, else it returns FALSE (zero).

gboolean xaccIsPeerSplit (const Split *split_1, const Split *split_2); Returns the split type, which is either the string "normal", or "stock-split" for a split from a stock split (pun intended? :-).

Definition at line 1944 of file Split.c.

1945 {
1946  GValue v = G_VALUE_INIT;
1947  const char *split_type = NULL;
1948 
1949  if (!s) return NULL;
1950  qof_instance_get_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
1951  if (G_VALUE_HOLDS_STRING (&v))
1952  split_type = g_value_get_string (&v);
1953  return split_type ? split_type : "normal";
1954 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccSplitGetValue()

gnc_numeric xaccSplitGetValue ( const Split *  split)

Returns the value of this split in the transaction's commodity.

Note that for cap-gains splits, this is slaved to the transaction that is causing the gains to occur.

Definition at line 1890 of file Split.c.

1891 {
1892  return split ? split->value : gnc_numeric_zero();
1893 }

◆ xaccSplitIsPeerSplit()

gboolean xaccSplitIsPeerSplit ( const Split *  split,
const Split *  other_split 
)

Report if a split is a peer of this one.

Parameters
other_splitThe split to test for being a peer of this one.
Returns
: True if other_split is registered as a peer of this one.

Definition at line 1999 of file Split.c.

2000 {
2001  const GncGUID* guid;
2002 
2003  g_return_val_if_fail (split != NULL, FALSE);
2004  g_return_val_if_fail (other_split != NULL, FALSE);
2005 
2006  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2007  return qof_instance_kvp_has_guid (QOF_INSTANCE (split), "lot-split",
2008  "peer_guid", guid);
2009 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
The type used to store guids in C.
Definition: guid.h:75

◆ xaccSplitLookup()

Split* xaccSplitLookup ( const GncGUID guid,
QofBook *  book 
)

The xaccSplitLookup() subroutine will return the split associated with the given id, or NULL if there is no such split.

Definition at line 1048 of file Split.c.

1049 {
1050  QofCollection *col;
1051  if (!guid || !book) return NULL;
1052  col = qof_book_get_collection (book, GNC_ID_SPLIT);
1053  return (Split *) qof_collection_lookup_entity (col, guid);
1054 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:214
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:603

◆ xaccSplitMakeStockSplit()

void xaccSplitMakeStockSplit ( Split *  s)

Mark a split to be of type stock split - after this, you shouldn't modify the value anymore, just the amount.

Definition at line 1959 of file Split.c.

1960 {
1961  GValue v = G_VALUE_INIT;
1962  xaccTransBeginEdit (s->parent);
1963 
1964  s->value = gnc_numeric_zero();
1965  g_value_init (&v, G_TYPE_STRING);
1966  g_value_set_string (&v, "stock-split");
1967  qof_instance_set_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
1968  SET_GAINS_VDIRTY(s);
1969  mark_split(s);
1970  qof_instance_set_dirty(QOF_INSTANCE(s));
1971  xaccTransCommitEdit(s->parent);
1972 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccSplitMergePeerSplits()

void xaccSplitMergePeerSplits ( Split *  split,
const Split *  other_split 
)

Merge the other_split's peer splits into split's peers.

Parameters
other_splitThe split donating the peer splits.

Definition at line 2029 of file Split.c.

2030 {
2031  xaccTransBeginEdit (split->parent);
2032  qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
2033  QOF_INSTANCE (other_split), "lot-split");
2034  mark_split (split);
2035  qof_instance_set_dirty (QOF_INSTANCE (split));
2036  xaccTransCommitEdit (split->parent);
2037 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccSplitOrder()

gint xaccSplitOrder ( const Split *  sa,
const Split *  sb 
)

The xaccSplitOrder(sa,sb) method is useful for sorting.

if sa and sb have different transactions, return their xaccTransOrder return a negative value if split sa has a smaller currency-value than sb, return a positive value if split sa has a larger currency-value than sb, return a negative value if split sa has a smaller share-price than sb, return a positive value if split sa has a larger share-price than sb, then compares memo and action using the strcmp() c-library routine, returning what strcmp would return. Then it compares the reconciled flags, then the reconciled dates, Finally, it returns zero if all of the above match.

Definition at line 1469 of file Split.c.

1470 {
1471  int retval;
1472  int comp;
1473  char *da, *db;
1474  gboolean action_for_num;
1475 
1476  if (sa == sb) return 0;
1477  /* nothing is always less than something */
1478  if (!sa) return -1;
1479  if (!sb) return +1;
1480 
1481  /* sort in transaction order, but use split action rather than trans num
1482  * according to book option */
1484  (xaccSplitGetBook (sa));
1485  if (action_for_num)
1486  retval = xaccTransOrder_num_action (sa->parent, sa->action,
1487  sb->parent, sb->action);
1488  else
1489  retval = xaccTransOrder (sa->parent, sb->parent);
1490  if (retval) return retval;
1491 
1492  /* otherwise, sort on memo strings */
1493  da = sa->memo ? sa->memo : "";
1494  db = sb->memo ? sb->memo : "";
1495  retval = g_utf8_collate (da, db);
1496  if (retval)
1497  return retval;
1498 
1499  /* otherwise, sort on action strings */
1500  da = sa->action ? sa->action : "";
1501  db = sb->action ? sb->action : "";
1502  retval = g_utf8_collate (da, db);
1503  if (retval != 0)
1504  return retval;
1505 
1506  /* the reconciled flag ... */
1507  if (sa->reconciled < sb->reconciled) return -1;
1508  if (sa->reconciled > sb->reconciled) return +1;
1509 
1510  /* compare amounts */
1512  if (comp < 0) return -1;
1513  if (comp > 0) return +1;
1514 
1516  if (comp < 0) return -1;
1517  if (comp > 0) return +1;
1518 
1519  /* if dates differ, return */
1520  if (sa->date_reconciled < sb->date_reconciled)
1521  return -1;
1522  else if (sa->date_reconciled > sb->date_reconciled)
1523  return 1;
1524 
1525  /* else, sort on guid - keeps sort stable. */
1526  retval = qof_instance_guid_compare(sa, sb);
1527  if (retval) return retval;
1528 
1529  return 0;
1530 }
gboolean qof_book_use_split_action_for_num_field(const QofBook *book)
Returns TRUE if this book uses split action field as the &#39;Num&#39; field, FALSE if it uses transaction nu...
Definition: qofbook.cpp:1046
int gnc_numeric_compare(gnc_numeric a, gnc_numeric b)
Returns 1 if a>b, -1 if b>a, 0 if a == b.
QofBook * xaccSplitGetBook(const Split *split)
Returns the book of this split, i.e.
Definition: Split.c:1938
int xaccTransOrder_num_action(const Transaction *ta, const char *actna, const Transaction *tb, const char *actnb)
The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting.
Definition: Transaction.c:1879
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
int xaccTransOrder(const Transaction *ta, const Transaction *tb)
The xaccTransOrder(ta,tb) method is useful for sorting.
Definition: Transaction.c:1873
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccSplitRemovePeerSplit()

void xaccSplitRemovePeerSplit ( Split *  split,
const Split *  other_split 
)

Remove a peer split from this split's lot-split list.

Parameters
other_splitThe split whose guid to remove

Definition at line 2012 of file Split.c.

2013 {
2014  const GncGUID* guid;
2015 
2016  g_return_if_fail (split != NULL);
2017  g_return_if_fail (other_split != NULL);
2018 
2019  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2020  xaccTransBeginEdit (split->parent);
2021  qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
2022  "peer_guid", guid);
2023  mark_split (split);
2024  qof_instance_set_dirty (QOF_INSTANCE (split));
2025  xaccTransCommitEdit (split->parent);
2026 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
The type used to store guids in C.
Definition: guid.h:75

◆ xaccSplitSetAction()

void xaccSplitSetAction ( Split *  split,
const char *  action 
)

The Action is an arbitrary user-assigned string.

The action field is an arbitrary user-assigned value. It is meant to be a very short (one to ten character) string that signifies the "type" of this split, such as e.g. Buy, Sell, Div, Withdraw, Deposit, ATM, Check, etc. The idea is that this field can be used to create custom reports or graphs of data. Note that the business features auto-fill this value, but doesn't depend on it. Rather than use this function directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically

Definition at line 1716 of file Split.c.

1717 {
1718  if (!split || !actn) return;
1719  xaccTransBeginEdit (split->parent);
1720 
1721  CACHE_REPLACE(split->action, actn);
1722  qof_instance_set_dirty(QOF_INSTANCE(split));
1723  xaccTransCommitEdit(split->parent);
1724 
1725 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccSplitSetAmount()

void xaccSplitSetAmount ( Split *  split,
gnc_numeric  amount 
)

The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have.

The following four setter functions set the prices and amounts. All of the routines always maintain balance: that is, invoking any of them will cause other splits in the transaction to be modified so that the net value of the transaction is zero.

IMPORTANT: The split should be parented by an account before any of these routines are invoked! This is because the actual setting of amounts/values requires SCU settings from the account. If these are not available, then amounts/values will be set to -1/0, which is an invalid value. I believe this order dependency is a bug, but I'm too lazy to find, fix & test at the moment ...

Note
If you use this on a newly created transaction, make sure that the 'value' is also set so that it doesn't remain zero.

Definition at line 1205 of file Split.c.

1206 {
1207  if (!s) return;
1208  g_return_if_fail(gnc_numeric_check(amt) == GNC_ERROR_OK);
1209  ENTER ("(split=%p) old amt=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT
1210  " new amt=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT, s,
1211  s->amount.num, s->amount.denom, amt.num, amt.denom);
1212 
1213  xaccTransBeginEdit (s->parent);
1214  if (s->acc)
1215  {
1216  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1218  g_assert (gnc_numeric_check (s->amount) == GNC_ERROR_OK);
1219  }
1220  else
1221  s->amount = amt;
1222 
1223  SET_GAINS_ADIRTY(s);
1224  mark_split (s);
1225  qof_instance_set_dirty(QOF_INSTANCE(s));
1226  xaccTransCommitEdit(s->parent);
1227  LEAVE("");
1228 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
No error.
Definition: gnc-numeric.h:224

◆ xaccSplitSetBaseValue()

void xaccSplitSetBaseValue ( Split *  split,
gnc_numeric  value,
const gnc_commodity *  base_currency 
)

Depending on the base_currency, set either the value or the amount of this split or both: If the base_currency is the transaction's commodity, set the value.

If it is the account's commodity, set the amount. If both, set both.

Note
WATCH OUT: When using this function and the transaction's and account's commodities are different, the amount or the value will be left as zero. This might screw up the multi-currency handling code in the register. So please think twice whether you need this function – using xaccSplitSetValue() together with xaccSplitSetAmount() is definitely the better and safer solution!

Definition at line 1288 of file Split.c.

1290 {
1291  const gnc_commodity *currency;
1292  const gnc_commodity *commodity;
1293 
1294  if (!s) return;
1295  xaccTransBeginEdit (s->parent);
1296 
1297  if (!s->acc)
1298  {
1299  PERR ("split must have a parent account");
1300  return;
1301  }
1302 
1303  currency = xaccTransGetCurrency (s->parent);
1304  commodity = xaccAccountGetCommodity (s->acc);
1305 
1306  /* If the base_currency is the transaction's commodity ('currency'),
1307  * set the value. If it's the account commodity, set the
1308  * amount. If both, set both. */
1309  if (gnc_commodity_equiv(currency, base_currency))
1310  {
1311  if (gnc_commodity_equiv(commodity, base_currency))
1312  {
1313  s->amount = gnc_numeric_convert(value,
1314  get_commodity_denom(s),
1316  }
1317  s->value = gnc_numeric_convert(value,
1318  get_currency_denom(s),
1320  }
1321  else if (gnc_commodity_equiv(commodity, base_currency))
1322  {
1323  s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
1325  }
1326  else
1327  {
1328  PERR ("inappropriate base currency %s "
1329  "given split currency=%s and commodity=%s\n",
1330  gnc_commodity_get_printname(base_currency),
1331  gnc_commodity_get_printname(currency),
1332  gnc_commodity_get_printname(commodity));
1333  return;
1334  }
1335 
1336  SET_GAINS_A_VDIRTY(s);
1337  mark_split (s);
1338  qof_instance_set_dirty(QOF_INSTANCE(s));
1339  xaccTransCommitEdit(s->parent);
1340 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
const char * gnc_commodity_get_printname(const gnc_commodity *cm)
Retrieve the &#39;print&#39; name for the specified commodity.
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.cpp:3151
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1346
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.

◆ xaccSplitSetDateReconciledSecs()

void xaccSplitSetDateReconciledSecs ( Split *  split,
time64  time 
)

Set the date on which this split was reconciled by specifying the time as time64.

Definition at line 1775 of file Split.c.

1776 {
1777  if (!split) return;
1778  xaccTransBeginEdit (split->parent);
1779 
1780  split->date_reconciled = secs;
1781  qof_instance_set_dirty(QOF_INSTANCE(split));
1782  xaccTransCommitEdit(split->parent);
1783 
1784 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccSplitSetMemo()

void xaccSplitSetMemo ( Split *  split,
const char *  memo 
)

The memo is an arbitrary string associated with a split.

It is intended to hold a short (zero to forty character) string that is displayed by the GUI along with this split. Users typically type in free form text from the GUI.

Definition at line 1697 of file Split.c.

1698 {
1699  if (!split || !memo) return;
1700  xaccTransBeginEdit (split->parent);
1701 
1702  CACHE_REPLACE(split->memo, memo);
1703  qof_instance_set_dirty(QOF_INSTANCE(split));
1704  xaccTransCommitEdit(split->parent);
1705 
1706 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccSplitSetReconcile()

void xaccSplitSetReconcile ( Split *  split,
char  reconciled_flag 
)

Set the reconcile flag.

The Reconcile flag is a single char, whose values are typically are 'n', 'y', 'c'. In Transaction.h, macros are defined for typical values (e.g. CREC, YREC).

Definition at line 1749 of file Split.c.

1750 {
1751  if (!split || split->reconciled == recn) return;
1752  xaccTransBeginEdit (split->parent);
1753 
1754  switch (recn)
1755  {
1756  case NREC:
1757  case CREC:
1758  case YREC:
1759  case FREC:
1760  case VREC:
1761  split->reconciled = recn;
1762  mark_split (split);
1763  qof_instance_set_dirty(QOF_INSTANCE(split));
1764  xaccAccountRecomputeBalance (split->acc);
1765  break;
1766  default:
1767  PERR("Bad reconciled flag");
1768  break;
1769  }
1770  xaccTransCommitEdit(split->parent);
1771 
1772 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define VREC
split is void
Definition: Split.h:75
#define YREC
The Split has been reconciled.
Definition: Split.h:72
#define FREC
frozen into accounting period
Definition: Split.h:73
void xaccAccountRecomputeBalance(Account *acc)
The following recompute the partial balances (stored with the transaction) and the total balance...
Definition: Account.cpp:2069
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define CREC
The Split has been cleared.
Definition: Split.h:71
#define NREC
not reconciled or cleared
Definition: Split.h:74

◆ xaccSplitSetSharePrice()

void xaccSplitSetSharePrice ( Split *  split,
gnc_numeric  price 
)
Deprecated:
The xaccSplitSetSharePrice() method sets the price of the split.

DEPRECATED - set the value and amount instead.

Definition at line 1171 of file Split.c.

1172 {
1173  if (!s) return;
1174  ENTER (" ");
1175  xaccTransBeginEdit (s->parent);
1176 
1177  s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
1178  price, get_currency_denom(s),
1180 
1181  SET_GAINS_VDIRTY(s);
1182  mark_split (s);
1183  qof_instance_set_dirty(QOF_INSTANCE(s));
1184  xaccTransCommitEdit(s->parent);
1185  LEAVE ("");
1186 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_mul(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Multiply a times b, returning the product.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccSplitSetSharePriceAndAmount()

void xaccSplitSetSharePriceAndAmount ( Split *  split,
gnc_numeric  price,
gnc_numeric  amount 
)

The xaccSplitSetSharePriceAndAmount() method will simultaneously update the share price and the number of shares.

This is a utility routine that is equivalent to a xaccSplitSetSharePrice() followed by and xaccSplitSetAmount(), except that it incurs the processing overhead of balancing only once, instead of twice.

Definition at line 1143 of file Split.c.

1144 {
1145  if (!s) return;
1146  ENTER (" ");
1147  xaccTransBeginEdit (s->parent);
1148 
1149  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1151  s->value = gnc_numeric_mul(s->amount, price,
1152  get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);
1153 
1154  SET_GAINS_A_VDIRTY(s);
1155  mark_split (s);
1156  qof_instance_set_dirty(QOF_INSTANCE(s));
1157  xaccTransCommitEdit(s->parent);
1158  LEAVE ("");
1159 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
gnc_numeric gnc_numeric_mul(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Multiply a times b, returning the product.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278

◆ xaccSplitSetValue()

void xaccSplitSetValue ( Split *  split,
gnc_numeric  value 
)

The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.

Note
If you use this on a newly created transaction, make sure that the 'amount' is also set so that it doesn't remain zero.

Definition at line 1241 of file Split.c.

1242 {
1243  gnc_numeric new_val;
1244  if (!s) return;
1245 
1246  g_return_if_fail(gnc_numeric_check(amt) == GNC_ERROR_OK);
1247  ENTER ("(split=%p) old val=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT
1248  " new val=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT, s,
1249  s->value.num, s->value.denom, amt.num, amt.denom);
1250 
1251  xaccTransBeginEdit (s->parent);
1252  new_val = gnc_numeric_convert(amt, get_currency_denom(s),
1254  if (gnc_numeric_check(new_val) == GNC_ERROR_OK &&
1255  !(gnc_numeric_zero_p (new_val) && !gnc_numeric_zero_p (amt)))
1256  s->value = new_val;
1257  else PERR("numeric error %s in converting the split value's denominator with amount %s and denom %d", gnc_numeric_errorCode_to_string(gnc_numeric_check(new_val)), gnc_numeric_to_string(amt), get_currency_denom(s));
1258 
1259  SET_GAINS_VDIRTY(s);
1260  mark_split (s);
1261  qof_instance_set_dirty(QOF_INSTANCE(s));
1262  xaccTransCommitEdit(s->parent);
1263  LEAVE ("");
1264 }
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
gchar * gnc_numeric_to_string(gnc_numeric n)
Convert to string.
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
const char * gnc_numeric_errorCode_to_string(GNCNumericErrorCode error_code)
Returns a string representation of the given GNCNumericErrorCode.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
No error.
Definition: gnc-numeric.h:224

◆ xaccSplitVoidFormerAmount()

gnc_numeric xaccSplitVoidFormerAmount ( const Split *  split)

Returns the original pre-void amount of a split.

Parameters
splitThe split in question.
Returns
A gnc_numeric containing the original value of this split. Returns a gnc_numeric of zero upon error.

Definition at line 2099 of file Split.c.

2100 {
2101  GValue v = G_VALUE_INIT;
2102  gnc_numeric *num = NULL;
2103  g_return_val_if_fail(split, gnc_numeric_zero());
2104  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_amt_str);
2105  if (G_VALUE_HOLDS_BOXED (&v))
2106  num = (gnc_numeric*)g_value_get_boxed (&v);
2107  return num ? *num : gnc_numeric_zero();
2108 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccSplitVoidFormerValue()

gnc_numeric xaccSplitVoidFormerValue ( const Split *  split)

Returns the original pre-void value of a split.

Parameters
splitThe split in question.
Returns
A gnc_numeric containing the original amount of this split. Returns a gnc_numeric of zero upon error.

Definition at line 2111 of file Split.c.

2112 {
2113  GValue v = G_VALUE_INIT;
2114  gnc_numeric *num = NULL;
2115  g_return_val_if_fail(split, gnc_numeric_zero());
2116  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_val_str);
2117  if (G_VALUE_HOLDS_BOXED (&v))
2118  num = (gnc_numeric*)g_value_get_boxed (&v);
2119  return num ? *num : gnc_numeric_zero();
2120 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransBeginEdit()

void xaccTransBeginEdit ( Transaction *  trans)

The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of its component splits.

If this is not done, errors will result.

Definition at line 1434 of file Transaction.c.

1435 {
1436  if (!trans) return;
1437  if (!qof_begin_edit(&trans->inst)) return;
1438 
1439  if (qof_book_shutting_down(qof_instance_get_book(trans))) return;
1440 
1442  {
1443  xaccOpenLog ();
1444  xaccTransWriteLog (trans, 'B');
1445  }
1446 
1447  /* Make a clone of the transaction; we will use this
1448  * in case we need to roll-back the edit. */
1449  trans->orig = dupe_trans (trans);
1450 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void xaccTransWriteLog(Transaction *trans, char flag)
Definition: TransLog.c:223
gboolean qof_begin_edit(QofInstance *inst)
begin_edit
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:579
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:530

◆ xaccTransCommitEdit()

void xaccTransCommitEdit ( Transaction *  trans)

The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are complete and should be made permanent.

Note this routine may result in the deletion of the transaction, if the transaction is "empty" (has no splits), or of xaccTransDestroy() was called on the transaction.

Definition at line 1633 of file Transaction.c.

1634 {
1635  if (!trans) return;
1636  ENTER ("(trans=%p)", trans);
1637 
1638  if (!qof_commit_edit (QOF_INSTANCE(trans)))
1639  {
1640  LEAVE("editlevel non-zero");
1641  return;
1642  }
1643 
1644  /* We increment this for the duration of the call
1645  * so other functions don't result in a recursive
1646  * call to xaccTransCommitEdit. */
1647  qof_instance_increase_editlevel(trans);
1648 
1649  if (was_trans_emptied(trans))
1650  qof_instance_set_destroying(trans, TRUE);
1651 
1652  /* Before committing the transaction, we are going to enforce certain
1653  * constraints. In particular, we want to enforce the cap-gains
1654  * and the balanced lot constraints. These constraints might
1655  * change the number of splits in this transaction, and the
1656  * transaction itself might be deleted. This is also why
1657  * we can't really enforce these constraints elsewhere: they
1658  * can cause pointers to splits and transactions to disappear out
1659  * from under the holder.
1660  */
1661  if (!qof_instance_get_destroying(trans) && scrub_data &&
1663  {
1664  /* If scrubbing gains recurses through here, don't call it again. */
1665  scrub_data = 0;
1666  /* The total value of the transaction should sum to zero.
1667  * Call the trans scrub routine to fix it. Indirectly, this
1668  * routine also performs a number of other transaction fixes too.
1669  */
1670  xaccTransScrubImbalance (trans, NULL, NULL);
1671  /* Get the cap gains into a consistent state as well. */
1672 
1673  /* Lot Scrubbing is temporarily disabled. */
1674  if (g_getenv("GNC_AUTO_SCRUB_LOTS") != NULL)
1675  xaccTransScrubGains (trans, NULL);
1676 
1677  /* Allow scrubbing in transaction commit again */
1678  scrub_data = 1;
1679  }
1680 
1681  /* Record the time of last modification */
1682  if (0 == trans->date_entered)
1683  {
1684  trans->date_entered = gnc_time(NULL);
1685  qof_instance_set_dirty(QOF_INSTANCE(trans));
1686  }
1687 
1688  qof_commit_edit_part2(QOF_INSTANCE(trans),
1689  (void (*) (QofInstance *, QofBackendError))
1690  trans_on_error,
1691  (void (*) (QofInstance *)) trans_cleanup_commit,
1692  (void (*) (QofInstance *)) do_destroy);
1693  LEAVE ("(trans=%p)", trans);
1694 }
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:59
gboolean qof_instance_get_destroying(gconstpointer ptr)
Retrieve the flag that indicates whether or not this object is about to be destroyed.
gboolean qof_commit_edit(QofInstance *inst)
commit_edit helpers
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
void xaccTransScrubImbalance(Transaction *trans, Account *root, Account *account)
Correct transaction imbalances.
Definition: Scrub.c:794
void xaccTransScrubGains(Transaction *trans, Account *gain_acc)
The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction...
Definition: Transaction.c:2880
gboolean qof_commit_edit_part2(QofInstance *inst, void(*on_error)(QofInstance *, QofBackendError), void(*on_done)(QofInstance *), void(*on_free)(QofInstance *))
part2 – deal with the backend
#define xaccTransGetBook(X)
Definition: Transaction.h:771
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:273
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:530

◆ xaccTransCopyFromClipBoard()

void xaccTransCopyFromClipBoard ( const Transaction *  from_trans,
Transaction *  to_trans,
const Account from_acc,
Account to_acc,
gboolean  no_date 
)

This function explicitly must robustly handle some unusual input.

'from_trans' may be a duped trans (see xaccDupeTransaction), so its splits may not really belong to the accounts that they say they do.

'from_acc' need not be a valid account. It may be an already freed Account. Therefore, it must not be dereferenced at all.

Neither 'from_trans', nor 'from_acc', nor any of 'from's splits may be modified in any way.

'no_date' if TRUE will not copy the date posted.

The 'to_trans' transaction will end up with valid copies of from's splits. In addition, the copies of any of from's splits that were in from_acc (or at least claimed to be) will end up in to_acc.

Definition at line 739 of file Transaction.c.

741 {
742  gboolean change_accounts = FALSE;
743  GList *node;
744 
745  if (!from_trans || !to_trans)
746  return;
747 
748  change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
749  xaccTransBeginEdit(to_trans);
750 
751  FOR_EACH_SPLIT(to_trans, xaccSplitDestroy(s));
752  g_list_free(to_trans->splits);
753  to_trans->splits = NULL;
754 
755  xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
756  xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));
757 
758  if ((xaccTransGetNum(to_trans) == NULL) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
759  xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));
760 
761  xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
762  xaccTransSetAssociation(to_trans, xaccTransGetAssociation (from_trans));
763  if(!no_date)
764  {
765  xaccTransSetDatePostedSecs(to_trans, xaccTransRetDatePosted (from_trans));
766  }
767 
768  /* Each new split will be parented to 'to' */
769  for (node = from_trans->splits; node; node = node->next)
770  {
771  Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
772  xaccSplitCopyOnto(node->data, new_split);
773  if (change_accounts && xaccSplitGetAccount(node->data) == from_acc)
774  xaccSplitSetAccount(new_split, to_acc);
775  xaccSplitSetParent(new_split, to_trans);
776  }
777  xaccTransCommitEdit(to_trans);
778 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
gboolean xaccSplitDestroy(Split *split)
Destructor.
Definition: Split.c:1439
const char * xaccTransGetAssociation(const Transaction *trans)
Gets the transaction association.
Definition: Transaction.c:2338
void xaccTransSetNotes(Transaction *trans, const char *notes)
Sets the transaction Notes.
Definition: Transaction.c:2175
void xaccSplitCopyOnto(const Split *from_split, Split *to_split)
This is really a helper for xaccTransCopyOnto.
Definition: Split.c:631
void xaccTransSetDescription(Transaction *trans, const char *desc)
Sets the transaction Description.
Definition: Transaction.c:2138
void xaccTransSetNum(Transaction *trans, const char *xnum)
Sets the transaction Number (or ID) field; rather than use this function directly, see &#39;gnc_set_num_action&#39; in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
Definition: Transaction.c:2118
const char * xaccTransGetNum(const Transaction *trans)
Gets the transaction Number (or ID) field; rather than use this function directly, see &#39;gnc_get_num_action&#39; and &#39;gnc_get_action_num&#39; in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
Definition: Transaction.c:2326
void xaccTransSetCurrency(Transaction *trans, gnc_commodity *curr)
Set a new currency on a transaction.
Definition: Transaction.c:1405
const char * xaccTransGetNotes(const Transaction *trans)
Gets the transaction Notes.
Definition: Transaction.c:2349
void xaccTransSetAssociation(Transaction *trans, const char *assoc)
Sets the transaction Association.
Definition: Transaction.c:2149
time64 xaccTransRetDatePosted(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2396
const char * xaccTransGetDescription(const Transaction *trans)
Gets the transaction Description.
Definition: Transaction.c:2332
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
Split * xaccMallocSplit(QofBook *book)
Constructor.
Definition: Split.c:527
void xaccTransSetDatePostedSecs(Transaction *trans, time64 secs)
The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)).
Definition: Transaction.c:1967
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1346

◆ xaccTransCopyToClipBoard()

Transaction* xaccTransCopyToClipBoard ( const Transaction *  from_trans)

Copy a transaction to the 'clipboard' transaction using dupe_transaction.

The 'clipboard' transaction must never be dereferenced.

Definition at line 699 of file Transaction.c.

700 {
701  Transaction *to_trans;
702 
703  if (!from_trans)
704  return NULL;
705 
706  to_trans = dupe_trans(from_trans);
707  return to_trans;
708 }

◆ xaccTransCountSplits()

int xaccTransCountSplits ( const Transaction *  trans)

Returns the number of splits in this transaction.

Definition at line 2317 of file Transaction.c.

2318 {
2319  gint i = 0;
2320  g_return_val_if_fail (trans != NULL, 0);
2321  FOR_EACH_SPLIT(trans, i++);
2322  return i;
2323 }

◆ xaccTransDestroy()

void xaccTransDestroy ( Transaction *  trans)

Destroys a transaction.

Each split in transaction trans is removed from its account and destroyed as well.

If the transaction has not already been opened for editing with xaccTransBeginEdit() then the changes are committed immediately. Otherwise, the caller must follow up with either xaccTransCommitEdit(), in which case the transaction and split memory will be freed, or xaccTransRollbackEdit(), in which case nothing at all is freed, and everything is put back into original order.

Parameters
transthe transaction to destroy

Definition at line 1456 of file Transaction.c.

1457 {
1458  if (!trans) return;
1459 
1460  if (!xaccTransGetReadOnly (trans) ||
1462  {
1463  xaccTransBeginEdit(trans);
1464  qof_instance_set_destroying(trans, TRUE);
1465  xaccTransCommitEdit(trans);
1466  }
1467 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2475
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:530

◆ xaccTransEqual()

gboolean xaccTransEqual ( const Transaction *  ta,
const Transaction *  tb,
gboolean  check_guids,
gboolean  check_splits,
gboolean  check_balances,
gboolean  assume_ordered 
)

Equality.

Parameters
taFirst transaction to compare
tbSecond transaction to compare
check_guidsIf TRUE, try a guid_equal() on the GUIDs of both transactions if their pointers are not equal in the first place. Also passed to subsidiary calls to xaccSplitEqual.
check_splitsIf TRUE, after checking the transaction data structures for equality, also check all splits attached to the transation for equality.
check_balancesIf TRUE, when checking splits also compare balances between the two splits. Balances are recalculated whenever a split is added or removed from an account, so YMMV on whether this should be set.
assume_orderedIf TRUE, assume that the splits in each transaction appear in the same order. This saves some time looking up splits by GncGUID, and is required for checking duplicated transactions because all the splits have new GUIDs.

Definition at line 854 of file Transaction.c.

859 {
860  gboolean same_book;
861 
862  if (!ta && !tb) return TRUE; /* Arguable. FALSE may be better. */
863 
864  if (!ta || !tb)
865  {
866  PINFO ("one is NULL");
867  return FALSE;
868  }
869 
870  if (ta == tb) return TRUE;
871 
872  same_book = qof_instance_get_book(QOF_INSTANCE(ta)) == qof_instance_get_book(QOF_INSTANCE(tb));
873 
874  if (check_guids)
875  {
876  if (qof_instance_guid_compare(ta, tb) != 0)
877  {
878  PINFO ("GUIDs differ");
879  return FALSE;
880  }
881  }
882 
883  if (!gnc_commodity_equal(ta->common_currency, tb->common_currency))
884  {
885  PINFO ("commodities differ %s vs %s",
886  gnc_commodity_get_unique_name (ta->common_currency),
887  gnc_commodity_get_unique_name (tb->common_currency));
888  return FALSE;
889  }
890 
891  if (ta->date_entered != tb->date_entered)
892  {
893  char buf1[100];
894  char buf2[100];
895 
896  (void)gnc_time64_to_iso8601_buff(ta->date_entered, buf1);
897  (void)gnc_time64_to_iso8601_buff(tb->date_entered, buf2);
898  PINFO ("date entered differs: '%s' vs '%s'", buf1, buf2);
899  return FALSE;
900  }
901 
902  if (ta->date_posted != tb->date_posted)
903  {
904  char buf1[100];
905  char buf2[100];
906 
907  (void)gnc_time64_to_iso8601_buff(ta->date_posted, buf1);
908  (void)gnc_time64_to_iso8601_buff(tb->date_posted, buf2);
909  PINFO ("date posted differs: '%s' vs '%s'", buf1, buf2);
910  return FALSE;
911  }
912 
913  /* If the same book, since we use cached strings, we can just compare pointer
914  * equality for num and description
915  */
916  if ((same_book && ta->num != tb->num) || (!same_book && g_strcmp0(ta->num, tb->num) != 0))
917  {
918  PINFO ("num differs: %s vs %s", ta->num, tb->num);
919  return FALSE;
920  }
921 
922  if ((same_book && ta->description != tb->description)
923  || (!same_book && g_strcmp0(ta->description, tb->description)))
924  {
925  PINFO ("descriptions differ: %s vs %s", ta->description, tb->description);
926  return FALSE;
927  }
928 
929  if (qof_instance_compare_kvp (QOF_INSTANCE (ta), QOF_INSTANCE (tb)) != 0)
930  {
931  char *frame_a;
932  char *frame_b;
933 
934  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (ta));
935  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (tb));
936 
937 
938  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
939 
940  g_free (frame_a);
941  g_free (frame_b);
942 
943  return FALSE;
944  }
945 
946  if (check_splits)
947  {
948  if ((!ta->splits && tb->splits) || (!tb->splits && ta->splits))
949  {
950  PINFO ("only one has splits");
951  return FALSE;
952  }
953 
954  if (ta->splits && tb->splits)
955  {
956  GList *node_a, *node_b;
957 
958  for (node_a = ta->splits, node_b = tb->splits;
959  node_a;
960  node_a = node_a->next, node_b = node_b->next)
961  {
962  Split *split_a = node_a->data;
963  Split *split_b;
964 
965  /* don't presume that the splits are in the same order */
966  if (!assume_ordered)
967  node_b = g_list_find_custom (tb->splits, split_a,
968  compare_split_guids);
969 
970  if (!node_b)
971  {
972  gchar guidstr[GUID_ENCODING_LENGTH+1];
973  guid_to_string_buff (xaccSplitGetGUID (split_a),guidstr);
974 
975  PINFO ("first has split %s and second does not",guidstr);
976  return FALSE;
977  }
978 
979  split_b = node_b->data;
980 
981  if (!xaccSplitEqual (split_a, split_b, check_guids, check_balances,
982  FALSE))
983  {
984  char str_a[GUID_ENCODING_LENGTH + 1];
985  char str_b[GUID_ENCODING_LENGTH + 1];
986 
987  guid_to_string_buff (xaccSplitGetGUID (split_a), str_a);
988  guid_to_string_buff (xaccSplitGetGUID (split_b), str_b);
989 
990  PINFO ("splits %s and %s differ", str_a, str_b);
991  return FALSE;
992  }
993  }
994 
995  if (g_list_length (ta->splits) != g_list_length (tb->splits))
996  {
997  PINFO ("different number of splits");
998  return FALSE;
999  }
1000  }
1001  }
1002 
1003  return TRUE;
1004 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:256
gboolean gnc_commodity_equal(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equal.
gchar * guid_to_string_buff(const GncGUID *guid, gchar *str)
The guid_to_string_buff() routine puts a null-terminated string encoding of the id into the memory po...
Definition: guid.cpp:174
gboolean xaccSplitEqual(const Split *sa, const Split *sb, gboolean check_guids, gboolean check_balances, gboolean check_txn_splits)
Equality.
Definition: Split.c:759
#define GUID_ENCODING_LENGTH
Number of characters needed to encode a guid as a string not including the null terminator.
Definition: guid.h:84
#define xaccSplitGetGUID(X)
Definition: Split.h:544
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
const char * gnc_commodity_get_unique_name(const gnc_commodity *cm)
Retrieve the &#39;unique&#39; name for the specified commodity.
char * gnc_time64_to_iso8601_buff(time64 time, char *buff)
The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-860...
Definition: gnc-date.cpp:1142

◆ xaccTransGetAccountAmount()

gnc_numeric xaccTransGetAccountAmount ( const Transaction *  trans,
const Account account 
)

Same as xaccTransGetAccountValue, but uses the Account's commodity.

Definition at line 1184 of file Transaction.c.

1185 {
1186  gnc_numeric total = gnc_numeric_zero ();
1187  if (!trans || !acc) return total;
1188 
1189  total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
1191  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1192  total = gnc_numeric_add_fixed(
1193  total, xaccSplitGetAmount(s)));
1194  return total;
1195 }
int xaccAccountGetCommoditySCU(const Account *acc)
Return the SCU for the account.
Definition: Account.cpp:2452
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccTransGetAccountBalance()

gnc_numeric xaccTransGetAccountBalance ( const Transaction *  trans,
const Account account 
)

Get the account balance for the specified account after the last split in the specified transaction.

Definition at line 1308 of file Transaction.c.

1310 {
1311  GList *node;
1312  Split *last_split = NULL;
1313 
1314  // Not really the appropriate error value.
1315  g_return_val_if_fail(account && trans, gnc_numeric_error(GNC_ERROR_ARG));
1316 
1317  for (node = trans->splits; node; node = node->next)
1318  {
1319  Split *split = node->data;
1320 
1321  if (!xaccTransStillHasSplit(trans, split))
1322  continue;
1323  if (xaccSplitGetAccount(split) != account)
1324  continue;
1325 
1326  if (!last_split)
1327  {
1328  last_split = split;
1329  continue;
1330  }
1331 
1332  /* This test needs to correspond to the comparison function used when
1333  sorting the splits for computing the running balance. */
1334  if (xaccSplitOrder (last_split, split) < 0)
1335  last_split = split;
1336  }
1337 
1338  return xaccSplitGetBalance (last_split);
1339 }
gint xaccSplitOrder(const Split *sa, const Split *sb)
The xaccSplitOrder(sa,sb) method is useful for sorting.
Definition: Split.c:1469
gnc_numeric xaccSplitGetBalance(const Split *s)
Returns the running balance up to and including the indicated split.
Definition: Split.c:1270
gnc_numeric gnc_numeric_error(GNCNumericErrorCode error_code)
Create a gnc_numeric object that signals the error condition noted by error_code, rather than a numbe...
Argument is not a valid number.
Definition: gnc-numeric.h:225
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912

◆ xaccTransGetAccountValue()

gnc_numeric xaccTransGetAccountValue ( const Transaction *  trans,
const Account account 
)

The xaccTransGetAccountValue() method returns the total value applied to a particular account.

In some cases there may be multiple Splits in a single Transaction applied to one account (in particular when trying to balance Lots) – this function is just a convienience to view everything at once.

Definition at line 1168 of file Transaction.c.

1170 {
1171  gnc_numeric total = gnc_numeric_zero ();
1172  if (!trans || !acc) return total;
1173 
1174  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1175 {
1176  total = gnc_numeric_add (total, xaccSplitGetValue (s),
1179  });
1180  return total;
1181 }
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:189
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

◆ xaccTransGetAPARAcctSplitList()

SplitList* xaccTransGetAPARAcctSplitList ( const Transaction *  trans,
gboolean  strict 
)

The xaccTransGetAPARSplitList() method returns a GList of the splits in a transaction that belong to an AR or AP account.

Parameters
transThe transaction
strictThis slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot
Returns
The list of splits. This list must be freed when you are done with it.

Definition at line 2256 of file Transaction.c.

2257 {
2258  GList *apar_splits = NULL;
2259  FOR_EACH_SPLIT (trans,
2260  const Account *account = xaccSplitGetAccount(s);
2261  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2262  {
2263 
2264  if (!strict)
2265  apar_splits = g_list_prepend (apar_splits, s);
2266  else
2267  {
2268  GncOwner owner;
2269  GNCLot *lot = xaccSplitGetLot(s);
2270  if (lot &&
2271  (gncInvoiceGetInvoiceFromLot (lot) ||
2272  gncOwnerGetOwnerFromLot (lot, &owner)))
2273  apar_splits = g_list_prepend (apar_splits, s);
2274  }
2275  }
2276  );
2277 
2278  apar_splits = g_list_reverse (apar_splits);
2279  return apar_splits;
2280 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
STRUCTS.
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:614
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4243
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1248
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
GNCLot * xaccSplitGetLot(const Split *split)
Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn&#39;t be...
Definition: Split.c:1850

◆ xaccTransGetCurrency()

gnc_commodity* xaccTransGetCurrency ( const Transaction *  trans)

Returns the valuation commodity of this transaction.

Each transaction's valuation commodity, or 'currency' is, by definition, the common currency in which all splits in the transaction can be valued. The total value of the transaction must be zero when all splits are valued in this currency.

Note
What happens if the Currency isn't set? Ans: bad things.

Definition at line 1346 of file Transaction.c.

1347 {
1348  return trans ? trans->common_currency : NULL;
1349 }

◆ xaccTransGetDate()

time64 xaccTransGetDate ( const Transaction *  trans)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank. (Although having different function names, GetDate and GetDatePosted refer to the same single date.)

Definition at line 2382 of file Transaction.c.

2383 {
2384  return trans ? trans->date_posted : 0;
2385 }

◆ xaccTransGetDateEntered()

time64 xaccTransGetDateEntered ( const Transaction *  trans)

Retrieve the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 2389 of file Transaction.c.

2390 {
2391  return trans ? trans->date_entered : 0;
2392 }

◆ xaccTransGetDatePostedGDate()

GDate xaccTransGetDatePostedGDate ( const Transaction *  trans)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank.

Definition at line 2402 of file Transaction.c.

2403 {
2404  GDate result;
2405  g_date_clear (&result, 1);
2406  if (trans)
2407  {
2408  /* Can we look up this value in the kvp slot? If yes, use it
2409  * from there because it doesn't suffer from time zone
2410  * shifts. */
2411  GValue v = G_VALUE_INIT;
2412  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_DATE_POSTED);
2413  if (G_VALUE_HOLDS_BOXED (&v))
2414  result = *(GDate*)g_value_get_boxed (&v);
2415  if (! g_date_valid (&result) || gdate_to_time64 (result) == INT64_MAX)
2416  {
2417  /* Well, this txn doesn't have a valid GDate saved in a slot.
2418  * time64_to_gdate() uses local time and we want UTC so we have
2419  * to write it out.
2420  */
2421  time64 time = xaccTransGetDate(trans);
2422  struct tm *stm = gnc_gmtime(&time);
2423  if (stm)
2424  {
2425  g_date_set_dmy(&result, stm->tm_mday,
2426  (GDateMonth)(stm->tm_mon + 1),
2427  stm->tm_year + 1900);
2428  free(stm);
2429  }
2430  }
2431  }
2432  return result;
2433 }
time64 xaccTransGetDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2382
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1256
struct tm * gnc_gmtime(const time64 *secs)
fill out a time struct from a 64-bit time value
Definition: gnc-date.cpp:189
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:84

◆ xaccTransGetFirstAPARAcctSplit()

Split* xaccTransGetFirstAPARAcctSplit ( const Transaction *  trans,
gboolean  strict 
)

The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an AR or AP account.

Parameters
transThe transaction
strictThis slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot

If there is no such split in the transaction NULL will be returned.

Definition at line 2293 of file Transaction.c.

2294 {
2295  FOR_EACH_SPLIT (trans,
2296  const Account *account = xaccSplitGetAccount(s);
2297  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2298  {
2299  GNCLot *lot;
2300  GncOwner owner;
2301 
2302  if (!strict)
2303  return s;
2304 
2305  lot = xaccSplitGetLot(s);
2306  if (lot &&
2307  (gncInvoiceGetInvoiceFromLot (lot) ||
2308  gncOwnerGetOwnerFromLot (lot, &owner)))
2309  return s;
2310  }
2311  );
2312 
2313  return NULL;
2314 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
STRUCTS.
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:614
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4243
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1248
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
GNCLot * xaccSplitGetLot(const Split *split)
Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn&#39;t be...
Definition: Split.c:1850

◆ xaccTransGetFirstPaymentAcctSplit()

Split* xaccTransGetFirstPaymentAcctSplit ( const Transaction *  trans)

The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an account which is considered a valid account for business payments.

Parameters
transThe transaction

If there is no such split in the transaction NULL will be returned.

Definition at line 2282 of file Transaction.c.

2283 {
2284  FOR_EACH_SPLIT (trans,
2285  const Account *account = xaccSplitGetAccount(s);
2286  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2287  return s;
2288  );
2289 
2290  return NULL;
2291 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
STRUCTS.
gboolean gncBusinessIsPaymentAcctType(GNCAccountType type)
Returns whether the given account type is a valid type to use in business payments.
Definition: gncBusiness.c:92
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912

◆ xaccTransGetImbalance()

MonetaryList* xaccTransGetImbalance ( const Transaction *  trans)

The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency for which the balance is not zero.

If the use of currency accounts is disabled, then this will be only the common currency for the transaction and xaccTransGetImbalance becomes equivalent to xaccTransGetImbalanceValue. Otherwise it will return a list containing the imbalance in each currency.

Definition at line 1050 of file Transaction.c.

1051 {
1052  /* imbal_value is used if either (1) the transaction has a non currency
1053  split or (2) all the splits are in the same currency. If there are
1054  no non-currency splits and not all splits are in the same currency then
1055  imbal_list is used to compute the imbalance. */
1056  MonetaryList *imbal_list = NULL;
1057  gnc_numeric imbal_value = gnc_numeric_zero();
1058  gboolean trading_accts;
1059 
1060  if (!trans) return imbal_list;
1061 
1062  ENTER("(trans=%p)", trans);
1063 
1064  trading_accts = xaccTransUseTradingAccounts (trans);
1065 
1066  /* If using trading accounts and there is at least one split that is not
1067  in the transaction currency or a split that has a price or exchange
1068  rate other than 1, then compute the balance in each commodity in the
1069  transaction. Otherwise (all splits are in the transaction's currency)
1070  then compute the balance using the value fields.
1071 
1072  Optimize for the common case of only one currency and a balanced
1073  transaction. */
1074  FOR_EACH_SPLIT(trans,
1075  {
1076  gnc_commodity *commodity;
1078  if (trading_accts &&
1079  (imbal_list ||
1080  ! gnc_commodity_equiv(commodity, trans->common_currency) ||
1082  {
1083  /* Need to use (or already are using) a list of imbalances in each of
1084  the currencies used in the transaction. */
1085  if (! imbal_list)
1086  {
1087  /* All previous splits have been in the transaction's common
1088  currency, so imbal_value is in this currency. */
1089  imbal_list = gnc_monetary_list_add_value(imbal_list,
1090  trans->common_currency,
1091  imbal_value);
1092  }
1093  imbal_list = gnc_monetary_list_add_value(imbal_list, commodity,
1094  xaccSplitGetAmount(s));
1095  }
1096 
1097  /* Add it to the value accumulator in case we need it. */
1098  imbal_value = gnc_numeric_add(imbal_value, xaccSplitGetValue(s),
1100  } );
1101 
1102 
1103  if (!imbal_list && !gnc_numeric_zero_p(imbal_value))
1104  {
1105  /* Not balanced and no list, create one. If we found multiple currencies
1106  and no non-currency commodity then imbal_list will already exist and
1107  we won't get here. */
1108  imbal_list = gnc_monetary_list_add_value(imbal_list,
1109  trans->common_currency,
1110  imbal_value);
1111  }
1112 
1113  /* Delete all the zero entries from the list, perhaps leaving an
1114  empty list */
1115  imbal_list = gnc_monetary_list_delete_zeros(imbal_list);
1116 
1117  LEAVE("(trans=%p), imbal=%p", trans, imbal_list);
1118  return imbal_list;
1119 }
gboolean gnc_numeric_equal(gnc_numeric a, gnc_numeric b)
Equivalence predicate: Returns TRUE (1) if a and b represent the same number.
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1013
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:189
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
MonetaryList * gnc_monetary_list_delete_zeros(MonetaryList *list)
Delete all entries in the list that have zero value.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.cpp:3151
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccTransGetImbalanceValue()

gnc_numeric xaccTransGetImbalanceValue ( const Transaction *  trans)

The xaccTransGetImbalanceValue() method returns the total value of the transaction.

In a pure double-entry system, this imbalance should be exactly zero, and if it is not, something is broken. However, when double-entry semantics are not enforced, unbalanced transactions can sneak in, and this routine can be used to find out how much things are off by. The value returned is denominated in the currency that is returned by the xaccTransFindCommonCurrency() method.

If the use of currency exchange accounts is enabled then the a a transaction must be balanced in each currency it uses to be considered to be balanced. The method xaccTransGetImbalance is used by most code to take this into consideration. This method is only used in a few places that want the transaction value even if currency exchange accounts are enabled.

Definition at line 1034 of file Transaction.c.

1035 {
1036  gnc_numeric imbal = gnc_numeric_zero();
1037  if (!trans) return imbal;
1038 
1039  ENTER("(trans=%p)", trans);
1040  /* Could use xaccSplitsComputeValue, except that we want to use
1041  GNC_HOW_DENOM_EXACT */
1042  FOR_EACH_SPLIT(trans, imbal =
1045  LEAVE("(trans=%p) imbal=%s", trans, gnc_num_dbg_to_string(imbal));
1046  return imbal;
1047 }
gchar * gnc_num_dbg_to_string(gnc_numeric n)
Convert to string.
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:189
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

◆ xaccTransGetNotes()

const char* xaccTransGetNotes ( const Transaction *  trans)

Gets the transaction Notes.

The Notes field is only visible in the register in double-line mode

Definition at line 2349 of file Transaction.c.

2350 {
2351  GValue v = G_VALUE_INIT;
2352  if (!trans) return NULL;
2353  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2354  if (G_VALUE_HOLDS_STRING (&v))
2355  return g_value_get_string (&v);
2356  return NULL;
2357 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetPaymentAcctSplitList()

SplitList* xaccTransGetPaymentAcctSplitList ( const Transaction *  trans)

The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits in a transaction that belong to an account which is considered a valid account for business payments.

Parameters
transThe transaction
Returns
The list of splits. This list must be freed when you are done with it.

Definition at line 2242 of file Transaction.c.

2243 {
2244  GList *pay_splits = NULL;
2245  FOR_EACH_SPLIT (trans,
2246  const Account *account = xaccSplitGetAccount(s);
2247  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2248  pay_splits = g_list_prepend (pay_splits, s);
2249  );
2250 
2251  pay_splits = g_list_reverse (pay_splits);
2252  return pay_splits;
2253 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
STRUCTS.
gboolean gncBusinessIsPaymentAcctType(GNCAccountType type)
Returns whether the given account type is a valid type to use in business payments.
Definition: gncBusiness.c:92
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912

◆ xaccTransGetReadOnly()

const char* xaccTransGetReadOnly ( Transaction *  trans)

Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text.

Definition at line 2475 of file Transaction.c.

2476 {
2477  if (!trans)
2478  return NULL;
2479 
2480  if (!trans->reason_cache_valid)
2481  {
2482  GValue v = G_VALUE_INIT;
2483  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_READ_ONLY_REASON);
2484 
2485  /* Clear possible old cache value first */
2486  g_free (trans->readonly_reason);
2487  trans->readonly_reason = NULL;
2488 
2489  /* Then set the new one */
2490  if (G_VALUE_HOLDS_STRING (&v))
2491  {
2492  trans->readonly_reason = g_value_dup_string (&v);
2493  g_value_unset (&v);
2494  }
2495  trans->reason_cache_valid = TRUE;
2496  }
2497  return trans->readonly_reason;
2498 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetReversedBy()

Transaction* xaccTransGetReversedBy ( const Transaction *  trans)

Returns the transaction that reversed the given transaction.

Parameters
transa Transaction that has been reversed
Returns
the transaction that reversed the given transaction, or NULL if the given transaction has not been reversed.

Definition at line 2811 of file Transaction.c.

2812 {
2813  GValue v = G_VALUE_INIT;
2814  g_return_val_if_fail(trans, NULL);
2815  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_REVERSED_BY);
2816  if (G_VALUE_HOLDS_BOXED (&v))
2817  return xaccTransLookup((GncGUID*)g_value_get_boxed (&v),
2818  qof_instance_get_book(trans));
2819  return NULL;
2820 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
Transaction * xaccTransLookup(const GncGUID *guid, QofBook *book)
The xaccTransLookup() subroutine will return the transaction associated with the given id...
Definition: Transaction.c:1022
The type used to store guids in C.
Definition: guid.h:75

◆ xaccTransGetSplit()

Split* xaccTransGetSplit ( const Transaction *  trans,
int  i 
)

The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction.

Parameters
transThe transaction
iThe split number. Valid values for i are zero to (number_of__splits-1). An invalid value of i will cause NULL to be returned. A convenient way of cycling through all splits is to start at zero, and keep incrementing until a null value is returned.

Definition at line 2216 of file Transaction.c.

2217 {
2218  int j = 0;
2219  if (!trans || i < 0) return NULL;
2220 
2221  FOR_EACH_SPLIT(trans, { if (i == j) return s; j++; });
2222  return NULL;
2223 }

◆ xaccTransGetSplitList()

SplitList* xaccTransGetSplitList ( const Transaction *  trans)

The xaccTransGetSplitList() method returns a GList of the splits in a transaction.

Parameters
transThe transaction
Returns
The list of splits. This list must NOT be modified. Do NOT free this list when you are done with it.

Definition at line 2236 of file Transaction.c.

2237 {
2238  return trans ? trans->splits : NULL;
2239 }

◆ xaccTransGetTxnType()

char xaccTransGetTxnType ( const Transaction *  trans)

Returns the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2459 of file Transaction.c.

2460 {
2461  const char *s = NULL;
2462  GValue v = G_VALUE_INIT;
2463 
2464  if (!trans) return TXN_TYPE_NONE;
2465  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2466  if (G_VALUE_HOLDS_STRING (&v))
2467  s = g_value_get_string (&v);
2468  if (s && strlen (s) == 1)
2469  return *s;
2470 
2471  return TXN_TYPE_NONE;
2472 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
#define TXN_TYPE_NONE
No transaction type.
Definition: Transaction.h:123

◆ xaccTransGetVoidReason()

const char* xaccTransGetVoidReason ( const Transaction *  transaction)

Returns the user supplied textual reason why a transaction was voided.

Parameters
transactionThe transaction in question.
Returns
A pointer to the user supplied reason for voiding.

Definition at line 2725 of file Transaction.c.

2726 {
2727  GValue v = G_VALUE_INIT;
2728  g_return_val_if_fail(trans, FALSE);
2729 
2730  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2731  if (G_VALUE_HOLDS_STRING (&v))
2732  return g_value_get_string (&v);
2733  return NULL;
2734 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetVoidStatus()

gboolean xaccTransGetVoidStatus ( const Transaction *  transaction)

Retrieve information on whether or not a transaction has been voided.

Parameters
transactionThe transaction in question.
Returns
TRUE if the transaction is void, FALSE otherwise. Also returns FALSE upon an error.

Definition at line 2712 of file Transaction.c.

2713 {
2714  const char *s = NULL;
2715  GValue v = G_VALUE_INIT;
2716  g_return_val_if_fail(trans, FALSE);
2717 
2718  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2719  if (G_VALUE_HOLDS_STRING (&v))
2720  s = g_value_get_string (&v);
2721  return s && strlen(s);
2722 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetVoidTime()

time64 xaccTransGetVoidTime ( const Transaction *  tr)

Returns the time that a transaction was voided.

Parameters
trThe transaction in question.
Returns
A time64 containing the time that this transaction was voided. Returns a time of zero upon error.

Definition at line 2737 of file Transaction.c.

2738 {
2739  GValue v = G_VALUE_INIT;
2740  const char *s = NULL;
2741  time64 void_time = 0;
2742 
2743  g_return_val_if_fail(tr, void_time);
2744  qof_instance_get_kvp (QOF_INSTANCE (tr), &v, 1, void_time_str);
2745  if (G_VALUE_HOLDS_STRING (&v))
2746  s = g_value_get_string (&v);
2747  if (s)
2748  return gnc_iso8601_to_time64_gmt (s);
2749  return void_time;
2750 }
time64 gnc_iso8601_to_time64_gmt(const gchar *)
The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64...
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:84

◆ xaccTransIsBalanced()

gboolean xaccTransIsBalanced ( const Transaction *  trans)

Returns true if the transaction is balanced according to the rules currently in effect.

Definition at line 1122 of file Transaction.c.

1123 {
1124  MonetaryList *imbal_list;
1125  gboolean result;
1126  gnc_numeric imbal = gnc_numeric_zero();
1127  gnc_numeric imbal_trading = gnc_numeric_zero();
1128 
1129  if (trans == NULL) return FALSE;
1130 
1131  if (xaccTransUseTradingAccounts(trans))
1132  {
1133  /* Transaction is imbalanced if the value is imbalanced in either
1134  trading or non-trading splits. One can't be used to balance
1135  the other. */
1136  FOR_EACH_SPLIT(trans,
1137  {
1138  Account *acc = xaccSplitGetAccount(s);
1139  if (!acc || xaccAccountGetType(acc) != ACCT_TYPE_TRADING)
1140  {
1141  imbal = gnc_numeric_add(imbal, xaccSplitGetValue(s),
1143  }
1144  else
1145  {
1146  imbal_trading = gnc_numeric_add(imbal_trading, xaccSplitGetValue(s),
1148  }
1149  }
1150  );
1151  }
1152  else
1153  imbal = xaccTransGetImbalanceValue(trans);
1154 
1155  if (! gnc_numeric_zero_p(imbal) || ! gnc_numeric_zero_p(imbal_trading))
1156  return FALSE;
1157 
1158  if (!xaccTransUseTradingAccounts (trans))
1159  return TRUE;
1160 
1161  imbal_list = xaccTransGetImbalance(trans);
1162  result = imbal_list == NULL;
1163  gnc_monetary_list_free(imbal_list);
1164  return result;
1165 }
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1013
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3006
STRUCTS.
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:189
Account used to record multiple commodity transactions.
Definition: Account.h:158
gnc_numeric xaccTransGetImbalanceValue(const Transaction *trans)
The xaccTransGetImbalanceValue() method returns the total value of the transaction.
Definition: Transaction.c:1034
void gnc_monetary_list_free(MonetaryList *list)
Free a MonetaryList and all the monetaries it points to.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:912
MonetaryList * xaccTransGetImbalance(const Transaction *trans)
The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency ...
Definition: Transaction.c:1050
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

◆ xaccTransIsOpen()

gboolean xaccTransIsOpen ( const Transaction *  trans)

The xaccTransIsOpen() method returns TRUE if the transaction is open for editing.

Otherwise, it returns false. XXX this routine should probably be deprecated. its, umm, hard to imagine legitimate uses (but it is used by the import/export code for reasons I can't understand.)

Definition at line 1865 of file Transaction.c.

1866 {
1867  return trans ? (0 < qof_instance_get_editlevel(trans)) : FALSE;
1868 }

◆ xaccTransIsReadonlyByPostedDate()

gboolean xaccTransIsReadonlyByPostedDate ( const Transaction *  trans)

Returns TRUE if this Transaction is read-only because its posted-date is older than the "auto-readonly" threshold of this book.

See qof_book_uses_autofreeze() and qof_book_get_autofreeze_gdate().

Definition at line 2523 of file Transaction.c.

2524 {
2525  GDate *threshold_date;
2526  GDate trans_date;
2527  const QofBook *book = xaccTransGetBook (trans);
2528  gboolean result;
2529  g_assert(trans);
2530 
2531  if (!qof_book_uses_autoreadonly(book))
2532  {
2533  return FALSE;
2534  }
2535 
2536  if (xaccTransIsSXTemplate (trans))
2537  return FALSE;
2538 
2539  threshold_date = qof_book_get_autoreadonly_gdate(book);
2540  g_assert(threshold_date); // ok because we checked uses_autoreadonly before
2541  trans_date = xaccTransGetDatePostedGDate(trans);
2542 
2543 // g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
2544 // qof_book_get_num_days_autofreeze(book),
2545 // g_date_get_day(&trans_date),
2546 // g_date_get_day(threshold_date));
2547 
2548  if (g_date_compare(&trans_date, threshold_date) < 0)
2549  {
2550  //g_warning("we are auto-read-only");
2551  result = TRUE;
2552  }
2553  else
2554  {
2555  result = FALSE;
2556  }
2557  g_date_free(threshold_date);
2558  return result;
2559 }
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:1112
#define xaccTransGetBook(X)
Definition: Transaction.h:771
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:1086
GDate xaccTransGetDatePostedGDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2402

◆ xaccTransLookup()

Transaction* xaccTransLookup ( const GncGUID guid,
QofBook *  book 
)

The xaccTransLookup() subroutine will return the transaction associated with the given id, or NULL if there is no such transaction.

Definition at line 1022 of file Transaction.c.

1023 {
1024  QofCollection *col;
1025  if (!guid || !book) return NULL;
1026  col = qof_book_get_collection (book, GNC_ID_TRANS);
1027  return (Transaction *) qof_collection_lookup_entity (col, guid);
1028 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:214
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:603

◆ xaccTransOrder()

int xaccTransOrder ( const Transaction *  ta,
const Transaction *  tb 
)

The xaccTransOrder(ta,tb) method is useful for sorting.

Orders ta and tb return <0 if ta sorts before tb return >0 if ta sorts after tb return 0 if they are absolutely equal

The comparrison uses the following fields, in order: date posted (compare as a date) num field (compare as an integer) date entered (compare as a date) description field (comcpare as a string using strcmp()) GncGUID (compare as a guid) Finally, it returns zero if all of the above match. Note that it does NOT compare its member splits. Note also that it calls xaccTransOrder_num_action with actna and actnb set as NULL.

Definition at line 1873 of file Transaction.c.

1874 {
1875  return xaccTransOrder_num_action (ta, NULL, tb, NULL);
1876 }
int xaccTransOrder_num_action(const Transaction *ta, const char *actna, const Transaction *tb, const char *actnb)
The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting.
Definition: Transaction.c:1879

◆ xaccTransOrder_num_action()

int xaccTransOrder_num_action ( const Transaction *  ta,
const char *  actna,
const Transaction *  tb,
const char *  actnb 
)

The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting.

Orders ta and tb return <0 if ta sorts before tb return >0 if ta sorts after tb return 0 if they are absolutely equal

The comparrison uses the following fields, in order: date posted (compare as a date) if actna and actnb are NULL, num field (compare as an integer) else actna and actnb (compare as an integer) date entered (compare as a date) description field (comcpare as a string using strcmp()) GncGUID (compare as a guid) Finally, it returns zero if all of the above match. Note that it does NOT compare its member splits (except action as specified above).

Definition at line 1879 of file Transaction.c.

1881 {
1882  char *da, *db;
1883  int na, nb, retval;
1884 
1885  if ( ta && !tb ) return -1;
1886  if ( !ta && tb ) return +1;
1887  if ( !ta && !tb ) return 0;
1888 
1889  if (ta->date_posted != tb->date_posted)
1890  return (ta->date_posted > tb->date_posted) - (ta->date_posted < tb->date_posted);
1891 
1892  /* Always sort closing transactions after normal transactions */
1893  {
1894  gboolean ta_is_closing = xaccTransGetIsClosingTxn (ta);
1895  gboolean tb_is_closing = xaccTransGetIsClosingTxn (tb);
1896  if (ta_is_closing != tb_is_closing)
1897  return (ta_is_closing - tb_is_closing);
1898  }
1899 
1900  /* otherwise, sort on number string */
1901  if (actna && actnb) /* split action string, if not NULL */
1902  {
1903  na = atoi(actna);
1904  nb = atoi(actnb);
1905  }
1906  else /* else transaction num string */
1907  {
1908  na = atoi(ta->num);
1909  nb = atoi(tb->num);
1910  }
1911  if (na < nb) return -1;
1912  if (na > nb) return +1;
1913 
1914  if (ta->date_entered != tb->date_entered)
1915  return (ta->date_entered > tb->date_entered) - (ta->date_entered < tb->date_entered);
1916 
1917  /* otherwise, sort on description string */
1918  da = ta->description ? ta->description : "";
1919  db = tb->description ? tb->description : "";
1920  retval = g_utf8_collate (da, db);
1921  if (retval)
1922  return retval;
1923 
1924  /* else, sort on guid - keeps sort stable. */
1925  return qof_instance_guid_compare(ta, tb);
1926 }
gboolean xaccTransGetIsClosingTxn(const Transaction *trans)
Returns whether this transaction is a "closing transaction".
Definition: Transaction.c:2360
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.

◆ xaccTransRetDateEntered()

time64 xaccTransRetDateEntered ( const Transaction *  trans)

Retrieve the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 2436 of file Transaction.c.

2437 {
2438  return trans ? trans->date_entered : 0;
2439 }

◆ xaccTransRetDatePosted()

time64 xaccTransRetDatePosted ( const Transaction *  trans)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank. (Although having different function names, GetDate and GetDatePosted refer to the same single date.)

Definition at line 2396 of file Transaction.c.

2397 {
2398  return trans ? trans->date_posted : 0;
2399 }

◆ xaccTransReverse()

Transaction* xaccTransReverse ( Transaction *  transaction)

xaccTransReverse creates a Transaction that reverses the given tranaction by inverting all the numerical values in the given transaction.

This function cancels out the effect of an earlier transaction. This will be needed by write only accounts as a way to void a previous transaction (since you can't alter the existing transaction).

Parameters
transactionThe transaction to create a reverse of.
Returns
a new transaction which reverses the given transaction

Definition at line 2780 of file Transaction.c.

2781 {
2782  Transaction *trans;
2783  GValue v = G_VALUE_INIT;
2784  g_return_val_if_fail(orig, NULL);
2785 
2786  trans = xaccTransClone(orig);
2787  xaccTransBeginEdit(trans);
2788 
2789  /* Reverse the values on each split. Clear per-split info. */
2790  FOR_EACH_SPLIT(trans,
2791  {
2795  });
2796 
2797  /* Now update the original with a pointer to the new one */
2798  g_value_init (&v, GNC_TYPE_GUID);
2799  g_value_set_boxed (&v, xaccTransGetGUID(trans));
2800  qof_instance_set_kvp (QOF_INSTANCE (orig), &v, 1, TRANS_REVERSED_BY);
2801 
2802  /* Make sure the reverse transaction is not read-only */
2803  xaccTransClearReadOnly(trans);
2804 
2805  qof_instance_set_dirty(QOF_INSTANCE(trans));
2806  xaccTransCommitEdit(trans);
2807  return trans;
2808 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1241
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
gnc_numeric gnc_numeric_neg(gnc_numeric a)
Returns a newly created gnc_numeric that is the negative of the given gnc_numeric value...
void xaccSplitSetReconcile(Split *split, char recn)
Set the reconcile flag.
Definition: Split.c:1749
void xaccSplitSetAmount(Split *s, gnc_numeric amt)
The xaccSplitSetAmount() method sets the amount in the account&#39;s commodity that the split should have...
Definition: Split.c:1205
Transaction * xaccTransClone(const Transaction *from)
The xaccTransClone() method will create a complete copy of an existing transaction.
Definition: Transaction.c:676
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
#define xaccTransGetGUID(X)
Definition: Transaction.h:773
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890
#define NREC
not reconciled or cleared
Definition: Split.h:74
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1884

◆ xaccTransRollbackEdit()

void xaccTransRollbackEdit ( Transaction *  trans)

The xaccTransRollbackEdit() routine rejects all edits made, and sets the transaction back to where it was before the editing started.

This includes restoring any deleted splits, removing any added splits, and undoing the effects of xaccTransDestroy, as well as restoring share quantities, memos, descriptions, etc.

Todo:
Fix transrollbackedit in QOF so that rollback is exposed via the API.

Definition at line 1707 of file Transaction.c.

1708 {
1709  GList *node, *onode;
1710  QofBackend *be;
1711  Transaction *orig;
1712  GList *slist;
1713  int num_preexist, i;
1714 
1715 /* FIXME: This isn't quite the right way to handle nested edits --
1716  * there should be a stack of transaction states that are popped off
1717  * and restored at each level -- but it does prevent restoring to the
1718  * editlevel 0 state until one is returning to editlevel 0, and
1719  * thereby prevents a crash caused by trans->orig getting NULLed too
1720  * soon.
1721  */
1722  if (!qof_instance_get_editlevel (QOF_INSTANCE (trans))) return;
1723  if (qof_instance_get_editlevel (QOF_INSTANCE (trans)) > 1) {
1724  qof_instance_decrease_editlevel (QOF_INSTANCE (trans));
1725  return;
1726  }
1727 
1728  ENTER ("trans addr=%p\n", trans);
1729 
1730  check_open(trans);
1731 
1732  /* copy the original values back in. */
1733 
1734  orig = trans->orig;
1735  SWAP(trans->num, orig->num);
1736  SWAP(trans->description, orig->description);
1737  trans->date_entered = orig->date_entered;
1738  trans->date_posted = orig->date_posted;
1739  SWAP(trans->common_currency, orig->common_currency);
1740  qof_instance_swap_kvp (QOF_INSTANCE (trans), QOF_INSTANCE (orig));
1741 
1742  /* The splits at the front of trans->splits are exactly the same
1743  splits as in the original, but some of them may have changed, so
1744  we restore only those. */
1745 /* FIXME: Runs off the transaction's splits, so deleted splits are not
1746  * restored!
1747  */
1748  num_preexist = g_list_length(orig->splits);
1749  slist = g_list_copy(trans->splits);
1750  for (i = 0, node = slist, onode = orig->splits; node;
1751  i++, node = node->next, onode = onode ? onode->next : NULL)
1752  {
1753  Split *s = node->data;
1754 
1755  if (!qof_instance_is_dirty(QOF_INSTANCE(s)))
1756  continue;
1757 
1758  if (i < num_preexist && onode)
1759  {
1760  Split *so = onode->data;
1761 
1762  xaccSplitRollbackEdit(s);
1763  SWAP(s->action, so->action);
1764  SWAP(s->memo, so->memo);
1765  qof_instance_copy_kvp (QOF_INSTANCE (s), QOF_INSTANCE (so));
1766  s->reconciled = so->reconciled;
1767  s->amount = so->amount;
1768  s->value = so->value;
1769  s->lot = so->lot;
1770  s->gains_split = so->gains_split;
1771  //SET_GAINS_A_VDIRTY(s);
1772  s->date_reconciled = so->date_reconciled;
1773  qof_instance_mark_clean(QOF_INSTANCE(s));
1774  xaccFreeSplit(so);
1775  }
1776  else
1777  {
1778  /* Potentially added splits */
1779  if (trans != xaccSplitGetParent(s))
1780  {
1781  trans->splits = g_list_remove(trans->splits, s);
1782  /* New split added, but then moved to another
1783  transaction */
1784  continue;
1785  }
1786  xaccSplitRollbackEdit(s);
1787  trans->splits = g_list_remove(trans->splits, s);
1788  g_assert(trans != xaccSplitGetParent(s));
1789  /* NB: our memory management policy here is that a new split
1790  added to the transaction which is then rolled-back still
1791  belongs to the engine. Specifically, it's freed by the
1792  transaction to which it was added. Don't add the Split to
1793  more than one transaction during the begin/commit block! */
1794  if (NULL == xaccSplitGetParent(s))
1795  {
1796  xaccFreeSplit(s); // a newly malloc'd split
1797  }
1798  }
1799  }
1800  g_list_free(slist);
1801  g_list_free(orig->splits);
1802  orig->splits = NULL;
1803 
1804  /* Now that the engine copy is back to its original version,
1805  * get the backend to fix it in the database */
1809  if (qof_backend_can_rollback (be))
1810  {
1811  QofBackendError errcode;
1812 
1813  /* clear errors */
1814  do
1815  {
1816  errcode = qof_backend_get_error (be);
1817  }
1818  while (ERR_BACKEND_NO_ERR != errcode);
1819 
1820  qof_backend_rollback_instance (be, &(trans->inst));
1821 
1822  errcode = qof_backend_get_error (be);
1823  if (ERR_BACKEND_MOD_DESTROY == errcode)
1824  {
1825  /* The backend is asking us to delete this transaction.
1826  * This typically happens because another (remote) user
1827  * has deleted this transaction, and we haven't found
1828  * out about it until this user tried to edit it.
1829  */
1830  xaccTransDestroy (trans);
1831  do_destroy (trans);
1832 
1833  /* push error back onto the stack */
1834  qof_backend_set_error (be, errcode);
1835  LEAVE ("deleted trans addr=%p\n", trans);
1836  return;
1837  }
1838  if (ERR_BACKEND_NO_ERR != errcode)
1839  {
1840  PERR ("Rollback Failed. Ouch!");
1841  /* push error back onto the stack */
1842  qof_backend_set_error (be, errcode);
1843  }
1844  }
1845 
1847  xaccTransWriteLog (trans, 'R');
1848 
1849  xaccFreeTransaction (trans->orig);
1850 
1851  trans->orig = NULL;
1852  qof_instance_set_destroying(trans, FALSE);
1853 
1854  /* Put back to zero. */
1855  qof_instance_decrease_editlevel(trans);
1856  /* FIXME: The register code seems to depend on the engine to
1857  generate an event during rollback, even though the state is just
1858  reverting to what it was. */
1859  gen_event_trans (trans);
1860 
1861  LEAVE ("trans addr=%p\n", trans);
1862 }
commit of object update failed because another user has deleted the object
Definition: qofbackend.h:79
#define qof_instance_is_dirty
Return value of is_dirty flag.
Definition: qofinstance.h:162
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:59
void xaccTransWriteLog(Transaction *trans, char flag)
Definition: TransLog.c:223
void qof_backend_set_error(QofBackend *qof_be, QofBackendError err)
Set the error on the specified QofBackend.
Transaction * xaccSplitGetParent(const Split *split)
Returns the parent transaction of the split.
Definition: Split.c:1800
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
QofBackendError qof_backend_get_error(QofBackend *qof_be)
Get the last backend error.
void xaccTransDestroy(Transaction *trans)
Destroys a transaction.
Definition: Transaction.c:1456
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:579
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
QofBackend * qof_book_get_backend(const QofBook *book)
Retrieve the backend used by this book.
Definition: qofbook.cpp:523

◆ xaccTransScrubGains()

void xaccTransScrubGains ( Transaction *  trans,
Account gain_acc 
)

The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction, with the end-goal of setting up a consistent set of gains/losses for all the splits in the transaction.

This includes making sure that the lot assignments of all the splits are good, and that the lots balance appropriately.

Definition at line 2880 of file Transaction.c.

2881 {
2882  SplitList *node;
2883 
2884  ENTER("(trans=%p)", trans);
2885  /* Lock down posted date, its to be synced to the posted date
2886  * for the source of the cap gains. */
2887  xaccTransScrubGainsDate(trans);
2888 
2889  /* Fix up the split amount */
2890 restart:
2891  for (node = trans->splits; node; node = node->next)
2892  {
2893  Split *s = node->data;
2894 
2895  if (!xaccTransStillHasSplit(trans, s)) continue;
2896 
2897  xaccSplitDetermineGainStatus(s);
2898  if (s->gains & GAINS_STATUS_ADIRTY)
2899  {
2900  gboolean altered = FALSE;
2901  s->gains &= ~GAINS_STATUS_ADIRTY;
2902  if (s->lot)
2903  altered = xaccScrubLot(s->lot);
2904  else
2905  altered = xaccSplitAssign(s);
2906  if (altered) goto restart;
2907  }
2908  }
2909 
2910  /* Fix up gains split value */
2911  FOR_EACH_SPLIT(trans,
2912  if ((s->gains & GAINS_STATUS_VDIRTY) ||
2913  (s->gains_split &&
2914  (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
2915  xaccSplitComputeCapGains(s, gain_acc);
2916  );
2917 
2918  LEAVE("(trans=%p)", trans);
2919 }
void xaccSplitComputeCapGains(Split *split, Account *gain_acc)
The xaccSplitComputeCapGains() routine computes the cap gains or losses for the indicated split...
Definition: cap-gains.c:528
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:268
GList SplitList
GList of Split.
Definition: gnc-engine.h:207
gboolean xaccSplitAssign(Split *split)
The`xaccSplitAssign() routine will take the indicated split and, if it doesn&#39;t already belong to a lo...
Definition: cap-gains.c:428
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:278
gboolean xaccScrubLot(GNCLot *lot)
The xaccScrubLot() routine makes sure that the indicated lot is self-consistent and properly balanced...
Definition: Scrub3.c:85

◆ xaccTransSetCurrency()

void xaccTransSetCurrency ( Transaction *  trans,
gnc_commodity *  curr 
)

Set the commodity of this transaction.

Set the commodity of this transaction.

When we do that to a transaction with splits we need to re-value all of the splits in the new currency.

Parameters
transThe transaction to change
currThe new currency to set.

Definition at line 1405 of file Transaction.c.

1406 {
1407  gnc_commodity *old_curr = trans->common_currency;
1408  if (!trans || !curr || trans->common_currency == curr) return;
1409  xaccTransBeginEdit(trans);
1410 
1411  trans->common_currency = curr;
1412  if (old_curr != NULL && trans->splits != NULL)
1413  {
1414  gnc_numeric rate = find_new_rate(trans, curr);
1415  if (!gnc_numeric_zero_p (rate))
1416  {
1417  FOR_EACH_SPLIT(trans, split_set_new_value(s, curr, old_curr, rate));
1418  }
1419  else
1420  {
1421  FOR_EACH_SPLIT(trans, xaccSplitSetValue(s, xaccSplitGetValue(s)));
1422  }
1423  }
1424 
1425  qof_instance_set_dirty(QOF_INSTANCE(trans));
1426  mark_trans(trans); /* Dirty balance of every account in trans */
1427  xaccTransCommitEdit(trans);
1428 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1241
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1890

◆ xaccTransSetDate()

void xaccTransSetDate ( Transaction *  trans,
int  day,
int  mon,
int  year 
)

The xaccTransSetDate() method does the same thing as xaccTransSetDate[Posted]Secs(), but takes a convenient day-month-year format.

(Footnote: this shouldn't matter to a user, but anyone modifying the engine should understand that when xaccTransCommitEdit() is called, the date order of each of the component splits will be checked, and will be restored in ascending date order.)

Definition at line 2027 of file Transaction.c.

2028 {
2029  GDate *date;
2030  if (!trans) return;
2031  date = g_date_new_dmy(day, mon, year);
2032  if (!g_date_valid(date))
2033  {
2034  PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
2035  year, mon, day);
2036  g_free(date);
2037  date = gnc_g_date_new_today();
2038  }
2039  xaccTransSetDatePostedGDate(trans, *date);
2040  g_free(date);
2041 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:1983
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1229

◆ xaccTransSetDateEnteredSecs()

void xaccTransSetDateEnteredSecs ( Transaction *  trans,
time64  time 
)

Modify the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 2001 of file Transaction.c.

2002 {
2003  if (!trans) return;
2004  xaccTransSetDateInternal(trans, &trans->date_entered, secs);
2005 }

◆ xaccTransSetDatePostedGDate()

void xaccTransSetDatePostedGDate ( Transaction *  trans,
GDate  date 
)

This method modifies posted date of the transaction, specified by a GDate.

The posted date is the date when this transaction was posted at the bank.

This is identical to xaccTransSetDate(), but different from xaccTransSetDatePostedSecs which artificially introduces the time-of-day part, which needs to be ignored.

Definition at line 1983 of file Transaction.c.

1984 {
1985  GValue v = G_VALUE_INIT;
1986  if (!trans) return;
1987 
1988  /* We additionally save this date into a kvp frame to ensure in
1989  * the future a date which was set as *date* (without time) can
1990  * clearly be distinguished from the time64. */
1991  g_value_init (&v, G_TYPE_DATE);
1992  g_value_set_boxed (&v, &date);
1993  qof_instance_set_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_DATE_POSTED);
1994  /* mark dirty and commit handled by SetDateInternal */
1995  xaccTransSetDateInternal(trans, &trans->date_posted,
1996  gdate_to_time64(date));
1997  set_gains_date_dirty (trans);
1998 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1256

◆ xaccTransSetDatePostedSecs()

void xaccTransSetDatePostedSecs ( Transaction *  trans,
time64  time 
)

The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)).

The posted date is the date when this transaction was posted at the bank.

Please do not use this function, as the extra time-of-day part messes up a lot of places. Rather, please use xaccTransSetDatePostedGDate() or xaccTransSetDatePostedSecsNormalized().

Definition at line 1967 of file Transaction.c.

1968 {
1969  if (!trans) return;
1970  xaccTransSetDateInternal(trans, &trans->date_posted, secs);
1971  set_gains_date_dirty(trans);
1972 }

◆ xaccTransSetDatePostedSecsNormalized()

void xaccTransSetDatePostedSecsNormalized ( Transaction *  trans,
time64  time 
)

This function sets the posted date of the transaction, specified by a time64 (see ctime(3)).

Contrary to xaccTransSetDatePostedSecs(), the time will be normalized to only the date part, and the time-of-day will be ignored. The resulting date is the same as if it had been set as a GDate through xaccTransSetDatePostedGDate().

Please prefer this function over xaccTransSetDatePostedSecs().

The posted date is the date when this transaction was posted at the bank.

Definition at line 1975 of file Transaction.c.

1976 {
1977  GDate date;
1978  gnc_gdate_set_time64(&date, time);
1979  xaccTransSetDatePostedGDate(trans, date);
1980 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:1983
void gnc_gdate_set_time64(GDate *gd, time64 time)
Set a GDate to a time64.
Definition: gnc-date.cpp:1247

◆ xaccTransSetNotes()

void xaccTransSetNotes ( Transaction *  trans,
const char *  notes 
)

Sets the transaction Notes.

The Notes field is only visible in the register in double-line mode

Definition at line 2175 of file Transaction.c.

2176 {
2177  GValue v = G_VALUE_INIT;
2178  if (!trans || !notes) return;
2179  g_value_init (&v, G_TYPE_STRING);
2180  g_value_set_string (&v, notes);
2181  xaccTransBeginEdit(trans);
2182 
2183  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2184  qof_instance_set_dirty(QOF_INSTANCE(trans));
2185  xaccTransCommitEdit(trans);
2186 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccTransSetReadOnly()

void xaccTransSetReadOnly ( Transaction *  trans,
const char *  reason 
)

Set the transaction to be ReadOnly by setting a non-NULL value as "reason".

FIXME: If "reason" is NULL, this function does nothing, instead of removing the readonly flag; the actual removal is possible only through xaccTransClearReadOnly().

Definition at line 2086 of file Transaction.c.

2087 {
2088  if (trans && reason)
2089  {
2090  GValue v = G_VALUE_INIT;
2091  g_value_init (&v, G_TYPE_STRING);
2092  g_value_set_string (&v, reason);
2093  xaccTransBeginEdit(trans);
2094  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_READ_ONLY_REASON);
2095  qof_instance_set_dirty(QOF_INSTANCE(trans));
2096  xaccTransCommitEdit(trans);
2097 
2098  g_free (trans->readonly_reason);
2099  trans->readonly_reason = g_strdup (reason);
2100  trans->reason_cache_valid = TRUE;
2101  }
2102 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccTransSetTxnType()

void xaccTransSetTxnType ( Transaction *  trans,
char  type 
)

Set the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2057 of file Transaction.c.

2058 {
2059  char s[2] = {type, '\0'};
2060  GValue v = G_VALUE_INIT;
2061  g_return_if_fail(trans);
2062  g_value_init (&v, G_TYPE_STRING);
2063  g_value_set_string (&v, s);
2064  xaccTransBeginEdit(trans);
2065  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2066  qof_instance_set_dirty(QOF_INSTANCE(trans));
2067  xaccTransCommitEdit(trans);
2068 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccTransUnvoid()

void xaccTransUnvoid ( Transaction *  transaction)

xaccTransUnvoid restores a voided transaction to its original state.

At some point when gnucash is enhanced to support an audit trail (i.e. write only transactions) this command should be automatically disabled when the audit trail feature is enabled.

Parameters
transactionThe transaction to restore from voided state.

Definition at line 2753 of file Transaction.c.

2754 {
2755  GValue v = G_VALUE_INIT;
2756  const char *s = NULL;
2757  g_return_if_fail(trans);
2758 
2759  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2760  if (G_VALUE_HOLDS_STRING (&v))
2761  s = g_value_get_string (&v);
2762  if (s == NULL) return; /* Transaction isn't voided. Bail. */
2763  xaccTransBeginEdit(trans);
2764 
2765  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2766  if (G_VALUE_HOLDS_STRING (&v))
2767  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2768  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_former_notes_str);
2769  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_reason_str);
2770  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_time_str);
2771 
2772  FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));
2773 
2774  /* Dirtying taken care of by ClearReadOnly */
2775  xaccTransClearReadOnly(trans);
2776  xaccTransCommitEdit(trans);
2777 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434

◆ xaccTransVoid()

void xaccTransVoid ( Transaction *  transaction,
const char *  reason 
)

xaccTransVoid voids a transaction.

A void transaction has no values, is unaffected by reconciliation, and, by default is not included in any queries. A voided transaction may not be altered.

Parameters
transactionThe transaction to void.
reasonThe textual reason why this transaction is being voided.

Definition at line 2673 of file Transaction.c.

2674 {
2675  GValue v = G_VALUE_INIT;
2676  char iso8601_str[ISO_DATELENGTH + 1] = "";
2677 
2678  g_return_if_fail(trans && reason);
2679 
2680  /* Prevent voiding transactions that are already marked
2681  * read only, for example generated by the business features.
2682  */
2683  if (xaccTransGetReadOnly (trans))
2684  {
2685  PWARN ("Refusing to void a read-only transaction!");
2686  return;
2687  }
2688  xaccTransBeginEdit(trans);
2689  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2690  if (G_VALUE_HOLDS_STRING (&v))
2691  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2692  else
2693  g_value_init (&v, G_TYPE_STRING);
2694 
2695  g_value_set_string (&v, _("Voided transaction"));
2696  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2697  g_value_set_string (&v, reason);
2698  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2699 
2700  gnc_time64_to_iso8601_buff (gnc_time(NULL), iso8601_str);
2701  g_value_set_string (&v, iso8601_str);
2702  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_time_str);
2703 
2704  FOR_EACH_SPLIT(trans, xaccSplitVoid(s));
2705 
2706  /* Dirtying taken care of by SetReadOnly */
2707  xaccTransSetReadOnly(trans, _("Transaction Voided"));
2708  xaccTransCommitEdit(trans);
2709 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2475
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
void xaccTransSetReadOnly(Transaction *trans, const char *reason)
Set the transaction to be ReadOnly by setting a non-NULL value as "reason".
Definition: Transaction.c:2086
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1633
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1434
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:273
char * gnc_time64_to_iso8601_buff(time64 time, char *buff)
The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-860...
Definition: gnc-date.cpp:1142