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.19 and 1.26

version 1.19, 2025/04/04 18:00:01	version 1.26, 2025/04/18 03:59:29
Line 4	Line 4
@settitle The FreeM Manual	@settitle The FreeM Manual

@copying	@copying
This manual is for FreeM, (version 0.63.1-rc6), which is a free and open-source implementation of the M programming language.	This manual is for FreeM, (version 0.64.0-rc0), 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.63.1-rc6	@subtitle Version 0.64.0-rc0
@c@vskip 10pt	@c@vskip 10pt
@c@center @image{freem-logo-sm,,,,.png}	@c@center @image{freem-logo-sm,,,,.png}
@author Serena Willis	@author Serena Willis
Line 43 This is the official manual for the Free	Line 43 This is the official manual for the Free
@menu	@menu
* Introduction:: About the FreeM Project, its history, and its goals.	* Introduction:: About the FreeM Project, its history, and its goals.
* FreeM Invocation:: How to invoke FreeM from the command line.	* FreeM Invocation:: How to invoke FreeM from the command line.
* The FreeM Daemon:: Managing shared resources in the FreeM environment.	* The FreeM Environment Daemon:: Managing shared resources in the FreeM environment.
* The FreeM Direct-Mode Environment:: Executing M programs interactively.	* The FreeM Direct-Mode Environment:: Executing M programs interactively.

* Directives:: Per-Routine Language Directives.	* Directives:: Per-Routine Language Directives.
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 238 $ @command{./freem} [@emph{OPTIONS}...]	Line 237 $ @command{./freem} [@emph{OPTIONS}...]

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 instead of @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

	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.

@section Command-Line Options	@section Command-Line Options
	@cindex options, command-line

@table @asis	@table @asis

@item @option{-d}, @option{--daemon}	@item @option{-d}, @option{--daemon}
Starts the FreeM daemon, exactly one of which must be running at all times in order for FreeM interpreter and fmadm processes to function.	Starts the FreeM environment daemon, exactly one of which must be running at all times in order for FreeM interpreter and fmadm processes to function.

@item @option{-e}, @option{--environment}	@item @option{-e}, @option{--environment}
Selects the environment to be used. If no environment is specified, @code{DEFAULT} is used.	Selects the environment to be used. If no environment is specified, @code{DEFAULT} is used.

@item @option{-k}, @option{--nofork}	@item @option{-k}, @option{--nofork}
When used with @option{-d} or @option{--daemon}, causes the FreeM daemon to run instead in the foreground. Useful for debugging.	When used with @option{-d} or @option{--daemon}, causes the FreeM environment daemon to run instead in the foreground. Useful for debugging.

@item @option{-p}, @option{--pidfile}
When used with @option{-d} or @option{--daemon}, sets the file in which the PID of the running daemon is stored.

@item @option{-S}, @option{--shmsize}	@item @option{-S}, @option{--shmsize}
When used with @option{-d} or @option{--daemon}, specifies the number of bytes of shared memory FreeM will allocate for the @code{LOCK} table, job table, and IPC table. This will determine the maximum number of concurrent FreeM processes and @code{LOCK}s available in this environment.	When used with @option{-d} or @option{--daemon}, specifies the number of bytes of shared memory FreeM will allocate for the @code{LOCK} table, job table, and IPC table. This will determine the maximum number of concurrent FreeM processes and @code{LOCK}s available in this environment.
Line 272 Causes your UNIX environment variables t	Line 275 Causes your UNIX environment variables t
Allows your M routines to be used as UNIX filters.	Allows your M routines to be used as UNIX filters.

@item @option{-n @emph{<namespace-name>}}, @option{--namespace=@emph{<namespace-name>}}	@item @option{-n @emph{<namespace-name>}}, @option{--namespace=@emph{<namespace-name>}}
Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/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}.
Line 305 Please note that FreeM is not entirely s	Line 308 Please note that FreeM is not entirely s
Displays FreeM version information.	Displays FreeM version information.

@item @option{-x @emph{<mcode>}}, @option{--execute=@emph{<mcode>}}	@item @option{-x @emph{<mcode>}}, @option{--execute=@emph{<mcode>}}
Executes M code @code{<mcode>} at startup instead of the startup routine.	Executes M code @code{<mcode>} at startup.

@end table	@end table

