create_job | Teradata DSA Commands - 17.20 - create_job - BAR - Data Stream Architecture

Teradata® DSA User Guide

Product
BAR
Data Stream Architecture
Release Number
17.20
Release Date
October 2021
Content Type
User Guide
Publication ID
B035-3150-101K
Language
English (United States)

Purpose

The create_job command creates a job based on the values you specify for parameters in the command line or in the XML file. Parameter values you enter in the command line supersede any value you enter for those parameters in the parameters XML file.

Syntax

create_job [ -file File | parameters]

Example

dsc create_job -n job1 -f parameters.xml

Parameters

n|name Name
The name of the job on which to perform the action. Must be unique for each job.
Example: job1
f|file filename
The full file path and file name of the file containing the necessary parameters to create the job. If the same parameters are provided both in the file and on the command line, Teradata DSA uses the values specified in the command line.
Example: parameters.xml
d|description Description
A meaningful description of the job. To allow a multiword description, add \" before and after the description string.
Example: \"backup web apps\"
t|type Type
The type of job. Enter one of the following:
  • BACKUP
  • RESTORE
  • ANALYZE_READ
  • ANALYZE_VALIDATE
Example: RESTORE
b|backup_name BackupName
[Optional] An existing backup job name. For restore, analyze_read, and analyze_validate jobs only.
Example: backupWeb1
u|user_authentication User
Required when security management is enabled. Supplies the command with the Viewpoint user, and triggers a password prompt for authentication.

Permissions required: User role

v|backup_version BackupVersion
[Optional] Backup version number to be replicated to or from third party storage. This number is visible in the backup filename (bar_123456789.out)

If you specify next_incremental_restore, do not specify a backup version number.

Example: 2

Usage Notes

A DBC only backup job cannot be run as online.

To get the backup version of a save set, use the list_save_sets command.

Set the skip_archive parameter to true to have the job continue to run if a table is non-existant; for example, access rights for objects are missing or a table specifically listed in a job file is missing (for example, dropped). By setting the parameter to true, the job skips the missing table and continues processing the remaining tables. The default value for skip_archive is false. The default value for existing jobs should be false and can be set during the upgrade procedure.

In a restore job, the parent_name parameter uses the backup job name when exporting the XML.

In a restore job, the map_to parameter is used to map one database to a new database or to map a table level object under multiple databases to a new database. Job creation fails under the following circumstances:
  • Multiple databases map to same database
  • Same table level object name under different databases maps to the same database
  • Database A is mapped to newA, and table level object x under database B is mapped to newA.x
If you have defined map_to, rename_to, or config_map_name for table level objects, this affects the results of a database level restore job definition.
  • If database is selected and includeAll attribute, map_to, or config_map_name is not set at the database level, the DSC expands objects under the database and treats the restore job as table level restore.
  • If database is selected and includeAll attribute, map_to, or config_map_name is set at the database level, the table level definitions are ignored, and the DSC treats the restore job as database level restore.

In a backup, restore, or analyze_validate job, use the streams_softlimit job option to override the system level streams soft limit. Range is 1- max soft limit of the stream soft limit, where max is the number of AMPs per node in the system. For more information about optimal settings, see Values for XML Elements.

In a backup or restore job, use the skip_joinhash_index job option to skip archiving the join and hash index during a backup job or to skip the join index restore during a restore job.

For an incremental restore backup job, use the enable_backup_for_IR job option to create the backup job for incremental restore. This can only be set during create_job. Once the job is created, it cannot be set for incremental restore.

Sample XML: Remote Backup Job

Job parameters for a remote backup job:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

              <!--****The command below must be on one line.****-->
<dscCreateJob xmlns="http://schemas.teradata.com/v2012/DSC" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="DSC.xsd">

<!--   Optional -->
<job_instance>
<!-- 'job_name' - Required, max 128 characters.-->
<!-- Note: Can be omitted in xml to be specified via command line. -->
  <job_name>SampleRemoteBackup1</job_name>

<!-- 'job_description' - Required, max 256 characters. -->
<!-- Note: Can be omitted in xml to be specified via command line. -->
  <job_description>This is a sample remote backup job.</job_description>

