home *** CD-ROM | disk | FTP | other *** search
/ IBM CD Showcase / OS2_CD_ROM.iso / smce0001 / sware / os2progs.exe / pmglobe / pmglobex.doc < prev    next >
Encoding:
Text File  |  1992-09-24  |  16.4 KB  |  363 lines
  1.  
  2. PMGlobe -- an OS/2 Presentation Manager Globe -- Extended functions
  3. ===================================================================
  4.  
  5. Copyright (c) IBM Corporation, 1991, 1992.
  6.  
  7.  
  8. PMGlobe commands, and how they are used
  9. """""""""""""""""""""""""""""""""""""""
  10. This document lists the PMGlobe commands that are currently implemented.
  11. These may be invoked from a PMGlobe macro (a program written in REXX),
  12. or directly from the command dialog (which can be displayed by pressing
  13. Escape while PMGlobe has the focus).  The command dialog allows editing
  14. of the command, using Insert, Delete, Backspace, and Cursor Left/Right;
  15. it also has a simple 'retrieve' function, controlled by the Cursor
  16. Up/Down keys.
  17.  
  18. To use commands from a macro, edit (perhaps with the OS/2 System Editor)
  19. a plain ASCII file such as the TEST.PMG supplied with PMGlobe and
  20. reproduced in part here:
  21.  
  22.   /* Sample (test) macro */
  23.   /* Get the version information and set a new title */
  24.   'extract version versionb'
  25.   'set title PMGlobe -' version '('versionb'-bit)'
  26.  
  27.   /* Mark and label some chosen cities */
  28.   "mark  51.5     0   label London"
  29.   "mark  37.8  -122.4 label San Francisco"
  30.   "mark -33.7   151.3 label Sydney"
  31.  
  32. This is a very simple REXX program that consists almost entirely of
  33. commands (see SPIN.PMG for a more typical macro).  After saving the
  34. file, it can by run by simply bringing up the PMGlobe command dialog,
  35. entering the name of the macro, and pressing Enter.
  36.  
  37. The 'Macros' checkbox on the command dialog means that macros will be
  38. searched for before commands.  If it isn't checked, the command "macro
  39. xxxx", where "xxxx" is the name of the macro, will invoke it.
  40.  
  41. A macro can be called when PMGlobe is first started by specifying "MACRO
  42. filename" as a parameter to the PMGlobe call, for example:
  43.  
  44.   "start pmglobe macro mymacro"
  45.  
  46. Macro names as a parameter or on a command may include an explicit drive
  47. and path, and if no extension is given then a default file extension of
  48. ".pmg" is added.
  49.  
  50. Note: all PMGlobe commands should currently be considered experimental;
  51. ****  the syntax and semantics of any command could change in future
  52.       versions of PMGlobe (if any).
  53.  
  54.  
  55. General notes
  56. """""""""""""
  57. -- Angles may be specified in decimal form, such as -30 or +45.5, where
  58.    for latitude and longitude negative implies south of the equator or
  59.    west of Greenwich respectively.  The more usual format is also
  60.    allowed (for example: 52°30'10"E) -- details below.  Angles
  61.    returned by QUERY or EXTRACT will always be in decimal form.
  62.  
  63. -- Times are specified and returned in seconds (with an optional sign
  64.    for relative times).
  65.  
  66. -- Keywords are shown below in capitals; they may be entered in mixed or
  67.    lower case.
  68.  
  69. -- Colors may also be in any case, and (with valid alternative spellings
  70.    in parentheses) must be one of: White Gray (Grey) Black Red Green
  71.    Blue Pink (Magenta) Cyan (Turquoise) Yellow DarkRed DarkGreen
  72.    DarkBlue Purple (DarkPink, DarkMagenta) DarkCyan (DarkTurquoise)
  73.    Brown.  PaleGray (PaleGrey) is also allowed, for the Background color
  74.    only.  The dark colors (from DarkRed onwards) cannot be used for Land
  75.    or Water coloring.
  76.    A QUERY or EXTRACT will return the first shown name for each color,
  77.    in uppercase.
  78.  
  79. -- The keyword "CENTER" may also be spelled as "CENTRE", and "COLOR"
  80.    as (or in) a keyword may be spelled "COLOUR".
  81.  
  82. -- It is recommended that long-running macros (especially those that use
  83.    the WAIT command) use the SET TITLE command to change the window
  84.    title to indicate that the macro is running.  Good macros will also
  85.    allow for asynchronous alteration of viewpoint, etc., due to use of
  86.    the pull-down menus.
  87.  
  88.  
  89. Commands in alphabetical order
  90. """"""""""""""""""""""""""""""
  91. CLOSE
  92.  
  93.   Close PMGlobe (as though Close had been selected in the System menu).
  94.  
  95. EXTRACT items
  96.  
  97.   Used for obtaining the values of various PMGlobe settings for use
  98.   with a REXX macro.
  99.  
  100.   'Items' is a list of one or more keywords, as given in the QUERY and
  101.   SET commands below. The values of the specified items are placed into
  102.   REXX variables of the same name.  (See above for a simple example.)
  103.  
  104. FONT name [SIZE height] [COLOR color] [FACE facename]
  105.  
  106.   Defines a font, with nickname 'name'.  SIZE sets the font size
  107.   (total height in points), and FACE specifies an OS/2 outline font
  108.   (e.g., "Helvetica", "Times New Roman", etc.).  If no FACE is specified
  109.   then the default system proportional font and size is used, and SIZE
  110.   is ignored.  The default size for all other fonts is 12 points.  See
  111.   also the additional notes below.
  112.  
  113.   The color for a font is specified using the COLOR keyword and one
  114.   of the colors listed above.  The default color is Yellow.
  115.  
  116.   Fonts may not be redefined.  The default system proportional font is
  117.   predefined with the nickname 'Default'.
  118.  
  119. MACRO file [argumentstring]
  120.  
  121.   Invoke the specified macro, a REXX program.  The macro should be in
  122.   the working directory for the application, or have its path specified.
  123.   If no filename extension is given, one of ".pmg" is added.  The
  124.   remainder of the command is passed as the argument to the macro
  125.   (accessible in REXX by the PARSE ARG instruction or ARG(1) built-in
  126.   function).
  127.  
  128.   Note:  At the highest level, macros run as a single separate thread.
  129.   Macros may invoke each other, using the MACRO command, up to a depth
  130.   of ten (other than this, only one macro can be running at a time).
  131.   All macros that are running will be halted by Ctrl-Break, or by
  132.   selecting 'Halt macro' from the menus or the command dialog.
  133.  
  134. MARK lat lon [MARKER m] [X x-offset] [Y y-offset] [CLOCK t-offset] [LABEL text]
  135. MARK lat lon DELETE
  136.  
  137.   Add or delete a mark to or from the displayed globe.  Latitude and
  138.   Longitude (lat lon) are always required.  If DELETE is used, the mark
  139.   must have been added before, and is deleted.  If more than one mark
  140.   have the same latitude and longitude then the most recently added is
  141.   deleted.
  142.  
  143.   If DELETE is not used, then a new mark is added.  The point will be
  144.   marked according to the setting of of SET MARKER (default "+") at the
  145.   time of the MARK command, unless overridden by the option MARKER.  The
  146.   value, m, of the marker can be any of ".", "+", "x", "X", or "OFF" for
  147.   various shapes of marker.  "!" may be used for a tiny (single-pel)
  148.   marker.
  149.  
  150.   The color used for a mark is the current drawing color, as set by 'SET
  151.   DRAWCOLOR color', at the time of the MARK command.  If none was set
  152.   then White is used.
  153.  
  154.   A mark may have a text associated with it, described by the CLOCK and
  155.   LABEL options.  This text is displayed with the start of the baseline
  156.   at an offset from the mark as determined by the X and Y options; the
  157.   offsets are given in pels, up to 1000, and may be positive or
  158.   negative, or CENTER.  The default X and Y offsets (x-offset and
  159.   y-offset) are +3. If the text would extend beyond the bounds of the
  160.   square enclosing the globe, then it is shifted in order to stay within
  161.   bounds (if possible).
  162.  
  163.   If CLOCK is specified, t-offset describes the current GMT offset of
  164.   the mark in seconds, and the text begins with the time calculated
  165.   using this. This time is shown in 24-hour or civil format, depending
  166.   on the setting of CLOCKCIVIL, and is refreshed according to the
  167.   REFRESH setting.  Use the CLOCKDAY setting for an additional
  168.   tomorrow/yesterday indication (+/-).
  169.  
  170.   If LABEL is specified, it must be the last option on the command: the
  171.   remainder of the command, after the keyword LABEL and one blank, forms
  172.   the label part of the text, which follows any clock and may be up to
  173.   100 characters.
  174.  
  175.   The font used for the text is the current font, as set by 'SET FONT
  176.   nickname', at the time of the MARK command.  If none is set then the
  177.   default system font is used.
  178.  
  179.   Markers, clocks, and labels can be included or excluded as a group by
  180.   using the MARKERS, CLOCKS, and LABELS settings.  None of these are
  181.   shown if the window size is less than or equal to 64 pels in either
  182.   dimension (for example, if the globe is minimized to the desktop).
  183.  
  184. MESSAGE text
  185.  
  186.   Display text in a message box.  The message box can be moved, and does
  187.   not inhibit interaction with the globe or distance calculator.  The
  188.   MESSAGE command waits until the "OK" pushbutton on the message box is
  189.   selected or the message box is closed.  Commands are currently limited
  190.   to 200 characters, so the longest message possible is 192 characters.
  191.  
  192. REDRAW [ALL]
  193.  
  194.   Initiates a redrawing of the Globe.  Normally a REDRAW is automatic at
  195.   the end of a macro or (if the box on the dialog is checked) after a
  196.   command is entered from the command dialog.  The REDRAW command is
  197.   provided for long-running macros.  The command does not wait until
  198.   redrawing is complete.
  199.  
  200.   The ALL option requests that all features of the globe are redrawn,
  201.   including any grid lines and marks (normally only those features that
  202.   have changed since the last draw are drawn).
  203.  
  204. QUERY items
  205.  
  206.   Queries the state of various PMGlobe settings.  'items' is a list of
  207.   one or more keywords.  Currently the result is displayed using
  208.   PMprintf; to see the results the PMprintf console must be active.
  209.   (PMprintf is an IBM developer's tool; if you do not have access to
  210.   this, use the EXTRACT command in a macro, followed by the MESSAGE
  211.   command to display values, etc.)
  212.  
  213.   Any item that can be set by the SET command (see below) may also be
  214.   queried.  The value of any item that may be set or queried may also be
  215.   obtained by a macro, using the EXTRACT command.  PMprintf is not
  216.   needed in order to use these values in a macro.
  217.  
  218.   Valid items are:
  219.  
  220.   ACTIVE     -- ON if the globe window is the active window, else OFF
  221.   CLOCKMARKS -- number of clocks set using the MARK command
  222.   DAYOFFSET  -- time offset due to daylight savings (in seconds), or "UNKNOWN"
  223.   DIAMETER   -- globe diameter in pels (0 if unknown)
  224.   FONTS      -- number of fonts defined using the FONT command
  225.   GMTOFFSET  -- base time offset from GMT (in seconds), or "UNKNOWN"
  226.   MARKS      -- number of marks set using the MARK command
  227.   SUNLAT     -- latitude at which sun is overhead (x.xxx), or "UNKNOWN"
  228.   SUNLON     -- longitude at which sun is overhead (x.xxx), or "UNKNOWN"
  229.                 (multiply by -4 to get time in minutes from solar noon)
  230.   VERSION    -- PMGlobe version number
  231.   VERSIONB   -- Version bits: always 32 for PMGLOBE2.EXE
  232.   ZONEABBREV -- timezone abbreviation (3 or 4 characters, or "???" if unknown)
  233.  
  234. SET item newvalue
  235.  
  236.   Changes the state of various PMGlobe settings.  Item is one of the
  237.   listed keywords.  The value of any item that can be SET can also be
  238.   queried using the QUERY command, or obtained by a macro using the
  239.   EXTRACT command (see above).
  240.  
  241.   Flags (items that are either ON or OFF) can also be set to INVERT,
  242.   which changes the state of the flag from ON to OFF or vice versa.
  243.  
  244.   BACKCOLOR  -- set the color of the background (names as given above)
  245.   CLOCKCIVIL -- use 12-hour clock format for any clocks (ON/OFF)
  246.   CLOCKDAY   -- add flag (+ for tomorrow, - for yesterday) to clocks (ON/OFF)
  247.   CLOCKS     -- display the clocks on marks (ON/OFF)
  248.   DESKTOP    -- make PMGlobe the bottommost window (ON/OFF)
  249.   DRAWCOLOR  -- set the color for drawing marks (names as given above)
  250.   ERRORBOX   -- display command errors in a message box (ON/OFF)
  251.   FONT       -- sets the current font, by nickname
  252.   GRIDCOLOR  -- set the color of grid lines (names as given above)
  253.   GRIDLAT    -- grid latitude line frequency (0/10/15/30/90)
  254.   GRIDLON    -- grid longitude line frequency (0/10/15/30)
  255.   GRIDPOLAR  -- show grid polar circles (ON/OFF)
  256.   GRIDTROPIC -- show grid tropics (ON/OFF)
  257.   IDLEDRAW   -- draw map at low (IDLE+1) priority (ON/OFF)
  258.   LABELS     -- display the labels on marks (ON/OFF)
  259.   LANDCOLOR  -- set the color used for land at its brightest
  260.   MARGIN     -- percentage border to allow around globe (0->49.999%)
  261.   MARKER     -- current default marker (".", "+", "x", "X", or "OFF")
  262.   MARKERS    -- display the markers on marks (ON/OFF)
  263.   REFRESH    -- current refresh interval (in seconds, max 24 hours)
  264.   SHADING    -- '3-D' shading (ON/OFF)
  265.   SHOWDRAW   -- show (update) picture of globe as it is calculated (ON/OFF)
  266.   STARLIGHT  -- 'star' lighting (ON/OFF) -- implies SUNLIGHT ON and SPACE ON
  267.   SUNLIGHT   -- 'sun' lighting (ON/OFF)
  268.   SPACE      -- 'earth from space' lighting (ON/OFF) -- implies SUNLIGHT ON
  269.   TITLE      -- window and task list title (max 50 characters)
  270.   TWILIGHT   -- degrees of twilight shown (max 18 degrees)
  271.   USEROFFSET -- time to add to real time (seconds, max +/- one year)
  272.   VIEWLAT    -- latitude of center of view  (x.xxx)
  273.   VIEWLON    -- longitude of center of view (x.xxx)
  274.   WATERCOLOR -- set the color used for lakes and seas
  275.  
  276.   The following settings are for development use only; the effect of
  277.   each is not defined:
  278.  
  279.   DIAG       -- send diagnostic messages to PMprintf (ON/OFF)
  280.   DIAGMSG    -- display PM client messages to PMprintf (ON/OFF)
  281.   TEST       -- controls certain test functions (ON/OFF)
  282.  
  283. WAIT [REDRAW] [time] [+time]
  284.  
  285.   Wait until a redraw is completed, or until a particular time-of-day,
  286.   or for a certain length of time from now.  "time" is in hours, with
  287.   optional minutes and seconds indicated by colons (for example, +0:20
  288.   would mean "wait for twenty minutes").  If a specific time of day is
  289.   given and is earlier than the current time of day, then the next day
  290.   is assumed.  Multiple times (absolute, relative, or mixed) may be
  291.   specified, and WAIT will return when the earliest is reached.  The
  292.   maximum wait time is 24 hours (+24).
  293.  
  294.   If REDRAW is specified, then a REDRAW is started automatically, and
  295.   WAIT will return when the redraw is complete or any time condition
  296.   specified is met, whichever happens earlier.
  297.  
  298.   Any WAIT is also ended by Ctrl-Break, or by selecting 'Halt macro'
  299.   from the menus or the command dialog.
  300.  
  301.  
  302. Changing fonts
  303. """"""""""""""
  304. The fonts used for any clocks and labels on the MARK command can be
  305. changed by first defining a new font (with the FONT command) and then
  306. making the new font the current font (with the SET FONT command) before
  307. issuing the MARK command.
  308.  
  309. The FONT command uses OS/2's facilities for choosing the 'nearest
  310. outline font'; if no good match is found (for example, no font with the
  311. specified face name exists) then the default system bitmap font is used.
  312.  
  313. The face name on a font definition should match the OS/2 font name for
  314. an outline font exactly (for example "Helvetica", not "helvetica").  It
  315. can be difficult to find a list of the fonts available; one way you may
  316. be able to find one (if you have a printer installed) is to look at the
  317. font installation panel for the printer driver you are using.  (Click
  318. mouse button 2 on the printer icon, then open Settings. Select the
  319. Printer Driver page, then click button 2 on the driver icon and select
  320. Settings again, then Fonts.)  The following should always be available:
  321. 'Courier', 'Helvetica', 'Times New Roman', and 'Symbol Set'.  The first
  322. three of these may be followed by 'Bold', 'Italic', or 'Bold Italic'.
  323.  
  324. Example:
  325.  
  326.   /* ORIGIN.PMG -- Show the origin in a Large font */
  327.   'font classic  size 18  color red  face Times New Roman Italic'
  328.   'set font classic'
  329.   'mark 0 0 y centre label The Origin'
  330.  
  331.  
  332. Formats allowed for specifying degrees
  333. """"""""""""""""""""""""""""""""""""""
  334. A degree value may be specified in in degree-minutes-seconds format, or
  335. in degree.decimal format.
  336.  
  337. If the degree value is specifying a latitude or longitude, then it
  338. may be followed by one of the characters N, S, E, W (in either case),
  339. as appropriate.  The default is N (North) for latitude and E (East) for
  340. longitude.  A leading minus sign is allowed in either format, and negates
  341. the direction implied by any N, E, S, or W.  A leading plus sign is also
  342. allowed; it has no effect.
  343.  
  344. No blanks are allowed: the seconds, or seconds and minutes, may
  345. be omitted, as may be insignificant leading zeros.  The syntax is
  346. therefore one of:
  347.  
  348.   [+|-][d]d[o[m]m['[s]s["]]][x]
  349.   [+|-][d]d[.[[d]d]d][x]
  350.  
  351. where the degree indicator in the first format may be either the letter
  352. O (either case) or the true degree character (°, ASCII 248 on IBM PCs
  353. and PS/2s).
  354.  
  355. Examples (all specifying a negative angle of 12 degrees 30 minutes):
  356.  
  357.      -12.5          -12°30         12°30W         12°30'S
  358.       12°30'0"S     -12°30'00N    -12.500E        12o30s
  359.  
  360. ----------
  361.  
  362. Mike Cowlishaw, IBM UK Laboratories
  363.