
                               ListObj 0.12 beta



  This software generates a script with the definition of  tables,  views  and
stored procedures and the data in tables  of  MS-SQL  7.0/2000  databases.  It
gives you more control over what objects to generate and how  than  Enterprise
Manager does and it also solves some  problems  with  the  Enterprise  Manager
script generator.

  CREDITS: This software uses a modified version of sp_decrypt_7, a  decryptor
of encrypted MS-SQL 7.0 views and  stored  procedures,  by  Martin  Rakhmanoff
(jimmers). See http://jimmers.narod.ru for his homepage.



  1. Usage

  You should run the script from SQL Query Analyzer and see its output in  the
Results pane.

  If you wish to use this script in  an  automated  environment,  execute  the
following shell command instead:

  osql -S "<server>" -d "<database>" -U "<username>" -P "<password>" -n  -r  1
  -w 32768 -i LISTOBJ.SQL

  replacing <server> and <database> with the name of the server  and  database
you wish to script objects in, and <user> and <password> with your login info.
Output on the  standard  error  is  redirected  into  the  file  specified  by
<outputfile>. Omit the angle brackets from the actual parameters. If there  is
a trusted connection between your client and the server, you may  shorten  the
shell command to:

  osql -S "<server>" -d "<database>" -E -n -r 1 -w 32768 -i LISTOBJ.SQL

  To redirect the output of the script - written by  OSQL  onto  the  standard
error, not the standard output! - into a file, use the following syntax:

  <command> 2> <outputfile>

  If you are using a non-NT Windows, the "2>" redirection syntax  will  result
in an error message. Instead, use ERR2OUT with the following syntax:

  err2out <command> > <outputfile>

  You will also need ERR2OUT if you want to pipe the output of OSQL  into  the
standard input of another program as the standard error cannot be piped:

  err2out <command> | <next pipe stage> ...

  Note that the OSQL utility converts text from the current Windows ANSI  code
page to the current DOS OEM code page. To convert national characters back  to
their ANSI codes, use OEM2ANSI:

  <command> | oem2ansi

  Beware, if regional settings are  configured  improperly  in  the  operating
system, some of the national characters may get lost  and  OEM2ANSI  will  not
help you either!

  Also, OSQL wraps lines at 255 characters, even if it is told to use a higher
column width. To compensate,  enable  the  beginning-of-line  and  end-of-line
marker characters in the script - read the comment at  the  beginning  of  the
"sp_temp_Print" stored procedure - and filter the output through UNWRAP1:

  <command> | unwrap1

  UNWRAP1 assumes that all non-wrapped lines start with the Chr(1)  character;
if a line doesn't then it has been wrapped, therefore, UNWRAP1 unwraps  it  by
appending it to the previous line. UNWRAP1 also adds a "--!TRUNCATE!"  warning
after any line that does not end with a Chr(1) character but, as the next line
does begin with a Chr(1) character, the reason for this is not wrapping.

  For a quick start, two example batches are included:

  - LO.BAT: Lists objects on the standard output, in a single stream.

  - LOX.BAT: Lists objects into files, each object into its own file (see  the
    @@_sepfiles parameter below for more information).

  Notes that apply to both batches:

  - The only command line parameter is the list of  objects  to  be  processed
    (see the @@_objnames parameter below for the syntax). It is recommended to
    enclose the parameter into quotation marks, in case it contains characters
    that have special meaning on the command line, e.g. the "|" (pipe).

  - They require SED and TR in the PATH. Download UnxUtils, the 32-bit Windows
    ports of the standard GNU utilities, from http://unxutils.sourceforge.net.

  - They require SQLLOGIN.BAT in the PATH. In SQLLOGIN.BAT, fill in the  SQL_*
    environment variables with the necessary information.

  - They require that LISTOBJ.SQL is present in the current directory.

  - They require write and delete privileges to the current directory so  that
    temporary files can be created and removed.

  The parameters are similar to those in the "Generate SQL  Scripts"  function
