Project: Project ( XPP 1. SOFTWAROV┴ s.r.o.)
Description: Internal Package for eXtreme Parallel Processing


@author Petr Jezek
@version 1.0.1, 2013-03-10
@since 1.0
@headcom


Method Summary
 add_request( p_queue_name in varchar2 , p_record in long raw , p_message_id out raw )
          
           The procedure add requests into queue p_queue_name.
          
          
 add_subscriber( p_queue_name in varchar2 , p_recipient_name in varchar2 )
          
           The procedure defines subscriber for queue p_queue_name.
           Name of subscriber and recepient is based on p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
 add_subscription_conf( p_queue_name in varchar2 , p_general_procedure in varchar2 , p_number_of_executors in number , p_procedure_to_run in varchar2 , p_procedure_on_success in varchar2 default null , p_procedure_on_error in varchar2 default null , p_param_on_error_input in number default 1 , p_step in number default 0 )
          
           The procedure defines subscriber for queue p_queue_name.
           Name of subscriber configuration is based on p_queue_name.
          
          
 clean_task( p_task_name in varchar2 )
          
           The procedure is cleaning configuration of task
           Note: All exceptions while cleaning are disabled.
          
          
 collect_and_raise_task_errors( p_task_name in varchar2 ) return varchar2 ;
          
           The function returns varchar2 with list of error raised while fatal error of task execution.
          
          
 define_processing_package( p_queue_name in varchar2 )
          
           The procedure defines interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
           Name of packages is based on p_queue_name.
           Note: it can raise the same exception like is raising CREATE OR REPLACE PACKAGE command and GRANT EXEUTE commnad.
          
          
 define_queue( p_queue_name in varchar2 , p_queue_comments in varchar2 : = null , p_user_to_grant in varchar2 : = null )
          
           The procedure defines queue p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
 define_sequence( p_queue_name in varchar2 )
          
           The procedure defines user sequence for queue p_queue_name.
           Name of sequence is based on p_queue_name.
          
          
 define_table( p_queue_name in varchar2 , p_storage_clause in varchar2 )
          
           The procedure defines table for queue p_queue_name.
           Name of table is based on p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
 define_type( p_queue_name in varchar2 , p_queue_type_body in varchar2 , p_queue_type_name out varchar2 )
          
           The procedure defines user type for queue p_queue_name acording definition in parameter p_queue_type_body.
           Name of required type is based on p_queue_name.
           Finally is the new type granted for actual executor.
           Note: it can raise the same exception like is raising CREATE TYPE command and GRANT EXEUTE commnad.
          
          
 del_subscriber( p_queue_name in varchar2 , p_recipient_name in varchar2 )
          
           The procedure drops subscriber for queue p_queue_name.
           Note: The expected time of dropping is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
 delete_all_request( p_queue_name in varchar2 )
          
           The procedure remove all requests from queue p_queue_name.
          
          
 delete_all_subscription_conf( p_queue_name in varchar2 )
          
           The procedure drops subscriber for queue p_queue_name.
          
          
 destroy_processing_package( p_queue_name in varchar2 )
          
           The procedure drops interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
           Note: it can raise the same exception like is raising DROP PACKAGE command.
          
          
 destroy_queue( p_queue_name in varchar2 )
          
           The procedure drops queue queue p_queue_name.
          
          
 destroy_sequence( p_queue_name in varchar2 )
          
           The procedure drops user sequence for queue p_queue_name.
          
          
 destroy_table( p_queue_name in varchar2 )
          
           The procedure drops table for queue p_queue_name.
          
          
 destroy_type( p_queue_name in varchar2 )
          
           The procedure drops user type for queue p_queue_name.
           Name of required type is based on p_queue_name.
           Note: it can raise the same exception like is raising DROP TYPE commnad.
          
          
 get_current_schema_name
          
           The function is returning name of current schema
          
          
 get_msg_name_empty_queue( p_queue_name in varchar2 ) return varchar2 ;
          
           The function is returning name exception when queue is empty.
          
          
 get_processing_status( p_task_name in varchar2 ) return varchar2 ;
          
           The function is returning of processing of task in varchar2.
           List of possible statuses
           NOT_EXISTS
           CREATED
           CHUNKING
           CHUNKING_FAILED
           CHUNKED
           PROCESSING
           FINISHED
           FINISHED_WITH_ERROR
           CRASHED
          


          

 get_queue_name( p_queue_name in varchar2 , p_with_schema in boolean default true ) return varchar2 ;
          
           The function is translating required p_queue_name to real queue name.
           The goal of this translation it to secure creation/modify/delete of internal XPP queues.
          
          
 get_queue_recipient_def_name( p_queue_name in varchar2 ) return varchar2 ;
          
           The function is translating required p_queue_name to real recipient name.
           The goal of this translation it to secure creation/modify/delete of internal XPP recipients.
          
          
 initiate( p_task_name in varchar2 , p_queue_name in varchar2 , p_comment in varchar2 , p_sql_stmt in clob , p_parallel_level in number )
          
           The procedure is initiate definition task, register catching of message when queue will be processed and execute the processing of the task.
          
          
 is_task_finished_successfuly( p_task_name in varchar2 ) return boolean ;
          
           The function is returning true task is successfuly finished, otherwise it return false.
          
          
 is_task_running( p_task_name in varchar2 ) return boolean ;
          
           The function is returning true task is running or configured an ready to running, otherwise it return false.
          
          
 licence_id( p_company_name out varchar2 , p_invoice_id out varchar2 , p_paymenent_type out varchar2 , p_paymenent_date out varchar2 )
          
           The procedure is returning identification of official buyer of the XPP.
          
          
 run_subscriber_processing( p_queue_name in varchar2 )
          
           The procedure is chceking if the instance is running.
           When is not running the it runs the parallel task.
           Each task will try in concurency mode dequeue and process messages from the queue.
          
          
 send_message( p_name in varchar2 , p_message in varchar2 )
          
           The procedure is sending message indentify by p_name parameter with context in parameter p_message.
           Note: When the length of context of message is longer then 1900 bytes then is cut to 1900
          
          
 task_stop( p_task_name in varchar2 , p_raise_exeception in boolean default true )
          
           The procedure is stopping running instance of task.
           It will raise exception when parameter p_raise_exeception is set to true and task is not running.
          
          
 wait_my_alert( p_alert in varchar2 , p_msg out varchar2 , p_stat out number , p_unlimited_time in boolean default false )
          
           The procedure is waiting for message.
           When value of input value p_unlimited_time is true, then waiting will be limited by maxiaml possible time defiend by database.
           Otherwise the expected time of waiting is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          

