freem/doc/freem.texi - diff

Return to freem.texi CVS log

Up to [Coherent Logic Development] / freem / doc

Diff for /freem/doc/freem.texi between versions 1.24 and 1.32

version 1.24, 2025/04/10 17:21:54	version 1.32, 2025/04/19 01:10:05
Line 4	Line 4
@settitle The FreeM Manual	@settitle The FreeM Manual

@copying	@copying
This manual is for FreeM, (version 0.64.0-rc0), which is a free and open-source implementation of the M programming language.	This manual is for FreeM, (version 0.64.0-rc1), which is a free and open-source implementation of the M programming language.


Copyright @copyright{} 2014-2025 Coherent Logic Development LLC	Copyright @copyright{} 2014-2025 Coherent Logic Development LLC
Line 18 Permission is granted to copy, distribut	Line 18 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-rc0	@subtitle Version 0.64.0-rc1
@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 73 This is the official manual for the Free	Line 73 This is the official manual for the Free
* Global Aliasing:: Defining alternate names for globals.	* Global Aliasing:: Defining alternate names for globals.
* Global Mappings:: Mapping global names to non-default namespaces.	* Global Mappings:: Mapping global names to non-default namespaces.

* Transaction Processing:: Transactions in FreeM.
* Asynchronous Event Handling:: Handling asynchronous events in FreeM.	* Asynchronous Event Handling:: Handling asynchronous events in FreeM.
* Global Triggers:: Responding to global accesses in M code.	* Global Triggers:: Responding to global accesses in M code.
* Synchronous Event Handling:: Synchronous events in FreeM.	* Synchronous Event Handling:: Synchronous events in FreeM.
Line 110 This is the official manual for the Free	Line 109 This is the official manual for the Free
@node Introduction	@node Introduction
@unnumbered Introduction	@unnumbered Introduction


FreeM started its life as @emph{FreeMUMPS}, written for MS-DOS and ported to SCO UNIX by a mysterious individual going by the name of "Shalom ha-Ashkenaz". It was released to MUG Deutschland in 1998. In 1999, Ronald L. Fox ported FreeM to the Red Hat Linux 5 of the GNU/Linux operating system. Thereafter, maintenance was taken over by the Generic Universal M Project, which changed its name first to Public Standard MUMPS and then by popular request to FreeM.	FreeM started its life as @emph{FreeMUMPS}, written for MS-DOS and ported to SCO UNIX by a mysterious individual going by the name of "Shalom ha-Ashkenaz". It was released to MUG Deutschland in 1998. In 1999, Ronald L. Fox ported FreeM to the Red Hat Linux 5 of the GNU/Linux operating system. Thereafter, maintenance was taken over by the Generic Universal M Project, which changed its name first to Public Standard MUMPS and then by popular request to FreeM.

When GT.M was open-sourced in late 1999, FreeM and GUMP were essentially abandoned. L.D. Landis, the owner of the original GUMP SourceForge project, and one of FreeM's significant contributors, passed maintenance of FreeM and ownership of its SourceForge project to Serena Willis in 2014. At this point, FreeM would not compile or run on modern Linux systems, so steps were taken to remedy the most pressing issues in the codebase. Limitations on the terminal size (previously hard-coded to 80x25) were lifted, and new @code{$VIEW} functions were added to retrieve the terminal size information. @code{$X} and @code{$Y} intrinsic special variables were updated to support arbitrary terminal sizes, and FreeM was once again able to build and run.	When GT.M was open-sourced in late 1999, FreeM and GUMP were essentially abandoned. L.D. Landis, the owner of the original GUMP SourceForge project, and one of FreeM's significant contributors, passed maintenance of FreeM and ownership of its SourceForge project to Serena Willis in 2014. At this point, FreeM would not compile or run on modern Linux systems, so steps were taken to remedy the most pressing issues in the codebase. Limitations on the terminal size (previously hard-coded to 80x25) were lifted, and new @code{$VIEW} functions were added to retrieve the terminal size information. @code{$X} and @code{$Y} intrinsic special variables were updated to support arbitrary terminal sizes, and FreeM was once again able to build and run.
Line 236 Steve Zeck (Code)	Line 234 Steve Zeck (Code)
$ @command{./freem} [@emph{OPTIONS}...] [[-r <entryref>] \| [--routine=<entryref>]]	$ @command{./freem} [@emph{OPTIONS}...] [[-r <entryref>] \| [--routine=<entryref>]]
@end example	@end example

When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{^%SYSINIT} routine, and begins executing it.	When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{%SYSINIT} routine, and begins executing it.

When @code{-r} or @code{--routine} are passed on the command line, FreeM will load and run the specified routine after running @code{^%SYSINIT}. Beginning with FreeM 0.1.7, routines invoked in this manner are no longer required to perform their own namespace setup with @code{VIEW} commands.	When @code{-r} or @code{--routine} are passed on the command line, FreeM will load and run the specified routine after running @code{%SYSINIT}. Beginning with FreeM 0.1.7, routines invoked in this manner are no longer required to perform their own namespace setup with @code{VIEW} commands.

@section %SYSINIT Routine	@section %SYSINIT Routine

The @code{^%SYSINIT} routine runs every time a FreeM interpreter process starts. This routine defines some useful constants, enables handling of @code{TRIGGER} events, and handles the execution of code passed via the @code{-x\--execute} or routines passed via @code{-r\|--routine}.	The @code{%SYSINIT} routine runs every time a FreeM interpreter process starts. This routine defines some useful constants, enables handling of @code{TRIGGER} events, and handles the execution of code passed via the @code{-x\--execute} or routines passed via @code{-r\|--routine}.

Do not modify the supplied @code{^%SYSINIT} routine to add site-specific startup items. Instead, create a @code{^LCLINIT} routine in the @code{USER} namespace of one or more environments. @code{^%SYSINIT} will automatically run @code{^LCLINIT} each time it starts.	Do not modify the supplied @code{%SYSINIT} routine to add site-specific startup items. Instead, create a @code{LCLINIT} routine in the @code{USER} namespace of one or more environments. @code{%SYSINIT} will automatically run @code{LCLINIT} each time it starts.

