UPDATE statement

Displays fields or variables, requests input, and then puts the input data in both the screen buffer and in the specified fields or variables.

The UPDATE statement is a combination of the following statements:

Note: Does not apply to SpeedScript programming.

Data movement



Syntax

UPDATE
  [ UNLESS-HIDDEN ]
  [  field  [ format-phrase ] [ WHEN expression ]
    | TEXT ( field [ format-phrase ] ... ) 
    | field = expression
    | constant [ AT n  | TO n ]
    | ^ 
    | SPACE [ ( n ) ]
    | SKIP [ ( n ) ]
  ] ...
  [ GO-ON ( key-label ... ) ]
  [ frame-phrase ]
  [ editing-phrase ]
  [ NO-ERROR ]
UPDATE record
  [ EXCEPT field ... ]
  [frame-phrase ]
  [ NO-ERROR ]
UNLESS-HIDDEN

Restricts UPDATE to fields whose HIDDEN attribute is FALSE.

field

Represents the name of the field or variable whose value you want to display, change, and store in the screen and record buffers.

In array fields, array elements with constant subscripts are handled as any other field. Array fields with no subscripts are expanded as though you entered the implicit elements. See the DISPLAY statement reference entry for information on how array fields with expressions as subscripts are handled.

You can supply values for array elements in the UPDATE statement as follows:

UPDATE x[1] = "x".

This statement assigns the letter x to the first element of array x. If you do not include an array subscript, the AVM assigns the value to all elements of the array.

UPDATE X = "X".

This statement assigns the letter x to all elements of the array x.

format-phrase

Specifies one or more frame attributes for a field, variable, or expression. For more information on format-phrase, see the Format phrase reference entry.

WHEN expression

Updates the field only when expression has a value of TRUE. The expression is a field name, variable name, or expression whose value is logical.

TEXT

Defines a group of character fields or variables (including array elements) to use automatic word wrap. The TEXT option works only with character fields that are ABL default FILL-IN widgets (not specified with the FILL-IN NATIVE option). When you insert data in the middle of a TEXT field, the AVM wraps data that follows into the next TEXT field, if necessary. If you delete data from the middle of a TEXT field, the AVM wraps data that follows to the empty area. If you enter more characters than the format for the field allows, the AVM discards the extra characters. The character fields formats must be in the x(n) format. A blank in the first column of a line marks the beginning of a paragraph. Lines within a paragraph are treated as a group and will not wrap into other paragraphs.

The following table lists the keys you can use within a TEXT field and their actions.

Key actions in a TEXT() field
Key Action
APPEND-LINE Combines the line the cursor is in with the next line.
BACK-TAB Moves the cursor to the previous TEXT field.
BREAK-LINE Breaks the current line into two lines beginning with the character the cursor is in.
BACKSPACE Moves the cursor one position to the left and deletes the character at that position. If the cursor is at the beginning of a line, BACKSPACE moves the cursor to the end of the previous line.
CLEAR Clears the current field and all fields in the TEXT group that follow.
DELETE-LINE Deletes the line the cursor is in.
NEW-LINE Inserts a blank line below the line the cursor is in.
RECALL Clears fields in the TEXT group and returns initial data values for the group.
RETURN In overstrike mode, moves to the next field in the TEXT group on the screen. In insert mode, the line breaks at the cursor and the cursor is positioned at the beginning of the new line.
TAB Moves to the field after the TEXT group on the screen. If there is no other field, the cursor moves to the beginning of the TEXT group.

In this procedure, the s-com field is a TEXT field. Run the procedure and enter text in the field to see how the TEXT option works:

r-text.p

DEFINE VARIABLE s-com AS CHARACTER NO-UNDO FORMAT "x(40)" EXTENT 5.

FORM 
  "Shipped   :" order.ship-date AT 13 SKIP
  "Misc Info :" order.instructions AT 13 SKIP(1)
  "Order Comments :" s-com AT 1
  WITH FRAME o-com CENTERED NO-LABELS TITLE "Shipping Information".

FOR EACH Customer NO-LOCK, EACH Order OF Customer:
  DISPLAY Customer.CustNum Customer.Name Order.OrderNum Order.OrderDate
    Order.PromiseDate WITH FRAME order-hdr CENTERED.
  UPDATE Order.ShipDate Order.Instructions TEXT(s-com) WITH FRAME o-com.
  s-com = "".
END.
field = expression

