NAME

query − interactive IMAGE database access

SYNOPSIS

query

HP-UX COMPATIBILITY

Level: HP-UX/NON-STANDARD

Origin: HP

Remarks: Query is implemented on the Series 500 only.  IMAGE must be previously installed on the system for query to function. 

DESCRIPTION

Query is an  interactive,  command  driven  program  to  simplify  IMAGE database  access.  It can be  used  to  generate reports from the database, add information to the database, change  information in the database, and aid in developing  programs that access  databases  using IMAGE library subroutines. 

Consistent with the HP-UX environment in which it operates, query is initiated by simply typing its name. There are no options or parameters.  Input and output redirection can be done at the shell level ( < > ) although more convenient methods are available via query commands. 

A list of the available commands:

data-base=helpexit!
listformfindxeq
update aupdate dupdate rreport

Query accepts these  commands in upper- or lower-case.  Special care must be taken in the case of set names,  item  names, and item  values  since these are case  sensitive.  That is, Setname,  setname,  and SETNAME are three unique sets. 

All query commands must be followed by a semicolon.  Query waits silently for a semicolon or a zero-length  record before processing  a  command.  A  zero-length  record  is  entered  as a solitary carriage  return.  This method of signaling  the end of a command line enables you to enter  commands  which are several  lines long.  Line length is limited to 256  characters.  At any point in a line, you may type a carriage return and continue the command line, thus improving the readability of long command lines. 

Once initiated, query identifies itself and gives the prompt:

NEXT? 

Whenever this prompt appears, you may enter any of the query commands, which are described below. 

DATA-BASE= The data-base= command opens a database.  You can type:

data-base=data_base_name;

where data_base_name is the name of a database.  If you are presently in the directory where the database exists, you need only give the database name. If the database is in another directory, you need to supply a partial or complete path name. 

Some examples are:

data-base=/users/fred/inventory;

specifies a database called "inventory" in the directory /users/fred. 

data-base=equipment;

specifies a database called "equipment" in the current directory. 

As part of the data-base= command, query asks for a password for that database with the prompt:

PASSWORD? 

The password is not echoed on the terminal as you type it.  As usual, the password must be followed by a semicolon. If no password is required, simply press RETURN. 

Provided the database name and password are valid, the database is opened with "modify shared" access (DBOPEN mode 1). The command prompt "NEXT?" appears. 

HELP The help command provides a syntax model, a brief description, and examples of itself or any other query command. It can be invoked in the following ways:

help [ command ];
   or
? [ command ];

where command is any query command.  If no command is supplied, help describes itself and gives a list of the commands for which help is available. 

EXIT The exit command provides you with a graceful way to terminate the query program. It is entered thus:

exit;

Query can also be terminated by hitting the BREAK key in response to a command prompt. 

!       
At any time, in response to a "NEXT?" prompt, you may wish to execute a shell command without leaving the query program. This is useful when debugging report procedure files from within query, or routing output files to a printer during a query session. For example:

!pr filename | lpr

runs the formatter/printer pr on a file called filename, and pipes the output into the lpr program. 

A shell command following an exclamation mark is executed, and query is suspended until that command is completed.  Query processing can be continued when the "[Hit return to continue QUERY]" message appears. 

LIST The list command is a convenient method of redirecting output from within the query program.  Query sends output to stdout (the input device) by default.  To send output elsewhere, type:

list=filename;

Output is sent to filename in the current directory. It may be sent to a file in another directory by specifying the desired pathname. 

An example is:

list=/usr/spool/uucppublic/report;

which specifies that the output file is /usr/spool/uucppublic/report. 

If query finds that the named file already exists, it prints the message:

FILE ALREADY EXISTS. (O)VERWRITE IT, (A)PPEND TO IT,
OR (N)EITHER ?

You type o, a, or n to select an option. If you choose n, query prompts:

NEW FILE NAME=

in response to which you provide a (presumably) different file name.  Otherwise, query overwrites or appends to the selected file, as instructed.  Output directed to a file is properly formatted for direct submission to lpr(1).  At any time during a query session, you may return output to the terminal by typing:

list;

This can be repeated as often as necessary, using the same file or many different files for output. When the list command appears in an XEQ file, no choices are offered. The specified file is silently opened and any output is appended to it. 

FORM The form command outputs a schema description for the open database. It lists each data set name, its type (automatic master, manual master, or detail), the set capacity, and the current number of entries in the set.  With each data set, each item is listed including its name, type (alphanumeric, integer, or real), length in bytes, and number of elements in the item.  Query also identifies key items, sort items (the sort item name may be truncated), and indicates whether you have write access for the item.  It is initiated by typing:

form;

Form’s output is directed to the file specified by the list command, or stdout by default. Its output can be terminated by hitting the BREAK key. Within a few seconds, output stops and a command prompt (NEXT?)  appears. 

FIND A major use of any query program is to search a database for an arbitrary group of entries meeting some criteria. Find is used in conjunction with the update or report commands, providing "victims" for the update or report. It is entered by typing:

find retrieve_procedure end;

where retrieve_procedure is a group of data item names, data item values, and relational operators joined together by logical connectors. 

A retrieve procedure defines a relationship between a data item and a data item value, and the find command collects entries which satisfy that relationship for later use by update or report.  A typical retrieve procedure looks like this:

[setname.]itemname operator "value"

where setname is the name of a data set which contains the data item.  It is always accepted, but is not necessary when the item name exists in only one data set, or when the set name has been previously established in the retrieve procedure.  Itemname is simply the name of a data item. For compound items, only the first element is used.  Operator is one of the following relational operators:

is, ie equal to

isnot, ine not equal to

ilt less than

inlt not less than

igt greater than

ingt not greater than

Value is enclosed in quotation marks ("") and is compared to the value of the named item for each entry in the specified (or implied) set. It should be appropriate for the data item type.

Two or more retrieve procedures can be joined by the logical operators and and or to make a more complex procedure.  Parentheses are not allowed in find procedures, so care should be taken in ordering statements in a compound retrieve procedure. 

Some examples are:

find inventory.quantity is "324" end;

searches all  entries in the  "inventory"  set for a "quantity"  equal to "324".  This  would be  appropriate for a quantity  of any type  (alphanumeric,  integer, or real). 

find part_description ie "widgit" end;

searches all  entries in the set which  contains  the item  "part_description"  for a value of  "widgit".  The value would obviously be inappropriate  for an item type of integer or real.  This example generates an error if "part_description"  exists  in more  than one set in the database. 

find inventory.quantity igt "324" and part_description isnot "widgit" end;

searches all entries in the set "inventory", collecting those that show a quantity greater than 324, excluding widgits. The items "quantity" and "part_description" must both be items contained in the set "inventory". 

XEQ The  xeq command  allows any number of  commands  to be read from a file created by any of the HP-UX editors. Commands  must appear in the file exactly as they would be entered  interactively,  one command per line.  The xeq command is entered:

xeq=filename;

The filename may be an absolute pathname, if necessary.  Query reads  commands from that file until it encounters either an end-of-file or another xeq command. When end-of-file is reached, query returns to an interactive state. When an xeq command is encountered within an xeq file, query closes the current xeq file and begins reading commands from the new one. The old one is not re-opened. Xeq files can be nested up to 10 deep. 

A few commands behave differently when they occur in an xeq file. The "list=file" command silently opens the specified file and appends data to it. The update mode of the update r command can be terminated only by a lone semicolon. (In interactive use, update r can be terminated by a semicolon or a zero-length record.) 

UPDATE A Update a (add)  adds  entries  to a data  set.  It is the only update  which  does not  require a  preceding  find.  The update add command is entered:

update a, setname;
   or
update add, setname;

Query checks the validity of the set name, and then prompts for item values one at a time. The item name is displayed followed by an "=".  The value to be assigned to that item should then be entered, enclosed in quotes, and followed by a semicolon.  Query then prompts for the next item value. Only one prompt is given for compound data items; the item values should be entered each in quotes, separated by commas. Null values may be entered by a lone carriage return in response to a prompt, but query insists on valid values for key items.  Addition of detail entries requires that values for key items already exist in the corresponding master set(s). 