<!-- 'job_type' - Required, accepted values: BACKUP, RESTORE, ANALYZE_VALIDATE, ANALYZE_READ -->
<!-- Note: Can be omitted in xml to be specified via command line. -->
  <job_type>BACKUP</job_type>

<!-- 'auto_retire' - Optional, accepted values: true/false    -->
  <auto_retire>true</auto_retire>

<!-- 'retire_value' - Required (if auto_retire is true) -->
  <retire_value>15</retire_value>

<!-- 'retire_units' - Required (if auto_retire is true), accepted values: DAYS, WEEKS -->
  <retire_units>DAYS</retire_units>

<!-- 'objectlist' - Required for BACKUP, RESTORE, ANALYZE_VALIDATE --> 
<!-- Note: 'objectlist' is NOT permitted for ANALYZE_READ jobs -->
  <objectlist>

  <objectinfo>
  <!-- 'object_name' - Required, max 128 characters -->
    <object_name>CreateQCFVer</object_name>

  <!-- 'object_type' - Required, accepted values: AGGREGATE_FUNCTION, AUTHORIZATION, COMBINED_AGGREGATE_FUNCTIONS, DATABASE, EXTERNAL_PROCEDURE, GLOP_SET, HASH_INDEX, INSTANCE_OR_CONSTRUCTOR_METHOD, JAR, JOIN_INDEX, MACRO, NO_PI_TABLE, ORDERED_ANALYTICAL_FUNCTION, QUEUE_TABLE, STANDARD_FUNCTION, STATISTICAL_FUNCTION, STORED_PROCEDURE, TABLE, TABLE_FUNCTION, TRIGGER, USER, USER_DEFINED_METHOD, USER_DEFINED_DATA_TYPE, VIEW -->
    <object_type>TABLE</object_type>

      <!-- 'parent_name' - Required, max 128 characters -->
        <parent_name>SystemFe</parent_name>

      <!-- 'parent_type' - Required, accepted values: DATABASE/USER -->
        <parent_type>DATABASE</parent_type>
    </objectinfo>

    <objectinfo>
      <object_name>ABC</object_name>
      <object_type>DATABASE</object_type>
      <parent_name>DBC</parent_name>
      <parent_type>DATABASE</parent_type>
      <object_attribute_list>
        <includeAll>false</includeAll>
      </object_attribute_list>
      <!-- 'exclude' - Optional -->
        <exclude>
          <excludeobjectinfo>
            <object_name>T1</object_name>
            <object_type>TABLE</object_type>
          </excludeobjectinfo>
          <excludeobjectinfo>
            <object_name>T2</object_name>
            <object_type>TABLE</object_type>
          </excludeobjectinfo>
        </exclude>
      </objectinfo>
  </objectlist>
  </job_instance>

<!-- 'source_tdpid' - Required, max 32 characters -->
  <source_tdpid>system1</source_tdpid>
<!-- 'source_accountid' - Optional, max 30 characters -->
  <source_accountid>acctid</source_accountid>

<!-- 'target_media' - Required, max 32 characters -->
  <target_media>remote1_nbu</target_media>

<!-- 'job_options' - Required -->
  <job_options>
<!-- 'online'- Optional, accepted values: true/false -->
  <online>false</online>

<!-- 'nosync' - Optional, accepted values: true/false -->
  <nosync>false</nosync>

<!-- 'data_phase' - Required,  accepted values: DATA,DICTIONARY  -->
  <data_phase>DATA</data_phase>

<!-- 'query_band' - Optional, max 2048 characters -->
  <query_band>queryBandTest</query_band>

<!-- 'dsmain_logging_level' - Optional, accepted values: Error, Info, Debug, Warning  -->
  <dsmain_logging_level>Error</dsmain_logging_level>

<!-- 'nowait' - Optional, accepted values: true/false -->
  <nowait>false</nowait>

<!-- skip_archive -Optional can be true/false. Skip archive during the backup job in case error in access rights. Supported in DBS 15.10.01 and above -->
  <skip_archive>true</skip_archive>

