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