Category : Miscellaneous Language Source Code
Archive   : AVTS.ZIP
Filename : AVTS.DOC

ARIS VERSION TRACKING SYSTEM

Version 1.3

















Alexander Riedel Informations-Systeme
Parkstr. 2
D-85646 Anzing
Germany













Document release date: June 10, 1993
Printed in Germany
Document AVTS.DOC












Information in this document is subject to change without notice and
does not represent a commitment on the part of ARIS. The software
described in this document is furnished under a licence agreement or
nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to
copy the software on any medium except as specifically allowed in the
license or nondisclosure agreement. No part of this manual may be
reproduced or transmitted in any form or by any means, electronic or
mechanical, including photocopying and recording, for any purpose
without the express written permission of ARIS.

(c) 1992 Alexander Riedel Informations-Systeme
All rights reserved



I. Introduction 4
1. What is a Version Tracking System? 4
2. Installing ARIS Version Tracking System 5
3. Differences to previous versions 6

II. Tutorial 7
1. Creating and editing a project 7
2. Configuration management 9
3. Module history and editing activity 10

III. Reference 11
1. AVTSDIFF - Compares two versions of an AVTS file 11
2. AVTSGREP - Search project files for patterns 11
3. CDC - Change Delta Comment 14
4. CREATE - Creates projects and apply files to them. 15
5. DELTA - Creates a new version (delta) of a file
in an AVTS project. 16
6. DIFF - Compares two files and creates a
difference listing 17
7. GET - Copies a project file and locks it 17
8. HISTORY - Prints the revision history of a file
in an AVTS project 19
9. LOGVIEW - View the contents of a project's log file 20
10. READ - Copies a project file without locking 20
11. RMALIAS - Removes an alias name from a
specific version of a module 22
12. RMAVTS - Removes a file from an AVTS project 23
13. SACT - Reports current editing activity in an
AVTS project 23
14. SETALIAS - Sets the alias name for one or more
modules 25
15. UNDIFF - Applies a diff script to a file. 26
16. UNGET - Reverses a GET command without
creating a new version 26
17. WHAT - Extracts identifying strings from program files 27

IV. APPENDIX A - ERROR MESSAGES 28
V. APPENDIX B - ENVIRONMENT 31





I. Introduction

1. What is a Version Tracking System?

A Version Tracking System is a valuable tool for managing software
projects in network environments. It prevents conflicts between team
members that could otherwise work on the same module and keeps track
of all changes that have been applied to a module of the software
project.

It also helps you maintain your current configuration by preventing
you from accidentally linking wrong modules and therefore increases
the quality of your software if you are a single programmer or if you
work in a team without network.

This is done by controlling access to the source files in such a way
that only one user at a time has control over the current version of
a module. All other users are still able to read the current or
earlier versions of a module for reference or for building test
applications.
Another advantage of a Version Tracking System is the ability to
trace back the development path. You may retrieve information about
who applied what change and when and you may even retrieve earlier
versions of your modules. This gives you the security and quality you
deserve. No need to guess which files belong to a specific version of
your software just ask for them, even if it is a long time ago and
even if you are two, three or more version after the one you want to
have rebuilt.


The ARIS Version Tracking System (AVTS) manages all files that belong
to a certain project by storing these files in an internal form in a
subdirectory. This sub directory is created under the directory where
the executable files for AVTS are stored.
You may create a project by explicit use of the command CREATE but it
is automatically created if you apply the first file to a non-
existent project (You will see a deeper discussion of the commands
and their usage later).
You will have to define all files that are involved with the project
to AVTS. For you as a user there is no difference whether you handle
source modules (ASCII text) or binary files (executables, object
files, spreadsheets or text processor documents). Once you have done
that you will always follow the development cycle outlined below:

- Get a file from the AVTS
- Work on it
- Give it back to keep a record of the changes.

That's it!

While you work on a specific module no other user is allowed to get
it for work. They may, however, get a copy of it for reference. Per-
haps you will also need some more modules from the project to create
a test version of your application. Then the development cycle looks
like that:

- Get the file to work on from AVTS
- Read all other files you need from AVTS
- Work on your module
- Give the modified module back

That is enough theory for the moment. You will see some examples that
show how to work with AVTS later.

2. Installing ARIS Version Tracking System

The installation of the ARIS Version Tracking System (AVTS) is very
easy. Simply type the following command at your DOS prompt:

A:SETUP

