[BACK]Return to freem.texi CVS log [TXT] [DIR] Up to [Coherent Logic Development] / freem / doc

Diff for /freem/doc/freem.texi between versions 1.45 and 1.56

version 1.45, 2025/05/05 12:34:02 version 1.56, 2025/05/16 13:22:58
Line 4 Line 4
 @settitle The FreeM Manual  @settitle The FreeM Manual
   
 @copying  @copying
 This manual is for FreeM, (version 0.64.0-rc1), which is a free software implementation of the M programming language.  This manual is for FreeM, (version 0.65.1-rc0), which is a free software implementation of the M programming language.
   
 Print-optimized versions of this book are typeset in @emph{Computer Modern} by the author using the @emph{GNU Texinfo} tools.  Print-optimized versions of this book are typeset in @emph{Computer Modern} by the author using the @emph{GNU Texinfo} tools.
   
Line 19  Permission is granted to copy, distribut Line 19  Permission is granted to copy, distribut
   
 @title The FreeM Manual  @title The FreeM Manual
 @subtitle @sc{The Official Manual of FreeM}  @subtitle @sc{The Official Manual of FreeM}
 @subtitle Version 0.64.0-rc1  @subtitle Version 0.65.1-rc0
 @c@vskip 10pt  @c@vskip 10pt
 @c@center @image{freem-logo-sm,,,,.png}  @c@center @image{freem-logo-sm,,,,.png}
 @author Serena Willis  @author Serena Willis
Line 100  This is the official manual for the Free Line 100  This is the official manual for the Free
 * Accessing FreeM from C Programs::     How to use the mlib interface.  * Accessing FreeM from C Programs::     How to use the mlib interface.
   
 * FreeM Administrator::                 The fmadm system manager tool.  * FreeM Administrator::                 The fmadm system manager tool.
 * FreeM Legacy Utilities::              FreeM legacy system manager utilities.  
 * FreeM VIEW Commands and Functions::   Getting and setting info about FreeM internals.  * FreeM VIEW Commands and Functions::   Getting and setting info about FreeM internals.
 * Implementation Limits::               FreeM limitations.  * Implementation Limits::               FreeM limitations.
 * US-ASCII Character Set::              The US-ASCII character set.  * US-ASCII Character Set::              The US-ASCII character set.
Line 149  Current contributors denoted with a @emp Line 148  Current contributors denoted with a @emp
 @cindex contributors, Gerum, Winfried  @cindex contributors, Gerum, Winfried
 @cindex contributors, Kreis, Greg  @cindex contributors, Kreis, Greg
 @cindex contributors, Landis, Larry  @cindex contributors, Landis, Larry
   @cindex contributors, McGlothlen, Ken
 @cindex contributors, Milligan, Lloyd  @cindex contributors, Milligan, Lloyd
 @cindex contributors, Morris, Steve  @cindex contributors, Morris, Steve
 @cindex contributors, Murray, John  @cindex contributors, Murray, John
Line 190  Larry Landis (Coordination, Code, Docume Line 190  Larry Landis (Coordination, Code, Docume
 Rick Marshall (Testing, MDC Conformance) @emph{+}  Rick Marshall (Testing, MDC Conformance) @emph{+}
   
 @item  @item
   Ken McGlothlen (Apple Silicon build/test environment, proofreading of documentation) @emph{+}
   
   @item
 Lloyd Milligan (Code, Testing, Documentation)  Lloyd Milligan (Code, Testing, Documentation)
   
 @item  @item
Line 271  Refers to an M intrinsic special variabl Line 274  Refers to an M intrinsic special variabl
 Indicates a @emph{list} of the following item, e.g., @emph{L gvn} means @emph{list of global variable names}.  Indicates a @emph{list} of the following item, e.g., @emph{L gvn} means @emph{list of global variable names}.
 @item @emph{lvn}  @item @emph{lvn}
 Refers to the name of an M local variable.  Refers to the name of an M local variable.
   @item @emph{postcondition}
   A @emph{tvexpr} immediately following a command verb affecting that command's execution.
 @item @emph{strlit}  @item @emph{strlit}
 Refers to an M string literal.  Refers to an M string literal.
 @item @emph{ssvn}  @item @emph{ssvn}
 Refers to the name of an M structured system variable.  Refers to the name of an M structured system variable.
 @item @emph{tvexpr}  @item @emph{tvexpr}
 Refers to a truth-valued expression.  Refers to a truth-valued expression, i.e., an expression interpreted as a truth value.
 @end table  @end table
   
 @node A Note on Standards  @node A Note on Standards
Line 439  Attempting to start a FreeM interpreter Line 444  Attempting to start a FreeM interpreter
 The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{<entryref>}} or @option{--routine=@emph{<entryref>}}:  The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{<entryref>}} or @option{--routine=@emph{<entryref>}}:
   
 @example  @example
 Coherent Logic Development FreeM version 0.64.0-rc1 (x86_64-pc-linux-gnu)  Coherent Logic Development FreeM version 0.65.1-rc0 (x86_64-pc-linux-gnu)
 Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC  Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC
   
   
Line 1113  See @emph{https://wiki.osdev.org/Target_ Line 1118  See @emph{https://wiki.osdev.org/Target_
 * $ZLSD()::                             Compute Levenshtein distance between two arguments.  * $ZLSD()::                             Compute Levenshtein distance between two arguments.
 * $ZM()::                               Unknown.  * $ZM()::                               Unknown.
 * $ZNAME()::                            Unknown.  * $ZNAME()::                            Unknown.
 * $ZNEXT()::                            Unknown.  * $ZNEXT()::                            Return glvn of next numeric subscript following given glvn.
 * $ZORDER()::                           Unknown.  * $ZORDER()::                           Unknown.
 * $ZPIECE()::                           Unknown.  * $ZPIECE()::                           Unknown.
 * $ZPREVIOUS()::                        Unknown.  * $ZPREVIOUS()::                        Unknown.
Line 1311  The optional second argument indicates t Line 1316  The optional second argument indicates t
 @cindex intrinsic functions, $NEXT  @cindex intrinsic functions, $NEXT
   
 Deprecated. Use @code{$ORDER} instead.  Deprecated. Use @code{$ORDER} instead.
   Returns the next numeric subscript of the specified glvn.
   
   @emph{Syntax}
   
   @example
   $NEXT(@emph{glvn})
   @end example
   
   @emph{Example}
   
   Assume the following array:
   
   @example
   ^foo(1)=""
   ^foo(2)=""
   @end example
   
   And the following code:
   
   @example
    W $ZNEXT(^foo(1)) ; => 2
   @end example 
   
 @node $ORDER()  @node $ORDER()
 @section $ORDER  @section $ORDER
Line 1711  Returns the Levenshtein distance between Line 1738  Returns the Levenshtein distance between
 @cindex intrinsic functions, $ZM  @cindex intrinsic functions, $ZM
 @cindex intrinsic functions, implementation-specific  @cindex intrinsic functions, implementation-specific
   
   Purpose unknown.
   
 @node $ZNAME()  @node $ZNAME()
 @section $ZNAME  @section $ZNAME
 @cindex $ZNAME  @cindex $ZNAME
Line 1719  Returns the Levenshtein distance between Line 1748  Returns the Levenshtein distance between
   
 Purpose unknown.  Purpose unknown.
   
   This function relies on the value of @code{$VIEW(71)} being @code{0} (this is not the default).
   
 @node $ZNEXT()  @node $ZNEXT()
 @section $ZNEXT  @section $ZNEXT
 @cindex $ZNEXT  @cindex $ZNEXT
 @cindex intrinsic functions, $ZNEXT  @cindex intrinsic functions, $ZNEXT
 @cindex intrinsic functions, implementation-specific  @cindex intrinsic functions, implementation-specific
   
 Purpose unknown.  Returns a fully-formed variable reference of the next numeric subscript of the specified glvn.
   
   @emph{Syntax}
   
   @example
   $ZNEXT(@emph{glvn})
   @end example
   
   @emph{Example}
   
   Assume the following array:
   
   @example
   ^foo(1)=""
   ^foo(2)=""
   @end example
   
   And the following code:
   
   @example
    W $ZNEXT(^foo(1)) ; => ^foo(2)
   @end example
   
   This function relies on the value of @code{$VIEW(71)} being @code{1} (this is the default).
   
 @node $ZORDER()  @node $ZORDER()
 @section $ZORDER  @section $ZORDER
Line 2011  Identical to @ref{$TRANSLATE()}, except Line 2065  Identical to @ref{$TRANSLATE()}, except
 * !::                                   Run an external program or command.  * !::                                   Run an external program or command.
 * !!::                                  Launch a subshell from FreeM direct mode.  * !!::                                  Launch a subshell from FreeM direct mode.
 * ABLOCK::                              Increment the block counter for one or more event classes.  * ABLOCK::                              Increment the block counter for one or more event classes.
 * ASSERT::                              Raise error when a conditional expression evaluates @emph{false}.  
 * ASTART::                              Enable asynchronous event handling for one or more event classes.  * ASTART::                              Enable asynchronous event handling for one or more event classes.
 * ASTOP::                               Disable asynchronous event handling for one or more event classes.  * ASTOP::                               Disable asynchronous event handling for one or more event classes.
 * AUNBLOCK::                            Decrement the block counter for one or more event classes.  * AUNBLOCK::                            Decrement the block counter for one or more event classes.
Line 2043  Identical to @ref{$TRANSLATE()}, except Line 2096  Identical to @ref{$TRANSLATE()}, except
 * VIEW::                                Modify FreeM internal parameters.  * VIEW::                                Modify FreeM internal parameters.
 * WRITE::                               Write output to current input/output device.  * WRITE::                               Write output to current input/output device.
 * XECUTE::                              Interpret string as M code.  * XECUTE::                              Interpret string as M code.
 * ZBREAK::                              Unknown.  * ZASSERT::                             Raise error when a conditional expression evaluates @emph{false}.
   * ZBREAK::                              Enable/disable ZBREAK mode.
 * ZCONST::                              Define a constant that cannot be altered after initial definition.  * ZCONST::                              Define a constant that cannot be altered after initial definition.
 * ZGO::                                 Unknown.  * ZGOTO::                               @code{GOTO} with @code{BREAK} control.
 * ZHALT::                               Unknown.  * ZHALT::                               Exit FreeM job with return value.
 * ZINSERT::                             Insert code into routine buffer.  * ZINSERT::                             Insert code into routine buffer.
 * ZJOB::                                Invokes a job, ignoring any timeouts.  * ZJOB::                                Invoke job, ignoring any timeouts.
 * ZLOAD::                               Load routine into routine buffer.  * ZLOAD::                               Load routine into routine buffer.
 * ZMAP::                                Map a global name to a non-default namespace.  * ZMAP::                                Map a global name to a non-default namespace.
 * ZNEW::                                Unknown.  * ZNEW::                                Unknown.
 * ZPRINT::                              Print contents of routine buffer.  * ZPRINT::                              Print contents of routine buffer.
 * ZQUIT::                               Quits multiple stack levels at once.  * ZQUIT::                               Quit multiple stack levels at once.
 * ZREMOVE::                             Remove code from routine buffer.  * ZREMOVE::                             Remove code from routine buffer.
 * ZSAVE::                               Save routine buffer to disk.  * ZSAVE::                               Save routine buffer to disk.
 * ZTHROW::                              Programmatically raise an error condition.  * ZTHROW::                              Programmatically raise an error condition.
 * ZTRAP::                               Unknown.  * ZTRAP::                               Raise a FreeM error.
 * ZUNMAP::                              Remove a mapping of a global to a non-default namespace.  * ZUNMAP::                              Remove a mapping of a global to a non-default namespace.
 * ZWATCH::                              Enable or disable watchpoints, or set or clear watchpoints on specified globals, locals, or structured system variables.  * ZWATCH::                              Enable or disable watchpoints, or set or clear watchpoints on specified globals, locals, or structured system variables.
 * ZWITH::                               Set prefix for future variable references.  * ZWITH::                               Set prefix for future variable references.
Line 2182  In its inclusive form, @code{ABLOCK} inc Line 2236  In its inclusive form, @code{ABLOCK} inc
   
 In its exclusive form, @code{ABLOCK} increments the block counters for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted.  In its exclusive form, @code{ABLOCK} increments the block counters for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted.
   
 @node ASSERT  
 @section ASSERT  
 @cindex ASSERT  
 @cindex commands, ASSERT  
 @cindex commands, debugging  
 @cindex commands, implementation-specific  
 @cindex commands, non-standard  
 @emph{FreeM Extension}  
   
 Triggers error @code{ASSERT} if the supplied truth-valued expression @emph{tvexpr} is @emph{false} (@emph{1} is @emph{true}, and @emph{0} is @emph{false}), and that the optional @emph{postcondition} evaluates to @emph{true} or is omitted.  
   
 The @code{ASSERT} error is catchable whether using standard-style, FreeM-style, or DSM 2.0-style error processing.  
   
 @emph{Syntax}  
   
 @example  
  ASSERT@emph{:postcondition} @emph{<tvexpr>}  
 @end example  
   
 @emph{Example}  
   
 @example  
 DEFAULT.USER> SET DEBUG=1  
   
   
 DEFAULT.USER> ASSERT:DEBUG 1=1  
   
   
 DEFAULT.USER> ASSERT:DEBUG 1=0  
    
    
 >> Error ZASSERT:  programmer assertion failed in SYSTEM::^%SYSINIT  [$STACK = 0]  
 >> ASSERT:DEBUG 1=0  
                    ^  
 @end example  
   
 @node ASTART  @node ASTART
 @section ASTART  @section ASTART
Line 2633  In the above @emph{inclusive} form, @cod Line 2652  In the above @emph{inclusive} form, @cod
 @cartouche  @cartouche
 @quotation  @quotation
 @emph{Note}  @emph{Note}
 The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release.  The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.65.1-rc0, but are planned for a future release.
 @end quotation  @end quotation
 @end cartouche  @end cartouche
   
Line 2668  In the above @emph{inclusive} form, @cod Line 2687  In the above @emph{inclusive} form, @cod
 @cartouche  @cartouche
 @quotation  @quotation
 @emph{Note}  @emph{Note}
 The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release.  The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.65.1-rc0, but are planned for a future release.
 @end quotation  @end quotation
 @end cartouche  @end cartouche
   
Line 3353  VIEW 133:@emph{tvexpr} Line 3372  VIEW 133:@emph{tvexpr}
 @cindex XECUTE  @cindex XECUTE
 @cindex commands, XECUTE  @cindex commands, XECUTE
   
   @node ZASSERT
   @section ZASSERT
   @cindex ZASSERT
   @cindex commands, ZASSERT
   @cindex commands, debugging
   @cindex commands, implementation-specific
   @cindex commands, non-standard
   @emph{FreeM Extension}
   
   Triggers error @code{ZASSERT} if the supplied truth-valued expression @emph{tvexpr} is @emph{false} (@emph{1} is @emph{true}, and @emph{0} is @emph{false}), and that the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
   
   The @code{ZASSERT} error is catchable whether using standard-style, FreeM-style, or DSM 2.0-style error processing.
   
   @emph{Syntax}
   
   @example
    ZASSERT@emph{:postcondition} @emph{<tvexpr>}
   @end example
   
   @emph{Example}
   
   @example
   DEFAULT.USER> SET DEBUG=1
   
   
   DEFAULT.USER> ZASSERT:DEBUG 1=1
   
   
   DEFAULT.USER> ZASSERT:DEBUG 1=0
    
    
   >> Error ZASSERT:  programmer assertion failed in SYSTEM::^%SYSINIT  [$STACK = 0]
   >> ZASSERT:DEBUG 1=0
                      ^
   @end example
   
 @node ZBREAK  @node ZBREAK
 @section ZBREAK  @section ZBREAK
 @cindex ZBREAK  @cindex ZBREAK
Line 3362  VIEW 133:@emph{tvexpr} Line 3417  VIEW 133:@emph{tvexpr}
 @cindex commands, non-standard  @cindex commands, non-standard
 @emph{FreeM Extension}  @emph{FreeM Extension}
   
   Sets or clears the @code{ZBREAK} flag@footnote{NOTE: FreeM team needs to investigate how @code{zbreakon} and @code{zbflag} affect program execution.}, based on the result of evaluating @emph{tvexpr}.
   
   @emph{Syntax}
   
   @example
   ZBREAK @emph{tvexpr}
   @end example
   
 @node ZCONST  @node ZCONST
 @section ZCONST  @section ZCONST
 @cindex ZCONST  @cindex ZCONST
Line 3379  Constants must only be locals, and globa Line 3442  Constants must only be locals, and globa
 @code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}}  @code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}}
 @end example  @end example
   
 @node ZGO  @node ZGOTO
 @section ZGO  @section ZGOTO
 @cindex ZGO  @cindex ZGOTO
 @cindex commands, ZGO  @cindex commands, ZGOTO
 @cindex commands, implementation-specific  @cindex commands, implementation-specific
 @cindex commands, non-standard  @cindex commands, non-standard
 @emph{FreeM Extension}  @emph{FreeM Extension}
   
   In its argumented form, enables @code{BREAK} mode and branches unconditionally to @emph{entryref}.
   
   @emph{Syntax}
   
   @example
   ZGOTO @emph{entryref}
   @end example
   
   In its argumented form, resumes execution after a @code{BREAK}.
   
   @emph{Syntax}
   
   @example
   ZGOTO
   @end example
   
 @node ZHALT  @node ZHALT
 @section ZHALT  @section ZHALT
 @cindex ZHALT  @cindex ZHALT
