Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / GET10.ZIP / GET.DOC next >

Wrap

Text File | 1988-11-09 | 73.1 KB | 1,780 lines

THE GET UTILITIES Version 1.0 9th Novemer, 1988 Copyright (c) 1988 Paul O'Nolan ┌──────────────────────────────────────────────────────┐ │ All you can take with you is what you've given away. │ └──────────────────────────────────────────────────────┘ Old Arab saying Table of Contents Preface ....................................................... 2 Distribution of this package .................................. 4 Acknowledgements .............................................. 4 Introduction .................................................. 5 Units used by GET ............................................. 8 The GET unit procedures ....................................... 9 GETCHAR ....................................................... 9 GETRESPONSE ................................................... 9 GETBOOLEAN ................................................... 10 GETDIGIT ..................................................... 10 GETSTRING .................................................... 11 GETNUM ....................................................... 19 GETREAL ...................................................... 20 GETDATESTRING ................................................ 23 GETTIMESTRING ................................................ 25 GETATTR ...................................................... 25 DATES IN GENERAL ............................................. 26 ADDENDUM ..................................................... 28 RELEASE NOTES ................................................ 28 IMPORTANT NOTE This software uses the copyrighted QWIK routines from Eagle Performance Software which have been included, in the form of a TPU file, by permission. Those who want to use this product must be registered for QWIK. Registration can be obtained from: Eagle Performance Software TP products Attn: James H. Le May P.O. Box 122237 Ft. Worth, TX 76121 GET utilities Page 1 Preface To European readers Ever been tempted to pay for some American shareware with a cheque dated in mm/dd/yy format -- knowing that it would bounce as result? I hope not, but I wouldn't be surprised. It would be a mean way of making a point even if it needs making badly. Our support is expected without much effort to earn it. Have you decided against supporting certain programs that are shareware in the US and sold as cut down commercial rip offs in Europe? I hope so. American shareware authors are aggrieved at our lack of support. In general, they are unaware of the reasons for this. Write to them. You may register as a user of this package by sending me the equivalent of US $1. To American readers: I have an admission to make. Although I use many US originated shareware programs, I have registered as a user of only a few -- and all when I lived in the US recently (as a graduate student) and had a $ check book. With your help I'd like to remedy this. Excuses, Excuses I have excuses for not registering ALL the US shareware I use. It's overpriced, it's a hassle logistically, I hardly ever use some programs etc. You know the score. If we (this means you too) paid the asking price for all of what we use we'd be much poorer, though not as impoverished as we'd be if shareware disappeared. There's no denying that Vern Buerg -- whose LIST program I have not registered -- ought to be a millionaire from the popularity of LIST. I don't know anyone who doesn't use it and I don't know anyone who's paid for it. There's something wrong here! Have YOU paid for it? Are you using it? Right now?! I'd like to see software authors do well out of programs as popular as LIST. Most of us would. I'd have given Dando Shaft a $1 but I'd have baulked at $25. With so many aspiring millionaires attaching importunate messages to their programs it's all too easy to ignore the requests for support from those that deserve it. This is not to deny anyone's right to ask for what they want or our debt to the software authors whose work we use. I think part of the problem is that we are spoiled for choice and don't always agree that a program is worth what the author asks for it. I'd be a lot happier and I think a lot of shareware authors would be richer if they asked for no more than they would get from the royalty on a book. I'd cheerfully register as a user of any number of programs costing as much as, say, a magazine. Agreed? GET utilities Page 2 And More Excuses Now for my logistic excuses. It's not EASY for a European user to become a registered user of an American shareware program. Why? How'd you like to send me a check for £5? You don't have a sterling bank account?! Sorry, I can't do it by credit card. Let's suppose I couldn't sleep at night until I'd sent you $15. I have a choice. I can take time off work, visit a bank to organise a foreign currency draft (would you do this?). Alternatively, I can just send you a check. Your bank would send it for collection and keep most of the money. Knowing this I might decide it was a waste of time. I might not even bother to write and say "nice program" (and "pity about your banking system"). Here's the beef What do I suggest? If you like this package and use it I ask you to send me a dollar bill. I will use it to register American shareware I use. If you have any other ideas on how Europeans can better support American shareware drop me a line. To American Shareware Authors Don't treat your international users with the same apparent contempt as some of the "big names" in the software business. Europe could account for much of your business if you play it right. It's a bigger market than the US and growing faster. There's an argument, an excuse for bad service or no service, that European users are hard to support. Oh sure there's a time difference, ok. In fact, European software users are not SO much more difficult to support than users in, say, Alaska. Most speak English. Federal Express, Purolator, DHL etc. (all but UPS) deliver here. Then there's the mail. We also have telephones, packet switching systems and many of us use services like CompuServe. If you can't support your European users directly (by mail even) consider charging them less. Try to make your software language independent so that the user interface can be adapted without too much hassle and do support international date formats and alternative currency symbols. First you must make people WANT to pay for your software. Next you could try to make it easier for them to pay you. THIS is the biggest hassle and the insular American banking system doesn't help. Until this problem disappears, as it will, you'll have to be creative. I hope to send CASH very soon! GET utilities Page 3 Distribution of this package This package may not be sold under any circumstances. It may not be distributed by PC-Sig or any organisation that operates in a substantially similar manner, including the Turbo User Group of Poulsbo, Washington. User groups who publish annual accounts and have elected officers may distribute this software for a nominal charge to cover the costs of such distribution. This package must be distributed without changes to the software or accompanying documentation. Acknowledgements This modest contribution to the "many hands make light work" school of programming would not have been possible without the work of others. Much as I have yet to learn (I'm working on it), I have gleaned a lot from reading source code unselfishly made available for public scrutiny by all of the following David Bennett Scott Bussinger David Dubois Ted Lassagne Jim Le May Carley Phillips Richard Sadowsky Juan Vegerra I thank them all, Jim LeMay and Richard Sadowsky in particular. If you do any serious Turbo Pascal programming should obtain and register a copy of Jim Le May's QWIK screen utilities. You cannot buy a better package. I couldn't imagine working without it and I think it's important that people like Jim are sufficiently rewarded for their work to go on making it so readily available. Paul O'Nolan Newstead, Forbes Place, Hatton of Fintray, Aberdeen AB2 0YB Scotland, UK CompuServe 72007,242 c/o EDAS BBS (Aberdeen) 0224-624264 The GET utilities are copyright by Paul O'Nolan 1988. GET utilities Page 4 GET UTILITIES v1.0 October 1988 Introduction The GET utilities consist of a number of Turbo Pascal procedures for getting input from the screen, with dynamic validation where possible. The procedures are written to make screen painting and editing straightforward, as well as enabling the provision of field dependent prompts and context sensitive help. As my use of borrowed code illustrates I hate reinventing wheels. Nevertheless, I knew I was going to have to write this set of procedures when I purchased a copy of the otherwise excellent Turbo Professional package from Turbo Power Software and sat down to look at it's data entry routines. The idea that one could enter "abc" in a numeric field and not know about it until one pressed <return> was not acceptable to me. I wanted keystroke by keystroke validation where possible, just for starters. After a couple of evening's work I came up with GETBOOLEAN Get a boolean value GETCHAR Get a character GETDIGIT Get a numeric digit GETSTR(ING) Get a string GETBYTE Get an integer, type byte GETSHORTINT Get an integer, type shortint GETINTEGER Get an integer GETWORD Get an integer, type word GETLONGINT Get an integer, type longint GETREAL Get a real number GETDATESTR(ING) Get a date string (variable format) GETTIMESTR(ING) Get a time string GETATTR Get a color attribute ... a list of procedures I thought I should, and did, write. Writing them took a little longer. Next I spent several weekends adding or fixing "one more thing" so I could call them "finished." Then, to my delight, Borland announced Turbo Pascal v5.0 and I thought I really ought to get this out the door before they actually delivered. In the UK this meant several months grace because Borland, like Microsoft, treats the European customer as a second class customer (pourquoi Philippe?) -- something Compaq and IBM make a point of not doing. Back to my story... All except GETATTR are part of the GET unit. In addition to the above, GETRESPONSE, which is similar to GETCHAR but which is not intended for data entry, is included. Procedures ending in (ING) have two versions, with the shorter procedure name corresponding to a version having an abbreviated parameter list, with default values used for the omitted parameters. Some supporting software is used and recommended: A unit of functions GETFNS used by the GET procedures is required GET utilities Page 5 and included. Jim LeMay's QWIK screen procedures (shareware, v4.2) and Richard Sadowsky's TOOLS4 procedures (public domain, v1.0) are used extensively in this package. These are essential if you wish to make changes to this package, but are not otherwise required. Mark Van Kekerix's QHELP program is useful but not essential. The GETATTR procedure requires Jim LeMay's WNDW package. If subsequent versions of this package do not make additional use of WNDW I may alter GETATTR to work without it. The files in this package are: GETTHIS.DOC A READ.ME file by another name GETDEMO.PAS Demonstration program for this package GETDEMO.DOC Notes on GETDEMO GET.DOC This file GETFNS.PAS A unit of functions used by GET unit GETFNS.TPU Compiled GETFNS unit GETOBJ.ARC Archive of OBJ files used by GETFNS unit GETVARS.PAS Global variable unit used by GET unit GET.PAS Compile this file to produce GET.TPU GETSTR.PAS Source GETNUM.PAS code GETREAL.PAS for GETDATE.PAS GET GETTIME.PAS procedures {included by GET.PAS} GETCOLOR.EXE Program demonstrating GETATTR procedure GETCOLOR.PAS Source code for above GETHELP Help file for this package for use with QHELP QWIK.TPU Jim LeMay's QWIK screen unit, used by GET Suggestions, enhancements and problem reports are all welcome. Few things are more exasperating for a BBS user than seeing a new version of a package, with bug fixes, within days of downloading an earlier version. There will not be another version of GET for a while. I wrote it in order to write some other programs, which I'm now going to write! GET will be updated in a few months, when I catch up with Turbo Pascal v5.0 etc. If anyone cares for the job, there's an obvious application waiting to be written using GET: a screen design program that generates source code for screen based data entry. There are a number of commercial programs that generate Turbo Pascal code from screen designs but none, to my knowledge, that are shareware or public domain. Drop me a line before undertaking this, I'll advise you if anyone else has volunteered/started. Of course, the GET procedures themselves could be used to help with the job. Since the preceding paragraph was written a package called OASIS has been uploaded to CompuServe which fits the bill marginally better than a mirage. Source code is not available. GET utilities Page 6 Why QuickHelp? Mark Van Kekerix's QHELP program (in IBMSW on CompuServe) is a useful tool for use when programming calls to GET procedures. Even though I wrote GET I can't remember all the parameters for all the procedures or the order of them. However, with QHELP all I need to do is enter the name of the procedure, hit the hot key, and read. It's even better than the built in help for Turbo Pascal. QuickHelp is an excellent program and well worth having. UNITS USED BY GET GETFNS This unit contains a number of functions used in GET and some others that I use frequently, often in conjunction with GET. It's a convenient repository for functions that are used in "higher level" units. The functions here are all straightforward and should be adequately documented in the code. This unit makes extensive use of assembly language procedures written by Jim Le May and Richard Sadowsky. Several of their routines replaced code of mine and sometimes of others. I try to be an honest magpie and have acknowledged my sources where possible. GETVARS.PAS This unit contains the type definitions, typed constants (incl. error messages), global variable declarations and code for the smaller procedures and functions used in the GET package. Global variables Numerous global variables are defined and initialised in GETVARS. The meaning and use of most will be apparent from their names. E.g: PasswordChar is set to a space, meaning that spaces are output for each character entered using the get string routine when PasswordField is true. An alternative value might be an asterisk. If AutoTab is true then fields are completed automatically on entering the last possible character, otherwise the user must enter a carriage return to complete the field. etc. A quick look at the code should suffice for any variables not described in this document. Error messages The text of all error messages is stored in the GETVARS unit. If you wish to change a message you need only alter it in GETVARS.PAS. Messages are stored as variables not constants to minimise the impact on the stack of passing them to procedures GET utilities Page 7 (only the address of a variable is passed) and reduce code size (constants are embedded in the code at each occurrence). All error messages are output on either of the two lines at the bottom of the screen. Ordinarily the last line is used. The penultimate and last lines are written to using the procedures error and error2 respectively. To prevent the issuance of multiple error messages, error messages are suppressed if the appropriate error line is not blank (monitored using boolean variables: ErrorLineClear and Error2LineClear). A consequence is that the appropriate procedure, clearerror or clearerror2, should be executed to clear any outstanding error messages and reset the corresponding boolean variable prior to accepting keyboard input. Other messages Informational messages (status information, acknowledgements, warnings etc.) are also rendered on the bottom two lines of the screen, using the procedures info and info2. These procedures do not ring any bells, they are otherwise identical to error and error2. The bell procedure may be used to give discretionary beeps to wake the user up. Sound is made only if SoundOn is true, this is a variable over which the user should have control. The beep procedure sounds a bell regardless of the status of SoundOn. The AltWrite procedure displays text in one or two attributes alternated by means of a switch passed as a parameter and embedded within text. The procedure then pads the rest of the line with spaces using the attribute in effect at the end of the string (so that "reverse video" messages don't end abruptly half way across the screen). A typical string to be displayed with this procedure might be: Delete ^ALL^ files? ^Y^/^N^? It is not necessary to hard code the switch character into the message. The brighten procedure can be used to embed text in a pair of switches: error(text + brighten(text) + text); This procedure uses the value of DefaultAltSwitch for the switch character. GET utilities Page 8 THE GET UNIT GET procedures It is expected that GET procedures will ordinarily be called twice to gather information from fields. On the first occasion, with the global variable PaintingFields set to true, each GET procedure will simply display the field contents and exit. This makes screen painting fairly easy. EditingField is another boolean variable -- the logical negative of PaintingFields -- it was created for readability. If EditingField is true then the active GET procedure will seek input. By default, a field prompt is not redisplayed on the second call to the relevant get procedure. This may be changed by changing the value of the boolean global variable RediplayPrompts to true. All GET procedures get input into a nominated variable at specified screen co-ordinates following a prompt string or fieldname. The prompt string may be blank; if it is too long to allow the field to fit on the screen it will be left-shifted automatically until the field can fit on the screen. If it is still too big it will be truncated as required. Notes Always ensure that you initialise all variables passed to get procedures. If you use get procedures independently, i.e. outside the context of a form make sure that you set PaintingFields to false and RedisplayPrompts to true. GETCHAR This procedure gets a single character in the variable 'response'.The character entered is validated against a set of characters passed as a parameter (valid_keys). If possible, an appropriate error message is issued when an invalid key is pressed: "Numeric input expected" e.g. The input type expected is deduced if the set of valid characters corresponds to one of the predefined sets. No such message can be issued if some other set of characters is passed as the set of valid characters (the bell procedure is executed however). In such cases you should highlight the valid options in the prompt or display them elsewhere on the screen. Note: the field will not be highlighted during data entry using the parameter cursor_attr unless FieldCursor is 0 (i.e. the global variable FieldCursor has precedence over the parameter). GETRESPONSE Like GETCHAR, this procedure gets a single character in the variable 'response'. The prompt string is displayed using the AltWrite procedure described above, so DefaultAltSwitch characters may be embedded in it to emphasise particular words if necessary. The default normal and bold video attributes, attrNM and attrBO, are passed GET utilities Page 9 to AltWrite. Validation is accomplished as per GETCHAR. If the value entered for 'response' is y or Y and 'makesure' is true then the response to 'Sure Y/N' is elicited via a recursive call. This is handy for getting answers to questions such as 'Delete all files.' Confirmation of responses other than y/Y is not possible with this procedure. Whereas GETCHAR is intended for entry of data, this procedure is intended for getting answers to questions, typically outside the data area and using default values for display attributes. Fewer parameters are needed as result. GETBOOLEAN This is essentially a call to GETCHAR with the redundant parameters taken out and the result translated to the appropriate type. There can be no default value parameter for this procedure, i.e. one entered in the event of the field being left "blank", since a boolean value must be true or false. The grey plus and minus keys on the numeric keypad are probably the most convenient keys to set the value of a boolean variable to true or false. The following keys may be used: True: T, t, +, Y, y, 1 False: F, f, -, N, n, 0, <space> GETDIGIT This procedure is used to get a numeric character, decimal point, plus or minus sign and certain editing characters at a designated screen position. GETDIGIT is not intended to be called by the user but by other GET procedures. This procedure has a feature it shouldn't have: hard coded bindings between certain ASCII characters and commands (e.g. ^J is tested for instead of the enter_default command). This is inconsistent with the way the rest of the code is intended to work and this discrepancy should be / will be fixed. I'm pointing it out just to indicate that I know about it. It needn't affect you unless you wish to alter the commands used to accomplish certain things, in which case you'll need to edit this procedure as well as the get_edit procedure (in GETFNS.PAS). This procedure should be implemented by a call to GETCHAR! GET utilities Page 10 GETSTR This procedure is used to get a string fom the screen. It is, effectively, a line editor and may be used to edit a series of lines in a window. It may also be used for routine data entry purposes, collecting and validating information from string fields. Why bother with a line editor? Surely a full screen editor, such as the binary editor provided with the Turbo Editor Toolbox, would be more useful? If you wish to edit some text in a window on its own, i.e., without reference to the contents of other windows, this may well be the case. If, however, you have a need for an application in which data in separate windows are linked, then adapting a line editor to do the job is often a lot simpler than reprogramming a text editor. A very trivial example in this package is the GETTIME procedure, where the separate windows amount to no more than two subfields. How it works Attributes: The string is displayed at the co-ordinates passed using the attribute parameter attr. The value of attr is considered the native attribute for the field, however this may be overridden by the global variable FieldCursor (if FieldCursor is not zero and the field is being edited rather than just displayed). FieldCursor is used to highlight the field the cursor is on and, as you would expect, it moves around from field to field with the ordinary cursor. The ordinary blinking underline cursor is a fairly miserable specimen. I prefer a non-blinking block cursor myself, so I've given GETSTR the ability to use one -- "faked" using a video cursor. To make a video cursor the blinking underline is switched off and a block cursor is simulated using the attribute byte of the appropriate screen location. This byte is set to the value of the parameter cursor_attr. This value should be different from attr if you wish to use this kind of cursor -- you don't have to of course. Arguably, cursor_attr should be a global variable, like FieldCursor, since it's not very likely that you'd change it between calls to GETSTR. In overwrite mode the cursor will change to include a blinking underline. If you elect not to use a non-blinking block cursor, in the colour of your choice, a blinking block cursor will be used instead, and overwrite mode will be indicated by a blinking underline cursor. If you find this blinking discourse hard to follow the following table summarizes everything. Insert Overwrite cursor_attr = attr blinking block* blinking underline cursor_attr <> attr non-blinking block** + blinking underline * black ** any colour GET utilities Page 11 The extent of the field is indicated, even if it is blank, if the attribute used to display it differs in background colour from the rest of the screen -- spaces are output to clear to the end of the field when the string is displayed. The PICTURE The picture parameter controls how the string is to be disposed on the screen and controls how individual characters are to be validated. In other words, it provides for a degree of formatted input. Suppose, for the sake of illustration, that you wished to get a 6 character date from the screen. The following picture would help: '99/99/99' The 9's indicate that only numeric input will be accepted in the corresponding positions. The slashes are field markers and will not be part of the string returned by GETSTR. Characters in specific positions may be constrained to belong to particular character sets: numeric, alphabetic, alphanumeric and printable are provided by default (you can add sets of your own). The picture descriptors for these sets are as follows: picture character character set A alphabetic C alphanumeric P printable 9 numeric X any character any other any character These picture characters may be entered in the picture string in upper or lower case. Upper case picture characters will cause characters entered at the corresponding screen position to be converted to upper case. Thus a picture beginning 'Aa' could be convenient for entering names, with the initial character automatically converted on entry to upper case. If more than one character set is employed in validating a string, the string is edited in overwrite mode and the Ins key has no effect. The last mode (overwrite or insert) will be resumed at the next field if appropriate. When character validation is position dependent it makes no sense to allow characters to be displaced by the insertion or deletion of other characters, this is why insert mode is temporarily disabled. If you wish to edit a field 5 characters long, without any constraints on what characters are entered, you do not need to pass GETSTR a picture of 'xxxxx'. A picture of just 'x' will do. In mapping the correspondences between the picture and data strings GETSTR will apply the last picture character repeatedly all the way to the end of the data string. If you wish to get 3 GET utilities Page 12 digits followed by 20 alphabetic characters a picture of '999a' will suffice. The number of a's to the end of the string will be controlled by the value passed for maxstrlen. However, if you wish to get 79 alphanumeric characters followed by a digit you would need to pass a string of 79 a's and a 9 (if you were determined to do it like that). There is a shortcut however, see RepeatCharacter below. The parameters instr and picture are both of type string, meaning that they cannot exceed 256 characters in length. This should not cause you any difficulty. I just wish to point out here that, as you have already seen, their lengths need not correspond. The picture string can actually be longer than the data string, since it can contain embedded field markers. Field Markers Field markers are characters which are output at designated positions on the screen within the string field but which are not actually returned as part of the string. GETSTR uses a predefined set of field markers which you can change if you wish to (see GETVARS). The default set includes most punctuation characters and special symbols. You are in no way debarred from entering these in the string by virtue of their being employed as field markers. Field markers can be strung together in succession as well as being entered individually. One special field marker deserves mention. The letter 'B' used in the picture is used to denote a blank character in the input field over which the cursor will skip. Thus, a picture of '(999)B999-9999' would leave a blank on the screen between the area code and the rest of the telephone number. The value of maxstrlen (following picture string in the parameter list) should, of course, be 10. There are 10 digits in the string. You could render the picture as '(999)B999-9' if you wanted to, and let GETSTR fill in the last few characters automatically, however your code would not be quite as readable. Note, B is used instead of a space to make counting field markers easier. Switches Special characters or switches may be embedded in the picture string to control how it is interpreted by GETSTR. Naturally, aone of these should appear in the predefined set of field markers, or they will be ignored in any picture string. You may change the switch characters if you wish. DefaultAltSwitch First is the constant DefaultAltSwitch (type char). It's default value is a tilde. It's name derives from the fact that this character is the default switch for the AltWrite procedure which GET utilities Page 13 is used to display text using either of two video attributes, with this character toggling between them. It is used to trigger the copying of text from the picture to the screen as if the characters following the switch were field markers. Thus, if an asterisk was the switch character, the following picture would allow you to get a date with '19' displayed on the screen for the first two digits of the year '99-99-*19*99' Note that GETSTR will not return the '19' as part of the string (unless you modify the code!). ShiftCharacter The second switch is the constant ShiftCharacter, with a default value of "\". This character is used to force GETSTR to treat the string parameter (instr) as one or more string segments which, although they belong together, are not displayed contiguously. This switch can be used to get GETSTR to break a 240 character comment string into three 80 character lines, e.g. Alternatively, it could be used to facilitate collection of input from a few, or even a few dozen, apparently separate text fields into one string (edits could be accepted or aborted collectively). Of course there would still be only one field prompt provided by GETSTR. The character following the ShiftCharacter controls how GETSTR breaks the string; the shift character itself is merely a flag indicating that the string is to be broken. If the next picture character is an "N" then the string is wrapped so that the next data string character is located beneath the first character in that string. Thus, using the default value of ShiftCharacter, the sequence "\N" embedded in the picture string connotes a new line. A picture of 'xxx\Nxxx\Nxxx' will correspond to 3 x 3 block of characters on the screen. If the character following the ShiftCharacter is anything other than an "N" then GETSTR displaces the next data string character by the ordinal value of that character. Thus, a picture of 'xxx\' + chr(10) + 'xxx' could be used for two three character fields separated by 10 screen positions. Note that this picture is not equivalent to 'xxxBBBBBBBBBBxxx' The B in the picture will cause the corresponding screen location to be blanked and displayed using an attribute controlled by GETSTR. This will not happen using the first picture above. If you wish to effect a displacement of ord('N') or one in excess of 255 locations simply use two or more successive displacements. Note: All displacements must be positive. GET utilities Page 14 RepeatCharacter The third switch is the RepeatCharacter (default value: "@"). This is used in a similar manner to the ShiftCharacter, except that the character following the RepeatCharacter represents a repeat value rather than a displacement. The picture character repeated is the last one used. The RepeatCharacter allows long picture strings to be specified conveniently (no miscounting and a reduced impact on code size and stack space). Thus, returning to the previous example, a picture of 'x@' + chr(79) + '\N' + 'x@' + chr(79) + '\N' + 'x@' + chr(79) or 'x@' + #79 + '\N' + 'x@' + #79 + '\N' + 'x@' + #79 corresponds to a 240 character string broken into three lines of 80 characters each. This could be rendered more economically as 'x@O\Nx@O\Nx@O' or even 'x@O\N@P\N@P'. Note that #n may be used instead of chr(n). As an aside, # is a hash character, or if you want to be exactly correct, an octothorpe. It is not, repeat not, a pound character. Note: the display_prompt procedure takes account of the fact that the string may be broken. It would not necessarily be appropriate to left shift the prompt and a long string field if the string was split into, say, two segments and enough room was allowed for these. However, it is assumed that string segments following the first will be on succeeding lines and no check is made to ensure that there is enough room for these. If you are silly and ask GETSTR to get data from a field whose picture string doesn't provide for anything other than embedded (marker) text and field markers you, and the field, will be ignored. GETSTR will display what it can and exit. Naturally, GETSTR allows you to display embedded text and field markers in strings using a different attribute from the rest of the string. If the field is being edited these characters will be displayed using the value of the constant PicCursor. If PicCursor has a value greater than 0 it will be used instead of the prevailing attribute. Other parameters The status parameter is used to pass a single byte bit map which controls the variables 'mandatory' and 'fixed_length' (bits 1 and 2 respectively). These control whether or not a blank field is an acceptable input and whether that input must, if not zero characters long, be a fixed number of characters (value of maxstrlen) in length. GET utilities Page 15 WordStar editing The GETSTR editor understands the following commands: Home beginning of string ^QS End end of string ^QD Ins toggle insert/overwrite ^V left word ^A right arrow right 1 character ^D left arrow left 1 character ^S up arrow up 1 character ^E down arrow down 1 character ^X <tab> insert tab (if allowed) ^I <ret> enter the string <ret> / ^M insert literal ^P followed by any char oops (undo) ^QL / ^U delete string ^Y delete to start of string ^Q<del> / ^QH delete to end of string ^QY delete next word ^T <esc> abandon changes to field <del> delete character ^G Many other commands are passed through to the calling program. <Tab> will either enter a "<tab>" or, if the global variable tabsize is set to 0, move to the next field. If tabsize is not 0 (default is 8) then the appropriate number of spaces is entered. The up arrow and down arrow commands are acted upon by GETSTR only if appropriate, i.e., if the string is broken into two or more segments -- these would normally be displayed on separate lines. The following are worthy of note ALT-R Reset -- disable validation (temporarily only) ALT-Y Delete a block (all subfields with a string) ALT-U Restore (undo) a block -- e.g subfields in dates and times ALT-X Exit: abort changes to current field and finish data entry ^J Enter default -- described below Enter Default The GETSTR procedure does not enter a default value in response to the enter default command, instead it returns to the calling procedure which may then take the appropriate action. This is done for two reasons: 1. to avoid passing an additional parameter (whether string, address or pointer) and 2. because it would not help in situations where strings were linked to make up a larger field -- how does one enter a default date, say 10 characters in a 2 character day field? GET utilities Page 16 Disabling Validation Validation may be disabled, on a field by field basis only, provided the user has the appropriate privilege. The privilege is controlled by the boolean variable ValidationOverride. In the case of the GETSTR procedure, bad data will not be displayed using asterisks (as is done to indicate overflow, e.g., in the procedure GETNUM). However, attempts to move the cursor to another field will be trapped, on the offending character, until validation is turned off, <escape> or ALT-X is pressed, or the data is corrected. Global variables affecting string editing PaintingFields (boolean) controls whether, having displayed the string 'instr', GETSTR should allow the user to edit this string or exit. At the moment this variable is global to all fields, however it could easily be set for particular fields using a bit map -- enabling write protected (display only) fields to be used. Top_n_tail (boolean) controls whether or not strings returned by GETSTR have leading and trailing blanks removed. ForceUppercase (boolean) controls whether all text is to be set to upper case regardless of the value of picture characters. PasswordField (boolean) controls how characters entered are echoed. If true then the character PasswordChar (default value is a space) is output in place of all characters entered and all validation is suspended -- no point in issuing messages like "numeric character expected"! Variables affecting cursor movement Fieldwrap (boolean) controls whether the cursor moves from the last field to the first on field completion/next field command or or vice versa when directed to the previous field. If Fieldwrap is false it is expected that the value of the variable 'field' will, in your program, eventually exceed the number of fields on the screen and that data entry can be terminated without requiring the user to enter an exit command. Cursor movement between fields effected using the horizontal arrow keys may be controlled directly by a lookup table in your application. StringFieldWrap (boolean) controls whether the cursor will respond to the left and right arrow keys when positioned in the first or last character positions in a string. If StringFieldWrap is set, GETSTR will attempt to move the cursor to the next or previous field if asked to do so, moving to the start or end of a string if appropriate -- i.e., from the end of one string to the start of the next and v.v. This variable can be set to enable the use of linked subfields within what appears to be a string but is in reality a series of strings. E.g. GET utilities Page 17 Getting a date using an apparent PIC '99/99/99' oldStringFieldWrap := StringFieldWrap; StringFieldWrap := true; now get 3 date subfields StringFieldWrap := oldStringFieldWrap; Other notes It is possible to include a field prompt in the picture string if you wish to do so. Simply embed it using DefaultAltSwitch as previously described; it may be displayed using the same attribute as the input field however. Alternatively, the following would work: promptstr := 'fieldname: '; picture := brighten(promptstr) + 'x'; Getstr(....,picture,...); The brighten procedure adds the switches for you, so you don't need to hard code them into the code. You may care to consider using RedAttr to display characters not matching the picture specified for them* (at the moment there is nothing to draw attention to 'abc' displayed in a field with a picture of '999' until the user attempts to leave the field). Alternatively, one could use a reserved graphics character for each bad character, perhaps with the reset validation command (currently Alt-R) enabling a display of the offending characters. * Some commented out code can be taken as a starting point. The GETFNS unit incorporates routines which could be used to add search or search and replace functions to GETSTR. Other routines could easily be added: change the case of the current character etc. GET utilities Page 18 GETNUM This procedure should never be called directly. It is intended to be called by one of the following procedures: GETBYTE GETSHORTINT GETWORD GETINTEGER GETLONGINT Each of these procedures indicates to GETNUMBER what the maximum value of a returnable number should be. This is accomplished using a longint parameter (maxvalue) having one of a restricted set of values, each of which is used to imply the required type of the returnable number. When you use one of the above procedures the appropriate value of maxvalue is set automatically. The parameter list includes the variables 'low' and 'high' which may be used for controlling range checking. Range checking is dynamic -- i.e., mistakes are caught immediately -- if the range does not exclude the number 0. If dynamic validation is not possible then numbers are validated after the user has finished entering them. If low and high are equal then range checking is turned off. If the value of either low or high is not appropriate for the implied type (e.g., a range of 0 to 999 with a maxvalue of 255) then the range is adjusted to the maximum permissible if the type is correct (in this case the range would become 0 to 255); Field size is determined in the first instance by the required number of digits for the implied type (3 for a byte, 5 for a word etc.). Validation criteria may constrain this further (a byte in range 0..99 will require a field size of only 2 digits), unless the user has ValidationOverride privilege in which case the nominal (full) field size is used. ValidationOverride is a boolean variable used to control whether or not a user may disable validation. Note that it may be turned on or off between fields. Naturally, if the user has this privilege for a field, the field needs to be the maximum size allowable for the type of data expected (3 digits for a byte etc.) regardless of what validation criteria are in effect. If the number passed is too big to be displayed in the field allowed then the field is asterisk filled. The delete_line command (default: ^Y) blanks the field for fresh input. Pressing <ret> sets a blank field to a default value if one has been specified. <esc> and ALT-X exit the field leaving it unchanged, as does moving to another field before terminating entry or editing of the field's contents. The enter_default command (default: ^J) forces entry of the default value. A default value may lie outside the validation range if the user has ValidationOverride privilege. GET utilities Page 19 Global variables RightJustifyNumbers (boolean) controls whether numbers are displayed right justified after entry. RightJustifyNumberEntry (boolean) controls whether numbers are right justified in the input field during data entry. If true they are, otherwise they are entered left justified. Note that RIghtJustifyNumbers controls how numbers are displayed AFTER they have been edited. If ZeroAsBlank is true then fields having a value of zero are displayed as blank. If ZeroFillNumbers is true then fields are displayed so that each field is filled with a right justified number preceded by zeros. Other notes Editing of a number always takes place at the end of the field. Because the cursor is not constrained to remain within the field, even when editing the last character in a full field (as it is in GETSTR), a real cursor is always used rather than a simulated one. If this were not done it would be necessary to save and restore the video attribute byte immediately following each field. Because a real cursor is used then, SetCursor(CursorOn) is executed at the start of the routine and SetCUrsor(CursorOff) at the end of it. GETREAL This procedure is broadly similar to GETNUM, having the same general parameters, but the parameter decimal_places is used instead of maxvalue to determine the maximum range of possible input. The larger field size required for low or high controls how big the field for the entry of 'number' is, unless low = high then the nominal field size of 13 digits is used (11 significant digits, plus sign and decimal point). The value of decimal_places constrains the maximum range of the input as follows: implied_lowest implied_highest decimal_places -2147483648 217483647 0 -2147483648.0 217483647.0 1 -999999999.99 99999999.99 2 -99999999.999 9999999.999 3 -9.9999999999 9.999999999 10 The ranges indicated above will be used for the corresponding number of decimal places if user specified range checking is not in effect (i.e., if low = high) or if the range specified is not appropriate for the number of decimal places specified. GET utilities Page 20 The range may be constrained further by the parameters low and high and the field size will be affected accordingly -- provided ValidationOverride is not true. Field size may be further affected if any user defined formats are used. As many additional characters as are required to cater for the maximum number of commas, e.g., in a number may be added to the field size. As with GETNUM, dynamic validation is not attempted unless the validation range includes the number 0. A decimal point is added automatically during data entry when the maximum number of digits for the integer part of a number has been entered. User Defined Formats It would be possible to add several parameters to the GETREAL procedure to control how real numbers were to be displayed after they had been entered. I thought it would be a better idea to collapse a number of parameters into one: the parameter decimal_places can have a negative value. Ordinarily, this would be nonsensical. However, this provides a means for passing additional information to the GETREAL procedure without expanding the parameter list. If the value of decimal_places is negative GETREAL uses its absolute value to index into an array of user specified display formats (in GETVARS.PAS). GETREAL uses the information obtained from this array to set the values of the several variables controlling number display. The first entry in this array looks like this: (UnitSymbol: '$'; places: 2; UnitFormat: SymbolFirst_Commas) If the value of decimal_places is -1 then 'number' is displayed to two places of decimals with a dollar in front of a comma punctuated amount. No problem? However, remembering to use -1 for one format and minus something else for another would be a little tedious, so I've set up some constants to make it simple; you should modify the list of these and the corresponding formats to suit your own purposes. The predefined values are as follows: Dollars = -1; Pounds = -2; FrenchFrancs = -3; SwissFrancs = -4; Kmpersec = -5; MHz = -6; All you have to do is write "Dollars", "SwissFrancs", "Pounds" etc. instead of a number of decimal places in the parameter list for GETREAL. GET utilities Page 21 The variable UnitFormat in the array of format descriptors is itself a composite variable. It is a byte whose bits are set or reset to indicate how the number should be displayed. Some constants are defined to make manipulating these bits easier: Unformatted = $00; SymbolFirst = $01; Commas = $02; Parentheses = $04; {display negative numbers in parentheses} Financial = $06; {shorthand for commas + parentheses} SIdisplay = $08; {Système International format} SymbolFirst_Commas = $03; SymbolFirst_Parentheses = $05; SymbolFirst_Financial = $07; To add your own format all you need do is: 1. Decide how you wish the number to be displayed 2. Increment the constant TotalUserFormats (also in GETVARS.PAS) 3. Add a record to the array of formats (UserFormatArray) You may add a constant to the list shown above (after MHz) so that you don't need to remember where in the table the appropriate format is defined. A further advantage of doing this lies in the fact that the table may be reordered without the need to make changes to every invocation of the procedure; the values of the appropriate constants (dollars, pounds etc.) may be changed instead. Find the appropriate value of UnitFormat by inspection of the table above. Système International Real numbers displayed in compliance with the conventions of the SI standard are shown with a comma delimiting the mantissa and the characteristic part of the number, with thousands delimited by either a space or a period. GETREAL supports the SI standard by means of its facilities for handling user-defined formats. If SIdisplay in the appropriate UnitFormat record is true then the real is displayed according to the conventions of the SI standard. A global character variable, SIThousandsDelimiter, with a default value of a period, is used to punctuate the integer part of the real. This variable can be set to a space if desired. Numbers entered with SIdisplay set true or false in their UnitFormat records will be displayed with a "decimal comma" or decimal point respectively during data entry, although either character may be entered as the decimal delimiter. Range values will be correspondingly affected in the text of any error messages issued during data entry (decimal comma if SIdisplay). GET utilities Page 22 GETDATESTRING This routine gets a date string from the screen using successive calls to the GETSTR procedure to accumulate an aggregate string. The description of that procedure's operation applies to the each of the day, month and year subfields comprising a date. The primary purpose of this procedure is to provide flexible date format control and to provide validated dates in a string format. The user may then convert dates using a preferred Julian conversion routine if desired. I believe that quite a few people will be happy to store dates as ASCII strings, particularly in cases where all other data are being stored as ASCII. In such cases the dates need only be temporarily converted to Julian format for arithmetic purposes. Date format control is accomplished by means of simple global variable assignments such as: DateFormat := European; YearFormat := YY; GETDATESTRING returns an 8 or a 10 character string with 2 subfield separators. The global variables DateFormat and YearFormat control the interpretation of the subfields in any string passed to this procedure (i.e., their order and implied nature -- month, day or year) and the number of characters in a year field. Thus, for a DateFormat of American, dates are expected in mm/dd/[yy]yy order. The date field separators, i.e. the characters between month, day and year subfields, are either those in the appropriate positions in the string being edited or the globally specified default (for blank dates). Unlike the field markers which appear in picture strings, date subfield separator are part of the string -- although they are skipped over during data entry or editing. In practice the content of these bytes is irrelevant, their position is more significant. Any separator character may be used, each will be displayed during date entry using the separator_attr attribute passed to the procedure. Valid date formats are: DateFormat date string format American mm/dd/[yy]yy European dd/mm/[yy]yy Japanese [yy]yy/mm/dd GET utilities Page 23 Valid year formats are: YearFormat year string subfield overall length YYYY 4 digits: 0000-9999 to be returned 10 YY 2 digits: 00-99 8 NY as above 8 The difference between NY and YY is that dates with a YearFormat of NY are displayed with a "19" prefacing a two character year subfield. This "19" is NOT returned as part of the date string. In determining what years are leap years ALL dates with effective field sizes of two characters for data entry are assumed to be 20th century dates, and 1900 is added to each. Dates entered are validated to ensure that the number of days in the month and number of months in the year are legal values. Because GETDATESTRING allows dates to be entered in a variable manner it also validates dates in the subfield order in which they are displayed. No validation is performed on the year subfield of any date other than to ensure that it is filled with numeric characters, though of course whether or not the year is a leap year will affect the validation of the day subfield. The following definition of a leap year is used: any year divisible by four except centuries divisible by four hundred and millennia by four thousand are leap years. Because the date string used by this procedure needs to be capable of being either 8 or 10 characters long the appropriate var parameter is a string (0 to 255 characters long). This means that any old rubbish can be passed to it without difficulty, it is your responsibility to see that this doesn't happen. GETDATESTRING doesn't do much to recover the situation if the string passed is simply not a date in the format expected. To blank a date field enter the del_block command (default Alt-Y) and to restore a date field enter the restore_block command (default Alt-U). The enter_default command (^J) enters the current system date. This command may be entered on the first subfield of a blank date field or on any completed date subfield. Pressing <return> on a blank date field will enter the system time if SystemDefault is set true (2nd bit in 'status' parameter). Blank dates will be displayed as blanks or zeros if the global boolean DateZeroAsBlank is true or false respectively. Short version: GETDATESTR GET utilities Page 24 GETTIMESTRING This routine gets a string time from the screen using successive calls to the GETSTR procedure. It is similar to but considerably simpler than GETDATESTRING because all times are returned in a fixed 24 hour format with, invariably, a colon between the hour and minute subfields. The enter_default command (^J) enters the current system time. Pressing <return> on a blank time field will enter the system time if SystemDefault is set true (2nd bit in 'status' parameter). Blank times will be displayed as blanks or zeros if the global boolean TimeZeroAsBlank is true or false respectively. Short version: GETTIMESTR Possible changes: Add minimum and maximum parameters (like GETNUM), ALT-R to disable this validation. Allow use of 12 hour times with A.M. / P.M. indicator (like DOS). If minimum and maximum time parameters are added and a given call to this procedure excluded 00:00 as a valid time, bit 1 of status could be used to control whether entry of a time was mandatory. Alternatively, if an AM/PM indicator were added this could take a null/blank value to indicate that a blank time was not 00:00 (midnight) but a blank field. GETATTR This procedure displays a palette of attributes similar to that used by Turbo Pascal's TINST program and allows the user to select one. The boolean parameter display_value controls whether or not the decimal value of the attribute is displayed at the bottom of the window. <Ret> selects foreground & background colours (attribute) <Esc> aborts leaving the attribute variable passed unchanged NOTE: The procedure InitWindow in Jim LeMay's WNDW unit should be run BEFORE this procedure is executed, preferably at the start of the program within which this procedure is used. GETATTR is not part of the GET unit. GET utilities Page 25 DATES IN GENERAL There's an old joke about the computer industry liking standards so much that it's got hundreds of them. How old? Let's see, which date routine are you using? There are a plethora of "date procedures" available. Scott Bussinger, Ted Lassagne, Carley Phillips, David Dubois and others have contributed useful routines. All of them have their advantages and all suffer from one or more disadvantages. In general, the readily available date routines offer one or more flavours of Julian/Gregorian date conversion. Background Some of the shortcomings of the so-called Julian date routines currently available are discussed below. Most commonly these routines allow a word (2 bytes) for the Julian day number, enough for 64k serial numbered days -- or a range of 179 years (65,535 / 365) . DOS stores dates in this fashion and has such a range, as does Lotus 1-2-3 and many other programs. There are a few problems with this approach. BY DEFINITION a Julian date is a number of days from an agreed base date: 1/1/4713 B.C. This date was fixed by the astronomer Joseph Scaliger, after whose father Julius the Julian date scheme is named, to facilitate conversion between the Gregorian and earlier calendars. Microsoft's DOS dates are numbered from midnight on the last day of 1979. They are not true Julian dates because this additional information is required to decode them properly. Similarly, dates with other bases -- such as Smithsonian dates -- are not true Julian dates. (Smithsonian day 0 was 17 November, 1858. This is the base date used in date calculations on many computers, DEC's VAX machines e.g. The conversion factor, according to Ted Lassagne, is Smithsonian = Julian - 2400001). Note that it is not necessary for the user of date conversion routines to know the base date to use them. David Dubois' FASTDATE routine is based on a day 0 = "a magic number". So far as I can tell, this derives from his birthday. Unfortunately, his assembler code isn't as accurate as one might hope for under the circumstances. However, if one decides to expand the day range to encompass the agreed starting point for true Julian dates one runs into other problems. The generally employed Julian to Gregorian inter- conversion procedures derive from the published work of Tantzen (Algorithm No. 398, Communications of the ACM, August 1963, Vol. 6 No. 8). These calculations are valid for dates between 15 October 1572 and 28 February 4000 AD The former is the date the starting date of the Gregorian system, GET utilities Page 26 established by Papal Bull in March 1572. The Bull suppressed the 5th to the 14th of October 1572, inclusive, in order to restore the vernal equinox to March 21st. Tantzen's routines are not valid after the latter date because they do not take into account the fact that years divisible by 4,000 are not leap years. The applicability of the calculations to dates prior 15 October, 1572 is at least debatable (Pope Gregory was not the first to eliminate days). Mathematically, the procedures are purportedly valid from the 1st of March, year 0. However, there was no year 0! The Christian calendar went from 1 BC to 1 AD. It's better not to worry if Jesus Christ was on earth for a week or so BC, because we almost certainly don't know the true date of his birth. If the 1st of March following the birth of Christ is taken to be day number 0 we are not dealing with a Julian date. Some date routines treat the first day as day 1 (W. Madison's e.g.). No problem, we can add a constant number of days to it -- the number of days in January and February of the first year would be one option. To do this we need to know if the year was a leap year. That depends on whether you call it year 0 or year 1. However, we really ought to add the number of days between the 1st of January 4713 BC and the 1st of March following Christ's birth. In calculating this total we need to bear in mind that years divisible by 4000 are not leap years and that there was no year zero (Are you with me? Sigh. I don't think I am!). I have yet to see any code which addresses this properly (Carley Phillips' routines are closest). To an extent the issue is academic, though it would be nice to have a(nother) standard for computing purposes. Days were dropped periodically prior to, and upon the introduction of, the Gregorian calendar to bring the calendar into line with the earth's astronomical calendar. Should date conversion routines know about the effects of these changes? I would argue against it, given that the Gregorian calendar was not adopted simultaneously all over the western world and we already have the confusion of different countries adopting it on different dates (Britain in 1752, Russia in 1918 and Turkey as recently as 1928 e.g.). Anyway... The whole business of date arithmetic requires either relatively adjacent dates or an agreed standard means of calculation (the actual base date is not particularly important). In the absence of a universally agreed procedure the GET procedures will have nothing to do with date arithmetic, for now anyway. You may select your own procedures (e.g. Ted Lassagne's EXDATE.PAS). For what it's worth, my preference is for the most recent popular base date (Smithsonian) because using it eliminates most of the problems, however it may not suit everybody. GET utilities Page 27 Addendum It's a small world so please, if you disseminate documents for printing, bear the following recommendations in mind. Use 66 line pages (not 70 line A4, unprintable in N.America). Use formfeeds not linefeeds at the end of a page -- A MUST! Set the right margin so that the total width does not exceed 77 characters -- the maximum the HP LaserJet II will print in Courier 10. RELEASE NOTES Since the beta distribution (October 1st) the following changes have been made: 1. Minor bug in display of time and date fixed (wrong attribute for separator character). 2. GETSTR display speed improved slightly. 3. Support for SI format reals added to GETREAL. During the month: UPS began delivering all over the UK; there's a depot in Aberdeen not far from where I live (hey hey!). Borland laid off staff, started looking for dealers to handle technical support, and still didn't deliver Turbo Pascal v5.0 -- now expected in the UK in December (1988). Blaises! What Kahn a poor boy do? Will it be Wirth waiting for? We shall C, perhaps. GET utilities Page 28