PMGlobe

PMGlobe 2.19 PMGlobe -- an OS/2 Globe -- Commands and Macros =============================================== Copyright (c) International Business Machines Corporation, 1991, 1994. All rights reserved. PMGlobe commands, and how they are used """"""""""""""""""""""""""""""""""""""" This document lists the PMGlobe commands that are currently implemented. These may be invoked from a PMGlobe macro (a program written in REXX), or directly from the command dialog (which can be displayed by pressing Escape while PMGlobe has the focus). The command dialog allows editing of the command, using Insert, Delete, Backspace, and Cursor Left/Right; it also has a simple 'retrieve' function, controlled by the Cursor Up/Down keys. To use commands from a macro, edit (perhaps with the OS/2 System Editor) a plain ASCII file such as the TEST.PMG supplied with PMGlobe and reproduced in simplified form here: /* Sample (test) macro */ /* Get the version information and set a new title */ 'extract version versionb' 'set title PMGlobe -' version '('versionb'-bit)' /* Mark and label some chosen cities */ "mark 51.5 0 label London" "mark 37.8 -122.4 label San Francisco" "mark -33.7 151.3 label Sydney" This is a very simple REXX program that consists almost entirely of commands (see SPIN.PMG for a more typical macro). After saving the file, it can by run by simply bringing up the PMGlobe command dialog, entering the name of the macro, and pressing Enter. The 'Macros' checkbox on the command dialog means that macros will be searched for before commands. If it isn't checked, the command "macro xxxx", where "xxxx" is the name of the macro, will invoke it. A macro can be called when PMGlobe is first started by specifying "MACRO filename" as a parameter to the PMGlobe call, for example: "start pmglobe macro mymacro" Macro names as a parameter or on a command may include an explicit drive and path, and if no extension is given then a default file extension of ".pmg" is added. NOTE: all PMGlobe commands should currently be considered experimental; the syntax and semantics of any command could change in future versions of PMGlobe (if any). General notes """"""""""""" 1. Angles may be specified in decimal form, such as -30 or +45.5, where for latitude and longitude negative implies south of the equator or west of Greenwich respectively. The more usual format is also allowed (for example: 52ø30'10E) -- details below. In this document, the character "ø" is the degree character, encoded on IBM PC's as 248 (decimal) or 'F8'x (hexadecimal). Angles returned by QUERY or EXTRACT will always be in decimal form. 2. Times are specified and returned in seconds (with an optional sign for relative times). 3. Keywords are shown below in capitals; they may be entered in mixed or lower case. 4. Colors may also be in any case, and (with valid alternative spellings in parentheses) must be one of: White Gray (Grey) Black Red Green Blue Pink (Magenta) Cyan (Turquoise) Yellow DarkRed DarkGreen DarkBlue Purple (DarkPink, DarkMagenta) DarkCyan (DarkTurquoise) Brown. PaleGray (PaleGrey) is also allowed, for the Background color only. The dark colors (from DarkRed onwards) cannot be used for Land or Water coloring. A QUERY or EXTRACT will return the first shown name for each color, in uppercase. 5. The keyword "CENTER" may also be spelled as "CENTRE", and "COLOR" as (or in) a keyword may be spelled "COLOUR". 6. It is recommended that long-running macros (especially those that use the WAIT command) use the SET TITLE command to change the window title to indicate that the macro is running. The title should be restored to its previous value if halted (see FASTSPIN.PMG, for example). Good macros will also allow for asynchronous alteration of viewpoint, etc., due to use of the pull-down menus. 7. Graphics (drawn with the GLINE command) are shown above any grid lines, and underneath any markers, clocks, and marks. Any tracks (drawn using the Distance Calculator, or using the TRACK option on graphics commands) are drawn immediately above any graphics. Commands in alphabetical order """""""""""""""""""""""""""""" CLOSE Close PMGlobe (as though Close had been selected in the System menu). EXTRACT items Used for obtaining the values of various PMGlobe settings for use with a REXX macro. 'Items' is a list of one or more keywords, as given in the QUERY and SET commands below. The values of the specified items are placed into REXX variables of the same name. (See above for a simple example.) GERASE [DRAW|TRACK] Erases either all DRAW graphics or all TRACK graphics. DRAW is the default; TRACK is normally only used by PMGlobe, for drawing tracks. GLINE lat lon [DRAW|TRACK] Draws either a DRAW or a TRACK line from the current point to the point specified, and then makes the specified point the current point. DRAW is the default, and draws the line in the color set by DRAWCOLOR. TRACK is normally only used by PMGlobe, for drawing tracks, and draws the line in the color set by TRACKCOLOR. If no current point has been set (by GMOVE) before this command is used, latitude 0 and longitude 0 are used. GMOVE lat lon [DRAW|TRACK] Sets the current point for either DRAW or TRACK graphics. DRAW is the default, and sets the current point for DRAW graphics. TRACK is normally only used by PMGlobe, and sets the current point for TRACK graphics. FONT name [SIZE height] [COLOR color] [FACE facename] Defines a font, with nickname 'name'. SIZE sets the font size (total height in points), and FACE specifies an OS/2 outline font (e.g., "Helvetica", "Times New Roman", etc.). If no FACE is specified then the default system proportional font and size is used, and SIZE is ignored. The default size for all other fonts is 12 points. See also the additional notes below. The color for a font is specified using the COLOR keyword and one of the colors listed above. The default color is Yellow. Fonts may not be redefined. The default system proportional font is predefined with the nickname 'Default'. MACRO file [argumentstring] Invoke the specified macro, a REXX program. The macro should be in the working directory for the application, or have its path specified. If no filename extension is given, one of ".pmg" is added. The remainder of the command is passed as the argument to the macro (accessible in REXX by the PARSE ARG instruction or ARG(1) built-in function). Note: At the highest level, macros run as a single separate thread. Macros may invoke each other, using the MACRO command, up to a depth of ten (other than this, only one macro can be running at a time). All macros that are running will be halted by Ctrl-Break, or by selecting 'Halt macro' from the menus or the command dialog. MARK lat lon DELETE or MARK lat lon [MARKER m] [X x-offset] [Y y-offset] [CLOCK t-offset] [LABEL text] Delete or add a mark from or to the displayed globe. Latitude and Longitude (lat lon) are always required. If DELETE is used, the mark must have been added before, and is deleted. If more than one mark have the same latitude and longitude then the most recently added is deleted. If DELETE is not used, then a new mark is added. The point will be marked according to the setting of of SET MARKER (default "+") at the time of the MARK command, unless overridden by the option MARKER. The value, m, of the marker can be any of ".", "+", "x", "X", or "OFF" for various shapes of marker. "!" may be used for a tiny (single-pel) marker. The color used for a mark is the current drawing color, as set by 'SET DRAWCOLOR color', at the time of the MARK command. If none was set then White is used. A mark may have a text associated with it, described by the CLOCK and LABEL options. This text is displayed with the start of the baseline at an offset from the mark as determined by the X and Y options; the offsets are given in pels, up to 1000, and may be positive or negative, or CENTER. The default X and Y offsets (x-offset and y-offset) are +3. If the text would extend beyond the bounds of the square enclosing the globe, then it is shifted in order to stay within bounds (if possible). If CLOCK is specified, t-offset describes the current GMT offset of the mark in seconds, and the text begins with the time calculated using this. This time is shown in 24-hour or civil format, depending on the setting of CLOCKCIVIL, and is refreshed according to the REFRESH setting. Use the CLOCKDAY setting for an additional tomorrow/yesterday indication (+/-). If LABEL is specified, it must be the last option on the command: the remainder of the command, after the keyword LABEL and one blank, forms the label part of the text, which follows any clock and may be up to 100 characters. The font used for the text is the current font, as set by 'SET FONT nickname', at the time of the MARK command. If none is set then the default system font is used. Markers, clocks, and labels can be included or excluded as a group by using the MARKERS, CLOCKS, and LABELS settings. None of these are shown if the window size is less than or equal to 64 pels in either dimension (for example, if the globe is minimized to the desktop). MESSAGE text Display text in a message box. The message box can be moved, and does not inhibit interaction with the globe or distance calculator. The MESSAGE command waits until the "OK" pushbutton on the message box is selected or the message box is closed. Commands are currently limited to 200 characters, so the longest message possible is 192 characters. REDRAW [ALL] Initiates a redrawing of the Globe. Normally a REDRAW is automatic at the end of a macro or (if the box on the dialog is checked) after a command is entered from the command dialog. The REDRAW command is provided for long-running macros. The command does not wait until redrawing is complete. The ALL option requests that all features of the globe are redrawn, including any grid lines and marks (normally only those features that have changed since the last draw are drawn). QUERY items Queries the state of various PMGlobe settings. 'items' is a list of one or more keywords. Currently the result is displayed using PMprintf; to see the results the PMprintf console must be active. (PMprintf is an IBM developer's tool; if you do not have access to this, use the EXTRACT command in a macro, followed by the MESSAGE command to display values, etc.) Any item that can be set by the SET command (see below) may also be queried. The value of any item that may be set or queried may also be obtained by a macro, using the EXTRACT command. PMprintf is not needed in order to use these values in a macro. Valid items are: ACTIVE ON if the globe window is the active window, else OFF CLOCKMARKS number of clocks set using the MARK command DAYOFFSET time offset due to daylight savings (in seconds), or "UNKNOWN" DIAMETER globe diameter in pels (0 if unknown) FONTS number of fonts defined using the FONT command GMTOFFSET base time offset from GMT (in seconds), or "UNKNOWN" MARKS number of marks set using the MARK command SETNAME 'application name' for .INI settings (up to 25 characters) SUNLAT latitude at which sun is overhead (x.xxx), or "UNKNOWN" SUNLON longitude at which sun is overhead (x.xxx), or "UNKNOWN" (multiply by -4 to get time in minutes from solar noon) VERSION PMGlobe version number VERSIONB Version bits: always 32 for PMGLOBE2.EXE ZONEABBREV timezone abbreviation (3 or 4 characters, or "???" if unknown) SET item newvalue Changes the state of various PMGlobe settings. Item is one of the listed keywords. The value of any item that can be SET can also be queried using the QUERY command, or obtained by a macro using the EXTRACT command (see above). Flags (items that are either ON or OFF) can also be set to INVERT, which changes the state of the flag from ON to OFF or vice versa. Valid items are: BACKCOLOR set the color of the background (names as given above) CLOCKCIVIL use 12-hour clock format for any clocks (ON/OFF) CLOCKDAY add flag (+ for tomorrow, - for yesterday) to clocks (ON/OFF) CLOCKS display the clocks on marks (ON/OFF) CROSSHAIR use cross-hair cursor when over globe (ON/OFF) DESKTOP make PMGlobe the bottommost window (ON/OFF) DRAWCOLOR set the color for drawing marks and graphics (names as above) ERRORBOX display command errors in a message box (ON/OFF) FONT sets the current font, by nickname GRIDCOLOR set the color of grid lines (names as above) GRIDLAT grid latitude line frequency (0/10/15/30/90) GRIDLON grid longitude line frequency (0/10/15/30) GRIDPOLAR show grid polar circles (ON/OFF) GRIDTROPIC show grid tropics (ON/OFF) IDLEDRAW draw map at low (IDLE+1) priority (ON/OFF) LABELS display the labels on marks (ON/OFF) LANDCOLOR set the color used for land at its brightest (names as above) MARGIN percentage border to allow around globe (0->49.999%) MARKER current default marker (".", "+", "x", "X", or "OFF") MARKERS display the markers on marks (ON/OFF) REFRESH current refresh interval (in seconds, max 24 hours) SHADING '3-D' shading (ON/OFF) SHOWDRAW show (update) picture of globe as it is calculated (ON/OFF) STARLIGHT 'star' lighting (ON/OFF) -- implies SUNLIGHT ON and SPACE ON SUNLIGHT 'sun' lighting (ON/OFF) SPACE 'earth from space' lighting (ON/OFF) -- implies SUNLIGHT ON TITLE window and task list title (max 50 characters) TRACKCOLOR set the color for drawing tracks (names as above) TWILIGHT degrees of twilight shown (max 18 degrees) USEROFFSET time to add to real time (seconds, max +/- one year) VIEWLAT latitude of center of view (x.xxx) VIEWLON longitude of center of view (x.xxx) WATERCOLOR set the color used for lakes and seas (names as above) The following settings are for development use only; the effect of each is not defined: DIAG send diagnostic messages to PMprintf (ON/OFF) DIAGMSG display PM client messages to PMprintf (ON/OFF) TEST controls certain test functions (ON/OFF) WAIT [REDRAW] [time] [+time] Wait until a redraw is completed, or until a particular time-of-day, or for a certain length of time from now. "time" is in hours, with optional minutes and seconds indicated by colons (for example, +0:20 would mean "wait for twenty minutes"). If a specific time of day is given and is earlier than the current time of day, then the next day is assumed. Multiple times (absolute, relative, or mixed) may be specified, and WAIT will return when the earliest is reached. The maximum wait time is 24 hours (+24). If REDRAW is specified, then a REDRAW is started automatically, and WAIT will return when the redraw is complete or any time condition specified is met, whichever happens earlier. Any WAIT is also ended by Ctrl-Break, or by selecting 'Halt macro' from the menus or the command dialog. Changing fonts """""""""""""" The fonts used for any clocks and labels on the MARK command can be changed by first defining a new font (with the FONT command) and then making the new font the current font (with the SET FONT command) before issuing the MARK command. The FONT command uses OS/2's facilities for choosing the 'nearest outline font'; if no good match is found (for example, no font with the specified face name exists) then the default system bitmap font is used. The face name on a font definition should match the OS/2 font name for an outline font exactly (for example "Helvetica", not "helvetica"). It can be difficult to find a list of the fonts available; one way you may be able to find one (if you have a printer installed) is to look at the font installation panel for the printer driver you are using. (Click mouse button 2 on the printer icon, then open Settings. Select the Printer Driver page, then click button 2 on the driver icon and select Settings again, then Fonts.) The following should always be available: 'Courier', 'Helvetica', 'Times New Roman', and 'Symbol Set'. The first three of these may be followed by 'Bold', 'Italic', or 'Bold Italic'. Example: /* ORIGIN.PMG -- Show the origin in a Large font */ 'font classic size 18 color red face Times New Roman Italic' 'set font classic' 'mark 0 0 y centre label The Origin' Formats allowed for specifying degrees """""""""""""""""""""""""""""""""""""" A degree value may be specified in in degree-minutes-seconds format, or in degree.decimal format. If the degree value is specifying a latitude or longitude, then it may be followed by one of the characters N, S, E, W (in either case), as appropriate. The default is N (North) for latitude and E (East) for longitude. A leading minus sign is allowed in either format, and negates the direction implied by any N, E, S, or W. A leading plus sign is also allowed; it has no effect. No blanks are allowed: the seconds, or seconds and minutes, may be omitted, as may be insignificant leading zeros. The syntax is therefore one of: [+|-][d]d[o[m]m['[s]s["]]][x] [+|-][d]d[.[[d]d]d][x] where the degree indicator in the first format may be either the letter O (either case) or the true degree character (ø, ASCII 248 on IBM PCs and PS/2s). Examples (all specifying a negative angle of 12 degrees 30 minutes): 12ø30'S -12ø30 12ø30W -12.5 12ø30'0"S -12ø30'00N -12.500E 12o30s -------- Mike Cowlishaw, IBM UK Laboratories