Line 3395  Constants must only be locals, and globa Line 3474  Constants must only be locals, and globa
 @cindex commands, non-standard  @cindex commands, non-standard
 @emph{FreeM Extension}  @emph{FreeM Extension}
   
   In its single-argumented form, @code{ZHALT} command is used to exit the FreeM process with a specific return value @emph{intexpr}.
   
   @emph{Syntax}
   
   @example
   ZHALT @emph{intexpr}
   @end example
   
   In its argumentless form, @code{ZHALT} is synonymous with @code{HALT}.
   
   @emph{Syntax}
   
   @example
   ZHALT
   @end example
   
 @node ZINSERT  @node ZINSERT
 @section ZINSERT  @section ZINSERT
 @cindex ZINSERT  @cindex ZINSERT
Line 3536  Raises an error condition as long as the Line 3631  Raises an error condition as long as the
 @cindex commands, non-standard  @cindex commands, non-standard
 @emph{FreeM Extension}  @emph{FreeM Extension}
   
   Synonymous with @ref{ZTHROW}.
   
 @node ZUNMAP  @node ZUNMAP
 @section ZUNMAP  @section ZUNMAP
 @cindex ZUNMAP  @cindex ZUNMAP
Line 5681  Raised when you attempt to use multiple Line 5778  Raised when you attempt to use multiple
 Raised when attempts are made to set @code{$ECODE} to an invalid error code value. Obsolete and replaced by standard error code @code{M101}.  Raised when attempts are made to set @code{$ECODE} to an invalid error code value. Obsolete and replaced by standard error code @code{M101}.
   
 @item @code{ZASSERT} - @emph{programmer assertion failed}  @item @code{ZASSERT} - @emph{programmer assertion failed}
 Raised when an @code{ASSERT} expression's result is not true.  Raised when an @code{ZASSERT} expression's result is not true.
   
 @item @code{ZUSERERR} - @emph{user-defined error}  @item @code{ZUSERERR} - @emph{user-defined error}
 Raised when program code calls @code{THROW} with an error code argument for which the first character is @code{U}, or when @code{$ECODE} is set to an error code for which the first character is @code{U}.  Raised when program code calls @code{THROW} with an error code argument for which the first character is @code{U}, or when @code{$ECODE} is set to an error code for which the first character is @code{U}.
