Piper's Pit BBS/FTP: ibm 0010 - 0019/ibm0010-0019/ibm0010.tar/ibm0010/REFLECT.ZIP/API.DOC

Text File | 1989-10-17 | 106.6 KB | 4,252 lines

             Reflection API Support Disk

This diskette contains support files and utility (demo) programs for
Reflection's API (Application Program Interface) feature.  All Reflection
emulators for the IBM PC family version 3.40 and above have API support
included.  This diskette containing special files and libraries is included
with PLUS versions of Reflection only.


           API Support Disk Files


    API.DOC     This document


<APIDEMO> Directory    Utility programs which use API feature

    HPCMD.EXE    Run HP commands at the DOS prompt and see
            the results displayed on the PC screen

    HPCMD.C     Source for HPCMD.EXE

    DOAPI.EXE    Send a command to Reflection in background
            to transfer a file or run a command script

    DOAPI.C     Source for DOAPI.EXE

    $.EXE        Run VAX commands from the DOS prompt with
            results displayed on PC screen

    HP.BAT        Sample DOS batch file which demonstrates
            how HPCMD.EXE (named LISTF.EXE) can be used
            to check for a file on the HP3000 from DOS

    APIDEMO.DOC    Documentation on the above files


<Pascal> Directory    Turbo Pascal Library support for API

    APIUNIT.PAS    Source of API UNIT file

    APIUNIT.TPU    TPU Unit file - created by compiling APIUNIT.PAS:
            Code can be included into your Pascal program via the
            'uses' statement

    P_APILIB.OBJ    API library in OBJ format. Used to create new
            APIUNIT.TPU.  You may customize APIUNIT.PAS as needed
            and recompile via the TPC command.

    SAMPLE.PAS    Sample Pascal program which does API calls

    SAMPLE.EXE    Compiled version of SAMPLE.PAS


<BASIC> Directory    Microsoft QuickBASIC library support for API

    API.INC     Include file listing all function
            declarations.    Use the $INCLUDE metacommand
            to include this file in your BASIC source.

    SAMPLE.BAS    Sample BASIC program using API calls

    SAMPLE.EXE    Compiled version of SAMPLE.BAS

    B_APILIB.QLB    QuickBASIC Library with API calls.
            Use with QuickBASIC environment.

    B_APILIB.LIB    Standard API LIB for use with command
            line BC compiler and linker

    BAS_API.DOC    List of API function declarations


<C> Directory        C Library support for API

    API.H        Include file with API structure definitions

    SAMPLE.C    Sample program which uses API calls

    SAMPLE.EXE    Compiled version of SAMPLE.C

    C_SAPI.LIB    Small model API library

    C_CAPI.LIB    Compact model API library

    C_MAPI.LIB    Medium model API library

    C_LAPI.LIB    Large model API library


          THE REFLECTION APPLICATION PROGRAM INTERFACE (API)


Reflection terminal emulation products with the BACKGROUND multitasking feature
have provided the ability to run two programs simultaneously on your PC.  You
can run a program in foreground - say a word processor - and at the same time
be transferring files from the PC to a host computer in the background.

With the arrival of the background multitasking feature, it made sense to
provide a way for foreground programs to 'hook' into Reflection so that they
could initiate file transfers, log on to a host computer, dial a modem or
perform some other communication function.  Reflection API provides that
service, allowing DOS programs to control a background copy of Reflection and
make the background copy do anything that a user could do.  Now your programs
can simulate a user typing on the keyboard, issuing commands, filling in data
entry screens, even hitting the hot-key which would pop Reflection into the
foreground.

All standard versions of Reflection will be shipped with API support starting
with version 3.40.  The code will not be loaded into memory, however, unless
the user invokes Reflection with the /W switch from the DOS command line.  API
support requires approximately 4000 additional bytes of memory.  While API
support will be present in all versions of Reflection for the IBM PC, software
developers will need the PLUS versions of Reflection 1, 2, 4, or 7 to avail
themselves of software libraries for C, Turbo Pascal and Microsoft QuickBASIC.


API functions fall into several groups:

Status calls

    api_rcheck        see if Reflection installed
    api_instchk        see if API present
    api_getinfo        get static information
    api_getstatus        get dynamic information

Command Language

    Group I  - synchronous (Do while-you-wait commands)

    api_startcommands    start a command sequence
    api_docommand        do a command
    api_getvar        return a command language variable
    api_setvar        set a command language variable
    api_found        return value of the FOUND boolean
    api_endcommands     end a command sequence

    Group 2  - queued/asynchronous (Do in background commands)

    api_cmdstatus        how much free space is in the API queue
    api_qcmd        queue a new command
    api_clrcmdq        flush the queue of commands

Keyboard support

    api_keystatus        how much free space is in the API queue
    api_qkeys        queue some keystrokes
    api_clrkeybd        flush the keyboard queue
    api_getfkey        get a function key
    api_setfkey        set a function key

Screen    support

    api_screenread        read the text screen (minus function keys)
    api_atrbscreen        read screen with character attributes
    api_searchscreen    search the screen for a string


Datacomm support

    api_rdchar        read a character from com port    (may be lan)
    api_writeasync        write character to com port (may be lan)
    api_xmitstatus        check status of transmit buffer
    api_releasedc        release the datacomm port
    api_assertdc        re assert control over the datacomm port

Session support

    api_open        start an API session
    api_close        end an API session
    api_wait        wait until Reflection is free
    api_block        give Reflection some CPU time
    api_popup        pop up Reflection

Miscellaneous

    api_reset        do a hard reset of Reflection
    api_offerbuf        provide buffers for queuing keys/commands
    api_cancelbuf        cancel use of buffer


Queued versus Synchronous commands

You will notice that some of the functions are QUEUED (asynchronous) and some
of the commands are synchronous.  A queued function posts a request for
Reflection to do something as time permits.  The request is processed when
Reflection gets to it in the queue, and there's no guarantee exactly when it
will be done.  The advantage is that the function call returns to the client
program immediately (as soon as the request is queued) and the client program
can go about its business while Reflection works on the queued request.

Suppose that a client program creates a file that it wants Reflection to
transfer to a VAX.  The program can queue the request and then let Reflection
worry about transferring the file.  Meanwhile the client program can be busy
interacting with the user.  Asynchronous commands capitalize on the
multitasking capability of Reflection.

More frequently used are synchronous functions, where you must wait for the
function to be completed before proceeding.  This will be familiar to most
programmers.  You want to transfer a file to the VAX.  You call the function,
the file transfers, and when it's all done the function returns with an error
code (hopefully 0).  Synchronous commands can have their limitations if you're
simultaneously trying to interact with a user since, unlike most system calls
(write to file, read character from keyboard), a file transfer can take a long
time.  Your user may wonder what's happening and will get no visual
feedback.  Your PC will act like it is hung and there is no way to break out
except by using Ctrl-Alt-Del.  See the tip on Synchronous File Transfers
below to get around this.

It can be dangerous, too.  If you forget and send Reflection a command like
"WAIT FOR 'Password:  '", you had better be sure that the text 'Password:'
is going to come down from the host computer SOON, otherwise the function call
will NEVER return!  Your computer is hung waiting for the required message to
come from the VAX or HP3000.  Rather than risk this, you will want to make sure
that all commands have a timeout period:

        'WAIT 0:0:2 for "Password: "'

This command will only wait up to 2 seconds for the string.  If the string has
already arrived or arrives in .05 seconds, the call will return quickly to your
program.  Another function lets you find out if the string was actually found.

Note that API is only active if Reflection is in background.  If Reflection is
popped into the foreground, the API client program (like any other foreground
program) freezes until Reflection is popped back into the background.



              The API Function Calls
              ----------------------


The following section consists of a description of each of the function calls
with short examples in C and assembler, Pascal and QuickBASIC.    Function
calls 28, 29, and 30 are reserved for future use.

    Assembly Language Interface

    AH = 0DE52H
    DX = 0
    CH = 0        (reserved for future use)
    CL = API function code
    ES   Used to pass parameters
    BX   Used to pass parameters
    SI   Used to pass parameters
    DI   Used to pass parameters

    INT    21H    Use MS-DOS Interrupt 21H to access API


-----------------------------------------------------------------------------
    api_rcheck        # - N/A
-----------------------------------------------------------------------------
    Purpose:    See if a copy of Reflection is present in the
            background.

    INPUT    AX = 0DE57H

    OUTPUT    AX = "RQ"        - implies Reflection present
        AX = other value - implies Reflection not present

       *This function has existed in all versions of Reflection
    from 2.00 on.    Departs from the standard API call format
    (AX = DE57H instead of DE52H.  CX N/A.

    This function may be used to detect the presence of any
    version of Reflection including those prior to version 3.4.
    It does not imply that the API code is present, only that
    a copy of Reflection is present in background.    This will
    enable you to tell a user that while Reflection may be
    installed, either the /W switch was not used or it is
    a pre-3.40 version.

Assembler Example:
------------------
    mov    ah,0DE57H
    int    21h
    cmp    ax, "RQ"                ;  Does AX have correct signature?
    jz    Reflection_present    ;  Yes - Reflection is present
    mov    ah,9            ;  No  - print error message and exit
    mov    dx,offset error_message
    int    21h
    mov    ah,4ch
    int    21h
error_message    db    "Reflection not installed",0dh,0ah,"$"


C Function Definition:
----------------------
int api_rcheck()    returns 0 if Reflection is present


C Programming Example:
----------------------
main()
{
    /* See if Reflection is in background */

    if (api_rcheck())
        printf("Reflection not installed\n");
    else
        printf("Reflection in background\n");
}




BASIC Function Definition
-------------------------

DECLARE FUNCTION api.rcheck% CDECL ()


BASIC example    - see if Reflection installed
-------------

' $INCLUDE: 'API.INC'

if api.rcheck <> 0 then
    print "Reflection not installed"
else
    print "Reflection in background"
end if

TURBO Function Definition
-------------------------

function api_rcheck : integer;


TURBO Pascal example    - see if Reflection installed
--------------------
uses    apiunit;
var

begin
    if api_rcheck <> 0 then
        writeln('Reflection not installed')
    else
        writeln('Reflection in background');



-----------------------------------------------------------------------------
    api_instchk            0
-----------------------------------------------------------------------------
    Purpose:  See if the API support code has been loaded via
          the /W switch.  Determines Reflection product,
          version, and serial numbers.

    The remaining 17 bytes of the buffer are reserved for future
    use.

    INPUT:    CX = 0
        AX = DE52H
        DX = 0
        ES:BX point to 32 byte buffer to receive serial number


    OUTPUT:
       No error:
        AX =  0
        Null-terminated Reflection 14-byte serial number
        copied to buffer.
        See Command Language manual for serial number format.
       Error:
        AX <> 0


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,0
    push    ds
    pop    es
    ASSUME ES:DATA
    mov    bx,offset serialno_buffer   ;ES:BX -> buffer
    int    21h
    or    ax,ax
    jnz    not_installed    ; Error if AX not zero


serialno_buffer db    32 dup (0)

C Function Definition:
----------------------

int api_instchk(serialbuf)    returns 0 if Reflection present
char    *serialbuf;        serialbuf points to 32 byte buffer


C Programming Example:
----------------------

char    serialbuf[32];
    if ( api_instchk( serialbuf )) {
        printf( "API support not present restart with /W switch\n");
        exit();
    }
    else
        printf( "Reflection serial number %s\n", serialbuf );


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.instchk% CDECL (SEG serno$)
set serno$ to spaces prior to call
serno$= spaces$(32)

Basic Example    - Get Reflection serial number if API present
-------------
' $INCLUDE: 'API.INC'

    serno$ = space$(32)
    if api.rcheck%(serno$) <> 0 then
         print "API support not present, restart with /W switch")
    end if

TURBO Function Definition
-------------------------

function api_InstChk( var s: string ) :integer;

TURBO Pascal example
--------------------

uses    apiunit;
var    serno    : string[32];

begin
    if api_instchk( serno ) > 0  then exit;
    writeln( 'serial number is ', serno )
end.

-----------------------------------------------------------------------------
        api_open               1
-----------------------------------------------------------------------------
    Purpose: Initialize Reflection for a series of API function
         calls.

    Make this call prior to making any others, except for
    api_instchk (function 0) or api_rcheck.

    Make this call once prior to using Reflection API
    and make the api_close call when API use is
    complete.


    INPUT:    CX = 1
        AX = DE52H
        DX = 0


    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = error code
        Should not return error if Reflection present

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,1
    int    21h
    or    ax,ax
    jz    api_started
    mov    ah,4ch
    int    21h

C Function Definition:
----------------------
int api_open();


C Programming Example:
----------------------

main()
{
    /* Start API services */

    if(!api_open())
        printf( "Reflection API initialized\n");
    else
        printf( "Reflection API not found\n");
    api_close();
}


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.open% CDECL ()

BASIC Example    - open API services
-------------
' $INCLUDE: 'API.INC'
    i% = api.open%

TURBO Function Definition
-------------------------

function api_Open :integer;


TURBO Pascal example
--------------------

    uses    apiunit;
    var
        i : integer;
    begin
        i := api_open;
    end.
-----------------------------------------------------------------------------
    api_close              2
-----------------------------------------------------------------------------
    Purpose: Closes API services, clears buffers and
         returns Reflection to pre-start state.

    Do not make this call until API use is complete.  You may wish to
    queue several commands and terminate your program without issuing an
    api_close command to allow Reflection to process the commands in
    background.  Don't issue the close command until the commands have
    been completed since this call will clear the command queues.


    INPUT:    CX = 2
        AX = DE52H
        DX = 0

    OUTPUT:
       No error:
        AX =  0
       Error:
        Should not return an error if installed


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,2
    int    21h
    or    ax,ax
    ret

C Function Definition:
----------------------
int api_close();


C Programming Example:
----------------------
    api_close();


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.close% CDECL ()


BASIC Example    - close API services
-------------
' $INCLUDE: 'API.INC'
    i% = api.close%


TURBO Function Definition
-------------------------

function api_Close :integer;

TURBO Pascal example
--------------------
    uses    apiunit;
    var
        i : integer;
    begin
        i := api_close;
    end.

-----------------------------------------------------------------------------
    api_getinfo        3
-----------------------------------------------------------------------------
    Purpose: Get information from Reflection.  This call returns
         information of a relatively non-volatile nature,
         i.e. information what should not change on a second
         by second basis.

    INPUT:    CX = 3
        AX = DE52H
        DX = 0
        ES:BX points to user buffer
        SI = # of words of information to be written to user
        buffer. If SI exceeds structure size (25) remaining space
        is zeroed.

    OUTPUT:
       No error:
        AX =  0
        Buffer initialized

       Error:
        AX = error code
        Should not return error if Reflection present



struct api_infostruc {
    int          apiinfo_apiversion;
    int          apiinfo_function_key_mode;
    int          apiinfo_local_echo;
    int          apiinfo_remote_mode;
    int          apiinfo_caps_lock;
    int          apiinfo_display_functions;
    int          apiinfo_auto_linefeed;
    int          apiinfo_right_margin;
    int          apiinfo_phys_screen_width;
    int          apiinfo_memory_response;         /* HP */
    int          apiinfo_xmit_functions;         /* HP */
    int          apiinfo_spow_strap;         /* HP */
    int          apiinfo_inheolwrp;         /* HP */
    int          apiinfo_line_page_mode;         /* HP */
    int          apiinfo_inhhndshk;         /* HP */
    int          apiinfo_inhdc2;             /* HP */
    int          apiinfo_block_mode;         /* HP */
    int          apiinfo_format_mode;         /* HP */
    int          apiinfo_memory_lock;         /* HP */
    int          apiinfo_type_ahead;         /* HP */
    int          apiinfo_normal_cursor_key_mode;/* DEC */
    int          apiinfo_numeric_keypad_mode;   /* DEC */
    int          apiinfo_multipage_mode;         /* DEC */
    int          apiinfo_user_features_locked;  /* DEC */
    int          apiinfo_udks_locked;         /* DEC */
}

        Structure Definitions
        ---------------------

apiinfo_apiversion           Version number of API.  High byte = major
                   version.  Low byte is minor version.

apiinfo_function_key_mode      Number identifying current set of
                   function keys displayed at bottom of
                   Reflection Screen

    R2 R4 Keys            R1, R7, R1V, R7V Keys

  MAINMENU       =      0      MODESKEYS       =      0
  SOFTKEYS       =      1      USERKEYS       =      1
  VT102KEYS       =      2      SYSTEMKEYS       =      2
  NOKEYS       =      3      CONFIGKEYS       =      3
  CONFIGKEYS       =      4      MARGINTABKEYS    =      4
  DEVICECTLKEYS    =      5      ENHANCEKEYS       =      5
  DEVICEMODESKEYS  =      6      DEVICECTLKEYS    =      6
  TODEVICEKEYS       =      7      DEVICEMODESKEYS  =      7
  FILEXFERKEYS       =      8      USERMENUKEYS       =      8
  TABKEYS       =      9      FILEXFERKEYS       =      9
  TERMINALKEYS       =      10      TODEVICEKEYS       =      10
  GRAPHICSKEYS       =      11      VT102KEYS       =      11    R1V/R7V
                  VMODESKEYS       =      12    R1V/R7V
                  VMAINMENU       =      13    R1V/R7V
                  VTABKEYS       =      14    R1V/R7V

apiinfo_local_echo           0 = OFF           1 = ON
apiinfo_remote_mode           0 = OFF           1 = ON
apiinfo_caps_lock           0 = OFF           1 = ON
apiinfo_display_functions      0 = OFF           1 = ON
apiinfo_auto_linefeed           0 = OFF           1 = ON
apiinfo_right_margin           logical right hand margin of screen (0 relative)
apiinfo_phys_screen_width      actual physical width of screen (1 relative)
apiinfo_memory_response
                0 = 4K
                1 = 8K
                2 = 12K
                3 = 15K

apiinfo_xmit_functions           0 = OFF           1 = ON
apiinfo_spow_strap           0 = OFF           1 = ON
apiinfo_inheolwrp           0 = OFF           1 = ON
apiinfo_line_page_mode           0 = LINE        1 = PAGE
apiinfo_inhhndshk           0 = OFF           1 = ON
apiinfo_inhdc2               0 = OFF           1 = ON
apiinfo_block_mode           0 = OFF           1 = ON
apiinfo_format_mode           0 = OFF           1 = ON
apiinfo_memory_lock           0 = OFF           1 = ON
apiinfo_type_ahead           0 = OFF           1 = ON
apiinfo_normal_cursor_key_mode 0 = APPL        1 = NORMAL
apiinfo_numeric_keypad_mode    0 = APPL        1 = NORMAL
apiinfo_multipage_mode           0 = OFF           1 = ON
apiinfo_user_features_locked   0 = UNLOCKED    1 = LOCKED
apiinfo_udks_locked           0 = UNLOCKED    1 = LOCKED

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset infostructure
    mov    cx,3
    int    21h
    or    ax,ax
    jnz    info_error

C Function Definition:
----------------------

int api_getinfo( infobuffer, count );
struct api_infostruc *infobuffer;    infobuffer points to structure
                    defined above
int    count;                infobuffer size in words

C Programming Example:
----------------------

