| |
|
|
|
A
- B - C - D - E - F - G - H - I - J - K - L - M - N - O - P - Q - R - S - T - U - V - W - X - Y - Z
4 REFERENCE
tclCpp pre-processes <file> with cpp. This means <file> can contain
cpp-style pre-processor directives, like #include and #define statements.
Apart from these pre-processor directives, <file> needs to be written
according to the Tcl syntax. To avoid confusion between Tcl commentlines
and pre-processor directives (both starting with a #-sign), the following
rule applies: lines starting with a hash sign followed immediately by a
lowercase alphabetic character are considered pre-processor directives;
otherwise they are considered Tcl commentlines.
In its first form (-p option), <file> is a Tcl script, which gets its
commentlines prettified/prepared for the cpp preprocessing. I.e. lines
starting with a hash sign followed immediately by a lowercase alphabetic
character get a space inserted after the #-sign.
-p : prettify commentlines
-s : do not substitute /* and */ by their hexadecimal representation.
By default tclCpp will replace these strings, in order to avoid
conflicts with cpp, which considers them the start resp end of
a comments block.
The output is a file named <file>.cpp
In the second form, the actual pre-processing takes place.
-b : keep blank lines; cpp may actually insert a few blank lines. By
default blank lines are removed.
-c : keep comment lines. They are removed by default.
-D : additional #define directives. tclCpp itself defines the MAKE_TCL
macro
-I : pathnames for #include directives.
<file> : Tcl script file, extended with pre-processor directives. Needs
to have a .cpp extension.
The output is a file named as <file> but without the .cpp extension.
tclCpp -p will replace the /* and */ strings by default, even in comment
lines and within curly braces, by \x2f* resp */(/being the
hexadecimal notation for "/"). If this is not desired, specify also the
-s option, and ensure that these strings will not disturb cpp.
.....
$ tclppp -p myScript.tcl
$ ... (edit myScript.tcl.cpp to add pre-processor directives)
$ tclppp myScript.tcl.cpp
.....
seqInitInterp, seqEval - create and initialize a Sequencer interpreter
and evaluate a Sequencer script
#include <seq.h>
ccsCOMPL_STAT seqInitInterp (char *reserved1,
char *reserved2,
vltLOGICAL interactive,
Tcl_Interp **interp,
ccsERROR *error)
ccsCOMPL_STAT seqEval (Tcl_Interp *interp,
char *script,
ccsERROR *error)
seqInitInterp creates and initializes a Sequencer interpreter.
reservedN : dummy string
interactive: flag to signal if this is an interactive application (like a
shell), i.e. if typed commands have to be expected.
If true, the Tcl-variable "tcl_interactive" is set to 1.
This is needed for the initialization of TclX
interp : pointer to the returned interpreter-pointer
error : CCS error structure pointer
seqInitInterp will call the Tcl_AppInit() function to initialize the
interpreter. The libseq library contains such a function, which is
identical to the Tcl_AppInit() function used by seqSh. In other words,
the version of Tcl_AppInit included in libseq initializes all extensions
just as seqSh does, i.e. [incr Tcl], Tcl, TclX and seq. If more
extensions are needed, like e.g. SeqOslx, they have to be loaded
dynamically via seqEval (see the Tcl "load" and "package" commands).
Remark that if Tcl_AppInit() includes the initialization of Tk, the Tk
main window can only appear or get updated when the Sequencer event-loop
is entered, i.e. by calling from your application either Tcl_Mainloop()
once or Tcl_DoOneEvent() repeatedly. In other words, if your application
does not include such calls, no window will appear.
seqEval evaluates a script in the context of the interpreter it is passed
interp : initialized interpreter (cf seqInitInterp)
script : string containing any valid script to execute (e.g. "source
myScriptFile" or "set a [seq_dbReadSymbolic <alias>myScalar]")
error : CCS error structure, filled out only if the evaluation fails
The application calling this function is responsible for including the
proper libraries, i.e. a library containing the Tcl_AppInit function.
Remark that the libseq library includes such a function, which is identical
to the one used for seqSh, i.e. it does not include any initialization of
Tk and related extension. The seq/src/tkXAppInit.c source can be used as
an example Tcl_AppInit function including this Tk initialization.
This function initializes the interpreter for the commands that are
specific for the Sequencer. This comes down to initializing a few
global Tcl variables, declaring the new commands, and finally the
execution of the initialization script seqInit.tcl
The environment variable SEQ_LIBRARY gives the pathname where a number of
predefined Sequencer scripts are looked for, including the initialization
script seqInit.tcl.
seq_library is a global Tcl variable, derived from the environment variable
SEQ_LIBRARY. If this environment variable is not set, seq_library will be
set to one of the following paths, in this order of precedence:
- ../lib/libseqTcl.tcl
- $INTROOT/lib/libseqTcl.tcl
- $VLTROOT/lib/libseqTcl.tcl
The environment variable SEQ_DEFAULT_PREC gives the default precision that
will be used for printing floats, and for conversion of database values to
strings.
tcl_precision is a global Tcl variable which is writable, and which is set
to SEQ_DEFAULT_PREC. If this environment variable is not set, a default
precision which was given at compilation time will be used (see Makefile).
tcl_precision is also linked to the global C-variable seqPrecision.
seq_ccsProcName is a global Tcl variable which is read-only, initialized to
seqNAME as defined in seq.h, and linked to the global C-variable
myProcName. This C-variable is used as the default name under which to
register the Sequencer with CCS - see seq_ccsInit.
seq_moduleId is a global Tcl variable which is writable, initialized to
"seq", and linked to the global C-variable seqModuleId of type ccsMODULEID.
This C-variable is used only in the seq_errAdd command, and allows to
modify the moduleId-argument of the underlying call to errAdd(3).
seq_errLogging is a global Tcl variable which is writable, initialized to
"auto". It reflects how the logging of errors occuring during the
execution of seq_* commands should be dealt with; "auto" leads to automatic
logging of all unrecoverable errors (by issuing an errCloseStack()), "off"
will not log any error (by issuing an errResetStack), while "manual" will
not issue any err*Stack command, assuming that the script will take care
of this (see seq_err* commands). In all cases the error stack remains
accessible with the seq_errGetStackSize and seq_errGetFromStack commands.
seq_errReplyMerging is a global Tcl variable which is writable, initialized
to "off". It reflects how the error stacks received as part of message
replies are dealt with; "off" means an error reply will not be merged into
any other error stack, "internal" means it will end up at the bottom of
the so-called internal error stack, while "local" means it will get appended
to the default error stack accessed by seq_errAdd(n) and company (see also
seq_errResetStack(n)).
seq_ccsCmdCheck is a global Tcl variable which is writable, initialized to
"NO_CHECK", and linked to the global C-variable seqCmdCheck of type
msgCHECKFLAG. This C-variable is in seq_msgSendCommand passed on to
msgSendCommand(3). Allowed values for seq_ccsCmdCheck are NO_CHECK and
CHECK_CMD. It is also used in seq_msgRecvReply, to decide whether
formatting of replies should be attempted by default (i.e. it won't if
seq_ccsCmdCheck is set to "NO_CHECK").
seq_ccsType is a global Tcl variable, read-only, which reflects how the
shell was linked. It is set to either "full", "light" or "none",
depending on whether the shell was linked with full CCS, CCS-light or
without CCS.
seq_debug is a global Tcl array-variable, which reflects the debug-info
flag for each of the primary seq_* commands it can handle. Each of the
elements of this array can be set to 0 (default - no debug info) or have
any combination of the following bits set: bit 0 (print stack level,
command name plus arguments to stderr), 1 (return-value gets printed),
2 (print timestamp) and 3 (print internal, command-specific debug info).
If bit 1 is set, the return value is printed as "OK" or "ERR" followed by
the return-string put in between greater-than and less-than signs, e.g.
'OK >13.1<'.
This provides basic functionality to debug scripts at the seq-level.
TCL_OK if no errors occurred.
TCL_ERROR if one of the following conditions is met (with the corresponding
error message between quotes):
- error message left by Tcl_LinkVar if tcl_precision could not be linked
to seqPrecision
- error message produced by evaluating seqInit.tcl, which contains an
error.
The callback routine which checks the modification of seq_moduleId will
produce an error whenever the new value contains less than 3 or more than
6 characters.
Renaming a seq_* command will not affect this command's name in the
seq_debug array. So after renaming, the original name has still to be used
to modify the debug-flag.
Some debugable seq_* commands are implemented as Tcl procedures (seq_catch,
seq_errDisplay and seq_msgFlush). Each of these procedures calls itself one
or more seq_* commands implemented in C. If all of their debugging flags
are on, you will see a "nesting" of debugging output.
Remark that due to the way CCS keeps track of the environment name, changing
the RTAPENV environment variable *after* any CCS-function has been called
(explicitly via a seq_* command, or implicitly as the result of calling
a seq_* command, e.g. when errors are logged) will have no effect on CCS.
Example:
seqSh> seq_dbSetCwp : ; # fails if no seq_ccsInit given before
Error: cannot set CWP to ":"
seqSh> set env(RTAPENV)
wte5
seqSh> set env(RTAPENV) wtetest
seqSh> seq_ccsInit me ; # will do a ccsInit in wte5, not wtetest
dputs: prints out the <args> to stderr, but only if the global Tcl variable
"Debug" is set to the name of the procedure we want to debug, or to
"toplevel" if the toplevel is to be debugged. If no arguments are
passed, a call to this procedure is equivalent to setting a
breakpoint (provided "Debug" is set to the name of the procedure to
debug).
breakpoint: set a breakpoint. Four commands are interpreted directly by
the breakpoint procedure itself:
+ to move up the call stack
- to move down the call stack
? to print information about the current stack frame
C return from a breakpoint
All other commands are evaluated in the current stack frame
The optional argument <level> indicates how many more levels to
go up, in case several of these debug-procedures are nested
(e.g. when dputs calls breakpoint)
showInfo: print useful information about the stack level (stack level,
procedure name and arguments) to stderr.
Based on: "PracTcl Programming Tips", Linux Journal, October 1995
by Stephen Uhler
The breakpoint proc seems to have some problems with namespaces, i.e
when in a child namespace it can complain that perfectly fine procedures
are not procedures. It looks like a bug in the "uplevel" command.
seq_catch has an identical syntax and behaves as the Tcl "catch" command.
<command> : any Sequencer script
<msg> : variable name where to store the result string for <command>
<sourceid> : string containing location identifier; remark that only the
first word of this string will be transmitted to the CCS
error logging system
On top of what "catch" does, seq_catch logs the error (if any) produced
by <command> to the CCS error logging system. For that purpose it can use
the optional <sourceId> argument, which is for the error system known as
the "location identifier". Typically the caller could set <sourceId> to
[info script]. If <sourceId> is not specified, it will be set to the name
of the script file which executes this seq_catch command.
identical to "catch":
returns OK, with the result string set to "0" if <command> did not produce
an error. If <command> returned an error, the result string contains 1
and <msg>, if given, will be set to the error message left by <command>.
returns ERROR with corresponding message in the result string under the
following conditions:
- "wrong # args: should be "seq_catch <command> ?<msg>? ?<sourceId>?"" if
there were more than 2 arguments given to this <command>.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_catch {set a $b} msg "MyProcedure"
0
seqWish>seq_catch {set a $c} msg "MyProcedure"
1
seqWish>set msg
can't read "c": no such variable
seqWish>.....
seq_ccsInit, seq_ccsExit, seq_ccsAsyncInput - interface to ccsInit, ccsExit
and the asynchronous input of messages
seq_ccsInit:
calls ccsInit to register the Sequencer in CCS
<procName> : string containing name under which to register the Sequencer.
seq_ccsInit sets also the global Tcl variable "seq_ccsStatus" to
"CLOSED". If <procName> is not given, it defaults to the value of the Tcl
variable seq_ccsProcName.
If all went well, the global Tcl variable "seq_ccsEnvName" will be set
to the name of the local environment.
seq_ccsExit:
calls ccsExit and unsets the global variable "seq_ccsStatus".
Whenever seq_ccsExit command completes successfully, internal lists
containing info about commands with pending replies are cleared,
i.e. seq_msgList will return an empty list. If the seq_ccsExit command
is given within the processing of a SCRIPT command (see
seq_msgDispatch), it will inform the originator(s) of this command that
it is exiting, sending a last reply with an error number 1.
seq_ccsAsyncInput:
enables or disables the treatment of commands that are sent to the
Sequencer via the CCS message system.
open : enable the input of commands
close : disable the input of commands
RTAPENV:
an environment variable, used to determine under which CCS-environment
the application needs to registered by the seq_ccsInit command. See also
the CAUTIONS section.
seq_ccsEnvName:
a read-only global Tcl variable, initialized after the first seq_ccsInit
command to the string-value given by CCS as the local environment name.
seq_ccsProcName:
a read-only global Tcl variable, initialized by seqInit to seqNAME as
defined in seq.h, and linked to the global C-variable myProcName.
This variable is used as the default name under which to register the
Sequencer with CCS. If the seq_ccsInit command includes the <procName>
parameter, seq_ccsProcName will be updated accordingly after a
successful ccsInit.
seq_ccsStatus:
a read-only global Tcl-variable, which reflects the status of
initialization the Sequencer went through; values can be:
- CLOSED : "seq_ccsInit" has been given before
- OPEN: "seq_ccsAsyncInput open" was given (after "seq_ccsInit"
succeeded)
- if the variable does not exist, "seq_ccsInit" was never given before
or "seq_ccsExit" was given after "seq_ccsInit".
OK if no errors occurred, accompanied by
- for seq_ccsInit the Tcl filedescriptor used for the message queue
monitoring
- an empty reply for all other commands.
ERROR if one of the following conditions is met (corresponding error
message is here between quotes):
- 'wrong # args: should be "seq_ccsInit ?<procName>?"', 'wrong # args:
should be "seq_ccsExit"' or 'wrong # args: should be "seq_ccsAsyncInput
open|close"' if the command was given with an improper amount of
arguments
- 'ccsInit failed' if ccsInit failed
- 'ccsGetMyProcId failed' if ccsGetMyProcId failed
- '"seq_ccsInit" was given before' if more than one seq_ccsInit command
is given without a seq_ccsExit in between (and remark that CCS expects
only one pair of init/exit commands per application).
- message left by Tcl_LinkVar, if the Tcl global variable seq_ccsStatus
or seq_ccsEnvName could not be linked to a C variable after ccsInit
succeeded.
- 'ccsExit failed' if ccsExit failed
- message left by Tcl_UnsetVar2, if the global variable seq_ccsStatus
could not be unset after ccsExit succeeded.
- 'bad argument: "<arg>" should be open or close' for a seq_ccsAsyncInput
command with an improper argument
- 'use seq_ccsInit first' if seq_ccsAsyncInput is given before
seq_ccsInit
- 'call to seqMonitorQ failed' if seq_ccsAsyncInput got an error returned
by this routine.
CCS errors are also logged via the CCS error logging system.
Under CCS-lite, the current setting of RTAPENV is taken whenever the first
CCS-function gets called, for CCS internal needs. If this first CCS-function
is not a ccsInit(), this value of RTAPENV will anyway be used later when
ccsInit() gets called, independent of RTAPENV's value at that later time.
This means that e.g. in the wtctest environment, issuing first a
"seq_errResetStack" command followed by a "set env(RTAPENV) xyz" and a
"seq_ccsInit" command, will lead to a ccsInit() in the wtctest
environment instead of the xyz environment.
This is not inherent to seq, but rather to CCS-lite. In fact, to enable an
effective modification of the environment variable RTAPENV within a
Sequencer script (e.g. based on runstring options), the Sequencer's internal
initialization does not call any CCS-function under CCS-lite, thereby
shifting the responsibility to do things in the proper order to the
application. Remark that there are several seq_* commands, apart from the
obvious ones, that (could) lead to calls of CCS-functions, e.g. seq_catch,
seq_errLog, seq_logTclErrors and seq_errDisplay.
Repeated seq_ccsExit commands will normally succeed as repeated ccsExit()
calls succeed. Use the Tcl-variable seq_ccsStatus if you want to know what
CCS-state the Sequencer-shell is in.
The handling of the seq_ccsInit command includes a rtMonitorQueue() call.
Due to what seems to be a bug in the latter, after messages came on the
queue this file descriptor will not be released by seq_ccsExit. In other
words, seq_ccsInit/seq_ccsExit cycli may lead to high-numbered file
descriptors, and even to some memory leaking. Remark that ccsInit/ccsExit
cycli are not officially supported by CCS.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the 'seqWish>' prompt, and all
replies on a new line)
....
seqWish>seq_ccsInit
file5
seqWish>echo $seq_ccsStatus
CLOSED (*)
seqWish>seq_ccsInit
Error: "seq_ccsInit" was given before
.....
seqWish>seq_ccsAsyncInput open
seqWish>echo $seq_ccsStatus
OPEN (*)
seqWish>seq_ccsExit
seqWish>echo $seq_ccsStatus
can't read "seq_ccsStatus": no such variable
seqWish>seq_ccsExit
seqWish>....
(*): These 3 characters are only there to avoid that docDoManPages
interprets the words CLOSED and OPEN as new sections of the manpage
'Tcl and the Tk toolkit', John K. Ousterhout, ISBN 0-201-6337-X
seq_msgDispatch(n), seqCcsInit(3), seqCcsExit(3), ccsInit(3), ccsExit(3),
seqInit(3)
seq_dbGetAttrInfo will retrieve the detailed description of an attribute.
<attrSymAddress> : string containing a symbolic address of the attribute,
in a format as permitted by dbGetAttrInfo(3)
seq_dbGetAttrInfo will return 4 values, in the following order:
- the attribute type (SCALAR, VECTOR or TABLE)
- a list of data types. In the case of SCALARs and VECTORs this list
contains a single element (without braces). For TABLEs this list
contains one element per field; if no field indices were specified, the
data types of all fields will be returned.
- the number of records; always 1 for SCALARS; for TABLES it is according
to the record indices, or the total number of records in the table if no
record indices were given
- the number of fields; always 1 for SCALARS and VECTORs; for TABLES it is
according to the field indices, or the total number of fields in the
table if no field indices were given
OK return if no errors occurred. In this case the result string contains
the attribute type, the list of data types (a single element for
SCALARs and VECTORs), the number of records and number of fields.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- "wrong # args : should be "seq_dbGetAttrInfo <attrSymAddress>": the
command was given with the wrong number of arguments;
- "cannot get info on "<attrSymAddress>": dbGetAttrInfo returned an
error for this argument
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbGetAttrInfo <alias>eric.myScalar
SCALAR 5 1 1
seqWish>seq_dbGetAttrInfo <alias>eric.myVector
VECTOR 6 15 1
seqWish>seq_dbGetAttrInfo <alias>eric.myTable
TABLE {20 24 25} 5 3
seqWish>seq_dbGetAttrInfo <alias>eric.myTable(0:0,1:2)
TABLE {24 25} 1 2
seqWish>.....
seq_dbGetAttrNames, seq_dbGetFamilyNames, seq_dbGetFieldNames,
seq_dbGetAlias -
list the attributenames of a point, get the symbolic addresses of
parent and children, list the field names of a table or get the
alias name of a point
seq_dbGetAttrNames <pointName>
seq_dbGetFamilyNames <pointName> <view>
seq_dbGetFieldNames <attrName>
seq_dbGetAlias <pointName>
seq_dbGetAttrNames:
will retrieve the list of names of the attributes belonging to a point
<pointName> : string containing a symbolic address of the point whose
attributenames we want to know
seq_dbGetAttrNames will return a single list containing the names of
the attributes.
seq_dbGetFamilyNames:
will retrieve the symbolic addresses of the parent and the children of
a point.
<pointName> : string containing a symbolic address of the point whose
family addresses we want to know
<view> : view specifier for the addresses; can be either ABSOLUTE,
ALIAS or RELATIVE (both upper- and lowercase allowed)
seq_dbGetFamilyNames will return a list containing the following values:
1. the parent's address
2. the addresses of the children, one list-element per child.
If the point does not have any children, this list will contain only one
element, i.e. the parent's address.
seq_dbGetFieldNames:
will retrieve the list of names of the fields of a TABLE attribute
<attrName> : string containing a full symbolic address of the attribute
whose fieldnames we want to know
seq_dbGetFieldNames will return a single list containing the names of
the fields.
seq_dbGetAlias:
will retrieve the alias name of a point
<pointName> : string containing a symbolic address of the point whose
alias we want to know
seq_dbGetAlias will return the alias name.
OK return if no errors occurred. In this case the result string contains
the attribute, family or alias names, as indicated above.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- "wrong # args : should be "seq_dbGetAttrNames <pointName>": the
command was given with the wrong number of arguments
- "wrong # args : should be "seq_dbGetFamilyNames <pointName> <view>":
the command was given with the wrong number of arguments;
- "wrong # args : should be "seq_dbGetFieldNames <attrName>": the
command was given with the wrong number of arguments;
- "wrong # args : should be "seq_dbGetAlias <pointName>": the command
was given with the wrong number of arguments;
- "wrong view specifier: should be ABSOLUTE, ALIAS or RELATIVE"
- "cannot get attribute names of "<pointName>": dbGetAttrNames returned
an error for this argument
- "cannot get family info on "<pointName>": dbGetFamilyNames returned
an error for this argument
- "cannot get field names of "<pointName>": dbGetFamilyNames returned
an error for this argument
- "cannot get alias name of "<pointName>": dbGetAlias returned an error
for this argument
Unfortunately, point and attribute names can in principle contain spaces.
If this is the case, such name will be surrounded by braces, as any
proper Tcl-list element.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbGetAttrNames :PARAMS:SCALARS
scalar_double scalar_float scalar_int32 scalar_logical scalar_string128
seqWish>seq_dbGetFamilyNames :PARAMS:SCALARS absolute
:PARAMS
seqWish>seq_dbGetFamilyNames :PARAMS absolute
: :PARAMS:SCALARS :PARAMS:TABLES :PARAMS:VECTORS
seqWish>seq_dbGetFamilyNames :PARAMS alias
<alias>root <alias>SCALARS <alias>TABLES <alias>VECTORS
seqWish>seq_dbGetAttrNames :PARAMS:TABLES
full_table
seqWish>seq_dbGetFieldNames :PARAMS:TABLES.full_table
logical int8 uint32 float string4 string32
seqWish>seq_dbGetAlias :PARAMS:TABLES
<alias>TABLES
seqWish>.....
seq_dbGetDirAddr, seq_dbDirAddrToName - get the internal address of a
point or attribute, or convert the direct address into a symbolic one.
seq_dbGetDirAddr will retrieve the detailed description of an attribute.
<attrSymAddress> : string containing a symbolic address of the attribute,
in a format as permitted by dbGetDirAddr(3);
seq_dbGetDirAddr will return a formatted string which is understood by
several db/Rtap routines and utilities as a direct address.
seq_dbDirAddrToName will convert the direct address into a symbolic one
<directAddress> : string with a direct address of a point/attribute;
<view> : view specifier for the address; can be either ABSOLUTE,
ALIAS or RELATIVE (both upper- and lowercase allowed)
seq_dbDirAddrToName will return the corresponding address in the form
as specified in <view>
OK return if no errors occurred. In this case the result string contains
the address.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- "wrong # args : should be "seq_dbGetDirAddr <attrSymAddress>": the
command was given with the wrong number of arguments;
- "wrong # args : should be "seq_dbDirAddrToName <directAddress> <view>":
the command was given with the wrong number of arguments;
- "cannot get internal address of "<attrSymAddress>"": dbGetDirAddr(3)
returned an error for this argument
- "wrong view specifier: should be ABSOLUTE, ALIAS or RELATIVE";
- "cannot convert "<directAddress>" to a symblic address":
dbDirAddrToName(3) returned an error for this argument
Suffering from the same limitations as dbGetDirAddr(3) resp.
dbDirAddrToName(3) these commands work only for the local environment (i.e.
there should be no environment-name part in <attrSymAddress> nor
<directAddress>)
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbGetDirAddr <alias>eric
@[10]
seqWish>seq_dbGetDirAddr <alias>eric.myVector
@[10.0]
seqWish>seq_dbGetDirAddr <alias>eric.myVector(1:2)
@[10.0(1:2)]
seqWish>seq_dbDirAddrToName @[10.0] alias
<alias>eric.myVector
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbGetDirAddr(3), dbGetDirAddr(3), seqDbDirAddrToName(3),
dbDirAddrToName(3)
seq_dbListCreate, seq_dbListAdd, seq_dbListRemove, seq_dbListDestroy,
seq_dbListPut, seq_dbListList
- commands for the handling of db multi-read/write lists
seq_dbListCreate <environment> <access>
seq_dbListAdd <listId> <attrSymAddr1> ?<attrSymAddr2>? ...
seq_dbListRemove <listId> <attrSymAddr1> ?<attrSymAddr2>? ...
seq_dbListDestroy <listId>
seq_dbListExtract <listId> <attrSymAddr1> ?<attrSymAddr2>? ...
seq_dbListPut <listId> <attrSymAddr1> <value1> ?<attrSymAddr2> <value2>? ...
seq_dbListList ?<environment>?
seq_dbListCreate:
create an empty list of attributes
<envName> : environment name of the database to access
<access> : read or write access (r for read, w for write)
seq_dbListCreate will create and initialize the structure used for
subsequent multi-read/write operations. It returns a listId, which has
to be used in other seq_dbList* commands to refer to this particular list.
seq_dbListAdd:
add attributes to the multi-read/write list
<listId> : list handle as returned by seq_dbListCreate
<attrSymAddrN> : symbolic address of the database attribute, including
eventual indices but excluding the environment name
(as the environment to access was defined already by
seq_dbListCreate)
Remark that there will be no errors produced if the attribute is already
in the list.
seq_dbListRemove:
remove attributes from the multi-read/write list
<listId> : list handle as returned by seq_dbListCreate
<attrSymAddrN> : symbolic address of the database attribute to remove,
in exactly the same format as it was added initially with
seq_dbListAdd.
seq_dbListDestroy:
delete a multi-read/write list
<listId> : list handle as returned by seq_dbListCreate
seq_dbListExtract:
extract the information of some attribute(s) from the multi-read/write
list as a result of a read/write operation
<listId> : list handle as returned by seq_dbListCreate
<attrSymAddrN> : symbolic address of the database attribute whose info
is wanted, in exactly the same format as it was added
initially with seq_dbListAdd.
seq_dbListExtract will return a list with the following info for each
attribute given as an argument:
- the attribute-type (either SCALAR, VECTOR or TABLE)
- the list of data-types; data-types are integers reflecting the type
of the attribute's fields. For SCALARs and VECTORs this is a single
value (hence not surrounded by curly braces)
- the complection status of the multi-read/write operation for this
particular attribute; 0 means success, 1 signals failure
- the quality of the data: either OK, SUSPECT, ERROR or DISABLED; for
an explanation of the meaning of these words, see the CCS db
documentation.
- the list of values. For SCALARs, this is a single value, which will
include braces if it contains spaces. For VECTORs, if the attribute
covers multiple records, this will be a list of values, one per
record. For TABLEs, each list of values for each record will contain
as values as there are fields specified in the attribute. This scheme
is identical to what goes for the seq_dbReadSymbolic command.
If a single attribute was given as argument, the return-string will be a
list with the 5 elements as described above. If multiple attributes are
passed, the return-string will be a list with one element per attribute,
and each element is on its turn a list with the 5 elements given above.
seq_dbListPut:
prepare the listId's internal buffer corresponding to a certain attribute
for a multi-write operation.
<listId> : list handle as returned by seq_dbListCreate
<attrSymAddrN> : symbolic address of the attribute
<valueN> : list of values for this particular attribute, in the format
as returned by seq_dbReadSymbolic. I.e. for attributes of
type VECTOR and TABLE, it is a list with as many elements as
records have to be written. As usual in Tcl/Tk lists, if only
one record is written, i.e. if this list contains only one
element, enclosing braces are not needed.
seq_dbListPut will take the values passed, and store them in the memory
assigned to this attribute, so it is ready to be written out with a
seq_dbMultiWrite command. There is no database access involved with
this command.
seq_dbListList:
return a list with one element per listId. Each such element contains
the following information, in the order as listed:
- the list handle
- the environment name it is linked to
- the use-flag for this list ("r" for read, "w" for write)
- a list containing the attributes of this multi-read/write list.
The optional <environment> argument allows to restrict the list to this
particular environment.
OK return if no errors occurred. The result string is empty, except for
seq_dbListCreate, seq_dbListExtract and seq_dbListList, where it will
contain the strings as indicated above.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- 'wrong # args : should be "seq_dbListCreate <envName> <access>"': the
command was given with the wrong number of arguments
- 'wrong # args : should be "seq_dbListAdd <listId> <attrSymAddr1>
?<attrSymAddr2>? ..."': the command was given with the wrong number of
arguments
- 'wrong # args : should be "seq_dbListRemove <listId> <attrSymAddr1>
?<attrSymAddr2>? ..."': the command was given with the wrong number of
arguments
- 'wrong # args : should be "seq_dbListDestroy <listId>"': the command
was given with the wrong number of arguments
- 'wrong # args : should be "seq_dbListExtract <listId> <attrSymAddr1>
?<attrSymAddr2>? ..."': the command was given with the wrong number of
arguments
- 'wrong # args : should be "seq_dbListPut <listId> <attrSymAddr1>
<value1> ?<attrSymAddr2> <value2>? ..."': the command was given with
less than 3 arguments or an even number of arguments
- 'wrong # args : should be "seq_dbListList ?<environment>?"': the
command was given with the wrong number of arguments
- 'wrong value for access: "<access>" should be either "r" or "w"'
- 'cannot create a multi-read/write list for env <envName>, access
<access>': the call to dbListCreate returned an error
- 'invalid list handle: "<listId>"': <listId> does not start with the
word "list"
- 'invalid list handle: "<listId>" (no multi-read/write items associated
to it)': the shell does not know of any multi-read/write list with this
particular <listId>
- 'cannot get info on "<attrSymAddrN>"': during seq_dbListAdd, the call
to dbGetAttrInfo() failed, most likely because this symbolic address
is not correct.
- 'cannot add <attrSymAddrN> to multi-read/write list "<listId>": the
call to dbListAdd() failed for this symbolic address
- 'cannot remove <attrSymAddrN> from multi-read/write list "<listId>"':
this symbolic address is not a member of the multi-read/write list, or
the call to dbListRemove() failed for other reasons.
- 'cannot extract info of <attrSymAddrN> from multi-read/write list
"<listId>"': this symbolic address is not a member of the multi-read/
write list, or the call to dbListExtract() failed for other reasons.
- 'cannot destroy multi-read/write list "<listId>"': the call to
dbListDestroy() returned an error
- errors from list-splitting (<valueN> for VECTOR and TABLE attributes)
- 'amount of data incompatible with attribute info' during execution of
seq_dbListPut, for VECTORs and TABLEs with less/more data than the
number of records indicates
- 'record <i>: expected <m> data values; have got <n>': for TABLES the
number of values in each sublist (record) of <value> should equal the
number of dataType elements.
- 'record <i> field <m>: could not convert "<valueN>" to dbTYPE <n>':
the routine dbStrToDe(3) choked on this conversion of a TABLE data
element.
- 'record <i>: could not convert "<valueN>" to dbTYPE <n>': as above,
but here for the conversion of a VECTOR record.
- 'could not convert "<valueN>" to dbTYPE <n>': as above, but now for
the conversion of a SCALAR.
Comparing seq_dbLisExtract's return-string for the case of a single
attribute with the case of multiple attributes, one might detect a slight
inconsistency. For the latter, the reply will consist of a list with one
element per attribute. Each of these elements are on their turn a list
containing the attribute-type, data-type(s), status, quality and value(s) -
some of which can again be sublists.
If there is on the other hand only one attribute passed to
seq_dbListExtract, the reply will not be a list with a single element
(extrapolating the above scheme), but rather the contents of that single
element. The advantage of this approach is that one does not need so many
layers of list-handling commands in the most trivial case of a single
attribute.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbListCreate wte67 r
list0
seqWish>set attribute1 :PARAMS:SCALARS.scalar_float
seqWish>set attribute2 :PARAMS:VECTORS.vector_double(1:2)
seqWish>set attribute3 :PARAMS:TABLES.full_table(1:2,3:4)
seqWish>seq_dbListAdd list0 $attribute1 $attribute2
seqWish>....
seqWish>seq_dbListRemove list0 $attribute2
seqWish>seq_dbListList
{list0 wte67 r :PARAMS:SCALARS.scalar_float}
seqWish>seq_dbListAdd list0 $attribute3
seqWish>....
seqWish>seq_dbMultiRead list0
seqWish>seq_dbListExtract list0 $attribute1 $attribute3
{{SCALAR 8 0 OK 5.75} {TABLE {8 16} 0 OK {{4 5} {3 4}}}}
seqWish>....
seqWish>seq_dbListPut list0 $attribute1 321.5 $attribute2 {3 7}
seqWish>seq_dbListPut list0 $attribute3 {{1.2 {hi there}} {2. hi!}}
seqWish>seq_dbMultiWrite list0
seqWish>....
seqWish>seq_dbListDestroy list0
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbListCreate(3), seqDbListAdd(3), seqDbListRemove(3),
seqDbListDestroy(3),
seq_dbLockPoint:
will lock a single point in the database.
<pointName> : symbolic name or alias of the point to lock
<timeout> : number of seconds the point will be locked (range: 3 to
60); default: 3
The point will remain locked for <timeout> seconds, unless a
seq_dbUnlockPoint command is given before the timeout expires
seq_dbUnlockPoint:
will unlock a locked database point.
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- "wrong # args : should be "seq_dbLockPoint <pointName> ?<timeout>?":
the command was given with the wrong number of arguments;
- "wrong # args : should be "seq_dbUnlockPoint <pointName>": the command
was given with the wrong number of arguments;
- error message left by Tcl_GetInt applied on <timeout>;
- "cannot lock point "<pointName>": dbLockPoint returned an error for
this argument
- "cannot unlock point "<pointName>": dbUnlockPoint returned an error
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbLockPoint "<alias>eric"
seqWish>seq_dbread "<alias>eric.my scalar"
199.5
seqWish>seq_dbUnlockPoint "<alias>eric"
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbLockPoint(3), seqDbUnlockPoint(3)
seq_dbMultiRead:
read a list of attributes on a particular environment
<listIdN> : list handle as returned by seq_dbListCreate
seq_dbMultiRead will do the actual database access for all attributes
in the multi-read/write list <listIdN>, which was created and prepared
previously with the seq_dbList* commands. The actual values read can
be extracted with the seq_dbListExtract command.
seq_dbMultiWrite:
write a list of attributes on a particular environment
-block : option that signals that all attributes should be considered
a unit, and consequently to succeed all addresses must be
correct and writable by the user. Default: no blocking
<listIdN> : list handle as returned by seq_dbListCreate
seq_dbMultiWrite will do the actual database access for all attributes
in the multi-read/write list <listIdN>, which was created and prepared
previously with the seq_dbList* commands.
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message here between single quotes):
- 'wrong # args : should be "seq_dbMultiRead <listId1> ?<listId2>? ..."':
the command was given with the wrong number of arguments
- 'wrong # args : should be "seq_dbMultiWrite ?-block? <listId1>
?<listId2>? ..."': the command was given with the wrong number of
arguments
- 'invalid list handle: "<listId>"': <listId> does not start with the
word "list"
- 'multi-read/write list "<listId>" is currently undefined': the shell
does not know of any multi-read/write list with this particular
<listId>
- 'multi-read for list "<listId> failed': the call to dbMultiRead failed.
- 'multi-write for list "<listId> failed': the call to dbMultiWrite
failed
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbListCreate wte67 r
list0
seqWish>set attribute1 :PARAMS:SCALARS.scalar_float
seqWish>set attribute2 :PARAMS:VECTORS.vector_double(1:2)
seqWish>set attribute3 :PARAMS:TABLES.full_table(1:2,3:4)
seqWish>seq_dbListAdd list0 $attribute1 $attribute2 $attribute3
seqWish>....
seqWish>seq_dbListPut list0 $attribute1 321.5 $attribute2 {3 7}
seqWish>seq_dbListPut list0 $attribute3 {{1.2 {hi there}} {2. hi!}}
seqWish>seq_dbMultiWrite list0
seqWish>....
....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbListCreate(3), seqDbListAdd(3), seqDbListRemove(3),
seqDbListDestroy(3),
seq_dbReadSymbolic will read a value of an attribute
-noBadQLog : an optional flag indicating that Quality Errors should not be
sent to the logging system (which they are by default). Remark
that polling of "bad" attributes tends to fill up the log. If
-noBadQLog is set, the corresponding error stack will be reset
(i.e. it will be lost).
<attrSymAddress> : string containing a symbolic address of the attribute
<badQualityFlag> : name of a Tcl boolean variable that will be set/reset
according to whether the quality is suspect (bad) resp.
OK. This is useful for scanned attributes only.
seq_dbReadSymbolic will convert the value read to a string, and return it
as the result-string.
Scalar-values are not seen as list elements, i.e. they are never returned
with enclosing braces, unless they are of type string and the braces are
part of that string.
Vector-records are returned as a list and tables as a list of lists (with
each sub-list containing the values of all fields of 1 record). Surrounding
curly braces are added to these sub-lists for table-reads with more than
one field. They will also appear around every list-element which is a
string containing spaces. I.e. the use of lists is limited to the cases
where they are really needed. See also the 'CAUTIONS' section.
For floats etc. the precision is determined by tcl_precision.
tcl_precision:
global Tcl variable whose value is passed on to dbDeToStr(3) as the
argument determining the precision (i.e. the maximum number of
significant digits) of the conversion to string.
OK if no errors occurred. In this case the result-string contains the
db value(s)
ERROR if one of the following conditions is met (with the corresponding
error message here between quotes):
- 'wrong # args: should be "seq_dbReadSymbolic ?-noBadQLog?
<attrSymAddress> ?<badQualityFlag>?"': the command was given with the
wrong number of arguments
- 'wrong option: if "seq_dbReadSymbolic" has 3 args, one of them must be
"-noBadQLog"': as the message says
- 'cannot read "<attrSymAddress>", even after resizing buffer' if
dbReadSymbolic still returned an error even after the receiving buffer
was resized properly (RTAP only)
- 'cannot read "<attrSymAddress>"' if dbReadSymbolic returned an error
from which seq_dbReadSymbolic cannot recover
The <badQualityFlag> can of course not be set to "-noBadQLog" - but variable
names should never start with a dash!
Comparing the return-string for the case of a single record, single field
(like SCALAR) with the case of multiple records, one might detect a slight
inconsistency. For the latter, the reply will consist of a list with one
element per record. Each of these elements will on their turn be a list
if multiple fields are involved.
If there is on the other hand only one record to read, the reply will not
be a list with a single element (extrapolating the above scheme), but
rather the contents of that single element, i.e. the value(s) of the
field(s).
So a table with one record, one field gives a result-string containing a
single value. One record, multiple fields gives a list with one element
per field (each element containing a field's value). Multiple records,
one field gives a similar list. Multiple records, multiple fields result
in a list with one element per record. Each of these elements are on their
turn a list, with one element per field.
The advantage of this approach is that one does not need so many layers of
list-handling commands in the most trivial case of a single value.
The internal buffer needed to read the attribute's value is automatically
increased if necessary. This memory is not returned to the system until
the shell is stopped.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_dbReadSymbolic ":PARAMS:SCALARS.scalar_float" bad
12.345679
seqWish>set bad
0
seqWish>set tcl_precision 3
seqWish>seq_dbReadSymbolic ":PARAMS:SCALARS.scalar_float"
12.3
seqWish>set tcl_precision 10
seqWish>seq_dbReadSymbolic ":PARAMS:VECTORS.vector_double(2:4)"
12.34567890 0. 0.987654321
seqWish>seq_dbReadSymbolic ":PARAMS:TABLES.full_table(0:1)"
{{First field} second third} {wow {again wow} {more wow}}
seqWish>....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbReadSymbolic(3), seqInit(3), dbReadSymbolic(3), dbDeToStr(3)
seq_dbSetCwp:
will set the current working point
<pointName> : the database point to set the current working directory
to; is either a symbolic address or its alias.
seq_dbGetCwp:
will return the current working point
<envName> : name of the environment whose current working point has to
be returned; defaults to the current environment.
OK return if no errors occurred. For seq_dbGetCwp the result string
contains the current working point (not including the environment
name).
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- "wrong # args : should be "seq_dbSetCwp <pointName>": the corresponding
Sequencer command was given with the wrong number of arguments;
- "wrong # args : should be "seq_dbGetCwp ?<envName>?": the
corresponding Sequencer command was given with the wrong number of
arguments;
- "cannot set CWP to "<pointName>": dbSetCwp returned an error
for this argument
- "cannot get CWP from "<envName>": dbGetCwp returned an error
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_dbSetCwp "<alias>eric"
seqWish>seq_dbGetCwp
:users config:eallaert
seqWish>.....
seq_dbWriteSymbolic will write the <value> into an attribute pointed to by
its symbolic address. The arguments are:
<attrSymAddress> : string containing the symbolic address of the attribute
<attrInfo> : a list containing 4 elements, in the following order:
- the type of the attribute, i.e. SCALAR, VECTOR or TABLE (attrType)
- the data type(s) of the attribute; integer(s) in the dbTYPE range
(datatype). Remark that for TABLEs, only the data types of the fields
which will be written into must be specified.
- the number of attribute records to write
- the number of attribute fields to write
The latter two pieces of informations correspond to the information
returned by seq_dbGetAttrInfo.
If <attrInfo> is not specified, a call to dbGetAttrInfo will be issued
to retrieve these data (which may slow down this function somewhat).
<value>: the new value(s) for the attribute.
For attributes of type VECTOR and TABLE, the last argument is a list with
as many elements as records have to be written. As usual in Tcl/Tk lists,
if only one record is written, i.e. if this list contains only one element,
enclosing braces are not needed.
For attributes of type TABLE, the data types (part of <attrInfo>) is a
sublist. This data type list contains one element per field. The
argument with the values consists of one element per record, as for
VECTORs. However, here each element is a sublist, with one element (value)
per field.
The number of records to write for VECTORs and TABLEs is taken from the
<attrInfo>, or, in its absence, via a call to dbGetAttrInfo. It is checked
against the length of the list of new attribute values.
The DB end-range character '$' is fully supported for both record and field
ranges, as are record addressing by content and field addressing by name.
Remark that some values (e.g. time values) can be (sub)lists.
OK if no errors occurred, with an empty result string.
ERROR if one of the following conditions is met (with corresponding
error message here between quotes):
- 'wrong # args: should be "seq_dbWriteSymbolic <attrSymAddress>
?<attrInfo>? <value>"': the corresponding Sequencer command was given
with the wrong number of arguments;
- '<attrInfo> should contain the data type' if the <attrInfo> list has
only one element;
- '<attrInfo> for VECTOR should contain the record count' if the
<attrInfo> list has only two elements for an attribute of type VECTOR;
- '<attrInfo> for TABLE should contain the record and field counts' if
the <attrInfo> list has less than 4 elements for an attribute of type
TABLE;
- 'attribute type "<attrType>" unknown; should be SCALAR, VECTOR or
TABLE': the attribute type specified is none of the three listed
- errors from parsing integers (data type, record count, field count)
- errors from list-splitting (<attrInfo>; dataType for TABLE; <value> for
VECTOR and TABLE)
- 'amount of data incompatible with attribute info' for VECTORs and
TABLEs with less/more data than the number of records indicates
- 'amount of supplied data type info inconsistent with number of fields'
for TABLEs with less/more data type info than the number of fields
indicates
- 'record <i>: expected <m> data values; have got <n>': for TABLES the
number of values in each sublist (record) of the last argument should
equal the number of dataType elements.
- 'record <i> field <m>: could not convert "<valueX>" to dbTYPE <n>':
the routine dbStrToDe(3) choked on this conversion of a TABLE data
element.
- 'record <i>: could not convert "<valueX>" to dbTYPE <n>': as above,
but here for the conversion of a VECTOR record.
- 'could not convert "<valueX>" to dbTYPE <n>': as above, but now for
the conversion of a SCALAR.
- 'cannot write to database': the call to dbWriteSymbolic failed
Although "named" record and field indices are allowed, they require an
additional access to the database to convert them to numbers. This means
extra overhead, which is avoided by giving numbers. Additionally, this
works only for the local environment, as it relies on dbGetDirAddr(3).
The buffer needed to write the attributes' values to the database via an
dbWriteSymbolic call is automatically resized if necessary, and never
deallocated. This may cause for unfairly big writes to TABLEs a one-time
noticeable growth of the process memory.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_dbWriteSymbolic <alias>me.myScalar {SCALAR 5 1 1} 327
seqWish>seq_dbWriteSymbolic <alias>me.myVector(1:2) {VEC 6 15 1} {3 7}
attribute type "VEC" unknown; should be SCALAR, VECTOR or TABLE
seqWish>seq_dbWriteSymbolic <alias>me.myVector(1:2) {VECTOR 6 15 1} {3 7}
seqWish>set a [seq_dbReadSymbolic <alias>me.myTable(0:0)]
seqWish>seq_dbWriteSymbolic <alias>me.myTable(1:1) {TABLE {20 25} 5 2} $a
seqWish>seq_dbWriteSymbolic <alias>me.myTable(1:1,1:1) {TABLE 25 5 2} ""
seqWish>....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqDbWriteSymbolic(3), dbStrToType(3), dbWriteSymbolic(3) , dbGetDirAddr(3)
seq_deleteHandle will delete a <handle> and its related resources. It
provides a unified way to do this for any of the handles currently used by
the Sequencer shell:
- a command handle, as obtained by issuing a "seq_msgSendCommand" (in this
section, the word "command" refers to such a message sent with
"seq_msgSendCommand). The handle itself will be removed; all buffers
corresponding to replies which are already in, but which are not yet
retrieved via e.g. a seq_msgRecvReply command, will be freed. Remark that
also the corresponding commandId will be freed up for re-use.
Consequently, replies for this particular command which are not yet on
the queue can no longer be handled properly after issuing a
seq_deleteHandle (see CAUTIONS).
- an event handle, as obtained by issuing a "seq_evtAttach" command. There
will be an evtDetach() call before the handle is removed. This is
equivalent to the command "seq_evtDetach".
- an alarm handle, as obtained by issuing a "seq_alrmAttach" command. There
will be an alrmDetach() call before the handle is removed. This is
equivalent to the command "seq_alrmDetach".
- a script handle, as received with a SCRIPT command (see seq_msgSendReply).
The process which sent this SCRIPT command will receive a final reply
indicating that the script handle is being deleted, and no further
processing will take place.
- a multi-read/write list, as obtained with a seq_dbListCreate command.
This is identical to issuing the seq_dlListDestroy command.
As indicated above, for event-handles and list-handles "seq_deleteHandle"
is equivalent to "seq_evtDetach" resp. "seq_dbListDestroy". There is no
obvious reason why one would want to delete a script-handle (as they are
under normal conditions short-lived and anyway not numerous), but for
reasons of uniformity this type of handles can be dealt with as well. So
the objects of seq_deleteHandle might remain limited to the command-
handles.
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message here between single quotes):
- 'wrong # args : should be "seq_deleteHandle <handle>"' the corresponding
Sequencer command was given with the wrong number of arguments;
- 'invalid handle: "<handle>"' if the handle is not one of the four types
listed above (looking at the first few characters)
- 'invalid cmd handle: "<handle>" (no replies pending on it)': if the
command-handle does not have any replies pending on it
- 'invalid event handle: "<handle>" (no database-events associated to it)'
if the event-handle does not have any attributes attached
- 'invalid script handle: "<handle>" (no SCRIPT command related to it)'
- 'invalid list handle: "<handle>" (no multi-read/write items associated
to it)'
The deletion of a command-handle should be exercised with proper care.
The reason being that the process who received the associated command will
not be informed that it should no longer send replies to this command. If
it still does, it will use a commandId which the Sequencer shell in the
meantime may have allocated to another command. This could obviously lead
to confusion in the reply handling. So this deletion of a command-handle is
intended for cases where one is confident that the partner process is no
longer alive, or when one has other means to prevent the partner from
sending "pending" replies.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>set cmdId [seq_msgSendCommand $env $proc INIT]
..... (user notifies that $proc died during initialization)
seqWish>seq_deleteHandle $cmdId
seqWish>.....
seq_errLog will handle the logging of a single error for the Sequencer,
i.e. it will first reset the error stack, then log <error> and finally
close (and thereby reset) the error stack.
<error> : string containing a description of the error
<srcId> : string containing the source identifier
OK return if no errors occurred. The result string is empty.
ERROR return if seq_errAdd fails, with a corresponding error message as
generated by seq_errAdd.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_errLog "Who the hell deleted this file??" "file_proc"
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seq_errResetStack(n), seq_errAdd(n), seq_errCloseStack(n)
seq_errResetStack, seq_errAdd, seq_errCloseStack, seq_errPrint,
seq_errDisplay, seq_errGetStackSize, seq_errGetFromStack -
interface to the CCS error logging
seq_errResetStack ?-internal|-reply?
seq_errAdd ?-internal|-reply? <error> <sourceId>
seq_errCloseStack ?-internal|-reply?
seq_errPrint ?-internal|-reply?
seq_errDisplay ?-internal|-reply? ?-suspend?
seq_errGetStackSize ?-internal|-reply?
seq_errGetFromStack ?-internal|-reply? <frameNr>
These commands will handle the logging of errors for the Sequencer (see
further below for a description of the -internal and -reply options):
seq_errResetStack: resets the error stack; to be used after the
successful recovery from an error, or at initialization time, before
calling seq_errAdd for the first time (see also CAUTIONS section).
seq_errAdd adds the string <error> to the error stack, pointing to
<sourceId> (a string) as the originator of the error. The moduleId
(default: "seq") with which it will be logged can be modified via the
global Tcl variable seq_moduleId. Of course this would then require that
a proper error definition file exist for this new moduleId. In
particular, error number 1 is reserved for this command; it needs to have
been defined with the format-string ".256s".
seq_errCloseStack logs the last added error and closes the stack; used
if no error recovery is possible. Remark that after this the error
stack is reset automatically.
seq_errPrint will return a list with all the elements of the last CCS
error, which was either produced internally or received as a reply.
The order of the list is as follows (see also a description of the CCS
error structure for more details):
o environment name
o stackId structure (hostId and localNumber) as a list
o stack sequence number
o location identifier
o module identifier
o error number (must be > 0)
o severity (W for Warning, S for Serious, F for Fatal)
o error message (between braces if it contains spaces)
o timestamp of the error
seq_errDisplay will pop up a panel showing the stack of the last CCS
error, which was either produced internally or received as a reply. If
the -suspend option is specified, the Sequencer script will wait for
this error panel to be closed before continuing.
seq_errGetStackSize returns the size of the stack of the last CCS error;
0 means it is empty
seq_errGetFromStack will return the contents of the frame <frameNr> in
the error stack as a list, formatted similar as seq_errPrint
The Sequencer uses 3 different error stacks, which can be selected via the
presence or absence of the options -internal and -reply. Also the logging
of these stacks can be influenced, via the setting of the Tcl-variable
seq_errLogging. The use of this variable, and the selection plus purpose
of the different stacks is explained in the next few paragraphs.
Whenever the Sequencer gets a CCS-error it cannot recover from, the
internal error stack will be submitted to an errCloseStack call
(seq_errLogging set to auto). This means that the Sequencer script does
not need to include any instructions to close and log any error stack.
In this case, the call to errCloseStack() will actually be preceded by an
errAdd() call, identifying the Sequencer as the top-level.
If the Sequencer receives via seq_msgRecvReply an error reply, this reply
error stack will also be logged automatically (if the default setting of
the variables seq_errLogging and seq_errReplyMerging is used, see below),
however without the Sequencer appending its own message. If you want to add
your own error messages to this reply stack, you can set seq_errLogging
to "manual" and then give the proper seq_errAdd / seq_errCloseStack
commands using the option -reply. Alternatively, one can use the
seq_errReplyMerging variable to have this stack automatically merged into
one of the two other stacks (see below).
In both cases, a copy of this error stack is kept in the "display stack",
so that it still can be displayed with e.g. the seq_errGet* commands even
after errCloseStack() was called automatically (which resets the stack,
rendering its previous contents unaccessible).
For seq_errResetStack, seq_errAdd and seq_errCloseStack the error stack
referred to is completely independent from the Sequencer's internal error
stack (used for returned CCS errors, as described above), unless the
-internal option is specified. This option is intended for the cases
where one does not want automatic logging, by setting the global
Tcl-variable seq_errLogging to manual - see the description of
seq_errLogging below. Remark however that issuing a seq_errCloseStack
command with seq_errLogging set to manual behaves the same as for auto,
i.e. the error stack will be logged, and it will be copied into the
display stack" for further display purposes.
The error stack referred to by seq_errPrint, seq_errDisplay,
seq_errGetStackSize and seq_errGetFromStack is by default the "display
stack", i.e. a copy of either the last error message received by
seq_msgRecvReply, the last internal error logged automatically or the last
error stack logged explictly via seq_errCloseStack. Again, the -internal
and -reply options are only useful when the global Tcl-variable
seq_errLogging is set to manual. The -reply option is to refer to the last
error which was returned as a reply to a command. This is useful in cases
where due to further script execution the "display stack" may get
overwritten by internal errors.
If both the -internal and -reply options are given, the one given last
prevails.
The environment variable NO_ERR_DISPLAY affects the behaviour of
seq_errDisplay, in that it will send its output to stdout instead of
popping up a new window if set. See also errDisplay(3).
The global Tcl variable seq_errLogging reflects how the logging of errors
occuring during the execution of seq_* commands are dealt with; "auto"
(default) leads to automatic logging of all unrecoverable errors (by
issuing an errCloseStack()), "off" will not log any error (by issuing an
errResetStack), while "manual" will not issue any err*Stack command.In the
latter case it is assumed that the script will take care of the error stack
via "seq_err* -internal|-reply" commands. In all cases, the corresponding
error stack will be copied over to the "display stack".
The global Tcl variable seq_errReplyMerging determines how the merging of
error-replies will take place: "internal" will append the reply-stack to
the internal error stack, "local" will make the reply-stack append to the
default stack of seq_errAdd etc, while "off" (default) leaves the error
reply stack alone. In the former 2 cases, the error reply stack will be
reset after merging, without any logging. In the latter case, it will get
logged automatically if seq_errLogging is set to "auto", in which case it
will also be copied over to the "display stack".
The global Tcl variable seq_moduleId has its effect on how errors are
logged with seq_errAdd - see above.
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message strings here printed in boldface):
- wrong # args : should be "seq_errResetStack ?-internal|-reply?"
wrong # args : should be "seq_errAdd <error> ?-internal|-reply?
<sourceId>"
wrong # args : should be "seq_errCloseStack ?-internal|-reply?"
wrong # args : should be "seq_errGetStackSize ?-internal|-reply?"
wrong # args : should be "seq_errGetFromStack ?-internal|-reply?
<frameNr>"
wrong # args : should be "seq_errPrint ?-internal|-reply?"
wrong # args : should be "seq_errDisplay ?-internal|-reply?
?-suspend?"
the corresponding Sequencer command was given with the wrong number
of arguments;
- sourceId "<sourceId>" too long if the string length of <sourceId>
exceeds the limits imposed by the ccsERROR structure;
- error message left by Tcl_GetInt, when trying to interpret <frameNr>
as an integer;
- could not do an errAdd - check the log if during the processing of
the seq_errAdd command the call to errAdd(3) failed.
- could not get error-frame <frameNr> from stack if seq_errGetFromStack
returns an error (e.g. <frameNr> exceeds the current stack size)
- wrong option: <option> should be "-internal", "-reply" or "-suspend"
if any of these words were misspelled for the seq_errDisplay command
Under NOCCS, only seq_errResetStack, seq_errAdd and seq_errCloseStack
are avaliable.
Under CCS-lite, the current setting of RTAPENV is taken whenever the first
CCS-function gets called. If this first CCS-function is not a ccsInit(),
this value of RTAPENV will anyway be used later when ccsInit() get called,
independent of RTAPENV's value at that later time. This means that e.g. in
the wtctest environment, issuing first a seq_errResetStack command
followed by a set env(RTAPENV) xyz and a seq_ccsInit command, will lead
to a ccsInit() in the wtctest environment instead of the xyz environment.
This is not inherent to seq, but rather to CCS-lite. In fact, to enable an
effective modification of the environment variable RTAPENV within a
Sequencer script (e.g. based on runstring options), the Sequencer's internal
initialization does not call any CCS-function under CCS-lite, thereby
shifting the responsibility to do things in the proper order to the
application.
seq_errGetStackSize and seq_errGetFromStack manipulate either the reply or
the internal error stack. The stack set aside for seq_errAdd,
seq_errCloseStack and seq_errResetStack is a different one, and hence
cannot be seen by the seq_errGet* commands.
The arguments of seq_errAdd will all be logged as errors with a severity
of "warning".
seq_errDisplay will by default use the information of the last CCS error,
which is stored in a global C-variable for use by all seq-commands. So if
the seq_errDisplay command is not called immediately after detecting such
an error, or if the -suspend option is not used, the displayed values may
not correspond to what is expected.
Subsequent calls to seq_errDisplay, without destroying windows in between,
will simply update the information displayed in these error stack windows.
This may not be the desired effect for panels with classes that can try
simultaneously to display errors via the seq_errDisplay command.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_errResetStack
seqWish>seq_errAdd "Who the hell deleted this file??" "my procedure"
seqWish>seq_errCloseStack
...(This error can now be seen with the log-monitor)...
.....
seqWish>seqSendCommand wte67 otherSeq SCRIPT {puts hello}
seqWIsh>seq_msgRecvReply cmd0 en lr -all
seqERR_NO_CMDS_ALLOWED : Command "SCRIPT" rejected - no commands allowed
seqWish>seq_errGetStackSize
1
seqWish>seq_errGetFromStack 1
wte67 {0 4869} 1 seqMsgDispatch.c seq 122 W {seqERR_NO_CMDS_ALLOWED :
Command "SCRIPT" rejected - no commands allowed} {97-02-14
15:35:53.324656}
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
errResetStack(3), errAdd(3), errCloseStack(3), errGetStackSize(3),
errGetFromStack(3), errDisplay
seq_evtAttach, seq_evtDetach, seq_evtSingleDisable, seq_evtSingleEnable,
seq_evtList - database and event management commands
seq_evtAttach <attrName> <filter> <script>
or
seq_evtAttach <cmdId> <timeout> <script>
seq_evtDetach <eventHandle>
seq_evtSingleDisable <eventHandle>
seq_evtSingleEnable <eventHandle>
seq_evtList ?-status? ?-attrName? ?-filter? ?-script? | ?-all?
seq_evtAttach:
in its first form will attach an event to a database attribute:
<attrName> : the database attribute to which an event has to be
attached; is either a symbolic address or its alias.
<filter> : to condition which should generate the event. It can be:
< or LT for less than
<=, =< or LE for less or equal
=, == or EQ for equal
> or GT for greater than
=>, >= or GE for greater or equal
!= or NE for not equal
w or W for any write
<> or >< for deadband
<script> : the script to execute when an event occurs; this script
will be evaluated at global level. The following substitutions will
be performed on this script before evaluation:
- %A : name of the attribute causing the event
- %D : event data; this is a list, whose contents depends on the
attribute type as follows (see also evtParseMsg(3))
for SCALAR: {<dataType> <oldValue> <newValue>}
for VECTOR: {<startElement> <endElement>}
for TABLE: {<startElement> <endElement> <startField>
<endField>}
- %P : info about the process causing the event; a list with two
elements: {<envName> <processName>}. Remark however that
events associated with LCU database attributes do not return
this information, and an attempt to use this substitution
will result in errors in this case.
- %Q : quality (for scalars only). It gives a list with 2 values:
{<oldQuality> <newQuality>}
where <oldQuality> and <newQuality> can be either OK,
SUSPECT, ERROR, or DISABLED. The exact meaning of these
words can be found in the evtParseMsg(3) manpage.
For vectors and tables, this will give an empty list.
- %T : attribute type. Either SCALAR, VECTOR or TABLE
- %U : the user-message part of the event
- %% : a single % character
Whenever the substitution on the original script or the evaluation
of the resulting script yields an error, the corresponding event
will be disabled, and the error will be logged and also signalled in
a separate window popping up via Tcl_BackgroundError.
in its second form will attach the execution of a script to an incoming
reply:
<cmdId>: as returned by seq_msgSendCommand
<timeout>: timeout value in ms; a timeout-error reply will be generated
if no reply came in within that time. Zero means no timeout. The
absolute value is taken.
<script>: a script to be executed (at global level) when such a reply
comes in; this script will be executed once for each reply,
independent from the value for lastReply or the error condition,
including timeout. In other words, the script must intercept these
different conditions.
The following substitutions will be performed on the script before
it is evaluated:
- %A : ASCII reply received in the message body; if this reply is
empty or contains any spaces, it will be surrounded by curly
braces.
- %E : error number from the received error structure; 0 means no
error
- %F : formatted binary reply received in the message body; if this
reply is empty or contains any spaces, it will be surrounded
by curly braces. Remark that this also works fine on ASCII
replies, although it is not as efficient as %A. Unformatted
binary replies will be left empty ({}), while replies without
an entry in the CDT will be treated as ASCII.
- %L : last reply flag; "0" for not set, "1" if set
- %R : reply received in the message body; if this reply is empty
or contains any spaces, it will be surrounded by curly braces.
This substitution is equivalent to %F if the command was sent
with command checking on (see seq_msgSendCommand(n));
otherwise it behaves as %A.
- %T : timeout flag; "0" for no timeout, "1" for timeout
- %% : a single % character
Whenever the substitution on the original script or the evaluation
of the resulting script yields an error, the corresponding event
will be disabled. On top of that, the error will be logged and also
signalled in a separate window popping up via Tcl_BackgroundError.
Replies already on the internal stack will be treated as events.
After the last reply is dealt with, the link between the <cmdId> and
the <script> is deleted (as in fact the command handle with all
associated information is removed).
The distinction between the two forms of the seq_evtAttach command is
done based on the second argument: if it is an integer, then it must be
the attachment to an event-reply.
seq_evtDetach:
will detach a previously attached event from a database attribute,
and delete the event handler
<eventHandle> : the event handle, as returned by seq_evtAttach.
seq_evtSingleDisable:
will disable a previously attached event
<eventHandle> : the event handle, as returned by seq_evtAttach.
seq_evtSingleEnable:
will enable a previously attached and disabled event
<eventHandle> : the event handle, as returned by seq_evtAttach.
seq_evtList:
lists the already defined events with their properties as requested:
-status : tell whether for each event whether it is enable or disabled
-attrName: give the attribute name to which the event is attached
-filter : include also the filter
-script : list the script that will be evaluated when the event occurs
-all : shorthand for the above 4 properties
The result string is contains per event a sublist with the elements as
requested. They will be listed in the order as given above, i.e.
independent of the order of these options on the command line, and
preceeded by the event handle. Remark that attrName, filter and script
are in the order and format as required for seq_evtAttach.
The value of the seq_ccsCmdCheck variable at the time the command was sent
can be used to flag the (expected) presence of a CDT of the process the
reply comes from. It influences the behaviour of the %R substitution. See
also seq_msgSendCommand(n) and seqInit(3).
The seq_evt* commands have corresponding entries in the global Tcl array-
variable seq_debug, which controls the printing of debug information (see
Seq_Init(3)). On top of that, if bit 3 of seq_debug(seq_msgDispatch) is set,
there will be additional info printed on incoming event messages.
OK return if no errors occurred. For seq_evtAttach the result string
contains the event handle (eventNNN for database events, <cmdId> for
reply events) to use when referring to this this event with any other
seq_evt* command. For seq_evtList the result string is a list of
sublists (one sublist per event, with elements as requested).
ERROR return if one of the following conditions is met (with corresponding
error message here in bold-face):
- wrong # args : should be "seq_evtAttach <attrName> <filter> <script>"
or "seq_evtAttach <cmdId> <timeout> <script>" when the seq_evtAttach
command was given with the wrong number of arguments;
- invalid cmd handle "<cmdId>" (no replies pending on it) if a command
was given with a <cmdId> which has no more pending replies (i.e. the
handle is no longer valid)
- invalid event handle "<eventHandle>" (no database-events associated
with it) if a command was given with an <eventHandle> which is no
longer valid
- invalid filter: "<filter>" should be one of "< <= = > => != W" when
the filter is not valid
- cannot attach event to "<attrName>" if the call to evtAttach(3)
returns an error
- wrong # args: should be "seq_evtDetach <eventHandle>" when the
seq_evtDetach command is given with the wrong number of arguments
- invalid cmd handle "<cmdId>" if <cmdId> is not a command handle
- invalid event handle "<eventHandle>" if <eventHandle> is not an event handle
- cannot detach <eventHandle> if the call to evtDetach(3) returns an error
- wrong # args: should be "seq_evtSingleDisable <eventHandle>" when the
seq_evtSingleDisable command is given with the wrong number of
arguments
- cannot de-activate <eventHandle> when seq_evtSingleDisable(3) returns an
error
- wrong # args: should be "seq_evtSingleEnable <eventHandle>" when the
seq_evtSingleEnable command is given with the wrong number of arguments
- cannot re-activate <eventHandle> when seq_evtSingleEnable(3) returns an
error
- wrong # args: should be "seq_evtList ?-status? ?-attrName? ?-filter?
?-script? | ?-all?" when the seq_evtList command is given with the
wrong number of arguments
- bad option: "<arg>" should be -status, -attrName, -filter, -script or
-all when the seq_evtList command is given with a bad argument
As events associated with LCU database attributes do not return the full
information about the process causing the event, an attempt to use the %P
substitution will result in errors in this case.
A deadband event can only be attached to an LCU database attribute;
moreover, this requires the event to be configured previously with a call
to evtConfig(3) (which only exists in LCC).
For reply events, the CDT must be loaded into cmdManager in order to be
able to format replies. See cmdManager(1) and cmdSetup(1). The CDT is
not accessed if "%A" is used instead of "%R".
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
..... (<alias>my.scalar is a float with value 1.23)
seqWish>seq_evtAttach <alias>my.scalar w {set new [lindex %D 2]; set b 5}
event2
seqWish>set b 32
seqWish>.....
..... (<alias>my.scalar gets modified to 32.1)
seqWish>set b
5
seqWish>set new
32.1
seqWish>set b 42
seqWish>seq_evtSingleDisable event2
seqWish>.....
..... (<alias>my.scalar gets modified to 4.3)
seqWish>set b
42
seqWish>set new
32.1
seqWish>seq_evtDetach event2
seqWish>.....
Tcl and the Tk toolkit, John K. Ousterhout, ISBN 0-201-6337-X
evtAttach(3), evtDetach(3), evtSingleDisable(3), evtSingleEnable(3),
seq_msgDispatch(n), seqInit(3)
seq_logData will log a single line. It will be logged with a logId of
0 (general purpose log identifier).
<logString> : string that has to be logged
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- 'wrong # args : should be "seq_logData logString"': the corresponding
Sequencer command was given with the wrong number of arguments;
- 'cannot log "<logString>"': logData returned an error for this argument
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_logData "Hi mom! I crossed the street without looking!"
seqWish>.....
seq_logFitsAction <dictionary> <category> <subsys> <action>
seq_logFitsComment ?-<who>? <logString>
seq_logFitsEvent ?-<type>? <logString>
seq_logFitsParRecord ?-<type>? <dictionary> <cat> <subsys> <param> <value>
seq_logFitsAction will generate a FITS action record. Its arguments are:
<dictionary> : name of the dictionary that will be checked for
correctness of the other arguments; remark that this
does not include the "ESO-VLT-DIC" prefix.
<category> : 3-letter keyword category
<subsys> : subsystem name(s)
<action> : verb defining the action; corresponds to parameter-name
in the dictionary.
seq_logFitsComment will generate a FITS comment record. Its arguments are:
<who> : "classname" of generator of this log; legal values are:
"observer", "staff", "remote control" or "night assistant". These
names can also be abbreviated to "ob", "sa", "rc" respectively
"na", and they can contain any mixture of lower- and uppercase
characters. If <who> is not specified, a free-format comment will
be logged.
<logString> : string that has to be logged
seq_logFitsEvent will generate a FITS event record. Its arguments are:
<type> : "unforeseen" (default) or "recovery". These names can also be
abbreviated to "ufo" resp "rec", and they can contain any mixture
of lower- and uppercase characters.
<logString> : string that has to be logged
seq_logFitsParRecord generates a FITS parameter record. Its arguments are:
<type> : either "int" (for 32-bit integers), "real" (for doubles) or
"string" (for strings containing up to 256 characters)
<dictionary> : name of the dictionary that will be checked for
correctness of the other arguments; remark that this
does not include the "ESO-VLT-DIC" prefix.
<cat> : 3-letter keyword category
<subsys> : subsystem name(s)
<parameter> : parameter name (last substring of the short-fits keyword)
<value> : value for the parameter (in 256-byte string).
This seq_logFitsParRecord command is normally used with a <type> option,
indicating what sort of conversion (from string values) should take place.
Without this <type> option, seq_logFitsParRecord should be used with
extreme caution only, as one needs to take care that <value> is (at least)
256 bytes long. See also the CAUTIONS section below.
Conversion from string values is done using sscanf(3), which means that
e.g. floats are simply truncated if converted to integer. No errors are
returned if this conversion fails (e.g. attempting to convert "abc" to
a integer), but the value shown in the log will of course be wrong (it
will be set to zero).
The exact format of the FITS logs generated by these commands is described
in the manpages of the underlying respective logFits*(3) procedures.
The setting of the global Tcl variable seq_moduleId is used as the CCS
module-identifier in the the underlying logFits*(3) calls.
OK return if no errors occurred. The result string is empty.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- 'wrong # args : should be "seq_logFitsAction <dictionary> <category>
<subsys> <action>"': the corresponding Sequencer command was given with
the wrong number of arguments;
- 'wrong # args : should be "seq_logFitsComment ?-<who>? <logString>"':
the corresponding Sequencer command was given with the wrong number of
arguments;
- 'wrong # args : should be "seq_logFitsEvent ?-<type>? <logString>"':
the corresponding Sequencer command was given with the wrong number of
arguments;
- 'wrong # args : should be "seq_logFitsParRecord ?-<type> <dictionary>
<cat> <subsys> <param> <value>"': the corresponding Sequencer command
was given with the wrong number of arguments;
- 'cannot generate FITS action log - dictionary <dictionary>, category
<category>, subsystem <subsys>, action <action>': the underlying
logFitsAction(3) call returned an error.
- 'wrong generator: "<who>" should be "ob|observer", "rc|remote
control", "sa|staff" or "na|night assistant"'
- 'cannot generate FITS comment log "<logString>": the underlying call to
logFitsComment(3) returned an error.
- 'wrong type: "<type>" should be "ufo|unforeseen" or "rec|recovery"'
- 'cannot generate FITS event log "<logString>": the underlying call to
logFitsEvent(3) returned an error.
- 'wrong type: "<type>" should be "int", "real" or "string"'
- 'cannot generate FITS paramater record log - dictionary <dictionary>,
category <cat>, subsystem <subsys>, param <param>, value <value>':
the underlying logFitsParRecord(3) call returned an error.
The seq_logFitsParRecord command calls the logFitsParRecord(3) function,
which does a binary copy of 256 bytes of <value>. This means that in the
presence of a valid <type> option, there will internally be a conversion,
into a 256-byte buffer. Without this <type> option, the user of this command
mandatorily needs to take care of the encoding (i.e. put the right number of
bytes in the proper order within <value>), and in particular that <value>
does contain (at least) 256 bytes. Not following this rule could result in
segmentation errors. See see also Tcl's binary(n) command and the example
below.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_logFitsComment "This is a free-field FITS comments log"
seqWish>.....
seqWish># the easy way to log an integer value
seqWish>seq_logFitsParRecord -int OBS OBS "" ID $value
seqWish># or the hard way .....
seqWish>if {[cequal $tcl_platform(byteOrder) bigEndian]} {set i I}
seqWish>seq_logFitsParRecord OBS OBS "" ID [binary format ${i}x252 $value]
seqWish>.....
seqWish>seq_logFitsParRecord -string OBS OBS "" NAME "any string"
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
logFitsAction(3), logFitsComment(3), logFitsEvent(3), logFitsParRecord(3)
See seq_logStringParRecord(n).
See seq_logStringParRecord(n).
seq_logStringParRecord, seq_logIntParRecord, seq_logRealParRecord -
FITS parameter logging for strings, integers and floats
seq_logStringParRecord <dictionary> <category> <subsys> <parameter> <value>
seq_logIntParRecord <dictionary> <category> <subsys> <parameter> <value>
seq_logRealParRecord <dictionary> <category> <subsys> <parameter> <value>
These commands are all simple wrappers around seq_logFitsParRecord, ensuring
that the latter is called with the right option (-string, -int or -real).
OK return if no errors occurred. The result string is empty.
ERROR return if argument count is wrong or if seq_logFitsParRecord fails,
with a corresponding error message.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_logStringRecord OBS OBS "" NAME "this is my name"
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seq_logFitsParRecord(n), logFitsParRecord(3)
seq_logTclErrors allows to send strings that normally go to exclusively
to stderr also to the CCS error log. This feature is enabled by setting
the argument to "open", and disabled by setting it to "close".
Once active, errors logged will all have the same stack id, until this
logging is closed.
This command relies on a file-event. Such events are only handled when
the Sequencer is idle, i.e. when it is not busy evaluating commands from
a script. In other words, the output to the error log may not be visible
immediately, depending on the Sequencer's activity.
When this error logging is active, the global Tcl-variables OSE, EPR and
EPW are set and accessed.
The global Tcl-variable OSE refers to the original stderr file descriptor.
EPR and EPW are the reading resp writing end of a pipe created to divert
the messages sent to stderr.
OK, with and empty result string if no errors
ERROR with corresponding message in the result string under the following
conditions:
- "called "seq_logTclErrors" with too many arguments" if there was more
than 1 argument given to this command.
- "wrong arg: should be "open" or "close"" if argument is not correct
- "Tcl error logging already active" if open has been given before (i.e.
the global Tcl-variable OSE exists)
- "Tcl error logging already disabled" if close has been given before
(i.e. the global Tcl-variable OSE does not exist)
When this error logging is active, the Tcl-variables OSE, EPR and EPW are
set at a global level (by lack of static variables in Tcl). They should
not be modified.
The overhead caused by sending these messages also to the CCS error system
is considerable (on top of adding possibly quite a few messages to the
log). Its use should therefore be restricted to the bare minimum (e.g.
for debugging purposes).
Stderr must be open when Tcl error logging is started.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_logTclErrors open
seqWish>blablabla
Error: invalid command name "blablabla"
seqWish>seq_logTclErrors close
seqWish>.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seq_errResetStack(n), seq_errAdd(n), seq_errCloseStack(n)
seq_msgCheck <cmdId> | {<envName> <procName> <command> }
seq_msgList ?{<envName> ?<procName> ?<command>??}?
seq_msgCheck:
checks if there are still replies pending on a command identified by
its arguments. A "1" is returned if replies are pending, "0" if not.
<cmdId> : unique command handle, as returned by seq_msgSendCommand
<envName> : environment name
<procName> : process name
<command> : command name
seq_msgList:
returns a list with pairs, one pair per pending reply. Each pair
contains a cmdId and a sublist with originating environment name,
process name and command name, describing the command for which a
reply is pending. The optional list allows to refine the reply-list
progressively.
<envName> : environment name
<procName> : process name
<command> : command name
OK if no errors occurred. In this case the result string contains the
result as indicated above.
ERROR if one of the following conditions is met (with the corresponding
error message here between quotes):
- seq_msgCheck:
* "wrong # args: should be "seq_msgCheck <cmdId> | {<envName> <procName>
<command>}""
* "bad argument: "<argv[1]>" should be "<cmdId> | {<envName> <procName>
<command>}""
* error message left by Tcl_SplitList failing to parse the list
* error message left by TclX_HandleXlate failing to parse the <cmdId>
- seq_msgList: (char *) NULL);
* "wrong # args: should be "seq_msgList ?{<envName> ?<procName>
?<command>??}?""
* "bad argument: "<argv[1]>" should be "?{<envName> ?<procName>
?<command>??}?""
* error message left by Tcl_SplitList failing to parse the list
* error message left by TclX_HandleXlate failing to parse the <cmdId>
The <cmdId> as returned by seq_msgSendCommand is a unique identifier, while
<{<command> <envName> <procName>}> is not if several identical commands to
a certain process have replies pending. Hence, it is strongly advised to
use the former as argument for this command.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_msgSendCommand wte13 DCS init
cmd15
seqWish>...
seqWish>seq_msgCheck cmd15
1
seqWish>seq_msgList wte13
{cmd11 {wte13 ICS START}} {cmd15 {wte13 DCS INIT}}
seqWish>seq_msgRecvReply cmd15
CCD#87 initialized OK
seqWish>seq_msgCheck cmd15
0
seqWish>........
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqMsgSendCommand(3), seqMsgRecvReply(3)
seq_msgDispatch:
the Sequencer command executed automatically whenever a message is
available on the queue, and message reading has been enabled (see
seq_css(n)). As a registered Sequencer command it can be called just
like any other command, although this is not its primary reason for
existence.
<timeout> : timeout value in ms; default: 0 (wait forever). Remark
that if there is no message getting on the queue within
this timeout, the Sequencer shell will not be responsive
for the duration of this timeout!
If the timeout is negative, a no-wait retrieval of
messages will be done, and no error will be reported if
the queue is empty.
<nrMessages> : number of messages to get; default: 1
The standard CCS message-types can be retrieved this way, including
obituaries (provided this shell's CCS process-name has been entered in
the RtapEnvTable, with a proper value in the 'Care about Terminations'
field; remark that processes doing a ccsInit/ccsExit will generate
obituaries by default).
When an obituary is received, the script contained in the global
variable seq_obiScript will be executed, after the following
substitutions took place:
- %D: 1 if the deceased process registered for debug, 0 otherwise
- %E: environment name of the deceased process/environment
- %P: deceased process name or {} if the environment deceased
- %R: 1 if the deceased process will be automatically restarted, 0
otherwise.
- %S: exit status of the terminating process (integer value)
- %%: a single % character
Internal tables related to the deceased process (like the ones kept for
commands with pending replies) will be cleaned upon reception of an
obituary message. This internal housekeeping takes place even if
seq_obiScript is empty, and is actually done before evaluating
$seq_obiScript.
When seq_msgDispatch gets a command from the message queue it will
execute it. Presently the following commands are recognized (on top of
the special commands BREAK, KILL and PING predefined for all CCS
applications):
- EVENT : the message body must contain a legal Sequencer script which
will be evaluated. Similar to the SCRIPT command (see below),
with the difference that no replies are generated: the sender
of the EVENT command will not receive and should not expect any
reply on this command. This command is useful in an environment
where some process(es) need(s) to be informed of an event,
while it is considered too expensive to create/access a
database branch just for this purpose.
If this command was sent via seq_msgSendCommand, the latter
needs to have the -noreply option specified.
- SCRIPT : the message body must contain a legal Sequencer script which
will be evaluated. The result of this evaluation (i.e. the
return string) will be sent as the second reply to this
command - an immediate, empty reply is given before the
evaluation starts. If in this script intermediate replies
have to be sent, the so-called script-command-handle will be
needed (as this allows to retrieve the originator of the
command). This handle can be obtained with a %-substitution,
performed on the script before evaluation (equivalent to the
seq_evt substitutions):
- %S : script-command-handle; it is needed by the
seq_msgSendReply command, as it allows to identify the
process which originated the SCRIPT command..
- %% : a single % character
If the result of the script-evaluation is a string of a size
which does not fit into a single reply, seq_msgDispatch will
automatically chop up this string into multiple fragments,
send each fragment (in the right order) as a reply, whereby
only the last fragment will have the 'lastReply' flag set.
It will be up to the sender of the SCRIPT command to re-assemble
these replies by concatenating these individual pieces.
All other commands will be logged as errors, and an error message will
be sent back as well to the originator of the command.
seq_msgDispatch does also react on events. Whenever an event message
comes in, the script given at the time this event was defined (see
seq_evtAttach(n) and seq_msgRecvReply(n)) will be executed. The
evaluation of the script is at global level.
Whenever the substitution on the original script or the evaluation of
the resulting script yields an error, the corresponding event will be
disabled, and the error will be logged and also signalled via
Tcl_BackgroundError(3).
Similar for alarms: whenever an alarm message comes in, the script
given at the time this event was defined (see seq_alrmAttach(n)) will
be executed. The evaluation of the script is at global level.
Same remark about script substitution/evaluation errors as for event
messages.
The setting up of the queue monitoring is done via a call to
seqMonitorQ(3). Also the suspension of this service can be requested
to the same routine.
Whenever the timeout (in msec) or the nrMessages to read leads to an
unacceptable blocking of other tasks, the read-and-dispatch loop can be
broken with the seq_msgDispatchBreak command. Timeout defaults to 0
(wait forever), while nrMessages defaults to 1. The timeout is the
time to wait on a msgRecvMsg(3) call for a single message, i.e. it is
not the cumulative timeout, nor does it take the time to execute the
command (contained in the message) into account.
seq_msgDispatchBreak:
breaks the execution of seq_msgDispatch
seq_obiScript is a global Tcl variable containing the script to be executed
when an obituary message is received. This script can contain some variables
(single characters preceded by a %-sign) giving information about the
obituary itself; they are substituted just before evaluation of the script.
seq_msgDispatchBreak always returns an OK; the remainder of this sections
is for seq_msgDispatch only.
OK if no errors occurred; the reply contains the number of messages
effectively dispatched. Remark that this may deviate from <nrMessages>
depending on the setting of <timeout> and the intermediate reception of
a seq_msgDispatchBreak command.
ERROR if one of the following conditions is met (corresponding error
message is here between quotes):
- "wrong # args: should be "seq_msgDispatch ?<timeout> ?<nrMessages>??""
if the command contains more than 2 arguments
- "bad argument: "<argv>" should be an integer" if either <timeout> or
<nrMessages> have illegal values
- "bad argument: "<argv>" should be positive" if <nrMessages> is a
negative integer
- "could not get msg queue file descriptor" if seqGetMsgFd(3) failed.
- "timed out after <xx> messages"; can obviously only occur if <timeout>
is greater than 0.
Remark that most of these messages cannot appear when the seq_msgDispatch
is called via the "fileevent" scheme. In this case we are 100 % sure the
arguments are set to legal values and there is a message on the queue.
Also internal messages, which cannot be retrieved by the application but
do cause a fileevent, do not provoke any errors.
The causes of these errors are also logged via the standard CCS error
system and logging.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_msgDispatch 1000 1
1
seqWish>seq_msgDispatch 100000 5
5
seqWish>....
.....
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seq_ccs(n), seq_evtAttach(n), seq_evtParseMsg(3), seqMsgDispatch(3),
seqMonitorQ(3), RtapEnvTable(4)
seq_msgFlush waits a certain time for all replies to flush them as they
come in, or optionally flushes replies that are already available.
<option> can be either:
* -nowait : flags not to wait, i.e. flush only replies which are
available at the time the command is given
* <nnn> : an integer giving the timeout in ms to wait for replies
If no <option> is specified, the wait will be forever.
<filter> is a list with at least one element; it is either:
* the environment, and optionally, the process name for which
we want to flush the replies
* the word "all" to indicate replies to all commands
OK, with and empty result string if no errors
ERROR with corresponding message in the result string under the following
conditions:
- "called "seq_msgFlush" with too many arguments" if there were more
than 2 arguments given to this command.
- "wrong filter: should be "{<envName> ?<procName>?}"" if <filter> is wrong
- "wrong option: should be "-nowait" or "<nnn>"" if <option> is not correct
- any error message returned by seq_msgRecvReply
The timeout given is applied to all replies separately, i.e. the total,
cumulative timeout may be much larger than given by this number
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_msgList
{cmd5 {wte13 OS INIT}} {cmd9 {lte18 ICS RESET}} {cmd27 {wte13 DCS INIT}}
seqWish>seq_msgFlush wte13
seqWish>seq_msgList
{cmd9 {lte18 ICS RESET }}
seqWish>.....
seq_msgRecvReply waits for a single or all replies on a command identified
by its first argument, or for the specified timeout - whichever comes
first.
<options>: any of the following options, in any order (if contradicting
options appear, the last one will prevail):
* -all : flags to get all replies in, instead of only one, and
return all replies separated by a newline (in absence of
option "-bin"); empty replies do not get a newline
appended, nor is there a newline appended to each reply
if the -nonewline option is specified.
* -ascii : flags reply is supposed to contain ASCII data; the CDT's
data for the reply's format is not checked nor used. This
is slightly more efficient if you know in advance that the
reply is ASCII (and/or that the CDT is not available)
* -bin : flags data should not be returned in result string
(e.g. when reply contains unformatted binary data).
* -fbin : flags data should be formatted according to the command's
entry in the CDT (DISPLAY_FORMAT field). This works fine
for formatted binary and ASCII replies, although for the
latter it is more efficient to use the -ascii option (so no
formatting needs to be attempted). Unformatted binary
replies will result in an empty string (although again, it
is more efficient to do that via the -bin option). If the
reply does not have an entry in the CDT, it will be
considered as ASCII (same remark again).
* -last : flags to wait on the last reply, and and return the data of
the last reply only (if option "-bin" is not set)
* -<nnn> : any integer, giving the timeout in ms; absolute value is
taken
* -nonewline: indicate that the concatenation of multiple replies
(see -all option) should be without additional newlines.
Specifying this option in the absence of "-all" does not
have any effect.
* -nowait : flags no wait, i.e. first the internal queue is checked,
and if no reply is found a call to msgRecvMsg() is placed
with the appropriate filter and msgNO_WAIT flag
The option -ascii is enabled by default if seq_ccsCmdCheck was set to
"CHECK_CMD" when the command was sent; otherwise the -fbin option is
active. These defaults may be overridden by command line options.
<cmdId>: as returned by seq_msgSendCommand
<errorNumber>: the name of a Tcl variable where to store the error-number
of the error-message structure returned as part of the reply. The
CCS convention is that "0" signals no error. This variable can only
be set after the message was received OK (i.e. one should test first
that the reply-protocol did not fail, then look at <errorNumber>).
When the "errorNumber" variable indicates the reception of an
error message, this error-stack can be displayed with seq_errDisplay
(until the next error comes in).
<lastReply>: the name of a Tcl boolean variable where to store the
"lastReply" flag; will contain "0" if there are more replies, "1" if
this reply is the last. This variable will not be touched untill the
reply(-ies) came in successfully.
Remark that imbedded applications (which call seqInitInterp()) can have
an event-loop out of the sequencer's control, i.e. they can call ccsInit()
instead of eval-ing seq_ccsInit (which would activate the monitoring of
the message queue within the sequencer's event-loop). In these cases,
seq_msgRecvReply will by default issue a blocking msgRecvMsg() call with
infinite timeout, as it cannot count on the sequencer's monitoring of the
message queue.
<errornumber> and <lastReply>: see above
The value of the seq_ccsCmdCheck variable at the time the command was sent
is used to flag the (expected) presence of the CDT of the process the reply
comes from. It influences the default behaviour of seq_msgRecvReply
(-ascii or -fbin).
OK if the reception of the reply caused no errors. In this case the
result string contains either the reply or error message received. An
eventual error will be returned independent of the setting of the -bin
option.
Remark that this OK return does not necessarily mean that the originator
of the reply signalled all is OK - cf the <errorNumber> variable.
ERROR if one of the following conditions is met (with the corresponding
error message here between quotes):
* 'wrong # args: should be "seq_msgRecvReply ?-all? ?-ascii? ?-bin?
?-fbin? ?-last? ?-nnn? ?-nonewline? ?-nowait? <cmdId> <errorNumber>
?<lastReply>? "' if there were not at least two additional arguments
(on top of eventual options)
* 'invalid cmd handle: "<cmdId>"'
* 'bad option: "<optionX>" should be -all, -ascii, -bin, -fbin, -last,
-nowait, -nonewline or a numeric value' if one of the options is wrong
* 'invalid cmd handle "<cmdId>" (no replies pending on it)'
* 'failed to allocate memory to format binary reply' if there seems
to be no memory available for the temporary formatting buffer; this
allocation is done the first time formatting of a reply is attempted.
* 'reply on <cmdId> (command <cmd> to <env>/<proc>) could not be
formatted' if the formatting failed (most likely there is something
wrong with the CDT - check the error stack and CDT).
* 'reply timed out' if no reply came in within the specified timeout
* 'message queue empty' if -nowait was specified and no reply was in
yet
* 'could not receive message' if msgRecvMsg returned an error
* 'could not parse reply'
* 'received reply on "<command>" with wrong commandId (<commandId>)'
when the replier either did not set the orgCommandId properly, or
sends more replies after the lastReply flag was set
* 'no memory available to store replies' if in the handling of incoming
replies a malloc failed
* error message left by Tcl_SetVar when trying to set the variable
<lastReply>; remark that when this error occurs, the reply was
received properly.
The identification of the command that caused a reply depends on the
the commandId parameter sent together with the command. It is therefore
absolutely essential that all applications receiving Sequencer commands via
the CCS message system, return replies that contain the CommandId of the
originating command.
When a reply comes in with the lastReply flag set, the Sequencer shells
will remove all information pertinent to this command after dealing with
this reply. If further replies would come in, they will be properly logged
as errors, and should be interpreted as an indication of a buggy replying
application.
For formatted binary replies, the formatted string of a single reply is
limited to 16 KBytes. There is however no checking for overflow possible
(due to how the CCS procedure cmdFormatReply is implemented), and if the
DISPLAY_FORMAT entry in the corresponding CDT leads to larger formatted
strings, a memory corruption will occur.
To be able to format replies, the CDT must be loaded into cmdManager.
See cmdManager(1) and cmdSetup(1).
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_msgSendCommand wte13 DCS init
cmd145
seqWish>.....
seqWish>seq_msgRecvReply cmd145 errNr lr
CCD#87 having problems, trying again...
seqWish>echo $lr
0
seqWish>seq_msgRecvReply cmd145 errNr lr
CCD#87 initialization failed
seqWish>echo $lr
1
seqWish>echo $errNr
15
seqWish>seq_msgSendCommand wte13 DCS init
cmd187
seqWish>seq_msgRecvReply cmd187 errNr lr -last
CCD#87 initialized OK
seqWish>echo $lr
1
seqWish>echo $errNr
0
seqWish>........
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqMsgRecvReply(3), seq_msgSendCommand(n), msgRecvMsg(3), msgParseMsg(3)
-noreply : flag that this command is of an event type, i.e. there will be
no replies to be sent back
-check : flag to request command and parameter checking for this
particular command, overriding the global setting of the
seq_ccsCmdCheck Tcl-variable (see below).
-nocheck : flag to turn off command and parameter checking for this
particular command, overriding the global setting of the
seq_ccsCmdCheck Tcl-variable (see below).
<envName> : name of the environment where the command has to be sent to
<procName>: name of the recipient process
<command> : name of the command to send to the environment/process
<args> : the arguments to pass along with <command> as the message body.
This can spread multiple words, and the Sequencer will concatenate
them into a single message body (string), separating neighbouring
arguments by a single space (similar to Tcl's join command). Remark
however that in this case the Tcl parser and the Sequencer need to do
some work on <args> which can be avoided: it is more efficient to have
<args> grouped as a single word, e.g. between quotes, or, if there are
no substitutions required, between curly braces.
The joining of the <args> happens of course after applying the standard
Tcl substitution- and grouping-rules. When arguments containing
quotes are involved, unexperienced Tcl users will often consider this
an odd behaviour. Again, this situation can be avoided by grouping
<args> into a single Tcl-word (see EXAMPLES section).
In the absence of -noreply, and when send_msgSendCommand is successful, it
returns the next available command handle. This handle points to a.o. the
msgCMDID parameter sent to the destination. The latter msgCMDID is derived
from the handle name (it is the numeric part of it), and it can be used to
construct a filter for receiving replies on this command. It is therefore
imperative that the recipients of such messages return the original command
identifier in the reply.
If -noreply is given, the command will be sent with a msgCMDID of value 0,
and the return will be empty, as there are supposed to be no replies coming
back. This option is useful in an environment where some well-known
process(es) need(s) to be informed of an event, while it is considered too
expensive to create/access a database branch just for this purpose. This
option is functionally equivalent to sending a normal command and then
receiving and discarding replies (e.g. via the seq_evtAttach mechanism),
but it is of course a lot more efficient.
If the recipient process is a Sequencer shell, the <command> needs to be
EVENT instead of SCRIPT, as this disables the return of replies by the
recipient.
The checking of commands is in the absence of the -cmdCheck and -noCheck
options done according to the value of the global Tcl-variable
seq_ccsCmdCheck.
seq_ccsCmdCheck is a global Tcl_variable whose value determines whether the
CCS message system will perform command checking based on the CDTs. It
must be set to either NO_CHECK or CHECK_CMD. The default is NO_CHECK.
Its application can be overridden by the options -check and -nocheck. See
also the description of the argument flag in the manpage of
msgSendCommand(3).
OK if no errors occurred. In this case the result string is either empty
if -noreply was specified, or otherwise contains the next available
command handle, as mentioned above.
ERROR if one of the following conditions is met (with the corresponding
error message here in bold-face):
* wrong # args: should be "seq_msgSendCommand ?-noreply? ?-check?
?-nocheck? <envName> <procName> <command> ?<args>?" if
seq_msgSendCommand is not given with at least 3 additional arguments
* wrong option: "-xyz" should be "-noreply", "-check" or "-nocheck" if
an unknown option -xyz was specified
* could not send command "<command> <args>" to <envName>/<procName>
if msgSendCommand(3) returned an error
<command> will be converted to UPPERCASE, as required by CCS! As a
consequence, the Sequencer shells cannot deal with command-synonyms
containing lowercase characters.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish># The trivial case: 3 parameters without quotes and spaces
seqWish>seq_msgSendCommand -check wte13 ICS TEST {par1 2 par3}
cmd14
seqWish># The same result, easy to grasp, but some more arbeit for seqWish
seqWish>seq_msgSendCommand -check wte13 ICS TEST par1 2 par3
cmd15
seqWish># The easy way to pass a parameter including quotes
seqWish>seq_msgSendCommand wte13 ICS TEST {1 2 "3rd parameter with quotes"}
cmd16
seqWish># The same result, but novices may have to think a bit about this
seqWish>seq_msgSendCommand wte13 ICS TEST 1 2 {"3rd parameter with quotes"}
cmd17
seqWish># Here the third parameter is a string which does not include
seqWish># quotes; as it contains spaces, the whole is after concatenation
seqWish># with the first two arguments equivalent to a string with 6
seqWish># individual parameters
seqWish>seq_msgSendCommand wte13 ICS TEST 1 2 "3rd 4th 5th 6th"
cmd18
seqWish>........
Tcl and the Tk toolkit, John K. Ousterhout, ISBN 0-201-6337-X
seqMsgSendCommand(3), seq_msgRecvReply(n), msgSendCommand(3),
seq_msgSendReply allows to send intermediate replies to the originator of
the SCRIPT command (see seq_msgDispatch(n)). As such, the only place where
it can appear is within the script received with this SCRIPT command, or
within a procedure called by this script.
-current: a flag indicating that the scriptId of the current SCRIPT command
should be used instead of an explicitly specified <scriptId>. This
provides an alternative to the %S substitution (see below).
In case various SCRIPTS commands are nested (possible if a script
being evaluated includes e.g. an "update" command), the handle
used is always the one of the current context.
<scriptId>: script-command handle as substituted for a %S by seq_msgDispatch
at the time it received the SCRIPT command; this handle allows
to identify the process which originated the SCRIPT command.
<errorNr>: number of the error; 0 means no error
<lastReply>: a Tcl boolean variable, to flag if this is the last reply.
Its default value is 0. If <errorNr> is not 0, the value
specified for <lastReply> is irrelevant, i.e. an error-reply
is by definition the last reply.
<reply>: string containing reply; if <errorNr> is 0, this will be in the
message buffer at the receiving side; otherwise, this string
will be in the ccsERROR structure passed across (which means
this is then also the last reply).
If <reply> is of a size which does not fit into a single reply,
seq_msgSendReply will automatically chop up this string into
multiple fragments, send each fragment (in the right order) as
a reply, whereby only the last fragment will have the
'lastReply' flag set, provided <lastReply> is true. It is up
to receiver of these replies to re-assemble them by
concatenating these individual pieces.
OK if no errors occurred. In this case the result string is empty,
except if the -current option was given; in the latter case, the
<scriptId> is returned.
ERROR if one of the following conditions is met (with the corresponding
error message here between quotes):
* 'wrong # args: should be "seq_msgSendReply -current|<scriptId>
<errorNr> ?<lastReply>? <reply>"' if seq_msgSendReply is not given with
the right amount of arguments
* 'not evaluating a SCRIPT command' when the command was used with the
-current option, while not evaluating a script that came with a SCRIPT
command.
* 'no replies to be sent for <scriptId>' when the <scriptId> handle does
not or no longer exist (e.g. the last reply was sent before).
* 'could not send reply "<reply>" to <envName>/<procName>' if
msgSendReply returned an error
* 'could not send reply "<reply>", nor get procName from msgPROCESSID' if
msgSendReply returned an error, and also ccsGetProcName failed.
The <errorNr> (if set) will be in the top of the error stack structure wich
is sent as a reply, and can be retrieved as such by the receiving side.
This means that the generic error mnemonic seqERR_CMD_SCRIPT used for these
cases does not correspond to a fixed error number - its number gets
overwritten with <errorNr>.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
....
seqWish>seq_msgSendReply script0 0 "I am still doing OK"
seqWish>........
seqWish>seq_msgSendReply script0 5 "I have found an error: $msg"
seqWish>........
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
seqMsgDispatch(n), seq_msgRecvReply(n), msgSendReply(3),
seq_oslxCmd will invoke oslxSHELL::CmdParser, with the following
arguments:
<command> : name of a command supported by oslxServer
<parameter> : parameter-name going with this command (see the CDT of
oslxServer).
<instanceId>: instance Id of the command; must be unique. Remark that not
all commands require this parameter
<arguments> : additional arguments of this <command> to be passed to
oslsServer; how many of these arguments there are, depends
on the specific <command>.
OK return if no errors occurred. Also, the reply-buffer of this <command>
will be returned in the result string.
ERROR return if one of the following conditions is met (with corresponding
error message here between quotes):
- 'wrong # args : should be "seq_oslxCmd <command> <parameter>
?<instanceId>? ?<arguments>?"': the corresponding Sequencer command
was given with too few arguments;
- 'could not parse "<command> <parameter> ..." (oslxERR_...)' if oslx
returned an error (the error message from oslx is included);
Remark that although the generic command syntax rules allows several
parameters and their corresponding values to be combined in a single
command, oslxServer does not do so. So <parameter> is a *single*
parameter of <command>.
Some of the oslxServer commands affect environment variables. In order
to keep the Tcl-array "env" aligned with the process' environment, it
is therefore imperative that the seq_oslxCmd command is given within a
shell which takes care of this aspect, like seqSh or seqWish.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>
seqWish>.....
When all 4 arguments of this command are specified, seq_redirect
will redirect <fileId> to <fileName>. This disk file is monitored each
<checkPeriod> seconds and whenever its size exceeds <maxSize> bytes only
the last part (10% of <maxSize>) will be kept.
If only the first argument is given, this logging to a file for <fileId>
is stopped.
This command is particularly useful to redirect e.g. stderr to a log-file,
as debugging info is always written to stderr (see seq_debug array)
returns OK, with an empty result string if all is OK.
returns ERROR with corresponding message in the result string if a file
access error occurred, or if attempting to stop redirection for a fileId
which is not being redirected.
(For clarity's sake, the example is for an interactive session with
input typed by the user coming after the "seqWish>" prompt, and all
replies on a new line)
.....
seqWish>seq_redirect stderr /tmp/myLogFile 3600 1000000
seqWish>
.....
seqWish>seq_redirect stderr
seqWish>
seq_relToAbsPath, seq_findFile, seq_waitTillActive, seq_waitTillDead,
seq_isoTime, seq_fitsDate, seq_timeOfDay, seq_isoTimeToClock -
a collection of Sequencer procedures
seq_relToAbsPath <pathName>
seq_findFile <relPath>
seq_waitTillActive <env> <proc> <timeout> \
?<period> ?<runstring> ?<preferExec>???
seq_waitTillDead <env> <proc> <timeout> ?<period>? ?<exitCmd>?
seq_isoTime
seq_fitsDate
seq_timeOfDay
seq_isoTimeString2Clock <timeString>
seq_relToAbsPath will return the absolute pathname corresponding to a
relative <pathName>; works for files as well as directories
seq_findFile will return the absolute path of <relPath>, after looking
for it in the following order:
1. the current working directory, i.e. ./<relPath>
2. ../<relPath>
3. $INTROOT/<relPath>
4. $VLTROOT/<relPath>
If <relPath> is not found, an error is returned ('<relPath> not found')
seq_waitTillActive will wait untill a certain process is active, i.e. until
it can receive CCS messages; this is tested by sending periodically PING
commands with the CCS message system
<env> : environment where the process will run
<proc> : name under which the process will register itself with CCS
<timeout>: how long to wait (in ms) before the seq_waitTillActive
returns an error
<period> : period (in ms) for sending PING commands; default: 100 ms.
This determines the resolution of <timeout>
<runstring>: If not empty, seq_waitTillActive will first of all schedule
the process in the environment <env>. If this <env> is the
local environment, "exec" can be used for this scheduling -
see <preferExec> - thereby setting stdout of this new process
the same as the script's stdout; otherwise, the msgSchedule(1)
utility is used (and there will be no stdout messages). In
both cases, the <runstring> is passed to the scheduling
utility.
<preferExec>: a boolean variable; if set to 1 and <env> is the local
environment, use exec(n) for the scheduling instead of
msgSchedule(1) (see above). Default: use msgSchedule(1).
There are no errors logged for the failed attempts to send a PING
command, nor for the failing of seq_waitTillActive itself.
If the scheduling is done with exec(n), the Unix process-id will be
returned if successful.
seq_waitTillDead will wait untill a certain process is inactive, i.e. until
it no longer responds to CCS PING messages
<env> : environment where the process is running
<proc> : name under which the process is registered with CCS
<timeout>: how long to wait (in ms) before the seq_waitTillDead
returns an error; remark that this timer starts *after* the
reply to <exitCmd> came in.
<period> : period (in ms) for sending PING commands; default: 100 ms.
This determins the resolution of <timeout>
<exitCmd>: If not empty, seq_waitTilDeadlActive will first of all send
the command <exitCmd> to <proc>, using seq_msgSendCommand,
before starting to test if it is still active. If this
parameter is given, seq_waitTillDead wait for a reply on this
command and wait for an additional 2 seconds before polling
with the PING command.
If the <exitCmd> argument is not given, the script calling this command
should make sure (e.g. using a delay) that the process had a reasonable
chance to terminate, before calling seq_waitTillDead. Otherwise the PING
commands may still get on the queue of the terminating process while it
is exiting and therefore it would not reply. Although seq_waitTillDead
would finally timeout after <timeout> ms, and consider the process for
that reason dead, this "delay" in coming to that conclusion could
surprise the user.
There are no errors logged for the failed attempt to send a PING command,
nor for the failing of seq_waitTillDead itself. If seq_waitTillDead
cannot communicate with <env>/<proc>, it is assumed that the process
is dead already (or that <env> is no longer active), and a OK-return
will be taken.
seq_isoTime will return the current UTC time in ISO 8601 format (i.e. in the
format 'yyyy-mm-ddThh:mm:ss').
seq_fitsDate will return the current UTC date in the format 'yyyy-mm-dd'
seq_timeOfDay will return the current UTC time-of-the-day in the format
'hh:mm:ss'.
seq_isoTimeToClock will convert the UTC time <timeString> (ISO-format) to
the internal clock value (integer, timezone adjusted) corresponding to
this UTC time. This is useful if one wants to make elapsed time
calculations starting from ISO-format time-strings, or to convert an
ISO <timeString> to another non-ISO format (e.g. "clock format
[seq_isoTimeToClock <timeString>]" will return the time in the format
as the standard Unix "date" command).
as any Tcl procedure; OK returns are always empty, except for
seq_waitTillActive when "exec" is used; in this case, the Unix process-id
of the scheduled process is returned.
In case of an error, the following self-explanatory error messages can be
returned:
seq_findFile:
'<relPath> not found in standard search path''
seq_waitTillActive:
'process <proc> (env <env>) not active after <timeout> ms'
seq_waitTillDead:
'process <proc> (env <env>) still active after <timeout> ms'
If seq_waitTillDead cannot communicate with <env>/<proc>, it is assumed
that the process is dead already, and a OK-return will be made. This
behaviour is desired in most cases. Beware however that this OK-return
will also occur when e.g. <env> has a wrong value.
On top of that, timeouts for replies on accepted PING commands (both for
seq_waitTillActive and seq_waitTillDead) result in the automatic deletion
of the corresponding command-handle.
All time-related procedures require that the TimeZone is set to the proper
value, as time-values are converted to/from UTC based on this TZ info.
OK, with a result string containing all what scanConfig(1) sent to stdout,
if it terminated OK (exit(0)).
ERROR with corresponding message in the result string if scanCOnfig(1)
terminated abnormally (exit(1)).
seqCon is a script which will invoke tkcon, and "customize" it to the
seqWish style.
The script will however return without action if the seqWish runstring
includes -noTkCon, or if this is a non-interactive shell.
The argv array is checked for the presence of the switch "-noTkCon",
in which case tkcon will not start up.
"Tcl and the Tk toolkit", John K. Ousterhout, ISBN 0-201-6337-X
tkcon documentation (http://www.cs.uoregon.edu/research/tcl/script/tkcon/)
5 PUBLIC INTERFACE FILE
#ifndef SEQ_H
#define SEQ_H
/*******************************************************************************
* E.S.O. - VLT project
#
# "@(#) $Id: seq.h,v 2.69 2002/02/15 14:04:41 vltsccm Exp $"
*
* seq.h
*
* who when what
* -------- -------- ----------------------------------------------
* eallaert 30/03/94 created
* eallaert 28/07/95 differentiation of seqLONGNAME according to use of CCS
* eallaert 11/10/95 fixed various problems for compilation without CCS
* eallaert 03/05/96 Seq_Init name compatible with "load" in Tcl 7.5
*/
/************************************************************************
* This is the public interface file for the Sequencer extensions to Tcl/Tk
*
* Remark that if you use it, the following compilation flags should be set:
* - CCS_FULL if the compilation is with full CCS
* - CCS_LIGHT if the compilation is with CCS-light
* - neither of the above if the compilation is without CCS
*
*----------------------------------------------------------------------
*/
/*
* Other header files
*/
#if defined(CCS_FULL) || defined(CCS_LIGHT)
#include "seqErrors.h" /* error interface file */
#else
#include "seqErrorsNoCcs.h" /* error interface file */
#endif
#include <tclExtend.h> /* interface file for Tcl/TclX */
#if defined(CCS_FULL) || defined(CCS_LIGHT)
#include <ccs.h> /* declares the vlt* and ccs* datatypes */
#endif /* CCS_FULL || CCS_LIGHT */
/*
* Definition of constants
*/
#define seqVERSION "$Revision: 2.69 $" /* string containing revision code */
/* "tclAppVersion" points to digits only */
/* "infox appversion" returns digits only */
#define seqNAME "sequencer" /* default name stored in tclAppName */
/* string returned by the command "infox applongname" for all CCS-cases
* (this string is pointed to by tclAppLongName)
*/
#if defined(CCS_FULL)
#define seqLONGNAME "The VLT Sequencer with full CCS"
#define seqCCSTYPE "full"
#elif defined(CCS_LIGHT)
#define seqLONGNAME "The VLT Sequencer with CCS-light"
#define seqCCSTYPE "light"
#else
#define seqLONGNAME "The VLT Sequencer without CCS"
#define seqCCSTYPE "none"
#endif
#define tclPRECISION "tcl_precision" /* Tcl-var linked to seqPrecision */
#define seqMODULEID "seq_moduleId" /* Tcl-var linked to seqModuleId */
#define seqERRLOGGING "seq_errLogging" /* Tcl-var linked to seqErrLogging */
#define seqERRREPLYMERGING "seq_errReplyMerging"/* linked to seqErrReplyMerging */
#define seqCMDCHECK "seq_ccsCmdCheck" /* Tcl-var linked to seqCmdCheck */
#define seqOBISCRIPT "seq_obiScript" /* Tcl-var linked to seqObiScript */
#define seqREPLYTIMEOUT "reply timed out" /* return string value for a */
/* timedout reply */
#define seqDEFAULTID "seq" /* default module Id - cf errAdd() */
/* package name is derived from this */
/* (1st character is upshifted) */
#define seqDEFAULTCHECK "NO_CHECK" /* def check - cf msgSendCommand() */
#define seqCMD_HANDLE_BASE "cmd" /* basis for command handle name */
#define seqEVT_HANDLE_BASE "event" /* basis for event handle name */
#define seqSCR_HANDLE_BASE "script" /* basis for script handle name */
#define seqLIST_HANDLE_BASE "list" /* basis for db-list handle name */
#define seqALRM_HANDLE_BASE "alarm" /* basis for alarm handle name */
/*
* Global variables- see also seqInit.c, seqMsgDispatch
*/
extern unsigned int seqPrecision; /* C-variable linked to tclPRECISION */
/* type must correspond to int */
extern char *seqModuleId; /* C-variable linked to seqMODULEID */
/* see a.o. errAdd(); max 6 chars!!! */
extern int seqErrLogMethod; /* C-var reflecting seqERRLOGGING */
/* 0=off, 1=auto, 2=manual */
extern int seqErrReplyMergeMethod; /* C-var corr. to seqERRREPLYMERGING */
/* 0=off, 1=internal, 2=local */
extern char *numericVersion; /* string containing version */
#if defined(CCS_FULL) || defined(CCS_LIGHT)
extern ccsERROR lastError; /* CCS error at last errCloseStack */
extern char *seqObiScript; /* C-var linked 2 string seqOBISCRIPT */
/* cf obituaries in seqMsgDispatch */
extern ccsENVNAME myEnvName; /* local environment name */
extern ccsPROCNUM myProcNum; /* Sequencer process number */
extern ccsPROCNAME myProcName; /* the CCS name of this process */
extern vltLOGICAL cmdsAllowed; /* reflects whether Sequencer event */
/* loop will allow incoming cmds */
#endif /* CCS_FULL || CCS_LIGHT */
/*
* Data types
*/
/*
* Function prototypes
*/
int Seq_Init ( /* Sequencer interpreter initialization */
Tcl_Interp *interp /* pointer to interpreter structure */
); /* (called by Tcl_AppInit & seqInitInterp) */
#if defined(CCS_FULL) || defined(CCS_LIGHT)
EXTERN ccsCOMPL_STAT seqInitInterp( /* creates/initializes a Sequencer interp */
char *display, /* string with display-term name */
char *name, /* label for main window */
vltLOGICAL interactive, /* flags if application is shell-like */
Tcl_Interp **interp, /* Tcl interpreter structure pointer-pointer */
ccsERROR *error);
EXTERN ccsCOMPL_STAT seqEval ( /* Sequencer interface to Tcl_Eval */
Tcl_Interp *interp, /* Tcl interpreter pointer */
char *script, /* string with script */
ccsERROR *error); /* error structure pointer */
EXTERN ccsCOMPL_STAT seqMonitorQ ( /* enables/disables monitoring of msg queue */
Tcl_Interp *interp, /* result string goes to interp->result */
vltLOGICAL stateflag, /* ccsTRUE => enable; ccsFALSE => disable */
ccsERROR *error); /* returned error structure */
#endif /* CCS_FULL || CCS_LIGHT */
EXTERN ccsCOMPL_STAT saveAndCloseStack (/* does a errCloseStack after saving */
ccsERROR *error); /* this error structure in global lastError */
#endif /*!SEQ_H*/
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|