Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Extensible Versatile Editor Reference Manual


Previous Contents Index

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 


Appendix D
EVE$BUILD Module

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

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:

D.1 Preparing Code for Use with 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:

D.1.1 Module Identifiers

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:
  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:

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:

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:

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:

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6021PRO_019.HTML