8/18/93  YY

1


Usage Guide of CAMAC Library for UNIX
Version 0.9
Y.Yasu( KEK Online Group)


Contents

INTRODUCTION	.............	1
SETUP FUNCTIONS	.............	1
CAMAC FUNCTIONS	.............	3
CAMAC SINGLE ACTIONS	.............	5
CAMAC BLOCK ACTIONS	.............	6
INTERRUPT HANDLING	.............	7
KEK LIST PROCESSING	.............	9
KINETIC LIST PROCESSING	.............	11
CONDITION WITH SIGNAL	.............	13
DESCRIPTION OF ERROR STATUS	.............	13


Introduction

This guide explains how to use CAMAC library for UNIX.  The library supports not only DECStation5000 withVME adaptor but also SUNSparc with that. Basically, the specification of the library is compatible with that of the library for VAX/VMS, but new function called Kinetic List Processing is added.

The library can be called not only C language but also Fortran language while the names of the routines for both are same.


Setup Functions

CAM_Open, COPEN or CAMOPN
Name :
	CAM_Open, COPEN and CAMOPN for opening the CAMAC controller 2917.

Syntax :
<C>
	#include "camlib.h"
	CAM_Open( ) 
<Fortran>
	include 'camlib.inc'
	CAM_Open( )

Description :
	This routine opens the CAMAC controller 2917s.  The device driver already 
	checks how many controllers are available. This routine make the controllers 
	available for users.

Arguments :

Return Value :
	Upon successful completion, value 0 is returned.
	This routine fails under the following condition :
	[ENXIO]	No such device.  There is no available 2917.

CAM_Close, CCLOSE or CAMCLS
Name :
	CAM_Close, CCLOSE or CAMCLS for closing the CAMAC controller 2917.

Syntax :
<C>
	#include "camlib.h"
	CAM_Close( )
<Fortran>
	include 'camlib.inc'
	CAM_Close( )

Description :
	This routine closes the CAMAC controller 2917. This means that the controllers 
	are not available for users until they are opened.
	These routines don't generate CAMAC list codes even if specified

Arguments :

Return Value :
	Upon successful completion, value 0 is returned.
	positive nonzero value : errno

CSETBR
Name :
	CSETBR for setting current branch number.

Syntax :
<C>
	#include "camlib.h"
	CSETBR( branch )
	int branch;
<Fortran>
	include 'camlib.inc'
	integer*4 branch
	CSETBR( branch )

Description :
	This routine sets the specified branch number into the driver's database.
	This routine doesn't generate CAMAC list codes even if specified

Arguments :
	branch	branch number( 0 <-> 7 )

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CSETCR
Name :
	CSETBR for setting current crate number.

Syntax :
<C>
	#include "camlib.h"
	CSETCR( crate )
	int crate;
<Fortran>
	include 'camlib.inc'
	integer*4 crate
	CSETCR( crate )

Description :
	This routine sets the specified crate number into the driver's database.
	This routine doesn't generate CAMAC list codes even if specified, but internal 
	variable crate_number will modified

Arguments :
	crate	crate number( 0 <-> 7 )

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


CAMAC Functions

CGENZ
Name :
	CGENZ for initializing the current CAMAC crate.
Syntax :
<C>
	#include "camlib.h"
	CGENZ()

<Fortran>
	include 'camlib.inc'
	CGENZ()

Description :
	This routine initializes the current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CGENC
Name :
	CGENC for clearing the dataway of the current CAMAC crate.
Syntax :
<C>
	#include "camlib.h"
	CGENC()

<Fortran>
	include 'camlib.inc'
	CGENC()

Description :
	This routine clears the dataway of the current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CSETI
Name :
	CSETI for setting the dataway inhibit of the current CAMAC crate.
Syntax :
<C>
	#include "camlib.h"
	CSETI()

<Fortran>
	include 'camlib.inc'
	CSETI()

Description :
	This routine sets the dataway inhibit of the current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :

Return Value :
	This routine fails under the following condition :
	[EBADF]	Bad File descriptor.  There is no 2917 controller.

CREMI
Name :
	CREMTI for resetting the dataway inhibit of the current CAMAC crate.
Syntax :
<C>
	#include "camlib.h"
	CREMI()

<Fortran>
	include 'camlib.inc'
	CREMI()

Description :
	This routine resets the dataway inhibit of the current CAMAC crate.
	This routine will generate CAMAC list codes if specified.

Arguments :

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


CAMAC Single Actions

CAMAC or CAMACL
Name :
	CAMAC or CAMACL for executing a single CAMAC operation 
	with 24 bit  CAMAC data on the current  CAMAC crate.

Syntax :
<C>
	#include "camlib.h"
	CAMAC(naf, data, q, x)
	int naf, *data, *q, *x;

