For additional information about the functions described in this section, see the online man pages provided with the McIDAS-X software.
McIDAS Programmer's Manual
Version 2003
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]
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. |
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 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.
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 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.
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:
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 |
|---|---|
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.
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 |
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.
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. |
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.
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.
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.
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 |
|---|---|---|
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.
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.
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.
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(' ') |
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 |
|---|---|
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.
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.
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.
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.
Use the functions below to change the appearance of the McIDAS-X cursor.
| Fortran function | Description |
|---|---|
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.
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]