@section Command-Line Options	@section Command-Line Options
@cindex options, command-line	@cindex options, command-line
Line 279 Allows your M routines to be used as UNI	Line 277 Allows your M routines to be used as UNI
Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/<environment>/freem.conf}.	Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/<environment>/freem.conf}.

@item @option{-r @emph{<entryref>}}, @option{--routine=@emph{<entryref>}}	@item @option{-r @emph{<entryref>}}, @option{--routine=@emph{<entryref>}}
Causes @code{<entryref>} to be executed at load, instead of @code{^%SYSINIT}.	Causes @code{<entryref>} to be executed at load, instead of @code{%SYSINIT}.

@item @option{--standard=@emph{<standard>}}	@item @option{--standard=@emph{<standard>}}
Sets the default FreeM dialect to use for new routine buffers.	Sets the default FreeM dialect to use for new routine buffers.
Line 372 Attempting to start a FreeM interpreter	Line 370 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-rc0 (x86_64-pc-linux-gnu)	Coherent Logic Development FreeM version 0.64.0-rc1 (x86_64-pc-linux-gnu)
Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC	Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC


USER>	USER>
@end example	@end example

The prompt (@code{DEFAULT.USER>}) the current environment and namespace, @code{DEFAULT} and @code{USER}, respsectively. If any uncommitted direct-mode transactions have been started, the prompt will change to reflect the current value of @code{@ref{$TLEVEL}}:	The prompt (@code{DEFAULT.USER>}) displays the current environment and namespace, @code{DEFAULT} and @code{USER}, respsectively. If any uncommitted direct-mode transactions have been started, the prompt will change to reflect the current value of @code{@ref{$TLEVEL}}:

@example	@example
TL1:DEFAULT.USER>	TL1:DEFAULT.USER>
Line 436 Displays a list of @code{LOCK}s held in	Line 434 Displays a list of @code{LOCK}s held in
@item @command{rbuf}	@item @command{rbuf}
Lists the status of all FreeM routine buffers.	Lists the status of all FreeM routine buffers.

@anchor{dbstats}
@item @command{dbstats}
Shows statistics for the BerkeleyDB global handler.

@anchor{wh}	@anchor{wh}
@item @command{wh}	@item @command{wh}
Forces an immediate flush of this process's @code{readline} history buffer to disk.	Forces an immediate flush of this process's @code{readline} history buffer to disk.
Line 475 DEFAULT.USER>	Line 469 DEFAULT.USER>
@end example	@end example

@item @command{!@emph{<external-command>}}	@item @command{!@emph{<external-command>}}
Invokes a shell to run @emph{<external-command>} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ESTART} and @command{ESTOP}.	Invokes a shell to run @emph{<external-command>} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ASTART} and @command{ASTOP}.

If the @command{>} character is supplied immediately preceding @emph{<external-command>}, FreeM will append the contents of an M local or global variable referenced in @code{^$JOB($JOB,"PIPE_GLVN")} to the standard input stream of @emph{<external-command>}.	If the @command{>} character is supplied immediately preceding @emph{<external-command>}, FreeM will append the contents of an M local or global variable referenced in @code{^$JOB($JOB,"PIPE_GLVN")} to the standard input stream of @emph{<external-command>}.

Line 664 Please note that FreeM is not entirely s	Line 658 Please note that FreeM is not entirely s

Returns a comma-delimited list of error conditions currently present, and is writable. An empty @code{$ECODE} indicates no errors.	Returns a comma-delimited list of error conditions currently present, and is writable. An empty @code{$ECODE} indicates no errors.

	Writing a value in the format @code{,<error-code>,} into @code{$ECODE} will raise that error condition.

@node $ESTACK	@node $ESTACK
@section $ESTACK	@section $ESTACK
@cindex $ESTACK	@cindex $ESTACK
Line 1208 The optional second argument indicates t	Line 1204 The optional second argument indicates t
@cindex $NEXT	@cindex $NEXT
@cindex intrinsic functions, $NEXT	@cindex intrinsic functions, $NEXT

	Deprecated. Use @code{$ORDER} instead.

@node $ORDER()	@node $ORDER()
@section $ORDER	@section $ORDER
@cindex $ORDER	@cindex $ORDER
@cindex intrinsic functions, $ORDER	@cindex intrinsic functions, $ORDER

	Returns the previous subscript or next subscript in a local, global, or a subset of structured system variables.

	The first argument is the subscripted local, global, or SSVN.

	The optional second argument can be @code{1} to retrieve the next subscript, or @code{-1} to return the previous.

@node $PIECE()	@node $PIECE()
@section $PIECE	@section $PIECE
@cindex $PIECE	@cindex $PIECE
Line 1235 The optional fourth argument is the fina	Line 1239 The optional fourth argument is the fina
Can be used on the left-hand side of an expression in order to @code{@ref{SET}} a value into a @code{d}-delimited piece of @code{s}, as in:	Can be used on the left-hand side of an expression in order to @code{@ref{SET}} a value into a @code{d}-delimited piece of @code{s}, as in:

@example	@example
; ^jpw="this^is^a^piece"	; ^snw="this^is^a^piece"
SET $PIECE(^jpw,"^",2)="isn't" ; => "this^isn't^a^piece"	SET $PIECE(^snw,"^",2)="isn't" ; => "this^isn't^a^piece"
@end example	@end example

@node $QLENGTH()	@node $QLENGTH()
Line 1268 Returns the number of subscripts in @emp	Line 1272 Returns the number of subscripts in @emp
@code{$QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})}	@code{$QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})}
@end example	@end example

Returns the @emph{n}th subscript of @emph{glvn}.	In the RHS form, returns the @emph{n}th subscript of @emph{glvn}.

@emph{Example}	@emph{Example}

Line 1276 Returns the @emph{n}th subscript of @emp	Line 1280 Returns the @emph{n}th subscript of @emp
@code{SET SUB=$QSUBSCRIPT("^GBL(1,2,3)",2) ; => 2}	@code{SET SUB=$QSUBSCRIPT("^GBL(1,2,3)",2) ; => 2}
@end example	@end example

	@emph{Syntax}

	@example
	@code{SET $QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})=@emph{expr} ; => ^GBL(1,4,3)}
	@end example

	In the LHS form, sets the @emph{n}th subscript of @emph{glvn} to @emph{expr}.