main()
{

    /* find the physical screen width */

    struct  api_infostruc infobuffer;
    struct  api_infostruc *sptr;
    api_open();
    sptr    = &infobuffer;
    api_getinfo( sptr , 25);
    printf( "Physical Screen Width = %d\n",sptr->apiinfo_phys_screen_width);
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.getinfo% CDECL (SEG buffer AS RINFO, BYVAL rvarlen%)
see api.inc for RINFO user-defined type definition
rvarlen% = size of buffer

BASIC Example    - get Reflection physical screen width
-------------

' $include: 'api.inc'
'
'       See API.INC for description of user-defined type RINFO
'
COMMON X AS RINFO

i% = api.getinfo( X, 25%)
print "Reflection screen width is "; x.rphysscreenwidth
end




TURBO Function Definition
-------------------------

function api_GetInfo(i:integer; var x:info_array ) :integer;

i = size of info_array buffer
see apiunit.pas for info_array type declaration

TURBO Pascal example    - get screen width
--------------------
uses  apiunit;
var
    info    : info_array;
    i    : integer;

begin
    if api_getinfo( 25, info )  > 0 then exit;
    writeln( 'screen width is ', info[8] );
end.
-----------------------------------------------------------------------------
    api_getstatus        4
-----------------------------------------------------------------------------
    Purpose: Return status of volatile information from Reflection.
         This information is time critical.

    INPUT:    CX = 4
        AX = DE52H
        DX = 0
        ES:BX point to    structure
        SI   specifies number of words (12) to be returned to user
             buffer.  If SI greater than structure size, excess
             buffer area will be zeroed.
    OUTPUT:
       No error:
        AX =  0


       Error:
        AX = error code
        Should not return error if Reflection present

struct api_statstruc    {
   int          apistat_pagetop_row;
   int          apistat_cursor_row;
   int          apistat_cursor_col;
   int          apistat_left_border;
   int          apistat_cursor_physrow;
   int          apistat_cursor_physcol;
   int          apistat_kb_lock_sw;
   int          apistat_batch_flag;
   int          apistat_datacomm_error_flag;    /* HP */
   int          apistat_host_prompt_received;    /* HP */
   int          apistat_xfer_pending_sw;        /* HP */
};

        Structure Definitions
        ---------------------

apistat_pagetop_row        0 relative row number of display memory
                for top of screen, i.e. if 100 lines
                of text have scrolled off the top of
                the screen (and are still in display
                memory), the top of the screen would
                display row 101 or pagetop_row 100.

apistat_cursor_row        logical 0 relative cursor row from
                beginning of display memory

apistat_cursor_col        logical 0 relative cursor column from
                left hand margin of screen

apistat_left_border        column position of left border of screen
                (true left margin may have been scrolled
                off of screen)

apistat_cursor_physrow        actual physical row where cursor is located
                (0 relative)

apistat_cursor_physcol        actual physical column where cursor is
                located (0 relative)

apistat_kb_lock_sw        keyboard lock status
                0 = No Lock    <>0 = Keyboard Locked


apistat_batch_flag        0 = Reflection IDLE, <>0 BUSY

apistat_datacomm_error_flag    1 = DATCOMM ERROR has occurred since last
                    primary status request.

apistat_host_prompt_received    1 = Host prompt has been received
                0 = Waiting for host prompt.

apistat_xfer_pending_sw     <>0 = Transfer of data has been requested
                      from host.  Waiting to receive prompt
                      before starting transfer.

                0   No transfer pending



Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset status_struc
    mov    cx,4
    int    21h
    or    ax,ax
    jnz    info_error

status_struc    dw    22 dup (?)    ; 44 byte buffer to receive data

C Function Definition:
----------------------

int api_getstatus(  statusbuf, siz )
struct api_statstruc *statusbuf;    statusbuf is pointer to structure
int    siz;

C Programming Example:
----------------------
main()
{

    /* find which row the cursor is on */

    struct    api_statstruc    buffer;
    struct    api_statstruc    *sptr;
    api_open();
    sptr = &buffer;
    api_getstatus(sptr, 11);    /* returns 11 words of status info */
    printf( "cursor row = %d",sptr->apistat_cursor_row);
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.getstatus% CDECL (SEG buffer AS RSTAT, BYVAL rvarlen%)
see api.inc for RSTAT user-defined type definition
rvarlen% = size of buffer


BASIC Example    - get physical cursor and row position.
-------------

' $include: 'api.inc'
'
'       See API.INC for description of user-defined type RSTAT
'
COMMON Y AS RSTAT

i% = api.getstatus( Y, 11%)
print "Cursor at ROW ";y.Rcursorphysrow ;" COL ";y.Rcursorphyscol
end

TURBO Function Definition
-------------------------

function api_getstatus(i:integer; var x:stat_array ) :integer;
i = size of stat_array buffer
see apiunit.pas for stat_array type declaration

TURBO Pascal example
--------------------
uses    apiunit;
var    status    : stat_array;

begin
    if api_getstatus(11, status )  > 0 then exit;
    writeln ( 'cursor row is ', status[1] , ' column ' ,status[2] );
end.


-----------------------------------------------------------------------------
    api_startcommands    5
-----------------------------------------------------------------------------
    Purpose: Prepares Reflection for series of synchronous commands.
         This call will return an error if Reflection is busy,
         i.e. if it is already performing a command or
         file transfer.  If successful, this call turns off
         incoming (characters remain in receive buffer) unless
         a docommand() is actually being processed.

    After the api_startcommands function has been issued, Reflection
    will no longer read incoming datacomm out of the receive buffer
    unless a Reflection command is actually being executed.  In most
    cases, startcommands should not be issued until you are ready to
    start processing commands.  Depending on the type of receive
    pacing, you may run the risk of overflowing the receive buffer.
    Note that datacomm is turned back on while Reflection is
    in foreground.    Upon return to background, datacomm is turned back
    off unless a command is active.

    INPUT:    CX = 5
        AX = DE52H
        DX = 0

    OUTPUT:
       No error:
        AX =  0
       Error:
        AX = 100H  Not available (busy)

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,5
    int    21h
    or    ax,ax
    jnz    Reflection_Busy

C Function Definition:
----------------------
int api_startcommands();    returns non-zero if error or busy

C Programming Example:
----------------------
    if(api_startcommands())
        printf( "Reflection Busy\n");

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.startcommands% CDECL ()

BASIC example    - see if we can start docommand sequence
-------------

' $include: 'api.inc'

if api.startcommands% > 0 then print "Reflection busy"
end

TURBO Function Definition
-------------------------

function api_startcommands :integer;

TURBO Pascal example
--------------------
    uses    apiunit;
    var
        i : integer;
    begin
        if api_startcommands <> 0 then
            writeln ( 'Reflection busy' );
    end.

-----------------------------------------------------------------------------
    api_docommand        6
-----------------------------------------------------------------------------
    Purpose: Perform a Reflection command synchronously.  The
         call does not return to the calling caller until the
         command has been completed or an error is encountered.

      During the wait for a Reflection command to complete, you can
      not use the HOT-KEY.  Reflection will just beep at you.
      "ALERT" messages will not blink on and off as normal.
      The calling program will be frozen until the command completes.
      Make sure that all commands issued will time out after
      a while otherwise your API program can crash waiting for
      a condition that may never be met.  See note on
      Synchronous File Transfers.

        i.e.  use:
            WAIT 0:0:10 FOR "^Q"
              rather than
            WAIT FOR "^Q"

    INPUT:    CX = 6
        AX = DE52H
        DX = 0
        ES:BX points to buffer containing null-terminated
        command string.

    OUTPUT:
       No error:
        AX =  0 Command performed satisfactorily


       Error:
        AX =  Standard Reflection error code for command
              language.
        AX =  102H Service not open - need api_startcommands()

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,6            ; Function call 6
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset Reflection_command
    int    21h
    or    ax,ax
    jnz    command_error


Reflection_command db "SEND ABC TO XYZ  ASCII REC=80",0

C Function Definition:
----------------------
int api_docommand( command_string )    returns error code / 0 if no error


char    *command_string;    command_string points to null-terminated
                Reflection command

C Programming Example:
----------------------
main()
{
    /* do a synch file transfer - print error code if failed */

    int     error;
    char    *command_string = "SEND ABC TO XYZ ASCII REC=80";
    api_open();
    api_startcommands();
    if (error = api_docommand(command_string))
           printf( "File transfer failed, error code = %d\n",error);
    api_endcommands();
    api_close ();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.docommand% CDECL (SEG rcommand$)

BASIC example:    - transfer a file
--------------
' $include: 'api.inc'

i% = api.startcommands%
cm$ = "SEND ABC TO XYZ ASCII REC=80"
error% = api.docommand%(cm$)
if error% > 0 then print "File transfer failed, error code = ";error%
i% = api.endcommands%
end

TURBO Function Definition
-------------------------

function api_DoCommand( var x: string ) :integer;

TURBO Pascal example    - send a file
--------------------
    {$V-}
    uses    apiunit;
    var
        i  : integer;
        cm : string[80];
    begin
        cm := 'SEND ABC TO XYZ ASCII REC=80';
        if api_startcommands <> 0 then
            writeln ( 'Reflection busy' );
        if api_docommand( cm ) <> 0 then
            writeln ( 'error transferring file' );
        i := api_endcommands;
    end.



-----------------------------------------------------------------------------
    api_getvar        7
-----------------------------------------------------------------------------
    Purpose: Return contents of variable to user buffer.
         Note that a Reflection variable may contain characters
         of any value including nulls.

    This command should only be executed as part of a synchronous
    command sequence otherwise it can return random values.
    i.e. It may interrupt Reflection's changing of one variable
    to another so a false result could occur.

    *Variables can not always be null-terminated in this way
    since it is possible for them to contain nulls themselves.

    INPUT:    CX = 7
        AX = DE52H
        DX = 0
        ES:BX points to 80 byte buffer
        SI = variable number

    OUTPUT:
       No error:
        AX =  0
        SI = # length of variable
       Error:
        AX = 10AH bad variable no



Assembler Example:    Get variable V8 and null-terminate
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,7            ; Function GetVar
    mov    si,8            ; get variable V8
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset Variable_Buffer
    int    21h
                    ; SI is length of variable V8
                    ; put NULL at end of string
    mov    byte ptr [variable_length+SI],0
    or    ax,ax            ; was there an error
    jnz    Bad_variable_number    ; yes.


Variable_Buffer db 80 dup (?)

C Function Definition:
----------------------

int api_getvar( var_buffer, varno, varlength )
                returns non-zero if error
                returns length of variable

char    *var_buffer;        buffer for 80 byte variable
int    varno;            variable number 0 - 799
int    &varlength;        returned length of variable

C Programming Example:
----------------------
main()
{

    /*   Find out if a file is present on the HP3000 */

    int    length;
    char    varbuf[80];
    api_open();
    api_startcommands();
    printf("Enter filename :");
    gets(varbuf);
    length = strlen( varbuf );
    api_setvar(varbuf,1, length);
    api_docommand("transmit 'listf $1^m'");
    api_docommand("readhost 0:0:5 v2");
    api_docommand("readhost 0:0:5 v2");   /* get HP response */
    api_docommand("wait 0:0:8 for '^q'");
    api_getvar( varbuf, 2, &length );     /* get v2 */
    varbuf[length] = '\0';                /* null-terminate v2 */
    if (strstr( varbuf, "CIERR" ))
        printf( "File Not Found on Host\n");
    api_endcommands();
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.getvar% CDECL (SEG var$, BYVAL varnumber%, SEG rvarlen%)
var$ = string first initialized to at least 80 characters in size
       - for receiving variable data
varnumber% = variable number
rvarlen% = length of variable

BASIC example    - find out if a file is present on a VAX
-------------

' $INCLUDE: 'api.inc'
LINE INPUT "Enter vax filename"; f$
if f$< "!" then end
i% = api.startcommands
j$ = "transmit 'dir " + f$ + CHR$(13) + "'"
i% = api.docommand(j$)
i% = api.docommand("readhost 0:0:5 v2")
i% = api.docommand("readhost 0:0:5 v2")
i% = api.docommand("readhost 0:0:5 v2")
i% = api.docommand("wait 0:0:8 for '^m$'")
varbuf$ = SPACE$(80)
i% = api.getvar( varbuf$, 2, l% )
varbuf$ = MID$( varbuf$, 1, l% )
IF INSTR(varbuf$, "%DIRECT-W-NOFILES") > 0 THEN
     PRINT "File "; x$; "not found on vax"
ELSE
     PRINT "File "; x$; " on VAX"
END IF
i% = api.endcommands
END

TURBO Function Definition
-------------------------

function api_getvar( i :integer; var x: string ) :integer;

i = variable number
x = string variable to return data to

TURBO Pascal example    - find out if a file is present on a VAX
--------------------
uses apiunit;
{$V-}
var    fname    : string[80];
    cm    : string[80];
    i    : integer;
    vlen    : integer;
begin
    write ( 'Enter vax filename' );
    readln( fname );
    if fname < '!' then exit;
    i := api_startcommands;
    cm := 'transmit "dir ' + fname + '^m"';
    i := api_docommand(cm);
    cm := 'readhost 0:0:5 v2';
    i := api_docommand( cm );
    i := api_docommand( cm );
    i := api_docommand( cm );
    cm := 'wait 0:0:8 for "^m$"';
    i := api_docommand( cm );
    i := api_getvar( 2, cm );
    if pos( '%DIRECT-W-NOFILES', cm ) <> 0 then
        writeln ('File ', fname, ' not found on VAX' )
    else
        writeln ('File ', fname, ' on VAX' );
end.

-----------------------------------------------------------------------------
    api_setvar        8
-----------------------------------------------------------------------------
    Purpose:  Load ascii string into Reflection variable.
          Reflection variables are limited in length to
          80 characters.  The default # of variables is
          10 but can be increased via a SET command to 800.

    This command should only be executed as part of a synchronous
    command sequence, otherwise it can return bogus values,
    i.e. it may interrupt Reflection changing one variable
    to another so a false result could occur.

    Variables can not always be null-terminated in this way
    since it is possible for them to contain nulls themselves.

    INPUT:    CX = 8
        AX = DE52H
        DX = 0
        ES:BX points to 80 byte buffer
        SI = variable #
        DI = length of variable
    OUTPUT:
       No error:
        AX =  0
       Error:
        AX = 10AH bad variable no
             106H bad length




Assembler Example:    Set variable V2 to value below
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,8
    mov    si,2
    mov    di,VARLENGTH
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset Variable_Buffer
    int    21h


    mov    byte ptr [variable_length+SI],0
    or    ax,ax            ; was there an error
    jnz    Bad_variable_number    ; yes.


Variable_Buffer db "Enter this string in V2"
VARLENGTH    EQU    $ - Variable_Buffer

C Function Definition:
----------------------

int    api_setvar( var_buffer, varno, varlength );
                returns non-zero if error


char    *var_buffer;
int    varno;            /* variable number 0-799 */
int    varlength;

C Programming Example:
----------------------
see api_getvar example above


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.setvar% CDECL (SEG var$, BYVAL varnumber%)
var$ = string containing data to load into variable
varnumber$ = variable number

BASIC example    - set a command language variable
-------------

' $INCLUDE: 'API.INC'
    a$ = "abc" + chr$(0) + "def" ' a$ contains a null
    i%=api.setvar(a$, 3 )     ' set V3 to a variable which contains a null

TURBO Function Definition
-------------------------

function api_setvar( i :integer; var x: string ) :integer;
i = variable number
x = string data to load into Reflection variable

TURBO Pascal example    - set a command language variable
--------------------
{$V-}
uses apiunit;
var    cmdvar    : string[80];
    retvar    : string[80];
    i    : integer;
begin
    cmdvar := 'Load this string in V3';
    i := api_setvar( 3, cmdvar );
    i := api_getvar( 3, retvar );
    writeln ( retvar );
end.



-----------------------------------------------------------------------------
    api_found        9
-----------------------------------------------------------------------------
    Purpose: Return the value of the command language FOUND boolean.

    INPUT:    CX = 9
        AX = DE52H
        DX = 0

    OUTPUT:
        AX = value of FOUND boolean
        AX =  0     Not found
        AX <> 0     Found


Assembler Example:
------------------

    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,9
    int    21h            ; call API
    or    ax,ax
    jz    String_Not_Found

C Function Definition:
----------------------
int api_found();        Returns value of FOUND boolean

C Programming Example:
----------------------

main()
{
      /* return the state of the found boolean */

      api_open();
      api_startcommands();
      api_docommand("transmit  'john^m'");         /* send username */
      api_docommand("wait 0:0:8 for 'Password:'"); /* wait 8 sec for password */
      if (!api_found()) {
          printf("Timed out waiting for password\n");
          printf("Try again ?:");
      }
      api_endcommands();
      api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.found% CDECL ()

BASIC example    - print a message if successful connect to remote modem
-------------
' $INCLUDE: 'api.inc'
i% = api.startcommands
i% = api.docommand("transmit 'ATDT 555-1212^m'")
i% = api.docommand("WAIT 0:0:45 for 'CONNECT'")
if api.found then print "Connected to REMOTE MODEM"
i% = api.endcommands
end

TURBO Function Definition
-------------------------

function api_Found :integer;

TURBO Pascal example    - print a message if successful connect to remote modem
--------------------
{$V-}
uses    apiunit;
var    cm    : string[80];
    i    : integer;
begin
    i  := api_startcommands;
    cm := 'transmit "ATDT 555-1212^m"';
    i  := api_docommand( cm );
    cm := 'WAIT 0:0:30 for "CONNECT"';
    i  := api_docommand( cm );
    if api_found <> 0 then
        writeln ( 'Connected to REMOTE MODEM' )
    else
        writeln ( 'No connection' );
    i  := api_endcommands;
end.

-----------------------------------------------------------------------------
    api_endcommands     10
-----------------------------------------------------------------------------
    Purpose: Stop series of synchronous commands.  Turn datacomm
         back on. Should not return an error


    INPUT:    CX = 10
        AX = DE52H
        DX = 0

    OUTPUT:
       No error:
        AX =  0
       Error:
        AX = error code
        Should not return error

Assembler Example:
------------------

    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,10
    int    21h
    or    ax,ax
    jnz    Serious_error


C Function Definition:
----------------------

int api_endcommands();

C Programming Example:
----------------------

    see    api_startcommands

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.endcommands% CDECL ()

BASIC example
-------------

    see    api_startcommands

TURBO Function Definition
-------------------------

function api_EndCommands :integer;

TURBO Pascal example
--------------------

    see    api_startcommands

-----------------------------------------------------------------------------
    api_screenread        11
-----------------------------------------------------------------------------

    Purpose: Read text from the Reflection screen in background.

    Screen reads do not extend to function key area.  Returns
    an error if the screen is in graphics mode.


    INPUT:    CX = 11
        AX = DE52H
        DX = 0
        BH = ROW    0 relative
        BL = COL    0 relative
        ES:DI        points to buffer to contain screen text
        SI = number of bytes to read

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = 106H asked for read off of screen
             103H Screen in graphics mode


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    bh,[start_row]
    mov    bl,[start_column]
    mov    si,[bytes_to_read]
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    di,offset screen_buffer
    mov    cx,11
    int    21h
    or    ax,ax
    jnz    screen_read_error

C Function Definition:
----------------------
int    api_screenread( buffer, row, col, length );
            returns non-zero if error
char    *buffer;
int    row;
int    col;
int    length;

C Programming Example:
----------------------
main()
{

    /* read a string off of the screen */

    char    screen_buffer[30];
    api_open();
    api_startcommands();

    /*    Home cursor, clear screen go down 4 and right 6   */
    /*    NOTE - THESE ARE HP ESCAPE SEQUENCES - !!!!!! */

    api_docommand("display '^[H^[J^[B^[B^[B^[B^[C^[C^[C^[C^[C^[C'");

    /*    display sample text */

    api_docommand("display 'line at row 4 column 6'");

    /*    read 22 bytes off of screen at row 4 column 6  */

    api_screenread(screen_buffer, 4, 6, 22 );

    screen_buffer[22]='\0';
    if (strcmp(screen_buffer,"line at row 4 column 6"))
        printf("returned string doesn't compare\n");
    else
        printf("Found [%s]\n",screen_buffer);
    api_endcommands();
    api_close();
}


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.screenread% CDECL (SEG scrbuffer$, BYVAL row%,
         BYVAL col%, BYVAL rvarlen%)

scrbuffer$ =  buffer to receive screen data - scrbuffer$  must be first
          initialized to size sufficient to contain data
row% = row to start read
col% = column to start read
rvarlen% = number of bytes to read

BASIC example    - print Reflection screen (characters only - no color)
-------------
' Print the Reflection screen.
' $INCLUDE: 'api.inc'
scbuf$ = space$(80*24)
i% = api.screenread( scbuf$, 0%, 0%, 80%*24% )
cls
print scbuf$
end

TURBO Function Definition
-------------------------

function api_ScreenRead( length ,column, row:integer; var x: buffer ) :integer;
length = number of bytes to read
column = column to start read
row    = row to start read
x      = buffer to receive data - see apiunit.pas for declaration

TURBO Pascal example    - read and print 80 columns from Reflection screen
--------------------
{$V-}
uses  apiunit;
var    scrbuf    : buffer ;
    j, row, col, k, i  : integer;
    scrtext        : string[255];
begin
     write( 'enter row and column to start screen read :');
     readln( row, col );
     j := 80;
     if api_screenread( j, col, row , scrbuf ) <> 0 then exit;
     k := 1;
     scrtext[0] := chr(j);
     while k <= j do
       begin
        scrtext[k] := scrbuf[k-1];
        k := k+1;
       end;
     writeln( scrtext );
end.


-----------------------------------------------------------------------------
    api_keystatus        12
-----------------------------------------------------------------------------
    Purpose: Returns amount of free space left in keyboard queue
         in keys.  Each key actually takes two bytes of space in
         the queue.

    INPUT:    CX = 12
        AX = DE52H
        DX = 0

    OUTPUT:
       AX = amount of free space in units of keys

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,12
    int    21h
    or    ax,ax
    jz    No_free_space_remaining


C Function Definition:
----------------------

int    api_keystatus();    returns free space in key units



C Programming Example:
----------------------

main()
{
    if (!api_keystatus)
        printf( "API Key buffer full\n");

}
BASIC Function Definition
-------------------------

DECLARE FUNCTION api.keystatus% CDECL ()

BASIC example    - see if any room left to queue keys
-------------
' $INCLUDE: 'api.inc'
if api.keystatus = 0 then print "API key buffer full"


TURBO Function Definition
-------------------------

function api_KeyStatus :integer;


TURBO Pascal example
--------------------
uses    apiunit;
var    i : integer;
begin
    if api_keystatus <> 0 then
        writeln( 'key buffer full');
end.

-----------------------------------------------------------------------------
    api_qkeys           13
-----------------------------------------------------------------------------
    Purpose: Queue Reflection keystrokes.  This function call queues
         keys and returns immediately to the caller.  Since
         this is an asynchronous (queued) call, the caller will
         not know when the keys are sent.  The keys are entered
         into Reflection's keyboard buffer exactly as though
         they had been typed, except no remapping takes place.

    There are two kinds of keys on your keyboard, those which
    cause standard ascii characters to be transmitted and those
    which perform control functions like resetting an internal modem,
    bringing up a configuration screen, or switching sets of
    softkeys.  The api_qkeys function differentiates between
    these sets of keys.  Keys which cause ascii values to be
    transmitted or entered are passed by enclosing the string
    of keys in quotes - either single or double.

        "read mail"
        "don't exit"
        'he said "wait for me!" '

    C uses quotes to delimit strings, but the quotes are not
    part of the string.  For this reason, you may have to use
    single quotes within C string constants such as:

        char    *keyentry = "'find employee miller'"

    Control keys such as RETURN and VT-ENTER are keywords
    and must be passed to the api function unquoted.  These
    keyword definitions are the same as those used in Reflection's
    keyboard mapping utility (Keymap or Keycomp).  Here's an
    example of entering a string of keys followed by a carriage return:

        api_qkeys( "'MyPassword'  RETURN ");

    Notice that the password (MyPassword) is a quoted string, but
    the keyword RETURN is not quoted.  The keynames are documented
    in the Reflection Technical Reference manual in the keyboard remapping
    section.

    INPUT:    CX = 13
        AX = DE52H
        DX = 0

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = 104H Queue full
        AX = 105H Bad Key


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    mov    bx,offset key_buffer
    mov    cx,13
    int    21h
    or    ax,ax
    jnz    key_queue_error


key_buffer    db     "'Hello user.acct' return",0


C Function Definition:
----------------------

int    api_qkeys( keybuffer );     returns non-zero if error
char    *keybuffer;


C Programming Example:
----------------------

main()
{

    /* Queue some keys if there is room in the key queue */

char    *keybuffer = "'Hello user.acct' return";

    api_open();
    if ( strlen( keybuffer ) <= api_keystatus())
        api_qkeys( keybuffer );
    else
        printf("No room in Reflection Key Queue.\n");
    while(!api_block())
        if (kbhit())
            break;
    /* don't call api_close     since it will clear the queue */
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.qkeys% CDECL (SEG keys$)
key$ = string containing keystrokes to queue

BASIC example    - queue keys to log on to an HP3000
-------------
' $INCLUDE: 'api.inc'
i% = api.qkeys( "'hello user.acct' return")

TURBO Function Definition
-------------------------

function api_QKeys( var keys: string ) :integer;

keys = string containing keystrokes

TURBO Pascal example
--------------------
{$V-}
uses    apiunit;
var    keys    : string[80];
    i    : integer;
begin
    keys := '"hello user.acct" return';
    i := api_qkeys( keys );
end.

-----------------------------------------------------------------------------
    api_clrkeybd           14
-----------------------------------------------------------------------------
    Purpose: Clear any remaining unprocessed keys out of the keyboard
         buffer.


    INPUT:    CX = 14
        AX = DE52H
        DX = 0

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = error code

       Should not return an error.

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,14
    int    21h


C Function Definition:
----------------------

int    api_clrkeybd ();


C Programming Example:
----------------------

api_clrkeybd ();

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.clrkeybd% CDECL ()

BASIC example    - clear the keyboard buffer
-------------
' $INCLUDE: 'API.INC'
i% = api.clrkeybd


TURBO Function Definition
-------------------------

function api_ClrKeybd :integer;

TURBO Pascal example
--------------------
uses    apiunit;
var    i : integer;
begin
    i := api_clrkeybd
end.

-----------------------------------------------------------------------------
    api_cmdstatus        15
-----------------------------------------------------------------------------
    Purpose: Returns amount of free space available in command queue
         buffer.

    INPUT:    CX = 15
        AX = DE52H
        DX = 0

    OUTPUT:
        AX = amount of free space  in bytes

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,15
    int    21h
    or    ax,ax
    jz    No_free_space

C Function Definition:
----------------------

int    api_cmdstatus();    returns free space in command queue




C Programming Example:
----------------------

main()
{
    /* Queue a command if there is room in the buffer */

    char    *send_command = "SEND ABC TO XYZ ASCII DELETE";
    api_open();
    if (api_cmdstatus() >= strlen( send_command ) ) {
        api_qcmd( send_command );
        printf("Command Queued\n");
    }
    else
        printf("Queue full\n");
    /* no api_close     here - allow command to be processed */
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.cmdstatus% CDECL ()

BASIC example    - Queue a command if there is room in the buffer
-------------

' $INCLUDE: 'api.inc'

    cm$= "SEND ABC TO XYZ ASCII DELETE";
    i%=api.open
    if (api.cmdstatus > len(cm$)) then     ' if there is room then
        api.qcmd( cm$ )            ' queue the command
        print "Command Queued"
    else
        print "Queue full"
    end if

TURBO Function Definition
-------------------------

function api_CmdStatus :integer;

TURBO Pascal example
--------------------
uses    apiunit;
var    i : integer;
begin
    i := api_cmdstatus;
    writeln ( 'bytes free in command buffer = ', i );
end.

-----------------------------------------------------------------------------
    api_qcmd        16
-----------------------------------------------------------------------------
    Purpose: Queue a new command in the command queue.  This call
         returns immediately to the caller and the command is
         processed asynchronously via background multitasking.

    INPUT:    CX = 16
        AX = DE52H
        DX = 0
        ES:BX point to null-terminated command

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = 104H Queue full
           = 106H Bad Length

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,16
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset command_string
    int    21h
    or    ax,ax
    jnz    Command_Queue_error


Command_string    db    "Send ABC to XYZ ASCII DELETE",0


C Function Definition:
----------------------

int    api_qcmd( command_string );        returns error-code
char    *command_string;


C Programming Example:
----------------------
See api_cmdstatus example


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.qcmd% CDECL (SEG rcommand$)

BASIC example    -  Queue a command - report if there was an error
-------------

' $INCLUDE: 'API.INC'

cm$ = "SEND ABC TO DEF ASCII REC = 256"
if api.qcmd( cm$ ) then print "Error queuing command"

TURBO Function Definition
-------------------------

function api_QCmd( var cmd : string ) :integer;
cmd = string containing command

TURBO Pascal example    -  Queue a command - report if there was an error
--------------------
uses    apiunit;
var    cm : string[80];
    i  : integer;
begin
    cm := 'SEND ABC TO DEF ASCII REC = 256';
    if api_qcmd( cm ) <> 0 then
        writeln( 'error occurred while queuing command');
end.

-----------------------------------------------------------------------------
    api_clrcmdq          17
-----------------------------------------------------------------------------
    Purpose: Clear the command queue

    INPUT:    CX = 17
        AX = DE52H
        DX = 0

    OUTPUT:
       AX = 0
       Should not encounter an error


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,17
    int    21h

C Function Definition:
----------------------

int api_clrcmdq();


C Programming Example:
----------------------

    api_clrcmdq();

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.clrcmdq% CDECL ()

BASIC example    - clear the command queue
-------------
' $INCLUDE: 'API.INC'

i% = api.clrcmdq

TURBO Function Definition
-------------------------

function api_ClrCmdQ :integer;

TURBO Pascal example    - clear the command queue
--------------------
uses    apiunit;
var    i : integer;
begin
    i := api_clrcmdq;
end.

-----------------------------------------------------------------------------
    api_releasedc        18
-----------------------------------------------------------------------------
    Purpose: Stop stealing datacomm hardware away from foreground
         process. Normally if Reflection is running a command
         file or processing a command, it will steal the
         datacomm hardware (COM1, COM2, etc.) away from a
         foreground process that may have grabbed it.
         This call allows a foreground task to initialize
         the datacomm hardware and do direct datacomm I/O
         without interference from Reflection in background.
         Reflection will not be able to do datacomm.

       This call will not restore datacomm to the foreground program
       if it has already been taken away.  The foreground program will
       have to re-initialize the datacomm hardware.  ReleaseDC should
       only be required when the hardware serial ports are being used
       by both Reflection and a foreground program.

    INPUT:    CX = 18
        AX = DE52H
        DX = 0

    OUTPUT:
        Should not return an error



Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,18
    int    21h

C Function Definition:
----------------------
int    api_releasedc();


C Programming Example:
----------------------

    api_releasedc();

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.releasedc% CDECL ()

BASIC example    - release datacomm
-------------
' $INCLUDE: 'API.INC'
i% = api.releasedc

TURBO Function Definition
-------------------------

function api_ReleaseDC :integer;

TURBO Pascal example
--------------------
....
i := api_releasedc
....

-----------------------------------------------------------------------------
    api_assertdc        19
-----------------------------------------------------------------------------
    Purpose: Tells Reflection to re-grab the serial hardware
         away from a foreground task that may have taken it.
         Reflection re-initializes datacomm back to its
         normal baud rate, parity, etc.   Reflection will
         continually re-grab the hardware from another program
         if necessary.

    INPUT:    CX = 19
        AX = DE52H
        DX = 0

    OUTPUT:
       Should not return an error.


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,19
    int    21h

BASIC, C, Pascal examples
----------------------

Note:    See ReleaseDC()


-----------------------------------------------------------------------------
    api_popup        20
-----------------------------------------------------------------------------
    Purpose: Pop Reflection into the foreground.  API client
         application will be frozen until user hits hot-key
         or a queued "BACKGROUND" command is processed.

    INPUT:    CX = 20
        AX = DE52H
        DX = 0


    OUTPUT:
       Should not return an error

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,20
    int    21h    ; This call freezes API Client program

C Function Definition:
----------------------
int    api_popup();



C Programming Example:
----------------------

    api_popup();
    printf("Back from POP COMMAND\n");

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.popup% CDECL ()

BASIC example    - pop up Reflection
-------------
' $INCLUDE: 'API.INC'
i% = api.popup
print "BACK from Reflection"

TURBO Function Definition
-------------------------

function api_PopUP :integer;

TURBO Pascal example    - pop up Reflection;
--------------------
uses    apiunit;
var    i : integer;
begin
    i := api_popup;
end.
-----------------------------------------------------------------------------
    api_reset        21
-----------------------------------------------------------------------------
    Purpose: Sends Reflection a hard reset.  Check the technical
         reference manual for the description of the hard
         reset process.  In addition, api_reset performs
         api_flushcmd(), api_clrkeybd (), and api_endcommands().
         To prevent the host from performing a hard-reset,
         issue the command "SET EXITS-DISABLED YES"

    INPUT:    CX = 21
        AX = DE52H
        DX = 0

    OUTPUT:
       Should not return an error

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,21
    int    21h


C Function Definition:
----------------------

int    api_reset();

C Programming Example:
----------------------

    api_reset();

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.reset% CDECL ()

BASIC example    - Hard reset Reflection
-------------
' $INCLUDE: 'API.INC'

i% = api.reset

TURBO Function Definition
-------------------------

function api_Reset :integer;

TURBO Pascal example    - Hard reset Reflection
--------------------
uses    apiunit;
var    i : integer;
begin
    i := api_reset;
end.

-----------------------------------------------------------------------------
    api_getfkey        22
-----------------------------------------------------------------------------
    Purpose: Return the current setting of a Reflection softkey
         to calling program.   This function returns value of
         R2 and R4 softkeys,  R2 and R4 user-defined keys (UDKs)
         and R1 and R7 HP userkeys.

    INPUT:    CX = 22
        AX = DE52H
        DX = 0
        ES:BX point to buffer to return key.
        SI = Key number (1 relative)
             To return R2/R4 user-defined keys    (UDKs)
            UDK # 6  = keynumber 17
            ...       ...
            UDK # 20 = keynumber 34

    OUTPUT:
       No error
       AX = 0
        key record copied to buffer

       Error:
        AX = 105H Badkey


HP Userkey label structure    R1/R7

struct    ukey    {
    char    unsigned   ukey_attr;   /* 0=normal, 1=local only, 2=transmit only*/
    char    unsigned   ukey_lablen; /* length of the label  */
    char    unsigned   ukey_deflen; /* length of the definition string */
    int            ukey_reserved;
    char        ukey_text[160]; /*label string followed by definition*/
}

DEC Softkey structure      R2/R4

struct softkey    {
    char    unsigned   action;    /* 0 = normal, 1 = local only */
    char    unsigned   label_length;
    char    label_text[8];
    char    unsigned   defn_length;
    char    defn_text[80];
}


DEC UDK structure   R2 / R4

struct udk {
    char    unsigned    udk_length;
    char            udk_text[255];
}

Assembler Example:            ; Get HP softkey # 3
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    mov    si,3            ; User key # 3
    assume    es:data
    mov    bx,offset ukey_buffer    ; where to put the ukey info
    mov    cx,22            ; get user key
    int    21h
    or    ax,ax            ; Error?
    jnz    getkey_error        ;  YES


key_buffer label byte
ukey_attr    db    ?    ; 0 = normal, 1 = local, 2 = transmit only
ukey_lablen    db    ?    ; length of label text
ukey_deflen    db    ?    ; length of definition string
reserved    dw    ?
ukey_text    db    160 dup (0)    ; label text and definition start



C Function Definition:
----------------------
int    api_getfkey( key_buffer, keynumber );
struct    ukey   *key_buffer;
int    keynumber;

C Programming Example:
----------------------
main()

    /* Retrieve a function key and print the label */


{
struct    ukey   key_buffer;

int    i;
int    keynumber=3;
struct    ukey  *kptr;
    kptr = &key_buffer;
    api_open();
    api_getfkey( kptr, keynumber );
    i = kptr->ukey_lablen;
    kptr->ukey_text[i]='\0';    /* null-terminate after label */
    printf("key %d label '%s'\n", keynumber, kptr->ukey_text );
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.getfkey% CDECL (SEG keybuff AS ukeytype, BYVAL keyno%)

BASIC example    - Print the definition part of HP function key #3
-------------

' $INCLUDE: 'api.inc'

COMMON x AS ukeytype
    i% = api.getfkey(x, 3)
    y$ = x.ukeytext
    PRINT MID$(y$, ASC(x.ukeylablen) + 1)
    END

TURBO Function Definition
-------------------------

function api_GetFkey( k : integer; var fkey: ukeytype ) :integer;

k = function key number
fkey = user key record - see apiunit.pas for declaration

TURBO Pascal example - Print the definition part of HP function key #3
--------------------
uses    apiunit;
var    x : ukeytype;            (* function key record *)
    i : integer;
    n : integer;            (* label length *)
    keydefn  : string[80];
begin
    i := api_getfkey( 3, x );
    n := ord( x.ukeylablen );
    i := 0;
    keydefn[0] := x.ukeydeflen;    (* definition length *)
    while i < ord( x.ukeydeflen ) do
        begin
         keydefn[i+1] := x.ukeytext[n + i ];
         i := i + 1;
        end;
    writeln ( 'definition of function key 3 = ',keydefn );
end.




-----------------------------------------------------------------------------
    api_setfkey        23
-----------------------------------------------------------------------------
    Purpose: Directly set an R1/R7 HP userkey or an R2/R4 softkey.
         DEC UDK's may only be set via the display command
         displaying the appropriate escape sequence.

    INPUT:    CX = 23
        AX = DE52H
        DX = 0
        ES:BX point to    ukey/softkey structure
        SI = key number

    OUTPUT:
       No error:
        AX =  0
       Error:
        AX = 105H bad key


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    assume    es:data
    mov    bx,offset key_structure
    mov    si,3            ; set user key 3
    mov    cx,23
    int    21h
    or    ax,ax
    jnz    key_error


key_structure label byte
ukey_attr    db    0    ; normal (as if typed at keyboard)
ukey_lablen    db    16    ; length of label text    (2 rows )
ukey_deflen    db    23    ; length of definition string
reserved    dw    ?
ukey_text    db    '  LOGON ','   HP   ','HELLO George,mgr.sales',0dh



C Function Definition:
----------------------
int api_setfkey( key_buffer, keynumber);
struct    ukey   *key_buffer;
int    keynumber;


C Programming Example:
----------------------
main()
{

    /* change function key 3 to LOCAL */

    int    keynumber = 3;
    struct    ukey  key_buffer;
    struct    ukey  *sptr;
    sptr = &key_buffer;
    api_open();
    api_getfkey( sptr, keynumber );
    sptr->ukey_attr = 1;          /* 1 = local */
    api_setfkey( sptr, keynumber );
    printf("Userkey 3 set to LOCAL  [L]  \n");
    api_close();
}

BASIC Function Definition
-------------------------

see api_getfkey

BASIC example
-------------

see api_getfkey

TURBO Function Definition
-------------------------

see api_getfkey

TURBO Pascal example
--------------------

see api_getfkey

-----------------------------------------------------------------------------
    api_offerbuf         24
-----------------------------------------------------------------------------
    Purpose: To provide larger buffers for command or keyboard queues
         than the default API buffers.    Default buffer size is
         approximately 190 bytes for the command buffer and 32 keys
         for the keyboard buffer.

    Make sure that the current queue is empty before offering
    a new buffer, otherwise any queued keys or commands will be lost.
    Each offer cancels the previous one.  Do not modify the offered
    buffer space until it has been canceled (see below).  Note that the
    pointer passed to API is a far pointer (32 bit address)!

    INPUT:    CX = 24
        AX = DE52H
        DX = 0
        ES:BX points to buffer
        SI    size of buffer
        DI    buffer type
            0 = keyboard buffer
            1 = command queue buffer

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = 103H  Bad buffer type

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset command_buffer
    mov    di,1            ; 1 <==> buffer for command queue
    mov    si,CBUFFER_LEN        ; length of buffer
    mov    cx,24
    int    21h

command_buffer    db    2000 dup (0)
CBUFFER_LEN    EQU    $ - command_buffer



C Function Definition:
----------------------

int api_offerbuf( command_queue, bufsize, type );
char far *command_queue;
int    bufsize;
int    type;


C Programming Example:            Offer a 2000 byte command buffer
----------------------

#define BUFSIZE  2000
#define COMMAND_TYPE    1
char far command_queue[BUFSIZE];

api_offerbuf(command_queue, BUFSIZE, COMMAND_TYPE );


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.offerbuf% CDECL (SEG buffer AS bufftype, BYVAL rvarlen%,
         BYVAL typ%)

buffer = buffer to be used for queuing keys or commands - see api.inc for
     user-defined type definition.
rvarlen% = size of buffer

BASIC example    - Setup 512 byte command buffer within BASIC's data
-------------      segment and queue some commands.

' $include: 'api.inc'

COMMON cmdbuf as bufftype    ' see api.inc for bufftype declaration
i% = api.offerbuf( cmdbuf, 512, 1% )
i% = api.qcmd("dir *.*")
i% = api.qcmd("display '^g'")
i% = api.qcmd("wait 0:0:10")
i% = api.wait
i% = api.cancelbuf
end

TURBO Function Definition
-------------------------

function api_OfferBuf(typ,buflen:integer;var x : buffer):integer;
type = 0 or 1    for keys or commands
buflen = size of buffer
x = buffer see apiunit.pas for declaration

TURBO Pascal example    - Offer a Keyboard Queue buffer from Pascal's
--------------------      data space.
{$V-}
uses  apiunit, crt;
const     maxlength = 256;
var    keys  : string[250];
    i     : integer;
    keybuf     : buffer;
begin
     i := api_offerbuf( 0, 256, keybuf );
     keys := '"enter these keys and hit return" return ';
     i := api_qkeys( keys );
     repeat
     until keypressed or (api_block = 0);
     i := api_cancelbuf;    (* cancel buffer before terminating program *)
end.

-----------------------------------------------------------------------------
    api_cancelbufs        25
-----------------------------------------------------------------------------
    Purpose: Reflection will return to use of default keyboard
         and command buffers.  Original buffer is
         reclaimed by API client program.  Issue this
         call prior to terminating.

    INPUT:    CX = 25
        AX = DE52H
        DX = 0

    OUTPUT:
       Should not return an error


Assembler Example:
------------------

    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,25
    int    21h



C Function Definition:
----------------------

int    api_cancelbuf();

C Programming Example:
----------------------

api_cancelbuf();

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.cancelbuf% CDECL ()

BASIC example
-------------

see api.offerbuf

TURBO Function Definition
-------------------------

function api_CancelBuf :integer;

TURBO Pascal example
--------------------

see api_offerbuf

-----------------------------------------------------------------------------
    api_wait        26
-----------------------------------------------------------------------------
    Purpose: Wait for Reflection to empty command and/or keyboard
         queues.  Does not return until Reflection is idle.
         When a series of commands are queued, but the API
         client program can not continue until the commands
         have been completed, this call could be used.
         Handle with care.  Keyboard lock could cause system
         hang.

    INPUT:    CX = 26
        AX = DE52H
        DX = 0

    OUTPUT:
       Should not return an error.


Assembler Example:
------------------

    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,26
    int    21h


C Function Definition:
----------------------

int    api_wait();

C Programming Example:
----------------------

main()
{

    /* Queue commands and WAIT till complete */

    api_open();
    api_qcmd("wait 0:0:5");
    api_qcmd("display '^g'");
    api_wait();
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.wait% CDECL ()

BASIC example    -  Queue commands and WAIT until complete
-------------

' $INCLUDE: 'api.inc'
i% = api.qcmd("WAIT 0:0:5")
i% = api.qcmd("display '^g'")
i% = api.wait

TURBO Function Definition
-------------------------

function api_Wait :integer;

TURBO Pascal example
--------------------
uses apiunit;
var i : integer;
var cm : string[80];
begin
    cm := 'SEND ABC TO XYZ';
    i  := api_qcmd( cm );
    i  := api_wait        (* wait until command completed       *)
end.                (* note: may cause program to hang if *)
                (* command can't complete             *)

-----------------------------------------------------------------------------
    api_block        27
-----------------------------------------------------------------------------
    Purpose: Give Reflection some CPU time.  This should be
         done if the API client program is waiting for
         Reflection to complete some queued commands or
         keystrokes but wants to maintain CPU control
         (api_block returns quickly).

    INPUT:    CX = 27
        AX = DE52H
        DX = 0

    OUTPUT:
       AX  = 0   implies Reflection idle.  Command or key
             queues have been completed.

       AX <> 0   implies Reflection is busy processing
             commands or queued keys.


Assembler Example:            Give Reflection CPU time while
------------------            waiting for user input.


Idle_Loop:
    mov    ah,1            ; Check keyboard status
    int    16h            ; BIOS keyboard interrupt
    jnz    Key_waiting        ; Exit if user has typed key
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,27            ; Do api_block
    int    21h
    or    ax,ax            ; Is Reflection finished?
    jnz    idle_loop        ; No.  See if keyboard input



C Function Definition:
----------------------
int    api_block();


C Programming Example:
----------------------
main()
{
    /* queue two commands and block until complete */

    api_open();
    api_qcmd("wait 0:0:3");
    api_qcmd("display '^g'");
    while (api_block())
        if (kbhit())    /* If key has been pressed */
            break;    /* stop waiting */
    api_close();
}


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.block% CDECL ()

BASIC example    - Give Reflection CPU time until file transfer completes
-------------      or user hits a key.

' $INCLUDE: 'api.inc'
i% = api.qcmd("send bigfile to xyz")
DO
LOOP WHILE  inkey$="" and api.block <> 0

TURBO Function Definition
-------------------------

function api_Block :integer;

TURBO Pascal example
--------------------

see    api_offerbuf example

-----------------------------------------------------------------------------
    api_atrbscreen          31
-----------------------------------------------------------------------------
    Purpose: Read text and color attributes from Reflection's
         background screen. Read can extend to function key display.
         Color attributes are IBM PC attribute bytes.  Client
         program may read Reflection screen and re-display with
         same color attributes.

    INPUT:    CX = 31
        AX = DE52H
        DX = 0
        BH = ROW    0 relative
        BL = COL    0 relative
        ES:DI        points to buffer to contain screen text
        SI = number of characters to read.  Note that each
             character is 2 bytes with this function.  For each
             character, the first byte is the character from
             the IBM character set and the second byte is
             the attribute which determines how the byte is
             displayed.

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX = 103H  read extends off of screen


Assembler Example:
------------------
    See example for api_screenread

C Function Definition:
----------------------
    See api_screenread

C Programming Example:
----------------------
    See example for api_screenread


BASIC Function Definition
-------------------------
    See api_screenread


BASIC example    - Read the Reflection screen and print characters with correct
-------------      color attributes.

' $INCLUDE: 'api.inc'
' Allocate space for reading 80 columns by 25 rows by two bytes per char.
x$ = SPACE$(80 * 25 * 2)
'
' Ask for 80*25 characters starting at row 0, column 0
'
i% = api.atrbscreen%(x$, 0, 0, 80 * 25)
'
' Make default segment the segment of the video display (use B000 for mono)
'
DEF SEG = &HB800
FOR i = 1 TO 80 * 25 * 2
POKE i-1, ASC(MID$(x$, i, 1))
NEXT i
END


TURBO Function Definition
-------------------------

function api_AtrbScreen(length,col,row:integer;var x:buffer):integer;

see api_screenread above

TURBO Pascal example   - Read 100 characters off of screen and put ascii
--------------------     bytes only into string variable.  Read starting
             row 10 column 1.

program ReadScrnAttr (input,output);
{$V-}
uses  apiunit;
var
    scrn    : buffer;
    row    : integer;
    col    : integer;
    i     : integer;
    scrtext  : string[100];
begin
     row := 10;
     col := 1;
     i     := api_atrbscreen (100, col, row, scrn );
     i     := 0;
     while i < 100 do
         begin
          scrtext[i+1] := scrn[ i*2 ];
          i := i+1;
         end;
     scrtext[0] := chr(100);
     writeln( scrtext );
end.




-----------------------------------------------------------------------------
    api_searchscreen    32
-----------------------------------------------------------------------------
    Purpose: Search the Reflection screen for a string.  If found,
         return row and column location


    INPUT:    CX =    32
        AX = DE52H
        DX = 0
        BH =    Column    (0 relative) where to start search
        BL =    Row    (0 relative)
        ES:DI = buffer containing null-terminated string
            to search for
    Output:
        No Error:
        AX = 0    found string
        BH =    Column    (0 relative)
        BL =    Row    (0 relative)
        Error:
        AX <> 0 String not found



Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bl,[row]
    mov    bh,[column]
    mov    di,offset search_string ; string to search for
    mov    cx,32
    int    21h
    or    ax,ax
    jnz    string_not_found
    mov    [row],bl        ; store location where found
    mov    [column],bh

column        db    20
row        db    2
search_string    db    "Enter Password:"

C Function Definition:
----------------------

int    api_searchscreen( search_string, row, col );
                returns NZ if not found
int    &row;
int    &col;
char    *search_string;

C Programming Example:    - Search screen for field. If found, print contents
----------------------
main()
{

    /* Search screen for a prompt */

    int    row, col;
    char    *string = "Employee Name:";
    char    employee[30];
    col = 0;
    row = 0;
    api_open();
    if (api_searchscreen( string, &row, &col ))
        printf("Can't find employee field\n");
    else    {
        col = col + 15;    /* skip 'Employee Name:' */
        api_screenread( employee, row, col, 30 );
        employee[30] = '\0';
        printf("Employee (%s)\n",employee);
    }
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.searchscreen% CDECL (SEG srchstrng$, SEG row%, SEG col%)
srchstrng$ = string being searched for
row% = row where search is to begin -
col% = column where search is to begin
if found, row% and col% are set to the location of string

BASIC example  - Search screen for field. If found, print contents
-------------
' $INCLUDE: 'api.inc'
srchtext$ = "Employee Name:"
namevar$ = SPACE$(40)        ' allow 40 spaces for name variable
column% = 0
row% = 0
IF api.searchscreen(srchtext$, row%, column%) <> 0 THEN
    PRINT "Can't find employee field"
ELSE
    PRINT "found", row%, column%
    column% = column% + 15
    i = api.screenread(namevar$, row%, column%, 40)
    PRINT "Employee name : "; namevar$
END IF
END

TURBO Function Definition
-------------------------

function api_SearchScreen(var col, row :integer;var x:string ):integer;
col = starting column
row = starting row
x = string to search for.
if string is found, col and row contain string position on screen

TURBO Pascal example  - Search screen for field. If found, print contents
--------------------
{$V-}
uses  apiunit;
var    searchtxt    : string[30];
    row    : integer;
    col    : integer;
    i    : integer;
    namvar    : string[40];
    scrtext : buffer;
begin
     row := 0;
     col := 0;
     searchtxt := 'Employee Name:';
     if api_searchscreen(col, row, searchtxt) <> 0 then
        writeln( 'employee field not found')
     else
     begin
          col := col + 15;
          i := api_screenread( 40, col, row, scrtext);
          i := 0;
          repeat
            namvar[i+1] := scrtext[i];
            i := i + 1;
          until i = 40;
          namvar[0] := chr(40);
          writeln( 'Employee name : ', namvar );
     end;
end.

-----------------------------------------------------------------------------
    api_rdchar          33
-----------------------------------------------------------------------------
    Purpose: Directly read async datacomm from Reflection's receive
         buffer.  Reflection will not read the characters.
         api_startcommands() must be invoked first to
         stop Reflection from reading its incoming datacomm.

      It is the API client program's responsibility to keep up with
      the incoming data.  Make sure that the appropriate flow control
      is set.  Recommend SET RECEIVE-PACING XON/XOFF in most cases.
      Character translation takes place from the host character set
      to the PC character set unless SET DISABLE-TRANSLATION YES
      is in force.

    INPUT:    CX = 33
        AX = DE52H
        DX = 0
        ES:BX points to  2 byte buffer for storing character.
        (Null is second byte)

    OUTPUT:
       No error:
        AX =  0  character read
       Error:
        AX <> 0  no characters available


Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    push    ds
    pop    es
    ASSUME    ES:DATA
    mov    bx,offset receive_buf
    mov    cx,33
    int    21h
    or    ax,ax
    jz    received_a_character


receive_buf    db    ?,0


C Function Definition:
----------------------
int    api_rdchar( string )  read character and store in *string
char    *string;         returns NZ if character not available


C Programming Example:
----------------------
main()
{

    /* transmit some characters and read their echo */

    char    one_byte[2];
    char    temp[33];
    int    k;
    api_open();
    if (api_startcommands())   {        /* tell Reflect not to read */
        printf("can't start\n");        /* incoming data */
        exit();
    }
    k=0;
    api_docommand("transmit 'Read echo from these characters^m'");
    while(k < 33 )    {
        if (kbhit())
            break;
        if (!api_rdchar(one_byte))
            temp[k++]=*one_byte;
    }
    temp[k]='\0';
    printf("%s\n",temp);
    api_endcommands();
    api_close();
}


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.rdchar% CDECL (SEG char$)
char$ = must be initialized to a length of 1 prior to call.
    if found, char$ will contain character that has been read.
    and api.rdchar% = 0

BASIC example    - send a character and then read the echo coming back
-------------

' $INCLUDE: 'api.inc'
ch$ = space$(1)
i% = api.startcommands
'
'       send a character - depending on host, will probably be echoed back
'
i% = api.writeasync( asc("a"))
'
'       rdloop waiting for character to come back or user to hit key
'
do
loop while api.rdchar( ch$ ) <>0 and inkey$=""
if ch$ = "a" then print "Successfully transmitted and received character"
i% = api.endcommands
end

TURBO Function Definition
-------------------------

function api_Rdchar(var x:integer) :integer;
x = integer which will contain character after successful read
    (api_rdchar returns 0)

TURBO Pascal example - write a string and read back the echo and print it
--------------------   out.  Requires connection to full duplex host with
               local echo off.
{$V-}
uses  apiunit;
var
    j    : integer;
    k    : integer;
    i     : integer;
    srctext  : string[255];
    destext  : string[255];
    c     : integer;
begin
     srctext := 'send this string';
     destext := '';
     i := api_startcommands;
     k := 0;
     while k < length( srctext ) do
    begin
        if api_xmitstatus > 0  then
            begin
            j := api_writeasync( ord( srctext[k+1] ));
            k := succ(k);
            end;
    end;
     k := 0;
     while k < length( srctext ) do
    if api_Rdchar    (c) = 0  then
       begin
       destext[k+1] := chr(c);
       k := succ(k);
       end;
    destext[0] := chr(k);
    j := api_endcommands;
    writeln( 'received data = ', destext );
end.


-----------------------------------------------------------------------------
    api_writeasync        34
-----------------------------------------------------------------------------
    Purpose: Write a single character to the Reflection transmit
         buffer for transmission to the host.

    INPUT:    CX = 34
        AX = DE52H
        DX = 0
        SI = character

    OUTPUT:
       No error:
        AX =  0

       Error:
        AX <> 0 buffer full

Assembler Example:
------------------
    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,34
    mov    si,'a'
    int    21h
    or    ax,ax
    jnz    buffer_full

C Function Definition:
----------------------

int    api_writeasync( c );        write character c. return NZ
                    if xmit buffer full
int    unsigned    c;

C Programming Example:
----------------------            transmit the contents of the string
main()
{

    /* write a string */

int    c;
char    *xmit_string   = "Send this string";
    api_open();
    while (( c =*xmit_string++)  != '\0' )  {
        while(!api_xmitstatus())
            if (kbhit())
                break;
        api_writeasync( c );
    }
    api_close();
}

BASIC Function Definition
-------------------------

DECLARE FUNCTION api.writeasync% CDECL (BYVAL c%)
c% = is the ordinal value of the character within the ASCII character
     set.  This can be derived via the ASC function.  c% = asc( c$  )


BASIC example
-------------

See    api.rdchar above

TURBO Function Definition
-------------------------

function api_writeasync(c :integer ) :integer;

c = integer containing character to be transmitted

TURBO Pascal example
--------------------
See    api_rdchar above

-----------------------------------------------------------------------------
    api_xmitstatus        35
-----------------------------------------------------------------------------
    Purpose: Return the amount of free space in the transmit buffer.
         Should be used before api_writeasync to prevent
         accidental overrun of the transmit buffer and loss of data.

    INPUT:    CX = 35
        AX = DE52H
        DX = 0

    OUTPUT:
        AX = amount of free space



Assembler Example:
------------------

    mov    ax,0DE52H
    xor    dx,dx
    mov    cx,35
    int    21h
    or    ax,ax            ; is there any free space
    jz    buffer_full        ;  NO

C Function Definition:
----------------------

int    api_xmitstatus();        ; returns # bytes of free space
                    ; in xmit buffer
C Programming Example:
----------------------

see api_writeasync above.


BASIC Function Definition
-------------------------

DECLARE FUNCTION api.xmitstatus% CDECL ()


BASIC example    - send an ASCII file out the datacomm port without
-------------      flow control

' $INCLUDE: 'api.inc'
    open "filename" for input as #1
readloop:
    if eof(1) then goto endit
    line input #1, x$
    for charpos = 1 to len(x$)
    do                 ' delay until transmitter ready
    loop while api.xmitstatus = 0
    i%=api.writeasync( asc( mid$(x$,charpos, 1) ))
    next charpos

    do                    ' delay until transmitter ready
    loop while api.xmitstatus = 0
    i%=api.writeasync( 13% )        ' send a carriage return
    for j% = 1 to 100 : next j%     ' delay after carriage return
    goto readloop
endit:
    close (1)
    end


TURBO Function Definition
-------------------------

function api_Xmitstatus :integer;

TURBO Pascal Example
--------------------

See    api_rdchar above





              An API Primer
      Converting an existing command file to  C
      -----------------------------------------

It is assumed that you are already familiar with Reflection and have
written Reflection command language programs.    If you haven't, that
is probably the best and easiest place to start.

If you have a supply of command files that you have written in the
past, a good way to get started with API is to convert one or more of
these files to an API program.    An example in C is shown.

The api_docommand function is shown since it is the easiest function
to use.

One of the principal differences you'll notice when using the
api_docommand() function is that the IF, ELSE, ENDIF, GOTO, and GOSUB
commands are not supported.  Flow of control must be handled by the
client program.

    A command language IF clause which reads...

        CONTINUE
        SEND "ABC TO XYZ"
        IF ERROR
            DISPLAY "ERROR TRANSFERRING FILE^m^j"
        ENDIF

    would be converted to C as follows

        (CONTINUE is on automatically)

        if (api_docommand( "SEND ABC TO XYZ"))
            printf("Error transferring file\n");

        api_docommand() returns 0 if no error or the
        error code if an error occurred.  This is then
        tested by C and a branch can be taken.

    a QuickBASIC version of the same thing would be

        if api.docommand( "SEND ABC TO XYZ") > 0 then
            print "Error transferring file"


    Another example:  Get  V1 from Reflection, test for a substring


    Command Language Version

        TRANSMIT "LISTF FOO^m"
        READHOST    V1
        READHOST    V1
        WAIT 0:0:8 FOR "^q"
        IF FIND("CIERR",v1) > 0
            DISPLAY "File FOO Not Found on Host^m^j"
        ENDIF

    C Version:
        int    length;
        char    varbuf[81];
        ....
        api_docommand("transmit 'listf foo^m'");
        api_docommand("readhost 0:0:5 v1);
        api_docommand("readhost 0:0:5 v1);
        api_docommand("wait 0:0:8 for '^q'");
        api_getvar( varbuf, 1, &length ); /* get v1 */
        varbuf[length] = '\0';               /* null-terminate */
        if (strstr( varbuf, "CIERR" ))
            printf( "File FOO Not Found on Host\n");
        ....

        *strstr() is the C counterpart of Reflection FIND()




    Handling Special Problems


Keyboard Reads

You will probably want to avoid  api_docommand( "accept v1").  ACCEPT
is the verb which reads input from the keyboard.  Since Reflection is
in background, the user won't be able to type anything (unless you
have queued keys) and your program will hang.

Most likely you'd normally be using the C gets command or some other
variant for reading keyboard input into your C program.

Unfortunately many Microsoft C and Turbo Pascal keyboard reads use
DOS calls like function 3FH (read file handle). This call has a side
effect of preventing Reflection from getting any CPU time until the
user enters the line and hits carriage return.

No multitasking takes place!  This can halt a file transfer and
cause a host or local timeout.    To avoid this problem, you will
need to use different calls to read from the keyboard.    The included
libraries for C and Turbo Pascal each support a keyboard read which
does not freeze Reflection.  BASIC does not use this call and
therefore encounters no problems.

C function available in the C_[X]API.LIB's   X = S,C,M,L

    char    *rgets( s, i )
    char    *s;    /*    buffer for string   */
    int    i;    /*    size of buffer        */

    Be sure to allocate a buffer which is one byte larger than
    its size parameter.  This call uses DOS function 0AH,
    (read string).


Pascal procedure available in APIUNIT.TPU and APIUNIT.PAS

procedure rfreadkeybd( length : integer; var x: string );

    Specify a length which is one less than the
    declared string size.

    Example - prompt for a queued command and then
    call API to queue it.

    program quecmd (input,output);
    {$V-}
    (*  include the API UNIT *)
    uses  apiunit;
    var    command  : string[80];
        i     : integer;
    begin
         write ( 'enter command : ');
         rfreadkeybd ( 79, command );
         while command >= ' ' do
           begin
        i := api_qcmd( command );
        write ( 'enter command : ');
        rfreadkeybd ( 79, command )
           end;
    end.



Timeouts

As previously mentioned, if you are using synchronous calls
(api_docommand) where your program has to wait for the call
to complete,  make sure that you specify a timeout on any
WAIT, HOLD, READHOST, or other command.  Otherwise your
application may hang waiting for a response that may never
arrive.

Conflicting Commands

Reflection is constantly accepting commands from both the host
computer and the user.    From time to time, however, these commands
may conflict with each other.  For instance, the host may lock the
keyboard while the user wants to type data for the next screen.  The
host also has the capability to invoke the Reflection command
facility by prefixing Reflection commands with the escape sequence
"<esc>&oC".  Some host programs use this facility.  Reflection may
then encounter a command file running on the PC which starts and
tries to run a host application which sends commands via the escape
sequence.  Since Reflection can't process two commands at once, the
host commands fail.  The results, however, are usually disastrous since
the host program isn't behaving the same way it was when you ran it
from the keyboard.  api_startcommands turns off host initiated
commands, i.e. if any commands come from the host, they will fail, but
this will certainly abort or seriously affect the host application.
There's no solution to problems of this kind except awareness.  It is
frequently helpful to turn on display functions or display controls
to see what the host is actually doing.  You will then see any host
commands, status requests, etc. that you'll have to program around.

Preventing User Exits

An unguarded API application can be unintentionally sabotaged by the
user. If the user pops up Reflection and hardexits (ALT-X), your
application will have nothing to interface with.  The only way that
your application can detect this is by looking at return codes.  If
AX returns with AH = DEH, this is precisely what has happened.
Reflection has been un-installed.  You'll want to make sure that the
user doesn't even have a chance to screw things up.  You can control
the user as much as you want by issuing the appropriate Reflection
set commands.

     SET HOT-KEY NONE

     Will prevent the user from popping up Reflection

     SET EXITS-DISABLED YES

     Will prevent the user from exiting via ALT-X or
     interfering by pressing hard-reset

     SET DISABLE-INTERRUPT

     Will prevent the user from stopping a command via
     Ctrl-Y

Of course all of these settings will make it much more
difficult for you to debug your program, so you shouldn't set
them until everything is working correctly.

Datacomm Disabling in docommand sequence

Once the api_startcommands function is performed, datacomm is turned
off except during the actual execution of an api_docommand.  This is
essential to allow your application to maintain synchronization with
the host program.  What we mean when we say datacomm is turned off is
that Reflection will not read any incoming characters from its
receive buffer unless you are actually processing a command.  The
characters will still be received, of course, but they will remain in
the buffer and Reflection will be ignorant of them.  This means that
you can pause and prompt the user for something without missing any
incoming characters.  If you were logging a user onto a DEC VAX and
had to stop and prompt for a password, you wouldn't have to worry
that the password prompt might have slipped in while you weren't
looking. The password prompt would still be in Reflection's receive
buffer waiting to be read by your next command.  If you then issued
the command

     api_docommand("WAIT 0:0:30 for 'Password:'");

the command would return immediately (since the prompt was
already in the receive buffer).

If, instead, Reflection were always reading datacomm and you
issued the above wait command, the WAIT would time out in 30
seconds without finding the 'Password:' prompt, since it
would have already been received. Your application would
likely assume that there was some kind of problem
communicating with the VAX and take incorrect action.

To prevent Reflection's receive buffer from being overrun by
the host during delays by your application, you must
set the appropriate type of flow control.  For both HP and
DEC, this will in most cases be XON/XOFF receive pacing.

When you issue a WAIT FOR command, you will
probably want to follow it with a api_found() command, which
will tell your application whether the wait command actually
found the string you were looking for, or it timed out
empty-handed.

    api_docommand("wait 0:0:30 for 'HP3000'");
    if (api_found())
        printf("Logged on Successfully\n");
    else
        .....

Configuration Issues

The api_getinfo command returns a structure of configuration
items, but they are pretty obscure.  These are items
which appear on config screens but have no corresponding SET
command.  The VALUE command can be relied upon to get more
common configuration items such as BAUD rate, PARITY, etc.
For instance, to find the baud rate execute the following
sequence:

     api_docommand( "set v3=value(BAUD)" );
     api_getvar( baudvalue, 3, length );
     baudvalue[length]='\0';
     printf( "Reflection BAUD RATE = %s\n",baudvalue);

     SET commands can be issued to change most configuration
     items.  Some items cannot be changed except via SET
     commands or display commands using escape sequences.


Configuring Reflection to use less memory

Since Reflection must be loaded in background to provide API services
to a client program, memory is at a premium.  There must be enough
for any resident device drivers plus Reflection, as well as your
application.  You can configure Reflection to use less memory by
setting display memory to 8K instead of 20K, using the standard IBM
font (/I switch), and by using expanded memory if available (/E
switch).

    R1 /Q /W /B /I /E

This command loads Reflection /Quickly /With API /Background immediately
with /IBM font using /Expanded memory.    Using a configuration file which
specifies 8K of display memory and no print buffers will also save
memory.


Queued File Transfers

When an API client queues a file transfer, the file transfer usually
will not start immediately.  Consequently, if you immediately test
apistat_batch_flag to see if the transfer is complete (== 0), you
will probably be testing it before Reflection has had a chance to
turn it on.  The best way to determine Reflection's status, and see
whether the file transfer is complete, is by testing the return code
from api_block.  If api_block returns 0, then Reflection has
exhausted all queues.  Api_block also gives Reflection a little CPU
time.

Synchronous File Transfers

One problem in performing a synchronous file transfer is that control
will not return to your PC until the file is transferred.  Since the
user will not receive any feedback as the file is being transferred,
it tends to look as though the machine is hung.  By using queued
commands, you can get around this problem and pop up the file
transfer screen during the transfer so the user will at least know
that something is happening. The following code fragment demonstrates
this.  It queues 3 commands: a command to perform the file transfer,
a command to get the error code into a variable, and a command to
switch back to background.  It then issues the pop_up command so the
user can view the file transfer.  As soon as the file transfer
completes, the error code is fetched and Reflection flips back to
background.  While these commands are queued, the effect is
synchronous since the file transfer is performed in the foreground.
It is important to capture the error code since it is possible for
the user to stop the transfer via the STOP TRANSFER key.  In this
case, you can detect why the xfer failed.



   char   error_text[81];
   int      length;
   api_qcmd( "send testall.c to data1 ascii delete");
   api_qcmd( "let v9=error-code" );
   api_qcmd( "background");
   api_popup();
   api_getvar( error_text, 9 , &length);
   error_text[length]='\0';
   printf( "File transfer Completed\n");
   printf( "Error code %s",error_text );
   exit();




Un-installing Reflection

If you need to un-install Reflection to free up some memory,
the correct method is to use api_qcmd as follows:

    api_qcmd("HARDEXIT");

Other methods may leave your PC in an unstable state.


Debugging API applications

Most programmers have their favorite debugger.    Microsoft C
developers usually use CodeView, and Turbo Pascal or QuickBASIC
programmers may use the built-in debug capabilities of those
environments.    Memory limitations, however, may also determine
which debugger is used.  Periscope has low memory requirements and
is useful for debugging memory-resident applications.


    COMMAND LANGUAGE PROGRAM -> API PROGRAM
        SAMPLE CONVERSIONS


Here's a fairly standard command file which dials a modem and
attempts to log on to an HP 3000 computer.  Following it is the exact
same function in a C program using API calls.

    COMMAND LANGUAGE VERSION


set datacomm-port com1
set baud 2400
set character-delay 80
;
; need to set big delays and long waits when talking to modems
;
; initialize retry_count
let v1 = 0
display 'Initializing Modem...^m^j'
wait 0:0:1
transmit '+++'
wait 0:0:2 for 'OK'
wait 0:0:.5
transmit 'ATH^m'
wait 0:0:2 for 'OK'
if NOT FOUND
    let v4 =   "No Response from modem^m^j"
    goto fail
endif
wait 0:0:1
display 'Dialing Modem...^m^j'
transmit 'ATDT 1234567^m'
wait 0:0:45 for 'CONNECT'
if NOT FOUND
    let v4 = "Did not receive CONNECT Message^m^j"
    goto fail
endif
display 'Connected to Remote Modem^m^j'
;
; Modem says we're connected - see if we can log on
;
:tryagain
if v1 < 6
    let v1 = v1 + 1
    transmit '^m'
    wait 0:0:1 for '^q'
    if NOT FOUND
    display 'Try $1 Failed^m^j'
    goto tryagain
    else
    goto logon
    endif
else
    let v4 = "Never Got Host Prompt^m^j"
    goto fail
endif
display 'Entering login and password^m^j'
transmit 'hello sazle,mgr.express/joshua^m'
wait 0:0:30 for 'HP3000'
if NOT FOUND
    display 'Login rejected - hangup modem^m^j'
    wait 0:0:2
    transmit '+++'
    wait 0:0:3 for 'OK'
    wait 0:0:1
    transmit 'ATH^m'
    wait 0:0:2 for 'OK'
    if NOT_FOUND
    let v4 = "Hangup Complete^m^j"
    goto fail
    else
    let v4 = "Hangup failed^m^j"
    goto fail
    endif
endif
wait 0:0:30 for ':^q'
set character-delay 0
display 'Successful Logon^m^j'
stop
;
;    Fail 'subroutine'
;
:fail
display  v4
stop


    C LANGUAGE VERSION of the same command file using Synchronous
    (Do while you wait) Commands.  Notice that we use C's if
    and for statements to control program execution.

main()
{
    int  retry_count;
    char    serbuf[32];
    if (api_instchk(serbuf)) {
        printf("API not present\n");
        exit();
    }
    api_open();
    if (api_startcommands()) {
        printf("API busy\n");
        exit();
    }

    api_docommand("alert 'API - AUTODIAL - LOGON'");
    api_docommand("set datacomm-port com1");
    api_docommand("set baud 2400");
    api_docommand("set character-delay 80");

    /* need to set big delays and long waits when talking to modems */

    retry_count = 0;
    printf("Initializing Modem...\n");
    api_docommand("wait 0:0:1");
    api_docommand("transmit '+++'");
    api_docommand("wait 0:0:2 for 'OK'");
    api_docommand("wait 0:0:.5");
    api_docommand("transmit 'ATH^m'");
    api_docommand("wait 0:0:2 for 'OK'");
    if (!api_found())
         fail("No Response from modem\n");

    api_docommand("wait 0:0:1");
    printf("Dialing Modem...\n");
    api_docommand("transmit 'ATDT 1234567^m'");
    api_docommand("wait 0:0:45 for 'CONNECT'");
    if (!api_found())
       fail("Did not receive CONNECT Message\n");

    printf("Connected to Remote Modem\n");

    /* Modem says we're connected - see if we can log on */

    for ( retry_count = 0 ; retry_count < 6 ; retry_count++) {
         api_docommand("transmit '^m'");
         api_docommand("wait 0:0:1 for '^q'");
         if (!api_found())
          printf("Try %d Failed\n",retry_count);
         else
          break;
    }
    if ( retry_count >= 6)
        fail("Never got host prompt\n");
    else
        printf("Entering login and password\n");

    api_docommand("transmit 'hello sazle,mgr.express/joshua^m'");
    api_docommand("wait 0:0:30 for 'HP3000'");
    if (!api_found())  {
         printf("Login rejected - hangup modem\n");
         api_docommand("wait 0:0:2");
         api_docommand("transmit '+++'");
         api_docommand("wait 0:0:3 for 'OK'");
         api_docommand("wait 0:0:1");
         api_docommand("transmit 'ATH^m'");
         api_docommand("wait 0:0:2 for 'OK'");
         if (!api_found())
        fail("Hangup Complete\n");
         else
        fail("Hangup failed\n");
    }
    api_docommand("wait 0:0:30 for ':^q'");
    api_docommand("set character-delay 0");
    printf("Successful Logon\n");
    api_endcommands();
    api_close();
}

fail(s)
char    *s;
{
    printf("%s",s);
    api_endcommands();
    api_close();
    exit();
}




       Using the api_qkeys() function.


You'll need to mind your single and double quotes when using this
function.  When passing keystrokes via the api_qkeys function, keys
with normal ASCII values such as "abcd12345%&*@" are passed between
single or double quotes.  Note that even control characters may be
passed in this way.  Keys with special functions such as the HP or VT
ENTER key, F1, PF1, or the ERROR-RECAP key which brings up the
summary of datacomm errors are not treated in this way.  Keys
providing special functions are passed as KEYWORDS and are not
quoted. A list of these keywords is found in the Keyboard
Remapping section of the Technical Reference Manual.  These are
keywords such as HARD-RESET, HOST-BREAK, RETURN, F1, F2, SYSTEM-KEYS,
ENTER, etc.

Be careful to observe the difference between:

        api_qkeys("'return'");

        which passes the keys r - e - t - u - r - n
        as a quoted string 'return' and...

        api_qkeys("return");

        which passes the keyword RETURN as a NON-quoted
        string to API - this refers to the carriage
        return key.




API SPECIFIC ERROR CODES returned to functions
------------------------
 hex   dec

  0    0    No Error         No error encountered


100h   256   Not_Available - Attempt to do api_startcommands when Reflection
                 busy or a config screen/help screen/file xfer
                 screen is present.
                 Attempt to do api_docommand when screen is up.

101H   257   OpenforSynch    Attempt to do api_qcmd when opened for Docommands
                 Issue an api_endcommands function first.


102H   258   ServiceNotOpen  Attempt to do an api_docommand before first
                 issuing an api_startcommands.  Also an
                 attempt to do an api_rdchar without doing
                 an api_startcommands (to turn off datacomm).

103H   259   IllegalFncCall  Call parameters are incorrect, i.e. a screen
                 read is requested which goes off of the screen

104H   260   QueueFull         Keyboard or Command queue is full

105H   261   BadKey         An attempt was made to queue a keyname that
                 could not be recognized

106H   262   BadLength         Attempt made to set a variable with length
                 greater than 80 or a command with greater
                 than 159

109H   265   NotFound         Searchscreen failed character not found
                 on api_rdchar

10AH   266   BadVarno         The variable number used exceeded the
                 current highest legal variable number

0FFFFH    -1   Uninstalled     Reflection was un-installed.  Also AH=DEH
                 for assembler

other codes             Api_docommand returns standard Reflection
                 error codes.  These codes are below 256.
                 See the Command Language manual for a
                 listing of these error codes.



Compiling and Linking with API Libraries
----------------------------------------


Building API applications with Borland Turbo Pascal
---------------------------------------------------

    Version 5.0 or greater of Turbo Pascal is required.



Sample session using TURBO integrated environment:

    1. Load Reflection in background using a minimum memory
       configuration

    2. Load SAMPLE.PAS file using pull-down menus

    3. Run SAMPLE.PAS - it will prompt for Reflection
       command language commands.  Use commands like
       'dir', 'display "^g"' to beep the bell, or
       'foreground' to pop Reflection up.

Sample session using DOS command line:

    1. Invoke Turbo Pascal compiler via TPC command

        TPC  sample   /GD

       (GD switch produces a detailed map which can be
         used for debugging)

       This will create a SAMPLE.EXE file

    Turbo Pascal will 'link' in APIUNIT.TPU to create
    SAMPLE.EXE






Building API applications using Microsoft QuickBASIC
----------------------------------------------------

    Version 4.5 or greater of Microsoft QuickBASIC
    required.


Special considerations for BASIC string variables:

    The size of a BASIC string variable cannot be
    modified by a called subroutine such as api.getvar.
    Any attempt to modify the length of a BASIC string
    variable results in a "String Space Corrupt" message
    and immediate termination of the program.  For this
    reason, if you need to get a Reflection variable into
    a BASIC string, you must first initialize the string
    to the correct length in BASIC and then pass the string
    to Reflection as shown:

        varbuf$ = SPACE$(80)
        i% = api.getvar( varbuf$, 2, l% )
        varbuf$ = MID$( varbuf$, 1, l% )




    Using the QuickBASIC environment:

    1. From DOS prompt load R1 or R2 using minimum memory
       configuration and requesting API support.  You must
       be using Reflection version 3.40 or above.    Reflection
       should immediately go into background if there is a
       configuration file.

        R1 /W /B /I /Q

        (for switch definitions, type  R1 /?)

    2. From DOS prompt, start QB environment by typing:

        QB  /L    B_APILIB.QLB

    3. The QuickBASIC environment will start up with the API
       support present.

    4. Load the SAMPLE.BAS program using the FILES pull-down
       menu.

    5. Run the program.  SAMPLE.BAS will first print the
       Reflection serial number and will then pop-up after
       you hit a key.  Hit hot-key (Alt-right Shift) to return
       to the BASIC program.

   Using the DOS command line:


    1. Invoke the QuickBASIC compiler

        BC    SAMPLE;

    2. Invoke the Microsoft Linker, linking in the
       B_APILIB.LIB library.

        LINK    SAMPLE,,,B_APILIB;

    Note that there are a number of command line options
    for producing stand alone .EXE versions and providing
    debug capabilities.  These options are documented in
    the QuickBASIC manuals.





Building API applications using  Microsoft C
---------------------------------------------

    Microsoft C version 5.0 or greater required

Sample Compile and Link of a small model API application.

        cl    sample.c  /link  c_sapi.lib

Sample Compile and Link of a medium model API application.

        cl /AM    sample.c  /link  c_mapi.lib