This appendix provides an overview of the optional Language-Sensitive Editor (LSE) productivity tool. ACMS software does not include this tool; you must purchase it separately. For information on how to purchase this tool, contact your Compaq sales representative.

D.1 Using LSE with ACMS

LSE is a text editor designed specifically for software development with features that help you produce syntactically correct ACMS code. With LSE, you can:

• Edit programs or text files using standard text editor commands with either the EDT or EVE keypad
• Use formatted language constructs to quickly develop syntactically correct programs
• Use two windows and multiple buffers
• Review and correct compilation errors from the editing session
• Customize your editing environment
• Integrate with other VAXset tools and products

In ACMS, you can use LSE for creating application, menu, task, and task group definitions for processing by the Application Definition Utility (ADU). Some of the key features of LSE when used with ACMS include:

• Creating source code
• Using placeholders and tokens
• Reviewing diagnostic files
• Getting ACMS-specific help for placeholders and tokens created by LSE

There are five LSE templates, one each for syntax for ACMS application definitions, task group definitions, task definitions, and menu definitions. The fifth template can be used for any of the four ACMS definition types.

There are two ways to invoke an LSE template for an ACMS definition. At the DCL prompt, do one of the following:

• Issue the LSEDIT command followed by a file name with one of these file extensions:
  • .ADF --- For the ACMS application definition template.
  • .GDF --- For the ACMS task group definition template.
  • .TDF --- For the ACMS task definition template.
  • .MDF --- For the ACMS menu definition template.
  • .ADU --- Invokes LSE with a template that can be used for any of the four preceding ACMS definitions. You can include more than one type of ACMS definition in a file with a .ADU extension.
• Issue the LSEDIT command with the /LANGUAGE qualifier and one of the following languages, followed by a file name with any file extension:
  • ACMS$APPLICATION --- For the ACMS application definition template.
  • ACMS$TASK_GROUP --- For the ACMS task group definition template.
  • ACMS$TASK --- For the ACMS task definition template.
  • ACMS$MENU --- For the ACMS menu definition template.

For example:

$ LSEDIT ADDCAR.TDF

or:

$ LSEDIT/LANGUAGE = ACMS$TASK ADDCAR.TDF

The ADU file type tells LSE to use the ADU template for a task group definition.

You can also use LSE as the editor of choice with ADU EDIT and MODIFY commands. To do this, you must define the ADU$EDIT logical name to point to a command procedure that invokes LSE. For example, in the following command line, the ADU$EDIT process logical name points to the command procedure LSEDIT.COM:

$ DEFINE ADU$EDIT "LSEDIT.COM"

The command procedure LSEDIT.COM actually invokes LSE. You can devise your own command procedure to perform this task or you can use the one shown in Example D-1.

Example D-1 LSEDIT.COM File

$ ! LSEDIT.COM - Invoke VAXLSE for ADU $ ! $ ! Inputs: $ ! $ ! P1 = Input file name $ ! P2 = Output file name $ ! $ ! Note that this procedure is run in the context of a spawned $ ! subprocess. Though LOGIN.COM is not executed when this $ ! subprocess starts, the spawning procedure copies the symbols $ ! and logicals from the spawning process. $ ! The default directory for the subprocess is the same as $ ! that for the spawning process. $ ! $ ASSIGN/USER 'F$LOGICAL("SYS$OUTPUT")' SYS$INPUT $ IF P1 .EQS. "" THEN GOTO NOINPUT $ LSEDIT /LANGUAGE=ACMSADU /OUTPUT='P2' 'P1' $ EXIT $ NOINPUT: $ LSEDIT /LANGUAGE=ACMSADU 'P2'

This command procedure accepts a definition file or command file for input. It then invokes LSE, edits the definition file or command file using ACMSADU language type, and produces a listing file if specified.

When you invoke LSE to create a new file with the .TDF extension, your terminal screen displays the text:

{TASK_definition}

Similarly, when you invoke LSE with the .ADF, .GDF, or .MDF extensions, your terminal screen displays initial template information for application, task group, and menu definitions.

D.2.1 Using Placeholders and Tokens in LSE

At the bottom of the screen shown in Figure D-1, LSE displays a bar containing TPU editing information. The phrase TASK_definition appears at the top of the screen. LSE provides this phrase, called a placeholder, as a starting template to aid you in coding your application. LSE surrounds a placeholder with:

• A pair of curly braces ({}) to represent a place in the source code where the user must provide additional program text
• A pair of square brackets ([]) to represent optional syntax which the user can delete or modify

The curly braces surrounding the phrase TASK_definition indicate that the phrase represents a required language construct.

Figure D-1 Creating a New File with LSE

In order to get template entries for a placeholder, you must move your cursor to the placeholder and expand it by using special LSE key sequences or key bindings. The most commonly used LSE commands and their default key bindings are:

• EXPAND (CTRL/E)
• GOTO PLACEHOLDER/FORWARD (CTRL/N)
• ERASE PLACEHOLDER (CTRL/K)
• GET LSE COMMAND LINE (CTRL/Z)
• HELP/INDICATED (PF1-PF2)

The HELP/INDICATED command summons ADU help for the token or placeholder on which you place your cursor. See Section D.5 for a description of help within the LSE template.

Suppose that you want to duplicate the source definition file ADDCAR.TDF shown in Example 2-2.

Use the EXPAND command to display in the editing buffer the clauses associated with the placeholder on which your cursor rests. Figure D-2 shows the result when you use the EXPAND command on the LSE phrase TASK_definition. You can also expand these clauses until you display the options necessary to create the source code for your particular task.

Figure D-2 Expanding a Placeholder

The cursor now rests on the [REPLACE_TASK|CREATE_TASK] placeholder. Use the EXPAND command again to list the additional options for that placeholder. Figure D-3 displays these options with the an arrow on the first choice.

Figure D-3 Expanding the REPLACE TASK |CREATE TASK Placeholder

To select an option from this menu, use the up and down arrow keys to position the pointer at one of the options and press [Return]. Figure D-4 shows the display you receive when you select the option REPLACE_TASK.

Figure D-4 Choosing REPLACE_TASK

LSE inserts the clause REPLACE_TASK into the buffer and displays a new string of arguments associated with the REPLACE clause. When you expand the placeholder path name, LSE displays the following message:

Enter the CDD path name of the object in the CDD

In Example 2-2, the object name is ADD_CAR_RESERVATION_TASK. When you type this object name, LSE automatically removes the placeholder path name from the display.

Move the cursor to the [replace_qualifiers] placeholder with the command GOTO PLACEHOLDER/FORWARD [Ctrl/N]. Since the REPLACE TASK clause in Example 2-2 does not contain any qualifiers, you can delete the placeholder with the ERASE PLACEHOLDER command [Ctrl/K]. When you erase a placeholder, LSE automatically positions the cursor at the next placeholder.

Note that when you attempt to delete a required placeholder (signified by curly braces), LSE returns the following message:

This is a required placeholder. Continue erase operation [Y or N]?

You can also use LSE to enter comments. Figure D-5 demonstrates the expansion of the ![definition_comment] placeholder.

Figure D-5 Expanded Comment Placeholders

The string ~tbs~ stands for to be supplied and indicates where you need to provide additional information.

Example 2-2 contains a line at the top of the file for which LSE did not give the user a prompt. That line is:

SET VERIFY

You can request that LSE prompt you for this line by expanding a token. A token is a keyword specific to ADU syntax. LSE does not provide tokens in the same way it provides placeholders. Instead, you must type a token directly into the buffer to add an ADU clause when there are no placeholders in the existing program. When you expand the token, LSE displays the available options in the same way it displays options for placeholders.

Figure D-6 demonstrates token expansion. The user has typed a portion of the token for the ADU clause SET VERIFY and expanded the token. LSE displays the option menu from which the user can select the SET_VERIFY clause.

Figure D-6 Expanding Tokens

You can also use tokens to bypass menus in cases where expanding a placeholder would result in a lengthy menu.

LSE also provides a COMMENT token that you can expand to include inline code. To use the COMMENT token, type the word COMMENT and expand the token. LSE inserts the following line at the position indicated by the cursor:

![inline_comment]

When you expand this new placeholder, LSE inserts the following lines into your program:

!++ ![~tbs~]... !--

LSE positions the cursor on the placeholder ~tbs~, which stands for to be supplied. You can then enter comment text.

D.2.2 Creating the Final Source File

By using this process of expanding, selecting, moving to, and deleting placeholders and tokens and adding text where necessary, you can use LSE to create a source file that looks something like Figure D-7.

Figure D-7 Final Source File Created with LSE

The syntax generated by LSE may differ slightly from syntax that you use. For example, the source file produced by LSE contains expanded versions of the ADU clauses, such as PROCESSING WORK IS, where you may simply use PROCESSING. Both versions are correct. Whether or not you use the expanded syntax and different spacing depends on the programming conventions used at your site.

D.2.2.2 Exiting Editing Mode

Once you finish editing text, you can save the file and process it. To exit editing mode, press [Ctrl/Z]. LSE opens a command line preceded by the prompt LSE> at the bottom of the screen. At this command prompt you can:

• EXIT or QUIT the LSE session
• Access HELP
• Enter LSE and SCA commands
• Continue editing

For example, to continue editing, use the CONTINUE command:

LSE> CONTINUE

LSE then positions your cursor in the editing buffer.

To leave the LSE session and save your editing changes, use the EXIT command:

LSE> EXIT

LSE then writes the buffer to a file and exits to the DCL level. You can then process your file with ACMS.

D.3 Compiling Definitions with LSE COMPILE

ACMS lets you use the LSE COMPILE command from within an LSE editing session to create, modify, or replace a task, task group, application, or menu definition. To use the COMPILE command, you must include the ADU CREATE, REPLACE, or MODIFY command in the definition, and enter COMPILE at the the LSE prompt.

LSE> COMPILE ADDCAR.TDF

LSE then displays the following message, indicating the start of the compilation:

Starting compilation: @SYS$LIBRARY:ACMS$LSE_COMPILE.COM ADDCAR.TDF

When the compilation is finished, LSE displays the following message:

Compilation of buffer ADDCAR.TDF completed

The ADU language templates define the LSE COMPILE string as "@SYS$LIBRARY:ACMS$LSE_COMPILE.COM". LSE passes the definition filename as a parameter to the ACMS$LSE_COMPILE.COM command procedure. The command procedure then enters ADU and invokes the definition file, using the @ command.

If ADU finds an error in the CREATE, REPLACE, or MODIFY command, ACMS does not create the LSE diagnostics file, and LSE does not display any messages referring to the error.

D.4 Examining Diagnostic Messages with LSE REVIEW

The REVIEW command issued within an LSE session enables you to display a diagnostics file at the same time you are examining the source code that generated the diagnostics file. ACMS creates the diagnostics file when you attempt to create, modify, or replace a definition with the /DIAGNOSTICS qualifier.

When you process the definition, ACMS creates a separate diagnostics file using the entity name and a .DIA extension. You can then use LSE to review the source code and the diagnostics file with a split screen.

D.4.1 Generating the Diagnostics File

Suppose you have created a definition file called ADDCAR.TDF and want to generate a diagnostics file to aid you in fixing coding errors. The REPLACE command in the definition file contains the task name with /DIAGNOSTICS qualifier required to produce the diagnostics file:

REPLACE TASK ADD_CAR_RESERVATION_TASK/DIAGNOSTICS

When you compile the definition file ADDCAR.TDF in ADU, ACMS produces a diagnostic file called ADD_CAR_RESERVATION_TASK.DIA.

ACMS names the diagnostic file after the entity, not after the source file. For example, if your source file is CLOCKS.GDF and you have defined a task group called GRANDFATHER with the /DIAGNOSTICS qualifier in the file, ACMS names the resulting diagnostics file GRANDFATHER.DIA.

If you want the name of the diagnostic file to be different than the entity name, specify the filename with the /DIAGNOSTICS qualifier. For example:

REPLACE GROUP CLOCKS/DIAGNOSTICS=CLOCKS.DIA

D.4.2 Examining the Diagnostics File with LSE REVIEW

To examine the diagnostics file, invoke LSEDIT and supply the name of the source file:

$ LSEDIT ADDCAR.TDF

Obtain the LSE> prompt by pressing [Ctrl/Z]. Then issue the REVIEW command, supplying the name of the diagnostics file:

LSE> REVIEW/FILE=ADD_CAR_RESERVATION_TASK.DIA

If your compilation was successful and the diagnostic file contains no errors, LSE displays the following message:

Compilation produced no errors

Because the compilation was error free, LSE does not display the .DIA file. If you make an error in the ADU command line of the task definition, ADU does not compile the task definition, and a success status is returned.

If the compilation was unsuccessful and the diagnostic file contains error messages, the screen displays two buffers --- one at the top half of the screen and one at the bottom half --- as shown in Figure D-8.

Figure D-8 Examining Diagnostic Files with LSE REVIEW

The window at the top of the screen contains the $REVIEW buffer that displays diagnostic messages. The window at the bottom of the screen contains the source file text. By moving between these two windows, you can review the compilation errors and correct the corresponding code.