@node $QUERY()	@node $QUERY()
@section $QUERY	@section $QUERY
@cindex $QUERY	@cindex $QUERY
Line 1293 Returns the next subscripted reference i	Line 1305 Returns the next subscripted reference i

We will assume the following data structure exists:	We will assume the following data structure exists:
@example	@example
^jpw(1)=1	^snw(1)=1
^jpw(1,2)="foo"	^snw(1,2)="foo"
^jpw(2)=3	^snw(2)=3
^jpw(3)=""	^snw(3)=""
@end example	@end example

The following code will retrieve the next subscripted name after @code{^jpw(1)}:	The following code will retrieve the next subscripted name after @code{^snw(1)}:

@example	@example
@code{SET NEXTNAM=$QUERY(^jpw(1)) ; => ^jpw(1,2)}	@code{SET NEXTNAM=$QUERY(^snw(1)) ; => ^snw(1,2)}
@end example	@end example

@node $RANDOM()	@node $RANDOM()
Line 1399 Returns a line of code from a routine.	Line 1411 Returns a line of code from a routine.
@cindex $TRANSLATE	@cindex $TRANSLATE
@cindex intrinsic functions, $TRANSLATE	@cindex intrinsic functions, $TRANSLATE

	Replaces characters in a string.

	The first argument is a string expression representing the text to be changed.

	The second argument is a list of characters to replace.

	The third argument is a list of characters to use as the replacements for the characters in the second argument.

	@emph{Example}

	@example
	DEFAULT.USER> W $TRANSLATE("twig","wt","rb")
	brig
	@end example

