____ ___ ___ ___ ___ ___ ___ ____ ___ ___ ___  / /__//_ /__ / //_ //__ / //_ / / / //_ //__//_   / / //__ ___//__//__/___//__// / /_/_// // \/__  ------------------------------------------------------------------------------ - FOR ABO'S CONTACT US AT: BP:28 1170 WATERMAEL-BOITSFORT 1 BELGIUM!!... ------------------------------------------------------------------------------ - DON'T SEND ANY DISKS - ------------------------------------------------------------------------------  THE LEGENDARY >> SUBSOFTWARE << IN 87/88/89/90/91!!...  ------------------------------------------------------ SUPERBASE WELCOME TO SUPERBASE This Introductory session with Superbase will give you an understanding of how to perform some of the basic database operations of the Superbase system. Some more complex functions are explained in the section Working with Superbase. OPENING A FILE If you look at the top left-hand corner of the screen you will see a message that reads "Superbase: Please open a file". You always see this message when you start Superbase up, or when there is no file open. Since you can't do any work without a file, let's open one and take a look at it. Files can only be opened from the Project menu. This is the first menu on the menu bar. SUPERBASE REQUESTERS Superbase now requestes the name of the file you wish to open. Requesters like this one (some are more complicated) are used in most Superbase operations. They also communicate messages to the user. They are known as requesters because their function is to request specific action from the user. Usually the action involves making selections by clicking the mouse or typing in a number of a text value of some kind. Many requesters show a panel that contains a list of items such as file name or field names. The panel may be only a few lines long, so there may be more files or fields than can be shown at one time. If there's a gap at the bottom of the scroll bar there are more items to be viewed. You can show them by dragging down the scroll bar at the right of the panel, or by clicking on the downwards pointing arrow gadget below the scroll bar. Many Superbase requesters include a Clear button. This has the effect of removing anything that's in the Selection Box, and can be used at any time. CHOOSING THE ADDRESSES FILE Move the pointer into the panel which contains a list of file names. Move it over the file name Addresses. This is the demonstration file you'll be using for the rest of this session. Using the left-hand button, click once on the name Addresses. Superbase copies the name of the file you've selected into the Selection Box -- that's the box underneathe the panel of tile names. (If you see the wrong file name in the box, move the pointer carefully onto the right file name, and click again.) Once you've selected the file, move the pointer onto the OK button and click once. Superbase now opens the Addresses file. THE MAIN DISPLAY When Superbase opens a file from the start up screen, it automatically reads the first record in the file and shows it on the Main Display screen. You'll see the name of the file appear on the title bar at the top of the window, followed by the name of the field on which the file is currently indexed. The Main Display is Superbase's permanent window onto your database. It's like a large worksheet, 273 colulmns across; the number of lines you can see depends on the size of your window. Surperbase uses the Main Display to show you the records in the current file, as well as the results of some other operations. At the bottom of the Main Display is the Control Panel, which we'll be looking at in a minute. On the Main Display, the field names for each record in the Addresses file appear down the left-hand side of the screen. The data for each filed is displayed to the right of its field name. If the data for a filed is wider than the window, it extends off to the right. You can bring it into view using the scroll bar at the bottom of the window. Remember that if there were more fields in the record than you could see, you could view them by dragging the scroll bar at the right of the window downwards, or by clicking on the downward pointing arrow. RECORD VIEW, FORM VIEW AND TABLE VIEW The record format you're looking at now is only one of the three possible ways of looking at your file. It's called Record View. This view shows the records one at a time, restricting the format by keeping the field names on the left and limiting you to one field per line. This restriction allows records to be scrolled up and down the screen with the Control Panel buttons. In Form View, you also see one record at a time. Each record is like a form or page and, as you'll see later, you can drag the fields around to create a worksheet desinged to suit your application. The third display format is Table View. This displays the field names across the top of the screen with the data appearing in rows and columns, each record occupying one line. SWITCHING TO TABLE VIEW Select Table View from the Set Menu. You will see the field names appear across the top of the screen. The same record is shown, but each item of data appears underneath its field name. As with Form View, there are ways of changing this row and colulmn display to suit your own preferences which we'll explain later. SCROLLING THE SCREEN While you are viewing your record in Table View you will notice that the field names do not all fit onto the screen. The fileds to the right can be viewed using the arrow at the right of the bottom scroll bar. Move the pointer onto this arrow, and click on it once. The display shifts five columns to the left. Click once on the left-hand arrow to shift right and restore the display. If you want to shift the display by larger areas, drag the bottom scroll bar with the mouse. CONTROL PANEL Now that you've opened a file, and discovered how to change the way in which records are displayed on the screen, let's look at the Control Panel. This is your means of controlling the main display. As you can see there are 12 buttons, most of them modelled on the controls for a video cassette or tape recorder, so you should find these conventions easy to learn and remember. Each button has a special purpose, and together they fall into three groups. On the left are the Pause and Stop buttons. Followed by seven buttons for browsing through the file. On the right are three special purpose buttons which we'll examine later. The functions of some controls are more intuitively obvious than others, so we'll take a look at the first nine now, one by one. Make sure you've set Table View for this exercise. ^ Current Record: This button is used to display the current record. When Table View has put a lot of records on the screen it can be helpful to select the current record as the top record in the display. Also, you can only Edit the current reacord, and this button is a useful way of ensuring that you've got the right record. If you click on this button you will notice that Superbase clears the screen and then displays the current record. > Next Record: Allows you to view the next record in the file. The order in which the records appear is dicided by the current index, which is shown by the message on the title bar of the main display window. Try this now, and you'll see the data for the next record come onto the screen. In Table View it appears underneath the previous record. In Form View it replaces the previous record. < Previous Record: This gets the previous record in the file, relative to the current record. >> Fast Forward: Instead of moving forwards through the file one record at a time by pressing the Next button, you can move much quicker using the Fast Forward button. Click on this button, and Superbase gets the next records in the file, displaying them row by row until the screen is full, when it selects the Pause button. || Pause: When the Pause button is selected, you cannot select any menu item until you either release it or click on the Stop button next to it. You can, however, use the other Control Panel buttons. So, to view the next screen of records, release the pause by clicking on the Pause button. Superbase continues with the Fast Forward display of records, stopping when the next screen is full, or when it reaches the end of the file. Pause is useful when you're searching for a record and you want to stop from time to time to read the screen. << Rewind: This does the opposite of the Fast Forward button. You will see the data appear from the top of the screen,in reverse index order. If you do this immediately after Fast Forward there will be an apparent delay while Superbase displays records over the text of the existing display. |< First: Pressing this button automatically displays the first record in the file, according to current index order. >| Last: Pressing this button automatically displays the last record in the file, according to current index order. | Stop: If you want to stop the Fast Forward or Rewind display, click on Stop. You must also click on Stop if you want to interrupt Pause when it's selected. OPENING FIELD TO VIEW As Superbase imposes no limit on the number of fields per record, you need to have a way of restricting the fields that actually appear on the Main Display. You can do this with the Open Field option on the Project Menu. Display the Project Menu, and select Open Fields. The basic procedure for selecting fields is very simple: 1. Click on a field name in the left-hand panel. Superbase copies it into the right-hand panel. 2. Repeat until the selection of fields you want is in the right-hand panel. 3. Click on OK. The list of fields in the right-hand panel is called the Open Fields List. Let's make one now. Move the pointer onto the list of fields names, and click on City. Nitice how Superbase copies it across. Now click on Lastname. When you have both names in the list, click on OK. (If you make a mistake, DEL romoves the current field from the right-hand panel; Clear removes the whole list.) Superbase immediately returns to the Main Display showing the data for the two open fields. Try out the Control Panel buttons to see their effect. Experiment with Record View as well as Table View. When you've finished, restore the full set of fields by selecting Close Fields from the Project menu. PAGING This is another feature which gives you control over the Main Display: the Paging option. If Record View is not set, select it now from the Set Menu. Then go back to the Set menu, and move the pointer down to the Paging item, which should have a check mark against it. Release the mouse button while Paging is highlighted. You've now turned the paging option off. (You can check this by looking at the Set menu again; there should be no check mark against the Paging item.) Now, select the first record in the file by clicking on the First Record button. Then click on Fast Forward, and watch the display. You'll see that Superbase down't pause when the screen is full -- It just goes on displaying records. You can still use pause to halt the display, but the automatic pausing at the end of each "page" of data no longer occurs. The same applies when Rewind is in use, except that the records appear at the top of the screen. If you now switch back to Table View and try out some of the Control Panel buttons, you'll see that with Paging off the difference is similar to that in Record View. Each record appears below the last, without clearing the screen. Rewind displays records from the top down, as in Record View. MOVING COLUMNS For this exercise you need to be able to see all the fields on the screen, not just those in the Open Fields list, so if you have an open Fields list in use, close it now by selecting Close Fields from the Project Menu. You can see that if you have all the fields open in Table View, some of the field data is very likely to be hidden from view. Normally, to see hidden fields you have to scroll the screen to the right. However, Superbase provides a way of closing up columns to get more data on the screen. Assuming you're in Table View -- set it if you're not -- click on the First button, then the First Record button on the Control Panel in order to get the first record of the Addresses file on your screen. MOVING A COLUMN TO THE LEFT Now move the pointer so that it is on the space to the right of "M" in the Title Field. Once you have done that press and hold down the left-hand button of the mouse. As you do this you will see two vertical lines appear, forming a column beneath the Title field. There are also lines extending off to the right of the screen. Keeping the left button depressed, drag the pointer a little to the left, then release the mouse. You will see that the column moves, and when you release the mouse the data beneath the field name has shifted to the left. All columns to the right have also moved leftwards. Now try the same with the Forename field. This time ove the column so that it is just to the right of the "e" in Title. If you also try this with Lastname and Street you will see that as you move the columns over to the left the field name City appears on the right of the screen. If you now move the City column to the left, the Code field will appear on the screen. Finally, if you move the Code field, Country will appear on the right- hand side. So by moving the columns you've got all the fields on one screen instead of two. Notice that you can move a column so that it overlaps the column to its left, truncating the data. This can be useful. MOVING A COLUMN TO THE RIGHT If you move a column back to the right, the truncated field name and data are not automatically restored to their full length. A quick way of restoring the length of a fiels is to double click in its column. Then if you click on the Current Record button the full field name and data will reappear. But as this only displays one record you will have to use Fast Forward if you want to redisplay a screen of Record data. FORM VIEW DESIGN Superbase allows you to rearrange the positions of the fields in Form View, setting more than one field on a line, creating columns of field to resemble invoices or other business forms, and generally talloring the system to suit your own application. The full 273 column woeksheet is available for Form View, and you can vary the depth by dragging fields downwards, creating new lines. You can use Form View for creating new records and editing them, as well as for display. By setting the Printer option on, you can copy the visible portion of the worksheet to the printer. Select Form View now from the Set Menu. Make sure you've got the Addresses file open, and that the current record is the first record in the file. DEFAULT FORM VIEW If you look at the screen you can see that the fields names already appear in a Form View. This is the default Form, which we have predefined for this demonstration file. You can change it, and then save it with Project Save File. Once a Form has been saved, the fields will appear in that layout every time you open the file. MOVING FIELDS Let's move the Lastname field to another position on the screen. Move the pointer so that it's on the field name Lastname. Then press and hold down the left-hand button of the mouse. Superbase outlines the field name and its data area. (If you see a cursor instead, you've started editing by mistake. Carefully click again on the field name itself.) Now drag the outlined box to a new position two lines above its present position. Release the mouse button. As you can see, the field name and data have moved to this new position. Now, if you want to, you can arrange the Form View for Addresses in any way you like. This can be just an experiment, but if you want to save the present arrangement, you can do so. Select Save File from the Project Menu. Superbase stores the File Definition, which contains the Form View location of each field, on disk. Although you have freedom to drag fields to any position on the screen, there are as usual a few limits to what you can do. You cannot place a field on top of either the name or the data area of another field. If you try this, Superbase leaves the field you tried to drag in its original position. Superbase won't let you move a field off the right or left-hand end of the worksheet. To gain more lines, move a field down into the Control Panel. Then use the vertical scroll bar on the Main Display window to bring it back into view. Move it down again if you still need more lines. To move a field over to the right of the worksheet, position it near the right-hand edge of the screen, then shift the display with the scroll bar, and drag the field further over. Only the open fields are shown, so close the Open Fields List if you want to see all the fields in Form View. Finally, a small but entertaining feature. Select Fast Forward, and drag the fields around as described above. No problem. SUMMARY Time for a check list of what you should know before we proceed. * How to open a file * How to switch betgween Form View, Table View, and Record View * How to switch Paging off and on * How to drag columns around in Table View * How to Open and Close a list of fields * How to select the Current record * How to move to the First record * How to move to the Last record * How to move to the Next record * How to go to the Previous record * How to use the Fast Forward to move forwards through the records * How to Rewind to move backwards through the file * How to Pause * How to Stop Understanding all these actions is essential if you wnat to be able to work easily with Superbase. If you do not understand them or are uncertain then take a little time to go back and re-read the appropriate sections before continuing. THE KEY LOOKUP BUTTON ? Key Lookup: This is for the retrieval of individual records. You enter a value for the field on which the file is currently indexed, and Superbase uses the index to find and display the record. You can only use one index field at a time -- the Filter button is used for multiple value searching. When you click on the Key Lookup button you'll see a requester for the entry of a key value. TYPING IN YOUR KEY To be able to type in the box, you must move the pointer into it and click the mouse once. This produces the cursor, and you can then type in your Index Key. Suppose you want to find the record for Julie Kasper. The file is indexed on the Number field, so we can use the current index to search for individuals by their Reference Numbers. Click in the box and then type in "KAS0001" (omit the quotation marks). This is the Index Key. RETRIEVING THE RECORD When you press Return or click on OK, Superbase looks up the first record for which the Number field has the value "KAS0001". If there were more than one with this value, you would have to browse through the file with the Next Record or Fast Forward button to find the exact record you wanted. KEY LOOKUP WITH A DIFFERENT INDEX You're not restricted to one index. Superbase allows you to have up to 999 indexes for each file, all automatically updated when you add or modify records. We've provided indexes on the other fileds besides the number field: Lastname, City and Country. Let's try one of these. Select Open index from the Project Menu. Click on the field name Lastname; this is copied into the Selection Box. When you're ready, click on OK. You've selected the Lastname index, and if you look at the title bar at the top of the window you'll see that the message now reads "Superbase: Addresses Indexed on Lastname". The record on the main display has not changed. Click on the Key Lookup button, and Superbase produces the Record Key requester. As you did above, click in the box and type in a key value, only this time type in "Forge". Press Return or click on OK, and Superbase looks up the first record with Forge in the Lastname field. ENTERING PARTIAL VALUES You don't even need to type the full index key in many cases. Try Key Lookup once more, but type in "Hut" and press Return. Superbase finds the first record for Huttermann. For your information, Superbase tells you that it didn't find the exact match. THE FILTER BUTTON = Filter: This is a very powerful feature. You may have thousands of records in a database file, yet you may often want to review them (or print them out) on a selective basis. The Filter allows you to enter a set of values, as simple or a comprehensive as you like, to restrict the display to only the records that match those values. THE FILTER REQUESTER Move the pointer and click on the Filter button on the Control Panel. This requester looks more complex than the ones you have seen so far, but after a little practice with the demonstration file you'll find that you can remember how to use it easily. It's important that you learn how to use the Filter, because Superbase uses filters in several other functions. The requester has four main parts: the Field Name Panel, the Operators, the Value Box, and the Main Box. A Filter is created by a combination of clicking on field names and operators and typing in values. These actions produce the Filter Command Line in the Main Box. Let's look at each component of the Filter Requester in turn. FIELD NAME PANEL This appears on the left-hand side of the requester. You can scroll the list of field names up and down in the usual way, using the scroll bar and arrows at the right of the Field Name Panel. You specify that a field is to be used in the Filter by clicking on its name in this panel. The list of field names is complete. It's not affected by whether you have an Open Fields List, so the fields that specify the Filter neen not be the same as the ones that are shown in the Main Display. OPERATORS These appear to the right of the Field Name Panel, and can be divided into the Relational Operators, Logical Operators and Mathematical Operators. We'll see how these are used below. VALUE BOX This is the box with the word "Value" next to it. You use it for typing in values such as names, numbers, and dates, which will form part of the Filter. Always remember to press Return after typing in the Value Box. You must do this to ensure that the contents are copied to the Main Box. MAIN BOX This is the long box that appears below the Field Name Panel and extends across the whole requester. When you make selections with the mouse or type values into the Value Box, Superbase copies them into the Main Box, building up the Filter Command Line. In this way you get immediate feedback about the results of your selections. The maximum length of the Filter Command Line is much greater than the apparent length of the box -- up to 255 characters are allowed. You can type directly into the Main Box, but in these exercises we'll stick to making selections with the mouse. USING THE OPERATORS The Operators are the most complex aspect of the requester. They are used to relate field names to other fields or values. For example, if we wanted to set up a Filter to show only the addresses in West Germany, we would need the expression: Country LIKE "West Germany". Here, Country is a field name obtained by clicking in the Field Name Panel; LIKE is selected by clicking on the LIKE Operator button; and "West Germany" is typed into the Value Box. TEXT STRING AND PATTERN MATCHING: LIKE When you're searching for names or text strings, uyou should avoid using the equals sign operator, and use LIKE instead. This is because only LIKE accepts matches on either upper or lower case characters; it's said to be "case insensitive". The equals sign operator, on the other hand, requires exact matches for what you type in: It is "case sensitive". LIKE also permits searches for text strings that include pattern matching characters. these allow you to enter incomplete words for the Filter. For example, to find all the records where the Lastname begins with "C" you need the Filter Command Line: Lastname LIKE "C". To specify a range add square brackets to the value: Lastname LIKE"[A-D]*"; this finds all the records where the Lastname begins with "A", "B", "C", or "D". Note that the Asterisk is placed outside the brackets. There are several other things you can do with the LIKE operator. You'll find a complete list and a number of examples in Appendix B. THE RELATIONAL OPERATORS = This specifies that the field is to be EXACTLY EQUAL TO the following value or field: Balance = 2000. <> The field is to be NOT EQUAL TO the following value or field: Country <> "France". > The field is to be GREATER THAN the following value or field: Balance > 1000. < The field is to be LESS THAN the following value or field: Balance < 1000. >= The field is to be GREATER THAN OR EQUAL TO the following value or field: Balance >= 1000. <= The field is to be LESS THAN OR EQUAL TO the following value or field: Balance <= 1000. THE LOGICAL OPERATORS AND, OR AND NOT Thes provide links between different expressions like the ones given above. You use them to specify alternatives and ranges for the Filter, either for a single field or for a number of interrelated fields: AND Both of the conditions linked by AND must be satisfied for the record to be accepted by the Filter: Country "West Germany" AND Balance >= 5000. OR Either of the conditions linked by OR is sufficient to make the record aceptable to the Filter: Country LIKE "West Germany" OR City LIKE "Geneva". NOT NOT is slightly different. It negates the effect of an expression: NOT (Country LIKE "West Germany" AND Balance > 5000). This will find all the records other than the ones where the country is West Germany and the balance is greater than 5000. Note the use made of Parentheses with NOT. PARENTHESES The ( and ) operators are used in the normal way, to give priority to one part of the expression over another. ( The following expression has a higher priority for evaluation than the preceding expression. ) Required to end a higher priority expression. The numbers of opening and closing parentheses must be equal. THE MATHEMATICAL OPERATORS + This is used to express addition: Balance > Amount + 1000. - The minus sign expresses subraction: Balance > Amount - 1000. * The asterisk is used for multiplication: Balance > Amount * 1.15. / The slash represents division: Balance < Limit / 10. TYPING IN THE MAIN BOX The great power and flexibility of the Filter system is only achieved by giving the user control of every aspect of the operation. Because you type into the Main Box you include all kinds of expressions which are not available from the buttons on the requester itself, and all kinds of text and numeric values. The price you pay for this flexibility is an increased risk of making mistakes. This is not too serious, as you cannot harm your data by using a Filter (although you can discard records using the Remove Records Filter). However, you may see a Superbase "Can't do this" message concerning an error in the Filter Command Line in two possible situations: When you click an OK after creating or editing a Filter Command Line. When you use a Filter after changing the definition of a field with Project Edit. If you see a "Can't do this" message you must either change the Filter Command Line or change the file definition. Here's a summary of the editing facilities available when typing inside the Main Box: FILTER COMMAND LINE EDITING You can remove everything from the Main Box by clicking on the Clear button. If you have clicked in the box, hold down the right-hand Amiga Key (next to the space bar) and press X to delete its contents. (Note: we refer to this key combination as Amiga-X). Provided you have not left the box -- the cursor is still visible -- Amiga-Q will restore the contents you deleted with the Amiga-X. This does not work after clicking on Clear. If Superbase won't let you make an Operator selection when you return to modify an existing Filter Command Line, click in the Main Box and press Return. Now you can go ahead. Shift key and cursor right arrow and shift key and cursor left arrow move the cursor to the end and beginning of the Filter Command Line respectively. The DEL key romoves the character to the left of the cursor. Backspace repeats its action if held down. USING A FILTER The Filter Command Line is made active by clicking on OK. Whenever a Filter is in use, Superbase highlights the Flter button on the Control Panel. You can perform all but one of the Control Panel record selection operations we've discussed, and Superbase will restrict the records displayed to the ones that match the Filter values. For example, if you have specified the Country LIKE "West Germany" and you click on the First Record button, Superbase will go and find the first record in the file, according to the current index, which has the value "West Germany" in the Country field. The Key Lookup button is an exception to the filter effect. You can still recall individual records by entering an index key value, whether or not they match the Filter. SUSPENDING A FILTER There wil be times when you want to remove the Filter effect so that you can review all the records in the file again. To do this, just click on the highlighted Filter button. It reverts to normal, and you'll find that when you use the Control Panel Superbase acts as if there were no Filter. MODIFYING OR RE-ACTIVIATING A FILTER If you've set up a Filter and then suspended it, you can bring it back into operation by clicking once more on the Filter button. Superbase displays the Filter requester, with the Filter Command Line in the Main Box just as you left it. If you want to, you can add to the Filter Command Line by clicking on more field names and oeprators (you may need to click in the Main Box and press Return first), or edit it after clicking in the Main Box, as described above. Whether you've made any changes or not, just click on OK to use the Filter again. FIFTEEN MINUTE TUTORIAL Make sure you've got the Addresses file open, indexed on Lastname. Set Table View with Paging off. Go into Project Open Fields and open these fields: Forename Lastname Street City Country In Table View, drag the Lastname column a few columns to the left, and then do the same for City, overlapping the Street column if necessary, until the Country column comes into view. Click on the Filter button. We are going to search for those name and address records where the person lives in the USA or West Germany. So we'll use the Country field, and LIKE operator, and the Value Box. You'll see the results of your selections appear as a Filter Command Line in the Main Box. Move the pointer into the Field Names Panel, and click once on the down arrow to bring Country into view. Then click on Country. The name appears in the Main Box. Next, move the pointer to the right and click on the LIKE button. This also appears in the Main Box. Now you must type in "USA". This goes in the Value Box. Move the pointer into the Value Box and click on the mouse to produce the cursor. Type in "USA" (no quotation marks). Press Return -- this is essential, or the contents of the Value Box will not be copied into the Main Box. Your Filter Command Line should read: Country LIKE "USA" Next, you need the OR operator. Click on it and Superbase copies it into the Main Box. Now you must click on the Country field name again. This is important. A Filter Command Line like this is not allowed: Country LIKE "USA" OR "West Germany" So, click on Country, as before, followed by LIKE. Then, as before, click in the Value Box, and type in "West Germany". Press Return. Your Filter Command Line should look like this: Country LIKE "USA" OR Country LIKE "West Germany" If there are any mistakes click on Clear and repeat the steps above until you get it right. You have built your Filter Command Line, so now you can put it into action. Click on the OK button. Superbase activates your Filter and displays the first record in the file that matches the Filter. Click on Fast Forward. Superbase shows all the records that match the Filter. Now de-activate the Filter. Click on the Filter button so that it's not highlighted. Now click on Rewind. You'll see all the records in the file appear as normal. Let's go back and add another condition. Click on the Filter button to recall the requester. Click on the OR operator, then on Country, then on LIKE, then in the Value Box, type in "France", and press Return. Your line should read: Country LIKE "USA" OR Country LIKE "West Germany" OR Country LIKE "France". Now click on OK and when Superbase shows the first record, click on Fast Forward. You will see that Superbase has added the addresses in France to the display. That concludes our short tutorial. OTHER FILTER BASED OPTIONS You should have acquired a feel for the way the Filter requester works, and you can experiment freely with the Addresses file to deepen your knowledge. When you're ready, you can start using the Process options, all of which are selected from the Process menu. SUPERBASE PROFESSIONAL DATABASE MANAGEMENT LANGUAGE USER GUIDE BEFORE YOU BEGIN... This Volume presents you with two user guids, one for Superbase's Database Management Language(DML)and one for the Forms Editor. Although they are both under the same cover, they can be treated as separate manuals. Each has its own Contents, Index, chapter numbers and page numbers. Note that the Forms Editor is a separate program from Superbase Professional. You will find instructions on how to install and load it on your computer in the Readme document which is supplied on the demonstration file disk. If you haven't done so already, you should read this document now. It also provides details of any features of Superbase Professional that are not covered in either Volume 1 or 2. CHAPTER 1 - INTRODUCTION TO DML Welcome to Superbase Professional's Database Management Language(DML). DML is based on the programming language Basic. It includes most of the standard Basic commands and functions, but supplements them with a large number of commands and functions that are specific to database management. The database commands duplicate the controls that Superbase Professional provides through its menus and dialogs. This means that almost all of Superbase's file and record handling facilities are available under program control. In fact, apart from Fast Forwards, Rewind and Duplicate, you can now carry out any Superbase operation using a single program command. Once you have familiarized yourself with Superbase's controls, the corresponding program, you may find the idea of learning a program language daunting. But as far as DML is concerned, a little goes long way, and you do not need to be fully conversant with the language in order to take advantage of it. In effect, you are already following a program sequence every time you perform a task which involves a series of menu operations. Writing a program that performs the task for you is simply a matter of entering commands in the same sequence. Generally, you will be able to find a single command to duplicate each of the menu operations. As you acquire more expertise, you can move on, building bigger and more complex programs by combining routines, until you have fully automated your database system. When you're ready, you can incorporate Superbase forms into your programs, taking advantage of their built-in facilities for generating and retrieving records in several files at once. At the highest level, you can specify your own pull-down menus, replacing the standard Superbase menus with the options that are relevant to the job in hand. And you can customize your application to an even more detailed level by creating your own pop-up selection panels to guide the user's choices. USING THIS GUIDE Before reading this guide, you will need to be familiar with Superbase's menu and keyboard controls. Many of DML's commands provide a program equivalent of a menu or keyboard option, and the descriptions given here presume that you already know how to use the corresponding option. However, once you have mastered Superbase itself, you do not need to read this book all the way through. As a reference guide, it can be consulted as and when it is needed. CHAPTER 2 - OVERVIEW OPERATING MODES DML has two modes of operation:direct mode and program mode. DIRECT MODE In this mode, DML executes instructions as soon as you have typed them in. First you need to select the Command option from the Program Menu. Then enter your instructions - a single command or a line of commands separated by colons - in the command line window;when you select 'OK' or press the Return key, DML will carry out the instructions straight away. The command line window is 64 characters long but you can enter up to 255 characters and move within the window using the cursor keys. PROGRAM MODE In program mode, DML does not execute commands as you enter them. Instead they are stored in memory and executed only when the program is run. The main difference between this mode and direct mode is that with the latter you can only enter and execute one line at time;program mode allows you to enter a series of instruction lines which are carried out in sequence. Program lines can be up to 255 characters long. OTHER DML APPLICATIONS DML's functions, along with its operators and variables, can also be used in other Superbase operations - such as field definition validations and calculations, filter conditions, update commands and query derived field definitions. KEYWORDS AND RESERVED WORDS Any word that DML recognises as a specific instruction, or part of an instruction, is known as a keyword. A keyword cannot be used as a variable name, a field name, or a label. In this context, keywords are also knows as reserved words - DML reserves them for its own use, and will interpret then as such even if they are in lower case. A reserved word can, however, from part of a name. For example, you can incorporate the reserved word TO in any of the following ways: TOP: (in a label) TOTAL% (a numeric variable) tot$ (in a string variable) TOTALS$ (in a field name) But you cannot use it like this: TO: TO% TO$ COMMANDS AND STATEMENTS Some programming manuals make a strict division between two kinds of executable instructions - commands and statements. Commands are those instructions which are generally executed in direct mode, while statements are instructions that can only appear in a program line. In DML there are only a few instructions that cannot be used in both operating modes and so the two terms are used almost interchangeably. Thus we refer to a line with more than one instuction on it as a multi-statement line; but it could equally well be called a multi-command line. VARIABLES There are three types of variables in DML:string variables, numeric variables, and arrays. In many circumstances, the fields in a Superbase file can also be treated in the same way as variables. VARIABLE NAMES Numeric variables must end with the '%' character, string variables end with an '$' character. Apart from this, the names for both types of variable follow the same rules: Variable names have a maximum length of 14 characters and a minimum length of 1 character(excluding '%' or '$'). The first character of the name must be a letter in the range 'a' to 'z' but the remaining characters can be either alphabetic or numeric. DML is not case sensitive; 'abc%' is the same as 'ABC%', and 'abc$' is the same as 'ABC$'. A variable name can contain a reserved word, but cannot consist of just a reserved word and the variable suffix, % or $. For example, names like 'lef$', 'cos%', 'report$' and 'FILE%' are forbidden. See Appendix A for the list of reserved words. Before using a variable, you must define it by assigning a value to it. This means that the first occurrence of a variable should be in an assignment statement, with the variable to the left of the equal sign. Suppose, for example, you instructed DML to display the value of a$, using the command ? a$ If you have not assign a value to a$ beforehand, DML will issue the error message: Can't do this Variable not defined To avoid this error message, you would have to define a$ at an earlier stage in the program, with line such as a$="Hello" or a$="" The double quotes are known as the 'empty string'. They allow you to define a string variable without actually assigning a specific value;they are also used to clear the contents of string variables. There are, however, a number of exceptions to the rule about defining variables. Some statements - READ, ASK, WAIT, and INPUT - define variables implicitly when they are used for the first time. Thus DML would accept the line: READ a$ even if you had not assigned a value to a$ previously. NUMERIC VARIABLES DML's numeric variables hold numbers at 13 figure accuracy, but if displayed or printed, they are shown in the current default numeric format. Note that there is only one type of numeric variable. In some versions of Basic, the % suffix indicates that the variable can only store whole numbers(integers):in DML, the same numeric variable can be used for both whole numbers and floating point numbers. STRING VARIABLES String variables are used to hold ASCII characters - usually alphanumeric text. The maximum length of data that can be held in a string variable is 255 characters. ARRAYS DML supports string and numeric arrays with up to three dimensions. The maximum number of elements in an array is limited only by the amount of memory available. The rules for array names are the same as those for numeric and string variables. Numeric arrays must end with '%' character, string arrays must end with '$' character. SYSTEM VARIABLES TODAY, NOW and ERRNO are variables which are supplied by DML. TODAY gives the system date, NOW gives the system time. DML treats these in the same way as date and time fields;that is, although they are numeric variables, they are displayed in the current date or time format. If the time of day is 9:41 and the system clock has been set to this time. NOW would display it as 9:41. But it stores this as 34919810 - the number of thousandths of a second from midnight to 9:41. ERRNO returns the number of the last error that occurred. You cannot assign a value to a system variable, but otherwise TODAY, NOW and ERRNO can used in the same way as any other numeric variable. FILE TYPES When you save a file using one of the SAVE options, DML automatically adds one of the following extension names to the file name: aaa.sbf is a database file aaa.sbd is a file definition for a database file aaa.sbk is a function key file aaa.sbp is a program file aaa.sbq is a Query file aaa.sbt is a text file saved from the text editor aaa.sub is an Update file aaa.### is an index(where ### is a number from 001 to 999) DML stores program files, Text Editor files, database files and index files in its own format(for example, it tokenizes keywords in program files and stores formatting information with documents saved in the Text Editor). The others are all text files and only contain ASCII characters. FIELDS With a few exceptions, you can use fields in the same way as variables. For instance, you can input data directly to fields;you can supply a field name as the argument for a function;and you can assign values to fields. Fieldnames must conform to the rules for field names as set out in Volume 1, i.e.: The maximum length is 15 characters. The minimum length is one character. They must begin with an alphabetic character, but can thereafter contain any alphanumeric characters. They can also contain the underscore and space characters. Superbase will accept a field name with several spaces embedded in it - i.e., 'a bc d' is a valid name - but this is not recommended. DML is not case sensitive;'abc' is the same as 'ABC'. The file a field belongs to must be open;otherwise the following requester appears: Can't do this.... 'field name' Can't find this field Where more than one file is open and there are two files with the same field name, the file name must be given as an extension to the field name and the two must be separated by a full stop. This enables DML to identify the field you are referring to. NOTE:FAILING TO SUPPLY FILE EXTENSION NAMES TO FIELDS MAY RESULT IN INCORRECT DATA, ALTHOUGH IT DOES NOT CAUSE AN ERROR. If the file name contains spaces, it must be included within quotation marks, e.g.: fielda.filea name.Customers Lastname."Customer File" DATE AND TIME Superbase stores dates as julian date numbers;that is, as the number of days from 31st December in the year zero. This means that date fields are numeric fields and hold their dates as numbers. When you display a date field, however, Superbase automatically converts it to a more recognizable format:it takes the format which has been set in the file definition(see Chapter 2, Volume 1). The date format only controls the way dates are displayed. You can enter a date from the keyboard in almost any format. For instance, the date might be shown on screen as 24/02/87, but you can type in a date like '28 February, 1962' and DML will accept it. Incidentally, DML does remember that eleven days were lost when the Gregorian Calendar reform was implemented(September 2nd, 1752 is followed by September 14th). As with dates, DML stores the time in time fields as a numeric value, but displays it in a different format. The time is stored as the number of thousandths of a second from midnight. When you display the time, it is given in hours and minutes in either 12 or 24 hour format. FUNCTIONS Functions form one of the largest groups of DML keywords. Most of them perform a calculation on a number or a string, but there are also functions that give information about some aspect of the system. RECCOUNT, for example returns the number of records in a file, and FREE returns the amount of free memory space. Unlike a command, a function cannot be entered on its own as a statement. Thus: ? RECCOUNT("address") NUMRECS%=RECCOUNT("address") are valid statements, but RECCOUNT("address") produces an error message. All functions take an argument, which is enclosed in parentheses, and return a result. If the function calculates a result, the argument is what it works on. In the example above, "address" is the argument. It tells the function which file to count. Depending on the funcion, the argument(or arguments)may be a field name, a file name, constant, a variable, or a combination of these connected by an operator to form an expression. You will find details of what kind of argument a function expects, in the Keyboard Reference section. Although functions are usually classed as either string or numeric functions, this does not always guarantee that they take a particular kind of argument. Numeric functions always take numeric arguments, but some string functions also expect a numeric argument. CHR$, for example, returns a string result from a numeric argument. When it comes to finding out what type of result a function returns, there is a simple rule you can apply. Functions which have a $ character at the end, return their results as string data;if they do not end in a $, they return a numeric result. There is one exception to this rule - REPLICATE, which returns a string result, despite the fact that it does not have a $ at the end. OPERATORS DML provides three types of operators:arithmetic, relational and string. ARITHMETIC OPERATORS Addition The plus sign specifies that the operand on the right is added to the operand on the left, e.g.: 2 + 2 a% + b% + c% a% + 12.225 Subtraction The minus sign specifies that the operand on the right will be subtracted from the operand on the left e.g.: -3 -a% Multiplication The asterisk is recognised by DML as the multiplication symbol and specifies that the operand on the left is multiplied by the operand on the right, e.g.: 3 * 2 a% * b% a% * 12.225 Division The slash is recognized by DML as the division symbol and specifies that the operand on the left is divided by the operand on the right, e.g.: 3 / 2 a% / b% a% / 12.225 NOTE:UNLIKE IN MANY OTHER PROGRAMMING LANGUAGES, DIVISION BY ZERO DOES NOT CAUSE AN ERROR MESSAGE AND RETURNS A VALUE OF ZERO. THIS, OF COURSE, IS A FALSE RESULT, AND YOU SHOULD CHECK NUMERICAL DATA TO ENSURE IT DOES NOT OCCUR. Exponentiation The up arrow(or caret)is recognized by DML as the exponentiation symbol and specifies that the operand on the left is raised to the power specified by the operand on the right(the exponent);that is, the operand on the left is multiplied by itself the number of times specified by the exponent. If the exponent is 2, the number is squared;if the exponent is 3, the number is cubed; if the exponent is 1/2, the square root of the number results, e.g.: 3 ^ 2 (3 squared) a% ^ b% a% ^ 12.225 a6 ^ 0.5 (the square root of 16) 27 ^ 0.33333333 (the cuberoot of 27) 3 ^ -2 (1/3 * 1/3) Modulo arithmetic MOD gives the remainder when the operand on the left is divided by the operand to the right, e.g.: 17 MOD 7 (returns 3) a % MOD b% Parentheses Parentheses are used to change the order in which the different parts of an expression are calculated. Without parentheses, expressions are evaluated in a certain order which depends on the operators they contain - some operators have precedence over others(see the Table of Precedence). For example, multiplication has precedence over addition; so, in the expression: 3 + 4 * 2 the 'four times' part is worked out first and then added to 3, giving 11 as the result. You could alter this by enclosing '3 + 4' in parentheses: (3 + 4) * 2 to give a result of 14. Parentheses must always be paired - each '('should have a matching')'. Concatenation When used with strings or string variables, the plus sign causes the string specified by the right operand to be appended to the string specified by the left operand, e.g.: "ABCD" + "defg" evaluates as "ABCDefgh" Used in this way, the plus sign acts as a string operator. RELATIONAL OPERATORS Relational operators compare the values of two numbers or two strings, and return a result which is either true or false. They are mainly used with IF THEN and WHILE WEND statements to make a decision about whether the program takes a particular action or not. For example: IF n% > 30 THEN GOSUB label The relational operators are: > greater than 12>55 is false, i.e.0 = greater than or equal to < less than <= less than or equal to 27<=27 is true, i.e.-1 <> not equal to 1=5-4 is true, i.e.-1 = equal to LIKE pattern matching operator for strings. CONTAINS pattern matching operator for text files. As far as the user is concerned the result of comparison is either true or false. But when DML comes to evaluate a comparison, it actually assigns a numeric value to the result. If the result is true, DML assigns it the value of -1; if false, it assigns the value of 0. This means that if you enter the statement: ? 8>5 or ? "F"=LEFT$("FRIDAY", 1) DML will display -1. If the result of a comparision is false, it will display 0. For string operands, comparison is character by character from the left where 'a' is less than 'b' is less than 'c' and upperacase characters are less than lower case characters ('A" is less than 'a'). Note that numeric data can only be compared with numeric data and string data can only be compared with string data. If you attempt to compare numeric data with string data then the message: Can't do this/Data types don't match appears. LIKE LIKE is a case insensitive pattern matching relational operator which is used to compare string data. The question mark '?' and asterisk '*' characters can be used as wildcards. The question mark matches single characters and the asterisk '*' matches multiple characters. For a full explanation of how to use LIKE, see Volume I, Appendix B. CONTAINS CONTAINS works in the same way as LIKE, but it used with ASCII files on disk; for example, you could use the expression: CONTAINS "*Smith*" to search for an ASCII file which contained the name Smith. See Chapter 9, Volume 1, for more details. LOGICAL OR BOOLEAN OPERATORS. Logical operators are most frequently used to modify the results of relational operators. An expression that contains a relational operator can either be true or false. With a logical operator you can create more complex expressions whose truth or falsity(their 'truth value')depends on the truth or falsity of one or more relational expressions. AND This operator allows you to test whether two comparisons are true at the same time. For example: 12 > 5 and 6 < 16 are both true, so 12 > 5 AND 6 < 16 is also true. NOT NOT reverses the truth or falsity of an expression. Thus: 12 < 5 is false, so NOT 12 < 5 is true. NOT is often used with the EOF function to set up a program loop for processing all the records in a file, e.g.: WHILE NOT EOF("address") SELECT NEXT VIEW WEND OR OR gives a true result if one or the other, or both, of its operands is true. For example: 12>5 OR 12<5 8=2*3 OR 6>5 8=2*4 OR 6<5 all give true results. 12>5 OR A$="LONDON" gives a true result whatever the value of A$. 8=2*3 OR 12<5 gives a false result. Logical operators can also be used with numeric expressions to give a result which depends on the binary digits of the operands. In this context, they are sometimes known as bitwise operators. Instead of comparing the truth or falsity of expressions, AND and OR - when used as bitwise operators - compare the binary digits of two numbers, while NOT takes a single number, and changes each binary 1 to 0, and vice versa. Thus AND returns binary 1, if and only if, the corresponding digits in the two operands are both 1, e.g.: 85 AND 19 gives a value of 17. 2-12 85 in binary is 01010101 19 in binary is 00010011 The result is 00010001 which is 17 TABLE OF PRECEDENCE Complex expressions, containing more than one operator and several simple expressions, are evaluated according to the following table. The higher up the table an operator is, the higher the precedence it is given. This means that if there are two simple expressions, the one whose operator has the highest precedence will be evaluated first. ^ Exponentiation */ Multiplication and Division MOD Modulo arithmetic +- Addition and Subtration <> <=> = Relational operators LIKE CONTAINS Relational operators NOT Logical NOT AND Logical AND OR Logical OR Where identical weighted operators are concerned evaluation will be from left to right e.g.: 12 + 3-2 is evaluated as 12 + 3=15 : 15-2=13 12 + 3*4 is evaluated as 3 * 4=12 : 12 + 12=24 12 + 3*4-2 is evaluated as 3*4=12 : 12 + 12=12: 24-2=22 Parentheses can be used to promote expressions up the table, e.g.: (12+3) * (4-2) evaluates as 15*2=30 CONSTANTS The fixed values that you assign to variables or use as part of an expression are known as constants. There are two types:string constants and numeric constants. String constants must be enclosed in quotation marks. DML also provides a ready-defined constant PI, which has the value of 3.141593265359 and can be used in numeric calculations. EXPRESSIONS Expressions are formed from any combination of: Fields Variables Constants Functions Operators An expression can consist of a single variable name, a field name, or a constant, or it may be more complex, combining these with operators, constants and functions. The following are examples of expressions: 396 TODAY a$ "31 Ambleside Drive" textfielda numfielda Firstname.address LEFT$(Firstname.address, 1) 3.44*22.8 + 450 "Mr" + A$ A$ + B$ a%<>b% (a$=b$)AND(c%=1) INT(RND(1)*26)+1 COS(n%) LINE FORMAT AND LABELS There are no line numbers in DML;instead, to provide a reference for GOTO and GOSUB commands(or ON GOTO and ON GOSUB commands)you can place a label at the front of a line. Labels can be any combination of alphanumeric characters but cannot contain spaces. Labels must end in a colon (':')unless they consist only of numeric characters. You can use a number as a label without adding a colon, but this will not have the effect of altering the sequence of program lines. So, if you enter a line with the label '30' after a line with the label '50', both lines will remain in that order. A DML line, whether in direct mode or program mode, can contain more than one statement, provided the statements are separated by colons. Labels, however, can only be used in program mode. Any command which is placed at the beginning of a multi-statement line should be followed by a space. If it is followed by a colon without an intervening space, DML may interpret it as a label. For example, in the line: CLS:STATUS the command CLS has no effect, but CLS:STATUS works as intended. You also need to insert a space before an expression - a variable name or a field name, for example - if it is preceded by a DML command word. But otherwise in program mode, DML will accept lines without any spaces in them (it inserts spaces when it parses a line). In direct mode, it is generally necessary to insert spaces between the various elements of a command line. SYNTAX The Keyword Reference section gives the exact syntax for each keyword. However, there are several rules that apply generally. FILE NAMES AND FIELD NAMES Wherever a command is followed by a file name - or takes a file name as one of its arguments - the file name must be enclosed in quotation marks. Fieldnames should not be in quotation marks. For most operations, you should not include the extension name for a file(the part of the name after the full stop). Superbase automatically looks for files with the appropriate extension;so, with the command: OPEN FILE "Address" it looks for the file "Address.sbf". The one exception to this rule is when you are dealing with text files. OPEN FOR INPUT/OUTPUT, OUTPUT TO, IMPORT and EXPORT all take data to or from text files, and require that file names are given in full. If you save a file from Superbase's text editor, it automatically adds an '.sbf' extension to the file name - and when you open a file from the text editor, you do not need to supply the '.sbt' extension. But when you make use of a text editor file in some other applications - with IMPORT, for example - you must remember to include the .sbt extension. By the same token, you will not be able to load text files into the text editor unless you give them a .sbt extension. UPPER CASE AND LOWER CASE Certain string functions such as INSTR are case sensitive, but otherwise DML ignores the difference between lower and upper case letters(small letters and capital letters). In other words, it does not matter whether you use lower or upper case letters when you type in a keyword or any of the following: variables file names field names It is a good idea, though, to enter program lines and direct command lines in lower case. Once DML has accepted a line, it converts any reserved words (that is, any keywords) to upper case. Typing in lower case allows you to check that you have not used a reserved word by mistake. CHAPTER 3 - THE PROGRAM EDITOR THE PROGRAM MENU Operations relating to programs and programming are controlled from a single menu at the right of the menu bar, the Program menu. This section lists the Program menu options, and gives a brief explanation of their functions. Apart from Print and Remove (which should not require further explanation), each option is also described in more detail in the sections that follow. COMMAND Opens the Command line window, allowing the user to enter program instructions as direct commands. RUN Runs the program in memory or, if there is no program in memory, loads a program from disk and runs it. NEW Opens the Program Editor window and clears any program that may be in memory. EDIT Opens the Program Editor window. OPEN Loads a program from disk into memory. CLOSE Clears the program in memory - the program that is currently in the Program Editor - and closes the Program Editor window. SAVE Saves the program in memory to disk. PRINT Prints the program in memory. REMOVE Deletes a program file from disk. THE PROGRAM EDITOR WINDOW When you select Edit or New from the Program menu, Superbase opens a window at the right-hand half of the screen. This is the program window where you enter and edit programs. In most respects, the program window can be treated in the same way as the text window: you use the same controls for closing, resizing and moving the window(as explained in Chapter 10, Volume 1); and you also use many of the same key controls for editing a program. In fact, both the Program Editor and the Text Editor make use of the same window. The window can only be occupied by one of them at a time, but any changes you make to the size or location of the window will apply when you switch to the other editor. The main difference between the two is that the Program Editor does not have its own set of menus. The Program menu is available at all times - except when the Text Editor menus are active - whether the program window is open or closed. As with the Text Editor, you can switch between the program window and the database window simply by moving the mouse pointer to the required window and clicking in it. Thus, to edit a record after opening the program window, you would click twice in one of the fields displayed in the database window - once to make the database window active, and once to activate the record editing cursor(on the Amiga, you would only need to click once). If you then wanted to return to the Program Editor, clicking once in the program window would make the program cursor active again. Notice that the Close option on the Program menu not only closes the window but also removes the current program from memory. If you wish to close the window without clearing the program from memory, click on the close window gadget at the top left-hand corner. NOTE: Screen output from a Superbase program is displayed in the database window. If there is a record in view, program data will be output below or to the right of the bottom line of record data. To clear the database window before displaying program data on screen, use the CLS command. CREATING A NEW PROGRAM Selecting Edit from the Program menu opens the program window and places the program cursor at the top left-hand corner. When you enter the Program Editor for the first time in a session, the window will be empty;you can then start entering program lines straight away. If you have previously loaded a program into memory and want to start afresh on a new program, select New to clear the existing program from memory. Entering program lines is simply a matter of typing them in at the keyboard. When you have typed in a line, pressing the Return key will take you to the start of the next line. Superbase accepts program lines up to 255 characters long. As you type characters beyond the right-hand edge of the window, the program will be scrolled to the left. Using the scroll bars enables you to move the window over any part of a line up to 255 characters. LINE FORMAT An explanation of the correct format for a Superbase program line is given in Chapter 2, Line Format and Labels. However, it is worth repeating th rule about inserting spaces in a line:you need to insert a space if you enter an expression - such as a variable name, a field name, or a constant - after a keyword, or if you enter two adjacent keywords. In the following example, the space between the two items on the line must be entered by the user: ? "Hello" You should also type a space between a command and a colon if the command is placed at the start of a multi-statement line. If you do not do this, DML will interpret the command as a label. Otherwise, you can ignore spaces as you type in a program. If a line contains adjacent variables or operators and other elements of an expression, DML inserts spaces between them when it 'parses' the line. Parasing refers to the process which takes place when you press Return or move the cursor away from the current line. DML scans the line and identifies the various elements in it. As well as inserting spaces between recognizable elements, it also converts any keywords that are entered in lower case to upper case. Thus if you typed: if a%=3.5+6then goto label1 DML would parse this line as: IF a%=3.5+6THEN GOTO label1 You are recommended to enter program lines in lower case as a way of ensuring that you do not use reserved words as labels or variables. When a line is parsed, you will be able to see at a glance whether these items are correct, because the reserved words will be shown in upper case. It is unlikely that you will need to create programs with lines over 200 characters long. However, if you do, it is important to bear in mind that spaces may be inserted in the line. Even though the line you type in is less than 255 characters, it may exceed this limit when it has been parsed. EDITING A PROGRAM The Program Editor uses the same key controls for editing a program and moving the cursor around the screen as the Text Editor. As you would expect, it is not possible to specify margins or reformat a program;and the style setting functions are not available. Otherwise, the only difference is in the way the Return key works. In the Text Editor, Return either moves the cursor to the start of the next line or creates a new line, depending on whether overwrite or inset mode has been selected. In this section, we only provide a list of the Program Editor key controls together a brief description of their functions. For a detailed explanation of these keys, see Chapter 10, Volume 1. The '^' character is used here to represent the CTRL key; ^N for instance, indicates that the CTRL key and the letter N should pressed in combination. MOVING THE CURSOR As with the Text Editor, you can move the cursor around the screen and edit a program at any point on the screen. The cursor keys are used to move the cursor by one character at a time. Note that the term character includes the space character. LEFT ARROW Moves the cursor to next character to the left. RIGHT ARROW Moves the cursor to the next character to the right. UP ARROW Moves the cursor to the character in the same column on the line above. DOWN ARROW Moves the cursor to the character in the same column on the line below. For larger cursor movements, use the following keys: ^B Takes the cursor to the first line in the text. ^G Takes the cursor to the last line in the text. Shift right cursor(Amiga) Moves the cursor to the beginning of a line. Shift left cursor(Amiga) Moves the cursor to the end of a line. Tab Moves the cursor eight characters to the right. Shift Tab Moves the cursor eight characters to the left. Control T Moves the cursor eight characters to the left. DELETING AND INSERTING The following keys are used for deleting and inserting program lines or parts of a program line: BACKSPACE Delete character to the left of the cursor. DEL Delete character to the right of the cursor. ^W Delete word. ^E Delete to end of line. ^D Delete line. ^X Clear line. ^N New line. ^S Split line. ^A Join line. ^V Insert mode on/off. ^U Undo. Note that Undo works in the same way as in the Text Editor, and can be used as a 'cut and paste' facility, allowing you to move mutiple program lines to a new position. USING THE COMMAND LINE Selecting the Command option on the Program menu presents you with the DML Command Line dialog. Any commands you type in the command line box will be executed as soon as you click on OK or press Return;that is, they will be executed as direct commands. The command line box accepts single or multi-statement lines(with statements separated by colons)up to 255 characters. You can type in commands when ever the cursor is present. If the cursor is not shown, click in the box to activate it. There is very little restriction on which keywords can be entered as direct commands. READ(and DATA), GOSUB, and ON GOSUB cannot operate as direct commands, and you cannot use labels in the command line. Apart from these, almost any single or multi-statement line that can be entered in a program can also be entered in the command line. Clearly, any statement that refers to another statement in the command line will not operate, because of the absence of labels. However, it is possible to enter GOTO statements which refer to labels in the current program. You may want to do this when you are testing a program. The normal way of executing a program -using the RUN command or Run option - clears the program's variables. GOTO allows you to execute a program or part of a program without destroying any variable assignments that may have already been made. You will use the command line for variety of purposes. There are some operations - such as appending a text or program file to a file in memory - which can only be performed using commands. You may also want to enter commands as an alternative to selecting options from the Superbase menus;but it is generally more practical to do this by assigning the commands to a function key. In addition, the command line is valuable tool for developing and testing programs. Particularly useful are commands such as: ? MEMORY and ? LIST The first command lists the current program's variables and their values;the second can be used to display the program listing in the database window. EDITING THE COMMAND LINE The cursor keys move the cursor in the command line one character at a time. Home(Clr Home on the Atari ST)and End(Insert on the Atari ST)take the cursor to beginning and end of the command line. Del deletes the character in front of the cursor, Backspace deletes the character before. If you make a mistake while typing in the command line, you can use these keys to correct it. Command lines remain in the box after they have been executed and function key commands are placed in the command line box after execution, so you may also want to recall the previous command for editing. LOADING A PROGRAM To load a program from disk into the Program Editor, select Open from the Program menu. A file dialog will appear, listing the names of the program files in the current directory. You can then select a file in the usual way. If you want to load a program in another directory or on another disk, type in the file name preceded by the path name. To append a program on disk to program in memory, select the Command option. Then enter: LOAD "programname", APPEND where "programname" is the name of the program on disk which is to be joined to the current program. Most of the programs you run will have been created in the Program Editor. However, it also possible to load a program which has been written in a word processor, or has been created in another program editor. In this case, there are two requirements:the program file must have an '.sbp' extension, and it must be an ASCII file. Note that Open loads a program into the Program Editor, but it does not open the Program Editor window. If the window is closed and you wish to edit a program after loading it, select Edit. SAVING A PROGRAM Save on the Program menu saves the current program on disk. When you select this option. Superbase displays a dialog where you type in the name under which the program is to be saved. Normally, programs are saved on disk in 'tokenized' form;instead of storing each character in a keyword, Superbase represents keywords using single character tokens(keywords are represented in this way internally as well as on disk). To save a program as an ASCII file, enter in the command line: SAVE "program name", TEXT ASCII program files can be loaded back into the Program Editor and run straight away. Note that all program files, both tokenized and ASCII files, are given an '.sbp' extension. RUNNING A PROGRAM Select Run from the Program menu to run the program in memory. If there isn't a program in the Program Editor, Run displays the program file dialog. When a program has been selected, it is loaded into memory and then executed. The DML command RUN provides the program equivalent of the menu option. It is generally entered as a direct command, but it can also be used within a program. As a program command(rather than a direct command), RUN allows you to perform a task by linking together a series of programs. When one stage has been completed, RUN followed by a program file name will load and execute the program which performs the next stage. However, the drawback to using RUN for this purpose is that loading and executing a new program clears the previous program's variables. If you want to link a number of programs together, it usually preferable to use the CHAIN command. This provides the same facility as RUN but has the advantage that it does not clear any existing variable assignments. CREATING A START UP PROGRAM One of Superbase's most useful features is the way it lets you specify a 'start up' program, which will be automatically loaded and executed when you run Superbase. There are many ways in which you can take advantage of this feature, especially if you use Superbase on a regular basis for a specific application. All the tasks that you need to perform at the start of a session - such as opening files and loading a function key set - can be taken care of by the start up program. The procedure for creating a start up program is straightforward. There are two requirements: The program must be stored in a directory where Superbase will find it:either the Start directory as specified in Options on the Set menu(see Chapter 7, Volume 1)or the directory which is current when Superbase is loaded;usually this will be the same directory as the Superbase program file. The program must be saved under the file name Start(this appears on disk as Start.sbp). When you run Superbase, it looks in the current directory for a program with the name Start. If you have specified a Start directory in the '.par' file, it then looks for the program in that directory. EXAMPLES LOAD KEY "Funkey1" OPEN FILE "Address" OPEN FILE "Customers" SET TABLE VIEW This program loads a function file, opens two database files, set Table View, and then displays the first record in the Customers file. LOAD KEY "Funkey1" NUMBASE "z999999." RUN "Prog2" After loading a function key file, this program sets the numeric format and then loads and executes prog2. CHAPTER 4 - FUNCTION KEYS With Superbase's function key facility, you can create a new set of key controls. Each function key may be assigned a string of up to 255 characters. Depending on the context, Superbase will interpret the string either as a command(or sequence of commands)or as text. The main applications for this facility are: Creating command sequences - one line programs - to provide keyboard equivalents for the Control Panel buttons and menu options. Creating more complex command sequences which will perform multiple operations with a singl key-stroke. Inserting often-used words, keywords, phrases, and paragraphs in a text document or a program. The number of functions keys you can define depends on which version of Superbase is used. All versions provide the function keys F1 to F10. In addition, Amiga and Atari owners can use the Help key, which may be regarded as key F0. Another set of ten function keys is available when you use F1 to F10 in combination with the Shift key. To summarize these differences: 21 function keys are available to Amiga and Atari owners;F1 to F10 plus Help, and Shift F1 to Shift F10. MS DOS computers have 40 function keys;F1 to F10, and the same keys in combination with Shift, CTRL or Alt. SETTING A FUNCTION KEY There are two ways of setting a function key:using the Set Menu option Function keys(Function keys Edit on the Amiga), and using the DML command KEY. With the first method, you select Function keys from the Set menu. You will then be presented with the Function key dialog(see next page). On the Amiga, the four keys at the right of the panel are replaced by the HELP and Shift keys. On entry to the dialog, the F1 key is highlighted. Clicking on one of the other keys, F2 to F10 and HELP, highlights the key, making it available for setting. You can then assign a string to the key by typing it in the entry box below. Click in the box first if the cursor is not shown. For the Amiga and the Atari, the Shift key is the only one that can be used in combination with the keys F1 to F10 - Shift HELP is the same HELP on its own. When you have set the functions keys you require, click on OK. This action will assign the strings you have entered to their respective keys and then remove the dialog. The other method of setting the function keys is to use the DML command KEY - either from the Command Line or from a program. Consult the keyword reference entry under KEY for an explanation of how to use this command. FUNCTION KEYS FOR COMMANDS As we mentioned earlier, Superbase treats function key assignments as commands or text according to the circumstances. If one of the editing cursors is active, a function key string is interpreted as text;if a cursor is not present, a string is executed as a command. There are three circumstances in which an editing cursor may be active:when you are editing a document in the Text Editor, or a program in the Program Editor, and when you are editing a field in record edit mode. The rules governing the commands which can assigned to function keys are the same as for the Command Line(see Chapter 3). If the commands can be executed as a one line program, they can also be assigned to a function key. Note that single word commands at the beginning of a function key string must have a trailing space if followed by a colon. EXAMPLES The following function key strings show how you can create keyboard equivalents for the Control panel buttons: SELECT FIRST:VIEW This has the same effect as clicking on the First record button. SELECT LAST:VIEW Equivalent to the Last Record button. a%=0:a$=" ":REQUEST "Locate key", "", 4, a%, a$, 20: IF a$ <> " " THEN SELECT KEY a$:VIEW Equivalent to the Key Lookup button. The REQUEST command is not necessary for this purpose, but it allows you to display a customized dialog, making the operation of using an index key easier to perform. It is worth pointing out that the command KEY lists all the current function key assignments to the current output device. You may find it useful to assign this command to one of the function keys. Enter the single KEY as the function key string. Pressing the key will then show you at glance what the settings are for the other keys. FUNCTIONS KEYS FOR TEXT AND PROGRAM ENTRY In text entry, Function keys are useful for entering text strings which occur many times in the same document or are regularly used in different documents. They save you the trouble of having to type in the string yourself everytime it is needed. Provided the text cursor is shown on screen, pressing a function key will insert a string at the point where the cursor is located. The same applies to the use of function keys in program entry. You can define function keys to insert commonly used keywords in a program. For example, you might want to define the keys F1 to F5 as: REM LOAD " SAVE " OPEN FILE " WHILE Keys F5 to F10 could then be assigned commands which are useful during program development (you would have to activate the database window before these could be executed): MEMORY RUN PAGING ON:? LIST EDIT STATUS If you wish to assign a text string that runs over several lines, you need to use the carriage return character. However, it is not possible to enter this character in the Function keys dialog, so you must enter it using the KEY command in a program or in the Command Line. Thus to assign an address to F1, you enter a string like this: KEY 1, "6 Park Terrace " + CHR$(13) + "Worcester Park" + CHR$(13) + "Surrey KT4 7 JZ" + CHR$(13) NOTE:In most cases, function key strings which are intended for text entry cannot be executed as commands. Pressing a function key of this type when the cursor is not active may cause an error message. EDITING A FUNCTION KEY STRING If a function key has already been set, selecting the Function keys option (Function keys Edit on the Amiga)from the Set menu displays the contents of the key in the string entry box. Initially, the setting for the F1 key will be shown. If you wish to change the current setting, you can do so using the same editing controls as for the Command Line:cursor keys, Backspace, Del, Home and End. Alternatively, click on Clear to remove the current setting and type in a new function key string. Remember to press the Return key after editing a function key; otherwise your alterations will not be registered. FUNCTION KEY FILES The strings you assign to the functions keys can be saved on disk for use in other sessions with Superbase. Function key files are saved as ASCII files with the extension '.sbk'. If you wish to examine a function key file, you may display it on screen or print it out with the List option on the System menu. Notice that any keys which have not been assigned a string are shown as blank lines. SAVING FUNCTION KEY FILES Selecting the Function keys Save option saves the current function key settings on disk. Superbase adds the '.sbk' extension to the file name you type in. Function keys Save presents you with a file dialog, showing the existing '.sbk' files in the current directory. This operates in the same way as any other file dialog. If you select a file name from the list - instead of typing in a new name - a dialog will appear, asking if you wish to overwrite the selected file. You can then click on OK to overwrite, or Cancel to halt the operation. LOADING FUNCTION KEY FILES Select Function keys Load from the Set menu to load a function key file from disk. A file dialog will appear showing the '.sbk' files in the current directory. After a file has been selected, it is loaded into memory and sets the current function keys. The LOAD KEY "file name" command is used to load a function key file under program control or from the Command Line. Once you have created the function key set that meets your requirements, you can include this command, followed by the name of the function key file, in the Start program(see Creating a Start up program, Chapter 3). This way, the function keys will be set up for you as soon as Superbase has loaded. Another way of using the LOAD KEY command is to assign it to a function key. You will then be able to load a specified function key file with a single key press. CHAPTER 5 - KEYWORD REFERENCE GUIDE SYNTAX CONVENTIONS This section describes the conventions that have been used in the following documentation. The general format used to explain each keyword is as follows: PURPOSE -a brief description of the keyword. SYNTAX - the format of the keyword. COMMENTS - explains the format and function of the keyword in more detail. EXAMPLES - program examples. NOTES - explains the program examples and covers any other points not dealt with under the above headings. For the syntax of the keyword, the following terms and symbols are used: nexpr This can be any valid numeric expression consisting of numeric fields, date fields, numeric constants and/or numeric results of other keywords. For example, if a function expects a numeric argument, you could enter any of the following expressions: 156 (an integer) 156.25 (a floating point number) num% (a numeric variable) numfield (the name of a numeric field in a file) 3 + 6 (the result of an expression) SQR(25) (the result of a keyword) strexpr This can be any string or substring from a text field, external field, string variable, text literal or string result of other keywords. For example, any of the following expressions would be suitable entries for strexpr: "hello" (a string constant) strfield (the name of a string field) numfield (the name of a numeric field) fielda$ (a string variable) fielda$ (a string variable) Address (a file name) MID$("immediately", 3, 2) (a calculated result) var This can be any variable, string or numeric. If the keyword requires variables of a particular type, strvar or nvar are used for string or numeric variables. Various other conventions - such as fieldname or just field - are used to indicate particular data types. These should be self-explanatory.sbfile, for example, means that you should enter the name of a database file;on disk, Superbase identifies database files by an .sbf extension, but you should not include the extension name when you use it in a DML command. Any parameters or arguments contained in parentheses are compulsory(including any commas), while those within square brackets- '['and']' - are optional. All other arguments are compulsory. For instance, supposing the syntax for a keyword is given as: XXX(strexpr$, nexpr[.nexpr2]) This means that strexpr and nexpr are required with the keyword XXX and that they must be separated by a comma. The next argument, nexpr2, is optional, but if used must be separated from the second argument by a comma. The '/' character is used to indicate a number of alternatives. For example: CLOSE ALL/FILE sbfile The syntax for this statement indicates that CLOSE can be followed by either ALL or FILE, but not both at the same time. ? COMMANDS ? is a general purpose output command. You can use it to display information on screen, or to send information to the printer, or to create a file on disk. When ? is followed by a list of expressions - text, numbers, variables, fields, etc it sends the expressions to the current output device. It can also be used with the following keywords: DIRECTORY LIST MEMORY QUERY STATUS TEXT These keywords have a specific function when used with ?, and have been treated as separate commands. You will find an entry for each of them further on in this section. CHANGING THE OUTPUT DEVICE When you load Superbase, the ? command takes the screen as the default device and works in the same way as the PRINT command does in other versions of Basic - it displays information on screen. If you want to direct output to another device use one of these commands first: PARAMETER PURPOSE PRINT for the printer OUTPUT TO for the disk drive DISPLAY to switch back to the screen ? then continues to output to the device selected by one of these commands. CLS and HOME do not reset the current output device. PRINT and DISPLAY can be followed by a list of expressions which will then be output to the devices associated with these commands. When you use PRINT and DISPLAY simply to change the current output device, they should be followed by a semicolon, as in: PRINT; which directs all future output to the printer. OUTPUT TO needs a filename after it, as in: OUTPUT TO "texta" which directs output to a file on disk named 'texta'. OUTPUT FORMAT PARAMETERS After outputting a list of expressions, the ? command starts a new line unless you specify otherwise. This means that it takes the cursor to the beginning of the next line(if the current output device is the screen). You can instruct DML to output the next list of expressions on the same line, by placing a semicolon at the end of an expression list. When it is used in this way, the semicolon is known as an output format parameter, and is one of a number of parameters that allow you to specify how output is formatted. Apart from the semicolon, you place these parameters in front of the expressions that you want to format. Thus you can place them at the front of the line immediately after the ? character, and you can also insert them in the middle of an expression list. Some output parameters are keywords such as BF and DOWN, and others are symbols such as the semicolon itself and the @ sign. If you use keyword parameters, they must separated from each other by spaces. For example, DML will accept a line like this: ? UL BF IT "One", , "TWO' UL OFF @5, 10"Three" but it will not accept ? ULBFIT"One", , "Two"ULOFF@5, 10"Three" The output format parameters for the ? command are: PARAMETER PURPOSE & Sets length of text string @ Sets row and column position , Outputs a space ; Used as a separator and to suppress new line DOWN Outputs each item on a new line ALL Outputs all the fields in the current record NEWLINE Starts a new line BF[ON] Sets text to bold face UL[ON] Underlines text IT[ON] Sets text to italic BF/UL/IT OFF Turns selected text attribute off ATTR OFF Turns all text attributes off FG(Amiga only) Sets foreground color BF(Amiga only) Sets background color SAY(Amiga only) Speaks output EJECTnn Outputs data on a new page if there are less than nn lines left at the bottom of the page COMMENTS The @ sign, followed by a numeric expression, specifies the coloumn and row position for your output. For example, if the screen is the output device selected: ? @12, 7"Smith" displays the name Smith on the screen at column 12, row 7. As an alternative to using @, see LOCATE. DML treats a comma as a space character. For example: ? "Hello", , , "goodbye" outputs Hello goodbye Placing a semicolon after the last expression in the output list prevents DML from outputting a new line character. For example: ? "Hello":? "there" outputs them on the same line as Hello there Note that when the output device is the screen, DML only outputs the expressions in a list when it starts a new line. For example, if you enter the line: ? "one";"two";"three"; nothing will appear on the screen until you enter another line which does not have a semicolon at the end of it. If used, DOWN must be placed at the front of a line, before the line's expressions and after the ? character. It ensures that each expression in the list is output on a new line. For example: ? DOWN "one";"two";"three" nothing will appear on the screen until you enter another line which does not have a semicolon at the end of it. If used, DOWN must be placed at the front of a line, before the line's expressions and after the ? character. It ensures that each expression in the list is output on a new line. For example: ? DOWN "one";"two";"three" formats the output on screen as one two three When Down is used to format field data, it displays the field names in inverse video at the left of the data - in same way as Record View displays a record. ALL outputs the fields in the current record; for example, if the screen is the current output device: ? DOWN ALL would have the same effect as clicking on the current record button when Record View is selected. NEWLINE instructs DML to start a new line. Thus ? "one", "two"NEWLINE "three" outputs the expressions as one two three NEWLINE can also be used on its own - see NEWLINE, Keyword Reference. BF, UL, and IT set the text style for output. BF sets boldface UL sets underline IT sets italic Each of these can be set by ON(which is optional)and cleared by OFF. ATTR OFF clears all the text style attributes. For example: ? BF"Bold face on";IT "italics on";BF OFF IT OFF "Bold and italics off" On the Amiga you can also set the forground and background colours, using FG and BG. Each takes a parameter in the range 1 to 4 for the four colours set by Preferences. For example: ? FG 2 BF 1 "Foreground colour 2, background colour 1" SAY, which is only availabe on the Amiga, uses the Amiga's narrator device to speak the items in an expression list. Thus if you wanted to speak the field names and field data for the current record, you would enter: ? SAY DOWN ALL EJECT can be used to ensure that a group of data items - the fields in a record, for example - all appear on the same page. For example: 5-6 ? DOWN "One";"Two";"Three";"Four" EJECT 4 displays a new page if there is not enough room at the bottom for the four items in the expression list. ? PURPOSE Sends information to a device. SYNTAX ? [@nexpr] [;expr;expr, ....] COMMENTS Used to send one or more expressions(an expression list)to the current output device. ? can also include any of the output format parameters. When you output nemeric, date, and time constants or the results of functions for these data types, they take the format which has been set with the Number or Date/Time format options on the Set menu(or with the commands NUMBASE and DATEBASE). Field data is output in the format set in the file definition. However, you can force Superbase to output field data in the current format by enclosing the field name in brackets. Thus: ? (numfielda), (datefielda) displays the contents of these fields in the current numeric and date formats rather than in the formats they have been given in the file definition. EXAMPLES 1 ? "Hello" 2 ? "Hello";a$ 3 ? UL BF "Hello";a$;NEWLINE b$ 4 ? "The square root of";n%;"is";SQR(n% 5 ? "One""two""three" NOTES Depending on the numeric format that has been set, example 4 would output the numeric expressions, n% and SQR(n%), with leading spaces. To remove these, you would have to use the STR$ and LTRIM$ functions. You will notice that there are no semicolons separating the expressions in example 5. It is not always to place a semicolon between two expressions. Provided DML has some other way of telling where one expression ends and the other one starts, you can omit the semicolon. In this example the quotation marks allow DML to distingusih between the three expressions. ? DIRECTORY PURPOSE Lists the current directory to an output device. SYNTAX [?] DIRECTORY COMMENTS When the screen has been selected as the current output device, the directory is listed in two columns in alphabetic order. If the output device is the printer or a disk file, the directory is listed in single column. The "?" command is optional - DIRECTORY on its own has the same effect. ? LIST PURPOSE List a program in memory to an output device. SYNTAX ? LIST COMMENTS Do not confuse this command with LIST, which displays a text file on screen. ? LIST has several applications. You can use it to examine a program listing by displaying it on screen on printing it out;and, when the current output device is the disk drive, it allows you to save a program as a text file. In this last application, it has the same effect as: SAVE "program name", TEXT ? MEMORY PURPOSE Sends information about any defined variables to an output device. SYNTAX [?] MEMORY COMMENTS This outputs the variables in memory as: a%=123.46 b%=12.00 a1$="aaaaaaaaaaaaaa bbbbbbbb" etc. The variables are output in the order in which they were assigned. If you specify OUTPUT TO file, the values of the variables can be recovered for a subsequent program by the SET file command. The "?" command is optional - MEMORY on its own has the same effect. ? QUERY PURPOSE Runs the current Query in memory and sends the results to an output device. SYNTAX ? QUERY COMMENTS Query has four output options(on the Amiga, SAY provides a fifth option). You can send the output from a Query to the screen, the printer, to disk(as an ASCII file) or to file(as an '.sbf' file). However, when you save a Query, the currently selected output option is not saved with the rest of the Query settings; so if you run a Query under program control, you will need to select the output device beforehand. To send output to the printer, either set the Printer option from the Set menu, or issue a PRINT;command. To send output to disk, you should use the OUTPUT TO filename or OPEN filename FOR OUTPUT commands. The Query output will then be stored on disk under file name specified. EXAMPLES 1 LOAD QUERY "Stockrep" PRINT; ? QUERY 2 LOAD QUERY "Addreport" OPEN "Addrep.asc" FOR OUTPUT ? QUERY NOTES In the first example, output from the Stockrep Query is directed to the printer; in the second example, output from the Addreport query is used to create an ASCII file on disk under the name Addrep.asc. ? STATUS PURPOSE Sends information about the System Status SYNTAX [?]STATUS[FILE sbfname] COMMENTS ? STATUS without the FILE option gives the same output as the menu option System Status. If no Superbase files('.sbf' files)are open, it displays the following information: Memory free Diskspace Free Current Directory Name Superbase Files open(as 0) Superbase Files available. If any database files are open, the header information for these files is also shown. ? STATUS FILE sbfname gives the same output as the menu option SYSTEM STATUS FILE, and produces a status report for the file. At the top of the report, it shows file statistics such as the nmber of records and the file siz. Belows this, it shows the file definition details:for each field, it lists the field name, its attributes, format, Form View location, and any associated calculation or validation formula. If the file is not open, the error message 'Can't do this / File not open' appears. The '?' command is optional with STATUS - using STATUS on its own has the same effect. ? TEXT PURPOSE Sends a text file in memory to an output device. SYNTAX ? TEXT[MERGE] COMMENTS This command outputs the current text file in the Text Editor. If the text file is a form letter and its associated database file has been opened, adding the MERGE command will merge the data in the current record with the text file. See also the Keyword Reference entry for MERGE. EXAMPLES 1 OPEN FILE "Address" LOAD TEXT "Maillet" ? TEXT MERGE NOTES If the current output device is the screen, this example will insert the data from the first record(in the Address file)into the Maillet text file, and display the result in the database window. ABS PURPOSE Turns negative numbers into positive numbers but leaves positive numbers unchanged. SYNTAX ABS(nexpr) COMMENTS ABS returns the 'absolute' value of a number. In effect, it simply strips the sign off a negative number, making it positive. One of its common uses is for calculating the difference between two numbers when you do not know which is larger. In example 2, which works out the number of days between two dates, ABS allows you to enter the dates without first knowing which is the later date. EXAMPLES 1 numfieldc=ABS(numfielda) 2 numfieldc=ABS(datefielda-datefieldb) 3 numfieldc>ABS(numfielda * numfieldb) 4 x%=ABS(y%) 5 x%=ABS(y% * numfielda * (datefielda-datefieldb)) 6 x%=ABS(VAL(RIGHT$(textfielda, 5))) 7 ? ABS(x%) ADD PURPOSE Adds a new field to a file definition. SYNTAX ADD[FILE sbfname]field-definition-string[formula-string][formula-string] COMMENTS This command is used in conjunction with CREATE and MAKE to create a new Superbase database file. It cannot be used to add a field to an existing file. To use ADD correctly, you need to understand how a file definition is set up. The best way to do this is to use the STATUS FILE option in Superbase's System menu. This will show you the file definition for the current file. Another way of viewing the same information would be to list an '.sbd' file on screen using the System menu's LIST option. With one exception, the parameters used with ADD to define a field are the same as those used in '.sbd' file definitions. The exception is '>' and '>>'. These are used in '.sbd' files to indicate that there are one or two formula lines to follow. You do not need to include these characters in a field definition string. From left to right, the field definition string is composed of the following parameters: fieldname fieldtype[other fieldtype parameters] format[case and multiple response parameter for text fields] row; col Each of these parameters must take the same form as it does in an 'sbd' file. fieldname must conform to the rules for fieldnames. fieldtype must be one of the following: TXT text EXT external NUM numeric DAT date TIM timefield DEL deleted The other fieldtype parameters are optional and, if used, are separated from fieldtype and each other by at least one space. You can specify up to three of these parameters, selecting one from each of the following groups: A) CLC Calculated CLV Calculated and validated CON Constant COV Constant and validated VAL Validated B) RDO Read only RDQ Read only required REQ Required C) IXU Indexed - Unique IXD Indexed - Normal format specifies the length of a field and the numeric format for numeric fields, format must be appropriate for the field type. For example, 20 for TXT, z99999.00 for NUM, ddmmmyy for DAT. The case parameter can be U, L or C, depending on whether the text data is to shown in upper case, lower case or with the first letter capitalized. The multiple response parameter is M followed by the number of elements in the multiple response field(maximum 9). These parameter are optional and can only be used with text fields. They must be separated from the field format by at least one space. For example, to define a text field with three multiple response fields, each up to 15 characters long, you would enter these parameters: 15 M3; If you also wanted the field data to be in upper case, you would enter: 15 UM3; row is the row position for FORM-view(maximum 255). col is the column position for FORM-view(maximum 255). row and col are optional, but you are strongly recommended to use them. If they are not used, all the fields will be positioned at the top left of the screen on top of one another when the record is displayed in Form View. The field types in group A-CLC, CLV, CON, COV, VAL-must be followed by a formula or formulas. CLV and COV require two formulas;the formula for constants or calculations should be come first, followed by the validation formula. Formulas should be enclosed in quotation marks and must be separated by commas from the first part of the field definition string and from each other. formula-string must follow the rules(given in Volume 1)for using formulas for calculations, constants and validations. Since formulas must be enclosed in quotation marks, DML will be confused if a formula itself contains quotation marks, as in: fielda LIKE "[a-c]*" The simplest solution here is to use the tilde character '~' in place of quotation marks. When you execute the ADD command, DML will interpret the tilde as a quotation mark. An alternative solution is to use the CHR$ function to insert quotation marks the ASCII code for quotation marks is 34. Thus the line to set up a validated field called fielda of length 12 at row 5, column 20 would be: ADD"fielda;TXT VAL;12, 5;20", "fielda LIKE" + CHR$(34) + "[a-c]*" + CHR$(34) In the unlikely event that your formula actually requires a tilde character, you can insert it in a string variable using CHR$(126). Note that the maximum length for a program line is 255 characters. Since a formula can also be up to 255 characters long, you may be unable to enter the entire field definition on a line. The solution is to assign formulas to string variables beforehand. For example: a$="Price.Orders * Quantity.Orders" ADD "Subtotal;NUM;$9999999.00;5, 20", a$ EXAMPLES 1 ADD "aatext;TXT REQ IXU;20 M3;1, 12" 2 ADD "aanumb;NUM;z999999.00;1, 40" 3 ADD "bbtext;TXT CLC RD0;10;2, 12", "UCASE$(LEFT$(aatext, 10))" 4 ADD "fielda;TXT VAL;12;15;20", "fielda LIKE " + CHR$(34) + "[a-c]*" + CHR$(34) NOTES Creating a file under program control is a three stage process involving CREATE, ADD, and MAKE. For a description of the process, see CREATE. AFTER GROUP PURPOSE Set after group activity with reports. SYNTAX AFTER GROUP fieldname COMMENTS When you create a report using the Forms Editor's reporting facility, Superbase generates a Report program for you. The AFTER GROUP statement is used within a Report program to mark the start of an AFTER GROUP section. This consists of a series of "?" statements which specify the information that is output every time a group changes. Each statement corresponds to a line in the AFTER GROUP box in the Forms Editor. fieldname identifies the group and must be name of a field which has previously been defined as a group with the GROUP statement. An AFTER GROUP section must end with an END REPORT statement. EXAMPLES 1 AFTER GROUP Lastname.Clients ? BF ?Client", GROUP, "has";COUNT amount;"Deposits" ? BF "Total desposits are", @25SUM amount ? BF "Maximum is", @s5 MAX amount ? BF "Minimum is", @25 MIN amount END REPORT NOTES In the second line of this example, the keyword GROUP is used in order to retrieve the name of the last group. At this point, the group has already changed;so, Lastname.Clients could not be used instead of GROUP because it would output the name of the current group. EXAMPLES 1 AFTER REPORT ?@1, 3;UL "Statistics for the Report", UL OFF:? ?"Total amount is", @30 SUM amount ?"Number of deposits", @30 COUNT amount ?"Average amount", @30 MEAN amount END REPORT ASC PURPOSE Returns the ASCII value of a single character. SYNTAX ASC(strexpr) COMMENTS ASC gives a numeric value-the ASCII code-for the text character in strexpr. When strexpr is longer than one character ASC returns the ASCII code of the leftmost character of strexpr. Appendix E, Volume 1, gives the ASCII characters and their decimal codes. The complementary function of ASC is CHR$. EXAMPLES 1 numfieldc=ASC(textfielda) 2 numfieldc=ASC(RIGHT$(textfielda, 1)) 3 ASC(textfielda) > 64 AND ASC(textfielda) < 91 4 x%=ASC("A") 5 x%=ASC(x$) 6 x%=ASC(UCASE$(MID$(extfield, 3, 1))) 7 ?ASC(x$) NOTES Example 3 provides one way of validating a text field to ensure that the first character is uppercase(but see FCASE$). ASK PURPOSE Inputs a character string from the keyboard. SYNTAX ASK[pos] [string] [&length];var/field COMMENTS This command allows the user to enter information from the keyboard into the computer while a program is running. It expects the user to type in one or more characters, and, as soon as the Return key is pressed, reads them into a variable or a field. string can be used to include a prompt message. pos gives the position of the prompt text and input string. It uses the @ output format parameter to specify the column position, followed by the row position. If pos is not given then the input string appears on the row where the cursor is currently located. &length limits the length of the input and shows the maximum length on screen using an 'end-of-field' marker. The input can be assigned to a variable or a field(in a currently open file). If the field is not in the current file, it can be specified with the filename extension. var or field can be either string or numeric variables or fields, and they must match the type of input expected:a string variable will accept whatever you type in, but a numeric variables when you input non-numeric data such as letters. The same restriction applies to numeric fields. EXAMPLES 1 ASK;x$ 2 ASK@2, 12"Enter a text string";x$ 3 ASK@2, 14"Enter a 3 character word"&3;x$ 4 ASK"Enter data-Customer Code"&8Cuscode.custfile 5 ASK"Enter a number";n% ATN PURPOSE Calculates an angle whose tangent is known. The result is given in radians. SYNTAX ATN(nexpr) COMMENTS This function works out the angle from the angle's tangent given in nexpr. For example: TAN(0.7854)is 1.0, so ATN(1.00)returns 0.7854 rads(which is 45 degrees). To convert radians to degrees multiply by PI/180. ATN is the complementary function of TAN. EXAMPLES 1 numfieldc=ATN(numfielda) 2 x%=ATN(y%) 3 x%=ATN(VAL(x$)) 4 ?ATN(x%) BEFORE GROUP PURPOSE Set before group activity with reports. SYNTAX BEFORE GROUP fieldname COMMENTS BEFORE GROUP is used in a Report Program to mark the start of a BEFORE GROUP section.fieldname identifies the group, and must be the name of a field which has previously been defined as a group-in the Forms Editor, you define a group in the SELECT box; Superbase then translates this into a GROUP statement in a Report program. The statements in the BEFORE GROUP section ar executed every time the group changes. Typically, they would be used to display header information for the group data which follows. A BEFORE GROUP section must end with an END GROUP statement. EXAMPLES 1 BEFORE GROUP Lastname.Clients ? "Deposits for client", Lastname.Clients ? ?"Firstname Lastname Bank Amount Date" "--------------------------------------" END GROUP BELL PURPOSE Makes a short beep. SYNTAX BELL COMMENTS Use this command to signal that a particular process has finished and to attract the user's attention. On the Amiga, BELL does not make a sound but causes the screen to flash. BLANK PURPOSE Creates a blank record in memory. SYNTAX BLANK[FILE sbfname] COMMENTS When you want to create a new record under program control, issuing a BLANK statement is the first step in the process. It sets up an empty record record ready for data entry. There are several ways in which you can then enter data into the record's fields. Using BLANK with ENTER, allows the user to type in the data for a new record from the keyboard. Together these two commands have the same effect as the RECORD NEW option in the RECORD menu. Alternatively, you can enter data from within a program, by assigning it directly to the fields in the new record. Typically, this would be the method you used to create new records by reading data in from another file on disk. EXAMPLES 1 BLANK 2 BLANK FILE"abc" 3 BLANK ENTER STORE 4 BLANK Firstname.address="John" Lastname.address="Smith" STORE The first example creates a new record in the current file. Example 2 creates a new record in another open file. Example 3 creates a new record in the current file, and allows the user to enter in the record;then it saves the record on disk. Example 4 creates a new record, and enters data into the fields Firstname and Lastname;then saves the record on disk. BREAK PURPOSE Allows the user to interrupt or halt a program from the keyboard. SYNTAX BREAK ON/OFF COMMENTS BREAK ON and BREAK OFF enable and disable CTRL C. After BREAK ON(the default condition), you can stop a program while it is running by pressing the Control key and C at the same time. This has the same effect as clicking on the STOP button at the bottom of the screen. CTRL C generates error 11. If you want to include error handling routines in your programs, you can use the ON ERROR statement to check for this error number. CALL PURPOSE Calls a user supplied function. SYNTAX CALL function COMMENTS function is string expression containing a command line to be executed by DOS or Amiga DOS. The expression should duplicate a command line that would normally be typed at the DOS or CLI prompt. Superbase stays in memory so there must be enough memory for the specified command to function correctly. CHAIN PURPOSE Executes another program from within a program but does not clear the first program's variables. SYNTAX CHAIN filename COMMENTS CHAIN allows you to carry out a task by linking together a number of programs. When a program is running, this command loads another program from disk, and transfers control to it. The second program displaces the first in memory but any variables that have already been set retain their values. EXAMPLES 1 CHAIN "Nextprog" CHR$ PURPOSE Generates the character associated with an ASCII code. SYNTAX CHR$(nexpr) COMMENTS CHR$ works in the opposite way to ASC. Wheras ASC takes a character and returns its ASCII code, CHR$ generates the character from its associated code. It is useful for handling characters which are not available from the keyboard, such as certain characters used to control a printer. nexpr must have a positive value in the range 0-255(although not all these values will give printable characters). A value outside this range will give the error 'Invalid numeric parameter'. If nexpr is not an integer, the integer part of the number is used, i.e., 65.999 is treated as 65. EXAMPLES 1 textfieldc=CHR$(numfielda) 2 textfieldc=CHR$(INT(numfielda/256)) 3 x$=CHR$(65) 4 x$=CHR$(ASC(y$)+32) 5 FOR n%=32 to 127 ? CHR$(n%); Next NOTES Example 3 stores the letter A in x$. Example 4 demonstrates one way of turning an uppercase character into lowercase - but see LCASE$ and FCASE$. Example 5 displays the character set on the screen. Note that it does not display characters are non-printing characters, and some of them have unexpected effects when you attempt to display or print them. CLEAR PURPOSE Clears all user variables. SYNTAX CLEAR COMMENTS This command clears all variable assignments in memory. Using ? MEMORY immediately after CLEAR would give no output. CLOSE PURPOSE Closes an input or output channel to a text file or comms line. SYNTAX CLOSE INPUT/OUTPUT COMMENTS Only one input channel and one output channel can be open at a time, so you are adivsed to use the CLOSE command when you have completed an I/O task. Unless you close the current channel you will not be able to open a new channel. CLOSE also ensure that all data in the disk buffer is written to disk. If you have a large disk buffer and a small amount of data, you will notice that some output commands-? LIST, for example-appear to have no effect. What happens is that DML places the data in the buffer before writing it to disk. It remains there until the buffer fills up-or until you execute a CLOSE OUTPUT command. Associated commands are OPEN and INPUT. EXAMPLES 1 OPEN FILE "aaa" FOR OUTPUT FOR i%=1 to 10:? i%, i%^2:NEXT i% CLOSE OUTPUT OPEN FILE "aaa" FOR INPUT getnext:INPUT LINE a$:? a$ IF EOF("*") THEN GOTO getnext CLOSE INPUT CLOSE FIELDS PURPOSE Closes the field list on the current file or another open file. SYNTAX CLOSE FIELDS[FILE sbfname] COMMENTS CLOSE FIELDS removes any restrictions on which fields are shown. If you VIEW a record after issuing this command, all its fields will be displayed on screen. On its own, CLOSE FIELDS closes the field list for the current file. When FILE sbfname is added, it closes the list for that file. EXAMPLES 1 CLOSE FIELDS Close field list on current file. 2 CLOSE FIELDS FILE "abc" Close field list for file 'abc'. CLOSE FILE PURPOSE Closes all files or a specified file. SYNTAX CLOSE[ALL]/[FILE sbfname] COMMENTS CLOSE FILE works in the same way as the equivalent option in the PROJECT menu, but unlike the menu option it also allows you to close all the open files in one go. EXAMPLES 1 CLOSE Closes the current file. 2 CLOSE FILE "aaa" Closes the database file 'aaa'. 3 CLOSE ALL Closes all open database files. CLOSE FORM PURPOSE Closes the current Form SYNTAX CLOSE FORM COMMENTS This command works in the same way as the Close Form option on the Project Menu: it clears the current Form from memory and displays the current file using one of the view modes. CLS PURPOSE Clears the screen. SYNTAX CLS COMMENTS CLS makes the output part of the screen-the output window-blank and takes the cursor to the top left-hand corner. EXAMPLES 1 CLS:? "Now at top of cleared screen" COL PURPOSE Returns the cursor's position across the screen. SYNTAX COL(0) COMMENTS Use this command to find out the column position of the screen cursor. For the row position, see ROW EXAMPLES 1 x%=COL(0) 2 ? COL(0) NOTES In practise, Example 2 would be pointless because the statement changes the cursor position in the course of printing it. COPY PURPOSE Makes a copy of a file on disk. SYNTAX COPY from.filename[, ]/[TO]to.filename COMMENTS Use this command either to copy a file to the same disk under a different name, or to copy it to another disk. In the latter case, you can give the file the same name or a new name. EXAMPLES 1 COPY "aaa", "bbb" Copies 'aaa' to 'bbb'. 2 COPY "A:aaa" TO "B:bbb" Copies 'aaa' to drive B under the name 'bbb'. COS PURPOSE Returns the cosine of an angle measured in radians. SYNTAX COS(nexpr) COMMENTS To convert an angle in degrees to radians, multiply by PI/180. Associated functions are ATN, SIN and TAN. EXAMPLES 1 numfieldc=COS(numfielda) 2 x%=COS(y%) 3 x%=COS(VAL(x$)) 4 ? COS (x%) CREATE PURPOSE Creates a new database file in memory. SYNTAX CREATE sbfname[:passwords] COMMENTS CREATE is only the first step in the process of building a new file. To define the file and store it on disk you also need to use ADD and MAKE. The whole process involves the following steps: 1. CREATE sbfname 2. ADD field At this point the file is held in memory and you can check it with ? STATUS sbfname. 3. MAKE sbfname Writes the file to disk. EXAMPLES 1 CREATE "Address" ADD "Recno;NUM CON IXU;999999.;0, 0", "SER(~Address~)" ADD "Title;TXT;10;1, 34" ADD "Firstname;TXT;15;3, 6" ADD "Lastname;TXT IXD;20;3, 34" ADD "Street;TXT;30;6, 6" ADD "City;TXT IXD;15;7, 6" ADD "Code;TXT;12;7, 31" ADD "Country;TEXT IXD;15;9, 6" MAKE "Address" NOTES This sample shows how to set up a simple address file under program control. The first ADD statement defines a numeric field which is automatically assigned a record number by means of the SER function. Note the use of the tilde character to enter the filename Address within quotation marks. Following this, the ADD statements define eight text fields which will hold the name and address. Once you have defined the file in this way, you could then enter its data under program control, using the commands BLANK and STORE. CREATE INDEX PURPOSE Creates a new index file. SYNTAX CREATE INDEX ON exp[FILE sbfname][TO index][UNIQUE] COMMENTS This command is the program equivalent of the New Index option on the Project menu. EXAMPLES 1 CREATE INDEX ON aaa 2 CREATE INDEX ON aaa.bbb UNIQUE 'bbb' does not need to be the current file, but it must be open. DATA PURPOSE Holds the data(numeric and string constants)that is accessed by a READ statement. SYNTAX DATA constant[, constant][, ......] COMMENTS The values(constants)following a DATA statement must be separated by commas and text constants must be in quotation marks. Because commas are used to separate the constants in a DATA statement, they cannot be included in a constant. If you need to insert a comma in your DATA items, you can use CHR$(44). To insert quotation marks in a string constant, use CHR$(34). Date values which are to be read into date fields must be in the correct format (e.g., "ddmmyy" or "mmddyy")and should be enclosed in quotation marks. If you intend to use the RESTORE statement, you need to place a label in front of the DATA statement. EXAMPLES 1 DATA "abcde", 1.04, 2.46, "uvwxyz" data1:DATA 12.2, 12.4, 12.97, 13.4, 9.2, -1 DATE$ PURPOSE Returns a string from a julian date number. SYNTAX DATE$(nexpr[, format-strin]) COMMENTS This function expresses a date number as a text string showing the day, month and year. The format-string option is used to specify the date format for the text string. It must be a valid Superbase format as shown in the entry for DATEBASE. If the format is given, the text string takes the date format as set with the Date Format option on the Set menu, or as specified with the DATEBASE command. The complementary function to DATE$ is DAYS. Associated date functions are DAY DAYS DAY$ MONTH MONTH$ YEAR. EXAMPLES 1 textfieldc=DATE$(datefielda, "ddmmyy") 2 textfieldc=DATE$(datefielda + 90) 3 textfieldc=DATE$(TODAY) 4 x$=DATE$(y%) 5 ? DATE$(datefielda + 30) NOTES Example 3 provides a calculation to insert the system date into a textfield. Example 2 gives the date 90 days after the date in datefielda. The Calendar adjustment of 1752 has been accounted for. Unless you are sure that the date supplied in nexpr will always fall within this century, you should set the date format to allow four figures for the year; otherwise you will not be able to distinguish between 1901 and 2001. With dates before AD 1000, the four figure year default option does not insert zeroes. AD 55, for example, is shown as 55 and not 0055. If you wish to have four figure years-say, to line up output-add 3653048 to nexpr. As well as ensuring that the date is always expressed as four figures, this is the only way to access AD 0. However, early calendars were not particularly accurate and accurate day counts between two dates cannot be relied on with dates before AD 1400. (Superbase always gives the same answer; history, though, is less consistent). DATEBASE PURPOSE Sets the DATE format and TIME format. SYNTAX DATEBASE string COMMENTS DATEBASE allows you to specify the format with which Superbase displays the date and time. Normally, this format only applies when you use the system variables, TODAY and NOW. It does not affect the format of date and time fields, as set in the file definition. This means that if you define a date field with the format "dd-mmm-yy", the command ? datefield will display it in this format, irrespective of what the DATEBASE format is. However, you can force Superbase to display a date field in the current date format by enclosing the field name in parentheses, as in: ? (datefield) string must have a valid date or time format, as shown in the examples below. EXAMPLES 1 DATEBASE "dd mmmm, yyyy" Displays the date like this as 10 June 1987 2 DATEBASE "dd/mm/yy" Display the date as 10/6/87 3 DATEBASE "mm-dd-yy" Displays the date as 6-10-87 4 DATEBASE "dd.mm.yy" Displays the date as 6.10.87 5 DATEBASE "dd mm yy" Displays the date as 6 10 87 6 DATEBASE "hh:mm" Displays the time as 14:35 7 DATEBASE "hh:mm:ss" Displays the timeas 14:35:08 8 DATEBASE "hh:mm:ss.s" Displays the time as 14:35:08.36 9 DATEBASE "hh:mm am" Displays the time as 2:35 pm DAY PURPOSE Returns the day of the month as a numeric value from a date field or a date string. SYNTAX DAY(nexpr) COMMENTS The number which DAY returns takes the numeric format as set in the SET- NUMERIC FORMAT Superbase menu, or as set with the command DATEBASE. Associated date functions are DATE$ DAY DAY$ MONTH MONTH$ YEAR. EXAMPLES 1 numfieldc=DAY(datefielda) 2 numfieldc=DAY(datefielda + 90) 3 numfieldc=DAY(TODAY) 4 x%=DAY(datefielda + VAL(textfielda)) 5 x%=DAY(DAYS("11 Jan 85") 6 ?DAY(datefielda + 30) NOTES Examples 3 provides a calculation to insert the day number of the system date into a numeric field. DAY$ PURPOSE Returns the day of the week as a text string from a julian date number. SYNTAX DAY$(nexpr) COMMENTS Associated date functions are DATE$ DAY DAY$ MONTH MONTH$ YEAR. EXAMPLES 1 textfieldc=DAY$(datefielda) 2 textfieldc=DAY$(datefileda + 90) 3 textfieldc=DAY$(TODAY) 4 x$=DAY$(DAYS("11 January 1985")) 5 x$=DAYS(y%) 6 ?DAYS(datefielda + 30) NOTES Example 3 provides a calculation to insert the weekday of the system date into a textfield. Example 4 provides a weekday for the date shown in quotation marks. DAYS PURPOSE Returns the date as a julian date number from a text string or text field. SYNTAX DAYS(strexpr) or DAYS(nexpr) COMMENTS This function returns a number which is the julian day number of the date in strexpr(31 December AD 0 has a julian date value of zero). It takes the 1752 Gregorian reform of the calendar into account. strexpr must be in a valid date format. A text expression which is not in one of the valid date formats will produce a message 'invalid date format'. Associated date functions are:DATE$ DAY DAY$ MONTH MONTH$ YEAR. EXAMPLES 1 numfieldc=DAYS(textfielda) 2 numfieldc=DAYS(datefielda + 90) 3 numfieldc=DAYS("11 jan 85") 4 x%=DAYS(a$) + 90 NOTES In example 2, the use of DAYS is redundant. DELETE PURPOSE Deletes a file stored on disk. SYNTAX DELETE filename COMMENTS This command has the same effect as the ERASE command in MS DOS and DELETE in Amiga DOS. To delete a file on a drive or directory other than the current one, you need to place the path name in front of the file name. EXAMPLES 1 DELETE "aaa" 2 DELETE "b:aaa" 3 DLETE "DF0:aaa" DIM PURPOSE Defines array variables SYNTAX DIM variablename(nexpr[, nexpr][, nexpr]) COMMENTS Arrays can have up to three dimensions. nexpr specifies the number of elements in each dimension of an array. The maximum number of elements is limited only by the amount of available memory. A single DIM statement can be used to define more than one array. If DIM is used in this way, each array defintion should be separated by commas. Note that the first element in an array dimension has the subscipt 0. EXAMPLES 1 DIM x%(20) Defines a one dimensional numeric array with 21 elements. 2 DIM b$(10) 3 DIM x%(3, 10) 4 DIM b$(2, 12) 5 DIM a$(20), n%(2, 3, 10), c$(2, 10) DIRECTORY PURPOSE Changes the current directory. SYNTAX DIRECTORY "path" COMMENTS Directory can be used to switch to a directory on another drive or to a different directory in the same drive. EXAMPLES 1 DIRECTORY "dh0:mydir/testdir" 2 x$="a:":DIRECTORY x$ 3 C:/Images DISKSPACE PURPOSE Shows the amount of space remaining on a disk. SYNTAX DISKSPACE(strexpr) COMMENTS This function gives the number of unused bytes on a disk. On the Amiga, the disk name given in strexpr can be either a drive name or a volume name(i.e., a diskname such as Mydisk:). On the Amiga, the diskname must end in a colon. Note also that the free block given by the CLI are 488 byte blocks. EXAMPLES 1 Diskspace "df0:" 2 DISKSPACE ("Mydisk:") 3 x$="df1:":x%=DISKSPACE(x$) 4 ? "Remaining diskspace is: ";DISKSPACE("a:");"bytes" EDIT PURPOSE Allows the user to edit a program, a text file, a Query, or an Update. SYNTAX EDIT [TEXT]/[QUERY]/[UPDATE] COMMENTS Depending on which option has been selected, EDIT displays a window or a dialog. EDIT QUERY displays the query dialog. EDIT UPDATE displays the update filter dialog. EDIT TEXT opens the text editor window. If none of the three options has been selected, EDIT opens the program window. After EDIT has opened a window or dialog, you can edit the information, just as you would if you had selected one of the Edit options from the Superbase menus for example, Edit Program from the Advanced menu, or Edit Query from the Process menu. The difference is that when you exit from the window or dialog, control returns to the program. To exit from a window, close the window by clicking on the close gadget in the top left-hand corner. You exit from a dialog by clicking on OK or Cancel. In Superbase itself, clicking on OK takes the user out of the dialog, and then runs the query or update;clicking on OK after EDIT returns control to the program without executing a query or an update.(To run a query, use ? QUERY, and use UPDATE to carry out an update.) EJECT PURPOSE Ejects the current page on the printer or feeds in a new page when the number of lines remaining is less than the number specified. SYNTAX EJECT[nexp] COMMENTS EJECT on its own has the same effect as pressing the Form Feed button on the printer. It sends a Form Feed character to the printer, which then moves the current page on and feeds in the next. If nexp is used, the page is ejected when the number of lines at the bottom of the page is less than nexp. EXAMPLES 1 EJECT 2 EJECT 3 Feeds in a new page if there are less than three lines left at the bottom of the current page. END PURPOSE Terminates program execution. SYNTAX END COMMENTS This command brings a program to a halt and returns control to the Superbase Menu system. END is optional and if you do not include it, DML will return control to Superbase when it reaches the last statement in a program. EXAMPLES 1 IF EOF("aaa") THEN END END GROUP SYNTAX END GROUP PURPOSE Marks the end of a BEFORE GROUP or AFTER GROUP section. COMMENTS A BEFORE GROUP or AFTER GROUP section in a Report program must end with an END GROUP statement. If it doesn't, Superbase will be unable to tell which statements below to which section. END HEADING PURPOSE Marks the end of a HEADING section in a Report program. SYNTAX END HEADING COMMENTS A HEADING section defines the headings for a report. It must start with the keyword HEADING, followed by one or more '?' statements which specify the heading information. END HEADING must be placed at the end of the section. END REPORT PURPOSE Marks the end of an AFTER REPORT or BEFORE REPORT section. SYNTAX END REPORT COMMENTS END REPORT must be placed at the end of the set of statements that constitute an AFTER REPORT or BEFORE REPORT section in a Report program. Superbase automatically generates END REPORT statements at the end of these sections when you create a report using the Forms Editor's reporting facility. ENTER PURPOSE Allows the user to enter data in the current file or to edit the data in a record. SYNTAX ENTER[field]/[nexpr][, nexpr2] COMMENTS ENTER works on the current file. Used on its own, it is equivalent to the Record menu option Edit. It displays the current record and allows you to edit it field by field, starting with the first field. In effect, ENTER temporarily hands over control from DML to Superbase itself. When you press Return after the last field in a record or when you move the cursor down to the bottom of the record, control is transferred back to DML. If field or nexpr is used, Superbase restricts the editing to just one field. You can supply either a field name or a field number where the number corresponds to the field's position in the field list;i.e., if there are six fields in a record, the number for the first field is 1 and the number for the last field in 6. When you enter the record, Superbase makes the editing cursor active in the field specified and transfers control back to DML when you press Return. With the second numeric parameter, nexpr2, you can specify that a range of fields is available for editing, field or nexpr1 gives the starting point, nexpr2 gives the number of fields that can be edited - from the first field after field on nexpr1 onwards. For example, if the command was: ENTER 3, 5 you would be able to edit fields 3 to 8. You may want to specify a starting point without restricting the yourself to a given number of fields. To do this, enter 0 as the second numeric parameter; e.g.: ENTER Lastname, 3 would make the cursor active in Lastname and would allow you to edit Lastname and the next three fields. ENTER works with the current view mode or Form. Note that if you have set the Field Order on the Form, Superbase will take the first record(in the order you have specified)as the starting point for data entry and editing. When used in conjunction with BLANK, ENTER is wquivalent to the Record menu option New, and allows you to enter data into a new record. This command does not save a record;to save a new or edited record use the command STORE. EXAMPLES 1 OPEN FILE "aaa" ASK "Record to edit";x$ SELECT KEY x$ ENTER STORE 2 OPEN FILE "aaa" BLANK ENTER STORE 3 ENTER Lastname 4 ENTER 4, 2 Example 1 shows how to enter an existing record in order to edit it. Example 2 creates a new record. Example 3 restricts editing to the Lastname field. In the last example, fields 4 to 6 can be edited. EOF PURPOSE Detects the end of a database file when reading through it under program control. SYNTAX EOF(strexpr) COMMENTS strexpr should contain the name of a currently open file. If DML reaches the end of a file, EOF is set to -1 (true); otherwise it is set to 0(false). EOF is only used under program control. Supplying the empty string as an argument-EOF("")-allows you to refer to the current file without giving the file name. For example, to define a function key which was equivalent to the Fast Forward button, you would enter: WHILE NOT EOF(""):SELECT NEXT:VIEW:WEND EOF can also be used to detect the end of a text file. For this purpose it takes the string "*" as an argument, and not the file name;that is, EOF("*") is set to 'true' when the end of a text file is found. EOF is only set and unset by the SELECT record selection commands exculding SELECT KEY(which only set the FOUND function). In other words it is possible to search through a file with a filter, and set EOF to 'true' by not finding a record, and then to use the 'key-lookup'(SELECT KEY)to look for a record outside the filter. If you do this, FOUND will reflect the success of the 'key-lookup' operation, while EOF will show that you are at the end of the file. EXAMPLES 1 ? EOF(x$) OPEN FILE "aaa";SELECT FIRST: IF EOF("aaa")THEN GOTO fempty loop1:SELECT NEXT:IF EOF("aaa")THEN GOTO fend .... GOTO loop1 fempty: ? "FILE 'aaa' has no records";END fend: ? "Process completed";END ERASE PURPOSE Clears a variable assignment from memory. SYNTAX ERASE varlist COMMENTS This command clears a variable or a list of variables from memory. If several variables are to be cleared, varlist should contain a list of variable names separated by commas. If you specify the name of an array, ERASE clears all the elements in the array (it also clears any other variable with the same name as the array). EXAMPLES 1 ERASE x$ 2 ERASE a%, b%, c%, d%, a$, b$ 3 a$="Fred" a%=2.35 MEMORY ERASE a$ MEMORY NOTES The most obvious use for this command is to tidy up the variables in memory before CHAINing another program or before OUTPUT TO "aaa" MEMORY. You could then use SET "aaa" to pass some values to variables in the new program. ERR$ PURPOSE Returns the text message associated with an error number. SYNTAX ERR$(nexpr) COMMENTS This function returns a text string containing the error message associated with the error number given in nexpr. Use this function in conjunction with the control flow commands ON ERROR and RESUME, and the system variable ERRNO. EXAMPLES 1 ? ERR$(ERRNO) CLS:NUMBASE "z9999" FOR i%=1 to 130 ? "Error number";i%, " ";ERR$(i%) NEXT i% 3 x$=ERR$(14) Example 2 displays a list of error numbers with their associated error messages. ERRNO PURPOSE Returns the number of the last error that occurred. SYNTAX ERRNO COMMENTS ERRNO is used in conjunction with the error handling commands ON ERROR and RESUME and with the function ERR$ which gives the error messge associated with an error number. EXAMPLES 1 x%=ERRNO 2 ? ERR$(ERRNO) NOTES Example 2 displays the error message associated with the last error which occurred. EXECUTE PURPOSE Executes a text string as though it were a command. SYNTAX EXECUTE string COMMENTS Any set of commands, statements, and functions that can be carried out as a single program line can be placed in a string and then executed. EXAMPLES 1 EXECUTE "SELECT CURRENT:VIEW:WAIT FOR 5" y$="REQUEST ~ OK/CANCEL Requestor ~, ~~, 1" EXECUTE y$ NOTES Example 2 suggests a way of using this function to set up a user-defined dialog which can be called from different points in a program. Note the use of the tilde character to embed quotation marks in a string. EXP PURPOSE Returns the value of the mathematical constant 'e' raised to a power. SYNTAX EXP(nexpr) COMMENTS EXP gives the value of 'e' to the power of expr. nexpr has a maximum absolute value of 709.7827128934, and a range of -709.7827128934 to + 709.7827128934. This in turn gives the largest number that Superbase can hold - 1.797693134862 times 10 to the power 308. EXAMPLES 1 numfieldc=EXP(numfielda) 2 numfieldc=EXP(datefielda-datefield) 3 numfieldc > EXP(numfielda & numfield) 4 x%=EXP(y%) 5 x%=EXP(y% * numfielda * (datefielda-datefield)) 6 x%=EXP (VAL(RIGHT$(textfielda, 5))) 7 ? EXP(x%) EXPORT PURPOSE Exports data to an external text file from the current file. SYNTAX EXPORT[FILE sbfname[INDEXindex][TO]filename [WHEREconditions] [USINGparams] COMMENTS This command is the program equivalent of the EXPORT option in the PROCESS menu. It creats a text file on disk using the data from an sbf file. The only compulsory parameter is filename, which gives the name of the text file. If FILE sbfname is not specified, EXPORT takes data from the current open file. Similarly, unless INDEX indexname is given, the command exports records in the order of the current index. WHERE conditions allows you to creates a filter to determine which records are copied to the text file.conditions is set up in the same way as the command string in the Filter requestor. USING parameters allows you to change the Export/Import parameters as specified by SET-OPTIONS. These determine what characters Superbase uses to separate fields and records in the text file. You can also specify whether text fields are exported with or without quotation marks around them. USING takes three parameters, each enclosed by quotation marks and separated by commas. For example: USING "&", "$$", "0" The first two parameters specify the field separation characters and the record separation characters. As in SET-OPTIONS, you can define a separator using one character or two characters. The third parameter must be eith 0 or 1;0 for no quotation marks, 1 to include quotation marks. If you want to use a non-printing character-the carriage return character or the line feed character, for example-as a separator, you need to enter its ASCII code with the CHR$ function. For example: USING "&", CHR$(13) + CHR$(10), "0" defines the record separator as the carriage return character followed by the line feed character. EXAMPLES 1 EXPORT "aaa.exp" 2 EXPORT FILE "aaa" INDEX fielda TO "aaa.exp" WHERE (datefield) < DAYS ("29 Apr 87") 3 EXPORT FILE "aaa" TO "aaa.exp" USING "&", "##", "1" FCASE$ PURPOSE Converts the first letter of a string to upper case, leaving the rest of the string in lower case. SYNTAX FCASE$(strexpr) COMMENTS FCASE$ takes a word and makes the first letter a capital letter. Associated functions are LCASE$ and UCASE$. EXAMPLES 1 textfielda=FCASE$(textfielda) 2 x$=FCASE$(y$) 3 x$=FCASE$("ABCDEF") 4 ? FCASE$(x$) FILE PURPOSE Marks an open file the current file. SYNTAX FILE sbfnam COMMENTS When several files have been opened, you can use FILE to make one of them the current file. EXAMPLES 1 FILE "aaa" 2 x$="bbb":FILE x$ 3 a$="address":b$="bank" OPEN FILE a$:SELECT FIRST OPEN FILE b$:SELECT FIRST PAGING OFF f$=b$ lab1:VIEW:WAIT x$ IF EOF(a$) OR EOF(b$) THEN END IF f$=b$ THEN f$=a$ ELSE f$=b$ FILE f$:SELECT NEXT GOTO lab1 NOTES The third example shows how you can display records from two(or more)files at the same time. It displays one record after another, alternating between two files until it reaches the end of the shorter file. FIX PURPOSE Sets the accuracy with which DML stores a number and performs calculations on it. SYNTAX FIX(nexpr1, nexpr2) COMMENTS FIX allows you to limit a numeric expression to a specified number of decimal places. nexpr2 is the number of decimal places that nexpr1 is evaluated at. Superbase stores numeric variables at 13 figure accuracy, so the fraction 1/3 is stored as 0.3333333333333. Adding two of these together gives 0.6666666666667. If you set the numeric format to two decimal places in a file definition, Superbase would show this result as:0.33 + 0.33=0.67. This is not incorrect, especially if you are a scientist or engineer, but it is not very helpful if you are using a Query to produce an invoice. FIX(1/3, 2) stores the fraction 1/3 as 0.330000000000, so FIX(1/3, 2) + FIX(1/3, 2) gives result as 0.66. Note that numeric fields with two decimal places are automatically FIXed. EXAMPLES 1 numfieldc=FIX(numfielda, 3) 2 numfieldc=FIX(datefielda-datefieldb, 0) 3 numfieldc > FIX(numfielda * numfieldb, 4) 4 $x=FIX($y, 2) 5 $x=FIX($y * numfielda * (datefielda-datefieldb), 2) 6 $x=FIX(VAL (RIGHT$(textfielda, 5)), 2) 7 ? FIX($x) FOOTING PURPOSE Sets the Report footing for every page. SYNTAX FOOTING nexpr COMMENTS FOOTING is followed by a number of ? statements specifying the information that will appear at the bottom of every page in a report. These must be followed by an END FOOTING statement. nexpr specifies the number of lines required for the report footing. Make sure that the number of lines output by your ? statements is the same as the number specified by nexpr. EXAMPLES 1 FOOTING 1 ? "Page";PG END FOOTING NOTES This examples uses the system variable PG to print the page number. See the entry HEADING for more details. FOR TO NEXT PURPOSE Repeats a series of program statements a specified number of times. SYNTAX FOR var=nexp1 TO nexp2[STEP nexp3]statements NEXT[var][, var]... COMMENTS This command sets up a program loop in which the statements between FOR TO and NEXT are executed a given number of times, using var as a counter. nexp1 sets the initial value of the counter and nexp2 sets the final value. If STEP nexp3 is not included, the counter is increased by one every time the program executes the statements inside the loop;that is, every time it passes from FOR to NEXT. When the counter reaches the value set in nexp3, the program moves on to the next statement after NEXT. When STEP nexp3 is included, the program increases the counter by the amount specified in nexp3. var must be a numeric variable;nexp1, nexp2, nexp3 can be any numeric expression, including other numeric variables. You can use FOR TO NEXT on the same line with multiple statements, or on multiple lines. But if there is more than one statement between FOR and NEXT, it is advisable to put each on a separate line. If a number of FOR NEXT loops end at the same point, you can use a single NEXT statement for all of them. NEXT n%, y%, z% is the same as NEXT n% NEXT y% NEXT z% EXAMPLES 1 FOR i%=1 to 10:? i%, i% ^ 2:NEXT 2 weekcount%=1 FOR i%=DAYS("01/01/87")TO DAYS("31/03/87")STEP 7 FOR j%=0 to 6:k%=i% + j% ? DAY(k%);" ";MONTH$(k%), DAY$(k%) NEXT j% weekcount%=weekcount% + 1 NEXT i% Example 2 prints out the weekdays for the first quarter of 1987 in weeks. FORM PURPOSE Specifies which part of a Form is displayed in the database window. SYNTAX FORM page[, row, col] COMMENTS This command is used to select a particular page within a multi-page form or to bring part of a page that is outside the database window into view. page must be a numeric expression specifying the page number.row and col must be numeric expressions which give a row and column position within the page. Form will then move the page so that the specified position is at the top left-hand corner of the database window. EXAMPLES 1 FORM 2 Selects page 2 in the Form currently displayed. 2 FORM 1, 24, 1 Makes row 24, column 1 of page 1 appear at the top left-hand corner of the database window. FOUND PURPOSE Detects whether a key lookup has been successful or not. SYNTAX FOUND(strexpr) COMMENTS After you have issued a SELECT KEY command to search for a particular record, FOUND will tell you whether the record has been found. If the search is successful, FOUND returns a value of -1(true);if the search is unsuccessful, FOUND returns 0. strexpr should contain the file name of '.sbf' file which has already been opened. However, you can use the empty string-as in FOUND("")-to refer to the current file. FOUND is only set and cleared by the SELECT KEY and LOOKUP commands. EXAMPLES 1 SELECT KEY "London" ? FOUND("") 2 a$="Clients":SELECT KEY "Smith" FILE a$ IF FOUND(a$)THEN ? "Smith found" ELSE ? "No Smiths" FREE PURPOSE Returns the amount of free memory. SYNTAX FREE(nexpr) COMMENTS This function returns a number showing how much free memory there is. On the Amiga, nexpr determines whether the figure refers to chip, contiguous or fast memory. 0=total free memory 2=chip memory 4=fast memory Adding 2^17 to one of these parameters gives the largest block of memory in its respective memory area. So, 2^17 + 2 gives the maximum area of contiguous chip memory. EXAMPLES 1 ? FREE(0) 2 x%=FREE(i%) GET PURPOSE Gets a character from the keyboard. SYNTAX GET strvar/field COMMENTS This command reads a character from the keyboard into a string variable or a text field. It does not wait for a keystroke, and if no key is pressed it returns an empty string. If you want GET to wait until a key is pressed, you need to place it in a loop, as in: LABEL:GET A$:IF A$=: "" GOTO LABEL Alternatively, use the WAIT command. GOSUB PURPOSE Calls a procedure or subroutine. SYNTAX GOSUB label COMMENTS Like the GOTO statement, GOSUB transfers control to a different part of the program: it causes the program to branch to the label specified. But unlike GOTO, it remembers where it branched from. When the program meets a RETURN statement, it jumps back to the line following the GOSUB statement. GOSUB is used to call a subroutine;that is, one or more program lines which perform a specific task and can be called from different places within the main program. Subroutines are useful if the same task needs to be performed at several different stages in the program. Instead of repeating a group of lines, it saves space and is more convenient to put them in a subroutine. In DML, a subroutine is defined by a label at the beginning and a RETURN statement at the end. EXAMPLES 1 GOSUB sub1 2 x$=Address(1):GOSUB label1 x$=Address(2):GOSUB label1 ..... ..... ..... label1: ? "This subroutine outputs x$ to the printer" PRINT x$ DISPLAY; RETURN GOTO PURPOSE Transfers control to another part of the program. SYNTAX GOTO label COMMENTS This statement makes the program jump to the label specified, instead of continuing to the next line in the program. It alters the order in which DML executes a program. This kind of control transfer is called an uncoditional jump. For conditional jumps, see the ON GOTO and the IF THEN ELSE statement. EXAMPLES 1 GOTO fred .... .... fred:.... GROUP PURPOSE Specifies the field on which a report is grouped and the field(s) for which subtotal reporting is required. SYNTAX GROUP fieldname [, fieldname] [.....] COMMENTS Superbase insets a GROUP statement in a report program when you specify fields with the GROUP option on the Forms Editor's Report menu. GROUP has two main functions. First, it defines the field on which Superbase groups data in a report. Second, it specifies any other fields for which subtotals-or other reporting features such as MAX and MEAN-are required. If you wish to specify several levels of grouping, you should enter a separate GROUP statement for each level. GROUP can also be used in an AFTER GROUP section as a reference for the field which defines the group. Since the group has already changed, entering the field name would output the data for the next group;GROUP allows you to retrieve the data for the previous group-i.e., the group for which the AFTER GROUP section provides reporting information such as subtotals and record counts. EXAMPLES 1 GROUP City, amount 'City' is field on which the report is grouped, 'amount' is a field for which subtotals are required-the AFTER GROUP section may include the statement: SUM amount 2 GROUP Country GROUP City, amount In this example, record data is grouped at two levels:City within Country. HEADING PURPOSE Sets the Report heading for each page. SYNTAX HEADING COMMENTS Superbase generates a HEADING statement when you specify a report heading using the Heading option on the Forms Editor's Report menu. This statement marks the start of a HEADING section and is followed by one or more statements which define the heading for a report. The section must end with an END HEADING statement. If you wish to include the page number in a heading, use the system variable PG, as in: ? @32, "Page";PG PG is set to one when the Report Select command is executed and incremented by one after each page. EXAMPLES 1 HEADING ? @22;BF;U;"DEPOSITS REPORT on", TODAY, "at", NOW;ATTR OFF END HEADING HOME PURPOSE Takes the cursor to the top left-hand corner of the screen. SYNTAX HOME COMMENTS Home moves the cursor to the top of the screen without clearing the screen. The next screen output will now appear at that position. HOME is useful when you want to overwrite something you have previously displayed on screen, or when you want to move the cursor up the screen or backwards. Normally, if you attempt to do this with LOCATE or using the @ parameter with the ? command, DML displays the next page. HOME allows you to display text and numbers anywhere on screen, no matter what has been displayed previously. EXAMPLES 1 CLS FOR r%=1 to 18 FOR c%=1 to 80 HOME:LOCATE c%, r%: ? "Hello" NEXT NEXT HRS PURPOSE Extracts the number of hours from a numeric expression containing the time in thousandths of a second. SYNTAX HRS(nexpr) COMMENTS nexpr will usually be a time field or the result of a TIMEVAL expression. EXAMPLES 1 hr%=HRS(timefield) IF THEN ELSE PURPOSE Executes a statement if a condition is true. SYNTAX IF exp THEN statements[END IF][ELSE statements][END IF] COMMENTS exp can be any expression-string, numeric or logical-which is capable of being true or false. For example, A$="Smith" is either true or false, so: IF A$="Smith" THEN... is a valid statement, but IF A$ THEN... is not. If exp is true, DML executes the statement or statements after THEN. Otherwise it proceeds to the next statement after the IF THEN statement. THEN can be omitted when it is followed by GOTO. For example: IF exp GOTO label is the same as IF exp THEN GOTO label By including the ELSE option, you can instruct DML to choose between two courses of action. It executes the statements after THEN if exp is true;if exp is false, it executes the statments after ELSE. An IF THEN ELSE statement can be split up so that it is placed on several lines. If you do this, the statements after THEN must start on a new line, and ELSE must also start on a new line. For example: IF x% > y% THEN ? "Greater than" ELSE ? "Less than or equal" can be written as: IF x% > y% THEN ? "Greater than" ELSE ? "Less than or equal" END IF END IF marks the end of the IF THEN ELSE statement. It should always be used when ELSE is placed on a separate line. If it is not used, DML assumes that all the separate line statements in the rest of the program belong to ELSE. END IF is also used when the ELSE option has not been selected, but the statements following THEN are placed on separate lines. For example: IF b$="Yes" THEN n%=1:z%=2:GOSUB label can be written: IF b$="Yes" THEN n%=1 z%=2 GOSUB label END IF ..... ..... Here too, END IF is used to tell DML where the statements belonging to THEN finish. exp does not always need to contain an operator. Remember that DML assigns a value of 0 to false expressions and -1 to true expressions. With IF THEN commands, though, DML treats a numeric expression with any value other than zero as true. And it treats a numeric expression with any value other than -1 as false. IF EOF("") THEN ..... implies: IF EOF("") <> 0 THEN... Likewise, IF NOT EOF("") THEN... implies IF EOF("") <> -1 THEN EXAMPLES 1 IF exp THEN x%=x% + 1 IF exp THEN x$="TRUE" IF exp THEN x%=x% + 1:x$="TRUE" IF exp THEN labltrue IF exp THEN GOTO labltrue 2 IF exp THEN x$="TRUE" ELSE x$="FALSE" IF exp THEN x$="TRUE":x% + 1 ELSE x$="FALSE" IF exp THEN labltrue ELSE lablfalse IF exp THEN GOTO labltrue ELSE GOTO lablfalse 3 IF b$=MID$(a$, 3, 1)THEN x%=1 GOSUB label1 ELSE x%=2 GOSUB label2 END IF 4 IF a$="Y" or a$="y" THEN ? "Yes" ELSE IF a$="N" or a$'"n" THEN ? "No" ELSE ? "Other" END IF NOTES Example 4 shows how IF THEN statements can be nested. In this case, the second IF THEN statement is only executed if the condition in the first statement gives a false result. IMPORT PURPOSE Imports an external text file into an open file. SYNTAX IMPORT filename [TO FILEsbname] [WHERE conditions] [USING parameters] COMMENTS This command imports the ASCII text file specified by filename into the current file or into the file specified by sbfname. It works in the same way the IMPORT option in the PROCESS menu. IFTOFILE sbfname is not specified, the text file is imported into the current open file. If it is specified, sbfname must be an open file. WHERE conditions allows you to add a filter to the command.conditions is set up in the same way as the command string in the Filter dialog. USING parameters can be used to change the default parameters specified by SET-OPTIONS. For a description of USING and the parameters it takes, see EXPORT. EXAMPLES 1 IMPORT "aaa.exp" 2 IMPORT "aaa.exp" TO FILE "aaa" WHERE(datefield) > DAYS("29 Apr 87") INDEX PURPOSE Selects the index to be used with the current file. SYNTAX INDEX index COMMENTS Superbase automatically selects the first index as default when you open a file or when you make an open file the current file. With the INDEX command, you can select another of the file's indexes. index is the name of a field in the current file. An index for this field must already exist. Because DML parses entire lines before executing them, you cannot place an Index statement-or any other statement that refers to a field-on the same line as the OPEN FILE statement. When the DML interpreter reaches the INDEX statement, the file will not yet be open, and the field name, therefore, will not be recognized. As a result, a line like OPEN FILE "aaa":INDEX anum will produce an error message such as "Can't do this" or "Can't find this field". EXAMPLES 1 OPEN FILE "aaa" INDEX anum 2 OPEN FILE "aaa":OPEN FILE "bbb" ..... ..... FILE "aaa":INDEX anum ..... FILE "bbb":INDEX datea INPUT PURPOSE Reads characters or a line from a text file on disk into a variable or a field. SYNTAX INPUT[&nexp[, ]/LINE]var/field COMMENTS This statement inputs data from a text file on disk or from another computer using the COMMS link. It assumes that an input channel has been opened for example, by OPEN FOR INPUT. With the LINE option, INPUT reads data from the input channel until it finds a line feed character(ASCII 10)and inputs the data into var or field. If the line feed character has been used as the record separator, INPUT LINE reads a record at a time. var can be a string or numeric variable and field can be a text, numeric or date field. However, in each case the type of variable or field used should match the type of data expected. Thus if you attempt to input alphabetic characters into a numeric variable they will be valued at zero, while inputting them into a date field will produce an invalid date error. &nexp specifies the number of characters that the command takes from the text file. The comma after nexp is entirely optional. When nexp is zero or when & nexp is not used, the command reads characters from the text file until it finds a comma (ASCII 44) or a line feed character (ASCII 10). This option allows INPUT to be used instead of IMPORT to read in data from an exported file. To detect the end of a text file, use EOF("*"). EXAMPLES 1 INPUT LINE a$ 2 INPUT &6a$(or INPUT &6, a$) 3 INPUT a% 4 FILE "aaa":EXPORT TO "aaa.exp" OPEN "aaa.exp" FOR INPUT FOR i%=1 TO RECCOUNT("aaa") BLANK INPUT field1 INPUT field2 ........ INPUT lastfield STORE NEXT i%:CLOSE INPUT Example 4 demonstrates how INPUT can be used as an alternative to IMPORT. INSTR PURPOSE Returns the starting character position of a substring within a string, or returns 0 if the substring is not contained within the string. SYNTAX INSTR[nexpr, ]strexpr, substrexpr) COMMENTS This function returns the position in strexpr of the first occurrence of substrexpr. If nexpr is used, INSTR searches for the first occurrence of substrexpr from position nexpr onwards. If the substring is not found, the value returned is zero. nexpr must be positive and less than the length of strexpr. INSTR is case sensitive, i.e., "abc" and "ABC" are different. EXAMPLES 1 x%=INSTR(x$, y$) 2 x%=INSTR(textfield, "Mr") 3 x%=INSTR(x$, "Mr"):y%=INSTR(x% + 1, x$, "Mr") 4 ? LEFT$(textfield, INSTR(textfield, " ") -1) 5 x$=LCASE$(textfield):x%=INSTR(x$, "abc") IF x% > 0 THEN ? LEFT$(textfield, x% -1) NOTES The second example simply locates the title 'Mr.'. Example 3 locates any 'Mr and Mrs' or 'Mr & Mrs'. Example 4 displays the first word in textfield. Example 5 finds any occurrence of the sequence "abc" in textfield regardless of what case the letters are in. INT PURPOSE Removes the part of a number to the right of the decimal point, turning it into a whole number. SYNTAX INT(nexpr) COMMENTS INT does not round a decimal number up or down to the nearest whole number, but simply strips off the decimal part. Thus INT(123.00001) and INT(123.999999) give the same result -123.0. EXAMPLES 1 numfieldc=INT(numfielda) 2 numfieldc=INT(numfielda * (1 + numfield)/100 3 $x=INT(VAL(RIGHT$(textfield, 2))/3.33 4 $x=INT($y) 5 ? INT($x ^ Sy) KEY PURPOSE Displays the current set of function key definitions, or defines a new set. SYNTAX KEY keynum[, string] COMMENTS On the AMIGA and the Atari ST, 21 function keys are available:the keys F1 to F10, which can be used with SHIFT, and the HELP key(HELP and Shift HELP are the same). Their numbers are: F1 to F10 1-10 SHIFT(F1-F10) 11-20 HELP 0 string can be any set of Superbase commands which can be entered on one line(provided that they do not acceess a field on the same line as an OPEN FILE). The command line in string is assigned to the key specified by keynum Using KEY without a following command string clears the key associated with keynum. If keynum and string and not used, KEY displays the current set of function key definitions. EXAMPLES 1 KEY 1 2 KEY 1, "OPEN FILE ~aaa~:BLANK:ENTER:STORE:? ~ Now ~;RECCOUNT(~aaa~);~Records~" 3 KEY 4 KEY 3, "Tel. (0428) 725400 [(04203) 5601 evenings]" Example 1 clears key F1. Example 2 sets F3 to enter a record into a file and report how many records there now are. Note the use of the tilde character to insert quotation marks. Since the entire string must be enclosed in quotation marks, you cannot use quotation marks within the string. LABELS PURPOSE Prints records as labels. SYNTAX LABELS [FILE sbfname] [WHERE conditions] [USING labelparams] COMMENTS This command is the program equivalent of selecting the Labels option from the PROCESS menu. It allows you print out records as labels and to define their format. WHERE conditions limits the records for which labels are printed and acts as a filter. USING allows you to specify the shape and content of the labels to be printed. labelparams is a series of parameters separated by commas, relating to the label definition dialog. Reading down the left column of the dialog and then down the right column, they are as follows: line 1 fields/line line 2 fields/line line 3 fields/line line 4 fields/line line 5 fields/line line 6 fields/line line 7 fields/line line 8 fields/line line 9 fields/line line 10 fields/line First label margin label text width Second label margin First line next label Copies per label Labels per line Note: All 16 parameters must be used. If USING is not specified, LABELS takes the default parameters as shown in the label definition dialog(see Volume 1, Chapter 5). EXAMPLES 1 LABELS WHERE CITY="London" USING 1, 0, 2, 1, 1, 1, 1, 1, 0, 0, 1, 35, 40, 12, 1, 2 2 LABELS "Address" WHERE Lastname LIKE "[a-c}*" LCASE$ PURPOSE Converts a text string to lowercase. SYNTAX LCASE$(strexpr) COMMENTS This function changes upper case letters to lower case;no other characters, including those already in lowercase, are affected. The complementary function of LCASE$ is UCASE$. EXAMPLES 1 textfieldc=LCASE$(textfielda) 2 x$=LCASE$(y$) 3 x$=LCASE$("ABCDEF") 4 ? LCASE$(x$) LEFT$ PURPOSE Extracts one or more characters from a string, starting at the left of the string. SYNTAX LEFT$(strexpr, nexpr) 5-78 COMMENTS LEFT$ returns the leftmost nexpr characters of the string strexpr. Thus, if strexpr is DICTIONARY and expr is 7: LEFT$("DIRECTIONARY", 7) returns DICTION. EXAMPLES 1 textfieldc=LEFT$(textfielda, 10) 2 textfieldc=UCASE$(LEFT$(textfielda, 1)) + MID$(testfielda, 2) 3 LEFT$(textfielda, 1)LIKE [a-c] 4 x$=LEFT$("ABCD", 2) 5 x$=LEFT$(x$, n$) 6 ? LEFT$(x$, 10) 7 strip:IF LEFT$(x$, 1)=" " THEN x$=MID$(x$, 2):GOTO strip NOTES Example 7 is a one line program to strip leading spaces from x$(see LTRIM$). LEN PURPOSE Returns the number of characters in a text string or text field. SYNTAX LEN(strexpr) COMMENTS LEN counts the number of characters in a string, including spaces and non- printing characters. EXAMPLES 1 numfieldc=LEN(textfielda) 2 textfieldc=RIGHT$(textfielda, LEN(testfieldb) 3 LEN(textfielda) > 25 AND LEN(textfielda) 50 4 x$=LEN("A") 5 x$=LEN(x$) 6 x$=LEN(MID$(extfield, 3)) 7 ? LEN(x$) LET PURPOSE Assign a value to a variable. SYNTAX [LET] var/field=expr/[expr1 ? expra:exprb] COMMENTS The keyword LET is optional and is usually omitted. In other words, to assign a value to a variable or a field, you only need to use the equal sign. The LET option has been included in DML to maintain compatibility with earlier versions of Basic. DML also provides a more unusual facility when you use the syntax: var/field=expr1 ? expra:exprab This option provides a short way of assigning different values to a variable or field, depending on whether an expression is true or not;that is, it makes assignment conditional on the truth or falsity of a specified expression. If expr1 is true, expra is assigned to the variable or field;if it is false, exprb is assigned. It is equivalent to IF expr1 THEN var/field=expra ELSE var/field=exprab Used in this way, the question mark character is referred to as a 'ternary operator' to reflect the fact that three operands are required at the right of the equal sign. In fact, you can chain ternary operators together to create a statement which contains multiple conditions and assigns one of multiple values. Within a program, however, you will generally find it easier to use the IF THEN ELSE statement. The main application for the ternary operator is in a Superbase file definition. Here it has an important advantage over the IF THEN ELSE statement: it can be entered as a calculation formula for a field in a file definition. For a fuller discussion of the ternary operator and its applications, see Chapter 2, Volume 1. EXAMPLES 1 item$="Sprocket" 2 Textfielda="London" 3 b%=3.25 4 numfieldb=INT(277/62) The following examples assume that x$="ABC" and x%=4.5 5 y$=(x$="ABC") ? "yes":"no" This example assigns "yes" to y$. 6 y$=(x$="aaa") ? x$:"" Assigns "" to y$. 7 y$=(x% > 3.5) ? "yes": "no" Assigns "yes" to y$ 8 y$=EOF ("INPUT") ? "end of file": "more to read" LIST PURPOSE Lists a text file to the screen. SYNTAX LIST filename COMMENTS LIST is the program equivalent of the LIST option in the SYSTEM menu. It displays a text file on the screen. Do not confuse LIST with ? LIST, which displays a program listing. LIST only works with text files. Note also that unlike many other DML commands, LIST requires the file name itself plus its extension name. EXAMPLES 1 LIST "aaa.exp" 2 LIST "Address.sbd" LOAD PURPOSE Loads any of the following types of file into memory:programs, text files, function key files, Query and Update files. SYNTAX LOAD [TEXT]/[KEY]/[QUERY]/[UPDATE]filename[, APPEND] COMMENTS If none of the options TEXT, KEY, QUERY or UPDATE is used, Superbase assumes that filename refers to a '.sbp' file and attempts to load a PROGRAM file. The APPEND option can be used with program files and text files to append a file on disk to the file in memory. Note that LOAD cannot be used to load a Superbase data file(a file with an '.sbf' extension). For this you need to use the OPEN FILE command. EXAMPLES 1 LOAD "Program1" 2 LOAD TEXT "Banklet" 3 LOAD QUERY "Deptran" 4 LOAD KEY "Funkey1" 5 LOAD TEXT "Document2", APPEND LOCATE PURPOSE Sets the position at which the next output appears on the current output device(generally, the screen or the printer). SYNTAX LOCATE column[, row] COMMENTS When you are displaying something on the screen, LOCATE allows you to specify where it appears. column and row must be numeric expressions.row is optional and if it is not included, LOCATE moves the cursor to the specified column position on the current line. You cannot use LOCATE to move the cursor backwards or up the screen:it will not move the cursor to a position on the same line which is to the left of the current position;and it will not move the cursor to a line above the current position. However, you can bypass this restriction if you place the HOME statement in front of LOCATE-see HOME. EXAMPLES 1 LOCATE 12, 5:? "Hello" 2 c%=12:r%=1:LOCATE c%, r% 3 LOCATE 12:? "Hello" NOTES The first example displays the word 'hello' at the 12th column on the sixth row. Example 3 displays 'hello' at the 12th column of whatever line the cursor happens to be on. LOG PURPOSE Returns the natural logarithm(log to the base 'e')of a number. SYNTAX LOG(nexpr) COMMENTS The value of nexpr must be positive. Negative numbers or zero produce the error message 'Invalid numeric parameter'. EXAMPLES 1 numfieldc=LOG(numfielda) 2 numfieldc=LOG(datefielda-datefieldb) 3 numfieldc > LOG(numfielda * numfieldb) 4 x%=LOG(y%) 5 x%=LOG(y% * numfielda * (datefielda-datefieldb)) LOOKUP PURPOSE Detects whether an expression occurs in a file in a specified field. SYNTAX LOOKUP(expr, field.file) COMMENTS This function checks whether a given field in a file contains the expression in expr. That is, it answers the question:does expr exist in field.file? If it finds the expression, LOOKUP returns the value -1(true);otherwise it returns the value 0 (false). expr and field.file must be of the same type(i.e. text or numeric). field.file must be the name of an indexed field in an open file. LOOKUP plays a major role in cross-file validation and calculation. The file specified with LOOKUP can be any open file;so you can use this function to perform a relational lookup, where it checks whether the contents of a field in one file match the contents of a field in another file. If LOOKUP is successful-if it finds the expression you have specified-the record containing the expression becomes the current record, even though the file may not be the current file and is not displayed on screen. At the same time, the FOUND function is set to -1 to reflect the fact that the search has been successful. For a fuller explanation of LOOKUP, see Chapter 2, Volume 1. EXAMPLES 1 OPEN FILE "aaa":OPEN FILE "bbb" SELECT FIRST WHILE NOT EOF("bbb") IF LOOKUP(field1.bbb, field1.aaa)THEN GOSUB Process_module WEND ? "Process completed":END Process_module: ...... ...... RETURN This example demonstrates a small program to process only those records in file 'bbb' that have a matching record in file 'aaa'. File 'bbb' could be an invoice file 'joined' to a customer file 'aaa' by a customer code(field1 in 'bbb' and 'aaa'). LTRIM$ PURPOSE Trims leading spaces from a text expression or a text field. SYNTAX LTRIM$(strexpr) COMMENTS LTRIM$ returns a string consisting of the original string specified by strexpr with any leading spaces removed. EXAMPLES 1 textfieldc=LTRIM$(textfielda) 2 x$=LTRIM$(textfieldc.filea) 3 ? LEN(x$);LEN(LTRIM$(x$)) MAKE PURPOSE Stores the file definition for a file it has been defined by CREATE and ADD. SYNTAX MAKE sbfname COMMENTS This command is used as the last step in the process of creating a new file. After the file has been defined by CREATE and ADD, MAKE writes the new file definition to disk together with any indexes that have created. Note that a file definition is not regarded as valid until the MAKE command has been executed. Before then, any error will have the effect of removing the file definition. EXAMPLES 1 CREATE "Address" ADD "Firstname;TXT REQ;20;1, 2" ADD "Lastname;TXT REQ IXD;20;1, 33" ADD "Street";TXT;25;3, 2" (other field definitions) ........ ........ MAKE "Address" MENU PURPOSE Sets up a user-define menu SYNTAX MENU column, item, state[, strexpr] COMMENTS Superbase let you define up to 10 menu each of which can have a maximum of 12 items. With the Menu command you supply the text for a single item and specify whether it will appear on the menu an enabled, disabled(ghosted)or with a check mark against it. Having defined a menu with a series of MENU commands-one for each menu item and one for the menu title-you can then use the MENU ON command to turn the menu(or menus)on. You also use MENU to specify a numeric variable which will return a value showing which item, if any, has been selected. column must be a numeric expression with a value in the range 1 to 10 giving the column number for the menu. To set up a menu in the first column on the left at the same position as the Superbase Project menu, you would enter a value of one. item must be a numeric expression with a value in the range 0 to 12, giving the number of the menu item. Item 0 is the menu heading, the text that appears on the menu bar. state can take a value of 0, 1 or 2.0 disables the item so that it appears on the menu as a ghosted option.1 enables it, 2 places a check mark against it. strexpr supplies the text for the item. For example, if you wished to define a menu in the first column which contained the option Deposits, you could enter: MENU 1, 3, 1, "Deposits" This would make Deposits the third item in the menu list. To disable the Deposits option, you would enter: MENU 1, 3, 0 Note that you do not need to specify the text a second time. EXAMPLES 1 MENU 1, 0, 1, "Transactions" MENU 1, 1, 1, "Deposits" MENU 1, 2, 1, "Withdrawal" MENU 1, 3, 1, "Direct debit" MENU 1, 4, 1, "Standing orders" MENU 1, 5, 1, "Credit card" MENU ON a%, b% NOTES This example defines a menu in the first column with five options(items), all of them enabled.(The heading for the menu is Transactions.) MENU ON then turns the menu on. When the user selects an item, Superbase will place its column and item numbers in the variables a% and b%. MENU CLEAR PURPOSE Turns off all user-defined menus and clears their definitions from memory. SYNTAX MEMORY CLEAR COMMENTS If you want to define a new set of menus, you can use this command to clear any menus which have been defined previously. You may also use it when your menus are no longer required, in order to make the memory space they occupy available for other purposes. MENU ON PURPOSE Turns user-defined menus on and specifies the variables which return the result of a menu selection. SYNTAX MENU ON nvar1, nvar2 COMMENTS MENU ON turns on any menus which have been defined with the MENU command and sets nvar1 and nvar2 to zero. When the user selects an item, Superbase places the column number in nvar1 and places the item number in nvar2. It also turns all the user-defined menus off. For example, if the second item in the third user-defined menu has been selected, the first numeric variable specified with MENU ON, will contain the value 3 and the second numeric variable will contain the value 2. You may sometimes want to turn the menus off without waiting for an item to be selected. You can do this with the command MENU OFF. EXAMPLES 1 menuloop: MENU ON a%, b% ON a% GOSUB sub1, sub2, sub3, sub4, sub5 GOTO menuloop NOTES This examples presumes that five menus have been defined and that sub1 to sub5 are subroutines which handle item selection for each menu. MERGE PURPOSE Loads a text file and performs a mail merge. SYNTAX MERGE [TEXT filename] [WHERE conditions] COMMENTS This command merges the data in an '.sbf' file with a form letter in the Text Editor and outputs the results to the printer. It takes data from the current open file and-if WHERE is not included-prints one letter for each record in the file. You can use WHERE to set up a filter restricting the merge operation to only those records which match the conditions specified. The TEXT option lets you specify a text file on disk; Superbase will then load the file into the Text Editor before starting the merge operation. Although Merge is the program equivalent of the Mail Merge option on the Process menu, it does not allow you to preview letters on screen before printing them. To do this, use ? TEXT with the MERGE parameter. EXAMPLES 1 OPEN FILE "Address" MERGE TEXT "Mailshot1" WHERE Country LIKE "USA" MID$ PURPOSE Returns one or more characters from within a text string or text field. SYNTAX MID$(strexpr, nexpr1[, nexpr2]) COMMENTS MID$ is more flexible than LEFT$ and RIGHT$ as it can extract characters from any point in a string.strexpr holds the string, and nexpr1 gives the starting point in the string.nexpr2 specifies the length of the substring to be extracted; if nexpr2 is not given, MID$ takes all the characters from the starting point to the end. EXAMPLES 1 textfieldc=MID$(textfielda, 10, 10) 2 textfieldc=LCASE$(MID$(textfielda, 8)) 3 MID$(textfielda, 12, 1)LIKE[a-c] 4 x$-MID$(textfieldc, 19, 2) 5 x$=(x$, 4) 6 ? MID$(x$, 4, 2) 7 ASK;A$: I%=LEN(A$) FOR n%=I% TO 1 STEP -1 B$=B$ + MID$(A$, n%, 1) NEXT ? B$ NOTES Example 7 inputs a word into A$ and turns it back to front. MINS PURPOSE Extracts the number of minutes from a numeric value which holds the time in thousandths of a second. SYNTAX MINS(nexpr) COMMENTS Usually, nexpr will be a timefield or the result of a TIMEVAL calculation. EXAMPLES 1 mnts%=MINS(timefield) 2 ? MINS(NOW - start%);"minutes have elapsed" MOD PURPOSE Gives the remainder of a numeric expression after it has been divided. SYNTAX nexpr1 MOD nexpr2 COMMENTS nexpr1 is the number to be divided, nexpr2 is the number that divides into it (the divisor). MOD returns the remainder when nexpr1 has been divided by nexpr2. For example: 14 MOD 3 gives 2 as a result. It is equivalent to: 14-INT(14/3) * 3 EXAMPLES 1 ?(2.53 * 100) MOD 100 NOTES The example line strips off the integer part of a number and displays the first two figures after the decimal place. MODIFY PURPOSE Modifies a field definition. SYNTAX MODIFY field[, ] [field definition string] [, formula] [, formula] COMMENTS MODIFY is the program equivalent of the EDIT FILE option in PROJECT. It allows you to alter a field's parameters;for example, the field name or its length. The field definition and formula strings take the same form as they do with the ADD command. EXAMPLES 1 MODIFY Forename "Firstname;TXT REQ IXU;15 U;1, 12" MONTH$ PURPOSE Takes a julian date number and returns the month of the year as a text string. SYNTAX MONTH$(nexpr) COMMENTS The same limitations on which julian dates are acceptable apply to this function as they do to other date functions. The format of the text string is the full month name regardless of what current date format is - i.e., January, not Jan). Associated date functions are DAY DAYS DAY$ MONTH MONTH$ YEAR. EXAMPLES 1 textfieldc=MONTHS$(datefielda) 2 textfieldc=MONTH$(datefielda + 90) 3 textfieldc=MONTH$(TODAY) 4 x$=MONTH$(datefielda + VAL(textfielda)) 5 x$=MONTH$(DAYS ("11 Jan 85") 6 ? MONTH$(datefielda + 30) NEW PURPOSE Clears the program area or text area. SYNTAX NEW [TEXT/QUERY/UPDATE] COMMENTS On its own, NEW erases any program that is currently in the computer's memory. When followed by TEXT, it clears the current text editor area of memory. Following it by or QUERY or UPDATE, clears their respective dialogs. Unlike the menu options Program New(and Text New)this command does not put you into the program(or text)editor. NEWLINE PURPOSE Sends a new line character(or characters)to an output device. SYNTAX NEWLINE[nexp] COMMENTS This command prints a new line at the current output device;i.e. with the screen display, it takes the cursor onto the start of the next line.nexp can be used to specify more than one new line. If nexp is not an integer, only the integer part will be taken. EXAMPLES 1 NEWLINE 2 2 FOR i%=1 to 20 ? i%:if i% MOD 5=0 THEN NEWLINE i%/5 NEXT i% NOTES Example 2 outputs the numbers 1 to 5 with single line spacing, 6 to 10 with double spacing, and so on up to 20. NOW PURPOSE Gives the system time. SYNTAX NOW COMMENTS NOW shows the time of day in hours and minutes, using the current time format. If you have a real-time clock in your computer or you have set the system time, this will be the current time. Note that NOW actually holds the time in thousandths of a second. When you display the time, Superbase automatically translates it into hours and minutes. EXAMPLES 1 ? NOW 2 ? MINS(NOW) 3 timefield=NOW NUMBASE PURPOSE Sets the numeric format in which numbers are displayed. SYNTAX NUMBASE string COMMENTS NUMBASE is the program equivalent of the Number Format option in the SET menu. string must be one of Superbase's valid numeric formats, as listed Chapter 2, Volume 1. For example, "z99999.00" or "z(+$, 000000.00". EXAMPLES 1 NUMBASE "z99999." Integer only format. 2 NUMBASE "+*****.00" Numbers displayed with a sign and leading cheque-protect. ON ERROR PURPOSE Tells DML to branch to another part of the program when an error occurs. SYNTAX ON ERROR [[GOTO]label] COMMENTS Normally, DML halts program execution and displays an error message when it detects an error. ON ERROR enables error trapping, and prevents the program from halting. Once an error has been detected, it causes the program to jump to the error handling routine specified with label. You can use ERRNO in your error handling routine to check on which error has occurred, and take appropriate action. In many cases, you will want the program to resume execution after detecting an error. You can do this with the RESUME statement. To disable error trapping, use ON ERROR without a following label. EXAMPLES 1 ON ERROR GOTO check ...... ...... ...... check:IF ERRNO 11 THEN RESUME ELSE? "Are you sure you want to exit from this program?" ? "Press Y to exit, any another key to resume" WAIT a$ IF a$="Y" OR a$="y" THEN END ELSE RESUME ENDIF NOTES In this example, ON ERROR is used to check whether the Stop button has been clicked on or CTRL C has been pressed. Both these events generate error number 11, so the error handling routine(which starts at label 'check')first tests for this error number. If it finds that another error event has occurred, program execution is resumed at the line which caused the error. The error handling routine then asks if the user wishes to exit or not. Depending on the answer it receives, it either resumes execution at the line which caused the error (the line being executed when the user pressed STOP or CTRL C)or terminates the program. ON GOSUB PURPOSE Calls one of a number of subroutines from a list of subroutines. SYNTAX ON nexp GOSUB label1 [, label2, label3, ...] COMMENTS This statement transfers program control to one of the subroutines given in the list. The value of nexp determines which subroutine the program jumps to. If nexp has valued at 1 the program branches to the subroutine at the first label, if nexp has a value of 2, it branches to the subroutine at the second label, and so on. Once the program has branched to a subroutine, it executes each statement in turn until it meets a RETURN statement. Then it jumps back to the line following the ON GOSUB statement. Any label can be repeated. If nexp is 0 or greater than the number of supplied labels, program control drops to the next statement after the ON GOSUB statement. EXAMPLES 1 ON x% GOSUB lab1, lab2, lab3 2 ON x% GOSUB lab1, lab2, lab1, lab2, lab1 ON GOTO PURPOSE Branches to one of a list of labels. SYNTAX ON nexp GOTO label [, label, ....] COMMENTS This command transfers program control to one of the program lines given in the list. The value of nexp determines which label the program jumps to. If nexp has valued at 1 the program branches to the first label, if nexp has a value of 2, it branches to the second label, and so on. For a general description of GOTO refer to GOTO itself. nexp should be a positive integer. If it is not an integer, the whole number part will be taken. Any label can be repeated. If nexp is 0 or greater than the number of supplied labels, program control drops to the next statement after ON GOTO. EXAMPLES 1 ON x% GOTO lab1, lab2, lab3 2 ON x% GOTO lab1, lab2, lab1, lab2, lab1 ? "Reached here only when x% is 0 or greater than 5 OPEN PURPOSE Opens a text file on disk or Comms channel for input/output. SYNTAX OPEN filename FOR[INPUT/OUTPUT/APPEND] COMMENTS When used for output to a file, OPEN has the same effect as OUTPUT TO file. There is only one channel for INPUT, and one for OUTPUT, so you cannot have two output channels, or two input channels. However, you can have one of each open at the same time. APPEND is an output channel and specifies that file is to be appended to. You must not try to specify OPEN "aaa" FOR OUTPUT APPEND. If using OPEN, file is overwritten without warning. If using APPEND, file need not exist. If using INPUT, file must exist. EXAMPLES 1 OPEN "aaa" FOR OUTPUT 2 OPEN "aaa" FOR APPEND 3 OPEN "bbb" FOR INPUT:OPEN "aaa" APPEND lab1:INPUT LINE a$:? a$ IF NOT EOF ("*")THEN GOTO lab1 CLOSE INPUT:CLOSE OUTPUT NOTES Example 3 appends the contents of file 'bbb' to file 'aaa'. Notice that the last line of the program CLOSEs the files that OPEN has opened. This practise is strongly recommended:you should always close a file when you have finished writing to it. OPEN FORM PURPOSE Loads a form from disk and displays it in the database window. SYNTAX OPEN FORM form COMMENTS form must be a string expression giving the file name of a form. Superbase will also open any database files associated with the form. EXAMPLES 1 OPEN FORM "Invoice" OPEN FIELDS PURPOSE Specifies which fields are displayed. SYNTAX OPEN FIELDS [FILE sbfname] fieldlist COMMENTS This command is the program equivalent of the Open Fields option on the Project Menu. fieldlist consists of the list of fields required to be open. To remove any restrictions on which fields are shown, use the CLOSE FIELDS command. EXAMPLES 1 OPEN FIELDS FILE "Address" Firstname, Lastname, Country, City OPEN FILE PURPOSE Opens a database file and its default index. SYNTAX OPEN FILE sbfname [;password] COMMENTS Note the distinction between OPEN FILE "aaa" which opens a database file, and OPEN "aaa"(FOR INPUT)which opens a text file. sbfname is compulsory, and if a password is required to access the file, then it is also compulsory (use a semicolon to separate the filename from the password). INDEX followed by a field name may be added to the end of an OPEN FILE command, allowing you to select an index other than the default index. But it can only be used if the file has already been opened by a direct command or an earlier program line. As explained in the entry for the INDEX command, DML parses the whole line before executing it;so if you refer to a field, it must be a field in a file that already been opened. Otherwise an error will result. EXAMPLES 1 OPEN FILE "aaa" 2 x$="bbb":OPEN FILE x$ 3 OPEN FILE "aaa";"John" NOTES In example 3, 'John' is the password for the file 'aaa'. ORDER PURPOSE Sets the order for Query output. SYNTAX ORDER [&nexpr]field[ASCENDING/DESCENDING] [, field] ASCENDING/DESCENDING] [, .....] COMMENTS ORDER is a Query Language command and can only be entered in a query section -i.e., it works in conjunction with the Query Language command Select. This command is the program equivalent of the Order command line in the query definition dialog: it takes the same syntax and serves the same purpose. The field specified with the ORDER command determines the order in which the field in the SELECT line are output. If you are familiar with the concept of sorting, you can think of ORDER as setting the sort 'key' for query output. field must be a field in an open file, but it does not need to be an indexed field; nor does it have to be one of the fields in the SELECT line. ASCENDING and DESCENDING allow you to specify whether data is sorted in ascending or descending order. If you specify a text field with the ORDER command - i.e., if you specify it as the sort key-Supervase outputs record data according to the alphabetical order of the sort field. DESCENDING reverses the order and sorts the field from Z to A. With numeric, date and time fields, ASCENDING sorts data in numeric, date or time order; and DESCENDING reverses the order. By default, fields are sorted in ascending order;so it not strickly necessary to include the ASCENDING parameter. You can also specify more than one field in the ORDER line, separating each with a comma. If enter two fields, the first field takes precedence as a sort key over the second field; i.e., records are first sorted according to the first field, and then any duplicate data items are sorted according to the second key. The same applies if there are more than two fields:the second key has priority over the third, the third has over the fourth, and so on. EXAMPLES The examples illustrate how ORDER works by taking a limited set of records and showing some of the different ways in which they may be sorted. Each record contains data from three fields, Firstname, Lastname, and Country. 1 SELECT Firstname, Lastname, Country ORDER Lastname This examples takes Lastname as the sort key and produces the following output: FIRSTNAME LASTNAME COUNTRY Pierre Arnauld France William Carter USA Gerde Hemrich West Germany John Miles England Anne Richardson USA Peter Smith England Robert Brown England 2 SELECT Firstname, Lastname, Country ORDER Country The output from this query would be as follows: FIRSTNAME LASTNAME COUNTRY Robert Brown England John Miles England Peter Smith England Pierre Arnauld France William Carter USA Anne Richardson USA Gerde Hemrich West Germany 5-107 3 SELECT Firstname, Lastname ORDER Country DESCENDING, Lastname ASCENDING The output from this query is: FIRSTNAME LASTNAME Gerde Hemrich William Carter Anne Richardson Pierre Arnauld Robert Brown John Miles Peter Smith 4 SELECT Firstname, Lastname, Country ORDER Country, Firstname This example uses Country as the primary sort key and Firstname as the secondary key to produce the following output: FIRSTNAME LASTNAME COUNTRY John Miles England Peter Smith England Robert Brown England Pierre Arnauld France Anne Richardson USA William Carter USA Gerde Hemrich West Germany NOTES The default length for sorting is 15 characters per field. Superbase gives equal weighting to upper case, lower case and accented instances of characters. The & character followed by a value up to the length of the field may precede any field, specifying the number of characters that will be used in sorting. OUTPUT TO PURPOSE Opens a text file on disk for output. SYNTAX OUTPUT TO filename COMMENTS This command makes the disk the current output device and sends any future output to filename. It has the same effect as OPEN filename FOR OUTPUT. If the text file already exists on disk, any output command issued after OUTPUT TO, will overwrite the file. If you want to add data to an existing text file, use OPEN filename FOR APPEND. EXAMPLES 1 OUTPUT TO "Names" ? Lastname CLOSE OUTPUT 2 OUTPUT TO a$ NOTES Example 1 stores the contents of the Lastname field(in the current record)on disk in the text file Names. PASSWORD PURPOSE Sets new password(or none)for a specified file. SYNTAX PASSWORD sbfname [;passwords] COMMENTS sbfname must be an open file and, as usual with filenames, must be included in quotation marks. If no password is given, the existing password for the specified file is removed. EXAMPLES 1 OPEN FILE "aaa;John" PASSWORD "aaa" Removes passwords. 2 PASSWORD "aaa;Rosebud" Sets a password for the file 'aaa'. 3 OPEN FILE "aaa;John" PASSWORD "aaa;John;Paul;George" Adds passwords for read/write and read only access privileges. PCOL PURPOSE Return the column position of the print head on the current output printer or resets the print head's position. SYNTAX PCOL(nexpr) COMMENTS If nexpr is zero, the function returns the column position of the print head on the current printer. For the Row position, see PROW. See also LOCATE. You can also use this function to set the counter Superbase uses to keep track of the print head's position. Giving nexpr a positive value, sets the counter to that value. The print head itself is not moved. This feature is used to reset the internal count after issuing a series of printer commands which have not in fact moved the print head, for example, after switching to high density graphics mode. EXAMPLES 1 x%=PCOL(0) 2 ? PCOL(0) POSITION PURPOSE Sets the data pointer to a new position in an ASCII file. SYNTAX POSITION nexp COMMENTS When you read data from an ASCII file on disk, Superbase uses an internal pointer to keep track of it. The OPEN file FOR INPUT command sets the pointer to zero, the position of the first character in the file. Thereafter it is incremented by one for each character that is input using the INPUT command. POSITION sets the pointer to the character position specified by nexpr. Normally, the data in an ASCII file is read into the computer sequentially. With Position, you can input character data on a more selective basis. You will only be able to take advantage of this command if you know where the data is stored in a file. Superbase stores data in variable length fields(as opposed to fixed length fields):when you create an ASCII file from an '.sbf' file by exporting it, the amount of space occupied on disk by field data may vary from record to record. This means that there is no simple way of knowing the position of any particular field or record. One solution to this problem is to create an ASCII file from a database file using the query option Output to Disk. When you do this, Superbase stores the data in fixed length fields-each field takes the length set in the file definition. You can then work out the number of characters occupied by a record in the ASCII and use this figure to retrieve specific records or fields. For example, if the record length was 49 characters, you would enter: POSITION 49 * 5 + 1:INPUT LINE a$ to retrieve the fifth record in the file(you need to add one because the first character position is zero). EXAMPLES 1 OPEN "Cust.asc" FOR INPUT FOR n%=0 to 76 * 12 STEP 77 POSITION n% INPUT & 15, a$ ? a$ NEXT CLOSE INPUT NOTES This example inputs the first field from the first twelve records in the ASCII file Cust.asc. It assumes that the record length is 77 characters and that the length of the first field is 15 characters. PRINT PURPOSE Sends information to the printer. SYNTAX PRINT[expressionlist] COMMENT PRINT, followed by a semicolon and nothing else, selects the printer as the current output device. The ? command can then be used to send information to the printer. You can also use PRINT to output information directly to the printer, by following the command with one or more expressions. But note that any use of PRINT makes the printer the current output device. The items in the expression list following the Print command may be separated by a semicolon or a comma. If a semicolon is used, Superbase will print the expressions one after the another without any spaces in between; a comma has the effect of inserting a space between items. In some circumstances, you may also dispense with separators altogether. Thus, provided it can distinguish between different items, Superbase will accept a list of expressions which are entered on the line head to tail; for example: PRINT a$b$c%"Hello" EXAMPLES 1 PRINT; ? MEMORY DISPLAY; 2 PRINT BF "The items in the following list will be printed in bold face" PRINT "One", "Two", "Three";CHR$(12) DISPLAY; NOTES The first example prints the current program's variables and their contents. Example 2 prints a list of items, and then sends the form feed character - CHR$(12)-to the printer. Both examples use the DISPLAY command to make the screen the current output device after the print operation is finished. PROTECT PURPOSE Saves the current program in an encrypted form. SYNTAX PROTECT filename COMMENTS Use this command to ensure that program files are not seen by anyone else. It stores a file on disk in an encrypted(scrambled)form so that it can be run but not edited. If the first line of a program is a REM statement, PROTECT displays that line, but hides the rest of the program from any attempt to edit or LIST it. EXAMPLES 1 PROTECT "myprog" PROW PURPOSE Returns the row position of the print head on the current output printer. SYNTAX PROW(nexpr) COMMENTS If nexpr is zero, the function returns the row position of the print head on the current printer. For the Column position, see PCOL. See also LOCATE. Giving nexpr a positive value resets Superbase's internal row counter. See PCOL. EXAMPLES 1 x%=PROW(0) 2 ? PROW(0) QUIT PURPOSE Exits from Superbase. SYNTAX QUIT COMMENTS This has same effect as selecting the Quit option from the Project menu. It exits from Superbase and returns the user to the desktop interface. READ PURPOSE Reads the data given in a DATA statement and assigns it to a variable or field. SYNTAX READ var/field[, var/field] [, .....] COMMENT The types of variables or fields used with a READ command must match the types of data expected-numeric variables or numeric fields for numeric data and string variables or string fields for string data. DML uses a pointer to keep track of where it is in the list of DATA items; that is, each time a data item is read, DML moves the pointer on to the next item in the list. If you wish to read the same data again, you can place a label in front of a DATA statement and use RESTORE. EXAMPLES 1 READ a%, b$, fielda.filea, fielda.fileb RECCOUNT PURPOSE Counts the number of records in a file. SYNTAX RECCOUNT(sbfname) COMMENTS This function returns a number showing how many records there are in the file specified. You can use the empty string as an argument-RECCOUNT("")-to refer to the current file. EXAMPLES 1 ? RECCOUNT("Orders") 5-116 2 x%=RECCOUNT(x$) 3 OPEN FILE("address") SELECT FIRST FOR n%=1 to RECCOUNT("address") VIEW SELECT NEXT NEXT n% NOTES Example 3 displays all the records in the file "address" in turn. REM PURPOSE Inserts a non-executable comment(a remark)into a program. SYNTAX REM[text] COMMENTS REM has the effect of cancelling any statements after it. This makes it useful when you are testing a program-placing it at the start of a multi-statement line puts the following statements temporarily out of action. More generally, use REM to annotate a program in order to explain how it works or what it does. A single quotation mark after a command without an intervening colon also acts as a REM statement. EXAMPLES 1 REM this is a remark 2 ....:FILE "aaa" open aaa 3 ....:FILE "aaa":REM open aaa 4 FILE "aaa":REM eliminate next commands:INDEX abc:SELECT FIRST NOTES Examples 2 and 3 have identical effects and demonstrate the two different ways of entering a comment. In example 4, the REM statement means that the INDEX and SELECT FIRST commands are not executed. REMOVE FILE PURPOSE Removes a database file from disk, along with its associated definition and index files. SYNTAX REMOVE sbfname COMMENT This command operates in the same way as the Remove File menu option. Note that you are not asked for confirmation-the file is just removed. EXAMPLES 1 REMOVE FILE "aaa" 2 REMOVE FILE "DF1:aaa" 3 REMOVE FILE "GEM\SBASE\aaa" REMOVE FROM PURPOSE Removes records which match the conditions specified. SYNTAX REMOVE FROM FILE sbfname[WHERE conditions] COMMENTS This command works in the same way as the equivalent PROJECT-REMOVE-FILE menu option. It deletes records from a file on disk. FILE sbfname has to be open, and if the file requires a password, you must have full access to it. WHERE conditions is optional and is set up in the same way as a filter. If it is not included, the command acts on all the records in a file. EXAMPLES 1 REMOVE FROM FILE "aaa" WHERE Lastname LIKE "[a-c]*" 2 REMOVE FROM FILE "aaa" This empties the file of all its data. REMOVE INDEX PURPOSE Removes an index on the current file from disk. SYNTAX REMOVE INDEX index COMMENT This command works in the same way as the Remove Index option on the Project menu. The file must be open, and, if it requires a password, you must have full access privileges. index is the name of an indexed field. It can be entered with a file extention. EXAMPLES 1 REMOVE fielda 2 REMOVE fieldb.aaa RENAME PURPOSE Renames a file on disk. SYNTAX RENAME old.filename[, /TO]new.filename COMMENT This command works in the same way as the RENAME command in MS DOS or Amiga DOS, but allows you to rename a file without exiting from Superbase. You have the option of using either a comma or the keyword TO as the separator between the two file names. EXAMPLES 1 RENAME "aaa", "bbb" 2 RENAME "aaa" TO "bbb" REORGANIZE PURPOSE Reorganizes the current file or a specified file. SYNTAX REORGANIZE [FILE sbfname] [TO]sbfnameb COMMENTS This command is the program equivalent of the Reorganize option on the System menu(see Chapter 8, Volume 1). It takes a file on disk, reorganizes it, and stores it as sbfnameb. IF the FILE option is not used, the current file is reorganized. sbfnameb can include the pathname for another directory or disk. If you enter a pathname without a file name following it, the file will be reorganized under the same name. Note that you cannot reorganize a file under the same name in the same directory;i.e. if a pathname is not supplied, sbfnameb must not be the same as sbfnamea. EXAMPLES 1 FILE "aaa":REORGANIZE TO "copy" 2 REORGANIZE "aaa" TO "a:mydir\" 3 REORGANIZE "aaa" TO "DF1:Mydir/" Example 1 creates a reorganized file 'copy' in the current directory, Example 2 creates a reorganized file 'aaa' in directory mydir on the disk in drive a (or, in example 3, drive DF1 on the Amiga). REPLICATE PURPOSE Replicates a character a given number of times. SYNTAX REPLICATE(strexp, nexp) COMMENTS REPLICATE repeats the character in strexpr the number of times given in nexp. EXAMPLES 1 textfieldc=REPLICATE("*", 10) 2 x$=REPLICATE(textfieldc, 4) 3 x$=REPLICATE(MID$(x$, 4, 2), 6) 4 x$=REPLICATE (" ", 25) NOTES Example 4 fills x$ with 25 spaces, but see function SPACE$. REPORT PURPOSE Specifies the field or fields on which totals(and other report statistics) will be produced for the report as a whole. SYNTAX REPORT [SUMMARIZE] [params]fieldname[, fieldname][, ....] COMMENT Report has two uses. When you create a Report with the Forms Editor, Superbase generates a Report statement by noting the fields which have been specified in an AFTER REPORT section;i.e., if the AFTER REPORT section in a Report program contains the statements: ? SUM amount ? COUNT deposits Superbase will generate the following line in the program: REPORT amount, deposits If you are writing a Report program yourself (as opposed to modifying a program generated by Superbase), you should remember to enter a Report statement including the names of any fields for which you wish totals and other report statistics to appear. The second application for REPORT is a query language command. In this context, it allows you to create a program line which is equivalent to the REPORT command line in the query definition dialog. REPORT is used here to specify the fields for which totals and other statistical. When you use the SUMMARIZE option, Superbase suppresses the main detail of the report and prints just the summary information. REQUEST PURPOSE Displays a Superbase dialog. SYNTAX REQUEST text1, text2, type[, nvar[, strvar[, len]]] COMMENT REQUEST allows you to select one of Superbase's dialogs and display it on screen. To some extent you can also customise a dialog to your own requirements. Thus you can place a title in box, and you can specify the text string that initially appears in the dialog's command line or selection box. For certain dialogs, it also possible to specify the length of the box. text 1 and text2 are the first and second line of the dialog title. They must be included although they can be "". The maximum length for each line is 50 characters. type is the dialog type. It defines the type of dialog according to the table shown below. nvar is a numeric variable. It returns a value of 1 if OK is selected and there is an entry into the string dialog. If CANCEL is selected or there is no entry into the string dialog, it returns 0. strvar can be used with dialogs which have a string entry box and has two functions: It is used to place a default value into the string box, i.e., the text string in strvar is entered into the string box when the dialog is displayed. It returns the string which the user enters in the box. len specifies the length of the string box(where appropriate). This is particularly useful for the information dialogs. For dialog types 5-16 it is not need as Superbase sets the box to the maximum file name length of 50 characters. For dialog type 4 len must be specified. Types of Dialogs available: TYPE DIALOG BUTTONS 0 string OK 1 string OK CANCEL 2 string OK 3 string OK CANCEL 4 string OK CLEAR CANCEL 5 Database Files OK CLEAR CANCEL 6 Open Fields List OK CLEAR CANCEL 7 Indexed fields OK CLEAR CANCEL 8 Non indexed fields OK CLEAR CANCEL 9 Field Info OK CLEAR CANCEL 10 Open Database Files OK CLEAR CANCEL 11 Database Files OK CLEAR CANCEL 12 Program Files OK CLEAR CANCEL 13 Text Files OK CLEAR CANCEL 14 Query Files OK CLEAR CANCEL 15 Update Files OK CLEAR CANCEL 16 Function Key Files OK CLEAR CANCEL 17 Directory listing OK CLEAR CANCEL 18 Subdirectory List OK CLEAR CANCEL Note that a database file must be open before dialogs 5 to 9 can be selected. EXAMPLES 1 REQUEST "", "", 2, 2 a%=0:a$="":REM initialize nvar and strvar REQUEST "Select a program", "", 5, a%, a$, 32 IF a%=0 THEN ? "OK so you do not want to run a program":END CHAIN a$ 3 a%=0:a$=":OPEN FILE "aaa" REQUEST "Select an Index", "", 7, a%, a$ IF a%=0 THEN END INDEX a$ lablook:a$="":REQUEST "Enter a key", "", 1, a%, a$, 15 IF a%=0 THEN END SELECT KEY a$ IF FOUND ("aaa") THEN GOTO lablook2 REQUEST "No Record with key" + a$, "See Nearest ?", 1a% IF a%=0 THEN GOTO lablook lablook2:VIEW:WAIT FOR 5:GOTO lablook NOTES Example 1 puts an "OK" dialog up for 2 seconds. Example 2 allows the user to select a program to run. Example 3 in essence duplicates the key lookup function from the ? button on the Superbase Control Panel. Note the concatenation of the first title line of the dialog on the third from last line. RESTORE PURPOSE Moves the data pointer back to the first DATA statement, or to a specified label. SYNTAX RESTORE[label] COMMENTS The data pointer is the internal pointer that Superbase uses to keep track of which DATA statements have been read. Initially it has a value of zero and points to the first DATA statement. As you READ data into variables or fields, the data pointer is increased by one for every data item read. This command resets the data pointer. If you do not specify label, the data pointer is reset to the beginning of the first DATA statement. If you specify label, the data pointer is reset to the data statement following the label. EXAMPLES 1 RESTORE 2 RESTORE datalabel1 RESUME PURPOSE Resumes execution after an error. SYNTAX RESUME[NEXT/label] COMMENTS The RESUME command works in conjunction with the ON ERROR GOTO command which is used to trap program errors. RESUME, on its own, returns program control to the statement that caused the error. When NEXT is included, the statement returns program control to the statement after the one which caused the error. label transfers program control to the label specified. EXAMPLES 1 REM Top of program ON ERROR GOTO errlab1 SELECT FIRST:? fieldname ..... ..... errlab1:IF ERRNO=44 THEN OPEN FILE "aaa":REM file not open RESUME 2 REM read data ON ERROR GOTO errlab2 ..... READ x$ ..... endread:..... ..... ..... errlab2:IF ERRNO=18 THEN RESUME endread:REM out of data RETURN PURPOSE Returns from a subroutine. SYNTAX RETURN COMMENTS The RETURN command is used to mark the end of a subroutine. It instructs the computer to transfer prgram control to the statement immediately following the GOSUB or ON GOSUB statement which initially called the subroutine. See GOSUB. RIGHT$ PURPOSE Extracts one or more characters from a text string or text field, starting from the right-hand end of the string. SYNTAX RIGHT$(strexpr, nexpr) COMMENTS This function starts at the right of a string given in strexpr and extracts nexpr characters. EXAMPLES 1 textfieldc=RIGHT$(textfielda, 10) 2 textfieldc=LCASE$(RIGHT$(textfielda, 1)) 3 IF RIGHT$(textfielda, 1)="s" THEN.... 4 x$=RIGHT$("ABCD", 2) 5 x$=RIGHT$(x$, 4) RND PURPOSE Returns a random number. SYNTAX RND(nexpr) COMMENTS What the function returns depends on the value of nexpr. It nexpr is less than zero, the random number generator is reseeded. This means that a new series of random numbers will be generated, completely unrelated to the last series. It also allows you to generate the same series again for testing purposes, by entering the same seed. If nexpr is zero, the number returned is the same as the previous one. If nexpr is positive, a new random number is generated. The random number returned is in the range 0 to 1. Technically, it is never zero and never unity, but all values between 0 and one will be randomly generated and the distribution of numbers will be relatively flat. EXAMPLES 1 numfieldc=RND(numfielda) 2 numfieldc=RND(2) * 12 3 textfieldc=MID$(x$, RND(2) * 6 + 1, RND(2) * 12 + 1) 4 $x=RND($y) 5 ? RND($x) ROW PURPOSE Returns the row position of the cursor on the screen. SYNTAX ROW(0) COMMENTS This function shows how far down the screen the cursor is. For the column position, see COL. EXAMPLES 1 x%=ROW(0) 2 ? ROW(0) NOTES In practise, example 2 would be pointless, because it changes the position of the cursor in the course of printing it. RUN PURPOSE Executes a program from memory, or loads it from disk and then runs it. SYNTAX RUN[filename] COMMENTS This will run the program currently in memory when used as a command or as a program statement without the filename option. If filename is used to specify a program, Superbase loads the program from disk and then runs it. If filename is specified, it must be a string variable or a string constant in quotation marks. SAVE PURPOSE Saves any of the following types of file:program, text, function key, query, and update files. SYNTAX SAVE [TEXT/KEY/QUERY/UPDATE]filename[, TEXT] COMMENTS filename is required. Superbase detects files of different types as follows: aaa.sbk is a saved function key set aaa.sbp is a saved program aaa.sbq is a saved query aaa.sbt is a saved document(text) aaa.sbu is a saved update If none of the options TEXT, KEY, QUERY or UPDATE is used, Superbase assumes that filename refers to an '.sbp' file and attempt to save a program file. If you include TEXT as the last parameter, DML saves a program file as a text file. Only one of the options, TEXT, KEY, QUERY or UPDATE, can be used at a time. SAVE FILE PURPOSE Saves the current file definition. SYNTAX SAVE FILE sbfname COMMENTS When you create a new file, you can use MAKE to save the file definition. SAVE FILE, however, must be used after you have edited a file definition with MODIFY. SAY PURPOSE Converts a text string into speech, using the Amiga's speech synthesis facility. SYNTAX SAY [USING parameters]exprlist COMMENTS SAY is only available on the Amiga. The parameters for the USING option are in this order: Pitch, Inflection, Rate(wpm), Sex, Phonemic The following table gives the range of each parameter and its default value: PARAMETER RANGE DEFAULT NOTES Pitch 65-320 110 Inflection 0-1 0 0 is expressive, 1 is monotone Rate in wpm 40-400 150 Sex 0-10 0 0 is male, 1 is female Phonemic 0-1 0 0 translates to phonemes, 1 assumes phonemes SAY only works with string expressions. To hear an external sound field use the SHOW command. EXAMPLES 1 OPEN FILE "Address" SELECT FIRST WHILE NOT EOF("Address") SAY Forename;Lastname;"comes from";City;Country SELECT NEXT WEND 2 SAY USING 280, 1, 200, 1, 0"Hello there", USING 140, 1, 200, 0, 0 "Well, hello there" SCRDUMP PURPOSE Outputs a copy of the screen to the printer-carries out a screen dump. SYNTAX SCRDUMP COMMENTS Only available on the Amiga. SECS PURPOSE Returns the numbers of seconds from a time field. SYNTAX SECS(nexpr) COMMENTS nexpr will usually contain a time in milliseconds(thousandths of a second) from a time field or from the result of a TIMEVAL calculation. EXAMPLES 1 scnds%=SECS(timefield) 2 scnds%=SECS(TIMEVAL("10:22AM")) SELECT COMMANDS The following SELECT commands relate to Record selection: SELECT CURRENT SELECT DUPLICATE SELECT FIRST SELECT KEY SELECT LAST SELECT NEXT SELECT PREVIOUS SELECT REMOVE SELECT WHERE SELECT commands can only be used on an open database file, although this does not have to be the current file. These commands do not display records on screen. To do this, you need to use VIEW. Similarly, although they can be used with any open file, the SELECT commands do not automatically make an open file the current file. For example, SELECT LAST selects the last record in a file(on index)even if the file is not current. If the file is current, executing the VIEW command will be enough to display the last record. But with any other open file, you will also need to use the FILE command(as opposed to the FILE parameter)before you can display the record(FILE makes an open file the current file). SELECT CURRENT PURPOSE Selects the current record. SYNTAX SELECT CURRENT [FILE sbfname] [INDEX index] COMMENT This command has the same effect as the Current Record button on the Control Panel at the bottom of the screen. Use INDEX to select the current record using a different index. SELECT DUPLICATE PURPOSE Selects the next record with the same key. SYNTAX SELECT DUPLICATE [INDEX index] COMMENTS This command finds the next record with the same key as the current key. The key is the field on which the file is currently indexed. If SELECT DUPLICATE fails to find a record with the same key, the EOF function is set to true. 1 SELECT FIRST:VIEW:x%=1 lab1:SELECT DUPLICATE IF NOT EOF("aaa")THEN VIEW:x%=x% + 1:GOTO lab1 ? "End of ";x%; "duplicates-strike key" lab2:SELECT PREVIOUS:SELECT NEXT:IF EOF("aaa")THEN END CLS:VIEW:GOTO lab1 Example 1 displays duplicate entries on an index. In Table view, it shows a set of records at a time. SELECT FIRST PURPOSE Selects the first record in the current or specified index sequence. SYNTAX SELECT[FILE sbfname] [INDEX index] COMMENTS This command has the same effect as the First Record button on the Control Panel. Use the INDEX parameter to alter the current index. EXAMPLES 1 SELECT FIRST 2 SELECT FIRST "Stock" INDEX Prodcode NOTES Example 1 selects the first record in the current file according to the current index. Example 2 selects the first record in the Stock file according to the Procode index. SELECT KEY PURPOSE Selects the first record with matching string. SYNTAX SELECT KEY string [FILE sbfname] [INDEX index] COMMENTS This command has the same effect as the Key Lookup button on the Control Panel. It searches the file for the first record whose index field matches the string specified. Unlike the other SELECT commands, this command does not affect the EOF function, but instead sets the FOUND Function(see the example given for FOUND). EXAMPLES 1 SELECT KEY "Zollinger" VIEW 2 SELECT KEY "Johnson" FILE "Customer" INDEX Lastname IF FOUND("Customer")THEN FILE "Customer":VIEW NOTES Example 1 selects the record in the current file whose Lastname field contains the name Zollinger. It assumes that the current file is indexed on Lastname. The program in example 2 selects the record in the Customer file whose Lastname field contains the name Johnson. The Customer file must have already been opened, but it does not have to be the current file. If the program finds a record with a matching key, it uses the FILE command to make the Customer file current and then displays the record. SELECT LAST PURPOSE Selects the last record in the current or specified index sequence. SYNTAX SELECT [FILE sbfname] [INDEX index] COMMENTS Has the same effect as the Last Record button on the Control Panel. SELECT NEXT PURPOSE Selects the next record in the current or specified index sequence. SYNTAX SELECT NEXT [FILE sbfname] [INDEX index] COMMENT Has the same effect as the Next Record button on the Control Panel. SELECT PREVIOUS PURPOSE Selects the previous record in the current or specified index sequence. SYNTAX [FILE sbfname] [INDEX index] COMMENTS This command has the same effect as the Previous button on the Control Panel. SELECT REMOVE PURPOSE Removes the current record in the current file or another open file. SYNTAX SELECT [FILE sbfname] COMMENTS This command has the same effect as the Remove option on the Record menu. SELECT WHERE PURPOSE Selects first record that matches the filter conditions or removes the filter. SYNTAX SELECT WHERE[[FILE sbfname] [conditions]] COMMENTS This command has the same effect as the Filter button on the Control Panel. conditions is set up in the same way as the string gadget in the Filter requestor. If not specified, the current filter conditions are cleared. SELECT WHERE can only be used to set a single file filter. If you enter the name of a field which also occurs in another open file, you should include the file the file name as an extension. Otherwise, Superbase may assume you are attempting to use this command in a multi-file operation, and will issue the error message: Can't do this This Where statement must be single file If you wish to set a multi-file filter - to select records whose field data matches the data in another file - use the LOOKUP function or the query language command WHERE. EXAMPLE 1 SELECT WHERE fielda LIKE "[a-c]" 2 SELECT WHERE "Stock" fieldb LIKE "[a-c]" 3 SELECT WHERE NOTES Once set, the Control Panel filters remains active until it is cleared. Example 3 clears the filter which may have been set by a previous SELECT WHERE command or by direct entry in the filter dialog. QUERY LANGUAGE COMMANDS DML's Query Language commans allow you to create a program which duplicates a Superbase query. These commands are used in report programs created by the Forms Editor; but they can also be used for any of the query applications described in Chapter 11, Volume 1 - sorting records, creating complex multi-file filters, merging files, and so on. In Superbase a query is defined by the four command lines in the query definition dialog(Chapter 5, Volume 1, introduces this dialog;Chapter 11 explains it in more detail). These command lines can be reproduced in a program by using the query language commands. SELECT is used to define the Fields command line; REPORT defines the Report command line;WHERE corresponds to the FILTER line; and ORDER is used for the Order line. You will find a explanation of these commands under their respective keyword entries. Here, we will describe how they work together to form a query section. A query section must start with the SELECT command and it should end with END SELECT. Any other query language commands are optional;you will include them according to your requirements. Thus, if you wish to use a filter, you will include a WHERE command within the query section. Likewise, if you wish to use reporting functions such as SUM and COUNT, you will need to insert a REPORT command after the SELECT command and before END SELECT. You can think of REPORT, WHERE and ORDER as modifying the query output which is specified with the SELECT command. When SELECT is used on its own - to form a single line query section - it outputs data from each record in a specified file(or files)in turn. For example: SELECT Lastname.Address, Country.Address: END SELECT This outputs a line showing the contents of the fields Lastname and Country for each of the records in the Address file. As such, SELECT works in the same way as the ? command except that it acts on all the records in a file. If you inserted TO PRINTER after Country.Address in the example above, SELECT would output data to the printer. The TO device parameter provides an equivalent to the Output options in the query definition dialog. You can use to specify an output device other than the screen:the printer, an ASCII file, or a new '.sbf' file. A QUERY LANGUAGE EXAMPLE Any query created with the query definition dialog can be reproduced under program control. We can illustrate this by converting a query file(an '.sbq' file)into a program, taking the Deptran file supplied with the demonstration file disk as an example. Deptran can be displayed on screen using the LIST option from the System menu. It looks like this: SB CLIENTS DEPOSITS Deposit Transaction Report ON "Clients" Firstname.Clients, Lastname.Clients, ON "Deposits" @24 Bank, Amount, Deposits REPORT SUM Amount COUNT GROUP Lastname.Clients SUM Amount Lastname.Clients=Lastname.Deposits Lastname.Clients SB on the first line indicates that this is a Superbase Professional query file as opposed to one created in Superbase Personal. The next two lines contain the names of the database files which are associated with this query. 'Deposit Transaction Report' is the query title, and the remaining lines represent the four query command lines. Before we can load this file into the Program Editor, we need to change its name to Deptran.sbp. To do this, select COPY from the System menu and, after selecting Deptran.sbq as the file to be copied, enter then name Deptran.sbp. You can now load the file into the Program Editor using the Program open option. Coverting it to a program is just a matter of deleting two lines and inserting keywords in the others. Once you have made these changes, the program should look like this: OPEN FILES "CLIENTS" OPEN FILE "DEPOSITS" SELECT ON "Clients" Firstname.Clients, Lastname.Clients, ON "Deposits" @24 Bank, Amount, Deposits REPORT SUM Amount COUNT GROUP Lastname.Clients SUM Amount WHERE Lastname.Clients=Lastname.Deposits ORDER Lastname.Clients Note that the report line is the same as in the query file and does not need to be altered. If you now run this program, it will have the same effect as running Deptran from the query definition dialog(by clicking on OK). SELECT PURPOSE Specifies which are to be output from a query. SYNTAX SELECT [params]firlds[TO device]:[statements]:END SELECT COMMENTS SELECT is a Query Language command and can used on its own or with other Query Language commands to form a query section. fields can be one or more field names from one or multiple files.params can be any of the output format parameters as listed in the section which describes the ? commands. In addition, there are three format parameters which can only be used with the SELECT command:ON file, AS heading and FIELD. The syntax and function of these parameters in described in their respective sections in Chapter 11, Volume 1. TO device specifies the device to which the query output will be sent. If it is not included output is to the screen. The device options are: TO PRINTER Outputs to the printer. TO FILE file Creates a new '.sbf' file on disk under the file name specified, using the query output. TO file Outputs to the ASCII file on disk specified by file. statements can be other query language statements formed with the commands REPORT, WHERE, and ORDER. END SELECT is used to indicate the end of a query section. It is not always necessary to include END SELECT, but you must provide Superbase with some indication of where the query section finishes and where the rest of the program starts. Otherwise, the statements following the last line in the query section will be interpreted as part of a multi-line SELECT statement. As an alternative to END SELECT, you could use a blank line. SER PURPOSE Returns the total number of records that have been created in a file. SYNTAX SER(filename) COMMENTS You can use the SER function to assign a serial number to each record in a file. To do this, you need to define a field which will hold the serial number. It should be defined as a constant field and should have SER("filename")as its constant formula. When you create the first record, it will be given the value 1. This value will then be incremented by one for each record you add to the file. The difference between SER and RECCOUNT is that SER gives the total number of records that have been created, irrespective of whether they have been deleted later. RECCOUNT returns the number of records currently in the file. 1 ? SER("Stock") 2 BLANK Recno.Stock=SER("STOCK") Price.Stock=14.95 Description.Stock="Widget" STORE SET PURPOSE Reads a text file and executes any commands in the file, or assigns variables from a text file. SYNTAX SET filename COMMENTS This command reads in a text file and executes it as if it were a sequence of command. The file, therefore, must contain valid DML commands. If the file holds a set of variables-which have previously been saved to disk by ? MEMORY-the variable assignments are executed. This provides a way of transferring variables between different programs when CHAIN is not appropriate. For example, Program 'a' can set up variables for Program 'c', but Program 'a' CHAINs to Program 'b'. Another application would be to communicate variables between different programs which are run on different days. EXAMPLES 1 ...... process a ...... OPEN "aaa" FOR OUTPUT:? MEMORY:CLOSE OUTPUT:DISPLAY another program SET "aaa" ...... process b 2 SET "abc" 'abc' could be ASCII file which contains a set of function key assignments. SET BUFFERS PURPOSE Sets the number of buffers Superbase uses as a disk cache. SYNTAX SET BUFFERS nexp COMMENTS Operates in the same way as the Buffers option in Set Menu Options, and allocates 512 bytes memory space for each buffer. nexp can have a value from 1 to 99. EXAMPLES 1 SET BUFFERS 24 SET PAGING PURPOSE Sets paging on or off. SYNTAX SET PAGING[ON/OFF] COMMENTS When used without ON/OFF, it acts as toggle and operates in the same way as the SET-PAGING menu options. With ON or OFF, it sets paging accordingly. EXAMPLES 1 SET PAGING OFF SET VIEW MODE PURPOSE Sets the view mode or switches between one of the view modes and a Form. SYNTAX SET [TABLE]/[FORM]/[RECORD] COMMENTS Works in the same way as the equivalent Set Menu option, except that it does not automatically display a record(use VIEW). If a Form(as opposed to Form view)is displayed, the SET command switches the Form off and selects the specified view mode. The Form remains in memory and can be switched on again by repeating the SET command for the same view mode. In other words, when a Form has been opened, the SET command toggles the current view mode on and off. EXAMPLES 1 SET FORM 2 SET TABLE:VIEW SGN PURPOSE Finds the sign of a number. SYNTAX SGN(nexpr) COMMENTS This function returns the positive value of 1 if nexpr is positive and returns the negative value -1 if nexpr is negative. EXAMPLES 1 numfieldc=SGN(numfielda) 2 IF SGN(datefielda-datefieldb)THEN GOTO lab1 3 x%=SGN(y%) 4 x%=SGN(y% * numfielda * (datefielda-datefieldb)) 5 x%=SGN(VAL(RIGHT$(textfielda, 5))) 6 ? SGN(x%) NOTES Example 2 tests whether datefieldb is later than datefielda SHOW PURPOSE Shows an external file. SYNTAX SHOW [field]/[strexpr] COMMENTS SHOW is the program equivalent of the camera button at the bottom of the screen. It displays a picture or text from an external file.field must be a field which holds the name of the external file, but it does not have to be a field in the current file:if you add a file name extension to the field name, you can display pictures using other open database files. As an alternative to specifying an external field, strexpr allows you to specify the name of an external file. When field or strexpr is not given, SHOW removes the picture from the screen. SIN PURPOSE Returns the sine of an angle measured in radians. SYNTAX SIN(nexpr) COMMENTS This function returns the sine of the angle in nexpr, where the angle is measured in radians. To convert degrees to radians, multiply by 180/PI. EXAMPLES 1 numfieldc=SIN(numfielda) 2 x%=SIN(y%) 3 x%=SIN(VAL(x$)) 4 ? SIN(x%) SPACE$ PURPOSE Fills a string with a specified number of spaces. SYNTAX SPACE$(nexpr) COMMENTS nexpr must be in the range 0 to 255. EXAMPLES 1 textfieldc=SPACE$(10) 2 x$=SPACE$(4) SQR PURPOSE Returns the square root of a number SYNTAX SQR(nexpr) COMMENTS The function returns the square root of the number specified by nexpr. If nexpr is less than zero, the function returns the error message 'ivalid number'. EXAMPLES 1 numfieldc=SQR(numfielda) 2 numfieldc=SQR(2 * numfirlda) 3 textfieldc=STR$(SQR(VAL(x$))) 4 x%=SQR(y%) STORE PURPOSE Stores the current record in the current file or in the file specified. SYNTAX STORE[, 0/1/2] [FILE sbfname] COMMENTS This command stores the record in memory for the current file, or for the file specified with sbfname. It is equivalent to the Save option on the Record menu. The numeric parameters - 0, 1 or 2 - allow you to specify whether the record is stored in batch mode or in the normal way(see the section on Batch in Chapter 5, Volume 1). STORE, 1 stores the current record in batch mode. The time taken to save the record on disk will be reduced, but the data will not yet be secure:if you suffer a power loss, you will lose any record data which has been saved(in the current session)using this option. Note that STORE, 1 only turns on batch mode for the current record.STORE, 2 does not store a record but makes the file secure. Any records that have been saved previously with the STORE, 1 command will now be made safe on disk. You should always execute a STORE, 2 command after storing records in batch mode. STORE, 0 is optional and is the same as STORE on its own:Superbase makes each record secure as it is stored. If you were to turn the computer off accidentally, the most you would lose would be the data in memory. EXAMPLES 1 BLANK Firstname="John" Lastname="Roberts" Street="15 Richmond Way" ...... ...... ...... STORE 2 FOR n%=1 to 10 BLANK Firstname=Recdata$(n%, 1) Lastname=Recadata$(n%, 2) Street=Recdata$(n%, 3) ...... ...... ...... STORE, 1 NEXT STORE, 2 NOTES The first example creates a new record and stores it in the normal way. Example 2 creates ten new records, reading data into the fields for each record from the array Recdata$ and storing them in batch mode. When all the records have been stored, it makes the file secure with the STORE, 2 command. STR$ PURPOSE Returns the text equivalent of a numeric expression. SYNTAX STR$(nexpr [[, nexpri [, nexprd]]/[, numeric-format-string]]) COMMENTS STR$ converts data which is held in a numeric variable or numeric field into a text string. nexpri specifies the number of integers before the decimal point and should be set large enough to avoid overflow display. nexprd specifies the number of integers after the decimal point. The maximum numeric format in Superbase is a total of 13 integers, so nexpri plus nexprd must be less than 14. As an alternative to using nexpri and nexprd, you can specify the numeric format as a string(see NUMBASE). If these parameters are not used, the default numeric format set by Numeric Format on the Set menu or by the most recent use of NUMBASE will be taken. The complementary function to STR$ is VAL. EXAMPLES 1 textfieldc=STR$(numfielda) 2 textfieldc-STR$(numfielda, 5, 0) 3 x$=STR$(165.4444, "z999999.00") TAN PURPOSE Returns the tangent of an angle measured in radians. SYNTAX TAN(nexpr) COMMENTS The function returns the tangent of the angle in nexpr measured in radians. The complementary function of TAN is ATN. EXAMPLES 1 numfieldc=TAN(numfielda) 2 x%=TAN(y%) 3 x%=TAN(VAL(x$)) 4 ? TAN(x%) THOUSECS PURPOSE Takes a numeric value and returns the number of thousandths of a second left over after subtracting the number of seconds. SYNTAX THOUSECS(nexpr) COMMENTS nexpr will usually contain a time in milliseconds from a time field or the result of a TIMEVAL calculation. THOUSECS returns the same result as nexpr MOD 1000. 1 x%=THOUSECS(timefield) TIME$ PURPOSE Returns the time in string format from a numeric value which gives the time in thousandths of a second. SYNTAX TIME$(nexpr [, timeformat]) COMMENTS The second argument for this function, timeformat, allows you to specify the format the time string will have. It must conform to the rules for Superbase time formats given in the keyword entry for DATEBASE. EXAMPLES 1 x$=TIME$(timefield) 2 ? TIME$(NOW, "hh:mm:ssam") TIMEVAL PURPOSE Returns the value of a time string in thousandths of a second. SYNTAX TIMEVAL(strexpr) COMMENTS strexpr must contain the time in a valid time format. See the keyword entry for DATEBASE for a list of acceptable time formats. EXAMPLES 1 t%=TIMEVAL("10:22am") 2 t%=TIMEVAL("14:03:12.201") TODAY PURPOSE Gives the system date. SYNTAX TODAY COMMENTS TODAY shows the date in the date format as set with Date Format option in the Set menu, or as set by the DATEBASE command. If your computer has a real-time clock or you have set the systeme date, TODAY gives the current date. Otherwise, it gives the default system date. TODAY holds the date as a julian date number. Superbase automatically translates this into the current date format when you display the date using ? TODAY. EXAMPLES 1 ? TODAY 2 datefield=TODAY 3 ? MONTH(TODAY) TRIM$ PURPOSE Trims trailing spaces from a string or a text field. SYNTAX TRIM$(strexpr) COMMENTS This returns the string consisting of the original string specified by strexpr with any trailing spaces eliminated. EXAMPLES 1 stringfieldc=TRIM$(textfielda) 2 x$=TRIM$(textfieldc.filea) 3 ? LEN(x$);LEN(TRIM$(x$) UCASE$ PURPOSE Returns the upper case equivalent of a text string or a text field. SYNTAX UCASE$(strexpr) COMMENTS UCASE$ returns the upper case equivalent of the lowercase alphabet;no other characters, including those already in upper case, are affected. The complementary function of UCASE$ is UCASE$. EXAMPLES 1 textfieldc=UCASE$(textfielda) 2 x$=UCASE$(y$) 3 x$=UCASE$("ABCDEF") NOTES If you wish to set the first letter of a string to upper case, leaving the rest in lower case, you can so using the FCASE$ function. UPDATE PURPOSE Performs a relational update. SYNTAX UPDATE[calclist] [WHERE conditions] [END UPDATE] COMMENTS UPDATE on its own runs the update in memory. This may have been loaded from disk with the LOAD UPDATE command, or it may have been created in the same session using the Process menu option Update Edit. By specifying calclist and conditions, you can also use UPDATE to define an update and then run it. calclist corresponds to command line set in the Update Fields dialog; conditions corresponds to the filter which is set in the Update Filter dialog. The first specifies how the records are updated, the second specifies which records are to be updated. WHERE conditions and calclist should be entered as separate statements, either on the same line as UPDATE separated by colons, or on separate lines. They form part of an Update program section, headed by the UPDATE command and ending with END UPDATE. The END UPDATE command must be included if the Update section is followed by other statements in a program. Otherwise Superbase will regard these as belonging to the Update section. As an alternative to using this command, you can terminate the section with a colon or a blank line. UPDATE is a multi-file command, so both conditions and calclist can refer to more than one file. In this case, the first condition in the update filter must establish a join between two files. 5-155 EXAMPLES 1 LOAD UPDATE "Newrate":UPDATE Loads the Update file Newrate from disk, and then runs it. 2 UPDATE Price.Orders=Price.Stock WHERE Product_Code.Orders=Product_Code.Stock AND Order_date "15 July 1987" END UPDATE Updates prices in the Orders file on the basis of the price details in the Stock file. VAL PURPOSE Returns the numeric value of a text string. SYNTAX VAL(strexpr) COMMENTS The function returns the numeric value of the number(if any)in the lefthand end of the string or substring specified in strexpr. In cases where strexpr does not contain a number or where the leftmost character of strexpr is not numeric, the function returns 0. The complementary function of VAL is STR$ EXAMPLES 1 numfieldc=VAL(textfielda) 2 numfieldc=VAL(RIGHT$(textfielda, 8)) 3 VAL(textfielda) > 1 AND VAL(RIGHT$(textfielda, 4) > 0 4 x%=VAL("12.45A456") 5 x%=VAL(x$) VIEW PURPOSE Displays the current record in the current file. SYNTAX VIEW COMMENTS Allows the user to see the current record in the current file in the view format specified by the SET view mode command. It can also be used to redisplay the current Form. WAIT PURPOSE Waits for a specified time or until a key is pressed. SYNTAX WAIT [FOR time]/[FOR nexp] [var/field] COMMENTS Wait waits for a given number of seconds(FOR nexp)or until a given time(FOR time). FOR nexp implies 'wait for nexp seconds'. FOR time implies 'eait until the system clock reached time', where the time is given in the current time format. FOR var/field implies 'wait until a key is pressed, and then place it in var or field'. If you follow WAIT with a numeric variable or numeric field, it will only accept a number. In other word, pressing any key except the keys with the digits 0 to 9, will have no effect. EXAMPLES 1 WAIT FOR 3 Waits for 3 seconds. 2 WAIT FOR 10:20:30 Wait until 10:20 am. 3 WAIT x$ Waits for a single key stroke and puts it in x$. WHERE PURPOSE Set the filter conditions for a query or a report. SYNTAX WHERE conditions COMMENTS WHERE is the program equivalent of the Filter command line in a query definition, and can only be used within a section that is headed by the query SELECT command. You can use WHERE to set a filter on the fields selected for report output or for other query applications, such as sorting, merging files, or simply retrieving data with query that has been saved to disk. conditions takes the same form as the Filter command line in the query definition dialog(see Chapter 11, Volume 1). WHERE is a multi-file filter command - unlike the record selection command SELECT WHERE - and if it used for this purpose, the join between two files must be placed at the beginning of the statement, as in: WHERE Lastname.Clients=Lastname.Deposits Any subsidiary conditions can then be added to the line using the AND operator. EXAMPLES 1 SELECT Firstname.Clients, Lastname.Clients, Bank, Amount WHERE Lastname.Clients=Lastname.Deposits AND Lastname.Clients LIKE "[d-3]*" ORDER Lastname.Clients END SELECT 2 WHERE Price > = 50 AND Price < = 100 3 WHERE Lastname LIKE ["a-c"*] AND NOT (Country=USA) NOTES In the first exampe, WHERE is used to set up a multi-file filter. It selects only those clients whose details are also stored in the Deposits file and whose last name initial falls in the range A to C. Note that file extension must be given for Lastname since the field occurs in both the Clients file and the Deposits file; the Bank and Amount fields do not require an extension name since they only occur in the Deposits file. The other two examples show WHERE in use as a single file filter command. WHILE WEND PURPOSE Executes a series of instructions as long as the specified conditions are true. SYNTAX WHILE exp statements WEND COMMENTS WHILE and WEND set up a loop, in which the statement in between are executed repeatedly for as long as the expression following WHILE is true. When the expression is not true, execution resumes with the first statement after WEND. EXAMPLES 1 OPEN FILE "Address" SELECT FIRST WHILE NOT EOF("Address") VIEW SELECT NEXT WEND 2 WHILE NOT EOF(*"):INPUT &1, a$:? a$:WEND YEAR PURPOSE Returns a numeric value for the year from a julian date number. SYNTAX YEAR(nexp) COMMENTS The function is only valid for dates from 1 January 1 to the end of December 9999. Consequently nexpr is only valid in the range 1 to 3652048. If nexpr is 0 then the number returned is 0. If nexpr is negative the results are unpredictable. Associated date functions are DATE$ DAY DAYS DAY$ MONTH EXAMPLES 1 numfieldc=YEAR(datefielda) 2 numfieldc=YEAR(datefielda + 90) 3 numfieldc=YEAR(TODAY) 4 x%=YEAR(datefielda + VAL(textfielda)) 5 x%=YEAR(DAYS("11 Jan 85") 6 ? YEAR(datefielda + 30) 7 YEAR(datefielda)=1986 NOTES Example 3 provides a calculation to insert the month number of the system date into a numeric field. Example 7 provides a filter to pick out all the dates in datefields which fall in the year 1986. CHAPTER 6 - QUICK REFERENCE GUIDE APPLICATION FUNCTIONS RUN [filename] Execute program, optionally loading from disk CHAIN filename Execute program without clearing variables NEW [TEXT/QUERY/UPDATE] Clear program or text area EDIT [TEXT/KEY/QUERY/UPDATE] Allow user to edit program, text, query or update LOAD [TEXT/KEY/QUERY/UPDATE] filename [, APPEND] Load program, text, file, function key list, query or update SAVE [TEXT/KEY/QUERY/UPDATE] filename [, TEXT] Save program, text file, function key list, query or update PROTECT [filename] Save the current program in encrypted form CALL function Call a user supplied function SYSTEM COMMANDS DEBUG [ON/OFF] Set or clear debug flag BREAK [ON/OFF] Set or clear user stop enabled QUIT Exit Superbase system KEY keynum [, string] Set keynum to string or clear it LIST filename List any system file to screen DELETE filename Delete any system file RENAME old filename [, TO] new filename COPY from filename [, TO] to filename Copy any system file NUMBASE string Set default numeric format DATEBASE string Set default date format DIRECTORY path Change directory to path SET TABLE/RECORD/FORM Set view according to parameter SET PAGING [ON/OFF] Set paging SET BUFFERS nexp Set number of cache buffers to use BASIC STATEMENTS [LET] var/field=exp Assign value of expression to variable or field ERASE varlist Remove a variable from memory CLEAR Clear all system variables READ var/field [, var/field] Read data into variables or fields from data pointer DATA constant [, constant]... Specify data for READ statement RESTORE [label] Move data pointer to specified position or home REM text Non executable comment line EXECUTE string Execute text string as though command DIM array variable Set array dimensions CONTROL FLOW FOR var=nexp TO nexp [STEP nexp]statements NEXT [var] Repeat program lines a number of times GOSUB label Call a procedure or subroutine GOTO label Call a procedure or subroutine GOTO label Branch to the specified label ON ERROR [GOTO label] Specify procedure to be followed on error condition ON nexp GOTO label [, label]... Branch to statement or label in list ON nexp GOSUB label [, label]... Call procedure or subroutine in list RETURN Return from procedure or subroutine execution RESUME [NEXT / label] Resuume execution after error at next or specified position END Terminate execution of application WHILE expr Perform following commands if expression true WEND Mark end of while command sequence CONDITIONALS IF exp THEN statement/label [ELSE statement/label] Conditional statement or expression execution varfield=exp ? expr:expr Conditional assignment of value to field or variable FILE AND INDEX COMMANDS CREATE sbfname;passwords Create a new database file in memory CREATE INDEX ON exp [FILE sbfname] [TO index] [UNIQUE] Create a new index file optionally make unique ADD [FILE sbfname] field definition string [, formula string] Add a new field to a file MAKE sbfname Make the file exist on disk and store the file def MODIFY field [, ] field definition string [, formula string] Modify parameters for field changing name, type etc. SAVE FILE sbfname Save the current file definition PASSWORD sbfname;passwords Set new passwords for a specified file REORGANIZE [FILE sbfname] [TO] pathname Reorganize current or specified file to new pathname OPEN FILE sbfname;passwords Open file set as default CLOSE [ALL]/[FILE sbfname] Close all or specified files FILE sbfname Select the default file to be used INDEX index Select the default index to be used for a file REMOVE FILE sbfname Remove all data, file and all indices REMOVE INDEX index Remove the specified index for specified file OPEN FIELDS [FILE sbfname] fieldlist Open a set of fields for specified file CLOSE FIELDS [FILE sbfname] Close the open fields for specified file RECORD COMMANDS BLANK [FILE sbfname] Clear all data from current record STORE [0/1/2, ] [FILE sbfname] Store current record in the file, batch mode optional. ENTER [field/nexpr] [, nexpr2] Allow the user to enter a record in the current file VIEW View record in the current file SELECT Record selection commands SELECT FIRST [FILE sbfname] [INDEX index] Select the first record in key sequence SELECT LAST [FILE sbfname] [INDEX index] Select the last record in key sequence SELECT NEXT [FILE sbfname] [INDEX index] Select the next record in key sequence SELECT PREVIOUS [FILE sbfname] [INDEX index] Select the previous record in key sequence SELECT CURRENT [FILE sbfname] [INDEX index] Select the current record in key sequence SELECT DUPLICATE [FILE sbfname] [INDEX index] Select the next record with the same key SELECT REMOVE [FILE sbfname] Remove the current record in selected file SELECT KEY string [FILE sbfname] [INDEX index] Select the first record with index matching string SELECT WHERE [FILE sbfname] [conditions] Select the first record matching conditions or clear conditions SELECT field parms [WHERE parms] [REPORT parms] [ORDER parms] [SAY]/[TO PRINTER/filename/FILE sbfname] [END SELECT] Query language command PROCESS COMMANDS UPDATE calc list [WHERE conditions] [END UPDATE] Perform relational update REMOVE FROM FILE sbfname WHERE conditions Remove records matching conditions IMPORT filename [[TO] FILE sbfname] [WHERE conditions] [USING parms] Import external text file to superbase EXPORT [FILE sbfname] [INDEX index] [TO] filename [WHERE conditions [USING parms] Export to external file LABELS [FILE sbfname] [WHERE conditions] [USING labelstring] Print labels as per label definition MERGE [TEXT filename [WHERE conditions] Load text file and mail merge INPUT OUTPUT FUNCTIONS SHOW field/strexpr Show external field OPEN filename FOR INPUT/OUTPUT/APPEND/COMM Open sequential file for input/output POSITION nexp Position in sequential file INPUT [&nexp/LINE] var/field Input characters or line from text file CLOSE INPUT/OUTPUT/COMM End input/output to/from text file or comms SET filename Read exec or variable file and execute GET var/field Get character from keyboard no wait WAIT FOR time/FOR nexp/var/field Wait till time, for no of secs or for single key entry ASK [string] [pos] [length] ;var/field Get input string from user BELL Ring bell HOME Move screen output position to home CLS Clear output screen EJECT [nexp] Do new pages on print device SCRDUMP Do screen dump to printer LOCATE coordinates Set position on output device NEWLINE [nexp] Send newline to output device MENU column, item, state [, text] Set up a user defined menu MENU CLEAR Clear user-defined menu MENU ON numvar Turn on user-defined menus, specify variable for return value REQUEST text[, ] text[, ] type [, numvar [, textvar [, len]]] Set up a user-defined dialog(requester) MEMORY List of variables in memory STATUS [FILE sbfname] Status of selected file or system SAY [[USING pitch, mode, rate, sex, phonemes] string [, /;string...]] Amiga only. Output string as speech FG nexp Set foreground colour BG nexp Set background colour UL [ON/OFF] Set or clear underline IT [ON/OFF] Set or clear italics BF [ON/OFF] Set or clear bold face ATTR OFF Clear bold face italics and underline ? /DISPLAY/PRINT/OUTPUT TO file Send information to selected output device ? SAY Use narrator device to speak output ? MEMORY List of variables in memory ? LIST Program listing in memory ? STATUS [FILE sbfname] Status of selected file or system ? DIRECTORY Current directory listing ? TEXT [MERGE] Text file in memory optionally mail merging ? QUERY Current query statement ? exprlist Any expression list REPORTING HEADING statements END HEADING Specify statements to execute on page heading FOOTING statements END FOOTING Specify statements to execute on page footing REPORT total list Set report totals, means and count BEFORE REPORT Specify before report activity AFTER REPORT Specify after report activity END REPORT End of report specifications GROUP field total list Specify subtotal break field and subtotals, means and counts for group BEFORE GROUP statements Specify before group activity AFTER GROUP statements Specify after group activity END GROUP End of group specifications FORM HANDLING CLOSE FORM Close current form OPEN FORM formname Load a form into memory FORM [, page [, row [, column]]]] Specify page for current and top left-hand corner ENTER [FORM view name] [field list Enter data into fields through view form OPERATORS ARITHMETIC OPERATORS ^ Exponentiation - Negation * Multiplication / Division MOD Modulo arithmetic + Addition - Subtraction RELATIONAL OPERATORS = Equality LIKE Pattern matching case insensitive equality <> Inequality < Less than > Greater than <= Less than or equal to >= Greater than or equal to LOGICAL OPERATORS NOT AND OR MATHEMATICAL FUNCTIONS SGN(x) Sign of variable INT(x) Integer portion of variable ABS(x) Absolute value of variable SQR(x) Square root RND(x) Random number LOG(x) Logarithm EXP(x) Exponent COS(x) Cosine SIN(x) Sine TAN(x) Tangent ATN(x) Arctangent FIX(x, y) Fix decimal precision of value FREE(n) Return free memory size DISKSPACE("disk") Return free disk space RECCOUNT(sbfname) Return number of records in file SER(sbfname) Return serial number of specified file ROW(0) Return current screen row COL(0) Return current screen column PROW(n) Return current printer row PCOL(n) Return current printer column EOF(sbfname) Return if at end of file FOUND(sbfname) Return result of last search LOOKUP(value, fld) Return if value exists in file(indexed field) STRING FUNCTIONS LEN(x$) Length of string STR$(x[[, y] [, z] / [, numformat]]) String from number with optional format VAL(x$) Value of string ASC(x$) Ascii value of character CHR$(x$) String value of character LEFT$(x$, nexp) Left portion of string RIGHT$(x$, nexp) Right portion of string MID$(x$, nexp [, nexp]) Mid portion of string DAYS(x$) Numeric value of date DATE$(nexp [, dform]) Date string from numeric using optional format DAY(date) Numeric day value of date DAY$(date) Day of week from date MONTH(date) Numeric month value of date MONTH$(date) Month string from date YEAR(date) Numeric year value of date TIMEVAL(time) Numeric value of time TIME$(nexp [, tformat]) Time string from numeric using optional time format HRS(time) Number of hours from time MINS(time) Number of minutes from time SECS(time) Number of seconds from time THOUSECS(time) Number of thousandths of second from time LCASE$(x$) Convert string to lower case UCASE$(x$) Convert string to upper case FCASE$(x$) Capitalize first letter of string TRIM$(x$) Trim trailing spaces from x$ LTRIM$(x$) Trim leading spaces from x$ INSTR([n, ]x$, y$) Find position of substring y$ in x$ REPLICATE(x$, nexp) Replicate character expression n times SPACES$(n) Return string with n spaces ERR$(n) Returns error message for error number n VARIABLES TODAY Return system date NOW Return system time ERRNO Return current error number PI Return value of pi FIELDS BY NAME Fieldname; Field.file; Field. "file" MULTIPLE RESPONSE FIELDS Fieldname(nexp) STRING VARIABLES X$ NUMERIC VARIABLES X% ARRAYS X% or X$(nexp[[, nexp] [, nexp]]) SUPERBASE PROFESSIONAL Using Superbase Personal Files ------------------------------ Superbase Personal is upwardly compatible with Superbase Professional; so if you have upgraded from one to the other, you can use any of the files that you created in Superbase Personal. (It doesn't work the other way round: Professional files cannot be loaded into Superbase Personal.) However, there a number of differences in the way the two programs store file data. You should take these into account when you are loading Personal files into Professional. When you save the files, Superbase Professional will automatically convert them to its own format. But in some cases you may need to edit your Personal files before you can use them. Here is a checklist of the points to bear in mind when converting files from Personal to Professional: * Professional query files include the details of any database files associated with a query and these files are opened automatically when the query is loaded. If you use a Personal query in Professional, you will need to open the database files yourself before loading the query. Then save the query in order to convert it to the Superbase Professional query format. * Although Superbase Personal does not offer a Constant field type, it allows you to create a special type of calculation formula which acts like a constant formula. For example, if you define a single word formula such as "London" or TODAY it will have the same effect as the equivalent constant formula in Superbase Professional. When you load a Personal file into Professional, calculated fields will be defined as CLC RDO fields. If they were originally intended to act as constants, you should change the CLC attribute to CON by selecting Edit File and editing the file definition. You may also want to remove the Read Only attribute. * The list of words that are reserved for the use of the system is more extensive in Superbase Professional than in Superbase Personal (see the section on Reserved Words further on in this document). As a result, you may find that some of the field names in your Personal files are treated as reserved words in Superbase Professional. For example, Professional offers a large of number of new functions such as YEAR and HRS. If you have used YEAR as a field name, it would now become invalid. Before loading a Personal file, check that the field names are valid; if they are not, change them by editing the file definition. Edit Form The Project menu option, Edit Form, runs the Forms Editor as an additional task if it is not already in memory, provided there is sufficient RAM capacity. If you have opened a form in Superbase, you can use this option to edit it in the Forms Editor and then return to Superbase. For Edit Form to work, Superbase must be able to locate the Forms Editor program. First it looks for the program in the current directory and then in the root directory of the current device. If this fails, Superbase will look in the parameters directory as specified in the Options dialog. If the Forms Editor still cannot be found, Superbase will assume that it resides on a disk with the volume name SBFORMED:. If this disk is not present in the system, and you have not used the CLI ASSIGN command to specify the location of SBFORMED:, then an AmigaDOS requester will prompt you to insert it. If the Forms Editor is already running when you select Edit Form, then the Forms Editor window is pulled to the front and made active. The current form in Superbase will also be selected for editing. To Return to Superbase you can use the depth arrangement gadget to push the Forms Editor screen to the back. Reorganize The primary application for Reorganize is as described in the User Guide. It allows you to reclaim disk space after deleting records from a file, and makes disk operations with the file more efficient. This option can also be used to recover records after their data has been corrupted; i.e., when an attempt to open a file produces a disk error message. Reorganize steps over any errors it finds in a file and retrieves as many valid records as it can. The records which have been damaged will be lost when the new file is created so Superbase informs the user with the message: "New file has different record count". There may also be circumstances in which Reorganize can be used to recover data which could not be accessed before. For example, if you turned off the computer after storing new records in Batch mode, the details of these records would not be stored in the file header. Reorganize rewrites the file header so that the records are included in the new file. In this case, it issues another error message (as well as the one above): "Source file size incorrect in header". Note that the manual suggests that the best way to recover data from a disk error is to Export the remaining records and then import them to a new file. This method has now been superseded by Reorganize. Using the Lookup Function There are several points to note in connection with the LOOKUP function: * When you are creating a validation formula (in a file definition) that uses LOOKUP, you should always enter the function's arguments by typing them into the box at the bottom of the validation dialog. In other words, even if your LOOKUP formula contains a field which is shown in the field list above, you should type the field name into the box instead of clicking on it. * It is important to include the file name as an extension to any field name used with LOOKUP. This applies to all fields irrespective of whether their names are unique to one file or not. For example: LOOKUP(Forename.Address, Firstname.Customers) is correct, while: LOOKUP(Forename, Firstname) may cause problems. * LOOKUP will not work correctly with date/time and numeric fields that have null values -- i.e., fields that have been left blank. If you wish to use LOOKUP on fields of this type you must force the first argument to give a null value when empty. For example LTRIM$(DATE$(date field)) will give a null string when the `date field' is empty. Amiga Requester Default Keys Many of the dialogs in the Amiga version of Superbase accept Return and Escape as keyboard equivalents to clicking on the OK or Cancel buttons. Press the Return key to select OK, press the Escape key for Cancel. In cases where a casual OK might be destructive, Superbase does not allow the Return key equivalent. Keyboard Equivalents In addition to the keyboard equivalents described in the User Guide, Superbase also provides the following: Alt/Amiga B Toggles Bold (text style) on and off in the Text Editor Alt/Amiga U Toggles Underline on and off Alt/Amiga I Toggles Italic on and off Alt/Amiga P Toggles Plain on, bold, italic, and underline off Alt/Amiga B Toggles Batch mode on and off (this option is only available when the database window is active, otherwise Alt/Amiga B acts as a keyboard equivalent for the Bold text style) Alt/Amiga A Select the program command line window --equivalent to selecting Command from the Program menu. Note that `Amiga' indicates the right Amiga key. The keyboard equivalent for Set Paging, Alt/Amiga P, is no longer available. New Editing Controls Two new controls have now been provided to allow the user to copy lines in the Program Editor and Text Editor. CTRL L is used to select the line you wish to copy; move the cursor to any point on the line and press CTRL L. CTRL R inserts a copy of the line that has previously been selected with CTRL L; move the cursor to the point in the program or document where the line is to be inserted and press CTRL L. A copy of the line will then be inserted below the cursor. Current Record Button By now you will have noticed that the current record button on the Control panel does not agree with the illustration in the User Guide on page 1-8. Whereas the guide shows a single triangle (as in Superbase Personal), the program now has two triangles pointing in opposite directions from each other. The reason for this is that, in Superbase Professional, the button has two functions. As well as acting as the current record button, it also allows you to change current page in a multi-page form. In the first capacity, it is used to redisplay the current record after the record data has been overwritten or removed from the screen by some other action -- for example, by Status File. As a page selector, the same button is used to select either the next page or the previous page. Clicking on the right-hand triangle displays the next page, clicking on the left-hand triangle displays the previous page. Passwords In earlier versions of Superbase, passwords were shown on screen in the Password dialog as you typed them in. Now, when you type in a password in order to gain access to a file, the password is not displayed in the Password dialog. RAM disk support (Amiga) Normally if you wish to use the Amiga RAM disk within a program, you need to copy data files into the RAM disk before running the program. With Superbase Professional, this step is unnecessary. You can load data into the RAM disk simply by using the drive identifier RAM: when you open a Superbase file. If the file is not already in the RAM disk, Superbase will copy it to the disk from the current directory, and open it at the same time. Superbase also provides a similar service when you close the file. It asks if you want the file to be copied back to the current directory, i.e. to the floppy or hard disk it was originally copied from. If you click on OK it does the job for you. Should you click on CANCEL the file will not be copied back and you will be asked if you want to erase the copy you have in the RAM disk. Selecting CANCEL will leave the RAM copy intact. (Note that if you open an existing file on RAM disk which has not been put there by Superbase then when you close that file Superbase will not ask you if you wish to copy it back.) As an example, suppose the Address file is stored on the disk in drive DF1: and the current directory is DF1:. To open this file from the RAM disk you would select the Open File option on the Project menu and then enter: RAM:Address You can now work on the file in the normal way -- retrieve data, edit data, remove records, and so on -- with the advantage that file operations using a RAM disk are much faster than they are on a physical disk. Remember to close the file at the end of a session so that any changes you have made can be saved permanently in the directory from which it was copied. This feature also works with other Ram disk facilities where the drive identifier is VD0: or VDK:. Reserved Words -------------- It should be emphasised that the reserved word list includes all Superbase functions even though they are not listed in Appendix C. You should bear this in mind when you are defining a file or writing a program: many of the DML functions have names which you might tempted to use as field or variable names, for example HRS, DAY, MONTH, YEAR. Note also the following keywords which should be added to the list in Appendix C. AS BUFFERS CALL COPY DISK DISKSPACE FIELDS PAGING RECORD TABLE Graphics and Form Printing -------------------------- On the Amiga, Printer on the Set menu has been extended to provide a graphics printing option for forms. Selecting this option displays a sub-menu with two items, Draft and Graphics. Draft works in the same way as is described in the User Guide, Volume 1. When Draft is set, output that appears on screen is sent to the printer as well; so if you select the next record in the current file, its field data will be output to the printer. If a form is in use all the text items will be printed as well as the field data. If you wish to print the field data only then you should set the Print Status of the text items to non-printing within the Forms Editor. The Graphics option can be used when you are displaying data with a form. It prints all the graphic elements in the form -- lines, boxes, areas, images, and so on -- together with all the data the form displays. Data items are printed in the system font, text items are printed in the fonts and point sizes which were set in the Forms Editor. However, Superbase will also take into account the Print Status of an item as set in the Forms Editor. On a 512K Amiga, you will only be able to print four colour forms in either draft or graphics modes. Using Superbase as a Relational System -------------------------------------- Although it is impossible to describe the principles of relational database design in this document, most users will benefit from an abbreviated account of some of the more important facts. When you are contemplating the basic design of a relational database application, there are three key considerations: 1. Establishing relationships between files. Every pair of files between which there is to be a relationship must have a field in each file that will be used as the link between them. These fields should be designated as key fields, preferably with unique indexes. 2. Ensuring integrity of relational link data. At the data entry stage, what goes into the link fields described above must be carefully controlled. The aim is to ensure that, for example, an account code (usually a text field) is always entered in the same case in all files in which it is used. This is done by setting the text field attribute for each of the link fields to perform automatic case conversion to either upper or lower case; obviously the conversion must be the same for both fields. Validation formulas may also be necessary to check the pattern of what is entered, its length, or the range of acceptable values. The second control on data integrity is via the LOOKUP function. This enables the system to check what is entered into the link field in one file against what already exists in the link field in the other file. For example, you would always want to check that a product was in stock before accepting an order for it. The LOOKUP function is attached to the link field in the file definition as a validation formula. However, if you are using links as described in the next paragraph, you must ensure that none of your LOOKUP functions tries to check for a record that you are still in the process of creating! 3. Including links in a multi-file form. If you want to design forms which can retrieve data from more than one file, you must use the Set Link menu option in the Forms Editor to create the links between the files. In Set Link, you specify the link fields described above as the master (or primary) and secondary link fields. At the other end of the application, you will want to retrieve data from your relational system in the most convenient way. There are a number of ways of doing this. 1. Browsing. Use a multi-file form with links set up as described above. The video buttons operate in the usual way, and you can switch files and indexes to vary the order of retrieval. The printer may be used to obtain draft or graphics hard copy. 2. Queries. The Process Query Edit menu option can be used to set up multi-file queries, which may be stored on disk. Output may include any fields from files between which a relation is specified in the Filter, and can be sorted as you wish. Report functions may be added, as well as limited formatting, but output is basically columnar and non-graphic. 3. Reports. Report programs may be generated automatically with the Forms Editor or written directly in the program editor (the Program Edit menu option). The forms editor allows for multi-line headings and footings, many levels of subtotalling and sorting, and full page field positioning, as well as offering many other features. Relations between files are derived from the links between files, so here again you must use the Set Link menu option before saving the report form. Output is non-graphic. Further Rules for Constructing Queries -------------------------------------- In multi-file queries, the user (especially the programmer) must exercise extra care to ensure that the query is efficient. The following rules should be observed: 1. Files are processed in the order in which they are mentioned in the WHERE statement (Query Filter Line). In some cases you will want to process the smallest file first, in some cases you won't. You may have to experiment to find the optimum query for a particular application. 2. Every file reference in the WHERE statement must be part of a chain. WHERE A=B AND B=C is acceptable, but WHERE A=B AND C=D is not. A simple rule of thumb is that there should always be one less join than the number of files in the query. Superbase Start Options ----------------------- When you run SBpro from the CLI, you can use the following optional parameters: SBpro [-c] [-r] [-fformname] [-p] [-s] [-z] -c Selects custom screen -r Disables returns (chr$(13)) when writing to disk files -f Loads form at startup time -p Removes remote control panel -s Removes scroll bars from Superbase window -z removes sizing gadget and disable sizing NOTE: Remember to set the stack to at least 8000 before running Superbase from the CLI. The start options are also available from the Workbench by setting Tool Types in the Info for the SBpro icon as follows: SCREEN=WORKBENCH Use Workbench SCREEN=CUSTOM Use custom screen RETURN=ON Enable returns RETURN=OFF Disable returns SYSTEM=NOPANEL|NOSCROLL|NOSIZE Remove panel scroll bars and size gadget You also may use any combination of the three options in the SYSTEM item. You can load a form at startup by creating an icon for it with the default tool set to SBpro and then double clicking on it. DATABASE MANAGEMENT LANGUAGE (DML) Changes to DML -------------- Programmers should be aware of the following changes, extensions and undocumented features in Superbase's Database Management Language: 1. The LOOKUP function is case sensitive -- for example, LOOKUP("fred", Firstname.Address) will not find an occurrence of "Fred". 2. The record SELECT commands (SELECT NEXT, SELECT LAST, SELECT KEY etc) have been amended so that they now take another optional parameter, FORM. The effect of this parameter is to activate any multi-file links that have been set in a form. If it is not used, the SELECT commands only operate on the current file and ignore any links between files. FORM must be placed immediately after SELECT. For example, with SELECT NEXT command, you would enter: SELECT FORM NEXT. 3. The KEY command now accepts a numeric key as well as a string key. 4. The commands EJECT, LOCATE, and FOOTING do not operate when the current output device is the screen and PAGING is OFF. You can, however, use LOCATE with paging off to set the column position -- but not the row position. 5. FORM. This command takes another optional parameter, SHOW, which is used to display external files. If the form contains external file fields, FORM SHOW is equivalent to clicking on the camera button. The syntax for FORM is: FORM [SHOW] [page [, row, column]] Note that the `page' parameter is now optional. When it is omitted and the FORM command is used without any following parameters, Superbase only displays the field data in a form and omits any other objects. 6. The command SET BUFFERS only sets the size of the disk buffers for the current session. If you want to set the number of buffers to be saved with the parameters file (SB.PAR), use the new command SAVE SET. 7. SET TABLE/RECORD/FORM can be followed by the ON parameter. This switches to the specified view mode even if there is a form in memory. Normally SET TABLE, for example, acts as a toggle between Table view and the form. If Table view is the current view mode, this command would switch in the form. SET TABLE ON, however, would leave the current view mode as it is. The advantage of this option is that it enables the programmer to select a view mode without having to keep track of what the current mode is. 8. During the execution of a program, BREAK OFF disables the Stop button and CONTROL-C; also, you cannot use the space bar to pause during program execution. When the program has finished, BREAK is turned on again. 9. Apart from the Stop and Pause button, the remote control panel is disabled while a program is running. Stop is only disabled if the BREAK OFF command has been issued, Pause is available at all times. 10. STORE takes another optional parameter, FORM. If FORM is used all the records in the current form are saved; otherwise STORE only saves the record which belongs to the current file. The new syntax for this command is: STORE [, 0/1/2] [FORM]/[FILE sbfname] Note that STORE , 2 secures not only the current file but also any other open files. It is therefore not necessary to follow it with the FORM or FILE parameters and, in fact, adding one of these parameters to STORE , 2 will cause an error. 11. BLANK can also take FORM as an optional parameter. With a multi-file form, BLANK FORM creates blank records for each file represented in the form. When the FORM parameter is not included, BLANK only creates a blank record for the current file. The syntax for this command is: BLANK [FORM]/[FILE sbfname] 12. If SELECT DUPLICATE does not find a duplicate of the current index field, it leaves the current record unchanged. 13. A string function should not contain more than one intermediate string concatenation. For example, LEFT$("abcde", LEN("x" + "y")) contains only one intermediate concatenation and gives the correct result, but LEFT$("ab" + "cde", LEN("x" + "y")) gives the wrong result because it contains two concatenations -- "ab" + "cde" and LEN("x" + "y"). 14. Superbase already provides you with equivalents for the system commands (or disk utilities) Delete, Rename and Copy. If you want to use some of the other disk utilities without switching screens or exiting from Superbase, you can do so with the CALL command. On the Amiga, you enter: CALL "NEWCLI" This opens a CLI window on the Workbench screen, and you can then type in and execute any of the AmigaDOS commands. Alternatively, you can execute a DOS command directly without first typing it in the CLI window. Thus to list the directory for drive DF1: you would enter: CALL "DIR DF1:" The directory will then be output in either the CLI window used to run Superbase or the small Superbase window opened on the Workbench screen. You may want to use CALL to run a program which requires input from the keyboard. In this case, you should follow the program file name with the `<*' parameter, as in: CALL "fcopy <*" The effect of this parameter is to redirect input from `stdin', allowing you to type in data from the CLI window. 15. With commands that set a single file filter using WHERE (for example, IMPORT, EXPORT and SELECT WHERE) you can include ASK as the parameter to the WHERE statement. The effect of ASK is to display the standard filter dialog when the command is executed, thus allowing the user to set a filter while a program is running. If a filter is present when ASK is executed, the filter expressions will be presented as a default for the dialog. Examples are: SELECT WHERE ASK In this example, ASK causes the filter dialog to be presented. Entering the following filter line (at run-time): Lastname LIKE "[r-z]*" would have the same effect as executing the command: SELECT WHERE Lastname LIKE "[r-z]*" However, a partial filter like this is not allowed: SELECT WHERE datefield > ASK 16. ENTER. The parameters for this command can only be used with a form. With other view modes, ENTER (on its own) places the data entry cursor in the first open field that is not Read Only. 17. REQUEST. There is now an additional dialog type with the dialog number 19. This displays a list of the forms in the current directory. Note that the description in the DML User Guide for dialog type 5 is incorrect. This dialog provides a list of the fields in the current file. 18. SHOW. The command now takes an optional extension to allow or remove the menu bar from the EFMS screen: SHOW [MENU ON/OFF] [field]/[strexpr] 19. ? QUERY. The syntax for this command has been extended to make it easier to select a device for output. It is no longer necessary to select an output device before executing ? QUERY. Instead you should specify the device using the TO parameter. The new syntax is: ? QUERY [TO device] where `device' can be the printer, an ASCII file or a new `.sbf' file. If this parameter is not included output is to the screen. The device options are: TO PRINTER Outputs to the printer. TO FILE filename Creates an `.sbf' file on disk under the file name specified. TO filename Outputs to the ASCII file specified by `filename'. 19. IF THEN ELSE. The explanation of block IF THEN statements given in the manual needs to be supplemented by two further points: * Every block IF THEN statement must end with an END IF statement. (Example 4 on page 5-69, Volume 2, requires a second END IF after the last line.) * Within a block IF THEN statement, you can insert one or more ELSE IF statements. These are used to extend the number of alternatives provided by the original block IF THEN (so that it has the same effect as the CASE statement found in some versions of Basic); but they do not require additional END IF statements. The following examples should make these points clear: IF a% THEN ? atrue$ IF b% THEN ? btrue$ ELSE ? bfalse$ END IF ELSE ? afalse$ END IF IF a% =1 THEN ? "one" ELSE IF a% = 2 THEN ? "two" ELSE IF a% = 3 THEN ? "three" ELSE ? "Not 1 to 3" END IF New DML Commands 1. SET PG Use this command to set the page size on your printer. It takes the syntax: [SET] PG rows [, columns [, ss]] where rows specifies the number of rows on the page and column specifies the number of columns (the page width). ss stands for single sheet and takes a value of 0 or 1. 0 specifies that single sheet paper is used, 0 specifies continuous stationery, also known as fan-fold paper. SET is optional. An example of the use of SET PG would be: SET PG 50, 65, 1 This line sets the format for a printed page to 50 lines of no more than 65 characters. It also tells Superbase that the printer takes continuous stationery. You can use this command in a program or from the command line to customize a page for any kind of printed output -- whether you are printing a text file, record data or a report. However setting up the printer in Preferences on the Amiga will override the PG settings. 2. SET PRINTER ON [, 0/1] / OFF This is the program equivalent of selecting Print on the Set menu. The 0 parameter specifies draft mode printing, and the 1 parameter specifies graphics mode printing. Use this command in conjunction with FORM to obtain form printouts. After SET PRINTER ON has been executed, any output to the screen will also be sent to the printer, so remember to SET PRINTER OFF when the print operation is complete. 3. SAVE SET This command saves the Superbase parameter file. It is equivalent to clicking on OK in the Options dialog. All the parameters that have set in the dialog (and those that are set elsewhere) will be saved on disk in the file SB.par. 4. SET MIN This command sets the minimum size allowed for the Superbase window. It takes two optional parameters, the minimum width and height of the window in pixels, so the full syntax is: SET MIN [width [, height]] Maximum width is 640, maximum depth is 183. SET MIN without parameters allows the programmer to lock the window to its current size while a program is running. You cannot use SET MIN to set the window larger than its size when the command is executed. SET MIN can also be executed from the command line or a function key. User-Defined Menus Other points to note in connection with the commands MENU and MENU ON are: * The first item defines the width of a menu in terms of the number of characters. When you define the text string parameter for item 1 you may need to allow for the width of other items in the menu by adding spaces to the end of the string. * If you wish to use checkmarks in your menus, remember to leave a space for the checkmark character when you define the MENU text string -- the first character in the string should be a space. * MENU on its own clears all the menu settings (as do ERASE and CLEAR). * After the MENU ON command has been executed, any menus that have been defined remain active until an item has been selected. The program example on page 5-91 of the DML User Guide is slightly misleading on this point since it suggests that the MENU ON command needs to be executed repeatedly. A better way of checking whether an item has been selected would be: MENU ON a%, b% menuloop: ON a% GOSUB sub1, sub2, sub3 GOTO menuloop Note, however, that the MENU ON command should be executed again after an item has been selected in order to reset the menu variables to 0. FORMS AND FORM HANDLING Changing Text Fonts Contrary to what is stated in the Forms Editor User Guide, text fonts can be altered without deleting the text and typing it in again. In fact, the text font can be treated in the same way as the text style, as one of the text object's attributes. To change the font, first select the object by double clicking on it; then select the new font from the Fonts menu. Using External Files in a Form You can use external file fields in a form in the same way as you do in a database file. The difference is that the external files are displayed in the field boxes rather than in a separate window. This means that multiple external files can be displayed at the same time. When you load the form into Superbase, the box for an external field will show the data in the current record; i.e., the name of an external file. To display the file in the box, click on the camera button. If a box which contains an image file extends beyond the screen, Superbase will move the form so that it shows as much of the image or text as possible. The result of entering a box -- by clicking on it, or by pressing Return after editing the previous field in the field order -- differs according to whether it contains a text file or an image file. If you enter a text box, Superbase replaces the box with the Text Editor window (which is given the same dimensions as the box). You can then edit the text in the normal way. Closing the Text Editor window or clicking in another part of the screen, restores the text to the field box, and moves on to the next field. With images, the effect of entering an external field box is to activate the image colour map: the image is displayed in its original colours. Otherwise, the image is displayed in the default colours of the form. These facilities for showing text and images in external field boxes only operate if the box is more than one character deep. For this reason, the first thing you should do after placing an external field on a form (in the Forms Editor) is resize it. Amiga Colour Palette On the Amiga, the Colour Palette option (in the Attributes window) has been altered to reflect this computer's special colour features. The Palette now works in the same way as the Preferences colour changing option. It also offers several extra facilities not available in Preferences or in Gem versions of the Forms Editor. You may find it helpful to read the section on page 3-9 of the Forms Editor Guide as an introduction to the ideas underlying this feature, but for detailed instructions on how to use the palette you should consult the next section. Changing the Colour Palette (Amiga only) When you click on the Colour Palette icon in the Attributes window, the Forms Editor will present you with the Colour Selection dialog (requester). At the top, there are three sliders for defining a colour in terms of its RGB (Red, Green and Blue) values and a box showing the currently selected colour. The set of colours available to you is shown below in the same format as in the Attributes window -- as two rows of eight colours. If you have previously set the resolution to 4 or 8 colours, only the first 4 or 8 colours will be available and the rest of them will be ghosted. To change one of the colours in the Palette, first select it by clicking on its box in the colour panel. The Forms Editor will then do two things: it will display the colour in the box at the top left-hand corner of the Colour Selection, and it will reset the sliders to reflect the RGB values for the colour you have selected. You can now change the colour by moving the sliders in the same way as you would if you were using Preferences. When you have finished, click on OK to return to the current Forms Editor page. By using this technique, you could define all the colours in the Palette, setting the RGB values for each of them in turn. The Forms Editor also provides several other options which allow you to change a number of colours at a time. These options are indicated by the buttons below the colour panel. The Copy button enables you to copy a colour from one box to another. The procedure is as follows: first, click on the colour you wish to copy; second, click on the Copy button; third, click on the target colour to which the first colour is to be copied. With the Range button you specify the two colours at either end of the range and the Forms Editor then adjusts the colours in between. If you specified white and dark blue, for example, the colours in between would be changed to shades of blue from light to dark. To set a colour range, click on the colour which is to form the starting point (or the end point) for the range, click on the Range button, then click on the colour at the other end of the range. The Read Prefs button at the right of the colour panel changes the first four colour boxes to the colours that have been set in Preferences. The Reset button reverses the effects of any changes you may have made and restores the colours that were set before you selected the Colour Palette. Report Functions Apart from COUNT the report functions -- SUM, MIN, MAX, MEAN, VAR and S.D. -- can only be used with numeric fields. These functions operate either on all the records in a group (if used in an AFTER GROUP section) or on all the records in the report (in an AFTER REPORT section). SUM Gives the field total for all the records in a group or report. MIN Returns the minimum value of the specified field among the records in a group or the report. COUNT Returns the number of records in a group or the report. Unlike the other functions, COUNT should not be followed by a field name -- it operates on the field specified in the REPORT or GROUP box. MAX Returns the maximum value of the specified field among the records in a group or for the report. MEAN Returns the average value of the field data in a group or in the whole report. VAR (Variance) Provides a measure of the spread of the data from its mean. S.D. (Standard Deviation) Provides a measure of the spread of the data from its mean -- for the field data in a group or over the entire report. Amiga Images ------------ When you add an image to the page, the Amiga version of the Forms Editor gives you a choice over the colours the image takes. A dialog appears with the message: Use image colour map? Clicking on OK selects the image colour map and resets the colour palette to those colours. If you click on Cancel, the image will be displayed using current range of colours as shown in the Attributes window. The form designer should ensure that only images compatible with the resolution and colour of the form are used. FORM CALCULATIONS Calculation Types ----------------- The calculations you add to a form have a number of features which are not covered in the Forms Editor guide (you should ignore the calculation examples given in the guide). In fact, with forms that are designed to be used in Superbase, calculations can play a far more important role than is suggested in the guide. This section describes these features in detail. Calculations take the same names as DML variables. If they are intended to store string data, the last character must be `$'; if they are used to store numeric data, the last character must be `%'. Calculations referred to by another calculation must already have been added to the form. When you create a calculation, you will be presented with a calculation dialog where you enter the formula for the calculation. Initially, it will show a list of the fields in the current file which have been added to the form. If you want to refer to other calculations in the formula, click on the multi- file gadget. The calculation names will then be listed as if they were fields belonging to a file called FORMCALCS. There are four different types of form calculation, and each has its own syntax. 1. Blank calculations. These are calculations which do not have a formula attached to them. They provide a means of interacting with a form from a program and can be treated as program variables. To define a calculation of this type, first enter its name and then, without entering a formula, click on OK in the formula dialog. Once the form has been loaded into Superbase, the calculation can be used as a link between the form and a program. This works both ways: you can assign a value to a calculation-variable either by typing it in the calculation's box on the form or by executing an assignment statement in a program. Suppose, for example, you defined a blank calculation with the name fred%. In the form's field order fred% is number 5. If you wanted to input data to a program from the form which contains fred%, you would include the program line: ENTER 5 When this line is executed, the input cursor will appear on screen in the box belonging to fred% and the value entered by the user will be assigned to fred%. If you now executed the Memory command, fred% and its contents will be listed along with all the other program variables. And any other DML commands which operate on variables, such as CLEAR, will also work with a calculation variable. To assign the value 22.5 to fred% from within the program, you would execute the statement: fred% = 22.5 This value will then be shown in the calculation box when the form display is next updated. Note that ENTER is the only input command that can be used with a form. Forms are object oriented rather than character oriented so you cannot use ASK or GET in combination with LOCATE. Another point to note is that you can only identify a calculation by its field order number; a command such as: ENTER fred% will not work. 2. Standard calculations. These function in the same way as the calculations which are attached to fields, and they take exactly the same syntax. In fact, they can be regarded as a special kind of field which only exists on a form. The calculation name should not occur in the calculation formula unless it is a self-referencing calculation. Instead the result is automatically assigned to the calculation when the formula is performed; that is, after each of these events: * Saving a record * Moving the cursor through the calculation box * Clicking in the calculation box * Retrieving another record, e.g. by clicking on the Next Record button or with the command SELECT NEXT * When you press Return after entering data in the box (only possible if the calculation is not Read Only) Typically, this type of calculation is used to derive a total from the contents of other calculations or fields and then to display it on the form. Another application would be to display a date by using the keyword TODAY in the formula. Examples are: Calculation name Calculation formula subtot1% Quantity * Price name$ Left$(Firstname, 1) + ". " + Lastname When$ TODAY If you want to create a self-referencing calculation (see Self-referencing Formulas, Chapter 2, Volume 1), you need to add the calculation to the page and then edit it. 3. LET calculations. The formula for this type of calculation must start with an assignment statement with LET as the first word. It is used to assign a calculated value to a field or another calculation. The field may belong to the current file or another open file. An example would be: LET Amount.invoice = quantity * cost where this formula is attached to the calculation fred%. Quantity times Cost will be evaluated in the same circumstances as for type 2 calculations and the result will displayed on screen in the calculation box belonging to fred%. When a new record is retrieved, things happen slightly differently. The right-hand part of the formula is evaluated and displayed, but the value is not assigned to the field named to the left of the equals sign. As with the other types of calculation, the result determines whether the calculation should be defined as a string or numeric variable; i.e. for a string result, the calculation name must end with the `$' character; for a numeric result, the name must end with the `%' character. If you are using a LET calculation to send or `post' data to a record in another file, remember to save the record after completing a task. 4. Executable calculations. These calculations contain program statements which are executed when the user passes through the calculation box or clicks on it. A calculation of this type must begin with a DML command as opposed to the name of a variable, field or calculation. But, to distinguish it from other types of calculations, the command word should not be LET, AFTER or POST. Apart from this, executable commands follow the same rules as for command line statements. Almost any single or multi-statement DML program line can be entered as an executable calculation. This provides immense scope for creating powerful forms with their own built-in processing facility. At the simplest level, you could use an executable calculation to assign strings to function keys for use in data entry. For example: Key 1, "London": Key 2, "New York": Key 3, "Paris": Key 4, ... More complex applications include running a program, executing another calculation, etc. You can even use the calculation itself as a variable into which the user can enter a value. Thus the following command string could be assigned to the calculation f$: IF f$ = "A" THEN ..... ELSE ..... To force a calculation, make it Read Only and next in order. You can only make a calculation self-referencing by creating then editing it. Calculation Prefixes In addition to the four calculation types, there are two prefixes, AFTER and POST, which can be placed in front of the formulas for types 2 and 3. AFTER The purpose of AFTER is to force a formula to be performed more frequently than it would be normally. It is followed by an optional field name and is separated from the rest of the formula by a colon. For example: AFTER : Quantity * Price Here AFTER forces the formula to be performed whenever any event occurs on the form -- if you click on or pass through a field, when you select a new record, and when the form is saved. In the example above, if the formula was attached to the calculation aa1%, the result would be displayed in aa1%'s box every time the user clicked the mouse in the box or in any other box on the form. If a field name is supplied, AFTER only takes effect after an event relating to the field specified. In the example below, we'll assume the formula is attached to the calculation Tot1%: AFTER Item: Subtot1% * 1.15 Tot1% will be assigned the result of the formula `Subtot1% * 1.15' after each of these events: * the cursor passes through the Item field * the user clicks in the Item box * the value of Item changes * all the usual events that cause evaluation of the formula POST Just as there are some calculation formulas which need to be performed repeatedly -- for these you will use AFTER -- so there are others which should only be performed once, when a record is saved. With POST, you can ensure that a result is only stored in a field (posted to another file) after the other calculations in the form have been carried out. POST takes the syntax: POST [LET xxx =] expression where xxx is a field name and the expression can be another field, a calculation, or a formula which calculates a result. The expression is not evaluated until the record is stored, unless the LET part of the formula is included. If this is the case, the expression is evaluated subject to the normal rules, but the assignment of LET is not made until the record is stored. Take, for example, the formula: POST LET Cust_Balance.Customers = Cust_Balance.Customers + Order_Amount.Orders Order_Amount could represent the final figure in a series of calculations which work out the final value of an order. Clearly, we do not want the total to be stored in the Customers file until all the calculations have been performed. By preceding the formula with POST we can ensure that this condition is satisfied. However, intermediate results can be shown on the form by clicking in the calculation box to which this formula is attached. MISCELLANEOUS * In some circumstances the Update option may skip some of the records in the file it is updating. The problem occurs when the update modifies a field which also forms part of the update filter; for example, it would occur if the update fields instruction was: Salary = Salary * 1.075 and the update filter was: Salary >= L8000 The solution is to enclose the filter statement in parentheses, as in: (Salary >= L8000) If you were running this example update under program control, you would place the entire WHERE statement within parentheses: (WHERE Salary >= L8000) This solution works by disabling the automatic optimization which causes the problem. * If you try to print a line longer than the line length set in Superbase's Printer options, Superbase will output a Carriage Return followed by a Line Feed when it reaches the maximum line length. * Note that Amiga owners can set a printer initialization sequence from within Superbase's Set Options dialog. This allows you to set the features and modes you prefer. The sequence of control codes is sent to the printer each time you perform a printing operation from within Superbase. If a sequence is present Superbase does not send the `Skip over perforation OFF' and `Set page length' codes that are normally sent when the printer is accessed. * The output format parameters BF, UL, IT enable you to set different print styles within a report or in the output from a query. If you wish to set other printing features, you can do so by using the CHR$ function to insert the appropriate printer control codes. With a report which has been generated in the Forms Editor, you will need to insert the control code sequences in the report program. In a query, you can simply enter them in the query fields line. For example, on some Epson printers, the sequence 27, 14 selects enlarged print, and the control code 20 turns it off. To output the data for one field in enlarged print, your query Fields line might look like this: Firstname, Lastname, CHR$(27);CHR$(14);City;CHR$(20), Street Note that some control codes may be inappropriately interpreted by the printer device, in which case you should set Print Raw on the Options requester to bypass the interpretation. * Path names. Superbase accepts path names up to 40 characters long (not including the file name). * File Names. Avoid using the characters : ? # / ; or the space character. When using a file name as an argument to a command such as OPEN FILE, it must always be inside quotation marks. However, a file name used to extend a field name, e.g. Name.Customers, need not be inside quotes, unless it includes non-alphanumeric characters, i.e. other than a-Z and 0-9. Superbase supplies quotes when necessary during dialog selections, but if you type a command line in directly be sure to observe this rule. * The Duplicate option on the Record menu re-initializes any constant formulas. This means you can duplicate a record which contains the constant formula SER without duplicating its serial number. Similarly, if a file uses the constant formula TODAY, creating a new record by duplicating an existing record does not reproduce the original date. * Superbase and the Forms Editor require a large amount of chip memory when printing a form in graphics mode. If your Amiga only has 512K RAM, the graphics print option may not be usable. * The DML LABELS examples on page 5-78 are wrong. Example 1 should not suggest that the command can extend over more than one line; example 2 requires the keyword FILE after LABELS. * The normal New Line sequence on the Amiga is a CHR$(10) (line feed). On most other machines and in Superbase, the default New Line sequence is CHR$(13) CHR$(10) (carriage return, line feed). The CHR$(13) may be suppressed, for example to achieve compatibility with the ED editor, by setting RETURN=OFF in the Tool Types list of the Superbase icon, which may be modified using the Workbench Info option. * GET and WAIT (1). Control characters can be returned in GET and WAIT statements. If these are saved in a file which is subsequently LISTed, they will generate the "File contains non-text characters" error. Note also that CONTROL-C, the standard interrupt key, does not stop program execution if returned in GET or WAIT. It is up to the program to detect the value and act appropriately. * GET and WAIT (2). WAIT makes the window active before it starts waiting for input, so if the window becomes inactive for any reason you cannot reactivate it. If this is a problem for your application, use GET instead; however, you will not be able to input into any other window, such as a CLI window, because GET continually reactivates the Superbase window. * The CLEAR statement must be placed last on a program line. * You may want to convert Superbase text files (`.sbt' files) to ASCII files. The technique for doing this is: 1. Rename the `.sbt' file, giving it a different extension. E.g., rename `Merge.sbt' as `Merge.asc'. 2. Load the file into the Text Editor. Its name will not appear in the list of files presented by the Project Open dialog and you will have to type it into the dialog box (remember to include the extension name). 3. Delete the lines containing information about ruler lengths. These will be blank lines except for two figures which give the start and end points for the ruler that is attached to the following paragraph. 4. Save the file using the same name with which it was loaded.