Commit 2a57dcc8 authored by John P. Willis's avatar John P. Willis
Browse files

Commands ABLOCK through WITH now documented. Remove final vestiges of old VIEW 22 aliases.

parent ddf3d46b
Pipeline #697 passed with stage
in 2 minutes and 11 seconds
......@@ -728,3 +728,8 @@ VERSION 0.47.1
VERSION 0.47.2
Fix data corruption in $ZHOROLOG
********************************************************************************
VERSION 0.48.0
Commands ABLOCK through WITH now documented. Remove final vestiges of old VIEW 22 aliases.
......@@ -37,7 +37,7 @@
#
#
AC_INIT([freem],[0.47.2],[jpw@coherent-logic.com])
AC_INIT([freem],[0.48.0],[jpw@coherent-logic.com])
AC_CONFIG_HEADERS([src/config.h])
AC_CONFIG_MACRO_DIRS([m4])
......
......@@ -4,7 +4,7 @@
@settitle The FreeM Manual
@copying
This manual is for FreeM, (version 0.47.2), which is a free and open-source implementation of the M programming language and database system.
This manual is for FreeM, (version 0.48.0), which is a free and open-source implementation of the M programming language and database system.
Copyright @copyright{} 2014-2021 Coherent Logic Development LLC
......@@ -18,7 +18,7 @@ Permission is granted to copy, distribute and/or modify this document under the
@title The FreeM Manual
@subtitle @sc{The Official Manual of FreeM}
@subtitle Version 0.47.2
@subtitle Version 0.48.0
@c@vskip 10pt
@c@center @image{freem-logo-sm,,,,.png}
@author John P. Willis
......@@ -280,7 +280,7 @@ $ chmod +x @emph{myscript.m}
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
Coherent Logic Development FreeM version 0.47.2 (x86_64-pc-linux-gnu)
Coherent Logic Development FreeM version 0.48.0 (x86_64-pc-linux-gnu)
Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC
......@@ -1696,7 +1696,7 @@ In the above @emph{inclusive} form, @code{KVALUE} will kill the data values at e
@cartouche
@quotation
@emph{Note}
The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.47.2, 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.48.0, but are planned for a future release.
@end quotation
@end cartouche
......@@ -1866,22 +1866,117 @@ If you do not specify the address family and connection type, they will default
@cindex QUIT
@cindex commands, QUIT
@code{QUIT} will end execution of the current process level, optionally returning @emph{expr}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@code{QUIT} with @emph{expr} when an argument is not expected will raise error @code{M16}; @code{QUIT} without @emph{expr} when an argument is expected will raise error @code{M17}.
Argumentless @code{QUIT} may also be used to exit a @code{FOR} loop occurring on the same line.
@emph{Syntax}
@example
QUIT[@emph{:postcondition}] [@emph{expr}]
@end example
@section READ
@cindex READ
@cindex commands, READ
The @code{READ} command takes input from I/O channel @code{$IO} and stores it into specified variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
READ[@emph{:postcondition}] @emph{read-argument}[,...@emph{read-argument}]
@end example
Each @emph{read-argument} may be one of the following:
@table @asis
@item String Literal
String literal @emph{read-argument}s will be output to @code{$IO} unmodified.
@item Format Specifier
One or more of the following:
@table @asis
@item @code{!} (newline)
Advances the cursor down by one line and returns it to the first column.
@item @code{#} (form-feed)
Advances the screen down by @code{$ZROWS} and moves the cursor to the upper-left corner of the screen.
@item @code{?@emph{n}} (position)
Advances the cursor and @code{$X} forward to position @emph{n}.
@end table
@item Single-Character Read (@code{*@emph{variable-name}[@emph{:timeout}]})
Reads one character into variable @emph{variable-name}. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve one character. If a character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}.
@item Variable-Length Character Read (@code{@emph{variable-name}[@emph{:timeout}]})
Reads characters into @emph{variable-name} until the character or character pair in @code{^$DEVICE(@emph{io-channel},"OPTIONS","TERMINATOR")} is encountered. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve characters. If characters are read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}.
@item Fixed-Length Character Read (@code{@emph{variable-name}#@emph{count}[@emph{:timeout}]})
Reads @emph{count} characters into @emph{variable-name}. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve characters. If characters are read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}.
@item Control Mnemonic (@code{/@emph{control-mnemonic}[@emph{(arg1[,...argN])}]})
Outputs X3.64 control mnemonic @emph{control-mnemonic} to @code{$IO}. Please see the appendix on X3.64 Control Mnemonics for more information.
@end table
@section SET
@cindex SET
@cindex commands, SET
The @code{SET} command places values into one or more variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
SET[@emph{:postcondition}] @emph{set-argument}[=@emph{expression} | @emph{postfix-operator}][@emph{,...set-argument}[=@emph{expression} | @emph{postfix-operator}]]
@end example
Each @emph{set-argument} can be:
@table @asis
@item @emph{variable-name}
A local variable, global variable, writable intrinsic special variable, or writable structured system variable.
@item @emph{lhs-function}
@code{$EXTRACT} or @code{$PIECE}.
@end table
If any grouping of @emph{set-argument}s is surrounded by parentheses, all @emph{set-argument}s in the parenthesized group will be set to the result of @emph{expression}.
If @emph{postfix-operator} is used instead of @code{=@emph{expression}}, the results of applying @emph{postfix-operator} to the @emph{set-argument} will be stored in @emph{set-argument}. @emph{postfix-operator} may not be used following a parenthesized group of @emph{set-argument}s.
@emph{Example (postfix-operator)}
@example
SET A++,B-- ; increments A, decrements B
@end example
@section TCOMMIT
@cindex TCOMMIT
@cindex commands, TCOMMIT
Commits all pending transactions to the database, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
TCOMMIT[@emph{:postcondition}]
@end example
@section THEN
@cindex THEN
@cindex commands, THEN
Saves the value of @code{$TEST} until the end of the current line, restoring it at the end of the current line or when a @code{QUIT} is encountered. @code{THEN} should be used in all new code in conjunction with @code{IF}.
@emph{Example}
@example
IF 1 THEN WRITE "HELLO!",!
@end example
@section THROW
@cindex THROW
@cindex commands, THROW
......@@ -1907,14 +2002,40 @@ Raises an error condition as long as the optional @emph{postcondition} is @emph{
@cindex commands, TRESTART
@cindex commands, unimplemented
FreeM does not yet support restartable transactions.
@section TROLLBACK
@cindex TROLLBACK
@cindex commands, TROLLBACK
Rolls back all pending transactions for the current process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
TROLLBACK[@emph{:postcondition}]
@end example
@section TSTART
@cindex TSTART
@cindex commands, TSTART
Introduces a new transaction level, incrementing @code{$TLEVEL}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Any database operations encountered when @code{$TLEVEL} is greater than zero will not be committed to the database until @code{TCOMMIT} is encountered.
@emph{Syntax}
@example
TSTART[@emph{:postcondition}]
@end example
@cartouche
@quotation
@emph{Non-Standard Syntax}
FreeM's current @code{TSTART} does not accept any arguments.
@end quotation
@end cartouche
@section USE
@cindex USE
@cindex commands, USE
......@@ -1961,6 +2082,309 @@ For network sockets, @emph{io-channel} must be in the range 100-255.
@cindex VIEW
@cindex commands, VIEW
Provides write access to various FreeM internal parameters, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
VIEW[@emph{:postcondition}] @emph{view-number}[:@emph{view-argument}[:@emph{view-argument}...]]
@end example
The @emph{view-number} argument can be one of the following:
@table @asis
@item @code{21} - Close All Globals
Closes all global database files open in the current process. Takes no arguments.
@emph{Syntax}
@example
VIEW 21
@end example
@item @code{29} - Symbol Table Copy
Copies the primary symbol table's contents to the alternate symbol table. Takes no arguments.
@emph{Syntax}
@example
VIEW 29
@end example
@item @code{52} - Set G0 Input Translation Table for @code{$IO}
@emph{Syntax}
@example
VIEW 52:@emph{expr V trantab}
@end example
@item @code{53} - Set G0 Output Translation Table for @code{$IO}
@emph{Syntax}
@example
VIEW 53:@emph{expr V trantab}
@end example
@item @code{54} - Set G1 Input Translation Table for @code{$IO}
@emph{Syntax}
@example
VIEW 54:@emph{expr V trantab}
@end example
@item @code{55} - Set G1 Output Translation Table for @code{$IO}
@emph{Syntax}
@example
VIEW 55:@emph{expr V trantab}
@end example
@item @code{62} - Set @code{$RANDOM} Seed Number
Sets the seed number used by @code{$RANDOM} to @emph{numexpr}.
@emph{Syntax}
@example
VIEW 62:@emph{numexpr}
@end example
@item @code{63} - Set @code{$RANDOM} Parameter A
Sets the number used for @code{$RANDOM} Parameter A to @emph{numexpr}.
@emph{Syntax}
@example
VIEW 63:@emph{numexpr}
@end example
@item @code{64} - Set @code{$RANDOM} Parameter B
Sets the number used for @code{$RANDOM} Parameter B to @emph{numexpr}.
@emph{Syntax}
@example
VIEW 64:@emph{numexpr}
@end example
@item @code{65} - Set @code{$RANDOM} Parameter C
Sets the number used for @code{$RANDOM} Parameter C to @emph{numexpr}.
@emph{Syntax}
@example
VIEW 65:@emph{numexpr}
@end example
@item @code{66} - Set or Clear @code{SIGTERM} Handling Flag
Enables or disables handling of @code{SIGTERM} UNIX signals. If @emph{tvexpr} evaluates to 1 (@emph{true}), @code{SIGTERM} handling will be enabled. Otherwise, @code{SIGTERM} handling will be disabled.
@emph {Syntax}
@example
VIEW 66:@emph{tvexpr}
@end example
@item @code{67} - Set or Clear @code{SIGHUP} Handling Flag
Enables or disables handling of @code{SIGHUP} UNIX signals. If @emph{tvexpr} evaluates to 1 (@emph{true}), @code{SIGHUP} handling will be enabled. Otherwise, @code{SIGHUP} handling will be disabled.
@emph{Syntax}
@example
VIEW 67:@emph{tvexpr}
@end example
@item @code{70} - Set @code{$ZSORT}/@code{$ZSYNTAX} Flag
Selects whether @code{$ZS} resolves to @code{$ZSORT} or @code{$ZSYNTAX}.
If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZSYNTAX}. Otherwise, selects @code{$ZSORT}.
@emph{Syntax}
@example
VIEW 70:@emph{tvexpr}
@end example
@item @code{71} - Set @code{$ZNEXT}/@code{$ZNAME} Flag
Selects whether @code{$ZN} resolves to @code{$ZNEXT} or @code{$ZNAME}.
If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZNAME}. Otherwise, selects @code{$ZNEXT}.
@emph{Syntax}
@example
VIEW 71:@emph{tvexpr}
@end example
@item @code{72} - Set @code{$ZPREVIOUS}/@code{$ZPIECE} Flag
Selects whether @code{$ZP} resolves to @code{$ZPREVIOUS} or @code{$ZPIECE}.
If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZPIECE}. Otherwise, selects @code{$ZPREVIOUS}.
@emph{Syntax}
@example
VIEW 72:@emph{tvexpr}
@end example
@item @code{73} - Set @code{$ZDATA}/@code{$ZDATE} Flag
Selects whether @code{$ZD} resolves to @code{$ZDATA} or @code{$ZDATE}.
If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZDATE}. Otherwise, selects @code{$ZDATA}.
@emph{Syntax}
@example
VIEW 73:@emph{tvexpr}
@end example
@item @code{79} - Set Old @code{ZJOB} vs. New @code{ZJOB} Flag
If @emph{tvexpr} evaluates to @emph{true}, sets the @code{ZJOB} mode to new, otherwise, sets it to old.
@emph{Syntax}
@example
VIEW 79:@emph{tvexpr}
@end example
@item @code{80} - Set or Clear 8-Bit Flag
If @emph{tvexpr} evaluates to @emph{true}, sets FreeM to 8-bit mode. Otherwise, sets FreeM to 7-bit mode.
@emph{Syntax}
@example
VIEW 80:@emph{tvexpr}
@end example
@item @code{81} - Set or Clear PF1 Flag
If @emph{tvexpr} evaluates to @emph{true}, sets the @code{PF1} flag. We do not yet know what this does.
@emph{Syntax}
@example
VIEW 81:@emph{tvexpr}
@end example
@item @code{83} - Set or Clear Text in @code{$ZERROR} Flag
If @emph{tvexpr} evaluates to @emph{true}, descriptive error messages will be included in @code{$ZERROR}. Otherwise, only the short error code (i.e. @emph{ZILLFUN}) will be included in @code{$ZERROR}.
@emph{Syntax}
@example
VIEW 83:@emph{tvexpr}
@end example
@item @code{87} - Date Type Definition
We believe this defines date formats for @code{$ZDATE}, but we have not yet figured out how it works.
@emph{Syntax}
@example
; Syntax unknown
@end example
@item @code{88} - Time Type Definition
We believe this defines time formats for @code{$ZTIME}, but we have not yet figured out how it works.
@emph{Syntax}
@example
; Syntax unknown
@end example
@item @code{89} - Set Default Expression for Undefined Local Variable
Sets the default expression to be printed when an undefined local variable is encountered. We're not entirely sure what this does.
@emph{Syntax}
@example
; Syntax unknown
@end example
@item @code{90} - Set Default Expression for Undefined Global Variable
Sets the default expression to be printed when an undefined global variable is encountered. We're not entirely sure what this does.
@emph{Syntax}
@example
; Syntax unknown
@end example
@item @code{91} - Set Default Expression for Missing @code{QUIT} Expression
Sets the default expression to be printed when a @code{QUIT} is encountered where a @code{QUIT} argument would be expected, but was not provided. We're not entirely sure what this does.
@emph{Syntax}
@example
; Syntax unknown
@end example
@item @code{92} - Set Type Mismatch Error Flag on @code{EUR2DEM}
If @emph{tvexpr} evaluates to @emph{true}, a type mismatch error will be thrown in @code{EUR2DEM} currency conversions in certain situations that we do not yet understand.
@emph{Syntax}
@example
VIEW 92:@emph{tvexpr}
@end example
@item @code{93} - Define @code{ZKEY} Production Rule
We do not know what this does.
@item @code{96} - Set Global Prefix
Forces global database filenames to be prefixed with the result of @emph{expr}.
@emph{Syntax}
@example
VIEW 96:@emph{expr V string}
@end example
@item @code{97} - Set Global Postfix
Forces global database filenames to be postfixed with the result of @emph{expr}.
@emph{Syntax}
@example
VIEW 97:@emph{expr V string}
@end example
@item @code{98} - Set Routine Extension
Sets the default extension for M routine filenames to the result of @emph{expr}.
@emph{Syntax}
@example
VIEW 98:@emph{expr V string}
@end example
@item @code{101} - Set @code{ierr}
Sets the FreeM internal @code{ierr} value to @emph{intexpr}. Used by some FreeM polyfills (commands or functions implemented in M code).
@emph{Syntax}
@example
VIEW 101:@emph{intexpr}
@end example
@item @code{102} - Set @code{ierr} (Deferred)
Sets the FreeM internal @code{ierr} value to @emph{intexpr}, but only after the current process stack level is exited. Used by FreeM polyfills to throw an error that will appear to come from the user's own code rather than the polyfill implementation M code.
@emph{Syntax}
@example
VIEW 102:@emph{intexpr}
@end example
@item @code{103} - Signal @code{MERGE} to @code{^$WINDOW} Complete
Signals FreeM's MWAPI implementation that a @code{MERGE} to @code{^$WINDOW} or descendant subscripts thereof has completed.
@emph{Syntax}
@example
VIEW 103[@emph{:subscript}]
@end example
@item @code{110} - Set Local @code{$ORDER}/@code{$QUERY} Data Value
Sets the local variable @code{$ORDER}/@code{$QUERY} data value to the result of @emph{expr}. We're not entirely sure what this is.
@emph{Syntax}
@example
VIEW 110:@emph{expr}
@end example
@item @code{111} - Set Global @code{$ORDER}/@code{$QUERY} Data Value
Sets the global variable @code{$ORDER}/@code{$QUERY} data value to the result of @emph{expr}. We're not entirely sure what this is.
@emph{Syntax}
@example
VIEW 111:@emph{expr}
@end example
@item @code{113} - Set @code{termio} Information
We don't know what this does.
@item @code{133} - Remember @code{ZLOAD} Directory on @code{ZSAVE}
We don't know what this does, but it takes a @emph{tvexpr}.
@emph{Syntax}
@example
VIEW 133:@emph{tvexpr}
@end example
@end table
@section WATCH
@cindex WATCH
@cindex commands, WATCH
......@@ -1977,7 +2401,7 @@ Sets a watchpoint on a global, local, or SSV node.
In its @emph{argumentless} form, @code{WATCH} toggles watchpoints on and off, provided the optional @emph{postcondition} is @emph{true} or omitted.
@example
WATCH@emph{:postcondition}
WATCH[@emph{:postcondition}]
@end example
In its @emph{inclusive} form, @code{WATCH} adds, removes, or examines watchpoints, provided the optional @emph{postcondition} is @emph{true} or omitted.
......@@ -1989,7 +2413,7 @@ A @code{-} removes an existing watchpoint for the following variable.
A @code{?} examines the status of a watchpoint for the following variable.
@example
WATCH@emph{:postcondition} [+|-|?]@emph{var1}...,[+|-|?]@emph{varN}
WATCH[@emph{:postcondition}] [+|-|?]@emph{var1}...,[+|-|?]@emph{varN}
@end example
......
......@@ -727,17 +727,6 @@ void view_com ()
return;
/* VIEW 22: clear all v22_aliases */
case 22:
if (v22size) free (v22ali);
v22ptr = 0L;
v22size = 0L;
return;
/* VIEW 29: symtab copy */
case 29: /* get space if needed */
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment