HAMMAP Application Program Interface HAMMAP V11.0
==================================== Gerhard Berg
File: HM-API.TXT ex DJ6FM
HAMMAP for Windows provides a programming interface for program extensions.
The interface may be used by other programs under the following conditions:
- Usage of the HAMMAP API requires the permission of the author of HAMMAP.
- HAMMAP itself may NOT be distributed together with the program.
- A copy of the program must be provided to the HAMMAP author.
- The HAMMAP author is not liable for any damages that may be caused by HAMMAP.
1. OLE-/ActiveX Interface
=========================
The HAMMAP OLE-/ActiveX-Interface is available only for the 32 Bit Version
of HAMMAP. HAMMAP is an OLE-/ActiveX-Server.
HAMMAP exposes the 'vb5HAMMAP' Library with 'HAMMAP' class. The members of
HAMMAP can be seen with the Object Browser. They have the following meaning:
1.1 Methods
-----------
Function Action(CmdStr As String) As String
The parameter CmdStr contains a Command List (see section 4) or a
single command (see section 5). The function returns the result
(or an empty string, if the command(s) have(has) no return value(s)).
In case of an error condition, the function returns an error code
as a string (see section 6). In addition HAMMAP sets the following
properties of the Windows 'Err' Object:
Err.Number:=80040000hex + 1004 + ErrNr
Err.Source:="HAMMAP"
Err.Description:=Description
Sub Disconnect()
Only for HAMMAP Version 10.2 and later.
This method removes the client from the client list in the server.
It should be called immediately before deleting the HAMMAP object.
1.2 Properties
--------------
Property CallBackObject As Object
This property should be set to an object of the OLE-/ActiveX-Client
to allow callback-functions from HAMMAP (notification of events).
See section 1.4 for more details.
Property CallbackMask As Integer
This property must be set by the client if it wants to be notified
by HAMMAP for any events. Each Bit in the Mask defines one event
CallbackMask = 2 ^ (Mode - 1) (see section 1.3) .
Property ClientName As String
When connecting to HAMMAP the Client should assign its Name to this
property. The property is intended for diagnostic purposes.
Property ClientNr As Integer (ReadOnly)
HAMMAP assigns a sequential number to all clients connecting to HAMMAP.
Property Ready As Integer (ReadOnly)
HAMMAP returns True = -1, if it is ready to receive a command or
False = 0, if it is busy. If a command is sent while HAMMAP
is busy it returns a 'Busy' Error Condition.
Property Station As String
When reading this property, HAMMAP returns the call of the currently
selected station or an empty string if no station is selected.
When setting the property HAMMAP selects the station specified by
the string.
1.3 Events
----------
Beginning with version 9.0 HAMMAP uses events for notification of the
client(s) for certain conditions:
Terminate()
HAMMAP raises this event when it is terminated by the user.
The client should then disconnect from HAMMAP. The event has no
parameters.
Sub Notify(EventNr As Integer, EventData as String)
HAMMAP raises this event on certain conditions. The condition for
which the event is raised can be selected by the client with the
CallbackMask property.
EventNr defines the condition. EventData provides information about
the condition. The following events are supported with HAMMAP 9.0
and later:
EventNr Condition EventData Mask
--------------------------------------------------------------------
1 New Station selected Call of selected Station 1
2 Change of Busy/Ready O=Busy, -l=Ready 2
3 New Map Area selected Co-ordinates of new area 4
4 Map output Co-ordinates of map area 8
Event-Nr. 4 is supported with HAMMAP version 10.2 and later.
1.4 Callback-Object
-------------------
Using Callback-Objects is an alternative method of event notification.
It is provided for backward compatibility. New programs should use
events (see 1.3) and not Callback-Objects.
The Callback-Object should provide the following methods:
Sub Terminate
HAMMAP calls this method when it is terminated by the user.
The client should then disconnect from HAMMAP.
Sub Notify(EventNr, EventData as String)
HAMMAP calls this methods on certain events. The events to be notified
can be selected by the client with the CallbackMask property.
Usage of EventNr and EventData are identical to Events (see 1.3).
2. DDE-Interface
================
The HAMMAP DDE-interface is available for the 16 and 32 Bit Version of HAMMAP.
HAMMAP is a DDE-Source (Server).
Application: HMWIN
Topic: MAP
Item: Result - contains the result of a commands or the error code
ClientName* - the name of the Client should be poked into it
Station - contains the call of the selected station
Ready* - contains -1 when HAMMAP is ready or 0 when busy
Area* - contains the co-ordinates of the current map area
NewMap* - contains the co-ordinates of the current map area
(to cause a change for each map output,
a space is appended on every 2nd map output)
Items marked with * are only available in version 10.2 and later.
Commands are executed with the Link-Execute command. Program control returns
when the execution is terminated (or a timeout occurs).
In case of no error, HAMMAP returns a positive acknowledge and the specified
result (if any) or an empty string. In case of an error, HAMMAP returns a
negative acknowledge and an error code (see section 6).
3. Overlays: (only HAMMAP Version 11.0 and later)
============
Normally API commands are executed immediately. An alternate method is
available for drawing commands (see section 5.2). By transferring these
commands as Overlays the commands are not executed immediately, but stored
in HAMMAP and executed each time the map is drawn and/or printed by HAMMAP.
There are two kinds of overlays:
- Foreground Overlays are drawn after the complete map has been drawn.
- Background Overlays are drawn before the complete map has been drawn.
(For vector map this is after the land and water is coloured and before
coasts, borders, rivers, stations, links etc. are drawn. For pixel maps
this is after the pixel map has been drawn and before stations and links
are drawn.)
Overlay command:
----------------
Overlay:Mode - Control Overlay Transfer / Delete Overlay
Mode: 1 = Begin of Foreground Overlay Transfer
2 = Begin of Background Overlay Transfer
0 = End of Forground/Background Overlay
-1 = Delete Foreground Overlay
-2 = Delete Background Overlay
Besides the Overlay command, only the following commands (see section 5)
are allowed in Overlays:
DRAWFIGURE, DRAWSHAPE, DRAWLINE, DRAWSYMBOL, DRAWTEXT,
DRAWSTN, MARKSTN, DRAWSTNS, DRAWLINK, DRAWLINKS, DRAWGRID,
SETPAR, SELSTN, NOOP or ';', STOREMAP, RESTOREMAP
4. Command List: (only HAMMAP Version 8.0 and later)
================
A command list contains of a series of commands separated by CR/LF.
The command list can be executed with a single Link-Execute command (DDE)
or Action Method (OLE).
command [ CR/LF command CR/LF command ... ]
The result is also a list consisting of a series of results separated
by CR/LF (one result line per command).
Overlay commands (see section 3) cannot be used in command lists. They must
always be executed as individual commands.
5. Command Syntax:
==================
5.1 Information Commands:
-------------------------
GetAnzStn[:Mode] - Return number of stations in current area
Mode: 0=without Filter
1=with Filter
(Mode only with version 8.0 and later)
GetStn[:[n][,Mode]] - Return call of station in current area
n: number of station (1...)
default: next station
Mode: 0=without Filter
1=with Filter
GetStnLines:Call - Return available lines (0...9)
for specified station
GetStnInfo:Call[,[Line][,Mode]] - Return Info for specified station
Line: Line-Nr. for station info
Mode: 0 = return Status,Type,Hardware, Soft-
ware as 2 character abbreviation.
return date as yymm
1 = return Status,Type,Hardware,
Software with full text.
return date as mm.yy
GetLinks:Call[,Mode] - Return Links for specified Station
Mode: 0 = return Status,Type,Hardware, Soft-
ware as 2 character abbreviation.
return date as yymm
1 = return Status,Type,Hardware,
Software with full text.
return date as mm.yy
GetLinkInfo:Call1,Call2[,Mode] - Return Info for specified Link
Mode: 0 = return Status,Type,Hardware, Soft-
ware as 2 character abbreviation.
return date as yymm
1 = return Status,Type,Hardware,
Software with full text.
return date as mm.yy
GetRoute:Call1,Call2[,[Flags],NotVia]
- Return Route between specified stations
Flags: (Only version 5.2a and later)
1=Fastest Route
2=Draw Route
4=Mark Route
Not Via: (Only version 5.2a and later)
Stations not used in route
(one call or several Calls separated
by space)
GetCoord - Return current coordinates
(xmin,ymin,xmax,ymax)
GetMaxCoord - Return maximum coordinates
(xmin,ymin,xmax,ymax)
(only version 9.0 and later)
GetMapType - Return type of map
(only in version 10.2 and later)
0=none, 1=Vector, 2=BMP, 3=RLE
GetSize - Return MapWidth,MapHeight,
WindowWidth,WindowHeight,
PrintWidth,PrintHeight
CopyMap - Copy Map to Clipboard
5.2 Draw Commands:
------------------
DrawMap[:xmin,ymin,xmax,ymax[,Mode]] - Draw Map (default: Current Coordinates)
(in version 10.0 and later map file is
selected automatically)
Mode: (only Version 8.0 and later)
default: defined by HM parameter
0 = only map (without towns, grid,
links, stations)
1 = with towns (as in HM parameter)
2 = as 1 but also with town names
SelStn[:Call] - Select Station (default: none)
DrawStn:Call[,Color] - Draw Station
(in version 8.1 or later color may be
specified in hex. - min. 3 characters long)
MarkStn:Call[,[Color][,Text]] - Mark Station
Default Text: Callsign
(Text only with version 5.2 and later.)
DrawStns[:Mode] - Draw all stations
(only in version 8.0 and later)
Mode: 0 = without calls (default)
1 = with calls
StoreMap (only Version 8.0 and later) - Store current map
RestoreMap (only Version 8.0 and later) - Restore previously stored map
Draw Symbol (only Version 5.2 and later)
DrawSymbol:Qth[,[Color][,[Symbol][,Text]]]
DrawSymbol:Lon,Lat[,[Color][,[Symbol][,Text]]]
(in version 8.1 or later color may be
specified in hex. - min. 3 characters
long)
DrawLink - Draw Link between Call1 and Call2
DrawLink:Call1,Call2[,[Color][,Pattern],[Width]]
(Width only in version 8.1 and later)
DrawLinks - Draw all links
(only in version 8.0 and later)
DrawLinks should be used before DrawStns
DrawGrid (only Version 5.2 and later) - Draw QTH-Locator Grid
DrawGrid:Mode[,Locator] Mode: 1 = Largest Locator Square
2 = Large Locator Square
3 = Small Locator Square
Locator: (only Version 8.0 and later)
default: defined by HM parameter
0 = Locator not written in grid
1 = Locator written in grid corners
2 = Locator written in all fields
DrawLine (only Version 5.2 and later) - Draw Line
DrawLine:Lon1,Lat1,Lon2,Lat2[,[Color][,Pattern],[Width]]
(Width only in version 8.0 and later)
Draw Shape (only Version 8.0) - Draw Shape
(in Version 8.1 and later this function is provided only for compatibility
reasons - for new programs or updates, the function DrawFigure should be
used instead)
DrawShape:Lon1,Lat1,Lon2,Lat2[,[Color][,Shape],[Width]]
DrawShape:Qth[,[Color][,Shape],[Width]]
Shape: 0 = Line
1 = Cross
3 = Box
4 = filled Box
10 = Circle/Ellipse
11 = filled Circle/Ellipse
Draw Figure (only Version 8.1 and later) - Draw Figure
DrawFigure:Lon1,Lat1,Lon2,Lat2,Figure[,[DrawColor][,[FillColor][,[DrawWidth][,[Pattern][,[FillStyle]]]]]]
DrawFigure:Qth,Figure[,[DrawColor][,[FillColor][,[Width][,[Pattern][,[FillStyle]]]]]]
Figure: 0 = nothing 10 = Circle / Ellipse
1 = Point 11 = Square
2 = Line 12 = Diamond
3 = + 13 = Triangle (pointing up)
4 = x 14 = Triangle (pointing down)
5 = Star 15 = Triangle (pointing right)
16 = Triangle (pointing left)
DrawColor: see Color (default: black)
FillColor: see Color (default: no filling)
FillStyle: 0 = solid (default if no FillColor specified)
1 = transparent (default if FillColor is specified)
DrawText (only Version 5.2 and later) - Output Text
DrawText:Lon,Lat,[Color],[Size],Text Lon,Lat = upper left corner
(version 8.0 and later output also to printer)
PrintMap[:xmin,ymin,xmax,ymax] - Print Map as defined by HM parameter
(default: Current Coordinates)
Note: With coordinates correct only with
version 5.0a and later.
(Preferred: StartPrint,DrawMap,...StopPrint)
StartPrint[:Mode] - Start Printer Output
(only Version 5.2 and later)
Mode: (only Version 8.1 and later)
1 = Screen
2 = Printer
4 = Print-Preview
(values may be added)
Default Mode = 3 in Versions 8.2 and later.
(Caution!! V8.1 default mode=0 = no output.)
StopPrint (only Version 5.2 and later) - Terminate Printer Output
KillPrint (only Version 8.0 and later) - Abort Printer Output
Color: Color Nr. 0...15 (default: HAMMAP color)
RGB-Color xxxxxx (only Version 8.0 and later)
RGB value of color in hex. (min.3 characters)
(e.g. 0FF=red, FF00=green,FF0000=blue)
8000000x = Windows system color
Symbol: Symbol Nr. 0...12 (default: 0)
Pattern: Pattern Nr. 0...6 (see Visual Basic DrawStyle Property)
Width: Drawing Width in pixels (default: 1)
only version 8.0 and later
applies to DrawLine, DrawFigure and DrawShape
Qth: QTH-Locator (2, 4, 6, or 8 characters)
Lon: Longitude (east)
Lat: Latitude (north)
Longitude and latitude are given in degrees. Decimal fractions are
separated by period. Western longitude and southern latitude are
represented by negative values (e.g. 8:30 W is given as -8.5).
5.3 System Commands:
--------------------
Noop - No Operation (use to test link)
;any text - Comment line in scripts (same as Noop)
(only version 8.0 and later)
Test:String - Test: Return specified String
GetVer - Return HAMMAP Version (e.g. 8.1)
GetStnAbv:n - Return station abbreviations
n: 1=Stations-Status
2=Stations-Typ
3=Software
4=Hardware
5=Link-Status
GetMsg:MsgNr - Return specified message
GetHammapDir - Return HAMMAP base directory
(only version 9.0 and later)
GetMapFile - Return map file name
(only version 9.0 and later)
LoadMapFile:Filename - Load specified map file
(only version 9.0 and later)
GetMsgFile - Return message file name
GetHlpFile - Return help file name
GetParFile - Return parameter file name
GetPar:ParName[,Id] - Return value of specified parameter
SetPar:ParName=Value - Set Parameter to specified value
The SETPAR commands should be used only with full understanding
of the HAMMAP program, because some parameters must not be modified
through the HAMMAP interface. The parameter assignments may change with
future versions of HAMMAP.
6. Return values:
-----------------
-5 - program error (e.g. out of string space)
-4 - bad command
-3 - bad parameter (out of range)
-2 - I/O-error
-1 - busy
0 - ok (or empty string)
1 - object not in current map area
2 - unknown QTH
3 - station not found
4 - bad callsign format
5 - link not found
6 - no route found
7. Demo Program
===============
The following programs are available to examine the HAMMAP programme interface
(DDE and OLE-/ActiveX):
HMAPI.EXE - API-interface for 16 bit version (DDE only)
HMAPI32.EXE - API-interface for 32 bit version (DDE and OLE-/ActiveX)
8. Sample Code
==============
This section shows typical Visual Basic Code (VB5 and later) of a simple
demo program 'ApiDemo' for the HAMMAP API.
Form ApiDemo.frm
----------------
VERSION 5.00
Begin VB.Form frmApiDemo
AutoRedraw = -1 'True
Caption = "HAMMAP-API Demo"
ClientHeight = 3165
ClientLeft = 9150
ClientTop = 3585
ClientWidth = 4740
Icon = "ApiDemo_x.frx":0000
LinkTopic = "Form1"
ScaleHeight = 3165
ScaleWidth = 4740
Begin VB.TextBox txtCommand
Height = 495
Left = 1560
TabIndex = 1
Text = "GetVer"
Top = 240
Width = 2895
End
Begin VB.Line Line1
X1 = 0
X2 = 4680
Y1 = 0
Y2 = 0
End
Begin VB.Label fldEvent
BorderStyle = 1 'Fixed Single
Height = 495
Left = 1560
TabIndex = 7
Top = 2400
Width = 2895
End
Begin VB.Label fldResult
BorderStyle = 1 'Fixed Single
Height = 495
Left = 1560
TabIndex = 6
Top = 1680
Width = 2895
End
Begin VB.Label lblCommand
Caption = "Command:"
Height = 255
Left = 240
TabIndex = 5
Top = 360
Width = 975
End
Begin VB.Label lblEvent
Caption = "Last Event:"
Height = 255
Left = 240
TabIndex = 4
Top = 2520
Width = 975
End
Begin VB.Label lblResult
Caption = "Result:"
Height = 255
Left = 240
TabIndex = 3
Top = 1800
Width = 975
End
Begin VB.Label lblStatus
Caption = "Status:"
Height = 255
Left = 240
TabIndex = 2
Top = 1080
Width = 975
End
Begin VB.Label fldStatus
BorderStyle = 1 'Fixed Single
Height = 495
Left = 1560
TabIndex = 0
Top = 960
Width = 2895
End
Begin VB.Menu mnuQuit
Caption = "&Quit"
End
Begin VB.Menu mnuCommand
Caption = "&Execeute"
End
End
Attribute VB_Name = "frmApiDemo"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = False
Attribute VB_PredeclaredId = True
Attribute VB_Exposed = False
DefLng A-Z
Option Explicit
Dim HMClient As HammapClient
Private Sub Form_Load()
Dim ErrorFlag
App.Title = "HAMMAP-API Demo"
Set HMClient = New HammapClient
'Connect to HAMMAP
ErrorFlag = HMClient.Connect
If ErrorFlag Then
fldResult.Caption = "Error starting HAMMAP"
Call HMClient.Terminate
Else
HMClient.CallbackMask = -1 'all Events
End If
End Sub
Private Sub Form_Unload(Cancel As Integer)
Call mnuQuit_Click
End Sub
Private Sub mnuCommand_Click()
Dim ErrorFlag, Result$
ErrorFlag = HMClient.Command(txtCommand.Text, Result$)
If ErrorFlag Then Result$ = "Error: " & Result$
fldResult.Caption = Result$
End Sub
Private Sub mnuQuit_Click()
HMClient.Terminate
Set HMClient = Nothing
End Sub
Module ApiDemo.bas
------------------
Attribute VB_Name = "modApiDemo"
DefLng A-Z
Option Explicit
Sub HMNotify(EventNr As Integer, EventData As String)
Dim msg$
With frmApiDemo
Select Case EventNr
Case 1
If Len(EventData) > 0 Then
.fldEvent.Caption = "New station selected: " & EventData
Else
.fldEvent.Caption = "No station selected"
End If
Case 2
If Val(EventData) Then
.fldStatus.Caption = "HAMMAP Ready"
Else
.fldStatus.Caption = "HAMMAP Busy"
End If
Case 3
.fldEvent.Caption = "New map area selected: " & EventData
Case 4
.fldEvent.Caption = "New map output: " & EventData
End Select
End With
End Sub
Sub HammapTerminate()
Unload frmApiDemo
Set frmApiDemo = Nothing
End Sub
Class Module HMClient.cls
-------------------------
VERSION 1.0 CLASS
BEGIN
MultiUse = -1 'True
END
Attribute VB_Name = "HammapClient"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = True
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = False
DefInt A-Z
Option Explicit
Private WithEvents HM As HAMMAP
Attribute HM.VB_VarHelpID = -1
Friend Function Connect(Optional Timeout = 10)
Dim Start As Date 'Date and Time
Connect = True
'--- Connect to HAMMAP ---
Start = Now
'Wait until HAMMAP Object is created
Do
On Error Resume Next
Set HM = New HAMMAP
On Error GoTo 0
If Second(Now - Start) > Timeout Then Exit Function
Loop While HM Is Nothing
'Wait until HAMMAP is Ready
Do
DoEvents
If Second(Now - Start) > Timeout Then Exit Function
Loop Until HM.Ready
HM.ClientName = App.Title
Connect = False
End Function
Property Get Station() As String
Station = HM.Station
End Property
Property Get Ready() As String
Ready = HM.Ready
End Property
Property Let CallbackMask(Mask)
HM.CallbackMask = Mask
End Property
Private Sub HM_Notify(EventNr As Integer, EventData As String)
Call HmNotify(EventNr, EventData)
End Sub
Friend Function Command(Cmd$, Result$) As Long
On Error Resume Next
Result$ = HM.Action(Cmd$)
If Err.Number Then
Result$ = Err.Description
If Err.Number < vbObjectError Then
Command = -6 'OLE-Error
Else
Command = Err.Number - vbObjectError - 1004
End If
End If
On Error GoTo 0
End Function
Private Sub HM_Terminate()
'Terminate Event from HAMMAP
Call Terminate
End Sub
Friend Function Terminate()
'Terminate OLE from HAMMAP or Client
Static Busy
'Avoid recursive calls when unloading forms
If Busy Then Exit Function
Busy = True
On Error Resume Next
HM.Disconnect
Set HM = Nothing
Terminate = Err
On Error GoTo 0
'Perform program specific Terminate
Call HammapTerminate
DoEvents
Busy = False
End Function