McIDAS Programmer's Manual
Version 2003

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]


User interface utilities

Users ultimately interact with McIDAS-X in one of two ways:

This section describes each part of the McIDAS-X command line, provides descriptions and examples of the command-line functions you can use in your programs, and defines the return status codes for these functions. This section also describes the standard pointing device for McIDAS-X and provides descriptions and examples of the functions available for reporting the state of the mouse buttons and changing the cursor's location, size, color and type.

 

For additional information about the functions described in this section, see the online man pages provided with the McIDAS-X software.

Command line

McIDAS-X applications are command-line driven. McIDAS-X has two basic command formats:

The multiple-letter command format is discussed in this section. The number of characters permitted in a command line is workstation dependent, although there is no practical limit.

A McIDAS-X command line may contain one or more of the following:

A sample McIDAS-X command line is shown below.

Each command line value is separated by one or more blank spaces. Surround an individual parameter requiring blank spaces with single quotes (' ') so it is treated as one parameter.

Each part of the McIDAS-X command line is discussed below, followed by a description of the functions for extracting individual values from the command line and interrogating the structure of the command line.

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 seven global keywords, which are common to all McIDAS-X commands:

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

 

For more information about the McIDAS-X global keywords, see the McIDAS User's Guide.

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.

C function Fortran function Description

Mccmddbl

mccmddbl

extracts a value as a double precision number

Mccmddhr

mccmddhr

extracts a time value as a double precision number in units of hours

Mccmddll

mccmddll

extracts a latitude or longitude value as a double precision number in units of degrees

Mccmdihr

mccmdihr

extracts a time value as an integer value in the hhmmss format

Mccmdill

mccmdill

extracts a latitude or longitude value as an integer value in the dddmmss format

Mccmdint

mccmdint

extracts a value as an integer

Mccmdiyd

mccmdiyd

extracts a day value as an integer value in the Julian day format ccyyddd

Mccmdquo

mccmdquo

extracts a character string value from the quote field

Mccmdstr

mccmdstr

extracts a character string value

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:

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

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

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.

Acceptable forms Unacceptable forms

FRA=

FR=

FRAM=

FRAEM=

FRAMENUM=

 

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.

C function Fortran function Description

Mccmd

mccmd

returns the entire user command in one string

Mccmdkey

mccmdkey

verifies that the keywords entered by the user are valid

Mccmdnam

mccmdnam

returns a list of the keywords entered by the user

Mccmdnum

mccmdnum

returns the number of parameters entered for a particular keyword

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.

Status code Definition

[-]0bcd

argument comes from the default

[-]1bcd

argument comes from the command line

[-]2bcd

argument comes from the McIDAS-X string table

[-]a00d

character string argument

[-]a01d

quote field string argument

[-]a10d

integer argument

[-]a11d

integer hexadecimal argument

[-]a20d

double decimal argument

[-]a21d

double hexadecimal argument

[-]a30d

date argument

[-]a31d

current date argument

- a32d

year within date argument is invalid

- a33d

mon month within date argument is invalid

- a34d

mm month within date argument is invalid

- a35d

day of month (dd) within date argument is invalid

- a36d

day of year (ddd) within date argument is invalid

[-]a40d

integer time argument

[-]a41d

current integer time argument

- a42d

hours within integer time argument are invalid

- a43d

minutes within integer time argument are invalid

- a44d

seconds within integer time argument are invalid

[-]a45d

double time argument

[-]a46d

current double time argument

- a47d

hours within double time argument are invalid

- a48d

minutes within double time argument are invalid

- a49d

seconds within double time argument are invalid

[-]a50d

integer lat/lon argument

- a52d

degrees within integer lat/lon argument are invalid

- a53d

minutes within integer lat/lon argument are invalid

- a54d

seconds within integer lat/lon argument are invalid

[-] a55d

double lat/lon argument

- a57d

degrees within double lat/lon argument are invalid

- a58d

minutes within double lat/lon argument are invalid

- a59d

seconds within double lat/lon argument are invalid

[-] 90d

keyword status

abc0

argument is ok

- abc1

argument has an invalid character

- abc2

integer argument can't contain a fraction

- abc3

argument exceeds system limits for desired format

- abc4

out-of-range argument < given min

- abc5

out-of-range argument > given max

Pointing device

The standard pointing device is usually a three-button mouse. The leftmost button is used by the window manager and the middle and right buttons are used by the McIDAS-X mouse interface.

If you have a two-button mouse, the left button is used by the window manager and the right button performs the tasks normally performed by the right button on a three-button mouse. Press both buttons to perform the tasks normally performed by the middle mouse button. Check the mouse settings in your X-server configuration if you see unexpected behavior.

Users can interact with the McIDAS-X Image Window and McIDAS-X commands via the mouse-driven cursor. McIDAS-X defines the cursor's size, color and shape as long as the cursor resides on the McIDAS-X Image Window. If the cursor is moved outside the window, the cursor's size, color and shape revert to the workstation's settings.

The McIDAS-X function for interfacing with the mouse is mcmoubtn, which performs the following tasks:

You can use the McIDAS-X functions putcur, mcgetcur, sizcur, colcur and typcur in your applications to define the cursor's location, size, color and type. The function mcgetcur will return the cursor position of the cursor when your command starts.

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:

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.

Fortran function Description

putcur

moves the cursor to a specified location

sizcur

changes the cursor size

colcur

changes the cursor color

typcur

changes the cursor type; for example, crosshair or box

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 )

...

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]