<!-- skip_stats - Optional can be true/false, default is false. Skip collecting the stats during the backup job. Supported in DBS 16.00 and above -->
  <skip_stats>true</skip_stats>

<!-- track_empty_tables -Optional can be true/false. When it's true, it will track empty table during the backup. Supported in DBS 16.00 and above -->
  <track_empty_tables>true</track_empty_tables>

<!-- streams_softlimit -Optional for BACKUP/RESTORE/ANALYZE_VALIDATE -->
<!-- Job level stream softlimit. This value will override system level stream softlimit-->
  <streams_softlimit>10</streams_softlimit>

<!-- single_object_locking - Optional, can be true/false, default is false. Enables the Enhanced Lock Management feature, to lock objects in a backup one at a time rather than all at the beginning of the backup. -->
  <single_object_locking>false</single_object_locking>

<!-- skip_joinhash_index - Optional can be true/false, default is false. Skip archiving the join and hash index during the backup job. Supported in DBS 16.20 and above -->
  <skip_joinhash_index>true</skip_joinhash_index>

  </job_options>
</dscCreateJob>

Sample XML: Backup Job Enabled for Incremental Restore

Job parameters for a remote backup job enabled for incremental restore:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

              <!--****The command below must be on one line.****-->
<dscCreateJob xmlns="http://schemas.teradata.com/v2012/DSC"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="DSC.xsd">
<!-- Optional -->
  <job_instance>
    <!-- 'job_name' - Required, max 128 characters.-->
    <!-- Note: Can be omitted in xml to be specified via command line. -->
      <job_name>SampleRemoteBackup1</job_name>

    <!-- 'job_description' - Required, max 256 characters. -->
    <!-- Note: Can be omitted in xml to be specified via command line. -->
      <job_description>This is a sample remote backup job.</job_description>

    <!-- 'job_type' - Required, accepted values: BACKUP, RESTORE, ANALYZE_VALIDATE, ANALYZE_READ -->
    <!-- Note: Can be omitted in xml to be specified via command line. -->
      <job_type>BACKUP</job_type>

    <!-- 'auto_retire' - Optional, accepted values: true/false -->
      <auto_retire>true</auto_retire>

    <!-- 'retire_value' - Required (if auto_retire is true) -->
      <retire_value>15</retire_value>

    <!-- 'retire_units' - Required (if auto_retire is true), accepted values: DAYS, WEEKS -->
      <retire_units>DAYS</retire_units>

    <!-- 'objectlist' - Required for BACKUP/RESTORE/ANALYZE_VALIDATE -->
    <!-- Note: 'objectlist' is NOT permitted for ANALYZE_READ jobs -->
      <objectlist>

        <objectinfo>
        <!-- 'object_name' - Required, max 128 characters -->
          <object_name>CreateQCFVer</object_name>

        <!-- 'object_type' - Required, accepted values: AGGREGATE_FUNCTION, AUTHORIZATION, COMBINED_AGGREGATE_FUNCTIONS, DATABASE, EXTERNAL_PROCEDURE, GLOP_SET, HASH_INDEX, INSTANCE_OR_CONSTRUCTOR_METHOD, JAR, JOIN_INDEX, MACRO, NO_PI_TABLE, ORDERED_ANALYTICAL_FUNCTION, QUEUE_TABLE, STANDARD_FUNCTION, STATISTICAL_FUNCTION, STORED_PROCEDURE, TABLE, TABLE_FUNCTION, TRIGGER, USER, USER_DEFINED_METHOD, USER_DEFINED_DATA_TYPE, VIEW -->
           <object_type>TABLE</object_type>

             <!-- 'parent_name' - Required, max 128 characters -->
               <parent_name>SystemFe</parent_name>

             <!-- 'parent_type' - Required, accepted values: DATABASE, USER -->
               <parent_type>DATABASE</parent_type>
        </objectinfo>

        <objectinfo>
          <object_name>ABC</object_name>
          <object_type>DATABASE</object_type>
          <parent_name>DBC</parent_name>
          <parent_type>DATABASE</parent_type>
          <object_attribute_list>
            <includeAll>false</includeAll>
          </object_attribute_list>
          <!-- 'exclude' - Optional -->
            <exclude>
              <excludeobjectinfo>
                <object_name>T1</object_name>
                <object_type>TABLE</object_type>
              </excludeobjectinfo>
            <excludeobjectinfo>
              <object_name>T2</object_name>
              <object_type>TABLE</object_type>
            </excludeobjectinfo>
          </exclude>
        </objectinfo>
      </objectlist>
  </job_instance>