@node $TYPE()	@node $TYPE()
@section $TYPE	@section $TYPE
@cindex $TYPE	@cindex $TYPE
Line 1472 Always @emph{true}	Line 1499 Always @emph{true}
@cindex intrinsic functions, $ZCALL	@cindex intrinsic functions, $ZCALL
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZCRC()	@node $ZCRC()
@section $ZCRC	@section $ZCRC
@cindex $ZCRC	@cindex $ZCRC
Line 1492 Returns a checksum of @code{arg1}.	Line 1521 Returns a checksum of @code{arg1}.
@cindex intrinsic functions, $ZDATA	@cindex intrinsic functions, $ZDATA
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZDATE()	@node $ZDATE()
@section $ZDATE	@section $ZDATE
@cindex $ZDATE	@cindex $ZDATE
Line 1516 The optional @emph{<format-string>} foll	Line 1547 The optional @emph{<format-string>} foll
@cindex intrinsic functions, $ZEDIT	@cindex intrinsic functions, $ZEDIT
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZHOROLOG()	@node $ZHOROLOG()
@section $ZHOROLOG	@section $ZHOROLOG
@cindex $ZHOROLOG	@cindex $ZHOROLOG
Line 1540 $ZHOROLOG(@emph{<date-value>},@emph{<for	Line 1573 $ZHOROLOG(@emph{<date-value>},@emph{<for
@cindex intrinsic functions, $ZKEY	@cindex intrinsic functions, $ZKEY
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZLENGTH()	@node $ZLENGTH()
@section $ZLENGTH	@section $ZLENGTH
@cindex $ZLENGTH	@cindex $ZLENGTH
@cindex intrinsic functions, $ZLENGTH	@cindex intrinsic functions, $ZLENGTH
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZLSD()	@node $ZLSD()
@section $ZLSD	@section $ZLSD
@cindex $ZLSD	@cindex $ZLSD
Line 1574 Returns the Levenshtein distance between	Line 1611 Returns the Levenshtein distance between
@cindex intrinsic functions, $ZNAME	@cindex intrinsic functions, $ZNAME
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@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.

@node $ZORDER()	@node $ZORDER()
@section $ZORDER	@section $ZORDER
@cindex $ZORDER	@cindex $ZORDER
@cindex intrinsic functions, $ZORDER	@cindex intrinsic functions, $ZORDER
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZPIECE()	@node $ZPIECE()
@section $ZPIECE	@section $ZPIECE
@cindex $ZPIECE	@cindex $ZPIECE
@cindex intrinsic functions, $ZPIECE	@cindex intrinsic functions, $ZPIECE
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZPREVIOUS()	@node $ZPREVIOUS()
@section $ZPREVIOUS	@section $ZPREVIOUS
@cindex $ZPREVIOUS	@cindex $ZPREVIOUS
@cindex intrinsic functions, $ZPREVIOUS	@cindex intrinsic functions, $ZPREVIOUS
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZREPLACE()	@node $ZREPLACE()
@section $ZREPLACE	@section $ZREPLACE
@cindex $ZREPLACE	@cindex $ZREPLACE
Line 1769 $$<objectName>.EXTRACT(<start>,<end>)	Line 1816 $$<objectName>.EXTRACT(<start>,<end>)
@node $$FIND	@node $$FIND
@section $$FIND	@section $$FIND

	Finds the character immediately following the first occurence of a substring within a string.

	The first argument is the substring to be located.

	The second argument is the position within the string at which to begin searching.

	See @ref{$FIND()}.

@node $$FNUMBER	@node $$FNUMBER
@section $$FNUMBER	@section $$FNUMBER

	Formats a number according to a set of formatting codes.

	The argument is a series of formatting codes. See @ref{$FNUMBER()} for details.

@node $$JUSTIFY	@node $$JUSTIFY
@section $$JUSTIFY	@section $$JUSTIFY

	Right-justifies a string based on a specified fixed length.

	The first argument is the character length of the output.

	The second argument controls the number of fractional digits to be included in the output, and defaults to the number of digits specified in the first argument.

	See @ref{$JUSTIFY()} for details.

@node $$LENGTH	@node $$LENGTH
@section $$LENGTH	@section $$LENGTH

	Returns the length of the string.

@node $$PIECECOUNT	@node $$PIECECOUNT
@section $$PIECECOUNT	@section $$PIECECOUNT

	Returns the number of items in a list delimited by the character specified in the argument.

@node $$PIECE	@node $$PIECE
@section $$PIECE	@section $$PIECE

	@emph{Syntax}

	@code{$PIECE(@emph{d}[,@emph{n}[,@emph{end}]])}

	Accesses the @code{n}th through @code{end} @code{d}-delimited pieces of the string.

	The first argument is the delimiter to be used.

	The optional second argument is the first @code{d}-delimited piece to access, and defaults to @code{1}.

	The optional third argument is the final @code{d}-delimited piece to access, and defaults to the value of the third argument (@code{n}).


@node $$REPLACE	@node $$REPLACE
@section $$REPLACE	@section $$REPLACE

	@emph{Syntax}
	@code{myString.$$REPLACE(@emph{arg1},@emph{arg2})}

	Replaces all instances of @code{arg2} with @code{arg3} in @code{myString}.

@node $$REVERSE	@node $$REVERSE
@section $$REVERSE	@section $$REVERSE

	Returns the reverse of the string.

@node $$TOLOWER	@node $$TOLOWER
@section $$TOLOWER	@section $$TOLOWER

	Returns an all-lowercase version of the string.

@node $$TOUPPER	@node $$TOUPPER
@section $$TOUPPER	@section $$TOUPPER

	Returns an all-uppercase version of the string.

@node $$TRANSLATE	@node $$TRANSLATE
@section $$TRANSLATE	@section $$TRANSLATE

	Identical to @ref{$TRANSLATE()}, except that the arguments are shifted left by one, and the input string is implicit (the object).

@node Commands	@node Commands
@chapter Commands	@chapter Commands
@cindex commands	@cindex commands
Line 1846 $$<objectName>.EXTRACT(<start>,<end>)	Line 1943 $$<objectName>.EXTRACT(<start>,<end>)
* WITH:: Set prefix for future variable references.	* WITH:: Set prefix for future variable references.
* 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.
* ZALLOCATE:: Alternative to @code{LOCK}.
* ZBREAK:: Unknown.	* ZBREAK:: Unknown.
* ZDEALLOCATE:: Alternative to @code{LOCK}.
* ZGO:: Unknown.	* ZGO:: Unknown.
* ZHALT:: Unknown.	* ZHALT:: Unknown.
* ZINSERT:: Insert code into routine buffer.	* ZINSERT:: Insert code into routine buffer.
Line 2419 In the above @emph{inclusive} form, @cod	Line 2514 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.3.3, 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.64.0-rc1, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2454 In the above @emph{inclusive} form, @cod	Line 2549 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-rc0, 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.64.0-rc1, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2495 LOCK[@emph{:postcondition}] [+\|-]@emph{n	Line 2590 LOCK[@emph{:postcondition}] [+\|-]@emph{n

@emph{Example}	@emph{Example}

This example will increment the lock counter for @code{^JPW} and decrement the lock counter for @code{^MJR}.	This example will increment the lock counter for @code{^SNW} and decrement the lock counter for @code{^MJR}.

@example	@example
LOCK +^JPW,-^MJR	LOCK +^SNW,-^MJR
@end example	@end example

In its non-incremental form, @code{LOCK} releases all @code{LOCK}s held by the current process, and then attempts to acquire a lock on each @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. If @emph{timeout} is supplied, FreeM will attempt to lock @emph{name} for no more than @emph{timeout} seconds.	In its non-incremental form, @code{LOCK} releases all @code{LOCK}s held by the current process, and then attempts to acquire a lock on each @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. If @emph{timeout} is supplied, FreeM will attempt to lock @emph{name} for no more than @emph{timeout} seconds.
Line 2571 NEW@emph{:postcondition} @emph{name}=@em	Line 2666 NEW@emph{:postcondition} @emph{name}=@em

In its initializing form, @code{NEW} stacks variable @emph{name} and sets its value to @emph{expr}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous value is restored.	In its initializing form, @code{NEW} stacks variable @emph{name} and sets its value to @emph{expr}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous value is restored.

	@emph{Syntax}
	@example
	NEW@emph{:postcondition} @emph{name}=$%@emph{^CLASS}(@emph{initializer-list})
	@end example

	In its object-oriented form, @code{NEW} creates an instance of class @emph{^CLASS} in local variable @emph{name} and calls the constructor of @emph{^CLASS}, passing @emph{initializer-list} as its argument(s).

@node OPEN	@node OPEN
@section OPEN	@section OPEN
@cindex OPEN	@cindex OPEN
Line 2934 Closes all global data files open in the	Line 3036 Closes all global data files open in the
VIEW 21	VIEW 21
@end example	@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}	@item @code{52} - Set G0 Input Translation Table for @code{$IO}

@emph{Syntax}	@emph{Syntax}
Line 3090 If @emph{tvexpr} evaluates to @emph{true	Line 3184 If @emph{tvexpr} evaluates to @emph{true
VIEW 83:@emph{tvexpr}	VIEW 83:@emph{tvexpr}
@end example	@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{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}	@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.	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.

Line 3235 WATCH[@emph{:postcondition}] [+\|-\|?]@emp	Line 3305 WATCH[@emph{:postcondition}] [+\|-\|?]@emp
@end example	@end example


The following example demonstrates turning watchpoint processing on and adding a watchpoint for global variable @code{^jpw(1)}. It then changes the value of @code{^jpw(1)}.	The following example demonstrates turning watchpoint processing on and adding a watchpoint for global variable @code{^snw(1)}. It then changes the value of @code{^snw(1)}.

@example	@example
DEFAULT.USER> WATCH	DEFAULT.USER> WATCH

Watchpoints enabled.	Watchpoints enabled.

DEFAULT.USER> WATCH +^JPW(1)	DEFAULT.USER> WATCH +^SNW(1)

Added '^JPW("1")' to the watchlist.	Added '^SNW("1")' to the watchlist.

DEFAULT.USER> SET ^JPW(1)="new value"	DEFAULT.USER> SET ^SNW(1)="new value"

>> WATCHPOINT: ^JPW("1") => 'new value' (changed 1 times)	>> WATCHPOINT: ^SNW("1") => 'new value' (changed 1 times)

@end example	@end example

The following example will remove that watchpoint:	The following example will remove that watchpoint:

@example	@example
DEFAULT.USER> WATCH -^JPW(1)	DEFAULT.USER> WATCH -^SNW(1)

Removed '^JPW("1")' from the watchlist.	Removed '^SNW("1")' from the watchlist.

DEFAULT.USER> WATCH ?^JPW(1)	DEFAULT.USER> WATCH ?^SNW(1)

'^JPW("1")' is not being watched.	'^SNW("1")' is not being watched.
@end example	@end example

@node WITH	@node WITH
Line 3271 DEFAULT.USER> WATCH ?^JPW(1)	Line 3341 DEFAULT.USER> WATCH ?^JPW(1)
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@emph{FreeM Extension}

	NOTE: This command may be deprecated and removed in future FreeM releases.

Sets a prefix to be applied to all subsequent local variable or constant references.	Sets a prefix to be applied to all subsequent local variable or constant references.

@emph{Syntax}	@emph{Syntax}
Line 3300 In the above argumentless form, clears t	Line 3372 In the above argumentless form, clears t
@cindex XECUTE	@cindex XECUTE
@cindex commands, XECUTE	@cindex commands, XECUTE

@node ZALLOCATE
@section ZALLOCATE
@cindex ZALLOCATE
@cindex commands, ZALLOCATE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}

@node ZBREAK	@node ZBREAK
@section ZBREAK	@section ZBREAK
@cindex ZBREAK	@cindex ZBREAK
Line 3317 In the above argumentless form, clears t	Line 3381 In the above argumentless form, clears t
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@emph{FreeM Extension}

@node ZDEALLOCATE
@section ZDEALLOCATE
@cindex ZDEALLOCATE
@cindex commands, ZDEALLOCATE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}

@node ZGO	@node ZGO
@section ZGO	@section ZGO
@cindex ZGO	@cindex ZGO
Line 3813 Returns or sets the maximum number of ch	Line 3869 Returns or sets the maximum number of ch
Returns or sets the maximum number of characters of a single global subscript, from 1-255.	Returns or sets the maximum number of characters of a single global subscript, from 1-255.

@item @code{SINGLE_USER} +R +U -D	@item @code{SINGLE_USER} +R +U -D
If set to @code{1}, FreeM will skip all file locking operations on globals, as well as the @code{LOCK} and @code{ZALLOCATE} tables. If set to @code{0}, FreeM will enforce file locking on both.	If set to @code{1}, FreeM will skip all file locking operations on globals. If set to @code{0}, FreeM will enforce file locking on both.

Setting @code{SINGLE_USER} to @code{1} will improve FreeM performance, but you must @emph{ONLY} use this on systems where you are absolutely sure that only one FreeM process will run at any given time, as running multiple instances of FreeM concurrently when any of them are set to @code{SINGLE_USER} mode @emph{will} cause global data and @code{LOCK}/@code{ZALLOCATE} table corruption!	Setting @code{SINGLE_USER} to @code{1} will improve FreeM performance, but you must @emph{ONLY} use this on systems where you are absolutely sure that only one FreeM process will run at any given time, as running multiple instances of FreeM concurrently when any of them are set to @code{SINGLE_USER} mode @emph{will} cause global data corruption.

@item @code{CHARACTER} +R -U -D	@item @code{CHARACTER} +R -U -D
Returns the character set of the job.	Returns the character set of the job.
Line 4115 Forces a number to positive, whether pos	Line 4171 Forces a number to positive, whether pos
@section Unary -	@section Unary -
@cindex operators, unary -	@cindex operators, unary -

	Forces a number to negative, whether positive or negative. Also forces numeric coercion of strings.

@node +	@node +
@section + (Add)	@section + (Add)
@cindex operators, +	@cindex operators, +

	@emph{Syntax}

	@example
	S X=1+2 ; => 3
	@end example

	Adds numbers together.

@node +=	@node +=
@section += (Add/Assign)	@section += (Add/Assign)
@cindex operators, +=	@cindex operators, +=

	@emph{Syntax}

	@example
	S X=5
	S X+=3 ; => 8
	@end example

	Increments the variable on the LHS by the value on the RHS.

@node ++	@node ++
@section ++ (Postfix Increment)	@section ++ (Postfix Increment)
@cindex operators, ++	@cindex operators, ++

	Increments a variable by 1.

@node -	@node -
@section - (Subtract)	@section - (Subtract)
@cindex operators, -	@cindex operators, -

	Subtracts one number from another.

@node -=	@node -=
@section -= (Subtract/Assign)	@section -= (Subtract/Assign)
@cindex operators, -=	@cindex operators, -=

	@emph{Syntax}

	@example
	S X=5
	S X-=3 ; => 2
	@end example

	Decrements the variable on the LHS by the value on the RHS.

@node --	@node --
@section -- (Postfix Decrement)	@section -- (Postfix Decrement)
@cindex operators, --	@cindex operators, --

	Decrements the variable by one.

@node *	@node *
@section * (Multiply)	@section * (Multiply)
@cindex operators, *	@cindex operators, *

	Multiplies one number by another.

@node *=	@node *=
@section *= (Multiply/Assign)	@section *= (Multiply/Assign)
@cindex operators, *=	@cindex operators, *=



@node /	@node /
@section / (Divide)	@section / (Divide)
@cindex operators, /	@cindex operators, /
Line 4310 An @code{INTEGER} is an interpretation o	Line 4404 An @code{INTEGER} is an interpretation o
@cindex data types, REAL	@cindex data types, REAL
@cindex types, REAL	@cindex types, REAL

	A @code{REAL} is a numeric interpretation of data including a fractional part.

@node STRING	@node STRING
@section STRING	@section STRING
@cindex data types, STRING	@cindex data types, STRING
@cindex types, STRING	@cindex types, STRING

	A @code{STRING} is any data in FreeM.

@node Custom Types (Classes)	@node Custom Types (Classes)
@section Custom Types (Classes)	@section Custom Types (Classes)
@cindex data types, custom	@cindex data types, custom
Line 4329 See @ref{Classes}.	Line 4427 See @ref{Classes}.
@cindex variables, global	@cindex variables, global
@cindex data	@cindex data

	FreeM supports typical M globals, which are often described as persistent, hierachical sparse arrays. Globals make it relatively simple to include persistent data in an application without requiring the developer to use an external database management system, and offer syntax and semantics so similar to M local variables and structured system variables that moving from one to the other is seamless.

	Each global comprises three elements:

	@itemize @bullet
	@item
	An alphabetic name beginning with a caret (@code{^}) or a caret and a percent sign (@code{^%})
	@item
	Optionally, one or more comma-delimited subscripts, enclosed in parentheses
	@item
	A value of up to 255 characters in length
	@end itemize

	The percent sign will force the named global into the @code{SYSTEM} namespace of the current FreeM environment.

	@node Creating Globals
	@section Creating Globals
	@cindex globals, creating

	To create a global, you can use the @code{SET} command:

	@example
	SET ^MYGLOBAL("foo","bar")="this is the data value"
	@end example

	@node Removing Globals
	@section Removing Globals
	@cindex globals, removing

	To remove an entire global, you can use the @code{KILL} command with the unsubscripted name of the global:

	@example
	KILL ^MYGLOBAL
	@end example

	If you only want to remove part of a global, i.e., beginning at a certain subscript level, use the @code{KILL} command with a subscripted name:

	@example
	KILL ^MYGLOBAL("foo")
	@end example

	This will remove only the @code{"foo"} subscript and all of its children.

	If you only want to remove the data value at a specific subscript level, leaving the subscript itself intact, use @code{KVALUE}:

	@example
	KVALUE ^MYGLOBAL("foo")
	@end example

	@node Global Storage
	@section Global Storage
	@cindex globals, storage

	FreeM globals are stored in @code{$PREFIX/var/freem/@emph{<environment-name>}/@emph{<namespace-name>}/globals} in a binary format.

	Global files have a header of the following format:

	@verbatim
	typedef struct global_header {

	char magic[5]; /* FRMGL */
	int format_version;
	char host_triplet[40];
	char host_id[256];

	unsigned long block_size;
	unsigned long last_transaction_id;

	long created;
	long last_backup;

	} global_header;
	@end verbatim

@node Concurrency Control	@node Concurrency Control
@chapter Concurrency Control	@chapter Concurrency Control
@cindex concurrency control	@cindex concurrency control
@cindex locking	@cindex locking
@cindex transaction processing	@cindex transaction processing

	Multitasking, multi-user FreeM applications must concern themselves with concurrent access to globals in order to maintain logical consistency and prevent concurrent writes from interleaving.

	In FreeM, there are two mechanisms provided for managing concurrent global access: advisory locks, and transaction processing.

	@node Transaction Processing
	@section Transaction Processing
	@cindex transaction processing

	FreeM implements a significant subset of the transaction processing features from @emph{ANSI X11.1-1995}. This allows a series of global operations to be conducted all at once, either in batch mode (where concurrency is not disturbed), or in serial mode (where writes are guaranteed to be atomic, consistent, isolated, and durable).

	@subsection Theory of Operation

	FreeM uses a pessimistic concurrency control mechanism for @code{SERIAL} transactions, meaning that any @code{TSTART} command that includes the @code{SERIAL} transaction parameter will cause the process to acquire the transaction processing mutex, which prevents any process but the one holding the mutex from performing any data access (read or write) until either @code{TCOMMIT} or @code{TROLLBACK} is called, either committing or rolling back the transaction, respectively.

	Any transaction in between its @code{TSTART} and @code{TCOMMIT}/@code{TROLLBACK} is said to be @emph{in-flight}. During the in-flight stage, pending global operations are held only in memory and after-image journals.

	FreeM maintains a list of all globals affected during a transaction in-flight. When a @code{TCOMMIT} is reached, FreeM will generate a @emph{checkpoint} of each global data file to be changed by the transaction. These checkpoints allow all FreeM globals to be restored to their pre-transaction state if a @code{TCOMMIT} should fail part of the way through its operation.

	Checkpoints can have one of two modes:

	@table @asis

	@item @code{CP_REMOVE}
	Used for globals that did not exist prior to the beginning of this transaction. Simply marks the entire global data file for deletion in case of @code{TCOMMIT} failure.

	@item @code{CP_RESTORE}
	Used for globals that @emph{did} exist prior to the beginning of this transaction. In this case, the entire global data file is copied to a new file with a @code{.chk} extension. In cases of @code{TCOMMIT} failure, @code{CP_RESTORE} checkpoint files will be restored over the partially-modified live data file.

	@end table

	The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command:

	@verbatim
	TL1:DEFAULT.USER> trantab
	$TLEVEL 1*
	Operations for Transaction ID: 6ea14aad-b8f1-47f9-9f52-4f513f892bc0 [RESTARTABLE SERIAL]

	OP. NO. ACTION KEY/DATA
	------- ------ --------
	1 SET ^FOO=3
	2 KILL ^FOO
	3 SET ^snw=10
	4 SET ^BRANDNEW=6

	Global checkpoints:

	GLOBAL MODE FILES
	------ ---- -----
	^BRANDNEW CP_REMOVE IN: /usr/local/var/freem/USER/globals/^BRANDNEW
	^snw CP_RESTORE IN: /usr/local/var/freem/USER/globals/^snw
	OUT: /usr/local/var/freem/USER/globals/^snw.23390.1.chk
	^FOO CP_RESTORE IN: /usr/local/var/freem/USER/globals/^FOO
	OUT: /usr/local/var/freem/USER/globals/^FOO.23390.1.chk
	@end verbatim

	In the above example, @code{IN} files are the live data file that will be overwritten or removed, and @code{OUT} files are the checkpoints themselves. Note that @code{OUT} files are only used for @code{CP_RESTORE} checkpoints.

	@subsection Using Transaction Processing

	To use transactions in FreeM, you need to be familiar with three commands:

	@itemize @bullet
	@item
	@code{TSTART}
	@item
	@code{TCOMMIT}
	@item
	@code{TROLLBACK}
	@end itemize

	With transaction processing, global variable operations occurring between @code{TSTART} and @code{TCOMMIT} commands will be contained within the transaction.

	The atomicity, consistency, isolation, and durability facets of FreeM transaction hinge on the transaction mode.

	@subsubsection BATCH Transactions
	@code{BATCH} transactions offer higher performance, and allow other applications aside from the one doing the transaction to continue normal operations until the transaction is committed with @code{TCOMMIT}. In batch mode, other processes are only locked out of normal operation during the commit phase of the transaction.

	The effect of this is that the operations within the batch transaction will not be interleaved with global writes from other applications, but the entire lifetime of the transaction is not guaranteed to be serialized with respect to the transaction processing activities of other running applications in the environment.

	@subsubsection SERIAL Transactions
	@code{SERIAL} transactions offer full ACID compliance at the expense of multiprocessing performance. In serial mode, a @code{TSTART} blocks all activity from all other FreeM processes in the environment, and this blocking effect is not released until the transaction is committed with @code{TCOMMIT} or rolled back with @code{TROLLBACK} (or due to abnormal conditions in the environment that preclude the successful completion of the transaction).

@node Local Variables	@node Local Variables
@chapter Local Variables	@chapter Local Variables
@cindex variables, local	@cindex variables, local
Line 4387 See @ref{Classes}.	Line 4641 See @ref{Classes}.
@cindex programming, object-oriented	@cindex programming, object-oriented

@menu	@menu
* Classes:: The basis of object-oriented programming.	* Classes:: The basis of object-oriented programming.
	* Inheritance:: Basing one class upon another.
	* Methods:: Attaching code to a class.
	* Public and Private Variables:: Managing class member access.
	* Instantiating Objects:: Creating instances of classes.
	* Determining Object Class:: Getting object information at runtime.
@end menu	@end menu

@node Classes	@node Classes
@section Classes	@section Classes

@menu	A @emph{class} is the primary organizing concept of FreeM support for object-oriented programming, and in FreeM, is simply an M routine with a few special properties:
* Inheritance:: Basing one class upon another.
* Methods:: Attaching code to a class.	@example
* Public Variables:: Variables visible outside of a class.	MYCLASS(THIS,INIT):OBJECT ; Constructor for MYCLASS, inherits OBJECT
* Private Variables:: Variables only visible within a class.	; two private variables
@end menu	S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1)
	S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2)
	Q
	;
	DESTROY(THIS) ; This is the destructor
	Q
	@end example

	The above example demonstrates general class syntax.

	@node Constructors
	@subsection Constructors

	A @emph{constructor} is an M entry point that is called when a new instance of a class is created.

	A constructor must be the first entry point in a class routine, its tag must match the class/routine name, and it must take two arguments, @code{THIS} and @code{INIT}.

	@code{THIS} represents the instance of the object being accessed, and @code{INIT} represents an initializer that can be used to assign an initial value to the object when instantiating the class.

	A constructor looks like this:

	@example
	%FRACTION(THIS,INIT):OBJECT ;
	S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1)
	S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2)
	Q
	@end example

	@emph{Syntax}
	@example
	@emph{<class-name>}(THIS,INIT)[:@emph{<superclass>}]
	@end example

	In the above example, @emph{<superclass>} represents the name of a class from which this class should inherit. In this case, the @code{FRACTION} class inherits from the @code{OBJECT} class. Note that this is not strictly necessary in this case, as all classes in FreeM automatically inherit from @code{OBJECT}.

	@node Destructors
	@subsection Destructors
	A @code{destructor} is called when you @code{KILL} an instance variable. Its tag must be @code{DESTROY}, and it must take one argument (@code{THIS}).

	The destructor should be used to clean up any resources used by class methods.

	A destructor looks like this:

	@example
	DESTROY(THIS) ;
	; free any resources that should be freed at the end of the object's lifetime
	Q
	@end example

@node Inheritance	@node Inheritance
@subsection Inheritance	@section Inheritance

	Every class you create will automatically inherit the methods and functionality of the @code{OBJECT} class, supplied with FreeM.

	When attempting to call a method, FreeM will first search the class routine for a matching entry point, and then follow the inheritance chain upwards until a matching entry point is found. If the final class in the chain does not have a matching entry point, FreeM will try to find a matching entry point in the @code{OBJECT} class.

	Inheritance is achieved by specifying the name of the superclass in the constructor:

	@example
	CLASS(THIS,INIT):SUPERCLASS
	@end example

	@node Runtime Polymorphism
	@subsection Runtime Polymorphism

	You can achieve runtime polymorphism by subclassing, and defining methods in the subclass that match the names of existing methods in the superclass. Following FreeM inheritance rules, the overridden method in the subclass will be called, and the method in the superclass will not.

	Note that the overridden method in the subclass can take a different set or number of arguments than the @emph{formallist} of the superclass method would specify.

@node Methods	@node Methods
@subsection Methods	@section Methods
	Class methods are defined as tags with @emph{formallist}s in a class routine, and per the typical FreeM object pattern, must take at least one argument, being @code{THIS} (representing a reference to the object instance being accessed).

	The following class (@code{MYCLASS}) has a constructor, a destructor, and a method called @code{MYMETHOD}:

	@example
	%MYCLASS(THIS,INIT) ;
	Q THIS
	DESTROY(THIS) ;
	Q
	MYMETHOD(THIS) ;
	Q "VALUE"
	@end example

	The dot operator is used to invoke class methods:

	@example
	DEFAULT.USER> N MYOBJ=$#^%MYCLASS("")
	DEFAULT.USER> W MYOBJ.MYMETHOD()
	VALUE
	@end example

	@node Public and Private Variables
	@section Public and Private Variables

	FreeM supports private fields with the @code{:PRIVATE} specifier in the @code{SET} command, enforcing classical object-oriented data encapsulation. The @code{:PUBLIC} specifier is provided for completeness, and is the default.

	The below constructor for a @code{FRACTION} class defines two private fields:

	@example
	%FRACTION(THIS,INIT):OBJECT ;
	S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1)
	S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2)
	Q
	@end example

	Either of the following commands will create a public field:

	@example
	S THIS("VARNAM")="Initial Value"
	S THIS("VARNAM"):PUBLIC="Initial Value"
	@end example

	Attempting to access private fields from outside of the class will raise error condition @code{ZOBJFLDACCV}.

