Migrating Legacy Maintain Procedures to Maintain Data

In this section:

How to:

You can run Maintain applications that were created in Developer Studio in WebFOCUS App Studio, without any changes or migration. However, if you wish to make changes to your application, you must migrate it to WebFOCUS App Studio.

You can migrate existing Maintain procedures to the WebFOCUS App Studio Maintain Data application, using the External Request option in the Requests & Data Sources panel.

Procedure: How to Migrate Legacy Maintain Procedures

  1. If you do not see your application on the Configured Environments tree, create a new one by right-clicking Applications and clicking New Application Directory.

    Note: Assign the application the name of the directory containing all of the files, including Master and Access Files, needed for the Maintain application.

  2. Create a new HTML page by right-clicking the application name, selecting New, and then selecting HTML/Document.

    Note: The Maintain application code is no longer a stand-alone application. It resides as part of an HTML page.

  3. In the HTML/Document Wizard, leave HTML Page selected and click Next.
  4. On the Templates, Settings, and Themes pane, click Finish to continue.
  5. Open the Requests & Data Sources panel and pin it to the canvas.
  6. From the New drop-down menu, select External Request and then select Maintain data: Existing from the shortcut menu.
  7. From the Open File dialog box, select the Maintain file to be migrated, and the migration process begins.

    Note: If there is more than one Maintain file, select the parent or main Maintain that CALLs the others. If you do not see the name of your Maintain file, select the Show All Files in Associated Paths radio button.

    The following WebFOCUS App Studio dialog box opens, asking you whether you want to start the Maintain Data procedure after the page is loaded.

  8. Click Yes.

    Note: All Maintain applications must have a Load task that performs a Connect to the code. Without this, when you run the application, the Maintain code will not be processed. Clicking Yes to start the Maintain right after the page is loaded creates this task. All new Maintain applications must also contain this task.

    As the migration runs, you may receive a message that the Maintain procedure contains multiple Winforms and that recommends that you use a multipage control for better layout and presentation, as shown in the following image. The multipage control puts one Winform on a page and the appropriate Winform is displayed automatically when needed.

  9. Click Yes.

    The migration process continues.

    If the conversion is successful, the following WebFOCUS App Studio dialog box opens, indicating that the conversion process is complete and asking if you want to see the log file.

  10. Click Yes if you want to review the log file. Otherwise, click No.
  11. Click OK if you receive a message stating that code in the Maintain procedure was found that could not be migrated automatically and that you need to revise it.

    The Maintain procedure opens in the WebFOCUS App Studio Maintain Editor, as shown in the following image. In addition, the Maintain request can be expanded in the Requests & Data Sources panel to see its components.

  12. In the WebFOCUS App Studio Maintain Editor, search for the following line of code:
    -* The following line of code is not consistent with the new design of Maintain. Please revise.
    This line appears for constructs, such as when the Maintain code wants to directly manipulate a control, or there is a Winform Set statement to make an object visible.

Maintain Data Migration Considerations

In this section:

The following are migration considerations when migrating legacy Maintain applications to Maintain Data.

Naming Changes

An object in Maintain Data or JavaScript code is no longer referenced using Form.Objectname. All migrated variables are changed to Form_Objectname.

Events

All Maintain code in the application event section is migrated into the application. A case is created for each event, and a task is assigned to that case. Display the Tasks & Animations panel. When you click on a control, you can see the task assigned to each case.

If the event contains JavaScript, you can view the JavaScript by clicking the Embedded JavaScript tab at the bottom of the form. To see if an object is associated with a JavaScript event, click the object and display the Properties panel. Click the lightning bolt to display the events. Clicking on an event name brings you to the code in the Embedded JavaScript view.

Winform Set Commands

There are no longer Winform Set commands in Maintain Data. All of these commands are replaced by computed variables. Assign these variables to an object property and when the variable is evaluated, the property is set. Instead of the following Maintain command to make something invisible: 

Winform Set Form.Object.Visible to No;

In Maintain Data, you use a Compute command, and assign that to the visible property of the object. For example: 

Compute Var/a10 = 'Hidden';

You can assign variables by dragging them from the Requests & Data Sources panel directly onto the Properties panel of the object.

Winform Get Command

The Winform Get command is no longer supported. You can test the associated variable to get the current value.

showLayer Command

The SetLayer command in Maintain has been replaced by the IbComposer_showLayer command in Maintain Data. The IbComposer_showLayer command allows layers to be set as visible or invisible at run time. It is used in a JavaScript event.

IWCTrigger Code

IWCTrigger code is no longer used for a JavaScript event to perform a Maintain case. Instead, a new task is created to perform the Maintain case and assigned to a Trigger Type of TBD. You can then drag that task into the JavaScript code and create: 

IbComposer_triggerExecution("taskn",1);

This conversion is done for you at migration. If the IWCTrigger code was in a linked or embedded JavaScript file, you will have to perform this code conversion yourself.

HTMLTable GetHTMLField

When embedding HTML objects in HTMLTables, GetHTMLField was used to retrieve the selected or entered value at run time. You can now assign a Selection To field when creating the HTMLTable, making this unnecessary.

HTMLTable ClickRow, ClickColumn, and Value

Retrieving the clicked row, column, or value from an HTMLTable has changed for using both Maintain Data and JavaScript code.

The Developer Studio functions ClickColumn, ClickRow, and Value(cell value) are now IbComposer_getClickedColumn, IbComposer_getClickedRow, and IbComposer_getClickedCellValue.

The following Developer Studio Maintain code is removed. 

compute X/13 = Form1.HTMLTable1.Clickrow;
compute Y/13 = Form1.HTMLTable1.Clickcolumn;
compute Z/13 = Form1.HTMLTable1.value;

X and Y are still created, but are assigned in the HTMLTable Settings panel to the ClickRow and ClickColumn parameters.

The statement: Form1.HTMLTable1.value; is no longer supported and will have to be replaced. You can use the code: 

compute Z/A10 = Stack(x).field;

where:

Stack

Is the name of the stack populating the HTMLTable.

x

Is the variable containing the ClickRow value.

field

Is the name of the field on which you are clicking.

This Developer Studio JavaScript code: 

var col = Form1.HTMLTable1_ClickColumn.value;
var row = Form1.HTMLTable1_ClickRow.value;
var val = Form1.HTMLTable1_Value.value;

is replaced by:

var col = IbComposer_getClickedColumn(ctrl);
var row = IbComposer_getClickedRow(ctrl);
var val = IbComposer_getClickedCellValue(ctrl);

HTMLTable Dynamic Sizing

In Maintain, the command: Form1.HTMLTable1.RealBodyRowHeight = n was used to change the height of a row in an HTMLTable. In Maintain Data, this is done in the HTMLTable Properties panel.

Freezing Grid Columns Using the FixedColumns Property

In Maintain Data, the FixedColumns property, which was used to freeze columns in a grid in legacy Maintain, is no longer supported. Legacy Maintain applications that use this property will no longer have frozen columns when migrated to Maintain Data.

Closing and Exiting a Form

Since the Maintain Data application is now part of an HTMLPage, the command self.Winexit or formname.Winexit is no longer supported.

Embedded or Linked JavaScript Files or CSS Files

To see the JavaScript or CSS files that are associated with your migrated application, click the form and display the Settings panel. The names of your resource files can be found there.

Displaying Forms and Databases

When you expand the Forms folder on the tree, all application forms are displayed. You can display one or multiple forms by checking the box next to their names.

Databases are displayed once for all the requests. They are not displayed for each request.

Using the ACCEPT Property to Specify Accepted Field Values

The ACCEPT property, used in a Master File to set a list of valid field values, is no longer respected when the field is part of a Maintain form. Additionally, if the field containing the ACCEPT list has an AnV format, you receive an error when running the form.

Property Functions in JSGrid

  • Two additional values for contentTypes were added to the ColumnSetContentType function. The two values are 3 - CheckBox and 4 - Select.
  • The CellSetFont function has been enhanced to include additional styling information, as follows:
    grid1.CellSetFont(3,2,"italic bold 12px antique, serif");
  • The syntax for the SetTopRow function is now:
    $('#Form1_Grid1_table').setTopRow
  • The syntax of the functions no longer includes the form name.
  • The Grid and JSGrid OnRowSized and OnRowSizing events are not available in WebFOCUS App Studio.

Migrating JavaScript Functions to TIBCO WebFOCUS App Studio Maintain Data

In this section:

You can execute JavaScript functions to get and temporarily set values in a grid. Since these changes are made at run time using JavaScript functions, any changes are lost when the form refreshes. For identification purposes, when using these functions, the first cell in the grid is row 0, column 0. Grid column and row headers are ignored for numbering purposes.

If you used JavaScript functions with an ActiveX grid in legacy Maintain, you can update them to the corresponding functions listed below.

Function: SetCellFocus

How to:

Use the function SetCellFocus to place the cursor on a specific cell of the grid. This replaces the legacy Maintain function GotoCell.

Syntax: How to Set the Cursor on a Row and Column of a Grid 
form.SetCellFocus(col,row);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Example: Setting the Cursor on a Row and Column of a Grid

The following example moves the cursor to the third column of the first row.

grid1.SetCellFocus(2,0);

Function: GetNumberRows and GetNumberColumns

How to:

Use the function GetNumberRows to determine the total number of rows in a grid, and use GetNumberColumns to determine the total number of columns.

Syntax: How to Get the Number of Rows and Columns in a Grid 
var var1 = form.GetNumberRows();
var var2 = form.GetNumberColumns();

where:

var1, var2

Alphanumeric

Are the names of the variables to set.

form

Alphanumeric

Is the unique identifier of the grid.

Function: GetCurrentRow and GetCurrentColumn

How to:

Use the function GetCurrentRow to determine the row where the cursor is currently located in the grid, and use GetCurrentColumn to determine the column where the cursor is currently located. These replace the legacy Maintain functions GetCurrentRow and GetCurrentColumn.

Syntax: How to Get the Current Row and Column in a Grid 
var var1 = form.GetCurrentRow();
var var2 = form.GetCurrentColumn();

where:

var1, var2

Alphanumeric

Are the names of the variables to set.

form

Alphanumeric

Is the unique identifier of the grid.

Function: CellSetBackColor

How to:

Use the function CellSetBackColor to change the background color of a grid cell. This replaces the legacy Maintain function QuickSetBackColor.

Syntax: How to Change the Background Color of a Grid Cell 
form.CellSetBackColor(col,row,color);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

color

Alphanumeric

Is a color name, RGB value, or hexadecimal color value, in double quotation marks.

Example: Changing the Background Color of a Grid Cell

The following example changes the background color of the cell in the third row and third column to blue.

grid1.CellSetBackColor(2,2,"blue");

Function: CellGetBackColor

How to:

Use the function CellGetBackColor retrieve the background color of a cell into a variable.

Syntax: How to Retrieve the Color of a Cell 
var var1 = form.CellGetBackColor(col, row);

where:

var1

Alphanumeric

Is the name of the variable to set.

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Example: Retrieving the Color of a Cell

The following example retrieves the background color of the cell in the third row and third column as celcolor.

var celcolor = grid1.CellGetBackColor(2,2);

Function: CellSetTextColor

How to:

Use the function CellSetTextColor to change the color of the text in a grid cell. This replaces the legacy Maintain function QuickSetBackColor.

Syntax: How to Change the Color of Text in a Grid Cell 
form.CellSetTextColor(col,row,color);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

color

Alphanumeric

