Document revision date: 19 July 1999

You can add EDT-style commands to EVE by creating "jacket" procedures that use EVE$EDT procedures. (The EVE source files are available in SYS$EXAMPLES.) Compile your procedures and save them in a section file, or put the procedures in a DECTPU command file. For example, the following procedures create two EVE commands, APPEND and CHANGE CASE, by using the procedures for the Append key and ChngCase key:

procedure eve_append return (EVE$EDT_APPEND); endprocedure; ! APPEND command procedure eve_change_case return (EVE$EDT_CHNGCASE); endprocedure; ! CHANGE CASE command

DECTPU contains the module EVE$BUILD, which you can use to:

• Modify EVE
• Layer products on EVE

EVE$BUILD compiles DECTPU code to produce a new section file. This new file can define either a new version of EVE or a new product.

When using these instructions, type uppercase strings exactly as they appear here. Replace lowercase strings with appropriate values. For example, in the expression product_MASTER.FILE, the string "product" indicates that you should substitute the product name of your choice. The string "MASTER.FILE" must be appended to the product name exactly as it appears in these comments.

These instructions cover the following:

• How to prepare code for use with EVE$BUILD
• How to invoke EVE$BUILD
• What happens when you use EVE$BUILD

For purposes of this section, it is assumed you have DECTPU code that modifies EVE or layers another product on EVE. To turn this code into a section file by using EVE$BUILD, follow the guidelines in this section.

You must observe special coding conventions for the following:

• Module identifiers
• Command parsers
• Initialization
• Command synonyms
• Status line fields
• Exit handlers
• Quit handlers

Organize the DECTPU code into one or more modules. To create a module, create a file that contains one or more DECTPU procedures and (if appropriate) one or more executable statements. All procedures and statements in a module should be related to the same task or subject. Then insert a new procedure at the beginning of the module. This procedure will return an "ident," or module identifier, which EVE$BUILD tracks during the build process. Use the following format for this procedure:

PROCEDURE facility_MODULE_IDENT RETURN "version-number"; ENDPROCEDURE;

In place of "facility," use a unique module identifier of up to 15 characters. If the module is part of a DIGITAL product, begin the identifier with the registered product facility code such as EVE or NOTES, followed by a dollar sign and the specific module name. For example, the EVE module EVE$CORE contains the procedure EVE$CORE_MODULE_IDENT.

If the code is not part of a DIGITAL product, do not use a dollar sign in the module identifier.

In place of "version-number," use any string of up to 15 characters identifying the version number of the module.

EVE$BUILD creates a list that shows the ident of each module it uses to build a section file. The list is written to a file referred to as the .LIST file. This file is discussed in Section D.2. In EVE, the format used for the version number string is Vnn-mmm. The characters nn represent the major version number of EVE to which the module belongs. The characters mmm represent the edit number.

For example, the following code is the _MODULE_IDENT procedure used by an older version of the module EVE$CORE.TPU:

PROCEDURE eve$core_module_ident RETURN "V02-242"; ENDPROCEDURE;

D.1.2 Command Parsers

EVE$BUILD can accommodate one or more user-written parsing routines in addition to the parser included in EVE. If you choose to include a parser in your product, the parser can either supplement or replace EVE's parser.

If you include one or more parsers in your product, the module that contains the parser should define a variable of the following form:

EVE$X_ENABLE_PARSER_facility

Replace the term "facility" with the name of the module in which the parsing routine appears. For example, if the parser occurs in the module SCHEDULER, the variable is as follows:

EVE$X_ENABLE_PARSER_SCHEDULER

Next, name the procedure that implements the parser. If the product is not a DIGITAL product, use the following format:

facility_PROCESS_COMMAND

Replace the term "facility" with the name of the module in which the parsing routine appears. For example, if the parser occurs in the module with the ident SCHEDULER_MODULE_IDENT, the procedure has the following name:

SCHEDULER_PROCESS_COMMAND

If the product is a DIGITAL product, use the following format:

facility$PROCESS_COMMAND

EVE has a procedure named EVE$PARSER_DISPATCH that defaults to the following code:

