$ude ("copy")

Copies one or more entity occurrences from a source database or XML file to another.

$ude("copy","misc", Source, Target {, OptionList} )

Example: vResult = $ude("copy", "misc", "myexportfile.xml", "def:")

Caution: Do not use $ude ("copy") to export and import Repository definitions. This can cause corruption of the Uniface Repository. Instead, use the $ude ("export") and $ude ("import") functions.

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.

$ude returns the number of records where an attempt was made to process them. This may differ from what is expected.

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.

Errors from -1 through -15 do not stop $ude processing, 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 data, the number of input and output records processed, and messages, warnings, and errors encountered during processing.

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 Uniface component types.

Description

The $ude ("copy") function copies one or more entity occurrences from a source database or file to another.

If the data source is a database, you can specify which entities and occurrences to copy using the where option. Make sure you compile the modeled entities to be exported. This is required to ensure entity descriptors are generated as .edc files. If entity descriptors are missing, the copy action will fail with message 

8066 - Copy failed: Open error on input file/table Source

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 $ude ("copy") to export and import Repository definitions. This can cause corruption of the Uniface Repository. Instead, use the $ude ("export") and $ude ("import") functions. For more information, see Export and Import Facilities.

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.

Converting Data

The following instructions convert data via the default path from the default Repository to an XML file and to an XML file in a zip archive.

vResult = $ude("copy", "misc", "def:myent.mymodel", "myexportfile.xml")
vResult2 = $ude("copy", "misc", "def:myent.mymodel", "myzip.zip:myexportfile.xml")

The following instruction converts the contents of an XML file to the database via the default path:

$result = $ude("copy", "misc", "myexportfile.xml", "def:")

Related Topics