CD Actual 15

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / basic / PSCRN42.ZIP / ROUTINES.DOC < prev next >

Wrap

Text File | 1990-09-02 | 33.1 KB | 761 lines

P-Screen Professional (tm) Supplementary Quick Reference Guide to: QuickBASIC Subroutines Included with P-Screen Professional PDS 7 Subroutines Included with P-Screen Professional +---------- For information or support, call or write -----------+ | | | Pro~Formance 132 Alpine Terrace San Francisco, Ca. 94117 | | | | Phone: (415) 863-0530 (10-5 Pacific time please) | | | | | | Your feedback, suggestions and comments are always welcome. | +----------------------------------------------------------------+ Copyright (C) 1988-1989, Rob W. Smetana and Pro~Formance P-Screen, it's manual and supporting materials are protected by U.S. and International Copyright Laws. All Rights Reserved. P~F Screen Design, P-Screen, P-Screen Professional, P~F Presents, PFP, Pro~Formance, and P~F are Trademarks of: Rob W. Smetana & Pro~Formance Overview ======== This supplementary manual explains how to call our subroutines from QuickBASIC or PDS 7 programs. We send these routines to registered users of P-Screen Professional. These routines are included in PS-Demo.Qlb and BC7-Demo.Qlb to help you run two demo programs we've included: Employee.Bas and Toorder.Bas. We'll first summarize each routine. We'll then explain how to use each routine. IMPORTANT NOTES =============== * PDS 7 routines have names starting with "7." So, for example, "7rsMinpt.Obj" is the PDS 7 version of rsMinput. The QuickBASIC version is "rsMinput.Obj" - ONLY the "string" routines differ between PDS 7 and QuickBASIC 4.x. That's because the PDS 7 routines were compiled with the "/fs" switch (FAR STRING). - If your PDS 7 programs DON'T use Far Strings, use the QuickBASIC versions rather than the "7" versions. - Use the SAME "screen restore" routines in QB or PDS 7. QuickBASIC Version Purpose PDS 7 Version =========== ------------------ ============= rsMinput.Obj User Input Routine 7rsMinpt.Obj LoadScrn.Obj Screen Library Load 7LdScrn.Obj PropName.Obj Text "Proper Name" 7PropNam.Obj FmtUsing.Obj Format #s for printing 7FmtUse.Obj rsQprint.Obj Assembler "Quick" print 7rsQprt.Obj * rsMinput.obj contains 4 other subroutines: OneKey, Mask, StripMask and StripTrail. * rsMinput REQUIRES rsQprint to handle text printing. If you link rsMinput to your programs, you must also link rsQprint. * ALL numeric variables MUST be integers (except in FormatUsing). If you do otherwise, these routines will crash. Adding Subroutines to your Programs ................................... You can add these subroutines to your programs in one of two ways. The easiest is to add these subroutines to any library you use with QuickBASIC. Then create a Quick Library out of the ".LIB" file. This allows you to call the routines from QB's editor while you're testing your programs. Here's how: Alternative 1 ............. Lib MyLib +rsMinput +rsQprint +rsCmpRst +FmtUsing +PropName; (this adds our routines to your ".LIB" file MyLib) Link /q/seg:256 MyLib.Lib, MyQuick.Qlb, , bqlb45; (this creates a QuickBASIC Quick Library out of MyLib.Lib) (you must include ".Lib" or Link assumes you mean ".Obj") - Replace "MyLib" and "MyQuick" with the names of your library and Quick library, respectively. Next, compile your program and link it to your library. bc MyProg /o; Link MyProg, , BCom45 + MyLib /exe; Alternative 2 ............. In this alternative, you don't add routines to libraries. Instead you compile your program, then link it to one or more of the ".obj" files we sent you. For example: bc MyProg /o; Link MyProg +rsMinput +rsQprint , ,BCom45 /exe; 1 Overview of Subroutines ======================= Routine Name Purpose ============ ================================================== rsMinput Handle ANY type of user input: A single key (like a menu choice), a full 80 columns of text, function keys, cursor pad keys, file names, anything! - rsMinput REQUIRES rsQprint (to handle printing). - "M" means Mask. rsMinput will format data entry using a mask you supply. For example, for Phone Numbers, use a mask like (...) ...-.... rsMinput accepts input where "." appears, and automatically skips over parentheses, spaces, hyphens, etc. - You specify the Length of each field (# of charac- ters) and which keys are Valid (eg., numbers only, A-D for 4 menu choices, upper case for file names). - You can ask rsMinput to exit on "extended keys," and report which one was pressed. This might include function keys, cursor pad keys, Alt-key combinations, etc. - P-Screen uses rsMinput to handle every key you press! OneKey Gets one key from the user -- a menu choice, cur- sor pad or function keys, etc. You specify which keys are "valid." Mask & Used by rsMinput for "formatted input," you can StripMask also call Mask directly to print formatted text. StripTail Strips any character from the end (tail) of text strings. StripTrail is particularly useful for striping Null characters (Chr$(0)) from file records. rsQprint Assembler routine to quickly print text on the screen. You tell it where to print (row & column), which color to use, and which string to print. FormatUsing Converts a number into a "formatted" string for editing or printing. It includes ALL of BASIC's "Print Using" options to insert dollar signs, commas, decimal points, etc. -- at your option. ProperName Type "john smith" or "san francisco" and ProperName returns it properly capitalized (ie., it returns "John Smith" and "San Francisco"). Speeds typing. Exist A QuickBASIC function to tell if files exist (before you try to open or write over them). Helps eliminate the need for "On Error." 3 Subroutine: rsMinput .......................... rsMinput handles virtually any type of user input: a single key, a full 80 columns of text, extended keys (function keys, cursor pad), printer control codes, etc. It will also "mask" data input (thus the "M"), giving you formatted input for things like phone numbers and Zip Codes. Calling format .............. Locate Row%, Column% Call rsMinput (Text$, Valid$, Exit$, Msk$, Length%, RetCode%, _ Colr%, HiLite%) Notes: - We must "Locate Row, Column" before calling. - Call rsMinput with 8 variables (4 strings and 4 integers) - Two variables (Exit$ and RetCode%) have "Double Duty" -- they mean one thing when you call rsMinput, and rsMinput changes them on exit letting you know how the user exited. Because they're changed, you MUST initialize them each time you call rsMinput. Variable Purpose ============ ================================================== Text$ Is the string you want to edit. - If it's blank, you can enter new text - If there's something there, you can edit it or add to it The maximum length is 80 characters. Valid$ Is a list of "valid" keys the user may press. - This could include ANY keyboard character, PLUS all extended codes PLUS low/high Ascii characters. - Or, it could include just numbers. - Or, it could be 5 letters corresponding to 5 menu choices. rsMinput processes only Valid keys (plus Exit$ keys and <cr> and Esc). It ignores all other keys. 4 rsMinput (continued) Variable Purpose ============ ================================================== Exit$ rsMinput normally exits when <cr> (Enter) or Esc Double is pressed. If you want rsMinput to exit when Duty other keys are pressed, list them in Exit$. - On Input: Assign "key codes" to Exit$ telling rsMinput which other keys to exit on. This can include function keys, cursor pad keys, etc. -- The screens "CursAlt" and "Function" in P-Screen.Psl list almost all key codes you need. -- Most of these keys return two bytes (Chr$(0) plus a scan code). List ONLY the scan code. -- Example: Exit$ = ";" + Chr$(16) to tell rsMinput to exit if F1 or Alt-Q is pressed. - On Exit: Exit$ = the last key pressed. This could be <cr> (Chr$(13), Esc (Chr$(27)), or F1 (;). -- Note, we strip the leading Chr$(0) from F1. -- You can test Exit$ to see what action to take. See RetCode% for an alternative. Msk$ This is a "mask" rsMinput uses for masked or formatted editing. - A mask is optional. If it's null or blank, input won't be formatted. - Example: Msk$ = "Enter a phone number: # (###) ###-####" - Msk$ works something like BASIC's Print Using. You enter "#" wherever you want data, other characters as a text prompt or for formatting. - Unlike Print Using: 1) Msk$ works with numbers OR text; and, 2) the mask may have up to 79 characters (unlike Print Using's 24). - rsMinput waits for input wherever you put "#". It skips over everything else. - rsMinput strips the mask on exit, returning to you just the edited text. Length% This is the maximum length you'll accept (ie., the number of characters). - If Length% = 1, rsMinput exits immediately when one of the VALID$ keys is pressed (See below) - If you forget (LIMIT%=0), you get 1 char. back - If you send down a mask, the number of "#" in the mask overrides Length. 5 rsMinput (continued) Variable Purpose ============ ================================================== RetCode% On Input: Double - Set RetCode% equal to the Ascii code of the Duty character you want blank areas of the field filled with (useful for highlighting fields). -- We use RetCode% = 32 (Ascii code for Space), then use Hilite% to highlight the field we're editing. But you can use ANY Ascii character (try 176, 250, 196 and 240). - If on entry RetCode% is NEGATIVE, rsMinput capitalizes all user input. (eg. -32). On Exit: - RetCode% = -27 or -13 if Esc or <cr> was pressed. - If one of your Exit$ keys was pressed, RetCode% returns equal to it's order in Exit$. For example, if Exit$ = ";" + Chr$(16), and the user pressed Alt-Q, RetCode% would be 2. Colr%/ Colr% is the color you want the field restored HiLite% to on exit. HiLite% is the color you want during editing. - Both colors are integers containing BOTH foreground and background attributes. - Use this formula to calculate each: (Back% And 7) * 16 + Fore% where "Back%" is the background, and "Fore%" is the foreground color you want. This formula can't create blinking colors. Notes on using rsMinput ....................... * Notice you have 2 ways to highlight the field during editing. - Use color by setting HiLite% to a contasting color (reverse?). - Or, set RetCode% equal to some interesting looking character. - Or, do both. * rsMinput has FULL EDITING KEY capability. The screen "EditHelp" in P-Screen.Psl summarizes rsMinput's editing features. Feel free to include this screen in your programs. - Be sure to notice Alt-U (undo) - Also note that certain keys are needed for editing. So you can't include them in Exit$. (left/right cursor, home, end, delete-to-end, delete Line, next word, last word, insert) 6 rsMinput, Examples Here are some examples showing how to initialize and call rsMinput. rsMinput Example 1 .................. '--- 1st, define a function to easily handle color calculations Def FnColr%(Fore%,Back%) = (Back% And 7) * 16 + Fore% Msk$ = "##### - ####" 'format this as a zip code Exit$ = ";<=>" 'exit on F1, F2, F3 or F4 Valid$ = "1234567890" 'accept numbers only for zip code RetCode% = 32 'pad the field with spaces Colr% = FnColr% (7, 1) 'restore color to White on Blue Hilite% = FnColr% (0, 7) 'while editing, use Black on White Locate 12, 25 Call rsMinput (Text$, Valid$, Exit$, Msk$, Length%, RetCode%, _ Colr%, HiLite%) Select Case RetCode% Case -13 'Enter pressed ...do something Case -27 'Esc pressed ...do something Case 1 'F1 pressed (1st character in Exit$) Gosub DisplayHelp Case 2 'F2 pressed (2nd character in Exit$) ...do something Case 3 'F3 pressed etc. ...do something Case 4 'F4 pressed ...do something Case else end select rsMinput Example 2 .................. In this example we "hardcode" -- Length%, Colr%, and HiLite%. Also notice Msk$ is nul (""). Exit$ = "D" 'exit on F10 Valid$ = AnyChar$ 'accept any keyboard character RetCode% = -250 'pad with Chr$(250) AND capitalize it Locate 8, 55 Call rsMinput (Text$, Valid$, Exit$, "", 80, RetCode%, 23, 112) Select Case RetCode% Case 1 'F10 pressed . . Case else End Select 7 rsMinput, Examples (continued) rsMinput Example 3 .................. In this example we only want cursor pad keys -- no text editing. Text$, Valid$, Msk$ are all null, we want only 1 key, and Colr% and Hilite% are the same (and irrelevant). We could also "Call OneKey ...." -- a more efficient way to get just 1 key. Exit$ = "GHIKMOQ" 'extended codes for cursor pad keys Locate 25, 79 Call rsMinput ("", "", Exit$, "", 1, RetCode%, 112, 112) Select Case RetCode% Case 1 'Home pressed Case 2 'Up Cursor pressed . . Case 7 'PgDn pressed (7th character in Exit$) . . Case else End Select 8 Subroutine: OneKey ........................ OneKey calls rsMinput. It's designed to get 1 key from the user (a menu choice, Yes/No, function keys, cursor pad keys, etc.). * Calling OneKey is simpler than calling rsMinput, since we know we want just one key, and Msk$ is irrelevant. * Text$, Valid$, Exit$, RetCode%, Colr%, and HiLite% work the same in OneKey as in RsMinput. * OneKey ALWAYS capitalizes Text$ on exit. So, be sure to set up Valid$ with ONLY upper case letters. Calling format .............. Locate Row%, Column% Call OneKey (Text$, Valid$, Exit$, RetCode%, Colr%, HiLite%) Notes: - How you set up Text$ before entry determines whether OneKey prints the character pressed. -- If Text$ is null ("") OR Chr$(0), we WON'T print any keys pressed. -- If Text$ is a space (" ") or a character, we WILL print it. - Call OneKey with 6 variables (3 string and 3 integer variables) - Two variables (Exit$ and RetCode%) have "Double Duty" -- they mean one thing when on entry, another on exit (the same as rsMinput). Refer to the section on rsMinput for an explanation of variables. OneKey Example 1 ................ Text$ = " " 'we DO want user input printed Valid$ "ABCD" '4 menu choices (note Upper Case!) Colr% = 23 'restore color to White on Blue Hilite% = 112 'while editing, use Black on White Call OneKey (Text$, Valid$, "", RetCode%, Colr%, HiLite%) On Instr (Valid$, Text$) Gosub Do.A, Do.B, Do.C, Do.D (if Enter or Esc is pressed, we'll fall thru "On Instr..." to here) 9 OneKey Example 2 ................ Here we just want function keys (so Text$ & Valid$ are null). We end on Esc. Note both colors are 0. They're irrelevant since we won't print user input (because Text$ = ""). Do Until RetCode% = -27 'loop until you press Esc FunctionKey$ = ";<=>?@ABCD" 'the screen "Function" gave us these Call OneKey ("", "", FunctionKey$, RetCode%, 0, 0) Locate 12,22: Print "You pressed "; Select Case RetCode% Case is 1 to 10 Print "function key F"; RetCode%; Case -27 Print "Esc. I'm ending"; Case -13 Print "Enter"; End Select Loop 10 Subroutine: Mask ........................ Mask is part of rsMinput's ".obj" module. rsMinput calls Mask to format text for "formatted data entry." You can also CALL Mask to format text for printing. Calling format .............. CALL Mask (Text$, Msk$) Text$ The text to be formatted. Msk$ The mask to use for formatting. Notes: - Text$ can be text or numbers (in string form). - To create a "mask," use "#" wherever you want Mask to insert a character from Text$. Use other characters (or words) to "visually format" the field, or to prompt the user. - Mask converts "#" to more discrete dots. - BE SURE to read the section on RSET in P-Screen's manual. Mask Example 1 .............. Text$ = "94117" Msk$ = "Our Zip Code is: ##### - ####" Call Mask (Text$, Msk$) Locate 12, 30: Print Text$ '....this prints Our Zip Code is: 94117 - .... Subroutine: StripMask ........................ StripMask (part of rsMinput.obj) strips the mask from a string, and returns just the valid text. rsMinput does this automatically. Calling format .............. Msk$ = "(###) ###-####" Text$ = "4158630500" Call Mask (Text$, Msk$) 'Text$ is now "(415) 863-0500" CALL StripMask (Text$, Msk$) 'Text$ is now "4158630500" Notes: - The mask you send to StripMask (Msk$) MUST be the same mask you used when calling Mask. If masks are different, StripMask won't be able to strip it properly. 11 Subroutine: StripTrail .......................... StripTrail (part of rsMinput.obj) strips any 1 character from the end of a string. Originally developed before Microsoft added RTrim$ and LTrim$, it's still useful for stripping Chr$(0)'s from Random record files. And it's called by rsMinput to strip the "prompt character" from Text$. "Prompt character" is the character you assigned with "RetCode% = #" (250, for example). Calling format .............. Call StripTrail (Text$, WhichChar$) Notes: - Text$ is the string you want stripped. WhichChar$ is the character you want stripped. - StripTrail strips WhichChar$ only from the end of Text$. It stops looking when it hits a character different than WhichChar$. StripTrail Example 1 .................... Call StripTrail (Text$, Chr$(0)) 'strips Chr$(0) from records read from a Random file 12 Subroutine: rsQprint .......................... rsQprint is an assembler routine to print text to the screen. It's required by rsMinput and OneKey to display text. Calling format .............. CALL rsQPrint(Row%, Column%, Colr%, Text$) Row%/ The screen row and column where you want text Column% printed. Colr% The color. Use the formula (or function "FNColr%") discussed under rsMinput to set Colr%. Text$ The text to be printed. If (Column% + Len(Text$)) exceed the number of columns on your screen, text will wrap to the beginning of the next line. Subroutine: ProperName .......................... ProperName is a QB function which returns a string properly capitalized in "proper name" format -- the 1st letter of each word capitalized. Because it's a function, it MUST be declared in QuickBASIC programs before it's called. Note: In its current form, ProperName won't properly capitalize names like MacDonald or McDonald (with 2 capital letters). If this presents problems, let us know. We can revise it -- though it would grow in size. Calling format .............. Declare Function ProperName$ (Text$) 'required Text$ = ProperName$ (c$) 'assign New variable Print ProperName$ (Text$) 'print in proper format ProperName Example 1 .................... Text$ = "san francisco" Print ProperName$ (Text$) '(prints "San Francisco") ProperName Example 2 .................... Input "Enter your name (all lower case): "; MyName$ Print "Your name is "; ProperName$ (MyName$) 13 Subroutine: FormatUsing .......................... FormatUsing is a QB function that works just like BASIC's Print Using statement. But instead of printing something it returns a "formatted" string. You can edit the string, insert it into another string, print it or save it. Because it's a function, it MUST be declared in QuickBASIC programs before it's called. Calling format .............. Declare Function FormatUsing$ (Format$, x#) 'required, note x# is 'double precision Format$ = "$$#####,.##" 'assign currency Format$ x# = 99 Text$ = FormatUsing$ (Format$, x#) 'Text$ is now "$ 99.00" Notes: - Since FormatUsing$ works exactly like BASIC's Print Using, refer to a BASIC manual for details on including "#," "$," "," etc. P-Screen's manual has some of these details. - If Format$ is too short for the number, FormatUsing returns "%" as the 1st or 2nd digit (just like Print Using). - Format$ must not be longer than 24 charac- ters (just like Print Using). - In many cases, Text$ must be initialized with enough spaces to handle what's returned by FormatUsing. If Text$ is too short, your number will be truncated. - Finally, RSET is often required to properly format certain numbers like phone numbers. FormatUsing Example 1 ..................... Format$ = "(###) ###-####" x# = 4158630500 Text$= Space$(10) RSET Text$ = FormatUsing$ (Format$, x#) 'Text$ is now: '"(415) 863-0500" FormatUsing Example 2 ..................... Format$ = "(###) ###-####" x# = 8630500 Text$= Space$(10) Text$ = FormatUsing$ (Format$, x#) 'Text$ is now: '"(863) 050-0..." ERROR This example shows how errors can occur if RSET is not used when it should be. Format$ has 10 digit positions (ie., 10 "#s"). But our number has only 7 digits. If we had said: RSET Text$ = FormatUsing$ (Format$, x#), Text$ would read (...) 863-0500. 14 Subroutine: Exists .......................... Exists is a QB function to tell if a file exists before you try to open it. We use it in P-Screen's demo programs to see if a screen library exists before we try to read help screens from it. Because it's a function, it MUST be declared in QuickBASIC programs before it's called. Calling format .............. Declare Function Exists (FileName$) 'required FileName$ = "P-SCREEN.PSL" 'NOTE: Be certain 'FileName$ contains NO 'wild cards (No * or ?) 'See Notes for why. If NOT Exists (FileName$) then 'if not here, Exists = 0 Print "Sorry, help screen library wasn't found" else 'Exists = -1, it exists Gosub DisplayHelp End If Notes: - Exists returns -1 if a file exists, and 0 if it does not. - If the File Name you sent down contains wild cards (* or ?), Exists exits immediately, and is set to 0 (doesn't exist.) This pre- caution is to ensure you don't delete ALL files on a disk or directory (see next point). - Exists simply checks the file length to determine if it exists. If a file's length is 0 bytes, Exists DELETE'S the file and returns 0. Zero-length files are very rare. But if for some reason you use empty, zero-length files for some legitimate purpose, DON'T use Exists to check for THEIR existence.