Method Detail

add_request

          add_request( p_queue_name in varchar2 , p_record in long raw , p_message_id out raw ) 
          
           The procedure add requests into queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.
p_record - The record to insert into queue is long row type.
p_message_id - The message id.

add_subscriber

          add_subscriber( p_queue_name in varchar2 , p_recipient_name in varchar2 ) 
          
           The procedure defines subscriber for queue p_queue_name.
           Name of subscriber and recepient is based on p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.
p_recipient_name - The name of recepient of queue associate to the the requested table.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_creation_subscriber - The subscriber is not created or is not created in expected time.

add_subscription_conf

          add_subscription_conf( p_queue_name in varchar2 , p_general_procedure in varchar2 , p_number_of_executors in number , p_procedure_to_run in varchar2 , p_procedure_on_success in varchar2 default null , p_procedure_on_error in varchar2 default null , p_param_on_error_input in number default 1 , p_step in number default 0 ) 
          
           The procedure defines subscriber for queue p_queue_name.
           Name of subscriber configuration is based on p_queue_name.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_number_of_executors - The number of requested parallel tasks is forbidden.
c_err_queue_is_not_defined - The queue is not defined. (Prior the XPP.EVENT_OPEN should be called XPP.EVENT_INIT)
c_err_subscr_conf_exists - The subscriber configuration of queue already exists.

clean_task

          clean_task( p_task_name in varchar2 ) 
          
           The procedure is cleaning configuration of task
           Note: All exceptions while cleaning are disabled.
          
          
Parameters:
p_task_name - The name of task.

collect_and_raise_task_errors

          collect_and_raise_task_errors( p_task_name in varchar2 ) return varchar2 ; 
          
           The function returns varchar2 with list of error raised while fatal error of task execution.
          
          
Parameters:
p_task_name - The name of task.
Returns:
It returns varchar2 with list of error raised while fatal error of task execution.

define_processing_package

          define_processing_package( p_queue_name in varchar2 ) 
          
           The procedure defines interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
           Name of packages is based on p_queue_name.
           Note: it can raise the same exception like is raising CREATE OR REPLACE PACKAGE command and GRANT EXEUTE commnad.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.