Line 333 You will also need to set the script's p	Line 336 You will also need to set the script's p
$ chmod +x @emph{myscript.m}	$ chmod +x @emph{myscript.m}
@end example	@end example

@node The FreeM Daemon	@node The FreeM Environment Daemon
@chapter The FreeM Daemon	@chapter The FreeM Environment Daemon
@cindex daemon, freem	@cindex daemon, freem

The FreeM daemon manages shared resources for a given FreeM environment. These include the lock table, job table, inter-process communication, and concurrency control for transaction processing. Unlike some M implementations, the FreeM daemon does @emph{not} function as a write daemon for global storage.	The FreeM environment daemon manages shared resources for a given FreeM environment. These include the lock table, job table, inter-process communication, and concurrency control for transaction processing. Unlike some M implementations, the FreeM environment daemon does @emph{not} function as a write daemon for global storage.

One daemon process is required per FreeM environment, and can be started as follows:	One daemon process is required per FreeM environment, and can be started in the following ways, in order of preference:

	@example
	$ sudo fmadm start environment [-e=<environment-name>]
	@end example

@example	@example
$ freem --daemon [--nofork] [--environment=<environment-name>] [--user=<username>] \	$ freem --daemon [--nofork] [--environment=<environment-name>] [--shmsize=<bytes>]
[--group=<group-name>] [--pidfile=<pid-file>] [--shmsize=<bytes>]
@end example	@end example

If the daemon is started with @option{--nofork}, it will run in the foreground and its output will be reflected on the terminal. Otherwise, the daemon will run as a child process in the background and immediately return terminal control to the shell. The latter option is recommended in most cases.	If the daemon is started with @option{--nofork}, it will run in the foreground and its output will be reflected on the terminal. Otherwise, the daemon will run as a child process in the background and immediately return terminal control to the shell. The latter option is recommended in most cases.

The @option{--environment} option will start the daemon for the specified @emph{environment-name}. The default environment, if unspecified, is called @code{DEFAULT}. If using an environment other than @code{DEFAULT}, interpreter processes that wish to also connect to the same environment must also use the @option{--environment} option when starting, and @code{libfreem} clients must also pass the environment name as the first argument to the @code{freem_init()} function. Environments allow you to run multiple, isolated instances of FreeM on the same machine, whose globals and routines are distinct and unique.	The @option{--environment} option will start the daemon for the specified @emph{environment-name}. The default environment, if unspecified, is called @code{DEFAULT}. If using an environment other than @code{DEFAULT}, interpreter processes that wish to also connect to the same environment must also use the @option{--environment} option when starting, and @code{libfreem} clients must also pass the environment name as the first argument to the @code{freem_init()} function. Environments allow you to run multiple, isolated instances of FreeM on the same machine, whose globals and routines are distinct and unique.

The @option{--user} and @option{--group} options are only valid when the FreeM daemon is started by the superuser, and will cause the daemon to reduce its runtime privileges to those of the specified user and group, and run as that user and/or group. We recommend creating a @code{freem} user and group and running the FreeM daemon with @code{--user=freem --group=freem}.

The @option{--pidfile} option specifies the file in which the FreeM daemon will store its own PID. If running as the superuser, the FreeM daemon will store the PID file in @code{/var/run/freem.pid}. Otherwise, the PID file will be stored as @code{.freem.pid} in the home directory of the user account which owns the FreeM daemon process.

The @option{--shmsize} option specifies the size in bytes of the FreeM shared memory segment. The default is 4194304 bytes. Increasing the size of the FreeM shared memory segment will, at the cost of increased memory usage, increase the number of concurrent jobs and lock table entries available to the environment; decreasing the size of the segment will have the expected opposite effect. Note that you must also pass @option{--shmsize} with the same number of bytes to any interpreter process to be used with an environment whose daemon uses a non-default shared memory segment size.	The @option{--shmsize} option specifies the size in bytes of the FreeM shared memory segment. The default is 4194304 bytes. Increasing the size of the FreeM shared memory segment will, at the cost of increased memory usage, increase the number of concurrent jobs and lock table entries available to the environment; decreasing the size of the segment will have the expected opposite effect. Note that you must also pass @option{--shmsize} with the same number of bytes to any interpreter process to be used with an environment whose daemon uses a non-default shared memory segment size.

