7 INSTALLATION GUIDE

This section describes how to build the LCU Common Software if executables and libraries are not already available. It then describes step by step the boot script file that loads the software on the target and test procedures that can be run to test the installation.

7.1 Installation requirements

7.1.1 Hardware Requirements

· LCU Common Software loaded and initialised, with boot script default parameters, a small database loaded (20 points, 300 attributes of mixed types) and two command interpreters spawned uses about 1.5 MBytes.

7.1.2 Software Requirements

Tasks using LCC functions (in particular Message System) require a stack size of minimum 30 kBytes to run without problems.

7.2 Building the Software

7.2.1 Delivery

The LCU Common Software is delivered in Unix tar format on tape. The tar file expands into three main directories:

./lcc,./lcustat and ./lcuwd follow the standard ESO organisation, except for the test directories grouped in
./test.

In addition to the standard sub-directories, ./lcc/lcu also contains the following sub-directories:

In addition to the standard sub-directories, ./lcc/ws also contains the following sub-directories:

In addition to the standard sub-directories, ./lccei also contains the following sub-directory:

7.2.2 Tape Downloading

Create a directory in order to download the tape. /install will be used in this document but any path can be chosen.

7.2.3 Build Procedure

If it is required to rebuild the software, standard ESO makefiles are provided in ./lcc/lcu/src, ./lcc/ws/src, ./lcustat/src and ./lcuwd/src.

7.2.3.1 Pre-Conditions

In order to compile the Engineering User Interface, the workstation part of LCC must be build and installed in INTROOT or VLTROOT.

Make sure that the XINC and XLIB variables are correctly defined before building lccei (see vltMakefile).

7.2.3.2 Clean-up of Delivered Environment

Before recompiling the software, it is recommended to clean the delivered environments, using the clean target of the makefile:

7.2.3.3 Recompilation and Link

The following command recompiles and links the complete LCU Common Software or Engineering User Interface:

Before installing the software, the manual pages must also be rebuild, using the man target of the makefile:

7.2.3.4 Install Software to Specified Target Directory

In addition to the standard ESO installation, the makefiles also install the following files into the VLTTARGET environment ($INTROOT or $VLTROOT):

· X11 customizable resources files for Engineering User Interface: Lccei to $(VLTTARGET)/config/

7.3 VxWorks Environment Configuration

Set up your environment with the tool vccEnv as described in [6]. This tool creates the $VLTDATA/ENVIRONMENTS/<lcuEnv> directory and installs the required files, including the database and boot script. It gives you also the possibility to customize your environment. Do not edit the bootScript file manually!! See also the description of the module lcuboot in [6].

7.3.1 Description

· load all files and tables required by the LCU Common Software (device table),

· run user script to download, start and initialize application software (userScript),

7.3.2 Required Database

vccEnv installs the database branches required by LCC in dbl format, see [3], and creates the database.

7.3.3 Customizable Parameters

7.3.3.1 Environment Variables

INTROOT Path of the INTROOT directory on the boot host. The LCU will search for CIT and CDT files in

INTROOT if defined. If the files are not found in INTROOT or if INTROOT is not defined it

BOOTROOT Path of the root directory under which the LCU boot files are located.

7.3.3.2 NFS Configuration

Files are accessed through NFS by the LCU boards during system loading and initialisation and for database loading/unloading and backup/restore operations.

By default, all exported file systems of the boot server host are mounted by VxWorks boot procedure. The NFS configuration section of the boot script allows to mount file systems from other hosts on the LCU.

7.3.3.3 Customizing the LCU Common Software

lccEventQueueSize Size of message queue for events and alarms to be dispatched to target processes
by low priority lccEvent task (number of messages).

lccLogQueueSize Size of message queue for log and error messages to be processed by low
priority lccLogger task (number of messages).

lccErrorBufferSize Size of buffer for error messages (size in bytes). Error messages are discarded
when buffer overflows.

