Workbench PL/I editor

Workbench PL/I Editor is an available option for edit, browse, and open actions for files with extensions such as .pli and .pl1. It provides colorization for language syntax, an outline view to assist navigation through the code, code folding functionality, and other functionality that is customized via preference settings. This editor does not allow code to extend beyond column 72.

To find a text string or EBCDIC hex characters

The editor supports default Eclipse functionality for finding text. In addition, users can find EBCDIC hex and all occurrences of a text string or EBCDIC hex characters, as described below.

1. In the editor, do any of the following:

   • Click CTRL+F.
   • Highlight the desired search text in the editor and click CTRL+F.
   • From the Edit menu, select Find/Replace.

   The Find/Replace dialog box appears.

2. Do any of the following:
   
   • To find a text string, in the Type box, select String.
   • To find all occurrences of a text string, in the Type box, select String, then select the Find all occurrences check box.
   • To find a EBCDIC hex characters, in the Type box, select EBCDIC hex.
   • To find all occurrences of EBCDIC hex characters,in the Type box, select EBCDIC hex, then select the Find all occurrences check box.
3. Complete the remainder of the dialog box as desired.
4. Click Find.

• • When searching for all occurrences, the matches are highlighted in the editor and the Search view shows the results. Refer to the Eclipse documentation for information about the Search view.

  • When searching for EBCDIC hex characters, the matches (whether in the Search view or in the editor) show the UTF display value based on the currently selected code page. For example, searching for F1F2F3F4F5 finds 12345 when using code page 1047 in the editor.

To use the outline view

1. If the Outline view is not already open, from the Window menu, select Show View>Outline. The Outline view displays an outline of the structural elements in the file that is open in the editor.
2. To position the cursor at a given structural element, click the element in the Outline view.

To select a block of code

Toggle Block Selection functionality allows users to select a block of code and then copy it, delete it, or replace it.

1. Do one of the following:
   • Right-click in the editor and select Toggle Block Selection.
   • Within the editor, press Alt+Shift+A.
2. Drag the crosshairs to select the desired code.
3. Do any of the following:

• 
  
  • To delete the code, click Delete.
  • To copy the code, press Ctrl+C. To paste it elsewhere, place the cursor in the new position and press Ctrl+V.
  • To replace the code, begin typin

To understand indentation within the editor

The following applies to indentation within the editor:

• Newlines after an IF, ELSE, or DO statement will be indented according to the Workbench PL/I Editor's Displayed tab width preference.
• When "ELSE" is typed, it will be aligned with its corresponding IF statement.

To use templates

Templates can be used from within the Workbench PL/I Editor or from the Templates view.

From the editor

1. In the editor, place the cursor where the template should be inserted within the PL/I program:
   • To list all defined templates, place the cursor after a space
   • To list templates that match a keyword, place the cursor immediately after the keyword
   • To filter the list of templates to those that match typed text, enter the filter text and place the cursor at the end of the desired text
2. Press Ctrl+Space. The list of templates appears.
3. Select the template to use and press Enter. The template is inserted into the program at the insertion point.

From the templates view

1. From the Window menu, select Show View>Other>General>Templates. The Templates view appears.
2. In the editor, position the PL/I program at the desired line.
3. In the Templates view, right-click the desired template and select Insert. One of the following occurs:

• 
  
  • The template is inserted into the program at the insertion point
  • If there is input for the selected template, the Input Assistance dialog box appears. Complete the dialog box and click OK. The template is inserted into the program at the insertion point.

Refer to the information below on setting template preferences. Refer to the Eclipse documentation for more information about templates.

To use hover functionality to see a variable's or a copybook's definition

1. Open the program in edit or browse mode in the editor.
2. If the PL/I source references copybooks, click Yes on the message that appears asking whether to download the copybooks. The copybooks are downloaded. Clicking No prevents copybook download and therefore disables hover functionality for copybooks.
3. Hover the cursor over the desired variable name or a copybook name in an INCLUDE statement. A tool tip appears showing the definition.

To go to a variable's definition

Do one of the following:

• Right-click the variable and select Open Definition.
• Select the variable and press F3.

If the variable definition is in the same file as the right-clicked variable, the open editor window moves to the line where the definition exists. If the variable definition is in a different file (copybook), then the copybook opens in a separate editor window, positioned at the appropriate line.

To go to a copybook's definition

Do one of the following:

• Right-click the copybook name and select Open Definition.
• Select the copybook name and press F3.
• Hover as described above and press F2 while the tooltip is displayed. Then click .

The copybook opens in a separate editor window, positioned at the appropriate line.

To change the case of the selected text

1. Select the desired text in the editor.
2. Right-click the text and do either of the following:

• 
  
  • To change the text to uppercase, select Source>To Upper Case.
  • To change the text to lowercase, select Source>To Lower Case.

To identify the scope of a statement

The Workbench PL/I Editor allows users to identify the beginning and end of a statement, such as DO/END and IF/ELSE, SELECT/END, BEGIN/END, PACKAGE/END, and PROC/END.

1. Select the keyword at the beginning or end of the statement. A box appears around the keyword.
2. Click Ctrl+Shift+P. A box appears around the keyword at the opposite end of the statement.

To use code folding functionality

Code folding allows users to select code blocks to be folded (collapsed) so only the first line of code is visible. Conversely, folded code can be unfolded (expanded) code so the entire block of code is visible. The presence of a (minus sign) or (plus sign) to the left of the code indicates the syntax for which this functionality is available.

Do any of the following:

• To fold code, click the to the left of the block of code.
• To unfold code, click the to the left of the line of code.
• To fold all collapsible regions in the program, right-click the line number area and select Folding>Collapse All.
• To unfold all collapsible regions in the program, right-click the line number area and select Folding>Expand All.
• To toggle code folding on or off, right-click in the line number area and select Folding>Toggle Code Folding.
• To display a preview of folded code in a popup window, hover over the to the left of the line of code.

To comment out/uncomment selected lines of code

1. Select the desired lines.
2. Do one of the following:

• 
  
  • Right-click and select Source>Toggle Comment.
  • Click CTRL+ /.

The selected lines are commented out or uncommented, depending on their original state.

To add or remove bookmarks or tasks

The editor supports the default Eclipse functionality for adding and removing bookmarks and tasks. However, markers only persist for files stored in projects, not those opened from Host Explorer. When a marker is added or the editor is closed, a warning message notifies users that the markers will be deleted. This warning can be customized as described below.

Do either of the following:

• To disable the warning message, click the Don't show this warning again check box on the warning message.
• To re-enable the warning message, from the Window menu, select Preferences. Toggle open the node and select Editors. Select the Show warning when adding bookmarks and tasks outside of projects check box.

To add/remove a block comment

Block comments are used to comment out a portion of the source code.

1. Select the block of text.
2. Do one of the following:

• 
  
  • To add a block comment: Right-click and select Source>Add Block Comment or click CTRL+ Shift+ /.
  • To remove a block comment: Right-click and select Source>Remove Block Comment or click CTRL+ Shift+ \.

The selected lines are commented out or uncommented, depending on their original state.

To view, edit, and insert a character using hex

The Workbench for Eclipse editors allow users to view the value of a non-displayable character, edit a character using hex, and insert a character using hex.

1. In the editor, do any of the following:
   • To view the value of a non-displayable character, highlight the character (represented by ), right-click, and select Source>Edit Character using Hex. The Edit Character dialog box appears and the EBCDIC hex value field shows the hex value of the non-displayable character. To change the character, enter its EBCDIC hex value.
   • To edit a character using hex, select the character, right-click, and select Source>Edit Character using Hex. The Edit Character dialog box appears. Enter the desired value in the EBCDIC hex value field.
   • To insert a character using hex, place the cursor in the desired location, right-click, and select Source>Insert Character using Hex. The Insert Character dialog box appears. Enter the desired value in the EBCDIC hex value field.
2. Click OK.

To edit a single line using hex

The Workbench for Eclipse allows users to edit a single line of characters, including non-displayable characters, using a vertical hex editor.

1. In the Workbench editor, select the desired line, click  or right-click and select Source>Toggle Hex Line Editor. The hex line editor appears and shows the hex value of the non-displayable characters in a four-line hex display. The first line shows the readable characters; the second, and third rows show the vertical EBCDIC hex value of each character. When logged in with a code page supporting double byte characters, the fourth line displays the ideogram for any double-byte characters in the text. The fourth line cannot be used for editing.

   Important

   Repeat any of these methods to toggle the hex line editor closed.

2. In the hex line editor, use the arrow keys or mouse to select the character to change in either the first line (readable text) or the hex value rows, then enter the new value. To append characters to the end of the line, continue entering data when the cursor is at the end of the line.

To delete text in the CTLASA column and the program identification area

The contents of the editor's column 1 (CTLASA) and columns 73-80 (the program identification area) can be quickly and easily deleted.

1. In the editor, right-click and select Source>Denumber. The Denumber dialog box appears.
2. Select the check boxes for the columns to be denumbered.

3. If Cols 73-80 was selected, do either of the following:

   • 
     
     • To clear fields that contain only numbers, select Clear numeric fields only.

   • 
     
     • To clear all fields, select Clear all fields.