The BREAK key can be used to abort an update a command. No update takes place, and a command prompt appears. 

UPDATE D Update d  (delete) deletes entries from a data set.  It  requires  a preceding find, and complains if not  satisfied.  The command is entered:

update d;
   or
update delete;

As a safety check, query asks "OK TO DELETE?(YES/NO)".  Upon receipt of a y or n, query proceeds as directed. It refuses to delete master set entries which contain chain heads with non-empty chains (i.e. connected detail sets), and displays a message to that effect. 

UPDATE R Update r (replace) also must be preceded by a find. It is a means of changing item values in an existing entry. It is invoked by typing:

update r;
   or
update replace;

Query responds with the prompt "ITEM =". You then enter:

item_name="value";

where item_name is an item name which exists in the entries in the select file.  Value is a value appropriate to the item type (alpha, integer, or real) enclosed in double quotes. 

When you have finished entering the changes desired, a lone carriage return or a lone semicolon exits this update mode, and query executes the changes and returns to the command level. (In an xeq file, only the semicolon suffices.) The new value(s) are inserted into all entries collected in the select file.  Updates are refused for key items and sort items in master sets. Updating key or sort items in detail sets causes that record to be deleted and re-entered with the new values. A report following such an update may give an "EMPTY RECORD" error message.  Don’t panic. The record may be found at its new location by a find command. 

The BREAK key can be used to abort an update r command.  No update takes place, and a command prompt appears. 

REPORT The report command provides many features to display  information  about the  entries in the select  file.  The  information  is sent to the list device  (the  input   device,  by  default).  Report’s   output  can  be terminated  by using the BREAK key, which yields a command  prompt (NEXT?).  You can request  the name and value of each data item for all the data  entries  specified  in the select file, or request the data item values for all of the data entries  without  printing the data item name.  Also you  may  create  output  formats  complete  with  page headings,  page numbers,  column  headings,  space and page control, and selectivity  in item  value  display.  Report can be  invoked  in one of three ways:

report all [,character];
   or
report name=procedure_name;
   or
report;
body
end;

where character is any ASCII printing character which determines the printing of certain optional information. 

Procedure_name is the name of a file (specified as a relative or absolute pathname) which contains report commands stored via a system editor, such as ed or vi. 

Body consists of header, detail, edit, and sort commands as outlined below. 

The three forms of the report command are described below. 

REPORT ALL [,CHARACTER]; prints the entire data item and all elements of a compound item. This report form prints the item name, followed by "=", followed by the item value. The optional character causes query to print only the item value, without the item name and "=". All item values appear left justified, and numbers are stripped of insignificant zeros. Real numbers may appear in decimal form or scientific notation, as necessary. This is the only report form which shows all values for compound data items. 

REPORT NAME=PROCEDURE_NAME; gets header, detail, edit, and sort commands from a file, reading commands until an "end;" or an error is encountered. The contents of a procedure file are identical to the "body" in the next form of the report command. It should be noted that the use of the shell escape (!) is a valuable aid in the development of procedure files. It enables you to invoke an editor, modify a file, exit it, and return to the same point in query to test the file, without having to re-define the database or re-establish a select file. 

REPORT;

BODY

END; accepts report commands from the user, scanning each line as it is entered for syntax errors. The entry of an "end;" command initiates the execution of the commands, producing a report. The body is a collection of the following commands:

Header Prints title, column headings, and page numbers at the top of each report page. 

Detail Prints data item values in the column position specified. 

Edit Describes the number of decimal places to be displayed for real numbers. 

Sort Sorts data entries based upon the value of a specified data item. 

Report Formatting

The above commands can be formatted using the following parameters.  (Note: these are parameters to the report commands, not commands themselves.) 

print position
Specifies the ending column for an item value or heading.

space and space control
Causes line skips between item values or heading lines.