<Fortran>
	include 'camlib.inc'
	Integer*4 naf, data, q, x
	CAMAC(naf, data, q, x)

Description :
	This routine executes a single CAMAC operation with 24-bit CAMAC data
	 on current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :
	naf	naf code, which can be generated by NAF function.
	data	24-bit CAMAC data
	q	CAMAC Q response.  if q=1, q is asserted.
	x	CAMAC X response.  if x=1, x is asserted.

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CAMACW
Name :
	CAMACW for executing a single CAMAC operation with 16-bit  
	CAMAC data on the current  CAMAC crate.

Syntax :
<C>
	#include "camlib.h"
	CAMACW(naf, data, q, x)
	short *data;
	int naf, *q, *x;

<Fortran>
	include 'camlib.inc'
	integer*2 data
	Integer*4 naf, q, x
	CAMACW(naf, data, q, x)

Description :
	This routine executes a single CAMAC operation with 16-bit CAMAC data
	on current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :
	naf	naf code, which can be generated by NAF function.
	data	16-bit CAMAC data
	q	CAMAC Q response.  if q=1, q is asserted.
	x	CAMAC X response.  if x=1, x is asserted.

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


CAMAC Block Actions

CamBloLonWAIt, CBLWAI or CDMAL
Name :
	CamBloLonWAIt,CBLWAI or CDMAL for executing a block CAMAC operation 
	with 24-bit  CAMAC data on the current  CAMAC crate.

Syntax :
<C>
	#include "camlib.h"
	CamBloLonWAIt(mode, naf, buffer, length, return_length, error)
	int mode, naf, *buffer, length, *return_length, *error;
<Fortran>
	include 'camlib.inc'
	integer*2 buffer(N)
	integer*4 mode, naf, length, return_length, error
	CamBloLonWAIt(mode, naf, buffer, length, return_length, error)

Description :
	This routine executes a block CAMAC operation with 24-bit CAMAC data
	on current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :
	mode		selection flags about block/single, 24/16, block modes
	naf		naf code, which can be generated by NAF function.
	buffer		data array to be transferred
	length		length of data array in long word
	return_length	actual length of data transferred in long word.
	error		error code.

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CamBloWorWAIt, CBWWAI or CDMAW
Name :
	CamBloWorWAIt,CBWWAI or CDMAW for executing a block CAMAC 
	operation with 16-bit  CAMAC data on the current  CAMAC crate.

Syntax :
<C>
	#include "camlib.h"
	CamBloWorWAIt(mode, naf, buffer, length, return_length, error)
	u_short *buffer;
	int mode, naf, length, *return_length, *error;
<Fortran>
	include 'camlib.inc'
	integer*2 buffer(N)
	integer*4 mode, naf, length, return_length, error
	CamBloWorWAIt(mode, naf, buffer, length, return_length, error)

Description :
	This routine executes a block CAMAC operation with 16-bit CAMAC data
	on current CAMAC crate.
	This routine will generate CAMAC list codes if specified

Arguments :
	mode		selection flags about block/single, 24/16, block modes
	naf		naf code, which can be generated by NAF function.
	buffer		data array to be transferred
	length		length of data array in short word
	return_length	actual length of data transferred.
	error		error code.

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


Interrupt Handling

CAM_EnableLAM, CENLAM or CELAM
Name :
	CAM_EnableLAM, CENLAM or CELAM for enabling LAM on the current crate
	controller 3922..

Syntax :
<C>
	#include "camlib.h"
	CAM_EnableLAM( mask )
	int mask;
<Fortran>
	include 'camlib.inc'
	integer*4 mask
	CENLAM(mask)

Description :
	This routine enables LAM on current crate controller 3922.  This routine doesn't 
	enable LAM each CAMAC module and CAMAC controller 2917.
	These routines don't generate CAMAC list codes even if specified

Arguments :
	mask	bit pattern of CAMAC station

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CAM_WaitLAM, CWTLAM or CWLAM
Name :
	CAM_WaitLAM, CWTLAM or CWLAM for waitting for generating LAM on
	 the current crate.

Syntax :
<C>
	#include "camlib.h"
	CAM_WaitLAM( timeout )
	int timeout;
<Fortran>
	include 'camlib.inc'
	integer*4 timeout
	CWTLAM( timeout )

Description :
	This routine enables LAM on current controller 2917 and then waits for generation 
	of LAM on the current crate..
	These routines don't generate CAMAC list codes even if specified

Arguments :
	timeout 	timeout time in second

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CAM_DisableLAM, CDSLAM or CDLAM
Name :
	CAM_DisableLAM, CDSLAM or CDLAM for disabling LAM on the current crate
	controller 3922..

Syntax :
<C>
	#include "camlib.h"
	CAM_DisableLAM(  )
