YumaWorks

The following article illustrates how to utilize the Transaction Start callback in examples.

The Transaction Start function is the user/system callback that is invoked before any changes to the candidate database will be committed.

The following function template definition is used for Transaction Start callback functions:

/* Typedef of the trans_start callback */
typedef status_t 
    (*agt_cb_trans_start_t)(agt_cfg_transaction_t *txcb);

Register Callback

The Transaction Start callback function is hooked into the server with the agt_cb_trans_start_register function, described below. 

extern status_t
    agt_cb_trans_start_register (agt_cb_trans_start_t cbfn);

The register function is used to declare a specific callback function for Transaction Star callbacks. The registration is done during the Initialization Phase 1 before the startup configuration is loaded into the running configuration database and before running configurations are loaded.

Callback Cleanup

The following example code illustrates how the callback can be cleaned up.The callback cleanup is getting done during module Cleanup Phase.

extern void
    agt_cb_trans_start_unregister (agt_cb_trans_start_t cbfn);

In this example, the Transaction Start callback function applies multiple actions prior the transaction is actually started. The purpose of this function is to provide more validation options and more flexible and easier development. This callback function may deny the start of the transaction if some specific check is unmet, in this example, if the node “trigger” is present in the datastore then the server will deny the transaction.

In addition, in this example, the callback function updates a comment string of this transaction, it may send a custom notifications, or write a system or other log entries.

The following example code illustrates how the Transaction Start callback may look like.

/******************************************************************** 
* FUNCTION transaction_start 
* 
* Start Transaction callback 
* The Start Transaction function is the user/system 
* callback that is invoked before any changes to the 
* candidate database will be committed. 
* 
* INPUTS: 
*   txcb == transaction control block in progress 
* 
* RETURNS: 
*   status 
********************************************************************/ 
static status_t 
    transaction_start (agt_cfg_transaction_t *txcb) 
{ 

    log_debug("\nEnter transaction_start callback"); 
    status_t res = NO_ERR; 

    /* deny the start of transaction if some specific check is unmet. E.g:
     * if there is a specific node present in the datastore
     */
    val_value_t *val = 
       agt_val_get_data(txcb->cfg_id, 
                        (const xmlChar *)"/if:trigger", 
                        &res); 
    if (val) { 
        res = ERR_NCX_ACCESS_DENIED; 
    } 

    /* update a comment string of this transaction */
     txcb->comment = (const xmlChar *)"special transaction";

    /* send custom notifications */

    /* write a sys, audit, vendor specific, etc log entries */


    return res; 

}  /* transaction_start */

NOTE:

Manipulation with datastore are only allowed for Set Hook callbacks. If Transaction Start or Complete callbacks call add_edit() the operation will be ignored. It will not return an error, just ignore add_edit calls.