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

Parameters
Parameter Data Type Description
Source String Source of data to be copied. One of:
  • Database path and entity: Path:Entity.Model

    Path can specify a connector path (such as XML, DEF, ORA), or a user-defined path (such as $ORA or $MyData).

    Either or both of Entity and Model can contain wildcards, for example DEF:ENT*.MOD*.

  • XML file: {ZipArchive:}Filename

    For example, myxmlfile.xml or ziparchive.zip:myxmlfile.xml

    When a ZipArchive is specified, it is created in the Zip64 format.

  • Uniface 8 TRX file: trx:Filename
Target String Destination database path or XML file.
  • Database objects: Path:

    Entity and/or model names following the path are ignored.

  • XML file: xml: or {ZipArchive:}Filename
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

Values returned by $ude and entitycopy
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.

Values commonly returned by $procerror after entitycopy
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.

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"
History
Version Change
9.1.01 Introduced

Related Topics