Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## 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:

> - DISPLAY — Moves the values of fields or variables into the screen buffer and displays them.

> - PROMPT-FOR — Prompts the user for data and puts that data into the screen buffer.

> - ASSIGN — Moves data from the screen buffer to the record buffer.

> 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, Progress 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 Progress default FILL-IN widgets (not specified with the FILL-IN NATIVE option). When you insert data in the middle of a TEXT field, Progress wraps data that follows into the next TEXT field, if necessary. If you delete data from the middle of a TEXT field, Progress wraps data that follows to the empty area. If you enter more characters than the format for the field allows, Progress 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.

> Table 50 lists the keys you can use within a TEXT field and their actions.

> Table 50: 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 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, EACH order OF customer:
>         DISPLAY cust.cust-num cust.name order.order-num order.order-date
>                order.promise-date WITH FRAME order-hdr CENTERED.
>         UPDATE ship-date 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 Progress 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, Progress starts a new line and discards any extra spaces. If you do not use this option or do not use `n`, Progress 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, Progress 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, Progress starts a new line unless it is already at the beginning of a new line.

> `GO-ON ( `keylabel` . . . )`

> Tells Progress 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 Progress 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`

> Specifies that any errors that occur in the attempt to update a record are suppressed. After the UPDATE statement completes, you can check the ERROR-STATUS system handle for information on any errors that occurred.

> ``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 name address city state country.
>     END.

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

> r-updat2.p
>     FOR EACH customer:
>       UPDATE customer.name
>         credit-limit VALIDATE(credit-limit < 500000, "Too high")
>           HELP "Enter credit-limit < 500000".
>         FOR EACH order OF customer:
>           DISPLAY order-num.
>           UPDATE promise-date ship-date VALIDATE(ship-date > today,
>               "Ship date must be later than today").
>         END.
>     END.

> The second FOR EACH block reads every order belonging to the customer, displays the order-num field, and lets you update the promise-date and ship-date 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 Progress 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.cust-num.
>       FIND customer USING cust-num.
>       UPDATE name address city customer.state country WITH 1 COLUMN 1 DOWN.
>     END.

> #### Notes

> - If any `field` is a field in a database record, the UPDATE statement upgrades the record lock condition to EXCLUSIVE-LOCK before updating the record.

> - If any `field` is part of a record retrieved with a field list, the UPDATE statement rereads the complete record before updating it. If any `field` is not part of the field list (or related fields) fetched with the record, or if `record` includes such unfetched fields, Progress raises the ERROR condition before the UPDATE statement accepts input. This is because the UPDATE attempts to display the fields before it rereads the record.

> - If an error occurs during UPDATE statement input (for example, the user enters a duplicate index value for a unique index), Progress retries the data entry part of the statement and does not do the error processing associated with the block that contains the statement.

> - The UPDATE statement is not equivalent to a combination of the DISPLAY and SET statements.

>     REPEAT:
>       PROMPT-FOR customer.cust-num.
>       FIND customer USING cust-num.
>       UPDATE credit-limit.
>     END.

> The previous procedure is approximately equivalent to the following procedure:

>     REPEAT:
>       PROMPT-FOR customer.cust-num.
>       FIND customer USING cust-num.
>       DISPLAY credit-limit.
>       DO ON ERROR UNDO, RETRY:
>         SET credit-limit.
>       END.
>     END.

> If an error occurs during an UPDATE statement, the statement is retried until the error is corrected. If this happens during a SET statement, an entire block is retried.

> - If you receive input from a device other than the terminal, and the number of characters read by the UPDATE statement for a particular field or variable exceeds the display format for that field or variable, Progress returns an error. However, if you are setting a logical field that has a y/n format and the data file contains a value of YES or NO, Progress converts that value to “y” or “n”.

> - If you use a single qualified identifier with the UPDATE statement, the compiler first interprets the reference as `dbname`.`tablename`. If the compiler cannot resolve the reference as `dbname.tablename`, it tries to resolve it as `tablename.fieldname`.

> - When updating fields, you must use table names that are different from field names to avoid ambiguous references. See the Record phrase reference entry for more information.

> - The UPDATE statement causes ASSIGN and WRITE events to occur and all related database ASSIGN and WRITE triggers to execute. The ASSIGN triggers execute before the WRITE triggers and after the field is actually updated. The WRITE triggers only execute if the ASSIGN triggers do not return an error. If an ASSIGN trigger fails, the database update is undone. This means that all database changes are backed out. If the UPDATE statement occurs within a transaction, any changes to variables, worktable fields, and temporary table fields are also undone unless the variable or field is defined with the NO-UNDO option. Likewise, if a WRITE trigger fails, the UPDATE statement is undone. See OpenEdge Development: Progress 4GL Handbook for more information on database triggers.

> - In Progress Version 7 and above, when you execute UPDATE with a specific or implied GO-ON(`keylabel`) from a called program, Progress generates an error message (4123). This is due to an incompatibility in focus. The workaround is to add a VIEW FRAME statement after the call to the subprocedure such that the VIEW FRAME is the first statement executed on return from the called procedure.

> #### See also

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

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095