Start anew

[git/jnareb-git.git] / share / vim / vim58 / doc / os_vms.txt

*os_vms.txt*    For Vim version 5.8   Last change: 2001 May 18


                  VIM REFERENCE MANUAL


                                                        *VMS* *vms*
This file contains the particularities for the VMS version of Vim.
You can reach this information file by typing :help VMS in Vim command
prompt.

 1. Getting started     |vms-started|
 2. Download files      |vms-download|
 3. Compiling           |vms-compiling|
 4. Problems            |vms-problems|
 5. Deploy              |vms-deploy|
 6. Practical usage     |vms-usage|
 7. GUI mode questions  |vms-gui|
 8. Useful notes        |vms-notes|
 9. Changes             |vms-changes|
10. Authors             |vms-authors|

==============================================================================

1. Getting started                                      *vms-started*

Vim (Vi IMproved) is a vi-compatible text editor that runs on nearly every
operating system known to humanity.  Now use Vim on OpenVMS too, in character
or X/Motif environment.  It is fully featured and absolutely compatible with
Vim on other operating systems.

==============================================================================

2. Download files                                       *vms-download*

You can download the Vim source code by ftp from the official Vim site:
        ftp://ftp.vim.org/pub/vim/
Or use one of the mirrors:
        ftp://ftp.vim.org/pub/vim/MIRRORS

You will need both the Unix and Extra archives to build vim.exe for VMS.
For using Vim's full power you will need the runtime files as well.

You can download precompiled executables from:
        http://www.polarfox.com/vim/

==============================================================================

3. Compiling                                            *vms-compiling*

Unpack the Unix and Extra archives together into one directory.  In the <.SRC>
subdirectory you should find the make file OS_VMS.MMS.  By editing this file
you may choose between building the character, GUI and debug version. There
are also additional options for Perl, Python and Tcl support.

You will need either the DECSET mms utility or the freely available clone of
it called mmk (VMS has no make utility in the standard distribution). You can
download mmk from http://www.openvms.digital.com/freeware/MMK/

If you have MSS on your system, the command

>       mms /descrip=os_vms.mms

will start building your own customised version of Vim.
The adequate command for mmk is:

>       mmk /descrip=os_vms.mms

==============================================================================

4. Problems                                             *vms-problems*

The code has been tested under Open VMS 6.2 - 7.1 on Alpha and VAX platforms
with the DECC compiler. It should work without bigger problems.
If it happened that your system does not have some include libraries you can
tune up in OS_VMS_CONF.H or GUI_VMS_CONF.H files.

If you decided to build Vim with +perl, +python, etc. options, first you need
to download OpenVMS distributions of Perl and Python. Build and deploy the
libraries and change adequate lines in OS_VMS.MMS file. There should not be
problem from Vim side.

Note: Under VAX it should work with DEC C compiler without problem, but the
code is not compilable with the old VAX C compiler.

MMS_VIM.EXE is building together with VIM.EXE, but for CTAGS.EXE and XXD.EXE
you should change to subdirectory <.CTAGS> or <.XXD> and build them
separately. You have to be prepared that the CTAGS and XXD make files are not
always up to date.

Advanced users may try some acrobatics in FEATURE.H file also.

It is possible to compile with +xfontset +xim options too, but then you have
to set up GUI fonts etc. correctly. See. :help xim from Vim command prompt.

==============================================================================

5. Deploy                                               *vms-deploy*

Vim uses a special directory structure to hold the document and runtime files:

   vim (or wherever)
    |- tmp
    |- vim55
    |----- doc
    |----- syntax
    |- vim56
    |----- doc
    |----- syntax
    vimrc    (system rc files)
    gvimrc

Use:

>       define/nolog device:[leading-path-here.vim]       vim
>       define/nolog device:[leading-path-here.vim.vim56] vimruntime
>       define/nolog device:[leading-path-here.tmp]       tmp

to get vim.exe to find its document, filetype, and syntax files, and to
specify a directory where temporary files will be located. Copy the "runtime"
subdirectory of the vim distribution to vimruntime.

