home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / business / hostkey1.zip / HOSTKEYS.DOC < prev    next >
Text File  |  1992-01-31  |  19KB  |  546 lines
  1.  
  2.  
  3.                    HOSTKEYS
  4.  
  5.                   VERSION 1.0
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                Logical Business Systems, Inc.
  19.  
  20.                    Copyright 1991, 1992
  21.                   15790 Dooley, Suite #105
  22.                    Dallas, Texas 75244
  23.  
  24.  
  25.                       NOTICE
  26.  
  27.       This software product is provided "as is" with no guarantees
  28.       or warranties express or implied. Logical Business Systems, Inc.
  29.       accepts no liability for the use of or inability to use this
  30.       product, or any damages attributable thereto.
  31.  
  32.       This software product is distributed as "shareware".  You may
  33.       evaluate the product at no charge for 30 days and distribute
  34.       complete and unaltered copies to others. If you find HOSTKEYS
  35.       useful and wish to continue using HOSTKEYS, please print the
  36.       file register.doc and send $49.95 to:
  37.  
  38.             Logical Business Systems, Inc.
  39.             15790 Dooley Suite #105
  40.             Dallas, Texas 75244
  41.  
  42.           Once registered, you will:
  43.  
  44.           Have access to free technical phone support.
  45.           Receive free product upgrades!
  46.           Be able to request enhancements and/or submit comments.
  47.  
  48.                 1-800-521-5904
  49.                 1-214-239-2146
  50.  
  51.  
  52.  
  53.  
  54.     INTRODUCTION:
  55.  
  56.  
  57.     Welcome to HOSTKEYS, the 3270 automation program.
  58.  
  59.     HOSTKEYS will save you time and effort controlling your 3270 terminal
  60.     sessions.  HOSTKEYS automates mainframe 3270 terminal sessions by
  61.     processing user defined script files.  HOSTKEYS works with all 3270
  62.     emulation products that support IBM compatible HLLAPI (High Level
  63.     Language Application Program Interface).
  64.  
  65.     HOSTKEYS is a communication option of AUTO-PC, another product from
  66.     Logical Business Systems, Inc.    AUTO-PC offers the most powerful
  67.     scheduling available for all your unattended PC processing needs.
  68.     AUTO-PC provides JOB scheduling for Batch Files, PC Programs, and
  69.     Keystroke Capture Sessions.  With AUTO-PC, calls to HOSTKEYS can
  70.     be scheduled for unattended processing.  See AUTO-PC.DOC.
  71.  
  72.     For more information about AUTO-PC, call or write Logical Business
  73.     Systems, Inc.  NOTE: AUTO-PC is not a shareware product.
  74.  
  75.     Before executing HOSTKEYS be sure the 3270 emulation software and
  76.     HLLAPI are loaded, and a 3270 session is active.
  77.  
  78.  
  79.     Starting HOSTKEYS processing.
  80.  
  81.        Format -> hostkeys parameter1 parameter2 (parameter3)
  82.              parameter1 = file name and extension of script file
  83.              parameter2 = required connection type ( P or L )
  84.              parameter3 = optional session id - default is the first
  85.                   valid session found (this may be blank)
  86.                          or
  87.         Format -> hostkeys /D
  88.               To Display System and Session(s) Status
  89.  
  90.     NOTE: When using HOSTKEYS with a 3270 emulation product for the
  91.           first time, you should display the System and Session status
  92.           to obtain the session id(s) (short names).
  93.  
  94.     NOTE: Use connection type "P" with 3270 emulation products that support
  95.           a concurrent DOS session.
  96.  
  97.           Use connection type "L" with 3270 emulation products that do not
  98.           support a concurrent DOS session.  Use the hotkey command "H:" to
  99.           get to the 3270 session if required.
  100.  
  101.           See Technical Notes for more on connection type.
  102.  
  103.  
  104.  
  105.      HOSTKEYS Script Commands:
  106.  
  107.      Introduction:    The following are the HOSTKEYS commands.  The command
  108.             can be either lower or upper case.  Following the
  109.             proper format is critical.  Use your favorite editor
  110.             to create your script files.
  111.  
  112.      --------------------------------------------------------------------
  113.      C: -> Check 3270 screen for a string.
  114.  
  115.      Format:   C:ROW,COLUMN,'STRING',TIMER,LABEL
  116.  
  117.        ROW        = The row on the screen.
  118.        COLUMN   = The column on the screen.
  119.        STRING   = The string to check for, must be in single quotes.
  120.        TIMER    = OPTIONAL: How long to continuously check for string.
  121.               Value is in 1/2 seconds.    If it is not supplied,
  122.               HOSTKEYS will check for the string indefinitly.  A
  123.               value of 0 will check only one time.
  124.        LABEL    = OPTIONAL: Where to branch to if the string is not found
  125.               and the timer expires.  If timer is supplied then this
  126.               parameter is required.
  127.  
  128.        NOTE: The first screen postion is Row 1, Column 1.
  129.        NOTE: The string is case sensitive, be sure to use the
  130.          appropriate case.
  131.  
  132.        EXAMPLE:  C:18,25,'OPTIONS',0,NOVTAM
  133.  
  134.              Check the 3270 screen for the uppercase string 'OPTIONS'
  135.              at Row 18, Column 25, if not immediately found, then
  136.              branch to the label NOVTAM.
  137.  
  138.      --------------------------------------------------------------------
  139.      G: -> GOTO LABEL
  140.  
  141.      Format:   G:LABEL
  142.  
  143.       NOTE: The label must be defined with a "L:" command.
  144.  
  145.      EXAMPLE: G:TRY_NEXT
  146.  
  147.      --------------------------------------------------------------------
  148.      H: -> HOTKEY (Toggle between PC session and Host session)
  149.  
  150.      Format:    H:
  151.  
  152.      NOTE:    This is provided for 3270 emulation products that do NOT
  153.         provide a concurrent DOS session.  Use this ONLY when
  154.         user interaction is required with the 3270 session.
  155.  
  156.      EXAMPLE: H:
  157.  
  158.           Hotkey between the HOST and PC sessions.
  159.  
  160.  
  161.  
  162.      HOSTKEYS Script Commands: (CON'T)
  163.  
  164.      --------------------------------------------------------------------
  165.      K: -> Send keystrokes to host.
  166.  
  167.      Format:   K:{ Keystrokes Go Here }
  168.  
  169.      The following represent all special keystrokes:
  170.  
  171.       $ALT_CUR =      "ALTERNATE CURSOR"
  172.       $AT =       "@"
  173.       $ATTN =      "ATTENTION"  ** an AID key mnemonic
  174.       $BACKSPACE =      "BACKSPACE"
  175.       $BACKTAB =      "BACKTAB"
  176.       $BLUE =      "BLUE"
  177.       $B_W_TAB =      "BACKWARD WORD TAB"
  178.       $CLEAR =      "CLEAR"
  179.       $CUR_DOWN =      "CURSOR DOWN"
  180.       $CUR_LEFT =      "CURSOR LEFT"
  181.       $CUR_L_FAST =   "CURSOR LEFT FAST"
  182.       $CUR_RIGHT =      "CURSOR RIGHT"
  183.       $CUR_R_FAST =   "CURSOR RIGHT FAST"
  184.       $CUR_SEL =      "CURSOR SELECT"  ** an AID key mnemonic
  185.       $CUR_UP =      "CURSOR UP"
  186.       $DELETE =      "DELETE"
  187.       $DUP =      "DUP"
  188.       $ENTER =      "ENTER"
  189.       $ERASE =      "ERASE EOF"
  190.       $ERASE_IN =      "ERASE INPUT"
  191.       $FLD_HIGH =      "FIELD HIGHLIGHT"
  192.       $FLD_MARK =      "FIELD MARK"
  193.       $F_W_TAB =      "FORWARD WORD TAB"
  194.       $GREEN =      "GREEN"
  195.       $HOME =      "HOME"
  196.       $INSERT =      "INSERT"
  197.       $JUMP =      "JUMP to destination LT"
  198.       $NEW_LINE =      "NEW LINE"
  199.       $PINK =      "PINK"
  200.       $PRINT_SCR =      "PRINT SCREEN"
  201.       $RED =      "RED"
  202.       $RESET =      "RESET"
  203.       $REV_VIDEO =      "REVERSE VIDEO"
  204.       $RE_COLORS =      "RESET COLORS"
  205.       $SYS_REQ =      "SYSTEM REQUEST"  ** an AID key mnemonic
  206.       $UNDER =      "UNDERSCORE"
  207.       $TAB =      "TAB"
  208.       $TURQ =      "TURQUOISE"
  209.       $WHITE =      "WHITE"
  210.       $YELLOW =      "YELLOW"
  211.       $PF1 =  "PF1"    $PF8 =  "PF8"    $PF15 = "PF15"   $PF22 = "PF22"
  212.       $PF2 =  "PF2"    $PF9 =  "PF9"    $PF16 = "PF16"   $PF23 = "PF23"
  213.       $PF3 =  "PF3"    $PF10 = "PF10"   $PF17 = "PF17"   $PF24 = "PF24"
  214.       $PF4 =  "PF4"    $PF11 = "PF11"   $PF18 = "PF18"   $PA1 =  "PA1"
  215.       $PF5 =  "PF5"    $PF12 = "PF12"   $PF19 = "PF19"   $PA2 =  "PA2"
  216.       $PF6 =  "PF6"    $PF13 = "PF13"   $PF20 = "PF20"   $PA3 =  "PA3"
  217.       $PF7 =  "PF7"    $PF14 = "PF14"   $PF21 = "PF21"
  218.  
  219.      EXAMPLE: K:GONEHOME$ENTER
  220.  
  221.           Send the keystrokes G-O-N-E-H-O-M-E followed by the ENTER key.
  222.  
  223.  
  224.      HOSTKEYS Script Commands: (CON'T)
  225.  
  226.      --------------------------------------------------------------------
  227.      L: -> LABEL
  228.  
  229.      Format:   L:LABEL NAME
  230.  
  231.      EXAMPLE: L:TRY_NEXT
  232.  
  233.      --------------------------------------------------------------------
  234.      P: -> PAUSE
  235.  
  236.      Format:   P:HALF SECONDS
  237.  
  238.            HALF SECONDS = The number of half seconds to pause.
  239.  
  240.      --------------------------------------------------------------------
  241.      S: -> Search 3270 screen for a string.
  242.  
  243.      Format:   S:ROW,COLUMN,'STRING',TIMER,LABEL
  244.  
  245.        ROW        = The row on the screen where to start search.
  246.        COLUMN   = The column on the screen where to start search.
  247.        STRING   = The string to search for, must be in single quotes.
  248.        TIMER    = OPTIONAL: How long to continuously search for string.
  249.               Value is in 1/2 seconds.    If not supplied will search
  250.               for string indefinitly.  A value of 0 will search only
  251.               one time.
  252.        LABEL    = OPTIONAL: Where to branch to if the string is not found
  253.               and the timer expires.  If timer is supplied then this
  254.               parameter is required.
  255.  
  256.        NOTE: The first screen postion is Row 1, Column 1
  257.        NOTE: The string is case sensitive (be sure to use the
  258.          appropriate case)
  259.  
  260.      EXAMPLE: S:1,1,'Electronic Funds Transfer',20,NOMONEY
  261.  
  262.           Search the 3270 screen for the string 'Electronic Funds
  263.           Transfer' starting at Row 1, Column 1 for a period of 10
  264.           seconds.  If not found within 10 seconds, branch to the
  265.           the label NOMONEY.
  266.  
  267.      --------------------------------------------------------------------
  268.      T: -> File Transfer
  269.  
  270.      Format:   T:TYPE,ACTUAL FILE TRANSFER COMMAND
  271.  
  272.            TYPE = S for a SEND to HOST
  273.               R for a RECEIVE from HOST
  274.  
  275.            ACTUAL FILE TRANSFER COMMAND = as defined by 3270 emulation
  276.  
  277.        NOTE: The file transfer commands ( SEND and RECEIVE ) must be
  278.          copied into the directory where HOSTKEYS is installed.
  279.  
  280.      EXAMPLE:  T:S,c:autoexec.bat 'autoexec.bat.file' recfm(v)
  281.  
  282.            Send the PC file autoexec.bat to the TSO dataset
  283.            'autoexec.bat.file' and store the file using a variable
  284.            record format.
  285.  
  286.  
  287.      HOSTKEYS Script Commands: (CON'T)
  288.  
  289.      --------------------------------------------------------------------
  290.      W: -> WAIT
  291.  
  292.      Format:   W:
  293.  
  294.            WAIT for XCLOCK or XSYSTEM.
  295.  
  296.        NOTE: Should the host session remain in an infinite XCLOCK or
  297.          XSYSTEM state this command will not return.
  298.  
  299.      --------------------------------------------------------------------
  300.      *: -> Comment
  301.  
  302.      Format:   *:Comments are placed here and will be displayed in PC
  303.              session screen or in the log if re-direction is in use.
  304.  
  305.  
  306.      FUTURE ENHANCEMENTS:
  307.  
  308.         The following are planned enhancements for HOSTKEYS.  If you are
  309.      a registered user, you will automatically receive upgrades as they
  310.      become available.
  311.  
  312.      --------------------------------------------------------------------
  313.      I: -> I/O Processing
  314.  
  315.      This command is useful for applications that require offline batching
  316.      of computer input data.  The application can collect host input data
  317.      into a file which can be sent to the host at a later time.  This is
  318.      very useful for remote and international sites where line costs
  319.      prohibit a constant online state.
  320.  
  321.      Formats:   I:O,FILENAME.EXT,MODE
  322.             I:W,FILENAME.EXT
  323.             I:R,FILENAME.EXT
  324.             I:C,FILENAME.EXT
  325.  
  326.             O = Open a file using the mode specified.
  327.             W = Write 3270 Screen to the file.
  328.             R = Read from the file to the 3270 screen and send to host.
  329.             C = Close the file.
  330.  
  331.             MODE   C = Create (If file does not exist)
  332.                A = Append (Open to end of file)
  333.                T = Truncate (Open existing file as empty)
  334.  
  335.        NOTE: You can open as many files as permitted by the system.
  336.        NOTE: Any files left open when the script terminates will
  337.          automatically be closed.
  338.  
  339.      --------------------------------------------------------------------
  340.      E: -> Execute DOS process
  341.  
  342.      This command allows you to execute batch files or PC programs.
  343.  
  344.      Format:    E:PROCESS.EXT,API
  345.  
  346.             PROCESS.EXT = HOSTKEYS will have COMMAND.COM process
  347.                   .BAT files, or will load and execute
  348.                   .EXE and .COM programs.
  349.  
  350.             API = Does DOS process uses HLLAPI?  This allows HOSTKEYS
  351.               to determine if it needs to disconnect from the
  352.               HLLAPI session so the called program can use HLLAPI.
  353.  
  354.                Y = Process USES HLLAPI.
  355.                N = Process does NOT USE HLLAPI.
  356.  
  357.  
  358.  
  359.  
  360.      HOSTKEYS SAMPLE SCRIPT:
  361.  
  362.      A simple sample script file has been provided for your review.
  363.      A batch file that calls HOSTKEYS is also provided.  These have
  364.      been included as a reference to show a script that works under a
  365.      specific environment.
  366.  
  367.       The batch file:  TSO.BAT
  368.  
  369.            hostkeys tso.dat P B > tso.log
  370.  
  371.      This allows the user to simply type TSO at the DOS prompt to
  372.      perform a TSO logon.  NOTE: The symbol ">" is for re-directing
  373.      all messages from HOSTKEYS to the DOS file TSO.LOG.  Use the
  374.      symbol ">>" to append to the log file for a running audit log.
  375.  
  376.       The script file:  TSO.DAT
  377.  
  378.       1.   K:$RESET
  379.       2.   c:18,32,'OPTION',0,NO_VTAM
  380.       3.   K:TSO$ENTER
  381.       4.   C:1,12,'ENTER USERID',120,TIMEFAIL
  382.       5.   K:YOUR_ID$ENTER
  383.       6.   c:1,32,'SECRET PASSWORD(S)',120,TIMEFAIL
  384.       7.   K:PASSWORD$ENTER
  385.       8.   c:5,2,'***',120,TIMEFAIL
  386.       9.   K:$ENTER
  387.      10.   c:1,27,'ISPF/PDF',120,TIMEFAIL
  388.      11.   K:END$ENTER
  389.      12.   c:2,2,'READY',120,TIMEFAIL
  390.      13.   c:18,32,'OPTION'
  391.      14.   g:EXIT
  392.      15.   L:NO_VTAM
  393.      16.   *:  Not at VTAM screen
  394.      17.   g:EXIT
  395.      18.   L:TIMEFAIL
  396.      19.   *:  Logon failure due to timeout
  397.      20.   L:EXIT
  398.  
  399.      NOTE: The numbering to the left is only used here as a reference.
  400.  
  401.      Line 1.  Although this will rarely be necessary, it is advised to
  402.           always start a script with a terminal reset command.
  403.      Line 2.  For this particular host system, when the VTAM banner is
  404.           displayed it contains the string 'OPTION'.  This command
  405.           will check for the string 'OPTION' one time (0 timer) and
  406.           branch to the label NO_VTAM if not found.
  407.      Line 3-12.  These lines send keystrokes and check for screen
  408.           responses until the script reaches the TSO READY prompt.
  409.      Line 13. This command will check for the VTAM banner indefinitly!
  410.           This allows the user to perform TSO processing. When
  411.           a TSO logoff is performed the system will return to the
  412.           VTAM banner, and the script will continue.
  413.      Line 14-20.  Exit and messages commands.
  414.  
  415.      NOTE:    This particular HOST system always has good response time.
  416.         Your particular scripts will need to be tailored to your
  417.         HOST response time.  HOSTKEYS messages are very useful
  418.         for determining where, when, and how much to set timings
  419.         in your commands.  In some cases you may need to call
  420.         the WAIT and/or PAUSE commands.
  421.  
  422.  
  423.     TECHNICAL NOTES:
  424.  
  425.      This section contains information for successfully using HOSTKEYS.
  426.  
  427.     *    CERTIFICATION:
  428.  
  429.     HOSTKEYS has been certified with the following 3270 products:
  430.  
  431.           COMPANY              PRODUCT
  432.         -----------------------------------------
  433.          ATTACHMATE          EXTRA!
  434.          DCA             IRMALAN
  435.          EICON             ACCESS/SDLC
  436.          ICOT             OMNI and KSAVER
  437.          PACKET             PACKET/3270
  438.          RABBIT             RABBITGATE
  439.  
  440.     *    CONNECTION TYPE:
  441.  
  442.     The following is a partial vendor list for concurrent DOS support:
  443.  
  444.           COMPANY              PRODUCT           CONCURRENT DOS SUPPORT
  445.        ------------------------------------------------------------------
  446.          ATTACHMATE          EXTRA!               YES
  447.          DCA             IRMALAN               NO
  448.          EICON             ACCESS/SDLC           YES
  449.          ICOT             OMNI and KSAVER           NO
  450.          PACKET             PACKET/3270           NO
  451.          RABBIT             RABBITGATE            YES
  452.  
  453.     NOTE:  Be sure to use the LOGICAL connection type "L" with
  454.            HOSTKEYS for the above vendor products that do not support
  455.            concurrent DOS.
  456.     NOTE:  Some vendors allow you to set concurrent DOS support at
  457.            configuration time (i.e. Attachmate EXTRA!).
  458.     NOTE:  You can always use the LOGICAL connection type even if your
  459.            3270 emulation has concurrent DOS support.
  460.     NOTE:  Use the hotkey command "H:" when using a LOGICAL connection
  461.            to get to the 3270 session.  When using the "H:" command with
  462.            emulation products that do not support concurrent DOS a manual
  463.            HOTKEY will need to be performed before HOSTKEYS will resume.
  464.  
  465.     Here is a simple way to determine if your 3270 emulation has
  466.     an activated concurrent DOS session.
  467.  
  468.         1. Pass the PHYSICAL "P" connection type to HOSTKEYS.
  469.         2. When HOSTKEYS executes, the PHYSICAL 3270 session will
  470.            appear on the screen.
  471.         3.A. If the 3270 session screen just stands there.
  472.                The DOS session is suspended and HOSTKEYS can not
  473.                continue processing the script.
  474.                You can now manually HOTKEY to the DOS session and
  475.                HOSTKEYS will resume execution.    Timing issues may
  476.                give unexpected results, however; you will now know
  477.                to pass a LOGICAL connection type to HOSTKEYS.
  478.         3.B. If the 3270 session screen is being controlled by
  479.              HOSTKEYS then you know the DOS session is not
  480.              suspended, and concurrent DOS is supported.
  481.  
  482.     NOTE:  The above products are trademarks of their respective
  483.            companies.
  484.  
  485.  
  486.     TECHNICAL NOTES Con't:
  487.  
  488.     *    TIMING:
  489.  
  490.      Successful scripting is very dependent on properly handling HOST
  491.     response times.
  492.  
  493.     Setting timer values on certain HOSTKEYS commands is critical
  494.     to allow the HOST ample time to respond, but also to allow you to
  495.     determine script processing control.  Depending on what the possible
  496.     HOST responses can be will determine what script commands should be
  497.     executed next.
  498.  
  499.     Due to poor HOST response time, a HOSTKEYS command can have a
  500.     successful condition (i.e. the specified string WAS found at row X
  501.     column X) yet the 3270 session is still in an XCLOCK or XSYSTEM state.
  502.  
  503.     NOTE: The following commands wait for XCLOCK or XSYSTEM up to 1 minute
  504.           after a successful condition.
  505.  
  506.           C:  Check 3270 screen for a string.
  507.           K:  Send keystrokes to host.
  508.           S:  Search 3270 screen for a string.
  509.  
  510.           In some cases slow HOST response time will leave the 3270 session
  511.           in an XCLOCK or XSYSTEM state for longer than 1 minute.
  512.  
  513.           The following message will be generated to indicate when this
  514.           condition has occured:
  515.  
  516.           HLLAPI WAIT - Warning: Timed out while still in XCLOCK or XSYSTEM.
  517.  
  518.           When more time is required for XCLOCK or XSYSTEM you can use the
  519.           WAIT "W:" command.  The WAIT command will wait for XCLOCK or
  520.           XSYSTEM indefinitly.
  521.  
  522.     NOTE: When refering to slow HOST response time, the terminology used
  523.           does not necessarily imply that the HOST system itself has poor
  524.           response time.  Response time is affected by the network topology
  525.           and the type of connection to it (i.e. direct coax, SDLC dial-up
  526.           or leased line, LAN Gateway, Packet/Switched Network, etc).
  527.  
  528.     *    INTERACTIVE USER:
  529.  
  530.      Successful scripting is very dependent on properly handling where
  531.     a user can leave a 3270 session when using HOSTKEYS to allow for
  532.     user interaction.
  533.  
  534.     When using HOSTKEYS to allow a user interactive use of the 3270
  535.     session, the 3270 session may need to be left at a particular
  536.     screen for HOSTKEYS to continue processing.  The sample script
  537.     provided is an example of using HOSTKEYS to allow user interaction.
  538.  
  539.     *    KNOWN ISSUES:
  540.  
  541.       When using HOSTKEYS with ATTACHMATE EXTRA! sessions "D" and "E"
  542.      are not recognized, however; sessions "B" and "C" work fine.
  543.  
  544.     Research and is currently underway to resolve these issues.
  545.  
  546.