                       **  P g b a s h  **

Outline 
-------

1.Database Interface 
  Pgbash has "Direct/Embedded SQL" interface for PostgreSQL-7.0/7.1/7.2.
  Here, "direct SQL" means the functionality which execute immediately 
  and outputs the results to standard output, if SQL is inputted. 
  And, "Embedded SQL" means the functionality which sets the retrieval 
  result into the shell variables which are processed by using shell 
  script language.  Pgbash can use SELECT_INTO or FETCH_INTO statement 
  as "Embedded SQL" interfaces. 

2.Processing method of SQL
  Pgbash deals with a SQL statement as a shell command. In short, if 'SQL;' 
  is inputted, 'exec_sql "SQL"' is executed. Therefore, Pgbash can execute 
  a SQL with pipeline, redirection and background_job options. 

3.Login shell or Sub shell
  It is possible to start Pgbash as a LOGIN_shell or a SUB_shell. Here, 
  a SUB shell is a child shell started from a parent shell. If you want 
  to start Pgbash as a SUB shell, you type only e.g. '/usr/local/bin/pgbash' 
  after log-in. 

  If you start Pgbash as a LOGIN_shell, the logout may be done when there 
  are some database troubles. Considering such fact, it would generally be 
  better that Pgbash is used as a SUB shell. 

4.Shell script and Web application
  You can make a shell script with SQL and the control statements such as 
  IF/WHILE and the shell variables using Pgbash. Pgbash has the functionality 
  of inputting data from GET/POST method and ouputting data to HTML table, 
  in order to use a shell script as a Web application. 

  The load of the server is higher on the CGI program using Pgbash than 
  on the PHP which is a built-in module of the web server software. So, 
  Pgbash is suited for a Web application of a few access, or a prototype 
  system before making a real Web application. 

5.Operation environment
  Pgbash needs the libpq library of PostgreSQL. So, you must describe the
  path of libpq library in the parent shell. And, Pgbash needs Pgbashrc when 
  Pgbash starts in the interactive environment. 

  (What is Pgbashrc)

  Pgbashrc is the pgbash shell startup file which sets the various commands
  for displaying the database information. Pgbash can either use a original 
  Pgbashrc file or modified Pgbashrc file. 

  When Pgbash starts in the interactive environment, Pgbash reads ~/.pgbashrc
  file. And, If ~/.pgbashrc file does not exist, then Pgbash reads /etc/pgbashrc
  file. If Pgbash starts as a shell script, Pgbash does not read Pgbashrc file.
  Therefore, If you want to read Pgbashrc file, You must use 'source' command 
  to read Pgbashrc file. 

  When Pgbash starts, Pgbash receives the environment variables from the parent
  shell. Therefore, ~/.bashrc file is not needed. If ~/.bashrc exists, Pgbash
  reads Pgbashrc file after reading ~/.bashrc. 


(Example in the interactive environment)
 ========================================================================
 prompt> /usr/local/bin/pgbash              --- Start Pgbash as sub-shell
 Welcome to Pgbash version 2.4a.1 ( bash-2.05a )

   Type '?' for HELP. 
   Type 'connect to DB;' before executing SQL.
   Type 'SQL;' to execute SQL.
   Type 'exit' or 'Ctrl+D' to terminate Pgbash.

 pgbash> connect to db2@xxx.com user sakaida;  --- connect to db2
 pgbash> connect to db3@yyy.com user postgres; --- connect to db3
         .......
 pgbash> set connection db2;                   --- sets db2 as current DB
 pgbash> addr='OSAKA'                               
 pgbash> insert into test values(              --- new line
 >  111,'name',
 > '$addr'                                     --- use a shell valiable
 > ); 
 
 pgbash> select * from test limit 100; | more  --- pipeline
         .......
 pgbash> select * from test; > /tmp/sel.dat &  --- redirect + background_Job
 pgbash> cat /tmp/sel.dat
         .......
 pgbash> set connection db3;                   --- sets db3 as current DB
 pgbash> select * from test limit 100; | more  
         .......
 pgbash> fc select                             --- edit and execute a Select
         .......
 pgbash> !!                                    --- re-execute a Select
         .......
 pgbash> disconnect all;                       
 pgbash> exit                                 --- end of Pgbash
 ========================================================================

