Command positional parameters

Command positional parameters provide input to a command and must be entered in the exact order specified. Use them in commands that have options which the user must always enter. One advantage of positional parameters is minimizing the number of keystrokes a user types. Be careful not to negate this advantage by using so many positional parameters that the user can't remember them all.

Keywords

Like command positional parameters, keywords are used for entering command input. Unlike command positional parameters, they are optional for most McIDAS-X commands and can be entered in any order as long as they follow command positional parameters and precede quoted text.

Keyword parameters are often used to clarify commands with many complicated options. Although keywords can occur in any order, their positional parameters must be entered in the order indicated. Since users don't always specify all keyword positional parameters in a command, be sure to assign them reasonable defaults.

In addition to the keywords that an application has built into it, McIDAS-X has six global keywords, which are common to all McIDAS-X commands:

• DEV= specifies the destination device of the text output generated by a command.
• FONT= specifies the font for drawing text on the McIDAS-X Image Window.
• PAN= specifies a frame's panel number.
• TCOL= specifies the color for command text output in the text window.
• TWIN= specifies the destination text window to route the command output.
• VIRT= specifies a virtual graphics number to write graphical output.

You can retrieve the parameters for these global keywords in your applications, as long as you don't change their functionality.

Quoted text

Quoted text input is most often used when strings entered by a user require blank spaces. Each application can contain only one quote string and it must be the last part of the command the user enters. Using quote fields in McIDAS-X commands is relatively easy from the McIDAS-X Text and Command Window; running McIDAS-X commands with quote strings from Unix shell prompts is more difficult. For this reason, the preferred method for entering strings with spaces in them from the command line is to use a positional or keyword parameter and surround the string with single quotes.

Functions for extracting values from a command line

The McIDAS-X library functions for extracting individual values from the command line are listed alphabetically in the table below. These functions have similar calling sequences.

You can use any of these functions, except Mccmdquo/mccmdquo , to extract information from any command or keyword positional parameter.

All of the functions in the table above, except Mccmdquo /mccmdquo , expect the following arguments:

• a keyword name, which can be a blank string (" ") if you are retrieving a command positional parameter
• a position number, 1-based
• a default value
• a variable to store the result

These functions, except Mccmdstr /mccmdstr , also expect the following additional information:

• a character string description of the requested value, which is printed if the user enters an incorrect syntax or a value out of range for this parameter
• a minimum and maximum acceptable value for this parameter; range checking can be inactivated by setting the minimum acceptable value greater than the maximum value

All the functions above perform similar operations when retrieving data from the command line, including:

• verifying the user-entered value is in an appropriate syntax; you can type the command ARGHELP from the McIDAS-X Text and Command Window to receive a list of the acceptable syntaxes
• verifying the user-entered value is within an acceptable range
• returning a proper default value if the user didn't enter a value
• verifying that there is enough room in the destination variable to contain the user-entered value
• printing a message to standard error if the user enters an inappropriate value; error messages are discussed later in this chapter in the section titled Text messages
• returning a status code to the calling routine

McIDAS-X uses a special syntax for identifying keyword names in these functions within an application. This syntax identifies a mandatory and an optional section, separated by a period. For example, if you use FRAME as a keyword in a command, it may be used in the above functions as FRA.ME to denote only the first three characters are mandatory. The table below shows some acceptable and unacceptable forms the user can enter.

Keyword names can be letters or numbers, as long as the name is unique; that is, you can't use COL.OR and COL.UMN in the same command.

Below is a description of each function for extracting values from a command line, along with examples.

Sample TEST command

The sample output in the examples below is based on the following user-entered command string for the program TEST. If you see the line goto 999 in the code fragments, it means: exit the command and return an error status.

 TEST LIST 4 END=X 4:30 STA=03-APR-1996 12:30 PAR=T TD HEAD=WI 'Dane County' "Home of the Black Wolf

Extracting a character string value

Use the mccmdstr function to extract a value from the command line as a character string. The code fragment below extracts the value from the first command positional parameter and puts it in the character string option .

character*12 default
character*12 option
default = ' '
ok = mccmdstr(' ', 1, default, option)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable option will contain the string LIST . If the user enters the string ABCDEFGHIJKLMN, an error occurs because option doesn't have room to store this string. The mccmdstr function prints the error message below and returns an error status.

TEST: first positional argument is too big --> ABCDEFGHIJKLMN
TEST: Must be a character string of no more that 12 chars.

The code below extracts the value of the second keyword positional parameter for the keyword HEAD and puts it in the character string mnhead.

character*12 default
character*24 mnhead
default = ' '
ok = mccmdstr('HEA.D', 2, default, mnhead)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable mnhead will contain the string Dane County. This string includes whitespace because the parameter is surrounded by single quotes on the command line. Note the mandatory and optional keyword components. This call will ignore a keyword named HEAP, while it will read a keyword named HEADER.

Extracting an integer value

Use the mccmdint function to extract a value from the command line as an integer value. The following code fragment extracts the value of the second positional parameter as an integer. The call to mccmdint also performs range checking to verify that the value entered by the user is within the range 1 to 9999. If the user doesn't enter a value for the second positional parameter, the default value of 1 is used.

parameter (MINFILE = 1, MAXFILE = 9999)
integer fileno
ok = mccmdint(' ', 2, 'File Number', 1, MINFILE, MAXFILE, fileno)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable fileno will contain the value 4. If the user enters the value 10000 for the second positional parameter, the range allowed in this mccmdint call is exceeded. Thus, mccmdint prints the following error message and returns an error status.

TEST: Invalid File Number.
TEST: 2nd positional argument is too big --> 10000
TEST: Must be valid 'File Number' integer value within range 1 thru 9999.

Extracting time information

The functions to extract time information, mccmddhr and mccmdihr , accept input in a variety of formats. To get a list of the acceptable formats, type the command ARGHELP TIME from the McIDAS-X Text and Command Window.

The following code fragment extracts the value of the second keyword positional parameter as an integer for the keyword START. Note that the call to mccmdihr also performs range checking to verify that the value entered by the user falls within the range 0 to 23:59:59. This is not done automatically, so you can also use these functions to extract an interval of time such as -18:45.

integer starttime
ok = mccmdihr('STA.RT', 2, 'Starting Time', 120000, 0, 235959, starttime)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable starttime contains the value 123000. If the user doesn't enter a value for the second keyword positional parameter for the START keyword, the value returned in starttime is the default of 120000.

Be careful when setting ranges and default values for the mccmdihr function and using the returned values. The format expected is hhmmss . To specify 15:00:00 as the default for a command, you must enter 150000 as the fourth parameter in mccmdihr . If you specify 15 for the default, the value returned will be 00:00:15.

The following code fragment extracts the value of the second keyword positional parameter as a double precision number for the keyword END. The default value is five hours. Note that range checking is turned off in this example by setting the minimum value, 99.0, greater than the maximum value, -99.0.

double precision endtime
ok = mccmddhr('END', 2, 'Ending Time', 5.0d0, 99.0d0, -99.0d0, endtime)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable endtime will contain the value 4.5.

Extracting date information

The function to extract date information, mccmdiyd , accepts input in a variety of formats. To get a list of the acceptable formats, type the command ARGHELP DATE from the McIDAS-X Text and Command Window.

The following code fragment extracts the value of the first keyword positional parameter for the keyword START. This call sets the default to the current day and does not perform range checking.

integer currentday
integer startday
ok = mcgetday(currentday)

ok = mccmdiyd('STA.RT', 1, 'Starting Day', currentday, 99, -99, startday)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable startday will contain the value 1996094.

Extracting a character string value from a quote field

Use the mccmdquo function sparingly when extracting a quote string that contains whitespace. The preferred method for retrieving parameters containing whitespace is to use the mccmdstr function and have the user enter the parameter with single quotes (') as shown in the mccmdstr section above.

The following code fragment extracts the value of the quote string.

character*256 quote
ok = mccmdquo(quote)
if (ok .lt. 0)then
  goto 999
endif

When the TEST command runs, the variable quote will contain the string Home of the Black Wolf . If this field is missing from the user command, the variable is set to blank characters.

Functions for interrogating the command line structure

Sometimes applications need to get information from the command line beyond the actual values entered by the user. The functions described in the table below provide these services.

Each function is described below, along with an example. The sample output is based on the user-entered command string for the program TEST, as shown in the section titled Sample TEST command above.

Verifying the validity of a keyword

Because of the complexity of the McIDAS-X command line, users will sometimes enter an incorrect keyword that is ignored and then not be able to determine why their command doesn't run properly. The mccmdkey function will verify that the keywords entered by the user are valid for the command. It compares the keywords the user enters with a list of acceptable keywords for a command and prints an error message if a discrepancy occurs. Additionally, mccmdkey checks your application to verify that it contains no ambiguous keywords; for example, COL.OR and COL.UMN.

The global keywords described earlier in this section are implicitly included in mccmdkey , so you don't need to include them in your list of keywords to be tested. Your cannot use the mccmdkey function if the keyword names in your command are not fixed; for example, cases where keyword names are related to data structures. Your program cannot predetermine the names the user may have entered; therefore, it cannot use mccmdkey .

The code fragment below shows how to validate the sample TEST command for the keywords END, FILE, PARAMETER, START and TITLE.

parameter (MAXKW = 5)
character*12 validkw(MAXKW)
data validkw/'END','FIL.E','PAR.AMETER','STA.RT','TIT.LE'/

ok = mccmdkey(MAXKW, validkw)
if (ok .lt. 0)then
  goto 999
endif

If the user enters the additional keyword argument COUNTRY=UK , the TEST command will output the following line to the McIDAS-X Text and Command Window and exit.

TEST: Invalid command keywords: COUNTRY=UK

Note that it is the programmer's responsibility to keep the keyword list used in mccmdkey consistent with the keywords actually used by the application. This checking can be turned off by the user by setting syskey word 15 to a non-zero value.

Retrieving a list of user-entered keywords

Sometimes an application needs to know exactly which keywords the user entered. The mccmdnam function will return this information. The code fragment below shows how to retrieve the list of user-entered keywords.

parameter (MAXKW = 5)
character*12 entered_kw(MAXKW)

n_ent = mccmdnam (MAXKW, entered_kw)
if (n_ent .lt. 0)then
  goto 999
endif

When the TEST command runs, the variables in this code fragment will contain the following values:

n_ent           = 4
entered_kw(1)       = 'END'
entered_kw(2)       = 'STA'
entered_kw(3)       = 'PAR'
entered_kw(4)       = 'TITLE'

Note that mccmdkey returns abbreviated values for the START and PARAMETERS keywords, since that is how they were entered on the command line.

Verifying the number of keyword parameters

When applications allow for multiple keyword positional parameters, you must be able to tell how many parameters the user actually included in the command. The mccmdnum function returns this information. The following code fragment extracts the number of keyword positional parameters that the user entered for the PARAMETER keyword.

integer n_parms

n_parms = mccmdnum('PAR.AMETER')

When the sample TEST command runs, n_parms will contain the value 2.

To find out how many command positional parameters the user entered, the code fragment would look like this:

n_parms = mccmdnum(' ')

Status codes

The command-line functions all return status codes. A non-negative value indicates a successful return. A value greater than zero indicates a successful return, but with additional information such as the parameter returned is the default value. A value less than zero indicates a problem, for example in the formatting or range checking. The argument fetching status codes are defined in the table below.

The status codes use the format abcd. The value in the a position indicates the parameter's location; for example, the command line or string table. The values in the b and c positions indicate the form of the value; for example, time or angle. The value in the d position indicates the status.

Reporting the state of the mouse buttons

The mcmoubtn function reports the state of the mouse buttons as soon as a mouse button event occurs. Button events include the following:

• a mouse button was up, but is now down
• a mouse button is being held down
• a mouse button was down, but is now up

Applications specify which of the above events triggers a response via the first argument of the mcmoubtn function. Once the event occurs, the state of each mouse button and the cursor's line and element position in the McIDAS-X Image Window are returned to the calling application.

Calling mcmoubtn inherently causes the application to sleep or idle. Thus, you can call it within tight, intensive loops without fear of saturating the processor. If, at any time, the desired mouse event does not occur within a two-minute time span, mcmoubtn returns a timeout status to the calling application. The application is free to call mcmoubtn again if that two-minute time span is not considered unusual.

The code fragment below, from the McIDAS-X ZLM command, monitors the mouse event status.

     parameter button_release=3
     ....
     
c---wait for mouse release
10  status=mcmoubtn(button_release,button(1),button(2),tvlin,tvele)

c---end mouse button sampling
   if((button(1).ne.0.and.button(2).ne.0).or.status.ne.0) then
       call beep(50,10)
       goto 100

c---on left mouse button press

   else if(button(1).ne.0) then

   ......

Note that the mcmoubtn function neither tests for nor protects against two applications using it at the same time. If several applications that call mcmoubtn are started concurrently, the results may be unpredictable.

Reporting the status of Alt G and Alt Q

The mcmoubtn function also indicates the status of the keyboard toggles Alt G and Alt Q, which are monitored by McIDAS-X similar to the mouse buttons. If you hold down the Alt key on the keyboard and press either the G or Q key, mcmoubtn will report that Alt G or Alt Q was pressed. These keyboard toggles are useful when you need to precisely position the cursor on the McIDAS-X Image Window and the act of clicking a mouse button may cause the mouse to move.

Defining cursor location, size, color and type

Use the functions below to change the appearance of the McIDAS-X cursor.

The values that these functions place into User Common are used by the mcimage program to define the appearance of the McIDAS-X cursor. The example below illustrates the use of these cursor functions.

    integer line, element
    integer height, width
    integer color
    integer type

    ..
C Define the new location of the cursor
    line = 200
    element = 351

C Define the new height and width; note: these values must be ODD
    height = 23
    width = 13

C Reassign the cursor to be displayed in color level 3
    color = 3

C Define the new type; 1=box, 2=cross-hair, 3=both, 4=solid,
C 5=bullseye
    type = 3

C Now make the change:

    call putcur ( line, element )
    call sizcur ( height, width )
    call colcur ( color )
    call typcur ( type )

...

Routing text

Text can be sent, or routed, to several destinations, as shown in the table below. Users enter the McIDAS-X global keyword, DEV, to specify the destination device of the text output generated by a command.

The user enters the disposition of the text messages as a series of three, contiguous disposition types in this order: standard, error, debug . For example, if the user enters DEV=CCC, all standard, error and debug messages are written on the McIDAS-X Text and Command Window. Entering DEV=CNN displays only the standard messages on the window; the error and debug messages are suppressed. The default is DEV=CCN, meaning the standard and error messages are written on the McIDAS-X Text and Command Window and the debug messages are suppressed.

Generating text

To display standard, error and debug messages in C or Fortran applications, use the library functions shown in the table below.

The sample code below illustrates the use of each message type in a Fortran application.

      subroutine main0
C $ ABCD - illustrates message disposition

      implicit none

c --- external functions
      integer mccmdint   ! integer arg fetch

c --- internal variables
      integer parameter  ! 1st parameter

c --- get the first positional parameter from the command line
      if( mccmdint(' ',1,'1st Parameter',1,1,0,parameter).lt.0)
    & return

      call sdest('STANDARD -- First parameter =',parameter)
      call edest('ERROR -- First parameter =',parameter)
      call ddest('DEBUG -- First parameter =',parameter)

      return
      end

The following table shows where text would be routed, based on the application, ABCD, presented in the code above.

If you don't have an integer value to be printed at the end of sdest, edest or ddest calls, specify zero as the second argument. These functions don't print an integer value of zero. To print a zero, format it into the string. The lines below show the use of a Fortran write to format a text message.

   write(cline,fmt='(a18,1x,f9.2)')'the temperature is',temp
   call sdest(cline,0)

You can create the same formatted output with the following C call.

(void) Mcprintf ("the temperature is %9.2f\n ",temp);

Basic McIDAS-X graphics techniques

This section describes the techniques that you will most often use when working with the McIDAS-X graphics subsystem. Figure 4-4 below shows
a graphic produced by the sample GRAF application when run from a McIDAS-X session with no arguments and a frame size of 480 lines by
640 elements.

Figure 4-4. This GRAF.PGM output is the result of a McIDAS-X session run with
no arguments and a frame size of 480 lines by 640 elements.

To produce such a graphic, an application must do the following:

• initialize the graphics subsystem
• draw lines
• write text and numbers
• flush the graphics subsystem's buffers
• close, or bind off, the graphics subsystem

These procedures are described below.

Initializing the graphics subsystem

Before you can use the McIDAS-X graphics subsystem, you must initialize it with a call to initpl as shown in the following code fragment from GRAF.PGM, lines 88 to 93; frame is the number of the frame where the graphics will appear and width is the line width, in pixels. Specify zero to use the current frame and width.

C     // Initialize the plot and fetch the color

      frame = luc(-1)
      call initpl( frame, width )

      if( mccmdint('COL.OR', 1, 'Graphic Color', 3, 1, 3,
     &  color ) .lt. 0 ) return

Drawing lines

All graphics objects are composed of line segments built using the plot function. The graphics subsystem lets you specify the following line segment attributes:

• line color
• line style, dash or solid, along with the dashing pattern
• line width

Line color

The diagonal line in Figure 4-4 is generated by these lines of code (91 to 132) in GRAF.PGM:

      call initpl( frame, width )
      ...
      call plot( w_ullin, w_ulele, PEN_UP ) 
      call plot( w_lrlin, w_lrele, color  ) 
      call enpt

The second plot call draws the line in color level color from the previous cursor position to line w_lrlin and element w_lrele , here the lower-right corner of the frame. The previous position is always the one specified by the most recent plot call; the PEN_UP defined constant, with a value of zero, moves the pen from its previous, undefined location to the start of the line at (w_ullin,w_ulele ) without drawing.

To use a particular graphics form repeatedly, you can write a routine to generate it at the desired location with desired attributes. A simple example from GRAF.PGM, lines 263 to 286, is shown below.

      subroutine box( ullin, ulele, lrlin, lrele, color )

      <...variable declaractions deleted...>

      call plot( ullin, ulele, PEN_UP )
      call plot( ullin, lrele, color  )
      call plot( lrlin, lrele, color  )
      call plot( lrlin, ulele, color  )
      call plot( ullin, ulele, color  ) 
      call enpt
      ...

This example draws rectangles on the display with a single call and makes applications easier to write and understand.

Dash mode

The dash mode is set by the dshon and dshoff functions. To determine the current mode at any time, call the qgdash function.

When a McIDAS-X session starts, the dash pattern is preset to 10 pixels on and 10 pixels off. You can change this pattern using the McIDAS-X GD command, either from the command line before running any graphics applications, or within an application using the keyin or Mckeyin functions. These values are stored in User Common words 47 to 49.

Lines 146 to 151 in GRAF.PGM draw a dashed box to outline the viewport, which is described later, using the calls below.

      if( border .gt. 0 ) then
          call qgdash( old_dash )
         call dshon 
          call box( v_ullin, v_ulele, v_lrlin, v_lrele, color )
          if( old_dash .eq. 0 ) call dshoff 
      end if

Though not strictly necessary in this context, this sequence also illustrates a helpful idiom: capturing an aspect of graphics status (here the dashing state old_dash ), changing it to a known state (dshon) and then restoring the original state when done. Such behavior is especially important when writing library functions, since they should be careful to leave things the way they found them.

Line width

The line width is established when the graphics subsystem is initialized with initpl . To change the line width, you must close the current graphic and restart another, specifying a new width. Previously drawn graphics remain on the frame with the former line width and new graphics are drawn with the new line width.

Displaying text and numbers

The McIDAS-X library provides two graphics functions, wrtext and pltdig , for writing text and numbers on a graphics frame. When using these functions, you must designate the following:

• the height of the characters
• the color level
• the location for the output: upper-left justified for wrtext and lower-right justified for pltdig
  

Lines 361 to 386 in GRAF.PGM use wrtext to produce the alphanumeric characters shown in Figure 4-4 through its own plttext subroutine, as shown below.

C --- Determine the center point in frame coordinates. Because
C --- sclpnt() always works whether the world is active or not,
C --- make this call only if scaling is actually on.

      call qscale( sclstat )
      if( sclstat .eq. 1 ) then
         call sclpnt( clin, cele, txtclin, txtcele )
      else
          txtclin = clin
          txtcele = cele
      end if
C --- Determine the length of the text message in characters.
C --- This information is then used, together with the actual
C --- heights, to compute the upper left corner in frame coordinates
      nchar = len_trim( text )
      ullin = txtclin - txthgt/2
      ulele = txtcele - txthgt*nchar/2 + txthgt/10

C --- Display the text. Turn scaling off first (we have figured
C --- the text height and location in frame coordinates ourselves,
C --- right?) but be sure to restore it to its original state
C --- according to the result 'sclstat' of the qscale() call above
      call scloff
      call wrtext( ullin, ulele, txthgt, text, nchar, color )
      if( sclstat .eq. 1 ) call sclon

For titles and labels, it is often easier to decide where text should be centered rather than where its left margin should be. The above code uses the number of characters nchar and height in pixels txthgt to compute the offsets in line and element from the center to the upper-left. The internal plttext subroutine encapsulates the logic and other computations to account for graphics scaling so GRAF.PGM generates a centered line of text with a single call, just as box draws a graphics object in a clear, abstract way.

The pltdig function is similar to wrtext except that it also allows the user to specify the number of spaces. If the value to be plotted contains fewer digits, the result is left-padded with zeros.

Flushing the buffers

Because the graphics subsystem is buffered, graphics may not appear as they are being drawn. Interactive applications may need to force graphics to appear at various stages in the process. To do this, you must enter the call below to flush the buffers without ending the application's ability to draw additional graphics.

      call enpt

In the listing for GRAF.PGM, this is done at the end of the box and plttext subroutines (lines 286 and 388). All graphics drawn to that point become visible and the graphics package, including all graphics options the application may have set, remains active.

Binding off graphics

When you're done creating graphics, call the endplt function (line 224 in GRAF.PGM) to bind off the graphics as shown below.

      call endplt

Calling endplt displays all graphics on the McIDAS-X Image Window and frees all associated resources. To create more graphics on this or other frames, you will have to call initpl again.

Advanced McIDAS-X graphics techniques

This section describes some advanced techniques that you can use with the McIDAS-X graphics subsystem. It builds upon the example and the McIDAS-X session started in the previous section, Basic McIDAS-X graphics techniques.

Using world coordinates

The example presented in the previous section positioned and drew all graphics in terms of pixel locations on the screen, assuming the typical frame size of 480 lines by 640 elements. However, McIDAS-X frames don't have a fixed size. If you restart the previous McIDAS-X session with a frame size of 350 by 480 and rerun GRAF.PGM, the display will look like Figure 4-5 below.

Figure 5-5. This GRAF.PGM output is the result of a McIDAS-X session run with no arguments and a frame size of 350 lines by 480 elements.

Although the text is still centered on (240,320), this is no longer the center of the frame. The text message describing the frame size gets its values from this line of code (line 195) in GRAF.PGM:

      call mcfsize( frame, f_nlins, f_neles )

The upper-left corner is always (1,1) and the lower-right corner (f_lrlin, f_lrele ) can be readily computed from the size.

The problem of positioning graphics in frames of various sizes remains, however. An obvious solution is for the application to create its graphics objects in some normal coordinate system in which the frame always occupies the same range, whatever its physical size in pixels. McIDAS-X refers to such systems as scaled or world coordinates because they let graphics applications run in their own little world, which is always the size that the application finds convenient. McIDAS-X supports the use of world coordinates with the page, sclon, scloff, sclpnt and sclhgt functions.

To use world coordinates properly, you must understand the concepts of defining and activating worlds. The sclon function activates world coordinates (scaling) and scloff deactivates them. You can use only one coordinate system, either world or frame, at a time. All functions that generate graphics using a line or element pixel coordinate (plot, pltdig, wrtext) use the current system, whether frame or world. Frame coordinates are determined entirely by the hardware and/or the McIDAS-X session; world coordinates, on the other hand, may be defined to be convenient for the application. The initpl function defines a default world of 480 lines by 640 pixels; this world may be redefined using the page function. Keep in mind that page also activates the world it defines, whereas initpl does not.

In Figure 4-5, the world is defined to be 480 by 640 by initpl but not activated, as noted on the display. If you instead enter this command:

GRAF.PGM looks at the four WORLD parameters and defines and activates a world using the code below (lines 99 to 117).

C   // If the user has specified the necessary four arguments to
C   // WORLD= read them and define the world; page()
C   // automatically activates it.
C   // The defaults are 1 1 480 640 but there is no significance
C   // to this here; the argfetchers will trigger a return
C   // if the user doesn't actually enter a legal value for
C   // each of the four positions

    if( mccmdnum('WORLD') .eq. 4 ) then
        if( mccmdint('WORLD',1, 'World upper left line',
   &      1, 1, 0, w_ullin ) .lt. 1100 ) return

    ...three more argfetches deleted...
    
    call page( w_ullin, w_ulele, w_lrlin, w_lrele, SET_WORLD )
    end if

The resulting output is shown in Figure 4-6 below.

Figure 4-6. This GRAF.PGM output uses world coordinates to position the text.

The diagonal now goes from corner to corner as in Figure 4-4 and the text is again centered even though the frame sizes are different. Making applications that can generate attractive, properly positioned output regardless of the physical size of the frame is the primary use of world coordinates and the page function. If a 480 by 640 world is suitable, you can just enter the calls below to activate initpl 's default world.

      call initpl( frame, width )
      call sclon

In general, you should use a world that is as large as or larger than your largest frame size to minimize truncation errors resulting from a single world pixel occupying multiple pixels of the frame.

One complication of world coordinates is the positioning and sizing of text. The wrtext function can be given positions and a height in either frame or world coordinates. If the world is smaller than the frame, the text is enlarged; if the world is larger than the frame, the text is not reduced. This prevents the text from becoming too small to read. The difficulty is that the application must be able to account for both cases when centering text. One solution is to do the positioning and output directly in frame coordinates even if scaling is on; the sclpnt and sclhgt functions allow explicit conversion of points and text heights from world to frame coordinates. The plttext subroutine in GRAF.PGM, lines 354 to 386, illustrates this technique as shown in the code samples below.

The actual text size in frame coordinates is determined first:

C --- Determine the actual (frame coordinates) height of the
C --- text. (The use of local variable 'txthgt' is needed to keep
C --- plttext() from modifying its inputs.)

      txthgt = hgt
      call sclhgt( txthgt )

The center point is then transformed to frame coordinates:

C --- Determine the center point in frame coordinates. Because
C --- sclpnt() always works whether the world is active or not,
C --- make this call only if scaling is actually on.
      call qscale( sclstat )
      if( sclstat .eq. 1 ) then
          call sclpnt( clin, cele, txtclin, txtcele ) 
      else
          txtclin = clin
          txtcele = cele
      end if

Then the upper-left corner is computed, again in frame coordinates:

C --- Determine the length of the text message in characters.
C --- This information is then used, together with the actual
C --- heights, to compute the upper-left corner in frame
C --- coordinates.
      nchar = len_trim( text )
      ullin = txtclin - txthgt/2
      ulele = txtcele - txthgt*nchar/2 + txthgt/10

Given that the position is in frame coordinates already, you must verify that scaling is off before calling wrtext and then be sure to restore the scaling to its original setting, whether off or on, before returning control to the caller:

C --- Display the text. Turn scaling off first (we have figured
C --- the text height and location in frame coordinates
C --- ourselves, right?) but be sure to restore it to its
C --- original state according to the result 'sclstat' of the
C --- qscale() call above.
      call scloff 
      call wrtext( ullin, ulele, txthgt, text, nchar, color )
      if( sclstat .eq. 1 ) call sclon

In the above examples, you used world coordinates to make graphics applications independent of frame size. You can also change the orientation and origin of world coordinates as well as their extent.

Some graphics such as scatter plots are easier to generate in an (x,y ) coordinate system in which x increases leftward and y increases upward. The page function allows this, but there are two caveats. First, you should make your world domains as large as, or larger than, the frame to avoid truncation. Second, inverting the world by making either coordinate decrease, rather than increase, from the upper-left corner of the frame to the lower-right may cause confusion if you want to display text in world coordinates or use viewports (see below). The difficulty with text is that a specific, negative scale factor for line may result in text becoming very small or invisible.

Clipping and viewports

Sometimes it is desirable to limit graphics to a particular region of the frame. Consider Figure 4-7 below, which is identical to Figure 4-6 except the line segment is only drawn when it is more than 130 pixels, in world coordinates, from the edge of the world.

Figure 4-7. This GRAF.PGM output shows a viewport, or clipping region.

One solution is to determine the intersection of the diagonal with the 130-pixel border to get two new endpoints for the line segment. This algorithm is cumbersome because the diagonal may intersect with any two of the borders. The simple solution, supported by the McIDAS-X graphics subsystem, is to use a viewport . Also called a clipping region, a viewport defines a region of the frame outside of which graphics will not appear even if drawn. Like worlds, viewports are defined using page , but with a fifth argument of zero instead of one. Lines 139 to 151 in GRAF.PGM define the above viewport and draws its extent, as shown below.

      if( mccmdint('BOR.DER', 1, 'Border Width', 0, 0,
     &  (w_lrlin-w_ullin)/3, border ).lt. 0 ) return
      v_ullin = w_ullin + border
      v_ulele = w_ulele + border
      v_lrlin = w_lrlin - border
      v_lrele = w_lrele - border
      call page( v_ullin, v_ulele, v_lrlin, v_lrele, SET_VIEW ) 
      if( border .gt. 0 ) then
          call qgdash( old_dash )
          call dshon
          call box( v_ullin, v_ulele, v_lrlin, v_lrele, color )
          if( old_dash .eq. 0 ) call dshoff
      end if

Note that the viewport also clips text. The main use of viewports in McIDAS-X programming is to generate graphical output in regions set by the LINE and ELEM keywords, as is done by the McIDAS-X commands PTLIST and GRDDISP. Some users have written simple, frame-based graphical interfaces that set aside a portion of the frame as a toolbar and use a viewport to prevent meteorological data from plotting there when the rest of the frame is generated.

Listing for GRAF.PGM

  1 C   THIS IS SSEC PROPRIETARY SOFTWARE - ITS USE IS RESTRICTED.
  2 
  3 C *** McIDAS Revision History ***
  4 C *** McIDAS Revision History ***
  5 
  6 C ? GRAF -- Demo of basic McIDAS graphics
  7 C ?   GRAF <keywords>
  8 C ? Parameters:
  9 C ?   (none)
 10 C ? Keywords:
 11 C ?   BORDER   = | border width, in pixels
 12 C ?   COLOR    = | graphics color level
 13 C ?   WORLD    = | mn_lin mn_ele mx_lin mx_ele  to define and
 14 C ?              | activate a world
 15 C ? Remarks
 16 C ?       This demo nominally draws a diagonal line from 
 17 C ?   the upper left to the lower right of the display.
 18 C ?
 19 C ?       If WORLD= arguments are not specified, the initpl()
 20 C ?   default world of 480 lines by 640 elements is defined
 21 C ?   but not activated. The diagonal line will be correct
 22 C ?   only if the display size is 480 by 640. If WORLD= arguments
 23 C ?   are specified the world will be defined and activated and
 24 C ?   the diagonal correct regardless of world size.
 25 C ? 
 26 C ?   BORDER= defines a viewport (clipping region) the indicated
 27 C ?   number of pixels (world coordinates) from the edge of the
 28 C ?   world and outlines it with a dashed line.
 29 C ? ----------
 30       subroutine main0
 31
 32       implicit      NONE
 33
 34 C