and press the ENTER key. If you have the product disk in a drive
other than A:, replace the A with the letter of the drive to be used.
You will be prompted for a directory where SETUP should install AVTS
after some screens providing additional information. The default in-
stallation drive and directory is C:\AVTS. You may, however, change
this to your needs. After supplying the path specification, SETUP
copies all necessary files to the installation drive and directory.

After this process is completed you are prompted, whether you want
SETUP to edit the PATH statement in your AUTOEXEC.BAT to include the
installation path in your search path. You may omit this step:

- if you have already chosen a directory in the search path
- or if you want to make these changes on your own.

Note that AVTS needs the installation directory included in the PATH
variable to work properly.

Once you are back to the DOS prompt, you might have to reboot your PC
to activate the changes to your AUTOEXEC.BAT. To do this, hold down
the keys Ctrl-Alt-Del and your system will reboot.

Below you see a list of the files you should find in the installation
directory with a brief description of what they are for.

AVTSDIFF.EXE Compares two versions of an AVTS file.
AVTSGREP.EXE Searches project files for regular expressions.
CDC.EXE Changes the comment of a delta.
CREATE.EXE Creates projects and apply files to them.
DELTA.EXE Creates a new version (delta) of a file in an AVTS
project.
DIFF.EXE Creates a listing of the differences between to
versions of a file.
GET.EXE Copies a project file and locks it.
HISTORY.EXE Prints the revision history of a file in an AVTS
project.
LOGVIEW.EXE Online viewer for a project's log file.
READ.EXE Copies a project file without locking it.
RMALIAS.EXE Removes an alias name from a specific version of a
module.
RMAVTS.EXE Removes a file from an AVTS project.
SACT.EXE Reports current editing activity in an AVTS project.
SETALIAS.EXE Sets the alias name for one or more modules.
UNDIFF.EXE Creates a new file by applying a diff listing to an
existing file.
UNGET.EXE Reverses a GET command and discards the changes.
WHAT.EXE Displays identifying information about files.

Since AVTS creates an audit trail of all changes applied to a pro-
ject, it needs to know your name. For that purpose you may either
specify your user name with an option for every command or, more con-
veniently, set the environment variable USERNAME to your login name.
If you are not working in a network we suggest to set this variable
to your last name or whatever suits you.

3. Differences to previous version

While the previous versions of AVTS only allowed simple filenames
(files in the current directory). This version now also allows names
including relative and absolute path names. Therefore a file in a
project created with the name C:\MYDIR\FOO.C will always be copied
to/from this specific path. The commands GET and READ take care of
eventually non-existing directories and create them if neccessary. As
this enhancement required a change in internal structures, a conver-
sion utility is neccessary to change projects created with AVTS ver-
sions prior to 1.3.
This conversion utility, V12TOV13.EXE, is only included in registered
versions of AVTS.

Another topic of discussion in previous versions was whether files
should be deleted after a DELTA or an UNGET command. According to the
majority of users, these commands now delete input files after pro-
cessing them. You may, however, specify a flag (-d) when using this
commands, which prevents the files from being deleted. In that case
the read- only attribute will be set for the processed files to keep
you from editing them by accident.

II. Tutorial

1. Creating and editing a project

For all of our following examples we will assume that our project has
four source code modules written in the C language (MYAPP.C, MYMENU.C,
MYFILE.C and MYPRINT.C), two header files (MYAPP.H and MYFILE.H), a
makefile (MYAPP.MAK) and the documentation file (MYAPP.DOC).

We will now assume, that we have written a first version of all these
files and will now start to introduce these files to an AVTS project.
This will be done by the following command sequence:

set USERNAME=MYNAME
create -pmyapp MYAPP.C
create -pmyapp MYMENU.C
create -pmyapp MYFILE.C
create -pmyapp MYPRINT.C
create -pmyapp MYAPP.H
create -pmyapp MYFILE.H
create -pmyapp MYAPP.MAK
create -t1 -pmyapp MYAPP.DOC

The last command has a parameter that makes it different from the
previous command: -t1
This tells AVTS that this file has to be treated as binary file
rather than as ASCII file. AVTS will not create differential listings
on versions applied to this file. Each version of this file is stored
as is.

You might now want to have a look at the log file which is updated
each time you make a change in a project.

Assuming that you installed the AVTS in the default directory
(C:\AVTS) you will find the log file under this name:

C:\AVTS\MYAPP.RCS\RCS.LOG

