From 959b3a46ffd1f888aaf861b2f17198494cc72788 Mon Sep 17 00:00:00 2001
From: "benjamin.franksen" <benjamin.franksen@helmholtz-berlin.de>
Date: Thu, 24 May 2012 11:06:44 +0000
Subject: [PATCH] docs: added a section about shell commands to the reference
---
documentation/Reference.txt | 201 ++++++++++++++++++++++++++++++++++++
1 file changed, 201 insertions(+)
diff --git a/documentation/Reference.txt b/documentation/Reference.txt
index 54a989b2..359cc888 100644
--- a/documentation/Reference.txt
+++ b/documentation/Reference.txt
@@ -1633,6 +1633,207 @@ the specified macro name. If the macro does not exist, it returns
``NULL``.
+Shell Commands
+--------------
+
+These are commands to be issued from the IOC shell or VxWorks shell.
+They can also be called from C (and therefore SNL) code.
+
+Some of these routines behave slightly different depending on whether
+run under iocsh or a VxWorks shell. This mostly concerns the
+``threadID`` argument: under iocsh, this can in fact be a *thread
+name* instead of a thread ID. Note, however, that this is
+unreliable if you have more than one instance of the same program
+running, since the thread names are identical for all instances. The
+VxWorks shell version directly takes an epicsThreadID argument and
+thus does not recognize thread names.
+
+.. c:function::
+ void seq(seqProgram *program, const char *macros, unsigned stacksize)
+
+Start the given program with the given set of macro expansions and
+stack size. If stacksize is zero or is omitted, then use a default
+(EPICS "small" stack). If macros is zero or the last two arguments are
+omitted, the no macros are defined. Otherwise macros should be a string
+that gives program parameters as specified in :ref:`run time parameters`.
+See also :token:`program_param`.
+
+.. c:function::
+ void seqShow()
+ void seqShow(epicsThreadId threadID)
+
+The first form shows a table of all programs, program instances, and
+state sets, e.g. ::
+
+ epics> seqShow
+ Program Name Thread ID Thread Name SS Name
+ ------------ --------- ----------- -------
+ demo 0x807e628 demo light
+ 0x809fbc8 demo_1 ramp
+ 0x809fcd8 demo_2 limit
+ ------------ --------- ----------- -------
+ demo 0x807fd98 demo light
+ 0xb7100470 demo_1 ramp
+ 0xb7100580 demo_2 limit
+ ------------ --------- ----------- -------
+ demo 0x80814e0 demo light
+ 0x809fe68 demo_1 ramp
+ 0x809ff78 demo_2 limit
+
+Note that in this example we have three running instances of a single
+program named 'demo', each of which consists of three state sets
+running in its own thread.
+
+The second form displays the internal state of a running program
+instance. The threadID parameter must be one of the program's state
+set thread IDs as listed in the above table.
+
+For instance, for the above example we might get ::
+
+ epics> seqShow 0x807e628
+ State Program: "demo"
+ thread priority = 50
+ number of state sets = 3
+ number of syncQ queues = 0
+ number of channels = 6
+ number of channels assigned = 6
+ number of channels connected = 6
+ number of channels monitored = 5
+ options: async=0, debug=0, newef=1, reent=1, conn=1, main=0
+ user variables: address = 0x807d158, length = 44
+
+ State Set: "light"
+ thread name = demo; Thread id = 0x807e628
+ First state = "START"
+ Current state = "LIGHT_OFF"
+ Previous state = "START"
+ Elapsed time since state was entered = 3.0 seconds
+ Get in progress = [000000]
+ Put in progress = [000000]
+ Queued time delays:
+
+ State Set: "ramp"
+ thread name = demo_1; Thread id = 0x809fbc8
+ First state = "START"
+ Current state = "RAMP_UP"
+ Previous state = "RAMP_UP"
+ Elapsed time since state was entered = 0.1 seconds
+ Get in progress = [000000]
+ Put in progress = [000000]
+ Queued time delays:
+ delay[0]=0.100000
+
+ State Set: "limit"
+ thread name = demo_2; Thread id = 0x809fcd8
+ First state = "START"
+ Current state = "START"
+ Previous state = ""
+ Elapsed time since state was entered = 3.0 seconds
+ Get in progress = [000000]
+ Put in progress = [000000]
+ Queued time delays:
+
+.. c:function::
+ void seqChanShow(epicsThreadId threadID)
+ void seqChanShow(epicsThreadId threadID, const char *)
+
+Display channel information for the program instance specified
+by the given threadID. If a second argument is given, it is
+interpreted as part of a channel name. Only channels whose name
+contains the given string as substring are displayed. The name
+can be preceded by a single "-" or "+" sign, signifying that only
+disconnected ("-") or connected ("+") channels should be
+displayed.
+
+The procedure displays one channel at a time, starting with the
+first matching one, and then asks the user
+for input. This input can be
+
+a (signed) integer:
+ increase / decrease current channel number by the given amount,
+ then display the current channel
+
+minus sign ("-"):
+ same as "-1"
+
+plus sign ("+"), empty string (return):
+ same as "+1"
+
+anything else:
+ quit, i.e. back to the shell
+
+If user interaction causes the channel number to leave the range
+(i.e. less than zero, greater or equal to number of channels),
+the command quits, too.
+
+.. c:function::
+ void seqQueueShow(epicsThreadId threadID)
+
+Display information about queued channels. For example ::
+
+ epics> seqShow
+ Program Name Thread ID Thread Name SS Name
+ ------------ --------- ----------- -------
+ syncqTest 0x8053e60 syncqTest get
+ (nil) (no thread) get1
+ (nil) (no thread) put
+ (nil) (no thread) flush
+ epics> seqQueueShow 0x8053e60
+ State Program: "syncqTest"
+ Number of queues = 2
+ Queue #0: numElems=5, used=0, elemSize=136
+ Next? (+/- skip count, q=quit)
+
+ Queue #1: numElems=5, used=0, elemSize=56
+ Next? (+/- skip count, q=quit)
+
+The command is interactive and accepts the same inputs as
+:c:func:`seqChanShow`.
+
+.. c:function::
+ void seqcar(int level)
+
+The name stands for "sequencer channel access report". It displays
+channel connection information. If level <= 1, or no level argument
+is given, only a summary line is displayed, for example ::
+
+ Total programs=3, channels=18, connected=18, disconnected=0
+
+For level > 1, connection information is displayed for all channels
+of all running programs. For instance ::
+
+ epics> seqcar 2
+ Program "demo"
+ Variable "light" connected to PV "demo1:light"
+ Variable "lightOn" connected to PV "demo1:lightOn"
+ Variable "lightOff" connected to PV "demo1:lightOff"
+ Variable "voltage" connected to PV "demo1:voltage"
+ Variable "loLimit" connected to PV "demo1:loLimit"
+ Variable "hiLimit" connected to PV "demo1:hiLimit"
+ Program "demo"
+ Variable "light" connected to PV "demo2:light"
+ Variable "lightOn" connected to PV "demo2:lightOn"
+ Variable "lightOff" connected to PV "demo2:lightOff"
+ Variable "voltage" connected to PV "demo2:voltage"
+ Variable "loLimit" connected to PV "demo2:loLimit"
+ Variable "hiLimit" connected to PV "demo2:hiLimit"
+ Program "demo"
+ Variable "light" connected to PV "demo3:light"
+ Variable "lightOn" connected to PV "demo3:lightOn"
+ Variable "lightOff" connected to PV "demo3:lightOff"
+ Variable "voltage" connected to PV "demo3:voltage"
+ Variable "loLimit" connected to PV "demo3:loLimit"
+ Variable "hiLimit" connected to PV "demo3:hiLimit"
+ Total programs=3, channels=18, connected=18, disconnected=0
+
+.. c:function::
+ void seqStop(epicsThreadId threadID)
+
+Initiate a clean program exit. Running state transitions are
+completed, then all state set threads exit, all channels are
+disconnected, and finally allocated resources are freed.
+
+
.. _safe mode:
Safe Mode
--
GitLab