McIDAS Programmer's Manual
[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.
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.
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.
|C function||Fortran function||Description|
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|
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.
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.
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.
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.
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.
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.
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.
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.
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.
|C function||Fortran function||Description|
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.
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.
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.
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.
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.
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.
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.
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.
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]