PMGlobe, version 3.31	3 Aug 2009
[previous \| contents \| next]

Command and Macro Reference

Using commands and macros

PMGlobe can be controlled or programmed by means of commands, which are text strings typed in by hand or generated by programs. For example, the command:

  set sunlight on

causes the globe image to be drawn with sunlighting (just as though ‘sunlight’ had been selected from the Imagery menu). For every command, the first word is the command verb (set, in this case) and the following words are arguments to the command. Similarly,

  set sunlight off

turns sunlighting off.

Using the Command dialog

To enter a command by hand, press the Esc (Escape) key when PMGlobe has the focus, or select ‘Command...’ from the Options menu. This will display the PMGlobe Command dialog. The command dialog allows editing of the command in the usual way, using Insert, Delete, Backspace, Cursor Left/Right, Cut, Paste, and so on. It also has a simple ‘retrieve’ (history) facility, controlled by the Cursor Up/Down keys.^[1] To enter (execute) the command, press the Enter key, or click the OK button.

The command dialog can be hidden (closed) by clicking on the close box or the Cancel button, or by pressing the Esc (Escape) key.

There are two check boxes in the dialog:

Macros: This indicates whether a search for macros (see below) is carried out before treating the entered string as a command. When checked, macros with the same name as the command verb will be searched for and (if found) that macro will be called, even if there is a command with the same name. Unchecking the box disables the macro search.
Console: This check box indicates whether a Windows console is active for PMGlobe, and has the same effect as the Use console option in the Options menu. Changing the state of the check box will remove or start the console, as appropriate.
Note that closing the console using its titlebar options will also exit PMGlobe.

Using macros

A PMGlobe macro is a text file which contains either a simple list of commands (a command-list macro) or a program written in the Rexx ^[2] programming language (a Rexx macro) which can give more control over the creation and issuing of PMGlobe commands. In either case, the macro is a simple text file with a file extension of .pmg.

A macro is invoked either from the command dialog (by typing the name of the macro) or by using the ‘Run Macro...’ selection in the Options menu. This latter selection will bring up a normal Windows file dialog which will let you choose the macro to run.

You can also have a macro run automatically when PMGlobe is started by specifying ‘macro filename’ as a parameter to the PMGlobe call, for example:

  start pmglobe macro triangle

Using command-list macros

A command-list macro is a text file (which you can edit with Notepad or any other plain text editor) which must have a file extension of .pmg. Each line of the file is either:

a comment (its first non-blank character is ‘;’)
a blank (empty) line
a command (just as could be entered from the command dialog).

The first line in a command-list macro must be a comment; this is used to distinguish command-list macros from Rexx macros.

Here is a simple command-list macro, called triangle.pmg (the numbers on the left identify the lines of the macro and do not appear in the macro file):

   1.  ; triangle.pmg: draw a triangle on the Globe
   2.  
   3.  set drawcolour red
   4.  gmove  0  0
   5.  gline  0 90
   6.  gline 90  0
   7.  gline  0  0

Line 1 is a comment which describes the macro. It, and the blank line 2, have no effect on PMGlobe.

Line 3 sets the colour for drawing on the globe to Red.

Line 4 (the graphics move command, gmove) moves the current point for graphics to latitude 0, longitude 0 (the coordinate system origin, a point off the coast of Africa).

Lines 5 through 7 are three graphics line commands (gline). Each of these draws a line, using the current drawing colour, from the current point to the point specified on the gline command, and then sets the current point to be the end of the new line.

Any of the commands described below, except extract, can be used in command-list macros.

Using Rexx macros

To use a Rexx macro, you must have a Rexx interpreter installed. PMGlobe has only been tested with IBM Object Rexx and Open Object Rexx – which is now available from http://www.oorexx.org/ – but other Rexx implementations which use the standard Rexx interface should also work.

In addition to issuing commands, macros using the Rexx language can use the full power of the Rexx language to program PMGlobe. A description of the language is outside the scope of this document, but here is a simple example:

   1.  /* myzone.pmg - display timezone in the titlebar */
   2.  
   3.  -- get PMGlobe version and timezone name
   4.  ’extract version zonename’
   5.  
   6.  if zonename=’???’
   7.    then ’message Time zone is unknown’
   8.    else ’set title PMGlobe’ version’, in’ zonename

Here, lines 1 through 3 are commentary. Line 4 then uses the extract command to get the current values of the PMGlobe version number and time zone name. As long as this is valid, the text of the PMGlobe window’s title bar is then set, perhaps to: PMGlobe 3.10, in GMT Daylight Time.

Rexx macros are run in the same way as command-list macros, but may have argument words passed to them from the rest of the command (these can be retrieved using parse arg or the arg() function in Rexx).

Footnotes:

[1]	For some reason, Windows generates a tone when these are used, but they should function correctly.
[2]	See:`http://en.wikipedia.org/wiki/REXX`