HP OpenVMS Utility Routines Manual


Previous Contents Index


Chapter 10
EDT Routines

On OpenVMS operating systems, the EDT editor can be called from a program written in any language that generates calls using the OpenVMS Calling Standard.

You can set up your call to EDT so the program handles all the editing work, or you can make EDT run interactively so you can edit a file while the program is running.

This chapter on callable EDT assumes that you know how to call an external facility from the language you are using. Callable EDT is a shareable image, which means that you save physical memory and disk space by having all processes access a single copy of the image.

10.1 Introduction to EDT Routines

You must include a statement in your program accessing the EDT entry point. This reference statement is similar to a library procedure reference statement. The EDT entry point is referenced as EDT$EDIT. You can pass arguments to EDT$EDIT; for example, you can pass EDT$FILEIO or your own routine. When you refer to the routines you pass, call them FILEIO, WORKIO, and XLATE. Therefore, FILEIO can be either a routine provided by EDT (named EDT$FILEIO) or a routine that you write.

10.2 Using the EDT Routines: An Example

Example 10-1 shows a VAX BASIC program that calls EDT. All three routines (FILEIO, WORKIO, and XLATE) are called. Note the reference to the entry point EDT$EDIT in line number 500.

Example 10-1 Using the EDT Routines in a VAX BASIC Program

 
100  EXTERNAL INTEGER EDT$FILEIO  (1)
200  EXTERNAL INTEGER EDT$WORKIO 
250  EXTERNAL INTEGER AXLATE 
300  EXTERNAL INTEGER FUNCTION EDT$EDIT 
400  DECLARE INTEGER RESULT 
 
 
450  DIM INTEGER PASSFILE(1%)  (2)
460  DIM INTEGER PASSWORK(1%) 
465  DIM INTEGER PASSXLATE(1%) 
470  PASSFILE(0%) = LOC(EDT$FILEIO) 
480  PASSWORK(0%) = LOC(EDT$WORKIO) 
485  PASSXLATE(0%) = LOC(AXLATE) 
 
500  RESULT = EDT$EDIT('FILE.BAS','','EDTINI','',0%,  (3)
     PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, (4)
     PASSXLATE(0%) BY REF)  (5)
600  IF (RESULT AND 1%) = 0% 
     THEN 
       PRINT "SOMETHING WRONG" 
       CALL LIB$STOP(RESULT BY VALUE) 
900  PRINT "EVERYTHING O.K." 
1000 END 
 

  1. The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are defined so they can be passed to callable EDT.
  2. Arrays are used to construct the two-longword structure needed for data type BPV.
  3. Here is the call to EDT. The input file is FILE.BAS, the output and journal files are defaulted, and the command file is EDTINI. A 0 is passed for the options word to get the default EDT options.
  4. The array PASSFILE points to the entry point for all file I/O, which is set up in this example to be the EDT-supplied routine with the entry point EDT$FILEIO. Similarly, the array PASSWORK points to the entry point for all work I/O, which is the EDT-supplied routine with the entry point EDT$WORKIO.
  5. PASSXLATE points to the entry point that EDT will use for all XLATE processing. PASSXLATE points to a user-supplied routine with the entry point AXLATE.

10.3 EDT Routines

This section describes the individual EDT routines.


EDT$EDIT

The EDT$EDIT routine invokes the EDT editor.

Format

EDT$EDIT in_file [,out_file] [,com_file] [,jou_file] [,options] [,fileio] [,workio] [,xlate]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.


Arguments

in_file


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor

File specification of the input file that EDT$EDIT is to edit. The in_file argument is the address of a descriptor pointing to this file specification. The string that you enter in this calling sequence is passed to the FILEIO routine to open the primary input file. This is the only required argument.

out_file


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor

File specification of the output file that EDT$EDIT creates. The out_file argument is the address of a descriptor pointing to this file specification. The default is that the input file specification is passed to the FILEIO routine to open the output file for the EXIT command.

com_file


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor

File specification of the startup command file to be executed when EDT is invoked. The com_file argument is the address of a descriptor pointing to this file specification. The com_file string is passed to the FILEIO routine to open the command file. The default is the same as that for EDT command file defaults.

jou_file


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor

File specification of the journal file to be opened when EDT is invoked. The jou_file argument is the address of a descriptor pointing to this file specification. The jou_file string is passed to the FILEIO routine to open the journal file. The default is to use the same file name as in_file.

options


OpenVMS usage: mask_longword
type: aligned bit string
access: read only
mechanism: by reference

Bit vector specifying options for the edit operation. The options argument is the address of an aligned bit string containing this bit vector. Only bits <5:0> are currently defined; all others must be 0. The default options have all bits set to 0. This is the same as the default setting when you invoke EDT to edit a file from DCL.

