home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / EM3270.ZIP / EM3270.DOC next >
Encoding:
Text File  |  1986-07-13  |  40.2 KB  |  990 lines

  1.         Pascal Library Member EM3270.INC                 Page 1
  2.  
  3.  
  4.                                   INTRODUCTION
  5.                                   ____________
  6.  
  7.         The  EM3270  procedures are the copyrighted property of  Piedmont 
  8.         Specialty Software.  They are distributed as "Shareware" to  save 
  9.         the enormous costs of publishing,  advertising,  and distributing 
  10.         software through the normal commercial channels.  In keeping with 
  11.         the established "rules" of this type of distribution, we ask that 
  12.         you:
  13.  
  14.           1. Send $20.00 to Piedmont Specialty Software,  P. O. Box 6637, 
  15.              Macon, GA  31208, if you find the procedures useful.
  16.  
  17.           2. Use  the procedures for your personal use only.  If you wish 
  18.              to use them in software for commercial distribution,  please 
  19.              contact us at the above address or by telephone at (912) 474 
  20.              2318 for details of a commercial license.
  21.  
  22.           3. Distribute the procedures freely, so long as you
  23.  
  24.                   - do not modify them,
  25.                   - include this documentation with them,
  26.                   - include the acompanying demonstration program.
  27.  
  28.         We  have used these procedures in many programs in the  last  two 
  29.         years  and  have found their screen management facilities  to  be 
  30.         well  received by all users from novice to expert.  We hope  that 
  31.         you will find them as useful and productive as we have.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.         Pascal Library Member EM3270.INC                 Page 2
  69.  
  70.  
  71.         I. PURPOSE
  72.  
  73.              Turbo  Pascal  library member EM3270.INC is an INCLUDE  file 
  74.              containing  a  set of procedures  which  allows  full-screen 
  75.              editing  patterned  after the IBM 3270 family of  terminals. 
  76.              The  3270  family consists of a number  of  terminal  models 
  77.              designed  to  connect to the System/370 family of  mainframe 
  78.              processors.  There are hundreds of thousands of them in  use 
  79.              by office workers all over the world.  They operate as "full 
  80.              screen  I/O"  terminals.  That is,  the mainframe  sends  an 
  81.              entire screen at a time to the terminal, the user enters and 
  82.              edits  all data on the screen while "disconnected" from  the 
  83.              mainframe,  and  when finished transmits the entire modified 
  84.              screen back to the mainframe by pressing one of the  "atten-
  85.              tion identifier" (AID) keys.
  86.  
  87.              The  EM3270 procedures facilitate writing programs in  Turbo 
  88.              Pascal which give the user the impression that he is working 
  89.              with  a 3270 terminal.  Then programming methods you use  in 
  90.              handling the screens are very different from those used by a 
  91.              mainframe programmer, but the appearance to the user closely 
  92.              mimics  a  3270 with only a few compromises made to  account 
  93.              for the differences in a PC keyboard and a 3270 keyboard.
  94.              
  95.              Significant features of the routines include:
  96.  
  97.                a. Attribute_bytes specifying visible or invisible, bright 
  98.                   _______________                                         
  99.                   or dim,  steady or blinking characters,  foreground co-
  100.                   lors, and Modified Data Tags.
  101.                b. Cursor_control consisting of character right, character 
  102.                   ______________                                          
  103.                   left,  tab forward, tab backward, home cursor, and next 
  104.                   line.
  105.                c. Field_selection  on  writes and reads to and  from  the 
  106.                   _______________                                         
  107.                   screen.
  108.                d. Cursor_positioning  under program control  before  data 
  109.                   __________________                                      
  110.                   entry.
  111.  
  112.         II. USAGE
  113.  
  114.           A. Program_Requirements
  115.              ____________________
  116.  
  117.              Before  inclusion of EM3270.INC,  the  following  statements 
  118.              must appear:
  119.  
  120.                   {$V-}
  121.                   . . .
  122.                   Const
  123.                     MaxFields = xxx;
  124.            
  125.              Where  xxx  is the maximum number of data fields  which  can 
  126.                                                   ____                    
  127.              appear  on any screen,  and is from 1 to 255.  Any number of 
  128.              prompt fields can appear.
  129.              ______                   
  130.  
  131.              NOTE:  DO_NOT  SET  COMPILER DIRECTIVE {$U+} IN ANY  PROGRAM 
  132.              NOTE:  DO_NOT  SET  COMPILER DIRECTIVE {$U+} IN ANY  PROGRAM 
  133.              ______
  134.                     ______                                                
  135.              USING  THE EM3270 PROCEDURES.  TURBO DOES STRANGE THINGS  TO 
  136.              USING  THE EM3270 PROCEDURES.  TURBO DOES STRANGE THINGS  TO 
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.         Pascal Library Member EM3270.INC                 Page 3
  146.                                                                
  147.  
  148.  
  149.              THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD  INPUT 
  150.              THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD  INPUT 
  151.              PROCEDURES OF EM3270 BECOME FRIED.
  152.              PROCEDURES OF EM3270 BECOME FRIED.
  153.  
  154.              The EM3270 routines use the heap,  but should not  interfere 
  155.              with any other heap operations of the calling program.
  156.              THE  DISPOSE COMMAND IS USED IN HEAP MANAGEMENT.  A  CALLING 
  157.                   _______                                                 
  158.              PROGRAM MUST NOT USE TURBO'S MARK AND RELEASE!!!!!
  159.                           ___                                  
  160.  
  161.           B. Initialization
  162.              ______________
  163.  
  164.              Before  any other EM3270 procedure is executed,  the  EM3270 
  165.                      ___                                                  
  166.              system must be initialized by issuing the following command:
  167.                     ____                                                 
  168.  
  169.                   InitScreen;
  170.  
  171.              This command must be issued once and only once for an execu-
  172.              tion of your program.
  173.  
  174.           C. Screen_Handling_Logic
  175.              _____________________
  176.  
  177.              The  general flow of logic in handling a screen consists  of 
  178.              the following sequence:
  179.  
  180.                     .
  181.                     .
  182.                     .
  183.              Procedure PresentScreen1;
  184.                Const
  185.                 Strng1 : String[8] = "Prompt 1";
  186.                 Strng2 : String[8] = "Prompt 2";
  187.                     .
  188.                     .
  189.                     .
  190.              Begin 
  191.                NewScreen;          { clear all existing fields }
  192.                WritePrompt(1,1,Dim,8,Strng1); { write a prompt }
  193.                WritePrompt(2,1,Dim,8,Strng2); { write a prompt }
  194.                     .
  195.                     .              { repeat for all prompts }
  196.                     .
  197.                Attr := 0;      {Bright, Steady, Visible, Unchanged}
  198.                WriteField(10,1,Attr,14,' ')      { define field 1 }
  199.                WriteField(10,2,Attr,16,' ')      { define field 2 }
  200.                     .
  201.                     .              { repeat for all data fields }
  202.                     .
  203.              End;  { of procedure }
  204.                     .
  205.                     .
  206.                     .
  207.              Procedure GetScreen1;
  208.              Begin
  209.                ReadScreen(FieldNo,FK);   { open screen for input }
  210.                GetField(1,Varbl1,Attr);  { retrieve a data field}
  211.                GetField(2,Varbl2,Attr);  { retrieve a data field}
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.         Pascal Library Member EM3270.INC                 Page 4
  221.  
  222.  
  223.                     .
  224.                     .
  225.              End; { of procedure }
  226.                     .
  227.                     .
  228.              Procedure RewriteScreen1;
  229.              Begin
  230.                Attr := 0;
  231.                RewriteField(1,Varbl1,Attr); { rewrite field 1 bright }
  232.                RewriteField(2,Varbl2,Attr); { rewrite field 2 bright }
  233.                     .
  234.                     .
  235.                     .
  236.              End; { of procedure }
  237.                     .
  238.                     .
  239.              Begin     { begin mainline program }
  240.                InitScreen;  { Initialize EM3270 }
  241.                     .
  242.                     .       { open files, etc. }
  243.                     .
  244.                PresentScreen1;  { write blank screen 1 }
  245.                Repeat
  246.                  GetScreen1;
  247.                     .
  248.                     .            { process screen 1 variables }
  249.                     .
  250.                  RewriteScreen1; { replace fields with new values }
  251.                Until Finished;
  252.                     .
  253.                     .
  254.  
  255.              Each of the EM3270 procedures is covered in Section III.
  256.  
  257.           D. Data_Fields
  258.              ___________
  259.  
  260.              A  data field is a string which is written to the screen and 
  261.                                 ______                                    
  262.              into  which  the  cursor can be moved  during  a  ReadScreen 
  263.              procedure.
  264.            
  265.              Every  data field written to the screen is assigned a  field 
  266.              number from 1 to MaxFields.  Data fields are numbered in the 
  267.              order in which you write them to the screen. It is up to you 
  268.              to keep track of what each field number contains. You always 
  269.                                                                    ______ 
  270.              address a data field by its number.
  271.  
  272.              Care must be exercised in planning the sequence in which you 
  273.              write  data fields because cursor tabbing at program  execu-
  274.              tion  time is determined by field number.  (This is a depar-
  275.              ture from the 3270 standard,  in which the field sequence is 
  276.              always  left-to-right,  top-to-bottom.) If the cursor is  in 
  277.              field 14 and the tab key pressed,  it will jump to field 15, 
  278.              no matter where 15 is.  To keep from driving the user  nuts, 
  279.              screens  should  normally  be designed so  that  fields  are 
  280.              always  written  in the  3270  left-to-right,  top-to-bottom 
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.         Pascal Library Member EM3270.INC                 Page 5
  290.  
  291.  
  292.              sequence.
  293.  
  294.              An  example  of when you might want to place fields  out  of 
  295.              sequence  might  be a field that is almost always  the  same 
  296.              value,  but should visually appear close to some other vari-
  297.              able  on  the  screen (state abbreviation in  a  local  area 
  298.              mailing list,  for example).  In such a case, you can define 
  299.              it  as the last screen field and provide the default  value. 
  300.              The cursor will skip over the field in normal  tabbing,  but 
  301.              the  user can still reach it when it needs to be changed  by 
  302.              tabbing until the cursor finally does reach it.
  303.  
  304.              You  specify  the  position  and  length  of  a  data  field      
  305.              when  you  first  write it with  the  WriteField  procedure. 
  306.              Position  and  length are fixed at that time and  cannot  be 
  307.              changed afterward.  When you retrieve a data field (with the 
  308.              GetField  procedure),  the string returned is always of  the 
  309.              length specified when the field was first written.
  310.  
  311.              You  also  specify  the attribute of a data field  when  you 
  312.              write it. (Attributes are discussed fully below.) The attri-
  313.              bute  of  a data field can be changed when you  rewrite  the 
  314.                                     ___                                   
  315.              field,  and  its  Modified  Data Tag  bit  is  automatically 
  316.              changed  if  any  data  in the field  is  changed  during  a 
  317.              ReadScreen procedure.
  318.  
  319.              The  routines DO_NOT check for a "collision" between fields. 
  320.                            ______                                         
  321.              If you write one field on top of another, the last field out 
  322.              will  be the one the user sees.  However,  the value of  the 
  323.              two  fields will be maintained intact,  and if you  retrieve 
  324.              them both you will get the correct values. The visual effect 
  325.              to a user, though, is quite bizarre.
  326.  
  327.           E. Prompt_Fields
  328.              _____________
  329.  
  330.              Prompts are strictly for the user's benefit and are  treated 
  331.              very different from data fields.  Once written,  a prompt is 
  332.              forgotten - it remains on the screen, but cannot be accessed 
  333.              thereafter,  other  than to overwrite it with another prompt 
  334.              or a data field.
  335.  
  336.              Prompts  are not numbered and there is no limit to how  many 
  337.              you can write to a screen,  other than the physical capacity 
  338.              of the screen.
  339.  
  340.              The  writing of prompts and data fields may be interspersed.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.         Pascal Library Member EM3270.INC                 Page 6
  359.  
  360.  
  361.           F. Attributes
  362.              __________
  363.  
  364.              An  attribute is a byte associated with a field (either data 
  365.              or  prompt)  which defines certain  characteristics  of  the 
  366.              field. The bits of the byte are used as follows:
  367.  
  368.                             Bit ==>  7  6  5  4  3  2  1  0
  369.                   Attribute Byte =>  X  X  X  X  X  X  X  X
  370.                                      ^  ^  ^  ^  ^        ^
  371.                   0=Bright           |  |  |  |  |________|
  372.                   1=Dim______________|  |  |  |      |
  373.                                         |  |  |      |
  374.                   0=Steady              |  |  |      |
  375.                   1=Blinking____________|  |  |      |
  376.                                            |  |      |
  377.                   0=Visible                |  |      |
  378.                   1=Invisible______________|  |      |
  379.                                               |      |
  380.                   0=Unchanged                 |      |
  381.                   1=Modified__________________|      |
  382.                                                      |
  383.                   0=Use default color                |
  384.                   1-15=Foreground color______________|
  385.  
  386.           G. Field_Appearance
  387.              ________________
  388.  
  389.              Original models of the 3270 could display a character in one 
  390.              of  two  brightnesses:   "normal"  (dim)  or   "highlighted" 
  391.              (bright).  Later  models extended this capability to include 
  392.              reverse video and blinking,  as well as color attributes.
  393.  
  394.              The EM3270 procedures implement the attributes in one of two 
  395.              ways,  depending  on  whether they are running on a  machine 
  396.              with a monochrome or color monitor (the EGA is not  support-
  397.              ed). The Steady/Blinking and the Visible/Invisible bits work 
  398.              the same on either type.
  399.  
  400.              If the Steady/Blinking bit is 0, the characters of the field 
  401.              or prompt are displayed normally; if it is 1, they blink off 
  402.              and on in a highly attention-grabbing (and distracting) way. 
  403.              Blinking characters are normally used in rewritten fields to 
  404.              call attention to a data entry error.
  405.  
  406.              If  the Visible/Invisible bit is 0,  the characters  of  the 
  407.              field are displayed normally; if it is 1, they are displayed 
  408.              as spaces (that is,  they are invisible). Moreover, any data 
  409.              keyed into the field will not be displayed. The cursor moves 
  410.              to  the  right as characters are keyed,  and the  characters 
  411.              entered are available to your program, but the person at the 
  412.              keyboard never sees them (unless you display them  elsewhere 
  413.              on the screen in a visible field). In the mainframe environ-
  414.              ment  invisible  fields are commonly used for the  entry  of 
  415.              security  passwords.  Their use in the micro environment  is 
  416.              more limited.
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.         Pascal Library Member EM3270.INC                 Page 7
  427.  
  428.  
  429.              On  the monochrome display,  the Bright/Dim bit  causes  the 
  430.              characters  of the field to be displayed in normal white  on 
  431.              black (Dim) when set to 1, or as inverse video (bright) when 
  432.              set to 0.  In the 3270, the equivalent bit simply causes the 
  433.              equivalent  of  Turbo's LowVideo and  NormVideo  procedures. 
  434.              However, one of the shortcomings of the original 3270 family 
  435.              was  that their was no easy way to show the user the  length 
  436.              of  a  data entry field.  The cursor always moves  into  the 
  437.              leftmost  position  of the field,  but there was nothing  to 
  438.              show  the  user where the right end of the  field  was,  and 
  439.              therefore no sure indication of how many characters he could 
  440.              enter before the cursor jumped to the next field. The intro-
  441.              duction  of inverse video models offered a solution to  this 
  442.              problem  and  programmers quickly adopted  the  standard  of 
  443.              setting  unprotected  (data entry) fields to  inverse.  This 
  444.              standard is implemented in the Bright/Dim bit in EM3270.
  445.  
  446.              On the color display,  the Bright/Dim bit selects one of two 
  447.              background/foreground  color  combinations  (see  section  I 
  448.              below). This has nothing to do with the actual brightness or 
  449.              dimness of the background and characters; it merely provides 
  450.              a convenient way of selecting between two palettes.
  451.  
  452.              The  color  bits of the attribute are used to  override  the 
  453.              foreground  color of the palette selected by the  Bright/Dim 
  454.              bit.  If  these  four bits are 0000,  the palette  color  is 
  455.              displayed. A value of 0001 through 1111 cause the foreground 
  456.              color  to be the equivalent color (dark blue through white). 
  457.              Note  that Turbo provides predefined integer  constants  for 
  458.              each  color  which can be conveniently added or ORed  to  an 
  459.              attribute  byte.  For example,    Attr := LightGreen    will 
  460.              give  an attribute that will cause light green characters on 
  461.              the "bright" background color. The color bits have no effect 
  462.              on a monochrome monitor.
  463.  
  464.              Four  constants  are  defined in EM3270 for  convenience  in 
  465.              working with attributes: Dim, Blinking, Invisible, Modified. 
  466.              These constants facilitate such attribute setting statements 
  467.              as:
  468.  
  469.                        Attr := Dim + Blinking + Magenta;
  470.  
  471.              and attribute testing statements like:
  472.  
  473.                        If (Attr and Modified) <> 0 Then . . .
  474.  
  475.           H. Modified_Data_Tags
  476.              __________________
  477.  
  478.              The modified data tag (bit 4) is normally set off (0) when a 
  479.              data field is written.  If the user changes any data in  the 
  480.              field during a ReadScreen procedure,  it will be set on (1). 
  481.              You can,  however turn it on before writing the field and it 
  482.              will  stay  on  no matter what the user does.  If  the  user 
  483.              simply  moves  the cursor through a field  with  the  cursor 
  484.              control keys,  the MDT will not be set.  If the user deletes 
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.         Pascal Library Member EM3270.INC                 Page 8
  494.  
  495.  
  496.              or enters any data in the field,  the MDT will be set,  even 
  497.                        ___                                                
  498.              if the data is the same as the original contents. The MDT is 
  499.              set  or  not in an invisible field exactly as for a  visible 
  500.              field.
  501.  
  502.           I. Defining_Color_Palettes
  503.              _______________________
  504.  
  505.              The background and foreground colors for "bright" and  "dim" 
  506.              fields are controlled by setting four global variables named
  507.  
  508.                             BrightBG, BrightFG
  509.                             DimBG,    DimFG
  510.  
  511.              These are of type Byte.  The background colors may be set to 
  512.              any of the "dark" colors,  0 (Black) through 7  (LightGray). 
  513.              The  foreground colors may be set to any of the 16  standard 
  514.              colors, 0 (Black) through 15 (White).
  515.  
  516.              These  variables may be set or reset at any time and can  be 
  517.              used  to  cause some interesting effects  on  color  screens 
  518.              (they have absolutely no effect on monochrome screens).  For 
  519.              example,  a data entry field can be written with one palette 
  520.              in  effect  and read with another in effect by changing  the 
  521.              palette  variables between the WriteField (or  RewriteField) 
  522.              and  the ReadScreen procedure calls.  As the user keys  data 
  523.              into the field,  the background and foreground colors change 
  524.              as each character is entered.
  525.  
  526.              These  variables  are normally reset immediately  after  the 
  527.              InitScreen procedure call.  InitScreen sets them to white on 
  528.              black  for dim and black on white (inverse video) for black, 
  529.              giving  an  approximation of the apearance of  a  monochrome 
  530.              screen.
  531.  
  532.              Note  that the entire screen background color is set to  the 
  533.              DimBG value,  so that "bright" fields appear as "islands" of 
  534.              the BrightBG color in a sea of DimBG.
  535.  
  536.           J. Field_Positioning
  537.              _________________
  538.  
  539.              The  position  of a data or prompt field on  the  screen  is 
  540.              specified  by an "X,Y" pair of coordinate.  X is the  column 
  541.              number on the screen and Y is the line number.
  542.  
  543.              X must be from 1 to 80.  Y must be from 1 to 25.  The use of 
  544.              line 25 is discouraged, except for brief error messages. The 
  545.              procedures  use  the  right end of line 25  to  display  the 
  546.              Insert mode flag,  and other uses for this line may be added 
  547.              to EM3270 in the future.  Besides, the most common models of 
  548.              the 3270 don't have a 25th line.
  549.  
  550.           I. Field_Length
  551.              ____________
  552.  
  553.              The  length  of a data or prompt field is specified  at  the 
  554.              time it is written.  The length must be from 1 to 79 charac-
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.         Pascal Library Member EM3270.INC                 Page 9
  564.  
  565.  
  566.              ters.
  567.  
  568.              There  is  no necessary connection between the length  of  a 
  569.              string written to a field and the length of the field.  A 20 
  570.              character  long field can be initialized with a 4  character 
  571.              string  (in which case 16 spaces will be added to the end of 
  572.              the  displayed field),  or with a 100 character  string  (in 
  573.              which  case  the last 80 characters will not be  displayed). 
  574.              However,  when  retrieving  strings from  the  screen,  care 
  575.              should  be taken to ensure that the receiving string  is  at 
  576.              least  as  long as the defined screen field.  Defining a  15 
  577.              character screen field and then trying to read it back  into 
  578.              a  10 character string can cause subtle and insidious  prob-
  579.              lems  that would bring tears to the eyes of the most experi-
  580.              enced Turbo programmers. This flexibility (and its attendant 
  581.              problems)  result from the {$V-} option at the beginning  of 
  582.              your program.
  583.  
  584.              No test is made for "line-wrap".  A 20-character field writ-
  585.              ten at X position 75 will give unpredictable results.
  586.  
  587.           J. AID_Keys
  588.              ________
  589.  
  590.              The  AID  keys recognized by EM3270 are the  ENTER  (RETURN) 
  591.              key,   the  ESCAPE  key,   F1..F10,   Alt/F1..Alt/F10,   and 
  592.              Alt/1..Alt/3.  An "enumerated type" is defined at the begin-
  593.              ning of the INCLUDE file:
  594.  
  595.                AID = (Enter,Escape,F1,F2,F3,F4,F5,F6,F7,F8,F9,F10,
  596.                       F11,F12,F13,F14,F15,F16,F17,F18,F19,F20,
  597.                       PA1,PA2,PA3);
  598.  
  599.              Alt/F1..Alt/F2   map  to  F11..F20;   Alt/1..Alt/3  map   to 
  600.              PA1..PA3.
  601.  
  602.              You  must define at least one variable of type AID  to  hold 
  603.              the  value of the AID key pressed to return control to  your 
  604.              program. The value of this variable may be tested for any of 
  605.              its defined values with If or Case statements.
  606.  
  607.              Most  3270  keyboards  have more AID keys  than  this.  3270 
  608.              keyboards have from 9 to 24 PF ("programmed function") keys, 
  609.              plus ATTN,  CLEAR,  and a strange and seldom used one called 
  610.              "Test Req". The PC keyboard's 10 function keys map nicely to 
  611.              the 3270's PF1 through PF20,  using the Alt key to  generate 
  612.              PF11 through PF20,  and the Alt/1 through Alt/3 key combina-
  613.              tions  map to PA1 through PA3.  The RETURN key is mapped  to 
  614.              the 3270 ENTER key by the EM3270 procedures.  The ESCAPE key 
  615.              can be used to simulate the 3270's CLEAR or ATTN key at your 
  616.              option.  If you need more AID keys,  you can modify the fol-
  617.              lowing sections of code in EM3270.INC to add them:
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.         Pascal Library Member EM3270.INC                 Page 10
  631.  
  632.  
  633.                   - The Const section of procedure ReadScreen 
  634.                   - The definition of type AID
  635.                   - Procedure GetChar
  636.                   - The last Case option in procedure ReadScreen
  637.                   - The "Until" test in ReadScreen
  638.  
  639.         III. PROCEDURES
  640.  
  641.           A. InitScreen
  642.              __________
  643.  
  644.              USAGE:    InitScreen;    { no parameters }
  645.  
  646.              This procedure has no visible affect.  It merely initializes 
  647.              the heap pointers to Nil,  determines the monitor type,  and 
  648.              sets  the background and foreground colors to their  default 
  649.              values.
  650.  
  651.              THIS  PROCEDURE  MUST BE EXECUTED BEFORE ANY OTHER  EM3270 
  652.              PROCEDURE AND SHOULD BE EXECUTED ONLY ONCE!!!!!
  653.  
  654.           B. NewScreen
  655.              _________
  656.  
  657.              USAGE:    NewScreen;     { no parameters }
  658.  
  659.              This procedure clears and resets the screen and deletes  all 
  660.              fields from the heap. It should be used every time a new set 
  661.              of prompts and fields is to be presented.  Using ClrScr will 
  662.              clear  the  screen,  but all data fields from  the  previous 
  663.              screen will still exist and results could be catastrophic.
  664.  
  665.           C. WritePrompt
  666.              ___________
  667.  
  668.              USAGE:    WritePrompt (X, Y, Attr, Lngth : Byte;
  669.                                     Strngin           : ScreenLine);
  670.  
  671.                   X = Column number of prompt (1..79)
  672.                   Y = Line number of prompt (1..25)
  673.                   Attr = Atrribute for prompt
  674.                   Lngth = Length of prompt field (1..79)
  675.                   Strngin = Prompt literal (any string)
  676.  
  677.              This  procedure writes one prompt to the screen at the posi-
  678.              tion  indicated  by  X,Y.  All  bits of  the  attribute  are 
  679.              effective except the Visible/Invisible bit and the  Modified 
  680.              Data Tag.
  681.  
  682.          D. WriteField
  683.             __________
  684.  
  685.              USAGE:    WriteField (X, Y, Attr, Lngth : Byte;
  686.                                    Strngin           : ScreenLine);
  687.  
  688.                   X = Column number of data field (1..79)
  689.                   Y = Line number of data field (1..25)
  690.                   Attr = Atrribute for data field
  691.                   Lngth = Length of data field (1..79)
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.         Pascal Library Member EM3270.INC                 Page 11
  701.  
  702.  
  703.                   Strng = Data field literal (any string)
  704.  
  705.              This  procedure  defines and writes one data  field  to  the 
  706.              screen  at the position indicated by X,Y with the character-
  707.              istics indicated by Attr.  The field number is determined by 
  708.              the number of executions of WriteField since the last execu-
  709.              tion of NewScreen.
  710.  
  711.           E. ReadScreen
  712.              __________
  713.  
  714.              USAGE:    ReadScreen (FieldNo     : Byte;
  715.                                    Var FuncKey : AID);
  716.  
  717.                   FieldNo = Data field number in wich to initially  place 
  718.                             the cursor
  719.                   FuncKey = A  variable  you define in which the AID  key 
  720.                             pressed by the user is returned
  721.  
  722.              This  procedure "unlocks" the keyboard for data  entry.  The 
  723.              procedure  maintains control allowing the user to  enter  or 
  724.              erase data in any data field until an AID key is pressed.
  725.  
  726.              Upon return from ReadScreen,  the position of the cursor  at 
  727.              the  time  the  user pressed the AID key is available  in  a 
  728.              record named "Cursor". Its fields (all of type BYTE) are:
  729.  
  730.                   Cursor.Field   The field number in which the cursor was 
  731.                                  positioned.
  732.                   Cursor.Char    The  character number within the  field. 
  733.                                  May be used to index the string returned 
  734.                                  from the field.
  735.                   Cursor.X       The screen column of the cursor.
  736.                   Cursor.Y       The screen line of the cursor.
  737.  
  738.           F. GetField
  739.              ________
  740.  
  741.              USAGE:    GetField (FieldNo   : Byte;
  742.                                  Var Strng : ScreenLine;
  743.                                  Var Attr  : Byte);
  744.  
  745.                   FieldNo = Data field number to be retrieved
  746.                   Strng = Returned  string  containing current  value  of 
  747.                           field.  Must be at least as long as the defined 
  748.                           field.            
  749.                   Attr = Returned current attribute of data field
  750.  
  751.              This procedure returns the current value of a data field. It 
  752.              is normally used after a ReadScreen procedure, once for each 
  753.              field to be examined.
  754.  
  755.           G. RewriteField
  756.              ____________
  757.  
  758.              USAGE:    RewriteField (FieldNo : Byte;
  759.                                      Strngin : ScreenLine;
  760.                                      Attr    : Byte);
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.         Pascal Library Member EM3270.INC                 Page 12
  770.  
  771.  
  772.  
  773.                   FieldNo = Data field number to be rewritten
  774.                   Strng = String to be written
  775.                   Attr = New attribute for field
  776.  
  777.              This procedure replaces the value of a data field already on 
  778.              the screen. Some occasions on which it is normally used are:
  779.  
  780.                1. Displaying  records  from  a file which  the  user  may 
  781.                   change.
  782.  
  783.                2. Displaying default values which may be overkeyed.
  784.  
  785.                3. Rewriting  a field that has failed an edit test with  a 
  786.                   blinking or alternate color attribute.
  787.  
  788.                2. The data field has been "prettied up" by editing and is 
  789.                   being displayed in its modified form for the benefit of 
  790.                   the user.
  791.  
  792.           H. SetVid
  793.              ______
  794.              NormVid
  795.              _______
  796.              LowVid
  797.              ______
  798.  
  799.              USAGE     SetVid (At : Byte);
  800.                        NormVid (At : Byte);
  801.                        LowVid (At : Byte);
  802.  
  803.                   At = Attribute byte
  804.  
  805.              These procedures may be used to set the video mode based  on 
  806.              an attribute byte at any time. SetVid sets the mode based on 
  807.              the  entire attribute except for the Visible/Invisible  bit. 
  808.              NormVid  and  LowVid bypass the Bright/Dim bit and  set  the 
  809.              video mode directly to "bright" or "dim" respectively,  with 
  810.              blink and color as specified by the attribute.
  811.  
  812.              Calls  to  these procedures are normally made  before  using 
  813.              Turbo's  Write or WriteLn procedures to add something to  an 
  814.              existing screen (an error message on line 25, for instance). 
  815.              You  could use TextBackground and TextColor just as  easily, 
  816.                   _____                                                   
  817.              but  the  use  of these procedures will  keep  your  program 
  818.              "attribute oriented".
  819.  
  820.         IV. OPERATION
  821.  
  822.           A. Cursor_Control
  823.              ______________
  824.  
  825.              During  the  ReadScreen  procedure the cursor can  be  moved 
  826.              anywhere in any data field without affecting the contents of 
  827.              the fields by the use of several cursor control  keys.
  828.  
  829.              Cursor  movements  and  the keys which control them  are  as 
  830.              follows:
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.         Pascal Library Member EM3270.INC                 Page 13
  841.  
  842.  
  843.              CURSOR RIGHT:  Right Arrow. Moves the cursor one position to 
  844.                        the right without affecting data. if the cursor is 
  845.                        in the last position of a field,  it jumps to  the 
  846.                        beginning of the next field.
  847.  
  848.              CURSOR LEFT:  Left  Arrow.  Moves the cursor one position to 
  849.                        the left without affecting data.  If the cursor is 
  850.                        in the first position of a field,  it jumps to the 
  851.                        beginning of the preceding field.
  852.  
  853.              TAB RIGHT:  TAB  key.  Moves the cursor to the beginning  of 
  854.                        the next data field without affecting data.
  855.  
  856.              TAB LEFT:  Shifted TAB or Backspace key. Moves the cursor to 
  857.                        the  beginning of the preceding data field without 
  858.                        affecting data.  The Backspace key is used because 
  859.                        it  is in the approximate position of the  Backtab 
  860.                        key  on most 3270 keyboards.  Shifted TAB is  also 
  861.                        used, because of PC conventions.
  862.  
  863.              NEW LINE:  PgDn  key.  Moves the cursor to the beginning  of 
  864.                        the  first data field on the next line down  which 
  865.                        contains  a data field.  If the cursor line is the 
  866.                        last  such  line on the screen  the  cursor  wraps 
  867.                        around  to the first line containing a data field. 
  868.                        The choice of PgDn is arbitrary, and can easily be 
  869.                        changed to Down Arrow or some other key.  Unfortu-
  870.                        nately, on most 3270 keyboards the New Line key is 
  871.                        in  about  the same position as  the  PC's  Return 
  872.                        (Enter) key,  and moreover is marked the same (ar-
  873.                        row  down and left).  If the Return key were  used 
  874.                        for New Line, there would be no appropriate key to 
  875.                        use  for  Enter.  (The 3270's Enter key  is  about 
  876.                        where  the  PC's Caps Lock key is,  except on  the 
  877.                        3270 "data entry" keyboards,  where it is  located 
  878.                        roughly  where the PC's left bracket key  is.  IBM 
  879.                        was never much good at ergonomics or consistency.) 
  880.                        Also,  you'd  think  that logically the  PgUp  key 
  881.                        would  jump  the cursor UP one line;  there is  no 
  882.                        such key on the 3270.
  883.  
  884.              HOME:      The Home key returns the cursor to the first data 
  885.                        field on the screen.
  886.  
  887.           B. Editing_Keys
  888.              ____________
  889.  
  890.              INSERT MODE:  Ins key.  In insert mode,  characters typed by 
  891.                        the  user  are inserted at  the  cursor  position, 
  892.                        pushing characters right until a non-blank charac-
  893.                        ter  is the last in the field.  This is a  toggle. 
  894.                        Pressing it again turns off insert mode. (The 3270 
  895.                        keyboard  has  a RESET key which turns off  insert 
  896.                        mode.)
  897.  
  898.              DELETE:   Del  key.  The character at the cursor is  deleted 
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.         Pascal Library Member EM3270.INC                 Page 14
  908.  
  909.  
  910.                        and  all characters in the field to the right  are 
  911.                        shifted left one position. A space is shifted into 
  912.                        the rightmost position of the field.
  913.  
  914.              ERASE EOF: End  key.  All characters in the data field  from 
  915.                        the  cursor position to the end of the  field  are 
  916.                        set to spaces (erased).  This is another arbitrary 
  917.                        key choice, since there is no analogous key on the 
  918.                        PC.
  919.  
  920.           C. Data_Entry
  921.              __________
  922.  
  923.              Any printable ASCII character entered ($20..$7E or ' '..'~') 
  924.              will  replace the character in the cursor position and  turn 
  925.              on the modified data tag of the field.
  926.  
  927.           D. Data_Transmission
  928.              _________________
  929.  
  930.              When all data entry has been completed,  control is returned 
  931.              to the application program by pressing any of the AID keys.
  932.  
  933.         V. PROBLEMS
  934.  
  935.           A. One of the most common problems in using EM3270 is FORGET-
  936.              TING TO CALL INITSCREEN before the first call to one of  the 
  937.              other  procedures.  The symptoms of this are almost always a 
  938.              totally "locked up" system.
  939.  
  940.           B. CALLING  WRITEFIELD  MORE THAN MAXFIELDS TIMES  will  almost 
  941.              always send your program into never never land.
  942.  
  943.           C. FORGETTING  TO CALL NEWSCREEN before writing prompts or cal-
  944.              ling WriteField will not lock up the system, but will result 
  945.              in "garbage" screens and unpredictable cursor positioning.
  946.  
  947.           D. OVERLAPPING  FIELDS  AND/OR  PROMPTS are  simply  errors  in 
  948.              specifying correct X/Y values in WritePrompt and WriteField.
  949.  
  950.           E. SPECIFYING  A FIELD NUMBER HIGHER THAN THE HIGHEST  ONE  DE-
  951.              FINED in arguments to ReadScreen,  RewriteField and GetField 
  952.              causes  unpredictable  results - frequently a  total  system 
  953.              lockup.
  954.  
  955.           F. THE  RETURN KEY can cause problems to people who are used to 
  956.              the  Teletype  (and PC) standard of hitting  it  after  each 
  957.              field.  It  can also cause problems for some 3270  operators 
  958.              since  on the PC keyboard it is in the sames position as the 
  959.              NEW LINE key on most 3270 keyboards.  One way to get  around 
  960.              this is to modify the EM3270 procedures so that the RETURN 
  961.              key is not one of the AID keys,  but performs the same func-
  962.              tion  as TAB or PgDn.  Another way is to eliminate the ENTER 
  963.              function  through programming:  every time you  return  from 
  964.              ReadScreen  with  an AID value of ENTER,  simply go back  to 
  965.              ReadScreen  again with the cursor placed in the  next  field 
  966.              (determined  by  adding 1 to Cursor.Field and  allowing  for 
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.         Pascal Library Member EM3270.INC                 Page 15
  976.  
  977.  
  978.              falling  out of the last screen field).  In either of  these 
  979.              solutions, you sacrifice the ENTER AID function and must use 
  980.              only the function keys or ESCAPE to get your data.
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.