PrimeBase™ Automation Client
What is the PrimeBase Automation Client (PBAC):
PBAC is a multi functional tool. In its simplest mode it is an interactive PBT client which can execute programs interactively on a PrimeBase™ data server or open server. In other modes PBAC can be used to execute a script at a specified time each day or be made to execute scripts as they appear in a specified directory. In all modes it is possible to have PBAC run in the background and use the PrimeBase™ console program; pbcon, to communicate with it. The mode in which PBAC runs is controlled by command line parameters which can either be passed in on the command line or placed in a file called "PBAC.cfg" which PBAC will look for in its current working directory and read if no command line parameters are given. The following explains the possible command line options.
PBAC Command Line Options:
PBAC [ -a <server alias> [ -b ]] [ -c ] [ -n <client_name>] [ -u <user>] [ -p <password>] [ -l <log file>] ([ -i <interval>[s|m|h]] | [ -t <execute times> ]) [ -d <working directory>] [ -x] [ -s <script file> [ -e <entry function>]]
The following are valid command line options:
-a <server alias>: The alias of the server as specified in the connect.def file. If not specified a list of possible server aliases taken from the connect.def file will be displayed for the user to choose from.
-b : Background the client without starting a pbcon console session.
-c : Background the client and start a pbcon console session with it.
-n <client name>: If the client is to run in the background use this name for console access. The default is PBAC_ADMIN.
-u <user>: The user to be initially logged on as. If not specified the user specified in the connection definition from the connect.def file will be used.
-p <password>: The user's password. If not specified the password specified in the connection definition from the connect.def file will be used.
-x : Indicates that the client is to run in auto execute mode. If no "entry function" (see option -e) then PBAC will automatically execute any files in the "<working directory>" with the suffix ".dal".
If an "entry function" is specified the files found will not be executed but the name will be passed into the "entry function" as the last parameter to the function.
After processing the file, the file is deleted and the client waits for another file to process. While the file is being processed the name is changed to "*.dalX". On error the file is copied to <working directory>/notdone/*.dal.
The frequency with which the client checks for files can be controlled by the " -i" and " -t" options.
-s <script file>: The PBT script which is executed. If the "-e" option is used then this script is only executed once and the entry function will be used to execute the script.
-e <entry function>: The PBT procedure to call to execute the PBT script complete with any required parameters. In "execute mode" (see -x) the name of any file found will be passed in as the last parameter in the functions parameter list.
-l : The name to be given to the log file. If not specified the log file will have the same name as the script file, or executable if there is no script file, with a ".log" suffix added.
-d <working directory>: The working directory into which all files and logs are to be placed or ".dal" scripts read if the "-x" option has been specified. The "working directory" is set to. the current directory if not specified.
-i <interval>[s|m|h]: The interval at which the script is to be executed specified in seconds (default), minutes, or hours. If neither ' -i' or 't' are specified the default is to execute the script only once.
-t : Use this if you want the script to be executed at a specific times. If neither ' -i' or 't' are specified the default is to execute the script only once.
<execute times> : This is a string containing 5 fields separated by a "/" character. Each field must contain either a "*" indicating all possible values, one or more integers separated by a comma, or an inclusive range specified by 2 integers separated by a "-" (hyphen) character. The five fields are:
Minutes: (0-59) The minute(s) execution is to start.
Hour: (0-23) The hour(s) execution is to start.
Day of the month: (1-31) The day(s) of the month execution is to start.
Month: (1-12) The month(s) execution is to start.
Day of the week:(0-6 with 0= Sunday) The day(s) of the week execution is to start.
"10/8,20/*/*/1-4" : Executes at 8:10 and 20:10 Monday through Friday.
"0/1/1/*/1" : Executes at 1:00(am) the first of every month and Mondays.
"0/1/*/*/*" : Executes at 1:00(am) every day.
The syntax and behavior of this is meant to be the same as that of the UNIX crontab entries. On UNIX do a "man crontab" to find out more.
Setting Up Connections:
(Note: On the Mac you can also use the PrimeBase™ ConnectionSetup tool in the control panel to set up connection definitions.)
PBAC can be used to set up connection definitions in the connect.def file. PBAC will display the location of the connect.def file that it is using when started with out the -a option along with a list of defined connections. By entering an 'A', 'E', 'D', or 'T' you can add, edit, or delete an entry or move an entry to the top of the list. When you add an entry PBAC will ask you to enter the data required to define a connection. If you edit an entry PBAC will ask the same questions as if it were creating a new entry but will supply the current settings as defaults where applicable. The questions asked will vary from platform to platform .
The following is an example of a session in which a new connection definition is being set up to connect over TCP to a PrimeBase™ data server called "Prime1". The text in bold and in () brackets are comments that have been added for this example. The text in bold but not in brackets is text entered into the PBAC session.
============= Begin Example ========================
PrimeBase Automation Client. Copyright 2008, PrimeBase Systems GmbH. Web: http://www.primebase.net E-mail: email@example.com Select a connection by number, and Login: Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry. Or enter 'T' to move an entry to the top of the list. File: ./setup/connect.def Alias Protocol Server -------------------- -------------------- -------------------- 0 (exit without connecting) 1 no_server TCP/IP PrimeServer 2 local_server TCP/IP PrimeServer 3 remote_server TCP/IP PrimeServer ----------------------------------------------------------------- Connection..: a To create or edit a connection entry answer the following questions. When you have answered all the questions you will be given the option of saving, canceling or re-entering your changes.
Enter the connection alias.: my_example
(This is the alias that this connection will be accessed via.) Is this a runtime server connection? [Y/N]: : n Select the brand to use from the following list: 1 : Database Server 2 : Open Server Use brand number: 1 The DBMS server's name: Prime1 Select a communications protocol from the following list: 1 : TCP/IP 2 : Shared Memory Use protocol number: 1 The server address for TCP: sun1.PrimeBase.net User's name for logging into the DBMS server (optional): administrator User's password for server login (optional): (If you give a user and password with the connection set up then all you will be required to give to open the connection will be the connection alias. The password is store as plain text in the connect.def file so if you are concerned about it's security then do not enter the password.) The default database (optional): (If you specify a database here it will be opened automatically when the connection is established.) Do you want to save the connection information? [Y/N]: : y Alias Protocol Server -------------------- -------------------- -------------------- 0 (exit without connecting) 1 no_server TCP/IP PrimeServer 2 local_server TCP/IP PrimeServer 3 remote_server TCP/IP PrimeServer 4 my_example TCP/IP Prime1 ----------------------------------------------------------------- Connection..:
============= End Example ========================