skip and skip control
Causes page skips between item values or heading lines.

edit     
Specifies edit commands to which output item values should conform.

These parameters are described below. 

print position
This parameter is an integer between 1 and 132 which indicates the column number in which the last character of an item value should appear in a header or detail line. It is your responsibility to avoid overlap between fields on the same line. However, in most cases query replaces an overlapping value with asterisks to indicate an error. 

space and space control
This parameter outputs blank lines either before or after the printing of a header string or detail line value. The keyword space should be followed by either an a or b, indicating where the blank line should appear − after or before the line to be printed.  The a or b may be followed by an integer in the range 1 − 5, to skip multiple lines. Absence of the integer causes query to skip 1 line. These may appear more than once in a command, as in spacing before and after a line:

h1,"page",35,space b2,space a3;

This generates two blank lines before printing "page", and three blank lines afterward. 

skip and skip control
Similar to space, skip yields page feeds either before or after the printing of a line. Unlike space, skip can only be used with a "detail" command. The keyword skip is followed by an a or b to direct where the page feed should be placed (see "space and space control" above). Normally, query prints 54 lines per page before skipping to a new page. 

edit    
The edit parameter is the letter e followed by an integer in the range 0 − 9. This number corresponds to a numbered edit command which specifies the number of decimal places (for real numbers) or the number of characters (for alphanumeric strings) to be printed. 

Report Commands

h (header command)
The header command is used to print heading  information of your choice at the top of each page of the  report.  A maximum of five  lines of header  information  can appear at the top of each report  page.  The format of the header command is:

hnumber,data_type,print_position[,space space-control];

where number is an integer from 1 to 5 specifying on which header line (out of five possible lines) the information is to appear. Header information in a header command labeled "h1" appears in the first line, "h2" appears in the second line, etc. 

Data_type is either an ASCII character string enclosed in double quotes, or the word pageno (without quotes). If pageno appears in the header command, query prints the page number of the report in the position specified by print_position.  Query increments the page number automatically for each page printed. 

Print_position, space, and space-control are parameters defined in the section on report formatting. 

An example is:

h1,"PAGE",70,space b2;
h1,pageno,76;
h2,"DAILY REPORT",50,space a3;

which prints the word "PAGE" with the letter "E" in column 70, on the second line from the top of a page (via the "space b2" parameter). On the same line, the page number is printed ending in column 76. The next line contains "DAILY REPORT" ending in column 50, followed by three blank lines. 

d (detail command)
The detail command indicates which data items of a data entry specified in the select file are to be printed in the report. Data items can be printed on up to 10 different lines.  Query prints only the values of data items which appear in a detail command. 

If an ASCII value length exceeds the distance  between a preceding value on the same line or the left  margin, it is silently  truncated  on the left.  If a numeric  value  overlaps in the same  manner, it is replaced by a series of asterisks, indicating the error. 

Detail commands without an edit parameter print numeric values in whatever  format  necessary to give maximum accuracy. 

The  format of a detail command is:

d[n],data_type,print_position[,space space-control][,skip
skip-control][,edit];

where n is an integer from 1 to 9. Each number specifies a different line on which the data items are printed. If the number is omitted, the unnumbered detail item is printed on a separate line above any numbered detail item lines. The lowest numbered command is printed first and all others follow in numeric order. Detail commands with the same number are printed on the same line. 

Data_type is either an ASCII character string enclosed in double quotes, or the name of a data item contained in the data entries specified in the select file. NOTE: the report command processor expects the data item name by itself. Preceding the item name with a set name generates an error. 

Print_position, space, space-control, skip, skip-control, and edit are parameters defined in the section on report formatting. 

e (edit command)
The edit command is used to format the printing of real and/or alphanumeric item values.  Up to ten edit commands, labeled from e0 to e9, can be used in a report. To edit output from a detail command, you include the label of the desired edit command.  Query refers to the labeled edit command to edit the value printed by the detail command. The same edit command can be referenced by more than one detail command in the same report, and each edit command must be referenced at least once in the report body.  The format of the edit command is:

