| |
|
|
|
3 REFERENCE
3.1 Utilities
This section contains the man pages of the progams available at UNIX level.
On full CCS alrmDisplay starts the RtapASDisplay with the parameter list
given. To be able to see the help file for a selected alarm the user
must select the POST action from the "Environment" menu on the upper left
corner of the RtapASDisplay GUI. A read-only text window will be
created displaying the help file. The search order for the help file
is MODROOT - INTROOT - VLTROOT. If no help file is available a warning
is displayed.
On CCS LITE alrmDisplay starts the CCS ALARM DISPLAY Panel. The following
options are available
-e <envname> environment to monitor for alarms
-se enable sound support
The alarm help files are stored in the subdirectory ALARMS/HELP of
MODROOT, INTROOT or VLTROOT. They are referenced via the alarm macros.
USER is required and must have an entry on the Rtap environments users branch
where the alrmDisplay is intended to be conected.
alrmDisplay can not be run on the background and requires the variable
RTAPENV to be defined to a running environment.
Full CCS:
alrmDisplay -E wsv1 -E wsv2
display/monitor alarms of the environments wsv1 and wsv2
CCS LITE:
alrmDisplay -e wte35a -se
display/monitor alarms of the environment wte35a with
sound enabled
CCS Alarm System Design Description VLT-SPE-ESO-17210-0782
CCS User Manual, Alarm System,chapter VLT-MAN_ESO-17210-0619
CCS Alarm System Logger.
This utility logs all alarms related events ocurring on a list of
environments. This logs are written throught the standard CCS
logging system. It also handles the LOCAL not ACKed. alarms. When
a LOCAL alarm enters a waiting for ACK. severity and stays there
for a period longer than the alarm instance parameter "timeout"
seconds, the almrLogger set the scope of this alarm to GLOBAL.
If the alarm is later ACKed, the alrmLogger will reset its scope
to LOCAL.
Each Rtap environment should start its own alrmLogger from the
RtapEnvTable
14 2 N N N N N 100 128 alrmLogger
Its run on the local environment ( RTAPENV ) and connects to the
lists of environemnts on the parameter list. If no environments are
given in the list, its connects to RTAPENV.
CCS Alarm System Design Description VLT-SPE-ESO-17210-0782
CCS User Manual, Alarm System,chapter VLT-MAN_ESO-17210-0619
The ccsCmdServer process executes an CCS LITE environment's command
schedule. On startup it tries to read the schedule from the local
database. If successful it begins to execute the commands according
to the schedule found.
The schedule itself is maintained in the table
<alias>schedule config.commands
If this attribute does not exist, the server process logs an error
and terminates immediately.
ccsCmdServer supports the following options
-e defines the environment to register with; if not defined
it registers with the environment defined by RTAPENV
-p if defined all actions are logged in the file <protocol-file>
(NOTE: the current working directory is the environment's
home directory)
3.1.4 ccsRunCmd(1)
ccsRunCmd executes the command defined by <runstring>. The
content of runstring is normally a process name with appropriate
command line options.
ccsRunCmd has the environment directory as its current working
directory. Therefore, any relative path name given is interpreted
as relative to that directory, rather than the one from which
ccsRunCmd is invoked.
-e <envName> environment to which ccsRunCmd should attach
-m currently not supported
-u causes ccsRunCmd to ensure that the process started by
<runstring> is unique meaning that runstring will not be
executed, if a program with the same basename is already
running.
-w <delay> directs ccsRunCmd to wait for the specified number of
seconds for the command to complete. If the command does
not complete in the given time, ccsRunCmd terminates with
a non-zero exit code. Otherwise it exits with the exit
status of the command itself.
In order to wait forever specify "-w 0"
runstring command to be executed
EXIT_SUCCESS (0), after successful termination (see -w option)
EXIT_FAILURE (1), if an internal error occurred
3.1.5 ccsScheduler(1)
ccsScheduler is the process scheduler for an CCS LITE environment.
An CCS LITE environment consists of the ccsScheduler, managing
the OS resources, a set of core processes which come with CCS LITE
(msgServer, cmdManager etc.) and all user-written applications.
ccsScheduler is responsible for starting the environment, managing
its processes, and shutting down the environment.
ccsScheduler has three distinct phases of operation. These are:
Startup During its startup phase, ccsScheduler starts
other processes which are part of the environment.
You can control the order in which processes are
started. Startup can take place in a number of
discrete, user-controlled stages.
Process Management During its management phase, ccsScheduler accepts
requests from processes in the environment and tries
to process them. It also acts on process terminations
within the environment and notifies all processes
configured to receive OBITUARIES.
Shutdown The ccsScheduler enters its shutdown phase, if it
either receives a SIGINT/SIGTERM/SIGQUIT or SIGUSR2
signal or a programmed shutdown request. During this
phase is sends a SIGTERM signal to all local processes
and removes all OS resources allocated during run-time.
ccsScheduler supports the following options
-e defines the environment to be started; if not defined
the environment defined by RTAPENV is started
-d will trigger activity logging. Whenever a process register or
deregister, a log with process name and procnum will be produced.
-s causes the ccsScheduler to raise the signal SIGUSR1 for process <pid>
after all autostart-processes have been started
-R enables real-time capabilities
/etc/services - UNIX system file which is a local source of information
regarding each service available through the Internet;
for each remote environment a local process wants to
communicate with, an entry has to exist in this file
CcsEnvList - this file contains the names of all RTAP/CCS LITE
environments and associated directories on the local host,
and all environments and associated host names on a network;
This file is stored in the directory $VLTDATA/config.
CcsEnvTable - this file contains a list of the processes that are known
to this environment and a set of characteristics associated
with each process; it has to exist for each environment in
its home directory $VLTDATA/ENVIRONEMENTS/<envname>
ccs_log - this file is created by the ccsScheduler on start-up for
logging purposes
ccsWaitForProc enters the local environment, and calls the
ccsWaitForProcStat function.
<environment> environment where the inspected process is running
<process> name of inspected process
<procState> one of:
REACHABLE: a ping command without reply has been sent.
ANSWERING: a PING command with reply is answered.
EXIT : the process has no procNum in the environment.
<time-out> time-out value in seconds to wait for reply for the
requested state to be reached. If value is negative,
will wait forever.
Any process registering into an environment (Rtap or CCS_Lite) can be
tested against the EXIT case. REACHABLE and ANSWERING cases must be
reserved for VLT applications only since Rtap processes might be
disturbed by PING commands, and show umpredictable behaviors.
EXIT_SUCCESS (0), if the inspected process is found within <time-out>
in the requested state.
EXIT_FAILURE (1), in any other case
>ccsWaitForProc "" cmdManager REACHABLE 10
-> query, up to 10 seconds, the cmdManager in the local environment to check
if it accepts a PING command.
cmdManager is a system server that enters the local RTAP environment
and enables the handling of CDT's (Command Definition Tables) as well
as provides means for simulation of processes and environments.
At startup all CDT's located in the search path are loaded into shared
memory areas where they are referenced by the cmd library.
By default the cmdManager searches for CDTs in
- $VLTROOT/CDT - global CDT files
- $INTROOT/CDT - integration CDT files
- $MODROOT/CDT - module CDT files
The search path can be changed using the command line option -l.
Passing
NONE - no CDT's are loaded
MODROOT - only CDT's found in $MODROOT/CDT are loaded
INTROOT - only CDT's found in $INTROOT/CDT are loaded
VLTROOT - only CDT's found in $VLTROOT/CDT are loaded
ALL - all CDT's found in VLTROOT/CDT, $INTROOT/CDT and $MODROOT/CDT are loaded.
If a CDT for process is existing in several directories part of the
search path, the one found at last is loaded.
CDT's can be loaded and unloaded dynamically using the utility cmdSetup(1).
If the CDT of a process is already loaded the cmdManager replaces the
existing one with the new one.
When the cmdManager is shutdown e.g. with the EXIT command the CDT's
and the corresponding shared memory areas are removed. Then command
checking is then no longer possible.
The cmdManager also provides the service to simulate processes. If a
CCS environment/process is set in simulation mode, the CCS Message System
redirects any command to the cmdManager, which then sends a reply
according to the information stored in the CDT of the process simulated.
The phoney reply is nested in a message of the type msgTYPE_SIMREPLY,
that is stripped of by the CCS Message System.
The cmdManager supports the following commands:
Command name Message Body Comment
________________________________________________________________
CDTSCHK <process> Check the syntax of the CDT
CDTLOAD <process> Load CDT of process
CDTUNLD <process> Unload CDT of process
CMDCLST <none> List loaded CDT's
CMDHELP <proc,command> Get command help text
CMDLIST <process name> List all commands for
CMDPAR <proc,command> List command parameters
CMDRPLY <proc,command> Get list of reply values
CMDSIM <internal format> Reserved
CMDSLST <none> List processes in simulation mode
PARTYPE <proc,command,par> Get parameter type data
SIMSET <process name> Set process in simulation mode
SIMUSET <process name> Unset process back to normal mode
SYNLST <process name> List all synonyms of process
SYNTOC <proc,synonym> Get command of synonym
VERSION <none> Return version of cmdManager
cmdSetup [-load <CDT filename>] [-syntax <CDT filename>]
[-unload all | <proc name>] [-loadDir <CDT directory>]
cmdSetup is CDT management utility. The main task is to load
CDT's (Command Definition Tables) by sending commands to the
cmdManager.
When cmdSetup is started with no parameters it lists the cur-
rently loaded list of CDT's.
When a specific CDT should be loaded the -load option can be used.
Furthermore the cmdSetup utility can be used to check syntax of
a CDT file (-syntax option) which check syntax, load and unload CDT.
cmdSetup accepts following options:
-load Parse and load the file specified in <CDT filename>.
-loadDir Load directory of CDT's.
-parse Same as -load option (obsolete).
-syntax Check syntax and integrity of <CDT filename>.
-unload Unload the process name. If "all" is specified all CDT's
currently loaded are unloaded.
cmdUser retrieves information on the CDTs (Command Definition
tables) loaded by the CCS Command Management System.
By using command line arguments specific processes (-p option)
and commands (-c option) can be specified. The CDT information
found will be displayed on stdout.
cmdUser accepts following options:
-v Run in verbose mode.
-p Specify process name.
-c Specify information on specific command.
-a Test argument
dbBackup() generates a backup of all attributes specified either
by <db item> or in the file <input> and stores it in <output>.
-c <cwp> specifies a CWP to be set before the input file
is processed. If the -f option is used this CWP
is valid until it is redefined in the input file.
-f <input> specifies a file containing a description of the
backup to be performed.
-n[b]<db item> symbolic address of an attribute/point to be saved.
If the -nb option is used and the database item is
a point, all attributes of the branch defined by
the point are read. <db item> must be specified
according the rules defined in the CCS User Manual.
-o[a]<output> name of file, where to store the data. If the -oa
option is used, the output will be appended to
<output>. If this option is omitted, the data will
be printed on the standard output.
-k causes dbBackup() to write the RCS-keyword at the
beginning of the output file.
NOTES:
- It is not possible to use the -f option in conjunction
with the -n[b] option and vice versa.
- If the -c option is used in conjunction with the -n[b]
option <cwp> and <db item> are just concatenated. So
>dbBackup -c "@lte40:" -nb "PARAMS" -o output.dat
is equivalent to
>dbBackup -nb "@lte40:PARAMS" -o output.dat
- Any symbolic address MUST NOT exceed 255 bytes.
For detailed information about the structure of a backup input/output
file see man-pages dbBackupFile(5)/dbBackupInFile(5).
This tool creates a temporary file in the tmp directory in order not
to corrupt an existing copy of the backup file in case of failure.
Example :
../bin/dbBackup -n ":PARAMS:SCALARS" -o /a/b.backupFile
The tools creates the temporary file /tmp/backupFile.bck and if the
backups exists with success, the temporary file is moved to its final
location as specified by the "-o" option.
RTAPENV name of local environment
(NOT USED if running in CCS-LITE environment)
NO_ERR_DISPLAY controls whether in case of an error the
errDisplay() will be started or not.
If set only the last error of the error stack
is displayed on the stdout.
>dbBackup -n "@wsct1:PARAMS:VECTORS.vector(0:10)" -o output.dat
reads the values of the records 0-10 of the attribute
vector within the point :PARAMS:VECTORS on the
environment wsct1 and stores them in output.dat
>dbBackup -n "@wsct1:PARAMS:VECTORS" -o output.dat
reads the values of all attributes within the point
:PARAMS:VECTORS on environment wsct1 and stores
them in output.dat
>dbBackup -nb "@wsct1:PARAMS" -o output.dat
reads the values of all attributes within the branch
:PARAMS on environment wsct1 and stores them in output.dat
>dbBackup -f input.dat -o output.dat
reads the values of all attributes defined in input.dat
and stores them in output.dat
Reads the database element specified by the symbolic address and
displays the result on the standard output.
symbolicAddress <IN> Symbolic address of the database element
Examples to address local DB:
- ":PARAMS:SCALARS.scalar_int32"
- "SCALARS.scalar_int32" using the alias in this
- "<alias>SCALARS.scalar_int32" way the access is faster.
Examples to address remote DB:
- "@wte13:PARAMS:SCALARS.scalar_int32"
- "@wte13:SCALARS.scalar_int32"
NOTE: This utility can read at maximum 100KB data from a WS and
64KB data from a LCU database.
Read a SCALAR attribute:
dbRead ":PARAMS:SCALARS.scalar_float"
dbRead "@lte23:PARAMS:SCALARS.scalar_float"
Read a VECTOR attribute:
dbRead ":PARAMS:VECTORS.vector_uint32(3:5)"
dbRead "@lte23:PARAMS:VECTORS.vector_uint32(3:5)"
Read a TABLE attribute:
dbRead ":PARAMS:TABLES.full_table(1:3,0:2)"
-f <input> specifies a file containing the data to be
restored. If no input file is specified, the
data is read from the standard input. This
allows to send the output of dbBackup() to
dbRestore() through a pipe.
-co <CWP> causes dbRestore() to substitue the first CWP
found in the input file by <CWP>.
-c <CWP1>=<CWP2> causes dbRestore() to substitute every current
working point found in <input> and matching
<CWP1> by <CWP2>. <CWP2> must be a valid symbolic
address. By this option it is possible to move
data between environments/branches and points.
EXAMPLES for substitution:
-c "@wte19=@wte16"
<CWP> @wte19: -> @wte16:
<CWP> @wte19:PARAMS -> @wte16:PARAMS
<CWP> @wte19<alias>TestRoot -> @wte16<alias>TestRoot
-c "<relative>PARAMS=<relative>TEST"
<CWP> @wte19:PARAMS -> @wte19:PARAMS
<CWP> <relative>PARAMS -> <relative>TEST
<CWP> <relative>PARAMS:SCALARS -> <relative>TEST:SCALARS
NOTE: At maximum 10 substitutions can be specified.
The following rules are applied during the restore operation:
- if a point specified in the input file is not
found, dbRestore() terminates with an error
- an attribute is skipped and a warning is printed
on the standard output, if
- an attribute specified in the input file is
not found
- the attribute type in the input file does not
match the type defined in the database
- the number of records/fields of an attribute found
in the input file does not match to the one retrieved
from the database; the records/fields matching the
range are always restored
RTAPENV name of local environment
(NOT USED if running in CCS-LITE environment)
NO_ERR_DISPLAY controls whether in case of an error the
errDisplay() will be started or not.
If set only the last error of the error stack
is displayed on the stdout.
>dbRestore -f input.dat
restores all data in file input.dat
>dbRestore -f input.dat -c "@wsct1:=@wsct2:"
restores all data in file input.dat replacing
the current working point @wsct1: by @wsct2:,
which means the data read from @wsct1: is stored
on @wsct2:.
>dbBackup -nb "@wsct1:" | dbRestore -co "@wte49:"
replaces contents of database on wte49 by
the contents of database on wsct1
dbStartup creates/loads the local database based on the DB files
found in the directory $(VLTDATA)/ENVIRONMENTS/<$RTAPENV>.
dbStartup first searches for a database snapshot-file, which
is normally called <$RTAPENV>.db and located in the environment's
home directory. If one is found, it tries to load the snapshot.
Otherwise it creates the database using the standard DB branch.
On termination dbStartup calls rtStartNextPhase() in order to trigger
the ccsScheduler to enter the next startup phase.
dbStartup supports the following options
-r defines the size of the shared memory segement used for the
local database (default: 0x007FFFFF bytes)
-h defines the size of the hash-table used to store symbolic
addresses (default: 1088 kb)
NOTE: This value has to be entered in bytes !
-q defines the size of the queue used for database event
handling (default: 200 elements)
-a defines the size of the queue used for alarm handling
(default: 100 elements)
-s skip the rtStartNextPhase() function call
$VLTDATA - location of environment's directory branch
RTAPENV - name of local environment
CCSDBSHM - address of shared memory segment to be used
(default: 0x01400000)
NOTE: CCSDBSHM must be defined in HEX format
3.1.14 dbWrite(1)
Writes the data specified in the <list_of_data> to a database element
defined by its symbolic address.
symbolicAddress <IN> symbolic address of the database element
list_of_data <IN> list of values to be written
Examples to address local DB:
- ":PARAMS:SCALARS.scalar_int32"
- "SCALARS.scalar_int32" using the alias in this way
- "<alias>SCALARS.scalar_int32" the access is faster.
Examples to address remote DB:
- "@wte13:PARAMS:SCALARS.scalar_int32"
- "@wte13:SCALARS.scalar_int32"
The attribute can be a SCALAR, VECTOR or a TABLE.
Write into a SCALAR attribute:
dbWrite ":PARAMS:SCALARS.scalar_float" 12.8
dbWrite "@lte23:PARAMS:SCALARS.scalar_float" -16.935
Write into a VECTOR attribute:
dbWrite ":PARAMS:VECTORS.vector_uint32(3:5)" 12 45 28
dbWrite "@lte23:PARAMS:VECTORS.vector_uint32(3:5)" 12 45 28
Write into a TABLE attribute
dbWrite ":PARAMS:TABLES.full_table(1:3,0:2)" \
0 12 45 1 24 90 1 36 135
dbWrite ":PARAMS:TABLES.full_table(3,string4)" "Hello world"
This utility is used to retrieve and display an error stack.
Its behaviour depends on the number of parameters supplied by the user.
<stackId> - Stack identifier
<file> - Name of the file where to retrieve the stack
?maxLines? - If specified the serach is done taking only the last ?lines?
of the <file>
Retrieve error stack 85 from file 'logFile'.
errShowStack 85 logFile
Retrieve error stack 85 from the log backup file 'logFile_96-05-29.bck'.
errShowStack 1113 logFile_96-05-29.bck
3.1.16 evtEventConfg
evtEventConfg - create, attach, detach, delete, trigger events
and notify hangers, for CCS_LITE. Runs also on
FULL_CCS to support remote events towards CCS_LITE.
evtEventConfg configures all event requests by processing the messages
it receives on its queue. Possible requests are:
- create events
- attach process hangers to events
- detach hangers from events
- delete events
- change status of hangers on events
If an event occurrs it forwards the occurrence of the trigger event
to all waiting hangers, using an event message.
When an obituary is received for a process, all hangers/events/notifications
are removed from the event list. When an obituary is received for an
environment, all potential notifications destined for the terminated
environment are removed.
evtEventCnfg supports the following options
-v run in verbose mode
-n defines the maximum number of events, that can be attached
(default is 4000)
-p defines the maximum number of processes, that can be handled
(default is 512)
-q defines the maximum number of events, that can be cached per
process (default is 96)
During start-up evtEventConfg registers with the environment defined by the
environment variable RTAPENV.
evtEventConfg under CCS_LITE provides the functionality normally available
directly from Rtap. evtEventConfg can also be generated under FULL CCS to
support event attachement from remote CCS_LITE environments.
evtEventConfg should have an entry in the environment table.
It may only run once in an environment.
On some UNIX systems the number of threads per process is a configurable
kernel parameter. Since evtEventConfg manages each process with a single
thread, this parameter has to be increased accordingly.
logConfig sends the INIT command to the logManager on the local
environment. This command causes the logManager to reinitialize.
RTAPENV defines the name of the local environment; inapplicable
to CCS-LITE
NO_ERR_DISPLAY if defined, errors are printed on the standard output;
otherwise errDisplay() is called.
This script generates the configuration file read used to configure
the logManager :
logCreateLcuConfig "" <list of "LCU WS" pairs>
Generates the generic 'logLCU.config' configuration file specifying which
LCUs have a given WS environment as logging reporting node.
The file contains these instructions for several WS environments.
logCreateLcuConfig <env> <list of LCUs>
Generates a configuration file associated to a specific env.
The configuration file is put under $VLTDATA/ENVIRONMENTS/<env> directory.
Checks are performed to verify that the utility has been called with
the proper parameter syntax.
If errors are detected the execution stops and a log is issued.
The utility first generates a temporary file and then replace the target
file with the newly generated one if it completes successfully.
logDisMsg disables the automatic logging of messages sent or
received for a given process running in a given environment.
logDisMsg sends the command "MSGDLOG" to a given process in a specific
environment.
process process name
environment environment name; if not defined, the local one is used
logEnMsg enables the automatic logging of messages sent or
received for a given process running in a given environment.
logEnMsg sends the command "MSGELOG" to a given process in a specific
environment.
process process name
environment environment name; if not defined, the local one is used
Logs sent from remote environments are stored in a file using the
syslog daemon. Two processes are involved :
- The logManager: this is the main process and it is responsible to
get the logs from the message queue and store them into an internal
buffer area to be processed.
- The vltLogger: this process is created as a thread by the logManager
and it is monitoring the buffer area for incoming new log messages.
The vltLogger reads the log messages from the buffer area, process
them and stores them into a log file through the syslog daemon.
When invoked, the logManager reads $VLT_LOG_ROOT/logLCU.config and
configures all LCU defined in that file to send their logged data
to the logManager.
-d <list of dict.> Loads the Fits definitions described in the list
of dictionaries.
-l <logging rate> Defines how often the vltLogger must be run.
The vltLogger is responsible to deliver the logs
to syslog.
-p <pollPeriod> Defines the period in milliseconds between two
attempts to restart logging on a LCU.
If not specified a default value of 30000
milliseconds is used. The smallest period allowed
is 15000 milliseconds.
The restart mechanism is enabled, whenever
- an obituary is received for a LCU configured
to send the logs to the logManager
- no or a negative reply is received on a command
sent to a LCU
-v Causes the logManager to run in verbose mode
-f <env> Define the name of the WS environment used to label FITS logs
The logManager supports the following public commands:
Command Parameters Purpose
________________________________________________________________
DEBUG "debugLevel" Enable/disable the printing of additional
information for debugging purposes
0 no debug information
1 First level debug
2 Second level debug
EXIT NONE Terminate logManager
INIT NONE Reinitialize the logManager
LOADICT filePath Loads a dictionary by specifying the
complete dictionary file path
LOGRATE delay (sec) Defines the delay before calling the vltLogger.
The vltLogger runs until all logs in the
buffered by the logManager are logged.
START NONE Start sending of logged data from LCUs
STATUS NONE Return status of logging system on LCUs
STOP NONE Stop sending of logged data from LCUs
VERBOSE "ON" or "OFF" Enable/disable verbose mode
VERSION NONE Returns version of logManager
ADDFITS <see examples> Allows the user to add a FITS log.
The message contains a CHECK flag that forces
the logManager to check if the FITS keyword is
correct.
If CHECK is enabled,the fits comment is taken
from the dictionary and there is a check on the
type of data provided by the user.
$VLT_LOG_ROOT/logLCU.config logManager configuration file
$VLT_LOG_FILES/logFile output file for normal logs
$VLT_LOG_FILES/logAuto output file for automatic logs
/etc/syslog.conf syslog-daemon configuration file
RTAPENV name of local environment; not used in CCS-LITE
INS_ROOT directory where to get the data dictionaries from
VLT_LOG_ROOT directory, where configuration file is stored
VLT_LOG_FILES directory containing logging-files
In order to work properly the logManager has to be configured to
receive obituaries in the RtapEnvTable file of an environment.
This is not applicable to CCS-LITE.
These are examples of use of the ADDFITS command. The examples report
only the message structure for each FITS type.
The message is made of the following fields
<FITS Type> Type of FITS log. The following values are valid :
C for FITS comment
E for FITS unexpected event
R for FITS recovery
P for FITS parameter record
CHECH/NO_CHECK Flag that forces logManager to check if the FITS
keyword is valid.
<DICT> Dictionary
<fitsKey FITS Keyword
<value> FITS Value
<comment> FITS Comment
In the following examples all the fields left 'empty' have no
influence on the processing of the message.
FITS Comment message
"C,,,,,,,\"comment 1\""
FITS Event message
"E,,,,,,,\"unforseen event\""
FITS recovery message
"R,,,,,,,\"recovery action\""
FITS action message
"A,NO_CHECK,TCS,TEL.GUID.STOP,,\"Stop Telescope\""
"CHECK,A,TCS,TEL.GUID.STOP,,"
FITS parameter record message
"P,NO_CHECK,LOG,CAT.SYS.PARAM_NAME,-3.8,\"my comment\""
"CHECK,P,LOG,CAT.SYS.PARAM_NAME,-3.8,"
logMonitor is an Xwindows based Tcl/Tk script which allows you to :
- Select beetween the standard VLT log files
- Monitor all incoming new lines from a log file
or to view the whole log file
- Select which portions of the lines shall be displayed
- Filter the lines which shall (or shall not) be displayed
- Produces a program suitable for the Unix AWK utility
A short help text is displayed at the bottom of the window when you move
the pointer over a specific button or other widget.
The utility can take some parameters which specify the log filtering
conditions, such as : environment name , module name, process name, logid.
See CCS User's manual for more details on the use.
<Button-1> Selects the log to perform the operations such as setting
filtering parameters (if Apply Filter is active)
<Double-Button-1> Set the initial 'Date Time'
<Double-Button-2> Set the final 'Date Time'
<Double-Button-3> Set all other filter parameters, such as : module,
environment, process id, process name, etc ..
VLT_LOG_FILES path to the directory containing the log files
VLTROOT path to VLT area
INTROOT path to VLT integration area (optional)
HOME path to user's home directory (optional)
XAPPLRESDIR path to X resource files (optional)
$VLTROOT/app-defaults/XlogMonitor X resource file
$HOME/.logMonitor.out Temporary output file for AWK
$HOME/.logMonitor.awk default name for temporary AWK command file
- INSPECT is very slow for big log files!
- Date/Time filter entry is not checked for correct format (not easy)
- Collector process for filter entry menus does not check for legal values,
no warning if maximum size is exceeded
- Extended help not implemented yet
RTAPENV defines the name of the local environment; inapplicable
to CCS-LITE
NO_ERR_DISPLAY if defined, errors are printed on the standard output;
otherwise errDisplay() is called.
Provides an interactive interface to the logging system.
moduleId module ID (see logData())
logId logging ID; the default value is 0
message message to be logged
msgSchedule enters the local environment and sends the special command
MSGSCHP to the msgServer running in <environment> in order to schedule
a process as specified by the input parameters.
<environment> : environment, where to schedule the process/task
<runstring> : command line to be used to start the process/task
optional parameters (WS/LCU):
<prio/flag> : - WS: flag to be passsed, when scheduling
the process
default value: 0
- LCU: task priority
default value: 100
For more detailed information see
msgScheduleProcess()
optional parameters (LCUs only)
<option> : option to be passed to taskSpawn();
(see taskSpawn());
default value: 0
<stacksize> : requested stacksize;
default value: 20000
<taskname> : requested task name;
default value: see taskSpawn()
>msgSchedule lte8 "msgTestRcv xxx" 100 8 2000 tmsgTestRcv
By this command a process with name tmsgTestRcv on environment
lte8 (VxWorks environment) with priority 100, option 8,
stack size 2000 is started using the command "msgTestRcv xxx".
>msgSchedule wsct1 "msgTestRcv xxx" 2
By this command a process on environment wsct1 (WS)
is scheduled using the command "msgTestRcv xxx".
For detailed information about the option see
msgScheduleProcess().
msgSend enters the local environment, sends the specified <command>
to <process> running in <environment> and waits for reply(ies).
Replies received or/and abnormal events are printed on stdout.
msgSend terminates after the last reply has been received,
the timeout has expired or an abnormal condition is encountered.
<environment> environment where the destination process
is running
<process> name of destination process
<command> command to be sent
<commandPar> command parameter
<time-out> time-out value in milliseconds to wait for reply;
default value: msgNO_TIMEOUT (WAIT FOREVER)
By default msgSend checks the validity of the command.
Hence CDT of the process the message is sent to has to be loaded.
In order to avoid this check the <-n>-option has to be used.
If the PING command is sent and <cmdpar> is undefined
(empty string), msgSend waits <time-out> milliseconds for a reply
from the destination process. If <cmdPar> contains at least one
character, msgSend returns immediately after the command was sent.
This allows to check the existence of processes not using msgRecvMsg().
Examples:
>msgSend -n wsct1 msgServer PING ""
-> msgSend waits for a reply
>msgSend -n wsct1 RtapTimeKeeper PING " "
-> msgSend returns immediately after the
command was sent
msgServer enters the environment and waits forever for
special commands. It should normally be started when the
environment starts and be running as long as the environment
is running.
Special commands handled by msgServer are:
MSGSCHP : By this command the runstring is executed using
the runoptions passed in the message body. It
returns a normal reply on success or an error
reply on failure.
BREAK : By this command the signal SIGUSR1 is sent to the
process passed in the message body. It returns a
normal reply on success or an error reply on failure.
KILL : Same as BREAK, but signal SIGUSR2 is sent.
Any other command will cause the msgServer to return an error reply
to the originator of the request.
The msgServer is started by default in quiet mode. If option -v
is passed the msgServer gives trace of every command received.
This is useful for debugging and troubleshooting.
Two types of errors can occur in msgServer:
- errors when receiving, parsing messages or sending replies.
In this case msgServer creates an error stack and logs
all errors on the stack using errCloseStack(). Then it
continues waiting for the next request.
- errors during execution of a request, e.g.
- the process requested is not active
- scheduling a process failed
In this case msgServer creates an error stack, sends an
error reply to the originator of the request and
continues waiting for the next request.
msgServer1 is used by the CCS msgServer to schedule respectively
send the BREAK/KILL signal to applications within an RTAP environment.
Input parameter:
argv[0] : name of the program
argv[1] : command (MSGSCHP/KILL/BREAK)
argv[2] : sourceUid
Dependent on <command>:
- MSGSCHP: - argv[3] : flag to be passed for
rtScheduleProcess()
- argv[4] : runstring
- KILL/BREAK: -argv[3] : pid of process to be killed
The CCS Scan System Engineering User Interface allows a user
to control and check the functionality of the CCS Scan System
running in the local environment which is (by default) defined
by the RTAPENV environment variable.
The -l option allows to redefine the local environment.
The application area contains the following sections:
"RtapScanMngr"
The status of the RtapScanMngr-process is displayed;
possible values are
- ACTIVE -> RtapScanMngr is running
- NOT_ACTIVE -> RtapScanMngr is not active
"START"
The RtapScanMngr is started
"STOP"
The RtapScanMngr is terminated
"CCS Scan Task"
The status of the CCS Scan Task (ccsScan) is displayed;
possible values are
- ACTIVE -> ccsScan is running
- NOT_ACTIVE -> ccsScan is not active
- FAILED -> RtapScanMngr failed to schedule ccsScan
"START"
The CCS Scan Task is started
"STOP"
The CCS Scan Task is stopped
"Scan Shared Memory"
The size and usage of the Scan Shared Memory Area (SSMA) is displayed;
the SSMA is used to store the data scanned for later (asynchronous)
processing by the calculation engine;
For each attribute to be scanned SSMA-memory is allocated, which is
ONLY freed again by a shutdown of the RtapScanMngr; if the SSMA is
fully occupied, no additional attributes can added to be scanned.
"Environments"
All environments scanned by the local CCS Scan System as well as
their status are displayed;
Selecting an environment (left mouse button) causes the system to
popup a further panel displaying more detailed information about
the system with reference to that environment; for more detailed
information see scaneiEnvStatus.
"Scan Interlock"
The status of the scan interlock is displayed; possible values are
- ACTIVE -> scan interlock is set
- NOT_ACTIVE -> scan interlock is not set
The scan interlock is used by the Scan Manager to coordinate the
control calls from multiple application programs; this interlock
should normally be NOT_ACTIVE; if it is ACTIVE for a longer period
is should be reset; so long as the interlock is set, control requests
as done by scanConfig are not possible.
"Message Queue"
The status of the scan task message queue is displayed; possible
values are
- OK -> everything OK
- OVERFLOW -> messages have been lost by the CCS Scan Task
"Reset"
The "Scan Interlock" and "Message Queue"-status are reset.
"Update"
Causes an update of all data displayed in the panel
"Check Configuration"
Invokes a check of the local Scan System configuration
RTAPENV Name of local environment
VLTROOT Path to the global VLT area
INTROOT Path to a public integration area (optional)
MODROOT Path to a private module area (optional)
This panel displays Scan System information for <environment> and allows
a user to perform requests to the local Scan System referring to
<environment>.
<environment> name of environment scanned
The application area contains the following sections:
"ENVIRONMENT"
The Scan System Status for <environment> is displayed;
possible values are
- ENABLED -> <environment> is currently scanned
- DISABLED -> scanning of <environment> is disabled
- FAILED -> the Scan Task failed to enable scanning
of <environment>
"ENABLE"
Enables scanning of <environment>
"DISABLE"
Disables scanning of <environment>
"Auto-Restart"
The status of the auto-restart mechanism for <environment> is
displayed; possible values are
- ENABLED -> the Scan System tries to restart the scanOut task on
<environment>, if scanOut has been stopped for
some reason
- DISABLED -> the auto-restart mechanism is disabled
"Delay"
The delay in seconds to wait for between two attempts to restart
scanOut is displayed;
"ENABLE"
Auto-restart is enabled
"DISABLE"
Auto-restart is disabled
"Scan Input Table"
A list of the names of all remote attributes currently configured in
the <environment>'s scan input table is displayed;
The configuration parameter of the attribute currently selected
are displayed in the widget below the list; for more detailed
information see scanConfig(1).
"Search for"
Attribute to search for in the list.
"Calculation Engine"
The status of the calculation engine for the attribute currently
selected is displayed; possible values are Enabled, Enabled(optimized),
Disabled and Unknown (if no attribute is selected).
For more information about the CE see RTAP/Plus User's Guide.
"Enable"
The CE for the attribute (point) selected is enabled
"Enable (optimized)"
The CE for the attribute (point) selected is enabled in
optimized mode
"Disable"
The CE for the attribute (point) selected is disabled
"Update"
All data displayed in the panel is updated.
"Check Configuration"
The local Scan System configuration referring to <environment>
is checked.
"Clean Table"
Scanning of <environment> is disabled and all entries in the
scan input table are removed.
"Check Table"
The scan input table is checked for faulty records.
RTAPENV Name of local environment
VLTROOT Path to the global VLT area
INTROOT Path to a public integration area (optional)
MODROOT Path to a private module area (optional)
scanConfig configures the CCS Scan System running in the local
environment to scan attributes from remote databases (WS or LCU).
One can add attributes in the following modes:
POLL: For this mode the PRBX Types in the communication port
point are used for the reporting of remote attribute
values to the local environment. The PRBX type table
has 32 entries containing the polling intervals available.
Any interval is referenced by a so called poll mask
(32 bit mask), the lowest significant bit accords to the
first entry in the PRBX Types table and the most significant
bit to the 32nd entry. The polling interval is the time
between sending two polling buffers from remote scanOut
task to local ccsScan task.
SRBX: For this mode a polling buffer is sent from the remote
scanOut task to the local ccsScan task, always when a
value is changed. The polling buffer contains the scan
input table entry number and the value of the changed
attribute.
Input parameters:
<localAttr> Name of the attribute receiving the value.
<remoteAttr> Name of the attribute where the value has to
come from. MUST CONTAIN THE ENVIRONMENT NAME.
<mode> Data acquisition mode. Possible values are:
- POLL (poll data)
- SRBX (report on change)
- DEL, is used to delete an entry
<period> Polling interval in seconds to be used for the attribute.
<type of deadband> Deadband type. Possible values are
- 0 means absolute value
- 1 means percentage
- 2 means no deadband
<deadband> Deadband value
Both attributes have to be specified by their symbolic name.
Attributes can be scanned in the following way:
Modes Deadband-type Destination-
Attribute
-------- --------- ------------------ -----------
Scalars SRBX/POLL 0 or 1 (numerical) Scalar
2 (all types)
-------- --------- ------------------ -----------
Vectors
1 record SRBX/POLL 0 or 1 (numerical) Scalar
2 (all types)
several
records SRBX/POLL 2 Vector
-------- --------- ------------------ -----------
Tables
1 field SRBX/POLL 0 or 1 (numerical) Scalar
2 (all types)
1 column SRBX/POLL 2 Vector
Scan attribute A01 of the remote environment TE21 in POLL mode
with an interval of 20 seconds
> scanConfig \<alias\>data:scan_test.A01 \@TE21:data:scan_test.A01 poll 20
Scan attribute A11 of the remote environment TE21 in SRBX mode
with no deadband:
> scanConfig \<alias\>data:scan_test.A11 \@TE21:data:scan_test.A11 srbx 2 0
Scan column 9 of table attribute A11:
> scanConfig \<alias\>data:scan_test.A11 \@TE21:data:scan_test.A11(0:9,8:8) poll 1
(Attribute A11 on the local environment must be a VECTOR)
Stop scanning of attribute A01 of the remote environment TE21:
> scanConfig \<alias\>data:scan_test.A01 \@TE21:data:scan_test.A01 del
The first attribute name is always local and thus does not require
an environment name.
The second one (source of data) is normally remote and requires
an environment name.
NEVER STOP scanConfig DURING EXECUTION. Otherwise the scan system
could get into a suspect status.
In order to delete an scan entry the remote attribute name has to be identical
to the one used to establisch the scan link.
It is possible to scan the same remote attribute more than once using different
symbolic addressing mode (and different destination attributes). However this
might have unexpected side effects; accordinlgy it is recommended not to use this
feature.
-p <point name> name of database point for which to
enable/disable calculation engine
-e enable calculation engine
-o enable calculation engine (optimized)
(for more information see RTAP User Manuals)
-d disable calculation engine
scanCreateFile creates a file defining all scan links currently existing
in the local environment for <environemt>. This file can be used as
input for the utilities scanLinks, scanLinksEnable and scanLinksDisable.
-e <environment> environment to be scanned
-o <output file> output file; if not defined the output
is redirected to <stdout>
-a directs scanCreateFile to append data to
<output file>
RTAPENV name of local environment
NO_ERR_DISPLAY controls whether in case of an error
errDisplay() will be started or not.
scanDevOff disables scanning of the environment specified by <env>.
-l <local environment> : optional environment name where to run.
the optional value overrides the default $RTAPENV.
<env> <IN> : environment (device) name.
Must come after the facultative option -l if present.
>scanDevOff lte8
By this command scanning of environment <lte8> is disabled from the current
environment defined in $RTAPENV
>scanDevOff -l wt0tcs lte8
By this command scanning of environment <lte8> is disabled in the
environment wt0tcs.
scanDevOn enables scanning of the environment specified by <env>.
If a local environment is specified with the option -l, the process
attaches to that one rather than the default taken from $RTAPROOT
<local Environment> : name of the local environment where the process
will run.
<env> <IN> : environment (device) name
NOTE: Successful completion of this program means only, that
the initialization procedure for a device has been started
successfully. The current status of a device can be checked
by the attribute 'scan input status' part of the scan device
point (scan config:LAN:<scanned environment>.scan input status).
scanDisable disables scanning of all attributes specified in
the command line. The -l option can be used to run the process
into an environment different from the one specified in $RTAPENV
local env <IN> : option to specify the environment to attach to.
attribute_.. <IN> : symbolic name of an attribute
NOTE: This function uses the CCS Scan System interface function
scanDisableAttr(). This function does not stop on an error.
It always tries to disable scanning of all attributes specified.
scanEnable enables scanning for all attributes specified in
the command line.. The -l option can be used to run the process
into an environment different from the one specified in $RTAPENV
local env <IN> : option to specify the environment to attach to.
attribute_.. <IN> : symbolic name of an attribute
NOTE: This function uses the CCS Scan System interface function
scanEnableAttr(). This function does not stop on an error.
It always tries to enable scanning of all attributes specified.
scanGetStatCE - get calculation engine operation indicator
The -l option can be used to run the process
into an environment different from the one specified
in $RTAPENV
scanGetStatCE returns the status of the calculation engine of
<point name> in the database of the environment specified with the -l option,
or the default one specified by the $RTAPENV environment variable.
<local env> option to specify the environment to attach to.
<point name> name of database point for which to return status
The following states are returned:
- DISABLED
- ENABLED
- ENABLED_OPT
scanOn disables the communication port <port name> in the default
environment ($RTAPENV) or in the environment specified with the -l option.
local env <IN> : option to specify the environment to attach to.
<portName> <IN> : communication port name (optional)
If no <portName> is specified
'LAN' is used as the default.
NOTE: For the CCS Scan System only one communication port
(called LAN) exists.
The current status of a comm-port can be checked by
the attribute 'status' part of the comm-port point
(scan config:LAN.status).
scanOn enables the communication port <port name> in the default
environment($RTAPENV) or in the one specified with the -l option.
local env <IN> : option to specify the environment to attach to.
<portName> <IN> : communication port name (optional)
If no <portName> is specified
'LAN' is used as the default.
NOTES: For the CCS Scan System only one communication port
(called LAN) exists.
Successful completion of this program means only, that
the initialization procedure for a comm-port has been
started successfully. The current status of a comm-port
can be checked by the attribute 'status' part of the
comm-port point (scan config:LAN.status).
The scanOut task is the counterpart of ccsScan and started by
the scan initialization task ccsScanInit. Its purpose is to acquire
the data of all attributes scanned in a remote environment.
In each environment scanned there may only run one instance of
the scanOut task, accordingly any environment (WS/LCU) may only
be scanned by ONE other environment.
Input parameters:
<environment> name of scanning environment
The main data structure used by the scanOut task is the scan output table,
stored in <alias>LAN:<environment>. A record is built up in the
following way:
point control : Control if a point has to be scanned (control = 1)
or not. This value is written by the scanOut task
during negociation with ccsScan.
point status : Reflects the result of the negociation between
ccsScan and scanOut.
reserved1 : Not used
element count : Size in bytes of attribute.
start address : Not used (might be used later on for offset in the
received buffer if a fixed format is used.)
ORG ID : Not used
DBNR : Not used
reserved2 : Not used
bit position : Not used
poll type mask: Used to code the polling period.
deadband type : Controls deadbanding: 0 means absolute or value.
1 means Percentage deadbanding.
2 means no deadbanding.
deadband : Deadband value according to its type definition.
link address : Local internal address of attribute.
eventId : Ihe event ID associated to a SRBX entry. (as returned
by the rtAttachDbevent in the rtEventId.event. The
environment name is not kept, as it is always the
local one.)
scanIn_num : Index in the remote scan input table.
reserved3 : Not used
scanLinks [-c] [-E | -d] [-o] [-l <loc env>] -e <rem env> -f <input file>
[-s <source root>] [-r <destination root>]
scanLinks is a program to establish scan links defined in a file.
A scan-link is defined in the following way
<destination> <source> <mode> <period/SRBX mode> <deadband>
with
<destination> name of attribute receiving the data (local)
<source> name of source attribute (remote);
the names must not include an environment name.
The names can be given relative to a root point
that will be passed as a run time parameter with
the options -s & -r.
<mode> data acquisition mode: POLL or SRBX
<period/SRBX mode> either polling interval in seconds (POLL)
or deadband type (SRBX): - 0 -> absolute value
- 1 -> percentage
- 2 -> no deadband
<deadband> deadband value
NOTE: The attribute names MUST NOT include an environment name.
Examples:
<alias>scan_1.C01 <alias>scan_test.C01 POLL 60
<alias>scan_1.C02 <alias>scan_test.C02 SRBX 1 20.39
If you want to create scan-links off-line
- the source attributes have to be defined by their ALIAS
- type and number of records of the source attributes
to be scanned have also to be defined
Examples:
<alias>scan_1.SCALAR <alias>scan_test.SCALAR POLL 60 dbUINT8 1
<alias>scan_1.VECTOR <alias>scan_test.VECTOR SRBX 2 dbDOUBLE 10
The data-type names are defined in $VLTROOT/include/db.h.
If a line starts with # it is treated as a comment.
-f <input file> specifies the file to be processed
-l <loc env> specifies the local environment. by default $RTAPENV.
-e <rem env> remote environment to be scanned
-c if defined, scanLinks doesn't stop
if an error occurs. scanLinks won't report failure
on termination in case of:
- link to be deleted not found
- link to be added/enabled already exists/enabled
-d directs scanLinks to remove the scan-links
defined in <input file>
-o directs scanLinks not to connect to the remote
environment, the system is only configured
locally
-E causes scanLinks to enable scanning for
new links; this option can not be used in
conjunction with the -o option
-s <source root> defines a root point below wich the source attributes
are located. Must be given by ALIAS which will be
pre-pended before each source attribute name in the
file.
-r <destination root> defines a root point below wich the destination
attributes are located. Must be given by ALIAS
which will be pre-pended before each destination
attribute name in the file.
Scan-links configured off-line can be enabled using the tool
scanLinksEnable.
RTAPENV name of local environment
NO_ERR_DISPLAY controls whether in case of an error the
errDisplay() will be started or not.
>scanLinks -e lte23 -f input.dat -o
all scan-links defined in the file input.dat are established off-line,
scanning of the attributes remains disabled
>scanLinks -e lte23 -f input.dat -E
all scan-links defined in the file input.dat are established on-line,
scanning of the attributes is enabled
In order to delete an scan entry the remote attribute name has to be identical
to the one used to establisch the scan link.
It is possible to scan the same remote attribute more than once using different
symbolic addressing mode (and different destination attributes). However this
might have unexpected side effects; accordinlgy it is recommended not to use this
feature.
scanLinksDisable disables scanning for all attributes defined in
the scan link definition file. It does it in the default(RTAPENV)
environment or the one specified with the -l option.
The -r option is used to specify a root point prefix to be pre-pended
before every destination attribute name.
RTAPENV name of local environment
NO_ERR_DISPLAY controls whether in case of an error the
errDisplay() will be started or not.
scanLinksEnable enables scanning for all attributes defined in
the scan link definition file. It does it in the default(RTAPENV)
environment or the one specified with the -l option.
The -r option is used to specify a root point prefix to be pre-pended
before every destination attribute name.
RTAPENV name of local environment if not given with -l option
NO_ERR_DISPLAY controls whether in case of an error the
errDisplay() will be started or not.
scanSsma prints on stdout the
- total size of the SSMA
- remaining size of spare SSMA
in the local environment.
scanTblClean is a utility to be used to check the scan input table
or remove records from the scan input table. The scan input table is
checked in the default ($RTAPENV) environment, or in the one specified
with th -l option.
-e <environment> for which to check/clean the scan input table
-l <local environment> environment to attach to.
-s if specified, the scan input table is checked for faulty records;
if one is found an error message is printed to stdout in the
following form
{record-Number {{local attribute} {remote attribute}} {error-reason}}
and the check is continued.
-c if defined, scanning for <environment> is disabled and all entries
specified by the r-option are removed from the corresponding
scan input table
-r <record> specifies the records to be deleted; the records have to be
specified in a string separated by commas:
e.g. -r "23,56,74" -> records 23,56 and 74 are removed
NOTE: The first record is specified by "0"
timsDate enters the local environment and returns the system time
and mode.
-m <mode> will set the tims in the mode specified. The following
arguments are allowed:
"timUTC","timsLOCAL", "timsSIMULATION"
-t "time" will set the time, but only if the system is running in
simulation mode. Currently only timsABS_TIME format is
supported, where time has to be defined as follows
"YYYY-MM-DDThh:mm:ss.uuuu"
or
"YY-MM-DD hh:mm:ss.uuuu"
The old time format not including the century is only
supported for backwards compatibility reasons and should
not be used anymore in new applications.
However if a user passes the time in the old format, the
following rule is applied. Values in the range [69-99] refer
to years in the twentieth century (1969-1999), and values
in the range [00-68] refer to the twenty-first century
(2000-2068).
-e <rtapenv> will set RTAPENV to rtapenv.
EXIT_SUCCESS (0) if success
EXIT_FAILURE (1) if failure
and the standard CCS error structure is printed on stdout.
3.2 Callable Interface
CCS Alarm System API functions to request connnection and
disconnection, from an application to the alarm server.
The parameters are:
<IN> alrmCONN *con : The connection request
<IN> ccsERROR *error : a standard CCS error stack used for
error handling inside the function
The alrmCONN structure holds all components of a connection:
<IN> unsigned char *alrmCon_Env
Environment name for the request.
<IN> unsigned char *alrmCon_Branch
Database branch from where to collect alarms.
<IN> unsigned short alrmCon_Filter
Severity levels to be notified by the connection.
<OUT> short alrmCon_Id
Identifier of the connection ( -1 Close, 0,....,n Open).
Used later to identify from which application connection
is an alarm message is arriving.
The request for attaching or detaching not issued due to errors
The actual errors are contained in the ccsERROR *error stack.
alarmAttach and alrmDetach are asyncronous functions. They
return inmidiatly after the call. The actual conection or
disconection event is signaled to the application via an
"Alarm Management" type message arriving later.
See alrmParseMsg man page for more details on the "Alarm
Management" messages.
#include "alrm.h"
ccsCOMPL_STAT st;
con.alrmCon_Env = "wsv1";
con.alrmCon_Branch = ":";
con.alrmCon_Filter = FATAL | NORMAL;
st = alrmAttach( c,error );
.
.
.
st = alrmDetach( c,error );
For an extended example see alrmApiTest.c on the test
directory of the module.
alrmParseMsg() CCS Alarm System API function.
CCS Alarm System Design Description VLT-SPE-ESO-17210-0782
CCS User Manual, Alarm System,chapter VLT-MAN_ESO-17210-0619
CCS Alarm System API test programs.
API function to parse an alarm message. This function parse an
alarm message into the alrmALARM structure which holds all the
information of an alarm related event.
Applications connected to the alarm system ( via alrmAttach() )
receive alarm related events in standard CCS messages. The
messages types are:
Alarm Notification msgTYPE_ALARM
Alarm Management msgTYPE_ALARM_CONN
Alarm Management messages inform about the status of a connection to the
alarm system ( see alrmAttach() alrmDetach() ). One standard CCS message
can hold only one "Alarm Management message"
Alarm Notification messages are actual alarms ocurring on any of the
environments connected to the application ( via alarmAttach() ). One
standard CCS message can hold more than just one alarm notification.
alarm notifications and management are parsed by alrmParseMsg
The parameters are:
<IN> msgHEADER *msg : The alarm message.
<IN> alrmALARM *alarm : An allocated alrm structure to hold
the parsed output.
<OUT>vltUINT16 *another : a value that indicates if there was
a notification inside the message.
<IN> ccsERROR *error : a standard CCS error stack used for
error handling inside the function.
A first call to alrmParseMsg with the msgHEADER *msg returns the parsed
alarm on alrmALARM. If there was an "alarm message" inside the given
standard message msgHEADER *msg, the parameter "another" will be set
by the function call to :
alrmMSG_MORE
To parse the following "alarm messages" alrmParseMsg should be continuosly
called with the msgHEADER *msg parameter set to NULL.
When the function does not find an "alarm messages" inside the given
message, the parameter *another is set ( inside the function call ) to :
alrmMSG_NOMORE
The alarmALARM structure can hold either an "alarm notification" or a
"connection management" message. It contains:
unsigned char * alrmMsg_Env:
Environment of the incoming alarm.
unsigned char * alrmMsg_Point:
Database point of the incoming alarm.
unsigned char * alrmMsg_Attribute:
Database attribute name ( .i.e. process value ) where
the alarm has ocurred.
unsigned char * alrmMsg_AttrValue:
Area with the actual value of the previous attribute.
short alrmMsg_AttrPlin:
Attribute PLIN.
short alrmMsg_AttrAin:
Attribute AIN.
long alrmMsg_AttrSize:
Size in bytes of the attribute.
vltUINT8 alrmMsg_AttrType;
Attribute type.
vltUINT16 alrmMsg_Severity;
Severity level of the incoming alarm.
vltUINT8 alrmMsg_Scope;
Scope of the incoming alarm ( LOCAL, GLOBAL )
vltUINT32 alrmMsg_Timeout;
Timeout of the incoming alarm ( only for LOCAL alarms )
short alrmMsg_SourceConnId;
Source connection identification. Used to identify
from what ( of all opened ) connection is the alarm
coming.
vltUINT8 alrmMsg_ConnAction;
Set only when the parsed message is of type "connection
managenment". A connection managenment message informs
the application about events on the stablished connections
to the alarm system ( via alrmAttach() ). This events are:
alrmMSG_CONN_OPEN:
Connection successfully stablished.
alrmMSG_CONN_CLOSE:
Connection has been closed.
alrmMSG_CONN_SHUTDOWN:
Connection closed due to alarm system shutdown.
unsigned short alrmMsg_IsAck;
Not Used in this release.
unsigned char * alrmMsg_Message;
The full message displayed by the Alarm Display
utility. It contains. It contain the time, scope,
attribute name and value, and severity level for
the incoming alarm.
An error has ocurred during the parsing of the message.
The actual error is contained in the ccsERROR *error stack.
The allocation and deallocation of the structure alrmALARM with all
internal buffers must be handled by the calling application.
#include "alrm.h"
ccsCOMPL_STAT st;
msgHEADER *msg;
ccsERROR error;
vltUINT16 another;
.
.
while ( msgRecvMsg(..) )
{
switch( msgtype )
{
case msgTYPE_ALARM:
st = alrmMsgParse(msg,&a,&another,&error);
while ( another == alrmMSG_MORE )
//An alarm notification received
//do something with it..........
//then..........................
//look for more
st = alrmMsgParse(NULL,&a,&another,&error);
break;
case msgTYPE_ALARM_CONN:
st = alrmMsgParse(msg,&a,&another,&error);
break;
}
}
For an extended example see alrmApiTest.c on the test
directory of the module.
CCS Alarm System Design Description VLT-SPE-ESO-17210-0782
CCS User Manual, Alarm System,chapter VLT-MAN_ESO-17210-0619
CCS Alarm System API test programs.
The following information is provided for on-line help.
It is copied from the ccs include files which are the only
valid reference.
#define ccsENVNAME_LEN 7 /* max. length of an environment name */
#define ccsPROCNAME_LEN 19 /* max. length of a process name */
#define ccsMODULEID_LEN 7 /* max. length of a module name */
/* 6 characters + 1 byte alignement */
#define ccsCMD_LEN 7 /* max. length of a command */
#define ccsLOCID_LEN 80 /* max. length of a location specification */
#define ccsFALSE 0 /* Definitions according to VxWorks rules */
#define ccsTRUE 1
#define ccsMAX_DE_TO_STR_CHARS ((256 * 4) + 1)
/*
* CCS Data Types
*/
typedef char vltINT8; /* 8 bits integers */
typedef unsigned char vltUINT8; /* 8 bits unsigned integers */
typedef short vltINT16; /* 16 bits integers */
typedef unsigned short vltUINT16; /* 16 bits unsigned integers */
typedef int vltINT32; /* 32 bits integers */
typedef unsigned int vltUINT32; /* 32 bits unsigned integers */
typedef unsigned char vltLOGICAL; /* logical (rtLogical) */
typedef double vltDOUBLE;
typedef float vltFLOAT;
typedef struct { /* Polar data type */
vltDOUBLE magnitude;
vltDOUBLE phase;
} vltPOLAR;
typedef struct { /* Rectangular data type */
vltDOUBLE real;
vltDOUBLE imaginary;
} vltRECTANGULAR;
typedef unsigned char vltBYTES4[4];
typedef unsigned char vltBYTES8[8];
typedef unsigned char vltBYTES12[12];
typedef unsigned char vltBYTES16[16];
typedef unsigned char vltBYTES20[20];
typedef unsigned char vltBYTES32[32];
typedef unsigned char vltBYTES48[48];
typedef unsigned char vltBYTES64[64];
typedef unsigned char vltBYTES80[80];
typedef unsigned char vltBYTES128[128];
typedef unsigned char vltBYTES256[256];
typedef char ccsENVNAME[ccsENVNAME_LEN+1]; /* Environment(Node) name */
typedef char ccsPROCNAME[ccsPROCNAME_LEN+1]; /* Process name */
typedef unsigned char ccsPROCNUM; /* Process number */
typedef char ccsMODULEID[ccsMODULEID_LEN+1]; /* Software module name */
typedef char ccsLOC_ID[ccsLOCID_LEN+1]; /* Subroutine identifier */
/*
* Error Structure Definition. It is formed by two parts
* - Information on the stack location
* - Routine dependent error parameters
*/
typedef union {
struct {
vltUINT16 hostId; /* host identification: 16 lower bits */
/* of internet address */
vltUINT16 localNumber; /* local stack sequence number */
} local;
vltUINT32 id; /* Complete stack id */
} ccsSTACK_ID;
typedef struct { /* Returned error structure */
ccsENVNAME envName; /* Where to log errors for this stack */
ccsSTACK_ID stackId; /* on which stack */
vltUINT16 sequenceNumber; /* Sequence number in the stack */
ccsLOC_ID location; /* Location where the error occurred : */
/* - Subroutine, Function, etc .. */
ccsMODULEID moduleId; /* Addresses the error messages file */
vltINT16 errorNumber; /* Addresses the right message */
vltBYTES256 runTimePar; /* Run Time Information about the error */
} ccsERROR;
/*
* Definition of the routine completion status
*/
typedef enum {
FAILURE = 1, /* */
SUCCESS /* */
} ccsCOMPL_STAT; /* Completion status returned by subroutines */
/*
* CCS time structure
*/
typedef struct {
unsigned long tv_sec; /* seconds since midnight January 1,1970 UTC*/
long tv_usec; /* and microseconds */
} ccsTIMEVAL;
/*
* Environment types
*/
typedef enum {
ENV_UNKNOWN = 1, /* Environment specification not recognized */
WS, /* Environment type = Workstation */
LCU /* Environment type = LCU */
} ccsENV_TYPE; /* List of Environment Type */
/*
* Data structure run options to schedule a process.
* Depending if destination environment is unix or VxWorks a
* union is used.
*/
typedef struct { /* VxWorks Task options */
vltUINT32 priority; /* Task priority */
vltUINT32 options; /* Task options */
vltUINT32 stacksize; /* Stack size */
char *taskname; /* Pointer to task name */
} ccsVXWORKS_OPTIONS;
typedef struct { /* Unix Process Options */
vltINT32 flags;
} ccsUNIX_OPTIONS;
typedef union { /* Combined definition */
ccsVXWORKS_OPTIONS vxto;
ccsUNIX_OPTIONS unixto;
} ccsRUNOPT;
/* Booking stuff is obsolete since 200011 */
typedef vltUINT32 bookUCODE; /* UserCode for booking checks.*/
/*
* Field descriptor data type (for tables).
*/
typedef rtTableField dbFIELD;
/*
* Database handle data type
*/
typedef rtDbConnection dbHANDLE;
/*
* Database view specifier
*/
typedef enum {
VIEW_UNKNOWN = 1, /* Database view not recognized */
ALIAS, /* Point address is an alias */
RELATIVE, /* Point address is relative to .. */
ABSOLUTE /* Point address is absolute */
} dbVIEW; /* List of RTAP defined views */
/*
* Residence flag for a Point's values
*/
#define dbRAM 0
#define dbDISK 1
typedef vltUINT8 dbRESIDENCE;
/*
* Direct address specification level. The first value is not a valid direct
* address type, but can be used to mark an DB_XREF as invalid or unused.
*/
#define dbDIR_INVALID 0
#define dbDIR_PLIN 1
#define dbDIR_AIN 2
#define dbDIR_REC 3
#define dbDIR_FIELD 4
/*
* types of attributes
*/
#define dbSCALAR 0
#define dbVECTOR 1
#define dbTABLE 2
typedef vltUINT8 dbATTRTYPE;
/*
* element types.
*/
#define dbUNDEFINED ((dbTYPE) 0)
#define dbLOGICAL ((dbTYPE) 1)
#define dbINT8 ((dbTYPE) 2)
#define dbUINT8 ((dbTYPE) 3)
#define dbINT16 ((dbTYPE) 4)
#define dbUINT16 ((dbTYPE) 5)
#define dbINT32 ((dbTYPE) 6)
#define dbUINT32 ((dbTYPE) 7)
#define dbFLOAT ((dbTYPE) 8)
#define dbDOUBLE ((dbTYPE) 9)
#define dbPOLAR ((dbTYPE) 10)
#define dbRECTANGULAR ((dbTYPE) 11)
#define dbBYTES4 ((dbTYPE) 16)
#define dbBYTES8 ((dbTYPE) 17)
#define dbBYTES12 ((dbTYPE) 18)
#define dbBYTES16 ((dbTYPE) 19)
#define dbBYTES20 ((dbTYPE) 20)
#define dbBYTES32 ((dbTYPE) 21)
#define dbBYTES48 ((dbTYPE) 22)
#define dbBYTES64 ((dbTYPE) 23)
#define dbBYTES80 ((dbTYPE) 24)
#define dbBYTES128 ((dbTYPE) 25)
#define dbBYTES256 ((dbTYPE) 26)
#define dbXREF ((dbTYPE) 28)
#define dbDATE ((dbTYPE) 29)
#define dbTIME_OF_DAY ((dbTYPE) 30)
#define dbABS_TIME ((dbTYPE) 31)
typedef vltUINT8 dbTYPE;
typedef rtDbXref DB_XREF;
#define dbITEM_LEN 255 /* Max len for an attribute specification */
#define dbMAX_ATTR_CNT 255 /* max number of attributes per point */
#define dbMAX_FIELD_CNT 255 /* Max number of fields for a table */
#define dbFIELDNAME_LEN 19 /* Max len for a field name */
#define dbMAX_CHILDREN 255 /* from rtMAX_CHILDREN */
/* String containing the hierarchical symbolic address, including record */
/* and field information according to the naming rules. */
/* Addressing with alias is included in the symbolic addressing by prefixing*/
/* the symbolic address with the view specifier <alias> */
typedef char dbSYMADDRESS[dbITEM_LEN+1];
typedef char dbATTRIBUTE[dbITEM_LEN+1]; /* Name of the attribute */
/* including range */
typedef char *dbITEM; /* To be compatible with LCC */
typedef char dbFIELDNAME[dbFIELDNAME_LEN+1];
typedef struct { /* Direct point specification */
vltUINT16 plin; /* Point internal number (rtPlin) */
vltUINT8 ain; /* Attribute internal number (rtAin) */
vltUINT8 reserved;
vltUINT16 startRec; /* First record to be accessed */
vltUINT16 endRec; /* Last record to be accessed */
vltUINT8 startField; /* First field to be accessed */
vltUINT8 endField; /* Last field to be accessed */
} dbPOINT;
typedef struct { /* Direct address */
vltUINT16 addrLevel; /* Addressing Level */
vltUINT16 reserved;
dbPOINT pointId; /* Point Specification */
} dbDIRADDRESS;
/*
* The event filter mask defines how the event is triggered.
* For SCALARS the event can be triggered by comparing old and new values
* according to the event mask.
*
* For VECTORS and TABLES an event is triggered at every write
*
*/
typedef enum {
evtLESS = 1,
evtEQUAL,
evtLESS_OR_EQUAL,
evtGREATER,
evtNOT_EQUAL,
evtGREATER_OR_EQUAL,
evtANY_WRITE,
evtDEAD_BAND
} evtFILTER;
typedef struct {
ccsENVNAME envName; /* Environment where the event occurred */
vltINT32 eventNum; /* Event Number */
vltUINT8 reserved; /* Event filter mask (not used on LCU) */
vltUINT8 fill[3]; /* padding bytes */
} evtEVENT_ID;
typedef struct { /* Information returned with an event */
/* associated to a SCALAR attribute */
dbTYPE dataType;
vltUINT8 oldQuality;
vltUINT8 newQuality;
vltUINT8 fill;
char oldValue[256];
char newValue[256];
} evtSCALAR_INFO;
typedef struct { /* Information returned with an event */
/* associated to a VECTOR attribute */
vltUINT16 startElem;
vltUINT16 endElem;
} evtVECTOR_INFO;
typedef struct { /* Information returned with an event */
/* associated to a TABLE attribute */
vltUINT16 startElem;
vltUINT16 endElem;
vltUINT8 startField;
vltUINT8 endField;
} evtTABLE_INFO;
typedef union { /* General structure with the event */
/* information */
evtSCALAR_INFO scalar;
evtVECTOR_INFO vector;
evtTABLE_INFO table;
} evtDATA;
/*
* Message formats
*/
typedef struct { /* Reply for EVTATT and EVTREQP */
/* commands */
evtEVENT_ID eventId; /* Event identifier */
evtFILTER trigCond; /* Condition that generated the */
/* event */
ccsPROCNUM procNum; /* Process that generated the event */
dbSYMADDRESS attrName; /* Name of the attribute that */
/* generated the event */
dbATTRTYPE type; /* Attribute type */
evtDATA eventInfo; /* Event info */
} evtEVTREQ_REPLY;
typedef struct { /* Reply to EVTREQA command */
evtEVENT_ID eventId; /* Event identifier */
evtFILTER trigCond; /* Condition that generated event */
ccsPROCNUM procNum; /* Process that generated the event */
dbSYMADDRESS attrName; /* Name of the attribute for which */
/* event is generated */
dbTYPE type; /* Type of attribute */
vltUINT16 alarmNumber; /* Alarm number */
alarmSTATUS oldStatus[2]; /* Old alarm status */
alarmSTATUS newStatus[2]; /* New alarm status */
char oldValue[16]; /* 16 bytes is large enough to hold */
char newValue[16]; /* the biggest data types for which */
/* alarms can be requested: */
/* vltPOLAR or vltRECTANGULAR */
} evtEVTREQA_REPLY;
#define logMAX_LEN 256 /* max. length of a log */
#define logTEXT_LEN 176 /* max. length of the user part of the log */
#define logSYS_LEN 80 /* max. length of the system part of the log */
/*
* Define logId for Automatic logs of specific modules
*/
#define logAUTO_RANGE 60 /* logs with 0 < Id < 50 are automatic */
#define logAUTO_MSG 20 /* Message System Automatic logs */
#define logAUTO_DB 21 /* Database Automatic logs */
#define logAUTO_SCAN 22 /* Scan System Automatic logs */
#define logAUTO_USR1 58 /* User defined */
#define logAUTO_USR2 59 /* User defined */
/*
* Define LogId for specific CCS/LCC modules
*/
#define logLOG (1 + logAUTO_RANGE)
#define logERR (2 + logAUTO_RANGE)
#define logSCAN (3 + logAUTO_RANGE)
#define msgMAXLEN 8192 /* max length for a complete message */
/*
* CCS message types, mapped in the user domain of the Rtap range.
*/
#define msgTYPE_COMMAND 129
#define msgTYPE_REPLY 130
#define msgTYPE_ERROR_REPLY 131
#define msgTYPE_REQUEUED 132
#define msgTYPE_SIMREPLY 133
#define msgTYPE_BOOK_REQUEST 134 /* booking obsolete with 200011 */
#define msgTYPE_SCAN_OFFSET 139
#define msgTYPE_NEXT_FREE 150
/*
* CCS message types equivalent to existing Rtap types.
* list to be upgraded according to recognized needs.
*/
#define msgTYPE_TIMER 65
#define msgTYPE_EVENT 66
#define msgTYPE_OBITUARY 67
#define msgTYPE_ALARM 75
#define msgTYPE_ALARM_CONN 76
#define msgNO_TIMEOUT 0 /* wait forever for msg */
#define msgNO_WAIT -1 /* don't wait for msg */
#define msgANY_MESSAGE 0 /* list of filter types */
#define msgANY_REPLY 1
#define msgREPLIES_FROM 2
#define msgREPLY_FOR_CMD 3
#define msgREPLY_FOR_CMDID 4
/*
* CCS check flag types of msgCHECKFLAG bitmask
*/
#define msgNO_CHECK 0x00
#define msgCHECK_PREBOOK 0x01 /* Booking obsolete with 200011 */
#define msgCHECK_CMD 0x02
#define msgCHECK_ALL 0xFF
/*
* Data types
*/
typedef char msgCMD[ccsCMD_LEN+1]; /* Command name: UPPER CASE ALWAYS! */
typedef vltUINT16 msgCMDID; /* command identifier */
typedef vltINT32 msgPRIORITY; /* message priority */
typedef vltINT32 msgLENGTH; /* message length */
typedef vltUINT8 msgCHECKFLAG; /* 8 bits mask defines checks to be */
/* performed. */
typedef vltINT32 msgTIMEOUT;
typedef vltUINT8 msgFILTERTYPE;
typedef struct {
ccsENVNAME envname;
ccsPROCNUM procnum;
vltUINT8 reserved;
} msgPROCESSID; /* Identifies a unique process */
typedef struct {
msgFILTERTYPE accept;
msgCMDID commandId; /*only if accept=msgREPLY_FOR_CMDID */
msgCMD command; /*only if accept=msgREPLY_FOR_CMD */
msgPROCESSID source; /* Meaningful only if accept */
/* = msgREPLIES_FROM */
} msgRECEIVEFILTER;
typedef struct {
msgPRIORITY priority; /* Internal use only */
msgPROCESSID source; /* Sender of the message */
msgPROCESSID dest; /* Recipient */
vltINT32 sourceUId; /* User Id */
msgCMDID msgId; /* To distinguish identical commands */
vltUINT8 msgType; /* Defined by message system */
vltUINT8 responseFlag; /* Command/Reply */
vltINT32 typeHdrSize;
vltINT32 msgBodySize;
} msgHEADER; /* 1st part of the message header */
/* (fixed) */
/*
* Depending on msgType, a second header, having the size indicated in
* typeHdrSize follows. It has the following composition, according to
* msgType :
*/
/*
* msgType = msgTYPE_COMMAND : Normal commands
*/
typedef struct {
bookUCODE bookingId; /* Added by message system when */
/* sending. Obsolete with 200011 */
vltUINT32 unused; /* replacement for bookingId */
msgCMD command; /* As provided by the user */
ccsTIMEVAL timeStamp; /* ~Unix timeval=8 bytes */
msgTIMEOUT timeout; /* Number of seconds, future */
/* extension */
} msgCOMMAND;
/*
* msgType = msgTYPE_REPLY : Normal replies
*/
typedef struct {
msgCMD command; /* The commandId is in header_1 */
ccsTIMEVAL timeStamp; /* ~Unix timeval=8 bytes */
vltLOGICAL lastReply; /* Flag TRUE if it is last reply */
} msgREPLY;
/*
* msgType = msgTYPE_ERROR_REPLY : Error replies
*/
typedef struct {
msgCMD command; /* The commandId is in header_1 */
ccsTIMEVAL timeStamp; /* ~Unix timeval=8 bytes */
} msgERROR_REPLY;
/*
* msgType = msgTYPE_REQUEUED : Requeued message
*/
typedef struct {
ccsTIMEVAL timeStamp; /* Time of requeuing */
} msgREQUEUED;
/*
* msgType = msgTYPE_OBITUARY : RTAP obituary message
*/
typedef struct {
vltINT32 exitStatus; /* how it terminated */
msgPROCESSID deceased; /* process that died */
/* deceased proc_num : positive if */
/* process obituary, 0 if environment*/
/* obituary */
ccsPROCNAME procName; /* process Name of the dead process */
vltINT8 restart; /* will it be restarted */
vltINT8 debug; /* did it register for debug */
vltUINT8 reserved[4];
} msgOBITUARY;
typedef union {
msgCOMMAND command;
msgREPLY reply;
msgERROR_REPLY errorReply;
msgREQUEUED requeued;
msgOBITUARY obi;
} msgHEADER2; /* Type dependant header */
#if defined(CCS_LIGHT) && !defined(__hp9000s700) && !defined(MAKE_VXWORKS)
# define msgBODYMAXLEN (5120 - sizeof(msgHEADER) - sizeof(msgHEADER2) - 1)
#else
# define msgBODYMAXLEN (msgMAXLEN - sizeof(msgHEADER) - sizeof(msgHEADER2) - 1)
#endif
typedef struct { /* The complete ccs message */
msgHEADER msgHeader;
msgHEADER2 type;
char body [msgBODYMAXLEN];
} msgMSG;
/* structures and defines for socket connection */
#define msgSOCK_SIZE 32768
#define msgCONNECT_CMD "MSGOCON"
/*
* REMARK: MAXHOSTNAMELEN should be used instead of 256, but
* for SUN/HP and VxWorks this literal is defined in
* different header files
*/
typedef struct {
char hostname[256];
int ipAddr;
msgPROCESSID procId;
int fd;
} msgSOCK_DESC;
typedef enum {
timsDATE = 1, /* yy-mm-dd The date at midnight at the */
/* beginning of that day. */
timsTIME_OF_DAY, /* hh:mm:ss.uuuuuu The time since midnight */
/* the same day. */
timsABS_TIME /* yy-mm-dd hh:mm:ss.uuuuuu The combination*/
/* of the two previous one.*/
} timsTIME_FORMAT;
typedef enum { /* Working mode for the time system */
timsUTC = 1, /* WS is synchronized with time Server */
timsLOCAL, /* WS is not synchronized */
timsSIMULATION /* For compatibility with LCU */
} timsMODE;
ccsExit() performs the necessary clean up for applications
making use of CCS.
error <OUT> error structure.
It perform the following operations :
- Closes all DB connections
- Sends a request to the QServer-Emulator to disconnect
from the environment ( ONLY CCS-LITE )
SUCCESS upon successful completion
FAILURE, return the following errors :
ccsERR_ENV_NAME, Invalid Environment name.
ccsERR_DB_CLOSE , Failure closing an existing environment.
Any application program, which has previously used ccsInit()
must call ccsExit() before terminating.
#include "ccs.h"
...
ccsERROR error;
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
...
if (ccsExit(&error) == FAILURE)
... error processing ...
else
... normal termination ...
#include "ccs.h"
ccsCOMPL_STAT ccsFindFile (const char *fileName,
char *filePath,
vltINT8 *mode,
vltUINT32 *size,
vltINT8 *dirFlag)
ccsCOMPL_STAT ccsFileExist ( char *filePath )
Parameter description :
fileName <IN> Name of the file to be found.
It can also be a "relative" file name.
filePath <OUT> Full name of the location where the file was found
mode <OUT> File permissions
size <OUT> File Size
dirFlag <OUT> Indicates that the file is a directory.
ccsFindFile
Searches for a file in the VLT file system hierarchy.
The routine checks if the file exists under a specific sequence of
directories. The table below show the searching paths and uses as
example : fileName = "config/ccsSHM_wte49.config"
=======================================================================
| Search Path Sequence | Returned Path |
=======================================================================
search file in current dir. | ./ccsSHM_wte49.config
search file in current sub-dir. | ./config/ccsSHM_wte49.config
search file under INTROOT | $INTROOT/config/ccsSHM_wte49.config
search file under VLTROOT | $VLTROOT/config/ccsSHM_wte49.config
ccsFileExist
Returns SUCCESS if the file exists and FAILURE otherwise.
char myFile[128];
char fullPath[256];
vltINT8 mode;
vltUINT32 size;
vltINT8 dirFlag;
if (ccsFindFile(myFile,fullPath,&mode,&size,&dirFlag) == FAILURE)
{
File does not exists
}
else if (dirFlag)
{
File is a directory
}
This function retrieves the environment variables VLTROOT and INTROOT.
vltPath <OUT> Path to the VLTROOT directory (NULL if undefined)
intPath <OUT> Path to the INTROOT directory (NULL if undefined)
vltData <out> Path to the VLTDATA directory (NULL if undefined)
SUCCESS upon successful completion
FAILURE, if none of the environment variables is defined.
No error is returned, only a log is produced.
This function retrieves the name of the local environment.
envName <OUT> environment name
error <OUT> error structure
SUCCESS, if defined
FAILURE, if environment name not defined
(e.g. RTAPENV not defined)
NOTE: No error is put on the error stack.
#include <ccs.h>
ccsCOMPL_STAT ccsGetMyProcId(ccsENVNAME envName,
ccsPROCNUM *procNum,
ccsPROCNAME procName,
ccsERROR *error)
This function returns for a process environment name, process number
and name.
envName <OUT> name of the environment, where the process is running
procNum <OUT> process number
procName <OUT> process name
error <OUT> error structure
The environment name can be up to 7 characters in lenght.
(excluding the NULL terminator).
The process identifier is a number, which can be statically assigned
in the RtapEnvTable or allocated automatically by RtapScheduler
(NOT for CCS-LITE).
SUCCESS, if information retrieved successfully
FAILURE, if an error occures:
ccsERR_NULL_PTR , illegal NULL pointer as parameter
ccsERR_PROC_INFO , Cannot get process identification
or environment name
ccsENVNAME myEnv;
ccsPROCNUM procId;
ccsPROCNAME procName;
ccsERROR error;
...
if (ccsGetMyProcId(myEnv,&procId,procName,&error) == FAILURE) {
{
Process failure condition
}
...
#include "ccs.h"
ccsCOMPL_STAT ccsGetProcName (const ccsENVNAME envName,
ccsPROCNUM procNum,
ccsPROCNAME procName
ccsERROR *error )
This routine retrieves the name of the process running in a given
environment knowing its process Id numbers.
envName <IN> - Name of the environment where the process runs
procNum <IN> - Process Identifier Number
procName <OUT> - Returned Process Name
error <OUT> - Returned error structure
ccsENVNAME envName;
ccsPROCNUM procNum;
ccsPROCNAME procName;
ccsERROR error
if (ccsGetProcName(envName,procNum,procName,&error) == FAILURE)
{
Process error condition
}
#include "ccs.h"
ccsCOMPL_STAT ccsGetProcNum (
const ccsENVNAME envName,
const ccsPROCNAME procName,
ccsPROCNUM *procNum,
ccsERROR *error
)
ccsGetProcNum() retrieves the process number for the indicated
process from the environment in which it is running.
envName <IN> environment name
procName <IN> process name
procNum <OUT> process number
error <OUT> error handling data structure
....
ccsENVNAME envName;
ccsPROCNUM procNum;
ccsPROCNAME procName;
ccsERROR error
if (ccsGetProcNum(envName,procName, &procNum, &error) == FAILURE)
{
process error condition
}
....
#include "ccs.h"
ccsCOMPL_STAT ccsInit(const ccsPROCNAME procName,
vltUINT32 obituary,
void (*breakHandler)(int),
void (*killHandler)(int),
ccsERROR *error)
Initializes the CCS services
procName <IN> Name of the process under which the application
should register. It is normally the application
name, but could also be something else.
It is normally passed using argv[0].
(A path, which may be included in argv[0],
is automatically cut off, and the process
is registered with the name of the binary)
obituary <IN> In CCS/RTAP not used
In CCS LITE used to change behaviour concerning
OBITUARIES; possible values are any "ORed"
combination of
- ccsOBI_CARE_ON/ccsOBI_CARE_OFF
enable/disable receiving of termination
broadcasts
- ccsOBI_CLEANUP_ON/ccsOBI_CLEANUP_OFF
enable/disable creating of termination
broadcast on termination
- if 0 the behaviour is unchanged
NOTES:
- Using this flag, the setup in the CcsEnvTable
is overwritten.
- Defining all four states, will result in
enabling both features.
breakHandler <IN> is the name of signal handler function for
the break command. If this parameter is set
to NULL the default breakHandler is used.
The parameter passed to the routine is a
signal code and allow the user to make the
routine react to the proper signal.
killHandler <IN> is the name of signal handler function for
the kill command. If this parameter is set
to NULL the default killHandler is used.
The parameter passed to the routine is a
signal code and allow the user to make the
routine react to the proper signal.
error <OUT> Returned Error structure.
The parameter passed to the routines 'breakHandler' and 'killHandler'
is a signal code and allow the user to make the routine react to
the proper signal (as shown in the examples below).
ccsInit() performs the following initializations :
1.) When registering to a standard (CCS) environment
- Registers the application in the RTAP environment.
This makes the application becoming a son of RtapScheduler,
inheriting its Path.
2.) When running without RTAP (CCS LITE):
- The signals SIGUSR1/SIGUSR2/SIGTERM/SIGINT and SIGQUIT
are configured
- An exit handler is established forcing a ccsExit()
- A pipe is opened and a message queue is established
- A request is sent to qsemu to register to the environment
In both cases, ccsInit also:
- Sets the message system automatic log ON or OFF according
to the values of the environment variable MSGAUTOLOG.
- Allows the user to define application specific signal
handlers.
A log is generated in the following cases :
- The application gets a 'kill' signal
- The kill and break handler receive a signal other than expected.
SUCCESS upon successful completion
FAILURE if an error occurred:
ccsERR_ENV_NOT_ACTIVE , The environment, RTAP or CCS_Lite, is not active.
ccsERR_INIT , Failure during registration with RTAP or CCS_Lite
ccsERR_ENV_NAME , Environment variable RTAPENV is not
defined. NB: the same variable is used in CCS_Lite
This routine must be called ONCE, normally in the initialisation
phase of the applications, BEFORE any call to a CCS function
(db, msg,...) can be performed. Unexpected results might occur if this rule
is not applied. In particular, logging and error handling can be affected
if called prior to ccsInit.
For ccs, to avoid multiple copies of processes running simultaneously,
the appropriate flag should be set in the RtapEnvTable.
If the routine fails to connect to the environment the error
stack is automatically closed before returning, thus logging the
whole error stack for later debug.
If the program registers into a Rtap environment, it becomes a
son of the RtapScheduler for that environment, and inherits its PATH.
In the present release, the current working directory is however
restored.
Use of ccsInit:
---------------
#include "ccs.h"
ccsERROR error;
...
if (ccsInit(argv[0],0,NULL,NULL,&error) == FAILURE)
{
Process Error condition
}
Signal handlers examples:
-------------------------
defaultBreak() - Default signal catching routine for Break (SIGUSR1).
Input : SIG - signal that was received
Output: none
void defaultBreak(int sig)
{
if (sig == SIGUSR1)
{
logData(ccsGEN,0,"The application received a BREAK command");
...
... Application specific code :
... e.g.
... trigger clean stop of current action,
... and return to wait for next request.
}
else
{
sprintf(logText,"The Break handler received a wrong signal (%d)",sig);
logData(ccsGEN,0,logText);
}
}
defaultKill() - Default signal catching routine for Kill (SIGUSR2).
Input : SIG - signal that was received
Output: none
void defaultKill(int sig)
{
ccsERROR error;
if (sig == SIGUSR2)
{
logData(ccsGEN,0,"Exit : Received the KILL command ");
ccsExit(&error); These two statements must always exist
exit(0); at the end of the KILL handler.
}
else
{
sprintf(logText,"Kill Handler got the wrong signal (%d)", sig);
logData(ccsGEN,0,logText);
}
}
#include "ccs.h"
ccsCOMPL_STAT ccsOpenFile (const char *fileName,
const char *mode,
FILE **fileHandle,
ccsERROR *error)
Opens a file located in a subdirectory of INTROOT (first) or VLTROOT.
fileName path/name of the file to be opened
mode a legal access mode for system call 'fopen()'
fileHandle pointer to the returned file handle (NULL: error)
error pointer to the returned error structure
SUCCESS .
FAILURE and error returns :
ccsERR_FILE , Invalid File name
ccsERR_ENV_VARIABLE , Undefined environment variable
ccsERR_NULL_PTR , One of the parameters is a NULL pointer
ccsCOMPL_STAT stat;
ccsERROR error;
FILE *file_p;
const char testFile[] = "tmp/ccsTestDummy";
const char mode = "w";
stat = ccsOpenFile(testFile, mode, &file_p, &error);
if (stat == FAILURE)
{
process error condition
}
ccsPthreadInit() - initialize CCS multithreading services
ccsMPthreadCreate() - start CCS thread registered with the local environment
ccsPthreadCreate() - start thread running in context of main thread
#include "ccsPthread.h"
ccsCOMPL_STAT ccsPthreadInit (ccsPROCNAME procName,
vltUINT32 obituary,
void (*breakHandler)(int),
void (*killHandler)(int))
ccsCOMPL_STAT ccsMPthreadCreate (pthread_t *threadId,
const ccsPROCNAME procName,
vltUINT32 obituary,
pthread_attr_t *attr,
void (*routine)(void*),
void *arg,
ccsERROR *error)
ccsCOMPL_STAT ccsPthreadCreate (pthread_t *threadId,
pthread_attr_t *attr,
void (*routine)(void*),
void *arg,
ccsERROR *error)
ccsPthreadInit() initializes the CCS multithreading services and registers
the main (calling) thread with the local environment. This function has to
be called before any other CCS function. It is important, that the main
thread calling this function terminates last.
procName <IN> Name of the process under which the application
should register. It is normally the application
name, but could also be something else. This is
the main thread name.
obituary <IN> In CCS LITE used to change behaviour concerning
OBITUARIES; possible values are any "ORed"
combination of
- ccsOBI_CARE_ON/ccsOBI_CARE_OFF
enable/disable receiving of termination
broadcasts
- ccsOBI_CLEANUP_ON/ccsOBI_CLEANUP_OFF
enable/disable creating of termination
broadcast on termination
- if 0 the behaviour is unchanged
NOTES:
- Using this flag, the setup in the CcsEnvTable
is overwritten.
- Defining all four states, will result in
enabling both features.
breakHandler <IN> is the name of signal handler function for
the break command. If this parameter is set
to NULL the default breakHandler is used.
The parameter passed to the routine is a
signal code and allow the user to make the
routine react to the proper signal.
killHandler <IN> is the name of signal handler function for
the kill command. If this parameter is set
to NULL the default killHandler is used.
The parameter passed to the routine is a
signal code and allow the user to make the
routine react to the proper signal.
ccsMPthreadCreate() starts a new thread registering with the local environment.
This generates the assignment of a new message queue for the new thread which
will become addressable like a standard standalone CCS application. This is the
mode to be used for threads accessing CCS resources like message system and database.
threadId <OUT> thread ID returned by the system.
procName <IN> Name of the process under which the new thread
should register. This name will be used by the
message system to retrieve the corresponding
message queue
obituary <IN> In CCS LITE used to change behaviour concerning
OBITUARIES; possible values are any "ORed"
combination of
- ccsOBI_CARE_ON/ccsOBI_CARE_OFF
enable/disable receiving of termination
broadcasts
- ccsOBI_CLEANUP_ON/ccsOBI_CLEANUP_OFF
enable/disable creating of termination
broadcast on termination
- if 0 the behaviour is unchanged
NOTES:
- Using this flag, the setup in the CcsEnvTable
is overwritten.
- Defining all four states, will result in
enabling both features.
attr <IN> specifies thread attributes to be applied to the new
thread (see pthread_create(), pthread_attr_init())
routine <IN> start routine applied by the new thread
(see pthread_create())
arg <IN> parameter passed as first argument to routine
error <OUT> return error structure
ccsPthreadCreate() starts a new thread sharing the CCS resources and message
queue of the main thread allocated by ccsPthreadInit(). This thread cannot
be individually addressed from other CCS processes.
threadId <OUT> thread ID returned by the system.
attr <IN> specifies thread attributes to be applied to the new
thread (see pthread_create(), pthread_attr_init())
routine <IN> start routine applied by the new thread
(see pthread_create())
arg <IN> parameter passed as first argument to routine
error <OUT> return error structure
Note that registering a new thread with this last method will prevent concurrent
access to CCS resources and the message queue in particular.
Since a lot of CCS library functions internally use the message queue,
waiting in the main thread on the queue for any kind of message and e.g. writing
in the database in another thread started by ccsPthreadCreate() will not work !
Multithreading is currently only available on Linux.
Signals are installed on process level. CCS only garanties, that
signals are not delivered to internal threads. Further signal handling
has to be implemented by the software developer of the application.
Note that CCS BREAK and KILL commands are implemented via the signals
SIGUSR1 and SIGUSR2. Accordingly sending one of these commands addresses
all threads of a process.
ccsInit() and ccsExit() should never be called from a multithreaded application.
#include "ccs.h"
#include "ccsPthread.h"
void ccsThread1(void *);
void ccsThread2(void *);
int main(int argc, char *argv[])
{
ccsERROR error;
int i = 0;
pthread_t threadId1;
pthread_t threadId2;
....
... initialize CCS multithreading services ...
if (ccsPthreadInit("Name", 0, NULL, NULL) == FAILURE)
{
printf("Error in ccsPthreadInit()\n");
return EXIT_FAILURE;
}
errResetStack(&error);
....
... start thread registered with the local environment ...
if (ccsMPthreadCreate(&threadId1, "thread1", 0, NULL,
ccsThread1, NULL, &error) == FAILURE)
{
errCloseStack(&error);
ccsExit(&error);
return EXIT_FAILURE;
}
....
.... start thread using resources of main thread ...
if (ccsPthreadCreate(&threadId2, NULL, ccsThread2,
NULL, &error) == FAILURE)
{
errCloseStack(&error);
ccsExit(&error);
return EXIT_FAILURE;
}
....
if (dbWriteSymbolic("<alias>SCALARS", "scalar_int32",
dataType, (char *)&i, 4, &actual,
1, dbSCALAR, &error) == FAILURE)
....
ccsExit(&error);
return EXIT_SUCCESS;
}
void ccsThread1(void *arg)
{
ccsERROR error;
....
errResetStack(&error);
....
status = msgRecvMsg(&filter, msgNO_TIMEOUT, &myMsg, &error);
....
errCloseStack(&error);
return;
}
void ccsThread2(void *arg)
{
ccsERROR error;
....
if (dbGetAttrNames("jhsjdd",&attrCount,&ains,&names,&error) == FAILURE)
....
if (dbGetAttrNames("<alias>SCALARS>",&attrCount,&ains,&names,&error) == FAILURE)
....
if (dbWriteSymbolic("<alias>SCALARS", "scalar_uint16", dataType, (char *)&i,
2, &actual, 1, dbSCALAR, &error) == FAILURE)
....
return;
}
3.2.15 ccsWaitForProcStat
#include "ccs.h"
ccsCOMPL_STAT ccsWaitForProcStat (
ccsENVNAME envName,
ccsPROCNAME procName,
ccsPROCSTAT procStat,
vltINT32 howLong,
ccsERROR *error
)
ccsWaitForProcStat() waits for the indicated process in the
indicated environment to be in the given procStat. If the
requested state is not reached within 'howLong' seconds,
a time out error is returned.
envName <IN> environment name
procName <IN> process name
procStat <IN> requested state:
ccsPROC_EXIT: the process has no procNum
ccsPROC_REACHABLE: a PING without reply can be sent.
ccsPROC_ANSWERING: a PING receives an OK reply.
howLong <IN> >0 integer number of seconds of wait to reach the requested state.
0 means no wait.
<0 means forever.
error <OUT> error handling data structure
Any process registering into an environment (Rtap or CCS_Lite) can be
tested against the EXIT case. REACHABLE and ANSWERING cases must be
reserved for VLT applications only since Rtap processes might be
disturbed by PING commands, and show umpredictable behaviors.
....
ccsENVNAME envName;
ccsPROCNAME procName;
ccsPROCSTAT procStat;
vltINT32 howLong;
ccsERROR error;
if (ccsWaitForProcStat(envName, procName, procStat, howLong, &error)
== FAILURE)
{
process error condition
}
....
ccsCOMPL_STAT cmdCheckCmd(const ccsPROCNAME processName.
const char *command,
const char *param,
msgLENGTH paramLen,
msgCMD cmd,
char **checkParam,
msgLENGTH *checkParamLen,
ccsERROR *error)
cmdCheckCmd performs checks on the availability and consistency of
a command and it's parameters. The reference for the checks performed
is the loaded CDT of the process specified with processName.
The CDT of the process is usually loaded at booking time. If the CDT is
not available a request is sent to cmdManager to dynamically load it
if the CDT is found in the standard path of the calling routine.
If inconsistencies are found cmdCheckCmd will return an error describing
the reason.
Furthermore default values (if existing) are inserted on omitted
parameters expanding the parameter list.
The checked and expanded parameter list is returned in the buffer
pointed to by checkParam.
Notice that the buffer is kept within the function.
processName <IN> Process name.
command <IN> Command name or command synonym.
param <IN> Buffer containing command parameters.
paramLen <IN> Length of param buffer.
cmd <OUT> Command name.
If a synonym was passed as command then
cmd contains the converted command name.
checkParam <OUT> Buffer containing checked and expanded
parameter list. Expanded means that missing
parameter are inserted with the default values
specified in the CDT.
checkParamLen <OUT> Length of checked parameter buffer.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_CDT_INFO , No CDT information available on process.
ccsERR_CMD_INVALID , Command not found in CDT.
ccsERR_CMD_PARAM_NB , Invalid number of command parameters.
ccsERR_CMD_PARAM_DEFVAL , Defaulted command parameter is missing.
ccsERR_CMD_PARAM_VAL , Parameter value does not match type or range.
ccsERR_CMD_PARAM_RANGEVAL, Parameter value does not match range.
ccsERR_CMD_PARAM_TYPEVAL , Parameter value does not match type.
ccsERR_CMD_CDT_FILE , Could not locate CDT file.
ccsERR_CMD_CDT_DYNLOAD , Could not dynamically load CDT
ccsCOMPL_STAT cmdFormatReply(const ccsPROCNAME processName.
const char *command,
const char *reply,
msgLENGTH replyLen,
char *formatedReply,
ccsERROR *error)
cmdFormatReply only applies structured binary replies where the type of
each reply parameter is described in the CDT of the 'processName'.
If the DISPLAY_FORMAT is specified for the command, the structured binary
will be formated to this printf like layout. The formated ascii reply
is returned to the user in formatedReply area.
If the reply type is ascii the cmdFormatReply will return the same ascii
reply it received as input. If the reply type is unformated binary
cmdFormatReply will return an error.
processName <IN> Process name.
command <IN> Command name or command synonym.
reply <IN> Message buffer containing the actual binary reply.
replyLen <IN> Size of the binary reply buffer.
formatedReply <IN> Caller allocated area where this function will store
the formated reply. Allocation and deallocation of it
is under the controll of the caller of this function.
The allocated size should be enought to hold the
formated reply.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_CDT_INFO , No CDT information available on process.
ccsERR_CMD_DISPLAY_FORMAT , No display format defined in CDT.
ccsERR_CMD_INVALID , Command not found in CDT.
ccsERR_CMD_INVFMT_BINREPLY , Unable to format, reply format type not specified on CDT
ccsERR_CMD_UNFMT_BINREPLY , Unable to format, reply format type is unformatted binary
cmdParamDefault - return parameter list with default values
cmdReplyDefault - return reply list with default values
ccsCOMPL_STAT cmdParamDefault(const ccsPROCNAME processName,
const char *command,
cmdPARAM_LIST *paramList,
ccsERROR *error)
ccsCOMPL_STAT cmdReplyDefault(const ccsPROCNAME processName,
const char *command,
cmdPARAM_LIST *replyList,
ccsERROR *error)
cmdParamDefault retrieves the defaulted parameters specified in the CDT
of the processName and builds a complete parameter list. Other parameters
entries are empty and can be inserted by the user e.g. using
cmdParamSetByIndex or cmdParamSetByName. The parameter list can be sent
with msgSendCommand after it has been converted with cmdParamToMsg.
cmdReplyDefault is identical to cmdParamDefault but works on command replies
instead of command parameters
processName <IN> Name of destination process.
command <IN> Command name.
paramList <OUT> List of defaulted parameters.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available on process.
ccsERR_CMD_INVALID , Invalid command specified.
ccsERROR error;
ccsPROCNAME process;
cmdPARAM_LIST paramList;
msgCMD command;
vltINT32 i,j;
memset(¶mList,'\0',sizeof(cmdPARAM_LIST));
//fill in process and command .
strcpy((char *)process, "myProcess");
strcpy((char *)command, "MYCMD" );
if ( cmdParamDefault(process,command,¶mList,&error) == FAILURE )
{
...error processing...
}
//paramList is now filled with the default values for each parameter.
//In case you need to call again the cmdParamDefault function, there is
//no need to free the paramList buffers. The function will reuse it ( free,
//allocate again ).
...........
if ( cmdParamFree(¶mList,&error) == SUCCESS ) !! release the internall memory
return;
else
{
...process error...
}
cmdParamDelete will delete a parameter from the parameter list given the
index number as parameter.
cmdParamDelete is usefull in situations where commands are forwarded and
the new destination does not support certain parameters.
The parameter structure is reduced with the selected parameter.
If the index is chosen in the middle of the parameter structure e.g.
index = 5 in a param list with 9 parameters. Then the paramter positions
for paramter 6 to 8 will shift to the left and become paramter 5 to 7.
Please note if multiple parameters needs to be removed then always start
from the back i.e. last number first.
paramList <IN/OUT> List of all parameters.
index <IN> Parameter number in paramter list.
error <OUT> error structure.
cmdParamGetByIndex - retrieve a parameter from the parameter list
by index
cmdParamGetLogicalByIndex - retrieve a logical parameter by index
cmdParamGetIntByIndex - retrieve a integer parameter by index
cmdParamGetDoubleByIndex - retrieve a double parameter by index
cmdParamGetStringByIndex - retrieve a string parameter by index
ccsCOMPL_STAT cmdParamGetByIndex(const cmdPARAM_LIST *paramList,
const vltINT32 index,
vltINT32 *paramNb,
cmdPARAM_TYPE *paramType,
void **paramValues,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetLogicalByIndex(const cmdPARAM_LIST *paramList,
const vltINT32 index,
vltLOGICAL *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetIntByIndex(const cmdPARAM_LIST *paramList,
const vltINT32 index,
vltINT32 *paramNb,
vltINT32 **value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetDoubleByIndex(const cmdPARAM_LIST *paramList,
const vltINT32 index,
vltINT32 *paramNb,
vltDOUBLE **value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetStringByIndex(const cmdPARAM_LIST *paramList,
const vltINT32 index,
vltINT32 *paramNb,
char **value,
ccsERROR *error)
cmdParamGetByIndex assists in navigating through the parameter list.
By providing the parameter index the specific parameters are
extracted from the paramList and a reference to the converted parameter
type is given by paramValues. The parameter type is identyfied by paramType
and can be one of the following: LOGICAL, INTEGER (vltINT32),
REAL (vltDOUBLE) or STRING.
paramValues points to an array of the specific type. The number of values
in the array are specified by paramNb.
Please note that for LOGICAL values only one value is possible.
A set of convenience functions are provided in order to retrive the value
types directly. These are: cmdParamGetLogicalByIndex, cmdParamGetIntByIndex,
cmdParamGetDoubleByIndex, cmdParamGetStringByIndex.
Note: the memory returned by cmdParamGetByIndex is kept internally within
the cmdParam function. The memory contents will change after a subsequent
call to cmdParamGetByIndex as the memory is dynamically managed. If the
user want's to keep the data returned it needs to be copied.
paramList <IN> List of all parameters.
index <IN> Index number of the parameter wanted.
paramNb <OUT> Number of values of the found parameter.
paramType <OUT> Parameter type.
paramValues <OUT> Values of the found parameters.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available
ccsERR_CMD_INVALID , Invalid command specified
ccsERR_CMD_PARAM_TYPE , Invalid parameter type
cmdParamGetByName - retrieve parameter(s) from the parameter list
by name
cmdParamGetLogicalByName - retrieve a logical parameter by Name
cmdParamGetIntByName - retrieve a integer parameter by Name
cmdParamGetDoubleByName - retrieve a double parameter by Name
cmdParamGetStringByName - retrieve a string parameter by Name
ccsCOMPL_STAT cmdParamGetByName(const cmdPARAM_LIST *paramList,
const char *paramName,
vltINT32 *paramNb,
cmdPARAM_TYPE *paramType,
void **paramValues,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetLogicalByName(const cmdPARAM_LIST *paramList,
const char *paramName,
vltLOGICAL *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetIntByName(const cmdPARAM_LIST *paramList,
const char *paramName,
vltINT32 *paramNb,
vltINT32 **value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetDoubleByName(const cmdPARAM_LIST *paramList,
const char *paramName,
vltINT32 *paramNb,
vltDOUBLE **value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamGetStringByName(const cmdPARAM_LIST *paramList,
const char *paramName,
vltINT32 *paramNb,
char **value,
ccsERROR *error)
cmdParamGetByName assists in navigating through the parameter list. By
providing the parameter name paramName the specific parameters are
extracted from the paramList and a reference to the converted parameter
type is given by paramValues. The parameter type is identyfied by paramType
and can be one of the following: LOGICAL, INTEGER (vltINT32),
REAL (vltDOUBLE) or STRING.
paramValues points to an array of the specific type. The number of values
in the array are specified by paramNb.
Please note that for LOGICAL values only one value is possible.
A set of convenience functions are provided in order to retrive the value
types directly. These are: cmdParamGetLogicalByName, cmdParamGetIntByName,
cmdParamGetDoubleByName, cmdParamGetStringByName.
Note: the memory returned by cmdParamGetByName is kept internally within
the cmdParam function. The memory contents will change after a subsequent
call to cmdParamGetName as the memory is dynamically managed. If the
user want's to keep the data returned it needs to be copied.
paramList <IN> List of all parameters.
paramName <IN> Name of the parameter wanted.
paramType <OUT> Parameter type.
paramNb <OUT> Number of values of the found parameter.
paramValues <OUT> Values of the found parameters.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available
ccsERR_CMD_INVALID , Invalid command specified
ccsCOMPL_STAT cmdParamList(const char *command,
const char *param,
const vltINT32 paramLen,
cmdPARAM_LIST *paramList,
ccsERROR *error)
cmdParamList parses the message buffer containing the parameters
of the command specified and places the inidividual parameters into
a paramList structure. param contains the raw message buffer as received
from msgParseMsg. The parser uses the CDT information of the process
to build the parameter list, thus the CDT of the process must be
loaded. The paramList of type cmdPARAM_LIST contains a list of parameter
items of the type cmdPARAM_LIST_ITEM.
typedef struct
{
cmdPARAM_TYPE type; !! Parameter type: INTEGER,REAL,STRING,LOGICAL
vltUINT16 valueNb;!! Number of values
char **text; !! Array of values in ASCII
vltLOGICAL flag; !! Flag value (only for LOGICAL parameters)
} cmdPARAM_LIST_ITEM;
command <IN> Command name.
param <IN> Buffer containing command parameters as received
with msgParseMsg.
paramLen <IN> Length of param buffer.
paramList <OUT> List of found parameters.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available on process.
ccsERR_CMD_INVALID , Invalid command specified.
ccsERR_CMD_PARAM_NB , Invalid number of command parameters.
ccsERR_CMD_PARAM_VAL , Parameter value does not match type or range
When calling cmdParamList the first time the paramList structure passed
must be zeroed. cmdParamList allocates memory internally which is freed
at the next call to cmdParamList, when a paramList is containing values.
This is very usefull as the user can reuse the same paramList structure
in additional calls to cmdParamList without worrying about memory leaks.
ccsERROR error;
char *buffer;
msgLENGTH buflen;
cmdPARAM_LIST paramList;
msgCMD command;
vltINT32 i,j;
!! remember to reset paramList the first time called
memset(¶mList,'\0',sizeof(cmdPARAM_LIST));
while (ccsTRUE)
{
... msgRecvMsg ...
if (msgParseMsg(..., &buffer, &buflen, ...) == SUCCESS)
{
if (cmdParamList(command,
buffer,
buflen,
¶mList,
&error) == FAILURE)
{
... error processing ...
}
else
{
... process the individual parameters ...
for (i=0;i<paramList.parameterNb;i++)
{
paramList.parameters[i].valueNb;
switch(paramList.parameters[i].type)
{
case cmdPARAM_TYPE_LOGICAL:
printf("%s\n",(paramList.parameters[i].flag ?
"TRUE" : "FALSE"));
break;
case cmdPARAM_TYPE_INTEGER:
case cmdPARAM_TYPE_REAL:
case cmdPARAM_TYPE_STRING:
for(j=0;j<paramList.parameters[i].valueNb;j++)
printf("%s\n",paramList.parameters[i].text[j]);
break;
}
}
}
}
} !! end while
cmdParamFree(¶mList,&error); !! release the internall memory
cmdParamSetByIndex - set a parameter in the parameter list
by name
cmdParamSetLogicalByIndex - set a logical parameter by index
cmdParamSetIntByIndex - set a integer parameter by index
cmdParamSetDoubleByIndex - set a double parameter by index
cmdParamSetStringByIndex - set a string parameter by index
cmdParamSetSingleStringByIndex - set a single string by index
ccsCOMPL_STAT cmdParamSetByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
vltINT32 paramNb,
void *paramValues,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetLogicalByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
vltLOGICAL value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetIntByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
vltINT32 paramNb,
vltINT32 *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetDoubleByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
vltINT32 paramNb,
vltDOUBLE *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetStringByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
vltINT32 paramNb,
char **stringArray,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetSingleStringByIndex(cmdPARAM_LIST *paramList,
vltINT32 index,
char *string,
ccsERROR *error)
cmdParamSetByIndex assists in navigating into the parameter list.
By providing the parameter index the specific value or values of type
LOGICAL, INTEGER (vltINT32), REAL (vltDOUBLE) or STRING are converted
and inserted into the paramList structure. Only INTEGER and REAL are
converted into strings.
The number of values in the array are specified by paramNb.
Please note that for LOGICAL values only one value is possible.
A set of convenience functions are provided in order to set the value
types directly. These are: cmdParamSetLogicalByIndex, cmdParamSetIntByIndex,
cmdParamSetDoubleByIndex, cmdParamSetStringByIndex,
cmdParamSetSingleStringByIndex.
paramList <IN> List of all parameters.
index <IN> Index number of the parameter wanted.
paramNb <IN> Number of parameters in list
paramValues <IN> String of one or more parameter values. If multiple
values the values are seperated by spaces.
paramFlag <IN> In case of logical parameter the flag value.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available
ccsERR_CMD_INVALID , Invalid command specified
cmdParamSetByName - set a parameter in the parameter list
by name
cmdParamSetLogicalByName - set a logical parameter by name
cmdParamSetIntByName - set a integer parameter by name
cmdParamSetDoubleByName - set a double parameter by name
cmdParamSetStringByName - set a string parameter by name
cmdParamSetSingleStringByName - set a single string parameter by name
ccsCOMPL_STAT cmdParamSetByName(cmdPARAM_LIST *paramList,
char *paramName,
vltINT32 paramNb,
void *paramValues,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetLogicalByName(cmdPARAM_LIST *paramList,
char *paramName,
vltLOGICAL value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetIntByName(cmdPARAM_LIST *paramList,
char *paramName,
vltINT32 paramNb,
vltINT32 *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetDoubleByName(cmdPARAM_LIST *paramList,
char *paramName,
vltINT32 paramNb,
vltDOUBLE *value,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetStringByName(cmdPARAM_LIST *paramList,
char *paramName,
vltINT32 paramNb,
char **stringArray,
ccsERROR *error)
ccsCOMPL_STAT cmdParamSetSingleStringByName(cmdPARAM_LIST *paramList,
char *paramName,
char *string,
ccsERROR *error)
cmdParamSetByName assists in navigating into the parameter list.
By providing the parameter name the specific value or values of type
LOGICAL, INTEGER (vltINT32), REAL (vltDOUBLE) or STRING are converted
and inserted into the paramList structure. Only INTEGER and REAL are
converted into strings.
The number of values in the array are specified by paramNb.
Please note that for LOGICAL values only one value is possible.
A set of convenience functions are provided in order to set the value
types directly. These are: cmdParamSetLogicalByName, cmdParamSetIntByName,
cmdParamSetDoubleByName, cmdParamSetStringByName, cmdParamSetStringByName.
paramList <IN> List of all parameters.
paramName <IN> Name of the parameter.
paramValues <IN> String of one or more parameter values. If multiple
values the values are seperated by spaces.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available
ccsERR_CMD_INVALID , Invalid command specified
ccsCOMPL_STAT cmdParamToMsg(const cmdPARAM_LIST *paramList,
char *param,
msgLENGTH *paramLen,
ccsERROR *error)
cmdParamToMsg converts the parameters in the paramList or replyList to
a string of comma seperated parameters. The parameter string is returned in
the param buffer which can be passed directly to the msgSendCommand
function.
paramList <IN> List of found parameters.
param <IN/OUT> Pointer to parameter string.
paramLen <OUT> Length of parameter string.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available
ccsERR_CMD_INVALID , Invalid command specified
The user must provide a clean buffer inorder for cmdParamToMsg
add the ascii parameters to the buffer.
cmdParseCDT reads the CDT file specified with fileName and parses the
contents of the CDT file. If the parsing is successfull a memory
area is allocated containing the command information of the process.
If the process already exists cmdParseCDT will replace the old command
information with the new one.
fileName <IN> file name of CDT.
load <IN> load CDT information in database.
error <OUT> error structure.
SUCCESS .
FAILURE an error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_CDT_FILE , Could not find or open CDT file.
ccsERR_CMD_CDT_CMDLEN , Invalid command length in CDT file.
ccsERR_CMD_CDT_SYNTAX , Syntax error in CDT file.
ccsERR_CMD_CDT_PARAM , Range or value incompatible in CDT file.
ccsERR_CMD_CDT_PARSE , Could not parse CDT file.
ccsERR_CMD_CDT_POINT , Could not access CDT database point.
ccsCOMPL_STAT cmdReplyList(const ccsPROCNAME processName,
const char *command,
const char *reply,
const vltINT32 replyLen,
cmdPARAM_LIST *replyList,
ccsERROR *error)
cmdReplyList parses the message buffer containing the reply of a
'command' request to the process specified by 'processName'. The reply
is parsed and the inidividual reply parameters are placed into
a replyList structure. 'reply' contains the raw message buffer as
received from msgParseMsg. The parser uses the CDT information of
the process to build the parameter list, thus the CDT of the process
must be loaded.
The paramList of type cmdPARAM_LIST contains a list of parameter
items of the type cmdPARAM_LIST_ITEM.
typedef struct
{
cmdPARAM_TYPE type; !! Parameter type: INTEGER,REAL,STRING,LOGICAL
vltUINT16 valueNb;!! Number of values
char **text; !! Array of values in ASCII
vltLOGICAL flag; !! Flag value (only for LOGICAL parameters)
} cmdPARAM_LIST_ITEM;
processName <IN> Name of process sending reply.
command <IN> Name of command name.
reply <IN> Buffer containing reply buffer as received
with msgParseMsg.
replyLen <IN> Length of reply buffer.
replyList <OUT> List of found reply parameters.
error <OUT> error structure.
SUCCESS .
FAILURE and error returns with one of the following errors:
ccsERR_CMD_MEMORY , Could not allocate memory.
ccsERR_CMD_SHM_CCS , Could not attach to CCS shared memory.
ccsERR_CMD_CDT_INFO , No CDT information available on process.
ccsERR_CMD_INVALID , Invalid command specified.
When calling cmdReplyList the first time the replyList structure passed
must be zeroed. cmdReplyList allocates memory internally which is freed
at the next call to cmdReplyList, when a replyList is containing values.
This is very usefull as the user can reuse the same replyList structure
in additional calls to cmdReplyList without worrying about memory leaks.
ccsERROR error;
char *buffer;
msgLENGTH buflen;
cmdPARAM_LIST replyList;
msgCMD command;
vltINT32 i,j;
!! remember to reset paramList the first time called
memset(¶mList,'\0',sizeof(cmdPARAM_LIST));
... msgSendCommand ...
... msgRecvMsg ...
if (msgParseMsg(..., &buffer, &buflen, ...) == SUCCESS)
{
if (cmdReplyList(command,
buffer,
buflen,
&replyList,
&error) == FAILURE)
{
... error processing ...
}
else
{
... process the individual parameters ...
for (i=0;i<replyList.parameterNb;i++)
{
replyList.parameters[i].valueNb;
switch(replyList.parameters[i].type)
{
case cmdPARAM_TYPE_LOGICAL:
printf("%s\n",(replyList.parameters[i].flag ?
"TRUE" : "FALSE"));
break;
case cmdPARAM_TYPE_INTEGER:
case cmdPARAM_TYPE_REAL:
case cmdPARAM_TYPE_STRING:
for(j=0;j<replyList.parameters[i].valueNb;j++)
printf("%s\n",replyList.parameters[i].text[j]);
break;
}
}
}
}
cmdParamFree(&replyList,&error); !! release the internall memory
ccsCOMPL_STAT cmdSimulation(const ccsENVNAME env,
const ccsPROCNAME process,
const msgCMD command,
vltLOGICAL *simulate,
const char **bufPtr,
vltUINT32 *bufSize,
ccsERROR *error)
cmdSimulation determines wheater a process or environment is to be
simulated or not. The information about simulation processes and
environments is stored in the RTAP database and maintained by cmd
utilities.
If the process or environment is in simulation mode a new buffer is
set up. The new buffer contains the old msgBODY and information
formated to the CMDSIM command of the cmdManager.
env <IN> Environment name.
process <IN> Process name.
command <IN> Command to simulate.
simulate <OUT> Return if process or environment is in simulation
mode.
bufPtr <IN/OUT> Pointer to message body. If no simulation pointer
is not used. If simulation bufPtr is pointing to
a buffer formated for cmdServer.
bufSize <IN/OUT> Size of bufPtr buffer.
error <OUT> Error structure.
#include "db.h"
ccsCOMPL_STAT dbAliasToName( const dbSYMADDRESS alias,
dbSYMADDRESS pointName,
ccsERROR *error )
Get the symbolic address of an alias.
alias <IN> Alias Name
pointName <OUT> Symbolic address of the point.
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid alias
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
This function does not support the resolution of static attributes in
the object oriented model implemented by the database loader, because
the symbolic address of a static attribute refers to the class path
and not to the instance path.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing one
#include "db.h"
ccsCOMPL_STAT dbDeToStr( dbTYPE dataType,
void *buffer,
char *string,
vltINT8 fieldWidth,
vltUINT16 precision )
Formats a data element value into a printable string.
dataType <IN> Type of data to be formatted, for example:
dbINT8, dbUINT32, dbBYTES20, dbLOGICAL etc ..
buffer <IN> Pointer to the data element
string <OUT> ASCII formatted value. The formatted string will
always be terminated by a NULL character, which
is not included in the field width.
fieldWidth <IN> Specifies the formatting as follows :
- 0 Exactly as many characters as needed
- n < 0 Left-justified (blank-filled) in
n characters
- n > 0 Right-justified (blank-filled) in
n characters
precision <IN> Specifies the precision (maximum number of significant
digits) required if deType is dbFLOAT, dbDOUBLE,
dbPOLAR or dbRECTANGULAR. For the time data element
types (dbTIME_OF_DAY or dbABS_TIME), precision specifies
the number of digits used to express fractions of a
second.
Some examples for the output of some data types.
Data Type | Output String Format
..............|........................................................
dbLOGICAL | Any nonzero value is printed as '1', otherwise as '0'.
dbPOLAR | {<magnitude>, <angle(deg)>, e.g. {1.35, -3.7d}
dbRECTANGULAR | {<real part><imaginary part>}, e.g. {6.37+4.3j}
dbABS_TIME | yyyy-mm-ddThh:mm:ss[.uuuuuuu]
dbDATE | yyyy-mm-dd
dbTIME | hh:mm:ss[.uuuuuuu]
dbXREF | @[71.2(4:5,6)]
If the specified length is insufficient then :
- The output of Numeric data (dbINT8, dbFLOAT, dbDOUBLE, etc .. )
is filled with '*'.
- The output of the other data (dbBYTESxx, dbPOLAR, dbABS_TIME, etc ..)
is truncated and marked with trailing ".."
The user must take care about the alignment of the pointers
passed to dbDeToStr(). This applies in particular when scanning
a record of a table. RTAP stores the data in an optimized way.
It is then up to the user to design the structure of the record
with a proper alignment.
See RTAP manuals for details.
#include "db.h"
ccsCOMPL_STAT dbDirAddrToName(dbDIRADDRESS *dirAddr,
dbVIEW addrType,
dbSYMADDRESS pointName,
ccsERROR *error )
Convert the direct address into symbolic address.
dirAddr <IN> Pointer to Direct address
dbVIEW <IN> Address Type : ALIAS, ABSOLUTE, RELATIVE
pointName <OUT> Returned Symbolic Address
error <OUT> Error structure.
The symbolic address can be obtained in the form specified by 'addrType'
SUCCESS .
FAILURE and error returns :
ccsERR_INV_ADDR , Invalid direct address
ccsERR_DB_QUERY , Failure during query operation.
Close a specific database connection or all.
envName <IN> The environment name identifies the database
error <OUT> Returned error structure
Use ccsLOCAL_ENV, to close the connection to local database.
Use dbALL_ENV, to close the connection to all databases.
SUCCESS .
FAILURE and error returns :
cccsERR_ENV_NAME , Invalid Environment name.
ccsERR_DB_CLOSE , Failure closing an existing environment.
ccsERROR error;
ccsENVNAME envName;
strcpy(envName,"wte13");
dbExit(envName, &error) ; To exit from a specific envionment.
dbExit(dbALL_ENV, &error); To exit from all envionments
#include "db.h"
ccsCOMPL_STAT dbFillBuf( char **userBuf,
char *value,
vltINT32 *bufSize,
dbTYPE dataType)
Fill a buffer of data according to the datatype supplied by the user.
This routine takes the individual values and copies them into the
user buffer according to the data type.
The pointer to the current position in the buffer and the current
buffer size are also updated.
userBuf <IN>/<OUT> Pointer to the current buffer position.
value <IN> Pointer to the new value to insert in the buffer.
bufSize <OUT> Current buffer size.
dataType <IN> Type of data represented by 'value'.
Strings can be shorter than the actual data type and the routine will
pad them with '\0' characters. This is due to the fact that RTAP expects
a string of length equal to the string data type, otherwise it fails.
Consider for example a table with a record composed by the
following data types : ccsTIMEVAL,vltINT8,vltBYTES20,vltFLOAT.
dbFillBuf allows to create a buffer of data according to structure of the
record and update the record with new values in one go.
ccsERROR error;
timsMODE mode;
ccsTIMEVAL now;
vltBYTES20 text;
vltINT8 var1 = 23;
vltFLOAT var2 = 253.94;
char myBuf[1000],*pBuf;
vltINT32 bufSize = 0;
if (timsGetUTC (&now,&mode,&error) == FAILURE)
... error processing ...
strcpy((char *) text, "Hello World ");
pBuf = myBuf;
dbFillBuf(&pBuf,&now, &bufSize,dbTIME_OF_DAY);
dbFillBuf(&pBuf,&var1,&bufSize,dbINT8);
dbFillBuf(&pBuf,text, &bufSize,dbBYTES20);
dbFillBuf(&pBuf,&var2,&bufSize,dbFLOAT);
#include "db.h"
ccsCOMPL_STAT dbGetAlias( const dbSYMADDRESS pointName,
dbSYMADDRESS alias,
ccsERROR *error)
Get the point's alias name
pointName <IN> Symbolic address of the point.
alias <OUT> returned alias
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point name
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
#include "db.h"
ccsCOMPL_STAT dbGetAttrInfo( const dbSYMADDRESS pointName,
const dbATTRIBUTE attrName,
dbATTRTYPE *attrType,
vltUINT8 *fieldCnt,
vltUINT16 *recCnt,
vltUINT32 *recSize,
vltUINT16 *recsUsed,
dbTYPE *dataType,
ccsERROR *error )
Retreives the detail description of the attribute in the local database.
pointName <IN> Name of the database point.
attrName <IN> Attribute Name (including range specification)
attrType <OUT> Attribute type : SCALAR, VECTOR or TABLE
fieldCnt <OUT> Number of fields. Always 1 for SCALAR and VECTOR
In TABLE this is the number of columns
recCnt <OUT> Number of records. Always 1 for SCALAR.
recSize <OUT> Record size in bytes.
recsUsed <OUT> Records currently in use (the highest index in use)
dataType <OUT> data type : provide a description of the type of data
stored in the DB element.
DataType is 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it returns the type of each field of the
record .
error <OUT> Error structure.
The point can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.' at the
beginning.
The attribute can also contain the range specification : the returned
information is relative to the 'portion' of data specified in the range
definition.
If the database is not yet opened, the routine takes care to open it.
This function support the resolution of static attributes in the object
oriented model implemented by the database loader.
SUCCESS, if everything OK
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point
ccsERR_DB_INV_ATTR , Invalid attribute name
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_DB_INV_RECEL , Invalid record/element in address
ccsERR_DB_INV_FIELD , Invalid field specifier in address
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE dataType[dbMAX_FIELD_CNT];
vltUINT8 fieldCnt;
vltUINT16 recCnt,recsUsed;
vltUINT32 recSize;
ccsERROR error;
strcpy((char *) attribute,"myAttribute")
strcpy((char *) pointName,":point1:point2:point3");
if (dbGetAttrInfo(pointName,attrName,&attrType,&fieldCnt,
&recCnt,&recSize,&recsUsed,dataType,&error) == FAILURE)
{
Process Error condition
}
dbGetAttrNames - Get the list of a point's attributes : names and AINs
(Attribute Identification Number) in the local database.
#include "db.h"
ccsCOMPL_STAT dbGetAttrNames( const dbSYMADDRESS pointName,
vltUINT8 *attrCount,
vltUINT8 **ains,
dbATTRIBUTE **names,
ccsERROR *error )
Get the list of a point's attributes : names and identification numbers
pointName <IN> Symbolic address of the point.
attrCount <OUT> Total number of attributes.
ains <OUT> Array containing the attributes identification numbers
dbATTRIBUTE <OUT> Array containing the attributes names
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
The AINs (Attribute Identification Number) can be used in the direct address
to access the specific attribute of a point.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point name
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
The routine access only the local database.
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
#include "db.h"
ccsCOMPL_STAT dbGetCwp( const ccsENVNAME envName,
dbSYMADDRESS pointName,
ccsERROR *error)
Get the current working point.
envName <IN> Name of the environmnet
pointName <OUT> Current working point. This returns the absolute
symbolic address of the CWP. The name does not
include the environment name.
error <OUT> Error structure.
Use ccsLOCAL_ENV to address the local default environment.
Each process can set its own Current Working Point, which is used
in the relative path in the point's symbolic address.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_GETCWP , Cannot Get Current Working Point
ccsERR_NULL_PTR , In case of NULL pointer in input parameters.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
dbSYMADDRESS pointCwp;
ccsERROR error;
if (dbGetCwp(ccsLOCAL_ENV, pointName,&error) == FAILURE) {
{
Process failure condition
}
#include "db.h"
ccsCOMPL_STAT dbGetDirAddr( const dbSYMADDRESS pointName,
const char *attrName,
dbDIRADDRESS *dirAddr,
ccsERROR *error)
Gets the attribute/point internal address in the local database.
pointName <IN> Name of the database point.
attrName <IN> Name of the attribute
dirAddr <OUT> Full direct address of the point or attribute
error <OUT> Error structure.
The point can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.' at the
beginning.
If the database is not yet opened, the routine takes care to open it.
The data structure dirAddr is filled to the same level of detail as
supplied by the attribute name and provides the following information:
- addrLevel Addressing Level. This indicates the level of detail
of the information returned in the direct address.
- dbDIR_AIN address specifies only the name.
- dbDIR_REC address specifies record ranges.
- dbDIR_FIELD address specifies record and field ranges.
- plin Point internal number (rtPlin)
- ain Attribute internal number (rtAin)
The following parameters are filled up according to the level of detail
given in the symbolic/alias name.
- startRec First record to be accessed
- endRec Last record to be accessed
- startField First field to be accessed
- endField Last field to be accessed
The addrLevel specifiers do not apply to all attribute types as
shown in the following :
attrName | level of detail | addrLevel
__________________________________________________
myTable all structure dbDIR_AIN
myScalar
myVector
myTable(0:3) record level dbDIR_REC
myVector(1:7)
myTable(0:1,3:5) field level dbDIR_FIELD
This function supports the rosolution of static attributes in the object
oriented model implemented by the database loader
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point or attribute name
ccsERR_DB_QUERY , Cannot open database or invalid DB connection Id.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbDIRADDRESS dirAddr;
ccsERROR error;
strcpy((char *) attrName,"myAttribute")
strcpy((char *) pointName,":point1:point2:point3");
if (dbGetDirAddr(pointName,attrName,&dirAddr,&error) == FAILURE)
{
Process Error condition
}
dbGetFamily - Get the direct address of myself, my parent
and the children points, in the local database.
#include "db.h"
ccsCOMPL_STAT dbGetFamily( const dbSYMADDRESS pointName,
vltUINT16 *myPlin,
vltUINT16 *parentPlin,
vltUINT16 *childCnt,
vltUINT16 **childPlins,
ccsERROR *error )
Get the direct address of myself, my parent and the children points.
pointName <IN> Symbolic address of the point.
myPlin <OUT> My Direct Address
parentPlin <OUT> My Parent Direct Address
childCnt <OUT> Total Number of sub-points
childPlin <OUT> Array with the sub-point direct addresses
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
The PLINs (Point List Index Number) can be used in the direct address
to access the specific point.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
The routine access only the local database.
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
#include "db.h"
ccsCOMPL_STAT dbGetFamilyNames( const dbSYMADDRESS pointName,
dbVIEW addrType,
dbSYMADDRESS parentName,
vltUINT16 *childCnt,
dbSYMADDRESS **childName,
ccsERROR *error )
Get the symbolic address of parent and children points.
pointName <IN> Symbolic address of the point.
dbVIEW <IN> Address Type : ALIAS, ABSOLUTE, RELATIVE
parentName <OUT> My Parent Symbolic Address
childCnt <OUT> Total Number of sub-points
childNames <OUT> Array with of children point names
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
dbGetFieldNames - Gets the the list of field names and corresponding
data type in a TABLE of the local environment.
#include "db.h"
ccsCOMPL_STAT dbGetFieldNames( const dbSYMADDRESS pointName,
const dbATTRIBUTE attrName,
vltUINT8 *fieldCnt,
dbFIELDNAME **fieldName,
dbTYPE **dataType,
ccsERROR *error )
Gets the the list of field names and corresponding data type in a TABLE
of the local environment.
pointName <IN> Name of the database point.
attrName <IN> Attribute name
fieldCnt <OUT> Number of fields.
fieldName <OUT> List of field names
dataType <OUT> data type : provide a description of the type of data
stored in the DB element.
DataType is 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it returns the type of each field of the
record .
error <OUT> Error structure.
The point can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
Both fielName and dataType structures are allocated by this function.
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.' at the beginning.
If the database is not yet opened, the routine takes care to open it.
This information is retrieved using one RTAP call to get the list of field
names and another for the dataType (RTAP constraint).
If one of the two parameters is not required, it can be skipped
by setting the parameter to NULL value, as follows :
- fieldName = NULL, no field names are returned
- dataType = NULL, no field data type names are returned.
This function supports the rosolution of static attributes in the object
oriented model implemented by the database loader
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point or attribute name
ccsERR_DB_QUERY , Cannot open database or invalid DB connection Id.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE **dataType;
dbFIELDNAME **fieldName;
vltUINT8 *fieldCnt;
ccsERROR error;
strcpy((char *) attribute,"myTable")
strcpy((char *) pointName,":point1:point2:point3");
if (dbGetFieldNames(&pointName,attrName,&fieldCnt,
&fieldName,&dataType,&error) == FAILURE)
{
Process Error condition
}
Getting only the field names
if (dbGetFieldNames(&pointName,attrName,&fieldCnt,
&fieldName,NULL,&error) == FAILURE)
{
Process Error condition
}
Getting only the field data types
if (dbGetFieldNames(&pointName,attrName,&fieldCnt,
NULL,&dataType,&error) == FAILURE)
{
Process Error condition
}
dbGetParent - Get the parent's direct address : PLIN
(Point List Index Number) in the local database.
#include "db.h"
ccsCOMPL_STAT dbGetParent( const dbSYMADDRESS pointName,
vltUINT16 *parentPlin,
ccsERROR *error )
Get the parent's direct address : PLIN (Point List Index Number)
pointName <IN> Symbolic address of the point.
parentPlin <OUT> Parent direct address
error <OUT> Error structure.
The symbolic address can be both the relative or absolute name.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point
ccsERR_DB_QUERY , Failure during query operation.
ccsERR_DB_LCU , Failure during access to a LCU.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
The routine access only the local database.
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
#include "db.h"
ccsCOMPL_STAT dbListAdd(dbLISTID listId,
dbSYMADDRESS attrName,
vltINT32 bufSize,
void *buffer,
ccsERROR *error)
Insert a new element in the list. If the element already exist, it is
rejected (difficulties with ranges for vectors and tables).
listId <IN> List Identifier, as returned by dbListCreate().
attrName <IN> Symbolic address of the database attribute, including
the ranges
bufSize <IN> Amount of data to be read or written (in bytes).
buffer <IN> Pointer to the buffer where the values are stored.
Both for Read and Write operations
error <OUT> Error structure.
The symbolic address can be specified using the following syntax :
- ":point1:point2.attribute"
- "<relative>:point1:point2.attribute"
- "<absolute>:point1:point2.attribute"
- "<alias>myalias.attribute"
If the type of addressing for the whole list is dbDIRECT, the routine gets
the direct address and stores it in the attribute description to be used
during the read/write operations.
The attribute characteristics are automatically queried from the database.
This function supports the rosolution of static attributes in the object
oriented model implemented by the database loader
SUCCESS .
FAILURE and error returns:
ccsERR_DB_LISTID , Invalid list Identifier.
ccsERR_DB_LIST , List element already exist.
ccsERR_DB_INV_NAME , Invalid attribute name
ccsERR_MEMORY , On memory allocation errors
ccsERR_NULL_PTR , One input paramater is NULL
:
ccsERROR error;
dbSYMADDRESS myVector;
vltINT32 myBuf[20];
vltINT32 bufSize;
dbLISTID listId;
strcpy(myVector,":point1:point2.vector(2:8)");
if (dbListCreate("myList","wte16",dbREAD,&listId,&error) == FAILURE) {
{
process failure condition
}
insert an element
if (dbListAdd(listId, myVector,sizeof(myBuf),
myBuff,&error) == FAILURE)
{
process failure condition
}
:
dbListCreate(3) dbListDestroy(3) dbListRemove(3) dbListGetId(3)
dbListModify(3) dbListChangeEnv(3) dbListSetAddr(3)
#include "db.h"
ccsCOMPL_STAT dbListChangeEnv(dbLISTID listId
ccsENVNAME newEnvName,
ccsERROR *error)
Change the name of the list.
listId <IN> List Identifier, as returned by dbListCreate().
newEnvName <IN> New environment name.
error <OUT> Error structure.
This allows the user to access the same set of data from another
environment
Use ccsLOCAL_ENV to reference the local default env.
SUCCESS .
FAILURE and error returns :
ccsERR_ENV_NAME , Invalid Environment Name.
ccsERR_DB_LISTID , Invalid list Identifier.
:
ccsERROR error;
dbLISTID listId;
if(dbListCreate("myList","wte13",dbREAD,&listId,&error) == FAILURE)
{
process failure condition
}
if (dbListChangeEnv(listId,"wte16",&error) == FAILURE)
{
process failure condition
}
dbListDestroy(3) dbListAdd(3) dbListModify(3) dbListGetId(3)
dbListRemove(3) dbListExtract(3) dbListCreate(3)
#include "db.h"
ccsCOMPL_STAT dbListCreate(char *listName,
ccsENVNAME envName,
vltINT8 useFlag,
dbLISTID *listId,
ccsERROR *error)
Create an empty a list of attributes.
listName <IN> Name of the list (ASCII NULL terminated string).
envName <IN> Environment name of the database to access.
Use ccsLOCAL_ENV to reference the local default env.
LCU's environments are allowed.
useFlag <IN> Define if the list is used to READ/WRITE : dbREAD, dbWRITE
listId <OUT> List Identifier. It is a data structure containing
global information on the list. This is also
used to perform operation on the list.
error <OUT> Error structure.
Initialize the structure containing a list of database elements
to be accessed by means of a multi-read or multi-write routine.
The environment name is also used to identify the list in order to
access its elements.
The list identifier is a data structure with the following information :
- index List Identifier
- name List Name
- envName Name of the RTAP environement
- writeMode Flag to set the mode for writing values
- blockCnt Number of successful 'blocks' for which the read/write
operation was SUCCESSFUL
SUCCESS .
FAILURE and error returns :
ccsERR_ENV_NAME , Invalid environment name.
ccsERR_DB_LIST , Invalid list name : the list already exist
ccsERR_DB_LIST_FLAG , Invalid useFlag : only dbREAD or dbWRITE
ccsERR_DB_MAX_LISTS , No more lists available.
:
ccsENVNAME envNam;
ccsERROR error;
dbLISTID listId;
strcpy((char *) envName,"wte16");
if (dbListCreate("myList",envName,dbREAD,&listId,&error) == FAILURE)
{
process failure condition
}
if (dbListCreate("myList",ccsLOCAL_ENV,dbWRITE,
&listId,&error)== FAILURE) {
{
process failure condition
}
:
dbListDestroy(3) dbListAdd(3) dbListModify(3) dbListGetId(3)
dbListRemove(3) dbListExtract(3) dbListChangeEnv(3)
Destroy a list of attributes.
listId <IN> List Identifier, as returned by dbListCreate().
error <OUT> Error structure.
Release all the memory allocated by the list.
SUCCESS .
FAILURE and error returns :
ccsERR_NULL_PTR , Passed a null parameter
ccsERR_DB_LISTID , Passed a not valid list identifier
:
ccsERROR error;
dbLISTID listId;
:
if (dbListDestroy(listId,&error) == FAILURE)
{
process failure condition
}
:
dbListCreate(3) dbListAdd(3) dbListModify(3) dbListGetId(3)
dbListRemove(3) dbListExtract(3) dbListChangeEnv(3)
#include "db.h"
ccsCOMPL_STAT dbListExtract(dbLISTID listId,
dbSYMADDRESS attrName,
dbATTRINFO *attrInfo,
ccsERROR *error)
Extract the information of a specific element returned by a READ/WRITE
operation.
listId <IN> List Identifier, as returned by dbListCreate().
attrName <IN> Symbolic address of the database attribute.
attrInfo <OUT> Data Structure containing the attribute description with
the data read/written
error <OUT> Error structure.
The symbolic address can be specified using the following syntax :
- ":point1:point2.attribute"
- "<relative>:point1:point2.attribute"
- "<absolute>:point1:point2.attribute"
- "<alias>myalias.attribute"
The data structure of type dbATTRINFO provides the following information :
attrInfo.bufSize Size of the data buffer
attrInfo.buffer Pointer to the data buffer
attrInfo.recordCnt Number of record
attrInfo.dataType Pointer to the array with data types
attrInfo.attrType Type of attribute
attrInfo.actual Actual number of read/written bytes
attrInfo.status Completion status of the operation
SUCCESS .
FAILURE and error returns:
ccsERR_DB_INV_NAME , Attribute is not in the list
ccsERR_DB_LISTID , Invalid list identifier
:
ccsERROR error;
dbSYMADDRESS myVector;
dbLISTID listId;
dbATTRINFO attrInfo;
strcpy(myVector,":point1:point2.vector(2:8)");
if (dbListCreate("myList","wte13",dbREAD,&listId,&error) == FAILURE)
{
process failure condition
}
read the list of attribute
strcpy(myVector,":point1:point2.vector(2:8)");
if (dbMultiRead(listId,..., &error) == FAILURE)
{
process failure condition
}
extract the information returned by the read operation
if (dbListExtract(listId,myVector,&attrInfo,&error) == FAILURE)
{
process failure condition
}
if (attrInfo.status == FAILURE)
{
Read Operation for this element failed
}
dbListCreate(3) dbListDestroy(3) dbListRemove(3) dbListSetAddr(3)
dbListAdd(3) dbListModify(3) dbListChangeEnv(3) dbListGetId(3)
Get the list identifier from the list name.
listName <IN> Name of the list (ASCII NULL terminated string).
This is used to perform operation on the list such as :
add an element, remove an element, destroy the list, etc ..
listId <OUT> List Identifier. To be used for successive operations on
the list.
error <OUT> Error structure.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_LIST , Invalid list name : the list doe not exist
ccsERR_DB_LISTID , Invalid list identifier
ccsERR_NULL_PTR , Passed a null parameter
:
ccsERROR error;
dbLISTID listId;
if (dbListGetId("myList",&listId,&error) == FAILURE)
{
process failure condition
}
dbListDestroy(3) dbListAdd(3) dbListModify(3) dbListCreate(3)
dbListRemove(3) dbListExtract(3) dbListChangeEnv(3)
#include "db.h"
ccsCOMPL_STAT dbListModify(dbLISTID listId,
dbSYMADDRESS attrName,
vltINT32 bufSize,
void *buffer,
ccsERROR *error)
Insert a new or replace element in the list. If the element already exist,
it is modified according to the new values.
listId <IN> List Identifier, as returned by dbListCreate().
attrName <IN> Symbolic address of the database attribute, including
the ranges
bufSize <IN> Amount of data to be read or written (in bytes).
buffer <IN> Pointer to the buffer where the values are stored.
Both for Read and Write operations
error <OUT> Error structure.
The symbolic address can be specified using the following syntax :
- ":point1:point2.attribute"
- "<relative>:point1:point2.attribute"
- "<absolute>:point1:point2.attribute"
- "<alias>myalias.attribute"
If the type of addressing is dbDIRECT, the routine gets the direct address
and stores it in the attribute description to be used during the read/write
operations.
Direct addressing is allowed only for the local default database.
If the referenced database is another one the dbDIRECT flag is ignored and
the addressing switches automatically to 'symbolic'.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid attribute name
ccsERR_DB_LIST , List does not exist
ccsERR_DB_LISTID , Invalid list identifier
ccsERR_MEMORY , On memory allocation errors
ccsERR_NULL_PTR , One input paramater is NULL
:
ccsENVNAME envName;
ccsERROR error;
dbSYMADDRESS myVector;
vltINT32 myBuf[20];
vltINT32 bufSize;
dbLISTID listId;
strcpy(myVector,":point1:point2.vector(2:8)");
strcpy((char *) envName,"wte16");
if (dbListCreate("myList",envName,dbREAD,&listId,&error) == FAILURE)
{
process failure condition
}
add an element for read
if (dbListAdd(listId,myVector,sizeof(myBuf),0,&error) == FAILURE)
{
process failure condition
}
modify the element
strcpy(myVector,":point1:point2.vector(5:14)");
if (dbListModify(listId,myVector,sizeof(myBuf),0,&error) == FAILURE)
{
process failure condition
}
dbListCreate(3) dbListDestroy(3) dbListRemove(3) dbListSetAddr(3)
dbListAdd(3) dbListExtract(3) dbListChangeEnv(3) dbListGetId(3)
Remove an element from the list.
listId <IN> List Identifier, as returned by dbListCreate().
attrName <IN> Symbolic address of the database attribute to take out
from the list.
error <OUT> Error structure.
The symbolic address can be specified using the following syntax:
- ":point1:point2.attribute"
- "<relative>:point1:point2.attribute"
- "<absolute>:point1:point2.attribute"
- "<alias>myalias.attribute"
SUCCESS .
FAILURE and error returns :
ccsERR_DB_LISTID , Invalid list Identifier.
ccsERR_DB_INV_NAME , Invalid attribute name
:
ccsERROR error;
dbSYMADDRESS myVector;
dbLISTID listId;
strcpy(myVector,":point1:point2.vector(2:8)");
if (dbListCreate("myList","wte16",dbREAD,&listId,&error) == FAILURE)
{
process failure condition
}
remove an element from the list
if (dbListRemove(listId,myVector,&error) == FAILURE)
{
process failure condition
}
dbListDestroy(3) dbListAdd(3) dbListModify(3) dbListSetAddr(3)
dbListCreate(3) dbListExtract(3) dbListChangeEnv(3) dbListGetId(3)
#include "db.h"
ccsCOMPL_STAT dbLockPoint( const dbSYMADDRESS pointName,
const vltUINT32 seconds,
ccsERROR *error)
Locks a single point in the database.
pointName <IN> Name of the database point.
seconds <IN> Time-out for lock. If seconds is defined as 0
a default timeout of 3 seconds is used.
error <OUT> Error structure.
The time-out defines the period the point should locked by the
calling process. It has a minimum of 3 seconds and a maximum
of 60 seconds.
The point is released either by an explicit call to dbUnlockPoint()
or when the time-out expires.
The point can be addressed by either the symbolic or the alias name.
If the point is already locked, the calling process waits until the
point has been released.
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
dbSYMADDRESS pointName;
ccsERROR error;
strcpy((char *)pointName,"log:user_log");
if (dbLockPoint(pointName,0,&error) == FAILURE)
{
Process Error condition
}
Copy single CCS data types from buf2 to buf1.
It is base on the UNIX routine memcpy().
buf2 <OUT> destination buffer
buf1 <IN> origin buffer
dataType <IN> RTAP data type
vltINT8 c1,c2;
vltINT16 s1,s2;
vltINT32 l;
vltFLOAT f1,f2;
dbMemCpy(&c1, &c2, dbINT8);
dbMemCpy(&s1, &s22, dbINI16);
dbMemCpy(&f1, &f2, dbFLOAT);
dbMultiRead - reads a list of attributes. The routine can access
the local or a remote WS database and LCU databases
Reads a list of attributes.
This routine can be used to read data from multiple attribute values
in a given database (which is identified by the environment name specified
when the list is created).
listId <IN> List Identifier
error <OUT> Returned error structure.
This is equivalent to multiple calls to a dbReadSymbolic() or
dbreadDirect() routines, but with better performance especially for remote
access or LCU access.
The data are stored in the element of the list containing the attribute
description.
The type of addressing is defined for the whole list and for each element
there is a completion status indicating if the operation applied to a given
attribute was successful.
The read data are returned in a buffer where the single elements are
'packed' and must be extracted according to their data type.
If the database is not yet opened, the routine takes care to open it.
The user can access to the returned information for each attribute by
the routine dbListExtract().
SUCCESS .
FAILURE when no read operation can be done.
ccsERR_DB_BLOCK_CNT , Error while reading/writing some block
ccsERR_DB_INV_ADDR , Invalid address
ccsERR_DB_LISTID , Invalid list identifier
ccsERR_DB_READ , Generic Failure during reading
ccsERR_DB_LCU , generic Failure accessing LCU.
:
dbLISTID listId;
create a list
:
add attributes to the list
:
if (dbMultiRead(listId,&error) == FAILURE)
{
process Error condition
}
extract the read information by dbListExtract()
:
dbListCreate(3) dbListDestroy(3) dbListRemove(3) dbListModify(3)
dbListChangeEnv(3) dbListAdd(3) dbListSetAddr(3) dbMultiWrite(3)
dbListUnpack(3) dbListPack(3)
dbMultiWrite - writes a list of attributes. The routine can access
the local or a remote WS database.
Writes a list of attributes.
This routine can be used to write data to multiple attribute values
in a given database (which is identified by the environment name specified
when the list is created).
listId <IN> List Identifier
writeMode <IN> Determines the write mode operation and can be :
- dbBLOCK The list is treated as a unit and no values
are written unless all the addresses are
correct and writable by the caller.
- dbNORMAL The single attributes are treated individually,
and each write on a single attribute can
succeded or fail independent of the others.
error <OUT> Returned error structure.
This is equivalent to multiple calls to a dbWriteSymbolic() or
dbWriteDirect() routines, but with better performance.
The data to be written are stored in the element of the list containing
the attribute description.
The type of addressing is defined for the whole list and for each element
there is a completion status indicating if the operation applied to a given
attribute was successful.
If the database is not yet opened, the routine takes care to open it.
The user can access to the returned information for each attribute by
the routine dbListExtract().
SUCCESS .
FAILURE when no write operation can be done.
ccsERR_DB_BLOCK_CNT , Error while reading/writing some block
ccsERR_DB_LISTID , Invalid list identifier
ccsERR_DB_WRITE , Generic Failure during reading
ccsERR_DB_WRMODE , Invalid writeMode specifier.
:
create a list
:
add attribute(s) to the list
:
write list of attributes
if (dbMultiWrite("myList",dbBLOCK,&error) == FAILURE)
{
process Error condition
}
extract the information by dbListExtract()
:
dbListCreate(3) dbListDestroy(3) dbListRemove(3) dbListModify(3)
dbListChangeEnv(3) dbListAdd(3) dbListSetAddr(3) dbMultiRead(3)
Give back the CCS data type corresponding to the specified name.
name <IN> Data type name.
Supported data type names are :
- dbINT8, dbUINT8
- dbINT32, dbUINT32
- dbINT64, dbUINT64
- dbFLOAT, dbDOUBLE,
- dbLOGICAL
- dbPOLAR, dbRECTANGULAR
- dbDATE, dbTIME_OF_DAY, dbABS_TIME
- dbBYTES4, dbBYTES8, dbBYTES16, dbBYTES20, dbBYTES32,
dbBYTES48, dbBYTES64, dbBYTES80, dbBYTES128, dbBYTES256
- DB_XREF
char *typeName = "dbFLOAT";
if ((dataType = dbNameToType(typeName)) == dbUNDEFINED)
{
Process Error condition
}
Opens a connection to the database of the specified environment.
envName <IN> Name of the database (environment). If the first
character is an '@', it is ignored.
error <OUT> Error structure.
The routine establishes a connection to the database referenced by the
environment name
The routine opens a connection to the local database (the one specified by
th environment variable RTAPENV if the environment name is ccsLOCAL_ENV.
The type of environment is determined by the first letter of the name,
such as :
- 'l' defines an environment running on a LCU
- 'w' defines an environment running on a WS
All others make the routine exit with an error.
SUCCESS .
FAILURE and error returns :
ccsERR_ENV_NAME , Wrong environment name.
ccsERR_DB_OPEN , Cannot open database.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
#include "db.h"
ccsCOMPL_STAT dbReadDirect( const dbDIRADDRESS *dirAddr,
dbTYPE *dataType,
char *buffer,
vltINT32 size,
vltINT32 *actual,
vltUINT16 *recordCnt,
dbATTRTYPE *attrType,
ccsERROR *error );
Reads an attribute specified by its internal address in the LOCAL
database.
This provides a very fast access to database data.
The value is copied into the user buffer and it is up to the user to
provide a variable of a data type matching that of the read value.
dirAddr <IN> Direct address of the attribute.
dataType <OUT> data type : provide a description of the type of data
stored in the DB element.
dataType is 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it returns the type of each field of the
record .
buffer <IN> Buffer where the values are stored.
size <IN> Buffer size.
actual <OUT> Number of bytes actually written.
recordCnt <OUT> Number of record to be written. For an array
this concides with the number of elements to
be written.
attrType <OUT> Type of attribute : dbSCALAR, dbVECTOR or dbTABLE.
error <OUT> Error structure.
If the local database is not yet opened, the routine takes care to
open it.
SUCCESS, if everything is OK
FAILURE and error returns :
ccsERR_DB_READ , Failure during reading
ccsERR_DB_QUALITY , The 'quality' flag in not OK.
ccsERR_INV_ADDR , Invalid direct address
ccsERR_NULL_PTR , Buffer Pointer is NULL
ccsERR_BUFF_SIZE , Buffer size too small
ccsERR_DB_CATEGORY , Category mismatch
ccsERR_DB_GROUP , Group mismatch
ccsERR_DB_INV_RECEL , Invalid record/element in address
ccsERR_DB_INV_FIELD , Invalid field specifier in address
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE dataType[2];
char myBuf[10000];
vltINT32 actual
vltUINT16 recordCnt;
ccsERROR error;
strcpy((char *) pointName,":branch1:branch2:mypoint");
strcpy((char *) attrName,"param1");
Get direct address
if (dbGetDirAddr(&pointName,attrName,&dirAddr,&error) == FAILURE)
{
Process Error condition
}
if (dbReadDirect(&dirAddr,dataType,myBuf,sizeof(myBuf),
&actual,&recordCnt,&attrType,&error) == FAILURE )
{
Process Error condition
}
#include "db.h"
ccsCOMPL_STAT dbReadSymbolic( const dbSYMADDRESS pointName,
const char *attrName,
dbTYPE *dataType,
char *buffer,
vltINT32 size,
vltINT32 *actual,
vltUINT16 *recordCnt,
dbATTRTYPE *attrType,
ccsERROR *error );
Reads an attribute by means of its symbolic address.
The value is copied into the user buffer and it is up to the user to
provide a variable of a data type matching that of the read value.
pointName <IN> Address of the database point.
attrName <IN> Name of the attribute to be read including the
specification of ranges.
dataType <OUT> data type : provide a description of the type of data
stored in the DB element.
dataType is 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it returns the type of each field of the
record .
buffer <OUT> Buffer where the values are stored.
size <IN> Buffer size;
actual <OUT> Number of bytes actually read.
recordCnt <OUT> Number of record read.
attrType <OUT> Type of attribute : dbSCALAR, dbVECTOR or dbTABLE.
error <OUT> Error structure.
The database parameter can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
- By specifying the environment : "|envName:branch1:branch2"
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.'
at the beginning.
If the database is not yet opened, the routine takes care to open it.
This function supports the rosolution of static attributes in the object
oriented model implemented by the database loader
SUCCESS, if everything OK
FAILURE and error returns:
ccsERR_DB_INV_NAME , Invalid point, attribute or alias name
ccsERR_DB_READ , Generic failure during reading
ccsERR_DB_LCU , Failure during access to a LCU
ccsERR_DB_QUALITY , Bad data quality
ccsERR_NULL_PTR , In case of NULL pointer in input parameters
ccsERR_BUFF_SIZE , Buffer size too small
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE
ccsERR_DB_CATEGORY , Category mismatch
ccsERR_DB_GROUP , Group mismatch
ccsERR_DB_INV_RECEL , Invalid record/element in address
ccsERR_DB_INV_FIELD , Invalid field specifier in address
ccsERR_ENV_NOT_ACTIVE, ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE dataType[dbMAX_FIELD_CNT];
char userBuf[10000];
vltINT32 actual
vltUINT16 recordCnt;
ccsERROR error;
strcpy((char *) pointName,":branch1:branch2:mypoint");
strcpy((char *) attrName,"param1");
if ( dbReadSymbolic(pointName,attrName,dataType,userBuf,sizeof(userBuf),
&actual,&recordCnt,&attrType,&error) == FAILURE )
{
Process Error condition
}
switch(attrType)
{
Process Data according to attribute type : SCALAR, VECTOR or TABLE
}
Set the current working point.
pointName <IN> Name of the database point.
error <OUT> Error structure.
The point can be addressed by either the symbolic or the alias name as
follows :
- ":point1:point2:myPoint" to set Cwp in th local environment
- "@envName:point1:point2:myPoint" to set Cwp in a remote environment.
Each process can set its own Current Working Point, which is then pre-pended
to all symbolic addresses making use of a 'relative' path.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_SETCWP , Invalid point name
ccsERR_NULL_PTR , In case of NULL pointer in input parameters.
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
dbSYMADDRESS pointName;
ccsERROR error;
strcpy((char *) pointName,":point1:point2:myPoint");
if (dbSetCwp(pointName,&error) == FAILURE) {
{
Process failure condition
}
Convert a string into the equivalent data element value.
dataType <IN> Type of data to be converted, for example : dbINT8,
dbUINT32, dbBYTES20, dbLOGICAL, dbPOLAR, etc ..
string <IN> ASCII representation of the value
buffer <OUT> User defined buffer of the type specified in the
dataType parameter.
Hereafter there are the string formats for some of the data types.
Data Type | Input String Format
........................................................................
dbLOGICAL only values of '0' or '1' are valid.
dbPOLAR {1.35, -3.7d} the two values are magnitude and angle (in degree).
dbRECTANGULAR {6.37+4.3j} the two values are real and imaginary parts
dbABS_TIME yyyy-mm-ddThh:mm:ss[.uuuuuuu]
dbDATE yyyy-mm-dd
dbTIME hh:mm:ss[.uuuuuuu]
dbStrToDe returns FAILURE for a float which equals the maximum
abs value of a float (i.e. 3.40282347e+38 - see /usr/include/limits.h).
It returns SUCCESS for all other permitted values,including 3.40282346e+38
and the minimum value 1.17549435e-38.
This is quite unfortunate, as many of the DB floats seem to be initialized
to this value, i.e. a write-back after reading such a float fails.
The behaviour for doubles is OK for the full range.
Unlock a point in the database.
pointName <IN> Name of the database point.
error <OUT> Error structure.
The point can be addressed by either the symbolic or the alias name.
This function does not support the rosolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
dbSYMADDRESS pointName;
ccsERROR error;
strcpy((char *)pointName,":point1:point2");
if (dbUnlockPoint(pointName,&error) == FAILURE)
{
Process failure condition
}
dbWriteDirect - writes values to an attribute by means of
its internal address in the LOCAL database
#include "db.h"
ccsCOMPL_STAT dbWriteDirect( const dbDIRADDRESS *dirAddr,
const dbTYPE *dataType,
const char *buffer,
vltINT32 size,
vltINT32 *actual,
vltUINT16 recordCnt,
dbATTRTYPE attrType,
ccsERROR *error );
Writes values to an attribute by means of its internal address in the
LOCAL database.
This provides a very fast access to the database parameter.
It is up to the user to store the values in the buffer with the proper
format according to the data type.
dirAddr <IN> Direct address of the attribute.
dataType <IN> data type : provide a description of the type of data
stored in the DB element.
DataType is 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it returns the type of each field of the
record .
dataType <IN> Attribute data type. For TABLES this is an array
providing the data type for each field.
buffer <IN> Buffer where the values are stored.
size <IN> Total number of bytes to be written.
actual <OUT> Number of bytes actually written.
recordCnt <IN> Number of records to be written. For an VECTOR
this concides with the number of elements to
be written.
attrType <IN> Type of attribute : dbSCALAR, dbVECTOR or dbTABLE.
error <OUT> Error structure.
If the local database is not yet opened, the routine takes care to
open it.
Handling of Strings
When the parameter <size> does not match the total size of the attribute
(or the field length for tables), the remaining portion of the buffer
is filled with '\0'.
This applies only to SCALARS or when writing a single element of a VECTOR
or a single TABLE field.
SUCCESS, if everything OK
FAILURE and error returns:
ccsERR_DB_WRITE , Generic Failure during writing
ccsERR_INV_ADDR , Invalid direct address
ccsERR_NULL_PTR , Buffer Pointer is NULL
ccsERR_INV_RECEL , Invalid Record Element
ccsERR_ATTR_TYPE , Invalid attribute type
ccsERR_DE_TYPE , Data Type mismatch
ccsERR_DB_CATEGORY , Category mismatch
ccsERR_DB_GROUP , Group mismatch
ccsERR_DB_INV_RECEL , Invalid record/element in address
ccsERR_DB_INV_FIELD , Invalid field specifier in address
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE dataType[dbMAX_FIELD_CNT];
vltINT16 buffer[] = {1,23,-56,6};
vltINT32 bufSize;
vltINT32 actual
vltUINT16 recordCnt;
ccsERROR error;
attrType = dbVECTOR;
dataType[0] = dbINT16;
dataType[1] = 0;
recordCnt = 4
bufSize = recordCnt*sizeof(vltINT16);
strcpy((char *) pointName,":PARAMS:VECTORS");
strcpy((char *) attrName,"vector_int16");
Get direct address
if (dbGetDirAddr(&pointName,attrName,&dirAddr,&error) == FAILURE)
{
Process Error condition
}
if (dbWriteDirect(&dirAddr,dataType,buffer,bufSize,
&actual,recordCnt,attrType,&error) == FAILURE )
{
Process Error condition
}
Example where string padding with NULLs is performed
strcpy((char *)pointName,":PARAMS:VECTORS.vector_string20(3)");
strcpy(cbuf,"Hello World");
if (dbGetDirAddr(&pointName,attrName,&dirAddr,&error) == FAILURE)
{
Process Error condition
}
if (dbWriteDirect(&dirAddr,dataType,cbuf,strlen(cbuf),
&actual,recordCnt,attrType,&error) == FAILURE )
{
Process Error condition
}
#include "db.h"
ccsCOMPL_STAT dbWriteSymbolic( const dbSYMADDRESS pointName,
const char *attrName,
const dbTYPE *dataType,
const char *buffer,
vltINT32 size,
vltINT32 *actual,
vltUINT16 recordCnt,
dbATTRTYPE attrType,
ccsERROR *error );
Writes values into an attribute by means of its symbolic name.
It is up to the user to store the values in the buffer with the proper
format according to the data type.
pointName <IN> Address of the database point.
attrName <IN> Name of the attribute to be written.
dataType <IN> data type(s); provides a description of the type of
data stored in the DB element.
dataType must be 'ZERO' terminated, therefore its size
must be at least 2 (for SCALARS and VECTORS).
SCALARS and VECTOR are described by only one element.
For TABLES, it should contain the type of each field
of the record .
buffer <IN> Buffer where the values are stored.
size <IN> Total number of bytes to be written.
actual <OUT> Number of bytes actually written.
recordCnt <IN> Number of record to be written. For an array
this concides with the number of elements to
be written.
attrType <IN> Type of attribute : dbSCALAR, dbVECTOR or dbTABLE.
error <OUT> Error structure.
The database parameter can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
- By specifying the environment : "|envName:branch1:branch2"
The attribute name must be detailed enough to describe the data
contained in the buffer.
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.'
at the beginning.
If the database is not yet opened, the routine takes care to open it.
Handling of Strings
When the parameter <size> does not match the total size of the attribute
(or the field length for tables), the remaining portion of the buffer
is filled with '\0'.
This applies only to SCALARS or when writing a single element of a VECTOR
or a single TABLE field.
SUCCESS, if everything OK
FAILURE and error returns :
ccsERR_DB_INV_NAME , Invalid point, attribute or alias name
ccsERR_DB_WRITE , Generic Failure during writing
ccsERR_DB_LCU , Failure during access to a LCU
ccsERR_NULL_PTR , In case of NULL pointer in input parameters.
ccsERR_DB_DE_TYPE , Datatype mismatch
ccsERR_DB_ATTR_TYPE , Attribute Type mismatch
ccsERR_DB_NO_RTAP , Failure when calling RTAP with CCS LITE.
ccsERR_DB_CATEGORY , Category mismatch
ccsERR_DB_GROUP , Group mismatch
ccsERR_DB_INV_RECEL , Invalid record/element in address
ccsERR_DB_INV_FIELD , Invalid field specifier in address
ccsERR_ENV_NOT_ACTIVE,ccsERR_REMOTE_LINK, The DB is unreacheable
or ccsERR_DB_OPEN
The routine allows to write up to 8000 bytes of data ONLY !!
This function does not support the resolution of static attributes in
the object oriented model implemented by the database loader, because
it is not allowed to access static attributes for WRITE but only for
READ.
As a consequence the address for a static attribute (a sub-point)
is treated as a non existing point
dbATTRIBUTE attrName;
dbSYMADDRESS pointName;
dbATTRTYPE attrType;
dbTYPE dataType[dbMAX_FIELD_CNT];
vltINT16 recordCnt, buffer[]={ 23,7,-9,-23};
vltINT32 bufSize,actual;
ccsERROR error;
char cbuf[80];
attrType = dbVECTOR;
dataType[0] = dbINT16;
dataType[1] = 0;
recordCnt = 4
size = recordCnt*sizeof(vltINT16);
strcpy((char *)pointName, "point1:point2");
strcpy((char *)attrName , "vector(3:6)");
if (dbWriteSymbolic(pointName,attrName,dataType,buffer,bufSize,
&actual,recordCnt,attrType,&error) == FAILURE )
{
Process Error condition
}
Example where string padding with NULLs is performed
strcpy((char *)pointName,":PARAMS:VECTORS.vector_string20(3)");
strcpy(cbuf,"Hello World");
if (dbWriteSymbolic(pointName,dbEMPTY,dataType,cbuf,strlen(cbuf),
&actual,recordCnt,attrType,&error) == FAILURE )
{
Process Error condition
}
#include "err.h"
ccsCOMPL_STAT errAdd ( ccsERROR *error,
const ccsMODULEID moduleId,
vltINT16 errorNumber,
const ccsLOC_ID locId,
char *format, (not Used on WS)
... )
Add a new log to the current error stack.
error <IN> Error Structure containing previous error context.
moduleId <IN> Module Identifier
errorNumber <IN> Error Number
locId <IN> Name of the routine/function generating the error
The preprocessor directive __FILE__ can be used.
format <IN> ( NOT USED ON WS or LCU using new format)
Format string for old format on LCU
... <IN> Variable list of run time parameters.
Error numbers are identified by mnemonics.
A new error is processed as follows :
- Log previous error (if the stack not empty). If the environment name
is not the same as the local one, the error log is logged to the remote
environment.
- Get a new stack identifier (if stack empty).
- Increase the error sequence number.
- Set current error structure according to the new error condition.
A new stackId is read from the RTAP database.
The error message is read from the error definition and it looks like a
'printf format' containing conversion specifications to be applied to the
run time parameters.
SUCCESS A log is issued in the following cases :
- error structure is a NULL pointer.
- moduleId is not existing.
- the error number does not have the corresponding error format.
The current implementation uses the routine errAdd_v() which can be
embedded in other routines having a variable number of parameters.
(See K&R section : Variable length Argument List).
ccsERROR error;
:
:
if (funct2(p2,&error) == FAILURE)
{
if (error can be recovered)
{
errResetStack(&error);
}
else
{
errAdd(&error,"module",moduleERR_INV_PARAMETER,__FILE__,DUMMY,p2);
return(FAILURE);
}
}
If the last error of the sequence cannot be recovered, the stack must be
closed and reset.
error <IN> Error Structure containing previous error context.
Therefore as general rule it is up to the application to close the error
stack and then, if appropriate, generate an alarm to notify the user the
error could not be recovered.
#define MAIN
main ()
{
ccsERROR error;
if (funct1(p1,p2,&error) == FAILURE)
{
if (error cannot be recovered) errCloseStack(&error);
}
.
.
}
Copy the content of and error structure into another.
The stack belonging to one error structure is not copied.
errDest <OUT> Destination error structure
errSrc <IN> Error structure to be copied.
errDisplay - Displays the error stack and close the stack.
errOpenDisplay - Displays the error stack but it does not close the stack.
#include "err.h"
ccsCOMPL_STAT errDisplay ( ccsERROR *error,
vltLOGICAL suspend)
ccsCOMPL_STAT errOpenDisplay ( ccsERROR *error,
vltLOGICAL suspend)
Displays the whole error stack associated to the current error context
described in the error data structure.
error <IN> Error Structure containing the current error context.
suspend <IN> Flag controlling the behaviour of the application :
- ccsTRUE The application suspend execution until
the user aknowledge the error
- ccsFALSE The application continues execution
The routine logs the last error and resets the stack.
This routine can be used in place of errCloseStack if the application
wants to close the stack and display it to the user.
The error dialog shows the following informations about the last error :
- Error Severity
- Name of the process generating the error
- Complete error description
It is up to the user to display the whole stack, by clicking on
"Show Stack"
As general rule it is up to the application to close the error stack and
then, if appropriate, generate an alarm to notify the user the error
could not be recovered.
The behaviour is determined by the definition of the following
environment variables :
DISPLAY - Defines the name of the display. If this is not defined
No error dialog can be shown to the user.
NO_ERR_DISPLAY - Forces errDisplay not to show the error dialog
regardless the value of the env. variable DISPLAY.
LOG_ON_STDOUT - Instruct the logging routines to print the error/logs
on the screen.
The following table explains the behavior of errDisplay according to the
setting of the above env. variables ( 1 = defined , 0 = not defined or empty)
The env. variable DISPLAY is DEFINED :
NO_ERR_DISPLAY LOG_ON_STDOUT |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
0 0 | The error dialog box appears
0 1 | The error dialog box appears and
| all error logs appear on the screen
1 0 | The top error is printed on the screen
1 1 | All error logs appear on the screen
The env. variable DISPLAY is NOT DEFINED : a warning message appear on
the screen and the errors are handled as follows.
NO_ERR_DISPLAY LOG_ON_STDOUT |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
0 0 | The top error is printed on the screen
0 1 | All error logs appear on the screen
1 0 | The top error is printed on the screen
1 1 | All error logs appear on the screen
main ()
{
ccsERROR error;
if (funct1(p1,p2,&error) == FAILURE)
{
if (error cannot be recovered) errDisplay(&error,ccsTRUE);
}
.
.
}
3.2.68 errInStack
#include "err.h"
vltLOGICAL errInStack (ccsERROR *error,
const ccsMODULEID moduleId,
vltINT16 errorNumber)
This routines allows the user to check if a given error is part of the
error stack : the error is univocally addressed by the moduleId and the
corresponding mnemonic.
error <IN> Error Structure containing current error context.
moduleId <IN> Module Identifier
errorNumber <IN> Error Number
ccsMODULEID mod;
ccsERROR error;
strcpy(mod,"trk");
if (errInStack(&error,mod,trkERR_PRESET) == ccsTRUE)
{
error trkERR_PRESET was found in the stack
}
else
{
The stack does not contain the error
}
#include "err.h"
ccsCOMPL_STAT errIsReason (ccsERROR *error,
const ccsMODULEID moduleId,
vltINT16 errorNumber,
vltLOGICAL *errFound,
ccsSTACK_ELEM **errDescription)
This routines allows the user to look for a specific error in the
error stack. The routine scans the error stack until it finds an
error matching both <moduleId> and <errorNumber> or it reaches the end.
error <IN> Error Structure containing current error context.
moduleId <IN> Module Identifier
errorNumber <IN> Error Number
errFound <OUT> Returned flag to indicate whether the specific error
in in the stack : ccsTRUE/ccsFALSE.
errDescription <OUT> Returns the pointer to the element in the error stack
containing the specific error, or NULL the error
has not been found.
Sometimes it does not not make sense to propagate to the higher level
all the detailed information on the cause of an error.
The application can look in the stack if specific error conditions have
occurred : for example an error can rise due to a bad quality of a DB
attribute, but the toplevel error could report the failure of a higher
level operation (for instance modERR_COMAND_FAILED ... )
ccsMODULEID mod;
ccsERROR error;
ccsSTACK_ELEM *stackElem;
vltLOGICAL errFound,
strcpy(mod,"trk");
if (errIsReason(&error,mod,trkERR_PRESET,&found,&stackElem) == FAILURE)
{
return(FAILURE);
}
if (found == ccsTRUE)
{
examine error description stored in stackElem.
...
errPrint((ccsERROR *) stackElem);
...
}
This routine takes the error at the top of the stack and converts the
error number into the equivalent CCS error number.
error <IN> Error Structure
Several LCC errors can be grouped into a single VLT error.
CCS Error LCC Error Description
___________________________________________________________
ccsERR_PARAMETER lccERR_PARAMETER Invalid Parameter
ccsERR_MSG_Q_FULL lccERR_FULL Message queue or buffer full
ccsERR_BOOK_BOOKABLE lccERR_BOOKABLE Process is bookable (obsolete)
ccsERR_BOOK_SHARABLE lccERR_SHARABLE Process is sharable (obsolete)
ccsERR_BOOK_BOOKED lccERR_BOOKED Process is booked (obsolete)
ccsERR_DB_INV_NAME lccERR_INV_NAME Syntax error in symbolic name
lccERR_ATTRIBUTE Invalid attribute name
lccERR_POINT Invalid point name
lccERR_MULTI Several parameters addressed
lccERR_NOT_FOUND
ccsERR_EVT_LCU lccERR_NO_EVENTS No events defined for process
lccERR_EVENTS_EXIST Events already defined
lccERR_ORDER Invalid order for event
configuration values
lccERR_EVENT Attribute is not configured
for events
ccsERR_PROC_NAME lccERR_PROC_NAME Invalid process name
ccsERR_MSG_TYPE lccERR_MSG_TYPE: Invalid message type
ccsERR_MSG_SIZE lccERR_MSG_SIZE: Message too big
ccsERR_MSG_Q_EMPTY lccERR_Q_EMPTY: No matching message in queue
ccsERR_MSG_CMD lccERR_MSG_CMD Invalid command received
lccERR_UNKNOWN_CMD Command not found
lccERR_CMD_SYNTAX Syntax error in command
lccERR_BAD_PARAM_NB Invalid number of parameters
lccERR_BAD_PARAM_VAL Bad parameter value
lccERR_MISSING_PARAM_VAL Missing parameter value
ccsERR_CMD_CDT_FILE lccERR_FILE_CDT Syntax error in Command
Definition Table
ccsERR_PROC_NAME lccERR_NOT_REGISTERED Process not registered
ccsERR_BUFF_SIZE lccERR_BUF_SIZE Buffer too small
ccsERR_DB_INV_ADDR lccERR_DIRADDRESS Invalid DB direct address
ccsERR_DB_DE_TYPE lccERR_DE_TYPE Invalid data type
ccsERR_ENV_NAME lccERR_ENV_NAME Invalid environment
ccsERR_DB_ATTR_TYPE lccERR_ATTR_TYPE Invalid attribute type
ccsERR_DB_INV_RECEL lccERR_INV_RECEL Invalid record specification
ccsERR_DB_INV_FIELD lccERR_INV_FIELD Invalid field specification
ccsERR_MSG_PARSE lccERR_MSG_PARSE Failed to parse runstring
ccsERR_TIMS_CONVERT lccERR_TIMS_CONVERT Unable to convert string
cceERROR &error;
switch (errLccToCcs(&error))
{
case ccsERR_DB_INV_NAME:
process error condition
break;
case ccsERR_MSG_SIZE:
process error condition
break;
case errNOT_CONVERTED:
got back original error
break;
default:
do nothing
}
Merge the error stack of errSrc to the one of errDest.
The stack of errSrc is addet to the stack of errDest according to the
flag specification -e.g.- TOP or BOTTOM.
errDest <OUT> Error Structure containing the stack to be modified
errSrc <IN> Error Structure containing the stack to be copied
flag <IN> Indicates how the two stack are merged.
The flag can assume these two values :
- errTOP , The errSrc stack will be added at the top
of the errDest stack.
- errBOTTOM The errSrc stack will be added at the bottom
of the errDest stack.
The stack identifier of the new added part of the stack will be changed
according to the lower part of the stack.
The description of the error stored in the ccsERROR structure is changed
according to the new top element of the stack.
#include "err.h"
ccsCOMPL_STAT errPrint (ccsERROR *error)
ccsCOMPL_STAT errPrintStderr (ccsERROR *error)
Prints the content of the local error structure on the screen,
alternatively on the stderr for the errPrintStderr version
error <IN> Error Structure containing previous error context.
The error information is presented as follows :
---------------------- Error Structure ----------------------
Time Stamp : yy-mm-dd hh:mm:ss.uuuuuu
Process Number : <pid> Process Name : <name>
Environment : <envName> StackId : <stackId> Sequence : <sequence N.>
Error Number : <number> Severity : <W>
ModuleId : <module> location : <location>
Error Text : < text ...>
#define MAIN
main ()
{
ccsERROR error;
if (funct1(p1,p2,&error) == FAILURE)
{
if (error cannot be recovered)
{
errPrint(&error);
errCloseStack(&error);
}
}
.
.
}
Initialize the error structure to start a new error stack.
error <IN>/<OUT> returned error structure
The routine initializes the following error parameters :
- envName = Environment name
- sequenceNumber = 0 This is used to check whether the stack is empty.
- runTimePar It is initialized as an empty string.
The routine must be called :
- Always at the beginning of an application. This is already included
in ccsInit().
- When a calling routine returns an error condition and such error
can be fixed.
ccsERROR error;
:
:
if (funct2(p2,&error) == FAILURE)
{
if (error can be recovered)
{
errResetStack(&error);
}
else
{
process error condition
}
}
errSetStack - Initialize the error structure according to the error context
sent back by the message system in the error reply message.
Initialize the error structure according to the error context
sent back by the message system in the error reply message.
error <OUT> Returned error structure initialized with the new stack
description.
message <IN> Message header
The following fields of the local error structure are initialized :
- envName
- sequenceNumber
- runTimePar
- stackId
#include "err.h"
ccsCOMPL_STAT errSysAdd ( ccsERROR *error,
const ccsMODULEID moduleId,
vltINT16 errorNumber,
const ccsLOC_ID locId,
char *format, (not Used on WS)
char *sysModule,
... )
Add RTAP, UNIX or VxWorks errors to the stack.
error <IN> Error Structure containing previous error context.
moduleId <IN> Module Identifier
errorNumber <IN> Error Number
locId <IN> Name of the routine/function generating the error
The preprocessor directive __FILE__ can be used.
format <IN> ( NOT USED WS or LCU using new format)
Format string for old format on LCU.
sysModule <IN> System producing the errors : UNIX, RTAP or VxWorks.
... <IN> Variable list of run time parameters.
Error numbers are identified by mnemonics.
Valid sysModule parameters are : modRTAP and modUNIX for CCS and
modVXWORKS for lcc.
A new error is processed as follows :
- Log previous error (if the stack not empty). If the environment name
is not the same as the local one, the error log is logged to the remote
environment.
UNIX Error : The UNIX global error number and error message is
converted into the CCS error format and logged.
RTAP Error : RTAP generates its own error stack and every element of the
stack is converted into the CCS error format and logged.
VxWorks Error : The VxWorks process error number and error message is
converted into the CCS error format and logged.
- Get a new stack identifier (if stack empty).
- Increase the error sequence number.
- Set current error structure according to the new error condition.
A new stackId is read from the RTAP database.
The error message is read from the error definition and it looks like a
'printf format' containing conversion specifications to be applied to the
run time parameters.
SUCCESS A log is issued in the following cases :
- error structure is a NULL pointer.
- moduleId is not existing.
- sysModule is not valid.
- the error number does not have the corresponding error format.
The current implementation uses the routine errSysAdd_v() which can be
embedded in other routines having a variable number of parameters.
(See K&R section : Variable length Argument List).
int funct2(int p2, ccsERROR *error)
{
if ((fileHandle = open(filename,O_RDWR)) == -1)
{
errSysAdd(error,"module",moduleERR_FILE,__FILE__,DUMMY,modUNIX,filename);
return(FAILURE);
}
if (rtapFunction(...) == rtFAILURE)
{
errSysAdd(error,"module",moduleERR_DB_READ,__FILE__,DUMMY,modRTAP,var1);
return(FAILURE);
}
if (vxworksFunction(...) == rtFAILURE)
{
errSysAdd(error,"module",moduleERR_DB_READ,__FILE__,DUMMY,
modVXWORKS,var1);
return(FAILURE);
}
return(SUCCESS);
}
evtAttach - Configure the database to generate an event
when a process accesses a specific database attribute.
#include "evt.h"
ccsCOMPL_STAT evtAttach( dbSYMADDRESS attrName,
evtFILTER filter,
evtEVENT_ID *eventId,
ccsERROR *error)
Configure the database to generate an event when a process accesses a
specific database attribute.
attrName <IN> Name of the attribute.
filter <IN> Condition to generate the event. This depends on the
attribute type as follows :
WS :
- SCALARS Generate events for the following triggering
conditions :
evtLESS, evtLESS_OR_EQUAL, evtEQUAL,
evtGREATER,evtGREATER_OR_EQUAL, evtNOT_EQUAL,
evtANY_WRITE
- VECTORS Generate events only on write : evtANY_WRITE
- TABLES Generate events only on write : evtANY_WRITE
LCU :
- SCALARS Generate events for the following triggering
conditions :
. evtANY_WRITE : event generated for every write,
. evtNOT_EQUAL : event generated whenever the value is changed,
. evtDEAD_BAND : event generated when the value has changed
more than the deadband or one of the limits is
crossed (deadband and limits are defined by
evtConfig()).
eventId <OUT> Event identifier. The event is identified by the name
of the environment where it occurred and the event
number within such environment.
error <OUT> Error structure.
The database parameter can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
- By specifying the environment : "@envName:branch1:branch2"
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.' at the beginning.
If the database is not yet opened, the routine takes care to open it.
SUCCESS .
FAILURE and error returns :
ccsERR_EVT_INV_NAME , Invalid point or attribute name
ccsERR_EVT_FILTER , Invalid Filter specification
ccsERR_EVT_EVENT , Generic failure.
ccsERR_EVT_LCU , Could not attach event to LCU
ccsERR_ENV_NAME , Invalid Environment Name
#include "evt.h"
dbSYMADDRESS pointName;
evtEVENT_ID eventId;
strcpy(pointName,":MYBRANCH:MYPOINT.myattribute");
if ( evtAttach(pointName,
evtANY_WRITE,
&eventId,
&error) == FAILURE)
{
.... error processing ...
}
evtAttachExt - Extended evtAttach. Configure database event
attachment with optional user message and other
event message recipiant.
#include "evt.h"
ccsCOMPL_STAT evtAttachExt( dbSYMADDRESS attrName,
evtFILTER filter,
ccsENVNAME evtEnv,
ccsPROCNAME evtProc,
char *userMsg,
evtEVENT_ID *eventId,
ccsERROR *error)
Configure the database to generate an event when a process accesses a
specific database attribute. Similar to evtAttach but with the difference
that an optional message string can be included in the event message.
Furthermore another event receiving process can be specified.
attrName <IN> Name of the attribute.
filter <IN> Condition to generate the event. This depends on the
attribute type as follows :
- SCALARS Generate events for the following triggering
conditions :
evtLESS, evtLESS_OR_EQUAL, evtEQUAL,
evtGREATER,evtGREATER_OR_EQUAL, evtNOT_EQUAL,
evtANY_WRITE
- VECTORS Generate events only on write : evtANY_WRITE
- TABLES Generate events only on write : evtANY_WRITE
ccsENVNAME <IN> Environment of the process receving events.
NULL have to be passed for current environment.
ccsPROCNAME <IN> Name of the process receving events.
NULL have to be passed for current process.
char* <IN> User message - a string that will be included in the
event message.
eventId <OUT> Event identifier. The event is identified by the name
of the environment where it occurred and the event
number within such environment.
error <OUT> Error structure.
The database parameter can be addressed using the following syntax :
- By its symbolic address : ":branch1:branch2"
"<relative>:branch1:branch2"
"<absolute>:branch1:branch2"
- By its alias : "<alias>myalias"
- By specifying the environment : "@envName:branch1:branch2"
If attrName = dbEMPTY, it is assumed that the attribute name is
directly specified in the pointName.
The attribute name can be specified WITH or WITHOUT the '.' at the beginning.
If the database is not yet opened, the routine takes care to open it.
SUCCESS .
FAILURE and error returns :
ccsERR_EVT_INV_NAME , Invalid point or attribute name
ccsERR_EVT_FILTER , Invalid Filter specification
ccsERR_EVT_EVENT , Generic failure.
ccsERR_ENV_NAME , Invalid Environment Name
ccsERR_ENV_NOT_ACTIVE, Environment not active
ccsERR_PROC_INFO , Event receiving process does exist
#include "evt.h"
dbSYMADDRESS pointName;
evtEVENT_ID eventId;
strcpy(pointName,":MYBRANCH:MYPOINT.myattribute");
if ( evtAttachExt(pointName,
evtANY_WRITE,
NULL,
NULL,
"Event occured",
&eventId,
&error) == FAILURE)
{
.... error processing ...
}
#include "evt.h"
rtEventId *(*attachFunc)(rtDbConnection dbConnection, rtDbAddress addr,
rtProcessId *who, rtUInt8 enable, rtHangerStatus status,
rtInt32 pri, rtUInt16 size, rtHangerMsg *msg);
ccsCOMPL_STAT evtDetach( evtEVENT_ID *eventId,
ccsERROR *error )
Remove the event definition from the database. The routine requires the
complete definition of the event when it was created.
eventId <IN> Event identifier as returned by evtAttach().
The event is identified by the name of the environment
where it occurred and the event number within such
environment.
error <OUT> Error structure.
SUCCESS .
FAILURE and error returns :
ccsERR_EVT_EVENT , Invalid event specification.
ccsERR_EVT_LCU , Could not attach event to LCU
#include "evt.h"
ccsCOMPL_STAT evtParseMsg( msgHEADER *message,
evtEVENT_ID *event,
vltUINT8 *trigger,
msgPROCESSID *triggerProc,
dbSYMADDRESS attrName,
dbATTRTYPE *attrType,
evtDATA *eventInfo,
char **userMsg,
ccsERROR *error )
Parses the event message.
message <IN> Pointer to the event message. (as provided by msgRecvMsg)
eventId <OUT> Event identifier. The event is identified by the name
of the environment where it occurred and the event
number within such environment.
trigger <OUT> Event trigger condition.
triggerProc <OUT> Processid of the process that caused the event.
attrName <OUT> Symbolic address of the database attribute where the
event occurred.
attrType <OUT> Attribute Type : SCALAR, VECTOR or TABLE
eventInfo <OUT> Return the information related to the event.
This information depends on the attribute type and
it is stored in three different data structures :
evtSCALAR_INFO, evtVECTOR_INFO, evtTABLE_INFO.
userMsg <OUT> Return the attached user message (optional).
If NULL is returned no user message was attached.
error <OUT> Error structure.
The information returned by the event depends on the type of the attribute
and it is described as follows :
SCALAR Attributes :
data Type | member | Comment
........................................................................
dbTYPE dataType;
vltUINT8 oldQuality; The Quality Flag can be : dbATTR_SUSPECT,
vltUINT8 newQuality; dbATTR_ERROR, dbATTR_DISABLED
char oldValue[256]; Buffer containing the old/new value, must
char newValue[256]; they must be casted to the real data type.
VECTOR Attributes :
data Type | member | Comment
........................................................................
vltUINT16 startElem These two parameters identify the portion
vltUINT16 endElem of the vector where the event occurred.
TABLE Attributes :
data Type | member | Comment
........................................................................
vltUINT16 startElem These two parameters identify the portion
vltUINT16 endElem of the table where the event occurred.
vltUINT8 startField;
vltUINT8 endField;
evtEVENT_ID eventId;
evtDATA eventInfo;
msgHEADER *message;
msgRECEIVEFILTER msgFilter;
msgPROCESSID triggerProc;
dbSYMADDRESS dbAttribute;
dbATTRTYPE attrType;
vltUINT8 trigger;
ccsERROR error;
vltUINT8 oldQuality,newQuality;
vltINT16 oldValue,newValue
vltUINT8 startField,endField;
vltUINT16 startElem, endElem;
The message system delivers the received message which is processed
by evtParseMsg to extract the event information
if (msgRecvMsg(&msgFilter,msgNO_TIMEOUT, &message, &error) != SUCCESS)
{
.... error processing ...
}
if (message->msgType == msgTYPE_EVENT)
{
if (evtParseMsg( message, &eventId, &trigger, &triggerProc,
dbAttribute, &attrType, &eventInfo, NULL,
&error) == FAILURE
{
.... error processing ...
}
switch (attrType)
{
case dbSCALAR: Get information on a scalar attribute
dataType = eventInfo.scalar.dataType;
oldQuality = eventInfo.scalar.oldQuality;
newQuality = eventInfo.scalar.newQuality;
dbMemCpy(&oldValue,eventInfo.scalar.oldValue,dbINT16);
dbMemCpy(&onewValue,eventInfo.scalar.newValue,dbINT16);
break;
case dbVECTOR: Get information on a vector attribute
startElem = eventInfo.vector.startElem;
endElem = eventInfo.vector.endElem;
break;
case dbTABLE: Get information on a table attribute
startElem = eventInfo.table.startElem;
endElem = eventInfo.table.endElem;
startField = eventInfo.table.startField;
endField = eventInfo.table.endField;
break;
evtSingleDisable - De-activate the event, that is, stops sending
the event notification to the process.
De-activate the event, that is, stops sending the event notification to
the process.
eventId <IN> Event identifier as returned by evtAttach().
The event is identified by the name of the environment
where it occurred and the event number within such
environment.
error <OUT> Error structure.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_EVENT , Invalid event specification.
ccsERR_EVT_LCU , Could not attach event to LCU
evtSingleEnable - Activate the event, that is, allow the RTAP event
manager to send an event notification to the
process.
Activate the event, that is, allow the RTAP event manager to send an event
notification to the process.
eventId <IN> Event identifier as returned by evtAttach().
The event is identified by the name of the environment
where it occurred and the event number within such
environment.
error <OUT> Error structure.
SUCCESS .
FAILURE and error returns :
ccsERR_DB_EVENT , Invalid event specification.
ccsERR_EVT_LCU , Could not attach event to LCU
#include "log.h"
ccsCOMPL_STAT logData ( const ccsMODULEID moduleId,
vltUINT8 logId,
const char *logText)
ccsCOMPL_STAT logData1 ( const ccsMODULEID moduleId,
vltUINT8 logId,
const char *logText
... )
Store a single log in log file.
moduleId <IN> Module reporting the log.
logId <IN> User tag.
logText <IN> Text to be logged.
logData :
The application provides an already formatted string describing the information
to be logged.
logData1 :
The application provides a string containing format patterns to be used to
actually create the final log message. The parameters following 'logText' are
used as arguments to create the log message (as by printf)
The user's defined log is concatenated with the 'logging system' part,
which contains the following information :
- Time Stamp
- Environment Name
- Module Id
- Process Name
- Process Number
LogId is a 'positive' number used to identify the format of the log.
If logId is negative the routine converts it to positive.
If the environment variable LOG_ON_STDOUT is set the routine
prints the log on standard output (screen by default)
The variable must exist, no matter its value -e.g.- setenv LOG_ON_STDOUT.
ccsMODULEID moduleId;
vltUINT8 logId = 0;
char log[logTEXT_LEN];
strcpy((char *)moduleId,"tcs");
strcpy(log," Telecope T1 tracking ");
logData(moduleId,logId,log);
#include "log.h"
ccsCOMPL_STAT logFitsAction ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logACTION fitsAction)
Generates a log describing an action : typical examples are opening
and closing operations or moving the telescope.
module <IN> Module's name.
fitsDict <IN> Defines the dictionary where to check the correctness
of the Fits action verb and keywords.
This information is stored internally and it is used
as default value when this is NULL.
fitsCat <IN> Category : it is pre-defined and designated by a
3-letter abbreviation.
Examples of 'category' are DET (Detector)
TEL (Telescope) ADA (Adapter) or INS (Instrument)
fitsSys <IN> Subsystem : identifies a component in a category and
can consist of zero or at maximum 2 words.
Examples of 'subsystems' are GRIS (grism), LAMP,
CCD (detector Chip) or EXPO (Exposure Descrition)
fitsAction <IN> Single verb defining the action
The log will be stored in the following format :
hh:mm:ss> -action category [subsystem(s)] /comment [mask]
Note That :
- The 'subsystem' parameter is optional
- The 'comment' is taken from the dictionary.
FAILURE When a parameter is not correct : a log is generated
specifying the wrong parameter: either a NULL pointer
or the parameter is too long.
SUCCESS .
logFitsSetMask("TE1");
logFitsAction("mod","TCS","TEL","SOFTW","START");
The next call will use the default value "TCS" as dictionary name
logFitsAction("mod",NULL,"TEL","","PRESET");
#include "log.h"
ccsCOMPL_STAT logFitsComment ( const ccsMODULEID module,
const char *who,
const char *text)
Store a string as a Operational Log in Fits Format describing a
comment : the comment can contain a tag identifying 'who'
generated the log.
module <IN> Module's name.
who <IN> Defines 'who' generated the code : logNULL, logSTAFF
logOBSERVER , logREMOTE_CONTROL, logNIGHT_ASSISTANT.
text <IN> Text to be inserted as comment
Two different record formats are provided according to the value of
parameter <who>.
If <who> = logNULL the format is
hh:mm:ss>/free-format comment up to 50 chars.
otherwise
hh:mm:ss>/COMMENT NN free-format comment
possibly spanning several lines
Where NN is a two letter code specifying <who> generated the code.
SUCCESS .
FAILURE For parameter with NULL pointers
In this case a log describing the error condition is generated.
logFitsComment("mod",logNULL,"This is my comment");
logFitsComment("mod",logREMOTE_CONTROL,"Let's sleep a bit");
#include "log.h"
ccsCOMPL_STAT logFitsEvent ( const ccsMODULEID module,
logFITS_TYPE what,
const char *text)
This routine provides a way to log a brief description associated to
'unforseen' events or 'recovery' actions.
module <IN> Module's name.
what <IN> Type of log : FITS_UNFORSEEN, FITS_RECOVERY
text <IN> Text to be inserted as comment. The maximum length
of the string is logFITS_TEXT_LEN.
'Unforseen' events are typically associated to failure conditions
and are logged with the following format :
hh:mm:ss>/UNFORSEEN: followed by a brief description of the event
Very often a there is a 'Recovery' action follows in response to
an 'Unforseen' event and are logged as follows :
hh:mm:ss>/RECOVERY: followed by a brief description of the action
SUCCESS .
FAILURE For parameter with NULL pointers
In this case a log describing the error condition is generated.
logFitsEvent("mod",FITS_UNFORSEEN,"Calibration Lamp not available");
logFitsEvent("mod",FITS_RECOVERY,"Got new calibration lamp");
3.2.86 logFitsParArray
#include "log.h"
ccsCOMPL_STAT logFitsParArray ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
vltINT16 first,
vltINT16 last,
vltINT16 elemSize,
char *array)
Logs array of numbers describing the status of a the components
of a given system. The elements are logged separated by commas.
module <IN> Module's name.
fitsDict <IN> Defines the dictionary where to check the correctness
of the Fits action verb and keywords.
This information is stored internally and it is used
as default value when this is NULL.
fitsCat <IN> Category : it is pre-defined and designated by a
3-letter abbreviation.
Examples of 'category' are DET (Detector)
TEL (Telescope) ADA (Adapter) or INS (Instrument)
fitsSys <IN> Subsystem : identifies a component in a category and
can consist of zero or at maximum 2 words.
Several subsystems are separated by ",".
fitsParam <IN> Identifies the parameter withing the subsystem.
first,last <IN> Indexes of the (first,last) elements of the array.
elemSize <IN> Size (in bytes) of a single element of the array
array <IN> Pointer to the first element of the array to be logged.
The log will be stored in the following format :
hh:mm:ss>category [subsystem(s) parameter(start_index)]=value / comment
- The 'subsystem' parameter is optional
- The 'comment' is taken from the data dictionary.
- The final format for each 'value' is taken from the data dictionary.
- NULL (non-existent) values are identified by the symbol '--'.
If the array cannot be logged along a single log, it is split into
several logs : in each log <start_index> identifies the array position
of the first element.
For example :
hh:mm:ss> DET PARM(1) = -8.05, 3.00, 23.52 / comment [mask]
hh:mm:ss> DET PARM(4) = -4.06, 5.99, 13.77 / comment [mask]
hh:mm:ss> DET PARM(7) = -0.36, 12.00, 0.31 / comment [mask]
FAILURE When a parameter is not correct : a log is generated
specifying the wrong parameter: either a NULL pointer
or the parameter is too long.
SUCCESS .
These are examples of calls taken from the testing procedure and
assume to use the following arrays :
vltINT16 int16[] = {100, 200, 300, 400, 500, 600, 700, 800};
vltFLOAT fff[] = {-1.123,2.345,3.456,-4.567,-5.678,-6.789,7.89,1.55};
vltLOGICAL lll[] = {ccsTRUE,ccsFALSE,ccsTRUE,ccsFALSE,ccsFALSE};
vltBYTES4 bytes4[] = {"st1","st2","st3","st4","st5","st6","st7"};
logFitsParArray("mod","LOG", "CAT","SYSTEM","INT16",2,5,
sizeof(int16[0]),(char *)&int16[2]);
logFitsParArray("mod","LOG", "CAT","SYSTEM","BYTES4",1,7,
sizeof(bytes4[0]),(char *)&bytes4[1]);
logFitsParArray("mod","LOG", "CAT","SYSTEM","FLOAT",2,2,
sizeof(fff[0]),(char *)&fff[2]);
logFitsParRecord , logIntParRecord , logStringParRecord,
logRealParRecord - Logs a parameter as Operational Log in Fits Format
#include "log.h"
ccsCOMPL_STAT logFitsParRecord ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
const void *value)
ccsCOMPL_STAT logIntParRecord ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
int value)
ccsCOMPL_STAT logRealParRecord ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
double value)
ccsCOMPL_STAT logStringParRecord ( const ccsMODULEID module,
const logDICTIONARY fitsDict,
const logCATEGORY fitsCat,
const logFITS_KEY fitsSys,
const logFITS_KEY fitsParam,
char *value)
Generate a log recording information on the status of the components
of a given system : typical examples are wind speed, guide star RA/DEC
or exposure number.
logFitsParRecord
Basic routine supporting the logging of parameters for the following
data types : vltINT32, vltDOUBLE, vltLOGICAL or a string.
Caution :
the routine deals always with the maximum size of the data to be
logged, that is, a string 256 bytes long, therefore it makes a memcpy
of 256 bytes from the location pointed to <value>
logIntParRecord
Extension supporting the logging of parameters defined as VLT
integer data types : vltINT8, vltINT16, vltINT32
logRealParRecord
Extension supporting the logging of parameters defined as VLT
'real' data types : vltFLOAT, vltDOUBLE.
logStringParRecord
Extension supporting the logging of parameters defined by as VLT
'string' data type : vltBYTESxxx.
The values are assumed to be be NULL terminated.
Parameter description :
module <IN> Module's name.
fitsDict <IN> Defines the dictionary where to check the correctness
of the Fits action verb and keywords.
This information is stored internally and it is used
as default value when this is NULL.
fitsCat <IN> Category : it is pre-defined and designated by a
3-letter abbreviation.
Examples of 'category' are DET (Detector)
TEL (Telescope) ADA (Adapter) or INS (Instrument)
fitsSys <IN> Subsystem : identifies a component in a category and
can consist of zero or at maximum 2 words.
Examples of 'subsystems' are GRIS (grism), LAMP,
CCD (detector Chip) or EXPO (Exposure Descrition)
fitsParam <IN> Identifies the parameter withing the subsystem.
Examples of keywords for 'parameter' are ALT (Altitude)
TEMP (Temperature) or WLEN (Wavelength)
value <IN> The current value associated to the parameter.
The log will be stored in the following format :
hh:mm:ss>category [subsystem(s) parameter]=value / comment
Note That :
- The 'subsystem' parameter is optional
- The 'comment' is taken from the data dictionary.
- The final format for 'value' is taken from the data dictionary.
FAILURE When a parameter is not correct : a log is generated
specifying the wrong parameter: either a NULL pointer
or the parameter is too long.
SUCCESS .
vltDOUBLE azAngle;
vltDOUBLE decRef;
logFitsSetMask("TE1");
logFitsParRecord("mod","TCS","TEL","POS","ALT",&azAngle);
The next call will use the default value "TCS" as dictionary name
logFitsParRecord("mod",NULL,"TEL","REF","DEC",&decRef);
Sets the default value for the mask parameter used to log
Operational Logs in FITS format.
This parameter appears always as last string of the log and the default
value is set to the 'hostname'.
moduleId <IN> Name of the VLT module calling the function
mask <IN> String representing the log mask. The string must be
at most logMASK_LEN chars long.
#include "msg.h"
ccsCOMPL_STAT msgAcceptConnection (msgPROCESSID *orgId,
char *buffer,
msgSOCK_DESC *sockDesc,
ccsERROR *error
)
msgAcceptConnection() establishes a socket connection between
the calling process and the process specified by <orgId> based
on the informations (IP address and port number) passed in <buffer>.
msgAcceptConnection() is the counterpart to msgOpenConnection()
and HAS TO and MAY ONLY be called on a msgCONNECT_CMD request.
orgId <IN> process ID of originator of request
buffer <IN> message buffer of request
socktDesc <OUT> socket descriptor, including
- hostname, undefined
- ipAddr, IP address of originator of request
- procId, ID of process to which communication
shall be established
- fd, socket descriptor
error <OUT> error data structure
The connection is bi-directional.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics:
- ccsERR_NULL_PTR, if one of the input parameters
is a NULL pointer
- ccsERR_PARAMETER, if buffer cannot be parsed
- ccsERR_MSG_SYSTEM, if a UNIX System call fails
...
ccsERROR error;
msgSOCK_DESC sockDesc;
ccsERROR errmsg;
msgHEADER *myMsg;
vltUINT8 msgType;
msgCMD *command;
msgCMDID commandId;
msgPROCESSID *orgId;
char *buffer;
msgLENGTH buflen;
vltLOGICAL last;
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
myMsg = NULL;
if (msgRecvMsg(&myMsg...) == FAILURE)
... error processing ...
if (msgParseMsg(myMsg,
&msgType,
&command,
&commandId,
&orgId,
&last,
&buffer,
&buflen,
&errmsg,
&error) == FAILURE)
... error processing ...
if (strcmp(msgCONNECT_CMD, *command) == 0)
if (msgAcceptConnection(orgId, buffer,
&sockDesc, &error) == FAILURE)
... error processing ...
else
.. data transfer ...
...
This function compares two process idendifiers and returns
a value of 1, 0 or -1 depending whether the process ID
pointed to by id1 is equal to or greater than that pointed
to by id2.
For two processes in the same environment, the process with the
numerically lowest RTAP process number is deemed less than the other
process.
For processes in different environments the process number is checked
first, which normally determines the outcome. If the two process
numbers match, a strcmp(3) is done on the two environment names, and
the alphabetically lower name is deemed the lesser of the two.
-1, 0, or 1 depending on whether the identifier pointed to by id1 is
less than, equal to, or greater than the identifier pointed to by id2.
#include "msg.h"
ccsCOMPL_STAT msgGetProcIdByName (
const ccsENVNAME envName,
const ccsPROCNAME procName,
msgPROCESSID *procId,
ccsERROR *error
)
msgGetProcIdByName() retrieves the process ID for the process
specified by its process name.
envName <IN> environment name; if a NULL pointer or ccsLOCAL_ENV
the process-ID of <procName> running in the local
environment is returned;
procName <IN> name of process for which to retrieve the process-ID
procId <OUT> process ID to be returned, which is a structure defined
as follows
typedef struct {
ccsENVNAME envname;
ccsPROCNUM procnum;
vltUINT8 reserved;
} msgPROCESSID;
envName is a character string defining the environment
in which the process is running.
procnum is the process number uniquely identifying the
process within its own environment.
error <OUT> error handling data structure
msgMonitorQueue - enable/disable asynchronous monitoring
of the message queue
msgSelect - pend on a set of file descriptors
#include "msg.h"
ccsCOMPL_STAT msgMonitorQueue (
int *fd,
vltLOGICAL state,
ccsERROR *error
)
int msgSelect (
int width,
void *readFds,
void *writeFds,
void *exceptFds,
ccsTIMEVAL *timeOut
)
msgMonitorQueue() allows a process to monitor its message queue
using msgSelect() based on the UNIX function select().
fd <OUT> OS file descriptor to be returned
state <IN> specifies whether mechanism should be enabled
(state > 0) or disabled (state = 0).
error <OUT> error handling data structure
If the process is running in an RTAP environment this routine
calls the RTAP routine rtMonitorQueue().
If running on a CCS-LITE environment the following operations
are performed:
Calling the msgMonitorQueue() function causes a process to
- open a pipe
- create a semaphore and pass its ID to the QServer
- fork
While the parent process continues, the child (monitoring)
process enters an endless loop waiting for the semaphore.
Each time the semaphore is given, the monitoring process writes
on the pipe in order to trigger select().
The semaphore is given by the QServer each time a message
is put on the message queue of the process.
When the monitoring mechanism is disabled the semaphore is
removed and the child process terminates automatically.
In order to avoid ZOMBIES the SIGCHLD is configured to be
ignored.
msgSelect() allows a process to pend until a set of file
descriptors becomes ready. msgSelect() is built on top of
select() and includes some extensions taking some special
features of the CCS Message System into account.
Input parameters and return values of msgSelect() and select()
are the same.
msgMonitorQueue():
SUCCESS upon successful completion
FAILURE, if an error occurres
- ccsERR_MSG_SYSTEM
- ccsERR_MSG_TIMEOUT
msgSelect():
-1, if an error occurred
0, if no descriptors are ready and the time limit expired
A positive return value specifies the number of descriptors
that are ready
The file descriptor returned must NOT be read or manipulated in any
way (e.g. close()) by the process. Otherwise the monitoring system
will lose syncronization with the message queue system.
When msgSelect() returns indicating an input, msgRecvMsg() should be
called to get the message.
ONLY IN CONJUNCTION WITH msgMonitorQueue() msgSelect() works
properly when monitoring the input queue.
#include <.....>
#include "ccs.h"
#include "msg.h"
main()
{
int fd[2];
pid_t pid;
fd_set readfs;
ccsERROR error;
if (ccsInit(......) == FAILURE)
get the file descriptor for the other input file
fd[0] = open(.....);
enable monitoring of message queue
if (msgMonitorQueue(&fd[1], ccsTRUE, &error) == FAILURE)
{
.....
}
initialize bit mask
FD_ZERO(&readfs);
configure file descriptors you are interested in
FD_SET(fd[0], &readfs);
FD_SET(fd[1], &readfs);
call select to watch queue and file
if (msgSelect(max(fd[0],fd[1]) + 1, (void *)&readfs,
NULL, NULL, NULL) > 0)
{
check if message arrived
if (FD_ISSET(fd[1], &readfs))
{
get the mesage
if (msgRecvMsg( .... ) == ...)
}
}
....
}
#include "msg.h"
ccsCOMPL_STAT msgOpenConnection (char *hostname,
ccsENVNAME envName,
ccsPROCNAME procName,
msgTIMEOUT timeout,
msgSOCK_DESC *sockDesc,
ccsERROR *error
)
msgOpenConnection() performs a request to establish a socket
connection between the calling application and <procName> running
in environment <envName>.
hostname <IN> specifies LAN interface to be used; this
parameters has only to be defined, if the
local machine is multi-homed and a particular
network interface should be used for the
connection; if <hostname> is not defined
(NULL pointer or empty string), the application
will accept a connection request on any local
interface
envName <IN> environment where <procName> is running
procName <IN> process name
timeout <IN> specifies the time-out in milliseconds for
synchronisation between the processes; for
details see msgRecvMsg()
sockDesc <OUT> socket descriptor, includes
- hostname, host-name of LAN interface used
- ipAddr, IP address of LAN interface used
- procId, ID of process to which communication
is established
- fd, socket descriptor
error <OUT> error data structure
NOTES: msgOpenConnection() sends a standard CCS command
(msgCONNECT_CMD) to trigger <procName> to connect.
In order to establish the connection <procName> then has
to call msgAcceptConnection(), which is NOT AUTOMATICALLY
DONE BY the CCS Message System.
IT IS UP TO <procName> TO CALL msgAcceptConnection()
ON A msgCONNECT_CMD REQUEST.
In order to cope with the CCS Command Management System the
CDT of <procName> MUST include the definition of the command
msgCONNECT_CMD (see msgSocket.icdt).
If a connection shall be established between a LCU and a WS,
the WS process MUST open the connection.
The connection is bi-directional.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics:
- ccsERR_NULL_PTR, if one of the input parameters
is a NULL pointer
- ccsERR_MSG_SYSTEM, if a UNIX System call fails
...
ccsERROR error;
msgSOCK_DESC sockDesc;
ccsENVNAME env = "wte13";
ccsPROCNAME process = "SOURCE_OF_DATA";
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
if (msgOpenConnection(NULL, env, process,
10000, &sockDesc, &error) == FAILURE)
... error processing ...
else
... trigger <process> to send data ...
if (msgSendCommand(...) == FAILURE)
... error processing ...
else
if (msgRecvData(...) == FAILURE)
... error processing ...
...
#include "msg.h"
ccsCOMPL_STAT msgParseMsg (
const msgHEADER *message,
vltUINT8 *msgType,
msgCMD **command,
msgCMDID *commandId,
msgPROCESSID **orgId,
vltLOGICAL *lastReply,
char **buffer,
msgLENGTH *buflen,
ccsERROR *errmsg,
ccsERROR *error
)
msgParseMsg() parses the message pointed to by <message>.
It returns all parameters of interest part of a CCS message.
This routine should normally be called after msgRecvMsg().
NOTE: This function returns pointers to the message buffer.
This data area may be destroyed by subsequent calls to
CCS Message System function calls. It is the users
responsibility to save data to local variables if this
is required.
message <IN> Pointer to the message to be parsed, which
is returned by the msgRecvMsg() function.
msgType <OUT> Pointer to the message type. Possible values are:
- msgTYPE_COMMAND
- msgTYPE_REPLY
- msgTYPE_ERROR_REPLY
- msgTYPE_OBITUARY
- msgTYPE_REQUEUED
command <OUT> Pointer to the command name.
commandId <OUT> Pointer to the command identifier supplied
by the user.
orgId <OUT> Pointer to the structure describing the originator
(environment and process number).
lastReply <OUT> Pointer to the flag, indicating whether it was the
last reply for a command or not. It is only defined,
if the message is of type msgTYPE_REPLY. Possible
values are:
- ccsTRUE -> last reply
- ccsFALSE -> more replies will follow
buffer <OUT> Pointer to the message body.
buflen <OUT> Pointer to the length of the message body in bytes.
errmsg <OUT> Error stack returned, if message is of type
msgTYPE_ERROR_REPLY.
error <OUT> Error handling data structure.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics:
- ccsERR_MSG_TYPE, if an invalid message type is found
within the message header
- ccsERR_NULL_PTR, if <message> is a NULL pointer
This function returns pointers to memory allocated internally by
the CCS Message System. This memory may be overwritten by subsequent
calls to CCS Message System function. Such calls can also be performed
within other CCS functions like dbWriteSymbolic(), errAdd() etc.
#include "msg.h"
...
ccsERROR error;
ccsERROR errmsg;
msgHEADER *myMsg = NULL;
vltUINT8 msgType;
msgCMD *command;
msgCMDID commandId;
msgPROCESSID *orgId;
char *buffer;
msgLENGTH buflen;
unsigned char last;
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
if (msgRecvMsg(...) == FAILURE)
... error processing ...
...
if (msgParseMsg(myMsg,
&msgType,
&command,
&commandId,
&orgId,
&last,
&buffer,
&buflen,
&errmsg,
&error) == FAILURE)
... error processing ...
...
#include "msg.h"
ccsCOMPL_STAT msgPing (
ccsENVNAME envName,
ccsPROCNAME procName,
vltLOGICAL reply,
ccsERROR *error
)
msgPing() checks whether <procName> running on <environment> is alive
sending a PING-command to that process.
envName <IN> name of the environment, where the processes running.
procName <IN> process name
reply <IN> flag indicating whether a reply should be returned or not:
- ccsTRUE : send reply
- ccsFALSE : send no reply
error <OUT> error handling data structure.
NOTE: An application (-> <procName>, destination of the PING command)
has not to handle the PING-command, it is handled internally by
the CCS Message System Software.
If <reply> is set, a reply is returned to the originator of the
PING command, which has to process it.
This function is only applicable for CCS Applications.
SUCCESS if the process is alive
FAILURE if an error occurred; either input parameters are wrong or
the process does not exist
#include "msg.h"
...
ccsERROR error;
ccsENVNAME envName;
ccsPROCNAME procName;
if (msgPing (envName, procName, &error) == FAILURE)
{
... process not running ...
... error processing ...
}
else
... normal processing ...
#include "msg.h"
ccsCOMPL_STAT msgRecvData (msgSOCK_DESC *sockDesc,
msgTIMEOUT timeout,
char **buffer,
vltUINT32 bytesToRead,
vltUINT32 *bytesRead,
vltINT16 *errorCode,
ccsERROR *error
)
msgRecvData() tries to read <bytesToRead> bytes from the socket
specified by <sockDesc>.
sockDesc <IN> socket descriptor
timeout <IN> specifies the time in milliseconds to wait
for data; for more detailed information see
msgRecvMsg()
buffer <IN/OUT> buffer where to store data; if the pointer
passed by <buffer> is NULL, the memory needed
is allocated by msgRecvData() and the pointer
to it is returned by <buffer>
bytesToRead <IN> number of bytes to be read
bytesRead <OUT> number of bytes read
errorCode <OUT> error code passed by the sender if
transfer has been stopped
error <OUT> error data structure
If the process and so the data transfer is interrupted by a signal
the transfer is automatically carried on after termination of the
signal handler.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics:
- ccsERR_NULL_PTR, if one of the input parameters
is a NULL pointer
- ccsERR_PARAMETER, if <timeout> is negative
- ccsERR_TIMEOUT, if no data available after
<timeout> milliseconds
- ccsERR_MSG_SYSTEM, if system function returns an error
- ccsERR_MSG_TRANSFER_ABORTED, if transfer has been aborted
- ccsERR_MSG_CONN_CLOSED, if connection has been closed by
counterpart
This routine uses the select() and read() functions to wait for
respectively read the data requested. If one of these functions
returns with an error, the socket connection is closed and an
error is returned.
If the transfer has been aborted (see ccsERR_MSG_TRANSFER_ABORTED)
the connection IS NOT CLOSED !
...
ccsERROR error;
msgSOCK_DESC sockDesc;
ccsENVNAME env = "wte13";
ccsPROCNAME process = "SOURCE_OF_DATA";
char *buffer = NULL; -> memory shall be allocated
by msgRecvData()
vltUINT32 bytesRead;
vltINT32 errorCode;
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
if (msgOpenConnection(..., &sockDesc, ...) == FAILURE)
... error processing ...
else
... trigger <process> to send data ...
if (msgSendCommand(...) == FAILURE)
... error processing ...
else
if (msgRecvData(&sockDesc,
msgNO_TIMEOUT, -> wait forever
&buffer,
1024, -> read 1K
&bytesRead,
&errorCode,
&error) == FAILURE)
if (errorCode != 0) -> transfer aborted by sender
... process errorCode returned by sender ...
else
... error processing ...
else
... process data ...
...
#include "msg.h"
ccsCOMPL_STAT msgRecvMsg (
const msgRECEIVEFILTER *filter,
msgTIMEOUT timeout,
msgHEADER **recvMsg,
ccsERROR *error
)
msgRecvMsg() tries to receive a CCS Message according <filter>.
If a message is received successfully, dependent on the content
of <recvMsg> a pointer to the message is returned or the
message is copied into a user provided buffer.
filter <IN> Filter to determine which messages are to be
received. For more detailed information see
msgSetFilter().
timeout <IN> Time-out in milliseconds to wait for a message.
As on a WS the resolution is second, the timeout
value is rounded to the nearest number of seconds,
with a minimum of 1 s. If <timeout> is set to
- msgNO_WAIT msgRecvMsg() immediately returns
with an error, if no message found
in the queue matching the filter
- msgNO_TIMEOUT msgRecvMsg() waits forever to
receive a message
recvMsg <IN/OUT> Pointer to the message received. If the pointer
passed by <recvMsg> is NULL, a pointer to the
message received is returned. If it is not equal
NULL, the message received is copied into the
buffer specified by the pointer. The destination
buffer should be of type msgMSG. The pointer to
that buffer passed to msgRecvMsg() should be casted
to a pointer to a msgHEADER.
error <OUT> Error handling data structure.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics:
- ccsERR_NULL_PTR
- ccsERR_MSG_FILTER
- ccsERR_MSG_TIMEOUT
- ccsERR_MEMORY
If a message is not copied into a buffer provided by the user
(<recvMsg> is equal NULL), this function returns a pointer to
memory internally allocated by RTAP or the CCS Message System.
This memory can be overwritten by subsequent calls to RTAP or
CCS Message System.
#include "msg.h"
...
ccsERROR error;
msgHEADER *myMsg = NULL;
msgRECEIVEFILTER myfilter;
if (ccsInit(...) == FAILURE)
... error processing ...
...
if (msgRecvMsg(&myfilter, msgNO_TIMEOUT,
&myMsg, &error) == FAILURE)
... error processing ...
...
If a user provided buffer is passed, it should be declared as follows:
.......
msgMSG buffer;
msgHEADER *myMsg = (msgHEADER *)&buffer;
.......
#include "msg.h"
ccsCOMPL_STAT msgScheduleProcess (
const ccsENVNAME env,
const char *runstring,
const ccsRUNOPT *runoptions,
ccsERROR *error
)
msgScheduleProcess() schedules a process on environment <env>.
It sends the command MSGSCHP to the msgServer on the destination
environment, which actually performs the scheduling and returns
after the msgServer on the destination environment has sent a
corresponding reply.
env <IN> Name of the environment, where to schedule
the process. It must be known to the sending
environment.
runstring <IN> Shell command line how to schedule the process.
runoptions <IN> Options to be used, when the process is scheduled.
Dependent on the requested environment (UNIX
or VxWorks) the following parameters have
to be specified:
UNIX:
- <runoptions>->unxito.flags:
Possible values are:
- 0, none of the following features
is desired
- msgDEFAULT_RUNSTRING, the run-string
specified in the RTAP environment
table <RtapEnvTable> is used. If no
entry for the requested process is
defined in the table <runstring> will
be used
- msgMERGE_RUNSTRING, the run-string will
be appended to the default commands
specified in RtapEnvTable
- msgNOTIFY, the user will be sent
explicit notification when the process
being scheduled terminates. Note that
this is independent of the care about
terminations field in the RTAP
environment table.
NOTE: More than one of these features can be
accessed by ORing their values together.
This flag has no meaning, if used on a
CCS LITE environment.
VxWorks:
- <runoptions>->vxto.priority:
Requested priority of the process.
- <runoptions>->vxto.options:
Options to be used, when scheduling the
process (see taskSpawn()).
- <runoptions>->vxto.stacksize:
Size of stack needed.
- <runoptions>->vxto.taskname
Name of the process.
error <OUT> Error handling data structure.
SUCCESS upon successful completion
FAILURE if an error occurred; possible error mnemonics :
- ccsERR_ENV_NAME
- ccsERR_NULL_PTR
- ccsERR_PROC_NAME
- ccsERR_NO_PROC
- ccsERR_ENV_NOT_ACTIVE
- ccsERR_PROC_INFO
- ccsERR_MSG_TYPE
- ccsERR_MSG_SIZE
- ccsERR_MSG_CMD
#include "msg.h"
...
ccsERROR error;
ccsENVNAME env;
char *runstring;
ccsRUNOPT runoptions;
...
if (ccsInit(...) == FAILURE)
... error processing ...
...
runoptions.vxto.taskname = (char *)malloc(sizeof(char)*100);
runoptions.vxto.priority = 100;
runoptions.vxto.options = 8;
runoptions.vxto.stacksize = 20000;
strcpy(runoptions.vxto.taskname,"mytaskname");
strcpy((char *)env, "lcu6");
if (msgScheduleProcess (env,
runstring,
&runoptions,
&error) == FAILURE)
... error processing ...
else
... normal processing ...