@node Public Variables	@node Instantiating Objects
@subsection Public Variables	@section Instantiating Objects

@node Private Variables	To instantiate an object (i.e., create an object from a certain class), you will use the @code{NEW} command as follows:
@subsection Private Variables
	@example
	NEW MYSTR=$#^%STRING("myString")
	@end example

	This will create a local variable called MYSTR of type STRING, and initialize it with the value myString.

	@node Determining Object Class
	@section Determining Object Class

	To determine the class of any FreeM local variable, you will use the @code{$$TYPE()} method:

	@example
	USER> W MYSTR.$$TYPE()
	^%STRING
	@end example

	The @code{$$TYPE()} method is a member of the @code{OBJECT} class.

@node Libraries	@node Libraries
@chapter Libraries	@chapter Libraries
Line 4518 To remove the above mapping, any of the	Line 4901 To remove the above mapping, any of the
KILL ^$SYSTEM("MAPPINGS","GLOBAL","^FOO")	KILL ^$SYSTEM("MAPPINGS","GLOBAL","^FOO")
@end example	@end example

@node Transaction Processing
@chapter Transaction Processing
@cindex transaction processing

FreeM implements a significant subset of the transaction processing features from @emph{ANSI X11.1-1995}. This allows a series of global operations to be conducted all at once, either in batch mode (where concurrency is not disturbed), or in serial mode (where writes are guaranteed to be atomic, consistent, isolated, and durable).

