.; Template for Reports, Papers, etc.
.; =================================
.ps 60,71
.autoparagraph
.subtitle
.date
.flags substitute
.flags underline
.flags bold
.;____________________________________________________
.s4
.c;The AIPS Code Checkout System
.title Code Checkout System
.s2
.c;Gary Fickling
.s1
.c;National Radio Astronomy Observatory
.c;Edgemont Road, Charlottesville, VA 22901
.c;(804)296-0211, FTS=938-1271
.s1
.;___________________
.; set date 06 02 1984
.;^^^^^^^^^^^^^^^^^^^
.c;DRAFT, at $$time $$day $$month $$year
.c;{Source in DOCTXT:CHKOUT.RNO}
.c;{Print copies with: Print/Queue=TTA0 DOCTXT:CHKOUT.MEM}
 
.s3
.c;Abstract
.lm+7.rm-7
A code checkout system has been implemented on CVAX for the AIPS
programming project.  This memorandum describes the commands and
procedures that are necessary for using this system.
.lm-7.rm+7
 
.s3
.c;Table of Contents
.s2
.require "chkout.rnt"
 
.tp20
.hl1 ^*General Principles\*
 
This is a simple system designed to be convenient and to cause a
minimum amount of disruption to the current ways of doing things,
rather than an air tight system that could not be circumvented by a
malicious user.
 
The source code directories are write protected to all users except
those with the SYSPRV privilege and to the VPOPS account.  Read
access is allowed for all users, since checking calling sequences or
the source of error messages is a common occurrence. Checking out,
putting back, deleting or adding code, is done through programs that
are installed with SYSPRV privilege.  These routines look like
standard DCL commands. For example, someone could checkout code with
the command:
.s1
.c;_$ CHKOUT APLPGM:IMEAN.FOR
.s1
In all of the commands, the directory, device, etc. of the file can be
specified in any way, including the use of defaults and logical
names.  Wild cards are not permitted.  The commands that copy files
will copy them from (or to) the current default area, to (or from) an
AIPS area specified as part of the file__name parameter.  In the
CHKOUT example shown above, IMEAN.FOR will be copied from APLPGM: to
the current default.
 
The commands will prompt for the file name if it is omitted just like
a DCL command.
 
This system maintains two lists.  One contains a list of files that
are currently checked out, and the other, which is updated on put
back, contains a history of files that have been checked out along
with the check out and check in dates, reason, and the process that
checked the code out.
 
.tp20.hl1 ^*Routines\*
 
.tp15.hl2 ^*_$ CHKOUT file__name\*
 
This command allows a user to check out code. The routine
.lm+1.ls
.le;Makes sure the current process is in a list of processes allowed
to check out code.  This insures that programmers do not check out
code from AIPS or some other general use login.
.le;Prompts for
"Reason", that is, the reason for checkout.  This reason can be 80
characters (one line) long.  A carriage return can be entered
instead of a reason.
.le;Checks to make sure that the code is not currently checked out. If
it has been checked out, the routine prints the
name of the owner, date, and reason for check out.
.le;If all is ok, the program updates the checked out list and
copies the code to the current default area.
.els.lm-1
 
.tp15.hl2 ^*_$ PUTBCK output__file__name\*
 
This command allows a user to check in code that has been checked out,
or to install new code. The routine
.lm+1.ls
.le;Verifies that the file has been properly checked out by a process
with the current process ID or else that the file does not
currently exist in the output area.
.le;If the programmer tries to check a file into an directory that is
different from the check out directory, then a
warning is printed and the programmer is given a chance to abort.
If the programmer wants to continue, the old file is renamed to
*.OLD.
.le;If all goes well thus far, the file in the current default
directory is copied to the area given by the output__file__name
removing any SOS line numbers.
.le;If the checked out list contained an entry for this file, the
entry is removed.
.els.lm-1
 
.tp15.hl2 ^*_$ REMOVE file__name\*
 
This command allows a user to delete ALL versions of a file from a protected
directory. The routine
.lm+1.ls
.le;Verifies that the file is not checked out.
.le;Deletes all versions of the file.
.le;Puts an entry into the history file.
.els.lm-1
 
.tp15.hl2 ^*_$ FORGET file__name\*
 
This command allows a user to delete an entry from the list of
checked out files.  This is useful when a programmer checks out a
routine and then changes his mind.  The routine
.lm+1.ls
.le;Verifies that the current process has the file checked out.
.le;Removes it from the checked out list.
.els.lm-1
 
.tp15.hl2 ^*_$ NAMCHK file__name\*
 
This command allows a user to reserve a name for a new program that
is being developed.  The user should enter the full file name
including the directory (logical names are permitted). The routine
.lm+1.ls
.le;Checks to make sure the file does not exist in the given
        directory.
