HP 3000 Manuals HP 3000 Manuals
REPLACE
Changes the values contained in a KSAM or MPE record or a data set entry.
Syntax
REPLACE[(modifier)] file-name[,option-list];
REPLACE allows you to replace one or more records or entries in a file or
data set. REPLACE uses the values in the update register as the new
values for the updated entries. REPLACE differs from UPDATE in that it
allows you to change search or sort items in a data set as well as key
items in a KSAM file, and because it can perform a series of changes to a
file or data set.
Note that it only replaces key (search) items in a manual master set if
there are no detail set entries linked to that key. It does not replace
detail set entries with search items that do not exist in manual master
sets associated with that detail.
The REPLACE operation does the following steps:
1. It retrieves a data record from the file or data set and places it
in the data register area specified by the LIST= option of
REPLACE, overwriting any prior data in this area.
2. It checks whether this record contains values that match any
selection criteria set up in the match register. If the retrieved
data does not meet the match criteria, it returns to step 1 to
retrieve the next record. If the record meets the selection
criteria specified in the match register, or if there are no match
criteria, it first performs any PERFORM= processing; then it
executes steps 3 through 5.
3. It replaces the values in the data register of the items to be
updated with the values in the update register. Or, if there are
no values in the update register, it uses the current values in
the data register. The update register can be set up by a routine
specified in a PERFORM= option since the PERFORM= processing is
done prior to the actual replacement. A PERFORM= routine can also
be used to place new values directly into the data register.
4. It writes a new record with updated values from the data register
to the file or data set and then deletes the old record.
5. It returns to step 1 unless the end of the file or chain has been
reached, or unless the SINGLE option or the CURRENT modifier has
specified replacement of a single entry only. At the end of the
file or chain or if only retrieving a single entry, it goes to the
next statement.
To use REPLACE effectively, do the followings:
1. Specify the entries to update. Set up the key and argument
registers if you are using REPLACE with no modifier or with the
CHAIN or RCHAIN modifiers. Set up the match register if you want
to replace particular entries when you use the CHAIN, RCHAIN,
SERIAL, or RSERIAL modifiers.
If you plan to replace a key item in a master set, then delete all
chains linked to that item from associated detail sets.
2. Get the new values and place them in the update register or, if
you are not using the update register, in the data register. Note
that REPLACE always uses the values in the update register if
there are any. You can get the new values from a user with a
DATA(UPDATE) or PROMPT(UPDATE) statement, or you can place them
directly in the update register with a SET(UPDATE) statement.
When you update multiple entries with different values, you should
set up the update or data register in a routine identified by a
PERFORM= option of the REPLACE statement. Otherwise, the same
items are updated with the same values in each of the multiple
entries.
3. Use the REPLACE statement to replace the selected entries, or to
replace all entries if no match criteria are specified. Make sure
that the entire record or entry is specified in a LIST= option.
Otherwise, REPLACE will write null values into items not specified
in the list register when it writes the updated entry back to the
file or data set.
_________________________________________________________________
NOTE Before using REPLACE, you must first set the SYSTEM
statement access mode to "UPDATE."
_________________________________________________________________
REPLACE adds the updated record and deletes the original entry so that
any data item that has not been specified in the list register will have
a null value after the operation. This is why you should make sure that
the list register contains every data item name in the set entry. If a
chained or serial access mode is specified (multiple entry updates), the
data items to be updated must have been specified in the update register
by using the PROMPT, DATA, LIST, or SET statements with the UPDATE
option.
REPLACE with the UPDATE option only replaces that part of the record or
entry that is not a search or sort item. Unlike the other forms of
REPLACE, it does not delete the original entry and replace it with a new
entry. Thus, for this option, only update items, not the whole record,
need be present in the list register.
If you are performing dynamic transactions (Transact/iX only), be aware
that transactions have a length limit. For a discussion about how
REPLACE is affected by this limitation, see "Limitations" under "Dynamic
Roll-back" in Chapter 6.
NOTE After the first retrieval, Transact uses an asterisk (*) for the
call list to optimize subsequent retrievals of that data set.
Statement Parts
modifier To specify the type of access to the data set or file, choose
one of the following modifiers:
none Updates an entry in a master set based on the
key value in the argument register; this option
does not use the match register. If the manual
master key is to be changed, there must not be
any entries in detail sets linked to the old
manual master key item.
CHAIN Updates entries in a detail set or KSAM chain
based on the key value in the argument register.
The entries must meet any match selection
criteria in the match register. If no match
criteria are specified, all entries are updated.
If the search item is to be changed in a chain
linked to a manual master set, the new item must
exist in the associated master set.
CURRENT Updates the last entry that was accessed from
the file or data set. This modifier only
replaces one entry, overriding the iterative
capability of REPLACE.
DIRECT Updates the entry stored at the specified record
number. The entry may not be defined as a child
item. Before using this modifier, you must
store the record number as a 32-bit integer
I(10,,4) in the item referenced by the RECNO
option.
PRIMARY Updates the master set entry stored at the
primary address of a synonym chain. The primary
address is located through the key value
contained in the argument register.
RCHAIN Updates entries in a detail set chain in the
same manner as the CHAIN option, only in reverse
order. For a KSAM file, this operation is
identical to CHAIN.
RSERIAL Updates entries from a file in the same manner
as the SERIAL option, except in reverse order.
For a KSAM or MPE file, this operation is
identical to SERIAL.
SERIAL Updates entries that meet any match criteria set
up in the match register in a serial mode. If
no match criteria are specified, all entries are
updated. Note that you cannot use this modifier
to replace key items in the master set. This
modifier forces the UPDATE option on a master
set if you are not matching on key items.
file-name The KSAM or MPE file or the data set to be accessed by the
replace operation. If the data set is not in the home base as
defined in the SYSTEM statement, the base name must be
specified in parentheses as follows:
set-name(base-name)
option- One or more of the following fields, separated by commas:
list
ERROR=label Suppresses the default error return that
([item-name]) Transact normally takes. Instead, the
program branches to the statement identified
by label, and Transact sets the list register
pointer to the data item item-name. Transact
generates an error at execution time if the
item cannot be found in the list register.
The item-name must be a parent.
If you do not specify an item-name, as in
ERROR=label();, the list register is reset to
empty. If you use an "*" instead of
item-name, as in ERROR=label(*);, then the
list register is not changed. For more
information, see "Automatic Error Handling"
in Chapter 7.
LIST=(range- The list of items from the list register to
list) be used for the REPLACE operation. For data
sets, no child items can be specified in the
range list.
If the LIST= option is omitted with any
modifier, all the items named in the list
register are used.
When the LIST= option is used, only the items
specified in a LIST= option have their match
conditions applied when the items are
included in the match register. When the
LIST= option is omitted, items which appear
in the list register and the match register
have their match conditions applied.
Otherwise, the match conditions for an item
are ignored.
The match register can be used only with the
modifiers CHAIN, RCHAIN, SERIAL, or RSERIAL.
All item names specified must be parent
items.
The options for range-list include the
following:
(item-name) A single data item.
(item-nameX: All the data items range from
item-nameY) item-nameX through item-nameY.
In other words, the list
register is scanned for the
occurrence of item nameY
closest to the top of the list
register. From that entry, the
list register is scanned for
item-nameX. All data items
between are selected. An error
is returned if item-nameX is
between item-nameY and the top
of the list register.
Duplicate data items can be
included or excluded from the
range, depending on their
position on the list register.
For example, if range-list is
A:D and the list register is as
shown,
![[]](../../pic3k/M013424/FFN323c50.gif)
then data items A, B, C, D, and
D are selected. For database
files, an error is returned if
duplicate entries are selected.
If item-nameX and item-nameY
are marker items (see the
DEFINE(ITEM) verb), and if
there are no data items between
the two on the list register,
no database access is
performed.
(item- All data items in the range
nameX:) from the last entry through the
occurrence of item-nameX
closest to the top of the list
register.
(:item- All data items in the range
nameY) from the occurrence of
item-nameY closest to the top
through the bottom of the list
register.
(item-nameX, The data items are selected
item-nameY,
...
item-nameZ)
from the list register. For
databases, data items can be
specified in any order. For
KSAM and MPE files, data items
must be specified in the order
of their occurrence in the
physical record. This order
need not match the order of the
data items on the list
register. Does not include
child items in the list unless
they are associated with a
VPLUS forms file. This option
incurs some system overhead.
(@) Specifies a range of all data
items of file-name as defined
in a data dictionary. The
range-list is defined as
item-name1:item-namen for the
file.
(#) Specifies an enumeration of all
data items of file-name as
defined in the data dictionary.
The data items are specified in
the order of their occurrence
in the physical record or form
as defined in the dictionary.
This order need not match the
order of the data items in the
list register.
( ) A null data item list. That
is, accesses the file or data
set, but does not transfer any
data.
LOCK Locks the specified file or database. If a
data set is being accessed, the lock is set
the entire time that REPLACE executes. If
the LOCK option is not specified but the
database is opened in mode 1, the lock
specified by the type of automatic locking in
effect is active while the entry is processed
by any PERFORM= statements, but is unlocked
briefly before the next entry is retrieved.
For a KSAM or MPE file, if LOCK is not
specified on REPLACE but is specified for the
file in the SYSTEM statement, then the file
is locked before each entry is retrieved,
remains locked while the entry is processed
by any PERFORM= statements, but is unlocked
briefly before the next entry is retrieved.
Including the LOCK option overrides
SET(OPTION) NOLOCK for the execution of the
REPLACE verb.
A database opened in mode 1 must be locked
while REPLACE executes. For transaction
locking, you can use the LOCK option on the
LOGTRAN verb instead of the LOCK option on
REPLACE if SET(OPTION) NOLOCK is specified.
If a lock is not specified (for a database
opened in mode 1) an error is returned.
See "Database and File Locking" in Chapter 6
for more information.
NOCOUNT Suppresses the message normally generated by
Transact to indicate the number of updated
entries.
NOMATCH Ignores any match criteria set up in the
match register.
NOMSG Suppresses the standard error message
produced by Transact as a result of a file or
database error.
PERFORM=label Executes the code following the specified
label for every entry retrieved by the
REPLACE verb before replacing the values in
the entry. The entries can be optionally
selected by MATCH criteria.
This option allows you to perform operations
on retrieved entries without your having to
code loop control logic. It is also useful
for setting up the update register for the
replacement. You can nest up to 10 PERFORM=
options.
The use of PERFORM forces application of the
UPDATE option on master sets.
RECNO= The item-name can be subscripted if an array
item-name item is being referenced. (See "Array
[(subscript)] Subscripting" in Chapter 3.)
With the DIRECT modifier, you must define
item-name to contain the 32-bit integer
number I(10,,4) of the record to be updated.
With other modifiers, Transact returns the
record number of the replaced record in the
32-bit integer I(10,,4) item-name.
SINGLE Updates only the first selected entry, and
then proceeds with the statement following
REPLACE.
SOPT Suppresses Transact optimization of database
calls. This option is primarily intended to
support a database operation in a performed
routine that is called recursively. The
option allows a different path to the same
detail set to be used at each recursive
entry, rather than optimizing to the same
path. It also suppresses generation of a
call list of "*" after the first call is
made. Use SOPT if you are calling TurboIMAGE
through the PROC or CALL verbs. For an
example of how SOPT is used, see "Examples"
at the end of the FIND verb description.
STATUS Suppresses the actions defined in Chapter 7
under "Automatic Error Handling." Use of this
option requires that you program your own
error handling procedures.
When STATUS is specified, the effect of a
REPLACE statement is described by the value
in the 32-bit status register:
Status Meaning
Register
Value
0 The REPLACE operation was
successful.
-1 A KSAM or MPE end-of-file condition
occurred.
> 0 For a description of the condition
that occurred, see the database or
MPE/KSAM file system error
documentation that corresponds to
the value.
STATUS causes the following with REPLACE:
* Makes the normal multiple accesses
single.
* Suppresses the normal rewind done by
REPLACE, so CLOSE should be used
before REPLACE(SERIAL).
* Suppresses the normal find of the
chain head by REPLACE, so PATH should
be used before REPLACE(CHAIN). (See
the example below.)
UPDATE When this option is used with Transact/iX
versions that are prior to A.04.00, REPLACE
does not update search or sort items. It
should be used to perform an iterative update
on a data set or file where you do not want
to change search or sort items. You should
use this option when replacing a non-key item
in a manual master set. Otherwise, a
DUPLICATE KEY IN MASTER error occurs when
REPLACE adds the new entry.
When UPDATE is used on Transact/iX versions
A.04.00 and later and the database is enabled
for critical item update, search and sort
items are updated. If critical item update
is not enabled, UPDATE operates as it did
prior to version A.04.00. See the
TurboIMAGE/XL Database Management System
Reference Manual for more information.
Examples
The first example replaces a search item value in a master set with a new
value. Before making the replacement, it makes sure that a detail set
linked to the master set through CUST-NO has no entries with the value
being replaced.
PROMPT(PATH) CUST-NO ("Enter customer number to be changed");
FIND(CHAIN) SALES-DET, LIST=(); <<Look for old number in detail set >>
IF STATUS <> 0 THEN <<and, if chain exists, delete it. >>
DO
DISPLAY "Before replacing customer number, delete from SALES-DET";
PERFORM DELETE-SALES-REC;
DOEND;
<< No chains linked to this customer number; so continue with update. >>
LIST LAST-NAME: <<Set up rest of list register >>
FIRST-NAME:
STREET-ADDR:
CITY:
STATE:
ZIP;
REPLACE CUST-MAST, <<Replace specified customer number >>
LIST=(CUST-NO:ZIP), <<with new number entered in >>
PERFORM=GET-NEW-NAME; <<GET-NEW-NAME routine >>
:
GET-NEW-NAME:
DATA(UPDATE) CUST-NO ("Enter new customer number");
RETURN;
The following example uses marker items to declare a range. If a key
item is involved, this code logs the change and uses REPLACE instead of
UPDATE to make the change. (Remember that you cannot be sure which items
are in a list delimited by marker items.) STATUS must be used to capture
the error of attempting to update a key or sort item:
UPDATE DETAIL-SET,
LIST=(MARKER1:MARKER2),
STATUS;
IF STATUS <> 0 THEN <<Error, Check it out >>
IF STATUS <> 41 THEN <<Unexpected >>
GO TO ERROR-CLEANUP
ELSE <<Log and complete update >>
DO
PUT LOG-FILE,
LIST=(MARKER1:MARKER2);
REPLACE(CURRENT) DETAIL-SET,
STATUS,
LIST=(MARKER1:MARKER2);
IF STATUS <> 0 THEN
GO TO ERROR-CLEANUP;
DOEND;
The following example replaces each occurrence of a non-key item, ZIP,
with a new value. It asks the user to enter the value to be replaced as
a match criterion for the retrieval. Before making the replacement, it
uses a PERFORM= routine to display the existing record and ask the user
for a new value:
LIST LAST-NAME: <<Set up list for update >>
FIRST-NAME:
STREET-ADDR:
CITY;
PROMPT(MATCH) ZIP ("Enter ZIP code to be replaced");
REPLACE(SERIAL) MAIL-LIST-DETL, <<Replace each occurrence of specified>>
LIST=(LAST-NAME:ZIP), <<zip code, a non-key item. >>
UPDATE,
PERFORM=GET-ZIP;
EXIT;
GET-ZIP:
DISPLAY;
DATA(UPDATE) ZIP ("Enter new ZIP code");
RETURN;
The next example changes the product number in a master set PRODUCT-MAST,
and then updates the related detail entries in the associated detail set
PROD-DETL. When the detail set entries have all been updated, it deletes
the master entry for the old product number for PRODUCT-MAST.
PROMPT PROD-NO ("Enter new product number"):
DESCRIPTION ("Enter a one line description");
PUT PRODUCT-MAST,
LIST=(PROD-NO:DESCRIPTION);
SET(UPDATE) LIST(PROD-NO); <<Set up update register with >>
<<new value >>
DATA(KEY) PROD-NO <<Set up key and argument registers >>
("Enter product number to be changed");
RESET(STACK) LIST; <<Release stack space >>
<<Now, update the product number in each entry of the associated detail
set>>
DISPLAY "Updating product number in PROD-DETL", LINE2;
LIST PROD-NO: <<Allocate space for PROD-DETL entry >>
INVOICE-NO:
QTY-SOLD:
QTY-IN-STOCK;
REPLACE(CHAIN) PROD-DETL, <<Replace each entry in detail set >>
LIST=(PROD-NO:QTY-IN-STOCK);
RESET(STACK) LIST;
DELETE PRODUCT-MAST, <<Delete old entry from master set >>
LIST=();