Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / EM3270.ZIP / EM3270.DOC next >

Wrap

Text File | 1986-07-13 | 40.2 KB | 990 lines

Pascal Library Member EM3270.INC Page 1 INTRODUCTION ____________ The EM3270 procedures are the copyrighted property of Piedmont Specialty Software. They are distributed as "Shareware" to save the enormous costs of publishing, advertising, and distributing software through the normal commercial channels. In keeping with the established "rules" of this type of distribution, we ask that you: 1. Send $20.00 to Piedmont Specialty Software, P. O. Box 6637, Macon, GA 31208, if you find the procedures useful. 2. Use the procedures for your personal use only. If you wish to use them in software for commercial distribution, please contact us at the above address or by telephone at (912) 474 2318 for details of a commercial license. 3. Distribute the procedures freely, so long as you - do not modify them, - include this documentation with them, - include the acompanying demonstration program. We have used these procedures in many programs in the last two years and have found their screen management facilities to be well received by all users from novice to expert. We hope that you will find them as useful and productive as we have. Pascal Library Member EM3270.INC Page 2 I. PURPOSE Turbo Pascal library member EM3270.INC is an INCLUDE file containing a set of procedures which allows full-screen editing patterned after the IBM 3270 family of terminals. The 3270 family consists of a number of terminal models designed to connect to the System/370 family of mainframe processors. There are hundreds of thousands of them in use by office workers all over the world. They operate as "full screen I/O" terminals. That is, the mainframe sends an entire screen at a time to the terminal, the user enters and edits all data on the screen while "disconnected" from the mainframe, and when finished transmits the entire modified screen back to the mainframe by pressing one of the "atten- tion identifier" (AID) keys. The EM3270 procedures facilitate writing programs in Turbo Pascal which give the user the impression that he is working with a 3270 terminal. Then programming methods you use in handling the screens are very different from those used by a mainframe programmer, but the appearance to the user closely mimics a 3270 with only a few compromises made to account for the differences in a PC keyboard and a 3270 keyboard. Significant features of the routines include: a. Attribute_bytes specifying visible or invisible, bright _______________ or dim, steady or blinking characters, foreground co- lors, and Modified Data Tags. b. Cursor_control consisting of character right, character ______________ left, tab forward, tab backward, home cursor, and next line. c. Field_selection on writes and reads to and from the _______________ screen. d. Cursor_positioning under program control before data __________________ entry. II. USAGE A. Program_Requirements ____________________ Before inclusion of EM3270.INC, the following statements must appear: {$V-} . . . Const MaxFields = xxx; Where xxx is the maximum number of data fields which can ____ appear on any screen, and is from 1 to 255. Any number of prompt fields can appear. ______ NOTE: DO_NOT SET COMPILER DIRECTIVE {$U+} IN ANY PROGRAM NOTE: DO_NOT SET COMPILER DIRECTIVE {$U+} IN ANY PROGRAM ______ ______ USING THE EM3270 PROCEDURES. TURBO DOES STRANGE THINGS TO USING THE EM3270 PROCEDURES. TURBO DOES STRANGE THINGS TO Pascal Library Member EM3270.INC Page 3 THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD INPUT THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD INPUT PROCEDURES OF EM3270 BECOME FRIED. PROCEDURES OF EM3270 BECOME FRIED. The EM3270 routines use the heap, but should not interfere with any other heap operations of the calling program. THE DISPOSE COMMAND IS USED IN HEAP MANAGEMENT. A CALLING _______ PROGRAM MUST NOT USE TURBO'S MARK AND RELEASE!!!!! ___ B. Initialization ______________ Before any other EM3270 procedure is executed, the EM3270 ___ system must be initialized by issuing the following command: ____ InitScreen; This command must be issued once and only once for an execu- tion of your program. C. Screen_Handling_Logic _____________________ The general flow of logic in handling a screen consists of the following sequence: . . . Procedure PresentScreen1; Const Strng1 : String[8] = "Prompt 1"; Strng2 : String[8] = "Prompt 2"; . . . Begin NewScreen; { clear all existing fields } WritePrompt(1,1,Dim,8,Strng1); { write a prompt } WritePrompt(2,1,Dim,8,Strng2); { write a prompt } . . { repeat for all prompts } . Attr := 0; {Bright, Steady, Visible, Unchanged} WriteField(10,1,Attr,14,' ') { define field 1 } WriteField(10,2,Attr,16,' ') { define field 2 } . . { repeat for all data fields } . End; { of procedure } . . . Procedure GetScreen1; Begin ReadScreen(FieldNo,FK); { open screen for input } GetField(1,Varbl1,Attr); { retrieve a data field} GetField(2,Varbl2,Attr); { retrieve a data field} Pascal Library Member EM3270.INC Page 4 . . End; { of procedure } . . Procedure RewriteScreen1; Begin Attr := 0; RewriteField(1,Varbl1,Attr); { rewrite field 1 bright } RewriteField(2,Varbl2,Attr); { rewrite field 2 bright } . . . End; { of procedure } . . Begin { begin mainline program } InitScreen; { Initialize EM3270 } . . { open files, etc. } . PresentScreen1; { write blank screen 1 } Repeat GetScreen1; . . { process screen 1 variables } . RewriteScreen1; { replace fields with new values } Until Finished; . . Each of the EM3270 procedures is covered in Section III. D. Data_Fields ___________ A data field is a string which is written to the screen and ______ into which the cursor can be moved during a ReadScreen procedure. Every data field written to the screen is assigned a field number from 1 to MaxFields. Data fields are numbered in the order in which you write them to the screen. It is up to you to keep track of what each field number contains. You always ______ address a data field by its number. Care must be exercised in planning the sequence in which you write data fields because cursor tabbing at program execu- tion time is determined by field number. (This is a depar- ture from the 3270 standard, in which the field sequence is always left-to-right, top-to-bottom.) If the cursor is in field 14 and the tab key pressed, it will jump to field 15, no matter where 15 is. To keep from driving the user nuts, screens should normally be designed so that fields are always written in the 3270 left-to-right, top-to-bottom Pascal Library Member EM3270.INC Page 5 sequence. An example of when you might want to place fields out of sequence might be a field that is almost always the same value, but should visually appear close to some other vari- able on the screen (state abbreviation in a local area mailing list, for example). In such a case, you can define it as the last screen field and provide the default value. The cursor will skip over the field in normal tabbing, but the user can still reach it when it needs to be changed by tabbing until the cursor finally does reach it. You specify the position and length of a data field when you first write it with the WriteField procedure. Position and length are fixed at that time and cannot be changed afterward. When you retrieve a data field (with the GetField procedure), the string returned is always of the length specified when the field was first written. You also specify the attribute of a data field when you write it. (Attributes are discussed fully below.) The attri- bute of a data field can be changed when you rewrite the ___ field, and its Modified Data Tag bit is automatically changed if any data in the field is changed during a ReadScreen procedure. The routines DO_NOT check for a "collision" between fields. ______ If you write one field on top of another, the last field out will be the one the user sees. However, the value of the two fields will be maintained intact, and if you retrieve them both you will get the correct values. The visual effect to a user, though, is quite bizarre. E. Prompt_Fields _____________ Prompts are strictly for the user's benefit and are treated very different from data fields. Once written, a prompt is forgotten - it remains on the screen, but cannot be accessed thereafter, other than to overwrite it with another prompt or a data field. Prompts are not numbered and there is no limit to how many you can write to a screen, other than the physical capacity of the screen. The writing of prompts and data fields may be interspersed. Pascal Library Member EM3270.INC Page 6 F. Attributes __________ An attribute is a byte associated with a field (either data or prompt) which defines certain characteristics of the field. The bits of the byte are used as follows: Bit ==> 7 6 5 4 3 2 1 0 Attribute Byte => X X X X X X X X ^ ^ ^ ^ ^ ^ 0=Bright | | | | |________| 1=Dim______________| | | | | | | | | 0=Steady | | | | 1=Blinking____________| | | | | | | 0=Visible | | | 1=Invisible______________| | | | | 0=Unchanged | | 1=Modified__________________| | | 0=Use default color | 1-15=Foreground color______________| G. Field_Appearance ________________ Original models of the 3270 could display a character in one of two brightnesses: "normal" (dim) or "highlighted" (bright). Later models extended this capability to include reverse video and blinking, as well as color attributes. The EM3270 procedures implement the attributes in one of two ways, depending on whether they are running on a machine with a monochrome or color monitor (the EGA is not support- ed). The Steady/Blinking and the Visible/Invisible bits work the same on either type. If the Steady/Blinking bit is 0, the characters of the field or prompt are displayed normally; if it is 1, they blink off and on in a highly attention-grabbing (and distracting) way. Blinking characters are normally used in rewritten fields to call attention to a data entry error. If the Visible/Invisible bit is 0, the characters of the field are displayed normally; if it is 1, they are displayed as spaces (that is, they are invisible). Moreover, any data keyed into the field will not be displayed. The cursor moves to the right as characters are keyed, and the characters entered are available to your program, but the person at the keyboard never sees them (unless you display them elsewhere on the screen in a visible field). In the mainframe environ- ment invisible fields are commonly used for the entry of security passwords. Their use in the micro environment is more limited. Pascal Library Member EM3270.INC Page 7 On the monochrome display, the Bright/Dim bit causes the characters of the field to be displayed in normal white on black (Dim) when set to 1, or as inverse video (bright) when set to 0. In the 3270, the equivalent bit simply causes the equivalent of Turbo's LowVideo and NormVideo procedures. However, one of the shortcomings of the original 3270 family was that their was no easy way to show the user the length of a data entry field. The cursor always moves into the leftmost position of the field, but there was nothing to show the user where the right end of the field was, and therefore no sure indication of how many characters he could enter before the cursor jumped to the next field. The intro- duction of inverse video models offered a solution to this problem and programmers quickly adopted the standard of setting unprotected (data entry) fields to inverse. This standard is implemented in the Bright/Dim bit in EM3270. On the color display, the Bright/Dim bit selects one of two background/foreground color combinations (see section I below). This has nothing to do with the actual brightness or dimness of the background and characters; it merely provides a convenient way of selecting between two palettes. The color bits of the attribute are used to override the foreground color of the palette selected by the Bright/Dim bit. If these four bits are 0000, the palette color is displayed. A value of 0001 through 1111 cause the foreground color to be the equivalent color (dark blue through white). Note that Turbo provides predefined integer constants for each color which can be conveniently added or ORed to an attribute byte. For example, Attr := LightGreen will give an attribute that will cause light green characters on the "bright" background color. The color bits have no effect on a monochrome monitor. Four constants are defined in EM3270 for convenience in working with attributes: Dim, Blinking, Invisible, Modified. These constants facilitate such attribute setting statements as: Attr := Dim + Blinking + Magenta; and attribute testing statements like: If (Attr and Modified) <> 0 Then . . . H. Modified_Data_Tags __________________ The modified data tag (bit 4) is normally set off (0) when a data field is written. If the user changes any data in the field during a ReadScreen procedure, it will be set on (1). You can, however turn it on before writing the field and it will stay on no matter what the user does. If the user simply moves the cursor through a field with the cursor control keys, the MDT will not be set. If the user deletes Pascal Library Member EM3270.INC Page 8 or enters any data in the field, the MDT will be set, even ___ if the data is the same as the original contents. The MDT is set or not in an invisible field exactly as for a visible field. I. Defining_Color_Palettes _______________________ The background and foreground colors for "bright" and "dim" fields are controlled by setting four global variables named BrightBG, BrightFG DimBG, DimFG These are of type Byte. The background colors may be set to any of the "dark" colors, 0 (Black) through 7 (LightGray). The foreground colors may be set to any of the 16 standard colors, 0 (Black) through 15 (White). These variables may be set or reset at any time and can be used to cause some interesting effects on color screens (they have absolutely no effect on monochrome screens). For example, a data entry field can be written with one palette in effect and read with another in effect by changing the palette variables between the WriteField (or RewriteField) and the ReadScreen procedure calls. As the user keys data into the field, the background and foreground colors change as each character is entered. These variables are normally reset immediately after the InitScreen procedure call. InitScreen sets them to white on black for dim and black on white (inverse video) for black, giving an approximation of the apearance of a monochrome screen. Note that the entire screen background color is set to the DimBG value, so that "bright" fields appear as "islands" of the BrightBG color in a sea of DimBG. J. Field_Positioning _________________ The position of a data or prompt field on the screen is specified by an "X,Y" pair of coordinate. X is the column number on the screen and Y is the line number. X must be from 1 to 80. Y must be from 1 to 25. The use of line 25 is discouraged, except for brief error messages. The procedures use the right end of line 25 to display the Insert mode flag, and other uses for this line may be added to EM3270 in the future. Besides, the most common models of the 3270 don't have a 25th line. I. Field_Length ____________ The length of a data or prompt field is specified at the time it is written. The length must be from 1 to 79 charac- Pascal Library Member EM3270.INC Page 9 ters. There is no necessary connection between the length of a string written to a field and the length of the field. A 20 character long field can be initialized with a 4 character string (in which case 16 spaces will be added to the end of the displayed field), or with a 100 character string (in which case the last 80 characters will not be displayed). However, when retrieving strings from the screen, care should be taken to ensure that the receiving string is at least as long as the defined screen field. Defining a 15 character screen field and then trying to read it back into a 10 character string can cause subtle and insidious prob- lems that would bring tears to the eyes of the most experi- enced Turbo programmers. This flexibility (and its attendant problems) result from the {$V-} option at the beginning of your program. No test is made for "line-wrap". A 20-character field writ- ten at X position 75 will give unpredictable results. J. AID_Keys ________ The AID keys recognized by EM3270 are the ENTER (RETURN) key, the ESCAPE key, F1..F10, Alt/F1..Alt/F10, and Alt/1..Alt/3. An "enumerated type" is defined at the begin- ning of the INCLUDE file: AID = (Enter,Escape,F1,F2,F3,F4,F5,F6,F7,F8,F9,F10, F11,F12,F13,F14,F15,F16,F17,F18,F19,F20, PA1,PA2,PA3); Alt/F1..Alt/F2 map to F11..F20; Alt/1..Alt/3 map to PA1..PA3. You must define at least one variable of type AID to hold the value of the AID key pressed to return control to your program. The value of this variable may be tested for any of its defined values with If or Case statements. Most 3270 keyboards have more AID keys than this. 3270 keyboards have from 9 to 24 PF ("programmed function") keys, plus ATTN, CLEAR, and a strange and seldom used one called "Test Req". The PC keyboard's 10 function keys map nicely to the 3270's PF1 through PF20, using the Alt key to generate PF11 through PF20, and the Alt/1 through Alt/3 key combina- tions map to PA1 through PA3. The RETURN key is mapped to the 3270 ENTER key by the EM3270 procedures. The ESCAPE key can be used to simulate the 3270's CLEAR or ATTN key at your option. If you need more AID keys, you can modify the fol- lowing sections of code in EM3270.INC to add them: Pascal Library Member EM3270.INC Page 10 - The Const section of procedure ReadScreen - The definition of type AID - Procedure GetChar - The last Case option in procedure ReadScreen - The "Until" test in ReadScreen III. PROCEDURES A. InitScreen __________ USAGE: InitScreen; { no parameters } This procedure has no visible affect. It merely initializes the heap pointers to Nil, determines the monitor type, and sets the background and foreground colors to their default values. THIS PROCEDURE MUST BE EXECUTED BEFORE ANY OTHER EM3270 PROCEDURE AND SHOULD BE EXECUTED ONLY ONCE!!!!! B. NewScreen _________ USAGE: NewScreen; { no parameters } This procedure clears and resets the screen and deletes all fields from the heap. It should be used every time a new set of prompts and fields is to be presented. Using ClrScr will clear the screen, but all data fields from the previous screen will still exist and results could be catastrophic. C. WritePrompt ___________ USAGE: WritePrompt (X, Y, Attr, Lngth : Byte; Strngin : ScreenLine); X = Column number of prompt (1..79) Y = Line number of prompt (1..25) Attr = Atrribute for prompt Lngth = Length of prompt field (1..79) Strngin = Prompt literal (any string) This procedure writes one prompt to the screen at the posi- tion indicated by X,Y. All bits of the attribute are effective except the Visible/Invisible bit and the Modified Data Tag. D. WriteField __________ USAGE: WriteField (X, Y, Attr, Lngth : Byte; Strngin : ScreenLine); X = Column number of data field (1..79) Y = Line number of data field (1..25) Attr = Atrribute for data field Lngth = Length of data field (1..79) Pascal Library Member EM3270.INC Page 11 Strng = Data field literal (any string) This procedure defines and writes one data field to the screen at the position indicated by X,Y with the character- istics indicated by Attr. The field number is determined by the number of executions of WriteField since the last execu- tion of NewScreen. E. ReadScreen __________ USAGE: ReadScreen (FieldNo : Byte; Var FuncKey : AID); FieldNo = Data field number in wich to initially place the cursor FuncKey = A variable you define in which the AID key pressed by the user is returned This procedure "unlocks" the keyboard for data entry. The procedure maintains control allowing the user to enter or erase data in any data field until an AID key is pressed. Upon return from ReadScreen, the position of the cursor at the time the user pressed the AID key is available in a record named "Cursor". Its fields (all of type BYTE) are: Cursor.Field The field number in which the cursor was positioned. Cursor.Char The character number within the field. May be used to index the string returned from the field. Cursor.X The screen column of the cursor. Cursor.Y The screen line of the cursor. F. GetField ________ USAGE: GetField (FieldNo : Byte; Var Strng : ScreenLine; Var Attr : Byte); FieldNo = Data field number to be retrieved Strng = Returned string containing current value of field. Must be at least as long as the defined field. Attr = Returned current attribute of data field This procedure returns the current value of a data field. It is normally used after a ReadScreen procedure, once for each field to be examined. G. RewriteField ____________ USAGE: RewriteField (FieldNo : Byte; Strngin : ScreenLine; Attr : Byte); Pascal Library Member EM3270.INC Page 12 FieldNo = Data field number to be rewritten Strng = String to be written Attr = New attribute for field This procedure replaces the value of a data field already on the screen. Some occasions on which it is normally used are: 1. Displaying records from a file which the user may change. 2. Displaying default values which may be overkeyed. 3. Rewriting a field that has failed an edit test with a blinking or alternate color attribute. 2. The data field has been "prettied up" by editing and is being displayed in its modified form for the benefit of the user. H. SetVid ______ NormVid _______ LowVid ______ USAGE SetVid (At : Byte); NormVid (At : Byte); LowVid (At : Byte); At = Attribute byte These procedures may be used to set the video mode based on an attribute byte at any time. SetVid sets the mode based on the entire attribute except for the Visible/Invisible bit. NormVid and LowVid bypass the Bright/Dim bit and set the video mode directly to "bright" or "dim" respectively, with blink and color as specified by the attribute. Calls to these procedures are normally made before using Turbo's Write or WriteLn procedures to add something to an existing screen (an error message on line 25, for instance). You could use TextBackground and TextColor just as easily, _____ but the use of these procedures will keep your program "attribute oriented". IV. OPERATION A. Cursor_Control ______________ During the ReadScreen procedure the cursor can be moved anywhere in any data field without affecting the contents of the fields by the use of several cursor control keys. Cursor movements and the keys which control them are as follows: Pascal Library Member EM3270.INC Page 13 CURSOR RIGHT: Right Arrow. Moves the cursor one position to the right without affecting data. if the cursor is in the last position of a field, it jumps to the beginning of the next field. CURSOR LEFT: Left Arrow. Moves the cursor one position to the left without affecting data. If the cursor is in the first position of a field, it jumps to the beginning of the preceding field. TAB RIGHT: TAB key. Moves the cursor to the beginning of the next data field without affecting data. TAB LEFT: Shifted TAB or Backspace key. Moves the cursor to the beginning of the preceding data field without affecting data. The Backspace key is used because it is in the approximate position of the Backtab key on most 3270 keyboards. Shifted TAB is also used, because of PC conventions. NEW LINE: PgDn key. Moves the cursor to the beginning of the first data field on the next line down which contains a data field. If the cursor line is the last such line on the screen the cursor wraps around to the first line containing a data field. The choice of PgDn is arbitrary, and can easily be changed to Down Arrow or some other key. Unfortu- nately, on most 3270 keyboards the New Line key is in about the same position as the PC's Return (Enter) key, and moreover is marked the same (ar- row down and left). If the Return key were used for New Line, there would be no appropriate key to use for Enter. (The 3270's Enter key is about where the PC's Caps Lock key is, except on the 3270 "data entry" keyboards, where it is located roughly where the PC's left bracket key is. IBM was never much good at ergonomics or consistency.) Also, you'd think that logically the PgUp key would jump the cursor UP one line; there is no such key on the 3270. HOME: The Home key returns the cursor to the first data field on the screen. B. Editing_Keys ____________ INSERT MODE: Ins key. In insert mode, characters typed by the user are inserted at the cursor position, pushing characters right until a non-blank charac- ter is the last in the field. This is a toggle. Pressing it again turns off insert mode. (The 3270 keyboard has a RESET key which turns off insert mode.) DELETE: Del key. The character at the cursor is deleted Pascal Library Member EM3270.INC Page 14 and all characters in the field to the right are shifted left one position. A space is shifted into the rightmost position of the field. ERASE EOF: End key. All characters in the data field from the cursor position to the end of the field are set to spaces (erased). This is another arbitrary key choice, since there is no analogous key on the PC. C. Data_Entry __________ Any printable ASCII character entered ($20..$7E or ' '..'~') will replace the character in the cursor position and turn on the modified data tag of the field. D. Data_Transmission _________________ When all data entry has been completed, control is returned to the application program by pressing any of the AID keys. V. PROBLEMS A. One of the most common problems in using EM3270 is FORGET- TING TO CALL INITSCREEN before the first call to one of the other procedures. The symptoms of this are almost always a totally "locked up" system. B. CALLING WRITEFIELD MORE THAN MAXFIELDS TIMES will almost always send your program into never never land. C. FORGETTING TO CALL NEWSCREEN before writing prompts or cal- ling WriteField will not lock up the system, but will result in "garbage" screens and unpredictable cursor positioning. D. OVERLAPPING FIELDS AND/OR PROMPTS are simply errors in specifying correct X/Y values in WritePrompt and WriteField. E. SPECIFYING A FIELD NUMBER HIGHER THAN THE HIGHEST ONE DE- FINED in arguments to ReadScreen, RewriteField and GetField causes unpredictable results - frequently a total system lockup. F. THE RETURN KEY can cause problems to people who are used to the Teletype (and PC) standard of hitting it after each field. It can also cause problems for some 3270 operators since on the PC keyboard it is in the sames position as the NEW LINE key on most 3270 keyboards. One way to get around this is to modify the EM3270 procedures so that the RETURN key is not one of the AID keys, but performs the same func- tion as TAB or PgDn. Another way is to eliminate the ENTER function through programming: every time you return from ReadScreen with an AID value of ENTER, simply go back to ReadScreen again with the cursor placed in the next field (determined by adding 1 to Cursor.Field and allowing for Pascal Library Member EM3270.INC Page 15 falling out of the last screen field). In either of these solutions, you sacrifice the ENTER AID function and must use only the function keys or ESCAPE to get your data.