HP 3000 Manuals HP 3000 Manuals
Updating Data TurboIMAGE/XL allows you to change the values of data items if the user class number with which you opened the database grants this capability to you. These items cannot be master data set key items or detail data set search or sort items, unless you take advantage of the critical item update (CIUPDATE) option. Depending on the CIUPDATE option settings for the database and the current process, you could change the values of detail data set search and sort items if the database access mode is 1, 3, or 4. This option is described later in this section. Before you call the DBUPDATE library procedure to change the item values, you must call DBGET to locate the entry you intend to update. This sets the current record address for the data set. The DBUPDATE library procedure uses the current record address to locate the data items whose values are to be changed. A lock can be established before the call to DBGET to guard against accidental modification of the record by another user. This is recommended in any shared access mode (as discussed below). When the program calls DBUPDATE, it specifies the data set name, a list of data items to be changed, and the name of a buffer containing values for the items. For example, if a program changes the street address of a customer in the CUSTOMER data set of the ORDERS database, the program can first locate the entry to be changed by calling DBGET in calculated access mode with the customer's account number and then calling the DBUPDATE procedure to change the value of the STREET-ADDRESS data item in that entry. Access Modes and User Class Number To update data items, the database must be opened in access mode 1, 2, 3, or 4. If it is opened in access mode 1, the data entry, data set, or database must be locked while the update is occurring. If the CIUPDATE option settings for the database and the current process permit updates of detail data set search and sort items, the database must be opened in access mode 1, 3, or 4 to take advantage of this option. TurboIMAGE/XL guarantees that all updates to a data entry will be carried out even if they are requested by different users concurrently and locking is not used. To ensure this, TurboIMAGE/XL always completes the processing of one DBUPDATE request before it begins processing under another. However, data consistency problems can still occur if an update is based on data values that are not current. For example, while withdrawing 10 items from the stock, two users may read the same data entry from the INVENTORY data set. If the current value of ONHANDQTY is 30 and they each subtract 10 from it and then update the entry, both updates will operate successfully but the new value will be 20 rather than 10. To prevent such errors, a lock covering the data entry can be put in effect before it is read and released after it is updated. TurboIMAGE/XL attempts to enforce this locking technique for users in database access mode 1 by checking to see if an appropriate lock is in effect before executing an update. However, to have its proper effect, the lock should be made before the call to DBGET.
NOTE To avoid locking around terminal reads, you may need to establish the lock, perform a mode 1 DBGET, check the value, update the entry, then remove the lock.
The password you use to open the database must grant update capability to the data items you intend to change. The user class number associated with the password must either be in the write class list of the data set containing the items to be updated, or in both the read class list of the data set and in the write class list of the data item. Updating Key, Search, and Sort Items For compatibility and security reasons, by default you cannot use the DBUPDATE library procedure to update a master data set key item, or a detail data set search or sort item. However, in database access mode 1, 3, or 4, you can update search or sort items if permitted by the CIUPDATE option settings for the database and the current process; refer to the following discussion of CIUPDATE. If you do not or cannot take advantage of the CIUPDATE option and need to change search or sort items, or if you need to change master data set key items, you can first delete the selected entry with DBDELETE (see the section entitled "Deleting Data Entries"), and then add the entry back into the database with DBPUT. However, keep in mind that this method places the new record at the end of each unsorted chain, which disturbs the chronological order of each path. The new entry must be complete. That is, you cannot delete an entry and then add a new entry with only the item you want changed. If you do this, the rest of the entry will be set to binary zeros by DBPUT. Furthermore, make sure the current list is truly current when using an asterisk (*) to reference the list; otherwise, if items have been added or deleted, you could cause DBPUT to write binary zeros over existing data. Note that using the commercial "at sign" (@) to write all the items in a data entry avoids this problem. To facilitate updates of detail data set critical items, you should design any new databases to take advantage of the CIUPDATE option. Applications to be used with these databases can be written as described in the next section. Critical Item Update. TurboIMAGE/XL provides an option called critical item update (CIUPDATE) which, depending on the settings for the database and the current process, can permit you to update the values of detail data set search and sort items. To take advantage of this option, you first need to set it through the TurboIMAGE/XL utility DBUTIL. Use the DBUTIL >>SET command, and set the CIUPDATE option equal to ON or ALLOWED; the default setting of DISALLOWED does not permit updates of detail data set critical item values with the DBUPDATE procedure. The ON setting permits any process to use critical item update on the database unless the process explicitly disables the option by calling the DBCONTROL procedure in mode 6; this call disables the option for the duration of the process or until a call to DBCONTROL in mode 5 enables the option. The ALLOWED setting requires that a process first call DBCONTROL in mode 5 to enable the CIUPDATE option for the duration of the process or until a call to DBCONTROL in mode 6 disables the option. Using DBCONTROL modes 5 and 6 does not alter the permanent setting set with the DBUTIL >>SET command. The database must be opened in access mode 1, 3, or 4; and your user class must have write access at the set level, or both read access at the set level and write access at the item level. Programmers should review the design of any of their applications that are used to update the values of data items to ensure that the data will be updated as expected. Applications that open the database in access mode 2 do not need to be modified, because only access modes 1, 3, and 4 can be used with CIUPDATE. Applications that rely on TurboIMAGE/XL to restrict update of detail data set search and sort items can continue to do so as long as the database access mode is not 1, 3, or 4, or the CIUPDATE option is set as follows: * DISALLOWED, or * ALLOWED and the process does not call DBCONTROL in mode 5. Otherwise, these applications need to be modified to call the DBINFO procedure to check the CIUPDATE flags for the database and the current process, and (if need be) to disable CIUPDATE for the current DBOPEN via the DBCONTROL procedure in mode 6. Another method of restricting access to search and sort items is by granting read-only access at the data set level and limiting write access at the data item level. Applications that allow the sort item for the current chain to be updated must allow the current entry to be moved within the chain. An entry which is moved can be encountered twice within one chained read. To update a detail data set search or sort item, the following sequence of operations is recommended for your programs: 1. Call DBOPEN in access mode 1, 3, or 4. 2. Call DBLOCK to lock all data which must not be changed by other processes. 3. If this is a logical transaction, you need to declare the beginning of modifications by calling DBBEGIN or, if you are using dynamic roll-back, DBXBEGIN (see the discussion of logical transactions later in this chapter). 4. Read data using DBFIND and DBGET to determine what needs to be modified. 5. Call DBINFO to check the specific CIUPDATE option setting for the database and the setting for the current DBOPEN. 6. If the CIUPDATE setting is ON and has not been disabled by a DBCONTROL mode 6, go to the next step. If the setting is ALLOWED, call DBCONTROL mode 5 to enable the option. Note that if the CIUPDATE setting is ON and the option has not been disabled, you can still call a DBCONTROL mode 5 successfully. 7. If the CIUPDATE option is permitted, call DBUPDATE. 8. If the CIUPDATE option is not permitted, call DBDELETE and DBPUT. 9. Check the status code. 10. If the status code is not 0, call DBERROR and take appropriate action. For example, if this is a dynamic transaction, you must call DBXUNDO to roll back the transaction. _________________________________________________________________ NOTE If this is a dynamic transaction, a call to DBXUNDO must be processed if an error occurs or if the transaction needs to be rolled back for any other reason. TurboIMAGE/XL will not go on to the next transaction in the event of a transact ion abort unless an intervening call to DBXUNDO occurs. _________________________________________________________________ 11. If this is a logical transaction, call DBEND or, alternatively, DBXEND to declare the end of the modifications. However, if this is a dynamic transaction and DBXUNDO was used to roll back the transaction, your program logic should ensure that the subsequent call to DBXEND is not processed. 12. Call DBUNLOCK to release all of the locks.