Symbols and their descriptions follow:
Symbol Description
EDT$M_RECOVER If set, bit <0> causes EDT to read the journal file and execute the commands in it, except for the EXIT or QUIT commands, which are ignored. After the journal file commands are processed, editing continues normally. If bit <0> is set, the FILEIO routine is asked to open the journal file for both input and output; otherwise FILEIO is asked only to open the journal file for output. Bit <0> corresponds to the /RECOVER qualifier on the EDT command line.
EDT$M_COMMAND If set, bit <1> causes EDT to signal if the startup command file cannot be opened. When bit <1> is 0, EDT intercepts the signal from the FILEIO routine indicating that the startup command file could not be opened. Then, EDT proceeds with the editing session without reading any startup command file. If no command file name is supplied with the call to the EDT$EDIT routine, EDT tries to open SYS$LIBRARY:EDTSYS.EDT or, if that fails, EDTINI.EDT. Bit <1> corresponds to the /COMMAND qualifier on the EDT command line. If EDT$M_NOCOMMAND (bit <4>) is set, bit <1> is overridden because bit <4> prevents EDT from trying to open a command file.
EDT$M_NOJOURNAL If set, bit <2> prevents EDT from opening the journal file. Bit <2> corresponds to the /NOJOURNAL or /READ_ONLY qualifier on the EDT command line.
EDT$M_NOOUTPUT If set, bit <3> prevents EDT from using the input file name as the default output file name. Bit <3> corresponds to the /NOOUTPUT or /READ_ONLY qualifier on the EDT command line.
EDT$M_NOCOMMAND If set, bit <4> prevents EDT from opening a startup command file. Bit <4> corresponds to the /NOCOMMAND qualifier on the EDT command line.
EDT$M_NOCREATE If set, bit <5> causes EDT to return to the caller if the input file is not found. The status returned is the error code EDT$_INPFILNEX.

fileio


OpenVMS usage: vector_longword_unsigned
type: bound procedure value
access: function call
mechanism: by reference

User-supplied routine called by EDT to perform file I/O functions. The fileio argument is the address of a bound procedure value containing the user-supplied routine. When you do not need to intercept any file I/O, either use the entry point EDT$FILEIO for this argument or omit it. When you only need to intercept some amount of file I/O, call the EDT$FILEIO routine for the other cases.

To avoid confusion, note that EDT$FILEIO is a routine provided by EDT whereas FILEIO is a routine that you provide.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). BPV is a two-longword entity in which the first longword contains the address of a procedure value and the second longword is the environment value. When the bound procedure is called, EDT loads the second longword into R1. If you use EDT$FILEIO for this argument, set the second longword to <0>. You can pass a <0> for the argument, and EDT will set up EDT$FILEIO as the default and set the environment word to 0.

workio


OpenVMS usage: vector_longword_unsigned
type: bound procedure value
access: function call
mechanism: by reference

User-supplied routine called by EDT to perform I/O between the work file and EDT. The workio argument is the address of a bound procedure value containing the user-supplied routine. Work file records are addressed only by number and are always 512 bytes long. If you do not need to intercept work file I/O, you can either use the entry point EDT$WORKIO for this argument or omit it.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). This means that EDT loads R1 with the second longword addressed before calling it. If EDT$WORKIO is used for this argument, set the second longword to 0. You can pass a 0 for this argument, and EDT will set up EDT$WORKIO as the default and set the environment word to 0.

xlate


OpenVMS usage: vector_longword_unsigned
type: bound procedure value
access: function call
mechanism: by reference

User-supplied routine that EDT calls when it encounters the nokeypad command XLATE. The xlate argument is the address of a bound procedure value containing the user-supplied routine. The XLATE routine allows you to gain control of your EDT session. If you do not need control of EDT during the editing session, you can either use the entry point EDT$XLATE for this argument or omit it.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). This means that EDT loads R1 with the second longword addressed before calling it. If EDT$XLATE is used for this argument, set the second longword to 0. You can pass a 0 for this argument, and EDT will set up EDT$XLATE as the default and set the environment word to 0.


Description

If the EDT session is terminated by EXIT or QUIT, the status will be a successful value (bit <0> = 1). If the session is terminated because the file was not found and if the /NOCREATE qualifier was in effect, the failure code EDT$_INPFILNEX is returned. In an unsuccessful termination caused by an EDT error, a failure code corresponding to that error is returned. Each error status from the FILEIO and WORKIO routines is explained separately.

Three of the arguments to the EDT$EDIT routine, fileio, workio, and xlate are the entry point names of user-supplied routines.


Condition Values Returned

SS$_NORMAL Normal successful completion.
EDT$_INPFILNEX /NOCREATE specified and input file does not exist.

This routine also returns any condition values returned by user-supplied routines.


FILEIO

The user-supplied FILEIO routine performs file I/O functions. Call it by specifying it as an argument in the EDT$EDIT routine. It cannot be called independently.

Format

FILEIO code ,stream ,record ,rhb


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value

A status code that your FILEIO routine returns to EDT$EDIT. The fileio argument is a longword containing the status code. The only failure code that is normally returned is RMS$_EOF from a GET call. All other OpenVMS RMS errors are signaled, not returned. The RMS signal should include the file name and both longwords of the RMS status. Any errors detected with the FILEIO routine can be indicated by setting status to an error code. That special error code will be returned to the program by the EDT$EDIT routine. There is a special status value EDT$_NONSTDFIL for nonstandard file opening.

