kst4contest/github_docs/en-Macros-and-Variables.md

Macros and Variables

🇬🇧 You are reading the English version | 🇩🇪 Deutsche Version

KST4Contest distinguishes between shortcut buttons, text snippets and variables. Shortcuts and snippets contain prepared text. Variables add information which may change during operation.

Inserted text remains visible in the send field and can be checked or edited before transmission.

---

Overview

Mechanism	Access	Use
Shortcut	Button above the send field	Inserts configured text into the send field
Snippet	Context menu or Ctrl+1 through Ctrl+0	Prepares text for the selected station
Variable	Placeholder within message text	Inserts current QRG, locator, direction, station or AirScout information

Shortcuts and snippets store text. Variables supply the corresponding current values.

A shortcut such as

pse sked?

always inserts the same text. A shortcut containing

pse call me at MYQRGSHORT

instead uses the QRG stored in KST4Contest when the button is pressed.

---

Shortcut Buttons

Shortcuts are configured under Preferences → Shortcut Settings.

Each entry creates one button in the main window. Pressing it appends the configured text to the existing contents of the send field. Text which has already been prepared is not removed.

If a shortcut contains a variable, the variable is resolved when the text is inserted. For example,

pse call me at MYQRGSHORT

may become:

pse call me at 144.388

The exact entries MYQRG and SECONDQRG are highlighted as QRG buttons. They insert the current QRG of the first or second chat category respectively.

The shortcut

/SETNAME MYQRG

is highlighted as well. Pressing it resolves MYQRG and inserts the resulting server command into the send field. The command is not transmitted automatically.

The order of the entries in the settings determines the button order in the main window. Editing, sorting and saving are described under Configuration – Shortcut Settings.

---

Text Snippets

Snippets are configured under Preferences → Snippet Settings. They are intended primarily for recurring messages to a particular station.

Snippets can be opened:

• by right-clicking a station in the user list,
• by right-clicking a public message,
• by right-clicking a private message, or
• with Ctrl+1 through Ctrl+0 for the first ten entries in the snippet list.

Using the Context Menu

Selecting a station or message will normally have prepared the corresponding /cq destination in the send field. A snippet subsequently chosen from the context menu is appended to this text.

Existing message text can therefore be extended deliberately.

Using the Keyboard

A snippet invoked with Ctrl+1 through Ctrl+0 replaces the previous contents of the send field with a complete directed message:

/cq CALLSIGN snippet text

The complete visible callsign, including any suffix, is retained. Selecting 9A0BB-70 may therefore produce:

/cq 9A0BB-70 pse ur qrg?

KST4Contest also retains the selected station's chat category internally. A snippet for 9A0BB-70 is therefore not accidentally transmitted through the other active chat category.

If no station is selected, or no snippet exists for the selected key combination, nothing is inserted.

The prepared text is not sent automatically:

• Enter or TX sends the message.
• Esc clears the send field.

Keyboard Mapping

The mapping follows the order of the snippet list:

Key combination	Entry used
Ctrl+1	first entry
Ctrl+2	second entry
…	…
Ctrl+9	ninth entry
Ctrl+0	tenth entry

The key combinations can also be assigned to a programmable macro keyboard. The idea for this method came from IU3OAR, Gianluca Costantino.

KST4Contest does not define a mandatory set of default snippets. The useful texts depend on the station's own contest operation and operating method.

Editing, sorting and saving are described under Configuration – Snippet Settings.

---

Variables

Variables are reserved placeholders within message text. They must be written in uppercase and are case-sensitive.

Variables can be used in:

• shortcuts,
• snippets,
• beacon texts, and
• message text entered or pasted directly into the send field.

Variables in a shortcut or snippet are resolved when the text is inserted into the send field. Variables entered or pasted directly into the send field are resolved immediately before the message is placed in the transmission queue.

Station-specific variables always use the currently selected station. KST4Contest does not derive this station from a /cq destination entered manually in the message text.

---

Global Variables

Global variables do not require a selected remote station.

Variable	Replacement value
MYQRG	current QRG of the first or primary chat category
MYQRGSHORT	first seven characters of MYQRG
SECONDQRG	current QRG of the second chat category
MYLOCATOR	complete locator configured for the local station
MYLOCATORSHORT	first four characters of the local locator
MYCALL	configured local callsign
MYQTF	current antenna direction as a numeric value in degrees

For example,

cq at MYQRGSHORT, qtf MYQTF, loc MYLOCATOR

may be resolved to:

cq at 144.388, qtf 135, loc JO51IJ

QRG Variables

MYQRG contains the QRG of the first chat category. The value may come from TRX synchronisation with the logging software or from the manually edited QRG field.

