Visual InterDev

Adding Records

See Also

When you work with a recordset object in script, you can add records to the database in two ways. The first is a two-step process. First you initialize a new, blank record. The user can then fill in the record. When the record is complete, the user can click a Save button (or similar) to write the current record to the database, just as if an existing record had been updated. This strategy is useful when you are working with a form where users can edit existing records or add new ones.

Alternatively, you can create a new record and populate it in a single operation. Adding immediately this way can be more efficient if your target scripting platform is Server, because it avoids a round trip to the server to initialize the new record. This strategy is particularly useful when you are not using a form, but instead creating new records in script — especially if you have to add several records to the database at once.

You might not always be able to create new records. You need the correct settings for your recordset, adequate permissions in the database, and sufficient information to uniquely identify records. For details, see Determining When Query Results Can Be Updated.

Note   If you are writing ASP pages, you can set options that help you find errors and trace events in the scripting object model. For details, see Debugging Script Objects in ASP Pages.

Initializing and Then Updating

You typically use the initialize and update strategy when working with a form. The form will usually have a New button and a Save button. By using the initialize and update strategy, you can use the same Save button to update existing records that have been edited as well as to insert new records.

To initialize a new record in the recordset, you use the Recordset object's addRecord method. If you are working with data-bound design-time controls, the recordset automatically clears the controls when you initialize a new record. Then when you save the record, the values the user has entered are automatically copied to the current record before it is written to the database.

If you are working with controls that are not data-bound design-time controls, you must perform some of this work yourself. After initializing a new record, you must manually clear the controls so users can enter new data. Then when the user clicks a Save button or similar, you must be sure to copy values from the controls to the current record before it is written to the database.

To initialize and add a record

1. Be sure there is a Recordset control on your page. For details, see Getting Records. Note the Recordset control's name.
   
   
2. In script, call the recordset script object's addRecord method to prepare a new, blank record in the recordset. For example, the following event handler for a New button calls the addRecord method.

   Sub btnNew_onclick
      rsEmployeeList.addRecord
   End sub
   

   If your page contains non-data-bound controls, clear them after initializing the new record, as in this example:

   Sub btnNew_onclick
      rsEmployeeList.addRecord
      txtName.value = ""
      chkInsured.value = false
   End sub
   

Note   You can only work with controls and recordsets at the same time if both use the same target scripting platform. For more details, see The Scripting Object Model and Creating Forms with Design-Time Controls.

When the user clicks the New button, the user can enter information for the new record. The Recordset control on the page sets a flag that this is a new record. When the user clicks the Save button, the Recordset control actually creates the new record, updates it with the user's data, and writes it to the database.

After the new record has been filled in, it is saved the same way an existing record is (with the recordset object's updateRecord method). For details, see Updating Records.

Adding Immediately

You typically add records to a database immediately if you are creating them in script. Adding a record immediately to the database is similar to first initializing a record and later saving it. However, because the add and update functions are performed in a single step, only one trip is required to the server.

When you create a record immediately, you must gather the information for the fields and then pass them as parameters when you add the new record.

To add a record immediately

1. Gather the information to be written to the database. You can do this using controls on the page, values derived from calculations, or any other method.
   
   
2. Create two arrays, one containing the names of the fields and the other the values. For example, the following script creates an array of fields that track a transaction (transID, transDate, and transTime) and values for each field:

   Dim fieldsArray(2)
   Dim valuesArray(2)
   fieldsArray(0) = "transID"
   fieldsArray(1) = "transDate"
   fieldsArray(2) = "transTime"
   valuesArray(0) = getTransactionCounter()
   valuesArray(1) = Date
   valuesArray(3) = Time
   

3. Call the addImmediate method of the Recordset object to add the record to, passing it the two arrays you just created, as in the following example:

   rsTransactionLog.addImmediate( fieldsArray, valuesArray )
   

For more information about writing event handlers for design-time controls, see Writing Scripts for Script Objects.