TNAPI - telnet API

Copyright 2017 Albert York

TNAPI can be used to run interactive jobs in a batch environment. It 
establishes a VT100 telnet connection with the iSeries and allows you 
to send keystrokes to the application and receive the resulting screen as 
data.

TNAPI is freeware. You may use it in your applications as long as you 
include all copyright information, don't represent it as your own, and 
do not attempt to sell it. Support is not provided, however, if you have 
any questions and/or comments contact me at albertyork@email.com.


Installation

Download the following files to the iseries, copy them to source file members, and compile them.
    TNAPI.DSPF - TNAPI display file
    TNAPI.RPGLE - TNAPI program
    RUNTNSCR.CMD - Run TNAPI script command
    RUNTNSCR.RPG - Run TNAPI script program
    #TNAPIFUNC.RPGLE - Copy source for TNAPIFUNC 
    TNAPIFUNC.RPGLE - TNAPI functions. See TNAPIFUNC.DOC for more information.

Note: Most functions are available through the TNAPIFUNC service program and are easier to use than directly calling TNAPI. 


Calling TNAPI
                            
Input Parameters:

Send buffer (256)
  The data to send to the iSeries. It can include imbedded 
  cursor control commands (for example %RT to move the cursor to the 
  right). Refer to the program for a complete list of cursor control codes. 
  Normally trailing blanks are not sent. In order to send trailing blanks, 
  follow them with %CR. For example: 'MYDATA   %CR'
  Special control codes:
         %L0 - do not log data that comes after %L0
               until %L1 or end of data
               (used primarily for passwords)
         %L1 - Resume logging data
         %PC - Send per cent symbol (%)
         %CR - End of data. Optional (used for trailing blanks)

Function key (6).
  A function key to send after the send buffer has been 
  sent or instead of sending data. The most common are ENTER and F1 through F24.  At the end of the job 
  you should call TNAPI with a function code of `EOJ' in order to ensure the connection is closed. 
  Special function codes:
      POSCSR - position cursor. Desired cursor position is in the send buffer as RR,CC (ex 03,27)
      REDRAW - Send request to iSeries to resend the current screen
      GETDTA - Do not send anything. Just receive data and return
      EOJ    - Close telnet session and exit

Timeout (5.1).
  The number of seconds (to 1/10th of a second) to wait for a 
  response from the iSeries before returning. TNAPI will return to your 
  program when the iSeries has completed sending a screen and is 
  waiting for input (unless a wait string is specified; see below) or until 
  the specified timeout has elapsed. If the wait time elapsed the return code will be set to 2

Wait String array (740). 
  An array of up to 20 wait strings. If wait strings are
  passed TNAPI will wait until the text appears at the specified location
  on the screen before returning. Multiple strings can be passed, using
  AND/OR logic.

  Each wait string is defined as follows:
     Pos 1-1  - And/Or option. A=and, O=or. First element or blank
                defaults to O.
     Pos 2-3  - Row to wait for text                                 
     Pos 4-5  - Column to wait for text                              
     Pos 6-37 - Text string to wait for. If there are trailing blanks
                then append  a null (x'00')
                                       
If there is no wait string then pass a blank field of 740 bytes.

Wait string pointer (2.0)
  If wait strings are passed this is a pointer
  to the array element of the first wait sequence which matched.

System name or address to connect to (64).
  If blank then LOOPBACK is assumed.

Display screens (Y/N). 
  Display screens as they are received (interactive jobs only)

Return screen attributes (Y/N)
  Return attributes as well as data.

Log file name (10). 
   Specify *NONE if no logging. If blank TNAPILOG is assumed.
      Log files are flat files 80 bytes in length that contains the data that is sent 
      and each screen that is received


Output Parameters

Return code. 
  0=Normal return. 
  1=Application error requiring ERROR RESET be sent. 
  2=TNAPI timed out waiting for a response from the iSeries.
  3=Socket (TCP/IP) error or end of job. 

Screen data buffer (1920). 
   The current screen (1920 bytes for 24X80 screen).                     

Screen attributes buffer (1920). 
   The current display attributes for each character. This is returned on if the Return screen attributes 
   parameter is set to Y
   X'20' - Normal display.
   X'21' - Reverse image
   X'22' - High intensity.
   X'23' - High intensity, reverse image.
   X'24' - Underline
   X'25' - Underline, reverse image
   X'26' - High intensity, underline
   X'27' - Non-display

Current row (2.0) 
   Row where the cursor is currently positioned.

Current column (2.0).
   Column where the cursor is currently positioned. 



Notes:

The first time TNAPI is called it will connect to the iSeries and wait 
for the sign on screen.

If wait strings are specified TNAPI will return as soon as any of the strings 
appear. If no wait string is specified and a function key is specified 
TNAPI will wait until the iSeries has completed sending the response 
before returning. If neither a wait string nor a function key is specified, 
TNAPI will receive any data the iSeries has sent and transmit the send 
buffer but will not wait for a response from the iSeries.


For an example of how to use TNAPI see the file TNAPIEX.TXT.

See the source file TNAPI.RPGLE for additional notes


