Developing Runtime Applications Summary: Developing a runtime application in Superbase requires that the application remain under program control at all times. This means the SBL program must never reach an END statement or the END SUB in the main() procedure unless you want the application to terminate. Furthermore, your application must handle any errors which occur during a session. This technote covers the fundamental concepts of developing runtime applications using the powerful SBL. The Stock Control System application which comes with Superbase 2.0 is a good example of a complete runtime application with the exception of its use of Query-by-Example, which is not available in the Runtime System. The application has complete error trapping and always remains under program control. Runtime System limitations Refer to page 1-4 of Using the Developer Edition manual for a complete list of unavailable procedures and functions in the Runtime System. For instance, the Runtime System does not make use of MNSTART.SBP and IBSTART.SBP like Superbase does when it is run. Also, the Runtime System has no native mode. Native mode is the mode in which Superbase operates when you open a file and are able to view data and edit data just by clicking into a field. Since there is no native mode in the Runtime System, there has to be a program which sits in a loop and waits for mouse, panel, menu, key, or icon action. When the program is sitting in this loop, it is said to be in the browse mode. This means that you can only view data and not edit or enter new data. In order to edit or add data, the user needs to be able to click on a button or choose a menu item which then places the program in an edit mode through the use of an ENTER command. In Edit mode, control is temporarily handed to Superbase until the user reaches a specified field or presses Esc. At this point, control returns back to the program to the next line after the ENTER command. Database and form design Before writing the SBL program for your application, you need to design your database files, forms for data entry and viewing records, and reports. This technote uses the Customer file and the Customer form which are in the Superbase 2.0 SAMPLES\STOCK subdirectory. Even though this is only a flat file example, it illustrates the basics of runtime applications development. The application developed here does not include any command buttons on the form but after learning the basics, you should have no problems handling objects such as command buttons. Structuring the SBL program The SBL program should have a main() procedure and separate procedures to handle each of the major tasks which are functionally necessary. It is also good programming practice to have a separate procedure for initialization. In order for the application to run under program control at all times, it is necessary to have some type of loop in which the program waits for user action. A typical construct for this is the While Wend loop with a WAIT command. The sample program below uses the While Wend loop to keep the application under program control at all times. The only time the While Wend loop is terminated in the sample program is when the user selects File | Exit from the menu. The While Wend loop of the program is the central part of your application. From the WAIT command in the While loop, user selection of menu items, icons, or pushbuttons is handled by calling procedures. For full functionality, it is important that none of your sub-procedures have WAIT commands. The sub-procedures should always return control back to the main While Wend loop. A WAIT command in a procedure called from a WAIT command will lead to unpredictable operation because Superbase is not designed to support embedded WAIT commands. Error trapping Error trapping is another important consideration for runtime applications. The SBL program should trap any error which can occur and take the necessary actions to resolve the error without interrupting the program. The program below has an error trapping routine called ERRchk which uses the SELECT CASE command to determine what action to take. An actual application would require a much more elaborate error trapping routine to handle all of the different types of errors which occur in different sections of your application. When running an application on the Runtime System, an error which is not trapped by your program will cause the Runtime System to look for the RESTART.SBP program in the current directory. If the RESTART.SBP program is not found, the Runtime System will stop execution and end the session. The RESTART.SBP is used only for instances of unforeseen errors and acts as a safeguard. The RESTART.SBP is not able to RESUME back to where the actual error occurred. In the RESTART.SBP, you should display a message that a unexpected error occurred, then either restart your entire application or close all the files and end your application. SBL program You can either type the program or you can log on to the Superbase Bulletin Board at (408) 986-0342 and download the entire application. The program uses the Customer file and form which are in the SAMPLES\STOCK subdirectory. If you type the program, place it in the STOCK subdirectory or copy the Customer.* files to another directory and place the program in it. If you download the program, create a subdirectory and Unzip the application in that directory. To run the program, load the program into the Program Editor in Superbase and select Program | Run. You can also use Program | Debug to bring up the Debug Program dialog box and step through the execution of the program. The debugger is a very useful tool to learn if you are serious about developing applications. Using the debugger to isolate programmatic errors will greatly reduce your application development time. The following code has a lot of remarks to help you understand what the different commands are doing. Please note that the program was only written to give you a taste of how to develop runtime applications and is in no way or form a complete application. Sample Runtime Application REM Program written to demonstrate how to develop REM a Superbase 2.0 Runtime Application SUB main() CALL Initialize() ' Initialize the environment REM Establish while loop to remain under program control WHILE sel%% <> - 1 sel%% = 0 WAIT MOUSE OR PANEL OR MENU OR ICON MENU ON WEND END SUB SUB Initialize() ' This procedure initializes the environment GLOBAL sel%%, statusline$ 'Make variables global sel%% = 0 PANEL OFF 12 ' Disable Image button on Selection Bar SET ERROR OFF 50 ' Disable "This field must have some data" error SET HEADING "SAMPLE RUNTIME APP" ' Change the title bar SET REQUEST HEADING "SAMPLE RUNTIME APP" ' Set heading for Request Boxes (Place on one line in Program Editor) statusline$ = "Sample Runtime Application" SET STATUS statusline$ STATUS ON ' Turn on status bar MOUSE ON ' Set mouse pointer to an arrow ON ERROR GOTO ERRchk ' Enable error trapping OPEN FORM "customer" CALL IBSETUP() ' Set up Icon Bar CALL MNSETUP() ' Set up Menu Bar ICON UPDATE ' Change Icon Bar ICON ON ' Activate Icon Bar MENU ON ' Enable Menus END SUB SUB NewRecord() ' Procedure to enter a new record CLEAR ERRNO ' Clear old error number ICON OFF' Turn off Icon Bar buttons SET STATUS "Press to End Editing" CALL AddRecord() ' Call Internal Procedure to Add New Record REM Check if new record and if error had occurred REM in AddRecord() IF NEW ("customer") AND ERRNO <> 11 THEN REQUEST "Save New Record?","",130,choice%% IF choice%% = 1 THEN ' Check for Yes STORE FORM END IF END IF SET STATUS statusline$ ' Restore status line ICON ON ' Turn on Icon bar buttons SELECT FORM CURRENT FORM END SUB SUB EditRecord() ' Procedure to Edit a Record CLEAR ERRNO ' Clear old error number ICON OFF' Turn off Icon bar buttons SET STATUS "Press to End Editing" CALL ChangeRecord() ' Call Internal Procedure to Change Record REM Check if record was modified and if error had occurred REM in ChangeRecord() IF MOD ("Customer") AND ERRNO <> 11 THEN REQUEST "Save Changes to Record?","",130,choice%% IF choice%% = 1 THEN ' Check for Yes STORE FORM END IF END IF SET STATUS statusline$ ' Restore status line ICON ON ' Turn on Icon bar buttons SELECT FORM CURRENT FORM END SUB SUB LabelReq() ' Procedure for printing labels ICON 10,"PrintSub","LabelReq",2 ' Display icon as selected SET ERROR OFF 11' Disable Error 11 Checking SET LABELS REQUEST ' Bring up Labels Dialog Box IF ERRNO <> 11 THEN ' If user does not CANCEL then output labels LABELS WHERE ASK END IF SET ERROR ON 11 ICON 10,"PrintSub","LabelReq" ' Display the icon as enabled END SUB '*********************************************************************** ' * AppExit() - This allows the user to QUIT the application ' * ' * The procedure closes down all database files, forms, ' * buffers, and exits out of Runtime System '*********************************************************************** SUB AppExit() CLOSE WINDOW ALL REMOVE DIALOG ALL CLOSE ALL sel%% = - 1 ' Set variable to exit while loop in sub main() END SUB SUB IBSETUP() ' Define Icon Bar ICON CLEAR ICON 1, FILE ICON 2, INDEX ICON 3,"TableView","TableView" ICON 4,"PageView","PageView" ICON 5,"RecordView","RecordView" ICON 6,"FormView","FormView" ICON 9,"AddRecord","NewRecord" ICON 10,"PrintSub","LabelReq" ICON 11,"TextEditor","MailMerge" END SUB SUB MNSETUP()' Define menu items MENU CLEAR MENU 1,0,1,"&File","","Work with files, forms, and indexes" MENU 1,1,1,"&Print...,Ctrl+P","PrintSub","Print a form, record, file, or status information" (Place on one line in Program Editor) MENU 1,2,1,"P&rint setup...","PrinterSetup","Change the printer configuration" MENU 1,3,1,"Pa&ge setup...","PageSetup","Change page dimensions and other settings" MENU 1,4,3,"","","" MENU 1,5,1,"E&xit","AppExit","Close all files and forms and exit Application" MENU 2,0,1,"&Data","","Use to work with Data" MENU 2,1,1,"&Add","NewRecord","Create a new record" MENU 2,2,1,"&Change,F4","EditRecord","Edit the current record" MENU 2,3,1,"&Remove","","Delete data from the current file" MENU 2,3;1,1,"&Current","RemoveCurrent","Delete the current record" MENU 2,3;2,0,"Ca&scade","RemoveCascade","Delete the current record and linked descendants" (Place on one line in Program Editor) MENU 2,3;3,1,"&Group...","RemoveGroup","Delete a group of records using a filter" MENU 2,3;4,1,"&All","RemoveAll","Delete all records from the current file" MENU 2,4,3,"","","" MENU 2,5,1,"&Update...","UpdateData","Create or run an update" MENU 2,6,1,"&Labels...","LabelReq","Print Labels" MENU 2,7,1,"&Mail merge...","MailMerge","Merge record data with a text document" END SUB REM Error checking routine to trap all errors ERRchk: IF ERRNO = 11 THEN RESUME ' This ensures user cannot interrupt program SELECT CASE ERRNO CASE 10' Trap for EOF (End of File) SET STATUS "End of File" BELL' Sound bell WAIT FOR 1 ' Wait for 1 second SET STATUS statusline$' Restore status line RESUME ' Resume execution at line where error occurred CASE ELSE REQUEST ERR$ ( ERRNO ) + " " + ERR$ (0),"",113 RESUME END CASE Notice the IF ERRNO =11 THEN RESUME command on the same line as the label for ERRchk. This is necessary to elevate error 11 to the highest order of priority to prevent determined users from stopping the program by repeatedly clicking the STOP button or pressing Ctrl+Break. Program: Superbase Versions: 2.0 Date: June 9, 1993 D Date: