Understanding and Replacing Deprecated Jam5 Syntax
with Jam7 Syntax

Screen and Message Window Functions

• sm_viewport

  sm_viewport(position_row, position_col, size_row, size_col, offset_row, offset_col)


  Status

  Jam5 & Jam6 Function
  Deprecated & Undocumented in Jam7/Prolifics
  Functional Through Jam7/Panther (Prolifics 4)
  

  Description:

  The sm_viewport was used to dynamically modify the viewport size and offset of the current screen. The physical display should be thought of as a grid, with the row 0, column 0 position being the top left corner. Rows and columns are defined as in terms of the size of a single character. The individual parameters are defined in the table below. Note that in the Jam5 functional form, giving a -1 for the viewport size (rows or columns) meant to expand the window to the maximum size in that dimension. This funtionality does not work in Jam7.

  The Jam7 replacement for this function is to dynamically modify the property associated with the screen. Rather than modifying all 6 properties as in the functional form, each property can be dynamically modified individually. The table below gives the Jam7 property that corresponds to each argument in the functional form.

  Jam5 sm_viewport to Jam7 Property Conversion Table

  sm_viewport Argument	Jam7 Property	Parameter/Property Definition
  position_row	vstline	Line position to place top corner of screen (viewport).
  position_col	vstcolm	Column position to place top corner of screen (viewport).
  size_row	vnlines	Size in rows of screen.
  size_col	vncolms	Size in columns of screen.
  offset_col	vofcolm	Within screen (viewport), the row of the screen to place in the top corner.
  offset_row	vofline	Within screen (viewport), the column of the screen to place in the top corner.

  JPL Examples

  call sm_viewport(5, 10, 25, 30, 3, 4)
  

            @screen("@current")->vstline = 5
            @screen("@current")->vstcolm = 10
            @screen("@current")->vnlines = 25
            @screen("@current")->vncolms = 30
            @screen("@current")->vofline = 3
            @screen("@current")->vofline = 4

  ---

• sm_mwindow

  sm_mwindow(text, line, column)


  Status

  Jam5 & Jam6 Function
  Deprecated & Undocumented in Jam7/Prolifics
  Functional Through Jam7/Panther (Prolifics 4)
  

  Description:

  The sm_mwindow function was used to display a pop up message window on the screen to the user. The box contained the OK button--after pressing OK, the window closed. In addition to specifying the text, the line and colum (integers) position of the top corner of the box could be set.

  This function is replaced by the sm_message_box function. This function provides more functionality than the sm_mwindow function, except that the line & column of the top corner of the box cannot be specified. The text of the message_box is the first parameter, the title of the box is the second parameter, the third parameter is a series of bit-masks defining the buttons and options to present the user, and the fourth parameter is a second method of specifying an icon. See the Language Reference for more details on all parameters of the sm_message_box function.

  JPL Examples

  call sm_mwindow("Don't touch that Button", 10, 10)
call sm_message_box("Don't touch that Button", "Warning!", SM_MB_OK, "")

  C Examples

  This function can also be called from C. See the Language Reference for more details.

  ---

• sm_query_msg

  sm_query_msg(text)


  Status

  Jam5 & Jam6 Function
  Deprecated & Undocumented in Jam7/Prolifics
  Functional Through Jam7/Panther (Prolifics 4)
  

  Description:

  The sm_query_msg function was used to display a pop up question window on the screen to the user. The box contained the YES and NO buttons--after pressing one, the window closed. The return value is either 'y' or 'n', depending upon the response.

  This function is replaced by the sm_message_box function. This function provides more functionality than the sm_query_msg function. However, the return value is provided in a slightly different manner. The text of the message_box is the first parameter, the title of the box is the second parameter, the third parameter is a series of bit-masks defining the buttons and options to present the user, and the fourth parameter is a second method of specifying an icon. See the Language Reference for more details on all parameters of the sm_message_box function.

  The sm_message_box function can display a variety of button combinations; to specifically get a YES/NO message box, the third argument of the function call must be SM_MB_YESNO. Then, the return values are either SM_IDYES or SM_IDNO. Again see the Language Reference for more details on the buttons that can be presented to users and the various return codes.

  JPL Examples

  

       if (sm_query_msg("Do you want to save before exiting?",0,0) = 'y')
       {
           call save_function()
       }
       

  

       if (sm_message_box("Do you want to save before exiting", "", SM_MB_YESNO, "") = SM_IDYES)
       {
            call save_function()
       }

  C Examples

  This function can also be called from C. See the Language Reference for more details.

  
  Note: Actually what the sm_query_msg returns is the first letter of SM_YES or SM_NO, as these are defined in the message file. Users working with foreign language message files, should replace the 'y' or 'n' with the appropriate responses.

  ---