HP 3000 Manuals HP 3000 Manuals
UPDATE
Modifies a single entry in a KSAM or MPE file or in a data set, or
modifies a VPLUS form.
Syntax
UPDATE[(FORM)] destination[,option-list];
UPDATE modifies data items that are not key search or sort items in a
master or detail set entry. The item to be updated must have been
retrieved by a prior FIND or GET statement. When used with the FORM
modifier, UPDATE modifies and redisplays a currently displayed VPLUS
form.
In versions of Transact/iX A.04.00 and later, UPDATE modifies key search
or sort items in a master or detail data set entry when critical item
update is enabled for the database. The UPDATE verb does not use the
update register. The new value must be placed in the data register
before UPDATE is executed. The value can be retrieved from a user, or
from a data set or file.
To update a non-key value with UPDATE, do the following:
1. Fetch the record or entry to update and place it in the data
register. You can do this with a GET or FIND statement. If you
want to update several entries, updating the same item in each
entry with a different value, use a FIND statement with a PERFORM=
option that calls a routine containing the UPDATE statement. If
you want to update a single entry, use a GET statement.
2. Place the new value in the data register. You can get the new
value from a data set or file, or from the user. If you are
getting a value from the user, a PROMPT(SET) or DATA(SET)
statement is useful, since it allows the user to choose whether to
leave an existing value in the data register or enter a new value.
3. Use the UPDATE statement to write the new values to the entry or
record. Since UPDATE always updates the last entry retrieved, it
needs no access modifiers. You must include the names of any
items to be updated in a LIST= option.
If you want to update several entries, updating the same data item in
each entry with the same value, you should use the REPLACE statement
rather than the UPDATE statement. (See the REPLACE verb description.)
NOTE Before using UPDATE, you must first set the SYSTEM statement access
mode to "UPDATE".
Statement Parts
FORM Causes this verb to transfer data from the data register to a
VPLUS form displayed at a VPLUS compatible terminal by
PUT(FORM) or GET(FORM). If the requested form is not currently
displayed on the terminal, an error results. If this modifier
is not specified, the destination must be a data set or file.
destinationThe name of a file, data set, or form to be updated.
If destination identifies a data set that 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)
In an UPDATE(FORM) statement, the destination must identify a
form in a forms file that was named in the SYSTEM statement.
For UPDATE(FORM), destination can be specified as any of the
following:
form-name Name of a form to be updated by UPDATE(FORM).
(item-name Name of an item whose data register location
[(sub- contains the name of the form to be updated by
script)]) UPDATE(FORM). The item-name can be subscripted
if an array item is referenced. (See "Array
Subscripting" in Chapter 3.)
* The form identified by the "current" form name;
that is, the form name most recently specified
in a statement that references a VPLUS form.
Note that this does not necessarily mean the
form currently displayed.
& The form identified as the "next" form name;
that is, the form name specified as the "NEXT
FORM" in the FORMSPEC definition of the current
form.
option- The LIST= option is always available. Other options,
list described below, can be used only with or only without the
FORM modifier.
LIST= The list of items from the list register to be
(range-list) used for the UPDATE operation. For data sets,
no child items can be specified in the range
list. For UPDATE(FORM) only, items in the range
list can be child items.
If the LIST= option is omitted with any modifier
except UPDATE(FORM), all the items in the list
register, and either in the SYSTEM statement or
the data dictionary for the form are used.
The LIST= option should not be used when
specifying an asterisk (*) as the source.
For all options of range-list, the data items
selected are the result of scanning the data
items in the list register from top to bottom,
where top is the last or most recent entry.
(See Chapter 4 for more information on
registers.)
The LIST= option has a limit of 64 individually
listed item names. A range limitation of 255
items for TurboIMAGE data sets and 128 items for
VPLUS forms also exists.
All item names specified must be parent items
when not using the FORM modifier. The options
for range-list and the records or forms they
update include the following:
(item-name) A single data item.
(item-nameX: All the data items in the range
item-name) from 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/FFN343c50.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 from
nameX:) the last entry through the
occurrence of item-nameX closest
to the top of the list register.
(:item- All data items in the range from
nameY) the occurrence of item-nameY
closest to the top through the
bottom of the list register.
(item-nameX, The data items are selected from
item-nameY, the list register. For databases,
... data items can be specified in any
item-nameZ) order. For KSAM and MPE files or
for VPLUS forms, data items must
be specified in the order of their
occurrence in the physical record
or form. This order need not
match the order of the data items
on the list register. Do not
include child items in the list
unless they are defined in the
VPLUS form. This option incurs
some system overhead.
(@) Specifies a range of all data
items of file-name as defined in a
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,
access the file or data set, but
do not transfer any data.
Options Available Without the Form Modifier
ERROR=label Suppresses the default error return that Transact
([item-name]) 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 specify no 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 the discussion "Automatic Error
Handling" in Chapter 7.
LOCK Locks the specified file or database for the
duration of the UPDATE. For databases, if this
option is not specified on UPDATE when the database
has been opened with mode 1, then automatic locking
will execute the lock.
For a KSAM or MPE file, if LOCK is not specified on
UPDATE 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 UPDATE verb.
For transaction locking, you can use the LOCK
option on the LOGTRAN verb instead of the LOCK
option on UPDATE if SET(OPTION) NOLOCK is
specified.
See "Database and File Locking" in Chapter 6 for
more information on locking.
NOMSG The standard error message produced by Transact as
a result of a file or database error is to be
suppressed.
STATUS Suppresses the actions defined in Chapter 7 under
"Automatic Error Handling." This option allows you
to program your own error handling procedures.
When STATUS is specified, the effect of an UPDATE
statement is described by the value in the 32-bit
integer status register:
Status Meaning
Register
Value
0 The UPDATE operation was successful.
-1 A KSAM or MPE end-of-file condition
occurred.
> 0 For a description of the. condition
that occurred, refer to database or
MPE/KSAM file system error
documentation that corresponds to
the value.
See "Using the STATUS Option" in Chapter 7 for
details on how to use the STATUS data.
Options Available Only With the Form Modifier
APPEND Appends the next form to the specified form,
overriding any freeze or append condition specified
for the form in its FORMSPEC definition. APPEND
sets the FREEZAPP field of the VPLUS comarea to 1.
CLEAR Clears the previously displayed form when the
requested form is displayed, overriding any freeze
or append condition specified for the form in its
FORMSPEC definition. CLEAR sets the FREEZAPP field
of the VPLUS comarea to zero.
CURSOR= field-name Positions the cursor within the specified field.
|item-name Field-name identifies the field and the item-name
[(subscript)] identifies the item which names the field. The
item-name can be subscripted if an array item is
being referenced. (See "Array Subscripting" in
Chapter 3.)
__________________________________________________
NOTE To ensure that the cursor will be positioned
on the correct field, you must have a one to
one correspondence between the fields defined
in VPLUS. Transact determines where to
position the cursor by counting the fields.
__________________________________________________
FEDIT Performs any field edits defined in the FORMSPEC
definition immediately before redisplaying the
form.
FKEY= item-name Moves the number of the function key pressed by the
[(subscript)] operator in this operation to a 16-bit integer
I(5,,2) item-name. The function key number is a
digit from 1 through 8 for function keys f1 through
f8, or zero for the ENTER key. Transact determines
which function key was pressed from the value of
the field LAST-KEY in the VPLUS comarea. The item
name can be subscripted if an array item is being
referenced. (See "Array Subscripting" in Chapter
3.)
Fn=label Control passes to the labeled statement if the
operator presses function key n. n can have a
value of 0 through 8, inclusive, where zero
indicates the ENTER key. This option can be
repeated as many times as necessary in a single
UPDATE(FORM) statement.
FREEZE Freezes the specified form on the screen and
appends the next form to it, overriding any freeze
or append condition specified for the form in its
FORMSPEC definition. FREEZE sets the FREEZAPP
field of the VPLUS comarea to 2.
INIT Initializes the fields in a VPLUS form to values
defined by the forms design utility FORMSPEC and
perform any Init Phase processing before
transferring data.
WAIT=[Fn] Does not return control to the program until the
terminal user has pressed function key n. n can
have a value of 0 through 8, where 1 through 8
indicate the keys f1 through f8 and 0 indicates the
ENTER key. If Fn is any key other than f8, the f8
exit function is disabled.
If the user presses a different function key,
Transact sends a message to the window saying which
key is expected.
If Fn is omitted, then UPDATE(FORM) waits until any
function key is pressed.
WINDOW= ([field,] Places a message in the window area of the screen
message) and, optionally, enhances a field on the form. The
fields field and message can be specified as
follows:
field Either the name of the field
to be enhanced, or an
item-name[(subscript)] within
parentheses that will contain
the data item of the field to
be enhanced at run time.
message Either a "string" enclosed in
quotation marks that
specifies the message to be
displayed, or an
item-name[(subscript)] within
parentheses containing the
message string to be
displayed in the window.
Examples
This example prompts the user for the values required to find a record.
After it is retrieved, the user is prompted for the new quantity for the
item and the record is updated. Note that the LIST= option for both the
retrieval and the update only need specify the item to be updated.
PROMPT(PATH) INV-NMBR ("INVOICE NUMBER");
PROMPT(MATCH) ITEM-NUM ("ITEM NUMBER");
LIST ITEM-QTY;
GET(CHAIN) ORDER-LINE,
LIST=(ITEM-QTY);
DISPLAY;
DATA(SET) ITEM-QTY
("Enter new quantity or press return to keep old quantity");
UPDATE ORDER-LINE,
LIST=(ITEM-QTY);
The next example is similar, except that it allows the user to update all
the entries in a chain, rather than a single entry.
PROMPT(PATH) INV-NMBR ("INVOICE NUMBER");
PROMPT(MATCH) ITEM-NUM ("ITEM NUMBER");
LIST ITEM-QTY;
FIND(CHAIN) ORDER-LINE,
LIST=(ITEM-QTY),
PERFORMUPDATE-QTY;
:
UPDATE-QTY:
DISPLAY;
DATA(SET) ITEM-QTY
("Enter new quantity or press return to keep old quantity");
UPDATE ORDER-LINE,
LIST=(ITEM-QTY);
RETURN;
The following example uses marker items to declare a range. If a key
item is involved, you should log the attempt. STATUS must be used to
capture the error of attempting to update a key or sort item:
UPDATE DETAIL-SET,
LIST=(MARKER1:MARKER2),
STATUS; STATUS;
IF STATUS <> 0 THEN <<Error, check it out >>
IF STATUS <> 41 THEN <<Unexpected error >>
GO TO ERROR-CLEANUP <<Log and complete update >>
ELSE
DO
PUT LOG-FILE,
LIST=(MARKER1:MARKER2);
DISPLAY "key update attempted";
DOEND;
The next example uses an UPDATE(FORM) statement to update the current
form. It highlights the item identified in FIELD-ENH and sends the
message contained in WINDOW-MSG to the window area of the form:
DEFINE(ITEM) FIELD-ENH U(16): <<Contains name of field in VPLUS form.>>
WINDOW-MSG U(72); <<Contains message for VPLUS window. >>
:
MOVE (FIELD-ENH) = "FIELD1";
MOVE (WINDOW-MSG) = "This field must be numeric";
:
UPDATE(FORM) *,
WINDOW=((FIELD-ENH),
(WINDOW-MSG));
In this particular case, as a result of the prior MOVE statements, the
UPDATE statement highlights FIELD1 in the current form and displays the
message "This field must be numeric" in the window area of that form.