This log file is a plain ASCII text file and readable by every editor.
You do not need to remember such long paths. Simply use the utility
LOGVIEW for viewing a project's log file.

For the above example the log file will now look like this:

Sun Dec 13 21:56:35 1992 User MYNAME creates MYAPP.C, version 1.0
Sun Dec 13 21:56:36 1992 User MYNAME creates MYMENU.C, version 1.0
Sun Dec 13 21:56:37 1992 User MYNAME creates MYFILE.C, version 1.0
Sun Dec 13 21:56:38 1992 User MYNAME creates MYPRINT.C, version 1.0
Sun Dec 13 21:56:39 1992 User MYNAME creates MYAPP.H, version 1.0
Sun Dec 13 21:56:40 1992 User MYNAME creates MYFILE.H, version 1.0
Sun Dec 13 21:56:41 1992 User MYNAME creates MYAPP.MAK, version 1.0
Sun Dec 13 21:56:42 1992 User MYNAME creates MYAPP.DOC, version 1.0

Now you decide that you want to make some enhancements to the module
MYFILE.C. To make things easier, you can now set the environment var-
iable PROJECT to MYAPP by using the command

SET PROJECT=MYAPP.

This allows you to omit the project name on the command lines of AVTS
commands.

Issue the following command to check MYFILE.C out:

get MYFILE.C

This command copies the actual version of MYFILE.C to your current
directory and locks this module for other users. You may now edit
this module to apply the changes you have in mind without worrying
about others that might change it while you work on it.

For reference you might need the file MYAPP.H also, but you do not
want to have it locked, so that another user is able to change this
module. To achieve that, issue the command:

read MYAPP.H

This also copies the actual version of this file to your current dir-
ectory, but leaves the module unlocked. You may also use this command
if this module is locked by another user.
After you have made all required changes to MYFILE.C you have to tell
AVTS that you have made some changes to that module. This is done by
the command

delta MYFILE.C

After issuing this command you will be asked to enter a comment for
your changes. You may type a character string of up to 126 characters
long.

What if you made up your mind and decided not to change anything in a
module you had checked out using the 'get' command? You may simply
remove the lock flag from the module by issuing the command

unget MYFILE.C

This removes the lock flag of module MYFILE.C and makes it available
for other users.


2. Configuration management

You have now learned the basic tasks for managing a project with AVTS.
You can introduce new files to a project, get files for editing and
read them for reference. You also know how to give them back to AVTS
to keep track of versions.
There is more to AVTS. It also allows you to keep track of your confi-
guration.
In a certain project state you will decide that the current state is
your "Beta Version 1.0". You may now give the current versions of
your modules an alias name, that allows you to retrieve all modules
belonging to this project state easily even if you have done major
changes to your modules.

For this purpose you have to use the command "SETALIAS". An alias
name can be up to 79 characters in length. For our sample project you
would have to enter the following command:

setalias "-aBeta Version 1.0" -pMYAPP all

This marks the current versions of all modules in the project MYAPP
with the alias name "Beta Version 1.0".
If you have already tagged one or more modules with the same alias
name you will get a warning and nothing will happen to them. If the
current version of a module already has another alias name you will
also get a warning message and that alias name will be overwritten
with the new one you specified on the command line.



If you want to remove an alias name from a specific version of a
module you can use this command:

rmalias -aaliasname module


If you want to retrieve a configuration with a specific alias name
simply issue the following command:

read "-aBeta Version 1.0" -pMYAPP all

This command reads all modules tagged with the alias name:

"Beta Version 1.0"

and copies them to your current working directory. Please note that
the quotation marks are necessary if your alias name contains blanks.

This mechanism provides an easy method to mark and retrieve specific
project states at every time. That way you can build up version 1.0
of an application that is currently at version 15.99 without thinking
about what modules belong to it.



3. Module history and editing activity

A major point of interest is which user has done which changes and
when. Some information can be obtained by reading the project's log
file. But if you need the specific history of a module and the
comments a user entered for each delta you will have to use the com-
mand 'HISTORY'.

The following command retrieves all information known of a certain
module and prints it to the screen. You can easily re-direct the out-
put of this command to a file or a printer. Have a look at the ex-
amples for the command 'HISTORY' in chapter III. REFERENCE.

A simple example for this command is:

history MYFILE.C

This command prints out a editing history for the module MYFILE.C
from its initial creation up to the current version.

