--- freem/doc/freem.texi 2025/04/10 14:37:20 1.22 +++ freem/doc/freem.texi 2025/04/18 03:59:29 1.26 @@ -110,7 +110,6 @@ This is the official manual for the Free @node 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. 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. @@ -379,7 +378,7 @@ Copyright (C) 2014, 2020, 2021 Coherent USER> @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 TL1:DEFAULT.USER> @@ -1134,7 +1133,7 @@ Will include a plus sign for positive nu 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 +@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. @@ -1208,11 +1207,19 @@ The optional second argument indicates t @cindex $NEXT @cindex intrinsic functions, $NEXT +Deprecated. Use @code{$ORDER} instead. + @node $ORDER() @section $ORDER @cindex $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() @section $PIECE @cindex $PIECE @@ -1399,6 +1406,21 @@ Returns a line of code from a routine. @cindex $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() @section $TYPE @cindex $TYPE @@ -1472,6 +1494,8 @@ Always @emph{true} @cindex intrinsic functions, $ZCALL @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZCRC() @section $ZCRC @cindex $ZCRC @@ -1492,6 +1516,8 @@ Returns a checksum of @code{arg1}. @cindex intrinsic functions, $ZDATA @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZDATE() @section $ZDATE @cindex $ZDATE @@ -1516,6 +1542,8 @@ The optional @emph{} foll @cindex intrinsic functions, $ZEDIT @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZHOROLOG() @section $ZHOROLOG @cindex $ZHOROLOG @@ -1540,12 +1568,16 @@ $ZHOROLOG(@emph{},@emph{.EXTRACT(,) @node $$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 @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 @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 @section $$LENGTH +Returns the length of the string. + @node $$PIECECOUNT @section $$PIECECOUNT +Returns the number of items in a list delimited by the character specified in the argument. + @node $$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 @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 @section $$REVERSE +Returns the reverse of the string. + @node $$TOLOWER @section $$TOLOWER +Returns an all-lowercase version of the string. + @node $$TOUPPER @section $$TOUPPER +Returns an all-uppercase version of the string. + @node $$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 @chapter Commands @cindex commands @@ -2419,7 +2511,7 @@ In the above @emph{inclusive} form, @cod @cartouche @quotation @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 cartouche @@ -2495,10 +2587,10 @@ LOCK[@emph{:postcondition}] [+|-]@emph{n @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 -LOCK +^JPW,-^MJR +LOCK +^SNW,-^MJR @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. @@ -2571,6 +2663,13 @@ 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. +@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 @section OPEN @cindex OPEN @@ -2934,14 +3033,6 @@ Closes all global data files open in the VIEW 21 @end example -@item @code{29} - Symbol Table Copy -Copies the primary symbol table's contents to the alternate symbol table. Takes no arguments. - -@emph{Syntax} -@example -VIEW 29 -@end example - @item @code{52} - Set G0 Input Translation Table for @code{$IO} @emph{Syntax} @@ -3090,30 +3181,6 @@ If @emph{tvexpr} evaluates to @emph{true VIEW 83:@emph{tvexpr} @end example -@item @code{87} - Date Type Definition -We believe this defines date formats for @code{$ZDATE}, but we have not yet figured out how it works. - -@emph{Syntax} -@example -; Syntax unknown -@end example - -@item @code{88} - Time Type Definition -We believe this defines time formats for @code{$ZTIME}, but we have not yet figured out how it works. - -@emph{Syntax} -@example -; Syntax unknown -@end example - -@item @code{91} - Set Default Expression for Missing @code{QUIT} Expression -Sets the default expression to be printed when a @code{QUIT} is encountered where a @code{QUIT} argument would be expected, but was not provided. We're not entirely sure what this does. - -@emph{Syntax} -@example -; Syntax unknown -@end example - @item @code{92} - Set Type Mismatch Error Flag on @code{EUR2DEM} If @emph{tvexpr} evaluates to @emph{true}, a type mismatch error will be thrown in @code{EUR2DEM} currency conversions in certain situations that we do not yet understand. @@ -3271,6 +3338,8 @@ DEFAULT.USER> WATCH ?^JPW(1) @cindex commands, non-standard @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. @emph{Syntax} @@ -3300,14 +3369,6 @@ In the above argumentless form, clears t @cindex 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 @section ZBREAK @cindex ZBREAK @@ -3317,14 +3378,6 @@ In the above argumentless form, clears t @cindex commands, non-standard @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 @section ZGO @cindex ZGO @@ -3826,25 +3879,6 @@ Returns or sets the current working dire @item @code{OPEN} +R -U -D The @code{^$JOB($JOB,"OPEN",} 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 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.