/sys$common/syshlp/HELPLIB.HLB  —  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.

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

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

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

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

2  –  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

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

2.2  –  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_     The record argument names a file to be
    NOSEQ                  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_     The command file.
    FILE
    EDT$K_INPUT_FILE   The primary input file.
    EDT$K_INCLUDE_     The secondary input file. Such a file is
    FILE               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_     The journal file. If bit 0 of the options is
    FILE               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.

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

    o  The record argument is always the RMS file name.

    o  The rhb argument is always the RMS default file name.

    o  There is no related name for the input file.

    o  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.

    o  The related name for the journal file is the input file name
       with the OFP RMS bit set.

    o  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.

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

3  –  WORKIO

    The user-supplied WORKIO routine is called by EDT when it
    needs temporary storage for the file being edited. Call it by
    specifying it as an argument in the EDT$EDIT routine. It cannot
    be called independently.

    Format

      WORKIO  code ,recordno ,record

3.1  –  Returns

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

    Longword value returned as a status code. It is generally a
    success code, because all OpenVMS RMS errors should be signaled.
    The signal should include the file name and both longwords of the
    RMS status. Any errors detected within work I/O can be indicated
    by setting status to an error code, which will be returned by the
    EDT$EDIT routine.

    The condition value is returned in R0.

3.2  –  Arguments

 code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    A code from EDT that specifies the operation to be performed.
    The code argument is the address of a longword integer containing
    this argument. The valid function codes are as follows:

    Function Code    Description

    EDT$K_OPEN_IN_   Open the work file for both input and output.
    OUT              Neither the record nor recordno argument is
                     used.
    EDT$K_GET        Read a record. The recordno argument is the
                     number of the record to be read. The record
                     argument gives the location where the record is
                     to be stored.
    EDT$K_PUT        Write a record. The recordno argument is the
                     number of the record to be written. The record
                     argument tells the location of the record to be
                     written.
    EDT$K_CLOSE_DEL  Close the work file. After a successful close,
                     the file is deleted. Neither the record nor
                     recordno argument is used.

 recordno

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference
    Number of the record to be read or written. The recordno argument
    is the address of a longword integer containing this argument.
    EDT always writes a record before reading that record. This
    argument is not used for open or close calls.

 record

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor
    Location of the record to be read or written. This argument
    always refers to a 512-byte string during GET and PUT calls.
    This argument is not used for open or close calls.

3.3  –  Description

    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 use the entry point EDT$WORKIO for this argument or you can
    omit it.

3.4  –  Condition Value Returned

    SS$_NORMAL         Normal successful completion.

4  –  XLATE

    The user-supplied XLATE routine is called by EDT when it
    encounters the nokeypad command XLATE. You cause it to be called
    by specifying it as an argument in the EDT$EDIT routine. It
    cannot be called independently.

    Format

      XLATE  string

4.1  –  Returns

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

    Longword value returned as a status code. It is generally a
    success code. If the XLATE routine cannot process the passed
    string for some reason, it sets status to an error code.
    Returning an error code from the XLATE routine aborts the current
    key execution and displays the appropriate error message.

    The condition value is returned in R0.

4.2  –  Argument

 string

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       modify
    mechanism:    by descriptor
    Text string passed to the nokeypad command XLATE. You can use the
    nokeypad command XLATE by defining a key to include the following
    command in its definition:

    XLATEtext^Z

    The text is passed by the string argument. The string argument
    can be handled by the Run-Time Library routine STR$COPY_DX.

    This argument is also a text string returned to EDT. The string
    is made up of nokeypad commands that EDT is to execute.

4.3  –  Description

    The nokeypad command XLATE allows you to gain control of the
    EDT session. (See the OpenVMS EDT Reference Manual for more
    information about the XLATE command.) If you do not need to gain
    control of EDT during the editing session, you can use the entry
    point EDT$XLATE for this argument or you can omit it.

4.4  –  Condition Value Returned

    SS$_NORMAL         Normal successful completion.
Close Help