.; Digital Standard Runoff .; .;AUTHORS: .;-------- .; Diane S. Reiss, GSD Engineering RCA .; Robert A. Harris, Leeds & Northrup Co., North Wales, Pa. 19454 .; in: [VAX84A.LN.RIM] .; Chris Doran, Sira Ltd., South Hill, Chislehurst, Kent, England, BR7 5EH .; More RUNOFF commands (fill & justification!), update for V5.1, summary .; card included as appendices C&D, spell-checked (English English), made .; into 3 chapters + appendices, instead of sections, and general tidy up. .; Merged in additions from [VAX86D.RCAF86.PCCUNV]DATMGR.AZC. .; Notes: .; 1) /VARIANT=SIRA describes some local customisations, mainly in directory .; names and installation details. .; 2) Uses an undocumented feature of the .SEND TOC command: .; .SEND TOC [[n,]m,]text .; writes to table n, where n=0 -> headers (default), n=1 -> EXAMPLES .; n=2 -> FIGURES, n=3 -> TABLES .; and m is sub-number for 1-3 .; 3) Each section which is referred to from elsewhere is marked with: .; .COMMENT section-number. Adjust references if these change. .; .f .ps 64,80 .RIGHT MARGIN 72 .nonumber .style headers 6,1,2,7,7,2,1,7,2 .noautosubtitle .xlower .enable indexing .! .figure 20 .c;Relational Informational Management System .s.c;RIM .s.c;Version 5.1 .! .page .number page 1 .display number rl .layout 0 .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .require 'rim.rnt' .! .page.f .st Definitions .send toc 0,Definitions .c;DEFINITIONS .x Definition of terms .s2.lm+16.i-16 .x Attributes ATTRIBUTE:######An attribute is a 1-8 character alphanumeric name .x Alphanumeric used to identify a specific column of a relation. .x Column .s.i-16 .x Domain DOMAIN:#########A domain is the set of values which are permissible in a column of a two-dimensional table of data (relation). .x Column .s.i-16 .x KEY attribute KEY:############An attribute may be specified to be "KEY". This specification will cause RIM to build an index for the attribute. Under certain conditions, this index will greatly improve the system efficiency for queries and updates. .s.i-16 .x Relation .x Tuple RELATION:#######A relation is a two-dimensional table of data. The column headings are the attributes of the relation .x Column and the rows are the data occurrences (tuples). .x Row .x Tuple .s.i-16 ROW:############A row is the set of values in a row of a two dimensional table (relation). A row is sometimes referred to as a tuple. .s.i-16 .x Schema .x Constraints .x Password SCHEMA:#########The schema is the definition of the relations and .x Definition, schema their attributes that comprise the database. The relation passwords and constraint rules also are part of the schema. .x Constraints .x Rules .lm-16 .page .layout 0 .st Summary .send toc 0,Summary .c;SUMMARY .x Summary .b2 .x Public domain This is the IPAD RIM program, a highly powerful and general relational DBMS. It was written on a NASA contract and is accordingly public domain within the .x NASA United States and is made available to aid those who cannot afford commercial DBMS packages. .p0 This document is the user's guide (VAX/VMS) for the Relational Information Management System, Version 5 (RIM-5). The information presented consists of instructions for using RIM-5 as a standalone system and for using RIM-5 in .x Standalone program conjunction with an application program. .x Application program .p0 Chapter 1 presents the method of implementation and access for RIM-5, a discussion of the files used by RIM-5, and the general syntax of the RIM-5 command language. .p0 .x Menu mode .x Command mode Chapter 2 presents instructions for the use of RIM-5 as a standalone system .x Standalone program in both menu and command modes. In the menu mode, you are prompted for the inputs required to create, update, and/or query the database. The command .x Query mode mode, as an alternative, requires the direct input of RIM-5 commands to create, update, and/or query the database. A discussion of all the available RIM-5 command is presented in this section. .p0 Chapter 3 presents the instructions for the application program interface. .x Application program Any programming language that can call FORTRAN subroutines can be used. .x FORTRAN Most VAX languages come into this category. An example program in VAX FORTRAN is given. .x Subroutines .p0 Appendix A gives a detailed description of the LXLREC command processor used by .x LXLREC the standalone program, including details of ways to speed up data entry. .p Appendix B lists several limitations in to RIM command formats. .p0 Appendices C and D are quick reference summaries of command syntaxes and application interface subroutine calls respectively. .display number d .Chapter OVERVIEW .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st Overview .x OVERVIEW .x Menu mode .x Command mode The Relational Information Management (RIM) System was originally developed as a prototype database management system by Dennis#L#Comfort and Wayne#J#Erickson at The Boeing Company under NASA Contract NAS1-14700 .x NASA (IPAD). Mr#Erickson at the University of Washington, and Frederick#P#Gray at Boeing made enhancements to the system, culminating in RIM Version 4 (RIM-4). RIM-5, which is the version of RIM described in this document, was developed by Mr#Erickson for NASA and Mr#Gray and Geofferey Von Limbach for Boeing. RIM is based upon the relational algebra model for data management and has been used for both engineering and business data. The system is available as a standalone system and through an application program .x Application program .x Standalone program interface. The standalone system may be executed in two modes: menu or command. The menu mode prompts the user for the input required to create, update, and/or query the database. The command mode requires the direct .x Query mode input of RIM commands. .p0 RIM-5 includes several enhancements relative to RIM-4, including: .list "o" .le;highly portable FORTRAN code .le;additional scientific attribute types for vectors and matrices .le;variable length attributes .le;improved sort option .le;improved where clause .le;an initial set of report writing commands .le;introduction of tolerance for floating point numbers .le;additional schema modification commands .le;enhanced FORTRAN interface .le;RIM-to-RIM communications file .els0.p0 .x Batch job .x Interactive job To the interactive/batch user the RIM-5 creation, update, and query are, for .x Query mode the most part, identical to RIM-4. Databases from RIM-4 must be reloaded for RIM-5, however. In addition, the application program interface has been .x Application program expanded and modified to accommodate increased capabilities. .p0 RIM formed the basis of the Rbase database packages supplied for IBM PC and compatible microcomputers. RIM and Rbase database files are therefore interchangeable. .! .hl1 IMPLEMENTATION AND ACCESS RIM is written entirely in FORTRAN 77. It requires approximately 300000 .x FORTRAN (decimal) bytes of virtual memory when run as a standalone program. .x Standalone program .p0 Access to RIM depends on the execution method desired. To use the RIM application program interface you need to link RIMLIB to your .x Application program application program. The procedure for doing this is described in Section 3.7. .p0 To execute the standalone program, .x Standalone program .IF SIRA .; In the Sira installation, the ASSIGNs are system-wide, and .; RIM is defined in SYLOGIN.COM by $ RIM:==$RIM you need type only the command: .s.i+4;$ RIM .p0 Help information is .ELSE SIRA the following control statements are needed: .s.tp4.lm+4.nf .x LIB__USER: $ ASSIGN LIB__USER:HELPDB1.DAT HELPDB1 $ ASSIGN LIB__USER:HELPDB2.DAT HELPDB2 $ ASSIGN LIB__USER:HELPDB3.DAT HELPDB3 $ RUN LIB__USER:RIM .lm-4.f.s where LIB__USER_: is the name of the user directory in which RIM.EXE and the RIM HELP database files reside. Help information is thus .x HELP database .ENDIF SIRA available internally to the RIM standalone program. Outside it, help may be obtained from the VAX/VMS system HELP library by typing: .s.i+4 .IF SIRA $ HELP RIM .ELSE SIRA $ HELP @USERLIB RIM .ENDIF SIRA .! .hl1 DATABASE FILES .COMMENT 1.2 .x Data, directory .x Data, actual .x Data, key element pointers .x Logical files Each database consists of three RIM-generated files whose logical names are formed by suffixing the database name with a 1, 2, and 3. The first file contains directory data, the second file contains the actual data for each relation, and the third file contains key element pointers. The default type for these files are "DAT". RIM uses logical files FOR005 and FOR006 for .x FOR006 .x FOR005 input and output. .p0 If your database files do not reside on your directory with names equal to the logical database files names, you must use ASSIGN control statements prior to the RIM execution to assign required names to your database files, as: .s.tp6.lm+4.nf .x dbname $ ASSIGN disk:[directory]dbname1.DAT dbname1 $ ASSIGN disk:[directory]dbname2.DAT dbname2 $ ASSIGN disk:[directory]dbname3.DAT dbname3 .s .IF SIRA $ RIM .ELSE SIRA $ RUN LIB__USER:RIM .ENDIF SIRA .lm-4 or##$ RUN your__program .x Application program .f.s where disk:[directory] specifies the VAX/VMS path name to the directory containing your database files and dbname is the 1 to 8 character file name used to identify your database. The '1', '2', and '3' must be appended to the dbname. .p0 You may also assign your input and output files to files other than FOR005 and FOR006 if desired. .x FOR006 .x FOR005 .IF SIRA .p0 A sample RIM database, containing some aircraft details and used in some of the examples in this manual, is in the PLANES%.DAT files in directory SYS$EXAMPLES:, and may thus be accessed by setting up: .s.LM+4.TP3.NF $ ASSIGN SYS$EXAMPLES:PLANES1.DAT PLANES1 $ ASSIGN SYS$EXAMPLES:PLANES2.DAT PLANES2 $ ASSIGN SYS$EXAMPLES:PLANES3.DAT PLANES3 .F.LM-4.P0 You can then use it to try some of the query examples in this manual. If you wish to try modification examples, however, you must instead make working copies of the files in a directory of your own, by: .s.i+4;$ COPY SYS$EXAMPLES:PLANES%.DAT [] .ENDIF SIRA .! .hl1 GENERAL COMMAND SYNTAX .COMMENT 1.3 .x DEFINE command .x HELP command .x LOAD command RIM is used by entering commands (which start with keywords) in response to input prompts (which vary according to the submodule in use). Three of the commands (DEFINE, HELP, and LOAD), are used to enter submodules which have their own sets of commands for defining and loading a database. In describing commands, the following conventions are used: .x Conventions .s .tp12 .nf relname or name of a relation(s) relname1,relname2,... .s attname or name of an attribute(s) attname1,attname2,... .s value or actual values(s) value1,value2,... (value may be a text string, scalar, vector, or matrix) .x relname .x attname .x value .f.p0 All relation and attribute names must contain at least 1, and no more than 8, alphanumeric characters. .x Alphanumeric .p0 RIM does not distinguish between upper and lower case letters in commands or keywords. .p0 Many of the commands in RIM have optional parts. These optional parts are enclosed in square brackets. .x Square brackets .s.i+4;[THIS IS OPTIONAL] .p0 .x Braces Some keywords in the commands are selected from a list of acceptable keywords. These keywords are in a vertical list with the first choice enclosed in braces. .s.NF {CHOOSE} ONE OF THESE .f.p0 RIM command keywords may be abbreviated. At least the first three characters in the keywords are required. .x Abbreviation .p0 The following are equivalent: .tp6 .list .le;SELECT, FROM, WHERE, DELETE DUPLICATES .le;SELEC, FRO, WHER, DELETE DUP .le;SEL, FRO, WHE, DEL DUP .els0.p0 .x Blanks .x Free-field format All commands in RIM are entered in a free-field format with blanks and commas as separators. The following contains a short description of RIM .x Commas conventions and data generation facilities. .x Conventions .x Continuation .x Command memory .x Plus .p0 Keywords and data values are separated by blanks or commas. If a command is too long for one 80 character line, it may be continued on succeeding lines by entering "+" as the last character of the preceding line. RIM remembers each previous command. This enables you to re-use all or part of the previous command. This is done by using an asterisk to indicate which items of the .x Asterisk previous command are to be re-used. A single asterisk means re-use the corresponding single item of the previous record. An asterisk followed by a number n means re-use the next n corresponding items. Two asterisks mean re-use all remaining corresponding items. .p0 The following are all equivalent: .tp14 .list .le;THIS IS A COMMAND .le;THIS + .br;IS + .br;A + .br;COMMAND .le;* IS,A COMMAND .le;THIS *2 COMMAND .le;THIS ** .end list .x Multiple commands .x Dollar sign .x Semicolon Multiple commands may be entered on one line separated by a semicolon (;) or dollar sign ($): .s.i+4;THIS IS THE FIRST _; THIS IS THE SECOND $ THIS IS THE THIRD .p0 Comments may be placed anywhere within a command by enclosing the .x Comments comment between the characters *( and ): .s.i+4;*(THIS IS A COMMENT) THIS IS NOT .p0 .x Quotation marks .x Alphanumeric When numeric data is to be interpreted as text (alphanumeric) data, the numerals must be enclosed by quotation marks: .s.i+4;"1234" .p0 .x Blanks, embedded .x Commas .x Quotation marks When entering text strings which contain embedded blanks or commas, the entire string must be enclosed by quotation marks: .s.i+4;"THIS IS A TEXT STRING" .p0 .x Quotation marks .x Blanks, leading .x Blanks, embedded .x Plus A text string may require continuation on one or more lines. The + sign .x Continuation continuation can then be used within the quotation marks. It is not recommended that you use leading blanks in text strings. Text which does not have embedded blanks or commas does not require quotes. .x Commas .p0 .x Integer .x Decimal point Integer data is input as a string of digits without a decimal point. A sign may precede the digits: .x Sign .s.i+4;123, -63, +56, 0 .p0 .x Floating point .x Decimal point .x Exponent .x Integer Real, or floating point, numbers must include a decimal point and/or E .x Real followed by the exponent, e.g.: .s.i+4;1.3, .005, 0., 6.E-1, 6E-1, 0.60, -23.45 .p0 .x Limit, real numbers The size of real numbers is limited to the range between 1.0E-38 .x Real range and 1.0E+38. .p0 Appendix A discusses command processing and data entry formats in more detail. .CHAPTER RIM EXECUTION .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st RIM Execution .x Command mode .x Menu mode Execution of RIM as a standalone program can be effective in two modes, .x Standalone program command mode or menu mode. The command mode is used when RIM is executed in the batch environment or for interactive users who wish to bypass the menu .x Interactive job .x Batch job dialogue. A detailed description of the commands are given in Section 2.1. The menu mode offers assistance to inexperienced users. An overview of this mode is discussed in Section 2.2 and a more detailed description of the menu mode dialogue is given in Section 2.3. The interactive user may switch .x Interactive job freely between menu mode and command mode. .p0 When executing RIM interactively, the first output to your display will be: .s.tp4 .i+4;Begin RIM --VAX-VMS Version 5.1##UDxx######yy/mm/dd##hh.mm.ss .s.i+4;RIM COMMAND MODE .x Command mode .i+4;ENTER "MENU" FOR MENU MODE .x Menu mode .p0 .x Time UDxx identifies the update level of RIM. The date and time stamp indicate .x Date current date and time. At the start of execution you are in the command mode but you may switch immediately to the menu mode as indicated. .! .hl1 RIM COMMANDS .COMMENT 2.1 .x Password .x Restrictions This section presents a summary of the RIM commands. You are restricted .x Summary from using certain commands based on the knowledge of assigned passwords. If no passwords are assigned to the relations by the database owner, there are no command restrictions (the DEFINE submodule excepted). See Figure 2-1. .x DEFINE command .s.lm+4.tp30.nf Current Password ^&Section_ Number Command owner modify read none\& o 2.1.1 General X X X X .s o 2.1.2 Define X .s o 2.1.3 Load X X .s o 2.1.4 Database query X X X .s o 2.1.5 Schema query X X 2 X 2 .s o 2.1.6 Computation X X X .s o 2.1.7 Database modification X X .s o 2.1.8 Schema modification X X 1 .s o 2.1.9 Relational algebra X X .s o 2.1.10 Report generation X X X .s o 2.1.11 Communication X X .s2 1 except CHANGE OWNER 2 except PRINT RULES .f.lm-4 .s .c;Figure 2-1 -- Password Requirements .send toc 2,1,Password Requirements .hl2 General Commands .COMMENT 2.1.1 .hl3 HELP Command .x HELP command .x Menu mode The HELP command allows you to obtain: a description of the available RIM commands, a discussion of the general command syntax, a summary of all .x Summary available commands, and general news about the RIM system. HELP is available at any time during execution except when in the menu mode. .p0 To receive help when in the command mode, enter: .x HELP command .s.tp8.lm+11.i-7.nf HELP [{command name}] RIM SYNTAX WHERE SUMMARY NEWS SORT INPUT FORMAT .lm-11.f.p0 If you type HELP alone, you enter the HELP submodule. This gives you an H> prompt, to which you may enter any of the above topics, without the need for the HELP keyword. The HELP submodule displays information one screen at a time. After each screen, you have the option to continue displaying the text by entering *, or return to the .x QUIT command HELP submodule by entering QUIT. You will remain in the submodule until you enter an END command which will return to the command mode. .x MENU command .hl3 MENU Command .x DEFINE command .x HELP command .x LOAD command .x Menu mode .x Schema .x Data loading The MENU command places you in the menu mode. It may be entered at any point when in command mode except when in the DEFINE, HELP, or LOAD submodules. The menu mode is particularly useful for schema definition and data loading. .x Definition, schema .s.i+4;MENU .x OPEN command .hl3 OPEN Command The OPEN command is required whenever an existing database is to be used. You specify the name of the database. RIM uses the name of the database to form the names of the three files which contain the database. The database files must either reside in your directory or you must make a logical file assignment prior to RIM execution (see Section 1.2). .s.i+4;OPEN dbname .x dbname .x OPEN command .p0 Only one RIM database may be open at a time (if you don't close the present database before opening a new one, RIM will do so automatically). The OPEN command must be issued before any commands that require data from the database can be processed. .hl3 CLOSE Command .x CLOSE command The CLOSE command permits you to close a RIM database without leaving RIM. This enables you to close one database, then open or define a different one, all within one RIM session. This command is not needed if only one RIM database is accessed during a RIM session. It results in update of the database files to reflect all changes you have made to the database. .s.i+4;CLOSE .p0 .x EXIT command Note: The current database will be closed for you when you leave RIM by issuing an EXIT command. .hl3 USER Command .x USER command This command is used to specify your user password to RIM. Your user password .x Password is used to check against read and modify passwords specified for the relations. Each time this command is issued, the new password replaces the current user password. The default password is the word NONE. .s.i+4;USER password .hl3 INPUT Command .x INPUT command .x Command procedures This command is used to specify the name of a file which contains the RIM commands and/or input data. Alternative input file names may be assigned as often as required. The use of this command allows you to define command procedures on a file and then have RIM execute the set of commands without user interaction. .x Command procedures .s.i+4;INPUT filename .p0 The last command in the alternative input file should be INPUT INPUT which returns input to the batch input file or your terminal. INPUT TERMINAL will, .x Batch job for interactive jobs, do the same thing. .x Interactive job .x INPUT INPUT .x INPUT TERMINAL .hl3 OUTPUT Command .x OUTPUT command This command is used to specify the name of the output file. Specifying a file other than OUTPUT will result in the output from the RIM commands being placed on the specified file name. The output file name may be changed as often as desired. The use of this command allows the interactive user to get an offline hardcopy output from RIM. .s.i+4;OUTPUT filename .p0 OUTPUT OUTPUT will return the output to the batch output file or your .x Batch job terminal. OUTPUT TERMINAL will, for interactive jobs, do the same thing. .x Interactive job .x OUTPUT OUTPUT .x OUTPUT TERMINAL .hl3 ECHO Command .x ECHO command This command is used to control the printing of your input commands on the output file. Default is for ECHO printing enter: .s.i+4;ECHO .hl3 NOECHO Command .x NOECHO command The NOECHO command turns off ECHO printing. .s.i+4;NOECHO .hl3 TOLERANCE Command .x TOLERANCE command .x Floating point .x Double precision .x WHERE keyword For attributes which contain floating point numbers, a tolerance may be used to qualify equality, inequality and order. The tolerance applies to any real or double precision number you use in a WHERE clause. If A is an .x Real attribute with value a, and r is a user-specified number used in a WHERE clause, and t a tolerance (positive, zero, negative), the following are true conditions: .s .tp6 .i+4;A EQ r IF AND ONLY IF r-t <= a <= r+t .i+4;A NE r IF AND ONLY IF a < r-t OR a > r+t .i+4;A GT r IF AND ONLY IF a > r-t .i+4;A GE r IF AND ONLY IF a => r-t .i+4;A LT r IF AND ONLY IF a < r+t .i+4;A LE r IF AND ONLY IF a <= r+t .p0 .x Tolerance, percent If t is a percentage tolerance, t is to be replaced with t#x#r/100 in the above expressions to define true conditions for percentage tolerances. .s.i+4;TOLERANCE tol [PERCENT] .s .x Tolerance, absolute .x Tolerance, percent .x PERCENT keyword where tol is the tolerance and the presence or absence of the keyword PERCENT indicates whether tol is a percentage tolerance or an absolute tolerance. The TOLERANCE command can be used as many times as desired to reset the .x TOLERANCE command tolerance. A tolerance stays in effect for a session until a new tolerance is specified. The default value for tolerance is 0. .hl3 NOCHECK Command .x NOCHECK command Rule checking applies to the CHANGE and LOAD commands. Default is that rules, .x LOAD command .x CHANGE command if defined, are enforced. The NOCHECK command suppresses the rule checking. .x NOCHECK command .s.i+4;NOCHECK .hl3 CHECK Command .x CHECK command The CHECK command turns on rule checking. The CHECK and NOCHECK commands may be issued as many times as required anywhere in the input stream. .s.i+4;CHECK .hl3 EXIT Command .COMMENT 2.1.1.13 .x EXIT command To leave RIM without dropping your current database enter: .s.i+4;{EXIT} .i+5;QUIT .x QUIT command .p0 .x Logical files This command closes your current database. Data needed by your databases is copied from the in-core working areas to the logical files whose names were determined by the OPEN command or by the database name designated in the .x OPEN command DEFINE submodule. .x DEFINE command .hl3 RELOAD Command .x RELOAD command .x Unused space .x Row deletion .x Relation removal .x Variable length The RELOAD command is used whenever you want to rebuild the data files of your .x RELOAD command database to recover unused space created by row deletions, relation removals, and certain attribute changes. When a row is deleted or a relation removed, its space is not re-used until you issue this command. In addition, if a variable length attribute is modified so that it increases in length, the row is deleted and replaced with a new one. The old row becomes unused space. If your database has any KEY attributes, then the access pointer files maintained for those attributes are also rebuilt. The syntax for the command is: .s.i+4;RELOAD .hl2 Define Submodule Commands .COMMENT 2.1.2 .x DEFINE command .x Password .x Rules .x Schema The Define submodule (prompt#=#D>) commands are used to define the structure of the database and are used in the sequence described below. The definition .x Definition, schema of the database is called the schema. The schema name is the name of the database and forms the essential part of the names of the files used for the database. Attributes, relations, passwords, and constraints (rules) are .x Constraints defined using this submodule. The naming conventions for schema definition .x Definition, schema .x Schema .x Conventions are described in Section 2.3.3. .x DEFINE command .hl3 DEFINE Command To access this submodule enter: .s.i+4;DEFINE dbname .x dbname .p0 You must identify the name of the database whose definition you are going to .x Definition, schema create or expand by specifying the schema name. This name is used to form .x Schema the name of the files used to store the database tables. The dbname, when augmented with a single digit, must be a legal filename. .x OWNER keyword .hl3 OWNER Keyword Once dbname is .x dbname specified you must identify the owner password of the definition. .x Definition, schema .x Password .x OWNER password .s.i+4;OWNER password .p0 .x Define attributes If the database already exists and you want to define additional attributes or relations, "password" is checked against the existing owner password. .hl3 ATTRIBUTES Keyword .x ATTRIBUTES keyword .x attname .x type1 .x type2 .x Row .x Column .tp17 To define the attributes enter: .s.nf.lm+4 ATTRIBUTES .s attname type1 [{length}] [KEY] VAR .s attname type2 [{row,col}] [KEY] row,VAR VAR,VAR . . . .f.lm-4.p0 .x PASSWORDS keyword .x RELATIONS keyword The attribute definitions are ended when you specify one of the keywords .x Definition, attributes RELATIONS, PASSWORDS or RULES. .x RULES keyword .s .x type1 ^&Type1_ attributes:\& .br .x Double precision .x Floating point .x Real vectors .x Integer vectors .x Double precision vectors .x DOUB keyword .x DVEC keyword .x REAL keyword .x INT keyword .x TEXT keyword .x RVEC keyword .x IVEC keyword .x VAR keyword .x KEY keyword .x BUILD KEY command .x DELETE KEY command .x Non-KEY attribute .x Text .x Variable length .x type1 RIM supports seven data types of "type1": real (floating point), integer, .x Integer .x Real text, double precision, real vectors, integer vectors and double precision vectors. You must enter REAL, INT, TEXT, DOUB, RVEC, IVEC or DVEC for type1. The default length is one number, except for TEXT, for which it is 8 characters. The length is specified in number of values and characters respectively. VAR indicates variable length. The optional KEY specification causes an index file to be built for the attributes. This is used by RIM to quickly find qualifying rows for retrievals and updates. The default is that .x Row such an index file is not built (non-KEY attribute). You should consider the cost of building and storing index file data versus the benefits you will obtain from quicker retrievals when deciding if a KEY declaration should be .x KEY attribute used. No specific rules can be given here; experience should be used to judge. An attribute can be changed from KEY to non-KEY or vice-versa by using the BUILD KEY and DELETE KEY commands described in Section 2.1.8. For large databases (more than 1000 rows), experience has shown that it is most efficient not to specify a KEY in the DEFINE submodule but rather to load the .x DEFINE command data without keys and to later cause index files to be built using the BUILD KEY command. The greater the number of keys, the more efficient this method is. .s .x type2 ^&Type2_ attributes:\& .br .x Real matrices .x Integer matrices .x Double precision matrices .x Row .x Column .x DMAT keyword .x RMAT keyword .x IMAT keyword .x KEY keyword .x type1 .x type2 .x Fixed size RIM supports three data types of "type2": real matrices, integer matrices or double precision matrices. You must enter RMAT, IMAT or DMAT for type2. The matrices can be of fixed size, have variable column dimension or variable .x Column row and column dimensions. You enter the row dimension first, followed by the column dimension. The default dimension is 1x1. The keyword KEY has the same meaning as for "type1" attributes. .hl3 RELATIONS Keyword .x Define relations .x RELATIONS keyword To define relations enter: .s .tp6 .nf.lm+4 RELATIONS .s relname WITH attname1 [attname2...] . . . .lm-4.f .x relname .x attname .x WITH keyword .p0 .x ATTRIBUTES keyword .x PASSWORDS keyword .x RULES keyword The relation definitions are ended by specifying one of the keywords .x Definition, relations ATTRIBUTES, PASSWORDS, RULES, or END which start the other sections of the .x END keyword DEFINE submodule or finishes the schema definition. .x Definition, schema .x Schema .x DEFINE command .p0 The attributes must be listed in the order in which they are to appear in the relation. No attributes can be used which have not been previously defined -- either in the current attributes definition subsection or in a previous .x Definition, attributes definition of this database. Attributes which are defined but not included in a relation will not become part of the RIM schema. .p0 .x Constraints .x Password A RIM database must have attributes and relations defined, but passwords and constraint rules are optional. .x Rules .hl3 PASSWORDS Keyword .x PASSWORDS keyword If read or modify passwords are desired, enter: .x MPW command .x RPW command .x READ PASSWORD command .x WRITE PASSWORD command .s.tp4.nf.lm+4 PASSWORDS .s {READ PASSWORD} FOR relname IS password RPW .s.tp5 {MODIFY PASSWORD} FOR relname IS password MPW . . . .f.lm-4.p0 .x READ PASSWORD command .x MODIFY PASSWORD command .x FOR keyword .x IS keyword .x ATTRIBUTES keyword .x RELATIONS keyword .x RULES keyword .x PASSWORDS keyword The password definitions are ended by specifying one of the keywords .x Password ATTRIBUTES, RELATIONS, RULES, or END which start the other sections of the .x END keyword DEFINE submodule or finishes the database definition. A password can be any .x DEFINE command string of alphanumeric characters up to 8 characters long. When you are doing .x Alphanumeric queries, loads, or modifications, the current password is specified by the USER command. If this password does not match the read, modify, or owner .x USER command password for a given relation, you cannot query that relation. If this password .x Query relation does not match the modify or owner password, you cannot load or modify the relation. .hl3 RULES Keyword .x RULES keyword .x Constraints Constraint rules are another optional section of the DEFINE submodule. If .x DEFINE command .x Rules rules are specified, they are used during the loading process or during CHANGE .x CHANGE command commands to screen out rows which do not meet the constraint rules. Rules are .x Row specified by relation. 10 rules at most may be specified for a single relation. There are several options available in the rule definition section. .x Definition, rules To define constraint rules, enter: .x Define constraints .x Define rules .x relname .x attname .x value .x EQ keyword .x AND keyword .x OR keyword .x NE keyword .x GT keyword .x GE keyword .x LT keyword .x LE keyword .x EQA keyword .x NEA keyword .x GTA keyword .x LTA keyword .x LEA keyword .s.tp8.nf.lm+4 RULES .s attname [IN relname] {EQ} value [{AND} attname ...] NE OR GT GE LT LE .s.tp7.i-4 or .s attname1 IN relname {EQA} attname [{AND} ...] NEA OR GTA LTA LEA .s.tp10.i-4 where: EQ = Equals NE = Not equal to GT = Greater than GE = Greater than or equal to LT = Less than LE = Less than or equal to EQA = Equals attribute NEA = Not equal to attribute LTA = Less than attribute LEA = Less than or equal to attribute .f.lm-4.p0 .x ATTRIBUTES keyword .x RELATIONS keyword .x PASSWORDS keyword .x Restrictions .x RULES keyword .x Password The rule definitions are ended by specifying one of the keywords ATTRIBUTES, .x Definition, rules RELATIONS, or PASSWORDS, which start the other sections of the DEFINE .x DEFINE command .x END keyword submodule, or END, which finishes the schema definition. Attributes referenced in the .x Schema rule definitions must have been previously defined. By specifying rules, you can restrict an attribute to a range of values, or require that the value of an .x Range of values attribute in one relation have a specified relationship to the values of an attribute in the same or different relation. The comparison operators ending in A are used when the comparison is to existing attribute values rather than to a specified constant. A rule expression may contain a maximum of 9 Boolean .x Boolean operators operators. .p0 .x Constraints The method used for constraint checking is that the first attribute mentioned in the rule is taken from the input (LOAD or CHANGE command) data and checked .x CHANGE command .x LOAD command against the remainder of the rule expression using existing values in the database. .hl3 END Keyword .x END keyword To finish the schema definition you enter the following keyword and leave the .x Definition, schema .x Schema DEFINE submodule: .x DEFINE command .s.i+4;END .p0 Example of DEFINE submodule commands: .send toc 1,DEFINE Submodule Commands .s.tp22.nf.lm+4 DEFINE RIMDS OWNER ME ATTRIBUTES MODEL TEXT KEY WEIGHT REAL NUMPASS INT CARRIER TEXT FLIGHTNO INT NAME TEXT KEY AGE INT UPDATE IMAT 4,VAR RELATIONS AIRPLANE WITH MODEL WEIGHT NUMPASS FLIGHTS WITH CARRIER FLIGHTNO MODEL UPDATE PEOPLE WITH NAME AGE PASSWORDS MPW FOR FLIGHTS IS AGENT RPW FOR PEOPLE IS BLUE RULES MODEL IN FLIGHTS EQA MODEL IN AIRPLANE AGE GT 21 AND AGE LT 65 NUMPASS IN AIRPLANE LE 350 END .f.lm-4 .hl2 Load Submodule Commands .COMMENT 2.1.3 .x LOAD command .x Define relations The LOAD submodule (prompt#=#L>) commands are used to add rows to a newly .x Row defined relation or to add rows to a relation which already contains data. .hl3 LOAD Command To access this submodule enter: .s.i+4;LOAD relname .p0 .x relname You may now load rows into the relation, one row at a time, by entering data .x Row values in an order corresponding to the attribute order: .s.i+4;value1 value2 .._. valueN .p0 .x value The method used to input values for the different attribute types is shown below: .x Attributes .x REAL keyword .x INT keyword .x DOUB keyword .x RVEC keyword .x IVEC keyword .x DVEC keyword .x VAR keyword .x TEXT keyword .x RMAT keyword .x IMAT keyword .x DMAT keyword .x Parentheses .s.tp8.nf.lm+4 .send toc 3,Attribute Entry Methods Attribute .s Length or Type Dimension Valuei Remarks --------- --------- ------------------------- ----------- REAL,INT n n=>1 (val1 ... valN) parentheses DOUB,RVEC optional IVEC,DVEC .s.tp3 REAL,INT VAR (val1 val2 ...) parentheses DOUB,RVEC required IVEC,DVEC .s.tp3 TEXT any "text string" quotes optional in many cases (see Section 1.3) .s.tp3 RMAT,IMAT m,n ((r1c1...rmc1)(r1c2...) + columnwise, DMAT ...rmcN)) parentheses optional .s.tp3 RMAT,IMAT m,VAR ((r1c1...) (r1c2...)...)) columnwise, DMAT or parentheses VAR,VAR required .f.lm-4 .hl3 END Keyword .COMMENT 2.1.3.2 .x END keyword To finish data loading you enter: .s.i+4;END .p0 Multiple relations may be loaded from within the LOAD submodule by reentering .x LOAD command the LOAD command instead of the END command. .s2 Example of LOAD submodule commands: .send toc 1,LOAD Submodule Commands .s.tp12.nf.lm+4 USER AGENT LOAD AIRPLANE DC9 87000. 110 747SP 200000. 350 LOAD PEOPLE BOB 30 JOE 32 ALICE 29 LOAD FLIGHTS UAL 16 "757" ((1,2,3,4) (4,5,6,7)) *3 ((2,4,5,8)(1,2,3,4) (4,5,6,7)) END .f.lm-4.p0 .x -0- .x Missing value (-0-) If the value for an attribute is unknown, you enter the characters -0- for the missing value, or use two successive commas. .s.tp2.nf.lm+4 L1011 -0- -0- 250 L1011,,,250 .f.lm-4.p0 These two input entries have identical meaning. .hl2 Commands for Querying the Database .COMMENT 2.1.4 .x Query commands .hl3 SELECT Command .x SELECT command The SELECT command is used for displaying or printing data from one relation. It has many options. To print all the data from a relation: .s.i+4;SELECT ALL FROM relname .p0 .x ALL keyword .x FROM keyword .x relname To print selected attribute values from all rows in a relation: .x Row .s.i+4;SELECT attname1 [attname2 .._. attnameN] FROM relname .p0 .x attname .x FROM keyword .x relname .x SELECT command .x Limit, printing The above command will print up to 20 attributes in any order. The number of attributes is limited by space available in a line. As a rule of thumb, 7 attributes may be selected when running at an 80 character interactive .x Interactive job .x Batch job terminal and 11 when running in batch mode or at an 132 character terminal. .p0 .x Variable length .x Fixed length .x Equal sign (=) .x Width control For variable length attributes, or for attributes of fixed length that would otherwise not fit on a line (alone or together with other attributes), you may format the output using the optional field width control: .s.tp3.i+4;SELECT attname1 [=fw1] [attname2 [=fw2] ...] + .s.i+4;FROM .p0 .x Width fwi is the output field width for attnamei. For a text type attribute, fwi is the width of the output paragraph in number of characters, for other attribute types it is the number of values. When the field width option is used, RIM will use as many output lines as required for each row. .p0 .x Row .x DOUB keyword .x Fixed length .x INT keyword .x REAL keyword .x TEXT keyword .x Variable length Defaults are rather complex. For a fixed length attribute, other than matrix, no paragraphing is attempted. For a fixed length matrix, the default paragraph width is a full row. The system will use the field width required .x Width to display the value(s) of the attribute. For a variable length attribute of type TEXT, the default is a display of a maximum of 40 characters with paragraphing. For variable length attributes of types REAL, INT, DOUB, the default is 4 elements with truncation. For variable length vector type attributes, the default is 4 elements with paragraphing (no truncation). For variable length matrix attributes the default is 4 elements with paragraphing (no truncation). A row starts on a new line. .p0 .x Row Whether field width is specified or not, the system will display the dimension .x Width of variable length vectors and matrices using one of the output positions. However, should you specify a width of one for such an attribute, the row and column dimensions will not be displayed. .x Column .p0 .x Lines per page Further information about line width, number of lines per page, defaults, and user specifications is given in Section 2.1.10, as part of the RIM report writing features. .p0 .x Blanks .x TEXT keyword When paragraphing TEXT type attributes, RIM will identify substrings of text separated by blanks. The substring is placed on the current line if there is space available. If the current line contains less than four characters, the number of characters that fit on the line are removed from (the front of) the substring and put on the line (without hyphen) and continued on the next line. If the current line contains more than four characters, the substring will be placed on the next line. .p0 .x SELECT command Examples of the SELECT command: .send toc 1,The SELECT Command .s.tp10.lm+4 SELECT ivecvar FROM rel1 .x FROM keyword .x SELECT command .nf.s DIM IVECVAR ----------------------------------- .s 7 1 2 3 4 5 6 7 1 10 .s2.tp11 SELECT imatvv FROM rel1 .s ROW COL IMATVV --------------------------------------- .s 2 5 11 12 13 14 15 21 22 23 24 25 1 1 11 .s .x SELECT command .tp13 SELECT textv = 9 FROM rel 1 .s TEXTV ------------ THIS IS AN EXAMPL E OF WRAPAROUN D OF TEXT THIS IS ANOTHER EXAMPLE OF TEXT .f.lm-4.p0 .x attname The attribute name attnamei may be replaced by its corresponding attribute number (attnum1). The attribute number is determined by the position of the attribute in the relation. Specific elements of a vector or a matrix may also be designated. The general form of the unconditional SELECT command is: .x SELECT command .x ALL keyword .x FROM keyword .x attname .x relname .x Equal sign (=) .s.tp8.nf.lm+4 SELECT {attname1 [=fw1]} [attname2 [=fw2] ...] + attnum1 [=fw1] attname1(i) attname1(i,j) attnum1(i) attnum1(i,j) ALL FROM relname .lm-4.f.p0 To print all attributes from a relation where certain conditions are met: .x SELECT command .x ALL keyword .x FROM keyword .x relname .x WHERE keyword .x Conditions .x AND keyword .x OR keyword .s.tp4.nf.lm+4 SELECT ALL FROM relname + .s WHERE condition1 [{AND} condition2 ...] OR .lm-4.f.p0 Up to ten conditions may be combined using the Boolean operators AND/OR. The .x Boolean operators .x Conditions conditions are combined from left to right. Each condition may be one of the following forms: .s.tp19.nf.lm+4 .send toc 3,Relational Operators .x attname .x EXISTS keyword .x FAILS keyword .x MAX keyword .x MIN keyword .x value .x EQ keyword .x EQS keyword .x NE keyword .x GT keyword .x GE keyword .x LT keyword .x LE keyword .x EQA keyword .x NEA keyword .x GTA keyword .x GEA keyword .x LTA keyword .x LEA keyword attname EXISTS attname FAILS attname EQ MAX attname EQ MIN attname EQ value attname EQS value attname NE value attname GT value attname GE value attname LT value attname LE value attname EQ list attname NE list attname1 EQA attname2 attname1 NEA attname2 attname1 GTA attname2 attname1 GEA attname2 attname1 LTA attname2 attname1 LEA attname2 .s.tp9 .x rownumber .x list .x ROWS keyword .x LIMIT keyword ROWS EQ rownumber ROWS NE rownumber ROWS LT rownumber ROWS LE rownumber ROWS GE rownumber ROWS GT rownumber ROWS EQ list ROWS NE list LIMIT EQ number .s.tp7.i-4 where: EQ = Equals EQS = Contains the text string NE = Not equals GT = Greater than GE = Greater than or equal to LT = Less than LE = Less than or equal to .s.tp6 EQA = Equals attribute NEA = Not equals attribute GTA = Greater than attribute GEA = Greater than or equal to attribute LTA = Less than attribute LEA = Less than or equal to attribute .s.tp2 MAX = Maximum value MIN = Minimum value .f.lm-4.p0 .x attname .x Matrices .x Vectors attname, attname1, attname2 may refer to an element of a vector or a matrix. .p0 .x -0- .x Missing value (-0-) .x EXISTS keyword .x FAILS keyword When an attribute has been assigned a value, then EXISTS will qualify those attributes. If an attribute has not been assigned a value, but was loaded with -0-, then FAILS will qualify those attributes. .p0 .x Double precision .x MAX keyword .x MIN keyword .x Fixed length MAX and MIN comparison can only be made for integer, real and double .x Real .x Integer precision attributes of fixed length equal to 1. .p0 .x Variable length .x Matrices value in a comparison statement must follow the rules of Section 2.1.3 for vectors and matrices, i.e_. if the attribute is of variable length or .x Vectors dimension, parentheses must be used to input a vector or a matrix value or a .x Parentheses list of vector and matrix values. .p0 .x EQS keyword EQS applies to text strings only. In such a comparison, value is a text string and the comparison is true if value is found as a substring anywhere within the attribute for which comparison is requested. .p0 .x NE keyword NE comparison when applied to matrices or vectors is true if the length or .x Vectors .x Matrices dimension is different from the length or dimension of your specified comparison vector or matrix, or if any vector or matrix elements differ. .p0 .x GT keyword .x LT keyword .x Lexicographical .x Matrices GT and LT comparisons for vector and matrix attributes are "lexicographical", i.e_. a comparison is made element by element (columnwise for matrices) and continued until a true or false condition is detected. If no such condition is detected after the last element is checked, a false condition is assumed. Comparison is made only for vectors and matrices of the .x Matrices .x Vectors same sizes as the comparison data. .p0 .x GE keyword .x LE keyword .x GT keyword .x LT keyword GE and LE comparisons for vector and matrix attributes are similar to GT and LT comparisons except they continue if an equal condition is detected and if no decisive condition is detected after the last element is checked, a true condition is assumed. .p0 .x Double precision .x Fixed length .x Variable length .x Real Comparison rules for vector attributes apply also to real, integer and .x Integer double precision attributes of fixed or variable length. .p0 A list is a simple list (a1, a2, a3, ..., aN) of values. .x List of values .p0 .x Row The comparison key words ending in A are used when comparing the value of one attribute to the value of another attribute in the same row of the relation. .p0 .x ROWS keyword ROWS refer to row numbers in a relation. Note that a relation is loaded in input row order but that subsequent operations which changes the database may cause the order of the rows to change. .p0 .x LIMIT keyword When the LIMIT clause is used, only the first LIMIT number of the rows that otherwise would qualify will actually qualify. .p0 .x WHERE keyword Processing the WHERE condition can be speeded up greatly if index processing is used. Index processing involves using the indexes created for KEY .x KEY attribute attributes rather than looking at each row of a relation to find the rows qualified by the WHERE conditions. Index processing will be used when the following are all true: .list .le;The last condition uses an attribute which is KEY, .le;The last condition uses EQ, .le;The last condition is not combined by OR with the other conditions. .els0.p0 .x Sort The output can be sorted by specifying sorting attributes. The sorting order is user-specified, with default low to high. .x SELECT command .x FROM keyword .x relname .x SORTED BY keyword .x attname .x WHERE keyword .x Equal sign (=) .s.tp5.nf.lm+4 SELECT ... FROM relname .s SORTED BY attname1 [{=A}] [attname2 [={A}] ...] + D D [WHERE ...] .f.lm-4.p0 .x Fixed length .x Variable length A and D stand for ascending and descending order respectively. If a sort .x Sort .x Descending .x Ascending on more than one attribute is requested, the output will first be ordered according to the first mentioned attribute. In case there are duplicates for the first sort attribute, these will be ordered by the second sort attribute, duplicates within this by the third and so on. A maximum of 5 sorts may be specified. When multiple attributes are used, ascending and descending order may be used in any combination. Variable length attributes may not be used as sort attributes. When fixed length attributes are used as sort attributes, only the first 20 characters and the first value is used for sort. .p0 All these options can be described using the following general syntax: .x SELECT command .x ALL keyword .x FROM keyword .x attname .x relname .x Equal sign (=) .x SORTED BY keyword .x WHERE keyword .x AND keyword .x OR keyword .x Conditions .s.tp13.lm+4.nf SELECT {attname1 [=fw1] [...attname [=fwN]]} + attnum1... attname1(i)... attname1(i,j)... attnum1(i)... attnum1(i,j)... ALL FROM relname + .s [SORTED BY attname [{=A}] ...] + D [WHERE condition1 [{AND} condition2 ...]] OR .f.lm-4.p0 If the sum of the lengths (or fwi) of the attributes requested exceeds the line capacity, the data line will be truncated. See Section 2.1.11.6 for further explanation of line width control. .x Width .x TALLY command .hl3 TALLY Command .x WHERE keyword The TALLY command prints a tally for an attribute giving each unique value .x TALLY command and the number of times it occurs in a relation. The tally is ordered ascending or descending per user input. Default is ascending. The WHERE .x Descending .x Ascending clause is optional and uses the same syntax as in the SELECT command. .x SELECT command .x attname .x FROM keyword .x WHERE keyword .x relname .x Equal sign (=) .s.tp2.lm+4 .nf TALLY attname [{=A}] FROM relname [WHERE ...] D .s.i-4 Examples of SELECT and TALLY commands: .send toc 1,The SELECT and TALLY Commands .x TALLY command .x SELECT command .s.tp10 SELECT ALL FROM AIRPLANE SELECT MODEL FROM AIRPLANE SELECT ALL FROM AIRPLANE WHERE WEIGHT GT 100000. *8 AND NUMPASS LT 200 SELECT AGE FROM PEOPLE WHERE NAME EQ BOB SELECT ALL FROM AIRPLANE SORTED BY MODEL=D TALLY MODEL FROM FLIGHTS TALLY MODEL FROM FLIGHTS WHERE CARRIER EQ UNITED SELECT ALL FROM DIMENS WHERE HEIGHT GTA WIDTH SELECT FILE TITLE=4 OWNER FROM PFDATA .f.lm-4 .hl2 Commands for Querying the Schema .COMMENT 2.1.5 .x Schema .x Query commands When you use any of these commands, RIM will display only the data you are authorised to access according to your current user password. .hl3 LISTREL Command .x LISTREL command The purpose of LISTREL is to provide you with information about the relations in the database. .p0 There are three formats for the LISTREL command. The first consists of simply entering: .s.i+4;LISTREL .p0 Using LISTREL in this fashion provides you with a list of all relations currently defined in your database. If you wish to display the definition of .x Definition, relations a specific relation, then the syntax is: .s.i+4;LISTREL relname .x relname .x LISTREL command .p0 The use of LISTREL in this manner also provides a count of the number of rows defined for the specified relation. .x Row .s.i+4;LISTREL ALL .x ALL keyword .p0 .x Password .x Restrictions This command (restricted by user password) will display the definitions of all .x Definition, relations relations in the database, including counts of the number of defined rows in .x Row each relation. .hl3 EXHIBIT Command .x EXHIBIT command The purpose of the EXHIBIT command is to allow you to query the RIM .x Query commands .x EXHIBIT command dictionary to obtain the names of all relations having a specific set of attributes. For example, if you want to know which relations contain the attribute attname you would enter: .x attname .s.i+4;EXHIBIT attname .x attname .p0 You would then obtain either a list of the relations having this attribute, or a message indicating that this attribute was not found in any relations in the database. .p0 The EXHIBIT command also allows you to query for a list of attributes .x Query relation (maximum of 10). Suppose that you wanted to know which relations contain both attname1 and attname2. The command would then be: .s.i+4;EXHIBIT attname1 attname2 .p0 .x attname The general syntax of this command is: .s.i+4;EXHIBIT attname1 [attname2 .._. attnameN] .hl3 PRINT RULES Command .x PRINT RULES command .x Constraints .x Definition, rules This command can be used when the current user password matches the owner .x Password password of the database definition. To obtain a complete list of all constraint rules enter: .x Rules .s.i+4;PRINT RULES .tp12 .hl2 Computation Command .COMMENT 2.1.6 .hl3 COMPUTE Command .COMMENT 2.1.6.1 .x COMPUTE command .x WHERE keyword The COMPUTE command is used to compute simple functional values of an .x COMPUTE command attribute. A WHERE clause is optional and uses the same syntax as is used in the SELECT command. .x SELECT command .x FROM keyword .x WHERE keyword .x relname .x attname .x COUNT keyword .x MAX keyword .x MIN keyword .x AVE keyword .x SUM keyword .s.lm+4.tp5.nf COMPUTE {COUNT} attname FROM relname [WHERE ...] MAX MIN AVE SUM .f.lm-4.p0 .x -0- .x Missing value (-0-) .x Restrictions There are some restrictions as to the type and word length of the attribute when using these computed functions. All of these functions exclude any -0- values when making their computations. The following table describes the attribute type and length restrictions for each function: .x COUNT keyword .x MAX keyword .x MIN keyword .x AVE keyword .x SUM keyword .s.lm+4.tp7.nf .send toc 3,COMPUTE Attribute Restrictions ^&Function Attribute_ Type Attribute_ Length\& COUNT any any MIN any of fixed length 1 for non-text, <= for text MAX any of fixed length 1 for non-text, <= for text AVE int, real, double 1 SUM int, real, double 1 .s.i-4 Examples of the COMPUTE command: .send toc 1,The COMPUTE Command .s.tp3 COMPUTE AVE NUMPASS FROM FLIGHTS COMPUTE MAX WEIGHT FROM FLIGHTS WHERE NUMPASS LT 100 COMPUTE COUNT NAME FROM PEOPLE WHERE AGE GT 30 .f.lm-4 .hl2 Database Modification Commands .COMMENT 2.1.7 These commands are used to change the contents of the database. A modify or owner password correlation is required in order to use them. .x Password .hl3 CHANGE Command .x CHANGE command The CHANGE command is used to change the value of an attribute in a relation .x CHANGE command where certain conditions are met. .x TO keyword .x IN keyword .x WHERE keyword .x attname .x value .x relname .s.tp3.nf.lm+4 CHANGE {attname1} TO value [IN relname] WHERE ... attname(i) attname(i,j) .f.lm-4.p0 .x WHERE keyword value has the same form as described in Section 2.1.3. The WHERE clause is required and uses the same syntax as in the SELECT command. If the relation .x SELECT command name is not specified, the attribute is changed in all relations where the attribute is found and the conditions are met. .hl3 DELETE ROW Command .x DELETE ROW command The DELETE ROW command is used to delete selected rows in a relation. .x Row .x FROM keyword .x WHERE keyword .s.i+4;DELETE ROW FROM relname WHERE ... .p0 .x WHERE keyword The name of the relation must be specified as well as a WHERE clause. The syntax for the WHERE clause is the same as in the SELECT command. .hl3 DELETE DUPLICATES Command .x DELETE DUPLICATES command .x JOIN command .x INTERSECT command .x SUBTRACT command .x PROJECT command This command is used to remove any duplicate rows from a relation. It is .x Row .x Row deletion .x Remove rows particularly useful on relations which have been created by any of the relational algebra commands (JOIN, INTERSECT, SUBTRACT, or PROJECT). The syntax for this command is: .x DELETE DUPLICATES command .x FROM keyword .x attname .x relname .s.i+4;DELETE DUPLICATES [attname1, attname2,...] FROM relname .p0 Duplicates are checked only for the specified (combination of) attribute(s). The default is to check the complete row (all attributes). .p0 .x DELETE DUPLICATES command .x CHANGE command .x DELETE ROW command Examples of CHANGE, DELETE# ROW, and DELETE# DUPLICATES commands: .send toc 1,The CHANGE and DELETE Commands .s.tp5.nf.lm+4 CHANGE NUMPASS TO 320 IN AIRPLANES WHERE MODEL EQ 747SP CHANGE NAME TO ROBERT WHERE NAME EQ BOB DELETE ROW FROM AIRPLANES WHERE MODEL EQ DC10 CHANGE STABILITY TO LOW IN DIMENSIONS WHERE HEIGHT GTA WIDTH DEL DUP NUMPASS FRO AIRPLANES .f.lm-4 .hl2 Schema Modification Commands .COMMENT 2.1.8 .x Schema .x CHANGE OWNER command These commands are used to change the database schema definition. Except for the CHANGE OWNER command, a modify or owner password correlation is required .x Password in order to use these commands. .hl3 CHANGE OWNER Command .x CHANGE OWNER command .x Password The CHANGE OWNER command is used to change the name of the database password. Only the current owner is allowed to use this command. .x TO keyword .s.i+4;CHANGE OWNER TO newowner .x newowner .hl3 RENAME ATTRIBUTE Command .x RENAME ATTRIBUTE command .x Schema The RENAME ATTRIBUTE command is used to change the name of an attribute in .x RENAME command the database definition (schema). .x Definition, schema .x attname .x TO keyword .x IN keyword .x relname .s.i+4;RENAME [ATTRIBUTE] attname1 TO attname2 [IN relname] .p0 The old name is attname1 and the new name is attname2. If the name of the relation is not specified, then the name change takes place in every relation that contains the old name. If a relname is specified, and attname1 occurs more than once, the first occurrence will be changed. .p0 .x Key RULES and KEY(s) defined for attname1 will automatically be .x RULES keyword redefined to apply to attname2. .P0 Note that the ATTRIBUTE part of the command name is optional, i.e_. RENAME on its own is taken as a RENAME#ATTRIBUTE command, not as RENAME#RELATION. .p0 Examples of the RENAME command: .send toc 1,The RENAME Command .x RENAME ATTRIBUTE command .s.tp2 .i+4;RENAME ATTRIBUTE MODEL TO VERSION IN AIRPLANES .i+4;RENAME NUMPASS TO CAPACITY .hl3 BUILD KEY Command .x BUILD KEY command .x Definition, relations This command is used to change an attribute from non-KEY to KEY. An index is .x KEY attribute built from existing data values by making a pass through current rows of the .x Row specified relation. This index is then used and maintained just as if the attribute had been declared to be KEY in the original database definition. .x BUILD KEY command .x FOR keyword .x IN keyword .x attname .x relname .s.i+4;BUILD KEY FOR attname IN relname .p0 Keys are not transferred to relations created by relational algebra commands. .hl3 DELETE KEY Command .x DELETE KEY command .x Non-KEY attribute This command is used to change an attribute from KEY to non-KEY. The index .x KEY attribute file for that attribute is deactivated and no longer maintained or used once the attribute has been changed to non-KEY with this command. .x FOR keyword .x IN keyword .s.i+4;DELETE KEY FOR attname IN relname .x relname .x attname .hl3 CHANGE PASSWORD Command .x CHANGE PASSWORD command .x Password The read or modify passwords may be changed by using the following command: .x RPW keyword .x MPW keyword .x TO keyword .x FOR keyword .x newpass .x relname .s.tp2 .i+4;CHANGE {RPW} TO newpass FOR relname .i+12;MPW .hl3 RENAME RELATION Command .x RENAME RELATION command You may change the name of a relation by using the following command: .x TO keyword .x newname .x relname .s.i+4;RENAME RELATION relname TO newname .p0 RULES applying to relname will automatically apply to newname. .P0 Note that the RELATION part of the command is required, to distinguish RENAME#RELATION from RENAME#ATTRIBUTE. .hl3 REMOVE Command .x REMOVE command The REMOVE command is used to remove a relation definition and its data from .x Definition, relations the database. .s.i+4;REMOVE relname .x relname .hl2 Relational Algebra Commands .COMMENT 2.1.9 .x Password These commands allow you to create new relations from existing relations. All relational algebra commands require modify permission on the constituent relations. .hl3 INTERSECT Command .x INTERSECT command The purpose of the INTERSECT command is to allow you to combine the rows of .x Row relations into a third relation based on common values within a set of specified attributes. The syntax of the INTERSECT command is: .x INTERSECT command .x WITH keyword .x FORMING keyword .x USING keyword .x relname .x attname .s.tp3 .i+4;INTERSECT relname1 WITH relname2 FORMING relname3 + .s .i+4;[USING attname1 [attname2 .._. attnameN]] .p0 .x USING keyword The USING clause identifies the attributes that form the resulting relation. The attributes used in the INTERSECT process are the subset of those .x INTERSECT command identified by the USING clause which are present in both relations. .p0 For example, assume that you have the following two relations defined: .s2.tp8 .send toc 1,The INTERSECT Command .c;REL1############################REL2 .s .c;NAME#####DEPT######JOB########DEPT#######JOB##########PAY .c;----#####----######----#######----#######----#########--- .c;BOB######A#########ENGR#######A##########ENGR#########800 .c;JIM######C#########SUPR#######B##########ENGR#########450 .c;BOB######B#########ENGR#######C##########ENGR#########750 .c;RAY######C#########ENGR################################## .p0 .x Restrictions .x USING keyword Then you may INTERSECT two relations restricted to specific sets of attributes .x INTERSECT command (the USING clause) or use all attributes of both relations. In either case, RIM will identify the common attributes and use the common values within these attributes to identify the conditions for intersect generation. .p0 Suppose you want to INTERSECT the two relations using attributes DEPT, NAME, and JOB. The command for this would be: .s.i+4;INTERSECT REL1 WITH REL2 FORMING REL3 USING DEPT NAME JOB .s The result would be the new relation REL3: .s.tp7 .c;REL3 .s .c;DEPT#####NAME######JOB# .c;----#####----######---- .c;A########BOB#######ENGR .c;B########BOB#######ENGR .c;C########RAY#######ENGR .p0 .x DELETE DUPLICATES command .x Restrictions .x USING keyword In this example there are no duplicate rows in REL3. However, it is possible .x Row that the intersect command will create duplicate rows. Since, in general, .x INTERSECT command duplicate rows are not desired in a relation, they can be removed with the DELETE# DUPLICATES command. Note also that by specifying which attributes the INTERSECT is using, you restrict the number of attributes in the resulting relation to only those specified in the USING clause. .p0 Suppose you want RIM to use all the attributes in the two relations. In this instance you would enter: .s.i+4;INTERSECT REL1 WITH REL2 FORMING REL4 .p0 The result would be REL4 consisting of the attributes NAME, DEPT, JOB, and PAY, shown below in the resulting rows: .s.tp7 .c;REL4 .s .c;NAME####DEPT#####JOB######PAY .c;----####----#####----#####--- .c;BOB#####A########ENGR#####800 .c;BOB#####B########ENGR#####450 .c;RAY#####C########ENGR#####750 .x INTERSECT command .p0 There may be situations where an INTERSECT is impossible to perform. These include: .list .le;The name of the resulting relation already exists. .le;The two relations have no common attributes. .le;The attributes in the USING clause do not exist in the relation being intersected. .le;The resulting relation exceeds 1021 words. .els0.p0 If any of the above situations is encountered, you are warned of the problem and the INTERSECT command processing is stopped. In the case where common .x INTERSECT command attribute names exist but there are no matching values, the operation will be successful, resulting in an empty relation (0 rows). .p0 The INTERSECT command is a powerful tool and may be used as a step towards .x INTERSECT command satisfying queries which require attributes from more than one relation. .hl3 JOIN Command .x JOIN command The JOIN command is a function operating on two relations to form a third relation. The purpose of the JOIN is to juxtapose two relations based on a specified attribute from each. The result of the JOIN command is a third relation containing all of the attributes from both relations. Rows are .x Row generated in the new relation as a result of the comparison conditions between attributes being satisfied. The syntax of the JOIN command is: .x USING keyword .x WITH keyword .x FORMING keyword .x WHERE keyword .x relname .x attname .x EQ keyword .x NE keyword .x GT keyword .x GE keyword .x LT keyword .x LE keyword .s.tp8.nf.lm+4 JOIN relname1 USING attname1 WITH relname 2 USING + .s attname2 FORMING relname3 [WHERE {EQ}] NE GT GE LT LE .f.lm-4.p0 .x EQ keyword .x WHERE keyword The WHERE clause of the JOIN command is different form the WHERE clause of .x JOIN command the SELECT command. In JOIN it applies only to the comparison of the two attributes upon which JOIN is based. If the WHERE clause is omitted (default), EQ is used. .p0 .x Row The value of attname1 in the first row of relname11 is compared to all the values of attname2. Rows which qualify are generated in relname3. The value .x Row of attname1 in the second row of relname1 is compared to all the values of attname2, etc.. Each row from relname1 may generate 0, 1, 2, or more rows in relname3. .p0 For example, consider the relations REL1 and REL2: .send toc 1,The JOIN Command .s.tp6 .c;REL1######################REL2 .s .c;#A########B########C############D########E# .c;---######---######---##########---######--- .c;#1########2########3############3########1# .c;#4########5########6############6########2# .c;#7########8########9####################### .p0 The following JOIN command would produce the result shown: .s.nf.lm+4.tp3 JOIN REL1 USING B WITH REL2 USING D + .s FORMING REL3 WHERE LT .s2.tp7.lm-4 .c;REL3 .s .c;#A########B#########C##########D#########E# .c;---######---#######---########---#######--- .c;#1########2#########3##########3#########1# .c;#1########2#########3##########6#########2# .c;#4########5#########6##########6#########2# .f.p0 The JOIN will function correctly on any comparison providing that you compare attributes of the same data type. All attribute names in the resultant relation must be unique in order for you to obtain accurate results from subsequent commands using the relation. Any duplicate attribute names should be change using the RENAME command before doing queries or updates to the new .x RENAME ATTRIBUTE command relation. In the case of duplicate attribute names, RENAME when applied to a specific relation will change the first attribute name. .p0 There may be situations where a JOIN is impossible to perform. These may .x JOIN command include: .list .le;The name of the resulting relation already exists. .le;The attribute in the USING clause does not exist in the relation being joined. .le;The attributes being compared are different data types or lengths. .le;An attribute in either of the relations greater than 300 computer words. .le;The resulting relation exceeds 1021 words. .els0.p0 If any of the above situations are encountered you are warned of the problem and the JOIN command processing is stopped. .hl3 PROJECT Command .x PROJECT command .x Row The function of a PROJECT command is to create a new relation as a subset of .x PROJECT command an existing relation. You may want to create the new relation from the old one by removing attributes, removing rows, or both. The syntax for the PROJECT command is: .x FROM keyword .x USING keyword .x ALL keyword .x WHERE keyword .x relname .x attname .s.tp3.nf.lm+4 PROJECT relname1 FROM relname2 USING {attname1 ... attnameN} + ALL [WHERE ...] .f.lm-4.p0 .x WHERE keyword The WHERE clause is optional but it is specified, it has the same syntax as in the SELECT command. You are required to specify which attributes are to be retained in the new relation. The old relation is relname2 and the new relation is relname1. .p0 For example, consider the following relation: .send toc 1,The PROJECT Command .s.tp8 .c;PEOPLE .s .c;EMPNUM#####EMPNAME######BOSS######POSITION########GROUP .c;------#####-------######------####--------########----- .c;#2181######JONES########SMITH#####MANAGER#########AADE# .c;#3964######ERICKSON#####BUSS######APPL-MGR########ACC## .c;#6543######GRAY#########PARKER####ASST-MGR########PHOTO .c;#2233######SCHMITZ######BUSS######APPL-MGR########ACC## .p0 To create a new relation with EMPNAME and GROUP as the only attributes and where now rows contain PARKER as BOSS enter the command: .x Row .nf.lm+4.s.tp2 PROJECT TEMP1 FROM PEOPLE USING EMPNAME GROUP + .s WHERE BOSS NE PARKER .s.tp7.lm-4 .c;TEMP1 .s .c;EMPNAME#########GROUP .c;--------########----- .c;JONES###########AADE# .c;ERICKSON########ACC## .c;SCHMITZ#########ACC## .f.p0 .x DELETE DUPLICATES command The PROJECT command is useful to reduce the size of a relation when only a .x PROJECT command subset of the data is needed. RIM will not eliminate any duplicate rows .x Row formed in the new relation. You must do that yourself with the DELETE# DUPLICATES command. .p0 There may be situations where a PROJECT is impossible to perform. These include: .list .le;The name of the resulting relation already exists. .x USING keyword .x WHERE keyword .le;An attribute in the USING or WHERE clause is not in the relation. .els0 .hl2 SUBTRACT Command .COMMENT 2.1.10 .x SUBTRACT command .x Row .x WHERE keyword The SUBTRACT command is similar to the PROJECT command in that the new .x PROJECT command .x SUBTRACT command relation is a subset of an existing relation. The rows, however, are selected based on the data in another relation rather than on a WHERE clause within the same relation. Where the INTERSECT command looked for rows of two relations .x INTERSECT command which matched up, the SUBTRACT command does just the opposite. It looks for .x SUBTRACT command rows in the relation which do not match any rows in the other relation. The syntax for the SUBTRACT command is: .x FROM keyword .x FORMING keyword .x USING keyword .x relname .x attname .s.i+4;SUBTRACT relname1 FROM relname2 FORMING relname3 + .s.i+4;[USING attname1 [attname2 .._. attnameN]] .p0 .x USING keyword All rows in the new relation will come from relname2. If the USING clause is .x Row not specified, then all attributes of relname2 will be attributes of relname3. relname1 is the relation that rows of relname2 are checked against for matches. If a USING clause is specified, at least one of the attributes in the clause must be common to both relations. .p0 As an example, consider these two example relations: .send toc 1,The SUBTRACT Command .s.tp8 .c;EMPDATA#####################BOSSDATA .s .c;EMPNUM###EMPNAME###BOSS#########BOSS#####POSITION###GROUP .c;------###-------###------#######------###--------###----- .c;#2181####JONES#####SMITH########SMITH####MANAGER####AADE# .c;#3964####ERICKSON##BUSS#########PARKER###ASST-MGR###PHOTO .c;#6543####GRAY######PARKER#######BUSS#####APPL-MGR###ACC## .c;#7193####BROWN#####WHITE################################# .p0 The following command will produce a new relation from EMPDATA: .s.tp3.i+4 SUBTRACT BOSSDATA FROM EMPDATA FORMING TEMP USING + .s.i+4 EMPNAME BOSS .p0 The resulting relation TEMP would contain only one row: .s.tp5 .c;TEMP .s .c;EMPNAME##BOSS# .c;-------##----- .c;BROWN####WHITE .p0 There may be situations where a SUBTRACT is impossible to perform. These .x SUBTRACT command include: .list .le;The name of the resulting relation already exists. .le;The relations have no common attributes. .le;The number of attributes in the USING clause is greater than the number in relname1. .le;An attribute in the USING clause is not in the relations. .els0 .hl2 Report Generation Commands .COMMENT 2.1.11 These commands establish a limited report generation capability. .hl3 NEWPAGE Command .x NEWPAGE command This command causes a new page to be issued. It applies to batch output only. .x Batch job The command is: .s.i+4;NEWPAGE .x NEWPAGE command .hl3 BLANK Command .x BLANK command .x Blank lines Blank lines can be inserted into the output stream by using the command: .s.i+4;BLANK n .s where n is the number of blank lines written. .hl3 TITLE Command .x TITLE command The command: .s.i+4;TITLE "titlestring" .x TITLE command .s causes the text "titlestring" to be printed, centered on the line. If the length of "titlestring" is longer than the current line's width it will be .x Width truncated and a warning issued. .hl3 DATE Command The command: .s.i+4;DATE .x DATE command .s will cause the current date to be printed, centered on the line. .hl3 LINES Command .x Lines per page .x LINES command This command controls the number of lines per page (exclusive of title.) The command is: .s.i+4;LINES n .s will establish page size to n lines. Default is 56. .hl3 WIDTH Command .COMMENT 2.1.11.6 This command controls the width of a printed line. The command: .s.i+4;WIDTH n .s .x WIDTH command .x Terminal will establish a line width of n characters. The default is 78 if output is to a terminal, or 132 if output is to a batch printer. If n is specified to be less .x Batch job than 20, 20 will be used. .hl2 Communication Command .hl3 UNLOAD Command .x UNLOAD command .x FOR006 The UNLOAD command permits you to offload a portion or all of your database onto a previously designated file (see OUTPUT command). The file will contain .x OUTPUT command 80-character text records, and can be read by RIM as an input file on the same or on a different computer using the INPUT command. Default file name is .x INPUT command FOR006. The syntax of this command is: .x UNLOAD command .x ALL keyword .x SCHEMA keyword .x DATA keyword .x dbname .x newname .x relname .x mpw .x Equal sign (=) .s.tp4.nf.lm+4 UNLOAD [dbname = newname] {ALL } + SCHEMA DATA [relname1 [mpw1] relname2 [mpw2] ...] .f.lm-4.p0 Specifying SCHEMA will offload the schema of your database, DATA will .x SCHEMA keyword offload the data of your data base and ALL will offload both schema and data. .p0 .x Equal sign (=) You may optionally rename your database by entering dbname#=#newname where .x dbname dbname is the name of the currently open database. By specifying relation names, you will only offload data and/or schemas for the specific relations. The modify password does not allow you to modify access to the relation. .x Password .p0 .x Restrictions .x Rules There are implicit password restrictions to the UNLOAD command as follows: If .x Password you are the database owner, you may offload any data and/or schema. If you are not the owner, you may offload data and/or schema for the relations for which you have modify access permission. Your password becomes the owner of the offloaded database. Rules, if any, will only be offloaded if you are the owner of the database and you have used the option ALL. .hl2 System Command .hl3 Spawn DCL Command .x Brace command .x DCL .x Spawn It is sometimes convenient to be able to issue a command to the VMS DCL interpeter, and have it executed, without leaving RIM. For example, you may receive notification of a MAIL message, and want to read it, without losing your current selections or needing to save and restore them. To permit this, RIM takes any line beginning with a right brace (}), removes the brace, and spawns the remainder of the line to DCL, as if you had typed it to the system $ prompt. For example:- .s.i+4;}SHOW USERS .s will tell you who is logged in to the system, and then return to RIM. .page .hl1 MENU MODE EXECUTION OVERVIEW .x Menu mode .x Definition, schema The RIM menu mode provides you with the capability to build the schema for a .x Schema new database and to update an existing database definition. .p0 .x Query option The options (create, update, query, command, and exit) available in menu mode are shown in Figure 2-2. .p0 Executions may be terminated at any time by entering the word QUIT. EXIT, in .x EXIT command response to an input prompt, will return you to the top menu. The database will be purged following a QUIT command. .x QUIT command .s.tp28.nf.lm+4 +----------------+ | Begin RIM 5.1 | +----------------+ | | RIM COMMAND MODE ENTER "MENU" FOR MENU MODE R>MENU | | | Select the execution option desired: 1) CREATE a new database 2) UPDATE an existing database 3) QUERY an existing database 4) ENTER command mode 5) EXIT | +--------------+---+---------+---------+---------+ | | | | | | | | | | CREATE OPTION | QUERY OPTION | EXIT Section 2.2.1 | Section 2.2.3 | Section 2.1.1.13 | | UPDATE OPTION COMMAND MODE Section 2.2.2 Section 2.1 .f.lm-4.s.c;Figure 2-2 -- Section References for the Menu Mode Options .send toc 2,2,Section References for the Menu Mode Options .x Menu mode .hl2 Database Creation Option .COMMENT 2.2.1 .x Database creation option .x Password The purpose of this option is to construct a schema by prompting you for the .x Schema database, owner, the names of the relations, their associated attributes and read/modify passwords. .p0 .x Schema After compilation of the schema, you have the opportunity to interactively load the database and/or query the database. .x Query mode .p0 In this command mode, you have available the full set of RIM commands (Section 2.1) allowing the direct definition of the schema using the DEFINE submodule .x DEFINE command .x Definition, schema commands and the loading of the database using the LOAD submodule commands. .x LOAD command .hl2 Database Update Option .COMMENT 2.2.2 .x Database update option .x Password With this option you may add/modify relations and/or load additional data into the database. If additional relations are desired, you are prompted for the names of the relations, their associated attributes and read/modify passwords. If additional data is to be loaded, the list of relations in the database is displayed and your enter the required data. Removal or modification of data in the database is done using the RIM database modification commands. .p0 In this command mode, you have available the full set of RIM commands (Section 2.1) allowing the direct addition of relations using the DEFINE submodule .x DEFINE command commands and the loading of data using the LOAD submodule commands. The .x LOAD command database modification commands are used to update existing data. .hl2 Query Option .COMMENT 2.2.3 .x Query option With this option you are prompted for the database name. The full set of RIM commands (Section 2.1) is available to you for database query. In addition to query, all other database activities are available through the RIM command mode. .hl1 RIM MENU MODE INTERACTIVE DIALOGUE .COMMENT 2.3 .x Menu mode This section presents the questions and menus that appear in the menu mode. The response options are also discussed. .p0 The menu mode is accessed by entering MENU any time in the command mode when an R> prompt is present. .hl2 General Option and Questions .tp6.nf SELECT THE EXECUTION OPTION DESIRED .lm+4 1) CREATE a new database 2) UPDATE an existing database 3) QUERY an existing database 4) ENTER command mode 5) EXIT .s.tp8.i-4 SELECT THE UPDATE OPTION DESIRED 1) DEFINE additional relations 2) LOAD additional data .f.p0 The desired update option is selected by entering either the integer 1, allowing the definition of .x Definition, relations additional relations, or 2, allowing the loading of additional data into the database. .s.tp4.i-4 DO YOU WANT TO QUERY THE DATABASE AT THIS TIME--Y OR N .x Query option .p0 You may switch to the command mode for query by entering Y. If the query option is not desired, enter N. .lm-4 .hl2 Database Files .lm+4.tp5.i-4 ENTER THE NAME OF THE DATABASE .p0 .x Logical files The 1-6 character alphanumeric name assigned to the .x Alphanumeric database is entered here. The name is used to create the names of the logical files that contain the database. .lm-4 .hl2 Schema Definitions .COMMENT 2.3.3 .x Definition, schema .x Schema .lm+4.tp5.i-4 ENTER THE NAME OF THE DATABASE .p0 The 1-6 character alphanumeric name assigned to the database .x Alphanumeric is entered here. All future references to this data will be via the assigned database name. .s.tp6.i-4 ENTER THE NAME OF THE DATABASE OWNER .p0 .x Password The 1-8 character alphanumeric name of the database owner .x Alphanumeric is entered here. This name is used as the schema password. .x Schema Additional schema definitions will not be permitted unless .x Definition, schema the user password matches the owner password assigned here. .s.tp4.i-4 ENTER THE NAME ASSIGNED TO THIS RELATION .p0 A 1-8 character alphanumeric name assigned to the relation being defined. .x Alphanumeric .s.tp7.i-4 ENTER THE READ PASSWORD FOR THIS RELATION .p0 A 1-8 character alphanumeric string assigned by the owner .x Alphanumeric as the read password for the relation being defined. If .x Password the owner has assigned a read password the user password must match in order to query the relation. If no read .x Query relation password is desired, enter NONE. .s.tp7.i-4 ENTER THE MODIFY PASSWORD FOR THIS RELATION .p0 A 1-8 character alphanumeric string by the owner as the .x Alphanumeric modify password for the relation being defined. If the .x Password owner has assigned a modify password the user password must match in order to load or modify the relation. If no modify password is desired, enter NONE. .s.tp7 .i-4;ENTER THE ATTRIBUTES OF THIS RELATION .i-4;ENTER END WHEN COMPLETE .x INT keyword .x REAL keyword .x TEXT keyword .x DOUB keyword .x RVEC keyword .x IVEC keyword .x DVEC keyword .x RMAT keyword .x IMAT keyword .x DMAT keyword .x attname .x type .x Row .x Column .x VAR keyword .s.nf attname type length (IF >) "KEY" (IF KEY) .s attname = 1-8 character alphanumeric string identifying .x Alphanumeric the attribute being defined. .s.tp10 type = INT (Integer) REAL (Real) TEXT (Text) DOUB (Double Precision) RVEC (Real Vector) IVEC (Integer Vector) DVEC (Double Precision Vector) RMAT (Real Matrix) IMAT (Integer Matrix) DMAT (Double Precision Matrix) .s.tp2 length = number of characters (text) or number of values (all others) .s.tp15 1,2,3 ..., etc., or VAR INT TEXT REAL DOUB RVEC IVEC DVEC .s row, column or RMAT row, VAR or IMAT VAR, VAR DMAT .x DOUB keyword .x DVEC keyword .x INT keyword .x REAL keyword .x IVEC keyword .x RVEC keyword .x Variable length .f.p0 A variable length (or length greater than one) INT, REAL, or DOUB can be considered to be functionally identical to IVEC, RVEC, or DVEC. .s .x KEY keyword KEY = the word KEY indicates the attribute is key. .p0 Example: To define a text string attribute (TEXTST) of 60 characters, a real attribute (TEXTST) of 60 characters, a real attribute (REAL1), an integer key .x Integer .x Real attribute (INT1), and a real matrix with dimensions 6x8 (MAT68), the .x Real following entries would be made: .s.tp4.nf.lm+4 R> TEXTST TEXT 60 R> REAL1 REAL R> INT1 INT KEY R> MAT68 RMAT 6,8 .f.lm-4.p0 To end the definition of the attributes for this relation, the word "END" is .x Definition, relations entered. .s.tp5.i-4;DO YOU HAVE ADDITIONAL RELATIONS TO DEFINE--Y OR N .p0 Additional relations may be defined by entering the character Y. If no additional relations are to be defined at this time, enter N. .lm-4 .hl2 Database Loading .lm+4.tp5.i-4 DO YOU WANT TO LOAD THE DATABASE--Y OR N .x Load relation .s The database is available for data loading if desired. Enter Y if you want to load the database at this time. Enter N if no data is to be loaded. .s.tp5.i-4 SELECT THE RELATION TO BE LOADED .b1 The relations defined in the database will be listed. You select the relation to be loaded by entering the integer corresponding to the desired relation. .s.tp4.i-4 ENTER THE MODIFY PASSWORD FOR THIS RELATION .s No data loading will be allowed for the selected relation unless the proper modify password is entered here. .x Password .s.tp7 .i-4;ENTER THE ATTRIBUTE VALUES IN THE SPECIFIED SEQUENCE .i-4;ENTER END WHEN COMPLETE .s .x Commas .x Blanks, embedded .x Quotation marks .x Blanks, leading .x Blank filled .x Fixed length Entering data values at this point loads the database. The values are entered in the order indicated and the value entered must correspond to the attribute type. If a text string contains embedded blanks, or commas, or if entirely numeric text is entered, it must be enclosed in quotation marks. Unused trailing characters in fixed length text strings will be blank filled. It is recommended that leading blanks not be used in text strings. If vectors or .x Vectors matrices are loaded, all values must be specified. Enter "END" when data .x Matrices loading is complete. It is recommended that large databases and databases that have vectors and matrices use the application program interface for .x Application program loading data. .s.tp4.i-4 DO YOU HAVE ADDITIONAL RELATIONS TO LOAD--Y OR N .x Load relation .s If you want to load another relation, enter Y. If all the database to be loaded at this time has been loaded, enter N. .lm-4 .CHAPTER EXECUTION THROUGH THE APPLICATION PROGRAM INTERFACE .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st Execution Through the Application Program Interface .x Application program .x RIMLIB.OLB .x Row Any programming language which can call FORTRAN subroutines can access and .x Subroutines .x FORTRAN modify a predefined RIM database through FORTRAN-callable subroutines contained in the RIM application program interface library (RIMLIB). Data is accessed one row at a time. The RIM data access subroutines store data in, and .x Subroutines retrieve data from, an array you provide in your program logic. In either case the array used must be large enough to hold one complete row for each relation accessed. .p0 .x Blank filled .x INT keyword .x REAL keyword Attributes which contain text data must be given particular care. In general, Hollerith format (left adjusted, blank filled) is used. Some textual parameters like those for database, relation and attribute names must allow for eight characters (8H), others like key words such as INT, REAL etc_. must allow room for four characters (4H). Values of textual attributes or text strings used in conditional expressions are passed in an array packed together with other kinds of information. Such text strings are left adjusted with unspecified fill. The number of words such text strings occupy depends upon the length of the text string. There are special instructions in appropriate sections on how to pass such attributes. .p0 .x Logical files The application program interface requires you to manage the database files. .x Application program The database files must exist on three properly named logical files before your program can be executed. .p0 Password checks operate in the application program interface in much the same way as in the standalone system. No password permission is required for .x Password .x Standalone program RMOPEN, RMUSER, RMRULE, or RMTOL. Read permission is required for all other .x RMOPEN subroutine .x RMUSER subroutine .x RMRULE subroutine .x RMTOL subroutine calls except RMLOAD and RMPUT, for which modify permission is required. .x RMLOAD subroutine .x RMPUT subroutine Modify permission implies read permission. .hl1 INITIALISING THE DATABASE .tp8 .hl2 RMOPEN .x Open database .x RMOPEN subroutine .x dbname .nf.lm+4.tp5 ^&CALL_ RMOPEN_ (dbname)\& Input parameter: .s dbname -- the name of the database in Hollerith format .f.lm-4.p0 This routine initialises the internal tables used by RIM and opens the specified database by reading the database control information into the in-core working areas. .hl2 RMCLOS .x Close database .x RMCLOS subroutine .i+4;^&CALL_ RMCLOS\& .p0 This routine closes the current database and copies the in-core working areas to the logical database files. This routine is required (if you have modified the database) before your program can access another database. .hl1 STATUS OF DATABASE ACTIVITY .x RIMCOM common block When an operation on the database has been attempted, the status of the operation is returned to the application program via the RMSTAT variable in .x Application program the RIMCOM common block. This common block must be declared in the calling program as follows: .x RIMCOM common block .x RMSTAT subroutine .s.tp2 .i8;COMMON /RIMCOM/ RMSTAT .i8;INTEGER RMSTAT .p0 The value of RMSTAT should be checked after each operation. A nonzero value indicates the operation was not successful. As a result, subsequent operations may not function as expected. The RMSTAT values and meanings are as follows:- .x Error codes .s.tp7.nf.lm+5 .send toc 3,RMSTAT Error Codes -1 No more data available for retrieval #0 Operation successful 10 Database files do not contain a RIM database 11 Database name does not match file contents 12 Incompatible database files (date,time,etc.) 13 Database is attached in read only mode 14 Database is being updated 15 Database files are not local files 16 Database has been opened 20 Undefined relation 30 Undefined attribute 40 More than 10 AND/OR operators in the WHERE clause 41 Illegal "LIMIT EQ N" condition 42 Unrecognised comparison operator 43 EQS only available for text attributes 44 Illegal use of MIN/MAX in the WHERE clause 45 Unrecognised AND/OR operator 46 Compared attributes must be the same type/length 47 Lists are valid only for EQ and NE 50 RMFIND not called 60 RMGET not called 70 Relation reference number out of range 80 Variable length attributes may not be sorted 81 The number of sorted attributes is too large 89 Sort system error 90 Unauthorised relation access .lm-1 100 Illegal variable length row definition (load/put) 110 Unrecognised rule relations 111 More than 10 rules per relation .f.s.tp10.i-4 The following codes should not be encountered in normal use:- .x Error codes .s.nf.lm-1 1001 Buffer size problem -- BLKCHG,BLKDEF 1002 Undefined block -- BLKLOC 1003 Cannot find a larger B-tree value -- BTADD,PUTDAT 1004 Cannot find B-TREE block -- BTPUT 21XX Random file error XX on FILE1 22XX Random file error XX on FILE2 23XX Random file error XX on FILE3 24XX Random file error XX on FILE4 .f.lm-3 .hl1 GENERAL ROUTINES .x Password .x Rules The following routines are used to set the internal switches for rule checking, to specify the database passwords, and to set the tolerance for .x Tolerance real numbers. These routines may be called any number of times with the new .x Real value overwriting the current value. .tp9 .hl2 RMUSER .x RMUSER subroutine .x Password .nf.lm+4 ^&CALL_ RMUSER_ (password)\& Input parameter: .s password -- the password in Hollerith (8H) .f.lm-4.p0 This routine is used to provide the password necessary for checking database .x Password access, relation read permission and relation modify permission. .tp10 .hl2 RMRULE .x RMRULE subroutine .nf.lm+4 ^&CALL_ RMRULE_ (switch)\& Input parameter: .s switch -- 0 no rule checking (NOCHECK RULES) (int) 1 check rules (CHECK RULES) .f.lm-4.p0 This routine turns rule checking on and off (default: on if rules are defined). .x Rules .tp11 .hl2 RMTOL .x RMTOL subroutine .x Tolerance, absolute .x Tolerance, percent .nf.lm+4 ^&CALL_ RMTOL_ (val,percent)\& Input parameters: .s val ------ the value of the tolerance (real) percent -- 0 if "val" is the absolute tolerance value (int) 1 if "val" is the tolerance percent .f.lm-4.p0 .x Floating point This routine sets the tolerance for floating point numbers, .x Tolerance (default_: 0.0). .tp12 .hl2 RMDATE .nf.lm+4 ^&CALL_ RMDATE_ (dates)\& Output parameter: .s date -- receives the current date in the form: yy/mm/dd (8H) .lm-4.f.p0 This is the standard date format used by RIM, being that most suitable for sorting. .x RMDATE subroutine .x Date .tp9 .hl2 RMTIME .nf.lm+4 ^&CALL_ RMTIME_ (time)\& Output parameter: .s time -- receives the current time in the form: hh.mm.ss (8H) .x RMTIME subroutine .x Time .f.lm-4 .hl1 ACCESSING THE SCHEMA .x Schema The following routines are used to obtain information about the database schema. .tp9 .hl2 RMLREL .x RMLREL subroutine .i4;^&CALL_ RMLREL\& .p0 .x RMGREL subroutine This routine sets an implicit pointer (used by the routine RMGREL) to the first relation in the database. It must be called before data about any relations may be obtained. If there are no relations defined for which the current user password has read permission, RMSTAT will return 90, otherwise 0. .x RMSTAT subroutine .x Password .tp14 .hl2 RMGREL .x RMGREL subroutine .x relname .x Row .x Date .x mpw .nf.lm+4 ^&CALL_ RMGREL_ (relname,row,mpw,lastmod,numatt,numrows)\& Output parameters: .s.lm+2 relname -- relation name (8H) rpw ------ read password (.TRUE. or .FALSE.) mpw ------ modify password (.TRUE. or .FALSE.) lastmod -- date of last modification of relation data (8H) numatt --- number of attributes in the relation (int) numrows -- number of rows of data in the relation (int) .f.lm-6.p0 .x Password .x RMGREL subroutine This routine returns the data about the current relation (the relation indicated by the current pointers) and increments the implied pointer to address the next relation for which read permission is available. A successful execution of this routine sets RMSTAT equal to 0. If you change .x RMSTAT subroutine passwords between calls to RMLREL and RMGREL or between successive calls to .x RMLREL subroutine RMGREL, unpredictable results may occur. When the last relation is accessed RMSTAT will be set to -1. .p0 The following example shows how to use RMLREL and RMGREL to obtain the data about all relations in the database: .send toc 1,RMLREL and RMGREL Subroutines .s.tp5.nf . . . COMMON /RIMCOM/ RMSTAT INTEGER RMSTAT .tp3 . . . .tp2 CALL RMOPEN (dbname) CALL RMUSER (password) .tp3 . . . .tp2 CALL RMLREL IF (RMSTAT.EQ.0) GO TO 100 .tp3 . . . .tp2 C Print message that no relations are available C using the current password .tp3 . . . .tp3 GO TO 200 100 CONTINUE CALL RMGREL(rname,rpw,mpw,lastmod,numatt,numrows) .tp3 . . . C Print out the data about the relation, etc. ... .tp3 . . . .tp5 GO TO 100 200 CONTINUE . . . .f.tp9 .hl2 RMLATT .x RMLATT subroutine .x relname .nf.lm+4 ^&CALL_ RMLATT_ (relname)\& Input parameter: .s relname -- relation name (8H) .f.lm-4.p0 This routine sets an implied pointer to the first attribute of the specified relation. If the relation exists and the current password allows access to .x Password relational data, RMSTAT will return 0. .x RMSTAT subroutine .tp19 .hl2 RMGATT .x RMGATT subroutine .x attname .x Column .x Variable length .nf.lm+4 ^&CALL_ RMGATT_ (attname,type,matvec,var,len1,len2,column,key)\& Output parameters: .s.lm+2 attname -- attribute name (8H) type ----- attribute type (INT,REAL,DOUB,TEXT) (4H) matvec --- attribute type (VEC or MAT -- otherwise blank) (4H) var ------ variable length attribute (.TRUE. or .FALSE.) len1 ----- attribute length data as follows (int): TEXT -- number of characters INT,REAL,DOUB,VEC -- number of items MAT -- row dimension len2 ----- column location in the relation (otherwise 0) (int) column --- attribute column location in the relation (int) key ------ keyed attribute (.TRUE. or .FALSE.) .f.lm-6.p0 This routine returns the data about the current attribute (the attribute indicated by the implied pointer) and increments the implied pointer to point to the next attribute. When the last attribute is accessed, RMSTAT will return -1. .x RMSTAT subroutine .p0 .x ALL keyword .x RMLREL subroutine .x RMGREL subroutine .x RMLATT subroutine .x RMGATT subroutine The following example shows the use of RMLREL, RMGREL, RMLATT, and RMGATT to obtain the data about all attributes for all relations (the equivalent of LISTREL# ALL): .send toc 1,RMLATT and RMGATT Subroutines .x LISTREL command .s.nf.tp5 . . . COMMON /RIMCOM/ RMSTAT INTEGER RMSTAT .tp3 . . . .tp2 CALL RMOPEN(dbname) CALL RMUSER(password) .tp3 . . . .tp8 CALL RMLREL 100 CONTINUE CALL RMGREL(rname,rpw,mpw,lastmod,numatt,numrows) IF (RMSTAT.NE.0) GO TO 300 CALL RMLATT(rname) DO 200 K=1,numatt CALL RMGATT(aname,type,matvec,var,len1,len2,column,key) IF(RMSTAT.NE.0) GO TO 300 .tp3 . . . C Print out the relation and attribute data, etc. ... .tp3 . . . .tp6 200 CONTINUE GO TO 300 300 CONTINUE . . . .f .hl1 ACCESSING THE DATABASE The routines which access the database allow the following operations: .list .x Row .x RMFIND subroutine .le;GET an existing row of data from a specified relation and store it in a local array (must be preceded by an RMFIND). .x RMFIND subroutine .le;LOAD a new row of data from a local array to the bottom of a specified relation (must be preceded by an RMFIND). .x RMFIND subroutine .le;PUT an existing row of data back into a specified relation after it has been modified (must be preceded by an RMFIND or RMGET). .x RMFIND subroutine .x RMGET subroutine .le;DELETE an existing row of data from a specified relation (must be preceded by .x DELETE ROW command an RMFIND or RMGET). .els0.p0 .x Sort .x RMFIND subroutine .x RMGET subroutine .x WHERE keyword Each of the above operations works on one row of data at a time. RMGET increments the pointers to point to the next row. The initial pointers must be established before the required operation can be performed (RMFIND). The rows returned may be qualified with a WHERE clause (default is all rows) and .x Row the rows may also be returned in a sorted order (RMGET only). .p0 To support concurrent access to multiple relation, a parameter is provided to allow the assigning of a number to identify the set of pointers for a given relation. In this way the operations on the database are related to a number which in turn corresponds to the pointers for a single relation. .tp10 .hl2 RMFIND .x RMFIND subroutine .x relname .nf.lm+4 ^&CALL_ RMFIND_ (number,relname)\& Input parameters: .s number -- number (0-5) assigns a pointer for the relation (int) relname -- relation name (8H) .f.lm-4.p0 .x RMGET subroutine .x RMWHER subroutine .x RMLOAD subroutine .x RMSORT subroutine This routine establishes the initial pointer number for a relation. A call to RMFIND must be made before calls to RMGET, RMWHER, RMLOAD, and RMSORT. .x RMFIND subroutine .tp19 .hl2 RMWHER .x Variable length .x RMWHER subroutine .x attname .x Column .x Row .nf.lm+4 ^&CALL_ RMWHER_ (number,attname,operator,value,numval,nextboo,numboo)\& Input parameters: .s.lm+2 number ---- number (0-5) identifies the relation pointer for this operation (int) attname --- array of attribute names (may also be attribute number, ROWS or LIMIT) where the nth attname corresponds to the nth WHERE clause (Hollerith) operator -- array of operators (EQ,GT,EQA,EXIS,FAIL,etc.) where the nth operator corresponds to the nth WHERE clause (each 4H) value ----- 2-dimensional array of (any type, fixed, or .lm+12 variable) where the nth row corresponds to the nth WHERE clause .s.tp6 The organisation of the array is dependent on the attribute type and length. Let vset represent a list of values (in most cases, the list has one in vset -- see the SELECT command). The rows are organised as follows: .s.tp6 Fixed length attributes------------------------------- vset(1),vset(2),...,vset(numval) where numval is equal to the number of values in the list (note if the EQA condition is used there can only be one member in the vset, see the SELECT command) .s.tp6 Variable length attributes---------------------------- TEXT -- c(1),0,vset(1),c(2),0,vset(2)............, c(numval),0,vset(numval) where c is the number of characters in the corresponding vset and numval is equal to the number of values in the list .s.tp5 INT,REAL,DOUB,VEC -- items(1),0,vset(1),items(2),0, vset(2),...,items(numval),0,vset(numval) where items is the number of items in the corresponding vset and numval is equal to the number of values in the list .s.tp4 MAT --- rows(1),col(1),vset(1), rows(2),col(2),vset(2),..., rows(numval),col(numval),vset(numval) where rows is the number of rows and cols is the number of columns in the matrix .lm-12.s.tp5 numval --- number of values in the list of values (vset) where the nth numval corresponds to the nth WHERE clause (int array) nextboo -- array of AND OR operators (each 4H) numboo --- number of WHERE conditions (int) .lm-6.f.p0 This routine qualifies a set of rows for retrieval (this corresponds to the WHERE clause). .p0 For example, if the following WHERE clause were required: .send toc 1,RMWHER Subroutine .x Variable length .s.tp8.nf.lm+4 WHERE ATT1 EQ 4 7 12 OR ATT2 EQS "TEXT STRING" AND ATT3 + .s GT 5. AND ATT3 EQA ATT4 .s (ATT1 -- integer length 1) (ATT2 -- text variable length) (ATT3 -- real length 1) (ATT4 -- real length 1) .s.tp9.i-4 The arrays would contain: .s attname(1) = 8HATT1 attname(2) = 8HATT2 attname(3) = 8HATT3 attname(4) = 8HATT3 operator(1) = 4HEQ operator(2) = 4HEQS operator(3) = 4HGT operator(4) = 4HEQA value(1,1) = 4 value(1,2) = 7 value(1,3) = 12 value(1,4) = value(1,5) = 0 value(2,1) = 11 value(2,2) = 0 value(2,3) = 4HTEXT value(2,4) = 4 H STR value(3,1) = 5. value(3,2) = value(3,3) = value(3,4) = value(3,5)=0 value(4,1) = 4HATT4 value(4,2) = value(4,3) = value(4,4) = value(4,5)=0 numval(1) = 3 numval(2) = 1 numval(3) = 1 numval(4) = 1 nextboo(1) = 4HOR nextboo(2) = 4HAND nextboo(3) = 4HAND nextboo(4) = 0 numboo = 4 .f.lm-4.p0 value would be dimensioned (4,5) in the above example. .tp16 .hl2 RMSORT .x RMSORT subroutine .x attname .x Ascending .x Descending .x Sort .nf.lm+4 ^&CALL_ RMSORT_ (number,attname,numsort,sortype)\& Input parameters: .s number --- number (0-5) identifies the pointer for the relation sorted (int) attname -- array of "numsort" attribute names to sort on (each 8H) numsort -- number of attributes to sort (int) sortype -- sort control numbers, corresponding to: attname LT 0 causes descending sort, GE 0 causes ascending sort (int array) .f.lm-4.p0 .x SORTED BY keyword This routine sorts the data prior to retrieval (this is equivalent to the SORTED BY clause). .p0 For example, if the following SORTED BY clause were required: .send toc 1,RMSORT Subroutine .x SORTED BY keyword .x Equal sign (=) .s.tp11.nf.lm+4 SORTED BY ATT1=A ATT2=A ATT3=D .s.i-4 The array would contain: .s attname(1) = 8HATT1 attname(2) = 8HATT2 attname(3) = 8HATT3 sortype(1) = 1 sortype(2) = 1 sortype(3) = -1 numsort = 3 .f.lm-4.tp10 .hl2 RMGET .x RMGET subroutine .x Column .x Row .x Variable length .nf.lm+4 ^&CALL_ RMGET_ (number,array)\& Input parameter: .s.lm+2 number -- number (0-5) identifies the relation pointer for this operation (int) .s.tp6.i-2 Output parameters: .s array --- array to receive the row of data (any type). Let "coli" be the column number in the relation for the i'th attribute (see RMGATT) .s.tp3 Fixed length attributes---------------------- Array (coli) contains the start of the value for the i'th attribute .s.tp4 Variable length attributes------------------- Array (coli) contains the pointer N which points to the start of the attribute data in array .s.tp4 Array(N) contains one of the following: TEXT -- number of characters INT,REAL,DOUB,VEC -- number of items MAT(N+2),... contains attribute values .f.lm-6.p0 This routine gets a row of data from the specified relation and advances the pointer to the next qualifying row (as determined by RMWHER and RMSORT .x RMSORT subroutine .x RMWHER subroutine conditions). .P The following figure illustrates the organization of fixed and variable length data in the array. The pointer word, array(p) contains values as shown. Word p+1 contains 0 or the column dimension for matrix attribute type. .s.tp28 .LITERAL Fixed Variable Fixed Variable Length Variable Length=1 Length Length=2 Attribute Length Attribute Attribute Attribute Parameters Attribute /------^--------\ +--+---------+---------+---------+---------+-+---------+---------+---------+-+ | | | | | |X| | | | | > | 3 | 4 | 5 | 6 |X| N | N+1 | N+2 | > < | | | | |X| | | | < | | | | | |X| | | | | +--+---------+---------+---------+---------+-+---------+---------+---------+-+ VALUE POINTER \-------v--------/ /---^---\ VALUE VALUE * NO. Chars 0 +---+ (text) | N | * NO. Words 0 +-+-+ (Int, Real) | * NO. Items 0 | (DOUB, DVEC) | * NO. Items 0 | (Ivec, RVEC) | * Row Dimens. Col. Dimens. | (Matrix) (Matrix) | \--v--/ | ^ | | +-------------------------------+ .END LITERAL .s.c;Figure 3-1 -- Organisation of RMGET/RMPUT Array Argument .send toc 2,1,Organisation of RMGET/RMPUT Array Argument .tp11 .hl2 RMPUT .nf.lm+4;^&CALL_ RMPUT_ (number,array)\& Input parameters: .s.lm+2 number -- number (0-5) identifies the relation pointer for this operation (int) array --- array containing a row of data, contents as RMGET .lm-6.f.p0 .x RMPUT subroutine The complement of RMGET -- puts data into the current row. .tp11 .hl2 RMLOAD .x Load relation .x RMLOAD subroutine .x Row .nf.lm+4 ^&CALL_ RMLOAD_ (number,array)\& Input parameters: .s number -- number (0-5) identifies the relation to load (int) array --- array containing the row of data to load (any type) (see RMGET for a description of array) .f.lm-4 .tp6 .hl2 RMDEL This sequence of calls will modify a row of data in a specified relation: .x RMGET subroutine .x RMDEL subroutine .x Row .x Delete relation .s.nf.lm+4.tp11 ^&CALL_ RMGET_ (number,array)\& . . . ^&CALL_ RMDEL_ (number)\& Input parameter: .s number -- number (0-5) identifies the relation from which rows are to be deleted (int) .f.lm-4.p0 Calls to RMPUT and RMDEL must be preceded by calls to RMGET since neither .x RMGET subroutine .x RMPUT subroutine RMPUT or RMDEL advances the pointer they operate on to the next row. .x RMDEL subroutine .hl1 LINKING YOUR PROGRAM TO RIM .COMMENT 3.7 .x RIMLIB.OLB .x LINK To use the RIM application program interface you need to link RIMLIB.OLB to .x Application program your program. .p0 .IF SIRA This can be done with either of the following commands: .b1.tp2 .i+4;$ LINK your__program, SYS$LIBRARY:RIM__SHARE/OPTIONS .br;or##$ LINK your__program, SYS$LIBRARY:RIMLIB/LIBRARY .p0 The first command is preferable, as it includes (in the RIM__SHARE.OPT LINK options file) instructions to cause your program to share much of the RIM source code with any other similarly-linked programs running at the same time. This reduces the size of the executable image (.EXE) file, and, more importantly, the combined system overhead of the two or more running programs. However, it presupposes that the VMS System Manager has installed the RIM shared library, and this may not be true of all VMS systems. So if you want to send the .EXE image file elsewhere, you should use the second command. A further advantage of the first, shared library, command is that if the RIM library is corrected or enhanced, you get the updates automatically, without necessarily having to relink your program. .ELSE SIRA This can be done with the following command: .x LIB__USER: .i+4;$ LINK your__program, LIB__USER:RIMLIB/LIBRARY .s where LIB__USER_: is the system logical name which points to the disk and directory where RIMLIB.OLB is stored. .ENDIF SIRA .hl1 SAMPLE PROGRAM The following is a small sample program in VAX FORTRAN to show how RIM may access a database called AERODB. It prints the following: .list 1 .le;All information about the schema (LISTREL ALL). .le;The data in the relation REL300 sorted for the airports in Brazil sorted by descending altitude. CITYNAME is variable length and the commands are: .s.i4;SELECT ALL FROM REL300 SORTED BY ALTITUDE=D WHERE + .i11;CITYNAME EQS "BRAZIL". .els2 .send toc 1,FORTRAN Example Program .lm+5.NF.TP6 LOGICAL RPW,MPW,VAR,KEY COMMON/RIMCOM/RMSTAT INTEGER RMSTAT REAL*8 NAME,LASTMD,NAMEA,NAMEC,IVAR,DBNAME DIMENSION NVAL(20) DIMENSION NAMEQS(5) .TP3 C Open the database DBNAME=6HAERODB CALL RMOPEN(DBNAME) .TP8 C LISTREL ALL CALL RMLREL 100 CONTINUE CALL RMGREL(NAME,RPW,MPW,LASTMD,NUMATT,NUMROW) IF(RMSTAT.NE.0)GOTO 200 LRP=3HNO IF(RPW) LRP=3HYES MRP=3HNO IF(MPW)MRP=3HYES WRITE(6,110)NAME,LRP,MRP,LASTMD,NUMATT,NUMROW 110 FORMAT(1X,A8,2(1X,A4),1X,A8,2I8) CALL RMLATT(NAME) 120 CONTINUE CALL RMGATT(NAMEA,ITYPE,MAT,VAR,LEN1,LEN2,NCOL,KEY) IF(RMSTAT.NE.0)GOTO 100 IVAR=5HFIXED IF(VAR)IVAR=8HVARIABLE IKEY=2HNO IF(KEY)IKEY=3HYES WRITE(6,130)NAMEA,ITYPE,MAT,IVAR,LEN1,LEN2,NCOL,IKEY 130 FORMAT(1X,A8,2(1X,A5),1X,A8,3I8,1X,A3) GOTO 120 200 CONTINUE .TP8 C SELECT ALL FROM REL300 SORTED BY ALTITUDE=D+ C WHERE CITYNAME EQS "BRAZIL" NAME=6HREL300 CALL RMFIND(1,NAME) IF(RMSTAT.NE.0)GOTO 999 NAMEQS(1)=6 NAMEQS(2)=0 NAMEQS(3)=4HBRAZ NAMEQS(4)=2HIL NAMEC=8HCITYNAME IBOOOP=3HEQS CALL RMWHER(1,NAMEC,IBOOOP,NAMEQS,1,0,1) IF(RMSTAT.NE.0)GOTO 500 NAMEA=8HALTITUDE CALL RMSORT(1,NAMEA,1,-1) IF(RMSTAT.NE.0)GOTO 999 300 CONTINUE CALL RMGET(1,NVAL) IF(RMSTAT.NE.0)GOTO 500 NUMX=(NVAL(5)-1)/10+1 NUMP=6+NUMX .TP2 WRITE(6,400)(NVAL(K),K=1,NUMP) 400 FORMAT(A4,5I6,2X,30A1) GOTO 300 .TP5 500 CONTINUE IF(RMSTAT.LT.0)GOTO 1000 999 CONTINUE WRITE(6,9001)RMSTAT 9001 FORMAT(' RMSTAT:',I5) .TP5 C Close the database 1000 CONTINUE CALL RMCLOS STOP END .F.TP7.lm-5.p0 This program (in file EXAMPLE.FOR) may be compiled and linked under VMS by:- .s.i4;$ FORTRAN EXAMPLE .IF SIRA .i+4;$ LINK EXAMPLE,SYS$LIBRARY:RIM__SHARE/OPTIONS .ELSE SIRA .x LIB__USER: .i+4;$ LINK EXAMPLE,LIB__USER:RIMLIB/LIBRARY .ENDIF SIRA .x LINK .! .send toc .tp10 .ax INPUT FORMAT .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st Input Format .x LXLREC .x Free-field format RIM processes command lines through its "LXLREC" subroutine, which is a free-field input routine which separates user input into items which are grouped into records. .hl1 TERMINOLOGY .send toc 3,Data Input Terminology .x Terminology .br.lm+11.i-11 line####--#one line of information with a maximum of 80 characters. A line corresponds to a card (for those old enough to remember card input). .x Blanks .x Text .s.i-11 item####--#one piece of information. An item may be a real .x Real number, an integer or text. Items are delimited .x Integer by blanks or commas. Multiple blanks count as a single blank. Multiple commas generate null items (see Sections 2.1.3.2 and A.2.2). .x Commas .s.i-11 record##--#a collection or list of up to 100 items which is in response to a single request for data by the calling program. .s.i-11 .x Integer integer#--#all characters must be numeric except the first one which may be + or -. For example:##-1##23##+10000 .x Real .s.i-11 real####--#an item of the form i1.i2ei3 where i1 and i3 may be signed integers and i2 is an unsigned integer. The entire form is not necessary but at least one digit and either the _. or the E must be present. For example:##1.##E-3##-2.7E+4##.0 .x Blanks .x Commas .s.i-11 text####--#any single item which is not an integer or real. If .x Text a text item looks like an integer or real or if it contains blanks or commas, it must be enclosed in quotation marks ("). .x Quotation marks .lm-11 .hl1 COMPOSING RECORDS .br .x Comments .x Dollar sign .x Plus .x Semicolon Ordinarily, records consist of one line. However, multiple records may be put on one line by separating them with dollar signs or semicolons. Alternatively, a record may span several lines by ending all but the last line with a plus. In general, items must be wholly contained on one line with the exception of quoted text items and comments. .hl2 Special Items: =, (, ) .x Equal sign (=) .x Parentheses Equals and left and right parentheses are treated as single items unless enclosed in quoted text items. Thus a=3_. is 3 items (two text and one real) rather than one item. "a=3." is one text item. This allows more convenient parsing of many commands. .hl2 Multiple Commas .COMMENT A.2.2 .x -0- .x Missing value (-0-) .x Commas If more than one comma separates two items, each additional comma will generate a text item with three characters "-0-". Thus, ",#,#abc,#,#2.5" is equivalent to "-0-,#abc,#-0-,#2.5". .hl2 Rules for Text Items .x Quotation marks .x Quote, trailing .x Quote, double .x Semicolon .x Dollar sign .x Limit, text item .x Plus .x Continuation .br A quoted text item is terminated by a record separator (dollar sign or semicolon). Quoted text items may be continued on multiple lines. If the trailing quote is omitted on the last item in a record, the quoted item is terminated at either the record separator, if any, or the last nonblank character on the line. A quotation mark may be included in a quoted text item by doubling .x Quotation marks it (e.g_. "a, ""b" yields a, "b as a text string). The total number of characters for all text items in a record is limited to 2000. .hl2 Some Examples .send toc 1,Data Input Formats .i+4;1, 2. ABC "2." .s This record has four items -- integer, real and two text. .s.i+4;1 $ 2 .b1 This line is two records -- each one integer. .s.i+4;1 + .i+4;2 .s This is one record on two lines with two integers. .hl2 Comments .x Blank lines .x LXLREC .x Parentheses .br Comments may be included anywhere in the input stream by .x Comments enclosing them between *( and ). For example, *(#this is a comment). Comments are completely ignored by LXLREC (except for the special case of those beginning with SET, described in Sections A.4 and A.5). Empty lines between records are also ignored and may be used to paragraph input. An alternative form of comment is */.../ where slashes replace the parentheses. This may be used if parentheses are needed in the comment. .hl1 SHORT CUTS IN DATA GENERATION Activities such as entering large volumes of data, repeating similar records and reentering mistyped records can be eased by using the LXLREC data generation facilities. .x LXLREC .hl2 Repeating Items in the Previous Record -- *n, **, * .x Asterisk .x Asterisk, double A data item of the form *n, where n is an unsigned integer, indicates that the next n items in that record are identical to the corresponding n items in the preceding record. An isolated * is treated as *1. Double asterisks (**) indicate that the remaining items in the previous record are to be copied into the current record. .x Equal sign (=) .hl2 Repeating an Item in the Current Record -- *=n *=n+step An item of the form *=n, where n is an unsigned integer, indicates that the next n items are identical to the immediately preceding item. An item of the form *=n+step or *=n-step where step is an unsigned real or integer, indicates that the next n items are to be generated by consecutively incrementing the immediately preceding item. .hl2 Generating Multiple Records -- *+n A record beginning with *+n, where n is an unsigned integer, indicates that the next n records are to be generated from the preceding record. Each item of the generated record is formed by adding an item of the *+n record to the corresponding item of the immediately preceding input or generated record. A zero (integer) item should be inserted in an *+n record for text items in the preceding record. The number of items after the *+n must match the number in the preceding record. .hl2 Note on Generating Items .x Asterisk .x Equal sign (=) .br When increments are specified, either on the *+n record or as step on an *=n+step item, they must match the item they are incrementing in type. It should be noted that the *+n record generation option is based on the expanded representation of the previous record. The generation does not operate on the card image of the preceding record if it contains data generation items. Therefore it is not possible to repeat or increment an asterisk-type item. .hl2 Examples Consider the following seven input records to illustrate the data generation features: .send toc 1,Data Generation Features .s.lm+4.nf.tp7 1 2 3 4 5 6 7 8 9 10 11 12 2 1 *2 4 *=2 1 *=2+2 ** *+1 0 *=3 0 *=5 ** *+1 0 *=11 *+1 *12 *+1 ** ** .f.lm-4.p0 Twelve data items are defined by each of these records. Each of the last six records is translated into the same internal record which is: .s.i+4;2 1 3 4 4 4 4 1 3 5 11 12 .p0 Note: The last five records could be replaced by the single record: .s.i+4;*+5 ** .hl1 CHANGING SPECIAL CHARACTERS .COMMENT A.4 It is possible to change the special characters LXLREC uses to break apart .x LXLREC records. A special character may either be changed to another character, or set to null so that it is ignored. This is useful for reading specially formatted files or to allow special characters to be input as text items. To change a special character, enter the following special comment as the only entry on a line between records: .x Equal sign (=) .s.i+4;*(SET keyword=newvalue) .x Blanks .x Dollar sign .x Semicolon .x Quotation marks .x PLUS keyword .x DOLLAR keyword .x SEMI keyword .x BLANK keyword .x COMMA keyword .x Commas .x Quotation marks .s.nf.tp6 where keyword can be: DOLLAR SEMI QUOTES BLANK PLUS COMMA .f.s .x Dollar sign and newvalue is either the word null or the new special character. For example, if one wanted to use dollar signs to delimit items rather than records and to not have commas delimit items, the following two lines could be entered: .send toc 1,Changing Special Characters .x Commas .x Equal sign (=) .s.i+4;*(SET DOLLAR=NULL) .i+4;*(SET COMMA=$) .s .x Dollar sign .x Plus Note that commas could now be used in unquoted text strings and dollar signs .x Commas could now be included in quoted text strings. Also, note that it is really the function that is being altered, not the character. Changing plus only changes the line continuation character, not the representation of real numbers. To .x Real .x Continuation restore the original condition after the above example, the following could be entered: .s.i+4;*(SET DOLLAR=$) .x Equal sign (=) .i+4;*(SET COMMA=, ) .p0 Warning: Using the same character for multiple functions will produce undefined results. (Undefined means that even the author wouldn't want to guess what will happen.) .hl1 CONTROLLING ECHO .COMMENT A.5 .x Echo LXLREC will echo the input line as the default. Either the user or the .x LXLREC calling program can switch echo on or off. The user accomplishes this by entering: .s.i+4;*(SET ECHO=ON) or .x Equal sign (=) .i+4;*(SET ECHO=OFF) .s in the same manner as setting special characters. .; .ax LIMITATIONS .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .ST Limitations .list 1 .le;There is no limit on the number of rows of a relation except disk size. .; .le;A row in a relation must fit in 1021 words. If len(i) is the fixed length (in words) of the ith attribute and var(j) is the length (in words) of the jth variable length attribute, then the requirement is: .s.lm+5.literal i=max j=max ----- ----- \ len(i) + \ var(j)+3 < 1021 / / ----- ----- i=1 j=1 .el.lm-5.p This can mean that relations that fit on 60 bit machines may not fit on 32 bit machines. .; .le;A relation or attribute name must not begin with the character string "RMRUL". .x relname .x attname .x RMRUL .; .le;The following words may not be used in attribute or relation names: TO, FROM, BY, USING, WHERE, IN, FORMING, ROWS, LIMIT, DUPLICATE. .x TO keyword .x FROM keyword .x BY keyword .x USING keyword .x WHERE keyword .x IN keyword .x FORMING keyword .x ROWS keyword .x LIMIT keyword .x DUPLICATE keyword Also, names must not be a substring of the above which is three characters or more long starting with the first character. Thus FOR and FORM are illegal, but FORT is not. .; .le;In loading data, the value of the first attribute, if it is text, is limited as follows: .s.list0 .le;If the relation contains only one or two attributes, then the following text strings and their RIM substrings are not allowed as values for the first attribute: CHECK, NOCHECK, ECHO, NOECHO, END, HELP, INPUT, OUTPUT, QUIT. .x attname .x CHECK command .x NOCHECK command .x ECHO command .x NOECHO command .x END command .x HELP command .x INPUT command .x OUTPUT command .x QUIT command .le;If the relation contains three attributes then the value for the first attribute may not be HELP or HEL. .x attname .x HELP command .els .; .le;The number of items in one command may not exceed 100. .; .le;The number of rules specified for one relation may not exceed 10. .x Rules .; .le;The number of conditions used in the SELECT WHERE clause may not .x SELECT command .x WHERE keyword .x Conditions exceed 10. .le;The number of sorts specified by the SELECT SORTED#BY clause may not exceed 5. .; NOTE: One of our users claims the maximum he can make work is TWO -- CJD. .x SELECT command .x SORTED BY keyword .le;There are restrictions as to the typw and length of attributes used with the COMPUTE command. Details are given in Section 2.1.6.1. .x COMPUTE command .els0 .! .ax COMMAND SYNTAX SUMMARY .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st Command Syntax Summary .x Summary .REQ 'RIMCRD.RNO' .ax APPLICATION INTERFACE SUMMARY .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st Application Interface Summary .x Summary .REQ 'APPCRD.RNO' .page .t RELATIONAL INFORMATIONAL MANAGEMENT SYSTEM -- RIM .st .layout 0 .REQUIRE 'RIM.RNX'