# BEGIN LICENSE BLOCK
# Version: CMPL 1.1
#
# The contents of this file are subject to the Cisco-style Mozilla Public
# License Version 1.1 (the "License"); you may not use this file except
# in compliance with the License.  You may obtain a copy of the License
# at www.eclipse-clp.org/license.
# 
# Software distributed under the License is distributed on an "AS IS"
# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
# the License for the specific language governing rights and limitations
# under the License. 
# 
# The Original Code is  The ECLiPSe Constraint Logic Programming System. 
# The Initial Developer of the Original Code is  Cisco Systems, Inc. 
# Portions created by the Initial Developer are
# Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
# 
# Contributor(s): 
# 
# END LICENSE BLOCK

Cut-fail-actions
----------------

This is a facility needed when retrieving information incrementally
on backtracking from an external resource.  In particular, the external
resource is a database, on which a cursor is opened, from which one
tuple at a time gets retrieved on backtracking. When the backtracking
retrieval is cut, or failed over, the cursor must be freed because
external resources are associated with it.

The C programmer interface is the function

void schedule_cut_fail_action(void (*function)(), value v, type t)

    This will cause function(v, t) to be called when the Prolog
    execution fails or cuts (whatever happens earlier) across
    the current point.

    The specified C function will be called as (*function)(v, t) where
    v, t is an arbitrary Prolog word.

    The function is executed either

	- on failure or
	- when cutting to a choicepoint older than the scheduling of the action

Note that schedule_cut_fail_action() consumes space on the global stack and
the trail, builtins calling it must therefore be declared as B_UNSAFE.


In a database interface, you would call this from the C function that
opens the cursor, e.g. after

    ...
    case 7: EXEC SQL OPEN C7 USING DESCRIPTOR bdp; break;
    case 8: EXEC SQL OPEN C8 USING DESCRIPTOR bdp; break;
    }

/* insert this: */

    {
       value vcursor;
       type tcursor;
       vcursor.nint = cursor;
       tcursor.kernel  = TINT;
       schedule_cut_fail_action(p_oracle_close_cursor, cursor.val, cursor.tag);
    }