Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / DATABASE / PROCLIP.ZIP / PROCLIP.DOC next >

Wrap

Text File | 1987-08-23 | 29.3 KB | 859 lines

PROCLIP.LIB - Professional Clipper Library - Version 1.00 ======================================================================== Copyright Acknowledgments CLIPPER is a Trademark of Nantucket, Inc. IBM is a Trademark of International Business Machines. Tom Rettig Library is a Trademark of Tom Rettig & Assoc. Microsoft Overlay Linker is a Trademark of Microsoft Corp. PLINK86plus is a Trademark of Phoenix Technologies, Ltd. ======================================================================== The Professional Clipper Library (PROCLIP.LIB) is not designed to replace the standard Nantucket Clipper Library (Winter '86), simply to enhance its capabilities. Some of the routines contained in PROCLIP are undoubtedly contained in the next release from Nantucket but I needed them now so I wrote them. Also, as I am an avid fan (and registered owner) of the Tom Rettig Library, I have taken precautions not to duplicate his work. I have coded some routines similar to his which have enhancements, but I will not attempt to "reinvent the wheel." The purpose of this library is to provide the programmer with additional tools that Nantucket and Tom haven't gotten around to releasing yet. I am releasing this software under the concept that most of us pay for what we use and appreciate. Those in the crowd who must steal from others can have at it, but your ears will become infested with the fleas of a thousand camels. If these functions are useful to you and you would like to encourage the creation of more a registration fee of $25.00 is suggested and appreciated. I also encourage more input into the creation of other functions. Every one of these functions were created from input from other CLIPPER users such as yourself. I'm not too good at dreaming these things up but I can follow directions pretty good. Now I'm not egotistic enough to say I can write anything, but give me an idea of what you'd like and I'll see what I can do. I will do my best to correct any programming problems (bugs) which are located and brought to my attention. I will not, however, be held responsible for any damages either real or imagined from the use of PROCLIP. Also, if any of you would like to obtain the source code for this library please send your request, along with an additional $25.00 to the address listed below. Currently all source code is 8088 assembler and heavily documented. For registration .or. source code: Genesis Development 3504 Jasmine Lane Rowlett, Texas 75088 Source ID: NAN779 CompuServe: 71410,2051 Page #1 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== PROCLIP Usage: As I am particularly fond of the UDF (user defined function) command type, most of my examples will be using them. Only in a few cases must we mandate the use of the procedure call format. The UDF type simply makes for cleaner looking code. In almost all cases the functions are checking the parameter count, types and values to prevent runtime problems. The library is using the published CLIPPER vector names for parameter retrieval and return (EXTENDA). Hopefully this will prevent this library from becoming obsolete with new versions of CLIPPER. Use of this library is identical to that of any other library designed for use with CLIPPER: With MicroSoft Linker - C>LINK Microsoft (R) Overlay Linker Version 3.51 Copyright (C) Microsoft Corp 1983, 1984, 1985, 1986. All rights reserved. Object Modules [.OBJ]: YOURPROG Run File [YOURPROG.EXE]: List File [NUL.MAP]: Libraries [.LIB]: CLIPPER + PROCLIP With PLink86 - C>PLINK86 PLINK86plus ( Nantucket ) Version 2.21 Copyright (C) 1984, 1985, 1986 by Phoenix Technologies Ltd., All Rights Reserved. =>FI YOURPROG =>LIB CLIPPER =>LIB PROCLIP Page #2 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== * * * NOTICES & WARNINGS * * * If you are using PROCLIP with any other library which contains the same function names (eg. SCROLL) you will see some warning errors generated by whichever linker you are using. If you like the PROCLIP function better than the others just make certain that PROCLIP is the first library in the list after the CLIPPER library is specified. Neither linker appreciates a bunch of functions with the same names but they both will use the first function of that name that they encounter. If you specify a function in CLIPPER you cannot specify it as a procedure in a different module of the same program and vice versa. What this means is...be consistent. If you use one of the routines as a function (eg. newattr(10,20,12,60,'n/w') ) you cannot use it in a different module of the same program as a procedure (eg. call newattr with 10,20,12,60,'n/w'). CLIPPER will scream it's head off at you so you don;t have to worry about it compiling incorrectly. Page #3 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== Function Name: SCROLL I know, I know, who doesn't already have a SCROLL routine. The Nantucket (DBU.LIB) and Rettig (TR86.LIB) libraries have nice scroll routines but neither one of them let you control the attribute of the blank line left behind. In some of my applications this got to be a real pain so I decided to fix it. After studying both Nantucket and Rettig's SCROLL routines I decided that Tom had the most sensible call format so I borrowed it. We won't mention the fact that I was also used to using it. Format: As a function - scroll(top,left,bottom,right,lines,dir[,attr]) As a procedure - call scroll with top,left,bottom,right,lines,dir[,attr] Parameters: top.......topmost row of the area to be scrolled. Value checked to be between 0 and 24 inclusive. left......leftmost column of the area to be scrolled. Value checked to be between 0 and 79 inclusive. bottom....ending (bottommost?) row of the area to be scrolled. Value checked to be greater than TOP but less than or equal to 24. right.....rightmost column of the area to be scrolled. Value checked to be greater than LEFT but less than or equal to 79. Lines.....number of lines to be scrolled, or zero (0) to scroll entire window (effectively erasing it). Value checked to be equal to or less than BOTTOM - TOP. Dir.......non case sensitive character variable or constant containing a flag indicating the direction of the scroll (u = Up & d = Down). Attr......non case sensitive character variable or constant containing a valid color command and combination for character and background. Must be the alpha representation of the color, the numeric will be rejected. This is NOT a mandatory parameter. If you do not furnish it in the command line the function will use the attribute currently on the screen for the character in the TOP, LEFT position. Page #4 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== SCROLL (cont'd) (valid colors) black N blue B green G cyan BG red R magenta RB brown GR white W intense + blink * Examples: 1. This will scroll one line down in the area from row #10, column #20 through row #12, column #60 using an attribute of black character (n) and white background (w). . . . scroll(10,20,12,60,1,'d','n/w') (or call scroll with 10,20,12,20,1,'d','n/w') . . . 2. This will scroll one line down in the area from row #05,column #00 through row #20, column #79 using whatever the attribute of the character at 10,20 currently is. . . . scroll(05,00,20,79,1,'d') . . . Returns: Not a thing. This function will either perform the function or ignore the request because of some parameter problem. Page #5 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== Function Name: NEWATTR This function was created for those of us who wish to highlight a particular area of the screen without having to bother setting colors and rewriting the text. This is real useful if you'd like to highlight a menu item or prompt area without having to rewrite it. When called with the proper parameters the function will change the attribute of the specified area (box). NEWATTR in its current form uses the IBM standard BIOS interrupt for writing to the screen. Given this it will not "pop" onto the screen on computers with slower clock cycles (4.77MHz - 6.0MHz). If the need arises I will write a different version to do direct screen writing. Format: As a function - newattr(top,left,bottom,right,attr) As a procedure - call newattr with top,left,bottom,right,attr Parameters: top.......topmost row of the area to be changed. Value checked to be between 0 and 24 inclusive. left......leftmost column of the area to be changed. Value checked to be between 0 and 79 inclusive. bottom....ending (bottommost?) row of the area to be changed. Value checked to be greater than TOP but less than or equal to 24. right.....rightmost column of the area to be changed. Value checked to be greater than LEFT but less than or equal to 79. Attr......non case sensitive character variable or constant containing a valid color command and combination for character and background. Must be the alpha representation of the color, the numeric will be rejected. Page #6 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== NEWATTR (cont'd) (valid colors) black N blue B green G cyan BG red R magenta RB brown GR white W intense + blink * Examples: 1. This will change the character attributes from row #10, column #20 through row #12, column #60 to intense blinking red on a black background (somebody must have hit the wrong key). . . . newattr(10,20,12,60,'*+r/n) . . . 2. This will change the character attributes from row #05, column #10 through row #05, column #15 to inverse with black characters. . . . t = 05 l = 10 b = 05 r = 15 newattr(t,l,b,r,'n/w') . . . Returns: Not a thing. This function will either operate with the given parameters of reject them due to validity checking. Page #7 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== Function Name: SAVEBOX In Clipper if you want to use the neat BOX command to prompt for a parameter or issue a warning and restore the screen to its original beauty and luster, you have to save the entire screen to a memory variable and then restore it. This is fine but if you get too many saved screens you'll run smack out of memory. Each screen as saved by CLIPPER requires a minimum of 4096 bytes. Tom Rettig was nice enough to allow us to slam that puppy on the disk but even this causes more trouble than necessary. The concept behind the SAVEBOX function was to allow the programmer to save only a specific section of the screen into a pre-defined memory variable. Using this you can save all the screen (4096 bytes) or only one character (2 bytes) or anywhere in between. As this procedure requires a pre-defined character memory variable to contain the screen data please ensure you define the variable as this document suggests (sizewise). This procedure is just that, a procedure. Do not call it as a function because CLIPPER will not allow me to return the character memory variable intact with all the goodies. Format: As a function - none As a procedure - call savebox with top,left,bottom,right,scrnarea Parameters: top.......topmost row of the area to be changed. Value checked to be between 0 and 24 inclusive. left......leftmost column of the area to be changed. Value checked to be between 0 and 79 inclusive. bottom....ending (bottommost?) row of the area to be changed. Value checked to be greater than TOP but less than or equal to 24. right.....rightmost column of the area to be changed. Value checked to be greater than LEFT but less than or equal to 79. Page #8 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== SAVEBOX (cont'd) scrnarea..a pre-defined character memory variable which will contain the screen data (and some control information) upon return. If the memory variable is not large enough to contain the total screen data requested it will be filled with whatever I can stuff into it. Use this algorithm (Texan for cipher) to allocate the memory variable properly: (((right - left + 1) * 2) * (bottom - top + 1)) + 6 The extra six (6) bytes on the end are for my control information. See RESTBOX for usage of these. It does not matter what the name of the memory variable is as long as it is a character type. Use the SPACE command to allocate the variable. Examples: 1. To save the screen data, and current attributes, into a memory variable from row #10, column #20 through row #12, column #60. . . . scrn1 = space((((60 - 20 + 1) * 2) * (12 - 10 + 1)) + 6) call savebox with 10,20,12,60,scrn1 . . . Returns: The character memory variable will contain the data as it was read from the screen preceded by six (6) bytes of control information. If this variable is released or otherwise changed the RESTBOX function may not operate as you intended. Page #9 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== Function Name: RESTBOX This function doesn't work too well if you don't use SAVEBOX first. RESTBOX will restore a saved SAVEBOX memory variable to the screen using either the original coordinates or different coordinates provided by the programmer. Creative use of SAVEBOX, BOX and RESTBOX can move stuff all over the screen making the user think you're a real wizard! RESTBOX in its current form uses the IBM standard BIOS interrupt for writing to the screen. Given this it will not "pop" onto the screen on computers with slower clock cycles (4.77MHz - 6.0MHz). If the need arises I will write a different version to do direct screen writing. Format: As a function - restbox([top,left,]scrnarea) As a procedure - call restbox with [top,left,]scrnarea Parameters: top.......topmost row of the area to be changed. Value checked to be between 0 and 24 inclusive. This is NOT a mandatory parameter, however if TOP is specified then LEFT must also be specified. If TOP,LEFT is not specified RESTBOX will obtain the original position from within the SAVEBOX'd variable. left......leftmost column of the area to be changed. Value checked to be between 0 and 79 inclusive. This is NOT a mandatory parameter, however if LEFT is specified then TOP must also be specified. scrnarea..a character memory variable containing a saved portion of the screen. This area must have been saved by SAVEBOX. No changes to this memory variable should have occurred between the SAVEBOX command and RESTBOX. Page #10 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== RESTBOX (cont'd) Examples: 1. This will restore a previously saved screen area to the original location. . . . restbox(scrn1) . . . 2. This will restore a previously saved screen area row #10, column #20 even if this is a different location than it was originally obtained from. . . . restbox(10,20,scrn1) . . . 3. A typical SAVEBOX and RESTBOX combination. . . . scrn1 = space((((60 - 20 + 1) * 2) * (12 - 10 + 1)) + 6) call savebox with 10,20,12,60,scrn1 . . . restbox(scrn1) . . . Returns: Not a thing. The screen area is restored per instructions. If the new TOP,LEFT of the screen area forces the BOTTOM,RIGHT of the area off the screen the program will restore what it can to the screen stopping at the 79th column and 24th line. Page #11 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== Function Name: CURSOR Rumor control has it that future versions of CLIPPER will have a cursor handling function built in, but that it still won't give the control this function gives. Many is the time I wished I could set the cursor to a different size, or make it disappear. Well I wished one time too many and wrote this function to solve the problem. Since I do not have access to one of the new nifty keen hi resolution monitor types recently released by Big Blue I haven't a clue how this will function. I am assuming two monitor types, color (or B&W) and monochrome in this function. If you have a different type of monitor I would be interested in hearing how this works. Format: As a function - cursor('[std,off,half,full]') As a procedure - call cursor with '[std,off,half,full]' Parameters: std.......sets the cursor to the default for the current monitor type. Parameter may be either a literal (as in the examples) or a memory variable. Case is insignificant as the function will perform case conversion prior to validation. If this is a color monitor then the cursor will be activated for video scan lines 6 thru 7. For a monochrome monitor the standard activated scan lines are 12 thru 13. off.......sets the cursor off. The cursor will not show on the current monitor. Parameter may be either a literal (as in the examples) or a memory variable. Case is insignificant as the function will perform case conversion prior to validation. half......sets the cursor to one half of the total character size for the current monitor type. Parameter may be either a literal (as in the examples) or a memory variable. Case is insignificant as the function will perform case conversion prior to validation.On a color monitor this is scan lines 4 thru 7 and on a monochrome monitor is scan lines 7 thru 13. full......sets the cursor to cover the total character position for the current monitor type. Parameter may be either a literal (as in the examples) or a Page #12 Copyright (c) 1986, 1987 by Genesis Development PROCLIP.LIB v1.00 Documentation August 23, 1987 =========================================================================== CURSOR (cont'd) memory variable. Case is insignificant as the function will perform case conversion prior to validation. Examples: 1. Set the cursor to one half of the current size and then turn it off for some other activity. . . . cursor('half') . . . cursor('off') . . . Returns: Nothing. Cursor is modified per the request or if the request is invalid the command is ignored. Page #13 Copyright (c) 1986, 1987 by Genesis Development