(Example of a shell script)
 ========================================================================
 #!/usr/local/bin/pgbash
 connect to dbname2 as db2 user postgres; 
 begin;
 declare cur cursor for select * from test; 
 while [ 1 ]
 do
    fetch in cur into :AA :AA_IND, :BB;        --- sets shell variables
    if [ $SQLCODE -eq $SQL_NOT_FOUND ]; then   --- end of a Fetch
       break  
    fi
    if [ $SQLCODE -eq $SQL_OK ]; then          --- normal end
       if [ $AA_IND -ne $SQL_NULL ]; then      --- AA is not NULL
          echo "$AA, $BB"
       fi
    fi 
 done
 end;
 disconnect db2; 

 # Here, $SQL shell variables are reserved.
 #  $SQLCODE       --- status parameter
 #  $SQL_OK        --- NORMAL END code value
 #  $SQL_NOT_FOUND --- NOT FOUND code value
 #  $SQL_NULL      --- NULL code value
 ========================================================================


Features
--------

Interactive environment.
  1.Pgbash has a database accessing function equivalent to psql. 
  2.Pgbash can set up a user's original interactive environment using pgbashrc. 
  3.Pgbash can offer flexible interactive environment, such as alias, function, 
    and history. 
  4.Pgbash can execute the SQL statement with pipeline, redirection and 
    background_job options. 

Extension of SQL. 
  1.Pgbash can connect to some databases by using CONNECT, DISCONNECT and 
    SET CONNECTION.
  2.Pgbash has the functionality which sets the retrieval result into the 
    shell variable by using SELECT_INTO/FETCH_INTO statements. 
  3.Pgbash implements the original COPY function which not only a postres 
    super user but a general user can copy. 
  4.Pgbash keeps the error code after SQL execution, the number of tuples 
    as a result of SELECT, the number of colums and the number of records, 
    to a shell variable. Therefore, it is possible to know the condition 
    after the SQL execution. 

Web application. 
  1.Pgbash has the functionality of changing HTML output mode, reading data
    from GET/POST method and reading values from HTTP_COOKIE. 
  2.Pgbash can print the retrieval results as HTML table format. And, Pgbash
    can change TABLE tag, HEADER tag, TR tag, TH tag, TD tag. 

History
-------

  1999.07.01 : An interface is discussed at pgsql-jp ML.
  1999.07.15 : KUBO Takehiro-san opened pqbash to the public.
  1999.07.30 : The examination pf pgbash was started.
  1999.08.31 : SAKAIDA Masaaki opened pgbash-1.0-beta to the public.
  1999.09.04 : The examination of pgbash-1.1 was started.
  1999.09.06 : pgbash-1.0b2 released.
  1999.10.01 : pgbash-1.1.1 released.
  1999.10.30 : pgbash-1.2.1 released.
  1999.10.31 : pgbash-1.2.2 released.(pgbash-1.2.1 bug fix)
  1999.11.22 : pgbash-1.2.3 released.
  1999.12.25 : pgbash-2.0 released(bash-2.03 main body was patched) 
  2000.01.11 : pgbash-2.0.1 released(MB functions, System messages) 
  2000.05.10 : pgbash-2.1 released 
  2001.05.01 : pgbash-2.2 released(for bash-2.03/2.04/2.05)
  2001.12.31 : pgbash-2.4 released(for PostrgeSQL-7.2)
  2002.02.10 : pgbash-2.4a released(for bash-2.05a)
  2002.05.10 : pgbash-2.4a.1 released
  2002.07.22 : pgbash-2.4a.2 released


Download
--------
  http://www.psn.co.jp/PostgreSQL/pgbash/pgbash-2.4a.1.tar.gz
  ftp://ftp.psn.ne.jp/pub/PostgreSQL/pgbash/pgbash-2a.1.4.tar.gz


HomePage
--------

  English:
    http://www.psn.co.jp/PostgreSQL/pgbash/index-e.html
  Japanese:
    http://www.psn.co.jp/PostgreSQL/pgbash/index-j.html


Questions or bug reports
------------------------

    If you have any questions or bug reports, please send them to
  SAKAIDA Masaaki.

--
SAKAIDA Masaaki<sakaida@psn.co.jp>
Osaka, Japan
# Sorry, I am not good at English. ;-)
