entitycopy
Copy one or more entity occurrences from a source database or XML file to another.
entitycopy Source,
Target {,
Options}
Example: entitycopy "def:myent.mymodel",
"xml:ABC.xml", "append=T"
Parameters
Parameter | Data Type | Description |
---|---|---|
Source | String | Source of data to be copied. One of:
|
Target | String | Destination database path or XML file.
|
OptionList | String | Associative list containing one or more options that are appropriate to the operation or the ObjectType. |
Arguments can also be a field, variable, or function that evaluates to a string or list.
Return Values
Value | Description |
---|---|
>=0 |
Success. Number of records where an attempt was made to process them. Detailed information is returned in $procReturnContext. |
<0 |
An error occurred. $procerror contains the exact error and $procerrorcontext provides the details. |
8066
|
8066- Copy failed: Open error on input
file/table. This error can occur when no entity descriptors cannot be found. |
Value | Error constant | Meaning |
---|---|---|
-1 through
-25 |
Various. See $procerror | Database I/O and network communication errors. |
-9
|
UIOSERR_LOGON_ERROR
|
DBMS logon error; for example, the maximum number of DBMS logons has already been reached. |
-1107
|
UPROCERR_PATH
|
The path name is not correct or the path does not exist, for example, no assignment is found for the path. |
Errors from -1
through
-15
do not stop the entitycopy process, with the exception of
error -9 <UIOSERR_LOGON_ERROR>
. The number of ignored errors is returned in
$procreturncontext, along with additional information, such as the Uniface
release number of the Source, and the number of input and output records
processed.
Items are omitted if their value is zero or an empty string.
Item | Description |
---|---|
Context = Context
|
Context of the information. For example
UDE Copy for $ude ("copy") or EntityCopy for
entitycopy. |
Error = Number
|
Error number if process failed on error |
InputRecords = Number
|
Records to be copied. |
OutputRecords = Number
|
Records written. |
SkippedRecords = Number
|
Records not written due to map file entity
mapping to <void> |
WriteErrorsContinues = Number
|
Write errors encountered that did not stop the import action. |
InputDescriptors=Number
|
Descriptors to be imported. The same descriptor can occur more than once. |
OutputDescriptors = Number
|
Signatures actually output. This can be
less than the number of InputDescriptors if void mappings are encountered. |
SkippedDescriptors
|
Entities mapped to
<void> |
InputTrxFiles = Number
|
TRX files to copy, if a wildcard was specified. |
InputXmlFiles = Number
|
XML files to copy, if a wildcard was specified. |
DETAILS = String
|
Messages, warnings, and errors encountered during processing, structured as a list. |
Use
Allowed in all component types.
Description
The entitycopy function copies one or more entity occurrences from a source database or file to another.
When copying data into a database, Uniface does not know anything about the contents of the source data and performs a physical conversion. The copy process does not consider referential integrity constraints, so it is possible to copy the data from one entity without its related entities. As a developer, you need to ensure that the correct data is copied to ensure referential integrity.
Caution: Do not use entitycopy to export and import Repository definitions. This can cause corruption of the Uniface Repository. Use the export and import functionality instead. For more information, see Export and Import Facilities.
If the data source is a database, you can specify which entities and occurrences to copy using the where option.
If the data target is an XML file, you can append data to it using the append option. However, if an XML file was originally created with Uniface's export functionality, it is not possible to append data to it using the copy functionality.
Converting Data Using the Map Option
You can use mapping functionality to specify how data is copied from existing entity and field definitions to new model definitions.
By default, entities are copied using descriptors in the Source to map entities to the Target, but you can override this and provide your own mapping rules.
If you specify the map=#
options,
the entity descriptors in the Target are used instead of those in the
Source.
Alternatively, you can also specify your own mappings in a map file. For more information, see Mapping Files.
Exchanging Data
The following examples show how entitycopy can be used to copy data to an XML file and then copy it into a database.
;copy data from database entitycopy "def:myent.mymodel", "xml:myexportfile.xml" entitycopy "def:myent.mymodel", "xml:myzip.zip:myexportfile.xml" ;Copy data to database entitycopy "xml:myexportfile.xml", "def:myent.mymodel"
Error Handling
entitycopy is a batch
processing instruction, so it is possible for errors to occur either in executing
entitycopy itself, or while processing an operation that it invokes. For
example, if you specify a source file that does not exist, $status returns
-4
and $procreturncontext returns:
Context=EntityCopy·; Release=9.5·; DETAILS= DETAILS= ID=8026·!·!·!·;MESSAGE=8026 - Input file mycart.xml does not exist.·!·!·; ID=8080·!·!·!·;MESSAGE=8080 - Nothing copied.
However, if you use entitycopy to copy from an XML file to a database, and $status contains 0, this indicates the entitycopy executed successfully, but no records were actually imported. $procreturncontext contains more information.
For example, after copying a data file, $status contains 0 and $procreturncontext returns the following (formatted for readability):
Context=EntityCopy·; InputRecords=9·; WriteErrorsContinued=9·; InputDescriptors=5·; InputXmlFiles=1·; Release=9.5·; DETAILS= Operation=entitycopy·!·!·; From=mycars.xml·!·!·; To=·!·!·; InputRecords=0·!·!·; OutputRecords=0·!·!·; DETAILS=·!·; Operation=entitycopy·!·!·; From=mycars.xml·!·!·; To=·!·!·; InputRecords=1·!·!·; OutputRecords=0·!·!·; DETAILS= ID=8069·!·!·!·!·; MESSAGE=8069 - Copy failed: Write error on file/table 'DEF:UCSCH.DICT'.·!·; Operation=entitycopy·!·!·; From=mycars.xml·!·!·; To=·!·!·; InputRecords=0·!·!·; OutputRecords=0·!·!·; DETAILS= ID=8078·!·!·!·!·; MESSAGE=8078 - Copy from 'mycars.xml' to 'DEF:UCSCH.DICT'.·!·; Operation=entitycopy·!·!·; From=mycars.xml·!·!·; To=·!·!·; InputRecords=0·!·!·; OutputRecords=0·!·!·; DETAILS= ID=8074·!·!·!·!·; MESSAGE=8074 - Copied from 'mycars.xml' to 'DEF:UCSCH.DICT' total records/rows 0.·!·; Operation=entitycopy·!·!·; From=mycars.xml·!·!·; To=·!·!·; InputRecords=1·!·!·; OutputRecords=0·!·!·; DETAILS= ID=8069·!·!·!·!·; MESSAGE=8069 - Copy failed: Write error on file/table 'DEF:UCTABLE.DICT'.·!·; ...
$procreturncontext indicates
that 9 non-fatal write errors were encountered (WriteErrorsContinued=9
) and the
DETAILS
topic provides additional information for each error. For actual I/O error
messages, you need to check the message frame or log files.
Specifying Multiple Conditions with where=
The following example uses the
where
option to retrieve all entities where the organization name (field ORGNAME)
starts with letters A through C, and the city (field CITY) is Detroit. The use of the GOLD subfield
separator (!;) in the where
option implies a logical
AND. The GOLD separators and operators are underlined.
entitycopy "def:ORG.ORGSMODEL", "xml:ABCOrgs.xml", %\ "printinterval=50 ;where=ORGNAME >=A&<=D!;CITY=Detroit"
Specifying Alternative Conditions with where
The following example uses the
where
option to retrieve all entities where the product code (field CODE) starts
with letters A through C, or the product category (field CATEGORY) is footwear. To specify a
logical OR between sub-fields in the where option, place the OR operator (GOLD |) immediately after
the subfield operator.
entityCopy "def:PRODUCT.PRODUCTS", "xml:myexportfile.xml", %\ "printinterval=50 ;where=CODE >=A &<=D !;CATEGORY|=footwear"
Version | Change |
---|---|
9.1.01 | Introduced |