Limitations

You must observe the following limitations when developing applications that access string tables.

• A string name may not exceed 12 alphanumeric characters.
• You can't use Y or H as string names because they are reserved for the present date and time and can't be reassigned.
• A question mark as the first character of a string name indicates a global string , which does not change when the workstation's current string table is replaced with another.
• Strings may not exceed 160 characters.
• A single string table may contain a maximum of 256 entries.

Cautions

String tables provide convenient, global storage for passing information in and out of applications without using the command line, text display or file I/O. Although the technique for implementing a string table is easy, using string tables for passing information between commands is not always desirable. If the applications using string tables do not provide a facility for reinitializing the strings used, unpredictable results may occur during subsequent use of the applications.

Storing or sharing information using the string table functions can make applications more convenient for users if used sparingly and documented clearly. It can just as easily lead to confusion, since a string name can't be protected for an application's exclusive use. Other applications or the user (via the string table editor TE) can modify or delete the string, causing the application relying on that string to behave unpredictably. To minimize the risk of name collisions in the string table, choose an unlikely name for the stored string.

Use the McIDAS-X disk file system if your application needs to save more than a few pieces of information that will be used by other applications at a later time. Use a text file, whenever practical, as it simplifies the editing and viewing of the file and makes debugging your application easier.

Examples

The code segments below demonstrate the McIDAS-X string table API. Sample user-level input, via the TE and ECHO commands, is also provided to show how string table entries can be written to and read from both the command line and within an application.

Reading a string from a string table

The lbget function extracts the contents of a string from within an application and places it in a character variable. If the string table value is longer than the character variable receiving it, the value stored in the character variable is truncated. For example, a user enters the following command from the McIDAS-X Text and Command Window.

The code segment below reads the contents of the string HITTER.

     character*12 string_name     ! name of McIDAS string to
                                  ! extract value from
     character*24 out_string      ! variable to store resulting 
                                  ! value in

     string_name = 'HITTER'
     ok = lbget (string_name, out_string)

     if (ok .lt. 0)then
        goto 999
     endif

c--- upon successful completion the contents of the variable 
c--- out_string will be 'MICKEY MANTLE'

Writing a string to a string table

The lbput function stores the contents of a character string in the current McIDAS-X string table associated with a specified string name, as shown in the code fragment below.

     character*12 string_name     ! name of McIDAS string to
                                  ! place new value in
     character*24 in_string       ! variable to store resulting 
                                  ! value in

     string_name = 'HITTER'
     in_string   = 'Willie Mays'
     ok = lbput (string_name, in_string)

     if (ok .lt. 0)then
        goto 999
     endif

c--- upon successful completion the contents of the McIDAS
c--- string HITTER will be 'Willie Mays'

If a user subsequently runs the following command from the McIDAS-X Text and Command Window:

The output displayed on the text screen will appear as shown below.

The Greatest Centerfielder of all time was Willie Mays

Writing character tokens to a string table

The lbputc function allows a user to enter a group of character tokens into one string. The code fragment below demonstrates this function.

     parameter (MAXTOK = 3)
     character*12 string_name     ! name of McIDAS string to 
                                  ! place new value in
     character*12 tokens(MAXTOK)  ! string tokens to write into
                                  ! the McIDAS string 700CLUB

     string_name = '700CLUB'
     tokens(1)   = 'Hank Aaron'
     tokens(2)   = 'and'
     tokens(3)   = 'Babe Ruth'
     ok = lbputc (string_name, MAXTOK, tokens) 
     if (ok .lt. 0)then
        goto 999
     endif

c--- upon successful completion the contents of the McIDAS
c--- string 700CLUB will be 'Hank Aaron and Babe Ruth'

If a user subsequently runs the following command from the McIDAS-X Text and Command Window:

The output displayed on the text screen will appear as shown below.

Hank Aaron and Babe Ruth are the two greatest sluggers of all time

Positive and negative User Common

User Common is divided into positive and negative regions. You must understand the differences between the two and use the appropriate region so that your applications will behave predictably. Note that each session running on a workstation has its own private copy of User Common.