4. Click Denumber. The applicable text is deleted from the source file.

To set general preferences

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Toggle open the node, toggle open the Editors node, and select PL/I. The PL/I preferences page appears.
3. Select the General tab.
4. Do any of the following:
   • To set general text editor preferences, click Text Editors. The Text Editors page appears. Make any desired changes and click OK.
   • To change the font properties used in the editor, click Colors and Fonts. The Colors and Font page appears. Make any desired changes and click OK.
   • Displayed_tab_width To set the tab width displayed in the editor, enter the desired tab width in the Displayed tab width field.
   • To highlight the current line in the editor, select the Highlight current line check box.
   • To type in all capital letters, select the Type in ALL CAPS check box. While in the editor, pressing Ctrl+Shift+Z toggles the option.  in the status bar indicates that the preference is on; a grayed-out icon indicates that it is off.
   • To make the print margin visible in the editor window, select the Show print margin check box and enter in the Print margin column field the column number for the start of the print margin.
5. Click OK.

To set syntax processing preferences

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Toggle open the node, toggle open the Editors node, toggle open the PL/I node, then select Syntax Processing. The Syntax Processing preferences page appears.
3. Do any of the following:
   • • To turn on syntax checking so that markers are added on lines with syntax errors, check the Enable syntax checking check box.

     • To set the margins within which the PL/I parser will parse, either select the Default button or select the Custom button and enter the custom margins in the Left and Right fields.

To set template preferences

Templates allow users to quickly insert frequently used blocks of code. The Templates preferences page is used to view a list of available templates, information about those templates, and a visual representation of the template. It also allows users to create, edit, remove, import, and export templates. The following describes the fields on the dialog boxes used in these processes:

• Name: The name given to the template.
• Context list: A list of the available contexts.
• Automatically insert check box: Allows the template to be automatically inserted when it is the only available proposal available at the position.
• Description: A short description of the template.
• Preview: Shows a visual representation of the template.
• Insert Variable: This functionality is not currently supported for PL/I templates.

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Toggle open the node, toggle open the Editors node, and toggle open the PL/I node.
3. Select Templates. The Templates preferences page appears and displays the templates in the current workspace.

4. Do any of the following:

   • To disable a template from appearing in any list of available templates (in the editor or in the Templates view), clear the check box in front of the template.
   • To create a new template, click New. Complete the New Template dialog box according to the definitions above and click OK. The new template is added to the table on the Templates preferences page.
   • To edit a template, select the template and click Edit. Complete the Edit Template dialog box according to the definitions above and click OK. The edits are reflected in the table on the Templates preferences page.
   • To remove a template, select the template and click Remove. The template is removed from the table on the Templates preferences page.
   • To restore any BMC-provided templates that were previously removed, click Restore Removed.
   • To revert a selected template to its BMC-provided state, click Revert to Default.
   • To export selected templates, select the templates and click Export. On the resulting dialog box, select the location for the export and click OK.
   • To import templates, click Import. On the resulting dialog box, select the location of previously exported templates and click Open.
   • To remove any user-created templates and restore all BMC-provided templates to their default states, click Restore Defaults.

   Important

   The Auto Insert column indicates whether the automatically insert functionality is activated for the selected template. The default is off, as indicated by a blank value. When this functionality is activated, the column shows on.

5. Click Apply and Close.

To set color preferences

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Toggle open the node, toggle open the Editors node, and select PL/I. The PL/I preferences page appears.
3. Select the Colors tab.
4. To change the colors used in the editor, select the item from the list and click Color. The Color dialog box appears. Select the desired color and click OK. The changes are reflected in the Preview box.
5. Click OK.

To set background preferences

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Toggle open the node, toggle open the Editors node, and select PL/I. The PL/I preferences page appears.
3. Select the Background tab.
4. To change the background colors used in the editor, select the color box adjacent to the item. The Color dialog box appears. Select the desired color and click OK.
5. Click OK.

To set content assist preferences

Content assist offers a pop-up list of choices for completing PL/I code based on the text entered so far. The content assist preferences allow users to set preferences that control content assist behavior.

1. From the Window menu, select Preferences. The Preferences dialog box appears.
2. Select BMC>Editors>PL/1>Content Assist. The Content Assist page of the Preferences dialog box appears.
3. Use the Enable auto activation check box to enable or disable the automatic display of the content assist list. By default, content assist is enabled.
4. In the Auto activation delay (ms) field, enter the number of milliseconds Workbench for Eclipse should wait before presenting the content assist pop-up list of choices.