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

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:


       HAMMAP raises this event when it is terminated by the user.
       The client should then disconnect from HAMMAP. The event has no

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:


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

                               - 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

GetMaxCoord                    - Return maximum coordinates
                                   (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,

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)
                                       (in version 8.1 or later color may be
                                       specified in hex. - min. 3 characters

DrawLink                             - Draw Link between Call1 and Call2
                                       (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
                                       (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)
                                       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

                   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

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
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
   Begin VB.Line Line1
     X1             =  0
     X2             =  4680
     Y1             =  0
     Y2             =  0
   Begin VB.Label fldEvent
     BorderStyle    =  1  'Fixed Single
     Height         =  495
     Left           =  1560
     TabIndex       =  7
     Top            =  2400
     Width          =  2895
   Begin VB.Label fldResult
     BorderStyle    =  1  'Fixed Single
     Height         =  495
     Left           =  1560
     TabIndex       =  6
     Top            =  1680
     Width          =  2895
   Begin VB.Label lblCommand
     Caption        =  "Command:"
     Height         =  255
     Left           =  240
     TabIndex       =  5
     Top            =  360
     Width          =  975
   Begin VB.Label lblEvent
     Caption        =  "Last Event:"
     Height         =  255
     Left           =  240
     TabIndex       =  4
     Top            =  2520
     Width          =  975
   Begin VB.Label lblResult
     Caption        =  "Result:"
     Height         =  255
     Left           =  240
     TabIndex       =  3
     Top            =  1800
     Width          =  975
   Begin VB.Label lblStatus
     Caption        =  "Status:"
     Height         =  255
     Left           =  240
     TabIndex       =  2
     Top            =  1080
     Width          =  975
   Begin VB.Label fldStatus
     BorderStyle    =  1  'Fixed Single
     Height         =  495
     Left           =  1560
     TabIndex       =  0
     Top            =  960
     Width          =  2895
   Begin VB.Menu mnuQuit
     Caption        =  "&Quit"
   Begin VB.Menu mnuCommand
     Caption        =  "&Execeute"
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
   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()

  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
       .fldEvent.Caption = "No station selected"
     End If
   Case 2
     If Val(EventData) Then
       .fldStatus.Caption = "HAMMAP Ready"
       .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
  MultiUse = -1  'True
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
   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
   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
     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
  Set HM = Nothing
  Terminate = Err
  On Error GoTo 0
  'Perform program specific Terminate
  Call HammapTerminate
  Busy = False
End Function