.!+++
.!
.! FACILITY:
.!	OAK RIDGE NATIONAL LABORATORY
.!	FUSION ENERGY DIVISION
.!	TOKAMAK SECTION
.!
.! ABSTRACT
.!	ORNL VAX CAMAC System Manager's Manual.
.!
.! AUTHOR
.!	E.T. Blair
.!
.! REVISION HISTORY 
.!	V00-000, E.T. Blair, 5-JAN-1983.
.!	Development started.
.!
.!---
.set date
.fl substitute @
.sthl 6,0,6,7,7,2,1,7,2
.ts 10,18,26,34,42,50
.nj
.ap
.lm 10
.rm 70
.ps 60,80
.s 12
.c
System Manager's Reference Manual
.c
for the ORNL VAX CAMAC System
.s 10
.c
By E.T. Blair
.s 5
.c
Published @@month @@day, @@year
.pg
.ch Introduction
 This document provides information required to install the ORNL VAX CAMAC
system. It does not attempt to explain or demonstrate the use of the system. 
Such information may be found in the "ORNL VAX CAMAC System User's Manual".
 Chapter two provides a brief description of the various source files
comprising the VAX CAMAC system. Chapter three describes the use of a number
of DCL command procedures that are included in the distribution. Chapter 4
describes the CAMAC Topology Supervisor utility program.
.ch VAX CAMAC System Source Files- An Overwiew
 The VAX CAMAC system distribution includes the following source files. Each
file is briefly described. Any special instructions relative to particluar
files are also provided. The files are partitioned into groups according
to the following categories:
.ls
.le
VMS System Level Software,
.le
CAMAC User Interface Software,
.le
VAX CAMAC System Documentation.
.els
 Note that the CAMAC source level system generation
performed by 'CAMGEN.COM' uses all of the files described in this chapter.
For more information on 'CAMGEN.COM' consult the next chapter.
.hl 1 VMS System Level Software
.s
.ls
.le
CAMDEF.MAR
.b
CAMAC MACRO library source file. Contains MACRO definitions for pertinent
data structures and symbolic constants utilized by the CAMAC device driver,
ACP, access procedures and support programs such as the ACP mount and
dismount images. Also, contains a number of code generation MACRO definitions
utilized by these same sources. The command procedure 'CAMGEN.COM' creates
and/or updates the CAMAC MACRO library file 'CAMDEF.MLB' using this 
file each time a source level generation is performed.
.le
KSDRIVER.MAR
.b
VMS device driver source code for Kinetic Systems 2050 series CAMAC
highway driver. Contains conditional assembly to allow both 2050 and 2051
device drivers to be generated from the same source code file. Switch
'KS_X_SH' controls serial(2050) compatible device driver object generation
and switch 'KS_X_PH' controls parallel(2051) compatible object generation.
Use DCL command file 'KSDRIVER.COM' to assemble and link the desired device
driver loadable image file. The loadable image 'SHDRIVER.EXE' is produced
for the serial highway(SH) and 'PHDRIVER.EXE' is produced for the parallel
highway.
.le
KSCAMACP.MAR
.b
VMS Ancillary Control Process(ACP) for the VAX CAMAC system. The CAMAC ACP
implements support for several high-level crate control functions and provides
LAM management support for application programs by allowing the application
program to request an AST in the event a LAM is asserted for a given crate and
station address on the CAMAC highway. The source file contains conditional 
assembly to allow both serial and parallel ACP object modules to be generated
from a common source file. Switch 'KS_X_SH' controls serial code generation and
'KS_X_PH' controls parallel code generation. The device driver to ACP interface
is designed in such a manner that only unit 0 for a particular CAMAC highway
can(or need) be mounted. All QIO requests are first handled by the device
driver which determines if ACP intervention is required and if so the QIO
request is passed on to the ACP. Only a few function codes require such 
interaction. A separate ACP process is required for each CAMAC
controller(KS 2050 series interface), although the pure(non-writeable)
image sections of the ACP image may be shared by using the INSTALL
utility to install the ACP image as 'SHAREABLE' before performing
the first CAMAC ACP mount request. Use DCL command procedure
'KSCAMACP.COM' to assemble and link the desired CAMAC ACP executable image.
The executable image 'SHCAMACP.EXE' is produced for the serial highway(SH)
and 'PHCAMACP.EXE' is produced for the parallel highway(PH). Use 'MCAM.COM'
to mount the CAMAC ACP(invoke the executable image) and 'DCAM.COM' to 
dismount the CAMAC ACP.
.le
MOUNTCAM.MAR
.b
CAMAC ACP mount image source file. This program establishes the necessary VMS
data structures for the CAMAC ACP creates the process to execute the CAMAC ACP
image for the specified CAMAC highway. The program uses logical names
'MCAM$UNIT' and 'MCAM$IMAGE' to associate the CAMAC controller unit and image 
file to be used for the mount operation. Use DCL command file 'MCAM.COM' to
invoke the CAMAC ACP mount image.
.le
DMOUNTCAM.MAR
.b
CAMAC ACP dismount image source file. This program posts a dismount request to
a CAMAC ACP. The program uses the logical name 'DCAM$UNIT' to determine the
unit to be dismounted. Use 'DCAM.COM' to invoke the dismount image.
.els
.hl 1 CAMAC User Interface Software
 Files described in this section contain source code for various VAX
