indexing
     description: "DB_SELECTION for dynamic sql"
     date: "$Date$"
     revision: "$Revision$"

class interface
     DB_DYN_SELECTION

create

     make
                 -- Create an interface objet to query active base.

feature -- Initialization

     make
                 -- Create an interface objet to query active base.
     
feature -- Access

     last_parsed_query: STRING
                 -- Last parsed SQL query
                 -- (from DB_SELECTION)
     
feature -- Status report

     after: BOOLEAN
                 -- Is the container after?
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 container_exists: container /= void

     container: LIST [DB_RESULT]
                 -- Stored cursors.
                 -- (from DB_SELECTION)

     cursor: DB_RESULT
                 -- Cursor pointing to last fetched query result
                 -- (from DB_SELECTION)

     immediate_execution: BOOLEAN
                 -- Are requests immediately executed?
                 -- (default is no).
                 -- (from DB_EXEC_USE)

     is_allocatable: BOOLEAN
                 -- Can Current be added to other concurrently opened selections?
                 -- (from DB_SELECTION)

     is_executed: BOOLEAN
                 -- Is the statement has been executed ?
                 -- (from PARAMETER_HDL)

     is_exiting: BOOLEAN
                 -- Is exit condition of load_result iteration loop met?
                 -- (from DB_SELECTION)
           ensure -- from DB_SELECTION
                 Result implies (not is_ok or else exhausted or else (stop_condition /= void and then stop_condition.found))

     is_mapped (key: STRING): BOOLEAN
                 -- Is key mapped to an Eiffel entity ?
                 -- (from PARAMETER_HDL)
           require -- from STRING_HDL
                 keys_exists: key /= void

     is_prepared: BOOLEAN
                 -- Is the statement has been prepared ?
                 -- (from PARAMETER_HDL)

     is_tracing: BOOLEAN
                 -- Is trace option for SQL queries on?
                 -- (from DB_EXEC_USE)

     last_query: STRING
                 -- Last SQL statement used
                 -- (from DB_EXPRESSION)

     mapped_value (key: STRING): ANY
                 -- Value mapped with key
                 -- (from PARAMETER_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 key_mapped: is_mapped (key)
           ensure -- from STRING_HDL
                 result_exists: Result /= void

     object: ANY
                 -- Eiffel object to be filled in by cursor_to_object
                 -- (from DB_SELECTION)

     parameter_name_exist (key: STRING): BOOLEAN
                 -- (from PARAMETER_HDL)
           require -- from PARAMETER_HDL
                 not_void: key /= void

     stop_condition: ACTION
                 -- Object providing an execute routine called
                 -- after each load_result iteration step
                 -- (from DB_SELECTION)

     trace_output: FILE
                 -- Trace destination file
                 -- (from DB_EXEC_USE)
     
feature -- Status report

     is_connected: BOOLEAN
                 -- Has connection to the database server succeeded?
                 -- (from DB_STATUS_USE)

     is_ok: BOOLEAN
                 -- Is last SQL statement ok ?
                 -- (from DB_STATUS_USE)
     
feature -- Status setting

     cursor_to_object
                 -- Assign object attributes with cursor field values.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 cursor_exists: cursor /= void
                 object_exists: object /= void

     forth
                 -- Move cursor to next element of container.
                 -- (from DB_SELECTION)
           require else -- from DB_SELECTION
                 container_exists: container /= void
           ensure then -- from DB_SELECTION
                 container_index_moved: container.index = old container.index + 1
                 cursor_updated: not after implies cursor = container.item

     no_object_convert
                 -- Do not transform cursor into an Eiffel object
                 -- while reading in selection results.
                 -- (from DB_SELECTION)
           ensure -- from DB_SELECTION
                 object = void

     object_convert (reference: ANY)
                 -- Set object with reference, reference to an Eiffel
                 -- object to be filled in with cursor field values.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 reference_exists: reference /= void
           ensure -- from DB_SELECTION
                 object_set: object = reference

     reset_cursor (c: DB_RESULT)
                 -- Reset cursor with c.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 arguments_exists: c /= void
                 connected: is_connected
           ensure -- from DB_SELECTION
                 cursor_reset: cursor = c

     set_action (action: ACTION)
                 -- Set stop_condition with action.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 action_exists: action /= void
           ensure -- from DB_SELECTION
                 stop_condition_set: stop_condition = action

     set_container (one_container: like container)
                 -- Make results of selection query persist in container.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 container_exists: one_container /= void
           ensure -- from DB_SELECTION
                 container_set: container = one_container

     set_immediate
                 -- Set queries to be executed with a
                 -- `EXECUTE IMMEDIATE' SQL  statement.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 execution_status: immediate_execution

     set_query (query: STRING)
                 -- Set last_query with query.
                 -- (from DB_EXPRESSION)
           require -- from DB_EXPRESSION
                 query_not_void: query /= void
           ensure -- from DB_EXPRESSION
                 last_query_changed: last_query = query

     set_trace
                 -- Trace queries sent to database server.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 trace_status: is_tracing

     start
                 -- Set cursor on first element of container.
                 -- (from DB_SELECTION)
           require else -- from DB_SELECTION
                 container_exists: container /= void
           ensure then -- from DB_SELECTION
                 container_on_first: container.isfirst
                 cursor_updated: cursor = container.item

     unset_action
                 -- Reset stop_condition to Void.
                 -- (from DB_SELECTION)
           ensure -- from DB_SELECTION
                 stop_condition_void: stop_condition = void

     unset_container
                 -- Do not store in container results of selection.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 container_exists: container /= void
           ensure -- from DB_SELECTION
                 container_is_void: container = void

     unset_immediate
                 -- Set queries to be executed with a
                 -- PREPARE followed by a EXECUTE SQL statement.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 execution_status: not immediate_execution

     unset_trace
                 -- Do not trace queries sent to database server.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 trace_status: not is_tracing
     
feature -- Element change

     bind_parameter
                 -- Bind of the parameters of the sql statement
           require
                 prepared_statement: is_prepared

     execute
                 -- Execute the sql statement
           require
                 prepared_statement: is_prepared
           ensure
                 prepared_statement: is_executed

     parameter_count: INTEGER
           ensure -- from PARAMETER_HDL
                 Result > 0 implies is_prepared

     prepare (s: STRING)
                 -- Parse of the sql statement s
           require
                 not_void: s /= void
                 meaning_full_statement: s.count > 0
                 is_ok: is_ok
                 is_allocatable: is_allocatable
           ensure
                 prepared_statement: is_prepared
                 prepared_statement: not is_executed
     
feature -- Basic operations

     execute_query
                 -- Execute query with last_query.
                 -- (from DB_SELECTION)
           require -- from DB_EXPRESSION
                 last_query_not_void: last_query /= void

     load_result
                 -- Iterate through selection results,
                 -- load container if requested and call action routine
                 -- for each iteration step until exit_condition is met.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 connected: is_connected
                 is_ok: is_ok
           ensure -- from DB_SELECTION
                 cursor_not_void: cursor /= void
                 exit_condition_met: is_exiting

     next
                 -- Move to next element matching the query.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 connected: is_connected

     query (s: STRING)
                 -- Select stored objects using s and make
                 -- them retrievable using load_result.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 connected: is_connected
                 argument_exists: s /= void
                 argument_is_not_empty: not s.is_empty
                 is_ok: is_ok
                 is_allocatable: is_allocatable
           ensure -- from DB_SELECTION
                 last_query_changed: last_query = s

     terminate
                 -- Clear database cursor.
                 -- (from DB_SELECTION)
           require -- from DB_SELECTION
                 connected: is_connected
           ensure -- from DB_SELECTION
                 is_allocatable: is_allocatable

     wipe_out
                 -- Clear selection results.
                 -- (from DB_SELECTION)
           ensure -- from DB_SELECTION
                 container_is_empty: container /= void implies container.is_empty
                 object_model_void: object = void
                 cursor_void: cursor = void
     
feature

     clear_all
                 -- (from PARAMETER_HDL)

     set_map_name (n: ANY; key: STRING)
                 -- Store item n whith key key.
                 -- (from PARAMETER_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 not_key_in_table: not is_mapped (key)
           ensure -- from STRING_HDL
                 ht.count = old ht.count + 1

     unset_map_name (key: STRING)
                 -- Remove item associated with key key.
                 -- (from PARAMETER_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 item_exists: is_mapped (key)
           ensure -- from STRING_HDL
                 ht.count = old ht.count - 1
     
feature -- setting

     set_executed (b: BOOLEAN)
                 -- (from PARAMETER_HDL)

     set_parameter (value: ANY; key: STRING)
                 -- (from PARAMETER_HDL)
           require -- from PARAMETER_HDL
                 key_not_void: key /= void
                 has_parameters: parameter_count > 0

     set_parameters_value (p: ARRAY [ANY])
                 -- (from PARAMETER_HDL)
           require -- from PARAMETER_HDL
                 has_parameters: parameter_count > 0

     set_prepared (b: BOOLEAN)
                 -- (from PARAMETER_HDL)

     setup_parameters
                 -- setup parameters_value with actual parameters value
                 -- (from PARAMETER_HDL)
     
invariant

           -- from ANY
     reflexive_equality: standard_is_equal (Current)
     reflexive_conformance: conforms_to (Current)
           -- from DB_SELECTION
     last_cursor_in_container: container /= void and then not container.is_empty implies container.has (cursor)

end -- class DB_DYN_SELECTION