Line 6397  int main(int argc, char **argv, char **e Line 6494  int main(int argc, char **argv, char **e
 @cindex fmadm  @cindex fmadm
   
 The @code{fmadm} utility is the preferred method of managing a FreeM installation, and will eventually replace all of the existing utilities.  The @code{fmadm} utility is the preferred method of managing a FreeM installation, and will eventually replace all of the existing utilities.
 Unlike the existing, legacy utilities, @code{fmadm} presents a consistent, simple interface for all FreeM management tasks, and is namespace-aware.  In support of FreeM operators, @code{fmadm} presents a consistent, simple interface for all FreeM management tasks, and is namespace-aware.
 This appendix will document each @code{fmadm} facility as it is implemented, until all of the legacy utilities have been replaced.  This appendix will document each @code{fmadm} facility as it is implemented.
   
 The @code{fmadm} utility's functions all follow the below, consistent syntax:  The @code{fmadm} utility's functions all follow the below, consistent syntax:
   
Line 6492  Supported actions are @code{list} and @c Line 6589  Supported actions are @code{list} and @c
 @end table  @end table
   
   
 @node FreeM Legacy Utilities  
 @appendix FreeM Legacy Utilities  
 @cindex utilities, legacy  
   
 @section Global Compactor (gcompact)  
 @cindex utilities, legacy, gcompact  
   
 Compacts the specified global in place.  
   
 @emph{Syntax}  
   
 @example  
 gcompact @emph{/path/to/global/file}  
 @end example  
   
 @section Block Examiner (gfix)  
 @cindex utilities, gfix  
   
 The @emph{gfix} interactive utility program permits navigation of the B-tree structure of the specified global a block at a time.  
   
 @emph{Syntax}  
   
 @example  
 gfix @emph{</path/to/global/file>}  
 @end example  
   
 @section Global Repair Tool (grestore)  
 @cindex utilities, legacy, grestore  
   
 This utility will fix problems with the specified global.  
   
 @emph{Syntax}  
   
 @example  
 grestore @emph{</path/to/global/file>}  
 @end example  
   
 @node FreeM VIEW Commands and Functions  @node FreeM VIEW Commands and Functions
 @appendix FreeM VIEW Commands and Functions  @appendix FreeM VIEW Commands and Functions
   
Removed from v.1.45  
changed lines
  Added in v.1.56

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>