<!-- 'source_tdpid' - Required, max 32 characters -->
  <source_tdpid>system1</source_tdpid>
  <!-- 'source_accountid' - Optional, max 30 characters -->
    <source_accountid>acctid</source_accountid>

  <!-- 'target_media' - Required, max 32 characters -->
    <target_media>remote1_nbu</target_media>

  <!-- 'job_options' - Required -->
    <job_options>
    <!-- 'online'- Optional, accepted values: true/false -->
      <online>false</online>

    <!-- 'nosync' - Optional, accepted values: true/false -->
      <nosync>false</nosync>

    <!-- 'data_phase' - Required,  accepted values: DATA, DICTIONARY -->
      <data_phase>DATA</data_phase>

    <!-- 'query_band' - Optional, max 2048 characters -->
      <query_band>queryBandTest</query_band>

    <!-- 'dsmain_logging_level' - Optional, accepted values: Error, Info, Debug, Warning -->
        <dsmain_logging_level>Error</dsmain_logging_level>

    <!--   'nowait' - Optional, accepted values: true/false -->
      <nowait>false</nowait>

    <!-- skip_archive -Optional can be true/false. Skip archive during the backup job in case error in access rights. Supported in DBS 15.10.01 and above -->
      <skip_archive>true</skip_archive>

    <!-- skip_stats - Optional can be true/false, default is false. Skip collecting the stats during the backup job. Supported in DBS 16.00 and above -->
      <skip_stats>true</skip_stats>

    <!-- track_empty_tables -Optional can be true/false. When it's true, it will track empty table during the backup. Supported in DBS 16.00 and above -->
      <track_empty_tables>true</track_empty_tables>

    <!-- streams_softlimit -Optional for BACKUP/RESOTRE/ANALYZE_VALIDATE -->
    <!-- Job level stream softlimit. This value will override system level stream softlimit-->
      <streams_softlimit>10</streams_softlimit>

    <!-- skip_joinhash_index - Optional can be true/false, default is false. Skip archiving the join and hash index during the backup job. Supported in DBS 16.20 and above -->
      <skip_joinhash_index>true</skip_joinhash_index>

    <!-- enable_backup_for_IR - Optional can be true/false, default is false. Enable the IR feature during backup job. Supported in DBS 16.20 Update 2 and above -->
      <enable_backup_for_IR>true</enable_backup_for_IR>
  </job_options>
</dscCreateJob>

Sample XML: Remote Restore Job

Job parameters for a remote restore job

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 
          <!--****The command below must be on one line.****-->
<dscCreateJob xmlns="http://schemas.teradata.com/v2012/DSC"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="DSC.xsd">

<!-- Optional --> 
<job_instance>
	    
<!-- 'job_name' - Required, max 128 characters.-->
<!-- Note: Can be omitted in xml to be specified via command line. -->
<job_name>SampleRemoteRestore1</job_name>
	    
<!-- 'job_description' - Required, max 256 characters. --> 
<!-- Note: Can be omitted in xml to be specified via command line. -->
<job_description>This is a sample remote restore job.</job_description>
	    
<!-- 'job_type' - Required, accepted values: BACKUP,RESTORE, ANALYZE_VALIDATE, ANALYZE_READ -->
<!-- Note: Can be omitted in xml to be specified via command line. -->
<job_type>RESTORE</job_type>
	    
<!-- 'auto_retire' - Optional, accepted values: true/false --> 
<auto_retire>true</auto_retire>
	    
<!-- 'retire_value' - Required (if auto_retire is true) -->
<retire_value>15</retire_value>
		