While reviewing the comments you made for specific versions of a
module you may think that the comment you typed in when the delta
command asked for it, doesn't really match what you wanted to say.
Therefore we supplied an extra command that allows you to change the
comment for a specific version of a module. Though, if you want to
change the comment for i.e. version 2.9 of module MYAPP.C you may use
the following command:

cdc -v2.9 -pMYAPP MYFILE.C

Note that if you omit the version parameter you will change the
comment of the current version. The project name specification
(-pMYAPP) may be omitted if you have set the environment variable
PROJECT correctly.

Another task, mainly performed by project administrators, will be to
have a look at the current activity on a project. The command 'SACT'
(System activity report) lists all modules in a project and their
current state. If a file is currently checked out, it also notes who
owns it and at what time he checked it out. Please refer to chapter
III. for more information about this command.



III. Reference

1. AVTSDIFF - Compare to versions of an AVTS file

Synopsis

avtsdiff [-pproject] -oversion1 -nversion2 file

Description

The command avtsdiff compares the two versions of file as
specified on the commandline by the parameters -o and -n by
using the diff command on them. The output is printed to
stdout and can be re-directed to a file or a printer. You can
not use avtsdiff on binary files, such as executables, bit-
maps of database files. In such a case avtsdiff informs you
about being unable to perform on binary files. The optional
parameter -p with the project specification can be ommited,
if the environment variable PROJECT is set.

Options

-pproject Specifies the name of the project. This
option can be omitted if the environment
variable PROJECT is set. However,
specifying a project's name with the -p
flag overrides the contents of the
environment variable.

-oversion1 Specifies a version of the file you want to
compare with another version. Version1 has
to be specified as a version number like
7.2 or 8.11

-nversion2 Specifies a version of the file you want to
compare with another version. Version2 has
to be specified as a version number like
7.2 or 8.11

2. AVTSGREP - Search project files for patterns

Synopsis

avtsgrep [-cilnsv] [-pproject] pattern file(s) [...]

Description

The command avtsgrep searches the current versions of all
files in a project that match the specified file parameter
for patterns, which are regular expressions in the style of
the common known grep command. The project specification can
be ommited, if the environment variable PROJECT is set
correctly. You may specify one or more file parameters, which
may also contain wildcard expressions (i.e. *.C).

The following rules are valid for avtsgrep :

- A regular expression followed by a plus sign (+)
matches one ore more occurences of the regular
expression.

- A regular expression followed by an asterisk (*)
matches zero or more occurences of the regular
expression.

- The characters ^,$,[ and ] have special meanings
to grep and must be escaped if you want them to be
used literally.

- The character ^ matches the beginning of a line
and $ (the dollar sign) matches the end of a line.
The character ^ has a different meaning if used
within a range specification (described later).

- The dot (.) matches any single character

Avtsgrep displays the name of the file containing the matched
line as well as the actual version number of this file. When
pattern is not a simple string, you usally must enclose the
entire pattern in double quotion marks. In an expression such
as [a-z], the minus means "through".

The exit values match the following specifications:

0 A match was found.
1 No match was found.
2 A syntax error was found or a file was inaccessible
(even if matches were found).

Notes:

1. Lines are limited to 512 characters; longer lines
are broken into multiple lines of 512 or fewer
characters.

2. Running grep on a special file produces unpredictable
results and is discouraged.

Options

-c Displays only a count of matching lines.

-i Makes no distinction between uppercase and
lowercase characters when making comparisons.

-l List just the names if files (once) with
matching lines. Each file name is separated
by a new-line-character.

-n Precedes each line with its relative line
number in the file.

-pproject Specifies the name of the project. This
option can be omitted if the environment
variable PROJECT is set. However,
specifying a project's name with the -p
flag overrides the contents of the
environment variable.

-s Suppresses error messages about
inaccessible files.

-v Displays all lines except those that match
the specified pattern.


Examples

1. To count the number of lines that match a pattern:

avtsgrep -c -pMYPRJ { pgm.c
avtsgrep -c -pMYPRJ } pgm.c

This displays the number of lines of pgm.c in
project MYPRJ that contain open and close braces.

If you do not put more than one { or } on a line in
your C programs, and if the braces are properly
balanced, the two numbers displayed will be the same.

2. To use patterns that contains some of the pattern-
matching characters *,^,+,[,] and . in an
avtsgrep command:

avtsgrep ^[a-zA-Z] -pMYPRJ pgm.s

