OpenVMS beginner's FAQ


         This is the OpenVMS beginner's FAQ.
         on alpha.mike-r.com

         A good guide for new OpenVMS system managers:
         How to build a base VAX-VMS System

Questions related to this FAQ.
  Who wrote this?
  What is OpenVMS, is it VMS?
  What version of OpenVMS does it apply to?
  What version of the FAQ is this?
  Where can I get a newer copy?
  Can I give this to other users or post it on my server?
  What conventions are used in this FAQ?
  Is this the official OpenVMS FAQ?

Questions related to processes.
  How do I ...
    login?
    logout?
    configure a terminal?
    execute a bunch of commands at login?
    create a subprocess?
    stop a process?
    start a program?
    stop a program?
    tell what a program is doing?
    redirect the input or output of a program?
    start a batch job?
    stop a batch job?
    modify a process's attributes: priority, privileges, and so forth.

  What is/are ...
    an UIC?
    a priority?
    a working set?
    a privilege?
    symbols?
    logical names?
    foreign commands?
    usernames and passwords?
    text editors?
 
Questions related to working on files and directories.

  How do I....
    list the files in a directory?
    copy files?
    create files?
    delete files?
    delete older versions of files?
    edit files?
    move files?
    rename files?
    view files' contents?
    print files' contents?
    find files by name, date, or other property?
    find files by their contents?
    protect files from other users? 
    share files with other users? 
    create a directory?
    delete a directory?
    rename a directory?
    move to another directory?
    identify the current directory?
 
  What is/are ...
    RMS attributes?
    creation, modification, and backup dates?

Questions related to communications.
  How do I....
    handle mail?
    have a conversation with somebody on the same machine?
    have a conversation with somebody on a different machine?
    copy files to/from another machine?
    execute commands on another machine?
    use a news reader? 
    participate in IRC sessions?

Questions related to DCL.
  What is DCL?
  What is a DCL procedure?
  Why would I ever use a DCL procedure?
  How do I....
    create a DCL procedure?
    pass parameters into a DCL procedure interactively?
    pass parameters into a DCL procedure when it runs in batch?
    see parameters inside a DCL procedure?
    control the flow of the procedure?
    manipulate symbols?
    manipulate logical names?
    gather information about files, processes, the system, etc.?
    bury untypable values in symbols?
    make text blink, underlined, and so forth?
    do decimal math?

Questions related to POSIX.
  What is POSIX?
  Why would I ever use POSIX?

Questions related to DECwindows.
  What is DECwindows?
  Why would I ever use DECwindows?
  How do I redirect the display to another machine?
  How do I tell where the display is going now?
  How do I allow another machine to display on my screen?
  Isn't there some sort of simple way to move files around?
  How do I stop an application that is locked up?
  How do I select menus and options without the mouse?
  What do each of the three buttons on the mouse do?

back to top of document


Who wrote this?

David Mathog
Manager, sequence analysis facility, Biology Division, Caltech
mathog@caltech.edu

Minor updates about later versions of OpenVMS by
* Mike Rechtman
mike@rechtman.com

back to top of document

What is OpenVMS, is it VMS?

First there was VMS, then Digital added POSIX, and renamed the
operating system OpenVMS.  OpenVMS currently runs on both VAX and
AXP (ALPHA) CPUs.
*Version 8.2  released in late 2005, and later versions run on Intel
64-bit CPU machines. 

back to top of document

What version of OpenVMS does it apply to?

OpenVMS 6.1, on either VAX or AXP.
Lines marked * in red  have been added to refer to later versions of OpenVMS

back to top of document


What version of the FAQ is this?

1.12, 14-JUN-2000

      Thanks for comments to:
          miken@tobinassoc.com
          fairfield@slac.stanford.edu
          juengst@loon1.spa.umn.edu"
back to top of document


Where can I get a newer copy?

http://saf.bio.caltech.edu/vms_beginners_faq.html

back to top of document


Can I give this to other users or post it on my server?

Yes.  Please do put copies on local servers rather than just putting in
links to our copy - it will distribute the load better.

back to top of document


What conventions are used in this FAQ?

Mostly this is just text, however, when describing command lines,
or how to use programs:

  [] Indicates an optional parameter, qualifier, or value except where
     it indicates part of a directory specification or a UIC value.

  {} Indicates a key name, ie {RETURN} means the return key on the
     keyboard. 
     {^C} means typing C while holding down the Ctrl or Control key

  $  Indicates a command that is often found on OpenVMS systems, but
     is not part of the operating system.

  bold text     Indicates what the computer wrote to the screen.

  Regular text  Indicates what the user is to type/has typed.

  italic text   Indicates a comment - it should NOT appear on the 
                command line!

It is understood that each command line is terminated by a single 
{RETURN} keystroke when entered interactively.

back to top of document


Is this the official OpenVMS FAQ?

No, it isn't!  This is aimed at people just starting out on OpenVMS.
The "real" OpenVMS FAQ is for more technically adept users.  It may be 
found at: 
* http://www.hoffmanlabs.com/vmsfaq/vmsfaq.html 

back to top of document


How do I login?

First your local system adminstrator must issue you a username and
(initial) password.  The next step depends on how your system is set 
up.

Logging in on a terminal
Hit {RETURN} a couple of times, you should see a prompt:

 Username: assigned_username The username that was assigned.
 Password: assigned_password It will not be visible when typed.

The first time you use the computer it will likely force you to change
your password.

Logging in via a terminal emulator, running on LAT, CTERM, or TELNET.

Configure the computer you are using to connect to the OpenVMS host.  
Then proceed as for a terminal.

Logging in via an Xterminal or on a workstation console.
There should be a login screen present, with blanks labeled Username
and Password.  Fill them in and then press {RETURN} or click with the 
mouse on an {OK} button, if present.

back to top of document


How do I logout?

From a terminal, or remote LAT, CTERM, SET HOST, or TELNET session:

 $ logout

From an Xterminal or workstation console

  Click on the Session Manager.
  Click on Session, a menu will drop down.
  Click on End Session.
  Confirm the logout, if it prompts you for that.

back to top of document


How do I configure a terminal?

This is often necessary for serial lines and sometimes necessary for
connections over ethernet via LAT, CTERM, or TELNET.

First, determine the current configuration of your terminal or 
terminal emulator.  You will need to know such things as the type of
emulation it is doing (typically VT100 or VT200), the number of bits, 
parity, and so forth.

Then try to log in.  If you succeed, do:

  $ SHOW TERMINAL

Generally the best thing to do is to adjust the terminal/terminal
emulator to match what the line expects.  If that isn't possible use:

  $ SET TERMINAL [options]

to make the connection match the terminal/terminal emulator.

If when you try to log in all that shows up on your screen is garbage, or
you don't even get that, ask the system administrator to tell you how that
line is configured. 

back to top of document


How do I execute a bunch of commands at login?

Create a file called LOGIN.COM and place it in SYS$LOGIN, the 
directory you start out in when you log in. Here is a very simple
LOGIN.COM file:

$! First line of example login.com
$ ds :== dir/size=all
$ define sys$print my_groups_queue
$! last line of login.com

Just to avoid some possible security problems, also do:

  $ set file/protection=(s:rwed,o:rwed,g:re,w) login.com

back to top of document


How do I create a subprocess?

Use the SPAWN command.  Here is an example of interrupting a program,
creating a subprocess, doing some stuff in it interactively, and then
returning to the program running in the main process:

$ run myprog
{^Y}
$ spawn
$ dir *.dat  Do a couple of commands, this is just an example
$ logout
$ continue   The program completes normally.

Note that giving a command other than spawn or attach would have
killed the halted program "myprog".

You can also use Spawn to get a subprocess running at the same time
as the main process.  For instance, the following will start the program
XV (an interactive graphics program for DECwindows) and then let you 
continue with the current session:

  $ spawn/nowait xv
  $

Note that a {^Y} or {^C} at the top session will kill the subprocess.

