.PL Object code Screen Generator (c) Copyright 1987 Project X Development Group Version 1.04, Released 10-September-1987 Hardware Requirements This program is designed to work with IBM PC XT/AT's, PS 2's, and compatibles. The base memory requirement is 320K. This program will function off floppy diskettes, although a hard disk is advisable. OSG will sense the screen you are running with, and will adjust accordingly. Preamble OSG is a full screen editor that requests input from the user, allows this input to be modified and manipulated, stored and fetched from disk, and then creates the program code needed to display that screen. Where OSG contrasts from most screen generation packages, is in the area of screen display. A customary procedure is to use the facilities of a language to display output to the screen. OSG has its own screen driver interface that is linked in to your application code. This driver handles the normal screen problems that are encountered such as 'snow' on CGA monitors. OSG directly generates a machine language program that sends its output to the display via the included driver. The result of this is faster output, and smaller code size. This code is also language independent. The same OBJECT file could, for instance, be used in a C context as well as a FORTRAN or BASIC program. The other benefit is then clear - OSG screens are portable when you make a change from one language to another. OSG screens are also easy to create. The color, drawing characters and general control offered make your screens start looking like symmetrical legacies instead of uncomfortable distortions. Sanctioned Languages As more languages become available, so will OSG's usage increase. Most languages are standardizing with the INTEL 8086 Object format used extensively by such organizations as Microsoft, MANX, Lattice, Nantuckett. Any language that adheres to this format will be able to make use of OSG screens. Microsoft Fortran 1 Microsoft Assembler Microsoft C Microsoft PASCAL Microsoft BASIC Compiler Microsoft QuickBASIC TURBO C Lattice C CLIPPER Some terminology that you should be aware of. If you see a block of text with a box around it like {RETURN} then you know that this refers to a SINGLE key stroke or ALT, SHIFT or CTRL combination. The above illustration means that you have pressed the {RETURN} or {ENTER} key. Other clear examples are {ESC} (the escape key), or {F1} (function key one). An ALT, CTRL or SHIFT combination is highlighted as {ALT+A}, where the '+' indicates that BOTH ALT and A should be pressed (hold down the ALT key and press A). Installing OSG Installing on a floppy disk: To install on a floppy, the contents of the OSG program disk should be copied over to a destination disk. A routine example is copying from drive A to drive B - COPY A:*.* B: Installing on a hard disk: Create a directory for OSG to reside in. Then copy the contents of the OSG diskette to this directory. Files on the support disk: There are two files that you should be concerned about. These files are OSG.EXE and OSG.LIB . OSG.EXE is the program that is run to create screens and object files. OSG.LIB is a library file that contains a driver for writing to the screen. OSG.LIB should be placed in the directory where you keep your LIB files or OBJ files. OSG.LIB will be needed when you link your generated OBJECT file into a program. In version 1.04, a new feature has been added, the ability to generate source program code for QuickBASIC. This is discussed in 'language dependant features'. Compiling and linking screens After you have generated a number of screens you will now wish to include them in your program. The first thing that you do is to COMPILE your program. COMPILING your program will be done with your NORMAL approach - COMPILE a program and then LINK the needed object files later. LINKING in the code is where the step differs. At this point 2 (let's say) you have generated 5 screens called STARTUP, GREET, CUSTOMER, DELETION, FINISHED. Your options are to either place these screens in a LIBRARY file (if your language has a LIB utility), or to LINK the screens in on the command line. Method one: LIBRARIES. You have placed the five screens into a LIBRARY file. Now, when you LINK your code, you append the LIBRARY NAME, and OSG.LIB on the command line AFTER your normal LIBRARIES. Method two: OBJECT FILES. Your LINK statement should have the name of your OBJECT file (the program you are creating - let us say NEWCUST for this example) with the names of the other five OBJECT files appended. This would appear as: LINK NEWCUST+startup+greet+customer+deletion+finished ....... You must also remember to include OSG.LIB with you library parameters. If your language handles LINKING and LIBRARIES in a different fashion, then call us, we have probably dealt with the problem before and will be able to assist you quickly. The various support numbers are listed in the appendix. Getting Started with OSG OSG is invoked by typing OSG at the DOS prompt. OSG's opening menu will be displayed (showing you what version of the program you are running, and any messages applicable to that version). At this point, you press ENTER. You are now at the OSG screen edit mode. From this point, you may issue any of the commands in OSG to create screens, but let us first deal with the command format. Normal typing (characters that have a one key combination entry, and do not include function keys) will produce characters upon the screen, wrapping when the end of the line is reached, and wrapping around to the top when the bottom of the screen is reached. In this fashion, the cursor, delete, insert and backspace keys work in the fashion you would expect an editor to. A few moments of typing and using these keys will give you all the training you need on getting around the screen. Some other editing keys that exist are perhaps not so clear, or are handled differently, in this program than others you might be used to. Page Up and Page Down will move the cursor to the top and bottom 3 of the screen respectively. Home and End will move the cursor to the top left hand corner and the bottom right hand corner respectively. Control and Right arrow, and control and Left arrow will move the cursor to the right and left hand sides of the screen respectively. In addition, the default TAB settings are placed five spaces apart, and may be used by pressing the TAB key, and SHIFT TAB for backwards movement. Two other 'movement' controls exist that do not fit into the discussion here, but will be mentioned for completeness. ALT K will move the cursor BACK to a previous word, and ALT W will move it forward to the next word. Other new features in Version 1.04 include {CTRL+A} which will allow a selection from the character set that is not supported on the keyboard. Altering the viewport Normally, the screen that you will be working with is 80 columns by 24 rows. The last row on the screen (25) is reserved for OSG status use. You may narrow this viewport so that most of the actions that you take will only affect this area of the screen. To modify the viewport, the combination of ALT+A must be chosen. This is the standard command issuing sequence. ALT+A is accomplished by holding down the ALT key, and pressing A. A question appears at the base of the screen as to whether you wish to change the LEFT, RIGHT, TOP or BOTTOM sides of the screen, or simply to expand it back to its full size again. This further option is chosen by pressing the key associated with the option you need. A box or rectangle will then open up on the screen. You will notice that one of the corners is highlighted with a double width drawing character. This is the ACTION corner - any cursor controls issued will affect this corner. You may now move the sides of the screen to where you want it by selecting the cursor keys. To move the highlight (or ACTION corner), press the TAB key, and you will notice the highlight move clockwise. You may also move the box around the screen by first pressing the SCROLL LOCK key and then using the CURSOR or ARROW keys. (CURSOR and ARROW keys have the same meaning in OSG). When you have sized and moved your VIEWPORT to the point you want 4 it, you may exit the selection by pressing ESC or RETURN. Try typing now, and you will notice a different WRAP AROUND. It now happens at the edges of the view port. You do not need to remember all these functions - pressing the HELP key ALT+H will bring up a summary of the functions available. Pressing the associated letter for the key that you need help on will display more detailed information for that option. You can now type and move around the screen, alter your viewport, and fetch help. What we need now is to be able to SAVE and LOAD screens. If you are working on a SCREEN that is detailed, it is a good idea to save it from time to time. Power failures are wondrous events! Saving and Loading Screen images. ALT+Q (Quit) brings up the QUIT prompt. Usually, saving the screen is the last thing that you do before you exit the program. Just to ensure that you haven't forgotton to do this, we placed the SAVE option near QUIT! ALT+Q allows you to SAVE the screen (and optionally quit) or simply to abandon and exit to DOS. Each time that you wish to save a screen, but want to continue editing; the key combination is: ALT+Q S filename {enter} N Try out the above example. To load a screen image into memory from disk, you should press the {ALT+L} combination. Two load options are available: a COMPLETE load, or a MERGE load. If you choose COMPLETE, then the contents of the screen will be completely replaced by the screen image loaded. If you need to keep hold of the current screen image, then ensure that you use the SAVE option before LOADing a screen. A MERGE load will do the following: Any character cell that is not a space in the file BEING MERGED, will replace what is on the current screen. Now that you have designed your screen, you'll want to create an OBJECT file and link it into your application program. Object File Creation OSG directly generates OBJECT code, as described in the following documents: 5 MS-DOS Programmers Reference Manual (P/N 036-014-012) October 1985 issue of PC Tech Journal 8086 Relocatable Object Module Formats, Ver 4.0 (121748-001) The OBJECT code that is generated may be linked into your application using the MSDOS LINK program, or generally a LINK program that was distributed with your programming language. The various LINK options may differ from language to language, and this is best covered in you language manual. You only need to know that you will be linking two files, the screen you have generated (extension of .OBJ) and the video support file (OSG.LIB) . An alternate file - OSG.OBJ is distributed in case you wish to include OSG.OBJ in your LIBRARIES (.LIB) files. NOTE: OSG.LIB or OSG.OBJ MAY NOT BE DISTRIBUTED alone, but only when linked into your program. OSG.EXE is the program that will produce the OBJECT files, but each of these OBJECT files makes reference to OSG.OBJ, which is the video driver. OSG's generated OBJECT files MUST be linked with either the OSG.LIB or OSG.OBJ. If there is any confusion in this matter, please refer to OBJECT linking in your programming manual, or from one of the documents referred to above. In creating an OBJECT file, you may select a RECTANGULAR area of the screen from a few lines and columns - up to the whole screen. OSG then optimizes the contents of the screen and squeezes it in the smallest possible format. If you have a common screen header (let us say the top 3 lines of the screen), then your best approach would be to create an object file that has these three lines, and each program, or section of program, that displays a screen where this standard header is needed simply places a call to HEADER, and then displays the rest of the screen. In this fashion, your programs can become MUCH smaller. Windowing can also be achieved here by overlapping screens (that is calls to screens) at will. This windowing effect is extremely simple to achieve. OSG will prompt you for a file name to create. This file name is the calling name that you will use within your programs, as well as the OBJECT file name. On line Help system The rest of this document follows the Online Help format. Each help section is displayed, then discussed with additional comments where relevant. The Online help system will allow you to gather most of the information about a specific option. You should refer to this 6 manual if you have difficulties. The help system is very easy to follow, and is invoked initially by pressing {ALT+H} and then the key that you wish to recieve help on. If you need help and you do not know what key will perform a function, then just press any presented value, and then you can navigate through the help system to the particular problem(s) that you face. Each help screen has a three alpha numeric character identifier. This identifier begins with H and is in the range of HAA to HBD. This identifier is presented here to allow you to find more information when looking at text upon the screen. HAA This is the help selection screen. You may choose a character off this screen associated with the topic you wish to have help on. This screen is the gateway between Help and the editor. Pressing the {ESC} key will return you to editor mode. HAB, HAC, HAD These are the three screens dealing with the command key functions. They are indexes to other screens, as detailed below. HAE - Altering the viewport The available screen is rows 1 through 24 and columns 1 through 80. The screen is edited through an adjustable 'viewport'. This viewport is initially set up to be the full screen size, but the {ALT+A} combination may be used to adjust this size. There are a number of advantages to using different viewport sizes. If you wish to split the screen into two columns, and place information in one, and then information in the other, you will know that most of the editing that you do will only affect the current viewport. The viewport is changed by using the 'box selection method'. This box selection is described here in full, and other sections will refer to it from time to time as it is a widely used function. Box Selection Throught OSG, there will be occasion to choose a rectangular area upon the screen. This could be a small section or up to the whole screen. The Box Selection method is used, where a rectangular box frame is manipluated, increased and decreased in size, moved until it is over the area that you wish to select. A summary of the command keys for positioning and selecting this box follows. {HOME} Expand the selection box so that it fills the whole screen. 7 {END} Contracts the box size so that it only covers a small central area. When first entering the selection, this or {HOME} is usually one of the first keys pressed in selecting an area. {PgUp} Two functions are accomplished. The rectangle will 'grow' in all dimensions. If a boundary is reached, then this function is disabled, but others exist that allow the box to grow upwards and downwards only, and another that allows it to grow sideways. {PgDn} This performs the opposite of {PgUp} in that the rectangle will shrink. {INS} Increases the width of the selection box on both sides. Again, if a boundary of the screen is reached, pressing {INS} will have no effect. {DEL} Reduces the width of the selection box, performing the opposite of {INS}. {Ctrl-PgUp} Increases the height and depth of the selection box, limited again by the boundary. {Ctrl-PgDn} Performs the opposite of {Ctrl-PgUp} A corner of the selection box is ALWAYS selected. This corner can be discerned by the Double width Corner character that will appear on one of the corners. This selection may be moved by pressing the {TAB} key. The currently selected corner may be expanded or contracted by using a cursor key. When {SCROLL LOCK} is depressed, a cursor key will MOVE the box around the screen, instead of allowing it to expand or contract. Most keyboards have Scroll Lock LED's, but if you are experiencing problems with box sizing, then try {SCROLL LOCK}, and then try your cursor option again. HAF - Using the Numeric keypad to place graphic drawing characters upon the screen. The numeric keypad, either at the right hand of the typewriter pad or on the typewriter pad itself may be used in placing graphic characters upon the screen. (Graphic drawing characters). To toggle this character mapping on or off, the {ALT C} combination is used. 8 HAG - Draw mode This toggles a 'drawing trace' for the cursor on. Wherever you move your cursor to, drawing characters will follow. Either single or double width characters will appear. (See Graphic drawing set change for information on changing between single and double - HAJ ). Draw senses changes in direction, and places the appropriate 'rounding off' character in place. Draw also checks what is in adjacent character position, trying to make the best fit. Draw mode is terminated either by pressing RETURN or ESC. HAH - Erasing rows and columns {ALT+E} brings up the erase menu. From it, you may select to erase a column or a row. Both of these functions will only take place within the currently defined viewport. If you wanted to scroll a section of the screen up, then you could select that area as the viewport, and then just erase a row at the top. Similarly, if you wished to scroll it left (or even right for that matter), you could select the area, and either delete or insert a column. (See INSERT - HAL) HAI - Color Selection This only determines what the color will be of future typed characters. All those on the screen will remain with their current colors / attributes. Selected with {ALT F}. The "Selecting a color" function is used in other areas, so coverage on making the selection is inserted here, and referred to from this point on. A screen with highlighted cells (test patterns) appears on the screen, with a rectangle highlighting one of them. This rectangle may be moved from pattern to pattern, upwards and downwards, left and right by using the cursor keys. {Home} will move the selection rectangle to the top left corner, while {END} will take it to the lower right corner. A color combination for foreground and background is selected by pressing {ENTER} or {ESC} HAJ - Toggle drawing character between double and single line type. Invoked with {ALT+G}, this defines what characters will appear when using DRAW. Also, if Character Mapping (for numbers) is ON, then Number pressing (or entries in macros) will produce the currently toggled line type character. 9 HAK - On Line Help This is invoked by pressing {ALT+H} . A series of menus and help screens will explain most of the features online. You obviously cannot find your reference there, or have not yet used it, otherwise you wouldn't be reading this..... HAL - Inserting a row or column {ALT+I} will allow a row or column to be inserted into the current viewport. The insert will place a blank row or column at the current cursor position. As was discussed previously, with experimentation and also with viewport alteration, this (and erase) are powerful editing features. HAM - Justify a row - left, right or centered. {ALT+J} will strip leading and trailing blanks, and justify the line either left, centered or right. If you wish the line to be left or right aligned with a margin, then all that needs to be done is to alter the viewport so that the margin that you wish the alignment to be on is at one edge of the viewport. As with a number of features of OSG, it is recommended that you SAVE your screen image regularly - to ensure that an 'edit' is not fatal. ('Caution' - My middle name) HAN - Load a previously saved image back into memory. {ALT+L} will either do nothing (in which case you know that there are no files to load), or it will display a scroll box from which you may select a file. These files all have extensions of OSC. If you are using a program or set of programs that already makes use of this extension, we suggest setting up OSG in a directory of its own. (Actually, we suggest you do this at any rate). There are two load options. One (COMPLETE) will erase what is currently in memory, and replace it with the loaded file. The other option (MERGE) is to be used when bringing in a common section (although spaces will be ignored). MERGE is really not the best way to do this. If you need to work with a common section, then use it as the base for designing a screen. What the OSC file looks like is not related to the ACTUAL object file, as the OBJECT file can contain screen primatives, and a number of OBJECT files (calls) can be used in creating just one screen. HAO - Macro Definitions {ALT+M}, the macro definition is a single keystroke feature for placing a number of characters on the screen. When I developed OSG help, I found that a common macro definition was "HA", which I mapped out to function key one (F1), and also "OSG" which I mapped out to function key two (F2). Although I have not had need to use more than 15 or so, there are a possible 40 Combinations. 10 This is achieved by using {SHIFT}, {CTRL} and {ALT} combinations with the function keys (as well as the normal keys). You may save the Macro Definitions to disk in a filename of your own choice. These definitions may be loaded in as needed. HAP - New screen {ALT+N} will allow the current viewport to be erased. The defined colors remain the same however. If you wish to select an area of the screen only (without having to select the viewport), then the Select and Erase function (see HAU) is suggested. HAQ - Create an Object file {ALT+O} invokes Object file creation. Any portion of the screen (even outside of the current viewport) may be selected for OBJECT creation. (See Box Selection) The object file that is created may be directly linked into an application program. It should be remembered that another section of program code (in fact, another Object file) needs to be linked in with the screen that is created. This Object file is needed only once. If you have 12 screens in a program, then your effective total of external OBJect files for running OSG screens is 13. This file is either OSG.LIB or OSG.OBJ . It is important for you to decide which file fits in best with your development. HAR - Creating a print file {ALT+P} will output the content of the screen to a file with an extension of .PRT . This file has all of the color attributes stripped from it, and is a plain ASCII file. The file may be TYPE'd, or included with many word and text processors. It is a useful way of including screens in your documentation. A number of other uses have been found for it .... Bulletin Board Systems, welcome screens Form Designs etc. HAS - Quit (Save or Abandon) {ALT+Q} will allow you to Save the screen you are working with (and then OPTIONALLY quit), or simply abandon the screen. Both options prompt with "Are you sure" before actually quitting. There should be little chance of loosing a screen by a slip of a key. It is recommended that the {ALT+Q} and the save option be used regularly, because you are BOUND to have a power failure when you are in the middle of designing the BEST SCREEN YET SEEN BY MANKIND. HAT- Search & Replace 11 {ALT+R} invokes an option that will allow you to replace characters of a certain type in the current viewport with a single other character. The character that is being replaced may not be a space, and neither may the character replacing another be a space. It is a good practice to SAVE the screen before such a search and replace. HAU - Select an area of the display. {ALT+S} is one of the most powerful commands in OSG. With this command you are able to: Select an area of the screen and a) copy it to another area. b) erase it completely c) fill it with a solid color d) invert the foreground and the background colors e) re-color (change) the current color attributes Selecting an area of the screen is done by using the selection box which has been previously discussed. HAV - TAB Settings {ALT+T} allows the user to clear and set TAB stops. The default settings are at every 5 characters. The TAB key will forward the cursor to the next available TAB stop, whereas the SHIFT TAB function will move the cursor BACK to the previous TAB stop. HAX - Exit to DOS {ALT+X} should be used only when you need to exit to DOS to run a program urgently. YOU MUST NEVER RUN A TSR (Terminate and Stay Resident) program when you have exited to DOS in this fashion. In all likelihood, you will not be able to RETURN to OSG, and in fact will probably CRASH the system. Appendix 1 - New features in OSG version 1.04 OSG now allows the extended character set to be used. This character set consists of the whole 255 characters that are available to the IBM PC and compatibles. To place an alternate character in an OSG screen, use the {CTRL-A} combination, and then select from the table presented. Two additional features have been introduced; using {CTRL- C}, will copy the line above to the current line. (Will have no effect upon row 1). The cursor is then moved down by one row. Using {CTRL-S} will swap the current row with the contents of the row above it (also, it has no effect on the top row). The cursor is moved up by one row. 12 Distribution of OSG OSG must be distributed with all of its component parts. It is suggested that you re-archive them to include your additions to the text file 'route.txt' ROUTE.TXT is an ASCII file which contains the route by which you received the OSG archive, and also (if you follow instructions) the place you uploaded it to and date. An example of this format is: Roy Barrow (76630,110) , UL to CompuServe. 09/01/87 Fred Smith (12345,678) , DL from CompuServe. 09/07/87 Fred Smith , UL to THE BACKROOM SYSTEM (222-222-2222) 09/07/87 Imelda Marcos , DL from THE BACKROOM SYSTEM 09/22/87 Imelda Marcos , UL to CORY's SYSTEM (999-999-9999) 09/22/87 etc. If you decide to register this product with us, then we would like you to send us either a printed copy of ROUTE.TXT, or a file of that name on a floppy disk. (You may send us hard disks if you like. Please ensure that the access time is less than 20ms. Hard disks with capacities of less than 20Mb are considered an insult). What do I get when I register ? Please read the end screen on the version of OSG that you are using for registration details. That will indicate the current level of support. Registering There are a number of ways to do this. 1) Send your check to Inventories Unlimited Inc, 222 Church Street, Philadelphia, PA 19106. 2) If you have VISA, MC or AMEX, call (215) 922-2557 and we will register you there and then, and get the package off to you in the next mail 3) If you want to call our BBS, you may register OSG with us by VISA, MC or AMEX (215) 627-3910. Please do this by leaving a PRIVATE MESSAGE to INVENTORIES UNLIMITED INC., include your full name and address, card type, number and expiration date, telephone number (required) and the level of registration. These orders are processed daily and will be sent to you two days after placement. Support Numbers Please do not call if you have not registered. Registered Users: 13 You may call us at (215) 922-2557 for any questions you might have, and we'll be pleased to answer them. We also run a Bulletin Board System that you might like to call (215) 627-3910. Unregistered users. We would still like to solve your problems. Please send us a SASE and the question you have will be answered. If you wish, you may dial into our BBS (215) 627-3910, and leave your question(s) there. BBBS (BASIC programmers Bulletin Board System) This Board runs 24 hours a day, and is available for access at 1200 or 2400 baud. There are a number of fine BASIC programs on this system, and it looks like becoming a complete QuickBASIC support system / outlet. Call us, and download & upload BASIC programs. 14