lccEvtDiscardDN Maximum number of identical events/alarms taken into account in a certain
interval of time. A value of zero means that all events/alarms are processed.

lccEvtDiscardDT Interval of time during which a certain amount of identical events/alarms are
taken into account. A value of zero means that all events/alarms are processed.

lccLogDiscardDN Maximum number of identical errors taken into account in a certain interval
of time. A value of zero means that all errors are processed.

lccLogDiscardDT Interval of time during which a certain amount of identical errors are taken
into account. A value of zero means that all errors are processed.

lccMsgQueueSize Size of input message queue for processes registered in the Message System
(number of messages).

lccMapNameNumber Maximum number of names (point, aliases and attributes) defined in the database.

lccSamplingTimer Timer to be used for sampling rates faster than one VxWorks tick (1 to 4).

lccDevicePollTime Interval for testing hardware device probe addresses (seconds).

lccDeviceTimeOut Time-out for replies from device control processes (seconds).

lccHwWdTimeout Timeout for the hardware watchdog timer (seconds). Valid values are 0 and

If you need to change any of these parameters, copy the file $VLTROOT/vw/bin/<CPU_ARCH>/lcc.boot to your environment, $VLTDATA/ENVIRONMENTS/<lcuEnv> and edit the file. If you put the file lcc.boot in $INTROOT/vw/bin, the modifications will affect all LCU environments using this introot, if you put the file in $VLTDATA/ENVIRONMENTS/<lcuEnv> , it will only affect this environment.

7.3.4 Header File for Database Unloading

When a database is unloaded by the LCC software, the header written at the beginning of each Point Configuration File is taken from the file dbHeader found in the boot directory ($VLTDATA/ENVIRONMENTS/<lcuEnv>).

7.3.5 Installation Verification

In order to verify the installation, start the Engineering User Interface and attempt to send commands to the LCU, e.g.

7.3.6 Unix Environment Configuration

7.3.6.1 X11 Resource File

In order to run the Engineering User Interface, the provided X resource file ($INTROOT/config/Lccei or $VLTROOT/config/Lccei) must be loaded into the X server using the following command:

7.3.6.2 Files

Files are searched by LCC software either under the $VLTDATA, that contains data and the $VLTROOT area, that contains released software, or under $INTROOT where software under development is integrated. For each user, what is in the integration area he refers has precedence to what has been already released.

Under both $VLTROOT and $INTROOT there is the same subdirectory structure and the files in the user's $INTROOT/xxx take precedence on those (with the same name) in $VLTROOT.

The following subdirectories and files structure is required to run LCC and the LCC Engineering User Interface:

There is one file for each process. All files are stored under a fixed directory (CDT).

ENVIRONMENTS directory contains one directory for each environment. The file PROCESSES lists all the processes belonging to that environment (one process name per line).

Remark: blank lines are not allowed in the environment file and all lines must be terminated by a new-line character.

There is one file for each software module: xxx_ERRORS. All files are stored under a fixed directory (ERRORS).

There is one file for each software module, xxx_ALARMS. The file is stored under a fixed directory (ALARMS).

7.3.6.3 Environment Variables

In order to run the Engineering User Interface on a workstation, the following Environment Variables MUST be defined:

· INTROOT and VLTROOT Path name of the VLT integration and release areas (where Command Definition Tables, Alarm and Error Definition files are searched).
VLTROOT is mandatory but INTROOT is optional.

· path Shell path variable must contain the path of the Engineering User
Interface executables (lccei and msgcoll).

8 ERROR MESSAGES AND RECOVERY

Each error returned by the LCU Common Software is described below, with the content of the run time parameters described between brackets, with possible corrective action.

lccERR_ACK Acknowledge message not received or invalid error count in acknowledge message [error].
Check Q Server or remote environment.

lccERR_ATTR_TYPE Type given in database write operation does not match actual database attribute type [given type, expected type].
Check database parameter type.

