Added command-line documentation from Louis Moore.

git-svn-id: https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/trunk@742 4979c152-3d1c-0410-bac9-87ea11338e46
author: einhverfr <einhverfr@4979c152-3d1c-0410-bac9-87ea11338e46> 2006-12-07 19:30:21 +0000
committer: einhverfr <einhverfr@4979c152-3d1c-0410-bac9-87ea11338e46> 2006-12-07 19:30:21 +0000
commit: dee2efb4095eea720dba50fb1115dd41b3f2be14 (patch)
tree: c25abf21eb0a8ea3cf8303d55af6e0906b78b39e /doc
parent: 20e0d5dc6e0d1bc8c224593fd08141349acec727 (diff)
3 files changed, 533 insertions, 2 deletions
diff --git a/doc/manual/LedgerSMB-manual.tex b/doc/manual/LedgerSMB-manual.tex
index 2e006554..0a620206 100644
--- a/doc/manual/LedgerSMB-manual.tex
+++ b/doc/manual/LedgerSMB-manual.tex
@@ -22,8 +22,6 @@
 \usepackage{metatron}
 
 \renewcommand{\abstractname}{Executive Summary}
-\newcommand{\mycustomer}[1][]{#1\space}
-\newcommand{\myproject}[1][]{#1\space}
 \title{Ledger-SMB Manual v. \version}
 \author{The LedgerSMB Core Team}
 \date{\today}
@@ -2297,6 +2295,332 @@ that was showing up before an upgrade stops showing up, one can either
 upgrade the templates by copying the source template over the existing
 one, or one can edit the template to make the change.
 
+\section{An Introduction to the CLI}
+
+\subsection{Conventions}
+
+The command-line API will be referred to as the API.
+
+\subsection{Preliminaries}
+
+Logging into Ledger-SMB (1.2+) updates a row in the users\_conf table
+containing your account configuration defaults and other information. 
+The implication for API users of LSMB is that you must login as part 
+of running API scripts. For security purposes, it is recommended that
+scripts prompt for a password rather than storing it.
+
+All scripts included in the documentation can also be found in the doc/samples
+directory.
+
+Consider a simple example:
+
+ cd /usr/local/ledger-smb
+./ct.pl "login=name\&path=bin\&password=xxxxx\&action=search\&db=customer"
+
+The cd command moves your terminal session's current working directory into
+the main Ledger-SMB directory. Then the Ledger-SMB perl script ct.pl is called 
+with one long line as an argument. The argument is really several variable=value pairs
+separated by ampersands (\&). The value for the login variable is the username
+that Ledger-SMB is to use, and the value for the password variable is the plaintext password.
+
+To build our examples we will use a username of "clarkkent" who has a password
+of "lOis,lAn3".
+
+ cd /usr/local/ledger-smb
+./ct.pl "login=clarkkent\&path=bin\&password=lOis,lAn3\&action=search\&db=customer"
+
+If we execute these commands we will get the html for the search form for 
+the customer database. This result isn't useful in itself, but it shows we 
+are on the right track.
+
+
+\subsection{First Script: lsmb01-cli-example.sh}
+
+With a working example, we can start to build reproducible routines that we can grow
+to do some useful work.
+
+This is a bash script which:
+
+ 1. sets NOW to the current working directory
+ 2. prompts for and reads your Ledger-SMB login
+ 3. prompts for and reads (non-echoing) your Ledger-SMB password
+ 4. changes directory to /usr/local/ledger-smb
+ 5. constructs login and logout commands and a transaction command
+ 6. logins into ledger-smb (in a real program, output would be checked for
+    success or failure)
+ 7. executes the transaction
+ 8. logs out of ledger-smb (although this is not necessary)
+ 9. returns to the original working directory
+10. exits
+
+Running lsmb01-cli-example.sh produces:
+
+\$ lsmb01-cli-example.sh 
+
+Ledger-SMB login: clarkkent
+
+Ledger-SMB password: 
+
+\begin{verbatim}
+<body>
+
+<form method=post action=ct.pl>
+
+<input type=hidden name=db value=customer>
+
+<table width=100%>
+  <tr>
+    <th class=listtop>Search</th>
+.
+.
+.
+\end{verbatim}
+
+A script like this would work well for simple batch transactions, but
+bash is not a very friendly language for application programming.
+
+
+A nicer solution would be to use a language such as perl to drive the
+command line API.
+
+\subsubsection{Script 1 (Bash)}
+\begin{verbatim}
+#!/bin/bash
+#######################################################################
+#
+# lsmb01-cli-example.sh
+# Copyright (C) 2006. Louis B. Moore
+#
+# $Id: $
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+#######################################################################
+
+NOW=`pwd`
+
+echo -n "Ledger-SMB login: "
+read LSLOGIN
+echo
+
+echo -n "Ledger-SMB password: "
+stty -echo
+read LSPWD
+stty echo
+echo
+
+ARG="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=search&db=customer"
+
+LGIN="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=login"
+LGOT="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=logout"
+
+cd /usr/local/ledger-smb
+
+./login.pl $LGIN 2>&1  > /dev/null
+./ct.pl $ARG
+./login.pl $LGOT 2>&1  > /dev/null
+
+cd $NOW
+
+exit 0
+\end{verbatim}
+
+
+\subsection{Second Script: lsmb02-cli-example.pl}
+
+Our second script is written in perl and logs you in but it still uses the API 
+in its simplest form, that is, it builds commands and then executes them. This 
+type of script can be used for more complex solutions than the simple bash script 
+above, though it is still fairly limited. If your needs require, rather than have 
+the script build and then execute the commands it could be written to generate a 
+shell script which is executed by hand. 
+
+This script begins by prompting for your Ledger-SMB login and password. Using
+the supplied values a login command is constructed and passed into the runLScmd
+subroutine. runLScmd changes directory to /usr/local/ledger-smb/ for the length 
+of the subroutine. It formats the command and executes it and returns both the 
+output and error information to the caller in a scalar.
+
+The script checks to see if there was an error in the login, exiting if there was.
+
+Next, the script reads some records which are stored in the program following the
+\_\_END\_\_ token. It takes each record in turn, formats it then feeds each transaction
+through runLScmd and looks at the results for a string that signals success.
+
+Once all the transactions are processed, runLScmd is called one last time to
+logout and the script exits.
+
+\subsubsection{Script 2 (Perl)}
+\begin{verbatim}
+#!/usr/bin/perl -w
+#
+#  File:         lsmb02-cli-example.pl
+#  Environment:  Ledger-SMB 1.2.0+
+#  Author:       Louis B. Moore
+#
+#  Copyright (C)   2006  Louis B. Moore
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+#  Revision:
+#       $Id$
+#
+#
+
+use File::chdir;
+use HTML::Entities;
+
+
+print "\n\nLedger-SMB login: ";
+my $login = <STDIN>;
+chomp($login);
+
+
+print "\nLedger-SMB password: ";
+system("stty -echo");
+my $pwd = <STDIN>;
+system("stty echo");
+chomp($pwd);
+print "\n\n";
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=login';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+	print "\nLogin error\n";
+	exit;
+
+}
+
+
+while (<main::DATA>) {
+
+	chomp;
+	@rec = split(/\|/);
+
+	$arg = 'path=bin/mozilla&login=' . $login . '&password=' . $pwd .
+		'&action='       . escape(substr($rec[0],0,35)) .
+		'&db='           . $rec[1] .
+		'&name='         . escape(substr($rec[2],0,35)) .
+		'&vendornumber=' . $rec[3] .
+		'&address1='     . escape(substr($rec[4],0,35)) .
+		'&address2='     . escape(substr($rec[5],0,35)) .
+		'&city='         . escape(substr($rec[6],0,35)) .
+		'&state='        . escape(substr($rec[7],0,35)) .
+		'&zipcode='      . escape(substr($rec[8],0,35)) .
+		'&country='      . escape(substr($rec[9],0,35)) .
+		'&phone='        . escape(substr($rec[10],0,20)) .
+		'&tax_2150=1' .
+		'&taxaccounts=2150' .
+		'&taxincluded=0' .
+		'&terms=0';
+
+	$rc=runLScmd("./ct.pl",$arg);
+
+	if ($rc =~ m/Vendor saved!/) {
+
+		print "$rec[2] SAVED\n";
+
+	} else {
+
+		print "$rec[2] ERROR\n";
+
+	}
+
+}
+
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=logout';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+    print "\nLogout error\n";
+
+}
+
+exit;
+
+
+#*******************************************************
+# Subroutines
+#*******************************************************
+
+
+sub runLScmd {
+
+    my $cmd  = shift;
+    my $args = shift;
+    my $i    = 0;
+    my $results;
+
+    local $CWD = "/usr/local/ledger-smb/";
+
+    $cmd = $cmd . " \"" . $args . "\"";
+
+    $results = `$cmd 2>&1`;
+
+    return $results;
+
+}
+
+sub escape {
+
+    my $str = shift;
+
+    if ($str) {
+
+	decode_entities($str);
+	$str =~ s/([^a-zA-Z0-9_.-])/sprintf("%%%02x", ord($1))/ge;
+    }
+
+    return $str;
+
+}
+
+
+#*******************************************************
+# Record Format
+#*******************************************************
+#
+# action | db | name | vendornumber | address1 | address2 | city | state | zipcode | country | phone
+#
+
+__END__
+save|vendor|Parts are Us|1377|238 Riverview|Suite 11|Cheese Head|WI|56743|USA|555-123-3322|
+save|vendor|Widget Heaven|1378|41 S. Riparian Way||Show Me|MO|39793|USA|555-231-3309|
+save|vendor|Consolidated Spackle|1379|1010 Binary Lane|Dept 1101|Beverly Hills|CA|90210|USA|555-330-7639 x772|
+
+ 	  	 
+\end{verbatim}
+
+
 \clearpage 
 
 
