Action Statement
Copy values to/from a variable, the clipboard, a structure, or a table row or cell.
copy
VALUE1 [VALUE2]...
to
{ clipboard
| VAR
| VAR[N1...Nn]
| STRUCT_2
| row ROWNUM of TABLE_NAME
| cell column COL_ID of row ROWNUM of TABLE_NAME
| cell COL_ID, ROWNUM of TABLE_NAME }
# OR #
copy
{ STRUCT_1|row ROWNUM of TABLE_NAME }
to
{ STRUCT_2
| row ROWNUM of TABLE_NAME
| cell column COL_ID of row ROWNUM of TABLE_NAME
| cell COL_ID, ROWNUM of TABLE_NAME }
VALUE1
VALUE2
Any values.
clipboard
Copy VALUEn to the Windows clipboard. Do not use with structures or table rows.
VAR
The identifier for a variable.
N1...Nn
Subscripts of an array.
STRUCT_n
The identifier for a previously declared structure variable.
ROWNUM
The number of a row.
TABLE_NAME
The identifier for a table.
COL_ID
The identifier (name or number) of a column.
Description
Use this statement to perform any of the following functions:
Assign one or more values to a variable, the clipboard, or a table cell, replacing any existing contents of the variable, the clipboard, or table cell.
Copy a string to a table row (using column delimiters).
Copy a structure variable to another structure variable.
Copy a table row to another row in the same or a different table.
Copy a row from a table to a structure variable or a structure variable to a row in a table.
The existing value of the specified destination is replaced with the new value.
There is no limitation on the source or type of values that you can copy to a variable; for example, you can copy values from expressions, variables, constants, literals, textual regions, built-in functions, and keyboard or application input. If you specify a value of a different type, ESL will try to convert the value to the expected type. (See "Type Conversions.") See "Data Types When Copying Between Structures" for information on the use of types when copying between structures.
Note that when you copy more than one value, the values are converted to strings and concatenated.
If you specify to clipboard after VALUEn, any textual data that previously existed in the clipboard is entirely replaced by the value of VALUEn. In this context, clipboard is not a built-in function, since it represents the target of a string copy operation and no string value is returned. You cannot append data to the clipboard.
The parent of a table specified in this statement may not be temporary and invisible or the statement will be ignored.
If the program is compiled with External Strings, then any string literals used in this statement will be externalized.
Copying to a Cell
A cell is defined as the intersection of a row and a column. There are two ways to refer to a cell:
cell column COL_ID of row ROWNUM of TABLE_NAME
cell COL_ID, ROWNUM of TABLE_NAME
You can use a cell reference as either the source or destination of a copy. (This is the same as using a variable in a copy statement.)
Copying a String to a Row
You can use a row reference as the destination of a copy with a string that is a series of values. When copying from a string to a row, a column delimiter string will cause the copy to continue at the next column. If there are more columns in the row than in the string, the other columns will not be modified. If there are more columns in the string than in the row, the excess are ignored.
If ESL encounters a row delimiter string, it stops the copy at that point. At least the first column will be modified. To copy a string to more than one row, your program must loop through the string, one row at a time. Use either extract or EslParseRow( ) for this. See the table Definition for more information about column and row delimiters.
Copying to and from Tables and Structures
When copying values from one structure or table row to another structure or table row, the existing value of each field within STRUCT_2 or of each column in the destination row is replaced with the value from the corresponding field within STRUCT_1 or from the corresponding column from the source row.
When copying to a table row, if the number of columns in the destination row does not match the number of data elements in the structure or the number of columns in the source row, excess values from the source are ignored and excess columns in the destination are left unchanged.
ESL accesses data values from a structure variable according to the structure definition and copies each field sequentially. If a field is an array, each element in the array is copied to the next column in the row before proceeding to the next field in the structure. All elements of the array will be copied, regardless of whether or not all of the array has been used by your ESL program. If an element in the array is a structure or the field is itself a structure, each field in the structure will be copied before proceeding to the next element in the array or the next field in the structure.
In a similar way, each data column from a table row will be accessed sequentially and copied to the next field in the structure, following the order specified in the preceding paragraph.
When copying from one row to another in the same table, ESL copies the whole row and no conversions are required.
Data Types When Copying Between Structures
When copying (part of) one structure to another, the data types of the structures do not need to match. However, the data types of the source and destination fields must match. Furthermore, as long as the field types match, you can copy between structures that were defined with dissimilar using specifications.
If you want to copy from a structure variable to a row, or from a row to a structure variable, there is no requirement that there be type correspondence between the column type in the row and the data field in the structure. The data copied will be converted to the type of the destination. The fields in a structure variable may be integers, floats, strings, a structure type, or an array of any of these types. The types allowed for columns in a row from a table are integer, float, string, and boolean.
Example
response to Widget1
copy Widgets to Inventory
action MoreVals is
copy (A * 5 - B) to Calc_IV
integer variable IntArray_IV[5]
action NewValue is
copy 1 2 3 4 5 to IntArray_IV[3]
if (IntArray_IV[3] != 12345) then
send "Error occurred \n" to errorlog
end if
string FirstName_SV is "Dixon"
LastName_SV is "Hill"
FullName_SV
copy LastName_SV ", " FirstName_SV to FullName_SV
# This example copies between structures.
# Note that the copy succeeds even though the fields in the two
# structures are defined with different using clauses.
Structure_1 is
integer int_IV
float flt_FV
end structure
Structure_2 is
integer int2_IV using integer size 2
float flt2_FV using float size 4
end structure
copy Structure_1 to Structure_2
See Also
append Action Statement
Array Definition and Reference
table Object Definition
use "indcopy" Action Statement
variable Definition
