 |
OpenVMS Utility Routines Manual
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
|
- The external entry points EDT$FILEIO,
EDT$WORKIO, and AXLATE are defined so they can be passed to callable
EDT.
- Arrays are used to construct the two-longword
structure needed for data type BPV.
- 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.
- 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.
- 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:
- The record argument is always the RMS file name.
- The rhb argument is always the RMS default file
name.
- There is no related name for the input file.
- The related name for the output file is the input file with OFP
(output file parse). EDT passes the input file name, the output file
name, or the name from the EXIT command in the record
argument.
- The related name for the journal file is the input file name with
the OFP RMS bit set.
- The related name for the INCLUDE file is the input file name with
the OFP set. This is unusual because the file is being opened for input.
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.
|
|