Is a color name, RGB value, or hexadecimal color value, in quotation marks (").

Example: Changing the Color of Text in a Grid Cell

The following example changes the text color of the cell in the third row and third column to blue.

grid1.CellSetTextColor(2,2,"rgb(0,0,255)");

Function: CellGetTextColor

How to:

Use the function CellGetTextColor retrieve the color of text in a cell into a variable. This replaces the legacy Maintain function CellGetTextColor.

Syntax: How to Retrieve the Color of Text in a Cell 
var var1 = form.CellGetTextColor(col, row);

where:

var1

Alphanumeric

Is the name of the variable to set.

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Example: Retrieving the Color of Text in a Cell

The following example retrieves the color of the text in the cell in the third row and third column as celcolor.

var celcolor = grid1.CellGetTextColor(2,2);

Function: CellSetText

How to:

Use the function CellSetText to change the text in a grid cell. This replaces the legacy Maintain function CellSetText.

Syntax: How to Change the Text in a Grid Cell 
form.CellSetText(col,row,text);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

text

Alphanumeric

Is the text to enter into the cell, in quotation marks (").

Example: Changing the Text in a Grid Cell

The following example changes the text of the cell in the second row and second column to the words New Text.

grid1.CellSetText(1, 1, "New Text");

Function: CellGetText

How to:

Use the function CellGetText to retrieve the text from a cell into a variable. This replaces the legacy Maintain function CellGetText.

Syntax: How to Retrieve the Text From a Cell 
var var1 = form.CellGetText(col, row);

where:

var1

Alphanumeric

Is the name of the variable to set.

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Example: Retrieving the Text From a Cell

The following example retrieves the text from the cell in the second row and second column as textvalue.

var textvalue = grid1.CellGetText(1,1);

Function: CellSetFontSize

How to:

Use the function CellSetFontSize to change the size of the text in a grid cell.

Size changes appear in navigation mode. When you edit the cell, the original size is displayed.

Syntax: How to Change the Size of Text in a Grid Cell 
form.CellSetFontSize(col,row,size);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

size

Numeric

Is the font size.

Example: Changing the Size of Text in a Grid Cell

The following example changes the size of the text in the second column and fourth row to size 25.

grid1.CellSetFontSize(1, 3, 25);

Function: CellSetFontStyle

How to:

Use the function CellSetFontStyle to change the style of the text in a grid cell.

Style changes appear in navigation mode. When you edit the cell, the original size is displayed.

Syntax: How to Change the Style of Text in a Grid Cell 
form.CellSetFontStyle(col,row,style);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

style

Alphanumeric

Is the font style, in double quotation marks. Available options are Normal, Italic, Oblique, Inherit, and Initial.

Example: Changing the Style of Text in a Grid Cell

The following example changes the style of the text in the second column and fourth row to italic.

grid1.CellSetFontStyle(1, 3, "Italic");

Function: CellSetFont

How to:

Use the function CellSetFont to change the font of the text in a grid cell. This replaces the legacy Maintain function QuickSetFont.

Font changes appear in navigation mode. When you edit the cell, the original font is displayed.

Syntax: How to Change the Font of Text in a Grid Cell 
form.CellSetFont(col,row,"Font");

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Font

Alphanumeric

Is the font definition, which can include a font size. The entire string is in double quotation marks, while the font name is in single quotation marks (').

Example: Changing the Font of Text in a Grid Cell

The following example changes the font of the text in the second column and second row to 20 pixel Times New Roman.

grid1.CellSetFont(1, 1, "20px 'Times New Roman'");
You can specify additional parameters with this syntax. For example, the following function changes the style, size, and font of text in the cell to italic, bold, 30 pixel Georgia, serif.
grid1.CellSetFont(1,1, "italic bold 30px 'Georgia, serif'");

Function: CellSetReadOnly

How to:

Use the function CellSetReadOnly to make a cell read only. This replaces the legacy Maintain function CellSetReadOnly.

Syntax: How to Change the Protection Value of a Cell 
form.CellSetReadOnly(col,row, {true|false});

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

{true|false}

Alphanumeric

Type 1 or true to make the cell read only, or type 0 or false to make it editable.

After migrating an application that contained the old grid, the following syntax may be seen:

form.GetCell(col, row);
form.SetCell (col, row) ;
form.CellSetReadOnly ({true|false});
form.RedrawAll();

This syntax accomplishes the same result as the CellSetReadOnly function with the grid name, column, and row specified.

Example: Changing the Protection Value of a Cell

The following example makes the cell in the second row and second column read only.

grid1.CellSetReadOnly (1,1,true);

Function: CellGetReadOnly

How to:

Use the function CellGetReadOnly to retrieve the protection value of a cell. This replaces the legacy Maintain function CellGetReadOnly.

Syntax: How to Retrieve the Protection Value of a Cell 
var var1 = form.CellGetReadOnly (col,row);

where:

var1

Alphanumeric

Is the name of the variable to set.

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

row

Numeric

Is the row of the cell.

Example: Retrieving the Protection Value of a Cell

The following example retrieves the protection value of the cell in the second column and second row as cellread.

var cellread = grid1.CellGetReadOnly (1,1);

Function: ColumnSetContentType

How to:

Use the function ColumnSetContentType to change the content of a column in a grid. The content is text, by default, but can be changed to other input types.

Syntax: How to Change the Content Type of a Column in a Grid 
form.ColumnSetContentType(col, contentType);

where:

form

Alphanumeric

Is the unique identifier of the grid.

col

Numeric

Is the column of the cell.

contentType

Numeric

Is a number specifying a content type. This can be one of the following values:

  • 0. Text. This is the default values.
  • 1. HTML.
  • 2. Image.
  • 3. Check boxes.
  • 4. Select.
Example: Retrieving the Protection Value of a Cell

The following example replaces the text in the second column with check boxes, which are specified by the contentType value of 3. 

grid1.ColumnSetContentType(1, 3);

Check Box Property

During the migration process, the TextOnLeft property does not migrate. If you require this property in WebFOCUS App Studio, set the Direction of text property in the Properties panel.