Note: Logicals $VIMRUNTIME and $TMP are optional. Read more at :help runtime

==============================================================================

6. Practical usage                                      *vms-usage*

Usually you want to run just one version of Vim on your system, therefore
it is enough to dedicate one directory for Vim.
Copy all Vim runtime directory structure to the deployment position.
Add the following lines to your LOGIN.COM (in SYS$LOGIN directory).
Set up logical $VIM as:

>       $ define VIM device:<path>

Set up some symbols:

>       $ ! vi starts Vim in chr. mode.
>       $ vi*m  :== mcr device:<path>VIM.EXE

>       $ !gvi starts Vim in GUI mode.
>       $ gv*im :== spawn/nowait mcr device:<path>VIM.EXE -g

Create .vimrc and .gvimrc files in your home directory (SYS$LOGIN).

The easiest way is just rename example files. You may leave the menu file
(MENU.VIM) and files vimrc and gvimrc in the original $VIM directory. It will
be default setup for all users, and for users is enough just to have their
own additions or resetting in home directory in files .vimrc and .gvimrc.
It should work without problems.

Note: Remember, system rc files (default for all users) does not have leading
"." So, system rc files are:

>       VIM$:vimrc
>       VIM$:gvimrc
>       VIM$:menu.vim

and user's customised rc files are:

>       sys$login:.vimrc
>       sys$login:.gvimrc

You can check that everything is on the right place with the :version command.

Example LOGIN.COM:

>       $ define/nolog VIM RF10:[UTIL.VIM]
>       $ vi*m  :== mcr VIM:VIM.EXE
>       $ gv*im :== spawn/nowait mcr VIM:VIM.EXE -g
>       $ set disp/create/node=192.168.5.223/trans=tcpip

Note: This set-up should be enough, if you are working on standalone server or
clustered environment, but if you want to use Vim as internode editor, it
will satiate you as well. You just have to define the "whole" path:

>       $ define VIM "<server_name>[""user password""]::device:<path>"
>       $ vi*m :== "mcr VIM:VIM.EXE"

as for example:

>       $ define VIM "PLUTO::RF10:[UTIL.VIM]"
>       $ define VIM "PLUTO""ZAY mypass""::RF10:[UTIL.VIM]" ! if passwd required

You can also use $VIMRUNTIME logical to point to proper version of Vim if you
have installed more versions in the same time. If $VIMRUNTIME is not defined
Vim will borrow value from $VIM logical. You can find more information about
$VIMRUNTIME logical by typing :help runtime as a Vim command.

==============================================================================

7. GUI mode questions                                   *vms-gui*

VMS is not a native X window environment, so you can not start Vim in GUI mode
"just like that". But anyhow it is not too complicate to get a running Vim.

1) If you are working on the VMS X console:
   Start Vim with the command:

>       $ mc device:<path>VIM.EXE -g

   or type :gui as a command to the Vim command prompt. For more info :help gui

2) If you are working on other X window environment as Unix or some remote X
   VMS console. Set up display to your host with:

>       $ set disp/create/node=<your IP address>/trans=<transport-name>

   and start Vim as in point 1. You can find more help in VMS documentation or
   type: help set disp in VMS prompt.
   Examples:

>       $ set disp/create/node=192.168.5.159             ! default trans is DECnet
>       $ set disp/create/node=192.168.5.159/trans=tcpip ! TCP/IP network
>       $ set disp/create/node=192.168.5.159/trans=local ! display on the same node

Note: you should define just one of these.
For more information type $help set disp in VMS prompt.

3) If you are working on MS Windows or other non X window environment
   You need to set up one X server and run Vim as in point 2.
   For MS Windows there are available free X servers as MIX , Omni X etc.

==============================================================================

8. Useful notes                                         *vms-notes*

8.1 backspace/delete.

There are backspace/delete key inconsistencies with VMS.
:fixdel doesn't do the trick, but the solution is:

>       inoremap ^? ^H          " for terminal mode
>       inoremap <Del> ^H       " for gui mode

Read more in ch: 8.6 (Terminal problems).
(Bruce Hunsaker <BNHunsaker@chq.byu.edu> Vim 5.3)

8.2 Filters.

Vim supports filters; ie. if you have a sort program that can handle
input/output redirection like Unix (<infile >outfile), you could use

>       map \s 0!'aqsort<CR>

(Charles E. Campbell, Jr. <cec@gryphon.gsfc.nasa.gov> Vim 5.4)

8.3 VMS file version numbers.

Vim is saving files into a new file with the next higher file version
number, try these settings.

>       set nobackup        " does not create *.*_ backup files
>       set nowritebackup   " does not have any purpose on VMS. It's default.

Recovery is working perfect as well from the default swap file.
Read more with :help swapfile

(Claude Marinier <ClaudeMarinier@xwavesolutions.com> Vim 5.5, Zoltan Arpadffy
Vim 5.6 )

8.4 Directory conversion.

Vim will internally convert any unix-style paths and even mixed unix/VMS
paths into VMS style paths. Some typical conversions resemble:

        /abc/def/ghi            -> abc:[def]ghi.
        /abc/def/ghi.j          -> abc:[def]ghi.j
        /abc/def/ghi.j;2        -> abc:[def]ghi.j;2
        /abc/def/ghi/jkl/mno    -> abc:[def.ghi.jkl]mno.
        abc:[def.ghi]jkl/mno    -> abc:[def.ghi.jkl]mno.
          ./                    -> current directoty
          ../                   -> relative parent directory
          [.def.ghi]            -> relative child directory
           ./def/ghi            -> relative child directory

Note: You may use <,> brackets as well (device:<path>file.ext;version) as
rf10:<user.zay.work>test.c;1

(David Elins <delins@foliage.com>, Jerome Lauret
<JLAURET@mail.chem.sunysb.edu> Vim 5.6 )

8.5 Remote host invocation

It is possible to use Vim as an internode editor.
1. Edit some file from remote node:

>       vi "<server>""username passwd""::<device>:<path><filename>;<version>"

example:
>       vi "pluto""zay passwd""::RF10:<USER.ZAY.WORK>TEST.C;1"

Note: syntax is very important, otherwise VMS will recognise more parameters
instead of one (resulting with: file not found)

2.  Set up Vim as your internode editor. If Vim is not installed on your host,
just set up your IP address, full Vim path including the server name and run
the command procedure below:

>       $ if (p1 .eqs. "") .OR. (p2 .eqs. "") then goto usage
>       $ set disp/create/node=<your_IP_here>/trans=tcpip
>       $ define "VIM "<vim_server>""''p1' ''p2'""::<device>:<vim_path>"
>       $  vi*m :== "mcr VIM:VIM.EXE"
>       $ gv*im :== "spawn/nowait mcr VIM:VIM.EXE -g"
>       $ goto end
>       $ usage:
>       $ write sys$output " Please enter username and password as a parameter."
>       $ write sys$output " Example: @SETVIM.COM username passwd"
>       $ end:

Note: Never use it in clustered environment (you do not need it), and load could
be very-very slow, but even faster then a local Emacs. :-)

8.6 Terminal problems

If your terminal name is not known to Vim and it is trying to find the default
one you will get the following message during start-up:
---
Terminal entry not found in termcap
'unknown-terminal' not known. Available built-in terminals are:
    builtin_gui
    builtin_riscos
    [...]
    builtin_debug
    builtin_dumb
defaulting to 'vt320'
---
The solution is to define default terminal name:

>       $ ! unknown terminal name. let us use vt320 or ansi instead.
>       $ ! Note: it's case sensitive
>       $ define term "vt320"

Terminals from VT100 to VT320 (as V300, VT220, VT200 ) do not need any extra
keyboard mappings. They should work perfect as they are, including arrows,
Ins, Del buttons etc. Except Backspace in GUI mode. To solve it, add to
.gvimrc:

>       inoremap <Del> <BS>

Vim will also recognise that they are fast terminals.

If you have some annoying line jumping on the screen between windows add to
your .vimrc file:

>       set ttyfast     " set fast terminal

Note: if you're using Vim on remote host or through very slow connection, it's
recommended to avoid fast terminal option with:

>       set nottyfast


8.7 Hex-editing and other external tools

A very important difference between OpenVMS and other systems is that VMS uses
special commands to execute executables:

>       RUN <path>filename             
>       MCR <path>filename <parameters> 

OpenVMS users always have to be aware that the Vim command :! "just" drop them
to DCL prompt. This feature is possible to use without any problem with all
DCL commands, but if we want to execute some program as XXD, CTAGS, JTAGS etc.
we're running into trouble if we following the Vim documentation (see: help
xxd).

Solution: Execute with the MC command and add the full path to the executable. 
Example: Instead of :%!xxd command use:

>       :%!mc vim:xxd

... or in general:
>       :!mc <path>filename <parameters>

(Zoltan Arpadffy, <arpadffy@altavista.net> Vim 5.6-70)

==============================================================================

9. Changes                                              *vms-changes*

Version 5.6 patches 46-70 (2000 May 5)
- VMS filename related changes:
        - version handling (open everything, save to new version)
        - correct file extension matching for syntax (version problem)
        - handle <,> characters and passwords in directory definition
        - handle internode/remote invocation and editing with passwords
        - OpenVMS files will be treated case insensitive from now
        - corrected response of expand("%:.") etc path related functions
        (in one word: VMS directory handling internally)
- version command
        - corrected (+,-) information data
        - added compiler and OS version
        - added user and host information
        - resolving $VIM and $VIMRUNTIME logicals
- VMS port is in MAX_FEAT (maximum features) club with Unix, Win32 and OS/2.
        - enabled farsi, rightleft etc. features
        - undo level raised up to 1000
- Updated OS_VMS.MMS file.
        - maximum features ON is default
        - Vim is compilable with +perl, +python and +tcl features.
        - improved MMK compatibility
- Created MAKEFILE_VMS.MMS, makefile for testing Vim during development.
- Defined DEC terminal VT320
        - compatibility for VT3*0, VT2*0 and VT1*0 - ANSI terminals
          backwards, but not VT340 and newer with colour capability.
        - VT320 is default terminal for OpenVMS
        - these new terminals are also fast ttys (default for OpenVMS).
        - allowed dec_mouse ttym
- Updated files vimrc and gvimrc with VMS specific suggestions.
- OS_VMS.TXT updated with new features.

Version 5.6 (2000 Jan 17)
- Popup menu line crash corrected.
- Handle full file names with version numbers.
- Directory handling (CD command etc.)
- Corrected file name conversion VMS to Unix and v.v.
- Correct response of expand wildcards
- Recovery is working from this version under VMS as well.
- Improved terminal and signal handing.
- Improved OS_VMS.TXT

Version 5.5 (1999 Dec 3)
- Cut & paste mismatch corrected.
- Motif directories during open and save are corrected.

Version 5.4 (1999 Sep 9)
- Minor changes in the code
- Standard distribution with +GUI option

Version 5.3 (1998 Oct 12)
- Syntax and DEC C changes in the code
- Fixing problems with the /doc subdirectory
- Improve OS_VMS.MMS

Version 5.1 (1998 Apr 21)

Version 4.5 (1996 Dec 16)
- First VMS port by Henk Elbers <henk@xs4all.nl>

==============================================================================

10. Authors                                             *vms-authors*

In alphabetical order:
        Zoltan Arpadffy <arpadffy@altavista.net>
        Charles E. Campbell, Jr. <cec@gryphon.gsfc.nasa.gov>
        Bruce Hunsaker <BNHunsaker@chq.byu.edu>
        Sandor Kopanyi <sandor.kopanyi@altavista.net>