home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / sample / dblibrary / README < prev    next >
Encoding:
Text File  |  1993-04-22  |  9.3 KB  |  284 lines
  1. This directory contains the following DB-Library example files and scripts:
  2.  
  3.     example1.c:    Submits 2 queries to the server on the table
  4.             'sysobjects', one to find all the system tables,
  5.             the other to find the first 10 stored procedures.
  6.             Binds program variables to the returned rows, then
  7.             displays the rows.
  8.  
  9.     example2.c:    Opens a data file, inserts data from the file into
  10.             a database table, binds the data to program variables,
  11.             and displays the results.
  12.  
  13.     example3.c:    Illustrates binding aggregate and compute by results
  14.             using the "pubs" database.
  15.  
  16.     example4.c:    Submits a query to the server and saves up to 1,000
  17.             rows of the results using row buffering rather
  18.             than binding. Asks the user which row to display,
  19.             then displays that row.
  20.  
  21.     example5.c:    Illustrates data conversion with the dbconvert()
  22.             routine.
  23.  
  24.     example6.c:    Demonstrates the use of two DBPROCESSes to
  25.             simultaneously query and update a table through
  26.             browse mode.  This example uses a hardcoded query.
  27.  
  28.     example7.c:    Demonstrates most of the browse mode routines
  29.             that deal with finding out about the results
  30.             of an ad hoc query.
  31.  
  32.     example8.c:    Illustrates how to use remote procedure calls
  33.             and how to process return parameter values.
  34.  
  35.     example9.c:    Illustrates a method for effectively managing 
  36.             multiple input and output data streams, via 
  37.             DBIORDESC(), DBIOWDESC(), DBRBUF(), dbsqlsend(), 
  38.             and dbsqlok().
  39.     
  40.     twophase.c:    Illustrates the use of the two-phase commit
  41.             service to perform a distributed transaction.
  42.  
  43.     datafile:    The data file for examples 2 and 6.
  44.     
  45.     installsample:    A script for building a sample dataserver and setting 
  46.             it up for running the sample DB-Lib programs.
  47.             
  48.     README:        This file.
  49.  
  50.  
  51. Examples 1-9 setup:
  52.  
  53.   There are two parts to running the DB-Library sample programs, setting up a
  54.   sample database, and compiling and running the samples:
  55.  
  56.   Setting up a sample database for examples 1-9:
  57.  
  58.     Because of the various permissions which the examples need
  59.     set in the server, it is easiest to use new temporary master
  60.     database devices.  The script "installsample" will build
  61.     a 16M sample database device, set it up, and start a server
  62.     named PRACTICE for running DB-Lib examples 1-9.  If you
  63.     want to set up the sample database by hand, see the Notes
  64.     section below for more details of the requirements for the
  65.     sample programs.  If you are planning on running the
  66.     "twophase" example, see the Twophase Example Setup section
  67.     below.
  68.  
  69.     Steps for setting up the sample database with a server
  70.     named PRACTICE:
  71.  
  72.     1. Set up the SYBASE environment variable using the following
  73.        command:
  74.  
  75.             source  /usr/sybase/scripts/SetVars
  76.         
  77.     2. Create a new entry in the /usr/sybase/interfaces file
  78.        for the server named  PRACTICE.  See the Install Guide
  79.        for information on adding entries to the interfaces file.
  80.  
  81.     3. Find enough space for a 16M database device on your disk.
  82.  
  83.     4. Using "installsample", create a new database device and start
  84.        a server named PRACTICE using the command:
  85.  
  86.     $SYBASE/sample/dblibrary/installsample <PRACTICE_device_name> PRACTICE
  87.         
  88.        where PRACTICE_device_name is the full pathname for the
  89.        database device to be installed.  We recommend that you
  90.        always name database devices with a .sdb extension, e.g.,
  91.  
  92.     $SYBASE/sample/dblibrary/installsample\
  93.         ~/your_dir/practice_db.sdb PRACTICE
  94.  
  95.        will install a 16M database device '~/your_dir/dbs/practice_db.sdb'
  96.        and bring up a dataserver for it named PRACTICE.
  97.  
  98.         The script "installsample" uses "startserver" to
  99.         build and/or start the specified device.  This
  100.         means that your server will be left running in a
  101.         Terminal window after the database is installed.
  102.  
  103.         For more details on "installsample", see the script
  104.         itself:  /usr/sybase/sample/dblibrary/installsample
  105.  
  106.     5. Set the DSQUERY environment variable to point to the PRACTICE
  107.            server by typing:
  108.  
  109.             setenv DSQUERY PRACTICE
  110.         
  111.     6. Now that the PRACTICE server is up and running, the
  112.        database is set up to run examples 1-9.
  113.  
  114.   To compile and run examples 1-9:
  115.   
  116.       1. You must login as 'sybase' in order to compile the samples.
  117.  
  118.     2. Change to the /usr/sybase/sample/dblibrary directory using:
  119.     
  120.             cd /usr/sybase/sample/dblibrary
  121.     
  122.     3. Set the SYBASE environment variable to the sybase root
  123.        directory using the following command:
  124.  
  125.             setenv SYBASE /usr/sybase
  126.  
  127.     4. Compile and link the source files:
  128.  
  129.         The makefile is set up to compile the samples and link them with
  130.         shared libraries.
  131.  
  132.         To compile all the samples, use the command:
  133.  
  134.             make all
  135.  
  136.         To compile individual samples:
  137.  
  138.             make exam1
  139.             make exam2
  140.             etc.
  141.  
  142.         To use compile switches, use the CFLAGS switch:
  143.  
  144.             make CFLAGS=-g all
  145.  
  146.     5. To run examples 1-9:
  147.  
  148.             exam1
  149.             exam2
  150.             etc.
  151.         
  152. Twophase Example Setup:
  153.  
  154. The two-phase commit C example requires two different master database
  155. devices and two servers to be running at the same time.  Each server
  156. will have its own name in the interfaces file: one server will be
  157. named SERVICE and the other server will be named PRACTICE. You can
  158. use the database device you created for examples 1-9 as one of the
  159. database devices. If the server you you used for running examples
  160. 1-9 is still running, the PRACTICE server is ready to go, and you
  161. only need to install the SERVICE server.
  162.  
  163. Here are the steps for setting up the databases and servers for
  164. the twophase sample.  Note that the setup for the SERVICE server
  165. is completely analogous to the PRACTICE server. If you have not
  166. yet setup the PRACTICE server, follow the instructions in the
  167. section "Setting up a sample database for examples 1-9".
  168.  
  169. Setting up the sample databases for the twophase example:
  170.  
  171.     1. Set up the SYBASE environment variable using the
  172.        following command:
  173.  
  174.         source /usr/sybase/scripts/SetVars
  175.         
  176.     2. Create a new entry in /usr/sybase/interfaces file for the
  177.        server named SERVICE.  See the Install Guide for
  178.        information on adding entries to the interfaces file.
  179.  
  180.     3. Find enough space for a 16M database device on your
  181.        disk.
  182.  
  183.     4. Using "installsample", create a new database device and
  184.        start a server named SERVICE using the command:
  185.  
  186.        $SYBASE/sample/dblibrary/installsample \
  187.             <SERVICE_device_name> SERVICE
  188.  
  189.        where SERVICE_device_name is the full pathname for
  190.        the database device to be installed.  We recommend
  191.        that you always name database devices with a
  192.        .sdb extension.  Note that this device must have
  193.        a different name from the PRACTICE device.
  194.  
  195.     5. Set the DSQUERY environment variable to point to
  196.        the PRACTICE server.  This is the necessary DSQUERY
  197.        setting for running "twophase":
  198.  
  199.        setenv DSQUERY PRACTICE
  200.  
  201.     6. With both the PRACTICE and SERVICE servers installed
  202.        and running, you are now set up to run "twophase".
  203.  
  204.   To compile and run twophase:
  205.  
  206.       1. You must login as 'sybase' in order to compile twophase.
  207.  
  208.         2. Change to the /usr/sybase/sample/dblibrary directory using:
  209.     
  210.            cd /usr/sybase/sample/dblibrary
  211.     
  212.       3. Set the SYBASE environment variable to the sybase root directory
  213.          using the following command:
  214.        
  215.        setenv SYBASE /usr/sybase
  216.         
  217.     4. Compile and link the source file using shared libraries:
  218.  
  219.           make twophase
  220.  
  221.     5. To run twophase, type:
  222.  
  223.         twophase
  224.             
  225.        The correct, exciting output for twophase is:
  226.   
  227.             Demo of Two Phase Commit
  228.             We made it!
  229.  
  230. To stop the servers, use:
  231.  
  232.     $SYBASE/install/stopserver PRACTICE
  233.     $SYBASE/install/stopserver SERVICE
  234.                 
  235.             
  236. Notes:
  237.  
  238.   This section describes the requirements for the sample databases used
  239.   by the DB-Lib examples.  If you have followed the previous instructions for 
  240.   installing the sample databases using the "installsample" script, then
  241.   you have performed all the required database initialization described here.
  242.  
  243.     These examples have "hard-coded" a server password
  244.     "server_password" in the source.  Make sure that the password
  245.     for your server login on any server used when running the
  246.     examples is "server_password".  (The two-phase commit
  247.     example requires two servers.) By default, the DB-Library
  248.     routines use the UNIX login name to determine who you are
  249.     and how to log you on.
  250.  
  251.     Each server used with the examples must contain the "pubs"
  252.     database.  This database is used by Example 3 and the
  253.     two-phase commit example.  The minimum size for the database
  254.     device is 14M, which includes "model", "pubs", and enough
  255.     space to create the "test" database.
  256.  
  257.     Example 2 requires that you have 'create database' permission.
  258.     The example creates database "test".
  259.  
  260.     Example 6 requires that you have 'create table' permission.  
  261.     The example creates the table "alltypes" in your default
  262.     database.
  263.  
  264.     Example 7 prompts the user for an ad hoc query.  Notice
  265.     how the results differ depending on whether the SELECT
  266.     query includes the keywords FOR BROWSE and whether the
  267.     table SELECTed is browsable.
  268.  
  269.     Example 8 assumes you have created the stored procedure
  270.     "rpctest" in your default database.  The comments at the
  271.     top of the Example 8 source code specify the CREATE PROCEDURE
  272.     statement necessary for creating "rpctest".  This SQL
  273.     statement is also specified in the "installsample" script.
  274.  
  275.     The two-phase commit example requires two servers.  See
  276.     the Twophase Example Setup for a complete description of
  277.     the requirements for running this example.  The example
  278.     has "hard-coded" server names SERVICE and PRACTICE which
  279.     must be in the interfaces file.
  280.  
  281.     The programs are well commented; take a look before you
  282.     run them if you'd like more details.
  283.  
  284.