rem
rem	Script:		c_paralloc_p.sql
rem	Author:		Jonathan Lewis
rem	Dated:		21-Sep-1998
rem	Purpose:	Parallel activity allocation package
rem
rem	This package allows calls to create a table of items  (e.g.
rem	table-names) which can then be processed by an arbitrary
rem	number of parallel processes, which declare an interest
rem	and acquire exclusivity by flagging a row.  The nature
rem	of the code assumes that the list will be small (no more
rem	than a few dozen).  Any item on the list can be in one of
rem	four states:
rem		Awaiting processing	(N)
rem		Being processed		(A)
rem		Processing completed	(C)
rem		Errored out		(E)
rem
rem	Legal Transitions:
rem		N -> A  A -> N
rem		N -> A  A -> E  E -> N
rem		N -> A  A -> C  C -> N
rem
rem	The structure of the table, and the nature of the flags
rem	on that table is hidden from the user.
rem
rem	Each procedure can return one of 6 codes:
rem		0	Operation successful
rem		1	No rows left to allocate
rem		2	Operation failed, row not found
rem		3	Operation failed, too many rows found
rem		4	Specific row locked by another user
rem		5	Trying to create duplicate entry in driver
rem		6	Driving table already exists
rem		9	Operation failed, error unknown
rem
rem	Initial Implementation - static SQL, with a single pre-created
rem	table;  the 'driving task' is specified in one column, the 
rem	'payload' in another.
rem
rem	Ultimate implementation - dynamic SQl creating a table for 
rem	each driving task, and an object type (v8) for the payload
rem
rem	Warnings:
rem	The procedures issue commits - this is a deliberate design
rem	feature.  If a task completes successfully, then flagging it
rem	in the table and commiting the completion state should be
rem	the same activity.
rem
rem	List of Functions:
rem	------------------
rem	procedure create_driver
rem		Create a table to hold the list of tables
rem
rem	procedure drop_driver
rem		Drop the list of tables
rem
rem	procedure populate_driver
rem		Add a row to the list
rem
rem	procedure allocate_target_item
rem		Request a currently free item on the list
rem
rem	procedure complete_target_item
rem		Mark a named item as completed processing
rem
rem	procedure free_target_item
rem		Free a named item 
rem
rem	procedure clear_error_for_target_item
rem		Clear the error flag from the named item
rem
rem	procedure reset_target_item
rem		Clear the completion flag from a named item
rem
rem	procedure reset_all_targets
rem		Clear all list items back to unprocessed
rem
rem	procedure clear_all_errors
rem		Clear all error flags on the entire list
rem


create or replace package parallel_allocation as

c_success	constant number := 0;
c_no_rows_left	constant number := 1;
c_row_not_found	constant number := 2;
c_too_many_rows	constant number := 3;
c_row_locked	constant number := 4;
c_duplicate_row	constant number := 5;
c_table_exists	constant number := 6;

c_general_error	constant number := 9;

procedure create_driver(
		i_driving_task		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure drop_driver(
		i_driving_task		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure populate_driver(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure allocate_target_item(
		i_driving_task		in	varchar2,
		o_payload		   out	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure free_target_item(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure complete_target_item(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure error_target_item(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure clear_error_for_target_item(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure reset_target_item(
		i_driving_task		in	varchar2,
		i_payload		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure reset_all_targets(
		i_driving_task		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);

procedure clear_all_errors(
		i_driving_task		in	varchar2,
		io_return_code		in out	number,
		io_error_message	in out	varchar2
);


end;
.
/