HELPLIB.HLB  —  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]

1  –  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.

2  –  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_           If set, bit <2> prevents EDT from opening
    NOJOURNAL        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_           If set, bit <4> prevents EDT from opening a
    NOCOMMAND        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.

3  –  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.

4  –  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.
Close Help