Throws:
c_err_queue_name - The queue name is forbidden.

define_queue

          define_queue( p_queue_name in varchar2 , p_queue_comments in varchar2 : = null , p_user_to_grant in varchar2 : = null ) 
          
           The procedure defines queue p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_creation_queue - The queue is not created or is not created in expected time.

define_sequence

          define_sequence( p_queue_name in varchar2 ) 
          
           The procedure defines user sequence for queue p_queue_name.
           Name of sequence is based on p_queue_name.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.

define_table

          define_table( p_queue_name in varchar2 , p_storage_clause in varchar2 ) 
          
           The procedure defines table for queue p_queue_name.
           Name of table is based on p_queue_name.
           Note: The expected time of ceration is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.
p_storage_clause - The storage clause for reation of queue table.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_creation_queue_table - The table is not created or is not created in expected time.

define_type

          define_type( p_queue_name in varchar2 , p_queue_type_body in varchar2 , p_queue_type_name out varchar2 ) 
          
           The procedure defines user type for queue p_queue_name acording definition in parameter p_queue_type_body.
           Name of required type is based on p_queue_name.
           Finally is the new type granted for actual executor.
           Note: it can raise the same exception like is raising CREATE TYPE command and GRANT EXEUTE commnad.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested type.
p_queue_type_body - The definition of new type. (It is according defintion part in the brackets while definion of new type.)
p_queue_type_name - The name of newly created type
Throws:
c_err_queue_name - The queue name is forbidden.

del_subscriber

          del_subscriber( p_queue_name in varchar2 , p_recipient_name in varchar2 ) 
          
           The procedure drops subscriber for queue p_queue_name.
           Note: The expected time of dropping is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_deletion_subscriber - The subscriber is not dropped or is not dropped in expected time.

delete_all_request

          delete_all_request( p_queue_name in varchar2 ) 
          
           The procedure remove all requests from queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested table.

delete_all_subscription_conf

          delete_all_subscription_conf( p_queue_name in varchar2 ) 
          
           The procedure drops subscriber for queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_deletion_queue_table - The table is not dropped or is not dropped in expected time.

destroy_processing_package

          destroy_processing_package( p_queue_name in varchar2 ) 
          
           The procedure drops interface packages (prefix XPPI_) and processing package (prefix XPPX_) for queue p_queue_name.
           Note: it can raise the same exception like is raising DROP PACKAGE command.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.

destroy_queue

          destroy_queue( p_queue_name in varchar2 ) 
          
           The procedure drops queue queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_deletion_queue_table - The queue is not dropped or is not dropped in expected time.

destroy_sequence

          destroy_sequence( p_queue_name in varchar2 ) 
          
           The procedure drops user sequence for queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.

destroy_table

          destroy_table( p_queue_name in varchar2 ) 
          
           The procedure drops table for queue p_queue_name.
          
          
Parameters:
p_queue_name - The name of table associate to the the requested sequence.
Throws:
c_err_queue_name - The queue name is forbidden.
c_err_deletion_queue_table - The table is not dropped or is not dropped in expected time.

destroy_type

          destroy_type( p_queue_name in varchar2 ) 
          
           The procedure drops user type for queue p_queue_name.
           Name of required type is based on p_queue_name.
           Note: it can raise the same exception like is raising DROP TYPE commnad.
          
          
Parameters:
p_queue_name - The name of queue associate to the the requested type.
Throws:
c_err_queue_name - The queue name is forbidden.

get_current_schema_name

          get_current_schema_name
          
           The function is returning name of current schema
          
          
Returns:
The name of schema where is XPP installed in varchar2
Throws:
c_err_get_curr_schema_name - The name of schema where is XPP installed is not possible to retrive.

get_msg_name_empty_queue

          get_msg_name_empty_queue( p_queue_name in varchar2 ) return varchar2 ; 
          
           The function is returning name exception when queue is empty.
          
          
Parameters:
p_queue_name - The name of queue.
Returns:
The message name of empty queue in varchar2

get_processing_status

          get_processing_status( p_task_name in varchar2 ) return varchar2 ; 
          
           The function is returning of processing of task in varchar2.
           List of possible statuses
           NOT_EXISTS
           CREATED
           CHUNKING
           CHUNKING_FAILED
           CHUNKED
           PROCESSING
           FINISHED
           FINISHED_WITH_ERROR
           CRASHED
          


          