PROCEDURE EVE$PARSER_DISPATCH (the_command) EVE$PROCESS_COMMAND (the_command); ENDPROCEDURE;

If you do not define a parser-related variable, then EVE$BUILD puts this default EVE$PARSER_DISPATCH into the .INIT file. The .INIT file contains procedures that EVE$BUILD creates and compiles into the resulting section file. See Section D.2 for more information on the .INIT file.

If you do define one or more parser-related variables, EVE$BUILD verifies that a corresponding facility_PROCESS_COMMAND procedure exists for each variable. If not, the build fails. If the corresponding procedure does exist, EVE$BUILD then adds the following code to EVE$PARSER_DISPATCH just before the call to EVE$PROCESS_COMMAND:

IF EVE$X_ENABLE_PARSER_facility THEN status := facility_process_command (the_command); if status then if status = eve$k_informational then return (FALSE); else return (TRUE): endif; endif; ENDIF;

If you want a particular module's parser to supersede EVE's parser, your parser should return a true status whether or not EVE$K_INFORMATIONAL can parse a command. Your parser should return EVE$K_INFORMATIONAL if you want the execution of an initialization file (with the @ command) to stop when a command either fails to parse or fails to execute. If you want your parser to supplement EVE's parser, your parser should return a false status if it cannot parse a command. The false status allows the parsers in other modules, and finally EVE's parser, to try to parse the command. The parsers are called in the order in which they appear in the master file. (The master file is discussed in Section D.1.7.)

D.1.3 Initialization

EVE$BUILD allows module-specific initialization. To perform initialization in a module, put an initializing procedure in the module and use the following format to name the procedure:

facility_MODULE_INIT

Replace the term "facility" with the name of the module in which the procedure appears. For example, if it occurs in the module SCHEDULER, the procedure is named as follows:

SCHEDULER_MODULE_INIT

The EVE module EVE$CORE.TPU contains a null procedure called EVE$INIT_MODULES. EVE$BUILD replaces EVE$INIT_MODULES with a procedure that calls each procedure whose name ends with _MODULE_INIT. The initialization procedures are called in the order in which they are found in the master file. (The master file is discussed in Section D.1.7.)

EVE performs initialization in the following order:

1. Processes the procedure TPU$INIT_PROCEDURE
   DECTPU executes the procedure TPU$INIT_PROCEDURE immediately after processing the /DEBUG qualifier. TPU$INIT_PROCEDURE performs the following tasks:
   • Initialization of EVE's variables and settings
   • Module preinitialization
   • Initialization of EVE's buffers, windows, and files
   • Initialization of user-written modules
   • Call to the end user's initialization file, TPU$LOCAL_INIT
2. Processes the /COMMAND qualifier if it is present on the DCL command line
3. Processes the procedure TPU$INIT_POSTPROCEDURE
   DECTPU executes the procedure TPU$INIT_POSTPROCEDURE after processing the /COMMAND qualifier. TPU$INIT_POSTPROCEDURE performs the following tasks:
   • Execution of EVE commands in the initialization file
   • Creation and initialization of the $DEFAULTS$ buffer. This buffer is a template for all buffers created during an editing session. New buffers get settings from the $DEFAULTS$ buffer for attributes such as margin settings, direction, mode, and so on.

During the preinitialization phase, you can redefine EVE's variables and settings to be compatible with your product.

Do not redefine any EVE variable or setting unless you are sure you understand all the possible side effects on EVE and on your product. Use of this option is recommended only for experienced EVE programmers.

To use preinitialization, put an initializing procedure in a module and use the following format to name the procedure:

facility_MODULE_PRE_INIT

Replace the term "facility" with the name of the module in which the initializing procedure appears. For example, if it occurs in the module SCHEDULER, the procedure is named as follows:

SCHEDULER_MODULE_PRE_INIT

The EVE module EVE$CORE.TPU contains a null procedure called EVE$PRE_INIT_MODULES. EVE$BUILD replaces EVE$PRE_INIT_MODULES with a procedure that calls each procedure whose name ends with _MODULE_PRE_INIT. The initialization procedures are called in the order in which they are found in the master file.