MYQRGSHORT uses the same value, but limits it to the first seven characters:

144.388.03 → 144.388

SECONDQRG contains the QRG of the second chat category. Selecting a station from the second chat does not change the meaning of MYQRG. Use SECONDQRG explicitly when the QRG of the second category is required.

Locator Variables

MYLOCATOR inserts the complete configured locator of the local station:

JO51IJ

MYLOCATORSHORT uses only the first four characters:

JO51

MYQTF

MYQTF inserts the current antenna direction stored in KST4Contest as a numeric angle in degrees.

For example,

ant MYQTF deg

may become:

ant 135 deg

The direction is not converted into compass terms such as north, north-east or south-west.

---

Variables for the Selected Station

These variables require a selected remote station:

Variable	Replacement value
QRZNAME	name of the selected station, or its complete callsign if no name is available
FIRSTAP	description and arrival time of the first aircraft reported by AirScout
SECONDAP	description and arrival time of the second aircraft reported by AirScout

For example,

Hi QRZNAME, FIRSTAP, pse lsn at MYQRGSHORT

may become:

Hi David, a very big AP in 2 min, pse lsn at 144.388

QRZNAME

KST4Contest uses the name from the selected station's name field. If that field does not contain a usable name, the complete visible callsign is inserted instead.

FIRSTAP

If an AirScout candidate is available, FIRSTAP contains its description and the expected time until the reflection window.

For example:

a very big AP in 2 min

If no aircraft is available for the selected station, KST4Contest inserts:

no ap available

SECONDAP

SECONDAP uses the second available AirScout candidate.

For example:

Next big AP in 9 min

If there is no second candidate, SECONDAP is replaced with an empty string.

Further information about the aircraft data is available under AirScout Integration.

Behaviour Without a Selected Station

If no station is selected, QRZNAME, FIRSTAP and SECONDAP remain visible in the text. KST4Contest does not remove these placeholders automatically.

A visible unresolved placeholder is clearer than a formally complete message which silently lacks important information. Before transmission, check that the intended station is selected and that all required variables have been resolved.

---

Variables in the Beacon

A public beacon has no selected remote station. It can therefore use only global variables:

• MYQRG
• MYQRGSHORT
• SECONDQRG
• MYLOCATOR
• MYLOCATORSHORT
• MYCALL
• MYQTF

QRZNAME, FIRSTAP and SECONDAP are not resolved in a beacon and should not be used there.

A possible template for the first chat category is:

calling cq at MYQRGSHORT, ant MYQTF deg, loc MYLOCATOR

If the second chat category uses a different QRG, its template must contain SECONDQRG:

calling cq at SECONDQRG, ant MYQTF deg, loc MYLOCATOR

Global variables are evaluated again on every timer run. A QRG updated by the logging software can therefore already appear in the next beacon message.

The fully resolved beacon text:

• must contain at least one valid character,
• must not exceed 120 characters,
• must not contain the protocol separator |, and
• must not contain line breaks.

If the text is empty or invalid when transmission is due, that beacon run is skipped.

The interval, activation and behaviour of both categories are described under Configuration – Beacon Settings.

---

Example Snippet Workflow

For example, the first configured snippet may contain:

Hi QRZNAME, pse sked? I call at MYQRGSHORT

The workflow can then look like this:

1. Select DL1ABC-432 in the user list.
2. Press Ctrl+1.
3. KST4Contest prepares the directed message and resolves its variables.
4. Check the complete text in the send field.
5. If the remote station has proposed another QRG, edit the text accordingly.
6. Press Enter or TX to send the message.

The result may be:

/cq DL1ABC-432 Hi Peter, pse sked? I call at 432.088

The complete callsign determines the recipient. The selected chat category determines the transmission path. Variables reduce repeated typing, but they do not decide whether the inserted information still matches the current operating situation.

---

Limits of Variable Resolution

Variables reflect the information available to KST4Contest at the time they are resolved.

In particular:

• A QRG supplied by the logging software may have changed in the meantime.
• A manually entered QRG remains active until it is changed again.
• MYQRG remains the QRG of the primary category even if a station from the second category is selected.
• The selected station may differ from a /cq destination entered manually.
• AirScout may not provide current aircraft data for the path in question.
• Station-specific variables remain visible when no station is selected.
• Inserted text is not checked automatically for operational correctness.

The send field therefore remains editable after a shortcut or snippet has been inserted. Variables avoid repeated input; the final check remains the operator's responsibility.

---

Use During a Contest

Shortcuts, snippets and variables are individual tools within the operating workflow. Their interaction with CQ operation, station selection, skeds, QRG changes and log synchronisation is described under Contest Workflow with KST4Contest.