UNLOAD

Exports database tables to an ASCII format file which can be loaded into the target database using the LOAD utility

See Transferring Data with the Load and Unload Facility in the DP4 Developer's Manual for further information about this program.

Command Tail	Description
−ALL	Exports all tables
-APPEND	By default UNLOAD overwrites any existing file of the same name. This option has been added because a user wished to be able to concatenate the output from several runs of UNLOAD. This option is disallowed if the -xml option is selected.
−CONFIG name	Reads the list of tables to export from a configuration file. If this option is used it is possible to use a per-table condition to limit which records are exported.
-QUIET	Do not display the exported lines
−CSV	Causes UNLOAD to dump data in a different format from usual. It uses a format which the Micorosoft Internet Explorer Tabular Data Control can understand. You could use data in this format to indirectly access data from DP4 databases via web pages.
−FILE name	Exports the data to the named file. The default is the DB_NAME.TXT (or .XML if -xml option specified)
-QUIET	Do not display the exported lines
−TABLE name	Export data from the named table
−TABLES t1,t2,...	Export data from the table list given
−TABLES @filename	Take the table list from the contents of file filename. This must be specified after all the other command tails.
−XML	Causes UNLOAD to dump data in XML format. The data is dumped to a file with .XML extension, and an XML schema which describes the data is created with extension .XSD. .

UNLOAD using a configuration file

As with the -tables @filename option The -config filename option allows the list of tables to be exported to be specified in a file, but more importantly it allows a table to be exported selectively. When this option is used then a table is only exported if the configuration file contains a section for that table and the option unload=1 is specified. In this case the table is exported normally unless the mode=1 option is also specified, when a condition must also be specified, using the same syntax as is used for formulas by BROWSER, AUDITOR, and RECASTDB.

Below an example of a configuration file is given. This exports selected records from a table named CUSTOMER and all records from a table named EMPLOYEE.

[customer]
unload=1
mode=1
condition="cust_acc_nr>=10001  and cust_acc_nr <= 10005"
[employee]
unload=1

XML Export using UNLOAD

File Format

The root of the XML document is an element named DP4.unload which has a single attribute - the database name. The data for table tablename is contained in an element tablename-data in multiple tablename elements. Each tablename-data element appears once. If a table to be exported is empty then the tag appears as an empty tag.

Each field in the table appears as an attribute of the tablename element. An alternative would have been to use a separate element for each field, and make the field value either a value attribute of its element, or else text content. The format used has been chosen because it is relatively easy to generate an XML schema for it, and because it is far more compact than either of the other formats would be.

Multi-occurs are treated as separate fields. The attribute name for a field is generated as follows:

For a single occurrence field, the name is fieldname.rolename or just fieldname if the role is blank
For a multi-occurs field multiple fields name fieldname.rolename-1,fieldname.rolename-2 etc. , or fieldname-1, fieldname-2 etc. are generated.

If a field is NULL then the corresponding attribute is omitted from that record.

Note that DP4 currently has no facilities for importing these or any other XML files. XML files are much larger than traditional CSV style files and should only be used when absolutely necessary.

Configuration Options

There are a number of configuration options that can be used to modify the XML produced

The xml_encoding entry in the [win32] or [unix] sections of the DP4 configuration file are used to specify how the file is encoded. This setting defaults to windows-1252 and UNLOAD makes no attempt to discover a name by querying the operating system. Note that without this setting XML files would be rejected by the Microsoft XML parser if they contain accented characters. Note also that this setting does not alter how DP4 creates the file - it is up to you to ensure the setting matches the character set that you are actually using.
Names of elements and attributes generated by UNLOAD can be changed by specifying an entry in an [xml.xlat dbname] section. These sections are modelled on the [sql.xlat dbname] sections and work in the same way. For example suppose the first line of an address is normally exported as address.jobs-1, but you wish it to be exported as job_address_1. Then you simply add the line
address.jobs-1=jobs_address_1
to your DP4 Configuration file in the appropriate [xml.xlat dbname] section. The only exception to this is that whatever name you choose to replace a tablename element by, its enclosing element will use the same element name followed by -data.

Limitations

Conforming XML parsers will reject files containing characters that do not belong to the character set including most control characters. The only way DP4 could work around this would be to export data using Base64 binary encoding, which would defeat the whole object of XML. DP4 converts control characters to "entities", but this will not make an invalid character valid. Therefore if you have stored binary data in character fields, you will probably not be able to export those tables using XML format.

Schema File

The Schema file generated by UNLOAD does not fully describe the data for a field. For example no attempt is made to limit the length of character fields, or the valid range of numeric fields. We intend to enhance LIBMAKE or provide a new utility which generates a more complete XML Schema for a DP4 database.