home *** CD-ROM | disk | FTP | other *** search
/ Computer Buyer 1998 October / dpcb1098.iso / Business / Maxim / MAX5 / data.z / RS_SQLIF.TXT < prev    next >
Text File  |  1996-06-07  |  22KB  |  474 lines
  1. ============================================================================
  2.  
  3. Information On The Connections ini File Used By ReportSmith:  "RS_SQLIF.INI"
  4. ----------------------------------------------------------------------------
  5.  
  6.  
  7.   This file contains information pertaining to database connections 
  8.   for ReportSmith.  New with the 3.0 release, this file also specifies
  9.   which connections should display as available in the Table Open dialog.
  10.  
  11.   ReportSmith needs to know certain information about the capabilities and
  12.   idiosyncrasies of the databases it retrieves data from.  The standard
  13.   ReportSmith product comes with this knowledge built in for many of the
  14.   industry-standard databases.
  15.  
  16.   With the advent of Microsoft's ODBC standard for accessing databases,
  17.   however, it is now possible for the end user to install new ODBC drivers
  18.   that the ReportSmith product has no built-in special knowledge of.  While
  19.   the ODBC interface allows ReportSmith to query the driver to find out some
  20.   of this information, much of it is not available through the ODBC
  21.   interface.
  22.  
  23.   When ReportSmith is directed to use a database driver for which it has no
  24.   built-in knowledge, it makes the best guesses it can with regards to the
  25.   capabilites and behaviors of the database by utilyzing what information is
  26.   is available through the standard ODBC interface.  Depending upon how
  27.   closely the database follows certain ODBC conventions and standards, this
  28.   may or may not be acceptable.
  29.  
  30.   The RS_SQLIF.INI file is used to allow the information about a new ODBC
  31.   driver to be specified to ReportSmith.  This allows ReportSmith to interact
  32.   more appropriately with the database, and with the user, by properly
  33.   conforming to the database's specific idiosyncrasies and by taking
  34.   advantage   of the database's capabilities.
  35.  
  36.   The RS_SQLIF.INI file is used not only for new ODBC drivers.  It may also
  37.   be used to change, add, or delete capabilities for the built-in databases
  38.   as well.  Part or all of the information for the database knowledge
  39.   built-in within ReportSmith may be overridden by placing specifications in
  40.   the file.  This could be useful, for example, if an older, newer, or custom
  41.   version of the database is being used.  By overriding the built-in
  42.   knowledge, ReportSmith could be made to behave properly with the different
  43.   database   version.
  44.  
  45.   As a side benefit, the RS_SQLIF.INI file can also be used to disable the
  46.   use of certain features of the database, if desired.  The RS_SQLIF.INI file
  47.   may be used, for example, to prevent the user from accessing particular
  48.   capabilities of the database by telling ReportSmith that the database does
  49.   not have those capabilities.  This applies to the built-in databases as
  50.   well as to newly-added ODBC drivers.
  51.  
  52.   The following information may be specified in the RS_SQLIF.INI file:
  53.  
  54.       1.  The outer join capabilites provided by the database.
  55.       2.  The SQL syntax used to express outer joins, if they are supported.
  56.       3.  Whether the SQL "COUNT(*)" aggregate function is supported.
  57.       4.  Whether expressions are supported in the SQL "ORDER BY" clause.
  58.       5.  The quoting character placed around field names in SQL statements
  59.           to distinguish them from keywords, and to allow field names that
  60.           contain special characters.
  61.       6.  The SQL functions and operators provided by the database, and the
  62.           details of their syntax.
  63.  
  64.   The ReportSmith product contains built-in knowledge about the following types 
  65.   of databases:
  66.  
  67.       Microsoft SQL Server
  68.       Sybase
  69.       Gupta SQLBase
  70.       DB2
  71.       Oracle
  72.       Teradata
  73.       Ingres
  74.       Informix
  75.  
  76.   When this release of ReportSmith is installed, a default version of
  77.   RS_SQLIF.INI is placed in the Windows directory.  This default version
  78.   contains information about certain ODBC drivers.
  79.  
  80.   FORMAT OF THE RS_SQLIF.INI FILE
  81.  
  82.   THE [CONNECTIONS] SECTION
  83.  
  84.   RS3.0 has a new section.  The [Connections] section specifies which connections
  85.   that ReportSmith should display in Connections drop down list in the Table Open 
  86.   Dialog box.  Normally this section is set by the install and reflects which connections 
  87.   were installed.  A user may change the values in order to remove the availability 
  88.   of a connection.  If ODBC=1 is specified then RS searches for installed ODBC drivers 
  89.   and places those in the listbox. 
  90.  
  91.   The settings take the form of:
  92.  
  93.       [Connections]
  94.       Oracle=0      - Oracle was not installed/not available as a connection
  95.       SQL Base=1    - Gupta SQL Base is available
  96.       SQL Server=1
  97.       Sybase10=1
  98.       Sybase=0
  99.       Teradata=0
  100.       Idapi=1       - IDAPI (aka BDE) should always be set to 1.  ReportSmith uses IDAPI
  101.                           for local sorting or when in client disk mode.
  102.       DB2=0            
  103.       DB2 Gupta=0
  104.       dBase for Windows=0   - Special integrated reporting with Borland's dBASE for Windows
  105.       ODBC=1
  106.       Unify=0
  107.  
  108.  
  109.   SPECIFIC CONNECTION SECTION NAMES
  110.  
  111.   The RS_SQLIF.INI file follows the format of Microsoft Windows ".ini" files.
  112.   There is a section for each database type.  The section name is either the
  113.   ODBC "Description" text for the ODBC Data Source.
  114.  
  115.   For the ReportSmith for SQL Databases product, there are special reserved
  116.   names for ReportSmith's built-in knowledge.  As with all Windows .ini files,
  117.   the section name is enclosed in brackets "[]".  The special reserved
  118.   section names are:
  119.  
  120.       [SQL Server]        Microsoft SQL Server / Sybase
  121.       [DB2]               DB2
  122.       [Teradata]          Teradata
  123.       [Oracle]            Oracle
  124.       [SQLBase]           Gupta SQLBase
  125.       [Ingres]            Ingres
  126.  
  127.   For ODBC databases, ReportSmith first looks at the ODBC "Description"
  128.   text for the database.  If the description text contains anywhere
  129.   within it certain special substrings, then it is assumed that the ODBC
  130.   driver is for one of the databases ReportSmith knows about and the
  131.   built-in knowledge is used (unless overridden in one of the special
  132.   section names listed above).  Otherwise, ReportSmith looks for a
  133.   section name that exactly matches the ODBC Description text.
  134.  
  135.       If this substring is contained
  136.       within the ODBC description, in      ReportSmith assumes that the
  137.       any combination of upper/lower       ODBC driver is for this type of
  138.       case:                                database:
  139.  
  140.       MICROSOFT SQL SERVER                 Microsoft SQL Server / Sybase
  141.       SYBASE                               Microsoft SQL Server / Sybase
  142.       DB2                                  DB2
  143.       TERADATA                             TeraData
  144.       ORACLE                               Oracle
  145.       GUPTA                                Gupta SQLBase
  146.       INGRES                               Ingres
  147.  
  148.   SECTION CONTENTS
  149.  
  150.   Within each database section are keywords and values that specify the
  151.   capabilities and idiosyncrasies of that particular database.  As with
  152.   all Windows .ini files, each entry is of the form "keyword=value".
  153.   There are a number of specifically-named keywords that describe
  154.   information for which there is a single value.  There are also
  155.   numbered keywords used to describe lists of values for operator and
  156.   function lists.  For these lists, there is a keyword that gives the
  157.   count of the number of items in the list.
  158.  
  159.   SINGLE-VALUE KEYWORDS
  160.  
  161.   SortExprSupport=n
  162.  
  163.       "n" should be the number 1 if the database supports expressions in the
  164.       SQL "ORDER BY" clause, or the number 0 if it does not.
  165.  
  166.   CountStarSupport=n
  167.  
  168.       "n" should be the number 1 if the database supports the SQL "COUNT(*)"
  169.       aggregate function, or the number 0 if it does not.
  170.  
  171.   IDQuote=string
  172.  
  173.       "string" is the quoting character(s) to be placed around field names in
  174.       SQL statements to allow SQL keywords and special characters in field
  175.       names.
  176.  
  177.   OuterJoinSyntax=n
  178.  
  179.       "n" should be the number 1, 2 or 3, according to which syntax is used
  180.       by the database to support outer joins:
  181.  
  182.       1 = The text is placed around the join operator.  To the left of it for
  183.           a left outer join, to the right of it for a right outer join, and
  184.           in both places for a full outer join.  The following examples
  185.           assume that the join text is an asterisk:
  186.  
  187.               Left outer join:  col1 *= col2
  188.               Right outer join: col1 =* col2
  189.               Full outer join:  col1 *=* col2
  190.  
  191.       2 = The text follows the join column names.  It follows the left column
  192.           name for a left outer join, the right column name for a right outer
  193.           join, both column names for a full outer join.  The following
  194.           examples assume that the join text is "(+)":
  195.  
  196.               Left outer join:  col1 (+) = col2
  197.               Right outer join: col1 = col2 (+)
  198.               Full outer join:  col1 (+) = col2 (+)
  199.  
  200.       3 = The special ODBC outer join SQL syntax extension is used in the SQL
  201.           "FROM" clause.  See the ODBC standard for a description.  In this
  202.           case, only left outer joins are permitted, and if an outer join
  203.           exists the query may contain only those two tables.
  204.  
  205.   OuterJoinText=string
  206.  
  207.       "string" should be the character(s) used in the outer join syntax (the
  208.       asterisk and "(+)" in the OuterJoinSyntax examples above).  This
  209.       keyword is used only if OuterJoinSyntax is 1 or 2.
  210.  
  211.   OuterJoinSupport=string
  212.  
  213.       "string" should be a string of characters that signifies which types of
  214.       outer joins are supported by the database.  It can be any combination
  215.       of the following characters:
  216.  
  217.           L - Left outer joins are supported.
  218.           R - Right outer joins are supported.
  219.           F - Full outer joins are supported.
  220.           M - The database supports multiple outer joins in a single query.
  221.  
  222.       This keyword is ignored is OuterJoinSyntax is 3.
  223.  
  224.   OPERATOR AND FUNCTION LIST KEYWORDS
  225.  
  226.   These keywords are used to allow the list of SQL functions and operators
  227.   supported by the database to listed, so that they may appear in various
  228.   dialog boxes in ReportSmith (for example the "Selections" and "Derived
  229.   Field" dialogs).
  230.  
  231.   For each database for which ReportSmith has built-in knowledge,
  232.   ReportSmith contains lists of the functions and operators supported.
  233.   It also contains two lists of standard ODBC functions and operators
  234.   that it will use for all ODBC databases for which it has no specific
  235.   knowledge.
  236.  
  237.   This portion of RS_SQLIF.INI can be used to either replace or augment the
  238.   built-in lists.  Entirely new lists can be given, or additional entries
  239.   added to the existing lists.
  240.  
  241.   Each list is divided into "groups".  For example, the functions list might
  242.   be divided into string, arithmetic, and date/time functions.  Each group
  243.   appears as entry in the upper combobox in the ReportSmith dialogs.  Each
  244.   element of a group contains two entries.  One entry is the description text
  245.   to be displayed to the user in the listbox, while the other entry is the
  246.   substitution text to be inserted into the SQL edit area if the user picks
  247.   that entry from the listbox.
  248.  
  249.   The substitution text may contain up to two special marker characters:
  250.  
  251.       A substitution location marker (SLM) is a location in the text, marked
  252.       by "\r" characters, where the user will have to insert something -- for
  253.       example, a parameter value for a function call.  If at the time of the
  254.       insert the user has blocked (highlighted) some text, the blocked text
  255.       will be placed inside the inserted text at the SLM location.
  256.  
  257.       A caret location marker (CLM) is a location in the text, marked by "\n"
  258.       characters, where the caret is to be placed after the text is inserted.
  259.       A CLM differs from an SLM in that for a CLM, no surrounding of blocked
  260.       text is done.
  261.  
  262.   The substitution text can contain one SLM, one CLM, or an SLM followed
  263.   by a CLM.  In the latter case, the CLM is used as the location to put
  264.   the caret if something was automatically substituted into the SLM
  265.   location.
  266.  
  267.   In addition to the SLM and CLM, the substitution text may also contain "\t"
  268.   characters, which will be replaced with a single tab character.  This
  269.   allows the tab-stops that ReportSmith places in some listboxes to be used.
  270.  
  271.   FUNCTION LIST KEYWORDS
  272.  
  273.   FnListType=n
  274.  
  275.       "n" is a number that indicates whether this list is to replace or
  276.       augment any built-in function list in ReportSmith for this database.
  277.       It should  be one of the following values:
  278.  
  279.       0 - Do not use the built-in list.  The entire list will be specified in
  280.           the .ini file.
  281.  
  282.       1 - Use the standard built-in list for this database, if there is one.
  283.           The entries in the .ini file will appended to the built-in list.
  284.           For ODBC databases, the list of functions described in the ODBC
  285.           standard is used.
  286.  
  287.       2 - Use the built-in ODBC "escaped" function list.  This applies to
  288.           ODBC databases only.  The ODBC standard provides for a special
  289.           function syntax that allows logical function names to be used in
  290.           the SQL statement that are then translated to the actual function
  291.           names and syntaxes that are used by the underlying databases.  If
  292.           this setting is used for a non-ODBC database, setting 1 will be
  293.           used.
  294.  
  295.   FnGrpCount=n
  296.  
  297.       "n" is the total number of function groups in the ini file.  This must
  298.       be a number from 0 to 255.
  299.  
  300.   FnGrp1Title=string
  301.  
  302.       There is one of these keywords for each function group.  The "1" in the
  303.       keyword should be replaced by the actual group number (from 1 to the
  304.       setting of FnGrpCount).  This specifies the title text for this
  305.       group -- the description that is to appear in the top combobox in the
  306.       dialog box.  If this list is being merged with a built-in list and the
  307.       built-in list already contains a group with the exact same title, the
  308.       entries in the .ini group will be appended to the built-in group.
  309.  
  310.   FnGrp1Count=n
  311.  
  312.       There is one of these keywords for each function group.  The "1" in the
  313.       keyword should be replaced by the actual group number (from 1 to the
  314.       setting of FnGrpCount).  "n" should be a number from 0 to 255 that
  315.       specifies how many entries (function descriptions) are contained within
  316.       the group.
  317.  
  318.   FnGrp1Item1Disp=string
  319.  
  320.       There is one of these keywords for each function within each group.
  321.       The first "1" in the keyword should be replaced by the actual group
  322.       number (from 1 to the setting of FnGrpCount), while the second "1"
  323.       should be replaced by the number of the function within the group
  324.       (from 1 to the setting of FnGrp1Count).  "string" is the descriptive
  325.       text for the function that is to be displayed in the listbox.
  326.  
  327.   FnGrp1Item1Text=string
  328.  
  329.       There is one of these keywords for each function within each group.
  330.       The first "1" in the keyword should be replaced by the actual group
  331.       number (from 1 to the setting of FnGrpCount), while the second "1"
  332.       should be replaced by the number of the function within the group (from
  333.       1 to the setting of FnGrp1Count).  "string" is the substitution text
  334.       to be inserted into the SQL edit area if the user picks that entry from
  335.       the listbox.  See the discussion above about the special "marker"
  336.       characters that may be placed in this text.
  337.  
  338.  
  339.   OPERATOR LIST KEYWORDS
  340.  
  341.   OpListType=n
  342.  
  343.       "n" is a number that indicates whether this list is to replace or
  344.       augment any built-in operator list in ReportSmith for this database.
  345.       It should  be one of the following values:
  346.  
  347.       0 - Do not use the built-in list.  The entire list will be specified in
  348.           the .ini file.
  349.  
  350.       1 - Use the standard built-in list for this database, if there is one.
  351.           The entries in the .ini file will appended to the built-in list.
  352.           For ODBC databases, the SQL syntax described in the ODBC standard
  353.           is used.
  354.  
  355.   OpGrpDCount=n
  356.   OpGrpWCount=m
  357.  
  358.       The operators list contains some syntax items that are allowed in both
  359.       derived field expressions and WHERE-clause text, and other syntax items
  360.       that are allowed only in WHERE-clause text.  The former must be at the
  361.       beginning of the operator list, while the latter must be at the end of
  362.       the operator list.  "n" is the number of operator groups in the ini
  363.       file that may be used in both places.  "m" is the number of operator
  364.       groups in the ini file that may be used only in the WHERE clause.  The
  365.       sum of "n" and "m" is the total number of operators in the list.  "n"
  366.       and "m", and the sum of "n" and "m" must be from 0 to 255.
  367.  
  368.   OpGrp1Title=string
  369.  
  370.       There is one of these keywords for each operator group.  The "1" in the
  371.       keyword should be replaced by the actual group number (from 1 to the
  372.       setting of OpGrpDCount + OpGrpWCount).  This specifies the title text
  373.       for this group -- the description that is to appear in the top combobox
  374.       in the dialog box.  If this list is being merged with a built-in list
  375.       and the built-in list already contains a group with the exact same
  376.       title, the entries in the .ini group will be appended to the built-in
  377.       group.
  378.  
  379.   OpGrp1Count=n
  380.  
  381.       There is one of these keywords for each operator group.  The "1" in the
  382.       keyword should be replaced by the actual group number (from 1 to the
  383.       setting of OpGrpDCount + OpGrpWCount).  "n" should be a number that
  384.       specifies how many entries (operator descriptions) are contained within
  385.       the group.
  386.  
  387.   OpGrp1Item1Disp=string
  388.  
  389.       There is one of these keywords for each operator within each
  390.       group.  The first "1" in the keyword should be replaced by the
  391.       actual group number (from 1 to the setting of OpGrpDCount +
  392.       OpGrpWCount), while the second "1" should be replaced by the
  393.       number of the operator within the group (from 1 to the setting of
  394.       OpGrp1Count).  "string" is the descriptive text for the function
  395.       that is to be displayed in the listbox.
  396.  
  397.   OpGrp1Item1Text=string
  398.  
  399.       There is one of these keywords for each operator within each
  400.       group.  The first "1" in the keyword should be replaced by the
  401.       actual group number (from 1 to the setting of OpGrpDCount +
  402.       OpGrpWCount), while the second "1" should be replaced by the
  403.       number of the operator within the group (from 1 to the setting of
  404.       OpGrp1Count).  "string" is the substitution text to be inserted
  405.       into the SQL edit area if the user picks that entry from the
  406.       listbox.  See the discussion above about the special "marker"
  407.       characters that may be placed in this text.
  408.  
  409.   SAMPLE RS_SQLIF.INI FILES
  410.  
  411.   This sample .ini file disables all outer-join use in Oracle databases:
  412.  
  413.       [Oracle]
  414.       OuterJoinSupport=
  415.  
  416.   This sample .ini file disables full outer join use in Oracle databases, but
  417.   continues to allow left and right outer joins:
  418.  
  419.       [Oracle]
  420.       OuterJoinSupport=LRM
  421.  
  422.   This sample .ini file is used for an ODBC driver for dBase.  The ODBC
  423.   "Description" text for the driver is "dBase Files (*.dbf)".   Due to
  424.   inadequacies in the ODBC interface, the driver is unable to tell
  425.   ReportSmith the following information, so the .ini file is used to provide
  426.   this additional information to ReportSmith:
  427.  
  428.       COUNT(*) is supported, even though other summary functions are not.
  429.       Some additional functions in the existing numeric and string categories
  430.           are provided over and above the ODBC standard.
  431.       Some additional operators are provided in a new "bitwise" category over
  432.           over and above the ODBC standard.  These operators are allowed in
  433.           both Derived Field Expressions and WHERE Clauses.
  434.       One form of subquery is supported, which may only be used in WHERE
  435.           clauses.
  436.  
  437.       [dBase Files (*.dbf)]
  438.       CountStarSupport=1
  439.       FnListType=1
  440.       FnGrpCount=2
  441.       FnGrp1Title="Numeric functions:"
  442.       FnGrp1Count=3
  443.       FnGrp1Item1Disp="POWER(num1, num2) - num1 to the power of num2"
  444.       FnGrp1Item1Text=" POWER(\r, \n) "
  445.       FnGrp1Item2Disp="EXP(num) - Exponential"
  446.       FnGrp1Item2Text=" EXP(\r) \n"
  447.       FnGrp1Item3Disp="SQRT(num) - Square root"
  448.       FnGrp1Item3Text=" SQRT(\r) \n"
  449.       FnGrp2Title="String functions:"
  450.       FnGrp2Count=2
  451.       FnGrp2Item1Disp="DIFFERENCE(char, char) - SOUNDEX difference"
  452.       FnGrp2Item1Text=" DIFFERENCE(\r, \n) "
  453.       FnGrp2Item2Disp="REVERSE(string) - Reverse string"
  454.       FnGrp2Item2Text=" REVERSE(\r) \n"
  455.       OpListType=1
  456.       OpGrpDCount=1
  457.       OpGrpWCount=1
  458.       OpGrp1Title="Bitwise:"
  459.       OpGrp1Count=4
  460.       OpGrp1Item1Disp="x&y\tAND"
  461.       OpGrp1Item1Text=" & "
  462.       OpGrp1Item2Disp="x|y\tOR"
  463.       OpGrp1Item2Text=" | "
  464.       OpGrp1Item3Disp="x^y\tExclusive OR"
  465.       OpGrp1Item3Text=" ^ "
  466.       OpGrp1Item4Disp="~x\tNOT"
  467.       OpGrp1Item4Text=" ~"
  468.       OpGrp2Title="Subqueries:"
  469.       OpGrp2Count=1
  470.       OpGrp2Item1Disp="x = (subquery) - True if x equals single result from
  471.                        subquery"
  472.       OpGrp2Item1Text=" = (\n)"
  473.  
  474.