<Fortran>
	include 'camlib.inc'
	CDSLAM()

Description :
	This routine disables LAM on current crate controller 3922.  This routine doesn't 
	affect LAM each CAMAC module and CAMAC controller 2917.
	These routines don't generate CAMAC list codes even if specified

Arguments :

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


KEK List Processing

CamReaLIST or CRLIST
Name :
	CamReaLIST or CRLIST reads a CAMAC list from a file.
Syntax :
<C>
	#include "camlib.h"
	CamReaLIST( FileName, List, LenList, RetLenList, Error )
	char *FileName;
	u_short  *List;
	int LenList, *RetLenList, *Error;
<Fortran>
	include 'camlib.inc'
	byte FileName(L)
	integer*2 List(N)
	integer*4 LenList, RetLenList, Error
	CamReaLIST( FileName, List, LenList, Error)

Description :
	This routine  loads the specified CAMAC list into the list buffer in  the CAMAC 
	device driver.
 
Arguments :
	FileName	File name to be read
	List		CAMAC List
	LenList	The length of the list in short word
	RetLenList	The actual length of the read list in short word
	Error		Error status code
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno
	-1		The specified list buffer is too small.

CamLisLOAD or CLLOAD
Name :
	CamLisLOAD or CLLOAD loads a CAMAC list.
Syntax :
<C>
	#include "camlib.h"
	CamLisLOAD( List, LenList,Error )
	u_short  *List;
	int LenList, *Error;
<Fortran>
	include 'camlib.inc'
	integer*2 List(N)
	integer*4 LenList, RetLenList, Error
	CamLisLOAD( List, LenList, Error)

Description :
	This routine  loads the specified CAMAC list into the list buffer in  the CAMAC 
	device driver.
 
Arguments :
	List		CAMAC List
	LenList	The Length of the list in short word
	Error		Error status code
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CamLisExeWAIt or CLEWAI
Name :
	CamLisExeWAIt or CLEWAI  loads a CAMAC list and executes it.
Syntax :
<C>
	#include "camlib.h"
	CamLisExeWAIt( List, LenList, Buffer, LenBuf, Iosb )
	u_short  *List, *Buffer;
	int LenList, LenBuf;
	struct iosb *Iosb;
<Fortran>
	include 'camlib.inc'
	integer*2 List(N), Buffer(N)
	integer*4 LenList, LenBuf, Iosb (3)
	CamLisExeWAIt( List, LenList, Buffer, LenBuf, Iosb )

Description :
	This routine  loads the specified CAMAC list into the list buffer in  the CAMAC 
	device driver and requests its processing. Then, the routine waits for its 
	completion.  After the completion, the routine returns the length of the transferred 
	data, error status and latest contents of S register.

Arguments :
	List		CAMAC List
	LenList	The Length of the list in short word
	Buffer	User Data Buffer
	LenBuf	The length of the buffer in short word
	Iosb 		Return information
			first long word	status
			second long word	actual length of data in the buffer in
						short word
			third long word	latest contents of S register
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CamExeWAIt or CEWAI
Name :
	CamExeWAIt or CEWAI executes CAMAC list.
Syntax :
<C>
	#include "camlib.h"
	CamLisExeWAIt( Buffer, LenBuf, Iosb )
	u_short *Buffer;
	int  LenBuf;
	struct iosb *Iosb;
<Fortran>
	include 'camlib.inc'
	integer*2 Buffer(N)
	integer*4 LenBuf, Iosb (3)
	CamExeWAIt( Buffer, LenBuf, Iosb )

Description :
	This routine requests the processing of CAMAC list  in device driver. Then, the 	routine waits for its completion.  After the completion, the routine returns the 	length of the transferred data, error status and latest contents of S register.

Arguments :
	Buffer	User Data Buffer
	LenBuf	The length of the buffer in short word
	Iosb 		Return information
			first long word	status
			second long word	actual length of data in the buffer in 
						short word
			third long word	latest contents of S register
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


Kinetic List Processing

CKINIT
Name :
	CKINIT initializes Kinetic list processing.
Syntax :
<C>
	#include "camlib.h"
	CKINIT( )
<Fortran>
	CKINIT( )

Description :
	This routine initializes Kinetic list processing.
Arguments :

Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CKADD
Name :
	CKADD adds a CAMAC list for Kinetic list processing.
Syntax :
<C>
	#include "camlib.h"
	CKADD( ListName, List, LenLis )
	char *ListName;
	u_short *List;
	int LenLis;
<Fortran>
	include 'camlib.inc'
	character*8 ListName
	integer*2 Buffer
	integer*4 LenBuf
	CKADD( ListName, List, LenLis )

Description :
	This routine  adds a CAMAC list into the command memory of
	the Kinetic K2917. The List's name is  specified by the ListName.
 Arguments :
	ListName	up to 8 characters
	List		list buffer area which includes the Kinetic list.
	LenBuf	Actual length of the List.
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CKEXEC
Name :
	CKEXEC executes the specified CAMAC list for Kinetic list processing.
Syntax :
<C>
	#include "camlib.h"
	CKEXEC( ListName, Buffer, LenBuf, Iosb )
	char *ListName;
	u_short *Buffer;
	int LenBuf;
	struct iosb *Iosb;
<Fortran>
	include 'camlib.inc'
	character*8 ListName
	integer*2 Buffer
	integer*4 LenBuf
	Integer*4 Iosb(4)
	CKEXEC( ListName, Buffer, LenBuf, Iosb )

Description :
	This routine  executes the CAMAC list specified by the ListName.
	The corresponding CAMAC list is in the command memory of
	the Kinetic K2917.
 Arguments :
	ListName	up to 8 characters
	Buffer	Data buffer area
	LenBuf	Length of the buffer area
	Iosb		Data structure for return code
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CKSAVE
Name :
	CKSAVE saves a CAMAC list for Kinetic list processing.
Syntax :
<C>
	#include "camlib.h"
	CKSAVE( FileName )
	char *FileName;
<Fortran>
	include 'camlib.inc'
	character*N FileName
	CKSAVE( FileName )

Description :
	This routine  saves all of the CAMAC lists in the command memory of
	the Kinetic K2917 into the specified file.
 Arguments :
	FileName	FileName into which all of the CAMAC lists in the command
			memory of  the Kinetic 2917 are stored.
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno

CKLOAD
Name :
	CKLOAD loads a CAMAC list for Kinetic list processing.
Syntax :
<C>
	#include "camlib.h"
	CKLOAD( FileName )
	char *FileName;
<Fortran>
	include 'camlib.inc'
	character*N FileName
	CKLOAD( FileName )

Description :
	This routine  loads the specified CAMAC list into the command memory of the Kinetic K2917.
 
Arguments :
	FileName	FileName which includes the CAMAC lists produced by 
			CKSAVE routine.
Return Value :
	This routine fails under the following condition :
	positive nonzero value : errno


Condition with SIGNAL

	When a routine CAM_WaitLAM(, CWTLAM or CWLAM) is called and then a signal arrives in the interim, the routine will be aborted while it will not accept an interrupt, LAM.  The return value is EINTR. If you don't like such a signal-handling, you can "block" the signal by using sigblock system call.
	When a list processing is executed and it includes "waitint" or/and "waitevent" codes and then a signal arrives in the interim, the codes will be aborted while it will not accept an interrupt, LAM.  Then, the list processing will be aborted at the time as well as at the occurrence of  the timeout.  The currently executing status such as the word count will return in the status word.
	The other CAMAC functions will not aborted even if the signal occurs, but the return status become EINTR even if the functions are done successfully. Of course, you can "block" the signal by using the system call "sigblock".


Description of Error Status

The return status of the execution of the library is given as the return function value and the I/O status block.  The former is called system status and the latter is called CAMAC status.  For examples, CC_STA_OK, CC_STA_SINGLE_TIMEOUT,... are the CAMAC status.  And, ENXIO, EBUSY,.. are the system status which is defined in the UNIX system.  Therefore,
	system status = 0 and camac status = 0	all are ok.
	system status = -1 and camac status !=0	system call is ok,
	but camac fails.

The system status is not explained here, but the CAMAC status is described below .  The status is in the I/O status block as data structure cc_iosb like this;

	struct cc_iosb {
	    int status;
	    int ret_length;
	    int s_reg;
	    int devinfo;
	};

* status :
	camac status  : success = 0 while error != 0. The error is negative value  which is defined as follows;
CC_STA_OK	successful
CC_STA_SINGLE_TIMEOUT	CAMAC single action timeout
CC_STA_BLOCK_INVFUNC	invalid CAMAC function at DMA
CC_STA_LIST_STOP	List processing will stop
CC_STA_LIST_TIMEOUT	LAM timeout
CC_STA_LIST_EMPTY	given List was empty
CC_STA_LIST_ZERODIV	Zero Divided at List processing
CC_STA_LIST_OVERSTEP	max. execution steps exceeds
CC_STA_KLIST_SAMENAME	Kinetic List name was used
CC_STA_KLIST_MEMORYFULL	Kinetic name directory was full
CC_STA_KLIST_NONAME	Kinetic name was not loaded

 * ret_length :
	actual length of data transferred in short word
 * s_reg :
	Only a parameter which is passed to device driver. Latest contents of s register is 	return
 * devinfo :
	first short word	Control Status Register(0:15)
	second short word	Channel Status/Error Register(0:4)