• Use positive User Common when writing interactive applications. Positive User Common contains the instantaneous state of the session. At any instant, it is the same for all processes. All processes, including applications, may change it at any time, and these changes are immediately visible to all other McIDAS-X processes and to the user via the display.
• Use negative User Common when writing applications that need to know the state of the system when the user starts a command by pressing the Enter key. Negative User Common contains a copy of the session state taken at the time a process or process chain starts, plus any modifications made to it by the process or chain. A process chain is a series of McIDAS-X processes run synchronously.

Negative User Common is initialized when the process chain starts. All subsequent processes inherit negative User Common and any changes made to it by processes in the chain.

Batch files, McBASI scripts, and commands separated from each other by a semicolon on a single command line all initiate a chain. Because each process chain has its own copy, Negative User Common cannot be changed from outside the process chain and changes to it are not visible except to the owning process chain, including the display.

The following sequence of commands illustrates why both positive (instantaneous) and negative (process-dependent) User Common are necessary and how applications use them to achieve predictable interactive behavior. If the user enters the three commands below:

The first command sets the current frame to 2; the second command requests that the latest GOES-EAST 4 km IR image, centered on Madison, Wisconsin, be displayed on the current frame. Now suppose the user wants to view a graphic already displayed on frame 4, and enters the third command before IMGDISP begins displaying the image. The display immediately switches to frame 4.

What happens to the IMGDISP command trying to display to the current frame? Is the current frame the frame the user intended (frame 2) or the frame presently displayed (frame 4)? The ambiguity is resolved with positive and negative User Common.

When SF 2 changes the appropriate word in User Common, in this case word 51, to 2, the display immediately reflects it. When IMGDISP starts, the display state, including the current frame number 2, is copied into negative User Common. IMGDISP can then examine the appropriate User Common word, in this case -1, to get the frame number that was current when it started. This value is always 2; whereas the true current frame (word 51) changes from 2 to 4 when SF 4 runs.

User Common API functions

The User Common functions are described in the table below.

The most common error in using these functions is specifying the wrong User Common index value; the second most common error is transposing a new value with the User Common index value in puc and Mcpuc.

The m0glue.h include file has many of the User Common indexes enumerated using #define statements.

Several APIs are provided in addition to the basic Mcluc and Mcpuc functions. They are described in the table below.

User Common functions are often used to verify that an item, such as a frame, etc., is within a valid range. The example below, from the MAP command, illustrates the use of one of these functions.

Determining if the current frame is within a valid range

The MAP command fragments below define what the highest numbered image frame is and compares that number to the desired frame to be used in the command.

c--- maximum image frame
     MAX_IMAGE = mcgetmaximageframenumber()
.
.
.
c--- get the current image frame
        def_image_frame = mcgetimageframenumber()

c--- get the user desired frame and check to see if it is
c--- out of range.  Note that the user may not have input
c--- a frame number, in which case the default frame is used.
         status = mccmdint('IMA.GE',1,'Image Frame',def_image_frame,
    &         1,MAX_IMAGE,nfri)
         if( status.lt.0 ) return

Note that mcgetimageframenumber, not mcgetimageframenumberi , determines the current frame. This ensures that the current frame is the one displayed at the time MAP is started, not the frame displayed at the time the above code fragment actually runs.

Restoring the display to its original state

The sample code below performs these three tasks:

• reads the roam and cursor state from User Common into variables
• performs interactions involving the mouse
• restores the original roam and cursor states when done

Note the use of luc and puc since no other APIs are currently available.

c --- freeze the roam
      roam = luc( 178 )
      call puc( 1, 178 )

c --- connect cursor to mouse
      mouse = luc( 67 )
      call puc( 1, 67 )

<deleted code>

100   continue
      status = mcmoubtn(3, button(1), button(2), line, elem)
      altG = 0
      if(status.eq.2) altG=1
      altQ = 0
      if(status.eq.1) altQ=1

c --- check for program termination
      if( altQ.ne.0 ) then
     call beep(200,100)
           interact = -3
     return
      endif

<deleted code>

      goto 100

<deleted code>

c --- reset the mouse
      call puc( mouse, 67 )

c --- reset the roam
      call puc( roam, 178 )