This displays all lines of pgm.s in project MYPRJ
that begin with a letter.

3. To display all lines that do not match a pattern:

avtsgrep -v -pMYPRJ ^#

This displays all lines that do not begin with a #
character.

4. To display the names of files that contain a pattern:

avtsgrep -l -pMYPRJ strcpy *.c

This searches all files in the project MYPRJ that
end with .c and displays the names of those files
that contain the string strcpy.


3. CDC - Change Delta Comment

Synopsis

cdc [-uusername] [-vx.y] [-pproject] file [...]

Description

The command cdc allows changing of the comment given to a
specific version of a file in an AVTS project. The optional
parameters username and project can be omitted if the corres-
ponding environment variables USERNAME and PROJECT are set
correctly. You may specify more than one file and each file
specifier may contain wildcard characters.

Options

-uusername Specifies the name of the user. This option
can be omitted if the environment variable
USERNAME is set. However, specifying a user's
name with the -u flag overrides the contents
of the environment variable.

-vx.y This flag specifies the version of the delta
for which you want to change the comment. If
omitted the actual version is used.

-pproject Specifies the name of the project. This
option can be omitted if the environment
variable PROJECT is set. However, specifying
a project's name with the -p flag overrides
the contents of the environment variable.

Examples

1. To change the delta comment of the current version of
file MYAPP.C in the project MYAPP:

cdc MYAPP MYAPP.C

This shows you the current contents of the comment
and prompts you for the new comment in the following
form:

ARIS Version Tracking System 1.2
(c) 1992,1993 All rights reserved
File MYAPP.C, created Sun Dec 13 21:56:35 1992
Version 1.2, derived from version 1.1
Comment: Debugging in progress...
New comment:

2. To change the comment of a specific version of
MYAPP.C:

cdc -v1.2 MYAPP MYAPP.C


4. CREATE - Creates projects and apply files to them.

Synopsis


create [-uuser] [-ttype] [-pproject] file [...]

Description

The command create allows creation of a new project and/or
adding files to a project. If there is no file specified with
the -f flag the project is created. However, if you add a
file with the -f flag to a non-existant project, the project
is created automatically. The parameter -uuser can be omitted
if the environment variable USERNAME is set correctly. You
may specify more than one file and each file specifier may
contain wildcard characters.


Options

-uuser Specifies the name of the user. This option
can be omitted if the environment variable
USERNAME is set. However, specifying a user's
name with the -u flag overrides the contents
of the environment variable.

-ttype Specifies the type of a new file. Legal
values are 0 (null) for ASCII files and 1
(one) for binary files. If this option is
omitted the default value 0 (null) will be
used.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.


Examples:

1. To create a new project NEWPRO:

create -pNEWPRO

2. To add the source file MYAPP.C to the project NEWPRO:

create -pNEWPRO MYAPP.C

3. To add the binary file MYAPP.DBF to the project
NEWPRO

create -t1 -pNEWPRO MYAPP.DBF


5. DELTA - Creates a new version (delta) of a file in an AVTS
project.

Synopsis

delta [-uusername] [-f] [-d] [-pproject] file [...]

Description

The delta command creates a new version of file. The file
must have been checked out with the command get by the same
user. Otherwise you will get an error message that either the
file has not been checked out or has been checked out by an-
other user. See appendix A for a list of error messages.
You will be prompted for a comment on the changes. The maxi-
mum length of the comment string is 127 characters. You may
specify more than one file and each file specifier may con-
tain wildcard characters.
After recording all changes to the specified file(s), delta
deletes each specified file unless the -d flag is present.

Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-f This flag forces a new version of all
specified files into an AVTS project
even if those files have not been
checked out. This flag does not al-
low to create a new version of a file
that is currently checked out by an-
other user.

-d With this flag present, delta sets the read-
only attribute of the specified file(s)
rather than deleting them.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.

Example

To create a new version of MYAPP.C in the project MYAPP:

delta -pMYAPP MYAPP.C


6. DIFF - Compares two files and creates a difference listing

Synopsis

diff [-s] [-mnum] oldfile newfile

Description

The command diff is a program that is used by the delta
command to create a difference listing when a new version of
an ASCII file is applied to a project. You may however, also
use this command to create difference listings for your own
use.
From the output of the diff command you can see what changes
must be made in oldfile to get newfile. The output has the
following form:

n1,n2d delete lines n1 to n2 from file oldfile.