back to top of document


How do I stop a process?

If you know the name or process ID, and it belongs to you, or you have
sufficient privileges: 

 $ stop process_name

           or

 $ stop/id=process_number   a typical number: 20200242

You can get the process_name or _number from:

 $ show system

If the process you want to stop is your current session, or the program
you are running, use:

  {^Y}   Control key and Y, stop the current program.
  $ logout

back to top of document


How do I start a program?

Method 1:  The program has been installed or is part of OpenVMS:

 $ program_name [command line arguments]

Method 2:  Use the RUN command:

 $ run program_name  No command line arguments allowed

Method 3:  Define a foreign command for it, then run it.  In the following
           example where is a logical name equivalent to the
           location of the program.

 $ new_command :== $where:program_name 
 $ new_command [command line arguments]

Method 4:  If the "program" is a DCL procedure.

 $ @new_command [command line arguments]

Method 5:  If the "program" is a DCL procedure, define a symbol to run it.

 $ new_command :== @where:program_name 
 $ new_command [command line arguments]

back to top of document


How do I stop a program?

If by "stop" you mean, keep it from scrolling by too fast, use

  {^S} to halt output.
  {^Q} to continue output.
  {^O} to temporarily throw away output/redirect it back to the screen.

If by "stop" you mean, kill the program, use

  {^C} if you want to stop what it is doing, but not totally kill it.
  {^Y} to stop it no matter what.

back to top of document


How do I tell what a program is doing?

If you are running it interactively from a terminal, do:

  {^T} 

this will give you a status line showing the time, and also these process
measurements:  total CPU, total page faults, total IO, and current
memory usage.

If it is running in batch, or as a subprocess, use:

 $ SHOW PROCESS /id=process_id

            or

 $ SHOW PROCESS process_name

You must either own the process, or have enough privileges to let you
gather this information.

You can tell which processes are hogging which resources using variants
of the MONITOR command:

 $ MONITOR process/topcpu   Who's using all the CPU?
 $ MONITOR process/topfault Who's page faulting so much?
 $ MONITOR disk             What's going on on the disks?

back to top of document


How do I redirect the input or output of a program?

* The following paragraph does not apply to current versions of
OpenVMS, which *do* support the use of pipes, using the
  $ PIPE
command. E.g.:
  $ PIPE prog1 | prog2 | prog3
or
  $ PIPE show device SYS$SYSTEM: /file | search SYS$PIPE: myfile

To check whether the PIPE commands exists on a particular version of OpenVMS,
and for further help, enter:
  $ HELP PIPE
 
This must be done *before* the program runs and involves temporarily
redefining certain logical names.  Examples are
given in that section.

OpenVMS does not support "pipes" as do some other operating systems.  
(* See above for change in latest versions )
However, pretty much the same effect can be obtained by explicitly chaining 
the output of one program as the input to the next - so long as what the
program produces is text, and all input/output goes through the standard 
devices.  In other words, the equivalent of the Unix command line: 

  % prog1 | prog2 | prog3

is:

 $ DEFINE/user sys$output temp1.txt
 $ prog1
 $ DEFINE/user sys$input  temp1.txt
 $ DEFINE/user sys$output temp2.txt
 $ prog2
 $ DEFINE/user sys$input  temp2.txt
 $ prog2

If the intermediate files are not needed afterwards, just delete them.

back to top of document


How do I start a batch job?

First you need to put a series of DCL commands into a file, because
batch jobs require DCL procedure files to tell them what to do.  (They
aren't interactive, so you can't do so from your terminal.)  Here is 
a simple procedure file lthat sorts a couple of files and then merges them.
Generally, you would use an editor to create this file.

$! first line of "TEST.COM", note no error checking!!!
$ sort file1.txt file1.txt_sorted
$ sort file2.txt file2.txt_sorted
$ sort file3.txt file3.txt_sorted
$ merge file1.txt_sorted,file2,file3 file4.txt
$ delete file%.txt.
$ write sys$Output "All done"
$!last line of file

This is one command you might use to start it on a batch queue:

 $ SUBMIT/NOTIFY/NOPRINT/LOG=SYS$LOGIN: [QUEUE=queue_name] test.com

This says:
  Put it on the batch queue named "queue_name"
  Notify my terminal when it finishes (only works if you are still
     logged in!) 
  Keep a log file, it will be SYS$LOGIN:TEST.LOG
  Don't print the log file

It will tell you the entry number when it is placed on the queue.

back to top of document


How do I stop a batch job?

First, figure out the entry number, if you didn't write it down when
you issued the SUBMIT command to place it on the QUEUE.

 $ SHOW ENTRY    Show all entries that you own in any queue.

Figure out which one is yours.  Then do:

 $ DELETE/ENTRY=entry_number

back to top of document


How do I modify a process's attributes: priority, privileges, and so forth.

This is where SHOW and SET come in.  SHOW tells you what they are, SET
lets you modify them.  There are a lot of possible combinations!  Here, use
a command that gets a whole bunch of information at once, use the /id
switch if you are modifying a process other than the one attached to your
terminal: 

 $ HELP SET         Learn about SET.
 $ HELP SHOW        Learn about SHOW.

 $ SHOW PROCESS/ALL [/id=process_id]
                           Tells a lot about a process.

The following examples all apply to the process attached to your terminal.

 $ SET PROC/PRIO=3  Lower process priority to 3.
 $ SET PROC/PRIV=(OPER,NOBYPASS)
                           Turn on one privilege, turn off another.
 $ SET WORKING_SET/LIMIT=1000
                           Set the working set limit to 1000.
  

back to top of document


What is an UIC?

The computer needs to know who you are, and which group you belong to.
This information is stored in the UIC (user identification code).  It
is written "[group,member]".  The group and member values are each
octal numbers between 0 and 37776.  However, on most systems these have
been mapped by the system administrator to case insenstive text names known
as "identifiers" which may be used instead, and which will show up
preferentially in any display commands.  For instance, [10,20] and
[AGROUP,AUSER] might be equivalent.  Typically "AUSER" is the same as the
user's USERNAME, and "AGROUP" has some fairly obvious meaning in a group
context, like "SHIPPING" or "PERSONNL". Here are some instances where you
will encounter UICs: 

 $ DIR/OWNER    Who owns the files in this directory.
 EXAMPLE1.DAT;1    [AGROUP,AUSER]$ If identifiers defined
 EXAMPLE2.DAT;1    [10,20]$        If identifiers not defined

 $ DIR/BY_OWNER=[AGROUP,AUSER]
                       Find a file by who owns it.
 $ SET FILE/OWNER=[AGROUP,AUSER] filename.txt
                       Give a file to somebody, requires privileges.


back to top of document


What is a priority?

Each process has a number associated with it that determines how much
CPU time it gets when in competition with all of the other processes on
the system.  A normal interactive priority is 4.  Less gets less time,
more gets more.  Normal users cannot increase their priorities above 4.
Nice users decrease their priorities when they run computationally 
intensive programs from their terminals.  Hint, if at all possible, run
these in batch instead.

back to top of document


What is a working set?

First some background.  OpenVMS uses virtual memory. This means that the
total amount of addressable memory is composed of the RAM, or physical
memory, of the machine plus a large area reserved on disk (swap).  When
processes on the system require more memory than is present in RAM, the
operating system adapts by copying memory in pages to/from the swap area on 
disk.  While this is transparent to the user, users should be aware of it,
since processes that request too much memory will spend a lot of time
moving data to and from the disks, which is much, much slower than moving
data around only in RAM. Secondly, if a lot of this disk access is going on
it can slow down the system for other users as well. 

OpenVMS controls how much of what kind of memory a process can get via
the "working set".  The working set has four parts: default, extent, quota, 
and limit, with all values given in units of 512 byte pagelets.  These are:

 Default:    The initial working set size limit for a user's process.
 Extent:     The maximum size to which a user's RAM usage can grow.
 Quota:      Has several meanings:
               1.  The maximum amount of RAM a user can lock in.
               2.  The maximum amount of swap space reserved for this 
                   process.
               3.  The maximum amount of RAM the system will let the 
                   process have if other processes also want more RAM.
 Limit:      When a program stops, the process will reduce it's working
             set to this size.

