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.22 and 1.27

version 1.22, 2025/04/10 14:37:20	version 1.27, 2025/04/18 15:39:23
Line 110 This is the official manual for the Free	Line 110 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 379 Copyright (C) 2014, 2020, 2021 Coherent	Line 378 Copyright (C) 2014, 2020, 2021 Coherent
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 1134 Will include a plus sign for positive nu	Line 1133 Will include a plus sign for positive nu
Will remove the minus sign from negative numbers. Not compatible with 'p' or 'P'.	Will remove the minus sign from negative numbers. Not compatible with 'p' or 'P'.
@item 't' or 'T'	@item 't' or 'T'
Will place the sign after the number instead of before the number.	Will place the sign after the number instead of before the number.
@end @table	@end table

The optional third argument is a number indicating how many digits to which the fractional part of the number will be zero-padded.	The optional third argument is a number indicating how many digits to which the fractional part of the number will be zero-padded.

Line 1208 The optional second argument indicates t	Line 1207 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 1399 Returns a line of code from a routine.	Line 1406 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 1494 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 1516 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 1542 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 1568 $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 1606 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 1811 $$<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 1938 $$<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 2509 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-rc0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2495 LOCK[@emph{:postcondition}] [+\|-]@emph{n	Line 2585 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 2661 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 3031 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 3179 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 3271 DEFAULT.USER> WATCH ?^JPW(1)	Line 3336 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 3367 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 3376 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 3864 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 3826 Returns or sets the current working dire	Line 3877 Returns or sets the current working dire
@item @code{OPEN} +R -U -D	@item @code{OPEN} +R -U -D
The @code{^$JOB($JOB,"OPEN",<channel>} subscripts list the open I/O channels in the specified job.	The @code{^$JOB($JOB,"OPEN",<channel>} subscripts list the open I/O channels in the specified job.

@item @code{ENGINES} +R -U -D
Returns or sets the storage engines for various FreeM subsystems.

The following table lists the types of storage engines that can be defined.

@table @asis

@item @code{GLOBAL} +R +U -D
Returns or sets the global handler for a particular FreeM namespace:

The following code would set the global handler for the @code{SYSTEM} namespace to @code{BERKELEYDB}:

@code{SET ^$JOB($JOB,"ENGINES","GLOBAL","SYSTEM")="BERKELEYDB"}

@item @code{LOCAL} +R -U -D
Returns the local handler for a particular FreeM namespace. Always @code{BUILTIN} in the current FreeM release.

@end table

@item @code{BERKELEYDB,FLUSH_THRESHOLD} +R +U -D	@item @code{BERKELEYDB,FLUSH_THRESHOLD} +R +U -D
Returns or sets the number of write operations that will be cached in the BerkeleyDB global handler prior to flushing BerkeleyDB's cache to disk.	Returns or sets the number of write operations that will be cached in the BerkeleyDB global handler prior to flushing BerkeleyDB's cache to disk.

Line 5806 The FreeM @code{LOCK} table.	Line 5838 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.

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

Removed from v.1.22
changed lines
	Added in v.1.27