lccERR_BAD_PARAM_NB Invalid number of parameters in command [command, expected number of parameters, actual number of parameters].
Check commands and tables.

lccERR_BAD_PARAM_VAL Invalid parameter value in command [command, parameter].
Check commands and tables.

lccERR_BAD_PRIORITY Invalid VxWorks priority in Command Interpreter Table or scheduled process [priority]. Valid VxWorks priority range from 0 to 255.
Modify priority.

lccERR_BAD_RT_OPTIONS Invalid VxWorks scheduling options in Command Interpreter Table or scheduled process [options].
Modify options.

lccERR_BOOK Access denied to process for command [booking id of the command].
Check the process booking status.

lccERR_BOOKABLE Booking operation is not allowed for a bookable process [process name].
Change the booking status of the process.

lccERR_BOOKED Booking operation is not allowed for a booked process [process name].
Change the booking status of the process.

lccERR_BUF_SIZE Buffer is too small to contain requested database values [required size, buffer size].
Increase size of buffer.

lccERR_CMD_SYNTAX Syntax error in command [command, invalid parameter].
Check commands and tables.

lccERR_BAD_STACK_SIZE Invalid VxWorks stack size in Command Interpreter Table or scheduled command [size].
Modify stack size.

lccERR_DB_BLOCK_COUNT One or more database attribute accesses failed during dbMultiRead or dbMultiWrite.
Check specification of list for multiple access.

lccERR_DB_CONVERT Not possible to convert value in database backup file during restore.
Check syntax of database backup file.

lccERR_DB_SYNTAX Syntax error in database definition file [error, line number].
Check database definition file.

lccERR_DB_HIERARCHY Error while loading child database item [name]. Error generated recursively for each point level when a database loading generated an error.
No corrective action.

lccERR_DE_TYPE Type given in database write operation does not match actual database parameter data type [given type, expected type].
Check database parameter data type.

lccERR_DEVICE Error reply or no reply from device control process [number of devices, device names].
Check device control process.

lccERR_DIRADDRESS Database direct address is not valid [invalid field, invalid value].
Use valid direct address. Re-compute all direct address when the LOADED state is exited.

lccERR_DRIVER A call to a driver function returned an error.
Check the error code and the command.

lccERR_DUPLICATE Another definition with the same name already exist [item type, name].
Use another name.

lccERR_ENV_NAME Invalid environment name or unknown environment [name].
Check name, or Q Server environment table definition in boot script, or environment is up.

lccERR_EVENT Error returned under the following conditions:
. attribute configured for abnormal event but not previously configured for
events [attribute];
. attribute configured for abnormal event with alarm number given for
limits that were not configured [attribute];
. attribute requested for abnormal events but not configured [attribute].
Check the attribute configuration.

lccERR_EVENTS_EXIST Request of events or alarms is possible only when no events or alarms have been requested yet.
Use evtAddXXX operation to add of events or alarms.

lccERR_FILE File access error [file, context].
Check file access rights, network and file content.

lccERR_FILE_CDT Syntax error in Command Definition Table [file name].
Check Command Definition Table.

lccERR_FILE_CIT Syntax error in Command Interpreter Table [file name].
Check Command Interpreter Table.

lccERR_FORMAT Invalid DISPLAY_FORMAT field in Command Definition table: format specification does not match reply parameters description.

lccERR_FULL A message queue (for events, logging or error messages) is full [context].
Increase the corresponding parameter in the boot script.

lccERR_IN_USE A functionality that can be used only once at a time (e.g. sampling or event request by remote process) is already in use [context].
Check with current user.

lccERR_INTERNAL Unexpected error in LCU Common Software [error context].
Send a problem report to ESO.

lccERR_INV_ACTION Operation not allowed in current LCU state [current state].
No corrective action.

ccERR_INV_FIELD Wrong number of fields or invalid field name for a database access operation.
Check number of fields or field names for the accessed attribute.

lccERR_INV_NAME Syntax error in database item or signal symbolic name [type of error, name].
Use a valid symbolic name.