Users can adjust these up to the maximum allowed by the system for any
process they create with SET WORKING_SET.  Note that the working set can
be higher on batch queues than for interactive use (another incentive to
use batch queues) and can be set on a user by user basis by the system
manager.

back to top of document


What is a privilege?

In order for a process to do certain operations on OpenVMS it must have the
appropriate privileges.  This is a security feature.  On most systems
"average" users will have these two privileges only: 

       NETMBX    Create a network device.
       TMPMBX    Create temporary mailbox devices.

It is not uncommon for a small number of users to have these additional
privileges:

      GROUP     Control execution of other processes in the same group.
      OPER      Perform system operator functions.

Privileges beyond those are usually reserved for the system manager.

Note that access to other users' files is controlled primarily by file
protections and (occassionally) access control lists.

back to top of document


What are symbols?

DCL can store information such as strings or integers in "symbols".  
DCL can also manipulate these symbols to create other symbols.
Symbols are primarily used to define short strings that replace long
commands, perform certain calculations and replacements within DCL
procedures, hold status information. 

Examples:

 $ three :== print/copies=3 Short hand for longer command.

 $ x == 3         Hold a value.
 $ copy filename out.txt;'x' 
                         Use it. New file is out.txt;3
 $ x == x + 1     Modify the value.
 $ copy filename out.txt;'x'
                         Use it. New file is out.txt;4

 $ search *.* fred          Do an operation.
 $ write sys$output $STATUS Check the completion status.

 $ delete/symbol/global three 
                         Delete a symbol.

back to top of document


What are logical names?

Logical names are strings that are primarily used to replace some or all of
a file specification, especially the DEVICE and DIRECTORY portions. For
instance, if the logical name THERE was defined to be
DISK:[DIRECTORY]FILENAME.EXTENSION then the file system would know how to
access the desired file when THERE was encountered in any location where
the full file name would have been appropriate, either on the command line
or within a program.  In comparison, a symbol THERE containing the string
DISK:[DIRECTORY]FILENAME.EXTENSION could only be interpreted by the
command line interpreter - within a program "THERE" would have no special
meaning.

There are several special logical names, these are:

  SYS$OUTPUT:    the place where normal output is sent
  SYS$ERROR:     the place where error messages are sent
  SYS$INPUT:     the place where data is read from
  SYS$COMMAND:   the place where DCL commands are read from
  TT:            another name for the terminal
  NLA0:          the null device, data directed here disappears

By redefining logical names it is possible to redirect the input and
output for programs that do not allow this to be done explicitly. (See
the examples below.)

Logical names can also be used to hold an arbitrary string.  Logical name
tables are sets of logical names.  Each logical name table restricts access
to processes belonging to a particular group of users (sometimes including
all users).  So one way that processes share information is by defining
logical names in logical name tables that they have common access to.

Examples:

 $ DEFINE there DISK1:[USERS.FRED]
            Define a logical value specifying a location.
 $ COPY there:file.txt []
            Copy a file from that location to the current directory.

 $ DEFINE avalue "This is a string that some program needs"
 $ SHOW LOG avalue
   "AVALUE" = "This is a string that some program needs" (LNM$PROCESS_TABLE)
 $ DEASSIGN avalue      Get rid of the logical name.

 This is how to redirect the input/output for a program that expects
 to read/write to the terminal.  DEFINE/USER is in effect until the 
 completion of the the next program or procedure that is run.

 $ DEFINE/USER sys$output    someprogram.output
 $ DEFINE/USER sys$error     someprogram.errors
 $ DEFINE/USER sys$input     someprogram.data
 $ RUN SOMEPROGRAM

 This is how to redirect the input/output for a program that expects
 to read/write from particular files with names that DO NOT have extensions,
 that is "DATAIN", but not "DATAIN.TXT"

 $ DEFINE/USER DATAOUT   someprogram.output
 $ DEFINE/USER DATAIN    someprogram.data
 $ RUN SOMEPROGRAM

back to top of document


What are foreign commands?

A foreign command is a way of running a program so that it can take
command line arguments, but without modifying the primary command table
(which is done with SET COMMAND, and can be slow).  Note that a single
* in the foreign command indicates how much of the command must be typed
for it to be recognized.

Example:

 $ DEFINE there DISK1:[USERS.FRED]
 $ mycom*mand :== $THERE:a_program
 $ mycom "a parameter"
 

back to top of document


What are usernames and passwords?

The computer needs to know who you are so that it can determine which
operations you may perform.  

The way it finds out who you are is at login, when it asks you for a
username, which is a unique name that has been assigned to you by your
system administrator.  For instance, if your name is "Mary Brown", your
username might be "MBROWN".  Usernames are not case sensitive, so "mBrown"
or "MBrown" would be equivalent. 

The way it verifies that you are who you say you are is by asking you for a
password.  This is a string of characters which you should keep
secret - letting others know what it is gives them full access to your
account.  Passwords, like usernames, are not case sensitive. In most
instances, when the computer asks for your password it will not echo the
characters back to the screen, so that somebody reading over your shoulder
will not be able to steal your password. On some OpenVMS systems you may
also need a secondary password.  Your initial password(s) will be chosen
for you by your system administrator.

On many OpenVMS systems you will be allowed to change your password.
On others you will be forced to change your password at regular intervals -
these latter systems will show you at login, in the days before your
password expires, a message similar to this one: 

  WARNING - Your password expires on Thursday,  9-NOV-1995 10:48:47.98

After it has expired you will instead see this message:

  Your password has expired; you must set a new password to log in

This is how you change a password on OpenVMS, in each instance where you
type a password it will not show up on the screen: 

 $ SET PASSWORD
 $ Old password:     Type in your current password.
 $ New password:     Type in the new password.
 $ Verification:     Type in the new password again.

Another method, which some sites require is to use instead:

 $ SET PASSWORD/GENERATE

In this variant after you supply the Old password you will be asked to 
select your new password from a list of randomly generated, and so
unguessable, passwords.


back to top of document


What are text editors?

Text editors are programs that modify text files. Their
editing functions are analogous to those in the word
processing programs that you may be familiar with, but they
may or may not use a graphics user interface, and none of
them can be used to affect a text file's format (fonts,
bold, italic, and so forth) - because text files don't have
any of these attributes.  For a description of the available
text editors, see How do I edit files?


back to top of document


How do I list the files in a directory?

Use the DIRECTORY command, which may be abbreviated to DIR.

Examples:

 $ DIR         List everything in the current directory.
 $ DIR DISK:[DIR1.SUBDIR1]
                      List everything in the specified directory.
 $ DIR/SIZE/OWNER/PROT FRED*.*
                      List all files begging with "FRED" and show
                      their size, who owns them, and what their protections
                      are.
 $ HELP DIR    More information on the DIRECTORY command.


back to top of document


How do I copy files?

Use the COPY command, or in some instances BACKUP or TYPE.

Examples:

 $ COPY file1 DISK:[DIR1.SUBDIR1]file2
                      Make a copy of file1 elsewhere, and call it file2.

 $ COPY *.TXT *.TEXT
                      Copy the most recent version of all files that 
                      have a .TXT extension, and give the copies .TEXT
                      extensions.

 $ BACKUP/VERIFY [.SUBDIR1...]*.*;* [.SUBDIR2...]
                      Copy the entire subdirectory tree from [.SUBDIR1]
                      down into another tree [.SUBDIR2].

 $ BACKUP/VERIFY [.SUBDIR1...]*.*;* []subdir1.bck/SAVE
                      Copy the entire subdirectory tree from [.SUBDIR1]
                      into a backup save set.  This could be transferred to
                      another machine and unpacked there.

 $ TYPE/OUT=file2 file1
                      Used for text files.  Copies file1 to file2, and
                      changes the file type from whatever it was to
                          File Organization: sequential
                          Record Format: variable
                          Record Attributes:  carriage-return
                      This can be useful before sorting files that
                      have stream-lf format - these often have invalid
                      longest record values, which complicates the SORT
                      command.

 $ HELP        More information on these commands.