Attempting to start a FreeM interpreter process without a daemon running with the same environment name will result in an error.	Attempting to start a FreeM interpreter process without a daemon running with the same environment name will result in an error.
Line 369 Attempting to start a FreeM interpreter	Line 371 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.63.1-rc6 (x86_64-pc-linux-gnu)	Coherent Logic Development FreeM version 0.64.0-rc0 (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{USER>}) indicates the currently-active namespace. 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:USER>	TL1:DEFAULT.USER>
@end example	@end example

In the above example, @code{TL1} indicates that @code{@ref{$TLEVEL}} is currently @emph{1}.	In the above example, @code{TL1} indicates that @code{@ref{$TLEVEL}} is currently @emph{1}.
Line 397 Accesses FreeM online help. Requires GNU	Line 399 Accesses FreeM online help. Requires GNU
Writes a list of @emph{event classes} and their @code{ABLOCK} counts:	Writes a list of @emph{event classes} and their @code{ABLOCK} counts:

@example	@example
USER> events	DEFAULT.USER> events

Event Class Processing Mode ABLOCK Count	Event Class Processing Mode ABLOCK Count
----------- --------------- ------------	----------- --------------- ------------
Line 417 TRIGGER Disabled 0	Line 419 TRIGGER Disabled 0
@item @command{trantab}	@item @command{trantab}
Displays information about any uncommitted transactions currently in-flight for this process.	Displays information about any uncommitted transactions currently in-flight for this process.

	@anchor{glstat}
	@item @command{trantab}
	Displays statistics about globals that have been opened in the current FreeM process.

@anchor{jobtab}	@anchor{jobtab}
@item @command{jobtab}	@item @command{jobtab}
Displays a summary of the FreeM job table.	Displays a summary of the FreeM job table.
Line 457 Allows you to recall command number @emp	Line 463 Allows you to recall command number @emp
Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands.	Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands.

@example	@example
USER> !!	DEFAULT.USER> !!

Type Ctrl-D to exit from the shell	Type Ctrl-D to exit from the shell
$ uname -a	$ uname -a
Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux	Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux
$ exit	$ exit

USER>	DEFAULT.USER>
@end example	@end example

@item @command{!@emph{<external-command>}}	@item @command{!@emph{<external-command>}}
Line 482 The data value in the unsubscripted M lo	Line 488 The data value in the unsubscripted M lo
If you issue a @code{@ref{HALT}} command at the direct-mode prompt, you will exit out of FreeM. However, if you issue a @code{@ref{HALT}} command when @code{@ref{$TLEVEL}} is greater than zero, you will be given the opportunity to commit or rollback any pending transactions:	If you issue a @code{@ref{HALT}} command at the direct-mode prompt, you will exit out of FreeM. However, if you issue a @code{@ref{HALT}} command when @code{@ref{$TLEVEL}} is greater than zero, you will be given the opportunity to commit or rollback any pending transactions:

@example	@example
USER> TSTART	DEFAULT.USER> TSTART


TL1:USER> SET ^MYGLOBAL=1	TL1:DEFAULT.USER> SET ^MYGLOBAL=1


TL1:USER> HALT	TL1:DEFAULT.USER> HALT

UNCOMMITTED TRANSACTIONS EXIST:	UNCOMMITTED TRANSACTIONS EXIST:

Line 510 In the above example, the user selected	Line 516 In the above example, the user selected
FreeM direct mode allows you to enter M expressions directly from the direct-mode prompt, as long as they begin with a number:	FreeM direct mode allows you to enter M expressions directly from the direct-mode prompt, as long as they begin with a number:

@example	@example
USER> S DENOM=10	DEFAULT.USER> S DENOM=10


USER> 100/DENOM	DEFAULT.USER> 100/DENOM

10	10
USER>	DEFAULT.USER>
@end example	@end example

Such expressions will be immediately evaluated, and the result printed on @code{@ref{$IO}}.	Such expressions will be immediately evaluated, and the result printed on @code{@ref{$IO}}.
Line 1081 SET M=$EXTRACT(NAME,1,5)	Line 1087 SET M=$EXTRACT(NAME,1,5)
It is also possible to use @code{$EXTRACT} on the left-hand side of a @code{SET} assignment in order to modify a substring:	It is also possible to use @code{$EXTRACT} on the left-hand side of a @code{SET} assignment in order to modify a substring:

@example	@example
USER> SET FOO="ABCDEFG"	DEFAULT.USER> SET FOO="ABCDEFG"