lccERR_INV_RECEL Wrong number of records for a database access operation [given number, expected number].
Check number of records for the accessed attribute.

lccERR_INV_XREF During database unloading or backup operation a database cross-reference value does not correspond to a valid point or attribute. The backup or unload is not interrupted; the faulty cross-reference value is unloaded as `[]'.

lccERR_IO_ADDRESS Invalid direct address of signal [address value]. Possible error when a database is reloaded and direct address of signal has not been re-computed.
Re-compute all direct address when the LOADED state is exited.

lccERR_LENGTH Invalid length of an item name [name, maximum length].
Use valid name length.

lccERR_LOCK Attribute cannot be accessed because attribute or parent point is locked [attribute name].
Check with other users or unlock attribute or point before accessing the attribute.

lccERR_MASTER_CODE The Master User Code used in a booking operation is not valid [invalid code].
Use the correct Master Code.

lccERR_MAP_MAXIMUM Maximum number of names allowed in the database has been reached [name of item].
Increase the corresponding parameter in the boot script.

lccERR_MEMORY Dynamic memory allocation error [variable name, requested size].
Verify dynamic memory management of applications.

lccERR_MISSING_PARAM_VAL Missing parameter value in command [command, parameter]
Check commands and tables.

lccERR_MSG_CMD Invalid command received by msgServer process [command].
Check sent commands.

lccERR_MSG_SIZE Message body is limited to (msgMAXLEN - sizeof(msgHEADER) - sizeof(msgOBITUARY)) [size].
Use smaller message body.

lccERR_MULTI Operation is allowed only for single database parameter and given address matches more than one parameter [name].
Modify address to match only one parameter.

lccERR_NO_EVENTS Operation evtAddXXX (on change, periodic events or alarms) is not allowed if no previous request operation was issued [requesting process].
Events and alarms must be requested before new events can be added.

lccERR_NO_IMAGE Missing attributes for image and status of a signal in the database [signal name].
Add attributes in database.

lccERR_NOT_FOUND An item (process name, attribute name, etc) is not defined [item type, not found name].
Use an existing name.

lccERR_NOT_REGISTERED Only processes registered in the Message System can send and receive command.
Register process before sending and receiving messages.

lccERR_ORDER Value given to limits for parameter monitoring are not in increasing order [lowLow value, low value, high value, highHigh value].
Modify the value of the limits.

lccERR_PARAMETER Invalid parameter to a function call [parameter name, invalid value].
Use a valid value.

lccERR_PROC_NAME Process name is invalid or does not match any existing process [name].
Check process name.

lccERR_Q_EMPTY No matching message is found in the queue.
No corrective action.

lccERR_QSERVER A Q Server system call returned an unexpected error [called function, error number].
Check the returned error number, eventually reboot the LCU.

lccERR_RANGE Signal value is out of range [context, value].
Use valid signal values.

lccERR_REMOTE Operation not allowed on remote database [attribute name].
No corrective action.

lccERR_SEM An internal mutual exclusion semaphore remains locked for long duration [semaphore identifier].
Send a problem report to ESO.

lccERR_SEND_MESSAGE Timer module cannot send message for timerSendMessage request [context].
Check parameters of timerSendMessage operation.

lccERR_SHARABLE Booking operation is not allowed for a sharable process [process name].
Change the booking status of the process.

lccERR_SIGNAL Invalid signal type for I/O operation [signal, expected type].
Use only valid I/O operations for signal.

lccERR_SIMULATION An operation is not allowed in simulation mode [context].
No corrective action.

lccERR_TIMEOUT Time-out expired for a function with time-out parameter [duration].
Check reason of time-out.

lccERR_UNKNOWN_CMD Received command not found in Command Interpreter Table or Command Definition Table [table, command].
Check commands and tables.

lccERR_VXWORKS A VxWorks system call returned an unexpected error [called function, errno].
Check the returned errno.