n1,n2cm1,m2 Replace the lines n1 to n2 in file oldfile by
the lines m1 to m2 from file newfile.

n1am1,m2 Insert lines m1 to m2 from file newfile in
file oldfile after line n1.


Options

-s Creates a script which can be used to convert oldfile
to newfile.

-mnum num specifies how many subsequent lines have to be
equal to synchronise.


7. GET - Copies a project file and locks it

Synopsis

get [-uusername] [-pproject] file [...]

Description

The command get copies a file from a project to the current
working directory and locks it in the project. Therefore an-
other user cannot "get" this file until it is checked in by
the command delta or the lock is removed by the command unget.
Other users may obtain a copy of a locked module by using the
command read. The optional parameters username and project
name can be omitted if the corresponding environment
variables USERNAME and PROJECT are set correctly. You may
specify more than one file and each file specifier may
contain wildcard characters.


Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.


-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.


8. HISTORY - Prints the revision history of a file in an AVTS
project

Synopsis

history [-uusername] [-vx.y] [-pproject] file [...]

Description

The command history prints out all activities that occured on
file from the initial creation to the current version or, if
supplied, to the version specified with the -v parameter. The
optional parameters username and projectname can be omitted
if the corresponding environment variables USER NAME and PRO-
JECT are set correctly. You may specify more than one file
and each file specifier may contain wildcard characters.


Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-vx.y This flag specifies the version of the
module where the printout of the
history should stop. If omitted the
actual version is used.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.

Examples

1. List the revision history of MYAPP.C in project MYAPP:

history -pMYAPP MYAPP.C

2. View the revision history of MYAPP.C page by page:

history -pMYAPP MYAPP.C | more

3. Print the history of MYAPP.C up to version 2.5 on a

parallel printer:

history -v2.5 -pMYAPP MYAPP.C >prn


9. LOGVIEW - View the contents of a project's logfile

Synopsis

logview project

Description

The utility logview allows you to easily browse through the
log file of the specified project. The parameter project can
be omitted if the environment variable PROJECT is set to the
correct value.


10. READ - Copies a project file without locking

Synopsis

read [-i] [-uuser] [[-vx.y]|[-aalias]] [-pproject] file [...]

Description

The command read copies the specified file(s) from project to
the current working directory. The retrieved module is not
locked and therefore still available for other users. If you
specify 'all' instead of a file's name all files in the pro-
ject are copied. If no version is specified with the -v flag,
the current version is used. The optional parameters user and
project can be omitted if the corresponding environment
variables USERNAME and PROJECT are set correctly. You may
specify more than one file and each file specifier may
contain wildcard characters. Each occurance of a macro ex-
pression is replaced by its corresponding value unless the -i
flag is used.

Options

-i Ignore macros.

-uuser Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-vx.y This flag specifies the version of the
module which should be retrieved.
If omitted the actual version is
used. This option is not allowed in
combination with the -a flag.

-aalias This copies the version that has the
given alias name. If there is no such
version you will get an error mes-
sage.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.



Macros

Each of the following macro expressions is replaced by its
corresponding value.