Indicates that the value of field is determined by evaluating the expression rather than having it entered on the screen or from a file. In effect, an assignment statement is embedded in the UPDATE statement.

constant AT n

Represents a constant value that you want to display in the frame. The n is the column in which you want to start the display.

constant TO n

Represents a constant value that you want to display in the frame. The n is the column in which you want to end the display.

^

Tells the AVM to ignore an input field when input is being read from a file. Also, the following statement reads a line from an input file and ignore that line:

UPDATE^
SPACE [ ( n ) ]

Identifies the number (n) of blank spaces to insert after the expression displays. The n can be 0. If the number of spaces you specify is more than the spaces left on the current line of the frame, the AVM starts a new line and discards any extra spaces. If you do not use this option or do not use n, the AVM inserts one space between items in the frame.

SKIP [ ( n ) ]

Identifies the number (n) of blank lines to insert after the expression is displayed. The n can be 0. If you do not use this option, the AVM does not skip a line between expressions unless they do not fit on one line. If you use the SKIP option, but do not specify n or if n is 0, the AVM starts a new line unless it is already at the beginning of a new line.

GO-ON ( keylabel . . . )

Tells the AVM to take the GO action when the user presses any of the keys listed. You list keys in addition to keys that perform the GO action by default or because of ON statements. For example, if you want the AVM to execute the GO action when the user presses F1, use the statement GO-ON(F1). If you list more than one key, separate them with spaces, not commas.

Note that the GO-ON option is valid if you specify a list of fields in the UPDATE statement, but is invalid if you specify a record.

frame-phrase

Specifies the layout and processing properties of a frame. For more information on frame-phrase, see the Frame phrase reference entry.

editing-phrase

Supported only for backward compatibility.

Identifies processing to take place as each keystroke is entered. This is the syntax for editing-phrase:

[ LABEL : ] EDITING : statement ... END

For more information on editing-phrase, see the EDITING phrase reference entry.

NO-ERROR

Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

To check for errors after a statement that uses the NO-ERROR option:

  • Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.
  • Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.
  • Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.

Some other important usage notes on the NO-ERROR option:

  • NO-ERROR does not suppress errors that raise the STOP or QUIT condition.
  • A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, ON ERROR phrase, or UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.
  • When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.
  • If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.
record

Specifies the name of a record buffer. All of the fields in the record are processed as if you updated each of them individually.

To update a record in a table defined for multiple databases, you must qualify the record's table name with the database name. See the Record phrase reference entry for more information.

EXCEPT field

Affects all fields except those fields listed in the EXCEPT phrase; they are omitted from the update list.

Examples

The following procedure lets you update the Name, Address, City, State, and Country for each Customer record in the database:

r-updat.p

FOR EACH Customer:
  UPDATE Customer.Name Customer.Address Customer.City Customer.State
    Customer.Country.
END.

The r-updat2.p procedure reads each Customer record and lets you update the Name and CreditLimit fields. The VALIDATE option on the first UPDATE statement ensures that you enter a CreditLimit value that is less than 500000. The HELP option displays a message to that effect.

r-updat2.p

FOR EACH Customer:
  UPDATE Customer.Name
    Customer.CreditLimit VALIDATE(Customer.CreditLimit < 500000, "Too high")
    HELP "Enter CreditLimit < 500000".

  FOR EACH Order OF Customer:
    DISPLAY Order.OrderNum.
    UPDATE Order.PromiseDate Order.ShipDate VALIDATE(Order.ShipDate > TODAY,
      "Ship date must be later than today").
  END.
END.

The second FOR EACH block reads every Order belonging to the Customer, displays the OrderNum field, and lets you update the PromiseDate and ShipDate fields. The VALIDATE option ensures that you enter a ship date value that is after today's date.

This procedure requests a Customer number and then lets you update information for that Customer record. The frame phrase WITH 1 COLUMN 1 DOWN tells the AVM to display the fields in a single column on the screen (rather than in a row across the screen) and to display only one Customer record on the screen at a time.

r-updat3.p

REPEAT:
  PROMPT-FOR Customer.CustNum.
  FIND Customer USING Customer.CustNum.
  UPDATE Customer.Name Customer.Address Customer.City Customer.State
    Customer.Country WITH 1 COLUMN 1 DOWN.
END.

Notes

See also

ASSIGN statement, DISPLAY statement, EDITING phrase, Format phrase, Frame phrase, PROMPT-FOR statement