Stefan Pfeiffer, DD9EP@DB0IZ, 930401, last modification 930422
S P E C I F I C A T I O N
-------------------------
0. Overview
1. Introduction
2. Interrupt-Functions of Interrupt 2Fh
2.1. Function FFh - Get Version Number
2.2. Function 00h - Register as Remoteprogramme
2.3. Function 01h - Get FileTransfer-Address
2.4. Function 02h - Get QSO-Data-Address
3. GPRI-Routines
3.1. The GPRI-Transmitting-Routine
3.2. The GPRI-FileTransfer-Routine
3.3. The GPRI-QSO-Data-Routine
4. Required Routines of the Remote-Programme
4.1. The Initialisation-Routine
4.2. The Receiving-Routine
4.3. The Strategy-Routine
4.4. The Exit-Routine
5. Schematic Structure of a GPRI-Programme
6. Hints & Clues
1. Introduction
The GPRI is a collection of functions which allow external DOS-programmes to
communicate with GP and to control it in a restricted way.
This allows the remote-programme to transmit and receive texts directly from
its execution. It has not to care for the handling of the TNC, as this task
is completely done by GP.
When executing a interactive remote-programme (that uses the GPRI), GPRI loads the programme in the memory and, after the remote-programme has "registered"
itself, executes a initialisation-routine, in which the programme can send
a startup-message, for example.
Then GPRI will call a specific routine in the remote-programme whenever a
text was received on that channel. In this routine the remote-programme can
react on the text and send back an answer.
GPRI will unload the program from memory when the remote-programme
requests GPRI to do so.
So the GPRI is completely based on a client/server-structure between GP and
the remote-programme, as the remote-programme requests services like "send
string", "send file" and "get QSO-data" directly from the GPRI.
This allows to operate remote-programmes via PR like DOS-programmes, that is
per a interactive communication with the program. This offers much more
possibilities for remote-programmes as before.
This document describes the interface between GP and the interactive remote
-programme. It is independent of the used programming-language, but it should
be able to call interrupts and imbed assembler-commands. I presuppose some
knowledge on programming, as the GPRI and its programming are relatively
complex and susceptible to errors.
This is caused by the fact that a GPRI-programme has no real main routine,
and that nearly all actions are done in the routines which are called by
the GPRI.
2. Interrupt-Functions of Interrupt 2Fh
To get in touch with GPRI, the remote-programme uses the interrupt 2Fh.
By this interrupt it is able to determine if it is running under GPRI and
which version of the GPRI is supported. It can also get the address of the
transmitting-routine and can "register" its own routines at the GPRI.
To attract GPRI, the remoteprogramme has to load the value DFh into the
register AH, the functionnumber will be loaded in AL.
2.1. Function FFh - Get Version Number
By this function the remoteprogramme can determine if it is running under
GPRI and which version of GPRI is supported.
Input:
AH: DFh (Code to attract the GPRI)
AL: FFh (Functionnumber)
Output:
If AX contains the value 4750h,the remote-programme is running under GPRI
(4750h is equal to 'GP' in ASCII).
Then the following values are valid:
BH: Versionnumber
BL: Revisionnumber
When running under GPRI version 1.0, BH is 1 and BL is 0.
If AX is unequal 4750h, the remote-programme runs under DOS and the GPRI
is not active.
2.2. Function 00h - Register as Remoteprogramme
By this function the remote-programme registers itself at GPRI, and gets
the address of the GPRI-transmitting-routine and a handle which
identifies the programme while communicating with the GPRI.
This function has to be called before calling any other GPRI-routine.
Input:
AH: DFh (Code to attract the GPRI)
AL: 00h (Functionnumber)
ES: Segment of the following structure
BX: Offset of the following structure
PrefixSegment of the remote-programme : WORD
Address of the initialisation-routine : POINTER
Address of the receiving-routine : POINTER
Address of the strategy-routine : POINTER
Address of the exit-routine : POINTER
Output:
If AX is unequal 4750h ('GP'), an error has occured.
if AX contains 4750h, the following values are valid:
ES: Segment of the GPRI-transmitting-routine
BS: Offset of the GPRI-transmitting-routine
CL: Handle of the remote-programme
Description of the transmitting-routine: 3.1.
Description of the routines in the structure: 4.
2.3. Function 01h - Get FileTransfer-Address
By this function the remote-programme can get the address of the GPRI
-routine to send a file.
Input:
AH: DFh (Code to attract the GPRI)
AL: 01h (Functionnumber)
Output:
If AX is unequal 4750h ('GP'), an error has occured.
If AX contains 4750h, the following values are valid:
ES: Segment of the filetransfer-routine
BX: Offset of the filetransfer-routine
Description of the filetransfer-routine: 3.2.
2.4. Function 02h - Get QSO-Data-Address
By this function the remote-programme gets the address of the GPRI-routine
to get the actual QSO-data.
Input:
AH: DFh (Code to attract the GPRI)
AL: 02h (Functionnumber)
Output:
If AX is unequal 4750h ('GP'), an error has occured.
If AX contains 4750h, the following values are valid:
ES: Segment of the QSO-data-routine
BX: Offset of the QSO-data-routine
Description of the QSO-data-routine: 3.3.
3. GPRI-Routines
3.1. The GPRI-Transmitting-Routine
The Address of this routine can be obtained by the interrupt-function
00h. It must be called with a FAR CALL, like all GPRI-routines.
The registers have to following meaning:
BL: Handle of the remote-programme
BH: Prompt-flag (1 -> Flush sendbuffer, 0 -> Do not flush sendbuffer)
CL: Macro-flag (1 -> Expand macros, 0 -> Do not expand macros)
ES: Segment of the string to send
DX: Offset of the string to send
This string is a pascal-string with a leading lengthbyte. It is not
terminated by a binary 0.
If the string coudn't be sent by GP (e.g. no TNC buffers), AX contains
0, else 1.
3.2. The GPRI-FileTransfer-Routine
This routine allows the remote-programme to transmit any file. First the
address of this routine has to be obtained with the interrupt-function 01h. This routine has to be called with a FAR CALL, too.
Meaning of the registers:
BL: Handle of the remote-programme
BH: Mode of the filetransfer
0: Textfile
1: Binary file, no AutoBin
2: AutoBin
ES: Segment of the filename
DX: Offset of the filename
Please notice that the filename is a pascal-like string with a leading
lengthbyte and without a terminating 0.
After calling this function, AX contains 1, if no error occured, else 0.
The strategy-routine will NOT be called during a filetransfer.
3.3. The GPRI-QSO-Data-Routine
By this routine, the remote-programme can get information about the actual
QSO. The address of the routine has to be obtained by the function 02h,
it has to be called by a FAR CALL.
Meaning of the registers:
BL: Handle of the remote-programme
ES: Segment of the following structure
DX: Offset of the following structure
MyCall : String[9] (Mycall on the actual channel)
Call : String[9] (Call of the remote station)
Name : String[80] (Name of the remote station)
Path : String[255] (Connect-path to the remote-station)
Please take again care of the strings being pascal-strings with a leading
lengthbyte. So the MyCall-string is 10 bytes long: 1 lengthbyte and 9
databytes. The length of the structure is 357 bytes due to this fact.
If the function call succeeded and the structure contains the QSO data,
AX contains 1, else 0.
4. Required Routines of the Remote-Programme
The addresses of the following routines have to be made public to the GPRI
via the function 00h. All these routines have to be compiled FAR!
4.1. The Initialisiation-Routine
Input:
No
Output:
BL: Flag to end programme (0 -> No, 1 -> Yes)
This routine will be called by the GPRI after the remote-programme has been
loaded into memory. Here you can, for example, transmit a startup-
message.
NOTICE: Do not use a GPRI-routine in the main-routine of the remote-
programme, as this might cause some problems. Please send the startup-
message in the initialisation-routine, not earlier!
4.2. The Receiving-Routine
Input:
ES: Segment of the received string
DX: Offset of the received string
This is again a pascal-like string with a leading lengthbyte.
Output:
BL: Flag to end programme (0 -> No, 1 -> Yes)
This routine will be called whenever GP has received a text on the actual
channel. The routine can evaluate the received text, send back a text or
a file and perhaps set BL to 0 to end itself.
4.3. The Strategy-Routine
Input:
No
Output:
BL: Flag to end programme (0 -> No, 1 -> Yes)
This routine will be called by GP periodically, except during file-
transfers. This routine can be used as a timer or to determine the end
of a filetransfer.
4.4. The Exit-Routine
Input:
No
Output:
No
This routine will be called before GPRI removes the remote-programme from
the memory. This will happen in the following cases:
a) The programme has set BL to 1 to request its termination.
b) The QSO has been interrupted by an re- or disconnect.
c) GP has been left.
5. Schematic Structure of a GPRI-Programme
To make the GPRI-principle a bit more clearly, I will describe the
schematic structure of a GPRI-programme in the following.
It is recommended that your remote-programmes are executable under GPRI and
DOS. So your programme should accept input from the keyboard and display
its texts on the screen when realizing that it is NOT running under GPRI.
But there is also the possibility that your program simply stops execution.
Now the scheme of a GPRI-programme:
PROCEDURE Init (FAR!)
{
Send startup-message via transmitting-routing
Set BL to 0 (No termination of programme)
}
PROCEDURE Receive (FAR!)
{
Analyze received text
Send back text or file
Set BL to 1 if the programme should be terminated, else set BL to 0
}
PROCEDURE Exit (FAR!)
{
Deallocate memory and do other tiding-up-actions
}
PROCEDURE Main (The real main routine)
{
Get version of GPRI
If an error occured, then normally work under DOS or terminate
Register adresses of the routines Init,Receive and Exit and also
the prefix-segment to GPRI, save address of transmitting-routine and the
handle
Save addresses of the QSO-data-routine and the filetransfer-routine, if
needed
Terminate programme but stay resident in memory (by command of the
programming language or by interrupt 21h, function 31h)
}
6. Hints & Clues
You are asked to restrict the heap- und stacksize of your programme, as it
stays resident in the memory. You can also lower the stacksize, as the
programme will use the stack of GP.
Enjoy the unbelievable possibilities of interactive remote-programmes and
the programming of the GPRI.
Vy 73, Stefan Pfeiffer, DD9EP
This text has been checked and corrected by Pete, PE1MHO. THANKS!
