<!-- Converted by db4-upgrade version 1.0 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dbconcat">
  
  <refmeta>
    <refentrytitle>DBCONCAT</refentrytitle>
    <manvolnum>nged</manvolnum>
    <refmiscinfo class="source">BRL-CAD</refmiscinfo>
    <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
  </refmeta>
  
  <refnamediv xml:id="name">
    <refname>dbconcat</refname>
    <refpurpose>
      Concatenates an existing BRL-CAD database to the
      database currently being edited.
    </refpurpose>
  </refnamediv>
  
  <!-- body begins here -->
  <refsynopsisdiv xml:id="synopsis">
    <cmdsynopsis sepchar=" ">
      <command>dbconcat</command>    
      <arg choice="opt" rep="norepeat"><replaceable>-t</replaceable></arg>   
      <arg choice="opt" rep="norepeat"><replaceable>-u</replaceable></arg>   
      <arg choice="opt" rep="norepeat"><replaceable>-c</replaceable></arg>   
      <arg choice="opt" rep="norepeat"><replaceable>-s|-p</replaceable></arg>
      <arg choice="req" rep="norepeat"><replaceable>database_file</replaceable></arg>
      <arg choice="opt" rep="norepeat"><replaceable>affix</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsection xml:id="description"><info><title>DESCRIPTION</title></info>
    
    <para>
      Concatenates an existing <emphasis>BRL-CAD</emphasis> database to the
      database currently being edited. If an <emphasis>affix</emphasis> is 
      supplied, then all objects from the <emphasis>database_file</emphasis> 
      will have the <emphasis>affix</emphasis> added to their
      names as a suffix (if the <emphasis>-s</emphasis> option is specified), or as a prefix
      (if the <emphasis>-p</emphasis> option is specified). The <emphasis>-p</emphasis> is the default.
      Note that each <emphasis>BRL-CAD</emphasis> object must have a unique 
      name, so care must be taken not to "dbconcat" a  database that has objects 
      with names the same as objects in the current database. 	The <command>dup</command> 
      command may be used to check for duplicate names. If the <command>dup</command> 
      command finds duplicate names, use the <emphasis>prefix</emphasis> option to both the 
      <command>dup</command> 	and <command>dbconcat</command> commands to find a 
      <emphasis>prefix</emphasis> that produces no duplicates.	If duplicate names 
      are encountered during the "dbconcat" process, computer-generated prefixes
      will be added to the object names coming from the <emphasis>database_file</emphasis> 
      (but member names appearing in combinations will not be modified, so this is a 
      dangerous practice and should be avoided). The <emphasis>-t</emphasis> option indicates that
      the title of the <emphasis>database_file</emphasis> should become the title of the currently
      edited database. The <emphasis>-u</emphasis> option indicates that the units of the
      <emphasis>database_file</emphasis> should become the units of the currently edited database. Similarly,
      the <emphasis>-c</emphasis> option indicates that the region color table of the currently edited database
      should be replaced with that of the <emphasis>database_file</emphasis>.
    </para>
  </refsection>
  
  <refsection xml:id="examples"><info><title>EXAMPLES</title></info>
    
    <para>
      This example shows the use of the <command>dbconcat</command> command to copy all objects in a particular
      database to the current database. It also shows how to add a particular prefix to every object copied.
    </para>
    <example><info><title>Copy objects in a specified database to the current one and add a prefix to all the copied objects.</title></info>
      
      <para><prompt>mged&gt;</prompt> <userinput>dbconcat model_two.g two_</userinput></para>
      <para>
	Copies all the objects in <emphasis>model_two.g</emphasis> to the current database,
	but prefixes the name of every object copied with the string <emphasis>two_</emphasis>.
      </para>
    </example>
    
    <para>
      Another example shows a usage to import the title, units, color table, and all the objects of a database file
      into the current database. This is particularly useful if the current database is empty or just created by mged.
    </para>
    <example><info><title>Copy an entire database, including title, units, and color table, to the current database without any affix</title></info>
          
      <para><prompt>mged&gt;</prompt> <userinput>dbconcat -t -u -c model_two.g</userinput></para>
      <para>
        Copies all the objects in <emphasis>model_two.g</emphasis> to the current database, including the title, units,
        and color table. No suffix or prefix is added to the object names.
      </para>
    </example>
  </refsection>
  
  <info><corpauthor>BRL-CAD Team</corpauthor></info>
  
  <refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
    
    <para>
      Reports of bugs or problems should be submitted via electronic
      mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
    </para>
  </refsection>
</refentry>