USER> SET $EXTRACT(FOO,1,3)="XYZ"	DEFAULT.USER> SET $EXTRACT(FOO,1,3)="XYZ"


USER> WRITE FOO	DEFAULT.USER> WRITE FOO

XYZDEFG	XYZDEFG
@end example	@end example
Line 1114 Formats a number according to a particul	Line 1120 Formats a number according to a particul

The first argument is the number to format.	The first argument is the number to format.

The second argument is the series of formatting codes.	The second argument is the series of formatting codes:

	@table @asis
	@item 'P' or 'p'
	Will display negative numbers within parentheses instead of showing a minus sign.
	@item , (comma)
	Will add commas as thousands separators.
	@item +
	Will include a plus sign for positive numbers. Not compatible with 'P' or 'p'.
	@item -
	Will remove the minus sign from negative numbers. Not compatible with 'p' or 'P'.
	@item 't' or 'T'
	Will place the sign after the number instead of before the number.
	@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.

@node $GET()	@node $GET()
@section $GET	@section $GET
Line 1139 The first argument is a string represent	Line 1160 The first argument is a string represent

The second argument is a string representing a valid FreeM class.	The second argument is a string representing a valid FreeM class.



@example	@example
USER> N STR=$$^%STRING	DEFAULT.USER> N STR=$$^%STRING

USER> W $INSTANCEOF("STR","^%STRING")	DEFAULT.USER> W $INSTANCEOF("STR","^%STRING")
1	1
@end example	@end example

Line 1188 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 1379 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 1452 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 1472 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 1496 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 1520 $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 1554 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 1749 $$<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 1861 Executes FreeM code @emph{expr V mcode}.	Line 1973 Executes FreeM code @emph{expr V mcode}.
@emph{Example (Using Variable)}	@emph{Example (Using Variable)}

@example	@example
USER> SET FOO="WRITE ""HELLO WORLD"",!"	DEFAULT.USER> SET FOO="WRITE ""HELLO WORLD"",!"
USER> @@FOO	DEFAULT.USER> @@FOO

HELLO WORLD	HELLO WORLD

USER>	DEFAULT.USER>
@end example	@end example

@emph{Example (Using String Literal)}	@emph{Example (Using String Literal)}

@example	@example
USER> @@"WRITE ""HELLO WORLD"",!"	DEFAULT.USER> @@"WRITE ""HELLO WORLD"",!"

HELLO WORLD	HELLO WORLD

USER>	DEFAULT.USER>
@end example	@end example

@emph{Example (Using Indirection)}	@emph{Example (Using Indirection)}

@example	@example
USER> SET FOO="BAR"	DEFAULT.USER> SET FOO="BAR"

USER> SET BAR="WRITE ""HELLO WORLD"",!"	DEFAULT.USER> SET BAR="WRITE ""HELLO WORLD"",!"

USER> @@@@FOO	DEFAULT.USER> @@@@FOO

HELLO WORLD	HELLO WORLD

USER>	DEFAULT.USER>
@end example	@end example


Line 1921 If the @command{>} character is supplied	Line 2033 If the @command{>} character is supplied
Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands.	Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands.

@example	@example
USER> !!	DEFAULT.USER> !!

Type Ctrl-D to exit from the shell	Type Ctrl-D to exit from the shell
$ uname -a	$ uname -a
Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux	Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux
$ exit	$ exit

USER>	DEFAULT.USER>
@end example	@end example


Line 1983 The @code{ASSERT} error is catchable whe	Line 2095 The @code{ASSERT} error is catchable whe
@emph{Example}	@emph{Example}

@example	@example
USER> SET DEBUG=1	DEFAULT.USER> SET DEBUG=1


USER> ASSERT:DEBUG 1=1	DEFAULT.USER> ASSERT:DEBUG 1=1


USER> ASSERT:DEBUG 1=0	DEFAULT.USER> ASSERT:DEBUG 1=0


>> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0]	>> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0]
Line 2232 FOR[@emph{:postcondition}] @emph{glvn}=@	Line 2344 FOR[@emph{:postcondition}] @emph{glvn}=@
@emph{Example}	@emph{Example}

@example	@example
USER> FOR I=1:1:10 WRITE I,!	DEFAULT.USER> FOR I=1:1:10 WRITE I,!

1	1
2	2
Line 2245 USER> FOR I=1:1:10 WRITE I,!	Line 2357 USER> FOR I=1:1:10 WRITE I,!
9	9
10	10