Table D-1 lists some commands you can use at the LSE> prompt to move between the $REVIEW buffer and the source code buffer.

Table D-1 LSE REVIEW Window Commands

Command	Default Key Binding	Description
NEXT ERROR	[Ctrl/N]	Highlights next error message in the $REVIEW buffer
GOTO SOURCE	[Ctrl/G]	Highlights source line corresponding with error message currently highlighted in the $REVIEW buffer
CONTINUE	[Ctrl/Z]	When used after GOTO SOURCE, places cursor in source code buffer for editing. To return to REVIEW mode, press [Ctrl/Z].
PREVIOUS ERROR	[Ctrl/B]	Highlights previous error line in $REVIEW buffer
END REVIEW	None	Terminates review. Removes $REVIEW buffer from screen and displays source code buffer only.

When you start the REVIEW session, LSE highlights the first error message in the $REVIEW buffer. To find the source code corresponding with this error message, use the GOTO SOURCE command:

LSE> GOTO SOURCE

In the lower part of the screen, LSE then displays and highlights the line of source code that generated the error. To edit the source code, use the CONTINUE command:

LSE> CONTINUE

You can now enter your changes in the source code buffer. Once you have made your changes, you can return to the LSE command by typing [Ctrl/Z].

When you have completed your review of the diagnostics file, you can terminate the review session by entering the END REVIEW command at the LSE> prompt:

LSE> END REVIEW

LSE then removes the diagnostics file from your screen and displays the source file.

When you use the REVIEW command, you must call the correct version of the diagnostics file generated by the source file you are currently editing. For example, suppose you compiled ADDCAR.TDF;4 to generate the diagnostics file ADD_CAR_RESERVATION_TASK.DIA;4. If you create another version called ADDCAR.TDF;5 but do not recompile it to generate a matching .DIA file, you will receive the following message when you attempt to use the GOTO SOURCE command during LSE REVIEW mode:

File in buffer is not the version compiled

When you receive this message, you can perform either of the following actions to resolve the problem:

• Enter the LSE COMPILE command to recompile the source file to generate a new diagnostics file. Then enter the REVIEW command. When you enter the REVIEW command and the file specification, LSE reads the most recent version of the .DIA file into the buffer.
• End the LSE session. Invoke LSE again and specify the source file name and the version number. For example, although ADDCAR.TDF;5 is the most recent version, you want to debug ADDCAR.TDF;4 with its corresponding diagnostics file, ADDCAR.DIA;4. Therefore, at the DCL level, specify the file name and version number:

  LSE> ADDCAR.TDF;4

  
  Then invoke REVIEW as you normally would. To ensure that you are requesting the correct version of the .DIA file, you can specify the version number:

  $ LSE> REVIEW/FILE=ADDCAR.DIA;4

  
  If you try to use REVIEW with a diagnostics file that was not generated from the source file you are displaying, LSE REVIEW attempts to match errors in the diagnostics file with lines in the source file. To avoid such confusion, always delete outmoded .DIA files.

LSE includes a help system for navigating and editing within the buffer being edited. Press [Help] within an LSE editing buffer to get a description of the LSE editing commands and key definitions.

LSE also provides access to context-senstive ADU help for ACMS. Within the LSE editing sesion, place your cursor on any placeholder or token and use the HELP/INDICATED command ([PF1] [PF2]). LSE summons an appropriate ADU help message from the ADU help message file. Just as when you type a series of help topics to reach a particular help message, the help message indicates the topic titles that led to the message for the placeholder or token for which you summoned help. For example, the help message for the placeholder GROUP in a task definition file is:

TASK WORKSPACES Keywords GROUP Identifies the workspace as a GROUP type workspace. The contents of a GROUP workspace can be used by many instances of the same or different tasks. ACMS maintains these contents from application startup to application shutdown.

You cannot move back up the topic path within the LSE editing session. However, if there are additionial subtopics for the current topic, you can reach them as you would for subtopics through the ADU HELP command.

If you type a portion of a token and press [PF1] [PF2], you get a message for each ADU keyword that could be expanded from the portion you typed. The messages correspond to the choices on the option menu that appears if you expand the partial token. For example, if you type the partial token SET as shown in Figure D-6, and then press [PF1] [PF2], you get help for each ADU keyword listed in the options menu.

For more comprehensive information on other LSE features, consult VAX Language-Sensitive Editor and VAX Source Code Analyzer User Manual.