procedures that allow convenient access to the functionality of the CAMAC device
driver and ACP from high-level languages such as FORTRAN or PASCAL. Detailed
descriptions of the various procedures and examples of their use may be found
in the "ORNL VAX CAMAC System User's Manual". All of the access procedure modules 
are included in an object library produced by 'CAMGEN.COM'. It is named
'CAMLIB.OLB'.
.hl 2 MACRO Source Files.
.s
.ls
.le
CAMCIB.MAR
.b
CAMAC Image Block(CIB) source file. The CIB is a writeable PSECT containing
tables and state variables used by the CAMAC access procedures to retain
information during the execution of an application program that makes CAMAC
access procedure calls. If the access procedures are linked into a shareable
image(and subsequently INSTALL'ed), the image activator gives each image
it's own copy of the CIB PSECT.
.le
CAMBLIB.MAR
.b
Basic CAMAC access procedure source file. Contains entry points for the
commonly used CAMAC access procedures. These procedures provide access to
all of the KS 2050 transfer modes expcept list driver transfers
(see CAMLLIB.MAR).
.le
CAMLLIB.MAR
.b
CAMAC list driven access procedure source file. Contains entry points for the
KS 2050 list mode support procedures. These procedures allow users to build and
execute lists of CAMAC commands.
.le
CAMSLIB.MAR
.b
CAMAC status analysis and display procedures. Contains entry points for
procedures that interpret CAMAC I/O status block(IOSB) information returned
from the device driver and ACP requests.
.le
CAMLAMS.MAR
.b
CAMAC LAM service procedures. Contains entry points for procedures that utilize
the LAM management functions supported by the CAMAC ACP.
.le
CAMTOPS.MAR
.b
CAMAC Topology Supervisor(CTS) support procedures. Contains entry points utilized
by the CTS utility.
.le
CAMSUBS.MAR
.b
CAMAC access procedure support routines. Contains a collection of routines
utilized by the CAMAC access procedures. These are not VAX procedures but
rather have very specialized linkages. These routines are called via 'JSB'
vs. 'CALLS' or 'CALLG'.
.le
CAMIODEF.MAR
.b
CAMAC I/O function codes defined as 'GLOBAL' symbols.
.le
CAMSTATE.MAR
.b
CAMAC CIB state flags defined as 'GLOBAL' symbols.
.els
.hl 2 FORTRAN Source Files.
.s
.ls
.le
CAMSUPORT.FOR
.b
CAMAC Topology Supervisor(CTS) procedures for ACP crate control functions.
These FORTRAN functions are used by the CTS utility to access the crate
control functions offered by the CAMAC ACP.
.le
CAMAC.FOR
.b
General CAMAC call for the "faint of heart". This is a very simple minded CAMAC
access call that requires the absolute minimum of information on behalf of the
caller. It also incorporates a substantial amount of error detection following
the execution of the CAMAC request.
.els
.hl 2 MESSAGE Utility Source Files.
.s
.ls
.le
SHMSG.MSG
.b
CAMAC serial highway message source. Contains source parallel highway
specific messages utilized by the status analysis and display procedures 
in module 'CAMSLIB.MAR'. Use 'MESSGEN.COM' to compile the message source 
file and produce equivalent MACRO definitions and FORTRAN PARAMETER 
statements for the message codes.
.le
PHMSG.MSG
.b
CAMAC parallel highway message source. Contains source for parallel highway
specific messages utilized by the module 'CAMSLIB.MAR'. Use 'MESGEN.COM'
to compile the message source.
.els
.hl 1 VAX CAMAC System Documentation
 Documentation for the VAX CAMAC system can be accessed by the DCL HELP command
or from one of the machine readable reference manuals provided in the
distribution package. The following files constitute the sources for this
documentation.
.ls
.le
CAMAC.HLP
.b
VMS HELP utility source for the VAX CAMAC system. Contains a information
on a number of topics about the CAMAC access calls, what they do, arguments
they require, etc. Other topics, such as CAMAC interface CSR and vector
assignments for serial and/or parallel controllers, instructions for
linking aganist the CAMAC object library and/or shareable images provide 
information that is almost certain to be site dependent. Information associated
with such topics should be modified or else the topics should be deleted
from the HELP source.
.le
CAMUSER.RNO
.b
RUNOFF source for "ORNL VAX CAMAC System User's Manual". Simply use the VMS RUNOFF
utility to format a copy of this document that users can access for printing.
.le
CAMMGR.RNO
.b
RUNOFF source for "System Manager's Reference Manual for the ORNL VAX CAMAC
System".
.els
.ch VAX CAMAC System Command Procedures-What They Do
 This chapter describes the use of a number of DCL command procedures
supplied with the VAX CAMAC system distribution. Some of these procedures
will probably need to be altered for a particular site installation. They
are grouped in the following sections according to an anticipated need for
such modification.
.hl 1 Site Independent Command Procedures.
.s
.ls
.le
CAMGEN.COM
.b
Generates a complete VAX CAMAC system from source files. This command procedure
prompts the user for serial and/or parallel CAMAC support. Having responses to
the prompts, the command procedure assembles and compiles all pertinent CAMAC
source modules, builds the appropriate loadable and executable images and
produces an object library containing the CAMAC access procedures.
.le
KSDRIVER.COM
.b
Conditionally assembles the common VMS device driver source for the KS 2050
series CAMAC interface and produces a loadable VMS device driver image. The
procedure prompts for the desired highway type. Respond 'SH' for a serial
(KS 2050) device driver or 'PH' for a parallel(KS 2051) device driver.
The serial device driver image file will be named 'SHDRIVER.EXE' and the
parallel image file will be named 'PHDRIVER.EXE'.
.le
KSCAMACP.COM
.b
Conditionally assembles the common CAMAC ACP source and produces an executable
ACP image file. The procedure prompts for the desired highway type. Respond
as for 'KSDRIVER.COM'. The serial ACP image will be named 'SHCAMACP.EXE' and the
parallel image will be named 'PHCAMACP.EXE'.
.le
MESSGEN.COM
.b
Compiles a MESSAGE utility source file producing a listing. Two optional
parameters, interpreted as file names, invoke additional command procedures
to scan the message listing file and produce a FORTRAN PARAMETER file and/or
a MACRO definition file with symbolic definitions of the message codes from
the message listing file.
.le
MESSMAR.COM
.b
Scans a MESSAGE utility listing file producing as output a MACRO definition
with symbols equated to the message codes from the listing file. The symbols
are generated in a manner consistent with the message utility standards.
.le
MESSFOR.COM
.b
Scans a MESSAGE utility listing file producing as output FORTRAN PARAMETER
statements with symbols equated to the message codes from the listing file.
The symbols are generated in a manner consistent with the message utility
standards.
.le
SHRCAMLIB.COM
.b
Generates a shareable image from the CAMAC object library.
.le
MCAM.COM
.b
Mounts the CAMAC ACP for a specified CAMAC highway. The procedure accepts
two parameters. The first is required and specifies the CAMAC highway(type and
controller) to be mounted. For example, to mount the ACP for serial highway
controller A, 'SHA' should be specified as P1. To mount the ACP for parallel
highway controller B, 'PHB' should be specified as P1. The second parameter
optionally specifies the name of the ACP image file to be used for this
mount request. The default is 'SYS$SYSTEM:SHCAMACP.EXE' for serial highway
requests and 'SYS$SYSTEM:PHCAMACP.EXE' for parallel highway requests.
.le
DCAM.COM
.b
Dismounts the CAMAC ACP for a specified CAMAC highway. The procedure expects a
parameter specifying the CAMAC highway(type and controller) to be dismounted.
For example, to dismount the ACP for serial highway controller A, 'SHA' should
be specified. To dismount parallel highway controller B, 'PHB' should be 
specified.
.els
.hl 1 Site Dependent Command Procedures
.s
.ls
.le
CAMCONFIG.COM
.b
Generates a SYSGEN configuration command file for a specified CAMAC highway.
The command procedure prompts the user for the highway type(SH/PH), the
controller ID(A,B,C,D,etc.) and the maximum number of units(crates) to be
supported. Then, the user is prompted for the specific crate unit(s) to be
connected. The user responds with decimal digits to select specific CAMAC
crates on the highway for which SYSGEN 'CONNECT' commands are to be
generated. A carriage return to this prompt exits the crate connect loop.
The user is then prompted for execution of the newly generated SYSGEN
command file.
.le
CAMSTART.COM
.b
Command procedure designed to be called from the site dependent 'SYSTARTUP.COM'
procedure to establish CAMAC support for some specified list of CAMAC interfaces.
The list, specified as a parameter, consists of CAMAC highway and controller
names. For example, to establish serial controllers A and B and parallel controller
A, the following command line would be used:
.c
_@CAMSTART	SHA,SHB,PHA
The command procedure invokes a driver loading command procedure and then
mounts the CAMAC ACP for unit 0 of the specified controller.
.els
.ch CAMAC Topology Supervisor Utility-An Overview
 To Be Supplied.