USER> FOR I=2:2:10 WRITE I,!	DEFAULT.USER> FOR I=2:2:10 WRITE I,!

2	2
4	4
Line 2265 FOR[@emph{:postcondition}] @emph{glvn}=@	Line 2377 FOR[@emph{:postcondition}] @emph{glvn}=@
@emph{Example}	@emph{Example}

@example	@example
USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,!	DEFAULT.USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,!

60	60
FOO	FOO
Line 2399 In the above @emph{inclusive} form, @cod	Line 2511 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 2434 In the above @emph{inclusive} form, @cod	Line 2546 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.63.1-rc6, 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-rc0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2475 LOCK[@emph{:postcondition}] [+\|-]@emph{n	Line 2587 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 2551 NEW@emph{:postcondition} @emph{name}=@em	Line 2663 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 2914 Closes all global data files open in the	Line 3033 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 3070 If @emph{tvexpr} evaluates to @emph{true	Line 3181 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 3218 WATCH[@emph{:postcondition}] [+\|-\|?]@emp	Line 3305 WATCH[@emph{:postcondition}] [+\|-\|?]@emp
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{^jpw(1)}. It then changes the value of @code{^jpw(1)}.

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

Watchpoints enabled.	Watchpoints enabled.

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

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

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

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

Line 3235 USER> SET ^JPW(1)="new value"	Line 3322 USER> SET ^JPW(1)="new value"
The following example will remove that watchpoint:	The following example will remove that watchpoint:

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

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

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

'^JPW("1")' is not being watched.	'^JPW("1")' is not being watched.
@end example	@end example
Line 3251 USER> WATCH ?^JPW(1)	Line 3338 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 3280 In the above argumentless form, clears t	Line 3369 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 3297 In the above argumentless form, clears t	Line 3378 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 3806 Returns or sets the current working dire	Line 3879 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 4477 You may also use an expression that reso	Line 4531 You may also use an expression that reso
WRITE ^\|NS\|VA(200,0),!	WRITE ^\|NS\|VA(200,0),!
@end example	@end example

@section File Path Extended Global References
@cindex extended global references, file path

If a namespace is configured to use the @code{BUILTIN} global handler, FreeM supports accessing a global data file by way of its filesystem path.

The following file path extended global reference will write the value of @code{^VA(200,0)}, assuming the @code{^VA} data file exists at path @code{/home/jpw/^VA}:

@example
WRITE ^/home/jpw/VA(200,0),!
@end example


@node Global Aliasing	@node Global Aliasing
@chapter Global Aliasing	@chapter Global Aliasing
@cindex aliasing, global	@cindex aliasing, global
Line 4558 Used for globals that @emph{did} exist p	Line 4600 Used for globals that @emph{did} exist p
The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command:	The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command:

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

Line 4818 This routine is the implementation of th	Line 4860 This routine is the implementation of th
@chapter Interrupt Handling	@chapter Interrupt Handling
@cindex interrupt handling	@cindex interrupt handling

When FreeM receives the @code{SIGINT} signal, either by pressing @code{Ctrl-C} during program execution, or by external signal from the operating system, the FreeM daemon, or another external process, one of two things can happen, depending on the state of the @code{$ZI} special variable:	When FreeM receives the @code{SIGINT} signal, either by pressing @code{Ctrl-C} during program execution, or by external signal from the operating system, the FreeM environment daemon, or another external process, one of two things can happen, depending on the state of the @code{$ZI} special variable:

@table @asis	@table @asis
@item @code{$ZI} evaluates @emph{true}	@item @code{$ZI} evaluates @emph{true}
Line 5071 Custom error messages for @code{ZUSERERR	Line 5113 Custom error messages for @code{ZUSERERR
For example:	For example:

@example	@example
USER> S ^$JOB($JOB,"USER_ERRORS","UBLACKHOLE")="black hole encountered"	DEFAULT.USER> S ^$JOB($JOB,"USER_ERRORS","UBLACKHOLE")="black hole encountered"


USER> THROW UBLACKHOLE	DEFAULT.USER> THROW UBLACKHOLE


>> Error UBLACKHOLE: black hole encountered in SYSTEM::^%SYSINIT [$STACK = 0]	>> Error UBLACKHOLE: black hole encountered in SYSTEM::^%SYSINIT [$STACK = 0]

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