Condition values are returned in R0.


Arguments

code


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference

A code from EDT that specifies what function the FILEIO routine is to perform. The code argument is the address of a longword integer containing this code. Following are the valid function codes:
Function Code Description
EDT$K_OPEN_INPUT The record argument names a file to be opened for input. The rhb argument is the default file name.
EDT$K_OPEN_OUTPUT_SEQ The record argument names a file to be opened for output as a sequenced file. The rhb argument is the default file name.
EDT$K_OPEN_OUTPUT_NOSEQ The record argument names a file to be opened for output. The rhb argument is the default file name.
EDT$K_OPEN_IN_OUT The record argument names a file to be opened for both input and output. The rhb argument is the default file name.
EDT$K_GET The record argument is to be filled with data from the next record of the file. If the file has record prefixes, rhb is filled with the record prefix. If the file has no record prefixes, rhb is not written. When you attempt to read past the end of file, status is set to RMS$_EOF.
EDT$K_PUT The data in the record argument is to be written to the file as its next record. If the file has record prefixes, the record prefix is taken from the rhb argument. For a file opened for both input and output, EDT$K_PUT is valid only at the end of the file, indicating that the record is to be appended to the file.
EDT$K_CLOSE_DEL The file is to be closed and then deleted. The record and rhb arguments are not used in the call.
EDT$K_CLOSE The file is to be closed. The record and rhb arguments are not used in the call.

stream


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference

A code from EDT that indicates which file is being used. The stream argument is the address of a longword integer containing the code. Following are the valid codes:
Function Code Description
EDT$K_COMMAND_FILE The command file.
EDT$K_INPUT_FILE The primary input file.
EDT$K_INCLUDE_FILE The secondary input file. Such a file is opened in response to an INCLUDE command. It is closed when the INCLUDE command is complete and will be reused for subsequent INCLUDE commands.
EDT$K_JOURNAL_FILE The journal file. If bit 0 of the options is set, it is opened for both input and output and is read completely. Otherwise, it is opened for output only. After it is read or opened for output only, it is used for writing. On a successful termination of the editing session, the journal file is closed and deleted. EXIT/SAVE and QUIT/SAVE close the journal file without deleting it.
EDT$K_OUTPUT_FILE The primary output file. It is not opened until you enter the EXIT command.
EDT$K_WRITE_FILE The secondary output file. Such a file is opened in response to a WRITE or PRINT command. It is closed when the command is complete and will be reused for subsequent WRITE or PRINT commands.

record


OpenVMS usage: char_string
type: character-coded text string
access: modify
mechanism: by descriptor

Text record passed by descriptor from EDT to the user-supplied FILEIO routine; the code argument determines how the record argument is used. The record argument is the address of a descriptor pointing to this argument. When the code argument starts with EDT$K_OPEN, the record is a file name. When the code argument is EDT$K_GET, the record is a place to store the record that was read from the file. For code argument EDT$K_PUT, the record is a place to find the record to be written to the file. This argument is not used if the code argument starts with EDT$K_CLOSE.

Note that for EDT$K_GET, EDT uses a dynamic or varying string descriptor; otherwise, EDT has no way of knowing the length of the record being read. EDT uses only string descriptors that can be handled by the Run-Time Library routine STR$COPY_DX.

rhb


OpenVMS usage: char_string
type: character-coded text string
access: modify
mechanism: by descriptor

Text record passed by descriptor from EDT to the user-supplied FILEIO routine; the code argument determines how the rhb argument is used. When the code argument starts with EDT$K_OPEN, the rhb argument is the default file name. When the code is EDT$K_GET and the file has record prefixes, the prefixes are put in this argument. When the code is EDT$K_PUT and the file has record prefixes, the prefixes are taken from this argument. Like the record argument, EDT uses a dynamic or varying string descriptor for EDT$K_GET and uses only string descriptors that can be handled by the Run-Time Library routine STR$COPY_DX.

Description

If you do not need to intercept any file I/O, you can use the entry point EDT$FILEIO for this argument or you can omit it. If you need to intercept only some file I/O, call the EDT$FILEIO routine for the other cases.

When you use EDT$FILEIO as a value for the fileio argument, files are opened as follows:

EDT contains support for VFC files. Normally, EDT will zero the length of the RHB field if the file is not a VFC file. However, when the user supplies the FILEIO routines, they are responsible for performing this operation.

EDT checks for a VFC file with the following algorithm:


IF FAB$B_RFM = FAB$C_VFC 
AND FAB$B_RAT <> FAB$M_PRN 
THEN 
        VFC file 
ELSE 
        not VFC file, zero out RHB descriptor length field. 


Condition Values Returned

SS$_NORMAL Normal successful completion.
EDT$_NONSTDFIL File is not in standard text format.
RMS$_EOF End of file on a GET.


Previous Next Contents Index