back to top of document


How do I create files?

Many, many ways.  If you want to create a text file you can use the CREATE
command, enter the text on subsequent lines, and terminate with a ^Z.
Using this method you can edit on the current line, but not fix typos on
previous lines.  Example:

 $ CREATE myfile.txt
 text line 1
 text line 2
 etc. etc. blah blah blah
 {^Z}               ! Hit Control-Z to end
 $

For bettter control, use one of the many available text
editor.  However, to do so you must first learn how to use that editor.
Example (editor commands not shown):

 $ EDIT myfile.txt

If you have DECwindows, the simplest "editor" is the Notepad program, which
you may start from the Session Manager's Applications menu.

back to top of document


How do I delete files?

Use the DELETE command.  Be careful with wildcards!!!!

 $ DELETE myfile.txt;  Delete the most recent version of myfile.txt.
 $ DELETE myfile.txt;* Delete all versions of myfile.txt.
 $ DELETE *.*;*        Delete everything in the current directory!!!!!!!
 $ HELP DELETE         More information on the DELETE command.

Note1:  Never delete MAIL*.MAI files using the DELETE command. Instead, go
into MAIL and use the DELETE command in there.

Note2:  You can only delete files which have a D (delete) protection that
enables you to do so.  If you own it, you can set this with:

 $ SET FILE/PROTECTIO=O:RWED filename

Note3:  You cannot delete a directory that has anything left in it.

back to top of document


How do I delete older versions of files?

Use the PURGE command.  This leaves the most recent version of a file, and
removes older ones. 

 $ PURGE             Remove older versions on all files in the 
                            current directory.
 $ PURGE/KEEP=3      Similar, but keep the 3 most recent versions.

 $ HELP PURGE        More information on the PURGE command.

back to top of document


How do I edit files?

Use a text editor.  Several come standard with OpenVMS, and it is very
common to see others that have been installed as well.

    $ Edit [/tpu] file   "Eve" Default OpenVMS text editor.
    $ Edit/EDT file      Used to be default OpenVMS text editor.
    $ Edit/TECO file     Older editor.
    $ note :== $SYS$SYSTEM:DECW$NOTEPAD
    $ note file          Requires DECwindows.  Simple GUI text editor.
    $ jed  file          Available for many platforms
    $ Pico file          Simple text editor, comes with PINE mailer.
    $ vi file            Standard Unix editor, comes with POSIX.
    $ EDIT/TPU/interface=DECWINDOWS  file
                          GUI interface for TPU
    $ nedit file         Requires DECWindows.  Simple GUI text editor.
    $ Xhtml file         Requires DECWindows.  Simple HTML editor. 
    
Note 1.  Prior to OpenVMS 6.0 the default editor was EDT, since then, TPU.

Note 2.  Virtually all editors have configuration files that they read
  when they start up.  TPU has several.  Here is a sample configuration 
  file for EDT and instructions for using it.

  First create an initialization file, here where it shows "^Z" in a
  line within the file, it means two separate characters: {^} and {Z}.