diff --git a/doc/samples/lsmb01-cli-example.sh b/doc/samples/lsmb01-cli-example.sh
new file mode 100644
index 00000000..1a95dc8a
--- /dev/null
+++ b/doc/samples/lsmb01-cli-example.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+#######################################################################
+#
+# lsmb01-cli-example.sh
+# Copyright (C) 2006. Louis B. Moore
+#
+# $Id: $
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+#######################################################################
+
+NOW=`pwd`
+
+echo -n "Ledger-SMB login: "
+read LSLOGIN
+echo
+
+echo -n "Ledger-SMB password: "
+stty -echo
+read LSPWD
+stty echo
+echo
+
+ARG="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=search&db=customer"
+
+LGIN="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=login"
+LGOT="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=logout"
+
+cd /usr/local/ledger-smb
+
+./login.pl $LGIN 2>&1  > /dev/null
+./ct.pl $ARG
+./login.pl $LGOT 2>&1  > /dev/null
+
+cd $NOW
+
+exit 0
+
+
+ 	  	 
diff --git a/doc/samples/lsmb02-cli-example.pl b/doc/samples/lsmb02-cli-example.pl
new file mode 100644
index 00000000..e0084c01
--- /dev/null
+++ b/doc/samples/lsmb02-cli-example.pl
@@ -0,0 +1,155 @@
+#!/usr/bin/perl -w
+#
+#  File:         lsmb02-cli-example.pl
+#  Environment:  Ledger-SMB 1.2.0+
+#  Author:       Louis B. Moore
+#
+#  Copyright (C)   2006  Louis B. Moore
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+#  Revision:
+#       $Id$
+#
+#
+
+use File::chdir;
+use HTML::Entities;
+
+
+print "\n\nLedger-SMB login: ";
+my $login = <STDIN>;
+chomp($login);
+
+
+print "\nLedger-SMB password: ";
+system("stty -echo");
+my $pwd = <STDIN>;
+system("stty echo");
+chomp($pwd);
+print "\n\n";
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=login';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+	print "\nLogin error\n";
+	exit;
+
+}
+
+
+while (<main::DATA>) {
+
+	chomp;
+	@rec = split(/\|/);
+
+	$arg = 'path=bin/mozilla&login=' . $login . '&password=' . $pwd .
+		'&action='       . escape(substr($rec[0],0,35)) .
+		'&db='           . $rec[1] .
+		'&name='         . escape(substr($rec[2],0,35)) .
+		'&vendornumber=' . $rec[3] .
+		'&address1='     . escape(substr($rec[4],0,35)) .
+		'&address2='     . escape(substr($rec[5],0,35)) .
+		'&city='         . escape(substr($rec[6],0,35)) .
+		'&state='        . escape(substr($rec[7],0,35)) .
+		'&zipcode='      . escape(substr($rec[8],0,35)) .
+		'&country='      . escape(substr($rec[9],0,35)) .
+		'&phone='        . escape(substr($rec[10],0,20)) .
+		'&tax_2150=1' .
+		'&taxaccounts=2150' .
+		'&taxincluded=0' .
+		'&terms=0';
+
+	$rc=runLScmd("./ct.pl",$arg);
+
+	if ($rc =~ m/Vendor saved!/) {
+
+		print "$rec[2] SAVED\n";
+
+	} else {
+
+		print "$rec[2] ERROR\n";
+
+	}
+
+}
+
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=logout';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+    print "\nLogout error\n";
+
+}
+
+exit;
+
+
+#*******************************************************
+# Subroutines
+#*******************************************************
+
+
+sub runLScmd {
+
+    my $cmd  = shift;
+    my $args = shift;
+    my $i    = 0;
+    my $results;
+
+    local $CWD = "/usr/local/ledger-smb/";
+
+    $cmd = $cmd . " \"" . $args . "\"";
+
+    $results = `$cmd 2>&1`;
+
+    return $results;
+
+}
+
+sub escape {
+
+    my $str = shift;
+
+    if ($str) {
+
+	decode_entities($str);
+	$str =~ s/([^a-zA-Z0-9_.-])/sprintf("%%%02x", ord($1))/ge;
+    }
+
+    return $str;
+
+}
+
+
+#*******************************************************
+# Record Format
+#*******************************************************
+#
+# action | db | name | vendornumber | address1 | address2 | city | state | zipcode | country | phone
+#
+
+__END__
+save|vendor|Parts are Us|1377|238 Riverview|Suite 11|Cheese Head|WI|56743|USA|555-123-3322|
+save|vendor|Widget Heaven|1378|41 S. Riparian Way||Show Me|MO|39793|USA|555-231-3309|
+save|vendor|Consolidated Spackle|1379|1010 Binary Lane|Dept 1101|Beverly Hills|CA|90210|USA|555-330-7639 x772|
+
+
author	einhverfr <einhverfr@4979c152-3d1c-0410-bac9-87ea11338e46>	2006-12-07 19:30:21 +0000
committer	einhverfr <einhverfr@4979c152-3d1c-0410-bac9-87ea11338e46>	2006-12-07 19:30:21 +0000
commit	dee2efb4095eea720dba50fb1115dd41b3f2be14 (patch)
tree	c25abf21eb0a8ea3cf8303d55af6e0906b78b39e /doc
parent	20e0d5dc6e0d1bc8c224593fd08141349acec727 (diff)