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.

The OptionList enables you to influence how the operation works. For example you can specify a map file, or select occurrences that have specific field values when converting data.

The OptionList is an associative list containing at least one option and value. Use Gold ; when specifying multiple options.

Options
Option Description
append=True | False Append the data to an existing XML file. Only applicable if Target is XML file.

Note: It is not possible to append data to an XML file that was exported (rather than copied) from the Uniface Repository.
keepopen=True | False Keep the file open in preparation for appending more data.

By default, the file is flushed and closed each time. However, to improve performance in cases when appending to a file, use this option to keep the file open.

If True, you must explicitly flush and close the file using flush or lflush.
sort=True | False Copy the output in primary key order. If True, the sort order is also affected by the database collation setting of the DBMS, which determines, for example, how special characters such as underscore (_) are sorted.

If False, depending on the database used, the order in the XML file can differ in repeated exports, even if nothing has changed.

map=MapFile | #{Entity | TargetEntity=SourceEntity} Use mapping functionality to determine how data is copied from existing entity and field definitions to new modeled entities and fields.
  • MapFile—ASCII file containing mapping between source and target entity and field definitions. For more information, see Mapping Files.
  • #—use Target Repository definitions to map all entities
  • #Entity—use Target Repository definitions to map the specified entity
  • #TargetEntity=SourceEntity—use Target Repository definitions to map a source entity to a target entity
where=SelectClause Copy selected occurrences. The SelectClause has the following syntax:

Field 1OperatorObjectSpec 1{;Field nOperatorObjectSpecn} {"}

  • Field—name of a field in the source entity.
  • Operator—logical operator preceded by GOLD, for example GOLD = ( = ) or GOLD > GOLD = ( >= ).
  • ObjectSpec—string specifying the retrieve profile for objects to be copied. Use the subfield separator GOLD ! GOLD ; ( !; ) to specify multiple conditions.
tran=TranslationTable Use the specified database translation table for converting the data.

A database translation table is a keyboard translation table that is used to convert character strings during database input or output.

library=LibraryName Library in which the TranslationTable is located.
supersede=True | False Indicate whether to overwrite existing occurrences having matching primary keys in the target DBMS.
  • True—overwrite occurrences. Default.
  • False—keep original data.
printinterval=Number Frequency with which a message is displayed, expressed as a number of occurrences.
commitinterval=Number Frequency with which data is stored in the database, expressed as the number of occurrences.

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.

Items are omitted if their value is zero or an empty string.

Items Returned in $procreturncontext
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"
History
Version Change
9.1.01 Introduced

Related Topics