<!-- 'retire_units' - Required (if auto_retire is true), accepted values: DAYS, WEEKS -->
<retire_units>DAYS</retire_units>
	    
<!-- 'objectlist' - Required for BACKUP, RESTORE, ANALYZE_VALIDATE -->
<!-- Note: 'objectlist' is NOT permitted for ANALYZE_READ jobs -->
<objectlist>
		
<objectinfo>
<!-- 'object_name' - Required, max 128 characters -->
<object_name>BAR1</object_name>
				
<!-- 'object_type' - Required, accepted values: AGGREGATE_FUNCTION, AUTHORIZATION, COMBINED_AGGREGATE_FUNCTIONS, DATABASE, EXTERNAL_PROCEDURE, FUNCTION_ALIAS, GLOP_SET, HASH_INDEX, INSTANCE_OR_CONSTRUCTOR_METHOD, JAR, JOIN_INDEX, JOURNAL, MACRO, NO_PI_TABLE, ORDERED_ANALYTICAL_FUNCTION, QUEUE_TABLE, STANDARD_FUNCTION, STATISTICAL_FUNCTION, STORED_PROCEDURE, TABLE, TABLE_FUNCTION, TRIGGER, USER, USER_DEFINED_METHOD, USER_DEFINED_DATA_TYPE, VIEW -->
<object_type>VIEW</object_type>
			    
<!-- 'parent_name' - Required, max 128 characters -->
<parent_name>DBC</parent_name>
				
<!-- 'parent_type' - Required, accepted values: DATABASE, USER -->
<parent_type>DATABASE</parent_type>
</objectinfo>
			
<objectinfo>
<object_name>BAR</object_name>
<object_type>DATABASE</object_type>
<parent_name>DBC</parent_name>
<parent_type>DATABASE</parent_type>

<!-- 'exclude' - Optional --> 
<exclude>
<excludeobjectinfo>	
<object_name>T1</object_name>
<object_type>TABLE</object_type>
</excludeobjectinfo>	
<excludeobjectinfo>	
<object_name>T2</object_name>
<object_type>TABLE</object_type>
</excludeobjectinfo>	
</exclude>
</objectinfo>
			
<objectinfo>
<object_name>BAR2</object_name>
<object_type>VIEW</object_type>
<parent_name>DBC</parent_name>
<parent_type>DATABASE</parent_type>

<!-- 'object_attribute_list' Optional -->
<object_attribute_list>

<!-- 'map_to' - Optional, max 128 characters -->
<map_to>DBC2</map_to>

<!-- 'rename_to' - Optional, max 128 characters -->
<rename_to>BAR2</rename_to>

<!-- 'config_map_name' - Optional hash map name, max 128 characters -->
<config_map_name>objectLevelMap</config_map_name>
</object_attribute_list>
</objectinfo>
</objectlist>
		
<!-- 'backup_name'- Required for RESTORE, ANALYZE_READ, ANALYZE_VALIDATE jobs. -->
<backup_name>SampleRemoteBackup1</backup_name>
		
<!-- 'backup_version' - Required for RESTORE, ANALYZE_READ, ANALYZE_VALIDATE jobs. Optional for incremental restore job. -->
<!-- Note: Value = '0', latest save set from backup. Value > 0 is an existing save set.-->
<backup_version>0</backup_version>

<!-- next_incremental_restore - Optional for incremental restore job. Default is false. Set to true to indicate restore to automatically apply the next available save set. If set to true, you cannot specify backup_version. Supported in Advanced SQL Engine 16.20 Update 2 and later-->
<next_incremental_restore>true</next incremental_restore>
		
<!-- 'all_backup_objects' - Required for RESTORE, ANALYZE_READ, ANALYZE_VALIDATE jobs. -->
<!-- Accepted values: true/false. -->
<!-- Note: If False then objectlist is required. -->
<all_backup_objects>false</all_backup_objects>
		
</job_instance>
	
<!-- 'source_media' - Required, max 32 characters --> 
<source_media>remote1_nbu</source_media>
	
