Returns the integer ASCII code for a character in the given string. For a mumps process started in UTF-8 mode, $ASCII() returns the integer Unicode® UTF-8 code-point value of a character in the given string.
The format for the ASCII is:
Example 1
Example 2
Returns a string of one or more characters corresponding to integer ASCII codes specified in its argument(s). For a process started in UTF-8 mode, $CHAR() returns a string composed of characters represented by the integer equivalents of the Unicode® code-points specified in its argument(s).
The format for the Char is:
Example 1
Returns an integer code describing the value and descendent status of a local or global variable.
The format for the Data is:
Example 1
Example 2
Example 3
Example 4
Returns a substring of a given string.
The format for the Extract is:
Example 1
Example 2
Returns an integer character position that locates the occurrence of a substring within a string.
The format for the Find is:
Example 1
Example 2
Returns a string containing a formatted number.
The format for the FNumber is:
Example 1
Example 2
Returns the value of a local or global variable if the variable has a value. If the variable has no value, the function returns a value specified by an optional second argument, and otherwise returns an empty string.
The format for the Get is:
Example 1
Example 2
Atomically adds (increments) a global variable by a numeric value. Note that increment is atomic, but the evaluation of the expression is not, unless inside a transaction (TStart/TCommit). The function also works on local variables, but has less benefit for locals as it does not (need to) provide ACID behavior.
The format for the Increment is:
Example 1
Example 2
Returns a formatted string.
The format for the Justify is:
Example 1
Example 2
Returns the length of a string measured in characters, or in "pieces" separated by a delimiter specified by one of its arguments.
The format for the Length is:
Example 1
Returns an evaluated representation of some or all of a local or global variable name.
The format for the Name is:
Example 1
Example 2
Returns the next subscripted local or global variable name in collation sequence within the array level specified by its argument.
$NEXT() has been replaced by $ORDER(). $NEXT has been retained in the current standard only for compatibility with earlier versions of the standard. $NEXT() is similar to $ORDER(). However, $NEXT() has the deficiency that when it encounters negative one (-1) as a subscript, it returns the same result as when it finds no other data at the level. This deficiency is particularly disruptive because it occurs in the middle of the M collating sequence.
The format for the Next is:
Example 1
Example 2
Returns the subscript of the next or prior local or global variable name in collation sequence within the array level specified by its first argument. In doing so, it moves in the direction specified by the second argument. In GT.M, when $ORDER() has an unsubscripted argument, it returns the next or previous unsubscripted local or global variable name in collating sequence.
The format for the Order is:
Example 1
Example 2
Example 3
Returns a substring delimited by a specified string delimiter made up of one or more characters. In M, $PIECE() returns a logical field from a logical record.
The format for the Piece is:
Example 1
Example 2
example1tbd
The format for the QLength is:
Example 1
Example 2
Returns a component of a variable name.
The format for the QSubscript is:
Example 1
Example 2
Returns the next subscripted local or global variable node name, independent of level, which follows the node specified by its argument in M collating sequence and has a data value.
The format for the Query is:
Example 1
Example 2
Returns a random integer from a range specified by its argument.
The format for the Random is:
Example 1
Example 2
Returns a string with the characters in the reverse order from that of its argument.
The format for the REverse is:
Example 1
Example 2
Returns a value associated with the first true truth-valued expression in a list of paired expression arguments.
The format for the Select is:
Example 1
Example 2
Returns strings describing aspects of the execution environment.
The format for the STack is:
Example 1
Example 2
Returns source text for the line specified by its argument.
The format for the Text is:
Example 1
Example 2
Returns a string that results from replacing or dropping characters in the first of its arguments as specified by the patterns of its other arguments.
The format for the TRanslate is:
Example 1
Returns information about an environmental factor selected by the arguments. In GT.M, the first argument contains a keyword identifying the environmental factor and, where appropriate, subsequent arguments select among multiple possible occurrences of that factor.
The format for the View is:
Example 1
Example 2
$ZAHANDLE() returns a unique identifier (handle) for the array associated with a name or an alias container; for an subscripted lvn, it returns an empty string. To facilitate debugging, the handle is a printable string representation of a hexadecimal number. The only meaningful operation on the value returned by a call to $ZAHANDLE() is to compare it for equality with the value returned by another call. Changing nodes within the array doesn't change its handle. $ZAHANDLE() returns different results for copies of an array.
The format for the ZAHandle is:
Example 1
Example 2
Returns the numeric byte value (0 through 255) of a given sequence of octets (8-bit bytes).
The format for the ZAscii is:
Example 1
Example 2
Returns the transformed representation of the first argument expr in a normalized form using the alternative transform specified by the second argument intexpr; the transformed representation can be used as an operand to the follows (]) or sorts-after (]]) operator such that, if both operands are in the normalized form, the result is independent of alternative collation.
The format for the ZATRansform is:
Example 1
Example 2
Returns a string composed of bytes represented by the integer octet values specified in its argument(s).
The format for the ZCHar is:
Example 1
Returns the transformed representation of the first argument glvn in a normalized form using the alternative transform specified by the second argument intexpr; the return can be used as an operand to the follows (]) or sorts-after (]]) operator such that, if both operands are in the normalized form, the result is independent of alternative collation.
The format for the ZCOllate is:
Example 1
Example 2
Returns its first argument as a string converted to a different encoding. The two argument form changes the encoding for case within a character set. The three argument form changes the encoding scheme.
The format for the ZCOnvert is:
Example 1
Example 2
Extends $DATA() to reflect the current alias state of the lvn or name argument to identify alias and alias container variables. It treats variables joined through pass-by-reference as well as TP RESTART variables within a transaction as alias variables. However, it does not distinguish nodes having alias containers among their descendants.
In addition to the four standard M results from $DATA(), $ZDATA() returns:
The format for the ZDATA is:
Example 1
Example 2
Returns a date and/or time formatted as text based on an argument formatted in the manner of $HOROLOG. For information on the format of $HOROLOG, refer to Chapter 8: “Intrinsic Special Variables.
The format for the ZDate is:
Example 1
Example 2
Returns a byte sequence from a given sequence of octets (8-bit bytes).
The format for the ZExtract is:
Example 1
Example 2
Returns an integer byte position that locates the occurrence of a byte sequence within a sequence of octets(8-bit bytes).
The format for the ZFind is:
Example 1
Example 2
Returns job or process information of the specified process.
The format for the ZGETJPI is:
Example 1
Example 2
Returns the full specification of the file into which the function places a ZSHOW "*". The return value serves as a way to save, to notify others of the exact location of the output, or to open the file for further processing. GT.M reports each $ZJOBEXAM() to the operator log facility with its file specification.
The optional expression argument is a template output device specification. It can be a device, a file directory, or a file name. The template is an expression that is pre-processed to create a file specification as the target for the ZSHOW. The preprocessing is equivalent to $ZPARSE(), as illustrated by the following M code:
set deffn="GTM_JOBEXAMINE.ZSHOW_DMP_"_$JOB_"_"_
$ZJOBEXAM() dump files contain the context of a process at the time the function executes. Placement and management of these files should consider their potential size and security implications.
The format for the ZJOBEXAM is:
Example 1
Example 2
Returns a formatted and fixed length byte sequence.
The format for the ZJustify is:
Example 1
Example 2
Returns the length of a sequence of octets measured in bytes, or in "pieces" separated by a delimiter specified by one of its arguments.
The format for the ZLength is:
Example 1
Returns a message string associated with a specified status code.
The format for the ZMessage is:
Example 1
Example 2
Expands a file name to a full pathname and then returns the full pathname or one of its fields (directory, name, or extension).
The format for the ZPARSE is:
Example 1
Example 2
Return a sequence of bytes delimited by a specified byte sequence made up of one or more bytes.
The format for the ZPIece is:
Example 1
Example 2
Provides a way to examine memory in the current process address space. Use of this function requires information about GT.M internals, which may change from release to release. Contact FIS support for information on techniques for using $ZPEEK() in largely release independent ways.
The $ZPEEK() function returns the contents of the memory requested as a string depending on the requested (or defaulted) formatting.
The format for the ZPEEK is:
Example 1
Example 2
The $ZPREVIOUS function returns the subscript of the previous local or global variable name in collation sequence within the array level specified by its argument. When $ZPREVIOUS() has an unsubscripted argument, it returns the previous unsubscripted local or global variable name in collating sequence.
The $ZPREVIOUS function provides compatibility with some other M implementations. The M Development Committee chose to implement this functionality with the optional second -1 argument of $ORDER(). Therefore, when a design requires this functionality $ORDER() has the advantage over $ZPREVIOUS of being part of the M standard.
The format for the ZPrevious is:
Example 1
Example 2
Returns information about a SOCKET device and its attached sockets.
The format for the ZSOCKET is:
Example 1
Example 2
Sends its string parameter to the system log and always returns TRUE (1). The text appears in the syslog with the same format as any other GT.M syslog message (that is, in the user.info log with GTM-MUMPS[pid]" or "GTM-MUPIP[pid]" prefix along with instance information where appropriate).
The format for the ZSYSLOG is:
Example 1
Example 2
The $ZQGBLMOD function enables an application to determine whether it can safely apply a lost transaction to the database. A lost transaction is a transaction that must be rolled off a database to maintain logical multisite consistency. $ZQGBLMOD() always applies to data-level (level-0) nodes.
The format for the ZQGBLMOD is:
Example 1
Example 2
The $ZSEARCH function attempts to locate a file matching the specified file name. If the file exists, it returns the file name; if the file does not exist, it returns the null string.
The format for the ZSEARCH is:
Example 1
Example 2
Sends a signal to a process.
The format for the ZSIGPROC is:
Example 1
Example 2
Returns a properly encoded string from a sequence of bytes.
The format for the ZSUBstr is:
Example 1
Example 2
Returns a byte sequence that results from replacing or dropping bytes in the first of its arguments as specified by the patterns of its other arguments.
The format for the ZTRanslate is:
Example 1
Example 2
Examine or load trigger definition.
The format for the ZTRIgger is:
Example 1
Example 2
The $ZTRNLNM function returns the value of an environment variable.The $ZTRNLNM function is analogous to the DCL Lexical function F$TRNLNM on OpenVMS.
The format for the ZTRNLNM is:
Example 1
Example 2
Returns the numbers of columns required to display a given string on the screen or printer.
The format for the ZWidth is:
Converts its first string argument to or from ZWRITE format (quoted graphics characters concatenated with $CHAR() representations of any non-graphic characters). The second integer expression controls the direction of conversion.
The format for the ZWRite is:
Example 1
Example 2
A series of functions beginning with $ZBIT lets you manipulate a bit stream. Internally, GT.M stores a bit stream in the form of a bit string. A bit string embeds a bit stream in such a way that the first byte specifies the number of trailing bits in the last byte that are not part of the bit-stream. In this way, GT.M is able to store bit-streams of lengths other than multiples of 8 bits in byte format. So for example, a first byte of value of zero (0) indicates that all of the bits in the last byte belong to the bit-stream, while a one (1) indicates the last bit is excluded and a seven (7) indicates that only the first bit in the last byte belongs to the bit-stream.
If you have to convert a character string into a bit string then add a leading byte to that character string so that all $ZBIT functions can recognize it. The most common and straightforward way of doing this is to concatenate a $CHAR(n) on the front of the character string, where the value of n is zero through seven (0-7) – most commonly zero (0). If you pass a bit string as an argument to a routine that is expecting a character string, then that caller routine must strip off the first (and possibly the last) byte so that it can recognize the character string.
This section contains the description of all $ZBIT function and an example of using $ZBIT functions to turn a character into a bit stream and return a coded value. However, the most appropriate use of these functions may include the formation of checksums, handling of bit-data (say pixels from a scan), or interfacing with a routine that requires bit-oriented arguments.
Performs a logical AND function on two bit strings and returns a bit string equal in length to the shorter of the two arguments (containing set bits in those positions where both of the input strings have set bits). Positions corresponding to positions where either of the input strings have a cleared bit, also have cleared bits in the resulting string.
The format for the ZBITAND is:
Example 1
Returns the number of ON bits in a bit string.
The format for the ZBITCOUNT is:
Example 1
Performs the analog of $FIND() on a bit string. It returns an integer that identifies the position after the first position equal to a truth-valued expression that occurs at, or after, the specified starting position.
The format for the ZBITFIND is:
Example 1
Example 2
Returns the value of a specified position in the bit string.
The format for the ZBITGET is:
Example 1
Example 2
Returns the length of a bit string, in bits.
The format for the ZBITLEN is:
Example 1
Example 2
Returns a copy of the bit string with each input bit position inverted.
The format for the ZBITNOT is:
Example 1
Example 2
Performs a bitwise logical OR on two bit strings, and returns a bit string equal in length to the longer of the two arguments (containing set bits in those positions where either or both of the input strings have set bits). Positions that correspond to positions where neither input string has a set bit have cleared bits in the resulting string.
The format for the ZBITOR is:
Example 1
Example 2
Returns an edited copy of the input bit string with a specified bit set to the value of the truth-valued expression.
The format for the ZBITSET is:
Example 1
Example 2
Returns a bit string of a specified length with all bit positions initially set to either zero or one.
The format for the ZBITSTR is:
Example 1
Example 2
Performs a bitwise exclusive OR on two bit strings, and returns a bit string equal in length to the shorter of the two arguments (containing set bits in those position where either but not both of the input strings have set bits). Positions that correspond to positions where neither or both input string has a set bit have cleared bits in the resulting string.
The format for the ZBITXOR is:
Example 1
Example 2