Macro Replaced by
==============================================
%M% Module name
%I% %R%.%L%
%R% Release
%L% Level
%D% Current date (YY/MM/DD)
%H% Current date (MM/DD/YY)
%T% Current time (HH:MM:SS)
%E% Date of extracted delta (YY/MM/DD)
%G% Date of extracted delta (MM/DD/YY)
%U% Time of extracted delta (HH:MM:SS)
%Y% Module type
%F% AVTS file name
%P% Full path name of project
%C% Current line number
%Z% 4 character string @(#) recognized by
the what command
%W% %Z%%M% (tab)%I%
%A% %Z%%Y% %M% %I%%Z%


Examples

1. Read the file MYFILE.C from project MYAPP:

read -pMYAPP MYFILE.C

2. Read version 1.5 of MYFILE.C from project MYAPP:

read -v1.5 -pMYAPP MYFILE.C

3. Read all file from project MYAPP that belong to
"Beta Version 1.0":

read "-aBeta Version 1.0" -pMYAPP all

Please note that the quotation marks are necessary because
the alias name contains space characters.



11. RMALIAS - Removes an alias name from a specific version of a
module

Synopsis

rmalias [-uusername] -aalias [-pproject] file [...]

Description

The command rmalias removes an alias name from the module
specified by file. If 'all' is specified instead of a file-
name, the alias name is removed from all modules in the
specified project. The optional parameters username and pro-
ject can be omitted if the corresponding environment
variables USERNAME and PROJECT are set correctly.
You may specify more than one file and each file specifier
may contain wildcard characters.


Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-aalias This specifies the alias name that
should be removed. If there is no
such alias you will get an error
message.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.

Examples

1. Remove the alias "BETA" from module MYFILE.C in
project MYAPP:

rmalias -aBETA -pMYAPP MYFILE.C

2. Remove the alias "BETA" from all files in project
MYAPP:

rmalias -aBETA -pMYAPP all


12. RMAVTS - Deletes a file from an AVTS project

Synopsis

rmavts [-uusername] [-pproject] file [...]

Description

The command rmavts deletes all specified files from the pro-
ject either specified with the -p flag or the project
specified by the environment variable PROJECT. The optional
parameter username may be omitted if the environment variable
USER is set correctly. Please note that rmavts does not allow
deleting a file which is currently checked out. There may be
one or more file specifiers on the command line, where each
allows usage of wildcard characters.

Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.



-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.


13. SACT - Reports current editing activity in an AVTS project

Synopsis

sact [-uusername] [-l] project

Description

The command sact prints out for each file in project whether
it is currently checked out and by whom or not. The optional
parameter username can be omitted if the corresponding en-
vironment variable USERNAME is set correctly.

Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-l If specified, sact will only display
those files, that are currently locked
in the project. Unlocked files will
not appear in the list.


14. SETALIAS - Sets the alias name for one or more modules

Synopsis

setalias [-uuser] [-vx.y] -aalias [-pproject] file [...]

Description

The command setalias sets an alias name for the specified
file. If 'all' is given instead of a filename, all files in
the specified project will get this alias name. If there is
no version specified with the -v flag, the current version of
file will be used. If you have already tagged another version
of the specified module with the same alias name you will
get a warning and nothing will happen. If the specified ver-
sion of a module has already another alias name you will also
get a warning message and the alias name will be overwritten
with the new one you specified with the -a flag. The optional
parameters user and project can be omitted if the correspond-
ing environment variables USERNAME and PROJECT are set
correctly. You may specify more than one file and each file
specifier may contain wildcard characters.

Options

-uuser Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-vx.y Specifies the version of the module
which should get an alias name.

-aalias Specifies the alias name which
should be used for the file. Maxi-
mum length is 78 characters.


-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.

Example

Tag the current versions of all file in project MYAPP with
the alias name "BETA":

setalias -aBETA -pMYAPP all


15. UNDIFF - Applies a diff script to a file

Synopsis

undiff oldfile newfile diffscript

Description

The command undiff uses a script generated by the command
diff to convert one file to another. Note that the diff
script must have been produced by using the switch -s (See
DIFF on page 17 for further details).
This command is not used by any other AVTS command. It is
just added for your convenience, to enable usage of the diff
command for other purposes beside version tracking as well.


16. UNGET - Reverses a GET command without creating a new version

Synopsis

unget [-uusername] [-pproject] [-d] file [...]

Description

The command unget unlocks a file previously locked with the
get command. Any changes on a file are ignored and the ver-
sion counter is not increased. The optional parameters user-
name and project can be omitted if the corresponding envi-
ronment variables USERNAME and PROJECT are set correctly. You
may specify more than one file and each file specifier may
contain wildcard characters. After the lock has been removed,
unget deletes the file, unless the -d flag is present.


Options

-uusername Specifies the name of the user. This
option can be omitted if the envi-
ronment variable USERNAME is
set. However, specifying a user's
name with the -u flag overrides the
contents of the environment vari-
able.

-pproject Specifies the name of the project.
This option can be omitted if the
environment variable PROJECT is
set. However, specifying a project's
name with the -p flag overrides the
contents of the environment vari-
able.

-d With this flag present, unget sets the
read-only attribute to each specified
file rather than deleting it.

17. WHAT - Extracts identifying strings from program files

Synopsis

what [-s] file ...

Description

The what command searches the named files for all occurrences
of the pattern that read substitutes for the %Z% keyletter
(See "Macros" on page 21). By convention, the value substi-
tuted is @(#).
what writes to standard output whatever follows the pattern
up to but not including the first double quotation mark ("),
greater than symbol (>), new-line character, backslash (\),
or null character.
You may specify more than one file and each file specifier
may contain wildcard characters.
The what command is intended for use in conjunction with the
read command, which automatically inserts the identifying in-
formation, provided that the %Z% keyletter is used in the
file. You can also use the what on files where the infor-
mation is inserted manually.

Flags

-s Searches only the first occurrence of @(#).



Examples

Suppose that the file test.c contains a C program
that includes the line:

char ident[] = "@(#)Test Program";

If you compile test.c to produce test.obj and
test.exe, the command:

what test.c test.obj test.exe

displays:

test.c:
Test Program
test.obj:
Test Program
test.exe:
Test program



IV. APPENDIX A - ERROR MESSAGES

Delta was created by another user, access denied

You tried to change the delta comment of a version that was
created by another user. Use the history command to obtain
information about this module and contact the user who
created this module.

File filename already in project projectname

You tried to introduce a file to a project that is already
in that project with the create command.

File name already in use

You tried to do an action on a file that is currently checked
out. For further information use the command sact that pro-
vides useage information for each file in a project.

File name already in use by user username

The specified file is currently checked out by another user.
You cannot complete the desired action until this user checks
the file in again.

File name checked out by username, access denied

You tried to modify the information of a file that is
currently checked out by another user.

File name is not checked out

You tried to create a delta on a file that is not checked out.
If you modified a file you obtained with the read command
this error can be overcome by doing the following actions:

- rename the file you want to check in (file.BAK).
- Use the get command to lock the desired file on your
user-id.
- rename the file back to its original name.
- use the delta command.

Note that it is recommended to check the project log file
first if to ensure that no other user made modifications to
that file in the meantime.

File name is not checked out, cannot unget

You tried to use the unget command for a file that is not
checked out.

File name not in project

You specified a file for an AVTS command that is not found in
the project specified. Check the environment variable PROJECT
and the spelling of the issued command.

Internal failure, not found name

Please contact ARIS support immediately if this error occurs.

Missing argument

A required argument, such as file- or projectname have not
been specified. Check the typing of the issued command.

Missing file name

You did not specify a filename where it was required.

Missing project name

You did not specify a project name where it was required.

Project name already exists

You tried to create a new project with the create command
that already exists. Use another name.

Projects is locked, access denied

An AVTS command was not able to lock the project directory
file after ten attempts. This may be caused by heavy use of
the system. Repeat your command and contact your network
administrator if it occurs again.

Unable to create name

An AVTS command was unable to create the file specified by
name. This might be caused by several reasons:

1. Your disk has no more free space
2. Your disk is write protected
3. The file specified by name already exists
and has a read-only or a system attribute.
4. On a network drive you may have no write
access to the current directory, contact
your system administrator for further in-
formation.

Unable to create file name

See above message for explanation.

Unable to open input file name

The file you specified cannot be opened. This may either be
caused by a misspelling or insufficient access rights in a
network environment.

Unable to open RCS.DAT

If this happens on a newly created project, you have not yet
added files to the project. Therefore no project directory
exists. If you where able to access the project before, your
disk may have been corrupted. Check the file system and use
your backup to restore the project.

Username unknown

There is no username specified. You must either use the -u
command line switch or the environment variable USERNAME to
specify a name.
V. APPENDIX B - ENVIRONMENT

USERNAME With this environment variable you can specify a
username, that will be used by all AVTS commands, so
that you do not have to specify the username for each
command by the -u flag. However, if you specify a
username with the -u flag, the contents of the en-
vironment variable USERNAME will be overridden.
To set the environment variable to a specific name,
use the DOS command SET as shown below:

SET USERNAME=MYNAME

PROJECT By setting the environment variable PROJECT to an
existing AVTS project, you do not have to specify the
name of the project for each AVTS command, unless you
want to work on a project other than the specified.
The example below set the environment variable
PROJECT to TEST.

SET PROJECT=TEST


The following command now obtains a copy of the file
MYAPP.C from the project TEST:

READ MYAPP.C

The next command copies and locks the file FOO.C from
a different project. Note that the contents of the
environment variable PROJECT needs not to be changed:

GET -pFOOPRO FOO.C

AVTSDIR This environment variable allows you to change the
default directory, where AVTS creates and maintains
projects. The default directory for projects is the
directory where the AVTS executable files reside. In
order to change the default directory, set the en-
vironment variable AVTSDIR to the directory where you
want your projects to reside. This procedure is
especially useful when working on a network, where
you want to have the AVTS commands on your local
harddisk and the projects are on a network drive.