@section Theory of Operation

FreeM uses a pessimistic concurrency control mechanism for @code{SERIAL} transactions, meaning that any @code{TSTART} command that includes the @code{SERIAL} transaction parameter will cause the process to acquire the transaction processing mutex, which prevents any process but the one holding the mutex from performing any data access (read or write) until either @code{TCOMMIT} or @code{TROLLBACK} is called, either committing or rolling back the transaction, respectively.

Any transaction in between its @code{TSTART} and @code{TCOMMIT}/@code{TROLLBACK} is said to be @emph{in-flight}. During the in-flight stage, pending global operations are held only in memory and after-image journals.

FreeM maintains a list of all globals affected during a transaction in-flight. When a @code{TCOMMIT} is reached, FreeM will generate a @emph{checkpoint} of each global data file to be changed by the transaction. These checkpoints allow all FreeM globals to be restored to their pre-transaction state if a @code{TCOMMIT} should fail part of the way through its operation.

Checkpoints can have one of two modes:

@table @asis

@item @code{CP_REMOVE}
Used for globals that did not exist prior to the beginning of this transaction. Simply marks the entire global data file for deletion in case of @code{TCOMMIT} failure.

@item @code{CP_RESTORE}
Used for globals that @emph{did} exist prior to the beginning of this transaction. In this case, the entire global data file is copied to a new file with a @code{.chk} extension. In cases of @code{TCOMMIT} failure, @code{CP_RESTORE} checkpoint files will be restored over the partially-modified live data file.

@end table

The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command:

@verbatim
TL1:DEFAULT.USER> trantab
$TLEVEL 1*
Operations for Transaction ID: 6ea14aad-b8f1-47f9-9f52-4f513f892bc0 [RESTARTABLE SERIAL]

OP. NO. ACTION KEY/DATA
------- ------ --------
1 SET ^FOO=3
2 KILL ^FOO
3 SET ^jpw=10
4 SET ^BRANDNEW=6

Global checkpoints:

GLOBAL MODE FILES
------ ---- -----
^BRANDNEW CP_REMOVE IN: /usr/local/var/freem/USER/globals/^BRANDNEW
^jpw CP_RESTORE IN: /usr/local/var/freem/USER/globals/^jpw
OUT: /usr/local/var/freem/USER/globals/^jpw.23390.1.chk
^FOO CP_RESTORE IN: /usr/local/var/freem/USER/globals/^FOO
OUT: /usr/local/var/freem/USER/globals/^FOO.23390.1.chk
@end verbatim

In the above example, @code{IN} files are the live data file that will be overwritten or removed, and @code{OUT} files are the checkpoints themselves. Note that @code{OUT} files are only used for @code{CP_RESTORE} checkpoints.


@node Asynchronous Event Handling	@node Asynchronous Event Handling
Line 4783 You can also set up a trigger that appli	Line 5114 You can also set up a trigger that appli