of Enterprise Manager. You can find the parameters by searching for the string
"!!!PARAMETERS!!!" in the script. Set @@_* parameters to a value of  0  (zero)
to disable the scripting of related objects or to a non-zero value  to  enable
scripting them. See below for more infos on valid parameter values:

  - @@_drop: Drop processed objects  (and,  for  tables,  referencing  foreign
    keys, as well) beforehands, if they already exist.

  - @@_create: Create processed objects.

  - @@_permissions: Grant or deny  user  and  role  permissions  on  processed
    objects.

  - @@_roles: Process database roles.

  - @@_users: Process database users that  are  optionally  linked  to  logins
    and are optional members of roles.

  - @@_tables: Process user-defined tables.  Extra  parameters  for  scripting
    table structure and contents:

    - @@_primarykey: Create primary keys.

    - @@_index: Create indexes.

    - @@_default: Create default constraints.

    - @@_foreignkey: Create foreign keys; 1 = all foreign keys; 2 = only those
      foreign keys that refer to tables being processed.

    - @@_data: List data; 1 = INSERT statements; 2 = Tab separated; 3 =  Comma
      separated (CSV); add 10 for column headers; add 100 for  prepending  the
      table name (without owner name) to the header and each record.

  - @@_views: Process user-defined views. A non-zero  value  for  @@_data,  to
    script contents, is valid for views, as well.

  - @@_procedures: Process user-defined stored procedures.

  - @@_objnames: Filter names of objects to be processed. The  general  syntax
    is the following, with optional components enclosed into square brackets:

    [~][<object type>#]<object name>[|...]

    - Wildcards are allowed in object names: "*"  (asterisk)  substitutes  any
      string of zero or more characters; "?" (question mark)  substitutes  any
      single character.

    - Separate object names with the "|" (pipe) character.

    - Prepend object names with the object  type  then  the  "#"  (hash  mark)
      character to filter for the object type, as  well.  Valid  object  types
      are: "T" for tables; "V" for views; "P" for stored procedures.

    - Add "~" (tilde) in front of object names to exclude  such  objects  from
      the process, rather than including them.

  Extra configuration options:

  - @@_identformat: Format for identifiers; 0 for plain  identifier  names;  1
    for the owner name prefixed to  object  names  (default);  10  for  quoted
    identifier names; 11 for quoted owner and identifier names.

  - @@_sepfiles: Separate files (script blocks) for  each  object.  Each  file
    starts with the following header:

    -- !NeWoBjEcT! Object: "<object name>" Type: "<object type>"

    When redirecting the output of the script into a file, you can use  LOSORT
    to sort each block into a separate file:

    err2out <command> | losort

    LOSORT saves blocks into files named "<object name>.<short  object  type>"
    where <short object type>, the extension, is a 3-character abbreviation of
    the object type, similarly to the script generator of Enterprise  Manager.
    The program writes the full file names, in their original order, onto  its
    standard output. The following options are available:

    - -d <directory>: Set the target directory for the output files.

    - -e: Do not create empty output files.

    - -n <num of digits>: Prepend a numerical prefix and an underscore to  the
      name of each output file. The prefix starts at 1 and is increased  by  1
      after each output file.

    - -o: Remove the owner name (string to the left of  the  first  dot)  from
      object names.

    - -x: Add the common ".sql" extension to all file names, independently  of
      the actual object type.

  - @@_insertbatchlength: When creating INSERT statements, to fill tables with
    data, there will be an end-of-batch command after this many lines, as  too
    long batches may get truncated or result in running out of memory.

  - @@_batchsep: String that separates batches, when put alone  into  a  line.
    Default: "GO".

  - @@_wordsep: Characters that  indicate  the  end  of  words  (identifiers).
    Default: space, both round parentheses, comma, Tab, line feed and carriage
    return.

  - @@_indentstr: String that indents the output for a more  structured  look.
    Default: Tab.

  - @@_identquote*: Strings that start and end identifiers.  Default:  opening
    and closing square bracket.

  Notes:

  - Scripting data in INSERT statement format is disabled for views.

  - When scripting data in a format other than INSERT statements, nothing else
    will be output. Obviously, merging  formatted data, to be  imported,  with
    SQL statements would not make much sense.

  - When scripting data, the special NULL value is scripted as following:

    - INSERT statement: unquoted literal "NULL" between the two commas.

    - Tab separated: no characters between the two Tabs.

    - Comma separated: no characters between the two commas.

  - When scripting the  contents  of  string  (char,  varchar,  text)  fields,
    trailing spaces are removed in all data formats. So that the empty  string
    can be distinguished from NULL, it is scripted as following:

    - INSERT statement: "''" (double apostrophes) between the two commas.

    - Tab separated: " " (single space) between the two Tabs.  Yes,  an  empty
      string and a string consisting of a single space cannot be distinguished
      this way! However, trailing spaces should not be  used  in  text  fields
      anyway.

    - Comma separated: """" (double quotation marks) between the two commas.
    


  2. Advantages over Enterprise Manager

  - You can save a preconfigured version of this  software  for  later  reuse.
    You can also use it from an automated environment, with a single keypress.
    No need to waste time with selecting the same parameters again and again.

  - Objects are listed in dependency order.  When  scripting  with  Enterprise
    Manager, it is possible that a  view  or  stored  procedure  uses  another
    object of the same type but that object is created later in the script! As
    a result, when you run the resulting script,  you  will  get  an  "Invalid
    object name '...'" error (for views) or a "Cannot add rows  to  sysdepends
    for the current stored procedure because it depends on the missing  object
    '...'. The stored procedure will still be created."  warning  (for  stored
    procedures).

  - The definitions of encrypted views and  stored  procedures  are  decrypted
    (only if encrypted by MS-SQL 7.0!).

  - In the CREATE statement of views and stored procedures, the owner name  is
    optionally prefixed to the object name, even if the object has  originally
    been created without explicitly specifying the owner.

  - Table data can optionally be scripted, in multiple formats.

  - Roles and users can optionally be dropped.



  3. Disadvantages compared to Enterprise Manager

  - Only the following column data types  are  supported  when  listing  table
    contents: tinyint, smallint, int, char, varchar, text  and  datetime.  For
    others, you will get an "Unknown column type: ..." error message.

  - Defaults, rules, user-defined  data  types,  logins,  full  text  indexes,
    triggers and check constraints are not scripted.

  - Multi-column foreign keys are not supported.

  If you need support for such objects, tell the author!



  4. Known problems and limitations

  - The OSQL utility is extremely poorly configurable. Steps have  been  taken
    to circumvent line wrapping because of low column  width  and  ANSI-to-OEM
    character code conversion but these may not help you in all cases.

  - Very long fields and records are not supported. If the  total  size  of  a
    record is more than about 8000 characters then the end of the record  will
    be truncated. UNWRAP1 will add a warning after such lines, though.

  - Although the software runs properly under MS-SQL 2000, as well, it  cannot
    decrypt the definition of encrypted views and stored  procedures:  instead
    of the original definition, you get garbage. To decrypt the definitions of
    views and stored procedures encrypted by MS-SQL 2000,  use  dSQLSRVD.  See
    its homepage at http://www.geocities.com/d0mn4r/dSQLSRVD.html.

  - "Phantom" users - ones that are not linked to any login -,  objects  owned
    by them and permissions denied from or granted to them are not  processed.
    This is an administrative problem that arises when you create new users in
    a database and then you implicitly  delete  them  by  restoring  an  older
    backup that  was  created  when  these  users  did  not  exist  yet.  (Use
    FIXUSERS.SQL - from the same author - to delete such "phantom" users,  and
    then create them again.)

  - In the definition of views and stored  procedures,  not  all  comments  in
    front of the CREATE statement may be skipped. Also, the  software  assumes
    that there are no comments between the CREATE keyword and the name of  the
    object. The worst that can happen is that the object  name  or  the  owner
    name is not fixed correctly. If you stumble upon a problematic definition,
    send it as an example to the author!

  - Apparently, you may have problems scripting data  if  some  string  fields
    contain characters that have special meaning in  that  particular  format.
    For this reason, such special  characters  are  converted  to  some  other
    characters or character sequences that are safe:

    - INSERT statements: "'" (apostrophe) characters are converted  to  double
      apostrophes.

    - Tab separated: char(9) (Tab), char(10) (LF) and char(13) (CR) characters
      are converted to spaces.

    - Comma separated: """ (quotation mark) characters are converted to double
      quotation marks.



  5. Copyright and legal issues

  This software is freeware. You may use it as long as you wish  and  you  may
spread it as you like provided that it is in the original unmodified  archive.
Don't distribute single files only the whole package and don't ask  for  money
above the normal fee of the distribution media itself. This program may not be
included in any compilation, sold on disk or CD-ROM or bundled  with  software
or hardware without prior permission from the author.



  6. The author

  If you're interested in some similarly useful utilities then contact  me  at
the E-mail address sta@c64.org or visit my homepage at http://sta.c64.org.

  If you wish to report a problem, make sure to supply an example database, as
well. Do not send a database backup as  backups  may  not  be  restored  in  a
destination SQL server whose regional settings are different from  the  source
SQL server! Instead, supply an SQL script that creates the objects,  necessary
for reproducing and testing the problem, in an empty database.

  Joe Forster/STA
  28th July, 2004
