From 7f40d4d4e9dbe8b7be9ee0582738d33fe1ff9859 Mon Sep 17 00:00:00 2001
From: "benjamin.franksen" <benjamin.franksen@helmholtz-berlin.de>
Date: Mon, 15 Jul 2013 12:20:43 +0000
Subject: [PATCH] docs: distinguish program parameters from CPP macros
Program parameters are now consistently referred to as such. The term
"macro" is used only for C preprocessor macros. Wordings were adapted
accordingly and some related improvements made.
---
documentation/Reference.txt | 63 ++++++++++++++++++++-----------------
documentation/Using.txt | 10 ++++--
2 files changed, 42 insertions(+), 31 deletions(-)
diff --git a/documentation/Reference.txt b/documentation/Reference.txt
index 40710b88..f6a3b5d4 100644
--- a/documentation/Reference.txt
+++ b/documentation/Reference.txt
@@ -103,8 +103,8 @@ This is the overall structure of an SNL program. After the keyword
parameter, global definitions, an optional entry block, the state sets, an
optional exit block, and finally some embedded C code.
-Program Name and Parameter
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Program Name and Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
The program name is an identifier. It is used as the name of the global
variable which contains or points to all the program data structures
@@ -119,7 +119,7 @@ time parameters`).
The program name may be followed by an optional string enclosed in
parentheses. The string content must be a list of comma-separated
-parameters in the same form as they are specified on the command line (see
+parameters in the same form as if specified on the command line (see
:ref:`run time parameters`).
.. note:: Command-line parameters override those specified in the program.
@@ -214,8 +214,7 @@ Variable declarations are quite similar to C.
.. versionadded:: 2.1
-You can now
-declare more than one variable in a single declaration (comma
+You can declare more than one variable in a single declaration (comma
separated) and add pointer and array markers (subscripts)
ad libitum as well as initializers.
@@ -323,8 +322,8 @@ Foreign Entities
~~~~~~~~~~~~~~~~
The pseudo type ``foreign`` is used to declare any number of C variables
-or struct tags or *cpp* macros that have been defined outside the SNL
-program. No warning will be issued if such a variable, struct tag, or
+or C preprocessor macros that have been defined outside the SNL
+program. No warning will be issued if such a variable or
macro is used in the program even if warnings are enabled.
You cannot declare arrays of or pointers to foreign entities.
@@ -432,11 +431,17 @@ are numeric types (char, short, int, long, and their unsigned variants)
and strings (these are sometimes referred to as *scalar types*), as well
as one or two dimensional arrays of these.
-The process variable name may contain macro names enclosed in
-braces, as in ``"{sys}{sub}voltage"``. Macros are named following
-the same rules as C language variables. Macros are defined via
-command line argument, or program parameter (see `Program Name and
-Parameter`_). If the process variable name is an empty string, then no
+Process variable names are subject to *parameter expansion*: substrings
+of the form ::
+
+ {parametername}
+
+(i.e. an identifier enclosed in curly braces) are expanded to the value of
+the program parameter *if* a corresponding parameter is defined (either
+inside the program or as extra argument on invocation); otherwise no
+expansion takes place.
+
+If the process variable name (after expansion) is an empty string, then no
actual assignment to any process variable is performed, but the variable
is marked for potential (dynamic) assignment with :c:func:`pvAssign`.
@@ -465,14 +470,15 @@ Pointer types may not be assigned to process variables.
.. versionadded:: 2.1
-The keyword "connect" is synonymous
-with "assign". It is offered as an alternative because the traditional
+You can use the keyword "connect" as a synonym
+for "assign". It is offered as an alternative because the traditional
term "assign" is too easily confused with the assignment
statement (``var = expression;``), even though these notions have
nothing in common. However, for compatibility and the
fact that most SNL programmers are used to it, I have refrained from
making any disruptive change here. Thus, the documentation still talks
-about "assigned variables", the "assign clause" etc.
+about "assigned variables", the "assign clause" etc. This might change
+in a future (major) release.
monitor
@@ -1346,6 +1352,8 @@ it causes assignment to an anonymous PV.
As usual, ``assigned_var`` can also be an array element.
+See also :token:`assign` clause.
+
Note that pvAsssign is *asynchronous*: it sends a request to search for and
connect to the given ``process_variable_name``, but it does not wait for a
response, similar to ``pvGet(var,ASYNC)``. Calling pvAssign *does* have one
@@ -1668,11 +1676,10 @@ macValueGet
^^^^^^^^^^^
.. c:function::
- char* macValueGet(char *macro_name)
+ char* macValueGet(char *parameter_name)
-Returns a pointer to a string that is the value for
-the specified macro name. If the macro does not exist, it returns
-``NULL``.
+Returns a pointer to the value of the specified program parameter, if
+it exists, else ``NULL``. See `Program Name and Parameters`_.
Shell Commands
@@ -1691,14 +1698,14 @@ 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)
+ void seq(seqProgram *program, const char *paramdefs, 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`.
+Start the given program with the given set of parameter definitions and
+stack size. If ```stacksize`` is zero or is omitted, then use a default
+(EPICS "small" stack). If ``paramdefs`` is zero or the last two arguments
+are omitted, then no parameters are defined. Otherwise ``paramdefs`` should
+be a string that specifies program parameters as detailed in :ref:`run time
+parameters`. See also :token:`program_param`.
.. c:function::
void seqShow()
@@ -2035,7 +2042,7 @@ by adding a line ::
This uses the one-line-escape syntax explained in the next section.
For historical reasons, *snc* complains with a warning if you use a
-foreign variable (or structure tag, or macro) in SNL code (but not for
+foreign variable or preprocessor macro in SNL code (but not for foreign
function calls). This can be suppressed by adding a foreign
declaration (see `Foreign Entities`_).
@@ -2063,7 +2070,7 @@ escape methods:
Note that text appearing on the same line after ``%{`` and
before ``}%`` also belongs to the literal code block.
-A variable (or struct tag or macro) declared in escaped C code is
+A variable or preprocessor macro declared in escaped C code is
foreign to the SNL, just as if it were declared in C code extern to
the SNL program and its use will give a warning if no foreign
declaration preceeds it.
diff --git a/documentation/Using.txt b/documentation/Using.txt
index 0f621a6f..3505e352 100644
--- a/documentation/Using.txt
+++ b/documentation/Using.txt
@@ -174,9 +174,8 @@ Specifying Run-Time Parameters
You can specify run-time parameters to the sequencer. Parameters
serve three purposes:
-
#. macro substitution in process variable names,
-#. for use by your program, and
+#. providing arguments to your program, and
#. as special parameters to the sequencer.
You can pass parameters to your program at run time by
@@ -189,10 +188,15 @@ list (see :ref:`StateProgram`). Parameters
specified on the command-line override those specified in the
``program`` statement.
+Parameter values are available inside the program via the built-in
+procedure :c:func:`macValueGet`. They are also (automatically)
+available for parameter expansion when specifying PV names in
+:token:`assign` clauses and the built-in procedure :c:func:`pvAssign`.
+
VxWorks
^^^^^^^
-For example, if we wish to specify the value of the macro "unit" in
+For example, if we wish to specify the value of the "unit" parameter in
the example in the last chapter, we would execute the program with
the following command::
--
GitLab