====== Copy_Row subroutine ======


 
==== Description ====
 
Copies a row or a group of rows from one table to another.
 
==== Syntax ====
 
**Copy_Row**(//scrtablename//, //scrkeylist//, //desttablename//, //destkeylist//, //overwriteflag//, //lockflag, deleteSource//)
 
==== Parameters ====
 
The Copy_Row **sub**routine has the following parameters.

^Parameter^Description^^
|//scrtablename//|The name of the table that contains the row or rows to be copied.||
|//scrkeylist//|A key or list of keys to copy from //scrtablename// to //desttablename//. A one-to-one correspondence must exist between //scrkeylist// and //destkeylist//.\\ \\ Note:  If more than one rows are to be copied, separate the keys with field marks. See the Example 2 below.||
|//desttablename//|Specifies the name of the table into which the rows are copied. If null, then //scrtablename// is used.||
|//destkeylist//|A key or list of keys to copy from //scrtablename// to the keys specified in //destkeylist// in the //desttablename// table. A one-to-one correspondence must exist between //destkeylist// and //scrkeylist//. If null, then //scrkeylist// is used.||
|//overwriteflag//|Specifies whether or not rows copied to a new table overwrite an existing row. The default value is 0 (no overwrites).\\ \\ __Value__ __Description__\\ 0 - Prevents overwriting an existing row (default).\\ 1 - Only replace an existing row. If destination row does not exist, then skip this row.\\ 2 - Write this row, unconditionally. If the destination row exists, overwrite it.|
|//lockflag//|Specifies whether rows are locked during the copy process. The default is 0 (no locking).\\ \\ __Value__ __Description__\\ 0 - No locking during the copy process.\\ 1 - Lock the source & destination rows during the copy process.|
|deleteSource|Specifies whether the source rows are deleted during the copy process. The default is 0 (no deletion).\\ \\  __Value__ __Description__\\ 0 - The source rows are not deleted after copying.\\ 1 - The source rows are deleted after copying.|

Notes:Although the Copy_Row subroutine can be called from a BASIC+ program, it is preferable to use the [[read|Read]] and [[write|Write]] statements instead.\\ [[set_status|Set_Status]]/[[get_status|Get_Status]] Error handling should be used when programmatically executing the Copy_Row routine.|

 
==== See Also ====
 
[[copy_os_to_row|Copy_OS_To_Row]], [[copy_row_to_os|Copy_Row_To_OS]], [[delete_row|Delete_Row]], Copy Row dialog
 
==== Example ====
 
From the System Monitor:

This command line example shows how to copy the row 5*5 to the key 5*20 in the CAR_PARTS table, overwriting any existing destination row:

<code>
run Copy_Row "CAR_PARTS", "5*5", "", "5*20", "2"
</code>

Example 2  * Copying Multiple Rows from BASIC+ Program

<code>
* Copy rows with keys '1' and '2' from CUSTOMERS table to the CUSTOMERS_BACKUP table.

declare subroutine Copy_Row, Set_Status, FsMsg
declare function Get_Status

row_list = '1': @fm : '2'

Set_Status(0)

Copy_Row( "CUSTOMERS", row_list, "CUSTOMERS_BACKUP", row_list , 0, 0, 0 )

if Get_Status( errCodes ) then

   FsMsg( errCodes )

end

 
 
</code>