System Management

Setting Up Alternate Editors

VA FileMan supplies two editors, the Line and Screen Editors, for entering and changing text in WORD-PROCESSING-type fields. Other editors can be made available by using the ALTERNATE EDITOR file (#1.2). Entries in this file specify the M code used to call the Alternate Editor and to restore the VA FileMan environment after work in the editor is complete.

The user can choose an editor in two ways:

1. The PREFERRED EDITOR field in the NEW PERSON file (#200) is a pointer to the ALTERNATE EDITOR file (#1.2). Any entry in the ALTERNATE EDITOR file can be selected as a Preferred Editor. Then, whenever a WORD-PROCESSING-type field is presented for editing, the user is automatically switched into this Preferred Editor.
   
   
2. From the Line Editor, the user can switch to any of the editors in the ALTERNATE EDITOR file temporarily by using the Editor Change option on the UTILITIES submenu. After exiting the chosen editor, the user is returned to the Line Editor.

NOTE: The "Choice of Word-processing Editors" chapter of the "VA FileMan Getting Started Manual" contains additional information about selecting editors.

ALTERNATE EDITOR File Entries

The requirements of the ALTERNATE EDITOR file's fields are explained in the following example of the creation of an entry in that file:

Select OPTION: ENTER OR EDIT FILE ENTRIES  

INPUT TO WHAT FILE: ALTERNATE EDITOR   (2 entries)
EDIT WHICH FIELD: ALL// 
Select ALTERNATE EDITOR: VMSEDT
  Are you adding 'VMSEDT' as a new ALTERNATE EDITOR (the 3RD)?  No// YES   (Yes)

An entry needs to be added to the ALTERNATE EDITOR file. The NAME of every entry must begin with a unique character. This name is used to select the editor.

The required ACTIVATION CODE FROM DIWE field contains M code that will invoke the Alternate Editor. In this case, a routine supplied by Kernel that invokes the VMS editor is called:

    ACTIVATION CODE FROM DIWE: G ^XTEDTVXD

Usually, this code will need to extract the word processing data from the WORD-PROCESSING-type field, present it to the Alternate Editor, and return the edited text to the WORD-PROCESSING-type field. DBS calls should be used to retrieve and file the text.

For example, if the text to be edited were in Field #56 of File #1234 use the following Data Retriever call to extract the text for entry 789:

    S MYFDA="^TMP(""MYDATA"",$J)" D GETS^DIQ(1234,"789,",56,"",MYFDA)

The text returns in nodes descendent from ^TMP("MYDATA",$J,1234, "789,",56).

After editing is complete, you can file the data from the same global array by using the following commands:

    S MYFDA="^TMP(""MYDATA"")" D FILE^DIE("","MYFDA")

NOTE: For more details of the use of these calls, please refer to the descriptions of the Data Retriever, Filer, and Word Processing Filer in the "Database Server (DBS) API" chapter of the "VA FileMan Programmer Manual."

This task of returning the data to the WORD-PROCESSING-type field can also be accomplished by code in the RETURN TO CALLING EDITOR field (see below).

If the editor uses any local M variables beginning with "D", they should be NEWed to avoid problems upon return to VA FileMan. Also, avoid calls to VA FileMan utilities in the fields that accept M code so that variables upon which VA FileMan depends -- like DA and D0 -- are not changed.

The OK TO RUN TEST field contains code that checks to determine whether it is OK to run the editor:

    OK TO RUN TEST: I ^%ZOSF("OS")["VAX"&(DUZ(0)["@")

This field is optional; if nothing is entered, there are no restrictions on the use of the editor. The code should set $T to true if it is OK to proceed or to false if it is not. If the code returns $T=false, the user will automatically return to the Line Editor. In this example, the environment is being checked to ensure that the called editor is available and it is verified that the user has the required VA FileMan Access Code.

M code entered into the optional RETURN TO CALLING EDITOR field can be used to restore the environment needed by the Line Editor:

    RETURN TO CALLING EDITOR: 

Since the user can switch editors at will, it is safest to restore the text to its previous location in the global and to maintain the local symbol table, as mentioned above. If these tasks are accomplished by code in the ACTIVATION CODE FROM DIWE field or by the called routine, this field is unnecessary.

NOTE: The edited text must be restored; VA FileMan will not move text back to the proper global location.

DESCRIPTION:
      1>The VMS editor.
      2> 
    EDIT Option: 
    Select ALTERNATE EDITOR: 

The definition of the Alternate Editor is complete. An editor's developer should provide information needed to set up an ALTERNATE EDITOR file entry. The local site manager has flexibility in setting up the editor. In particular, the OK TO RUN TEST field can be used to enforce local policies regarding access to editors.

Reviewed/Updated: March 4, 2007