Assigns the value of an expression to a database field or variable.
Syntax
field = expression [ NO-ERROR ]
|
-
field
- The name of an ABL data element to which you want to assign
the value of expression and that is defined with
a data type that is compatible with the data type of expression.
This data element can include a:
- Database or temp-table field
- Variable scoped to the current procedure, user-defined function,
or method of a class or an accessible class-based variable data
member, including a subscripted or unsubscripted array variable
- Parameter defined for the current procedure, user-defined function, or
method of a class, including a subscripted or unsubscripted array parameter
- Writable class-based or COM property, including a subscripted
or unsubscripted array property
- Writable handle attribute (such as PRIVATE-DATA)
- Writable system handle (such as CURRENT-WINDOW)
- ABL syntax that specifies a keyword-driven assignment statement (such
as the PROPATH statement, SUBSTRING statement, or similar statement)
-
expression
- An expression with a data type that is consistent with the data
type of field. For more information, see the Expression 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.
For the
Assignment (=) statement with NO-ERROR, if ERROR is raised, then the leftside of the
assignment will be unchanged.
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.
Example
This
procedure resets all the monthly quota values to 2500 in all salesrep records.
If you want to set values for individual array elements, you can
do so by making an explicit assignment using the assignment statement
and a specific array reference, such as month-quota[1] or month-quota[i].
r-asgmnt.p
DEFINE VARIABLE ctr AS INTEGER NO-UNDO.
FOR EACH SalesRep:
DO ctr = 1 TO 12:
SalesRep.MonthQuota[ctr] = 2500.
END.
END.
|
Notes
- If field is
an integer and expression is a decimal, the AVM
rounds the value of the expression before assigning it. If field is
a decimal and expression is a decimal, the AVM rounds
the value of the expression to the number of decimal places defined
for the field in the Data Dictionary, or defined or implied for
a variable or temp-table field.
- If field is an ABL array type (defined with EXTENT)
and expression is not an array, and you do not
identify a particular array element, the AVM stores expression in
each element of the array. If you identify a particular element,
the AVM stores expression in the specified array
element.
- If both field and expression are
ABL array types, the AVM copies the data for all expression array
elements into the corresponding elements of the field array.
This is known as a deep copy.
- An indeterminate array is one where the size of
the EXTENT is not yet fixed. A determinate array is
one where the EXTENT size is fixed. When deep copying one array
to another, the following rules apply:
- If both the array
on the left-hand side and the right-hand side of the equation are
determinate arrays, the EXTENT size must match or the AVM raises
an error.
- You cannot assign an indeterminate array to a determinate array.
- You can assign any array to an indeterminate array, but you cannot
assign a scalar value to an indeterminate array.
- ABL allows you to assign ABL arrays and .NET array objects
to each other. How an array assignment works between ABL and .NET arrays depends
upon the array type of field (the target of the
assignment) and the array type of expression (the
source for the assignment). For more information, see the Data types reference
entry.
- If an assignment of one array to another encounters an error after some, but not all of
the source array's elements are retrieved, none of the target's elements are updated.
- If expression is an ABL handle-based object (for
example, a temp-table, ProDataSet, widget, or socket), field must
be a temp-table field, variable, or other ABL data element defined
as a compatible handle. In this case, the AVM assigns only the handle
of the ABL handle-based object to field, not
the entire object and its contents.
- If you assign a value to a database field, any ASSIGN trigger
associated with that field executes at the end of the assignment
statement (after any index changes are made). If the trigger raises
ERROR, the assignment fails and the database changes are undone.
- You can embed an assignment in a SET or UPDATE statement.
- For multiple assignments, use the ASSIGN statement. This is
more efficient than multiple assignment statements.
- If field is a handle, the expression on the
right-hand-side must also evaluate to a handle value that is specified using an
appropriate reference to a handle-based object handle. For more information on object
handle references, see the Handle Attributes and Methods Reference.
- You can assign DATE, DATETIME, and DATETIME-TZ data. When the data type
expression on the left side of the assignment statement contains more information than the
data type expression on the right side provides (for example, datetime-tz = date where a DATETIME-TZ value contains more information than a
DATE value), the time value defaults to midnight and the time zone is calculated using
SESSION:TIMEZONE when that attribute is in use. If the attribute is not in use, the value
defaults to the session's timezone. When the data type expression on the left side of the
assignment statement contains less information than the data type expression on the right
side provides (for example, date = datetime-tz where a
DATE value contains less information than a DATETIME-TZ value), the AVM converts the
DATETIME-TZ value to the local date and time of the session, then drops the time and time
zone.
Note: For releases 11.6.0 and earlier, assignments such as datetime-tz = date used the system's timezone, regardless
of whether or not SESSION:TIMEZONE was set. To revert to this earlier behavior, use the
Use SESSION:TIMEZONE (-useSessionTZ) startup
parameter. See OpenEdge Deployment: Startup Command and Parameter
Reference for more information.
- Starting with Version 9.1, you can assign RAW values to MEMPTR variables
and MEMPTR values to RAW variables. If the target variable is a
RAW data type, the AVM re-sizes the target variable, if necessary,
so that after the assignment is the same size as the source. Note
that after the assignment (whether RAW = MEMPTR or MEMPTR = RAW),
the target variable has a copy of the memory associated with the
source—each variable has an independent copy of the data.
- You can assign large object data from one BLOB or MEMPTR to another,
and from one CLOB, LONGCHAR, or CHARACTER to another. You cannot
assign large object data between BLOBs and CLOBs or MEMPTRs and
LONGCHARs. You can accomplish this, indirectly, by using the COPY-LOB
statement. For more information, see the COPY-LOB statement reference
entry.
Note: When assigning BLOB or CLOB fields, the
field must appear by itself on either the right-hand or the left-hand
side of the assignment.
The following table lists the default
character conversions that the AVM performs when assigning CLOB,
LONGCHAR, and CHARACTER data between a source and target object.
References to CLOBCP and CLOBDB represent CLOB data in either the
CLOB's defined code page or the database's defined code page, respectively.
References to the "fixed code page" represent the code page of a
target LONGCHAR variable set using the FIX-CODEPAGE statement.
Default assignment character conversionsWhen the target object (on the left) is a .
. . |
And the source object (on the right) is a .
. . |
The AVM converts the data in the source object
to . . . |
LONGCHAR |
CLOBDB |
-cpinternal or the fixed code
page |
LONGCHAR |
CLOBCP |
The CLOB's defined code page or the fixed code
page |
LONGCHAR |
CHARACTER |
-cpinternal or the fixed code
page |
CLOBDB |
CHARACTER |
The database's defined code page |
CLOBDB |
LONGCHAR |
The database's defined code page |
CLOBCP |
CHARACTER |
The CLOB's defined code page |
CLOBCP |
LONGCHAR |
The CLOB's defined code page |
CHARACTER |
CLOBDB |
-cpinternal code page |
CHARACTER |
CLOBCP |
-cpinternal code page |
CHARACTER |
LONGCHAR |
-cpinternal code page |
- When you assign the Unknown value (?) to a BLOB or
CLOB field, the AVM deletes any associated object data.
- If expression is a solitary invocation of the NEW function (classes), this statement represents and conforms to the rules
specified for the NEW statement.
- If expression evaluates to an object reference value,
field must also be a data element defined as a class or interface
type that is type-compatible with expression according to the rules for
assigning references to class instances defined for the NEW statement. For more
information, see the NEW statement reference entry. Thus, you can
assign one object reference variable to another object reference variable when the
destination object reference (on the left side of the assignment) is defined for the same
class, a super class, or an interface of the object reference being assigned (on the right
side of the assignment). The destination object reference retains its defined class or
interface type for compilation. However, following its assignment, at run time, the
destination represents the sublcass of field (or the class that
implements the interface specified by field) that is defined by
expression.
If field has a class type that is a
subclass lower in the class hierarchy than the class type represented by
expression, you can cast expression to the type
of field using the CAST function, but only if
expression is a super class that actually contains an instance of
the field class type. If field has a class type
that implements an interface type represented by expression, you can
similarly cast expression using the CAST function, but only if
expression actually contains an instance of the
field class type. For more information about the CAST function, see
the CAST function reference
entry.
After the assignment, field contains a copy of the
object reference value returned by expression, which points to the
same object instance, not a copy of the object referenced by
expression.
- Although you can assign an object reference to a temp-table field defined as a Progress.Lang.Object class type, you cannot assign an object
reference to a field in a database table. For more information, see OpenEdge
Development: Object-oriented Programming.