<!-- 'target_tdpid' - Required, max 32 characters --> 
<target_tdpid>system1</target_tdpid>
	
<!-- 'target_accountid' - Optional, max 30 characters -->
<target_accountid>acctid</target_accountid>
	
<!-- 'job_options' - Required -->	
<job_options>
		
<!-- 'data_phase' - Optional, accepted values: DATA, DICTIONARY  --> 
<data_phase>DATA</data_phase>
		
<!-- 'enable_temperature_override' - Optional, accepted values: true/false -->
<enable_temperature_override>false</enable_temperature_override>
		
<!-- 'temperature_override' - Optional, accepted values: DEFAULT, HOT, WARM, COLD -->
<temperature_override>DEFAULT</temperature_override>
		
<!-- 'block_level_compression' - Optional, accepted values: DEFAULT, ON, OFF -->
<block_level_compression>DEFAULT</block_level_compression>
		
<!-- 'disable_fallback' - Optional, accepted values: true/false -->
<disable_fallback>false</disable_fallback>
		
<!-- 'query_band' - Optional, max 2048 characters -->
<query_band>queryBandTest</query_band>
		
<!-- 'dsmain_logging_level' - Optional, accepted values: Error, Info, Debug, Warning -->
<dsmain_logging_level>Error</dsmain_logging_level>
        		
<!-- 'reblock' - Optional, accepted values: true/false -->
<!-- Note: Only useful for RESTORE jobs.-->
<reblock>false</reblock>
		
<!-- 'run_as_copy' - Optional, accepted values: true/false -->
<!-- Note: Only useful for RESTORE jobs.-->		
<run_as_copy>false</run_as_copy>
		
<!-- 'skip_archive' -Optional can be true/false. Skip archive during the restore job in case error in access rights. Supported in DBS 15.10.01 and later -->
<skip_archive>true</skip_archive>
		
<!-- 'skip_stats' - Optional can be true/false, default is false. Skip restoring the stats during the restore job. Supported in DBS 16.00 and later -->
<skip_stats>true</skip_stats>

<!-- 'config_map_name' - Optional, Hash map name, max 128 characters -->
<config_map_name>jobLevelMap</config_map_name>
                
<!-- 'concurrent_bld_per_tbl' - Optional, Number of index and fallback subtables that can be built concurrently per table during restore. -->
<!-- Range 1-5 for database version 16.0 and later -->
<!-- Note: Only useful for RESTORE jobs. -->
<concurrent_bld_per_tbl>5</concurrent_bld_per_tbl>
		
<!--  'map_to' - Optional, apply map_to to all objects in the restore job. Supported in Teradata Database 16.00 and later -->
<map_to>new_db</map_to>

<!-- 'streams_softlimit' - Optional for BACKUP, RESTORE, ANALYZE_VALIDATE -->
<!-- Job level stream softlimit. This value will override system level stream softlimit. -->
<!-- Value can be 1 - max soft limit of the stream soft limit, where max is the number of AMPS per node in the system. -->
<streams_softlimit>10</streams_softlimit>

<!-- skip_joinhash_index - Optional. Can be true/false. Default is false. Skip restoring the join and hash index during the backup job. Supported in DBS 16.20 and later -->
<skip_joinhash_index>true</skip_joinhash_index>

<!-- enable_incremental_restore - Optional. Can be true/false. Default is false. Enable incremental restore feature when creating restore job. Supported in Advanced SQL Engine 16.20 Update 2 and later -->
<enable_incremental_restore>false</enable_incremental_restore>

<!-- skip_build_secondary_indexes - Optional. Can be true/false. Default is false. Skip building the secondary index during the restore job. Supported in Advanced SQL Engine 16.20 Update 2 and later -->
<skip_build_secondary_indexes>fales</skip_build_secondary_indexes>

</job_options>
</dscCreateJob>

Command XML for Incremental Restore job

<enable_backup_for_IR>true</enable_backup_for_IR>

<!—include_DBC_data -– Optional. Can be true/false, default is false. Enable the IR feature for DBC tables during backup job. Supported in DBS 17.10 and above -->

<include_DBC_data>true</include_DBC_data>