5.1 Introduction
This section describes, in alphabetical order, commands available in UNIBASE.
5.1.1 Manual Page Command Syntax
Unless otherwise noted, commands described in the SYNOPSIS section of a manual page accept options and other arguments according to the syntax and should be interpreted as explained below:
name [-option…][cmdarg…]
where
[ ] Surrounding an option or cmdarg that is not required
… Indicates multiple occurrences of the option or cmdarg.
name the name of the executable file
option (Always proceeded by a “-“).
noargletter… or argletter optarg[,…]
noargletter A single letter representing an option without an option argument. Note that more than one noargletter option can be grouped after one “-“.
argletter A single letter representing an option requiring an option argument
optarg An option argument (character string) satisfying a preceding argletter. Note that groups of optarg’s following and argletter must be separated by commas or separated by a white space and quoted.
cmdarg Pathname (or other command argument) not beginning with “-“.
5.1.2 Environment Variables
UNIBASE will substitute environment variables for their values as it is reading dictionaries or format files. If the variable is not defined then it is copies as is for later substitution by eg. A shell.
Using Environment Variables is a good way to get a customised application without writing separate programs.
UBERROR File for logging UNIBASE errors
UID User Login ID
PRINT Print Screen Command
TERM Terminal Type
MAIL See Mail (section )
MAIL CECK See Mail (section )
MAILER See Mail (section )
MAILPROGS See Mail (section )
MAXIDLE Idle time (no keystrokes) before terminal locked
UBDIR Location of UNIBASE configuration files (default /usr/lib/ub)
DICTIONARY Name of data dictionary file (default dict.dat)
TTY Terminal Line
UBPG Program to use for screen out put (default pg)
5.1.3 Included Files
UNIBASE can be directed to read from another file at any time by placing a line starting with ‘@’ in the input file. The remainder of the line (after skipping any spaces or tabs) is the name of the file to read for input. The file name is determined after any environment variable substitutions have been completed.
Include files can be used in the Data Dictionary, screen formats, report formats, etc.
@format.loc
Will direct UNIBASE to read from the file “format.loc” before reading the rest of the current file.
Include can be nested.
WARNING: – No check is done on recursive calls.
5.1.4 Line Draw Graphics
ubmulti, ubprompt and ubreport all recognise the following conventions from putting line drawing on the screen:
– in the first column, draw a line across the screen
~ draw a horizontal line
| draw a vertical line
Additionally these programs will adjust the graphics to include corners, tees, crosses etc as required.
5.1.5 Mail
UNIBASE can check form mail in much the same way as the shell. It is controlled by the same environment variables plus a few extras to extend the functionality of the mail system.
5.1.5.1Mailcheck
The time in seconds between checks for incoming mail. It must be given to enable the mail checking routines. The last time mail was checked is stored in a file called /tmp/mail/<process group id> so these variables will work even if the user is not in a single grogram for MAILCHECK seconds.
5.1.5.2 Mailpath
‘:’ separated list of files to check.
NB. Each name can be followed be a ‘%’ and a message to be used instead of default “you have mail”.
Eg. MAILPATH=”/usr/mail/john%mailx:/usr/stocknew%newstock”
5.1.5.3 Mailer
Mail program to use to read mail, default is “mail”
Mailprogs
‘:’ separated list of programs to use. Each item in the list is a mail file followed by a ‘%’ followed by a program, to use to read mail from the mail file instead of the default “mail” or the default program defined in “MAILER”. There is no way to specify the mail file in the command aside from using its name.
5.1.6 Error Codes
NB. There are deliberate gaps in this list as not all codes have been allocated.
Not all errors cause a message including an error code to be printed. This section describes the codes that may be returned by an error. Many of the codes are self-explanatory. Codes marked RESERVED are codes used internally by UNIBASE and should not be seen by programmers or users.
To see the line in a program/dictionary that caused an error, call the program specifying the –d flag. (see section )
All program errors are recorded in a file “.uberror” in the directory where the program executes. (see uberror XXX) for the format of this file.
As this file can grow it is good practice to examine it and remove it on a regular basis. For remote maintenance, it could be emailed to the support site.
| 1. | OPERATING SYSTEM ERROR An operating system call has returned an error. This error is not usually reported as such, instead the operating system error code is reported. Most Unix Systems list these in the intro. |
| 2. | UNEXPECTED END OF FILE End of file was reached while reading a record. This error usually indicated a corrupt key file and the table is question should be rebuilt. Fortunately it is not often encountered and is most likely to be seen after an abnormal systems shutdown. |
| 3. | NO FILE NAME ENTRY A table has been referenced that does not exist in the Data Dictionary |
| 4. | ACCESS PERMISSION DENIED A user has tried to access a file to which they have no access permission |
| 5. | RESERVER |
| 10. | NO DICTIONAY AVAILABLE The program cannot find a Data Dictionary ie. There is not a file called dict.dat in the current directory and the environment variable DICTIONARY does not exist and in some cases there is no “D” option specified in the command line. |
| 11. | NO TABLE NAME WHERE ONE WAS EXPECTED |
| 12. | DICTIONARY NOT LOADED This is an internal error and should be reported to Zenucom |
| 13. | TABLE NOT DEFINED IN DICTIONARY A table has been referenced that does not exist in the Data Dictionary |
| 14. | COMMA (,) AFTER FIELD NAME MISSIN |
| 15. | INVALID OR MISSING FIELD SIZE |
| 16. | INVALID OR MISSING ARRAY SIZE |
| 17. | INVALID FIELD TYPE |
| 18. | RESERVED |
| 19. | TWO OR MORE ASSOCIATIONS BETWEE TABLES Only 1 association between two tables is meaningful. This error is often caused by declaring a field a Foreign Key filed (which implies an association) and also declaring the association in the association list. |
| 20. | NO FILE DESCRIPTION FOR TABLE You have too many files open. UNIBASE opens two files per table as required and tis error means it needs more file descriptors. Either reconfigure your kernel from more file descriptors (per user) or revise the application. |
| 21. | RESERVED |
| 22. | RESERVED |
| 30. | CAN’T FIND FIELD NAME IN TABLE DEFINITION |
| 31. | INVALID SUB FIELD START POSITION |
| 32. | INVALID SUB FIELD END POSITION |
| 33. | A DASH (-) WAS EXPECTED IN THE SUB FIELD DEFINTION |
| 34. | KEY NOT FOUND A screen, report, dump, etc has asked for a key ordering that it is not defined in the Data Dictionary. |
| 35. | INVALID SUB FIELD LENGTH |
| 40-52 | RESERVED |
| 60. | QUIT KEY USED TO EXIT |
| 61. | PASSWORD FAILED A password required was not entered correctly |
| 70. | OPERAND MISSING IN AN EXPRESSION Operands are numbers, fields, dates, strings and expressions surrounded by ‘(‘and’)’. |
| 71. | ADJACENT OPERATORS Two operators (+ – * / ^ etc) are next to each other in an expression |
| 72. | BINARY OPERATOR AFTER A UNARY OPERATOR A binary operator (+ – * etc) is placed after a unary operator (SIN, COS, ABS etc) |
| 73. | UNEXPECTED OPERATOR/OPERAND Whatever it was UNIBASE doesn’t like it. |
| 74. | NOT ENOUGH OR TOO MANY FIELDS IN AN OPTION |
| 80. | NO NAME GIVEN TO A COMMAND SECTION IN A MENU |
| 81. | NO OPTION IS A MENU |
5.2 ubaudit
ubaudit –log audit trail deatils
ubaudit –[a]
This program reads lines of input and logs them into the audit trail file ”/usr/adm/audit” which is not generally readable or writ5able, except to root (because it can’t be stopped) and members of the group “security”.
The format of “/usr/adm/audit” is:
A<identifier> : <sys time> : <usr> : <group> : \
<directory> : <tty> : <description> : <command>
{M<identifier> : <message>}
ubaudit reads standard input until end of file. Each line of input comprises a command (single letter) followed by data.
The commands are:
A – Audit Identifier
C – Command being Audited
D – Directory command ran in
F – Alternate audit files name instead of “/usr/adm/audit”
G – Group name of user
M – Rest of input is a message to store in the audit file
N – Notify user (may be repeated) by write or email is user is not logged on. If the first character of the user name is a “*” then the name is interpreted as a group name and all members of the group are notified.
T – tty the user was logged on
U – User name
X – Description of Audit Trail Entry
NB. The system time is given in tics as returned by time (2) and is determined by ubaudit. Any field not given is left empty.
When called with the –a flag, ubaudit writes a unique Audit Identifier to it output. This should be passed to any audit write request to ensure identification of a group of audit comments. In particular this can be used when audit comments might be written at different times even though they apply to the same event.
Audit trails have a habit of growing to excessive size. If using audit trails a policy for monitoring, archiving and resetting them should be developed at the same time, eg. cron can be set to mail the audit trail to a supervisor, archive and compress it and then remove it.
5.3 ubbatch
ubbatch – batch process data
ubbatch [-Dbcdqs] [-P pipe] [-e table] [-f separator] [-n number] table
ubbatch is used to batch load data into a UNIBASE file. Each input record is in the same format as the record stored in the UNIBASE file. This means that expressions and unions must not be part of the input record. Records are lines of text terminated by line feeds. Each field is the same width as the width in the Data Dictonary.
Command line options are:
-D This option allows for the alternative date format YYMMDD. Normally, all dates are expected to be in the format DD.MM.YY (or DD/MM/YY). Using this option reads dates in the alternative format.
-P pipe ubbatch will read its input from the named pipe pipe. To do this ubbatch becomes a daemon and continuously reads pipe. It must be manually killed to terminate it. The named pipe must exist before ubbatch is called, it will not create it if it does not exist.
-b This option allows ubbatch to read UDF (Universal Dump Format) dump formats. In this format each record is a line of ASCII text. Fields are separated by commas with “ “ surrounding the text and date fields, but not numbers.
eg. “FRED SMITH”,”10 JOHN STREET”,”TOWN”,49,3.72
-c Only print a total count of the records processed. This option will suppress the normal “Records Processed” message that is printed every ten records and will instead print a single number being the total records processed.
-d This option gives a debug output. As ubbatch reads the Data Dictionary each line is echoed to the screen. In this way the exact point at which an error occurs can be observed and corrected.
-e file Records that can’t be written because of some error are normally written to the standard output. With this option they are saved in file.
-f separator Instead of fixed length input records, this option allows for variable length records with each field separated by a field separator, which in the example below is the character “:”
ubbatch –f :stock <stock.txt
-n number Print record count every number records instead of default 10.
-q Quiet mode. When this flag is given ubbatch doesn’t write any output.
-s This causes ubbatch to allocate new sequence numbers when it adds records to the file.
To batch lines of text in a standard text file called “sales.txt” to a UNIBASE file called “sales”:
ubbatch sales <sales.txt
When ubbatch is running it normally outputs a message every 10 records:
Records processed: 10
5.4 ubcheck
ubcheck – exhaustively check UNIBASE tables for structure errors
ubcheck <directory><application>{<table>}
ubcheck will exhaustively check every UNIBASE table in a directory for errors. Any errors are logged in a file called .filecheck in <directory>. An existing .filecheck is removed before the testing begins.
As ubcheck is exhaustive it can take a long time and is best run as an overnight process.
NB. The UNIBASE routines are very robust and tables are not normally corrupt except by machine failures, which are usually detected by a redundancy check every time a table is opened. This utility simply provides an extra level of assurance.
<directory> Directory to be tested.
<application> Application to be tested
<table> Optional table if only one table, rather than all tables, is to be tested.
5.5 ubcp
ubcp –copy one UNIBASE table to another
ubcp table1 [table2…] target
ubcp copies UNIBASE table (“.dat” and “.key” files) to a target name, table1 and target can not be the same. If target is an existing table, the contents of both of its “.dat” and “.key” files are going to be overwritten, but the mode, owner