Returns:
The status of tasks in varchar2.

get_queue_name

          get_queue_name( p_queue_name in varchar2 , p_with_schema in boolean default true ) return varchar2 ; 
          
           The function is translating required p_queue_name to real queue name.
           The goal of this translation it to secure creation/modify/delete of internal XPP queues.
          
          
Parameters:
p_queue_name - The requested name of queue. * @return name of real queue in varchar2
Returns:
name of real queue in varchar2
Throws:
c_err_get_curr_schema_name - The name of schema where is XPP installed is not possible to retrive.

get_queue_recipient_def_name

          get_queue_recipient_def_name( p_queue_name in varchar2 ) return varchar2 ; 
          
           The function is translating required p_queue_name to real recipient name.
           The goal of this translation it to secure creation/modify/delete of internal XPP recipients.
          
          
Parameters:
p_queue_name - The requested name of queue.
Returns:
name of real recipient in varchar2

initiate

          initiate( p_task_name in varchar2 , p_queue_name in varchar2 , p_comment in varchar2 , p_sql_stmt in clob , p_parallel_level in number ) 
          
           The procedure is initiate definition task, register catching of message when queue will be processed and execute the processing of the task.
          
          
Parameters:
p_task_name - The name of task.
p_queue_name - The requested name of queue.
p_comment - The comment of task.
p_sql_stmt - The sql statement to be executed in parallel.
p_parallel_level - The level of requested parallel execution of queue.
Throws:
c_err_end_of_evaluation_period - The evaluation period is over.

is_task_finished_successfuly

          is_task_finished_successfuly( p_task_name in varchar2 ) return boolean ; 
          
           The function is returning true task is successfuly finished, otherwise it return false.
          
          
Parameters:
p_task_name - The name of task.
Returns:
It returns true when task is successfuly finished, otherwise it returns false.

is_task_running

          is_task_running( p_task_name in varchar2 ) return boolean ; 
          
           The function is returning true task is running or configured an ready to running, otherwise it return false.
          
          
Parameters:
p_task_name - The name of task.
Returns:
It returns true when task is running, otherwise it returns false.

licence_id

          licence_id( p_company_name out varchar2 , p_invoice_id out varchar2 , p_paymenent_type out varchar2 , p_paymenent_date out varchar2 ) 
          
           The procedure is returning identification of official buyer of the XPP.
          
          
Parameters:
p_company_name - The name of company.
p_invoice_id - The identification of invoice.
p_paymenent_type - The payment information.
p_paymenent_date - The date of payment.

run_subscriber_processing

          run_subscriber_processing( p_queue_name in varchar2 ) 
          
           The procedure is chceking if the instance is running.
           When is not running the it runs the parallel task.
           Each task will try in concurency mode dequeue and process messages from the queue.
          
          
Parameters:
p_queue_name - The requested name of queue.
Throws:
c_err_error_while_run_parallel - The creation of parallel task fail.

send_message

          send_message( p_name in varchar2 , p_message in varchar2 ) 
          
           The procedure is sending message indentify by p_name parameter with context in parameter p_message.
           Note: When the length of context of message is longer then 1900 bytes then is cut to 1900
          
          
Parameters:
p_name - The name of message.
p_message - The content of the message.

task_stop

          task_stop( p_task_name in varchar2 , p_raise_exeception in boolean default true ) 
          
           The procedure is stopping running instance of task.
           It will raise exception when parameter p_raise_exeception is set to true and task is not running.
          
          
Parameters:
p_queue_name - The requested name of queue.
Throws:
c_err_task_not_exists - The task to stop not exists.

wait_my_alert

          wait_my_alert( p_alert in varchar2 , p_msg out varchar2 , p_stat out number , p_unlimited_time in boolean default false ) 
          
           The procedure is waiting for message.
           When value of input value p_unlimited_time is true, then waiting will be limited by maxiaml possible time defiend by database.
           Otherwise the expected time of waiting is defined by value of MAX_DURATION in table XPP_CONF_PARAM.
          
          
Parameters:
p_alert - The name of message (or alert).
p_msg - The content of message.
p_stat - Status of message. Possible values is 0, 1, 2. See definition of dbms_alert.waitone.
p_unlimited_time - The boolean value is setting waiting time to maximum configured in DB or based on XPP configuration.