home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / tt2man.zip / tthllapi.doc < prev    next >
Text File  |  1993-12-10  |  34KB  |  964 lines
  1.  
  2.                              TABLE OF CONTENTS                              
  3.  
  4.  
  5.           8. EHLLAPI Support
  6.             8.1 Standard EHLLAPI Support
  7.               8.1.1 Overview
  8.               8.1.2 Activating EHLLAPI For A Session
  9.             8.2 Guidelines For Usage
  10.               8.2.1 Overview
  11.               8.2.2 EHLLAPI Functions
  12.               8.2.3 TalkThru EHLLAPI Extensions
  13.                 8.2.3.1 Connect and Disconnect Enhancements
  14.                 8.2.3.2 Dialing and Hanging Up The Phone
  15.                 8.2.3.3 Data Capture
  16.                 8.2.3.4 Sending Control Sequences
  17.                 8.2.3.5 Clearing The Local Screen
  18.                 8.2.3.6 Sending TalkThru Assigned Keys
  19.                 8.2.3.7 File Transfer Requests
  20.  
  21.  
  22.  
  23.                              8. EHLLAPI Support                             
  24.  
  25.  
  26.                         8.1 Standard EHLLAPI Support                        
  27.  
  28.  
  29.  
  30. ┌────────────────┐
  31. │ 8.1.1 Overview │
  32. └────────────────┘
  33.  
  34.   The TalkThru  EHLLAPI Interface is designed to provide compatibility  with
  35.   the EHLLAPI  calls supported by the Communications Manager.  This  feature
  36.   allows:
  37.  
  38.    - any Proprietary Product which uses EHLLAPI for their communications
  39.  
  40.    - any  development language which supports calls to EHLLAPI (i.e.  EASEL,
  41.      The Applications Manager)
  42.  
  43.    - any compiled language (i.e. 'C', 'COBOL', 'PASCAL', etc.)
  44.  
  45.   to access and control any host environment available through TalkThru.
  46.  
  47.   For the  TalkThru EHLLAPI calls supported, they are written exactly as  if
  48.   you were  communicating directly to the Communications Manager.  The  fact
  49.   that  TalkThru  is  intercepting  and processing  these  calls  should  be
  50.   transparent  to  your application.  For more information  on  how  EHLLAPI
  51.   support has been implemented and the limitations related to the  different
  52.   protocols  (i.e.  TTY, VT100), refer to the section Guidelines  For  Usage
  53.   later in this chapter.
  54.  
  55.   NOTE:
  56.      TalkThru  determines the EHLLAPI calls directed to him by  SESSION  ID.
  57.      For more  information  on the Communications Manager  Interface,  refer
  58.      that Appendix.
  59.  
  60.   TalkThru  is not distributed with a reference document for EHLLAPI  calls.
  61.   To use  TalkThru EHLLAPI, merely refer to any document describing the  IBM
  62.   Communications Manager EHLLAPI call structure.
  63.  
  64. ┌────────────────────────────────────────┐
  65. │ 8.1.2 Activating EHLLAPI For A Session │
  66. └────────────────────────────────────────┘
  67.  
  68.   In order for any EHLLAPI calls to work with a TalkThru session  (including
  69.   the Communications  Manager  through  TalkThru),   a   session  with  that
  70.   EHLLAPI  Session  Id  must  be  started.   This  is  true,  not  only  for
  71.   applications you write in languages like EASEL, REXX, "C", etc., but  also
  72.   for applications developed in AUTOPILOT.
  73.  
  74.   In the  case  of  the   Communications    Manager,  this  means  that  the
  75.   Communications  Manager  must have been loaded and  the  sessions  started
  76.   prior to TalkThru initialization.
  77.  
  78.   In the  case of TalkThru, the Phone Book entries you wish to control  must
  79.   be loaded  from  the Phone Book for EHLLAPI support.   This  requires  two
  80.   things:
  81.  
  82.   1. That  you provided an EHLLAPI Session Id for the Phone Book  Entry  you
  83.      wish to control.  If you did not assign an EHLLAPI Session Id when  you
  84.      created the Phone Book Entry, you can do so by:
  85.  
  86.         o invoking the Phone Book
  87.         o positioning the Selector Bar over the Phone Book Entry you wish to
  88.           control
  89.         o selecting Change from the Phone Book pull down menu
  90.         o specifying a Session Id in the dialog EHLLAPI Session Id
  91.  
  92.      The EHLLAPI Session Id you specify must be a letter from "A" to "Z" and
  93.      must be  unique to  ALL other  sessions  (including  3270 session) that  
  94.      might be active concurrently.
  95.  
  96.   2. That  the session is loaded for EHLLAPI Support.  This could also  have
  97.      been  done when the Phone Book was created.  If this was not,  you  may
  98.      accomplish this in one of two ways:
  99.  
  100.     o When  you  select  Add or Change from the Phone Book  pull  down  menu
  101.       (available  on  any  Phone  Book window), you will  see  a  Check  Box
  102.       beginning Make session available for EHLLAPI ... .  If you check  this
  103.       box,  EHLLAPI  support for that Phone Book Entry will be  loaded  each
  104.       time the Phone Book is loaded.
  105.  
  106.     o From  any Phone Book Window, you can position the Selector Bar over  a
  107.       Phone  Book  entry and select Setup for EHLLAPI from  the  Phone  Book
  108.       pull  down  window.  This will dynamically load  EHLLAPI  support  for
  109.       this entry.
  110.  
  111.   Notice  that, in neither of these cases, does this mean that the  Terminal
  112.   Emulator  will  be started, only that EHLLAPI support will  be  available.
  113.   The reverse,  though,  is  not  true.  If you  have  loaded  the  Terminal
  114.   Emulator  representing  a  Phone Book Entry and it has  been  assigned  an
  115.   EHLLAPI Session Id, EHLLAPI support IS IMMEDIATELY available.
  116.  
  117.   Once you feel you have loaded EHLLAPI support for the session you wish  to
  118.   control,  you may check this by requesting the Controller Panel  from  the
  119.   Utilities  pull down menu on any Phone Book window. For  more  information
  120.   on the  Controller  Window, see The Controller Panel in the  Chapter,  The
  121.   Phone Book.
  122.  
  123.   WARNING:
  124.        Once  you have Created EHLLAPI support for a session, it can only  be
  125.        stopped from the TalkThru Sessions Controller panel.
  126.  
  127.  
  128.  
  129.  
  130.                           8.2 Guidelines For Usage                          
  131.  
  132.  
  133.  
  134. ┌────────────────┐
  135. │ 8.2.1 Overview │
  136. └────────────────┘
  137.  
  138.   Before  identifying the differences between TalkThru EHLLAPI and  the  IBM
  139.   Standard,  let's  clarify some of the philosophy  regarding  the  TalkThru
  140.   implementation.
  141.  
  142.  
  143.   First:
  144.  
  145.    Regardless  of  protocol the terminal screen  represents  a  Presentation
  146.    Space.    For many emulation modes, this Presentation  Space  has  little
  147.    value  beyond  a 24 X 80 buffer which may be examined  for  text  content
  148.    only.    In  the  simpler protocol implementations  there  are  no  field
  149.    delineations  or attributes and therefore EHLLAPI functions  are  limited
  150.    due to lack of available information.
  151.  
  152.  
  153.   Second:
  154.  
  155.    The less  sophisticated protocols (i.e. TTY, VT100, etc.) do not  provide
  156.    any mechanism  by which a keyboard lock or input inhibited state  may  be
  157.    determined.  The most viable implementation of an EHLLAPI application  in
  158.    these  situations is one that has been created by someone  familiar  with
  159.    the host  systems who can textually identify when the  full  presentation
  160.    space  is  available  and  input  may  commence.   This  may  sound  very
  161.    restrictive  but  in fact very complex EHLLAPI front ends  may  be  built
  162.    even  for  systems  as  straight forward  as  TTY  Information  Retrieval
  163.    Services or Bulletin Boards.
  164.  
  165.   Having  started  with  some  of    the  shortcomings  of  EHLLAPI  in  the
  166.   asynchronous  environment,  let  us  now  examine  the  various  protocols
  167.   available  in  TalkThru  and where some of those provide  a  feature  rich
  168.   environment  for the EHLLAPI programmer.  Before proceeding,  however,  we
  169.   need  to  categorize  the protocols into two types -  Character  Mode  and
  170.   Block Mode.
  171.  
  172.  
  173.   Character Mode
  174.  
  175.    Character  Mode  protocols  are those where the host  only  sends  enough
  176.    information  to  paint  the screen,  generally  echoes  every  keystroke,
  177.    totally  controls cursor positioning and in no way indicates where  input
  178.    areas  are  until necessary. Examples of these protocols are  TTY,  VT52,
  179.    VT100, VT220, HP23xx in character mode, ANSI etc..  Another good  example
  180.    of this  category is the variety of protocol converters available to  IBM
  181.    hosts, e.g. 3710, 7171, and various other vendor products.
  182.  
  183.  
  184.   Block Mode
  185.  
  186.    Block  Mode  protocols are those which operate in a manner not  unlike  a
  187.    3270  terminal.   The host in essence transmits a data  stream  that  not
  188.    only  contains the text to be displayed but also input field  definitions
  189.    that  include attribute, length and size.  These protocols  also  perform
  190.    keyboard  locking and unlocking as well as local cursor control.   HP23xx
  191.    and TYMNETxx  are  examples of block emulation modes which  are  superbly
  192.    suited  to  the  EHLLAPI environment.  There is  however  the  occasional
  193.    difference  from a 3270 that can cause the EHLLAPI programmer to be  more
  194.    alert  in  handling  some  situations.   For  example,  the  syndrome  of
  195.    Keyboard  Lock  Flickering,  where  the input  inhibited  status  in  the
  196.    Operator Information Area of a 3270 turns on and off between screens,  is
  197.    accentuated in the asynchronous environment especially at slower speeds.
  198.  
  199.   Basically,  any host application may be front-ended by an EHLLAPI  program
  200.   with  very  little  difficulty regardless of  environment.   An  IBM  host
  201.   system administrator may easily port a 3270 home office application to  an
  202.   asynchronous protocol converter implementation to support the remotest  of
  203.   the company's  user  community.   TalkThru provides  some  facilities  for
  204.   handling  the  asynchronous  only functions such  as  dialing  the  phone,
  205.   sending  control  keystrokes,   unloading    the  application  etc..   The
  206.   following pages examine each call and indicate how it is supported.
  207.  
  208. ┌─────────────────────────┐
  209. │ 8.2.2 EHLLAPI Functions │
  210. └─────────────────────────┘
  211.  
  212.  
  213.  
  214.   CONNECT
  215.      Restrictions:
  216.          None
  217.      Enhancements:
  218.          Upon  a  Connect  request, TalkThru will load  and  initialize  the
  219.          terminal  emulation  session.  The desired session must  have  been
  220.          selected  to  "Autoload On Startup" or have  been  manually  loaded
  221.          using  the  "Setup For EHLLAPI" pulldown menu  selection  from  the
  222.          phone book.  TalkThru permits session letters A through Z.
  223.  
  224.  
  225.   DISCONNECT
  226.      Restrictions:
  227.          None
  228.      Enhancements:
  229.          So that  a  user's  desktop  and memory  usage  may  be  optimized,
  230.          TalkThru  provides an extension that will remove the emulator  when
  231.          no longer required. See TalkThru Extensions later in this document.
  232.  
  233.  
  234.   SEND KEY
  235.      Restrictions:
  236.          None
  237.      Enhancements:
  238.          The Send  Key facility has been extended to permit EHLLAPI to  pass
  239.          commands  to  TalkThru.    These commands  are  documented  in  the
  240.          TalkThru Extensions later in this document.
  241.  
  242.  
  243.   WAIT:
  244.      Restrictions:
  245.          XCLOCK  and XSYSTEM states are not supported in the character  mode
  246.          protocols.
  247.      Enhancements:
  248.          None
  249.  
  250.  
  251.   COPY PRESENTATION SPACE:
  252.      Restrictions:
  253.          For character mode protocols very limited attribute information  is
  254.          available and no "input field" data may be present. The block  mode
  255.          protocols  generally  return  full information  but  HP23xx  has  a
  256.          difference from the 3270 implementation.
  257.          
  258.          HP23xx  does  not use a screen position for  each  field  attribute
  259.          therefore  TalkThru has to place attributes in actual  screen  text
  260.          positions according to the following algorithm:
  261.          
  262.          If a  protected field follows an unprotected field then  the  first
  263.          position  of the protected field will be set as the attribute.   If
  264.          an unprotected  field  follows  a protected  field  then  the  last
  265.          position  of  the protected field will be set as the  attribute  of
  266.          the unprotected  field.  If two protected fields adjoin each  other
  267.          the last  byte of the first field will be used as the attribute  of
  268.          the second.  The  only caveat occurs when  two  unprotected  fields
  269.          abut  in  which case loss of an input position may be  apparent  in
  270.          this call, but will be correct in the individual field calls.
  271.      Enhancements:
  272.          None
  273.  
  274.  
  275.   QUERY CURSOR LOCATION
  276.      Restrictions:
  277.          None
  278.      Enhancements:
  279.          None
  280.  
  281.  
  282.   COPY PRESENTATION SPACE TO STRING
  283.      Restrictions:
  284.          See COPY PRESENTATION SPACE above.
  285.      Enhancements:
  286.          None
  287.  
  288.  
  289.   SET SESSION PARAMETERS
  290.      Restrictions:
  291.          Though  all parameters are accepted as defined in the OS/2  EHLLAPI
  292.          manual,  some  have  limited meaning  depending  on  the  emulation
  293.          protocol  being  used.    Refer to  individual  EHLLAPI  calls  for
  294.          restrictions.
  295.      Enhancements:
  296.          None
  297.  
  298.  
  299.   QUERY SESSIONS
  300.      Restrictions:
  301.          None
  302.      Enhancements:
  303.          As TalkThru  now permits session letters A through Z the number  of
  304.          sessions  returned  may be greater than the  maximum  permitted  by
  305.          OS/2  EHLLAPI.   Therefore, the application may  have  to  allocate
  306.          more memory to get an accurate response to this call.
  307.  
  308.  
  309.   RESERVE
  310.      Restrictions:
  311.          None
  312.      Enhancements:
  313.          None
  314.  
  315.  
  316.   RELEASE
  317.      Restrictions:
  318.          None
  319.      Enhancements:
  320.          None
  321.  
  322.  
  323.   COPY OIA
  324.      Restrictions:
  325.          The data  contents  of the OIA string will  reflect  the  emulation
  326.          name.    The  only  bit  combinations  supported  are  those  which
  327.          indicate  connect and keyboard lock states.  All other  3270  style
  328.          bits are off.
  329.      Enhancements:
  330.          None
  331.  
  332.  
  333.   QUERY FIELD ATTRIBUTE
  334.      Restrictions:
  335.          The attribute  data  returned  will depend on  the  protocol  being
  336.          used.    In most character mode situations limited  information  is
  337.          available.   In block mode emulation, more accurate information  is
  338.          returned as close as possible to the 3270 values.
  339.      Enhancements:
  340.          None
  341.  
  342.  
  343.   COPY STRING TO PRESENTATION SPACE
  344.      Restrictions:
  345.          This  call  acts  like an equivalent SEND KEY call  and  should  be
  346.          viewed accordingly. In most cases the results are identical  except
  347.          where  an  attempt  is made to modify a protected  portion  of  the
  348.          screen.  In this case, results are unpredictable.
  349.      Enhancements:
  350.          None
  351.  
  352.  
  353.   STORAGE MANAGER
  354.      Restrictions:
  355.          All calls  to  this  function  are passed on  to  the  IBM  EHLLAPI
  356.          facility  and  handled  by  it according  to  its  own  rules.   If
  357.          Communications  Manager  is not available, calls to  this  function
  358.          will return a System Error code.
  359.      Enhancements:
  360.          None
  361.  
  362.  
  363.   PAUSE
  364.      Restrictions:
  365.          None
  366.      Enhancements:
  367.          None
  368.  
  369.  
  370.   QUERY SYSTEM
  371.      Restrictions:
  372.          All calls  to  this  function  are passed on  to  the  IBM  EHLLAPI
  373.          facility  and  handled  by  it according  to  its  own  rules.   If
  374.          Communications  Manager  is not available, calls to  this  function
  375.          will return a System Error code.
  376.      Enhancements:
  377.          None
  378.  
  379.  
  380.   RESET SYSTEM
  381.      Restrictions:
  382.          This  call  is  processed    by     TalkThru  and  then  passed  to
  383.          Communications Manager, if available.
  384.      Enhancements:
  385.          None
  386.  
  387.  
  388.   START HOST NOTIFICATION
  389.      Restrictions:
  390.          None
  391.      Enhancements:
  392.          None
  393.  
  394.  
  395.   QUERY HOST UPDATE
  396.      Restrictions:
  397.          None
  398.      Enhancements:
  399.          None
  400.  
  401.  
  402.   STOP HOST NOTIFICATION
  403.      Restrictions:
  404.          None
  405.      Enhancements:
  406.          None
  407.  
  408.  
  409.   SEARCH FIELD
  410.      Restrictions:
  411.          The field  functions will be of most value, and  fully  functional,
  412.          when block mode emulation is active.  In character mode the  amount
  413.          of information  available is generally limited and only relates  to
  414.          the text currently displayed.
  415.      Enhancements:
  416.          None
  417.  
  418.  
  419.   FIND FIELD POSITION
  420.      Restrictions:
  421.          See SEARCH FIELD.
  422.      Enhancements:
  423.          None
  424.  
  425.  
  426.   FIND FIELD LENGTH
  427.      Restrictions:
  428.          See SEARCH FIELD.
  429.      Enhancements:
  430.          None
  431.  
  432.  
  433.   COPY FIELD TO STRING
  434.      Restrictions:
  435.          See SEARCH FIELD.
  436.      Enhancements:
  437.          None
  438.  
  439.  
  440.   COPY STRING TO FIELD
  441.      Restrictions:
  442.          See SEARCH FIELD.
  443.      Enhancements:
  444.          None
  445.  
  446.  
  447.   SET CURSOR
  448.      Restrictions:
  449.          None
  450.      Enhancements:
  451.          None
  452.  
  453.   START CLOSE INTERCEPT
  454.   QUERY CLOSE INTERCEPT
  455.   STOP CLOSE INTERCEPT
  456.   START KEYSTROKE INTERCEPT
  457.   GET KEY
  458.   POST INTERCEPT STATUS
  459.   STOP KEYSTROKE INTERCEPT
  460.      Restrictions:
  461.          To be supported in a future release.
  462.  
  463.  
  464.   SEND FILE:
  465.      Restrictions:
  466.          Supported as of release 1.01 only.
  467.      Enhancements:
  468.          Access  is  provided  to other transfer methods  by  modifying  the
  469.          command text.
  470.  
  471.  
  472.   RECEIVE FILE:
  473.      Restrictions:
  474.          Supported as of release 1.01 only.
  475.      Enhancements:
  476.          Access  is  provided  to other transfer methods  by  modifying  the
  477.          command text.
  478.  
  479.  
  480.   CONVERT POSITION/CONVERT ROWCOL
  481.      Restrictions:
  482.          None
  483.      Enhancements:
  484.          None
  485.  
  486.  
  487.   CONNECT PM WINDOW SERVICES
  488.      Restrictions:
  489.          None
  490.      Enhancements:
  491.          None
  492.  
  493.  
  494.   DISCONNECT PM WINDOW SERVICES
  495.      Restrictions:
  496.          None
  497.      Enhancements:
  498.          None
  499.  
  500.  
  501.   QUERY PM WINDOW COORDINATES
  502.      Restrictions:
  503.          None
  504.      Enhancements:
  505.          None
  506.  
  507.  
  508.   PM WINDOW STATUS
  509.      Restrictions:
  510.          None
  511.      Enhancements:
  512.          None
  513.  
  514.  
  515.   CHANGE SWITCH LIST LT NAME
  516.      Restrictions:
  517.          None
  518.      Enhancements:
  519.          None
  520.  
  521.  
  522.   CHANGE PS WINDOW NAME
  523.      Restrictions:
  524.          None
  525.      Enhancements:
  526.          None
  527.  
  528. ┌───────────────────────────────────┐
  529. │ 8.2.3 TalkThru EHLLAPI Extensions │
  530. └───────────────────────────────────┘
  531.  
  532.   As IBM  designed  the  EHLLAPI interface to  suit  synchronous  block-mode
  533.   terminal  devices,  some  features  required,  or  at  least  useful,  for
  534.   asynchronous  terminals  were   not    considered.  TalkThru  provides  an
  535.   extension  to the EHLLAPI interface to achieve greater  functionality  for
  536.   communications application programmers.
  537.  
  538.   The extended functions are:
  539.  
  540.       - Enhanced Connect/Disconnect capability
  541.       - Telephone dialing
  542.       - Data capture
  543.       - Sending control sequences
  544.       - Local screen clearing
  545.       - Sending TalkThru Assigned Keys
  546.       - File Transfer Request
  547.  
  548.   Before  examining each feature we must review the general principle  under
  549.   which  this  facility  has  been implemented.  So  that  EHLLAPI  specific
  550.   products  such as EASEL from EASEL Corp. may take advantage of  the  added
  551.   capability, TalkThru could not actually add new EHLLAPI commands but  must
  552.   use the  existing  constructs.    Therefore    these  features  have  been
  553.   implemented  as  commands,  communicated to  the  controlling  application
  554.   using  the EHLLAPI SEND KEY (3) facility. If a series of  keystrokes  sent
  555.   to the  session begin with "@@TALKTHRU" then the remaining characters  are
  556.   interpreted  as  a TalkThru command. The @@ pair of  characters  represent
  557.   the standard  EHLLAPI escape characters, certain special applications  may
  558.   change  the  escape character to a different value, such as  *,  in  which
  559.   case  those  applications should substitute ** for each @@  pair  in  this
  560.   document.
  561.  
  562.   A sample C program code fragment to execute a TalkThru command would be:
  563.  
  564.     USHORT ClimFunction = PCB_SEND_KEY;
  565.     USHORT Size = 15;
  566.     USHORT ReturnCode = 0;
  567.  
  568.     hllapi(&ClimFunction, "@@TALKTHRU DIAL", &Size, &ReturnCode);
  569.  
  570.  
  571.   Program  products such as EASEL detect whenever an application is  sending
  572.   the EHLLAPI Escape Character (@) and double it automatically. As a  result
  573.   the EASEL programmer must code in the following fashion:
  574.  
  575.     copy "@TALKTHRU DIAL" to Keystrokes
  576.     action TypeString
  577.  
  578.   In this  scenario,  TalkThru will actually receive  "@@TALKTHRU  DIAL"  as
  579.   EASEL will automatically double the escape character.
  580.  
  581.  
  582.   All following  examples  will show both a C implementation  and  an  EASEL
  583.   Action implementation.
  584.  
  585.   ┌─────────────────────────────────────────────┐
  586.   │ 8.2.3.1 Connect and Disconnect Enhancements │
  587.   └─────────────────────────────────────────────┘
  588.  
  589.  
  590.     ┌────────────┐
  591.     │ Connecting │
  592.     └────────────┘
  593.  
  594.       Under TalkThru's implementation of EHLLAPI, a session to be used  need
  595.       not be  already  started  so long as it has been  loaded  for  use  by
  596.       EHLLAPI  at some prior time. There are two ways that this can  happen.
  597.       Each  Phone  Book item may be marked for "Autoload at  Startup"  which
  598.       will place the potential communications session in the Query  Sessions
  599.       list.  This enables EHLLAPI applications to know that such  a  session
  600.       exists  but  conserves  system resources by not  actually  having  the
  601.       terminal emulator active.
  602.  
  603.       When  such  sessions  have been defined  and  an  EHLLAPI  application
  604.       attempts  to  connect to one, TalkThru will then  automatically  start
  605.       the terminal  emulator  for that connection.  This  emulation  session
  606.       will  then  remain  in  the system until the user  closes  it  or  the
  607.       EHLLAPI application uses the disconnect extension described below.
  608.  
  609.       The method  is  useful  for casual applications such  as  accessing  a
  610.       stock  market,  news  or other outside data service.  Having  to  load
  611.       emulation  sessions  for  less   frequently  accessed  services  might
  612.       severely constrain the OS/2 environment.
  613.       TalkThru's  EHLLAPI extension provides for up to 26  loaded  sessions,
  614.       3270  and  5250  sessions inclusive. Programmers must  be  aware  that
  615.       loading  many sessions will increase the memory required to receive  a
  616.       full reply from the Query Sessions EHLLAPI command.
  617.  
  618.     ┌───────────────┐
  619.     │ Disconnecting │
  620.     └───────────────┘
  621.  
  622.       EHLLAPI  applications  may disconnect from any  connected  session  as
  623.       desired,  but  in  order      to  conserve  system  resources,  casual
  624.       applications  may wish to unload the terminal emulation sessions  when
  625.       the job has been completed.
  626.  
  627.       To facilitate  this  requirement, the SET_UNLOAD_ON_DISC  command  has
  628.       been implemented. This command has no parameters.
  629.  
  630.  
  631.       A C example of this would be:
  632.  
  633.         USHORT ClimFunction = PCB_SEND_KEY;
  634.         USHORT Size = 29;
  635.         USHORT ReturnCode = 0;
  636.  
  637.  
  638.         hllapi(&ClimFunction, "@@TALKTHRU SET_UNLOAD_ON_DISC",
  639.         &Size, &ReturnCode);
  640.         ClimFunction = PCB_DISCONNECT;
  641.         hllapi(&ClimFunction, NULL, NULL, &ReturnCode);
  642.  
  643.  
  644.       An EASEL Action sample would be:
  645.  
  646.         copy "@TALKTHRU DIAL" to Keystrokes
  647.         action TypeString
  648.         action Disconnect
  649.  
  650.  
  651.   ┌──────────────────────────────────────────┐
  652.   │ 8.2.3.2 Dialing and Hanging Up The Phone │
  653.   └──────────────────────────────────────────┘
  654.  
  655.  
  656.     ┌─────────┐
  657.     │ Dialing │
  658.     └─────────┘
  659.  
  660.       As EHLLAPI  has  no knowledge of telephones, TalkThru had  to  add  an
  661.       extension  to  permit    applications    to  dynamically  connect  the
  662.       asynchronous  session's telephone call. This has been  implemented  as
  663.       the DIAL command.
  664.  
  665.       The DIAL command has the following format:
  666.  
  667.   ┌──────────────────────────────────────────────────────────────────────┐
  668.   │ DIAL [phone number];                                                 │
  669.   └──────────────────────────────────────────────────────────────────────┘
  670.  
  671.       The optional  phone  number parameter overrides the number  stored  in
  672.       the session  definition under the Connections Setting. This is  useful
  673.       for sessions  that  have alternative numbers in case the  original  is
  674.       busy.  An  EHLLAPI  application can detect  one  busy  or  unanswering
  675.       number and then attempt to connect to another.
  676.  
  677.  
  678.       A C example of this would be:
  679.  
  680.         USHORT ClimFunction = PCB_SEND_KEY;
  681.         USHORT Size = 11;
  682.         USHORT ReturnCode = 0;
  683.  
  684.         hllapi(&ClimFunction, "@@TALKTHRU DIAL",
  685.         &Size, &ReturnCode);
  686.  
  687.  
  688.       An EASEL Action sample would be:
  689.  
  690.         copy "@TALKTHRU DIAL 555 1211" to Keystrokes
  691.         action TypeString
  692.  
  693.     ┌────────────┐
  694.     │ Hanging Up │
  695.     └────────────┘
  696.  
  697.       When  an application has completed on a connection but wants  to  keep
  698.       the terminal emulator available though not keep the phone  connection,
  699.       the TalkThru  HANGUP  extension command will  perform  the  operation.
  700.       This command has no parameters.
  701.  
  702.  
  703.       A C example of this would be:
  704.  
  705.         USHORT ClimFunction = PCB_SEND_KEY;
  706.         USHORT Size = 13;
  707.         USHORT ReturnCode = 0;
  708.  
  709.         hllapi(&ClimFunction, "@@TALKTHRU HANGUP",
  710.         &Size, &ReturnCode);
  711.  
  712.  
  713.       An EASEL Action sample would be:
  714.  
  715.         copy "@TALKTHRU HANGUP" to Keystrokes
  716.         action TypeString
  717.  
  718.   ┌──────────────────────┐
  719.   │ 8.2.3.3 Data Capture │
  720.   └──────────────────────┘
  721.  
  722.  
  723.     ┌───────────────────────┐
  724.     │ Starting Data Capture │
  725.     └───────────────────────┘
  726.  
  727.       Data capture is often the only programmatic method to record all  data
  728.       on a  stream  oriented  device   such  as  an  asynchronous  terminal,
  729.       particularly  using  a  block   oriented  facility  such  as  EHLLAPI.
  730.       TalkThru  provides a START_CAPTURE command to permit  applications  to
  731.       record streamlike data.
  732.  
  733.       The format of this command is:
  734.  
  735.   ┌──────────────────────────────────────────────────────────────────────┐
  736.   │ START_CAPTURE filespec [ {APPEND  }    ] [ {ALL   } ]                │
  737.   │                        [ {OVERWRITE )  ] [ {TEXT  } ]                │
  738.   │                                          [ {SCREEN} ]                │
  739.   └──────────────────────────────────────────────────────────────────────┘
  740.  
  741.       The "filespec"  parameter  should contain a fully  qualified  filename
  742.       where the TalkThru capture facility should store the data.
  743.  
  744.       The mutually  exclusive  keywords APPEND and  OVERWRITE  indicate  the
  745.       disposition of a preexisting file as defined in "filespec".
  746.  
  747.       The mutually  exclusive  keywords ALL, TEXT and  SCREEN  indicate  the
  748.       type  of data to be captured. These types are defined in the  Terminal
  749.       Emulator reference material.
  750.  
  751.  
  752.       A C example of this would be:
  753.  
  754.         USHORT ClimFunction = PCB_SEND_KEY;
  755.         USHORT Size = 39;
  756.         USHORT ReturnCode = 0;
  757.  
  758.         hllapi(&ClimFunction, "@@TALKTHRU START_CAPTURE C:\\CAPTURE.DAT"
  759.         &Size, &ReturnCode);
  760.  
  761.  
  762.       An EASEL Action sample would be:
  763.  
  764.         copy "@TALKTHRU START_CAPTURE C:\CAPTURE.DAT 
  765.         OVERWRITE TEXT" to Keystrokes
  766.         action TypeString
  767.  
  768.     ┌──────────────────┐
  769.     │ Stopping Capture │
  770.     └──────────────────┘
  771.  
  772.       To turn  off a previously started capture session,  TalkThru  provides
  773.       the STOP_CAPTURE command. This command has no parameters
  774.  
  775.  
  776.       A C example of this would be:
  777.  
  778.         USHORT ClimFunction = PCB_SEND_KEY;
  779.         USHORT Size = 23;
  780.         USHORT ReturnCode = 0;
  781.  
  782.         hllapi(&ClimFunction, "@@TALKTHRU STOP_CAPTURE",
  783.         &Size, &ReturnCode);
  784.  
  785.  
  786.       An EASEL Action sample would be:
  787.  
  788.         copy "@TALKTHRU STOP_CAPTURE" to Keystrokes
  789.         action TypeString
  790.  
  791.   ┌───────────────────────────────────┐
  792.   │ 8.2.3.4 Sending Control Sequences │
  793.   └───────────────────────────────────┘
  794.  
  795.     Certain  data  services  such as CompuServ require at the  user  type  a
  796.     control  key  to initial a session, in this case a  Control  C.  EHLLAPI
  797.     regards such keystrokes as invalid and some applications, such as  EASEL
  798.     edit  out  such data. To circumvent such action, TalkThru  provides  the
  799.     SENDCTRL command.
  800.  
  801.     The format of this command is:
  802.  
  803.   ┌──────────────────────────────────────────────────────────────────────┐
  804.   │ SENDCTRL keyletter                                                   │
  805.   └──────────────────────────────────────────────────────────────────────┘
  806.  
  807.     The required  parameter "keyletters" represent the key code to be  sent,
  808.     A, B, C, etc. All 26 control keys are supported.
  809.  
  810.  
  811.     A C example of this would be:
  812.  
  813.       USHORT ClimFunction = PCB_END_KEY;
  814.       USHORT Size = 21;
  815.       USHORT ReturnCode = 0;
  816.  
  817.       hllapi(&ClimFunction, "@@TALKTHRU SENDCTRL C",
  818.       &Size, &ReturnCode);
  819.  
  820.  
  821.     An EASEL Action sample would be:
  822.  
  823.       copy "@TALKTHRU SENDCTRL C" to Keystrokes
  824.       action TypeString
  825.  
  826.   ┌───────────────────────────────────┐
  827.   │ 8.2.3.5 Clearing The Local Screen │
  828.   └───────────────────────────────────┘
  829.  
  830.     Certain  line mode services such as stock quotations return only 3 or  4
  831.     lines  of  data for each request. So that a programmed  application  may
  832.     more  easily  diagnose  the screen contents of  each  request,  TalkThru
  833.     provides  the  CLEAR_BUFFER  extension  command.  This  command  has  no
  834.     parameters.
  835.  
  836.     This  command wipes the local screen buffer clean and homes  the  cursor
  837.     to screen  position  1,1.  Now the presentation space  is  free  of  any
  838.     clutter that would otherwise remained from a prior request.
  839.  
  840.  
  841.     A C example of this would be:
  842.  
  843.       USHORT ClimFunction = PCB_SEND_KEY;
  844.       USHORT Size = 23;
  845.       USHORT ReturnCode = 0;
  846.  
  847.       hllapi(&ClimFunction, "@@TALKTHRU CLEAR_BUFFER",
  848.       &Size, &ReturnCode);
  849.  
  850.  
  851.     An EASEL Action sample would be:
  852.  
  853.       copy "@TALKTHRU CLEAR_BUFFER" to Keystrokes
  854.       action TypeString
  855.  
  856.   ┌────────────────────────────────────────┐
  857.   │ 8.2.3.6 Sending TalkThru Assigned Keys │
  858.   └────────────────────────────────────────┘
  859.  
  860.     If you  wish to send a key using the name assigned through the  TalkThru
  861.     Keyboard  Mapping,  you may do so with the TalkThru  SENDKEY  extension.
  862.     The only  parameter  passed  to  this command is the  name  of  the  key
  863.     assigned.  These key names are the same as you would use when  referring
  864.     to these keys in AUTOPILOT.
  865.  
  866.  
  867.     A C example of this would be:
  868.  
  869.       USHORT ClimFunction = PCB_SEND_KEY;
  870.       USHORT Size = 31;
  871.       USHORT ReturnCode = 0;
  872.  
  873.       hllapi(&ClimFunction, "@@TALKTHRU SENDKEY KEYPAD_ENTER",
  874.       &Size, &ReturnCode);
  875.  
  876.  
  877.     An EASEL Action sample would be:
  878.  
  879.       copy "@TALKTHRU SENDKEY KEYPAD_ENTER" to Keystrokes
  880.       action TypeString
  881.  
  882.  
  883.   ┌────────────────────────────────┐
  884.   │ 8.2.3.7 File Transfer Requests │
  885.   └────────────────────────────────┘
  886.  
  887.  
  888.     ┌────────────────────────┐
  889.     │ Invoking File Transfer │
  890.     └────────────────────────┘
  891.  
  892.       TalkThru  allows  you  to  invoke  any  of  the  File  Transfer  types
  893.       supported  by  it  through   the  FILE_TRANSFER  extension.  The  file
  894.       transfer  runs asynchronously to your processing (see  Obtaining  File
  895.       Transfer  Status next).  The following parameters are passed  to  this
  896.       request:
  897.  
  898.       <file-transfer-type>
  899.         this  is a keyword indicating the type of file transfer to  be  run.
  900.         This can be:
  901.  
  902.         XMODEM            = Use XMODEM CRC protocol
  903.         XMODEM_CRC        = Use XMODEM CRC protocol
  904.         XMODEM_CHECKSUM   = Use XMODEM CHECKSUM protocol
  905.         YMODEM            = Use YMODEM protocol (XMODEM 1K)
  906.         YMODEM_G          = Use YMODEM G protocol (XMODEM 1K G)
  907.         YMODEM_BATCH      = Use YMODEM BATCH protocol
  908.         YMODEM_BATCH_G    = Use YMODEM BATCH G protocol
  909.         KERMIT            = Use KERMIT SEND/RECEIVE protocol
  910.         IND$FILE          = Use IBM IND$FILE (SEND/RECEIVE) protocol
  911.  
  912.       <file-transfer-command>
  913.         indicates  which  file(s) are to be transferred. The format  is  the
  914.         same as would be provided for the specific file transfer.
  915.  
  916.       A C example of this would be:
  917.  
  918.         USHORT ClimFunction = PCB_SEND_KEY;
  919.         USHORT Size = 40;
  920.         USHORT ReturnCode = 0;
  921.  
  922.         hllapi(&ClimFunction, "@@TALKTHRU FILE_TRANSFER XMODEM test.dat" ,
  923.         &Size, &ReturnCode);
  924.  
  925.  
  926.       An EASEL Action sample would be:
  927.  
  928.         copy "@TALKTHRU FILE_TRANSFER XMODEM test.dat" to Keystrokes
  929.         action TypeString
  930.  
  931.     ┌────────────────────────────────┐
  932.     │ Obtaining File Transfer Status │
  933.     └────────────────────────────────┘
  934.  
  935.       TalkThru allows you to obtain the status of the File Transfer  invoked
  936.       through  the  FILE_TRANSFER extension  with  the  FILE_TRANSFER_STATUS
  937.       extension.  FILE_TRANSFER_STATUS returns one of the  following  return
  938.       codes:
  939.  
  940.         0  - Successful completion
  941.         1  - Not connected
  942.         2  - The file could not be opened.
  943.         3  - Syntax error within <file-transfer-command> or
  944.                                  <file-transfer-type>
  945.         4  - File transfer failed
  946.         5  - File transfer was canceled
  947.         10 - File transfer is running
  948.         11 - File transfer waiting to start
  949.  
  950.       A C example of this would be:
  951.  
  952.         USHORT ClimFunction = PCB_SEND_KEY;
  953.         USHORT Size = 31;
  954.         USHORT ReturnCode = 0;
  955.  
  956.         hllapi(&ClimFunction, "@@TALKTHRU FILE_TRANSFER_STATUS",
  957.         &Size, &ReturnCode);
  958.  
  959.  
  960.       An EASEL Action sample would be:
  961.  
  962.         copy "@TALKTHRU FILE_TRANSFER_STATUS" to Keystrokes
  963.         action TypeString
  964.