Component /dat/lib/database/dbCursor

DbCursor provides cursor styled access to data within a database. A dbCursor must be custom configured with an document type, database mapping, and database access information. Once configured, the dbCursor will fetch, insert, update, and delete documents of the document type to and from the database.

Documents are fetched using dbCursor find port. On receipt of document on this port, dbCursor will begin a query for documents having the same element and attribute values as the input document. The first document satisfying the query will be retrieved and retained in variable contained within the dbCursor. The fetched document and or any element or attribute within the document can be accessed using output data ports on the contained variable.

Cursor movement to the next or previous document is performed using the next and previous pins.

Documents are updated by replacing the values of elements and attributes within the contained variable and then using the save pin. Values for elements and attributes are updated using input data ports on the contained variable.

Documents are inserted into the database by first using the clear pin, then enter new values to the elements and attributes of the contained variable, and lastly using the save pin.

Documents are deleted by fetching the desired document to be deleted and then using the delete pin.

In order to work correctly, a dbCursor must be configured with a document type, database mapping, and database connection information.

Configuring a dbCursor with a document type is accoumplished by dragging the document type from the component tree and dropping it over the dbCursor or over the dbCursor's editor.

Database access information is configured by entering values into the dsn, userName, and password properties. This maybe performed on the dbCursor or in its editor.

Database mapping is configured by opening dbCursors component editor. Once the database access information is entered, the left part of the dbCursor's editor will display the tables and columns found within the schema of the database. Database mapping is added by drap and drop of a columns from the data base tree over an element or attribute within the document type.

Pins

• send receipt of a signal on this pin will result sending the respective documents out in each output data port. After sending data on all output ports, a signal will be sent on the sent pin.
• prev receipt of a signal on this pin will result in fetching the previous document satisfying the input query from the data base and storing it in the contained variable. If successful, a signal will be sent on the fetched pin. If unsuccessful an signal will be sent on the bod pin.
• next receipt of a signal on this pin will result in fetching the next document satisfying the input query from the data base and storing it in the contained variable. If successful, a signal will be sent on the fetched pin. If unsuccessful an signal will be sent on the eod pin.
• clear receipt of a signal on this pin will result in clearing the contained variable. After clearing the variable, a signal will be sent on the cleared pin.
• save receipt of a signal on this pin will result saving the document in the contained variable into the database. If the variable contains a document that was previously fetched from the data base, the records in the database will be updated accordingly. If the contains a document that was created by data ports after the variable was cleared, then records will be inserted into the database. After updating or inserting a document into the database a signal is sent on the saved pin.
• delete receipt of a signal on this pin will result deleting data in database corresponding the the document currently in the contained variable and last fetched by the dbCursor.
• fetched a signal will be sent on this pin after successfully fetching a document from the database either as a result of receipt of a document on find port, or by receipt of a signal on the next or prev pins.
• saved a signal will be sent on this pin after successfully inserting or updating a document as a result of receipt a signal on the save pin.
• deleted a signal will be sent on this pin after on successfully deleting a document as a result of receipt a signal on the delete pin.
• bod on receipt a signal on the prev pin and there are no prior document satisfying the query, a signal will be sent on this pin.
• eod on receipt of a document on the find port for which no document can be found in the database to match the input document, or on receipt a signal on the next pin and there are no next document satisfying the query, a signal will be sent on this pin.
• sent on receipt a signal on the send pin and after sending all corresponding documents out any output data port, a signal will be sent on this pin.
• cleared on receipt a signal on the cleared pin and after clearing the document in the variable, a signal will be sent on this pin.

Ports

• find on receipt of a document on this port will start a query to find all documents with data matching the data on the input document and will fetch the first document into the contained varaible. If successful, a signal will be sent on the fetched pin, othewise a signal will be sent on the eod pin.
• error if an error occurs while accessing the data base, an error document will be sent on this port.

Properties

• dsn the jdbc data source url needed to access the database.
• userName the user name needed to access the database.
• password the password needed to access the database.