nz_migrate undocumented

#########################
# Undocumented Features #
#########################
#
# Normally, I would expect you to want to migrate ALL of a table (all rows).  But maybe
# you want to migrate just some of the data and/or break the migration up into smaller
# pieces.  Therefore, I allow you to specify optional SQL -- on a PER TABLE BASIS -- that
# can be used to control/limit the data extraction.
#
# You do this via environment variables.
# You can set them up for as many, or as few, tables as you wish.
# You set them on a per-table basis (one environment variable per table).
#
# If your table name was CUSTOMER_ORDERS, then you would set up this optional
# environment variable in the following manner, prior to launching nz_migrate.
#
#     export OPTIONAL_SQL_CUSTOMER_ORDERS="order_quantity > 1000"
#
# The environment variable must start with OPTIONAL_SQL_
# The tablename part is case sensitive.  It must match the source system exactly (e.g., upper or lower)
# You must set the variable to a valid SQL statement appropriate for this table.
# BASICALLY, this script is going to issue the first part of the SQL statement, e.g.
#           select * from customer_orders where
# and then append to it whatever you've specified
#           order_quantity > 1000
#
# No error checking will be performed.  Make sure you use valid SQL if you use this option.
# If this feature is used, it will be recorded in the nz_migrate output.  e.g.,
#
#      .....OPTIONAL SQL RESTRICTION                    order_quantity > 1000
#
# Any such restriction will also be passed to the nz_cksum portion of the script,
# so that it verifies+validates just the portion of the data that was moved.


# If your migration is going to take a long time ... if you want to migrate the
# data as of a particular point-in-time ... if the source tables might be changing,
# and you don't want those changes to affect the migration ... then you can add
# this switch
#                -stableTXid nnnn
# where nnnn is the stable transaction ID/number.  For more info (or to find out
# the current stableTXid) see:  nz_get_stableTXid -?


# By default, when larger tables are migrated, 4 threads are used.
#
# But what if ...
# say 3 of the threads finished, but one got hung up/failed for "some reason".
# Here is a way to redo just that one thread ... so you only need to (re)migrate
# that portion of the table.  (The less data you have to move over, the better
# off you'll be).
#
# a)  Terminate the nz_migrate job (and any jobs it may have left running on
#     either of the two boxes)
# b)  Did the target table have any rows inserted into it for this thread?
#     They'll get rolled back automatically.  But at some point in time you'll
#     want to nzreclaim that space.  A block level reclaim should suffice.
# c)  Lets say that "thread 2 of 4" failed.  So you want to redo just that thread.
#     Set the following environment variable
#            export MIGRATE_JUST_THIS_THREAD=2
# d)  Then (re)run nz_migrate against that database table ... using basically the
#     same options as before.  But now the script will just start up thread 2 (of 4)
#     rather than threads 1 thru 4.  It is all controlled by this environment
#     variable.