.le;Makes sure the file is not checked out from any directory.
.le;Puts an entry into the list of programs checked out.
.le;Puts a dummy file in the directory specified by file__name.
.els.lm-1
.NOTE
This routine does not search all directories for the
file name.  The user must make sure that the name is
not used by a file in another AIPS directory.
.EN
.tp15.hl2 ^*_$ CPURGE file__name__or__wildcard\*
 
This command works just like the DCL purge, except that the command
can purge files in the protected checkout directories.
 
.tp15.hl2 ^*_$ OUTPRT\*
 
This command prints the list of files that are currently checked
out. The routine
.lm+1.ls
.le;prompts the user for options such as 80 or 132
column output (the 80 column output truncates the reason for
checkout), and the output device, i.e. the CRT, a disk file, or the
printer.  Defaults can be chosen by pressing a carriage return.  The
user gets an 80 column report on the CRT by choosing all defaults.
.els.lm-1
.tp15.hl2 ^*_$ HISPRT\*

This command will print the check out history.  The routine
.lm+1.ls
.le;prompts the
user for options such as 80 or 132 column output, the output device,
the range of check in dates, and the name of the file that was
checked in.  By choosing all defaults (pressing carriage return for
all prompts), the user gets a report of 80 columns for all dates and
all files on the CRT.  When selecting entries for one specific file
DO NOT enter a device and directory name.  Enter only the file name
and extension.
.els.lm-1

.tp20.hl1 ^*An example\*
To check out code, a user needs to have an account on CVAX node, and
needs to be in a list of authorized users.  If you lack either of these,
contact the Vax system manager in Charlottesville.

Suppose a user wishes to make an entry into the CHANGE.DOC file.  First,
the user logs on to his own area on the CVAX node.  This requires, of course,
that users on other nodes SET HOST to the CVAX node. The user then does a
SET DEFAULT to get to the directory where CHANGE.DOC is to be kept while
it is checked out.  For example, a user who wants to use a subdirectory
that he owns called SCRATCH should execute the command
.s1
.c;_$ SET DEF [.SCRATCH]
.s1
  A user in the AIPS group (group UIC of 100) or the VLB group (group UIC
of 300) may want to
access the AIPS directories through the logical names listed in Appendix A.
To set these logical names, use the command
.s1
.c;_$ @NEW:ASSIGNP
.s1

Next, check out the file with the command
.s1
.c;_$ CHKOUT HST:CHANGE.DOC
.s1
CHKOUT will prompt for the reason.  Reasons are limited to one line.
An example is
.s1
.c;Reason  To describe changes to IMEAN.
.s1
CHKOUT will then copy CHANGE.DOC from the AIPS history directory to
the current default directory.  The user can edit this copy of
CHANGE.DOC using any text editor.  To put this copy back in the
proper directory the user issues the command
.s1
.c;_$ PUTBCK HST:CHANGE.DOC
.s1
.appendix logical names for the AIPS directory structure.

   Procedure ASSIGNP can be used to create a set of logical names
that can be used to access the AIPS directory structure.  This procedure
constructs the names for the current directory structure based on the
logical name NEW.  NEW must be assigned to UMA0:[AIPS.latest__date]
where latest__date is the latest release date, such as 15JAN84.
If you are in the AIPS group (group UIC of 100) or the VLB group
(group UIC of 300) logical name NEW will automatically be assigned
to the correct directory.  Otherwise, you may have to execute the command
.s1
.c;_$ ASSIGN UMA0:[AIPS.latest__date]  NEW
.s1
After NEW is assigned properly, the rest of the logical names can be
created with the command
.s1
.c;_$ @NEW:ASSIGNP
.s1

.lt

DIRECTORY                           LOGICAL NAME