This routine is the implementation of the @code{$ZCOLUMNS} intrinsic special variable.	This routine is the implementation of the @code{$ZCOLUMNS} intrinsic special variable.

@section ^%SYSINIT	@section %SYSINIT
@cindex ^%SYSINIT	@cindex %SYSINIT
@cindex system library routines, ^%SYSINIT	@cindex system library routines, %SYSINIT

This routine is the default startup routine for FreeM running in direct mode.	This routine is the default startup routine for FreeM running in direct mode.

Line 5787 The FreeM @code{LOCK} table.	Line 6118 The FreeM @code{LOCK} table.

Supported actions are @code{list} and @code{remove}.	Supported actions are @code{list} and @code{remove}.

@item zallocate
The FreeM @code{ZALLOCATE} table.

No actions yet implemented.

@item journal	@item journal
FreeM after-image journaling.	FreeM after-image journaling.

Line 6013 Module headers should adhere to the foll	Line 6339 Module headers should adhere to the foll
* binding library	* binding library
*	*
*	*
* Author: Serena Willis <jpw@coherent-logic.com>	* Author: Serena Willis <snw@coherent-logic.com>
* Copyright (C) 1998 MUG Deutschland	* Copyright (C) 1998 MUG Deutschland
* Copyright (C) <Year> Coherent Logic Development LLC	* Copyright (C) <Year> Coherent Logic Development LLC
*	*

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