$ CREATE SYS$LOGIN:EDTINI.EDT
!
! Set-up file for EDIT/EDT
!
! Pieces from many places - no credits to anybody, sorry!!!
!
! Suppress the bell or buzzer that signals errors
! SET QUIET
!
! Define delimiters for the word entity
SET ENTITY WORD '	 .,?!;:[]()><*-+=/\'
!
! Define delimiters for the sentence entity
SET ENTITY SENTENCE '. ?!'
!
! Suppress line numbers in line mode
SET NONUMBERS
!
! Wrap full words to the next line at 75 characters
SET WRAP 75
!
! Key Definitions:
! 
! Change to the specified buffer
DEFINE KEY GOLD B AS "EXT CHANGE =?'CHANGE TO BUFFER: '."
!
! Change to the last current line in the previous buffer
DEFINE KEY GOLD C AS "EXT CHANGE LAST."
!
! Change the case of the current word
DEFINE KEY GOLD D AS "+CHGCW."
!
! Locate the last current line in the MAIN buffer
DEFINE KEY GOLD G AS "EXT FIND=MAIN.."
!
! Prompt for a buffer name and then locate the last current line
! in the specified buffer
DEFINE KEY GOLD H AS "EXT FIND=?*'BUFFER:  '.."
!
! Exit file
!
DEFINE KEY GOLD E AS "EXT EXIT."
!
! Fill the text of the current paragraph to the right margin
DEFINE KEY GOLD P AS "FILLPAR."
!
! Quote file macro and key definition
DEFINE MACRO QUOTE
FIND BUFFER QUOTE
insert;set quiet
insert;change;er -l 9999(i>^Z -2l) ex
insert;set noquiet
FIND LAST
DEFINE KEY GOLD Q AS "EXT QUOTE."
!
! Shift screen left 1 tab (8 columns)
DEFINE KEY GOLD L AS "SHL."
!
! Append signature file macro and key definition
DEFINE MACRO SIGNATURE
FIND BUFFER SIGNATURE
insert;change;desel er sel ^m ex
insert;include sys$login:signature.txt end
insert;change; -sr ex
FIND LAST
DEFINE KEY GOLD N AS "EXT SIGNATURE."
!
! Shift screen right 1 tab (8 columns)
DEFINE KEY GOLD R AS "SHR."
!
! Replace all occurrences of the specified string in the 
! current buffer with the specified string
DEFINE KEY GOLD S AS "EXT S/?*'REPLACE: '/?*'   WITH: '/WHOLE."
!
! Transpose the two characters to the left of the cursor
DEFINE KEY GOLD T AS "BACK C DC ADV C UNDC."
!
! Write the current buffer to the specified file
DEFINE KEY GOLD W AS "EXT WRITE ?*'WRITE TO FILE: '."
!
! Include the specified file at the current line
DEFINE KEY GOLD X AS "EXT INCLUDE ?*'INCLUDE FILE: '."
!
! Include the specified file at the beginning of 
! the specified buffer
DEFINE KEY GOLD Y AS "EXT INCLUDE ?*'INCLUDE FILE: ' =?*' BUFFER: ';FIND BEGIN."
!
! Select editing mode: 
SET MODE CHANGE
{^Z}          Control-Z to terminate entry of the file

   Next, add the following line in your LOGIN.COM so that EDIT/EDT will
   automatically use this file. It will take effect next time you log in.
   (If ever you don't want to use it, start EDT with: EDIT/EDT/NOCOMMAND).  

 $DEFINE EDTINI SYS$LOGIN:EDTINI.EDT

   If you plan on appending a signature to mail messages, you must
   create the file SYS$LOGIN:SIGNATURE.TXT which is referenced by the
   GOLD N key.

Note 3.  Most text editors use particularly keypad keys for certain
   purposes.  Unfortunately, the keys on your keyboard may not be labeled
   to match the names used in the program.  In particular, the {GOLD} key\
   referred to in the EDT initialization file above is labeled {PF1} on
   most Digital keyboards,  and {NumLOCK} on most PC and Macintosh keyboards.
   It is usually, but not invariably, the leftmost button in the top
   row of the numeric keypad.  To get a keypad map in EDT press the {HELP}
   button on your keyboard.  If that fails, press the second to leftmost
   key on the top row of the numeric keypad.

Note 4.  Most text editors need to know which type of terminal you are 
   using.  Be sure that the command

 $ SHOW TERMINAL     Show terminal configuration.

   is consistent with the terminal/terminal emulator that you are using.

back to top of document


How do I move files?

If they are being moved on the same disk use RENAME.  If they are going
to another disk use COPY or BACKUP.

Examples:

 $ RENAME file1 [DIR1.SUBDIR1]file2
                      Rename file1 to file2 and put it in another 
                      directory on the same disk.
 $ COPY file1 DISK:[DIR1.SUBDIR1]file2
                      Make a copy of file1 elsewhere, and call it file2.
 $ BACKUP/VERIFY/DELETE file1 DISK:[DIR1.SUBDIR1]file2
                      Make a copy of file1 elsewhere, and call it file2.
                      Delete the original after first verifying the copy.
 $ HELP        More information on these commands.


back to top of document


How do I rename files?

See "How do I move files".

back to top of document


How do I view files' contents?

As usual, there are a couple of ways.  Which you use depends mostly
on what you want to know.  Note that most editors have a /READ
switch, or equivalent, which will prevent you from disturbing the file's
contents while looking through it.

    $ TYPE [/page] filename     View contents on screen
    $ EDIT/READ filename        View contents on screen
    $ MOST [/page] filename     View contents on screen
    $ DIFFERENCES filename1 filename2
               Compare two files, look for differences.
    $ DUMP filename   Various views of data in the file.
    $ HELP            More information on these commands.


back to top of document


How do I print files' contents?

Use the PRINT command. All Print commands send a job to a print queue and
then return control to the command line.  Jobs wait in the print queue
until the printer is free, and then they are sent to it.  The logical
symbol SYS$PRINT determines which print queue will be used unless it
is overridden via a /QUEUE= qualifier on the command line. 

Examples:

    $ PRINT filename     Print contents on default printer.
    $ PRINT/QUEUE=CPS_PS filename.ps  
                         Print (Postscript) contents on specified queue.
    $ PRINT/QUEUE=group_lw/FORM=PS_PLAIN filename.ps
                         Print (Postscript) contents on specified queue
                         using a Form.
    $ SHOW QUEUE/FORM    List all available print forms.
    $ SHOW QUEUE/BY_OWN  List queued print and batch jobs.
    $ DELETE/ENTRY=entry_number 
                         Oops, print job to wrong queue? Kill it this way.

back to top of document


How do I find a files by name, date, or other property?

There are two methods.  Usually the DIRECTORY command has the appropriate
qualifiers to find what you want.  For really technical parameters you may
have to use lexical functions inside a DCL procedure.

Examples:

    $ DIR/SINCE=YESTERDAY/BY_OWNER=[GRP_12,FRED]/MODIFIED
              All files in the current directory owned by FRED, who is
              a member of GRP_12, that have been modified since yesterday.

The following is a brief procedure that will find all files in the current
directory that have file organization = sequential.  (Silly example - most
files are sequential!).

$!first line of DCL procedure
$top:
$ file = f$search("*.*")
$ if (file .eqs. "")then exit
$ org = f$file_attributes(file,"ORG")
$ if (org .eqs. "SEQ")then write sys$output file
$ goto top
$!last line of DCL procedure

back to top of document


How do I find files by their contents?

Use the SEARCH command.

Examples:

    $ SEARCH *.TXT FRED
              Find FRED, fred, Fred ,etc. in the most recent versions
              of any file with a TXT extension in the current directory.
    $ SEARCH/WINDOW=0/Exact/Match=and *.TXT "Fred","Jones"
              List the name of any file whose most recent version has
              Fred and Jones in the same line, and which as a TXT extension.
    $ HELP SEARCH More information on the SEARCH command.


back to top of document


How do I protect files from other users? 
How do I share files with other users? 

Set the file protection appropriately.  There are four categories of
users: System, Owner, Group, and World.  For each group, you can specify
what actions they can take regarding a particular file, these are
Read, Write, Execute, and Delete.  Here are some examples of how file
protections are used:

    $ DIR/OWNER/PROTECTION Show who owns what with what protections.
    $ SET FILE/PROTECTION=(S:RWED,O:RWED,G:RE,W) filename
                Owner and system can do anything they want to this file,
                other group members can Read or Executate it, nobody else
                can do anything.  This is a common way to set protectins.
    $ SET FILE/PROTECTION=O:RWED filename
                Reset owner protections as shown, don't change others.

    $ HELP SPECIFY PROTECTION  More info on protections.

You can also allow and deny access by attaching an ACL (access control
list) to a file.  This method of protection is generally configured by
the system manager rather than by a user.

back to top of document


How do I create a directory?

Use the CREATE/DIR command.


    $ CREATE/DIR [.SUBDIR1]
                Create a subdirectory named subdir1.dir in the
                current directory.
 
Note1: Directories can only go eight levels deep.
Note2: You must have appropriate Write access to the point where the
       directory is going in.

back to top of document


How do I delete a directory?

Change protections so that you can delete it.
First delete everything that is in it.
Then delete it.

Example:

  $ SET FILE/PROTECTION=O:RWED [.subdir1]*.*;*
  $ SET FILE/PROTECTION=O:RWED SUBDIR.DIR
  $ DELETE [.subdir1]*.*;*
  $ DELETE SUBDIR.DIR;

back to top of document


How do I rename a directory?

Use the RENAME command, just as you would for a regular file.  However,
first you must modify it so that O:D protection exists.

Example:

  $ SET FILE/PROTECTION=O:RWED subdir1.dir
  $ RENAME sudir1.dir [-]
                move the subdirectory one level up

back to top of document


How do I move to another directory?

Use the SET DEFAULT command. You can use either an absolute
directory path, a relative directory path, or a logical name
defined to be one of these. 

The general form is:

  $ SET DEFAULT DEVICE:[DIRECTORY.SUBDIR]

Usually DEVICE: is a disk of some type, you can leave that
piece off if you are moving around on the same disk. 

Examples:

  $ SET DEFAULT  [.SUBDIR]          relative move down
  $ SET DEFAULT  [.SUBDIR1.SUBDIR2] relative move deeper
  $ SET DEFAULT  [-]                relative move up one level
  $ SET DEFAULT  DISK:[USERNAME]    absolute move
  $ DEFINE THERE DISK:[USERNAME]    define an absolute location
  $ SET DEFAULT THERE               move there
  $ DEFINE UP  [-]                  define a relative location
  $ SET DEFAULT UP                  move there

back to top of document


How do I identify the current directory?

Use the command SHOW DEFAULT.

Example:

  $ SHOW DEFAULT
  DISK:[USERNAME]


back to top of document


What are RMS attributes?

Most OpenVMS files are handled by a subsystem known as RMS, for Record
Management Services.  This part of the operating system allows OpenVMS
programs to use optimized file formats for various applications, and yet
still be able to read each others' files.  Rarely do users need to concern
themselves with RMS attributes, which describe the way the records (chunks
of information within the file) are arranged.  If it does come up, here are
a few of the relevant commands: 

  $ ANAL/RMS file
       See what the RMS attributes of file are.
  $ ANAL/RMS/FDL/OUTPUT=RMS  file
       Create a file called RMS.FDL that describes the records in file.
  $ CONVERT/FDL=RMS.FDL  file1 file2
       Convert the record structure in file1 to match that described in
       RMS.FDL and put the result in file2.
  $ SET FILE/ATTRIB=(LRL:1000) file
       Change one of the RMS attributes of file.
  $ EXCHANGE/NETWORK/FDL=RMS.FDL file1 file2
       Used primarily with files that are in stream-lf or fixed 512 byte
       record format (both common "binary" formats).  The exchange command
       will reestablish the original RMS attributes of the file, if they
       are available in an RMS.FDL file. 

Note 1.  The output of many DEC C programs are in stream-lf format.  Such 
         files have the unfortunate property that the Longest Record
         field is set to its maximum value of 32767.  Normally this makes
         no difference, but it is a problem if you try to SORT such a file.
         The default action of the SORT utility is to allocate as much space
         for each record as the LRL value specifies.  This works well for
         most files where each record is short.  Here, however, the
         huge apparent record sizes make the sort exceedingly slow.  There
         are a couple of workarounds:

         $ TYPE/OUT=NEW.TXT file.txt
                     Make another copy through type, which will 
                     correctly set the LRL, then sort the copy
         $ SET FILE/ATTRIBUTE=(LRL:30) file.txt
                     Set the LRL correctly, if you happen to know it.
                     Then sort the modified file.
         $ SORT/PROCESS=TAG/key=(pos:1,size:10) file.txt
                     Tell SORT to process the file differently - it will
                     only make space for the key region - 327 times smaller
                     than the declared "record" size.

back to top of document


What is/are creation, modification, and backup dates?

Creation date:         when the file was first made.
Modification date:     when the file was last modified.
Backup date:           when the file was last backed up.

back to top of document


How do I handle mail?

Use the MAIL command in a terminal.  If you have DECwindows, there is a
similar MAIL tool available on the Session Manager's Applications 
menu.  Additional mail tools may have been installed, notably PINE.

In all cases, you start the appropriate mail tool, and then do all mail 
manipulations from within it: create, read, send, delete, etc.

Examples:

  $ MAIL    Start mail for interactive use.
  $ PINE    Start pine for interactive use.
  $ run sys$system:decw$mail
             Requires DECwindows.  Or start it from the session manager.
  
The TCP/IP transport on an OpenVMS system may be provided by one of
several different vendors.  To send SMTP (internet) mail through
these, use an address like: 

  PREFIX%"username@what.where.com"

Where prefix is usually one of: SMTP, IN, ST, MX, or MM.  The Pine mailer
is usually configured to know the local SMTP transport's PREFIX and to use
it automatically, so the destinations used within that program are usually
just the unadorned internet addresses.  

  Here is a very brief example of how to use MAIL to send an internet message.

  $ MAIL
  MAIL> send
  TO: SMTP%"username@what.where.com"   Locally correct transport
  Subj:   this is a test
  Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit:
  This is a test message
  bye
  {^Z}
  MAIL> exit
  $

  Here is a somewhat longer example which demonstrates some of the typical
  operations in MAIL:

  $ MAIL                   Start mail for interactive use.

  You have 10 new messages.

  MAIL> DIR                List messages in the NEWMAIL folder.
  MAIL> 5                  Read message 5.
  MAIL> EXTRACT/NOHEADER sys$login:fromjane.txt
                           Copy it into a text file in the login directory.
  MAIL> REPLY/EXTRACT
                           Starts an editor and copies the message into
                           it. On exit the reply is sent back to the
                           original sender.  Use the SET and SHOW commands
                           to customize operations like this, here, to
                           choose a different editor. 
  MAIL> DEL 1-4,6-10       Move all other messages to the WASTEBASKET folder.
  MAIL> DIR/FOLDER         List names of all folders.
  MAIL> SET FOLDER MAIL    Move to another mail folder.
  MAIL> DIR/FROM=jane/subject=project/since=1-JUN-1995
                           Select a subset of all messages in this folder.
  MAIL> EXTRACT/ALL/NOHEADER sys$login:fromjane_project.txt
                           Copy all of these, each separated by a form
                           feed character into a text file in the login
                           directory. 
  MAIL> SET FOLDER WASTEBASKET 
                           Move to the WASTEBASKET folder.
  MAIL> DIR                List messages in the WASTEBASKET folder.
  MAIL> SELECT/from=john   Not going to delete those from john after all.
  MAIL> MOVE MAIL          Move them WASTEBASKET -> MAIL
  MAIL> SEND/EDIT
  TO:      SMTP%"username@what.where.com" Internet mail, see below
  SUBJECT: Test
                           An editor is started, a text file is edited,
                           on exit it is mailed to the address shown.  To
                           mail to somebody onthe same system just put
                           their username on the TO line. 
  MAIL> EXIT               Leave mail, delete anything left in WASTEBASKET
  $

Note 1: After entering MAIL, use HELP to figure out what it does.

Note 2: Send/edit and reply/extract are how you generally want to
        send and reply to mail.

        Here's why.  The SEND command in interactive mail, if invoked with
        no qualifiers, puts up a simple text entry window.  You must
        type a {RETURN} at the end of each line (even though the screen
        usually appears to be wrapping text as in a word processor) or any
        but the shortest message will fail with this error: 

               Error reading SYS$INPUT
               xxx byte record too large for user's buffer
               No message sent

        Using SEND/EDIT avoids this problem.

        REPLY always puts you into an editor so the above problem doesn't
        occur. However, you likely want to use REPLY/EXTRACT instead of
        REPLY, since the former starts the editor with the text of the
        message that you are replying to already loaded. 

Note 3: Mail messages by default go into your SYS$LOGIN directory. To
        put them elsewhere (a very good idea), do the following ONCE:

  $ MAIL
  MAIL> set mail [.MAIL]  This might take a while to complete.
  MAIL> exit
       

Note 4. It sometimes happens that the new mail counter maintained
        elsewhere in the OpenVMS operating system gets out of
        synchronization with  the actual number of unread mail messages. 
        Most  notably, it will say that you have N new mail messages when
        you enter mail, there are none in the NEWMAIL folder.  If you ever
        observe this, simply issue these commands: 

  $ MAIL

  You have 2 new messages.

  MAIL> read/new
  MAIL> exit

Note 5. On rare occasions you may need to email binary files to somebody
        on another machine.  The best way to do this is to use PINE, which
        can send these as MIME (Multimedia Internet Mail Extensions) 
        attachments.  This transfers the data, but all RMS attributes
        will be lost.  Most of the time this doesn't matter, as when 
        transferring a GIF or PICT file, for instance.  However, it DOES 
        matter for BACKUP files and others.  The easist thing to do for
        them is to use ZIP or some other utility to put them into an
        archived form from which they can be extracted with their file
        attributes intact.  ZIP is not part of OpenVMS, but is available
        from a  variety of FTP.  Try FTP.WKU.EDU first.

back to top of document


How do I have a conversation with somebody on the same machine?

Use PHONE.

Examples:

  $ phone username
  $ phone answer      Answer the phone when it is ringing.
  $ set term/[no]broadcast 
                             Enable/disable messages.

back to top of document


How do I have a conversation with somebody on a different machine?

Use PHONE or, if you have it, TALK.

Examples:

  $ phone nodename::username
  $ phone answer      Answer the phone when it is ringing.
  $ set term/[no]broadcast 
                             Enable/disable messages.
  $ talk username@what.where.com
                             Same command to answer a call.

Note1:  To get out of PHONE, use {^Z}, then EXIT.  For more information
        you can type HELP after {^Z}.
Note2:  To get out of TALK, use {^C}.
Note3:  TALK may not work to some machines due to byte swapping issues.

back to top of document


How do I copy files to/from another machine?

Use COPY, or if you have them FTP.

Examples:

  $ COPY filename NODE::DISK:[DIRECTORY]filename
                             Over DECNET, requires proxy access.
  $ COPY filename NODE"username password"::DISK:[DIRECTORY]filename
                             Over DECNET, no proxy required, but you 
                             have to have an account there that is valid.
  $ FTP what.where.com
                             To a Unix machine, MULTINET syntax shown.

* Latest versions of OpenVMS recognize COPY/FTP e.g.:
  COPY/FTP/BIN filename NODE"username passwd"::DEV:[DIRECTORY]targetfile
                              Copy using FTP in BINARY mode.
 
Note1:  COPY and FTP can be used in either direction.
Note2:  Unless all nets are secure between the two machines in question,
        putting the username,password pair into one of these programs is
        a security risk.  Network sniffers can easily retrieve them and 
        then your account may be compromised.
Note3:  Unless all nets are secure between the two machines in question,
        the contents of the files transferred may end up in the hands of
        third parties.
Note4:  If your site uses PATHWORKS you may be able to use COPY to move
        files directly to/from a PC or Macintosh that is running DECNET:

        $ define desktop macname::disk:[DESKTOP_FOLDER]
        $ COPY filename desktop:
                             The file appears on the Mac's desktop.
        $ DIR desktop:
                             Files on the Mac's desktop are listed.

back to top of document


How do I execute commands on another machine?

You can either use a combinatin of COPY and TYPE commands, or use RSH
if that is installed.

Examples:

  $ COPY procedure.com NODE::DISK:[DIRECTORY]
                             Over DECNET, requires proxy access.
  $ TYPE NODE::"task=DISK:[DIRECTORY]procedure.com"
                             Over DECNET, requires proxy access.
Note1:  This copies a procedure to another node and then executes it.
        If proxy access is not available an explicit "username password"
        string can follow the NODE name.

  $ RSH what.where.com "command"

Note2:  Generally RSH is used to talk to Unix machines. These are case
        sensitive, so double quoting the command is often required.  If no
        .rhosts file or hosts.equiv provides access you may be prompted
        for username and password.

back to top of document


How do I use a news reader? 

Details vary from system to system - there is no standard news reader.
Ask your system manage what is installed on your system.

Example:

  $ NEWSRDR

back to top of document


How do I participate in IRC sessions?

Internet Relay Chat (IRC) is not generally installed on OpenVMS systems. 
If it happens to be on your system, then the following command is usually
the one that start it:

  $ IRC

Note1:  To get started with IRC, issue the command: /HELP.
Note2:  IRC use may pose a security risk, at the very least, do not
        type in a command that somebody tells you to type!

back to top of document


What is DCL?

DCL stands for Digital Command Language.  It is the primariy command line
interface on OpenVMS systems.  DCL is in charge of interpreting commands
entered either interactively from a terminal, or read form a command 
procedure.

back to top of document


What is a DCL procedure?

Often the same series of DCL commands need to be issued many times,
or some action needs to be automated.  By placing a series of DCL commands
in a file these goals can be attained.  DCL supports control logic
(IF, GOTO, CALL, etc.) so that quite complicated programs can be written in 
it, if need be.

Examples DCL procedure (finds all organization:sequential files in a
directory - not a terribly useful thing to do!):

$!first line of DCL procedure: search_example.com
$!P1 is a search string
$ if(P1 .nes. "")
$ then
$   string = P1
$ else
$   string = "*.*"
$ endif
$top:
$ file = f$search(string)
$ if (file .eqs. "")then exit
$ org = f$file_attributes(file,"ORG")
$ if (org .eqs. "SEQ")then write sys$output file
$ goto top
$!last line of DCL procedure

  $ @SEARCH_EXAMPLE        Default, look at everything in local directory
  $ @SEARCH_EXAMPLE [.SUBDIR]*.TXT
                                  Look where indicated
  $ SUBMIT/LOG=SYS$LOGIN:/NOPRINT/AFTER=20:00 SEARCH_EXAMPLE
                    Default, but do in batch, after 8:00 PM
  $ SUBMIT/LOG=SYS$LOGIN:/NOPRINT/AFTER=20:00 -
  $_/PARAMETER=("[.SUBDIR]*.TXT")SEARCH_EXAMPLE
                    Look where indicated, in batch after 8:00 PM

back to top of document


Why would I ever use a DCL procedure?

You would use one if you don't want to type the same thing over and
over, if you want something to happen when you aren't around, or if
you need to do some processing and/or calculations, but not manually.

back to top of document


How do I create a DCL procedure?

Use the same tools as for any other file.

back to top of document


How do I pass parameters into a DCL procedure interactively?

You can pass up to eight parameters to a DCL procedure.

  $ @procedure A B C D E F G H

Note:  If any parameter A through H contain case sensitive values or spaces
       enclose it in double quotes.

back to top of document


How do I pass parameters into a DCL procedure when it runs in batch?

You can pass up to eight parameters to a DCL procedure which is run in 
batch:

  $ SUBMIT/parameter=(A,B,C,D,E,F,G,H) procedure

Note:  If any parameter A through H contain case sensitive values or spaces
       enclose it in double quotes.

back to top of document


How do I see parameters inside a DCL procedure?

Inside a DCL command file they will appear as symbols, named P1 through P8.

Here is a common trick:

  $ if(P1 .eqs. "")
  $ then
  $!   There was no P1 parameter
  $ else
  $!   There was a P1 parameter
  $ endif

Note that other global symbols (those defined with :== or == before
the procedure is run) may also be used inside a procedure.  However,
the proper way to test for one of these is like this:

  $ if("''SOME_GLOBAL_SYMBOL'" .eqs. "")

The "''symbol'" form must be used with global symbols because otherwise if
one were not defined the procedure would generate an error like this: 

  Undefined symbol - check validity and spelling
    \SOME_GLOBAL_SYMBOL\

The simpler form can be used for P1 through P8 because when a procedure
starts, DCL creates all eight symbols automatically (even those that were
not specified on the command line, which are set to ""). 

back to top of document


How do I control the flow of the procedure?

Here are some examples of the control structures in DCL, for more
information on each use HELP:

  $ ON condition THEN action

  $ IF (expression) THEN action

  $ IF (expression)
  $ THEN
  $! action1
  $ ELSE
  $  action2
  $ ENDIF

  $ TOP:            This is a label, note the colon.
  $ GOTO TOP        This is a goto, note the lack of a colon.

Note1:  As for command procedures, up to eight parameters may be passed
to a subroutine.  This form is roughly equivalent to creating a separate
file and executing it via "@filename parameters".  Here is an example,
note especially the SUBROUTINE and ENDSUBROUTINE lines:

  $ SUB1: SUBROUTINE Begin a subroutine declaration.
  $! a bunch of commands that compose the subroutine
  $ EXIT             Exit point for subroutine.
  $ ENDSUBROUTINE    End subroutine declaration.
  $ CALL SUB1 A B C D E F G H

Note2:  There is another form of subroutine, a labeled subroutine, that
runs at the same level as the calling program.  One cannot pass parameters
to them.  Not is there a need to - they have direct access to all locally
defined variables.  Here is an example of this second type of subroutine
In the following example of this second type of subroutine, note in
particular that the transfer of control to the subroutine is via a GOSUB
rather than a CALL, that  the SUBROUTINE and ENDSUBROUTINE lines are
absent, and the use of RETURN instead of EXIT: 

  $ SEMISUB1:        Begin a labeled subroutine.
  $! a bunch of commands that compose the subroutine
  $ RETURN [value]   Exit point for subroutine.
  $!
  $ GOSUB SEMISUB

Note3:  The operators which may be used in expressions are:
Integer operations: +,-,*,/ (the standard math functions)
Integer comparisons: .EQ., .GE., .GT., .LE., .NE.
String operations: + (concatenate), - (remove substring)
String  comparisons: .EQS., .GES., .GTS., .LES., .NES.
Logical operations:  .NOT., .AND., .OR.
An integer is TRUE if it is ODD.  The special symbol $STATUS will
be odd if the preceding command completed successfully, and even
if it failed.

back to top of document


How do I manipulate symbols?

There are a lot things that one can do with symbols.  Here is a not
particularly useful piece of code that shows some of them.

 $ INQUIRE string "This is a prompt, enter a string"
 $! echo the string to the terminal, note that it has gone to all upper case
 $ WRITE SYS$OUTPUT string
 $! echo the string to the terminal, show what quotes do in double quotes
 $ WRITE SYS$OUTPUT "This is a ''string'"
 $! Here's a lexical function - learn them, love them
 $ x = f$length(string)
 $ WRITE SYS$OUTPUT "''string' is ''x' characters long"
 $! one more time, same output, different method
 $ WRITE SYS$OUTPUT string," is ",x," characters long"
 $ write sys$output "Here is ''string' in all lower case, no spaces",-
   F$edit(string,"LOWERCASE,COLLAPSE")
 $!
 $! invert string order
 $!
 $ ix = X - 1
 $ OUTSTRING=""
 $ TOP:
 $   OUTSTRING = OUTSTRING + F$EXTRACT(ix, 1, string)
 $   ix = ix - 1
 $   if (ix .ge. 0)then goto top
 $ write sys$Output "''string' backwards is: ''outstring'"
 $!
 $! more fun with strings, replace part of a string
 $!
 $ frag = "this is a long string"
 $ frag[0,4] := THIS
 $ write sys$output "this is frag now: ''frag'"
 $!
 $! remove a piece and glue on another one
 $!
 $ where :== disk:[DIR.SUBDIR1]
 $ where = where - "]" + ".SUBDIR2]filename"
 $ write sys$Output "Where is ''where'"
 $!
 $! ring a bell on the user's terminal
 $!
 $ bell[0,7]=7
 $ write sys$output "You should here a bell''bell'"

back to top of document


How do I manipulate logical names?

Use DEFINE, ASSIGN, DEASSIGN and sometimes SHOW LOGICAL or
F$TRNLNM("logical_symbol_name").

Examples:

 $ DEFINE there DISK1:[USERS.FRED]
            Define a logical value specifying a location.
 $ ASSIGN DISK1:[USERS.FRED] there
            Same effect as preceding command.
 $ DEFINE avalue "This is a string that some program needs"
 $ SHOW LOG avalue
   "AVALUE" = "This is a string that some program needs" (LNM$PROCESS_TABLE)
 $ DEASSIGN avalue      Get rid of the logical name.

back to top of document


How do I gather information about files, processes, the system, etc.?

Use lexical functions.  For more information use:

 $ HELP LEXICAL   Look up info on lexical functions.

See in particular:

  F$FILE_ATTRIBUTES      Get file information
  F$GETDVI               Get device information
  F$GETJPI               Get job and process information
  F$GETQUI               Get batch and print job information
  F$GETSYI               Get local system information

back to top of document


How do I bury untypable values in symbols??
How do I make text blinking, underlined, and so forth?

To put things like {bell} or {escape} into a text string one
must use a special symbol definition syntax.  Note that the
symbol must not have been previously defined or this will
NOT work. 

 $ bell[0,7]=7
 $ esc[0,7]=27
 $ write sys$output "''esc'[5mblinking''esc'[m and beeping ''bell'"

The list of escape codes for various terminals is in
SYS$SYSTEM:SMGTERMS.TXT, where {$} is used for {escape}.
Note that the user's terminal must understand VT type escape
codes to respond properly. You can and should check this
before sending these codes to a terminal (and NEVER to a
batch job). This information can be found via: 

 $    if(F$GETDVI("TERM","TT_DECCRT"))then some action
back to top of document


How do I do decimal math?
With "vanilla" DCL you cannot - it only supports integer
math. However, in some cases you can fake it, for instance,
if you need to multiply 1.2 * 1.3, you might instead
multiply 12 * 13 and then use other DCL features to shift
the decimal point back where you want it. 

Sometimes a better option is to use ICALCV.  (ICALCV is 
available via anonymous FTP as [.software]ICALCV.ZIP from 
seqaxp.bio.caltech.edu, UNZIP is available from ftp.wku.edu)
ICALC is a small program that implements a command line 
calculator, ICALCV is a slightly modified version that 
places the last 10 results into a comma delimited list and
assigns that string to the DCL symbol ICALC_OUT.  So, for
instance:

 $  show symbol icalc    ICALC must be defined
  ICALC == "$ICALC:ICALCV"
 $  define/user sys$output nla0:  suppress terminal output
 $  icalc 1.2*1.3
 $  write sys$Output icalc_out Show the result
        1.56

Or, to do a bunch of things at once, for instance, as part 
of a DCL procedure:

 $  string := 1.2*1.3; 1.3*1.5; 1.5*1.9; 1.2*sqrt(10)
 $  define/user sys$output nla0:  suppress terminal output
 $  icalc 'string'
 $  write sys$Output icalc_out Show the result
        1.56,        1.95,        2.85,        3.794733192

Then use F$ELEMENT to retrieve each desired result, for 
instance:

 $  write sys$output f$element(0,",",icalc_out)
        1.56
 $  write sys$output f$element(1,",",icalc_out)
        1.95

etc.

back to top of document


What is POSIX?

POSIX is a "standard" form of Unix.  On OpenVMS, if you type POSIX you
will be transferred into the POSIX subsystem, which looks pretty much
like any other Unix you are used to.  Or at least, it is no more different
from other Unixes than they are from each other.
* POSIX is not found, by default, on current versions. 

back to top of document


Why would I ever use POSIX?

Primarily you either use POSIX because you grew up using Unix and can't 
function outside of that environment (give me vi or give me death!), or
because you need to use some tool that is in there that doesn't have a
close OpenVMS equivalent (awk, for instance). 

back to top of document


What is DECwindows?

DECwindows is Digital's version of the X11 window system.  It provides
a Graphical User Interface (GUI) similar in some ways to that on a
Macintosh or Windows computer.  It differs from them primarily in that
the machine displaying the GUI (the SERVER) need not be the same as
the machine writing/reading the GUI (the CLIENT).

back to top of document


Why would I ever use DECwindows?

Because it will let you point and click your way through various operations,
and also manipulate images relatively easily.  Besides, if you ever use the
console of a VAXstation or AlphaStation you will have little choice. 

back to top of document


How do I redirect the display to another machine?

  $ SET DISPLAY/CREATE/TRANSPORT=TCPIP/node=what.where.com

The transport can be TCPIP, LAT, or DECNET, subject to that transport 
having been properly configured on your machine.  Note that only Digital
machines are likely to support DECwindows over LAT or DECNET.  Use
the appropriate node name for the type of transport, in the example
shown the equivalent DECNET node name is likely "WHAT".

back to top of document


How do I tell where the display is going now?

  $ SHOW DISPLAY

If you want to move the values into symbols so that a DCL program
can handle it, use instead:

  $ SHOW DISPLAY/SYMBOL

This will define the following symbols:

  DECW$DISPLAY_NODE
  DECW$DISPLAY_SCREEN
  DECW$DISPLAY_SERVER
  DECW$DISPLAY_TRANSPORT

Note:  The /SYMBOL qualifier is undocumented and may change in
future versions of OpenVMS.

back to top of document


How do I allow another machine to display on my screen?

Click on "Session Manager".
Click on the "Options" menu.
Select "Security Options".
Fill in the NODE, TRANSPORT, and USERNAME information for the machine
  that you wish to allow access.  The wildcard * can be used in any field.
  Some transports don't verify usernames, so use * in the username filed
  if it won't work otherwise.
Click on "Add".
Click on "Apply", to have it take effect.

To remove access rights, as above, but instead of "Add", highlight
a field in the "Authorized Users" list, then click on "Remove".
Again, "Apply" makes it take effect.

back to top of document


Isn't there some simple way to move files around?

Yes, use the FileView application.  Start it from the applications menu
in the Session Manager.

back to top of document


How do I stop an application that has locked up?

If your application has gone into an infinite loop or wait, as signified by 
either nonresponse or a "watch" icon that won't go away, you can stop it by:

Select Session Manager window.
Select Session Menu.
Select Work in Progress.
Select the window that is giving you problems by clicking on it.
Click on Stop Task.  Sometimes you must click on it twice for the same 
  window.

back to top of document


How do I select menus and options without the mouse?

Hold down the {alt-function} key and press the matching letter on the 
keyboard.  For instance, to open the File menu in the current window
press  {alt-function} and {f} together.

To move between windows use {alt}{F3}, but the mouse works better.

back to top of document


What do each of the three buttons on the mouse do?

Unfortunately, that depends a lot on the application in question.  In 
general though:

Left:    Select objects in the window, or items on the menu bar.
Center:  Varies.
Right:   Pop up menus when clicked in the window.

Inside text fields, dragging over an area with the left button down selects 
it, then it can be pasted with a click of the center button.  Or, in some
applications, dragging over text with the center button down, then 
releasing it, will paste the highlighted text at the cursor.

back to top of document


Valid HTML 4.01! Valid CSS!