UMA0:[AIPS.new.LOAD]                LOAD
UMA0:[AIPS.new.APL]                 APL
UMA0:[AIPS.new.AIPS]                POPS
UMA0:[AIPS.new.NOTST]               NOTST
UMA0:[AIPS.new.FPS]                 FPSFIL
UMA0:[AIPS.new.PSAP]                PSAP
UMA0:[AIPS.new.ICAP]                ICAP
UMA0:[AIPS.new.INC]                 INCS
UMA0:[AIPS.new.HELP]                HLPFIL
UMA0:[AIPS.new.HIST]                HST
UMA0:[AIPS.new.DOC]                 DOC
UMA0:[AIPS.new.DOC.WHO]             DOCWHO
UMA0:[AIPS.new.DOC.TEXT]            DOCTXT
UMA0:[AIPS.new.DOC.GRIP]            DOCGRIP
UMA0:[AIPS.new.DOC.PUBL]            DOCPUBL
UMA0:[AIPS.new.AIPS.SUB]            AIPSUB
UMA0:[AIPS.new.AIPS.PGM]            AIPPGM
UMA0:[AIPS.new.AIPS.ZSUB.VMS]       AIPVMS
UMA0:[AIPS.new.AIPS.ZSUB.MC4]       AIPMC4
UMA0:[AIPS.new.AIPS.YSUB.IIS]       AIPIIS
UMA0:[AIPS.new.APL.SUB]             APLSUB
UMA0:[AIPS.new.APL.PGM]             APLPGM
UMA0:[AIPS.new.APL.APGM]            APLAPG
UMA0:[AIPS.new.APL.ZSUB.VMS]        APLVMS
UMA0:[AIPS.new.APL.ZSUB.MC4]        APLMC4
UMA0:[AIPS.new.APL.YSUB.IIS]        APLIIS
UMA0:[AIPS.new.NOTST.SUB]           NOTSUB
UMA0:[AIPS.new.NOTST.PGM]           NOTPGM
UMA0:[AIPS.new.NOTST.APGM]          NOTAPG
UMA0:[AIPS.new.FPS.SUB]             FPSSUB
UMA0:[AIPS.new.FPS.ZSUB.VMS]        FPSVMS
UMA0:[AIPS.new.FPS.ZSUB.MC4]        FPSMC4
UMA0:[AIPS.new.PSAP.SUB]            SAPSUB
UMA0:[AIPS.new.PSAP.ZSUB.VMS]       SAPVMS
UMA0:[AIPS.new.PSAP.ZSUB.MC4]       SAPMC4
UMA0:[AIPS.new.ICAP.SUB]            CAPSUB
.el
.appendix compilation command procedures.

  If you have executed command procedure NEW:ASSIGNP as described in
Appendix A and have set the default directory to NEW, then the
following command procedures can be used to compile
and link programs or compile subroutines and insert them into the
proper library.
.lt

COMMAND PROCEDURE   SUBROUTINE IS IN DIR                  SOURCE

ACOMRPL             [AIPS.new.AIPS.(SUB or ZSUB.VMS)]     FORTRAN
AASMRPL             [AIPS.new.AIPS.ZSUB.VMS]              MACRO
COMRPL              [AIPS.new.APL.(SUB or ZSUB.VMS)]      FORTRAN
ASMRPL              [AIPS.new.APL.(SUB or ZSUB.VMS)]      MACRO
FCOMRPL             [AIPS.new.FPS.SUB]                    FORTRAN
ICOMRPL             [AIPS.new.ICAP.SUB]                   FORTRAN
NCOMRPL             [AIPS.new.NOTST.SUB]                  FORTRAN
NASMRPL             [AIPS.new.NOTST.SUB]                  MACRO
PCOMRPL             [AIPS.new.PSAP.SUB]                   FORTRAN
.el
   When a subdirectory portion of a directory can be SUB or
ZSUB.VMS, a procedure looks at the first letter of the program
name.  A 'Z' indicates the subroutine is found in ZSUB.VMS.

   A procedure may be invoked by typing
.s1
.c;_$ @procedure__name  subroutine__name   option
.s1
   Three options concerning listings are available.  The default is
no listing, a short listing is specified by LIST and a cross reference
listing is specified by CROSS.

   For example to compile and insert into a library, subroutine
CTICS.FOR found in [AIPS.new.APL.SUB] and produce a short listing type
the command
.s1
.c;_$ @COMRPL CTICS LIST
.s1
   Other command procedures exist to compile programs.  The three
listing options are available (default (none), LIST and CROSS) plus
a MAP option and a DEBUG option.  The command procedures used with the
AP programs (APCLNK and NAPCLNK) also have the options NOPSAP for
skipping the link with the pseudo array processor code and NOFPS for
skipping the link with the FPS array processor code. The options are
placed after the program name and can occur in any order.  For example
to compile and link with the debugger program PRTPL.FOR found in
[AIPS.new.APL.PGM] and get a cross reference listing type the command
.s1
.c;_$ @COMLNK PRTPL CROSS DEBUG  or @COMLNK PRTPL DEBUG CROSS
.lt

The command procedures for linking are:

COMMAND PROCEDURE      PROGRAM IS IN DIRECTORY

ACOMLNK                [AIPS.new.AIPS.PGM]
COMLNK                 [AIPS.new.APL.PGM]
NCOMLNK                [AIPS.new.NOTST.PGM]
APCLNK                 [AIPS.new.APL.APGM]
NAPCLNK                [AIPS.new.NOTST.APGM]
.el