Most programmers who are layering a product onto EVE should initialize modules by using procedures of the type facility_MODULE_INIT. Use of TPU$LOCAL_INIT should be reserved for the end user. Use of procedures of the type facility_MODULE_PRE_INIT should be reserved for experienced EVE programmers.

D.1.4 Command Synonyms

A command synonym is a string that produces exactly the same effect as an EVE command or phrase. Command synonyms are useful for creating foreign-language versions of EVE or a product layered onto EVE. For example, you could designate the Swedish string "näasta_bild" to have the same effect as the EVE command NEXT SCREEN.

With EVE$BUILD, you can create synonyms both for EVE and user-written commands and phrases. This discussion assumes that when you create a command synonym, you first choose a root command (the EVE command or user-written command for which you want to create a synonym), and then equate the synonym to the root command.

You can create synonyms in each module of your product. To create synonyms in a module, you must first create a facility_MODULE_INIT procedure, and then place the synonym declaration statements in the procedure.

You name the initializing procedure by using the following format:

facility_DECLARE_SYNONYM

Replace the term "facility" with the name of the module in which the procedure appears. For example, if you create the procedure in the module SCHEDULER, you would name the procedure as follows:

SCHEDULER_DECLARE_SYNONYM

To declare a synonym, use the EVE$BUILD_SYNONYM statement in the procedure. This command enters the root command and the synonym into the EVE data structure that associates synonyms with root commands. Use one EVE$BUILD_SYNONYM statement for each synonym you want to declare. The statement has the following format:

EVE$BUILD_SYNONYM ("root_command", "synonym", integer)

The parameters are as follows:

• root-command---A quoted string that names the command for which you want to declare a synonym. The string must not contain spaces. If the command contains more than one word, place an underscore between the words.
  synonym---A quoted string that names the synonym you want to associate with the root command. The string must not contain spaces. If the command usually contains more than one word, place an underscore between the words.
  integer---Either 0, 1, or 2.
  The value 0 tells EVE$BUILD that you, not EVE$BUILD, will create the procedure and parameters that implement the synonym. This value instructs EVE$BUILD to verify that the root command exists and to associate the root command with the synonym.
  The value 1 causes EVE$BUILD to perform the following tasks:
  • Verify that the root command exists.
  • Associate the root command with the synonym.
  • Create a new procedure that gives the synonym the same effect as the root command.
  • Declare how many parameters are expected by the procedure that is implementing the synonym. (That is, if the procedure implementing the root command requires two parameters, then the procedure implementing the synonym also requires two parameters.)
  • Initialize the parameters of the synonym procedure so they equal the parameters of the corresponding root procedure.
  
  The value 2 causes EVE$BUILD to associate the root with the synonym. Use this value if you are creating a synonym for a phrase rather than a command synonym.

Example

The following statement creates a Spanish synonym for the ONE WINDOW command and instructs EVE$BUILD to create the necessary structures for the synonym:

EVE$BUILD_SYNONYM ("one_window", "una_ventana", 1)

You can declare a synonym to be a terminator. A terminator is a command that, if bound to a key and executed with a keystroke, tells an EVE prompt to stop prompting. For example, when the DO command is bound to the DO key, pressing the DO key terminates most EVE prompts.

To make a synonym a terminator, use an EVE$MAKE_SYNONYM_A_TERMINATOR statement in the facility_MODULE_INIT procedure. For example, if you want to make the string "Haga" a synonym for "DO" and to declare "Haga" as a terminator, place the following statement in the facility_MODULE_INIT procedure for the module:

EVE$MAKE_SYNONYM_A_TERMINATOR ("DO", "Haga");

D.1.5 Status Line Fields

Using EVE$BUILD, you can create new areas for displaying information in the status line that EVE displays under each window. These areas are called "fields." By default, the EVE status line contains fields to display the following information:

• The buffer mapped to the window
• The write status of the buffer
• The text entry mode
• The direction of the buffer

A field can display more than one message. For example, the direction field in the default EVE status line can display either the string "Forward" or the string "Reverse."

To add a field to the status line, write a procedure that creates the field and includes the procedure in the appropriate module. The following sample procedure creates a field that indicates whether a buffer is a read-only buffer:

! Procedure to put up the "Read-Only" indicator on NO_WRITE buffers PROCEDURE eve$nowrite_status_field (the_length, ! Status line indicator the_format) ON_ERROR [OTHERWISE]: ENDON_ERROR; IF GET_INFO (CURRENT_BUFFER, "no_write") THEN RETURN FAO (the_format, eve$x_read_only); ELSE RETURN FAO (the_format, eve$x_write); ENDIF; ENDPROCEDURE;

Use the following conventions for procedures:

• Use the following format for the procedure name:

  field_name_STATUS_FIELD

  
  For example, if you are adding a field to display the current line number and if your facility is called SCHEDULER, the first line of the procedure appears as follows:

  PROCEDURE SCHEDULER_LINE_NUMBER_STATUS_FIELD

• Give the procedure the following input parameters:
  • the_length---The number of unused column spaces in the status line before the new field is added to the line. Use this parameter to ensure that all messages fit on the status line.
  • the_format---The FAO directive to be used to format the field.

The module EVE$CORE.TPU contains a procedure called EVE$GET_STATUS_FIELDS that returns the null string. EVE$BUILD replaces EVE$GET_STATUS_FIELDS with the following procedure in the .INIT file:

PROCEDURE EVE$GET_STATUS_FIELDS (the_length, the_format) LOCAL remaining, the_fields, the_field; the_fields := ""; remaining := the_length; RETURN the_fields ENDPROCEDURE;

For each _STATUS_FIELD procedure you put in a module, EVE$BUILD inserts the following code just before the "RETURN the_fields" statement:

the_field := field_name_STATUS_FIELD (remaining, the_format); IF LENGTH (the_field) <= remaining THEN the_fields := the_field + the_fields; remaining := remaining - LENGTH (the_field); ENDIF;

D.1.6 Exit and Quit Handlers

When you create a new or layered product, you can provide one or more user-written exit handlers, one or more user-written quit handlers, or one or more of both. Depending on how you write the handlers, EVE$BUILD uses your exit or quit handlers to either supplement or replace those provided by EVE. This section contains pointers on writing both supplementary and replacement handlers.

When you write an exit handling procedure, use the following format to name the procedure for a non-DIGITAL product:

facility_EXIT_HANDLER

Use the following format for a non-DIGITAL quit handler:

facility_QUIT_HANDLER

Replace the term "facility" with the name of the module in which the handler appears. For example, if the handler occurs in the module with the ident SCHEDULER_MODULE_IDENT, you name an exit handling procedure as follows:

SCHEDULER_EXIT_HANDLER

You would name a quit handling procedure as follows:

SCHEDULER_QUIT_HANDLER

If the product is a DIGITAL product, use the following format to name the procedure for an exit handler:

facility$EXIT_HANDLER

Use the following format for a quit handler:

facility$QUIT_HANDLER

EVE has procedures named EVE$EXIT_DISPATCH and EVE$QUIT_DISPATCH. By default, EVE$EXIT_DISPATCH contains the following code:

PROCEDURE EVE$EXIT_DISPATCH EVE$EXIT; ENDPROCEDURE;

By default, EVE$QUIT_DISPATCH contains the following code:

PROCEDURE EVE$QUIT_DISPATCH EVE$QUIT; ENDPROCEDURE;

If you do not create an exit or quit handling procedure, EVE$BUILD puts the default versions of EVE$EXIT_DISPATCH and EVE$QUIT_DISPATCH into the .INIT file. If you create an exit handling procedure, EVE$BUILD adds the following code to EVE$EXIT_DISPATCH just before the call to EVE$EXIT:

IF facility_EXIT_HANDLER THEN RETURN; ENDIF;

If you create a quit handling procedure, EVE$BUILD adds the following code to EVE$QUIT_DISPATCH just before the call to EVE$QUIT:

IF facility_QUIT_HANDLER THEN RETURN; ENDIF;

If you want a particular module's exit or quit handler to supersede EVE's handler, your handler should return a true status. If you want your handler to supplement EVE's handler, your handler should return a false status. The false status allows EVE$BUILD to call the handlers in other modules and finally in EVE.

	privacy and legal statement
6021PRO_019.HTML