enumber,"places,format";

where number is an integer from 0 to 9, identifying the edit command. An integer cannot be used to identify more than one edit command. 

Places is an integer indicating the number of digits to follow the decimal point (for real numbers) or the number of characters to be printed (for alphanumeric strings). 

Format is one of the following single letters:

f indicating that the number should be formatted in decimal form, with the specified number of digits following the decimal point. Numbers accurate to more than the specified number of places are rounded. 

e indicating that the number should be formatted in scientific notation with the specified number of digits following the decimal point. 

s indicating that the data item is an alphanumeric string. The number of characters printed is specified by the accompanying integer.  If you specify 10 characters for a data item 40 characters in length, the leftmost 10 characters are printed. If you specify 100 characters for the same data item, only 40 characters are printed. 

Here are some examples:

e1,"6f";
d1,real_number,40,e1;

might yield such numbers as:

2.340000
25487.123456
1.000000

and

e1,"4e";
d1,realnum,40,e1;

might yield

2.3400e+0
3.2549e+5
1.0000e+0

and

e1,"15s";
d1,String,40,e1;

might yield

Smith, Jame
truncate ri
Walker, Mau
Doe, John

Finally, the difference between the edit command and the edit parameter should be emphasized. For example,

e1,"7f";
d1,Any_real,30,e1;
end;

The first line is an edit command, specifying a format for real numbers.  In the second line, the "e1" is a parameter, indicating that the real number(s) "Any_real" should be printed according to the format shown in the "e1" command. 

s (sort command)
The sort command specifies an item upon which you want the entries in the select file sorted. The format of the sort command is:

s,itemname;

where itemname is the name of a data item which appears in entries currently stored in the select file. 

A sort item  value may not exceed 80 bytes in  length.  In the case of a compound  data item, sort uses only the first value in that item.  After a  "find", the  entries  appear in the select  file in the order the find command  encounters them.  The sort command will rearrange those entries in ascending alphabetic or numeric order, depending on the sort item. 

Report Example

Assuming that Emp_name is a 20-byte alphanumeric item, Emp_age is a 2-byte integer, and Emp_wage is a 4-byte real:

H1,"EMPLOYEE REPORT",34,space b3;
h1,"PAGE",52;
h1,pageno,56,space a2;
h2,"NAME",7;
H2,"AGE",27;
H2,"HOURLY WAGE",52;
e1,"2f";
s,Emp_name;
d1,Emp_name,20;
d1,Emp_age,27;
d1,"$",44;
d1,Emp_wage,50,e1,space a;
end;

This report might yield:

EMPLOYEE REPORTPAGE 1
NAMEAGEHOURLY WAGE
Anderson,Richard32$ 14.75
Carr,Elaine21$ 11.50
Wilson,Kathy42$ 17.25
  .
  .
  .

Summary

Although the commands appear throughout this document in lower-case, query accepts them in upper-case also. This is helpful when working with databases ported from Series 500 BASIC, in which database names, data set names, and data item names are frequently in upper-case. 

It should be stressed that all commands must end with a semicolon or zero-length entry. If query seems to have "gone away", be sure that a semicolon followed tha last command entered. If this is not the case, an extra carriage return serves to terminate the command and prompt query into action. 

Query sometimes appears to be "eating" report commands and doing nothing about them, other than supplying the "NEXT?" prompt. This is usually the result of having used the "list" command to re-route output earlier in the session, and having forgotten about it. Typing

list;

re-routes output to the terminal again. 

Abnormal  termination  of query leaves files in /usr/tmp.  It is your  responsibility  to remove these files or they may  accumulate and use up large amounts of memory.  The files can be identified by the owner id,  shown by typing  "ll  /usr/tmp".  Do not  attempt  to remove  files belonging to anyone else. 

FILES

/usr/lbin/query

/usr/lbin/querysort query’s own sort routine

/usr/lib/query.help help file

/usr/tmp/∗ temporary files

Hewlett-Packard  —  last mod. May 11, 2021