1 About_GTM
   GT.M Version 4.4

   UNIX Edition

   October 2003

   The information in this manual is subject to change without notice and
   should not be construed as a commitment by Sanchez Computer Associates.
   The software described in this manual is furnished under a license and
   may be used or copied only in accordance  with  the  terms  of  such  a
   license.

   Copyright 1987 - 2003

   Sanchez Computer Associates

   All rights reserved

   GT.M, and GT.CM are trademarks  of  Sanchez  Computer  Associates.  All
   other company and product names may be  trademarks  of  the  respective
   companies with which they are associated.

1 Prog_Dev_Cycle
   Program Development Cycle

   In contrast to M environments that interpret M code,  GT.M  compiles  M
   code from source files into  the  target  machine  language.  The  GT.M
   compiler produces object files, which are dynamically  linked  into  an
   image. Source files and object files may be managed  independently,  or
   placed together in a specific directory. GT.M permits access to source
   and object files in multiple directories.

   GT.M databases are UNIX files identified  by  a  small  file  called  a
   Global Directory. Global Directories allow management of  the  database
   files to  be  independent  of  the  placement  of  files  containing  M
   routines. By changing the  Global  Directory,  you  can  use  the  same
   programs to access different databases.

   Program development may utilize both GT.M and UNIX  development  tools.
   The development methodology and environment  chosen  for  a  particular
   installation, and tailored  by  the  individual  user,  determines  the
   actual mix of tools. These tools  may  vary  from  entirely  GT.M  with
   little UNIX, to mostly UNIX with a modest use of GT.M.

   Direct Mode serves as an interactive interface  to  the  GT.M  run-time
   environment and the  compiler.  In  Direct  Mode,  the  user  enters  M
   commands at the  GT.M  prompt,  and  GT.M  compiles  and  executes  the
   command. This feature provides immediate turnaround for  rapid  program
   development and maintenance.

        The methods described in the GT.M column assume you are already at
        the GTM> prompt, which is also called Direct Mode. To get  to  this
        prompt, type $gtm_dist/mumps -direct.

2 Def_Env_Var
   Defining Environment Variables

   GT.M requires the definition of certain environment variables  as  part
   of setting up the environment.

   o    To locate the files that Sanchez Computer  Associates  provides  as
        part of GT.M

   o    To hold  some  user-controlled  information  which  GT.M  uses  for
        run-time operation

   The procedure below describes how to define  an  environment  variable.
   Use this procedure to define an  environment  variable  either  at  the
   shell prompt or in your shell startup file. If you define the variable
   at the shell prompt, it will be effective only until you logout. If you
   define it in your .profile file (.cshrc, if using a C  shell  variant),
   it will be in effect whenever you log in. Your system manager may have
   already defined some of these variables.

        Each  environment  variable  required  by  GT.M  is  described  and
        illustrated in individual sections following  the  procedure.  Only
        gtm_dist,  and  in  some  cases  gtmgbldir,  gtm_principal  and
        gtmroutines, are required by users who do not  perform  programming
        activities.

   To define an environment variable type the following commands:

$ env_variable=env_variable_value
$ export env_variable
   The following environment variables hold  information  that  determines
   some details of GT.M  run-time  operation,  over  which  the  user  has
   control.

3 gtm_dist
   gtm_dist

   gtm_dist is used to  establish  the  location  of  the  installed  GT.M
   program and support files.

   The syntax for gtm_dist is as follows:


   $ gtm_dist=<GT.M-distribution-directory>

   The standard installation places these files in /gtm/bin.

   Example:


   $ gtm_dist=/usr/staff/smith/GTM.dist

   $ export gtm_dist

   This  identifies  /usr/staff/smith/GTM.dist  as  the  location  of  the
   installed GT.M files.

   Add gtm_dist to your PATH environment variable to have UNIX search the
   GT.M installation directory (when processing a command to  activate  or
   run an image). This allows you  to  activate  GT.M  and  the  utilities
   without explicitly specifying a path.

   To add gtm_dist to your PATH type the following commands:


   $ PATH=$PATH:$gtm_dist

   $ export PATH

        Most of the examples in this manual  assume  that  you  have  added
        gtm_dist to your PATH.

3 gtmgbldir
   gtmgbldir

   gtmgbldir defines the path to a Global Directory.  A  Global  Directory
   maps global variables to physical database files, and  is  required  to
   locate M global variables. gtmgbldir provides  the  initial  value  for
   $ZGBLDIR,  the  intrinsic  special  variable  that  connects  the  GT.M
   run-time system to the Global Directory. It also  connects  the  Global
   Directory to the utilities requiring one.

   If you maintain multiple global directories, define  gtmgbldir  to  the
   Global Directory you currently want to use.

   The syntax of a gtmgbldir definition is:


   $ gtmgbldir=/directory/filename.gld

   Example:


   $ gtmgbldir=/usr/staff/mumps.gld

   $ export gtmgbldir

   This specifies  /usr/staff  as  the  directory  containing  the  Global
   Directory file named mumps.gld.

3 gtm_principal
   gtm_principal

   The  gtm_principal  environment  variable  specifies  the  value  for
   $principal, which designates the absolute pathname of the principal $IO
   device. This is an MDC Type A enhancement to standard M.

   The following is an example of gtm_principal definition:


   $ gtm_principal=/usr/filename

   $ export gtm_principal

   This specifies the /usr/filename as the principal $IO device, effective
   until changed further or until you logout of the particular session.

3 gtmroutines
   gtmroutines

   The  gtmroutines  environment  variable  specifies  a  search  list  of
   possible locations for M routines. This value  is  used  to  initialize
   $ZROUTINES, (the intrinsic special variable that enables GT.M  to  find
   the routine (program) you want to run).  gtmroutines  is  required  for
   ZLINKing.  gtmroutines  is  particularly  helpful  in  calling  percent
   utilities and the Global Directory Editor (GDE), which are in gtm_dist.

   $ gtmroutines="directories in search list"

   The directories in the search list must be separated  by  a  space  and
   enclosed in quotation marks (" "). Environment variables  are  accepted
   in the search list.

   The following is an example of gtmroutines definition:


   $ gtmroutines=". $gtm_dist"

   $ export gtmroutines

   This specifies that GT.M search for a  routine  first  in  the  current
   directory (.), then in the distribution directory (which is identified
   by the environment variable gtm_dist). The  distribution  directory  is
   included in the list because it contains the percent routines. You will
   probably want the search list to contain these two items at a minimum.
   In addition, you may want to add directories of your own.

3 Editor
   Editor

   The EDITOR environment variable specifies the  UNIX  text  editor  used
   when editing a routine either from the shell or with ZEDIT. Since this
   is a standard part of establishing  your  UNIX  environment,  you  will
   probably only need to define this when you  want  to  use  a  different
   editor than the one defined in your shell startup file.

   Example:


   $ EDITOR=/usr/bin/vi

   $ export EDITOR

   This defines the current text editor to vi.

2 Prep_the_DB
   Preparing the Database

   GT.M databases consist of one or more UNIX files. Most  database  files
   have a UNIX file structure externally and  a  GT.M  Database  Structure
   (GDS) internally. Management of the GDS  files  by  the  GT.M  run-time
   system assures high performance and integrity. GT.M database files are
   coordinated by a Global  Directory.  The  Global  Directory  identifies
   which global names belong in which files, and  specifies  the  creation
   characteristics for each file. To specify access to a database, each M
   process must define the gtmgbldir environment variable to point to the
   associated Global Directory.

   To define and maintain a Global Directory,  use  the  Global  Directory
   Editor (
   GDE) utility. The GDE utility automatically  upgrades  existing  global
   directories to the current format.The MUPIP  command  CREATE  uses  the
   characteristics as defined  in  the  Global  Directory  to  create  the
   associated database. In a production environment,  the  system  manager
   typically maintains Global Directories.

   For more information on GDE and MUPIP refer to  the  "Global  Directory
   Editor" and "MUPIP" chapters in the GT.M Administration and Operations
   Guide .

   Example:

   This example is a sequence of events that illustrate  steps  you  might
   typically perform in creating a new global directory,  in  our  example
   PAYROLL.GLD. To assist you in following the sequence, each actual step
   appears in typewriter font, as you might see on your  terminal  screen,
   followed by an explanation in normal text font.


   $ ls payroll.gld


   payroll.gld not found

   The ls command verifies that there are no existing files with the name


   payroll.gld.

   $ gtmgbldir=payroll.gld

   $ export gtmgbldir

   This  establishes  the  current  value  of  the  environment  variable
   gtmgbldir as payroll.gld. GT.M uses gtmgbldir to identify  the  current
   Global Directory. When defined at the shell prompt, gtmgbldir maintains
   the defined value only for the current login session. The next time you
   log into UNIX,  you  must  again  define  the  value  of  gtmgbldir  as
   payroll.gld to use it as the current Global Directory.

   This example defines gtmgbldir without a full pathname. The environment
   variable  points  to  the  payroll.gld  file  in  the  current  working
   directory. Therefore if the default directory changes, GT.M attempts to
   locate the Global Directory in the new default directory and cannot use
   the  original  file.  If  you  intend  for  the  Global  Directory  to
   consistently point to this file, even if the default directory changes,
   use a full file-specification for gtmgbldir.


   $ gtm

   GTM>d ^GDE

   %GDE-I-GDUSEDEFS, Using defaults for Global Directory

   /staff/payroll.gld

   GDE>

   This invokes the Global Directory  Editor  from  the  GT.M  prompt  and
   produces an informational message. Refer to  the  "Program  Development
   Cycle" in GT.M Programmer's Guide for more details.

   Example:


   $ mupip load payroll.gld

   GT.M

   09-OCT-2001 11:26:44
   keycnt: 100 max subsc len:12 max data len: 3

   Last record number: 202

   This uses the MUPIP LOAD command to load a  sequential  file  into  the
   database.

   Because MUPIP uses the  environment  variable  gtmgbldir  to  locate  a
   Global Directory, which  identifies  the  database  file(s),  the  LOAD
   command does not require any information  about  the  target  database.
   With few exceptions, the GT.M utilities work in the same way.

        For general information on shareable libraries in HP-UX,  refer  to
        the "Programming on HP-UX" manual.
        Refer to the documentation accompanying AIX for more information on
        shareable libraries on AIX.

   entryref: return-value routine-name

   (parameter, parameter, ..)
   where entryref is an M entryref,

   return-value is xc_long_t, xc_status_t, or void

   and parameter are in the format: direction:type.

   len: void length (I:xc_float_t*, o:xc_float_t*)

   Example:

   % echo $GTMXC_mathpak

2 Cre_Edt_Source_Prog
   Creating and Editing a Source Program

   The first step in developing a GT.M program is to create a source file.
   In most cases, the user can create  and  modify  GT.M  source  programs
   using UNIX text editors.

   When the program is very simple (and its lines  do  not  need  revision
   after they are entered), you can use the cat command  to  direct  input
   from your terminal to your source file.

3 Edit_from_GTM
   Editing from GT.M

   Invoke Direct Mode to create and edit a source program in GT.M. At the
   GTM> prompt, invoke the editor by typing:

   ZEDIT <filename>

   ZEDIT invokes the editor specified by the EDITOR environment variable,
   which creates a seperate file for each M source module.

   The GT.M environment works most efficiently if the file  has  the  same
   name as the M routine it contains, and has an .m extension. Since ZEDIT
   automatically defaults the.m extension, it is not necessary to specify
   an extension unless you require a different one.  If  you  use  another
   extension, you must specify that extension with every reference to the
   file. Multiple character file extensions are  permitted  for  M  source
   file names.

3 Edit_from_Shell
   Editing from the Shell

   To create and edit a source program from the  shell,  invoke  any  text
   editor at the shell prompt and specify a UNIX file as the  source.  The
   GT.M environment works best when you give a file  the  name  of  the  M
   routine that it contains, and an .m extension.

   Example:

   $ vi payroll.m

   The vi command initiates an editing  session  for  payroll.m  from  the
   shell prompt. If payroll.m does  not  already  exist,  vi  creates  it.
   Because this example uses UNIX rather than GT.M tools, we must specify
   the .m file extension.

2 Comp_Source_Prog
   Compiling a Source Program

   GT.M compiles M  source  code  files  and  produces  object  files  for
   complete integration into the UNIX enviroment. The object modules have
   the same name as the compiled M source file with an .o file extension,
   unless  otherwise  specified.  The  object  files  contain  machine
   instructions and information necessary  to  connect  the  routine  with
   other routines, and map it into memory. An M routine source  file  must
   be compiled after it is created or modified. You can compile explicitly
   with the ZLINK command or implicitly  with  auto-ZLINK.  At  the  shell
   command line, compile by issuing the mumps command.

   The compiler checks  M  code  for  syntax  errors  and  displays  error
   messages on the terminal,  when  processing  is  complete.  Each  error
   message provides the source line in error with an indicator pointing to
   the place on the line where the error is  occurring.  For  a  list  and
   description of the compiler error messages, refer to the  GT.M  Message
   and Recovery Procedures Reference Manual.

   You can generate a listing  file  containing  the  compile  results  by
   including the
   -list qualifier as a modifier to the argument to the ZLINK  command  in
   Direct Mode. This can also be done by redirecting the compiler messages
   to a file by adding >filename 2>&1 to the mumps command when compiling
   a program from the shell. Refer  to  the  "Compiling  from  the  Shell"
   section for an explanation of the M command describing -list, and other
   valid qualifiers for the M and ZLINK commands.

   The compiler stops processing a routine line when it detects  an  error
   on that line. Under most conditions the compiler  continues  processing
   the remaining routine lines. This allows the compiler to produce a more
   complete error analysis of the routine and to generate  code  that  may
   have valid executable paths. The  compiler  does  not  report  multiple
   syntax errors on the same line. When it detects more  than  127  syntax
   errors in a source file, the compiler ceases to process the file.

3 Comp_from_GTM
   Compiling from GT.M

   In Direct Mode, GT.M provides access to the compiler explicitly through
   the ZLINK and  ZCOMPILE  commands,  and  implicitly  through  automatic
   invocation of ZLINK functionality (auto-ZLINK) to add required routines
   to the image. ZCOMPILE  is  a  GT.M  routine  compilation  command,  it
   compiles the routine and creates a new object module. The primary task
   of ZLINK is to place the object code in memory and  "connect"  it  with
   other routines. However, under certain circumstances, ZLINK  may  first
   use the GT.M compiler to create a new object module.

   The difference between ZCOMPILE and ZLINK is that  ZCOMPILE  creates  a
   new object module on compiling, whereas the  ZLINK  command  links  the
   object module with other routines and places the object code in memory.


   ZLINK compiles under these circumstances:

   o    ZLINK cannot locate a copy of the object module but  can  locate  a
        copy of the source module.

   o    ZLINK can locate both object  and  source  module,  and  finds  the
        object module to be older than the source module.

   o    The file-specification portion of the ZLINK  argument  includes  an
        explicit extension of .m.

   Auto-ZLINK compiles under the first two circumstances,  but  can  never
   encounter the last one.

   When a command refers to an M routine that is not part of  the  current
   image, GT.M automatically attempts to ZLINK and, if necessary, compile
   that routine. In Direct Mode, the most  common  method  to  invoke  the
   compiler through an auto-ZLINK is to enter DO ^routinename at the GTM>
   prompt. When the current image does not contain the routine, GT.M does
   the following:

   o    Locates the source and object

   o    Determines whether the source has been edited  since  it  was  last
        compiled

   o    Compiles the routine, if appropriate

   o    Adds the object to the image

   By using the DO command, you implicitly instruct GT.M to compile, link,
   and execute the program. With this method, you can  test  your  routine
   interactively.

   For complete  descriptions  of  ZLINK  and  auto-ZLINK,  refer  to  the
   "Commands" chapter in GT.M Programmer's Guide.

   Example:


   GTM>do ^payroll

   GTM>do ^taxes

   This uses the M DO command to invoke the GT.M compiler implicitly from
   the GTM> prompt if the routine  requires  new  object  code.  When  the
   compiler runs, it produces  two  object  module  files,  payroll.o  and
   taxes.o.

   If you receive error messages from the compilation, you  may  fix  them
   immediately by returning to the editor and correcting  the  source.  By
   default, the GT.M compiler operates in "compile-as-written"  mode,  and
   produces object code even when a routine contains syntax  errors.  This
   code includes all lines that are correct and all  commands  on  a  line
   with an error, up to the error. Therefore, you may decide to tailor the
   debugging cycle by running the  program  without  removing  the  syntax
   errors.

3 Comp_from_Shell
   Compiling from the Shell

   From the shell, invoke the compiler by entering mumps file-name at the
   shell prompt.

   Example:


   $ mumps payroll.m

   $ mumps taxes.m

   This uses the mumps command to invoke the GT.M compiler from the shell
   prompt, and creates .o versions of these files.

   Use the mumps command at the shell prompt to:

   o    Check the syntax of a newly entered program.

   o    Optionally, get a formatted listing of the program.

   o    Ensure that all object code is up to date before linking.

   The mumps command invokes the compiler to translate an  M  source  file
   into object code.

   The format for the MUMPS command is:

   MUMPS [-qualifier[...]] pathname

   o    Source programs must have an extension of .m.

   o    Each pathname identifies an M source program to compile.

   o    Qualifiers determine characteristics of the compiler output.

   o    Qualifiers must appear after the command, but before the file name
        to be properly applied.

   o    GT.M allows the UNIX * and ? wildcards in a file name.

   The * wildcard accepts any legal combination of numbers and characters
   including a null, in the position the wildcard holds.
   The ? wildcard accepts exactly one legal character in its position.

   For example, mumps *.m  compiles  all  files  in  the  current  default
   directory with an .m extension. mumps *pay?.m compiles  .m  files  with
   names that contain any characters followed  by  pay,  followed  by  one
   character. Unlike when using ZLINK or ZCOMPILE, the  filename  must  be
   fully specified when compiling from the shell.

1 Opr_Dbg_Dir_Mode
   Operating and Debugging in Direct Mode

   Direct Mode is an important tool in  GT.M  because  it  allows  you  to
   interactively debug, modify, and execute M routines. Direct Mode  is  a
   shell that immediately compiles and executes GT.M commands providing an
   interpretive-like interface. M simplifies debugging by using  the  same
   commands for debugging that are used for programming.

   The focus of this chapter is  to  describe  the  debugging  process  in
   Direct Mode, and  to  illustrate  the  GT.M  language  extensions  that
   enhance the process. Command functionality is described only in enough
   detail to illustrate why a particular command is useful for a debugging
   activity being described. If you have specific functionality questions
   about a command or variable, refer to the  "Commands",  "Functions"  or
   "Intrinsic Special Variables" chapters in GT.M Programmer's Guide.

2 Opr_Dir_Mode
   Operating in Direct Mode

   This section provides an overview of the  following  basic  operational
   issues in Direct Mode:

   o    Entering Direct Mode

   o    Available functionality

   o    Exiting Direct Mode

3 Entr_Dir_Mode
   Entering Direct Mode

   To enter Direct Mode, type $gtm_dist/mumps -direct at the shell prompt.

   Example:


   $ $gtm_dist/mumps -direct

   GTM>

   This shows using $gtm_dist/mumps -direct at the prompt to enter Direct
   Mode.

   To create a gtm alias in your shell startup file (in the example below
   the startup file is assumed to be a .profile file):

   o    Open an edition session for your .profile file by typing:
	$vi .profile

   o    Add a function to the file to define your gtm alias
   o    	gtm()
	{
	  $gtm_dist/mumps -direct
	}

   o    save the file.

   Now, when you want to enter Direct Mode for  an  editing  or  debugging
   session, simply type gtm at the shell prompt.

   Example:

   $ gtm

   GTM>

   This shows that the gtm alias typed at the shell prompt also takes you
   to the Direct Mode.

3 Func_in_Dir_Mode
   Functionality Available in Direct Mode

   This section provides an overview of basic functionality  and  concepts
   that enhance your use of Direct Mode.

4 Comm_Recall
   Command Recall

   Direct  Mode  includes  a  line  command  recall  function  to  display
   previously entered command lines. Use the Up  Arrow  key  at  the  GTM>
   prompt to scroll back through command lines. Usethe Down Arrow  key  to
   scroll forward through the command lines.  GT.M  displays  one  command
   line at a time. You may delete and reenter characters starting  at  the
   end of a recalled line.

   The RECALL command is another way to access previously  entered  Direct
   Mode command lines. RECALL is only valid in Direct Mode and  causes  an
   error if it appears in other M code.

   The format of the
   RECALL command is:


   REC[ALL] [intlit|strlit]

   o    The optional integer literal specifies a previously entered command
        by the counting back from the present.

   o    The optional string literal specifies  the  most  recently  entered
        command  line  that  starts  with  characters  matching  the
        (case-sensitive) literal.

   o    When the RECALL command has  no  argument,  it  displays  up  to  a
        maximum of 99 available past Direct Mode entries.

   If the Direct Mode session has just started, you may not  have  entered
   99 lines for GT.M to save and therefore you will not have 99  lines  to
   look at. The most recently entered GT.M command line has the number one
   (1), older lines have higher numbers. GT.M does not include the RECALL
   command in the listing. If the RECALL command is issued from a location
   other than the Direct Mode prompt, GT.M issues a run-time error.

   Example:


   GTM>WRITE $ZGBLDIR

   M.GLD

   GTM>SET $ZGBLDIR TEST.GLD

   GTM>SET A=10

   GTM>SET B=A

   GTM>REC

   1 SET B=A
   2 SET A=10
   3 SET $ZGBLDIR TEST.GLD
   4 WRITE $ZGBLDIR
   This REC[ALL] command displays the previously entered commands.

   You can also display a selected command by entering RECALL and the line
   number of the command you want to retrieve.

   Example:


   GTM>REC 2

   GTM>SET A=10

   This RECALLs the line number two (2).

   If the RE[CALL] command includes a text parameter,  GT.M  displays  the
   most recent command matching the text after the RE[CALL] command.

   Example:


   GTM>REC WRITE

   GTM>WRITE $ZGBLDIR

   MUMPS.GLD

   This RECALLs "WRITE", the command most  recently  beginning  with  this
   text. Note that the RECALL command text is case sensitive.  The  RECALL
   command with a text argument treats WRITE and write  differently,  that
   is, it treats them case  sensitively.  If  you  first  type  the  WRITE
   command in lower-case and then type WRITE in upper-case to  recall  it,
   the RECALL command does not find a match.

4 Line_Editing
   Line Editing

   GT.M permits the use of the GT.M command line editor at the Direct Mode
   prompt and during M READs from a terminal. The GT.M line editor allows
   cursor positioning using the <CTRL> key, edit keypad and function keys.

   The GT.M Direct Mode line editing keys are as follows:


        Backspace Deletes the character to the left of the cursor
        Delete Same as backspace
        Up-arrow Moves to a less recent item in the RECALL list
        Down-arrow Moves to a more recent item in the RECALL list
        Left-arrow Moves the cursor one character to the left
        Right-arrow Moves the cursor one character to the right
        <CTRL-A> Moves the cursor to the beginning of the line
        <CTRL-B> Moves the cursor one character towards  the  beginning  of
        the line
        <CTRL-D> Deletes the character at the cursor position
        <CTRL-E> Moves the cursor to the end of the line
        <CTRL-F> Moves the cursor one character towards the end of the line
        <CTRL-K> Deletes all characters from the cursor to the end  of  the
        line
        <CTRL-U> Deletes the entire line
4 M_Invo_Stack
   The M Invocation Stack

   The ANSI M Standard describes certain M operations in terms  of  how  a
   stack-based virtual machine would operate. A stack is a repository for
   tracking temporary information on a "last-in/first-out" (LIFO) basis. M
   program behavior can be understood using a stack-based model. However,
   the standard is not explicit in defining  how  an  implementation  must
   maintain a stack or even whether it must use one at all.

   The stack model provides a trail of routines currently in progress that
   shows  the  location  of  all  the  M  operations  that  performed  the
   invocations leading to the current point.

3 Exit_Dir_Mode
   Exiting Direct Mode

   Four M commands terminate a Direct Mode session:

   o    HALT

   o    ZCONTINUE

   o    GOTO

   o    ZGOTO

   The
   HALT command exits Direct Mode and terminates the M process.

   The
   ZCONTINUE command instructs GT.M to exit Direct Mode and resume routine
   execution at the current point in the M invocation stack. This  may  be
   the point where GT.M interrupted execution  and  entered  Direct  Mode.
   However, when the Direct Mode interaction includes a QUIT  command,  it
   modifies the invocation stack and causes ZCONTINUE to resume execution
   at another point.

   The
   GOTO and
   ZGOTO commands instruct GT.M to leave Direct Mode, and transfer control
   to a specified entry reference.

2 Debug_Rtn_Dir_Mode
   Debugging a Routine in Direct Mode

   To begin a debugging session on a specific routine, type the following
   command at the GTM prompt:


   GTM>DO ^routinename

   You can also begin a  debugging  session  by  pressing  <CTRL-C>  after
   running an M application  at  the  shell.  To  invoke  Direct  Mode  by
   pressing <CTRL-C>, process  must  have  the  Principal  Device  in  the
   CENABLE state and not have the device set to CTRAP=$C(3).

   When GT.M receives a <CTRL-C> command from  the  principal  device,  it
   invokes Direct Mode at  the  next  opportunity,  (usually  at  a  point
   corresponding to the beginning of the next source line). GT.M can also
   interrupt at a FOR loop iteration or during a command of indeterminate
   duration such as  JOB,  LOCK,  OPEN  or  READ.  The  GT.M  USE  command
   enables/disables  the  <CTRL-C>  interrupt  with  the  [NO]CENABLE
   deviceparameter. By default, GT.M starts <CTRL-C> enabled. The default
   setting for <CTRL-C> handling is controlled by GTM$DEFAULTS.M64 and is
   enabled in the distribution version of that file.

   GT.M displays the GTM> prompt on  the  principal  device.  Direct  Mode
   accepts commands from, and reports errors  to,  the  principal  device.
   GT.M uses the current device for all other I/O. If the  current  device
   does not match the principal device when GT.M enters Direct Mode, GT.M
   issues a warning message on the principal device. A USE command changes
   the current device. For more information on the USE command,  refer  to
   the "Input/Output Processing" chapter.

   The default "compile-as-written" mode of the GT.M compiler lets you run
   a program with errors as part of the debugging cycle. The  object  code
   produced includes all lines that are correct and all commands on a line
   with an error, up to the error.  When  GT.M  encounters  an  error,  it
   XECUTEs non empty  values  of  $ETRAP  or  $ZTRAP.  By  default  $ZTRAP
   contains a BREAK command, so GT.M enters Direct Mode.

   The rest of the chapter illustrates the debugging capabilities of GT.M
   by taking a sample routine, dmex, through the debugging  process.  dmex
   is intended to read and edit a name, print the last and first name, and
   terminate if the name is an upper-case or lower-case "Q".

   Each of the remaining sections of the chapter uses dmex  to  illustrate
   an aspect of the debugging process in GT.M.

3 Creat_Display_M_Rtn
   Creating and Displaying M Routines

   To create or edit a routine, use the
   ZEDIT command.  ZEDIT  invokes  the  editor  specified  by  the  EDITOR
   environment  variable,  and  opens  the  specified  file.  dmex.m,  for
   editing.

   Example:


   GTM>ZEDIT "dmex"

   Once in the editor, use the standard editing commands to enter and edit
   text. When you finish editing, save the changes, which returns  you  to
   Direct Mode.

        For further details and examples, refer to  the  GT.M  Programmer's
        Guide.

3 Exec_M_Rtn_Inter
   Executing M Routines Interactively

   To  execute  an  M  routine  interactively,  it  is  not  necessary  to
   explicitly compile and link your  program.  When  you  refer  to  an  M
   routine that is not part  of  the  current  image,  GT.M  automatically
   attempts to compile and
   ZLINK the program.

   Example:


   GTM>DO ^dmex

   Name: Revere, Paul

   %GTM-E-UNDEF, Undefined local variable: bame

   At M source location name+3^dmex

   GTM>

   In this example GT.M places you in Direct Mode, but also cites an error
   found in the program with a run-time error message. In this example, it
   was a reference to bame, which is undefined.

   To see additional information about the error message, examine the
   $ECODE or
   $ZSTATUS special variables.

   $ECODE is read-write intrinsic special variable that maintains  a  list
   of comma delimited codes that describe a history of past errors  -  the
   most recent ones appear at the end of the  list.  In  $ECODE,  standard
   errors are prefixed with an "M", user defined errors with  a  "U",  and
   GT.M errors with a "Z". A GT.M code always follows a standard code.

   $ZSTATUS is a read-write intrinsic special variable  that  maintains  a
   string containing the error condition code and  location  of  the  last
   exception condition occurring during routine  execution.  GT.M  updates
   $ZSTATUS only for errors found in routines and not for  errors  entered
   at the Direct Mode prompt.

        For further details and examples, refer to  the  GT.M  Programmer's
        Guide.

3 Proc_with_Runtime_Syn_Err
   Processing with Run-time and Syntax Errors

   When GT.M encounters a run-time or syntax error, it stops executing and
   displays an error message. GT.M reports the error in  the  message.  In
   this case, GT.M reports an undefined local variable  and  the  line  in
   error, name+3^dmex. Note that GT.M re-displays the GTM> prompt so that
   debugging may continue.

   To re-display the line and identify the error, use the
   ZPRINT command.

   Example:


   GTM>ZPRINT, name+3

   %GTM-E-SPOREOL, Either a space or an end-of-line was expected  but  not
   found
   ZP, name+3

   ^_____

   GTM>

   This example shows the result of incorrectly entering a ZPRINT command
   in Direct Mode. GT.M reports the location of the syntax  error  in  the
   command line with an arrow. $ECODE and $ZSTATUS do  not  maintain  this
   error message because GT.M did not produce the message  during  routine
   execution. Enter the  correct  syntax,  (i.e.,  remove  the  comma)  to
   re-display the routine line in error.

   Example:


   GTM>WRITE $ZPOS

   name+3^dmex

   This example writes the current line position.

   $ZPOSITION is a read-only GT.M special variable that  provides  another
   tool for locating and displaying the  current  line.  It  contains  the
   current  entry  reference  as  a  character  string  in  the  format
   label+offset^routine, where the label is the closest  preceding  label.
   The current entry reference appears at the top of the
   M invocation stack, which can also be displayed with a
   ZSHOW "S" command.

   To display the current value of every local variable defined, use the
   ZWRITE command with no arguments.

   Example:


   GTM>ZWRITE

   ln=12

   name="Revere, Paul"

   This ZWRITE displays a listing of all  the  local  variables  currently
   defined.

        ZWRITE displays the variable name. ZWRITE does not display a value
        for bame, confirming that it is not defined.

3 Correcting_Errors
   Correcting Errors

   Use the
   ZBREAK command to establish  a  temporary  breakpoint  and  specify  an
   action. ZBREAK sets or clears  routine-transparent  breakpoints  during
   debugging. This command simplifies debugging by interrupting execution
   at a specific point to examine variables, execute commands, or to start
   using
   ZSTEP to execute the routine line by line.

   GT.M suspends execution  during  execution  when  the  entry  reference
   specified by ZBREAK is encountered. If the ZBREAK does not  specify  an
   expression "action", the process uses the default,
   BREAK, and puts GT.M into Direct Mode. If the ZBREAK  does  specify  an
   expression "action", the process XECUTEs the  value  of  "action",  and
   does not enter Direct Mode unless the  action  includes  a  BREAK.  The
   action serves as a "trace-point". The trace-point is silent unless the
   action specifies terminal output.

   Example:


   GTM>ZBREAK name+3^dmex:"set bame=name"

   This uses a ZBREAK with an action that SETs the variable bame equal to
   name.

3 Stepping_Thru_Rtn
   Stepping Through a Routine

   The
   ZSTEP command provides a powerful tool to direct GT.M  execution.  When
   you issue a ZSTEP from Direct Mode, GT.M executes the  program  to  the
   beginning of the next target line and performs the ZSTEP action.

   The optional keyword portion of the argument  specifies  the  class  of
   lines where ZSTEP pauses its execution, and XECUTEs  the  ZSTEP  action
   specified by the optional action portion of the ZSTEP argument. If the
   action is specified, it must be an expression that evaluates  to  valid
   GT.M code. If no action is specified, ZSTEP XECUTEs the code specified
   by the $ZSTEP intrinsic special variable; by  default  $ZSTEP  has  the
   value "B", which causes GT.M to enter Direct Mode.

   ZSTEP actions, that include commands followed by a BREAK,  perform  the
   specified action, then enter Direct Mode. ZSTEP  actions  that  do  not
   include a BREAK perform the command action and continue execution. Use
   ZSTEP actions that issue conditional BREAKs and  subsequent  ZSTEPs  to
   perform tasks such as test for changes in the value of a variable.

   Use ZSTEP to incrementally execute a routine or a series  of  routines.
   Execute any GT.M command from Direct Mode at any ZSTEP pause. To resume
   normal execution, use ZCONTINUE. Note that ZSTEP arguments are keywords
   rather than expressions, and they do not allow indirection.

   Example:


   GTM>ZSTEP INTO

   Break instruction encountered during ZSTEP action

   At M source location print^dmex

   GTM>ZSTEP OUTOF

   Paul Revere

   Name: Q

   %GTM-I-BREAKZST, Break instruction encountered during ZSTEP action

   At M source location name^dmex

   GTM>ZSTEP OVER

   Break instruction encountered during ZSTEP action

   At M source location name+1^dmex

   This example shows using the ZSTEP command to step through the routine
   dmex,  starting  where  execution  was  interrupted  by  the  undefined
   variable error.  The  ZSTEP  INTO  command  executes  line  name+3  and
   interrupts execution at the beginning of line print.

   The ZSTEP OUTOF continues execution until line name.  The  ZSTEP  OVER,
   which is the default, executes until it encounters  the  next  line  at
   this level on the M invocation stack. In this case, the  next  line  is
   name+1. The ZSTEP OVER could be replaced with a ZSTEP with no argument
   because they do the same thing.

3 Cont_Exec_Frm_Breakpt
   Continuing Execution From a Breakpoint

   Use the
   ZCONTINUE command to continue execution from the breakpoint.

   Example:


   GTM>ZCONTINUE

   Paul Revere

   Name: q

   Name: QUIT

   Name: ?

   Please use last-name, first name middle-initial

   or 'Q' to Quit.

   Name:

   This uses a ZCONTINUE command to resume execution from the point where
   it was interrupted. As a result of the ZBREAK action, bame  is  defined
   and the error does not  occur  again.  Because  the  process  does  not
   terminate as intended when the name read has q as a value, we  need  to
   continue debugging.

3 Interr_Execution
   Interruption Execution

   Press <CTRL-C> to interrupt execution, and return to the GTM prompt to
   continue debugging the program.

   Example:


   %GTM-I-CTRLC, CTRLC_C encountered.

   GTM>

   This invokes direct mode with a <CTRL-C>.

3 Using_Invoc_Stac_in_Debug
   Using the Invocation Stack in Debugging

   M DOs, XECUTEs, and extrinsics add a level  to  the  invocation  stack.
   Matching QUITs take a level off the stack. When GT.M executes either of
   these  commands,  an  extrinsic  function,  or  an  extrinsic  special
   variable, it "pushes" information about  the  new  environment  on  the
   stack. When GT.M executes the
   QUIT, it "pops" the information about the discarded environment off the
   stack. It then reinstates the invoking routine  information  using  the
   entries that have now arrived at the active end of the stack.

        In the M stack model, a
        FOR command does not add a stack frame, and a QUIT that terminates
        a FOR loop does not remove a stack frame.

4 Deter_Levels_of_Nest
   Determining Levels of Nesting

   $STACK contains an integer value  indicating  the  "level  of  nesting"
   caused by DO commands, XECUTE commands, and extrinsic functions in the
   M virtual stack.

   $STACK has an initial value of zero (0), and  increments  by  one  with
   each DO,  XECUTE,  or  extrinsic  function.  Any  QUIT  that  does  not
   terminate a FOR  loop  or  any  ZGOTO  command  decrements  $STACK.  In
   accordance with the M standard, a FOR command does not increase $STACK.
   M routines cannot modify $STACK with the SET or KILL commands.

   Example:


   GTM>WRITE $STACK

   2
   GTM>WRITE $ZLEVEL

   3
   GTM>

   This example shows the current values for
   $STACK and
   $ZLEVEL. $ZLEVEL is like  $STACK  except  that  uses  one  (1)  as  the
   starting level for the M stack, which $STACK uses zero (0), which means
   that $ZLEVEL is always one more than $STACK.  Using  $ZLEVEL  with  "Z"
   commands and functions, and $STACK with standard functions  avoids  the
   need to calculate the adjustment.

4 Look_Invoc_Stack
   Looking at the Invocation Stack

   The $STACK intrinsic special variable and the $STACK() function provide
   a mechanism to access M stack context information.

   Example:


   GTM>WRITE $STACK

   2
   GTM>WRITE $STACK(2,"ecode")

   ,M6,Z150373850,

   GTM>WRITE $STACK(2,"place")

   name+3^dmex

   GTM>WRITE $STACK(2,"mcode")

   if ln<30,bame?1.a.1"-".a1","1" "1a.ap do print q

   GTM>

   This example gets the value of $STACK and then uses that value  to  get
   various types of information about that stack level using the
   $STACK() function. The "ecode" value of the error information for level
   two, "place" is similar to
   $ZPOSITION, "mcode" is the code for the level.

   In addition to the $STACK intrinsic special  variable,  which  provides
   the current stack level, $STACK(-1) gives the highest level  for  which
   $STACK() can return valid information. Until there is an  error  $STACK
   and $STACK(-1) are the same, but once
   $ECODE shows that there is an "current" error, the information returned
   by $STACK() is frozen to capture the state at the time of the error; it
   unfreezes after a SET $ECODE="".

   Example:


   GTM>WRITE $STACK

   2
   GTM>WRITE $STACK(-1)

   2
   GTM>

   This example shows that under the  conditions  created  (in  the  above
   example), $STACK and $STACK(-1) have the same value.

   The $STACK() can return information about lower levels.

   Example:


   +1^GTM$DMOD

   GTM>WRITE $STACK(1,"ecode")


   GTM>WRITE $STACK(1,"place")

   beg^dmex

   GTM>WRITE $STACK(1,"mcode")

   beg for read !,"Name:",namde do name

   GTM>

   This example shows that there was no error at $STACK level one, as well
   as the "place" and "mcode" information for that level.

4 Using_ZSHOW_Ex_Context_Info
   Using ZSHOW to Examine Context Information

   The ZSHOW command displays information about the M environment.

   Example:


   GTM>ZSHOW "*"

   $DEVICE=""

   $ECODE=",M6,Z150373850,"

   $ESTACK=2

   $ETRAP=""

   $HOROLOG="59149,36200"

   $IO="/dev/pts/17"

   $JOB=310051

   $KEY=""

   $PRINCIPAL="/dev/pts/17"

   $QUIT=0

   $REFERENCE=""

   $STACK=2

   $STORAGE=1072300032

   $SYSTEM="47,gtm_sysid"

   $TEST=1

   $TLEVEL=0

   $TRESTART=0

   $X=0

   $Y=23

   $ZA=0

   $ZB=$C(13)

   $ZCMDLINE=""

   $ZCOMPILE=""

   $ZCSTATUS=0

   $ZDIRECTORY="/ext1/home/"

   $ZEDITOR=0

   $ZEOF=0

   $ZERROR="Unprocessed $ZERROR, see $ZSTATUS"

   $ZGBLDIR="/ext1/home/mumps.gld"

   $ZININTERRUPT=0

   $ZINTERRUPT="IF $ZJOBEXAM()"

   $ZIO="/dev/pts/17"

   $ZJOB=0

   $ZLEVEL=3

   $ZMODE="INTERACTIVE"

   $ZPOSITION="name+3^dmex"

   $ZPROCESS=""

   $ZPROMPT="GTM>"

   $ZROUTINES=". /usr/library/gtm_dist"

   $ZSOURCE=""

   $ZSTATUS="150373850,name+3^dmex,  %GTM-E-UNDEF,  Undefined  local
   variable: bame"
   $ZSYSTEM=0

   $ZTRAP="B"

   $ZVERSION="GT.M V4.3-001D AIX RS6000"

   $ZYERROR=""

   bame="?"

   ln=12

   name=""

   /dev/pts/17 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24

   name+3^dmex ($ZTRAP)

   (Direct mode)

   beg^dmex

   ^GTM$DMOD (Direct mode)


   GTM>

   This example uses the asterisk (*) argument  to  show  all  information
   that ZSHOW offers in this context.  First  are  the  Intrinsic  Special
   Variables ($DEVICE-$ZYERROR, also available with ZSHOW "I"),  then  the
   local variables (bame, ln and name, also  available  with  ZSHOW  "V"),
   then the ZBREAK locations (name+3^dmex, also available with ZSHOW "B"),
   then the device information (also available with ZSHOW "D"), then the M
   stack (also available with ZSHOW "S"). ZSHOW "S"  is  the  default  for
   ZSHOW with no arguments.

   Context information that does not exist  in  this  example  includes  M
   LOCKs of this process (
   ZSHOW "L").

   In addition to directing its output to the current  device,  ZSHOW  can
   place its output  in  a  local  or  global  variable  array.  For  more
   information, refer to the ZSHOW section of the  "Commands"  chapter  in
   GT.M Programmer's Guide.

        ZSHOW "V" produces the same output as ZWRITE with no arguments, but
        ZSHOW "V" can be directed to a variable as well as a device.

3 Transf_Rtn_Control
   Transferring Routine Control

   The
   ZGOTO command transfers  control  from  one  part  of  the  routine  to
   another, or from one routine to  another,  using  the  specified  entry
   reference. The ZGOTO command takes an optional integer expression that
   indicates the M stack level reached by performing  the  ZGOTO,  and  an
   optional  entry  reference  specifying  the  location  to  where  ZGOTO
   transfers control. A ZGOTO command, with an entry reference, performs a
   function similar to the GOTO command with the additional capability of
   reducing the M stack level. In a single operation, the process executes
   $ZLEVEL-intexpr, implicit QUITs from DO or extrinsic operations, and a
   GOTO operation transferring control to the named entry reference.

   The ZGOTO command leaves the invocation stack at the level of the value
   of the integer expression. GT.M implicitly terminates  any  intervening
   FOR  loops  and  unstacks  variables  stacked  with  NEW  commands,  as
   appropriate.

   ZGOTO $ZLEVEL:LABEL^ROUTINE takes the same action as GO LABEL^ROUTINE.

   ZGOTO  $ZLEVEL-1  produces  the  same  result  as  QUIT  (followed  by
   ZCONTINUE, if in Direct Mode).

   If the integer expression evaluates to a value greater than the current
   value of $ZLEVEL, or less than zero (0), GT.M issues a run-time error.

   If ZGOTO has no entry reference, it performs some  number  of  implicit
   QUITs and transfers control to the next command at the specified level.
   When no argument is specified, ZGOTO 1 is  the  result,  and  operation
   resumes at the lowest level M routine as displayed by ZSHOW "S". In the
   image invoked by mumps -direct, or a similar  image,  a  ZGOTO  without
   arguments returns the process to Direct Mode.

3 Disp_Source_code
   Displaying Source Code

   Use the
   ZPRINT command to display source code lines selected by  its  argument.
   ZPRINT allows you to display the source for the current routine and any
   other related routines. Use the ZPRINT command to display the last call
   level.

   Example:


   GTM>ZPRINT beg

   beg for read !,"Name: ",name do name

   This example uses a ZPRINT command to print the line indicated  as  the
   call at the top of the stack. Notice that the routine has an  error  in
   logic. The line starting with the label beg has  a  FOR  loop  with  no
   control variable, no QUIT, and no GOTO. There is no way out of the FOR
   loop.

3 Correct_Errs_in_M_Rtn
   Correcting Errors in an M Routine

   Now that the routine errors have been identified, correct them in the M
   source file. Use
   ZEDIT to invoke the editor and open the file for editing.  Correct  the
   errors previously identified and exit the editor.

   Example:


   GTM>ZEDIT "dmex"

   dmex ;dmex - Direct Mode example

   ;

   beg for read !,"Name: ",name do name q:name="Q"

   quit

   name set ln=$l(name)

   if ln,$e("QUIT",1,ln)=$tr(name,"quit","QUIT") d q

   . s name="Q"

   if ln<30,name?1.a.1"-".a1","1" "1a.ap do print q

   write !,"Please use last-name, "

   write "first-name middle-initial or 'Q' to Quit."

   quit

   print write !,$p(name,", ",2)," ",$p(name,", ")

   quit

   GTM>

   This example shows the final state of a ZEDIT session of  dmex.m.  Note
   that the infinite FOR loop at line beg is corrected.

3 Relink_Edited_Rtn
   Relinking the Edited Routine

   Use the ZLINK command to add the edited routine to the  current  image.
   ZLINK automatically recompiles and relinks the routine. If the routine
   was the most recent one ZEDITed or ZLINKed, you do not have to specify
   the routine name with the ZLINK command.

        You may have to issue a ZGOTO or  a  QUIT  command  to  remove  the
        unedited version of the routine from the M invocation stack before
        ZLINKing the edited version.

   Example:


   GTM>ZLINK

   Cannot ZLINK an active routine

   This illustrates a GT.M error report caused by an attempt  to  ZLINK  a
   routine that is part of the current invocation stack.

   To ZLINK the routine, remove any invocation levels for the routine off
   of the call stack. You may use the ZSHOW "S"  command  to  display  the
   current state of the call stack. Use the QUIT  command  to  remove  one
   level at a time from the call stack. Use the ZGOTO  command  to  remove
   multiple levels off of the call stack.

        For further details and examples, refer to  the  GT.M  Programmer's
        Guide.

3 Reexec_the_Rtn
   Re-executing the Routine

   Re-display the DO command using the RECALL command.

   Execute the routine using the DO command.

   Example:


   GTM>D ^dmex


   Name: Revere, Paul

   Paul Revere

   Name: q

   This example illustrates a successful execution of dmex.

3 Using_Forked_Proc
   Using Forked Processes

   The
   ZSYSTEM command creates a new process called  the  child  process,  and
   passes its argument  to  the  shell  for  execution.  The  new  process
   executes in the same directory  as  the  initiating  process.  The  new
   process has the same operating system environment, such as environment
   variables and input/output devices,  as  the  initiating  process.  The
   initiating process  pauses  until  the  new  process  completes  before
   continuing execution.

   Example:


   GTM>ZSYSTEM

   $ ls dmex.*

   dmex.m dmex.o


   $ ps

   PID TTY TIME COMMAND

   7946 ttyp0 0:01 sh

   7953 ttyp0 0:00 gtm

   7955 ttyp0 0:00 ps

   $ exit


   GTM>

   This example uses ZSYSTEM to create a child process, perform some shell
   actions, and return to GT.M.

1 Lang_Features_M
   General Language Features of M

   MUMPS is a general purpose language with an embedded  database  system.
   This section of the help file describes the features  of  the  language
   that are not covered  as  Commands,  Functions,  or  Intrinsic  Special
   Variables.

2 Data_Types
   Data Types

   M operates with a single basic data type, string. However, M evaluates
   data using methods that vary according to context.

3 Num_Expressions
   Numeric Expressions

   When M syntax specifies a numexpr, M evaluates the data as  a  sequence
   of ASCII characters that specify a number. M stops the  evaluation  and
   provides the result generated from  successfully  evaluated  characters
   when it encounters any character that is not the following:

   o    A digit 0-9

   o    A plus sign (+) or minus sign (-) and also the first  character  in
        the string

   o    The first decimal point (.) in the string

3 Num_Accuracy
   Numeric Accuracy

   GT.M provides 18 digits of accuracy, independent of the  decimal  point
   (.) placement, and a numeric range from 10**(-43) to (10**47). Numbers
   with three digits or fewer to  the  right  of  the  decimal  point  are
   precise.

3 Int_Expressions
   Integer Expressions

   When M syntax specifies an intexpr, M evaluates the data as it would a
   numexpr except that it  stops  the  evaluation  at  any  decimal  point
   including the first.

3 Truth_valued_Expr
   Truth-valued Expressions

   When M syntax specifies a tvexpr, M evaluates the data  as  a  numeric.
   However, it stops the evaluation and returns a true value (1)  as  soon
   as it encounters a non-zero digit, otherwise it returns a  false  value
   (0). In other words, M treats expressions that have a non-zero numeric
   value as true, and expressions that have a zero numeric value as false.
   The sign  and/or  decimal  have  no  affect  on  the  evaluation  of  a
   truth-valued expression.

2 M_Names
   M Names

   M uses names for variables, LOCK command arguments,  labels  on  lines,
   and routine names. M names are alphanumeric  and  must  start  with  an
   alphabetic character or a percent sign (%).

   The percent sign can only appear as the first character in a  name.  By
   convention,  names  starting  with  percent  signs  are  generally
   application-independent or distinguished in some similar way.

   M does not reserve any names. That is, M always distinguishes keywords
   by context. Therefore, M permits a variable or a label called SET even
   though the language has a command called SET.

   M names are case sensitive. That is, M treats ABC, Abc, ABc,  AbC  ABC,
   and abc as six different names.

   M does not restrict the length  of  names  in  the  main  body  of  the
   standard. However, the portability section of the  standard  recommends
   limiting names to a maximum of eight (8) characters.  GT.M  effectively
   limits names to eight characters by ignoring any characters  after  the
   first eight.

2 Variables
   Variables

   M does not require predefinition of variable type or size. M variables
   are either local or  global.  Any  variable  may  be  unsubscripted  or
   subscripted.

3 Arrays_Subscripts
   Arrays and Subscripts

   In M, subscripted variables identify elements in sparse arrays. Sparse
   arrays comprise existing subscripts  and  data  nodes  -  no  space  is
   reserved  for  potential  data  nodes.  These  arrays  generally  serve
   logical, rather than mathematical, purposes.

   M array subscripts are expressions, and are not restricted  to  numeric
   values.

   The format for an M global or local variable is:

   [^]name[(expr1[,...])]
   o    The optional leading caret symbol (^) designates a global variable.

   o    The name specifies a particular array.

   o    The optional expressions specify the subscripts
   o    and must be enclosed in parentheses and separated by commas (,).

   The body of the M standard places no restrictions  on  variable  names.
   However, the portability section of the standard does suggest limits on
   the length of an individual subscript  expression,  and  on  the  total
   length of a variable name. The measurement  for  the  length  of  names
   includes the length of the global variable name itself, the sum of the
   lengths of all the  evaluated  subscripts,  and  an  allowance  for  an
   overhead of two (2) times the number of subscripts. The total must not
   exceed 237. For globals, GT.M permits this total to  be  modified  with
   GDE up to 255.  For  locals,  GT.M  limits  the  length  of  individual
   subscripts to the maximum string length of 32,767. GT.M  restricts  the
   number of subscripts for local or global variables to 32.

3 M_Collation_Seq
   M Collation Sequences

   M  collates  all  canonic  numeric  subscripts  ahead  of  all  string
   subscripts, including strings such as those  with  leading  zeros  that
   represent non-canonic numbers. Numeric subscripts collate from negative
   to  positive  in  value  order.  String  subscripts  collate  in  ASCII
   sequence. In addition, GT.M allows the empty string subscript  in  most
   contexts, (the null, or empty, string collates  ahead  of  all  canonic
   numeric subscripts).

   GT.M allows definition of alternative collation sequences. For complete
   information  on  enabling  this  functionality,  refer  to  the
   "Internationalization" chapter in GT.M Programmer's Guide.

3 Local_Variables
   Local Variables

   A local variable in M refers to a variable used solely within the scope
   of a single process. Local variable names have no leading delimiter.

   M makes a local variable available and subject to modification  by  all
   routines executed within a process from the time that variable is first
   SET until it is  KILLed,  or  until  the  process  stops  executing  M.
   However, M "protects" a local variable after that variable  appears  as
   an argument to a NEW command, or after it appears as an  element  in  a
   formalist used in parameter passing. When M protects a local variable,
   it saves a copy  of  the  variable's  value  and  makes  that  variable
   undefined. M restores the variable to its saved value during execution
   of the QUIT that terminates the process stack level associated with the
   "protecting" NEW or formalist. For more information on  NEW  and  QUIT,
   refer to the "Commands" chapter in GT.M Programmer's Guide.

   M restricts the following uses of variables to local variables:

   o    FOR command control variables.

   o    Elements within the parentheses of an "exclusive" KILL.

   o    TSTART [with local variables list].

   o    A KILL with no arguments removes all current local variables.

   o    NEW command arguments.

	Actualnames used by pass-by-reference parameter passing.

3 Glob_Var_Resrc_Nam_Env
   Global Variables and Resource Name Environments

   M recognizes an optional environment specification in global  names  or
   in the LOCK resource names (nrefs), which have analogous syntax. Global
   variable names have a leading caret symbol (^) as a delimiter.

   M makes a global variable available, and subject to modification by all
   routines executed within all processes in an environment, from the time
   that variable is first SET until it is KILLed.

4 Naked_References
   Naked References

   M accepts an abbreviation of the global name under some circumstances.
   When the  leading  caret  symbol  (^)  immediately  precedes  the  left
   parenthesis delimiting subscripts, the  global  variable  reference  is
   called a naked reference. M evaluates a naked  reference  by  prefixing
   the last used global variable name, except for its last  subscript,  to
   the list of subscripts specified by the naked reference.  The  prefixed
   portion is known as the naked indicator. An  attempt  to  use  a  naked
   reference when the prior global reference does not exist,  or  did  not
   contain a subscript, generates an error.

   Because M has only one process-wide naked indicator which it maintains
   as a side affect of every evaluation of a global  variable,  using  the
   naked reference requires an understanding of M  execution  sequence.  M
   execution generally proceeds from left to right within a line, subject
   to commands that change the flow of control. However, M  evaluates  the
   portion of a SET command argument to the right side of the  equal  sign
   before the left side. Also, M does not evaluate any  further  $SELECT()
   arguments within the function after  it  encounters  a  true  selection
   argument.

   In general, using naked references only in very  limited  circumstances
   prevents problems associated with the naked indicator.

4 Glob_Var_Name_Env
   Global Variable Name Environments

   M recognizes an optional environment specification in global names. The
   environment specification designates one of  some  set  of  alternative
   database files.

   The syntax for  global  variable  names  that  include  an  environment
   specification is:

   ^|expr|name[(subscript[,...])]

   In GT.M, the expression identifies the Global Directory for mapping the
   global variable.

   Environment specifications permit easy access to  global  variables  in
   alternative databases, including other "copies" of active variables in
   the current database. Environment specifications are sometimes referred
   to as extended global syntax or extended value syntax.

   GT.M also allows:

   ^|expr1,expr2|name[(subscript[,...])]

   Where the first expression identifies  the  Global  Directory  and  the
   second expression is accepted but ignored by GT.M.

   To improve compatibility with some other M implementations,  GT.M  also
   accepts another non-standard syntax. In this syntax,  the  leading  and
   trailing up-bar (|) are respectively replaced by a left square-bracket
   ([)  and  a  right  square-bracket  (]).  This  syntax  also  requires
   expratoms, rather than expressions.

   The formats for this non-standard syntax are:

   ^[expratom1]name[(subscript...)]

   or

   ^[expratom1,expratom2]name[(subscript...)]

   Where expratom1 identifies the Global  Directory  and  expratom2  is  a
   dummy variable. Note that the first set of brackets in each  format  is
   part of the syntax. The second set of square brackets is  part  of  the
   meta-language identifying an optional element.

   Example:


   $ gtmgbldir=Test.GLD

   $ export gtmgbldir

   $ GTM

   GTM>WRITE $ZGBLDIR

   TEST.GLD

   GTM>WRITE ^A

   THIS IS ^A IN DATABASE RED

   GTM>WRITE ^|"M1.GLD"|A

   THIS IS ^A IN DATABASE WHITE

   GTM>WRITE $ZGBLDIR

   TEST.GLD

   GTM>HALT

   $ echo gtmgbldir

   TEST.GLD

   The statement WRITE ^|"M1.GLD"|A writes variable ^A  using  the  Global
   Directory, M1.GLD, but does not change the current Global Directory.

   Example:


   GTM>WRITE $ZGBLDIR

   M1.GLD

   GTM>WRITE ^A

   THIS IS ^A IN DATABASE WHITE

   GTM>WRITE ^|"M1.GLD"|A

   THIS IS ^A IN DATABASE WHITE

   The statement WRITE ^|"M1.GLD"|A is equivalent to WRITE ^A.

   Specifying separate Global Directories does  not  always  translate  to
   using separate databases.

   Example:


   GTM>WRITE ^|"M1.GLD"|A,!,^|"M2.GLD"|A,!,^|"M3.GLD"

|A,!
   THIS IS ^A IN DATABASE WHITE

   THIS IS ^A IN DATABASE BLUE

   THIS IS ^A IN DATABASE WHITE

   In this example, the WRITE does not display ^A from three GT.M database
   files.  Mapping  specified  by  the  Global  Directory  Editor  (GDE)
   determines the database file to which a Global Directory points.

   This result could have occurred under the following mapping:


   ^|"M1.GLD"|A --> REGIONA --> SEGMENTA --> FILE1.DAT

   ^|"M2.GLD"|A --> REGIONA --> SEGMENT1 --> FILE2.DAT

   ^|"M3.GLD"|A --> REGION3 --> SEGMENT3 --> FILE1.DAT

   For more information  on  Global  Directories,  refer  to  the  "Global
   Directory Editor" chapter of the  GT.M  Administration  and  Operations
   Guide.

4 Opt_GTM_Env_Trans_Facility
   Optional GT.M Environment Translation Facility

   For users who wish to dynamically  (at  run-time)  determine  a  global
   directory from non-global directory information (typically UCI and VOL)
   in the environment specification, GT.M provides an interface to add an
   appropriate translation.

   Using this facility impacts the performance of every global access that
   uses environment specification. Make sure you use it only  when  static
   determination of the global directory is not feasible. When used, make
   every effort to keep the translation routines very efficient.

   The  use  of  this  facility  is  enabled  by  the  definition  of  the
   environment variable gtm_env_translate, which contains the  path  of  a
   shared library with the following entry point:

5 gtm_env_xlate
   gtm_env_xlate

   If the shared object is not  accessible  or  the  entry  point  is  not
   accessible, GT.M reports an error.

   The gtm_env_xlate() routine has the following C prototype:


   int gtm_env_xlate(xc_string_t *in1, xc_string_t *in2,  xc_string  *in3,
   xc_string_t *out)
   where xc_string_t is a structure defined in gtmxc_types.h as follows:


   typedef struct

   {

   int length;

   char *address;

   } xc_string_t;

   The purpose of the function is to use  its  three  input  arguments  to
   derive and return an output argument that can be used as an environment
   specification by GT.M. Note that the input values passed (in1, in2 and
   in3) are the result of M evaluation and must not be modified. The first
   two arguments are the expressions passed within the up-bars  "|  |"  or
   the square-brackets "[ ]",  and  the  third  argument  is  the  current
   working directory as described by $ZDIRECTORY.

   A return value other than zero (0) indicates an error  in  translation,
   and is reported by a GT.M error

   If the length of the  output  argument  is  non-zero,  GT.M  appends  a
   secondary message of GTM-I-TEXT,  containing  the  text  found  at  the
   address of the output structure.

   GT.M does not do any memory management related to the output argument -
   space for the output should be allocated by the external  routine.  The
   routine must  place  the  returned  environment  specification  at  the
   address it has allocated  and  adjust  the  length  accordingly.  On  a
   successful return, the return value should be zero. If the translation
   routine must communicate an error to GT.M, it must  return  a  non-zero
   value, and if it is to communicate additional error information, place
   the error text at the address where the environment would  normally  go
   and adjust the length to match the length of the error text.

   Length of the return value  may  range  from  0-32767,  otherwise  GT.M
   reports an error.

   A zero-length (empty) string specifies the current value  of  $ZGBLDIR.
   Non-zero  lengths  must  represent  the  actual  length  of  the  file
   specification pointed to by address, excluding any <NUL> terminator. If
   the address field of the output argument is NULL, GT.M issues an error.


   The file specification may be absolute or relative and may  contain  an
   environment variable. If the file specified is not  accessible,  or  is
   not a valid global directory, GT.M reports errors in the  same  way  it
   does for any invalid global directory.

   It is possible to write this routine in  M  (as  a  call-in),  however,
   global variables in such a routine would change  the  naked  indicator,
   which  environment  references  normally  do  not.  Depending  on  the
   conventions of the application, there  might  be  difficult  name-space
   management issues such as protecting the local variables used by the M
   routine.

   While it is possible for  this  routine  to  take  any  form  that  the
   application designer  finds  appropriate  within  the  given  interface
   definition, the following paragraphs make some recommendations based on
   the expectation that a routine invoked for any more than a  handful  of
   global references should be efficient.

   It is expected that the routine loads one or  more  tables,  either  at
   compilation or the first time it is invoked. The logic of  the  routine
   performs a look up on the entry in the set of tables. The lookup might
   be based on the length of the strings and some unique set of characters
   in the names, or a hash, with collision provisions as appropriate.

   The routine may have to deal with a case  where  one  or  both  of  the
   inputs have zero length. A subset of these cases  may  have  the  first
   string holding a comma limited string that needs to  be  re-interpreted
   as being equivalent to two input strings (note that the  input  strings
   must never be modified). The routine may  also  have  to  handle  cases
   where a value (most likely the first) is accidentally or intentionally,
   already a global directory specification.

   Example:


> cat gtm_env_translate.c
   #include <stdio.h>

   #include <string.h>

   #include "gtmxc_types.h"


   static int init = 0;

   typedef struct

   {

   xc_string_t field1, field2, ret;

   } line_entry ;


   static line_entry table[5], *line, linetmp;

        /* Since these errors may occur before setup is complete, they are
        statics */
   static  char  *errorstring1  =  "Error  in  function  initialization,
   environment  variable  GTM_CALLIN_START  not  defined.  Environment
   translation failed.";
   static char *errorstring2 = "Error in function initialization, function
   pointers could not be determined. Envrironment translation failed.";
   #define ENV_VAR "GTM_CALLIN_START"

   typedef int (*int_fptr)();

   int_fptr GTM_MALLOC;


   int init_functable(xc_string_t *ptr)

   {

        /* This function demonstrates the initialization of other function
        pointers as well (if the user-code needs them for any reason, they
        should be defined as globals)*/
   char *pcAddress;

   long lAddress;

   void **functable;

   void (*setup_timer) ();

   void (*cancel_timer) ();


   pcAddress = getenv(ENV_VAR);

   if (pcAddress == NULL)

   {

   ptr->length = strlen(errorstring1);

   ptr->address = errorstring1;

   return 1;

   }

   lAddress = -1;

   lAddress = atol(pcAddress);

   if (lAddress == -1)

   {

   ptr->length = strlen(errorstring2);

   ptr->address = errorstring2;

   return 1;

   }

   functable = (void *)lAddress;

   setup_timer = (void(*)()) functable[2];

   cancel_timer = (void(*)()) functable[3];

   GTM_MALLOC = (int_fptr) functable[4];

   return 0;

   }

   void copy_string(char **loc1, char *loc2, int length)

   {

   char *ptr;

   ptr = (char *) GTM_MALLOC(length);

   strncpy( ptr, loc2, length);

   *loc1 = ptr;

   }


   int init_table(xc_string_t *ptr)

   {

   int i = 0;

   char buf[100];

   char *buf1, *buf2;

   FILE *tablefile;

   char *space = " ";

   char *errorstr1 = "Error opening table file table.dat";

   char *errorstr2 = "UNDETERMINED ERROR FROM GTM_ENV_XLATE";


   if ((tablefile = fopen("table.dat","r")) == (FILE *)NULL)

   {

   ptr->length = strlen(errorstr1);

   copy_string(&(ptr->address), errorstr1, strlen(errorstr1));

   return 1;

   }

   while (fgets(buf, (int)SIZEOF(buf), tablefile) != (char *)NULL)

   {

   line= &table[i++];

   buf1 = buf;

   buf2 =strstr(buf1, space);

   line->field1.length = buf2 - buf1;

   copy_string( &(line->field1.address), buf1, line->field1.length);

   buf1 = buf2+1;

   buf2 = strstr(buf1, space);

   line->field2.length = buf2-buf1;

   copy_string( &(line->field2.address), buf1, line->field2.length);

   buf1 = buf2+1;

   line->ret.length = strlen(buf1) - 1;

   copy_string( &(line->ret.address), buf1, line->ret.length);

   }

   fclose(tablefile);

        /* In this example, the last entry in the table is the error string
        */
   line = &table[4];

   copy_string( &(line->ret.address), errorstr2, strlen(errorstr2));

   line->ret.length = strlen(errorstr2);

   return 0;

   }


   int cmp_string(xc_string_t str1, xc_string_t str2)

   {

   if (str1.length == str2.length)

   return strncmp(str1.address, str2.address, (int) str1.length);

   else

   return str1.length - str2.length;

   }


   int cmp_line(line_entry *line1, line_entry *line2)

   {

   return  (((cmp_string(line1->field1,
   line2->field1))||(cmp_string(line1->field2, line2->field2))));
   }


   int look_up_table(line_entry *aline, xc_string_t *ret_ptr)

   {

   int i;

   int ret_v;


   for(i=0;i<4;i++)

   {

   line = &table[i];

   ret_v = cmp_line( aline, line);

   if (!ret_v)

   {

   ret_ptr->length = line->ret.length;

   ret_ptr->address = line->ret.address;

   return 0;

   }

   }

        /*ERROR OUT*/
   line = &table[4];

   ret_ptr->length= line->ret.length;

   ret_ptr->address = line->ret.address;

   return 1;


   }


   int gtm_env_xlate(xc_string_t  *ptr1,  xc_string_t  *ptr2,  xc_string_t
   *ptr_zdir, xc_string_t *ret_ptr)
   {


   int return_val, return_val_init;

   if (!init)

   {

   return_val_init = init_functable(ret_ptr);

   if (return_val_init) return return_val_init;

   return_val_init = init_table(ret_ptr);

   if (return_val_init) return return_val_init;

   init = 1;

   }

   linetmp.field1.length= ptr1->length;

   linetmp.field1.address= ptr1->address;

   linetmp.field2.length= ptr2->length;

   linetmp.field2.address= ptr2->address;


   return_val = look_up_table(&linetmp, ret_ptr);

   return return_val;

   }


> cat table.dat
   day1 week1 mumps

   day2 week1 a

   day3 week2 b

   day4 week2 c.gld

   This example demonstrates the mechanism. A table is set  up  the  first
   time for proper memory management, and  for  each  reference,  a  table
   lookup is performed. Note that for the purpose of simplicity, no error
   checking is done, so table.dat is assumed to be in the correct format,
   and have exactly four entries.

2 Literals
   Literals

   M has both string and numeric literals.

3 String_Literals
   String Literals

   String literals (strlit) are enclosed in quotation marks (" ") and must
   only contain graphic characters. In  other  words,  control  characters
   (ASCII 0-31 and 127) cannot appear in  a  strlit.  M  attempts  to  use
   character text  that  appears  outside  of  quotation  mark  delimiters
   according to context, which generally means as a local variable name.

   To include a quotation mark (") within a  strlit,  use  a  set  of  two
   quotation marks ("" "").

   Example:


   GTM>WRITE """"

   "

   GTM>

   The WRITE displays a single quotation mark because the first quotation
   mark delimits the  beginning  of  the  string  literal,  the  next  two
   quotation marks denote a single quote within the string, and  the  last
   quotation mark delimits the end of the string literal.

   Use the $CHAR  function  and  the  concatenation  operator  to  include
   control characters within a string.

   Example:


   GTM>WRITE "A"_$CHAR(9)_"B"

   A B

   GTM>

   The WRITE displays an "A," followed by a tab (<HT>), followed by a "B"
   using $CHAR(), to introduce the non-graphic character.

3 Numeric_Literals
   Numeric Literals

   In  M,  numeric  literals  (numlit)  are  entered  without  surrounding
   delimiters.

   Example:


   GTM>WRITE 1

   1
   GTM> WRITE 1.1

   1.1
   These display numeric literals that are integer and decimal.

   M also accepts numeric literals in  the  form  of  a  mantissa  and  an
   exponent, separated by a delimiter of "E" in  uppercase.  The  mantissa
   may be an integer or a decimal fraction. The integer exponent may have
   an optional leading minus sign (-).

   Example:


   GTM>WRITE 8E6

   8000000
   GTM> WRITE 8E-6

   .000008
   GTM>

2 Expressions
   Expressions

   The following  items  are  legal  M  expression  atoms  (expratom).  An
   expression atom is a component of an M expression.

   o    Local variables

   o    Global variables

   o    Intrinsic special variables

   o    Intrinsic functions

   o    Extrinsic functions

   o    Extrinsic special variables

   o    Numeric literals

   o    String literals

   o    An expression enclosed in parentheses

   o    Any of the above preceded by a unary operator

   In addition, any of these items may be combined with a binary operator
   and another expression atom.

2 Operators
   Operators

   M has both unary and binary operators.

3 Precedence
   Precedence

   All unary operations have right to left precedence.

   All M binary operations have strict  left  to  right  precedence.  This
   includes all arithmetic, string, and logical operations. Hierarchies of
   operations  require  explicit  establishment  of  precedence  using
   parentheses (). Although this rule is counterintuitive, it is  easy  to
   remember and has no exceptions.

3 Arithmetic_Operators
   Arithmetic Operators

   All arithmetic operators force M to evaluate the expressions  to  which
   they apply as numeric. The arithmetic operators are:

        + as a unary operator simply forces M to  evaluate  the  expression
        following as numeric; as a binary operator it causes M  to  perform
        addition.
        - as a unary operator causes M to negate the expression following;
        as a binary operator it causes M to perform subtraction.
        * binary operator for multiplication.
        ** binary operator for exponentiation.
        / binary operator for fractional division.
        \ binary operator for integer division.
        # binary operator for modulo, that is,  causes  M  to  produce  the
        remainder from integer  division  of  the  first  argument  by  the
        second.
   Remember that precedence is left to right for all arithmetic operators.

   Example:


   GTM>WRITE 1+1

   2
   GTM>WRITE 2-1

   1
   GTM>WRITE 2*2

   4
   GTM>WRITE 3**2

   9
   GTM>WRITE 4/2

   2
   GTM>WRITE 7

   2
   GTM>WRITE 7#3

   1
   GTM>

   This simple example demonstrates how each arithmetic  binary  operation
   uses numeric literals.

   Example:


   GTM>WRITE +"12ABC"

   12
   GTM>WRITE --"-3-4"

   -3

   GTM>

   The first WRITE shows the unary plus sign  (+)  operation  forcing  the
   numeric evaluation of a string literal. The second  WRITE  demonstrates
   the unary minus sign (-). Note the second minus sign within the string
   literal does not cause subtraction, but rather, terminates the numeric
   evaluation with the result of negative three (-3). Each of the leading
   minus signs causes one negation and therefore, the result  is  negative
   three (-3).

3 Logical_Operators
   Logical Operators

   M logical operators always produce a result that is TRUE (1)  or  FALSE
   (0). All logical operators force M to evaluate the expressions to which
   they apply as truth-valued. The logical operators are:

        '  unary  NOT  operator  negates  current  truth-value;  M  accepts
        placement of the NOT operator next to a  relational  operator,  for
        example, A'=B as meaning '(A=B).
        & binary AND operator produces a true result only if  both  of  the
        expressions are true.
        ! binary OR operator produces  a  true  result  if  either  of  the
        expressions is true.
   Remember that precedence is always left  to  right,  and  that  logical
   operators have the same precedence as all other operators.

   Example:


   GTM>WRITE '0

   1
   GTM>WRITE '1

   0
   GTM>WRITE '5689

   0
   GTM>WRITE '-1

   0
   GTM>WRITE '"ABC"

   1
   GTM>

   The above example demonstrates the unary NOT operation. Note  that  any
   non-zero numeric value is true and has a false negation.

   Example:


   GTM>WRITE 0&0

   0
   GTM>WRITE 1&0

   0
   GTM>WRITE 0&1

   0
   GTM>WRITE 1&1

   1
   GTM>WRITE 2&1

   1
   GTM>WRITE 0!0

   0
   GTM>WRITE 1!0

   1
   GTM>WRITE 0!1

   1
   GTM>WRITE 1!1

   1
   GTM>WRITE 2!1

   1
   GTM>

   The above example demonstrates all cases covered by the binary logical
   operators.

3 String_Operators
   String Operators

   All string operators force M to evaluate the expressions to which they
   apply as strings. The string operator is:

        _ binary operator causes M to  concatenate  the  second  expression
        with the first expresion
   Example:


   GTM>WRITE "B"_"A"

   BA

   GTM>WRITE "A"_1

   A1

   GTM>

   The above example demonstrates M concatenation.

3 Num_Relational_Operators
   Numeric Relational Operators

   M relational operators always generate a result of TRUE  (1)  or  FALSE
   (0).  All  numeric  relational  operators  force  M  to  evaluate  the
   expressions to which they apply  as  numeric.  The  numeric  relational
   operators are:

        > binary arithmetic greater than
        < binary arithmetic less than
   The equal sign (=) does not force numeric  evaluation,  and  should  be
   viewed as a string  operator.  However,  the  equal  sign  between  two
   numeric values tests for numeric equality.

   Other numeric relations are  formed  using  the  logical  NOT  operator
   apostrophe (') as follows:

        '> not greater than, that is, less than or equal to
        '< not less than, that is, greater than or equal to
        '= not equal, numeric or string operation
   Example:


   GTM>WRITE 1>2

   0
   GTM>WRITE 1<2

   1
   GTM>

   The  above  example  demonstrates  the  basic  arithmetic  relational
   operations.

   Example:


   GTM>WRITE 1'<2

   0
   GTM>WRITE 2'<1

   1
   GTM>

   The above example demonstrates combinations of  arithmetic,  relational
   operators with the logical NOT operator.

3 Str_Relational_Operators
   String Relational Operators

   M relational operators always generate a result of TRUE  (1)  or  FALSE
   (0).  All  string  relational  operators  force  M  to  evaluate  the
   expressions to which they  apply  as  strings.  The  string  relational
   operators are:

        = binary operator causes M to produce a TRUE if the expressions are
        equal.
        [ binary  operator  causes  M  to  produce  a  TRUE  if  the  first
        expression contains the  ordered  sequence  of  characters  in  the
        second expression.
        ] binary  operator  causes  M  to  produce  a  TRUE  if  the  first
        expression lexically follows the second expression in the character
        encoding sequence, which by default is ASCII.
        ]] binary operator  causes  M  to  produce  a  TRUE  if  the  first
        expression lexically sorts  after  the  second  expression  in  the
        subscript collation sequence.
   Note that all non-empty strings lexically follow the empty string, and
   every string contains the empty string.

   Other string relations  are  formed  using  the  logical  NOT  operator
   apostrophe (') as follows:

        '[ does not contain.
        '] does not follow, that is, lexically less than or equal to.
        ']] does not sort after, that is, lexically less than or  equal  to
        in the subscript collation sequence.
        '= not equal, numeric or string operation.
   Example:


   GTM>WRITE "A"="B"

   0
   GTM>WRITE "C"="C"

   1
   GTM>WRITE "A"["B"

   0
   GTM>WRITE "ABC"["C"

   1
   GTM>WRITE "A"]"B"

   0
   GTM>WRITE "B"]"A"

   1
   GTM>WRITE "A"]]"B"

   0
   GTM>WRITE "B"]]"A"

   1
   These examples demonstrate the string relational operators using string
   literals.

   Example:


   GTM>WRITE 2]10

   1
   GTM>WRITE 2]]10

   0
   GTM>WRITE 0]"$"

   1
   GTM>WRITE 0]]"$"

   0
   These examples illustrate that when using the primary  ASCII  character
   set, the  main  difference  in  the  "follows"  (])  operator  and  the
   "sorts-after" (]]) operator is the way they treat numbers.

   Example:


   GTM>WRITE 1=1

   1
   GTM>WRITE 1=2

   0
   GTM>WRITE 1="1"

   1
   GTM>WRITE 1=01

   1
   GTM>WRITE 1="01"

   0
   GTM>WRITE 1=+"01"

   1
   GTM>

   These examples illustrate the dual nature of the equal  sign  operator.
   If both expressions are string or numeric,  the  results  are  straight
   forward. However, when the expressions are  mixed,  the  native  string
   data type prevails.

   Example:


   GTM>WRITE "a"'="A"

   1
   GTM>WRITE "FRED"'["RED"

   0
   GTM>WRITE "ABC"']""

   0
   These  examples  demonstrate  combinations  of  the  string  relational
   operators with the NOT operator.

3 Pat_Match_Operator
   Pattern Match Operator

   The pattern match operator (?)  causes  M  to  return  a  TRUE  if  the
   expression ahead of the operator matches the characteristics described
   by  the  pattern  following  the  operator.  The  pattern  is  not  an
   expression.

   Patterns are made up of two elements:

   o    A repetition count

   o    A pattern code, a string literal or an alternation list

   The element following the pattern match  operator  may  consist  of  an
   indirection operator, followed  by  an  element  that  evaluates  to  a
   legitimate pattern.

   The repetition count consists of either a single integer literal  or  a
   period  (.)  delimiter  with  optional  leading  and  trailing  integer
   literals. A single integer literal specifies an exact repetition count.
   The period syntax specifies a range of repetitions  where  the  leading
   number is a minimum and the trailing number  is  a  maximum.  When  the
   repetition count is missing the leading number, M assumes there  is  no
   minimum, (i.e., a minimum  of  zero).  When  the  repetition  count  is
   missing the trailing number, M does not place a maximum on  the  number
   of repetitions.

   The pattern codes are:

        A alphabetic characters upper or lower case
        C control characters ASCII 0-31 and 127
        E any character; used to pass all characters  in  portions  of  the
        string where the pattern is not restricted
        L lower-case alphabetic characters, ASCII 97-122
        N digits 0-9, ASCII 48-57
        P punctuation, ASCII 32-47, 58-64, 91-96, 123-126
        U upper-case alphabetic characters, ASCII 65-90
   Pattern codes may be upper or lower case and may  be  replaced  with  a
   string literal. GT.M allows the M pattern match definition of patcodes
   A, C, N, U, L, and P to be extended or changed, (A can only be modified
   implicitly by modifying L or U) and new patcodes  added.  For  detailed
   information  on  enabling  this  functionality,  refer  to  the
   "Internationalization" chapter in GT.M Programmer's Guide.

        The GT.M compiler accepts pattern codes other than those explicitly
        defined above. If, at run-time, the pattern codes come into use and
        no pattern definitions are available, GT.M issues a run-time error
        (PATNOTFOUND). GT.M does not currently implement a mechanism for Y
        and Z patterns and continues to treat those as compile-time syntax
        errors.

   Example:


   GTM>WRITE "ABC"?3U

   1
   GTM>WRITE "123-45-6789"?3N1"-"2N1"-"4N

   1
   The first WRITE has a simple one-element pattern while the  second  has
   multiple elements including both codes and  string  literals.  All  the
   repetition counts are fixed.

   Example:


   I x?.E1C.E W !,"Must not contain a control character" Q

   This example uses a pattern match to test for control characters.

   Example:


   I acn?1U.20A1","1U.10A D

   .S acn=$G((^ACX($P(acn,","),$P(acn,",",2)))

   This example uses a pattern match with implicit minimums  to  determine
   that an "account number" is actually a name, and to trigger  a  look-up
   of the corresponding account number in the ^ACX cross index.

   The pattern match operator accepts the  alteration  syntax.  Alteration
   consists of a repeat  count  followed  by  a  comma-delimited  list  of
   patatoms enclosed in parentheses "()". The semantic is that the pattern
   matches if any of the listed patterns matches the operand  string.  For
   example, ?1(2N1"-"7N,3N1"-"2N1"-"4N).1U might be a way to match either
   a social security number or a taxpayer ID. Since alternation is defined
   as one of the ways of constructing a patatom, alternation can nest (be
   used recursively).

        Complex pattern matches may not be efficient to evaluate, so every
        effort should be made to simplify any commonly used pattern and to
        determine  if  more  efficient  alternative  logic  would  be  more
        appropriate.

2 Gen_M_Comm
   General M Commands

   M commands may be abbreviated to a defined prefix. Most  commands  have
   arguments. However, some commands have either optional arguments or no
   arguments. When a command has no  argument  and  is  followed  by  more
   commands on the same line, at least two spaces (<SP>) must  follow  the
   command without arguments. Commands  that  accept  arguments  generally
   accept multiple arguments  on  the  same  command.  M  treats  multiple
   arguments the same as multiple occurrences of the  same  command,  each
   with its own argument.

3 Postconditionals
   Postconditionals

   M provides postconditionals as a tool for placing a  condition  on  the
   execution of a single command and, in  some  cases,  a  single  command
   argument. A postconditional consists of a colon (:) delimiter followed
   by a truth-valued expression. When the expression evaluates to true, M
   executes the command  occurrence.  When  the  expression  evaluates  to
   false, M does not execute the command occurrence.

4 Comm_Postconditionals
   Command Postconditionals

   Command postconditionals appear immediately  following  a  command  and
   apply to all arguments for the command when it has multiple arguments.
   All commands except commands that themselves have a conditional aspect
   accept a command postconditional. Among the M standard commands, ELSE,
   FOR, and IF do  not  accept  command  postconditionals.  All  the  GT.M
   command extensions accept command postconditionals.

4 Arg_Postconditionals
   Argument Postconditionals

   Commands that affect the flow of control may accept postconditionals on
   individual  command  arguments.  Because  multiple  arguments  act  as
   multiple commands, this is a straight-forward application of  the  same
   principal as command postconditional. The only M standard commands that
   accept argument postconditionals are DO, GOTO,  and  XECUTE.  The  GT.M
   command extensions that accept  argument  postconditionals  are  BREAK,
   ZGOTO, and ZSYSTEM.

3 Timeouts
   Timeouts

   M provides timeouts as a tool to retain program control  over  commands
   of indefinite duration. A timeout consists of a colon (:) delimiter on
   an argument, followed by a numeric expression specifying the number of
   seconds for M to attempt to execute the command. When  the  timeout  is
   zero (0), M makes a single attempt to complete the command.

   GT.M has been designed to allow large timeout values,  and  to  protect
   against arithmetic overflow when converting  large  timeout  values  to
   internal representations. When a command has a timeout, M maintains the
   $TEST intrinsic special variable  as  the  command  completes.  If  the
   command completes successfully, M  sets  $TEST  to  TRUE  (1).  If  the
   command times out before successful completion, M sets $TEST  to  FALSE
   (0). When a command argument does not specify a  timeout,  M  does  not
   maintain $TEST.

   The following commands accept timeouts:

   o    LOCK

   o    JOB

   o    OPEN

   o    READ

   o    ZALLOCATE

   When a READ times out, M  returns  any  characters  that  have  arrived
   between the start of the command and the timeout. M  does  not  produce
   any partial results for any of the other timed commands.

2 Gen_M_Intrin_Func
   General M Intrinsic Functions

   M Intrinsic Functions start with a single dollar sign ($) and have one
   or more arguments enclosed in parentheses () and  separated  by  commas
   (,). These functions provide an expression result by performing actions
   that would be impossible or difficult to perform using M  commands.  It
   is now possible to invoke a C function in a package  via  the  external
   call mechanism.

2 Gen_M_Intr_Spec_Var
   General M Intrinsic Special Variables

   M Intrinsic Special Variables start with a single dollar sign ($). GT.M
   provides such variables for program examination.  In  some  cases,  the
   Intrinsic Special Variables may be SET to modify the corresponding part
   of the environment.

2 Routines
   Routines

   M routines have a name and consist of lines  of  code  followed  by  an
   end-of-record which is a carriage return, formfeed (<CR><FF>) sequence.
   M separates the name of a routine from the body of the routine with an
   end-of-line which is a carriage-return, line-feed (<CR><LF>) sequence.

   GT.M stores routine sources in UNIX files and implicitly  supplies  the
   end-of-record and end-of-line character sequences.

   In M, a routine has no particular impact on variable management and may
   include code that is invoked at different  times  and  has  no  logical
   intersection.

3 Lines
   Lines

   A line of M code consists of the following elements  in  the  following
   order:

   o    An optional label.

   o    A  line-start  delimiter.  The  standard  defines  the  line-start
        delimiter as a space (<SP>) character. In order to enhance routine
        readability, GT.M extends M by accepting one  or  more  tab  (<HT>)
        characters as line-start delimiters.

   o    Zero or more level indicators, which are  periods  (.).  The  level
        indicators show the level of nesting for argumentless DO commands:
        the more periods, the deeper the  nesting.  M  ignores  lines  that
        contain  level  indicators  unless  they  directly  follow  an
        argumentless DO command with a matching level of nesting.

   o    Zero or more commands  and  their  arguments.  M  accepts  multiple
        commands on a line. The argument(s) of one  command  are  separated
        from the next command by a command-start delimiter,  consisting  of
        one or more spaces (<SP>).

   o    A terminating end-of-line, which is a carriage  return,  line  feed
        (<CR><LF>) sequence.

4 Labels
   Labels

   In addition to labels that follow the rules  for  M  names,  M  accepts
   labels consisting only of digits. In a label consisting only of digits,
   leading zeros are considered significant. For example, labels 1 and 01
   are different. Formalists may immediately follow a label. A Formalists
   consists of one or more names enclosed in  parentheses  ().  Formalists
   identify local variables that "receive" passed values  in  M  parameter
   passing.

   In GT.M, a colon (:) delimiter may be  appended  to  the  label,  which
   causes the label to be treated as "local." Within the routine in which
   they appear, they perform exactly as they would  without  the  trailing
   colon but they are inaccessible to other routines. Using  local  labels
   reduces object size and linking  overhead,  for  both  ZLINK  and  host
   linking.

4 Comments
   Comments

   In addition to commands, a line may also contain a comment that starts
   with a leading semi-colon (;) delimiter. The scope of a comment is the
   remainder of the line. In other words, M ignores anything to the right
   of the comment delimiter. The standard defines  the  comment  delimiter
   (;) as it would a command, and therefore requires that it always appear
   after a linestart. GT.M extends the  standard  to  permit  comments  to
   start at the first character of a line or in an argument position.

3 Entry_Ref
   Entry References

   M entryrefs provide a generalized target for referring to a line within
   a routine. An entryref may contain some  combination  of  a  label,  an
   offset, and a routine name (in that order). The offset is delimited by
   a plus sign (+) and the routinename is delimited by a caret symbol(^).
   When an entryref does not contain a label, M assumes the offset is from
   the beginning of the routine. When an  entryref  does  not  contain  an
   offset, M uses an offset of zero (0). When an entryref does not contain
   a routine name, M assumes the routine that is currently executing.

   M permits every  element  in  an  entryref  to  have  the  form  of  an
   indirection operator, followed  by  an  element  that  evaluates  to  a
   legitimate occurrence of that portion of the entryref.

        While  most  commands  and  functions  that  use  entryrefs  permit
        argument indirection, M does not accept indirection  that  resolves
        to a combination of label and offset or offset and routine name.

   Offsets provide an extremely useful tool for debugging. However, avoid
   their use in production code because they generally produce maintenance
   problems.

3 Label_Ref
   Label References

   M labelrefs are a subset of entryrefs that exclude offsets and separate
   indirection. Labelrefs are used with parameter passing.

2 Indirection
   Indirection

   M provides indirection as a means to defer definition  of  elements  of
   the code until run-time. Indirection names a  variable  that  holds  or
   "points" to the element. The indirection operator is  the  "at"  symbol
   (@).

3 Arg_Indirection
   Argument Indirection

   Most commands accept indirection of their entire argument.

   Example:


   GTM>SET x="^INDER"

   GTM>DO @x

   This example is equivalent to DO ^INDER.

3 Atomic_Indirection
   Atomic Indirection

   Any expratom or any local or global variable name may  be  replaced  by
   indirection.

   Example:


   GTM>SET x="HOOP",b="x"

   GTM>WRITE a="HULA "__@b

   HULA HOOP

   GTM>

   This example uses indirection within a concatenation operation.

3 Entryref_Indirection
   Entryref Indirection

   Any element of an entryref may be replaced by indirection.

   Example:


   GTM>SET lab="START",routine="PROG"

   GTM>DO @lab^@routine

   This example is equivalent to DO START^PROG.

3 Patt_Code_Indirection
   Pattern Code Indirection

   A pattern code may be replaced by indirection.

   Example:


   GTM>FOR p="1U.20A1"",""1U.20A",5N IF x?@p QUIT

   GTM>ELSE WRITE !,"Incorrect format" QUIT

   This example uses pattern code indirection to test x for either a name
   or a number.

3 Name_Indirection
   Name Indirection

   Indirection may replace the prefix of a  subscripted  global  or  local
   variable  name.  This  "name"  indirection  requires  two  indirection
   operators,  a  leading  operator  similar  to  the  other  forms  of
   indirection, and a trailing operator marking the  transition  to  those
   subscripts that are not specified by indirection.

   Example:


   GTM>SET from="B",to="^A(15),x=""

   GTM>FOR SET x=$O(@from@(x)) Q:x="" S @to@(x)=@from@(x)

   This example uses name indirection to copy  the  level  contents  of  a
   local array to a part of a global array. The example assumes  that  all
   existing first level nodes of variable B have data.

3 Indirection_Concerns
   Indirection Concerns

   M indirection provides  a  very  powerful  tool  for  allowing  program
   abstraction. However, because indirection is frequently unnecessary and
   has some disadvantages, use it carefully.

   Because routines that use indirection  in  some  ways  do  not  contain
   adequate information for easy reading, such routines tend  to  be  more
   difficult to debug and maintain.

   To improve run-time performance, GT.M tends to move work from run-time
   to compile-time.  Indirection  forces  compiler  actions  to  occur  at
   run-time, which minimizes the benefits of compilation.

   M allows most forms of indirection to be recursive.  However,  in  real
   applications, recursive indirection typically makes  the  code  obscure
   and slow.

   There are circumstances where indirection serves a worthwhile purpose.
   For instance, certain utility functions with a general  nature  may  be
   clearly abstracted and coded using indirection. Because M has no "CASE"
   command, DO (or  GOTO)  with  argument  indirection  provides  a  clear
   solution to the problem of providing complex branching.

   Some M users prototype with indirection and  then  replace  indirection
   with generated code that reduces run-time overhead. In any case, always
   consider whether indirection can be replaced with  a  clearer  or  more
   efficient approach.

2 Param_Passing
   Parameter Passing

   Parameter passing provides a way of explicitly controlling some or all
   of the variable context transferred between M routines.

   M uses parameter passing for:

   o    A DO command with parameters

   o    Extrinsic functions and special variables

   Parameter passing is optional on DO commands.

   Parameter  passing  uses  two  argument  lists:  the  actuallist  that
   specifies the parameters that M passes to an invoked routine,  and  the
   formalist that specifies the local variables to  receive  or  associate
   with the parameters.

3 Actuallists
   Actuallists

   An actuallist specifies the parameters M passes to the invoked routine.
   The actuallist contains a list of zero or more parameters  enclosed  in
   parentheses, immediately following a DO or extrinsic function.

   An actuallist:

   o    Is made up of items separated by commas

   o    Contains expressions and/or actualnames. Items may be missing, that
        is, two commas may appear next to each other, with nothing between
        them.

   o    Must be used in an invocation of a label with a formallist, except
        in the case of extrinsic special variables.

   o    Must not contain undefined variables.

   o    Must not have more items than a formallist with which it is used.

   o    May contain the same item in more than one position.

   Example:


   GTM>DO MULT(3,X,.RESULT)

   This example illustrates a DO with parameters. The actuallist contains:

   o    3 - a numeric literal

   o    X - a local variable

   o    .RESULT - an actualname

3 Actualnames
   Actualnames

   An actualname starts with a leading period (.) delimiter,  followed  by
   an unsubscripted local variable name.  Actualnames  identify  variables
   that are passed by reference, as described  in  a  subsequent  section.
   While expressions in  an  actualname  are  evaluated  when  control  is
   transferred to a formallabel, the variables identified  by  actualnames
   are not; therefore, they do not need to be defined at the time control
   is transferred.

3 Formallists
   Formallists

   A formallist specifies the variables M uses to hold  passed  values.  A
   formallist contains a list of  zero  or  more  parameters  enclosed  in
   parentheses, immediately following a label.

   A formallist:

   o    Is made up of items separated by commas.

   o    Contains unsubscripted local variable names.

   o    Must be used and only used with a label invoked with an actuallist
        or an extrinsic.

   o    May contain undefined variables.

   o    May have more items than an actuallist with which it is used.

   o    Must not contain the same item in more than one position.

   o    Must contain at least as many items as the actuallist with which it
        is used.

   Example:


   MULT(MP,MC,RES)

   SET RES=MP*MC

   QUIT RES

   In this example,  illustrating  a  simple  parameterized  routine,  the
   formallist contains the following items:

   o    MP

   o    MC

   o    RES

   An example in the section describing "Actuallists" shows an invocation
   that matches this routine.

3 Formallabel
   Formallabel

   A label followed by a formallist is called a formallabel.

3 Param_Pass_Operation
   Parameter Passing Operation

   M performs an implicit NEW on the formallist  names  and  replaces  the
   formallist items with the actuallist items.

   M provides the actuallist values to the  invoked  procedure  by  giving
   each element in the formallist the value or reference provided  by  the
   corresponding element in the actuallist. M associates the first name in
   the formallist with the first item in the actuallist, the  second  name
   in the formallist with the second item in the actuallist and so on. If
   the actuallist is shorter than  the  formallist,  M  ensures  that  the
   formallist items with no corresponding value are in  effect  NEWed.  If
   the formallist  item  has  no  corresponding  item  in  the  actuallist
   (indicated by two adjacent commas in the actuallist), that item in the
   formallist becomes undefined.

   If  the  actuallist  item  is  an  expression  and  the  corresponding
   formallist variable is an array, parameter passing does not affect the
   subscripted elements of the array. If an actualname  corresponds  to  a
   formallist variable, M reflects  array  operations  on  the  formallist
   variable, by reference, in the variable specified by the actualname.

   M treats variables that are not part of the formallist as if parameter
   passing did not exist (i.e., M makes  them  available  to  the  invoked
   routine).

   M initiates execution at the first command following the formallabel.

   A QUIT command terminates execution of the invoked routine. At the time
   of the QUIT, M restores the formallist items to the values they had at
   the invocation of the routine.

        In the case where a variable name appears as an actualname  in  the
        actuallist, and also as a variable in the formallist, the restored
        value reflects any change made by reference.

   A QUIT from a DO does not take  an  argument,  while  a  QUIT  from  an
   extrinsic must have an argument. This represents one of the  two  major
   differences between the DO command with parameters and the extrinsics.
   M returns the value of the QUIT command argument as the  value  of  the
   extrinsic function or special variable. The other difference is that M
   stacks $TEST for extrinsics.

   Example:

   SET X=30,Z="Hello"

   DO WRTSQR(X)

   ZWRITE

   QUIT

   WRTSQR(Z)

   SET Z=Z*Z

   WRITE Z,!

   QUIT

   Produces:


   900
   X=30

   Z="Hello"

3 Param_Pass_Mechanism
   Parameter Passing Mechanisms

   M passes the  actuallist  values  to  the  invoked  routine  using  two
   parameter-passing mechanisms:

   o    Call-by-Value - where expressions appear

   o    Call-by-Reference - where actualnames appear

   A call-by-value passes a copy of the value of the actuallist expression
   to the invoked routine by assigning the copy to a formallist variable.
   If the parameter is a variable, the invoked  routine  may  change  that
   variable. However, because M constructs that variable to hold the copy,
   it deletes the variable holding the copy when  the  QUIT  restores  the
   prior formallist values. This also means that changes to  the  variable
   by the invoked routine do not affect the value of the variable  in  the
   invoking routine.

   Example:


   SET X=30

   DO SQR(X)

   ZWRITE

   QUIT

   SQR(Z) SET Z=Z*Z

   QUIT

   Produces:


   X=30

   A period followed by a name  identifies  an  actualname  and  causes  a
   call-by-reference.

   A call-by-reference passes a pointer to the  variable  of  the  invoked
   routine so operations on the assigned formallist variable also  act  on
   the actualname variable. Changes, including  KILLs  to  the  formallist
   variable,  immediately  have  the  same  affect  on  the  corresponding
   actualname variable. This means that M  passes  changes  to  formallist
   variables in the invoked  routine  back  to  the  invoking  routine  as
   changes in actualname variables.

   Example:


   SET X=30

   DO SQR(.X)

   ZWRITE

   QUIT

   SQR(Z) SET Z=Z*Z

   QUIT

   Produces:


   X=900

3 GTM_Param_Pass_Extn
   GT.M Parameter Passing Extensions

   The standard does not provide for indirection of a labelref because the
   syntax has an ambiguity.

   Example:


   DO @X(1)

   This example could be:

   o    An invocation of the label specified by X with a parameter of 1.

   o    An invocation of the label specified  by  X(1)  with  no  parameter
        list.

   GT.M  processes  the  latter  interpretation  as  illustrated  in  the
   following example.

   Example:

   The syntax:


   SET A(1)="CUBE",X=5

   DO @A(1)(.X)

   WRITE X,!

   QUIT

   CUBE(C) ;cube a variable

   SET C=C*C*C

   QUIT

   Produces the result:

   125
   GT.M follows analogous syntax for routine indirection:

   DO ^@X(A) invokes the routine specified by X(A).

   DO ^@(X)(A) invokes the routine specified by X and passes the parameter
   A.

   DO ^@X(A)(A) invokes the routine  specified  by  X(A)  and  passes  the
   parameter A.

2 Ext_Calls
   External Calls

   GT.M allows references to a GT.M  database  from  programs  written  in
   other programming languages that run under UNIX.

   In GT.M, calls to C language routines may be made  with  the  following
   syntax:


   DO &[packagename.]name[^name][parameter-list]

   or as an expression element,


   $&[packagename.]name[^name][parameter-list]

   Where packagename, like the name elements is a valid M name. Because of
   the parsing conventions of M, the identifier between the ampersand (&)
   and the optional parameter-list has precisely constrained punctuation -
   a latersection describes how to  transform  this  into  a  more  richly
   punctuated name should that be appropriate  for  the  called  function.
   While the intent of the syntax is to permit the name^name to match an M
   labelref, there is no semantic implication to any use of  the  up-arrow
   (^).

2 Extrinsic_Func
   Extrinsic Functions

   An extrinsic function is an M subroutine that  another  M  routine  can
   invoke to return a value.

   The format for extrinsic functions is:


   $$[label][^routinename]([expr|.lname[,...]])

   o    The optional label and optional routinename make up the formallabel
        that specifies the name of the subroutine performing the extrinsic
        function. The formallabel must contain at least one of its optional
        components.

   o    The optional expressions and actualnames  make  up  the  actuallist
        that specifies the list  of  actual  parameters  M  passes  to  the
        invoked routine.

   M stacks $TEST for extrinsic functions. This is one of  the  two  major
   differences between the DO command with parameters and  extrinsics.  On
   return from an extrinsic function, M restores the  value  of  $TEST  to
   what it was before the extrinsic function, regardless  of  the  actions
   executed by the invoked routine.

   M requires a routine that implements an extrinsic function to terminate
   with an explicit QUIT command which has  an  argument.  M  returns  the
   value of the QUIT command  argument  as  the  value  of  the  extrinsic
   function. This is the other major difference  between  the  DO  command
   with parameters and extrinsics. It  is  now  possible  to  invoke  a  C
   function in a package via the external call mechanism.

   Example:


   GTM>ZPRINT ^POWER

   POWER(V,X,S,T) ;extrinsic to raise to a power

   ;ignores fractional powers

   SET T=1,S=0

   IF X<0 SET X=-X,S=1

   FOR X=1:1:X S T=T*V

   QUIT $S(S:1/T,1:T)

   GTM> WRITE $$^POWER(3,4)

   81
   GTM>

        The POWER routine  uses  a  formallist  that  is  longer  than  the
        "expected" actuallist to  protect  local  working  variables.  Such
        practice may be encouraged or  discouraged  by  your  institution's
        standards.

2 Extrinsic_Spc_Vars
   Extrinsic Special Variables

   An extrinsic special variable  is  a  user-written  M  subroutine  that
   another M routine can invoke to return a value.

   The format for extrinsic special variables is:

   $$[label][^routinename]

   o    The  optional  label  and  optional  routinename  make  up  the
        formallabel, which specifies the name of the subroutine performing
        the extrinsic function. The formallabel must contain at  least  one
        of its optional component.

   An extrinsic special  variable  can  be  thought  of  as  an  extrinsic
   function without input parameters. $$x is equivalent  in  operation  to
   $$x(). Extrinsic special variables are the only case  where  invocation
   of a formallabel does not require an actuallist.  M  stacks  $TEST  for
   extrinsic special variables.

   M requires that a routine that implements an extrinsic special variable
   terminate with an explicit  QUIT  command  which  has  an  argument.  M
   returns the value of the QUIT command argument  as  the  value  of  the
   extrinsic special variable.

   Example:


   GTM>ZPRINT ^DAYOWEEK

   DAYOWEEK() ;extrinsic special variable to

   ;provide the day of the week

   QUIT $ZD($H,"DAY")

   GTM>WRITE $$DAYOWEEK^DAYOWEEK

   MON

2 Trans_Processing
   Transaction Processing

   Transaction Processing (TP) provides a way for M programs  to  organize
   database updates into logical groups  that  occur  as  a  single  event
   (i.e., either all the database updates in a transaction occur, or none
   of them occur). No other process may  behave  as  if  it  observed  any
   intermediate state.

   Transaction  processing  has  been  designed  to  improve  output  and
   eliminate "live lock" conditions. The number of  attempts  to  complete
   the transaction is limited to four. The fourth attempt is made inside a
   "critical section" with all other processes temporarily locked  out  of
   the database. Between the second and third  tries,  GT.M  waits  for  a
   random interval between 0 and 500 milliseconds.

3 TP_Def
   TP Definitions

   In M, a transaction is a sequence of commands that begins with a TSTART
   command, ends with a TCOMMIT command, and is not within  the  scope  of
   another transaction.

   A successful transaction ends with a COMMIT that is  triggered  by  the
   TCOMMIT command at the end of the transaction. A COMMIT causes all the
   database updates performed within the transaction to  become  available
   to other processes.

   An unsuccessful transaction ends with a ROLLBACK. ROLLBACK  is  invoked
   explicitly by  the  TROLLBACK  command,  or  implicitly  at  a  process
   termination that occurs during a  transaction  in  progress.  An  error
   within a transaction does not cause an implicit  ROLLBACK.  A  ROLLBACK
   removes any database updates performed within  the  transaction  before
   they are made available to other processes. ROLLBACK also releases all
   resources LOCKed since the start of  the  transaction,  and  makes  the
   naked reference undefined.

   A RESTART is a transfer of control to the TSTART at  the  beginning  of
   the  transaction.  RESTART  implicitly  includes  a  ROLLBACK  and  may
   optionally restore local variables to the  values  they  had  when  the
   initial TSTART was originally executed. A RESTART always restores $TEST
   and the naked reference to the values they had when the initial TSTART
   was executed. RESTART does  not  manage  device  state  information.  A
   RESTART is invoked by the TRESTART command or by M if it is determined
   that the transaction  is  in  conflict  with  other  database  updates.
   RESTART can only successfully occur if the initial TSTART  includes  an
   argument that enables RESTART.

3 TP_Characteristics
   TP Characteristics

   Most transaction processing systems try to have transactions  meet  the
   "ACID" test-Atomic, Consistent, Isolated, and Durable. To conform with
   the M approach of providing maximum  flexibility  and,  when  possible,
   backwards  compatibility  with  older  versions  of  the  standard,  M
   transaction processing requires the use of programming conventions that
   meet the ACID test.

   For example, some effects of the BREAK, CLOSE,  JOB,  OPEN,  READ,  USE
   WRITE, and ZSYSTEM commands may be observed by parties to  the  system.
   Because the effects of these commands might cause an observing process
   or person to conclude that a transaction executing them was in progress
   and  perhapsfinished,  they  violate,  in  theory,  the  principle  of
   Isolation.

   The LOCK command is another example. A program may  attempt  to  use  a
   LOCK to determine if another process has a transaction in progress. The
   answer would depend on the management  of  LOCKs  within  transactions,
   which is implementation-specific. This would therefore clearly violate
   the principle of Isolation. The LOCK command is discussed later in this
   section.

   The simplest way to construct a transaction that meets the ACID test is
   not to use any commands within  a  transaction  whose  affects  may  be
   immediately "visible" outside the transaction. Unfortunately, because M
   applications  are  highly  interactive,  this  is  not  entirely
   straightforward.  When  a  user  interaction  relies  on  database
   information, one solution is for the program to save the initial values
   of any global values that could affect the outcome, in local variables.
   Then, once the  interaction  is  over  and  the  transaction  has  been
   initiated,  the  program  checks  the  saved  values  against  the
   corresponding global variables. If they are the same, it  proceeds.  If
   they differ, some other update has changed  the  information,  and  the
   program must issue a TROLLBACK, and initiate another interaction  as  a
   replacement.

   Even when the "visible" commands appear  within  a  transaction,  an  M
   application may provide wholesome operation by  relying  on  additional
   programming or operating conventions.

   A program using LOCKs to achieve  serializability  relies  on  properly
   designed  and  universally  followed  LOCKing  conventions  to  achieve
   Isolation with respect to database operations. LOCKs placed outside the
   transaction (usually a LOCK immediately before the TSTART and an unlock
   immediately after the  TCOMMIT)  achieve  serializability  by  actually
   serializing any  approximately  concurrent  transaction.  LOCKs  placed
   inside the transaction (frequently a LOCK immediately after the TSTART
   and an unlock immediately before the TCOMMIT) signal M to  ensure  that
   no operations  using  the  same  LOCK  resource(s)  overlap.  Within  a
   transaction, an M implementation may defer both LOCKing  and  unlocking
   to achieve its goal of serializability. A program  using  TSTARTs  with
   the SERIAL keyword replaces the convention with a guarantee from M that
   all the  database  activity  of  the  transaction  meets  the  test  of
   Isolation with respect to database activity.

   In GT.M the Durability aspect of the  ACID  properties  relies  on  the
   journaling  feature.  When  journaling  is  on,  every  transaction  is
   recorded in the journal file as well as in the  database.  The  journal
   file constitutes a serial record of database actions and states. It is
   always written before the database updates and is  designed  to  permit
   recovery of the database if the database should be damaged. By default
   when a process commits a transaction, it does not return control to the
   application code until the transaction has reached  the  journal  file.
   The  exception  to  this  is  that  when  the  TSTART  specifies
   TRANSACTIONID="BATCH" the process resumes application execution without
   waiting for the file system to confirm  the  successful  write  of  the
   journal record. The  idea  of  the  TRANSACTIONID="BATCH"  has  nothing
   inherently to do with "batch" processing -  it  is  to  permit  maximum
   throughput  for  transactions  where  the  application  has  its  own
   check-pointing mechanism, or method of recreating  the  transaction  in
   case of a failure. The real durability of transactions is a function of
   the durability of the journal files. Putting journal files on reliable
   devices (RAID with UPS protection) and  eliminating  common  points  of
   failure with the path to the  database  (separate  drives,  controllers
   cabling) improve durability. The use of  the  replication  feature  can
   also improve durability by moving the data to a separate site  in  real
   time.

   Attempting to QUIT (implicitly or explicitly) from code  invoked  by  a
   DO, XECUTE, or extrinsic after  that  code  issued  a  TSTART  not  yet
   matched by a TCOMMIT, produces an error. Although this is a consequence
   of the RESTART capability, it is true  even  when  that  capability  is
   disabled. For example, this means that  an  XECUTE  containing  only  a
   TSTART fails, while an XECUTE  that  performs  a  complete  transaction
   succeeds.

3 TP_Performance
   TP Performance

   To achieve the best GT.M performance, transactions should:

   o    be as short as possible

   o    consist, as much as possible, only of global updates

   o    be SERIAL with no associated LOCKs

   o    have RESTART enabled with a minimum of local variables protected by
        a restart portion of the TSTART argument.

   Large concurrent transactions using TCOMMIT may result in repeated and
   inefficient attempts by competing processes to  capture  needed  scarce
   resources, resulting in poor performance.

   Example:


   TSTART ():SERIAL

   SET (ACCT,^M(0))=^M(0)+1

   SET ^M(ACCT)=PREC,^PN(NAM)=ACCT

   TCOMMIT

   This transaction encapsulates these two SETs. The first increments the
   tally of patients registered, storing the number in local variable ACCT
   for faster access in the current program, and in global variable ^M(0).
   The second SET stores a patient record by account number and the third
   cross-references the account number with the patient name. Placing the
   SETs within a single  transaction  ensures  that  the  database  always
   receive either all of  the  SETs  or  none  of  them,  thus  protecting
   database  integrity  against  process  or  system  failure.  Similarly,
   another concurrent process, whether using transactions  or  not,  never
   finds one of the SETs in place without also finding the other one.

   Example:

   TSTART ():SERIAL

   IF $TRESTART>3 DO QUIT

   .TROLLBACK

   .WRITE !,"Too many RESTARTs"

   .QUIT

   SET (NEXT,^ID(0))=^ID(0)+1

   SET ^ID(NEXT)=RECORD,^XID(ZIP,NEXT)=""

   TCOMMIT

   This transaction will automatically restart if it cannot serialize the
   SETs to the database, and will terminate with a TROLLBACK if more than
   3 RESTARTs occur.

   GT.M provides a way to monitor transaction restarts by  reporting  them
   to  the  operator  logging  facility.  If  the  environment  variable
   TPRESTART_SYSLOG_DELTA is defined, GT.M reports every Nth restart where
   N is the numeric evaluation of the value of TPRESTART_SYSLOG_DELTA. If
   the environment variable TPRESTART_SYSLOG_LIMIT is defined, the restart
   reporting begins after the number of restarts specified by the value of
   TPRESTART_SYSLOG_LIMIT. For  example,  defining  both  the  environment
   variable to the value 1, causes all TP  restarts  to  be  logged.  When
   TPRESTART_SYSLOG_DELTA  is  defined,  leaving  TPRESTART_SYSLOG_LIMIT
   undefined is equivalent to giving it the value 1.

        For more information on  enhancements  related  to  TP  performance
        refer to the "NOISOLATION" section under VIEW command topic in the
        "Commands" chapter in GT.M Programmer's Guide.

3 TP_Example
   TP Example

   Here is a transaction processing example that  lets  you  exercise  the
   concept. If you  use  this  example,  be  mindful  that  the  functions
   "holdit" and "trestart" are included as tools to allow  you  access  to
   information within a transaction which would normally  be  hidden  from
   users. These types of functions would not normally appear in production
   code. Comments have been inserted into the code to explain the function
   of various segments.


   trans

   ;This sets up the program constants

   ;for doit and trestart

   n

   s $p(peekon,"V",51)=""

   s $p(peekon,"V",25)="Peeking inside Job "_$j

   s $p(peekoff,"^",51)=""

   s $p(peekoff,"^",25)="Leaving peeking Job "_$j

   ;This establishes the main loop

   s CNFLTMSG="Conflict, please reenter"

   f r !,"Name: ",nam q:'$l(nam) d

   .i nam="?" d q
   ..w !,"Current data in ^trans:",! d:$d(^trans) q
   ...zwrite ^trans
   .f s ok=1 d q:ok w !,$C(7),CNFLTMSG,$C(7),!
   ..s old=$g(^trans(nam),"?")
   ..i old="?" w !,"Not on file" d q
   ...;This is the code to add a new name
   ...f d q:data'="?"
   ....r !,"Enter any info using '#' delimiter: ",!,data
   ...i data="" w !,"No entry made for ",nam q
   ...TSTART ():SERIAL i $$trestart ;$$trestart for demo
   ...i $d(^trans(nam)) s ok=^trans(nam)=data TRO q
   ...s ^trans(nam)=data
   ...TCOMMIT:$$doit ;$$doit for demo
   ..;This is the beginning of the change and delete loop
   ..f d q:fld=+fld!'$l(fld) w " must be numeric"
   ...w !,"Current data: ",!,old
   ...r !,"Piece no. (negative to delete record) : ",fld
   ..i 'fld w !,"no change made" q
   ..;This is the code to delete a new name
   ..i fld<0 d q ; delete record
   ...f d q:"YyNn"[x
   ....w !,"Ok to delete ",nam," Y(es) or N(o) <N>? "
   ....r x s x=$e(x)
   ...i "Yy"'[x!'$l(x) w !,"No change made" q
   ...TSTART ():SERIAL i $$trestart ;$$trestart for demo
   ...i $g(^trans(nam),"?")'=old TROLLBACK s ok=0 q
   ...kill ^trans(nam)
   ...TCOMMIT:$$doit; $$doit for demo
   ..;This is the code to change a field
   ..f r !,"Data: ",data q:data'="?"&(data'["#") d
   ...w " must not be a single '?' or contain any '#'"
   ..TSTART ():SERIAL i $$trestart ;$$trestart for demo
   ..i '$d(^trans(nam)) s ok=0 TROLLBACK q
   ..i $p(^trans(nam),"#",fld)=$p(old,"#",fld) d q
   ...s ok=$p(^trans(nam),"#",fld)=data TROLLBACK
   ..s $p(^trans(nam),"#",fld)=data
   ..TCOMMIT:$$doit; $$doit for demo
   q


   doit()

   ;This inserts delay and an optional

   ;rollback only to show how it works

   w !!,peekon d disp

   f d q:"CR"[act

   .r !,"C(ommit), R(ollback), or W(ait) <C>? ",act
   .s act=$tr($e(act),"cr","CR")
   .i act="?" d disp
   i act="R" TROLLBACK w !,"User requested DISCARD"

   w !,peekoff,!

   q $TLEVEL


   trestart()

   ;This is only to show what is happening

   i $TRESTART d

   .w !!,peekon,!,">>>RESTART<<<",! d disp w !,peekoff,!
   q 1


   disp

   w !,"Name: ",nam

   w !,"Original data: ",!,old,!,"Current data: "

   w !,$g(^trans(nam),"KILLED!")

   q

   Generally, this type of program would be receiving data  from  multiple
   sessions into the same global.

1 BREAK
   Break

   The BREAK command pauses execution of the  code  and  initiates  Direct
   Mode.

   The format of the BREAK command is:


   B[REAK][:tvexpr] [expr[:tvexpr][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional expression contains a fragment of GT.M code to XECUTE
        before the process enters Direct Mode.

   o    The BREAK command without an argument causes a pause  in  execution
        of the routine code and immediately initiates Direct Mode. In this
        case, at least two (2) spaces must follow the BREAK to separate it
        from the next command on the line.

   o    The optional  truth-valued  expression  immediately  following  the
        expression is the argument postconditional  that  controls  whether
        GT.M XECUTEs  the  argument.  If  present  and  true,  the  process
        executes the code before  entering  Direct  Mode.  If  present  and
        false, the process does not execute the code before entering Direct
        Mode.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more BREAK arguments form a legal argument for a BREAK.

   Issuing a BREAK command inside a transaction destroys the Isolation of
   that transaction. Beacuse of the way that GT.M  implements  transaction
   processing, a BREAK within  a  transaction  may  suffer  an  indefinite
   number of restarts ("live lock").

   Generally, programs in production  must  not  include  BREAK  commands.
   Therefore, GT.M provides the ZBREAK and ZSTEP  commands,  which  insert
   temporary breakpoints into the process rather  than  the  source  code.
   BREAKs inserted with ZBREAK only exist until the  image  terminates  or
   until explicitly removed by another ZBREAK command. ZSTEP also inserts
   temporary BREAKs in the image that only exist for the execution of the
   ZSTEP command. In the GT.M debugging environment,  ZBREAKs  and  ZSTEPs
   that insert BREAKs provide a more flexible and less  error-prone  means
   of setting breakpoints than coding BREAKs directly into a routine. For
   more information on ZBREAK  and  ZSTEP,  refer  to  the  sections  that
   describe those commands.

   To resume execution of  the  interrupted  program,  use  the  ZCONTINUE
   command.

   GT.M displays messages identifying the source of a BREAK as:

   o    The body of a program

   o    A
   o    ZBREAK action

   o    A device EXCEPTION

   o    A ZSTEP action

   The  VIEW  "BREAKMSG"  mask  selectively  enables  or  disables  these
   messages. See the section on "VIEW" for an explanation of the mask. By
   default, a process executing a GT.M image displays all BREAK messages.

   When a process encounters a BREAK,  it  displays  a  prompt  indicating
   readiness to process commands in Direct Mode. By default,  Direct  Mode
   displays the  GTM>  prompt.  SETting  the  $ZPROMPT  intrinsic  special
   variable alters the prompt.

2 Ex_of_Break
   Examples of BREAK

   Example:


   LOOP0 F S act=$O(^act(act)) Q:act="" B:debug D LOOP1

   This FOR loop contains a BREAK with a command postconditional.

   Example:


   B:$D(x) "W !,""OK""":x,"W !,""Wrong again""":'x

   This uses a BREAK with both command and argument postconditionals. The
   actions display debugging messages.

1 CLOSE
   Close

   The CLOSE command breaks the connection between a process and a device.

   The format of the CLOSE command is:


   C[LOSE][:tvexpr] expr[:(keyword[=expr][:...])][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to CLOSE.

   o    The optional keywords specify device parameters that control device
        behavior; some device parameters take  arguments  delimited  by  an
        equal sign (=). If there  is  only  one  keyword,  the  surrounding
        parentheses are optional.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more CLOSE arguments form a legal argument for a CLOSE.

1 DO
   Do

   The DO command  makes  an  entry  in  the  GT.M  invocation  stack  and
   transfers execution to the location specified by the entryref.

   The format of the DO command is:


   D[O][:tvexpr] [entryref[(expr|.lvn[,...])][:tvexpr][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional entryref specifies a location (with  some  combination
        of label, offset, and routinename)  at  which  execution  continues
        immediately following the DO.

   o    A DO command without an argument (that is, a DO followed by two (2)
        spaces) transfers execution to the next line in the routine if that
        line contains a number of periods (.) after the optional label and
        before the required linestart. These periods indicate  the  current
        level of "immediate" nesting caused by  argumentless  DOs.  If  the
        line following the DO contains too many periods,  GT.M  reports  an
        error; if the line following the DO contains too few periods, GT.M
        ignores the DO command.

   o    A DO command without an argument stacks the current value of $TEST,
        in contrast to a DO with an argument, which does  not  protect  the
        current value of $TEST.

   o    The optional parameter list enclosed in parentheses  (  )  contains
        parameters to pass to the routine entry point.

   o    If the DO specifies a parameter list, the  entryref  location  must
        start with a label and an argument list (that  is,  GT.M  prohibits
        entryrefs with offsets during parameter passing).

   o    If an element in the  parameter  list  starts  with  a  period,  it
        specifies an unsubscripted local variable name and  the  DO  passes
        that variable by reference. Otherwise,  the  element  specifies  an
        expression that the DO evaluates and passes as a value.

   o    The optional truth-valued expression following the parameter list,
        or the  entryref  if  the  argument  contains  no  parameter  list,
        specifies the argument postconditional and  controls  whether  GT.M
        performs a DO with that argument.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more DO arguments form a legal argument for a DO.

   An explicit or implicit QUIT within the scope of the DO, but not within
   the scope of any other DO, FOR, XECUTE, or extrinsic, returns execution
   to the instruction following the calling point. This point may  be  the
   next DO argument or another command. At the end of a  routine,  or  the
   end of a nesting level created by an argumentless DO, GT.M performs an
   implicit QUIT. Any line that reduces the current level  of  nesting  by
   changing the number of leading periods (.)  causes  an  implicit  QUIT,
   even if that line only contains a comment.

   Terminating the image and execution of ZGOTO commands are the only ways
   to avoid eventually returning execution to  the  calling  point.  A  DO
   command may optionally pass parameters to the invoked subroutine.

2 Ex_of_Do
   Examples of DO

   Example:


   GTM>DO ^%RD

   This example invokes the routine directory utility program  (%RD)  from
   Direct Mode. The caret symbol (^) specifies that the DO command invokes
   %RD as an external routine.

   Example:


   GTM>DO A(3)

   This example invokes the subroutine at label A and passes the  value  3
   as a parameter. Because the DO argument does not have  a  caret  symbol
   (^), it identifies A as a label in the current routine.

   Example:


   Label A;

   SET di="" U outfile

   FOR SET di=$O(^div(di)) Q:di="" D PREP D D POST

   .SET de="",(nr,gr)=0

   .WRITE "Division ",di,! F S de=$O(^de(di,de)) Q:de="" D

   ..WRITE "Department ",de," Gross Rev: ",^grev(di,de),!

   ..WRITE "Department ",de," Net Rev: ",^nrev(di,de),!

   ..SET gr=gr+^grev(di,de),nr=nr+^nrev(di,de)

   .W "Division Gross Rev: ",gr,!,"Division Net Rev: ",nr,!

   DO PRINT^OUTPUT(outfile)

   QUIT

   This routine first uses a DO with a label argument (PREP)  to  do  some
   pre-processing. Then, it uses an argumentless DO to loop  through  each
   division of a company to format a report. Within the first argumentless
   DO, a second argumentless DO (line 4) loops through  and  formats  each
   department within a division. After the processing of all departments,
   control returns to the first argumentless DO, which prints a summary of
   the division. Following processing of all divisions, a DO with a label
   argument (POST) does some post-processing. Finally, at the next-to-last
   line, the routine uses a DO  that  invokes  a  subroutine  at  a  label
   (PRINT) in an external routine  (^OUTPUT),  passing  the  name  of  the
   output file (outfile) as a parameter.

1 ELSE
   Else

   GT.M executes the remainder of the line after  the  ELSE  if  $TEST  is
   FALSE (0). GT.M does not execute the rest of the line if $TEST is TRUE
   (1).

   The format of the ELSE command is:

   E[LSE]

   o    Because ELSE is a  conditional  command,  it  does  not  support  a
        command postconditional.

   o    The scope of the ELSE is the remainder of the line.

   o    Because the ELSE has no argument, at  least  two  (2)  spaces  must
        follow the command to separate it from  the  next  command  on  the
        line.

   Because the scopes of both the IF and the ELSE commands extend  to  the
   rest of the GT.M line,  placing  an  ELSE  on  the  same  line  as  the
   corresponding IF cannot achieve the desired result.  If  an  ELSE  were
   placed on the same line as its corresponding IF,  then  the  expression
   tested by the IF would be either TRUE or FALSE.  If  the  condition  is
   TRUE, the code following  the  ELSE  would  not  be  executed.  If  the
   condition is FALSE, the ELSE and everything following it would  not  be
   executed.

   ELSE is analogous to IF '$TEST, except the  latter  statement  switches
   $TEST to its complement and ELSE never alters $TEST.

   The scope of an ELSE can be extended with DO or XECUTE commands.

2 Ex_of_Else
   Examples of Else

   Example:


   IF x=+x SET x=x+y

   ELSE WRITE !,x

   The IF command evaluates  the  conditional  expression  x=+x  and  sets
   $TEST. If $TEST=1 (TRUE), GT.M executes the commands following the IF.
   The ELSE on the following line specifies an alternative action to take
   if the expression is false.

   Example:


   IF x=+x DO ^GOFISH

   ELSE SET x=x_"^"_y

   The DO with an argument after the IF raises the  possibility  that  the
   routine ^GOFISH changes the value of $TEST, thus making it possible to
   execute both the commands following the IF and the  commands  following
   the ELSE.

   Example:


   OPEN dev::0 ELSE WRITE !,"Device unavailable" QUIT

   This ELSE depends on the result of the timeout on the OPEN command. If
   the OPEN succeeds, it sets $TEST to one (1) and GT.M skips the rest of
   the line after the ELSE. If the OPEN fails, it sets $TEST to zero (0),
   and GT.M executes the remainder of the line after the ELSE.

1 FOR
   For

   The FOR command provides a looping mechanism in  GT.M.  A  FOR  command
   does not generate an additional level on the GT.M invocation stack.

   The format of the FOR command is:


   F[OR][lvn=expr[:numexpr1[:numexpr2]][,...]]]

   o    Because FOR is a conditional command, it does not support a command
        postconditional.

   o    The scope of the FOR is the remainder of the line.

   o    When the FOR has no argument, at least two (2) spaces  must  follow
        the command to separate it from the next command on the line. This
        specifies a loop that must be terminated by a QUIT, HALT, GOTO, or
        ZGOTO.

   o    The optional local variable name specifies a loop control variable
        delimited by an equal sign (=). A FOR command has only one control
        variable, even when it has multiple arguments.

   o    When initiating the FOR, GT.M assigns the loop control variable the
        value of the expression. When only an initial value  appears,  GT.M
        executes the remainder of the line once for that  argument  without
        forcing the control variable to be numeric.

   o    If  the  argument  includes  an  increment  and,  optionally,  a
        terminator, GT.M treats the initial expression as a number.

   o    The optional numeric expression after the first colon (:) delimiter
        specifies the increment for each iteration. The  FOR  command  does
        not increment the control variable on the first iteration.

   o    The  optional  numeric  expression  after  the  second  colon  (:)
        delimiter specifies the limiting value for  the  control  variable.
        This expression is evaluated only  when  the  control  variable  is
        initialized to the corresponding initial value, then used  for  all
        subsequent iterations.

   o    GT.M does not execute the commands on the same line  following  the
        FOR if:

   The increment is non-negative and the  initial  value  of  the  control
   variable is greater than the limiting value.
   The increment is negative and the initial value of the control variable
   is less than the limiting value.
   o    After the first iteration, GT.M does not alter the control variable
        and ceases execution under the control of the FOR if:

   The increment is non-negative, and altering the control variable by the
   increment would cause the control  variable  to  be  greater  than  the
   limiting value.
   The increment is negative, and altering the  control  variable  by  the
   increment would cause the control variable to be less than the limiting
   value.
   o    When the FOR has multiple arguments,  each  one  affects  the  loop
        control variable in sequence. For an argument to gain  control,  no
        prior argument to the FOR can have an increment without a limit.

   Increments and limits may be  positive,  negative,  an  integer,  or  a
   fraction. GT.M never increments a control variable  "beyond"  a  limit.
   Other commands may alter a control variable within the  extended  scope
   of a FOR that it controls. When the argument  includes  a  limit,  such
   modification can cause the FOR argument to yield control at  the  start
   of the next iteration.

   The scope of a FOR can be extended with DO or XECUTE commands.

   GT.M terminates the execution of a FOR when  it  executes  an  explicit
   QUIT or a GOTO (or ZGOTO in GT.M) that appears on the  line  after  the
   FOR. FOR commands with arguments that have  increments  without  limits
   and argumentless FORs can be infinite loops. Such FORs  must  terminate
   with a QUIT or a GOTO within the immediate scope of the FOR. Also, such
   FORs can, but seldom, terminate by a HALT within the scope of  the  FOR
   as extended by DOs, XECUTEs, and extrinsics. FORs  terminated  by  such
   commands act as "while" or "until" control mechanisms.

2 Ex_of_For
   Examples of FOR

   Example:


   GTM>KILL i FOR i=1:1:5 WRITE !,i

   1
   2
   3
   4
   5
   GTM>WRITE i

   5
   GTM>

   This FOR loop has a control variable, i, which has the value one (1) on
   the first iteration, then the value two (2), and so on,  until  in  the
   last iteration i has the value five (5).  The  FOR  terminates  because
   incrementing i would cause it to exceed the limit. Notice that i is not
   incremented beyond the limit.

   Example:


   GTM>FOR x="hello",2,"goodbye" WRITE !,x

   hello

   2
   goodbye

   GTM>

   This FOR loop uses the control variable x and  a  series  of  arguments
   that have no increments or limits. Notice that the control variable may
   have a string value.

   Example:


   GTM>FOR x="hello":1:-1 WRITE !,x

   GTM>ZWRITE x

   x=0

   GTM>

   Because the argument has an increment, the FOR initializes the control
   variable x to the numeric evaluation of "hello" (0). Then,  GT.M  never
   executes the remainder of the line because the increment  is  positive,
   and the value of the control variable (0) is greater than the limiting
   value (-1).

   Example:


   GTM>FOR y=-1:-3:-6,y:4:y+10,"end" WRITE !,y

   -1

   -4

   -4

   0
   4
   end

   GTM>

   This FOR uses two limited loop arguments and one  value  argument.  The
   first argument initializes y to negative one (-1), then increments y to
   negative four (-4). Because another increment would cause y to be less
   than the limit (-6), the first argument  terminates  with  y  equal  to
   negative four (-4). The second argument initializes  the  loop  control
   variable to its current value and establishes a limit of six (6=-4+10).
   After two iterations, incrementing y again would cause it to be greater
   than the limit (6), so the second argument terminates with y  equal  to
   four (4). Because the final argument has no increment, the FOR  sets  y
   to the value of the argument, and GT.M executes the commands following
   the FOR one more time.

   Example:


   GTM>S x="" F S x=$O(ar(x)) Q:x="" W !,x

   This example shows an argumentless FOR used to examine all first level
   subscripts of the local array ar. When $ORDER indicates that this level
   contains  no  more  subscripts,  the  QUIT  with  the  postconditional
   terminates the loop.

1 GOTO
   Goto

   The GOTO command transfers execution to a  location  specified  by  its
   argument.

   The format of the GOTO command is:


   G[OTO][:tvexpr] entryref

   [:tvexpr][,...]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required entryref specifies the target location for the control
        transfer.

   o    The optional  truth-valued  expression  immediately  following  the
        entryref  specifies  the  argument  postconditional,  and  controls
        whether GT.M performs a GOTO with that argument.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more GOTO arguments form a legal argument to a GOTO.

   A GOTO command within a line following a FOR  command  terminates  that
   FOR command.

2 Ex_of_Goto
   Examples of GOTO

   Example:


   GTM>GOTO TIME+4

   This GOTO command transfers control from Direct Mode to the  line  that
   is four (4) lines after the line labeled TIME (in the currently active
   routine). Using an offset is typically a debugging technique and rarely
   used in production code.

   Example:


   GOTO A:x<0,^A:x=0,A^B

   This GOTO command transfers control to label A in the current routine,
   if x is less than zero (0), to routine ^A if x is equal to zero (0), or
   to label A in routine ^B. Once any of the transfers occurs, the rest of
   the arguments have no effect.

1 HALT
   Halt

   The HALT command stops GT.M program execution and causes GT.M to return
   control to the operating  system  environment  that  invoked  the  GT.M
   image.

   The format of the HALT command is:


   H[ALT][:tvexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional  that  controls  whether  GT.M
        executes the command.

   o    Because the HALT command has no argument, at least two  (2)  spaces
        must follow the command to separate it from the next command on the
        line. Note that additional commands do not serve any purpose unless
        the HALT has a postconditional.

   A HALT releases all shared resources  held  by  the  process,  such  as
   devices OPENed in GT.M, databases, and GT.M  LOCKs.  If  the  value  of
   $TLEVEL is greater than zero (0), a ROLLBACK is performed.

   Because  HALT  and  HANG  share  the  same  abbreviation  (H),  GT.M
   differentiates them based on whether an argument follows the command.

   Example:


   $ gtm

   GTM>HALT

   $

   Because we invoke this GT.M image interactively,  the  HALT  in  Direct
   Mode leaves the process at the shell prompt.

1 HANG
   Hang

   The HANG command suspends GT.M program execution for a period  of  time
   specified by the command argument.

   The format of the HANG command is:


   H[ANG][:tvexpr] numexpr[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The numeric expression specifies the  time  in  seconds  to  elapse
        before resuming execution; actual elapsed time  may  vary  slightly
        from the specified time. If the  numeric  expression  is  negative,
        HANG  has  no  effect.  Portability  requirements  for  GT.M  only
        guarantee accuracy to the nearest second.However, more accuracy can
        be found on different UNIX systems.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more HANG arguments form a legal argument to a HANG.

   A process that repeatedly tests  for  some  event,  such  as  a  device
   becoming available or another process modifying a global variable, may
   use a HANG to limit its consumption of computing resources.

   Because  HALT  and  HANG  share  the  same  abbreviation  (H),  GT.M
   differentiates them based on whether an argument follows the command.

2 Ex_of_Hang
   Examples of HANG

   Example:


   FOR QUIT:$D(^CTRL(1)) HANG 30

   This FOR loop repeatedly tests  for  the  existence  of  ^CTRL(1),  and
   terminates when that global  variable  exists.  Otherwise  the  routine
   HANGs for 30 seconds and tests again.

   Example:


   SET t=1 F Q:$D(^CTRL(1)) H t I t<30 S t=t+1

   This is similar to  the  previous  example,  except  that  it  uses  an
   adaptive time that lengthens from 1 second to a limit of 30 seconds if
   the routine stays in the loop.

1 IF
   IF

   The IF command provides conditional execution of the remaining commands
   on the line. When IF has an argument, it updates $TEST with  the  truth
   value of its evaluated argument. GT.M executes the remainder of a line
   after an IF statement when $TEST is 1 (TRUE). When $TEST is 0 (FALSE),
   GT.M does not execute the rest of the line.

   The format of the IF command is:


   I[F] [tvexpr[,...]]

   o    Because IF is a conditional command, it does not support a command
        postconditional.

   o    The scope of the IF is the remainder of the line.

   o    The action of IF is controlled by the value of the  expression  and
        by $TEST, if there is no expression.

   o    IF with no argument acts on the existing value of $TEST  (which  it
        does not change); in this case, at least two (2) spaces must follow
        the IF to separate it from the next command on the line.

   o    An indirection operator, and an expression  atom  evaluating  to  a
        list of one or more IF arguments form a legal argument to IF.

   Example:

   IF A,B ...

   is equivalent to

   IF A IF B

   An IF with more than one argument behaves as if  those  arguments  were
   logically "ANDed." However, execution  of  the  line  ceases  with  the
   evaluation of the first false argument.  For  IF  argument  expressions
   containing the "AND" operator (&),  execution  still  ceases  with  the
   evaluation of the first false argument. Any  global  references  within
   the expression act in sequence to maintain the naked reference.

   Postconditionals perform a function similar to IF; however, their scope
   is limited to a single command or argument,  and  they  do  not  modify
   $TEST. For more information on postconditionals.

2 Ex_of_IF
   Examples of IF

   Example:


   IF x=+x!(x="") DO BAL

   In this example, the DO executes if x  contains  a  number  or  a  null
   string.

   Example:


   WRITE !,?50,BAL IF 'BAL WRITE "****"

   IF S EMPTY(acct)=""

   The IF in the first line changes the value of  $TEST,  determining  the
   execution of the code following the argumentless IF in the second line.
   Such argumentless IFs may serve as a form of line continuation.

   Example:


   GTM>SET X=1,Y=1,Z=2 KILL UNDEF

   GTM>IF X=1,Y=1,Z=3,UNDEF=0 W "HI"

   GTM>

   The IF command causes  GT.M  to  cease  executing  the  line  after  it
   determines Z is not equal to three (3). Therefore, GT.M never evaluates
   the reference to the undefined variable and never generates an error.

   Example:


   GTM>SET X=1 KILL UNDEF

   GTM>IF X=1!(UNDEF=3) WRITE "HI"

   HI

   GTM>

   Because GT.M  recognizes  that  the  X=1  fulfills  the  IF,  it  skips
   evaluation of the UNDEF variable and executes this IF  command  without
   generating an error. Because GT.M does not require  such  optimizations
   and in fact discourages them by requiring that  all  global  references
   maintain the naked indicator, other  implementations  may  generate  an
   error.

1 JOB
   Job

   The JOB command initiates another GT.M process that executes the named
   routine.

   $ZJOB is set to the pid of the process created by the JOB command. For
   details  refer  to  the  "$ZJOB"  section  in  the  "Intrinsic  Special
   Variable" chapter of GT.M Programmer's Guide.

   The format of the JOB command is:


   J[OB][:tvexpr] entryref

   [(expr[,...])]
   [:[(keyword[=value][:...])][:numexpr]][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required entryref specifies a location at which the new process
        starts.

   o    The optional parameter list enclosed  in  parentheses  ()  contains
        parameters to pass to the routine entry point.

   o    If the JOB specifies a parameter list, the entryref  location  must
        start with a label and a formallist. GT.M prohibits entryrefs with
        offsets during parameter passing.

   o    The optional elements in the  parameter  list  specify  expressions
        that the JOB evaluates and passes as values.

   o    The  keywords  specify  optional  processparameters  that  control
        aspects of the environment for the new process.

   o    If the JOB command has only one processparameter,  the  surrounding
        parentheses are optional.

   o    Some keywords take numeric or string literals delimited by an equal
        sign (=) as arguments. Because the values  are  constants,  strings
        must be enclosed in quotation marks (" "), and  variable  arguments
        require that the entire  argument  be  constructed  and  referenced
        using indirection.

   o    The optional numeric expression specifies a time in  seconds  after
        which the command should timeout if unsuccessful; 0  results  in  a
        single attempt.

   o    When a JOB command contains  no  processparameters,  double  colons
        (::) separate the time-out numeric expression from the entryref.

   o    An indirection operator and an expression  atom,  evaluating  to  a
        list of one or more JOB command arguments, form  a  legal  argument
        for a JOB command.

   o    The maximum command-line length from a JOB command is 8192 bytes.

   The operating system deletes the resultant process  when  execution  of
   its  GT.M  process  is  complete.  The  resultant  process  executes
   asynchrounously  with  the  current  process.  Once  GT.M  starts  the
   resultant process, the current process continues.

   If a JOB command specifies a timeout, and GT.M  creates  the  resultant
   process before the timeout elapses, JOB sets $TEST to true (1). If GT.M
   cannot create the process within the specified timeout, JOB sets $TEST
   to false (0). If  a  JOB  command  does  not  specify  a  timeout,  the
   execution of the command does not affect $TEST.

   If GT.M cannot create the process because of something that is unlikely
   to  change  during  the  timeout  interval,  such  as  invalid  DEFAULT
   directory specification, or the parameter list is  too  long,  the  JOB
   command generates a run-time error. If the command does not  specify  a
   timeout and the environment does not provide  adequate  resources,  the
   process waits until resources become available to create the resultant
   process.

2 The_JOB_Env
   The JOB Environment

   When the JOB is forked,  UNIX  creates  the  environment  for  the  new
   process by copying the environment  of  the  process  issuing  the  JOB
   command and making a few minor modifications.By default,  the  standard
   input is assigned to the null device, the standard output  is  assigned
   to  routinename.mjo,  and  the  standard  error  is  assigned  to
   routinename.mje.

3 JOB_Impl_for_Dir
   JOB Implications for Directories

   By default, GT.M uses the  current  working  directory  of  the  parent
   process for the working directory of the initiated process.

   If the files specified by processparameters do not exist, and GT.M does
   not have permission to create them, the JOBed process terminates. When
   the corresponding files are  in  the  current  working  directory,  the
   OUTPUT, INPUT, and  ERROR  processparameters  do  not  require  a  full
   pathname.

2 JOB_ProcParam
   JOB Processparameters

   The following sections describe the processparameters available for the
   JOB command in GT.M.

3 DEFAULT
   DEF[AULT]=strlit

   The string literal specifies the default directory.

   The maximum directory length is 255 characters.

   If the JOB command does not specify a DEFAULT directory, GT.M uses the
   current default directory of the parent process.

3 ERROR
   ERR[OR]=strlit

   The string literal specifies a value for stderr.

   The maximum string length is 255 characters.

   By default, JOB constructs the error file from the routinename using a
   file extension of .mje: the default directory of the process created by
   the JOB command.

3 GBLDIR
   GBL[DIR]=strlit

   The string literal specifies  a  value  for  the  environment  variable
   gtmgbldir.

   The maximum length of the value permitted is 255 characters.

   By default, the job uses the same specification for gtmgbldir  as  that
   defined for the process using the JOB command.

3 INPUT
   IN[PUT]=strlit

   The string literal specifies a value for stdin.

   The maximum string length is 255 characters.

   GT.M does not supply a default file extension.

   By default, the job takes its input from the null device.

3 OUTPUT
   OUT[PUT]=strlit

   The string literal specifies a value for stdout.

   The maximum string length is 255 characters.

   By  default,  JOB  constructs  the  output  file  pathname  from  the
   routinename using a file extension of  .mjo  and  the  current  default
   directory of the process created by the JOB command.

3 STARTUP
   STA[RTUP]=strlit

   The string literal specifies a command line that GT.M invokes  a  shell
   to execute before executing the GT.M  routine.  The  command  line  may
   invoke a shell script or other images.

        The executed command does not affect the environment of  the  JOBed
        process.

2 Ex_of_JOB
   Examples of JOB

   Example:


   GTM>JOB ^TEST

   This creates a job that starts doing the routine ^TEST in  the  current
   working directory.

   Example:


   JOB PRINTLABELS(TYPE,PRNTR,WAITIM)

   This passes three values (TYPE, PRNTR, and  WAITIM)  to  the  new  job,
   which starts at the label PRINTLABELS of the current routine.

1 KILL
   Kill

   The KILL command deletes local or global variables and their descendant
   nodes.

   The format of the KILL command is:


   K[ILL][:tvexpr] [glvn|[(]lvn[,...][)][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional global or local variable name specifies  the  variable
        to delete; KILL deletes not only  the  variable  specified  in  the
        argument, but also all variables descended from that variable, that
        is, those starting with the identical key-prefix.

   o    KILLing a variable that does not currently exist has no effect.

   o    The KILL command without an argument deletes all currently existing
        local variables; in this case, at least two (2) spaces must follow
        the KILL to separate it from the next command on the line.

   o    When a KILL argument is enclosed in parentheses,  that  "exclusive"
        KILL deletes  all  local  variables  except  those  listed  in  the
        argument.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more KILL arguments
   o    form a legal argument for a KILL.

   KILL does not affect copies of local variables that have been "stacked"
   by NEW or parameter passing.

   Because a KILL can have a major impact, use KILL with caution.

2 Ex_of_Kill
   Examples of KILL

   Example:


   GTM>KILL SET a=0,a(1)=1,a(1,1)="under" KILL a(1) ZWR

   a=0

   GTM>

   This uses an argumentless KILL to get a "fresh start" by  deleting  all
   existing local variables. After SETting a, a(1), and a(1,1),  the  KILL
   deletes a(1) and its descendants. The ZWRITE shows only a remaining.

   Example:


   GTM>KILL (a,b),^AB(a,b)

   The first argument (an exclusive KILL)  specifies  to  KILL  all  local
   variables except a and b. The second argument deletes ^AB(a,b) and any
   descendants of that global variable node.

1 LOCK
   Lock

   The LOCK command  is  used  to  reserve  and  release  resource  names,
   providing a semaphore capability for GT.M  processes.  This  capability
   can be used for interprocess synchronization and signaling.

   Assigning a LOCK does not specify any explicit control  over  variables
   and does not directly effect either read or write access to global (or
   local) data. However, an application that adheres  to  clearly  defined
   conventions of LOCKing before any access can indirectly achieve such an
   effect.

   The format of the LOCK command is:


   L[OCK][:tvexpr] [[-|+]nref|(nref[,...])[:numexpr]

   [,...]]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The nref argument specifies a resource name in the  format  of  the
        GT.M name, with  or  without  subscripts  and  with  or  without  a
        preceding caret (^). An nref can  optionally  have  an  environment
        specification, including one without a preceding caret (^).

   o    Outside of transactions, only one process in an environment can own
        a particular LOCK at any given time.

   o    Because the data storage in GT.M uses hierarchical  sparse  arrays,
        and LOCK frequently serves to protect that data from inappropriate
        "simultaneous" access by multiple processes, LOCK  treats  resource
        names in a hierarchical fashion; a LOCK protects not only the named
        resource, but also its ancestors and descendants.

   o    When one or  more  nrefs  are  enclosed  in  parentheses  (),  LOCK
        reserves all the  enclosed  names  "simultaneously,"  that  is,  it
        reserves none of them until all become available.

   o    A LOCK with no  argument  or  an  argument  with  no  leading  sign
        releases all names currently reserved with previous  LOCK  commands
        by the process; when a LOCK has  no  argument,  at  least  two  (2)
        spaces must follow the LOCK to separate it from the next command on
        the line.

   o    A LOCK argument with a leading plus sign  (+)  acquires  the  named
        resources without releasing currently held resources; if the named
        resource is already LOCKed, such a LOCK  "counts  up"  the  process
        interest in the resource.

   o    A LOCK argument with a leading minus sign  (-)  "counts  down"  the
        process interest in a named resource; if the count on a particular
        lock reaches zero (0), GT.M releases the lock without releasing any
        other currently held locks; a LOCK that releases a  named  resource
        not currently owned by the process has no effect.

   o    The optional numeric expression specifies a time in  seconds  after
        which the command should timeout  if  unsuccessful;  0  provides  a
        single attempt.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more LOCK arguments form a legal argument for a LOCK.

   GT.M records LOCK and ZALLOCATE information  in  the  "lock  database."
   GT.M distributes  the  lock  database  in  space  associated  with  the
   database identified by the current Global Directory. However, the lock
   database does not overlap or coincide with the  body  of  the  database
   files holding the global data. Only the LOCK, ZALLOCATE and ZDEALLOCATE
   commands, and the LKE utility program access the lock database.

   GT.M maps reservations of names starting with ^ to  the  database  file
   used to map global variables of the same name. If the Global Directory
   maps the name A to file A.DAT, GT.M maps all reservations on ^A to file
   space associated with A.DAT.

   GT.M maps reservations on names not starting with ^ to  the  region  of
   the database specified with the GDE command LOCK -REGION=. By default,
   when GDE creates a Global Directory any reservations of local names are
   mapped to the region DEFAULT.

   These two factors  effect  the  following  result  in  the  programming
   environment:

   o    ^ reservations automatically intersect for all users  of  the  same
        data in any database  file  independent  of  the  Global  Directory
        mapping that file.

   o    reservations without a leading ^ intersect in an arbitrary pattern
        dependent on the Global Directory and  therefore  controlled  by  a
        design decision made independently of application code design.

   Since GT.M uses  resource  names  as  semaphores  for  signaling  among
   multiple processes in a database environment, they interlock in a tree
   structured fashion. When  LOCK  or  ZALLOCATE  reserves  a  subscripted
   resource name such as ^D(1), other users of the database mapped by the
   LOCKing (or ZALLOCATEing) process  cannot  reserve  ancestors  of  that
   name, such as ^D, or  descendants,  such  as  ^D(1,2),  until  LOCK  or
   ZDEALLOCATE releases that name.

   Execution of the LOCK command does not affect the value or the state of
   a variable. LOCK tests each argument to determine whether  the  process
   can claim the name space. If another GT.M process has a  LOCK  on  that
   name space, GT.M suspends the current process until the  other  process
   releases the name space. To prevent the potential "infinite" suspension
   of a routine execution, specify a timeout for the LOCK command.

   LOCK with a leading plus (+) or minus (-)  sign  (incremental  LOCKing)
   allows the acquisition of locks without releasing currently held locks.
   This can lead to deadlocks.

   To avoid deadlocks, use LOCK without a leading  +  or  -  sign  on  its
   arguments  because  such  a  command  releases  all  previously  LOCKed
   resources; or use a timeout with the LOCK command.

   If a LOCK command specifies a timeout, and GT.M acquires  ownership  of
   the named resource before the timeout elapses, LOCK
   sets $TEST to TRUE (1). If GT.M cannot acquire ownership of  the  named
   resource within the specified timeout, LOCK sets $TEST to FALSE (0). If
   a LOCK command does not specify a timeout, the execution of the command
   does not affect $TEST. If a LOCK with  an  argument  having  a  leading
   minus sign (-) specifies a timeout, the command always  sets  $TEST  to
   TRUE (1).

   If a process issues  a  LOCK  command  for  a  named  resource  already
   ZALLOCATEd by that process, the resource is both ZALLOCATEd and LOCKed.
   LOCK does not release ZALLOCATEd resources. To  release  such  a  named
   resource, the process must both ZDEALLOCATE and  unLOCK  the  resource.
   For more information on ZALLOCATE, refer to the "ZALLOCATE".

2 Locks_within_Trans
   Using Locks within Transactions

   Within transactions LOCKs are used by GT.M to  ensure  the  ability  to
   serialize. There is no  guarantee,  however,  that  attempts  by  other
   processes to examine LOCKs held with a  transaction  will  produce  the
   same results as when LOCKs are  outside  of  a  transaction.  In  other
   words, LOCKs  within  transactions  should  never  be  used  as  simple
   semaphores.

   The LOCK command locks a specified resource name that controls  a  tree
   structured name space. Outside of transactions when one process  in  an
   environment acquires a LOCK or a ZALLOCATE  on  a  named  resource,  no
   other GT.M process in that environment can  LOCK  a  resource  with  an
   "overlapping" name until the first process releases the  LOCK  that  it
   holds.

2 Ex_of_Lock
   Examples of LOCK

   Example:


   LOCK A,^B,@C

   LOCK (A,B,@C)

   The first LOCK command LOCKs A and unLOCKs A before  LOCKing  ^B,  then
   unLOCKs ^B before locking the name specified by  the  variable  C.  The
   second LOCK command acquires all three resources at  once.  GT.M  waits
   until all the named resources in the  argument  list  become  available
   before  LOCKing  all  the  resources.  For  example,  if  the  resource
   specified by the variable C is not available for  LOCKing,  GT.M  waits
   until that resource becomes available before LOCKing A and ^B.

   Example:


   LOCK (A,B)

   LOCK +C

   LOCK -B

   This LOCKs A and B, then incrementally LOCKs C. Finally it releases the
   LOCK on B, while retaining the LOCKs on A and C.

   Example:


   LOCK (A,B,C)

   LOCK +(B,C)

   LOCK -(B)

   This LOCKs A, B and C together. It then increments the lock "counts" of
   B and C. The last LOCK command removes one "count" of  B,  leaving  one
   count of A and B and two counts of C.

   Example:


   LOCK ^D:5

   This command attempts to LOCK ^D with a timeout  of  five  seconds.  If
   LOCK acquires the named resource before the timeout elapses, GT.M sets
   $TEST to 1 (TRUE). If LOCK fails to acquire the named  resource  before
   the timeout elapses, GT.M sets $TEST to 0 (FALSE).

1 MERGE
   Merge

   The MERGE command copies  a  variable  and  all  its  descendants  into
   another variable. MERGE does not delete the destination  variable,  nor
   any of its descendants.

   The format of MERGE command is:


   M[ERGE][:tvexpr] glvn1=glvn2[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command post conditional that controls whether or not
        GT.M executes the command.

   o    When both glvn1 and glvn2 are local variables, the naked indicator
        is not changed.

   o    If glvn2 is a global variable and glvn1 is a local  variable,  then
        the naked indicator references glvn2.

   o    When both are global variables, the state of the naked indicator is
        unchanged if glvn2 is undefined ($DATA(glvn2)=0).

   o    In all other cases including $DATA(glvn2)=10, the  naked  indicator
        takes the same value that it would have if the SET command replaced
        the MERGE command and glvn2 had a value.

   o    If glvn1 is a descendant of glvn2, or if glvn2 is a  descendant  of
        glvn1; GT.M generates an error.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more MERGE arguments form a legal argument for a MERGE.

   MERGE simplifies the copying  of  a  sub-tree  of  a  local  or  global
   variable to another local or global variable. A sub-tree is all global
   or local variables that are descendants of an specified variable. MERGE
   offers a one-command alternative to the  current  technique  for  doing
   sub-tree  copy  (that  is,  a  series  of  SET  commands  with  $ORDER
   references).

        GT.M may permit certain syntax or actions that are described by the
        standard as in error. For example, a MERGE command  that  specifies
        an  operation  where  the  source  and  destination  overlap  but
        $DATA(source)=0 does not produce an error (which is equivalent to a
        no-operation).

2 Ex_of_Merge
   Examples of MERGE

   Example:


   GTM>SET ^gbl1="one"

   GTM>SET ^gbl1(1,1)="oneone"

   GTM>SET ^gbl1(1,1,3)="oneonethree"

   GTM>SET ^gbl1(1,2,4)="onetwofour"

   GTM>SET ^gbl2(2)="gbl2_2"

   GTM>SET ^gbl2(2,1,3)="gbl2_2_1_3"

   GTM>SET ^gbl2(2,1,4,5)="gbl2_2_1_4_5"

   GTM>MERGE ^gbl1(1)=^gbl2(2)

   GTM>WRITE $REFERENCE

   ^gbl1(1)

   GTM>ZWRITE ^gbl1

   ^gbl1="one"

   ^gbl1(1)="gbl2_2"

   ^gbl1(1,1)="oneone"

   ^gbl1(1,1,3)="gbl2_2_1_3"

   ^gbl1(1,1,4,5)="gbl2_2_1_4_5"

   ^gbl1(1,2,4)="onetwofour"

   GTM>ZWRITE ^gbl2

   ^gbl2(2)="gbl2_2"

   ^gbl2(2,1,3)="gbl2_2_1_3"

   ^gbl2(2,1,4,5)="gbl2_2_1_4_5"

   GTM>

   The example illustrates how MERGE copies a sub-tree of one global into
   another. The nodes in the sub-tree of ^gbl(2), for which $DATA() value
   is 1 or 11, are copied to sub-tree of ^gbl1(1) as follows:

   ^gbl1(1) is updated with value of ^gbl2(2)

   ^gbl1(1,1,3) is updated with value of ^gbl2(2,1,3)

   ^gbl1(1,1,4,5) is updated with value of ^gbl2(2,1,4,5)

   Since ^gbl1(2,1) and ^gbl2(2,2,4) do not have values  ($DATA()=0),  the
   corresponding nodes ^gbl1(1,1) and ^gbl(1,2,4)  respectively  are  left
   unchanged. The naked indicator  takes  the  value  ^gbl(1)  as  if  SET
   replaced MERGE. Notice that the MERGE command does not change ^gbl2(2)
   or its descendants. Ancestor nodes of ^gbl(1) are also left unchanged.

   Example:


   GTM>KILL

   GTM>SET ^gbl(1,2)="1,2"

   GTM>MERGE lcl(3,4)=^gbl(1)

   GTM>SET ^("naked")=2

   GTM>ZWRITE ^gbl

   ^gbl(1,2)="1,2"

   ^gbl("naked")=2

   GTM>ZWRITE lcl

   lcl(3,4,2)="1,2"

   GTM>

   The example illustrates how MERGE creates a sub-tree of a variable when
   the variable does not exist. Also, notice how the  naked  indicator  is
   set when the source of the MERGE is a  global  and  the  destination  a
   local.

1 NEW
   New

   The NEW command "stacks" copies of local  variables  and  reinitializes
   the variables. An explicit or  implicit  QUIT  from  a  DO,  XECUTE  or
   extrinsic function "unstacks" the NEWed variables,  that  is,  restores
   the variable to the stacked value. A NEW lasts  only  for  the  current
   scope of execution.

   The format of the NEW command is:


   N[EW][:tvexpr] [[(]lvn[,...][)][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    NEW arguments are unsubscripted local variable names;  NEW  affects
        not only the variable specified  in  the  argument,  but  also  all
        variables descended from that variable.

   o    When an undefined variable is NEWed, the fact that it is undefined
        is "stacked", and when leaving the current  scope,  it  returns  to
        being undefined, that is, the variable is KILLed.

   o    Without  an  argument  GT.M  NEWs  all  currently  existing  local
        variables; in this case, at least two (2) spaces  must  follow  the
        NEW to separate it from the next command on the line.

   o    When a NEW  argument  is  enclosed  in  parentheses,  that  NEW  is
        considered "exclusive" and the variables inside the parentheses are
        excluded from the effect of the NEW.

   o    When the flow of execution leaves the scope of an  argumentless  or
        an exclusive NEW, GT.M restores  all  stacked  variables  to  their
        previous values, and deletes all other local variables.

   o    The intrinsic special  variables  $ESTACK,  $ETRAP,  $ZGBLDIR,  and
        $ZYERROR can be an explicit argument of a NEW.

   o    The intrinsic special variable  $ZTRAP  can  also  be  an  explicit
        argument of a NEW; this stacks the  current  value  of  $ZTRAP  and
        assigns $ZTRAP a null value ($ZTRAP="").

   o    An indirection operator and an expression atom evaluating to a list
        of one or more NEW arguments form a legal argument for a NEW.

   The NEW command provides a  means  of  confining  the  scope  of  local
   variables. NEW operates only on unsubscripted local names and  acts  on
   the entire named array.

2 Ex_of_New
   Examples of NEW

   Example:


   SET A(1)=1,B=4,C=5

   WRITE !,"VARIABLES BEFORE NEW:",!

   ZWRITE

   DO LABEL

   WRITE !,"VARIABLES AFTER RETURN:",!

   ZWRITE

   QUIT

   LABEL NEW A SET C=7

   WRITE !,"VARIABLES AFTER NEW:",!

   ZWRITE

   QUIT

   Produces the results:


   VARIABLES BEFORE NEW:

   A(1)=1

   B=4

   C=5

   VARIABLES AFTER NEW:

   B=4

   C=7

   VARIABLES AFTER RETURN:

   A(1)=1

   B=4

   C=7

   Example:


   SET (A,B,C,D)="TEST"

   DO LABEL

   WRITE !,"VARIABLES AFTER RETURN:",!

   ZWRITE

   QUIT

   LABEL NEW (B,C) SET (A,B,Z)="NEW"

   WRITE !,"VARIABLES AFTER EXCLUSIVE NEW:",!

   ZWRITE

   QUIT

   Produces the results:


   VARIABLES AFTER EXCLUSIVE NEW:

   A="NEW"

   B="NEW"

   C="TEST"

   Z="NEW"

   VARIABLES AFTER RETURN:

   A="TEST"

   B="NEW"

   C="TEST"

   D="TEST"

1 OPEN
   Open

   The OPEN command creates a connection between  a  GT.M  process  and  a
   device.

   The format of the OPEN command is:


   O[PEN][:tvexpr] expr[:[(keyword[=expr][:...])]

   [:numexpr]][,...]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to OPEN.

   o    The optional keywords specify deviceparameters that control device
        behavior; some deviceparameters  take  arguments  delimited  by  an
        equal sign (=); if the argument only contains one deviceparameter,
        the surrounding parentheses are optional.

   o    The optional numeric expression specifies a time in  seconds  after
        which the  command  should  timeout  if  unsuccessful;  choosing  0
        results in a single attempt to open the device.

   o    When  an  OPEN  command  specifying  a  timeout  contains  no
        deviceparameters, double colons (::) separate the  timeout  numeric
        expression from the device expression.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more OPEN arguments form a legal argument for an OPEN.

1 QUIT
   Quit

   Except when a QUIT appears on a line after  a  FOR,  the  QUIT  command
   terminates  execution  of  the  current  GT.M  invocation  stack  level
   initiated by a DO, XECUTE, extrinsic function or special variable, and
   returns control to the next "lower" level. In this case, QUIT restores
   any values stacked at  the  current  level  by  NEWs  or  by  parameter
   passing. When a QUIT appears on the line following a FOR, it terminates
   execution of the FOR.

   The format of the QUIT command is:


   Q[UIT][:tvexpr] [expr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    When a QUIT terminates an  extrinsic  function,  it  must  have  an
        argument that supplies the value returned by the function;  in  all
        other cases, QUIT must not have an argument and must be followed by
        at least two (2) spaces to separate it from the next command on the
        line.

   o    An indirection operator and an expression atom evaluating to a QUIT
        argument form a legal argument for a QUIT.

   The QUIT performs two similar, but different,  functions  depending  on
   its context. Because FORs do not add  levels  to  the  GT.M  invocation
   stack, QUITs inside FOR loops simply terminate  the  loop.  QUITs  that
   terminate DOs, XECUTEs and extrinsics remove a  GT.M  invocation  stack
   level and therefore may adjust the local variable environment resulting
   from previous NEWs or parameter passing. A QUIT from an extrinsic or a
   frame created by an argumentless  DO  restores  $TEST  to  its  stacked
   value.

   Attempting to QUIT (implicitly or explicitly) from code  invoked  by  a
   DO, XECUTE or extrinsic after that code issued a TSTART not yet matched
   by a TCOMMIT, produces an error.

2 Ex_of_Quit
   Examples of QUIT

   Example:


   DO A

   QUIT

   A WRITE !,"This is label A"

   The explicit QUIT at the line preceding the label  A  prevents  line  A
   from executing twice. The sub-routine at line  A  terminates  with  the
   implicit QUIT at the end of the routine.

   Example:


   WRITE $$ESV

   QUIT

   ESV()

   QUIT "value of this Extrinsic Special Variable"

   Because the label ESV has an argument list (which is empty),  GT.M  can
   only legally reach that label with a extrinsic invocation. The QUIT on
   the second line prevents execution from erroneously  "falling  through"
   to the line labelled ESV. Because  ESV  identifies  a  subroutine  that
   implements an extrinsic special variable, the QUIT on  the  line  after
   ESV has an argument to provide the value of the extrinsic.

   Example:


   SET x="" F S x=$O(^BAL(x)) Q:x]]"AR5999"!'$L(x) D STF

   The postconditional QUIT terminates the FOR loop.

1 READ
   Read

   The READ command transfers input from the current device to a global or
   local variable specified as a READ argument. For convenience, READ also
   accepts arguments that perform limited output to the current device.

   The format of the READ command is:


   R[EAD][:tvexpr] (glvn|*glvn|glvn#intexpr)[:numexpr]|strlit|fcc[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    A subscripted  or  unsubscripted  global  or  local  variable  name
        specifies a variable into which to store the  input;  the  variable
        does not have to exist prior to the  READ;  if  the  variable  does
        exist prior to the READ, the READ replaces its old value.

   o    When an asterisk (*) immediately precedes the variable  name,  READ
        accepts one character of input and places the ASCII code  for  that
        character into the variable.

   o    When  a  number-sign  (#)  and  a  non-zero  integer  expression
        immediately  follow  the  variable  name,  the  integer  expression
        determines the maximum number of characters accepted  as  input  to
        the read; such reads  terminate  when  GT.M  reads  the  number  of
        characters specified by the  integer  expression  or  a  terminator
        character in the input stream, whichever occurs first.

   o    The optional numeric expression specifies  a  time  in  seconds  at
        most, for which the command waits for input to be terminated. When
        a timeout is specified, if the input has been terminated before the
        timeout expires, $TEST is set to 1 (true), otherwise, $TEST is set
        to 0 (false).

   o    To provide a concise means of issuing prompts,  GT.M  sends  string
        literal and format control character (!,?intexpr,#) arguments of a
        READ to the current device as if they were arguments of a WRITE.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more READ arguments form a legal argument for a READ.

1 SET
   Set

   SET assigns values to variables or to a selected portion of a variable.

   The format of the SET command is:


   S[ET][:tvexpr] glvn|$EXTRACT()|$PIECE()|(glvn[,...])=expr[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    A subscripted or unsubscripted local or global variable name on the
        left of the equal-sign (=) specifies a variable in which  to  store
        the expression found on the  right  side  of  the  equal-sign;  the
        variable need not exist prior to the SET; if  the  variable  exists
        prior to the SET, the SET replaces its old value.

   o    During a SET, GT.M evaluates the  right  side  of  the  equal  sign
        before the left; this is an exception to the left-to-right order of
        evaluation  in  GT.M  and  means  that  GT.M  maintains  the  naked
        indicator using the expression on the right-hand side of the equal
        sign (=) before setting the variable.

   o    When the portion of the argument to the left of the  equal-sign  is
        in the form of a list of variables  enclosed  in  parentheses,  SET
        assigns the value of the expression on the right of the equal sign
        to all the variables.

   o    When the portion of the argument to the left of the equal  sign  is
        in the form of a $PIECE function, SET replaces the specified piece
        or pieces of the variable (specified as the first argument  to  the
        $PIECE() form) with the value of the expression on the  right  side
        of the equal-sign; if the variable did not exist prior to  the  SET
        or does not currently contain the pieces identified by the optional
        third  and  fourth  arguments  to  the  $PIECE()  form,  SET  adds
        sufficient leading delimiters, as specified by the second argument
        to the $PIECE form, to make the assignment fit the  $PIECE()  form.
        Note that if the fourth argument exceeds the  third  argument,  the
        target glvn is not changed and the  naked  indicator  is  also  not
        modifed.

   o    When the portion of the argument to the left of the equal  sign  is
        in the form of a $EXTRACT  function,  SET  replaces  the  specified
        character or characters of the variable  (specified  as  the  first
        argument to the $EXTRACT() form) with the value of  the  expression
        on the right side of the equal-sign; if the variable did not exist
        prior to the SET or does not contain the characters  identified  by
        the optional second and third arguments to the $EXTRACT() form, SET
        adds sufficient leading spaces  to  make  the  assignment  fit  the
        $EXTRACT() form. Note that if the third argument exceeds the second
        argument, the target glvn is not changed and the naked indicator is
        also not modifed.

   o    The left-hand side of the equal-sign may also contain  any  of  the
        following Intrinsic Special Variables:

$ECODE
$ETRAP
$X
$Y
$ZCOMPILE
$ZDIRECTORY
$ZERROR
$ZGBLDIR
$ZINTERRUPT
$ZMAXTPTIME
$ZPROMPT
$ZROUTINES
$ZSOURCE
$ZSTATUS
$ZSTEP
$ZTRAP
$ZYERROR
   o    An indirection operator and an expression atom evaluating to a list
        of one or more SET arguments form a legal argument for a SET.

   Because GT.M does not require predeclaration or typing of variables, a
   SET with proper syntax always succeeds regardless of the prior state or
   value of the variable, as long as GT.M can evaluate the  expression  to
   the right of the equal sign (=).

2 Ex_of_Set
   Examples of SET

   Example:


   GTM>KILL SET a="x",(b,c)=1,@a="hello" ZWRITE

   a=x

   b=1

   c=1

   x="hello"

   GTM>

   The KILL command deletes any previously defined  local  variables.  The
   SET command has three  arguments.  The  first  shows  a  simple  direct
   assignment. The second shows the form that assigns the  same  value  to
   multiple variables. The third shows atomic indirection on the  left  of
   the equal  sign.  The  ZWRITE  command  displays  the  results  of  the
   assignments.

   Example:


   GTM>SET ^(3,4)=^X(1,2)

   Because GT.M evaluates the right-hand side of the equal sign before the
   left-hand  side  within  a  SET  argument,  the  right-hand  expression
   determines the
   naked reference indicator prior to evaluation of  the  left-hand  side.
   Therefore, this example assigns ^X(1,3,4) the value of ^X(1,2).

   Example:


   GTM>KILL x SET $P(x,"^",3)="piece 2" ZWRITE x

   x="^^piece 2"

   GTM>

   This SET demonstrates a "setpiece" and shows how SET generates missing
   delimiters when required.

   Example:


   GTM>SET x="I love hotdogs"

   GTM>SET $EXTRACT(x,3,6)="want"

   GTM>WRITE x

   I want hotdogs

   GTM>SET $EXTRACT(x,7)=" many "

   GTM>WRITE x

   I want many hotdogs

   GTM>

   The SET $EXTRACT command replaces and extracts the specified characters
   with the value of  the  expression  on  the  right  hand  side  of  the
   equal-sign (=).

1 TCOMMIT
   TCommit

   The TCOMMIT command marks the end of a transaction  or  sub-transaction
   and decrements $TLEVEL. If TCOMMIT  marks  the  end  of  a  transaction
   (decrements $TLEVEL to zero), it invokes  a  COMMIT,  which  makes  the
   database updates performed by the transaction  generally  available.  A
   TCOMMIT issued when no transaction is in progress ($TLEVEL=0) produces
   an error.

   The format of the TCOMMIT command is:


   TC[OMMIT][:tvexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    Because TCOMMIT has no argument,  at  least  two  (2)  spaces  must
        follow the command to separate it from  the  next  command  on  the
        line.

   For an example of the use of the TCOMMIT command, refer to the chapter
   on General Language Features of M in GT.M Programmer's Guide.

1 TRESTART
   TREstart

   The TRESTART command attempts to RESTART  the  current  transaction.  A
   RESTART transfers control back to the initial TSTART and restores much
   of the process state to what it was  when  that  TSTART  was  executed.
   Errors are produced if a TRESTART is used when  no  transaction  is  in
   progress ($TLEVEL=0) and when the transaction  does  not  have  RESTART
   enabled.

   The format for the TRESTART command is:


   TRE[START][:tvexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    Because TRESTART has no argument, at  least  two  (2)  spaces  must
        follow the command to separate it from  the  next  command  on  the
        line.

   TRESTARTs (and implicit RESTARTs) do not  restore  any  device  states;
   they do restore the following to the state they had when GT.M executed
   the initial TSTART:

   o    $TEST

   o    The naked indicator

   o    LOCKs held by the process

   They also restore any local variables  named  by  one  or  more  active
   TSTARTs to the values they had when they were first named.

   For an example of the use of the TRESTART command, refer to the chapter
   on "General Language Features of M" in the GT.M Programmer's Guide.

1 TROLLBACK
   TROllback

   The TROLLBACK command terminates a transaction by causing  a  ROLLBACK,
   which removes all database  updates  performed  within  a  transaction.
   TROLLBACK also sets $TLEVEL  and  $TRESTART  to  zero  (0).  Issuing  a
   TROLLBACK when no transaction is in progress  ($TLEVEL=0)  produces  an
   error.

   The format of the TROLLBACK command is:


   TRO[LLBACK][:tvexpr] [intexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional integer expression indicates  an  argument  specifying
        incremental rollback. If the value of the  argument  expression  is
        greater than zero, it specifies the value of $TLEVEL to be achieved
        by the rollback. If the value of the expression is less than zero,
        the result is the number of levels to  rollback.  For  example;  -1
        means rollback one level. If the argument expression is  zero,  the
        effect is same as not specifying the argument, that is, the entire
        GT.M transaction is rolled back.

   Attempting  to  rollback  more  than  $TLEVEL  levels  (the  outermost
   transaction) generates an error.

   o    When the TROLLBACK has no argument, at least two  (2)  spaces  must
        follow the command to separate it from  the  next  command  on  the
        line.

   In order to allow for  error  recovery  and/or  access  to  the  global
   context of the  error,  errors  do  not  initiate  implicit  ROLLBACKs.
   Therefore, the code for  handling  errors  during  transactions  should
   generally include a TROLLBACK. Because the TROLLBACK releases resources
   held by the transaction, it should appear as early as possible  in  the
   error handling code.

        A TROLLBACK does not cause a transfer of control but  is  typically
        associated with one such as a QUIT or GOTO.

   For an example of the use  of  the  TROLLBACK  command,  refer  to  the
   chapter on "General Language Features of M" in  the  GT.M  Programmer's
   Guide.

1 TSTART
   TStart

   A  TSTART  command  marks  the  beginning  of  a  transaction  or
   sub-transaction and increments $TLEVEL. When TSTART marks the beginning
   of a transaction  ($TLEVEL=1),  its  arguments  determine  whether  the
   transaction may RESTART and whether serializability is enforced.  If  a
   transaction may RESTART, the TSTART  arguments  determine  which  local
   variables are restored during a RESTART. Serializability is enforced by
   LOCK commands or, if the SERIAL keyword is specified, by GT.M.

   The format of the TSTART command is:


   TS[TART][:tvexpr] [([lvn...])|lvn|*|][:keyword|(keyword...)]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    If $TLEVEL is 0 before the TSTART, the TSTART starts a transaction;
        otherwise it starts a sub-transaction.

   o    If the TSTART initiates  a  transaction  and  the  portion  of  the
        argument before the colon (:) delimiter is empty,  the  transaction
        is not eligible for RESTART. If the  TSTART  starts  a  transaction
        ($TLEVEL=0) and the portion of the argument before the colon is not
        empty, the transaction is eligible for RESTART. If  the  TSTART  is
        nested (starts a sub-transaction), its arguments have no effect on
        whether the transaction is eligible for RESTART.

   o    If the portion of the argument before the colon is an asterisk (*),
        any subsequent RESTART restores all local variables  to  the  value
        they had when the TSTART was executed.

   o    If the portion of the argument before the colon is an unsubscripted
        local  variable  name  or  a  list  of  such  names  enclosed  in
        parentheses, a RESTART restores the named variables  to  the  value
        they had when the TSTART was executed.

   o    If the portion of the argument before the colon is a set  of  empty
        parentheses (), a RESTART does not restore any local variables.

   o    The optional portion of the argument after the colon is  a  keyword
        or a colon-separated list  of  keywords  enclosed  in  parentheses,
        where the keywords specify transaction characteristics.

   o    An indirection operator and an  expression  atom  evaluating  to  a
        TSTART argument form a legal argument for a TSTART.

   A TSTART within a transaction starts a sub-transaction. The argument to
   such a TSTART has no effect on whether  the  existing  transaction  may
   RESTART or whether serializability of the transaction is enforced. This
   type of TSTART may add local variables to be restored in a transaction
   that has RESTART enabled.

   It is good coding  practice  to  synchronize  enabling  of  RESTART  on
   TSTARTs at all levels of a transaction. A nested TSTART that  does  not
   permit RESTART where  the  transaction  does,  may  indicate  that  the
   sub-transaction has not been coded to properly handle RESTART.

   Sub-transactions cannot COMMIT independently from the transaction, nor
   can they RESTART independently. Sub-transactions  exist  largely  as  a
   programming convenience to allow flexibility in organizing  code  in  a
   modular fashion, and in addition to allow incremental ROLLBACKs.

   When journaling, a transaction with  an  initial  TSTART  that  has  an
   argument specifying TRANSACTIONID=expr, where  expr  is  an  expression
   that evaluates to the keyword (case insensitive) BA[TCH], does not wait
   for the journal update to be written before returning  control  to  the
   application after a successful TCOMMIT. The goal of this feature is to
   permit application control over any performance impact of journaling on
   any subset of transactions that can be recreated or recovered by means
   other than journaling.

   For an example of the use of the TSTART command, refer to  the  chapter
   on "General Language Features of M" in the GT.M Programmer's Guide.

   The following keywords may appear in a TSTART argument:

2 SERIAL
   S[ERIAL]

   The SERIAL keyword indicates that GT.M must ensure the serializability
   of the transaction. When the SERIAL keyword is absent, the GT.M program
   must ensure serializability by proper use of LOCK commands. On a nested
   TSTART, this portion of the argument is ignored.

2 TRANSACTIONID
   T[RANSACTIONID]=expr

   The  TRANSACTIONID  keyword  declares  an  arbitrary  transaction
   identification.

   If TRANSACTIONID="BATCH" or "BA" at transaction completion, the process
   immediately continues  execution.  When  a  process  issues  a  [final]
   TCOMMIT for a transaction and journaling  is  active,  by  default  the
   process waits until the entire transaction is written  to  the  journal
   file(s) before executing the next  command.  This  ensures  that  every
   transaction is durable before the process moves on to the next step.

   Transactions  flagged  as  "BATCH"  have  lower  latency  and  higher
   throughput, but a lower guarantee of durability. Normally this flag is
   used when operational procedures (such as a backup) or application code
   (such as a checkpoint algorithm)  provides  an  acceptable  alternative
   means of ensuring durability.

1 USE
   Use

   The USE command selects the current device for READs (input) and WRITEs
   (output).

   The format of the USE command is:


   U[SE][:tvexpr] expr[:(keyword[=expr][:...])][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to  make  the  current
        device.

   o    A USE that selects a device not currently  OPENed  by  the  process
        causes a run-time error.

   o    The optional keywords specify deviceparameters that control device
        behavior; some deviceparameters  take  arguments  delimited  by  an
        equal sign (=); if the argument only contains one deviceparameter,
        the surrounding parentheses are optional.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more USE arguments form a legal argument for a USE.

   For more information on USE, devices and deviceparameters, refer to the
   "Input/Output Processing" chapter in the GT.M Programmer's Guide.

1 VIEW
   View

   The VIEW command adjusts an environmental factor selected by a keyword
   argument.  For  example,  VIEW  controls  journal  buffer  flushing,
   determines whether GT.M reports undefined variables as errors or treats
   them as null,  and  determines  which  BREAK  commands  should  display
   messages.

   The format of the VIEW command is:


   V[IEW][:tvexpr] keyword[:expr2[:...]][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The keyword specifies the environmental factor to change.

   o    The optional expression following the keyword specifies the nature
        of the change to the environmental factor.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more VIEW arguments form a legal argument for a VIEW

2 Key_Words_View
   Key Words in VIEW Command

   The following sections describe the keywords  available  for  the  VIEW
   command in GT.M.

3 BREAKMSG
   "BREAKMSG":value


   Sets the value of the BREAK message mask. When GT.M processes  a  BREAK
   command, the BREAK message mask controls whether to display  a  message
   describing the source of the BREAK.

   The mask uses the following four values  that  are  added  together  to
   provide the BREAKMSG value.

   1 - BREAKs within the body of a program
   2 - BREAKs within a ZBREAK action
   4 - BREAKs within a device EXCEPTION
   8 - BREAKs within a ZSTEP action
   By default GT.M displays all BREAK messages.

   Example:

   GTM>VIEW "BREAKMSG":5

   In this example the BREAKMSG value is 5, representing the sum of 1 and
   4. This enables BREAKS within the body of a program (value 1) and for a
   device EXCEPTION (value 4).

3 GDSCERT
   "GDSCERT":value


   Enables (value=1) or disables (value=0) database block certification.

   Database  block  certification  causes  GT.M  to  check  the  internal
   integrity of every block as it writes the  block.  Block  certification
   degrades performance and exists primarily as a tool for use by Sanchez.
   The default is GDSCERT:0.

3 JNLFLUSH
   "JNLFLUSH"[:region]


   Writes or flushes journaling buffers associated with the  given  region
   to permanent storage, for example, to disk. If the VIEW "JNLFLUSH" does
   not specify the optional region, GT.M flushes all active regions of the
   current Global Directory.

   Normally GT.M writes journal buffers when it fills the  journal  buffer
   pool or when some period of time passes with no journal activity.

   For more information on journaling,  refer  to  the  "GT.M  Journaling"
   chapter in the GT.M Administration and Operations Guide.

3 JNLWAIT
   "JNLWAIT"


   Causes a process to  pause  until  its  journaling  buffers  have  been
   written. JNLWAIT ensures that GT.M successfully transfers all database
   updates issued by the process to the journal file  before  the  process
   continues. Normally, GT.M performs journal buffer writes asynchronously
   while the process continues execution.

   For more information on journaling,  refer  to  the  "GT.M  Journaling"
   chapter in the GT.M Administration and Operations Guide.

3 JOBPID
   "JOBPID":"value"


   Enables (value=1) or disables  (value=0)  the  addition  of  the  child
   process ID to the output and  error  filenames  generated  by  the  JOB
   command.

   This option prevents output files generated by  the  JOB  command  from
   being overwritten each time a new job is spawned from the  GT.M  source
   file.

3 LABELS
   "LABELS":"value"


   Enables (value="LOWER") or disables  (value="UPPER")  case  sensitivity
   for labels within routines.

   It is important to have the same  case  handling  at  compile-time  and
   run-time.

   Because GT.M stores routines as regular files and file names  are  case
   sensitive on UNIX, GT.M always treates routine names as case sensitive.

3 LVNULLSUBS
   "[NO]LVNULLSUBS"


   Allows or disallows local arrays to have null subscripts.  The  default
   is LVNULLSUBS.

3 NOISOLATION
   "NOISOLATION":<expr>


   where expr must evaluate to one of the following forms

   o    "", that is, empty string : turn off the feature  for  all  globals
        for which it has previously been turned on

   o    "^gvn1,^gvn2,..." : turn on the feature  for  the  globals  in  the
        list, turning it off for globals for which it has  previously  been
        turned on

   o    "+^gvn1,^gvn2,..." : add these globals to the list of globals that
        have this feature turned on

   o    "-^gvn1,^gvn2,..." : turn off the feature for these globals leaving
        the status for other globals unchanged

   GT.M transaction processing permits the application to specify a set of
   globals that do not require GT.M to  preserve  Isolation,  one  of  the
   "ACID" properties of TP. This shifts the responsibility  for  Isolation
   from GT.M to the application logic, and permits GT.M to  relax  its  TP
   Isolation  rules.  This  avoids  TP  restarts  in  certain  cases  thus
   improving the performance of the application. For example, if a global
   variable includes $JOB as a subscript, the application may  be  written
   and scheduled in such a way that no more than one process uses  a  node
   of that  global  at  any  given  time.  Specifying  such  a  global  as
   "NOISOLATED" avoids transaction  restarts  that  occur  when  different
   processes concurrently update and access nodes that share the same GDS
   block.

   The  rules  for  enforcement  by  GT.M  of  Isolation,  and  therefore
   potentially Consistency, are relaxed for  application-specified  global
   variables in order to allow the application to manage these properties.
   GT.M is responsible for  Atomicity  and  Durability,  as  well  as  for
   database integrity for all variables, and for Isolation and Consistency
   for any global variables for which  the  application  does  not  accept
   responsibility.

   Note that if an  application  incorrectly  specifies  a  global  to  be
   NOISOLATED, severe, and possibly intermittent and difficult to diagnose
   damage to application-level integrity is likely to result.  A  thorough
   understanding of the application is necessary before declaring a global
   to be noisolated. GT.M preserves database integrity (accessibility) for
   NOISOLATED, as well as ISOLATED global variables.

   GT.M ignores attempts to turn on (or off) the feature for globals that
   already have the feature turned on (or off). It is an error  to  modify
   the isolation-status of a global variable within a  transaction  across
   different  references  (either  reads  or  writes)  of  that  global
   variable.The VIEW command by itself is not considered to be a reference
   of the global variable. While  not  recommended  programming  practice,
   this means that a process can change a global's isolation-status within
   a transaction as long as it hasn't referenced it yet.

   Any reads on a NOISOLATION global are validated at the time of the read
   and not re-validated at TCOMMIT time. This means that if the value that
   was read changed after the read but before the TCOMMIT, the transaction
   would still be committed. Therefore it is important that any reads on a
   NOISOLATED global (if any) should be of data that does not change with
   time. Sanchez has not identified applications where this  could  be  an
   issue.

3 PATCODE
   "PATCODE":"tablename"


   Identifies the alternative table of unique patterns for  use  with  the
   "?" operator to  be  loaded  from  the  pattern  definition  file.  For
   additional information refer to the "Internationalization"  chapter  in
   the GT.M Programmer's Guide.

3 PATLOAD
   "PATLOAD":"file-specification"


   Identifies the file containing definitions of unique patterns  for  use
   with the "?" operator. These pattern definitions can be used  in  place
   of, or in addition to, the standard C, N, U, L, and P.

3 UNDEF
   "[NO]UNDEF"


   Enables or disables handling of undefined  variables  as  errors.  With
   UNDEF, GT.M  handles  all  references  to  undefined  local  or  global
   variables as errors. With  NOUNDEF,  GT.M  handles  all  references  to
   undefined local or global variables as if the variable had a  value  of
   the null string. In other words, GT.M treats all variables appearing in
   expressions as if they were the argument of an implicit  $GET().  UNDEF
   is the default.

3 TRACE
   "TRACE":value<expr>


   Traces GT.M program execution and generates profiling information about
   the lines and functions executed;  with  low  impact  on  the  run-time
   performance.

   The feature turns on (value=1) or turns off (value=0)  tracing.  <expr>
   must evaluate to  a  string  containing  the  name  of  a  GT.M  global
   variable. The global may also have subscripts; however  the  subscripts
   must be literals or the special variable $JOB.

        The <expr> is optional when turning tracing off, if it  exists,  it
        overrides the global variable set when tracing was turned on.

   GT.M-tracing uses a technique called Basic Block Counting  where  calls
   are made to special  profiling  functions  at  key  points  in  a  GT.M
   program. A trace consists of the following run-time data as output for
   each GT.M function, as well as for each GT.M statement:

   o    The number of times it is executed.

   o    The total CPU time spent across all invocations for  each  function
        and each GT.M statement as three values: user  time,  system  time,
        and total time.

   Instead of modifying the generated code as  done  by  common  profiling
   tools, such as gprof, GT.M tracing operates entirely  within  the  GT.M
   run-time system; therefore, this feature does  not  require  a  special
   compilation,  has  no  effect  on  code  size  and  minimizes  run-time
   overhead.

   When the feature is turned on, it  gathers  profiling  information  for
   each line and GT.M function invocation. The reported time  for  a  GT.M
   line is the time spent in generated code for that line,  and  does  not
   include time spent in entreyrefs called from that line. When profiling
   is turned off, the  accumulated  statistics  are  loaded  into  a  GT.M
   global. GT.M profiling accumulates and provides the data; the user may
   choose tools and techniques to analyze the data.

   The trace information is  stored  in  the  variable  in  the  following
   format:

   o    If <expr> is a global variable  without  subscripts  name  such  as
        "^foo",  the  trace  information  is  stored  in  the  nodes
        ^foo(<routine>,<label>) and ^foo(<routine>,<label>,<offset>), each
        of  which  has  a  value  in  the  form
        "<count>:<usertime>,:<systemtime>,:<total_time>" on UNIX.

   o    If <expr> has a  value  such  as  "^foo("MYTRACE",$J)",  the  trace
        information  is  stored  in  the  nodes
        ^foo("MYTRACE",<pid>,<routine>,<label>)  and
        ^foo("MYTRACE",<pid>,<routine>,<label>,<offset>), each of which has
        a value in the form "<count>,<usertime>,<systemtime>,<total_time>"
        on UNIX as described above.

   o    For FOR loops, information for each level of the loop is stored in
        the nodes as described above, with the extra subscipts "FOR_LOOP".
        <for_level> is the value of the number of iterations at that level
        of the FOR loop.

   Thus, if the GT.M program lv1.m is:


   lv1 f i=1:1:10 d

   .s l(i)=i

   .d bar

   for i=1:1:5 for j=1:1:4 s lij(i,j)=i+j

   q

   bar s l(-i)=-i

   q


   And the program lv2.m is:

   lv2 VIEW "TRACE":1:"^lvtr"

   d ^lv1

   VIEW "TRACE":0:"^lvtr"

   zwr ^lvtr

   q

   On executing lv2, the output looks like this (times in the example were
   chose for clarity of illustration and are not typical):


   ^lvtr("lv1","bar")="10:8:1:9"

   ^lvtr("lv1","bar",0)="10:5:1:6"

   ^lvtr("lv1","bar",1)="10:3:0:3"

   ^lvtr("lv1","lv1")="1:37:2:39"

   ^lvtr("lv1","lv1",0)="1:8:0:8"

   ^lvtr("lv1","lv1",0,"FOR_LOOP",1)=10

   ^lvtr("lv1","lv1",1)="10:3:1:4"

   ^lvtr("lv1","lv1",2)="10:19:2:21"

   ^lvtr("lv1","lv1",3)="1:15:0:15"

   ^lvtr("lv1","lv1",3,"FOR_LOOP",1)=5

   ^lvtr("lv1","lv1",3,"FOR_LOOP",2)=20

   ^lvtr("lv1","lv1",4)="1:0:0:0"

   ^lvtr("lv2","lv2",1)="1:47:3:50"

   In this case, ^lvtr("lv1","bar",0)="10:5:1:6" means that the statement
   bar s l(-i)=-i was executed 10 times, with a total of 5 microseconds of
   user  time  and  1  microsecond  of  system  time.
   ^lvtr("lv1","lv1")="1:37:2:39" means that 37 microseconds of user time
   was spent within that GT.M frame (lv1^lv1), and does not  include  time
   spent  in  routines  called  from  it  (such  as  bar^lv1),  whereas
   ^lvtr("lv1","lv1",3)= "1:15:0:15" includes the time spent at bar^lv1.

   Note  that  there  is  no  data  in  ^lvtr("lv2","lv2",0)  or  for
   ^lvtr("lv2","lv2",2) because the execution of the lines containing the
   VIEW commands that turn profiling on and off are not profiled.

   Because of the underlying timers provided  by  the  operating  systems,
   times of less than a microsecond are measured as zero. Therefore, even
   if a statement executes one million times, it may report zero  time  if
   it took less than a microsecond each time.

   GT.M profiling cannot handle more than 1024 levels. If  the  GT.M  code
   executed has  more  than  1024  levels,  frame  information  cannot  be
   recorded, and frame information upto the first point where  this  limit
   is reached is reported with a note (":INCOMPLETE DATA: MAXTRACELEVEL" )
   appended to the data.

2 Ex_of_View
   Examples of VIEW

   Example 1:


   GTM>KILL A

   GTM>VIEW "NOUNDEF"

   GTM>WRITE A,?10,$L(A)

   0

   GTM>

   This demonstrates how a VIEW that specifies NOUNDEF prevents UNDEFined
   errors.

   Example 2:


   GTM>ZL "NOSENSE"

   %GTM-E-LABELMISSING Label referenced but

   not defined:lab

   %GTM-I-SRCNAM in source module /usr/work/NOSENSE.m

   GTM>

   GTM>ZPRINT ^NOSENSE


   NOSENSE;

   DO lab

   QUIT

   LAB WRITE !,"THIS IS NOSENSE"

   QUIT


   GTM>VIEW "LABELS":"UPPER"

   GTM>ZLINK "NOSENSE.m"

   GTM>DO ^NOSENSE

   THIS IS NOSENSE

   GTM>

   This demonstrates use of VIEW "LABELS"  to  make  label  handling  case
   insensitive. Notice that the routine was ZLINKed with an  extension  of
   .m to force a recompile  and  ensure  that  the  object  code  and  the
   run-time handling of labels is the same.

1 WRITE
   Write

   The WRITE  command  transfers  a  character  stream  specified  by  its
   arguments to the current device.

   The format of the WRITE command is:


   W[RITE][:tvexpr] expr|*intexpr|fcc[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    An expression argument supplies the text of a WRITE.

   o    When a WRITE argument consists of a leading asterisk  (*)  followed
        by  an  integer  expression,  WRITE  outputs  one  ASCII  character
        associated with the ASCII code specified by the integer evaluation
        of the expression.

   o    WRITE arguments may  also  be  format  control  characters;  format
        control characters modify the position  of  a  virtual  cursor:  an
        exclamation point (!)  produces  a  new  line,  a  number-sign  (#)
        produces a  new  page  and  a  question-mark  (?)  followed  by  an
        expression moves the virtual cursor to the column specified by the
        integer evaluation of the  expression  provided  that  the  virtual
        cursor is to the "left" of the specified  column;  if  the  virtual
        cursor is not to the left of the specified column, then the text is
        printed at the current cursor position.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more WRITE arguments form a legal argument for a WRITE.

   For more information  on  WRITE,  devices,  input,  output  and  format
   control characters, refer to the "Input/Output Processing"  chapter  in
   GT.M Programmer's Guide.

1 XECUTE
   Xecute

   The XECUTE command makes an entry in  the  GT.M  invocation  stack  and
   executes the argument as GT.M code.

   The format of the XECUTE command is:


   X[ECUTE]:tvexpr expr[:tvexpr][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies a fragment of GT.M source code.

   o    The optional  truth-valued  expression  immediately  following  the
        argument expression  specifies  the  argument  postconditional  and
        controls whether GT.M performs an XECUTE with that argument.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more XECUTE  arguments  form  a  legal  argument  for  an
        XECUTE.

   An explicit or implicit QUIT within the scope of the  XECUTE,  but  not
   within the scope of any other DO, FOR,  XECUTE  or  extrinsic,  returns
   execution to the instruction following the calling point. This  may  be
   the next XECUTE argument or another command. At the  end  of  the  code
   specified by the XECUTE argument expression, GT.M performs an implicit
   QUIT.

   Because XECUTE causes run-time compilation  in  GT.M,  and  because  it
   tends to obscure code, use XECUTE only when other approaches clearly do
   not meet your particular requirement.

2 Ex_of_Xecute
   Examples of XECUTE

   Example:


   GTM>SET A="HELLO" XECUTE "WRITE A"

   HELLO

   GTM>

   This demonstrates a simple use of XECUTE.

   Example:


   SET x="" F S x=$O(^%x(x)) Q:x="" X x

   This $ORDER() loop XECUTEs code out of the first level  of  the  global
   array ^%x. Note that, in most cases, having the code in a  GT.M  source
   file, for example TMPX.m, and using a DO ^TMPX improves efficiency.

1 ZALLOCATE
   ZAllocate

   The ZALLOCATE command reserves the  specified  name  without  releasing
   previously reserved names. Other  GT.M  processes  cannot  reserve  the
   ZALLOCATEd name with a ZALLOCATE or LOCK command.

   The ZALLOCATE command  provides  compatibility  with  some  other  GT.M
   implementations. The M Development Committee chose to add the +  and  -
   delimiters to the LOCK command (incremental locking) rather than adopt
   the ZALLOCATE  and  ZDEALLOCATE  approach.  Therefore,  when  a  design
   requires an incremental lock mechanism, LOCK +/- has the advantage over
   ZALLOCATE / ZDEALLOCATE of being part of the M standard. LOCK +/- also
   has the advantage of working symmetrically when  routines  using  LOCKs
   are nested. That is, a ZALLOCATE command issued  by  a  process  for  a
   named resource already ZALLOCATEd by that process results in no change
   of state. This means that routines that  do  ZALLOCATE  followed  by  a
   ZDEALLOCATE on a named resource that is already ZALLOCATEd by the same
   process (at routine entry time), will end up ZDEALLOCATEing  the  named
   resource (which might not be desired). On the  other  hand,  a  LOCK  +
   command issued by a process for a named resource already LOCKed by that
   process causes the LEVEL of the LOCK to be incremented (as  seen  in  a
   ZSHOW "L" output). Every LOCK - command on that named  resource  causes
   the LEVEL to be decremented.  When  the  LEVEL  becomes  0,  the  named
   resource is no longer LOCKed.

   For more information  on  troubleshooting  LOCKs  with  the  GT.M  Lock
   Utility  (LKE),  refer  to  the  appropriate  chapter  of  the  GT.M
   Administration and Operations Guide.

   The format of the ZALLOCATE command is:


   ZA[LLOCATE][:tvexpr] [(]nref[,...][)][:intexpr][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The nref argument specifies a name in the format  of  a  GT.M  name
        with or without subscripts, and with or without a  preceding  caret
        (^).

   o    Outside of transactions, only one process  in  an  environment  can
        ZALLOCATE (or LOCK) a particular resource name at any given time.

   o    Because the data storage in GT.M uses  hierarchical  sparse  arrays
        and ZALLOCATE may serve to protect  that  data  from  inappropriate
        "simultaneous"  access  by  multiple  processes,  ZALLOCATE  treats
        resource names in a hierarchical fashion; a ZALLOCATE protects not
        only the named resource, but also its ancestors and descendants.

   o    When one or more nrefs are enclosed in  parentheses  (),  ZALLOCATE
        reserves all the  enclosed  names  "simultaneously,"  that  is,  it
        reserves none of them until all become available.

   o    The optional numeric expression specifies a time in  seconds  after
        which the  command  should  timeout  if  unsuccessful;  choosing  0
        results in a single attempt.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZALLOCATE arguments form  a  legal  argument  for  a
        ZALLOCATE.

   For an explanation of the LOCK command see the "LOCK" section in the M
   LOCK Utility chapter of GT.M Administration and Operations Guide.

   If a ZALLOCATE command specifies a timeout, and GT.M acquires ownership
   of the named resource before the timeout elapses, ZALLOCATE sets $TEST
   to TRUE (1). If GT.M cannot acquire ownership  of  the  named  resource
   within the specified timeout, ZALLOCATE sets $TEST to FALSE (0).  If  a
   ZALLOCATE command does not specify a  timeout,  the  execution  of  the
   command does not affect $TEST.

   When given a list of nrefs, ZALLOCATE tries to reserve each  nref  from
   left to right in the order specified taking into  account  the  timeout
   specified for each. If the timeout elapses before  reserving  an  nref,
   GT.M terminates the ZALLOCATE command. Any nrefs  already  acquired  as
   part of the current ZALLOCATE command stay acquired.

2 Ex_of_ZAllocate
   Examples of ZALLOCATE

   Examples:


   ZALLOCATE A

   ZALLOCATE ^A

   ZALLOCATE ^A(1)

   ZALLOCATE (^B("smith"),^C("jones"))

   ZALLOCATE @A

   The first command ZALLOCATEs A; the second, ^A; the  third,  ^A(1)  and
   the fourth, both ^B("smith") and ^C("jones") simultaneously.  The  last
   command ZALLOCATEs the resources named by the value of the variable A.

   Example:


   ZALLOCATE A,^B,@C

   ZALLOCATE (A,B,C)

   If ZALLOCATE arguments are enclosed in parentheses, the  command  waits
   until all names in the argument list become available before reserving
   any of the names. For example, in the  statement  ZA  (A,B,C),  if  the
   resource named C is not available,  ZALLOCATE  waits  until  C  becomes
   available before reserving A and B. Using the format illustrated in the
   first line above, can cause deadlocks because the  resource  names  are
   reserved as they come available.

   When a process attempts to ZALLOCATE a  name  currently  ZALLOCATEd  or
   LOCKed (with the LOCK command) by  another  process,  the  ZALLOCATEing
   process hangs until the other process releases the name. In  the  event
   that names remain unavailable for significant periods of time, timeouts
   allow the process issuing a ZALLOCATE to regain program control.

   Example:


   ZALLOCATE ^D:5

   This example specifies a timeout of five seconds. If GT.M  reserves  ^D
   before the five seconds elapses, ZALLOCATE sets $TEST to TRUE. If GT.M
   cannot reserve ^D within the five second timeout, ZALLOCATE sets $TEST
   to FALSE.

   When you ZALLOCATE a name, no names previously reserved with ZALLOCATE
   or the LOCK command are released (similarly, LOCKing a  name  does  not
   release  names  that  have  been  ZALLOCATEd).  For  example,  after
   ZALLOCATEing A and LOCKing  B,  LOCKing  B  does  not  release  A,  and
   ZALLOCATEing C does not release A or B.

   To  release  a  ZALLOCATEd  name,  use  the  ZDEALLOCATE  command.  The
   ZDEALLOCATE command can only release previously ZALLOCATEd (not LOCKed)
   names.

   Resource name arguments for LOCKs and ZALLOCATEs intersect. That is, if
   one process holds a LOCK or ZALLOCATE, another process can neither LOCK
   nor ZALLOCATE any name falling in the hierarchy of  the  resource  name
   held by the first process. When a process holds a  LOCK  or  ZALLOCATE,
   that same process may also LOCK or ZALLOCATE resource names falling in
   the hierarchy of the  currently  held  resource  name.  When  a  single
   process holds both LOCKs and ZALLOCATEs, a LOCK does  not  release  the
   ZALLOCATEd resource(s) and a ZDEALLOCATE does not  release  the  LOCKed
   resource(s).

   Example:


   L ^AR(PNT)

   .
   .
   .
   ZALLOCATE ^AR(PNT,SUB)

   .
   .
   .
   L ^TOT(TDT)

   .
   .
   .
   ZDEALLOCATE ^AR(PNT,SUB)


   This LOCKs ^AR(PNT), then, after performing some unspecified commands,
   it ZALLOCATEs ^AR(PNT,SUB). Because ZALLOCATE does not imply any change
   to LOCKs or existing ZALLOCATEd resource names, the  LOCK  of  ^AR(PNT)
   remains in effect. Assuming the routine does not  modify  the  variable
   PNT, ^AR(PNT,SUB) is already protected by the LOCK.  Next,  because  an
   unsigned LOCK releases all  resource  names  currently  LOCKed  by  the
   process, the routine releases ^AR(PNT) with the LOCK of ^TOT(TDT). This
   leaves the  ZALLOCATE  of  ^AR(PNT,SUB).  The  name  ^AR  and  all  its
   subscripts except for  those  that  begin  with  ^AR(PNT,SUB)  are  now
   available for LOCKing by other processes. Finally the routine releases
   ^AR(PNT,SUB) with a  ZDEALLOCATE  command.  The  ZDEALLOCATE  does  not
   affect the LOCK on ^TOT(TDT). Note that this example was constructed to
   illustrate the interaction between LOCK, ZALLOCATE and ZDEALLOCATE, and
   not to illustrate sound programming practice.

1 ZBREAK
   ZBreak

   The ZBREAK command sets or clears routine breakpoints during debugging.

   The format of the ZBREAK command is:


   ZB[REAK][:tvexpr] [-]entryref[:[expr][:intexpr]]

   [,...]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required entryref specifies a  location  within  a  routine  at
        which to set or remove a breakpoint.

   o    The optional minus  sign  (-)  specifies  that  ZBREAK  remove  the
        breakpoint; -* means remove all breakpoints.

   o    The optional expression specifies a fragment of GT.M code to XECUTE
        when GT.M  execution  encounters  the  breakpoint;  if  the  ZBREAK
        argument does not specify an action, the default action is "BREAK".

   o    The  optional  integer  expression  immediately  following  the
        expression specifies  a  count  of  process  transits  through  the
        breakpoint before the breakpoint action  takes  effect;  once  GT.M
        exhausts the count and the action takes effect, the  action  occurs
        every time the process encounters the  breakpoint.  If  the  action
        expression is omitted, the  optional  integer  expression  must  be
        separated from the entryref by two adjacent colons (::).

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZBREAK arguments form a legal argument for a ZBREAK.

   When GT.M encounters the  entryref,  GT.M  suspends  execution  of  the
   routine code and XECUTEs the breakpoint action before executing any of
   the commands on the line.

   When the optional  integer  expression  is  used,  GT.M  activates  the
   breakpoint on the intexpr-th time the process encounters the breakpoint
   during routine execution. Once  GT.M  activates  the  breakpoint,  that
   breakpoint remains active for the process until explicitly replaced or
   removed, or until the process terminates.

2 Ex_of_ZBreak
   Examples of ZBREAK

   Example:


   GTM>ZPRINT ^ZBTEST

   ZBTEST;

   DO SUB

   QUIT

   SUB WRITE !,"This is ZBTEST"

   QUIT

   GTM>ZBREAK SUB^ZBTEST

   GTM>DO ^ZBTEST

   %GTM-I-BREAKZBA, Break instruction encountered

   during ZBREAK action

   At M source location SUB^ZBTEST

   GTM>

   ZSHOW "B"

   SUB^ZBTEST

   This inserts a ZBREAK with a default action at SUB^ZBTEST.  After  GT.M
   encounters the BREAK, the ZSHOW "B" displays this as the only ZBREAK in
   the image.

   Example:


   GTM>ZBREAK -*

   GTM>ZGOTO

   GTM>ZBREAK SUB^ZBTEST:"W !,""Trace"""

   GTM>DO ^ZBTEST

   Trace

   This is ZBTEST

   GTM>

   This removes all existing ZBREAKs with a ZBREAK -*. Note that it is not
   necessary to remove ZBREAKs before modifying them. It also  clears  the
   process invocation stack with an argumentless ZGOTO.  Then  it  uses  a
   ZBREAK to insert a trace-point. Every time GT.M executes  the  line  to
   where ZBREAK has established a trace-point, it performs  the  specified
   action without entering Direct Mode.

   Example:


   ZBREAK PRINT^TIME::5

   This BREAKs execution at line PRINT in routine just  before  the  fifth
   time the line is executed.

   Example:


   ZBREAK PRINT^TIME:"WRITE AVE BREAK":3

   This inserts a ZBREAK action of WRITE AVE and BREAK  before  the  third
   execution of PRINT^TIME.

1 ZCOMPILE
   ZCOMpile

   The ZCOMPILE command invokes the GT.M compiler  from  within  the  GT.M
   run-time environment.

   Within GT.M itself, ZCOMPILE provides the functionality  of  the  mumps
   command, except for mumps -direct.

   The format of the ZCOMPILE command is:


   ZCOM[PILE][:tvexpr] expr[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The expression argument specifies one or more filenames, which must
        include the .m extension. Wildcards are acceptable in the filename
        specification.  The  filename  specification  can  be  optionally
        prefixed by qualifiers valid for a mumps command.

   The $ZCSTATUS intrinsic special variable holds the value of the status
   code for the compilation performed by a ZCOMPILE command.

2 Ex_of_ZCOMpile
   Examples of ZCOMPILE

   ZCOMPILE "EXAMPLE.m"

   This compiles EXAMPLE.m in the current working directory.

   Example:


   ZCOMPILE "-list A*.m"

   This compiles all files starting with a [capital] A and an extension of
   .m in the current working directory.

1 ZCONTINUE
   ZContinue

   The ZCONTINUE command continues routine execution after a BREAK command
   or a <CTRL-C>.

   The format of the ZCONTINUE command is:


   ZC[ONTINUE][:tvexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    Because ZCONTINUE changes the flow of execution away  from  control
        of the principal device back to the current routine, it is usually
        the final command on a line; however, if it  is  not,  because  the
        ZCONTINUE has no argument, at least two (2) spaces must follow the
        command to separate it from the next command on the line.

   o    If the process is not in Direct Mode, ZCONTINUE has no effect.

1 ZDEALLOCATE
   ZDeallocate

   The ZDEALLOCATE command releases a specified  resource  name  or  names
   previously reserved by the ZALLOCATE command. The  ZDEALLOCATE  command
   releases only the  specified  name(s)  without  releasing  other  names
   previously reserved with the ZALLOCATE or LOCK command.

   The ZDEALLOCATE command provides compatibility  with  some  other  GT.M
   implementations. The M Development Committee choose to add the + and -
   delimiters to the LOCK command rather  than  adopt  the  ZALLOCATE  and
   ZDEALLOCATE approach. Therefore, when a design requires an incremental
   lock mechanism, LOCK +/- has the advantage  of  being  part  of  the  M
   standard. LOCK +/- also has the advantage of working symmetrically when
   routines using LOCKs are nested.

   The format of the ZDEALLOCATE command is:


   ZD[EALLOCATE][:tvexpr] [nref[,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command

   o    The nref argument specifies a name in the format  of  a  GT.M  name
        with or without subscripts and with or without a leading caret (^).

   o    A  ZDEALLOCATE  with  no  argument  releases  all  names  currently
        reserved with ZALLOCATE by the process; in this case, at least two
        (2) spaces must follow the ZDEALLOCATE to separate it from the next
        command on the line.

   o    ZDEALLOCATEing a named resource that is not currently owned by the
        process has no effect.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZDEALLOCATE arguments form a legal  argument  for  a
        ZDEALLOCATE.

1 ZEDIT
   ZEDit

   The  ZEDIT  command  invokes  the  editor  specified  by  the  EDITOR
   environment variable for GT.M and opens the specified file for editing.
   If the EDITOR environment variable is undefined, ZEDIT tries to invoke
   the UNIX vi editor.

   By default, ZEDIT puts a new file into the first  source  directory  in
   $ZROUTINES. Previously, it used the current working directory. The old
   behavior can be obtained by specifying the  current  working  directory
   explicitly in the argument to the ZEDIT command:

   o    ZEDIT "./file"

   The format of the ZEDIT command is:


   ZED[IT][:tvexpr] [expr[,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional expression(s) specifies the name of a  file  to  edit;
        note the argument is an expression rather than a routinename; ZEDIT
        rejects arguments with a file extension of .o as illegal.  A  valid
        GT.M file name with no extension will be given an extension of .m;
        therefore it is not possible, through ZEDIT, to edit a file with a
        valid GT.M filename and no extension.

   o    If ZEDIT has an argument, it not only invokes the editor, but also
        sets $ZSOURCE=expr.

   o    If ZEDIT has no argument or expr="", the command acts  as  a  ZEDIT
        $ZSOURCE; at least two (2) spaces must follow a ZEDIT command with
        no argument to separate it from the next command on the line.

   o    GT.M stores source code in files  with  standard  operating  system
        format; generally the file name is the same as the GT.M routinename
        with a default type of .m.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZEDIT arguments form a legal argument for a ZEDIT

   If the expression  includes  a  directory,  ZEDIT  searches  only  that
   directory. If $ZROUTINES is not null, a ZEDIT  command  that  does  not
   specify a directory uses $ZROUTINES to locate files. If  $ZROUTINES  is
   null, ZEDIT edits a new file in the first source directory specified in
   $ZROUTINES.

   When the argument to a ZEDIT includes a file  or  path  name,  $ZSOURCE
   maintains that as a default for ZEDIT and ZLINK.

2 Ex_of_ZEDit
   Examples of ZEDIT

   Example:


   GTM>ZEDIT "BAL"

   This invokes the editor for a file with a name of BAL and an extension
   of .m. Notice that BAL is a string literal.

   Example:


   GTM>SET prog="BAL"

   GTM>ZEDIT prog

   This is similar to the first example except that  it  uses  a  variable
   argument rather than a string literal.

   Example:


   GTM>zedit ".login"

   This invokes the editor for a file with the name .login. Notice that in
   this case the file is not a GT.M  file,  since  .login  starts  with  a
   period, and therefore, cannot be a GT.M file.

1 ZGOTO
   ZGoto

   The ZGOTO command transfers control  to  various  levels  in  the  GT.M
   invocation stack. It also can transfer control from  one  part  of  the
   routine to another or from one routine to another using  the  specified
   entryref.

   The format of the ZGOTO command is:


   ZG[OTO][:tvexpr] [[intexpr][:entryref

   [:tvexpr]],...]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional integer expression specifies the stack  frame  nesting
        level reached by performing the ZGOTO.

   o    A ZGOTO with no argument returns control to the next command at the
        bottom of the stack (level 1); in  this  case,  at  least  two  (2)
        spaces must follow the command to separate it from the next command
        on the line.

   o    The optional entryref specifies a location to which ZGOTO transfers
        control.

   o    If ZGOTO specifies no entryref, it  returns  control  to  the  next
        command at the level specified by the integer expression.

   o    The optional  truth-valued  expression  immediately  following  the
        entryref  specifies  the  argument  postconditional  and  controls
        whether GT.M uses the argument.

   o    If the ZGOTO includes the level and  the  argument  postconditional
        but  not  the  entryref,  two  colons  (::)  separate  the  integer
        expression from the truth-valued expression.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZGOTO arguments form a legal argument for a ZGOTO.

   A ZGOTO command with an entryref performs a  similar  function  to  the
   GOTO command, with the additional capability of reducing the GT.M stack
   level. In a  single  operation,  ZGOTO  executes  ($ZLEVEL  -  intexpr)
   implicit QUITs and a GOTO operation, transferring control to the named
   entryref.

   The ZGOTO command leaves the invocation stack at the level specified by
   the integer expression. GT.M implicitly terminates any intervening FOR
   loops and unstacks variables stacked with NEW commands as appropriate.

   Using ZGOTO results in an exit from the current GT.M invocation. ZGOTO
   resembles HALT (and not QUIT) in that it causes an exit  regardless  of
   the number of active levels in the current invocation. ZGOTO resembles
   QUIT (and not HALT) in that it destroys the GT.M context and terminates
   the process only if the current GT.M invocation is at the base  of  the
   process. Understanding the difference between ZGOTO  and  HALT  has  an
   impact only in an environment where GT.M is  invoked  recursively  from
   other languages.

   ZGOTO  $ZLEVEL:LABEL^ROUTINE  produces  identical  results  to  GOTO
   LABEL^ROUTINE. ZGOTO  $ZLEVEL-1  responds  like  a  QUIT  (followed  by
   ZCONTINUE, if in Direct Mode). If the integer expression evaluates to a
   value greater than the current value of $ZLEVEL or less than zero (0),
   GT.M issues a run-time error.

   If ZGOTO has no entryref, it performs some number of implicit QUITs and
   transfers control to the next command at the specified level. If ZGOTO
   has no argument, it behaves like ZGOTO 1, which  resumes  operation  of
   the lowest level GT.M routine as displayed by ZSHOW "S". In  the  image
   invoked by $gtm_dist mumps -direct, a ZGOTO without  arguments  returns
   the process to Direct Mode.

   ZGOTO provides a useful debugging tool in Direct Mode. However, because
   ZGOTO is not conducive to structured coding, it is best to restrict its
   use in production programs to error handling.For  more  information  on
   error handling,  refer  to  the  "Error  Processing"  chapter  in  GT.M
   Programmer's Guide.

2 Ex_of_ZGOTO
   Examples of ZGOTO

   Example:


   GTM>ZGOTO

   GTM>ZSHOW


   +1^GTM$DMOD (Direct mode)

   GTM>

   This uses ZGOTO to clear all levels of the GT.M invocation stack. ZSHOW
   with no arguments displays the stack.

   Example:


   SET $ZTRAP="ZGOTO "_$ZLEVEL_":^ERROR"

   This SETs $ZTRAP to contain a ZGOTO, so if  an  error  causes  GT.M  to
   XECUTE $ZTRAP, the routine ERROR executes at the same level as the SET
   command shown in the example.

1 ZHELP
   ZHelp

   The ZHELP command provides access to help information from the GTM help
   library or from any help library specified in the command argument.

   The format of the ZHELP command is:


   ZH[ELP][:tvexpr] [expr1[:expr2],...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional first expression specifies the help topic.

   o    If ZHELP has no argument or  expr1="",  ZHELP  invokes  base  level
        help; at least two (2) spaces must follow a ZHELP command  with  no
        argument to separate it from the next command on the line.

   o    The optional second expression  specifies  the  name  of  a  Global
        Directory containing ^HELP.

   o    If ZHELP does not specify the second expression, the  name  of  the
        Global Directory defaults to $gtm_dist/gtmhelp.gld.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZHELP arguments form a legal argument for a ZHELP

2 Ex_of_ZHelp
   Examples of ZHELP

   Example:


   GTM>zhelp "func $data"

   This lists the  help  for  function  $DATA,  which  is  a  subtopic  of
   functions topic.

   Example:


   GTM>zhelp

   This uses ZHELP to list all the keywords in the help library.

   Example:


   GTM>zhelp "ZSHOW"

   This lists the help for command ZSHOW.

1 ZLINK
   ZLink

   If the current process does not contain a copy of a routine, the ZLINK
   command adds an executable GT.M routine to the current process. If the
   current process contains a copy of a routine and  the  routine  is  not
   active, the ZLINK command replaces the current routine process  with  a
   "new" version. If necessary, the ZLINK  command  compiles  the  routine
   prior to integrating it with the process.

   The format of the ZLINK command is:


   ZL[INK][:tvexpr] [expr1[:expr2][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional first expression specifies the pathname of  a  routine
        to ZLINK; if ZLINK has an argument, it not only adds the routine to
        the image, but also sets $ZSOURCE=expr.

   o    If ZLINK has no argument, or expr="", it uses value of $ZSOURCE as
        the routine specification filename; at least two  (2)  spaces  must
        follow a ZLINK command with no argument to  separate  it  from  the
        next command on the line.

   o    The optional second expression specifies  a  string  holding  MUMPS
        command qualifiers delimited by a dash (-); the qualifiers control
        compile options when the current ZLINK requires a compile; if ZLINK
        omits  the  second  expression,  the  command  uses  the  $ZCOMPILE
        intrinsic special variable to determine the compile qualifiers.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZLINK arguments form a legal argument for a ZLINK.

   ZLINK cannot change a routine that  GT.M  is  currently  executing.  An
   attempt to ZLINK an active routine results in a run-time error because
   changing a routine in progress could have unpredictable results. Before
   ZLINKing the routine, use the ZSHOW command to  display  the  currently
   active routines, then remove it from the GT.M stack using ZGOTO, or the
   appropriate number of QUITs.

   When the ZLINK command specifies a file, GT.M  sets  $ZSOURCE  to  that
   filename. By default, ZLINK and ZEDIT use $ZSOURCE for a filename when
   they have a missing or null argument. A  subsequent  ZLINK  without  an
   argument is equivalent to ZLINK $ZSOURCE.

        In order to ensure compatibility with GT.M  versions  that  do  not
        permit the percent sign (%) in a file name, use an  underscore  (_)
        in place of the  percent  in  the  ZLINK  file  name  for  routines
        beginning with a percent sign.

   If the expression includes an explicit directory, ZLINK  searches  only
   that directory. Otherwise, if $ZROUTINES is not null, a  ZLINK  command
   uses $ZROUTINES to locate files. If $ZROUTINES is null, ZLINK uses the
   current directory.

   If the filename contains an explicit file  extension,  ZLINK  processes
   the file according to the extension, object  (.o)  or  source  (usually
   .m). If the file name does not specify a file extension, ZLINK attempts
   to find and match both the object and source for a routine.

2 ZLINK_Compilation
   ZLINK Compilation

   If ZLINK compiles  a  routine  and  the  -OBJECT=  qualifier  does  not
   redirect the output,  it  places  the  resulting  object  file  in  the
   directory indicated by the search criteria. ZLINK incorporates the new
   object file into the image, regardless of its directory placement.

   If the command does not specify compile  qualifiers  (with  expr2)  and
   $ZCOMPILE is null, GT.M uses the default M command qualifiers, -ignore,
   -labels=lower, -nolist, and -object. For more information on $ZCOMPILE,
   refer to the appropriate section in the "Intrinsic  Special  Variables"
   chapter in this manual.

   For information on producing object files, but not adding them  to  the
   current image, refer to ZCOMPILE.

2 Ex_of_ZLink
   Examples of ZLINK

   Example:


   GTM>ZLINK "test"

   If ZLINK finds test.m or test.o,  it  adds  the  routine  test  to  the
   current image. If ZLINK does not find test.o, or finds that  test.o  is
   older than test.m, GT.M compiles test.m to produce a  new  test.o,  and
   adds the contents of the new object file to the image.

   Example:


   GTM>

   zlink "test.m":"-noobject -list"

   This compiles the routine "test" and produces a listing but  no  object
   file. Because the example produces no object file, it does  not  change
   the current image.

2 Auto_ZLink
   Auto-ZLINK

   If a GT.M routine refers to a routine that is not linked  to  the  GT.M
   image, GT.M automatically attempts to ZLINK that routine. An auto-ZLINK
   is functionally equivalent to an explicit ZLINK of a routine without a
   specified directory or file extension.

   The following GT.M commands and functions can initiate auto-ZLINKing:

   DO

   GOTO

   ZBREAK

   ZGOTO

   ZPRINT

   $TEXT()

   GT.M auto-ZLINKs the routine if the following conditions are met:

   o    ZLINK can locate and process the routine file, as indicated in the
        previous ZLINK Operation Summary table

   o    The name of the routine is the same as the name of the source file;
        the only exception is  in  cases  where  GT.M  converts  a  leading
        percent sign (%) in a file name to an underscore (_)

2 ZL_AutoZL_and_Rtn_Nam
   ZLINK, Auto-ZLINK and Routine Names

   In GT.M, the name of the source file determines the name  of  the  GT.M
   routine. The file name of the object file is not required to match the
   name of the routine. Linking the object file makes the internal routine
   name (derived from the source file) known to GT.M.  This  can  lead  to
   potential confusion, however, since both ZLINK and auto-ZLINK  use  the
   name of the object file to find the routine. When the object file name
   differs from the name of the routine, auto-ZLINK generates  a  run-time
   error.

1 ZKILL
   ZKill

   The ZKILL command KILLs the data value  for  a  variable  name  without
   affecting the nodes descended from that node.

   The format of the ZKILL command is:


   ZK[ILL][:tvexpr] glvn

   The  functionality  of  ZKILL  is  identical  to  ZWITHDRAW.  For  a
   comprehensive description of the format and usage, refer to  the  entry
   for ZWITHDRAW.

1 ZMESSAGE
   ZMessage

   The ZMESSAGE command signals a specified condition.

   The format of the ZMESSAGE command is:


   ZM[ESSAGE][:tvexpr] intexpr

   [:expr...][,...]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required integer expression specifies the  exception  condition
        to signal.

   o    The additional expressions specify one or more arguments passed to
        the GT.M message formatter  to  substitute  as  parameters  to  the
        message text. For example,  if  the  message  associated  with  the
        condition contains  a  corresponding  !AD  substitution  directive,
        passing a string as an additional expression causes the  string  to
        be inserted in the message  text  instead  of  the  !AD.  $ZMESSAGE
        function returns the message text with the substitution directives
        for a given message number.

2 Ex_of_ZMessage
   Examples of ZMESSAGE

   All of the following examples issue ZMESSAGE  from  Direct  Mode  where
   exception conditions do not invoke $ZTRAP. ZMESSAGE allows you to feed
   an undefined message number back into GT.M to  try  and  determine  the
   message and/or mnemonic associated with it.

   Example:


   GTM>ZMESSAGE 2

   %SYSTEM-E-ENO2, No such file or directory

   This ZMESSAGE does not specify substitution text and the  message  does
   not include any substitution directives.

   Example:


   GTM>ZMESSAGE 150372994

   %GTM-E-GVUNDEF, Global Variable undefined:

   The message specified by this ZMESSAGE command includes a substitution
   directive but the command does not supply any text.

   Example:


   GTM>ZMESSAGE 150373850:"x"

   %GTM-E-GVUNDEF, Undefined local variable: x

   This ZMESSAGE command supplies the substitution text for the message.

   GT.M treats  odd-numbered  conditions  as  "successful."  GT.M  handles
   successful  conditions  by  displaying  the  associated  message  and
   continuing execution. GT.M treats even-numbered conditions as failures.
   GT.M handles failure conditions by storing  the  error  information  in
   $ZSTATUS and XECUTEing $ZTRAP or by terminating if $ZTRAP="". In Direct
   Mode, GT.M only reports failure conditions to the principal device and
   does not XECUTE $ZTRAP or set $ZSTATUS. For more information  on  error
   handling, refer to the "Error Processing" chapter in GT.M Programmer's
   Guide.

1 ZPRINT
   ZPrint

   The ZPRINT command displays source code lines selected by its argument.

   The format of the ZPRINT command is:


   ZP[RINT][:tvexpr][entryref

   [:label[+intexpr]][,...]]
   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    A ZPRINT with no argument prints the entire current routine, which
        is the routine closest to  the  top  of  an  invocation  stack,  as
        displayed by a ZSHOW "S"; in this case, at  least  two  (2)  spaces
        must follow the command to separate it from the next command on the
        line.

   o    The optional entryref specifies the location in a routine at which
        to start printing; the entryref can include either a routinename or
        a label plus a  routinename  in  the  format  LABEL^ROUTINENAME  or
        LABEL+OFFSET^ROUTINENAME;  if  the  entryref  does  not  contain  a
        routinename, ZPRINT defaults to the current routine.

   o    The optional label following the entryref identifies a location at
        which to stop printing; the optional integer  expression  specifies
        an offset from  the  label;  the  label  and  offset  together  are
        referred to as a lineref and this lineref identifies the last line
        to print; if the offset is specified without the label, the offset
        in the optional lineref is always counted from the beginning of the
        routine, even when the entryref specifies a label.

   o    If the ZPRINT argument includes the colon (:) delimiter,  then  the
        argument must also include at least one component of  the  optional
        lineref.

   o    If  the  ZPRINT  argument  contains  only  the  entryref,  with  no
        components of the optional lineref  and  the  entryref  contains  a
        label or offset, ZPRINT displays only the one line that  occurs  at
        that entryref.

   o    If the entryref contains only a routinename,  ZPRINT  displays  the
        entire routine.

   o    If the entryref  contains  only  a  routinename  and  the  argument
        includes the optional lineref, ZPRINT starts  the  display  at  the
        beginning of the routine.

   o    If the optional lineref specifies  a  line  prior  to  the  lineref
        specified within the entryref, ZPRINT does not display any lines.

   o    If the offset in the optional lineref specifies a line  beyond  the
        end of the routine, ZPRINT displays the remainder of the routine.

   o    If ZPRINT cannot locate the routine or if either of the labels does
        not appear in the routine, ZPRINT issues an error.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZPRINT arguments form a legal argument for a ZPRINT.

   Note that  the  routinename  may  only  appear  before  the  colon  (:)
   delimiter. The integer expression offsets may be positive or negative,
   but they must always be delimited by a plus sign (+).

2 Ex_of_ZPrint
   Examples of ZPRINT

   Example:


   GTM>ZPRINT X^RTN

   This example displays the line  beginning  with  the  label  X  in  the
   routine RTN.

   Example:


   GTM>ZPRINT X^RTN:X+5

   GTM>ZPRINT X+-5^RTN:X

   GTM>ZPRINT X^RTN:X+-5^RTN

   The first line displays the line beginning with the  label  X  and  the
   next 5 lines in routine RTN. The  second  line  displays  the  5  lines
   preceding label X in the same routine and the line beginning with label
   X. The third line generates a run-time error because the  routine  name
   must appear only before the colon in the argument.

1 ZSHOW
   ZSHow

   The  ZSHOW  command  displays  information  about  the  current  GT.M
   environment.

   The format of the ZSHOW command is:


   ZSH[OW][:tvexpr][expr[:glvn][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional expression specifies one or more codes determining the
        nature of the information displayed.

   o    A ZSHOW with no argument defaults to ZSHOW "S"; in  this  case,  at
        least two (2) spaces must follow the ZSHOW to separate it from the
        next command on the line.

   o    The  optional  global  or  local  variable  name  specifies  the
        destination for the ZSHOW output; if the ZSHOW  argument  does  not
        contain a global or local variable name, ZSHOW directs its display
        to the current device ($IO).

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZSHOW arguments form a legal argument for a ZSHOW.

2 ZSH_Info_Codes
   ZSHOW Information Codes

   A ZSHOW argument is an expression containing  codes  selecting  one  or
   more types of information.

        B displays active ZBREAK breakpoints
        C displays available external call table entry names
        D displays device information
        I displays the current values of all intrinsic special variables
        L displays GT.M LOCKs and ZALLOCATEs held by the process
        S displays the GT.M invocation stack
        V displays local variables
        * displays all possible types of ZSHOW information
   Codes may be upper- or lower-case. Invalid  codes  produce  a  run-time
   error. Multiple occurrences of the same code in one ZSHOW argument only
   produce one output instance of the corresponding information. The order
   of the first appearance of the codes in  the  argument  determines  the
   order of the corresponding output instances.

        If you are using a local variable  destination  and  place  another
        code ahead of "V", the effect is to have the results of the earlier
        code also appear in the results of the "V" code.

   If the wildcard (*) occurs in the list, ZSHOW uses the default order:

   o    intrinsic special variables

   o    local variables

   o    ZBREAK information

   o    device information

   o    LOCK and ZALLOCATE information

   o    the GT.M stack

2 Ex_of_ZSHow
   Examples of ZSHOW

   Example:


   GTM>ZSHOW "db"

   This command displays  all  devices  with  deviceparameters  reflecting
   their current characteristics followed by any current ZBREAK locations
   with their corresponding actions.

   Example:


   GTM>ZSHOW "dbd"

   This command displays the same output as the previous example.

   Example:


   GTM>ZSHOW "ax"

   This command generates a run-time error.

   Example:


   LAB1 DO LAB2

   QUIT

   LAB2 DO LAB3

   QUIT

   LAB3 ZSHOW

   QUIT

   Produces the results:


   LAB3^RTN

   LAB2^RTN

   LAB1^RTN

2 ZSH_Destination_Vars
   ZSHOW Destination Variables

   ZSHOW may specify an  unsubscripted  or  subscripted  global  or  local
   variable name (glvn)  into  which  ZSHOW  places  its  output.  If  the
   argument does not include  a  global  or  local  variable  name,  ZSHOW
   directs its output to the current device.

   When ZSHOW directs its output to a variable,  it  adds  two  levels  of
   descendants to that variable. The  first  level  subscript  contains  a
   one-character string from the set of  upper-case  ZSHOW  action  codes,
   identifying  the  type  of  information.  ZSHOW  implicitly  KILLs  all
   descendants of the first level nodes. ZSHOW stores information elements
   at the second level using ascending integers, starting at 1.

   When a ZSHOW "V" directs its output to  a  local  variable  (lvn),  the
   result does not contain a copy of the descendants of the resulting "V"
   node.

   Example:


   GTM>KILL SET b(1,"two")="test" ZSHOW "v":a ZWR

   a("V",1)="b(1,""two"")=""test"""

   b(1,"two")="test"

   GTM>

   This ZSHOW stores all local variables in the  local  variable  a.  Note
   that ZSHOW does not replicate a("V") and a("V",1).

   Example:


   GTM>KILL SET a(1,"D",3,5)="stuff",a(1,"X",2)="",a(1)=1

   GTM>zsh "d":a(1)

   GTM>zwrite

   a(1)=1

   a(1,"D",1)="/dev/ttyp8 OPEN TERMINAL NOPAST NESCA

   NOREADS TYPE WIDTH=80 LENG=52"

   a(1,"X",2)=""

   GTM>

   This ZSHOW stores the  current  open  device  information  under  a(1).
   Notice how the ZSHOW deletes a(1,"D",3,5).

   Example:


   GTM>KILL ^ZSHOW

   GTM>ZB -*,lab^rout ZSH "B":^ZSHOW

   GTM>ZWRITE ^ZSHOW

   ^ZSHOW("B",1)="LAB^ROUT"

   GTM>

   This ZSHOW stores the  current  ZBREAK  information  under  the  global
   variable ^ZSHOW.

2 Use_of_ZSHow
   Use of ZSHOW

   Use ZSHOW as

   o    a debugging tool to display information on the environment.

   o    an error-handling tool to  capture  context  information  after  an
        unpredictable error with output directed to a sequential file or a
        global.

   o    part of a context-switching mechanism in a server program that must
        manage multiple contexts.

   o    a development tool to determine the  external  call  table  entries
        available from the current process.

   To prevent confusing data interactions, avoid  directing  ZSHOW  output
   into variables holding other kinds of information and  directing  ZSHOW
   "V" output into local variables. For a  comparison  of  ZSHOW  "V"  and
   ZWRITE, refer to the ZWRITE section in the "Commands" chapter  in  GT.M
   Programmer's Guide.

1 ZSTEP
   ZSTep

   The ZSTEP command provides the ability to control GT.M execution. When
   a ZSTEP  is  issued  from  Direct  Mode,  execution  continues  to  the
   beginning of the next target line  and  then  GT.M  XECUTEs  the  ZSTEP
   action. The keyword in the optional ZSTEP argument determines the class
   of eligible target lines.

   The format of the ZSTEP command is:


   ZST[EP][:tvexpr] [keyword[:expr]][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional keyword specifies the nature of the step; the keywords
        are INTO, OVER, and OUTOF.

   o    A ZSTEP with no argument performs the default action OVER; in this
        case, at least two (2) spaces must follow the ZSTEP to separate it
        from the next command on the line, which will be ignored.

   o    The optional expression specifies GT.M  code  to  XECUTE  when  the
        ZSTEP arrives at its destination.

   o    If the ZSTEP argument does  not  contain  an  expression  argument,
        ZSTEP defaults the action to the value of $ZSTEP, which defaults to
        "BREAK."

   The ZSTEP argument keywords are not  expressions  and  ZSTEP  does  not
   accept argument indirection.

   In Direct Mode, ZSTEP performs an implicit ZCONTINUE and therefore GT.M
   ignores all commands on the Direct Mode command line after the ZSTEP.

   The keyword arguments define the class of lines where ZSTEP next pauses
   execution to XECUTE the ZSTEP action. When a ZSTEP command has multiple
   arguments, it ignores all arguments except the last.

2 ZSTEP_Into
   ZSTEP Into

   ZSTEP INTO pauses at the beginning of  the  next  line,  regardless  of
   transfers of control. When the ZSTEPed line invokes another routine or
   a subroutine in the current routine, ZSTEP INTO  pauses  at  the  first
   line of code associated with the new GT.M stack level.

2 ZSTEP_OUtof
   ZSTEP OUtof

   ZSTEP OUTOF pauses at the beginning of the next line executed after an
   explicit or implicit QUIT from the current GT.M invocation stack level.
   A ZSTEP OUTOF does not pause at lines associated with the current GT.M
   stack level or with levels invoked from the current level.

2 ZSTEP_OVer
   ZSTEP OVer

   ZSTEP OVER pauses at the  beginning  of  the  next  line  in  the  code
   associated with either the current GT.M stack level or a previous GT.M
   stack level if the ZSTEPed line contains an explicit or  implicit  QUIT
   from the current level. A ZSTEP OVER does not pause  at  lines  invoked
   from the current line by DOs, XECUTEs or extrinsics.

2 ZSTEP_Actions
   ZSTEP Actions

   The optional action parameter of a ZSTEP  must  contain  an  expression
   evaluating to valid GT.M code. By default,  ZSTEP  uses  the  value  of
   $ZSTEP, which defaults to "B" ("BREAK"), and enters Direct Mode. When a
   ZSTEP command specifies an action, the process does  not  enter  Direct
   Mode unless the action explicitly includes a BREAK command.

2 ZSTEP_Interact
   ZSTEP Interactions

   ZSTEP currently interacts with  certain  other  elements  in  the  GT.M
   environment.

   o    If a <CTRL-C> or a CTRAP character arrives  at  certain  points  in
        ZSTEP processing, there is a  small  chance  GT.M  may  ignore  the
        <CTRL-C> or CTRAP; in a later release,  <CTRL-C>  and  CTRAPs  will
        always have priority over ZSTEP.

   o    If GT.CM reports an asynchronous network error, a ZSTEP  may  cause
        the  network  error  to  go  unreported;  the  chance  of  such  an
        occurrence is small and the chance the error would subsequently be
        reported is high; in a later release, network errors will always be
        given priority over ZSTEP.

2 Use_of_ZSTEP
   Use of ZSTEP

   Use ZSTEP to incrementally execute a routine  or  series  of  routines.
   Execute any GT.M command from Direct Mode at any ZSTEP pause. To resume
   normal execution, use ZCONTINUE.

   Note that ZSTEP arguments are keywords rather than expressions. They do
   not allow indirection, and argument lists have no utility.

   ZSTEP actions that include commands followed by a  BREAK  perform  some
   action before entering Direct Mode. ZSTEP actions that do not include a
   BREAK perform the command action  and  continue  execution.  Use  ZSTEP
   actions that issue conditional BREAKs and subsequent ZSTEPs to do such
   things as test for changes in the value of a variable.

2 Ex_of_ZSTEP
   Examples of ZSTEP

   Example:


   GTM>ZSTEP INTO:"W ! ZP @

   $ZPOS W !"

   This ZSTEP resumes execution of the current routine. At  the  beginning
   of the next line executed, the ZSTEP action ZPRINTs the source code for
   that line. Because the  specified  action  does  not  contain  a  BREAK
   command, execution continues to the next line and all subsequent lines
   in the program flow.

   Example:


   GTM>S curx=$g(x),zact="ZST:curx=$g(x) I:zact B:curx'=$g(x)"

   GTM>ZSTEP INTO:zact

   This sequence uses ZSTEP to invoke Direct Mode at the beginning of the
   first line after the line that alters the value of x.

1 ZSYSTEM
   ZSYstem

   The ZSYSTEM command creates a child of the current process.

   The format of the ZSYSTEM command is:


   ZSY[STEM][:tvexpr] [expr[:tvexpr][,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional expression specifies the command passed to the shell;
        after processing the command, the shell returns control to GT.M.

   o    If ZSYSTEM has no argument or expr="", the shell prompts for input
        until provided with an exit command; at least two (2)  spaces  must
        follow a ZSYSTEM command with no argument to separate it  from  the
        next command on the line.

   o    The  optional  truth-valued  expression  following  the  argument
        expression specifies  the  argument  postconditional  and  controls
        whether ZSYSTEM processes that argument.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZSYSTEM  arguments  form  a  legal  argument  for  a
        ZSYSTEM.

   The ZSYSTEM command creates a new process and passes  its  argument  to
   the shell for execution. The new process executes in the same directory
   as the initiating process  using  the  shell  specified  by  the  SHELL
   environment variable, or if that is not defined, the Bourne shell. The
   new  process  has  the  same  operating  system  environment,  such  as
   environment variables  and  input/output  devices,  as  the  initiating
   process. The initiating process pauses until the new process completes
   before continuing execution. The return status of the forked process is
   reflected in $ZSYSTEM.

   If a ZSYSTEM command has multiple arguments, it starts  a  new  process
   for each argument, one at a time. ZSYSTEM  waits  for  one  process  to
   complete before starting the next one.

   A ZSYSTEM with a null argument creates a shell with the standard input
   and output devices. When the shell exits, control is returned to GT.M.
   For an interactive process, both stdin and  stdout  are  generally  the
   user's terminal. A ZSYSTEM with no arguments is equivalent to a ZSYSTEM
   with a single null string argument.

   If a command postconditional  is  false,  GT.M  does  not  process  the
   ZSYSTEM command. If an argument postconditional is false, GT.M does not
   process that argument.

   Issuing a ZSYSTEM command inside a transaction destroys  the  Isolation
   of  that  transaction.  Because  of  the  way  that  GT.M  implements
   transaction processing, a ZSYSTEM within a transaction  may  suffer  an
   indefinite number of restarts ("live lock").

2 Ex_of_ZSYSTEM
   Examples of ZSYstem

   Example:


   GTM>ZSYSTEM "ls *.m"

   This uses ZSYSTEM to fork a process that then performs the  ls  command
   with *.m as an argument to ls. Once the command completes,  the  forked
   process terminates.

   Example:


   GTM>ZSYSTEM

   $

   This ZSYSTEM has no argument so the forked process prompts for input.

1 ZTCOMMIT
   ZTCommit

   The ZTCOMMIT command marks the end of a logical  transaction  within  a
   GT.M program. ZTCOMMIT used with ZTSTART  "fences"  transactions  (that
   is, marks the end and beginning). Fencing transactions allows the MUPIP
   JOURNAL  facility  to  prevent  incomplete  application  transactions
   consisting of multiple  global  updates  from  affecting  the  database
   during a database recovery.

   The format of the ZTCOMMIT command is:


   ZTC[OMMIT][:tvexpr] [intexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional integer expression specifies the number  of  currently
        open ZTSTARTs for the ZTCOMMIT to close.

   o    A ZTCOMMIT with no argument closes one ZTSTART; in  this  case,  at
        least two (2) spaces must follow the command to  separate  it  from
        the next command on the line;  with  an  argument  of  0,  ZTCOMMIT
        closes all open ZTSTARTs.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZTCOMMIT arguments  form  a  legal  argument  for  a
        ZTCOMMIT.

   When an application requires sub-transactions, it may nest ZTSTARTs and
   ZTCOMMITs to a maximum depth of 255. However, a ZTCOMMIT  must  "close"
   the outer-most ZTSTART  before  journaling  accepts  any  part  of  the
   "transaction" as complete.

2 Ex_of_ZTCommit
   Examples of ZTCOMMIT

   Example:


   GTM>ZTCOMMIT 0

   This ZTCOMMIT issued from Direct Mode would close any open ZTSTARTs.

   Example:

1 ZTSTART
   ZTStart

   The ZTSTART command marks the beginning of a logical transaction within
   a GT.M program. ZTSTART and ZTCOMMIT  "fence"  transactions  (that  is,
   mark the beginning and end).  Fenced  transactions  prevent  the  MUPIP
   JOURNAL facility from recovering incomplete transactions. All ZTSTARTs
   must be matched with ZTCOMMITs before the journal  processing  facility
   recognizes the transaction as complete.

   The format of the ZTSTART command is:


   ZTS[TART][:tvexpr]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    Because ZTSTART has no argument,  at  least  two  (2)  spaces  must
        follow the command to separate it from  the  next  command  on  the
        line.

   For more information on Journaling and transaction  fencing,  refer  to
   the section on ZTCOMMIT and the "GT.M Journaling" chapter in  the  GT.M
   Administration and Operations Guide.

2 Ex_of_ZTStart
   Examples of ZTSTART

   Example:


   LOCK ^P(t)

   ZTSTART

   SET ^P(t)=prec,^($H)=$G(^P(t,+$H))+1,^(+$H,s)=hrec

   ZTCOMMIT

   LOCK

   This uses a LOCK on ^P(t) to serialize  the  transaction.  The  logical
   transaction consists of three global sets that are  enclosed  within  a
   ZTSTART and a ZTCOMMIT.

   Example:


   BASE DO WORK

   QUIT

   GRP LOCK ^FAM(prn)

   SET b=^FAM(prn)

   ZTSTART

   FOR i=1:1:$L(b,"|") D GET,WORK

   ZTCOMMIT

   LOCK

   QUIT

   WORK LOCK +^ACT(acct)

   ZTSTART

   SET ^ACT(acct)=actrec

   SET ^ACTX(lname,fname,acct)=""

   ZTCOMMIT

   LOCK -^ACT(acct)

   This has a sub-routine  WORK,  which  BASE  invokes  directly  and  GRP
   invokes to perform a sub-transaction.

1 ZWITHDRAW
   ZWIthdraw

   The ZWITHDRAW command KILLs the data value for a variable name without
   affecting the nodes descended from that node.

   The format of the ZWITHDRAW command is:


   ZWI[THDRAW][:tvexpr] glvn

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The global or local variable name identifies the variable for which
        ZWITHDRAW removes the data value.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZWITHDRAW arguments form  a  legal  argument  for  a
        ZWITHDRAW.

   ZWITHDRAW provides a tool to quickly restore a node to a state where it
   has descendants and no value-that is, where $DATA for  that  node  will
   have a value of 10-for the case where such a  state  has  some  control
   meaning. GT.M also  provides  the  ZKILL  command,  with  functionality
   identical to ZWITHDRAW.

2 Ex_of_ZWIthdraw
   Examples of ZWITHDRAW

   Example:


   KILL A

   SET A="A",A(1)=1,A(1,1)=1

   WRITE $D(A(1)),!

   ZWITHDRAW A(1)

   WRITE $D(A(1)),!

   ZWRITE A

   QUIT

   produces the result:


   11
   10
   A="A"

   A(1,1)=1

   This sets up local variables A and A(1) and A(1,1). It then deletes the
   data for A(1) with ZWITHDRAW. The ZWRITE command shows ZWITHDRAW KILLed
   A(1) but left A and A(1,1).

1 ZWRITE
   ZWRite

   The ZWRITE command displays the current value of one or more  local  or
   global variables. ZWRITE formats its output so that each  item  in  the
   display forms a valid argument to a SET @ command.  This  means  ZWRITE
   encloses string values in quotes and represents  non-graphic  (control)
   characters in $CHAR() syntax.

   The format of the ZWRITE command is:


   ZWR[ITE][:tvexpr] [zwrglvn[,...]]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The optional global or local variable name specifies  the  variable
        for ZWRITE to display.

   o    ZWRITE accepts several alternative syntaxes in place of subscripts;
        ZWRITE  also  accepts  arguments  specifying  naked  references  to
        globals. Because ZWRITE is primarily a debugging tool, ZWRITE does
        not affect the naked indicator.

   o    ZWRITE accepts null subscripts in its  arguments,  when  these  are
        allowed, and reports array nodes that have null subscripts.

   o    A ZWRITE with no arguments displays  all  the  currently  available
        local variables; in this case, at least two (2) spaces must follow
        the command to separate it from the next command on the line.

   o    If the global or  local  variable  name  is  unsubscripted,  ZWRITE
        displays  the  unsubscripted  variable  and  all  subscripted
        descendants.

   o    If an asterisk (*) appears in the space normally  occupied  by  the
        last subscript in a subscripted variable name, ZWRITE displays all
        variable nodes descended from the previously specified subscripts.

   o    ZWRITE accepts GT.M pattern-match syntax in place of both variable
        names and subscripts.

   o    ZWRITE <name>(), where <name> is a local or a global is treated as
        a synonym for ZWRITE <name>.

   o    A colon acts as a  range  operator  for  subscript  values;  ZWRITE
        displays all subscripts of the variable starting with the value on
        the left side of the colon and ending with the value on  the  right
        side of the colon; if the range delimiter has no  left-hand  value,
        or has the empty string as the left-hand value, the display begins
        at the first subscript; if the range delimiter  has  no  right-hand
        value or has the empty string as the right-hand value, the display
        ends at the last subscript at that level; if  the  range  delimiter
        has no values or empty strings on either side, ZWRITE displays all
        subscripts at that level; an empty subscript  level  also  displays
        all subscripts at that level.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more ZWRITE arguments form a legal argument for a ZWRITE.

   o    Long ZWRITE format records can be loaded.

2 Ex_of_ZWRite
   Examples of ZWRITE

   Example:


   GTM>ZWRITE ^?1"%"2U(0:":",)

   This command displays the descendants of all subscripts between  0  and
   ":" of all global names starting with a "%" and having two  upper  case
   letters-for example, "%AB".

   Example:


   GTM>ZWRITE A(,:,3)

   This command displays all of the third level nodes with a subscript of
   3 for local variable A.

   Example:


   ZWRITE ?1"A".E(?1"X"3N)

   This would display data for any  local  variables  starting  with  "A",
   optionally followed  by  any  characters,  and  having  any  subscripts
   starting with "X" followed by three numerics.

1 Functions
   Functions

   M Intrinsic Functions start with a single dollar sign ($) and have one
   or more arguments enclosed in parentheses () and  separated  by  commas
   (,). These functions provide expression results by  performing  actions
   that are impossible or difficult to perform using M commands.

2 $ASCII()
   $ASCII()

   The $ASCII function returns the integer ASCII code for a character in a
   string.

   The format for the $ASCII function is:

   $A[SCII](expr[,intexpr])

   o    The expression acts  as  the  source  string  from  which  $ASCII()
        extracts the character it decodes.

   o    The optional integer expression contains the  position  within  the
        expression of the character that $ASCII() decodes. If this argument
        is missing, $ASCII() returns a result based on the first character
        position. $ASCII() starts numbering character positions at one (1),
        (i.e., the first character of a string is at position one (1)).

   o    If the explicit or implicit position is  before  the  beginning  or
        after the end of  the  expression,  $ASCII()  returns  a  value  of
        negative one (-1).

   $ASCII() provides a means of  examining  non-graphic  characters  in  a
   string. Used with $CHAR(), $ASCII() also provides a  means  to  perform
   arithmetic operations on the codes associated with characters.

3 Ex_of_$ASCII()
   Examples of $ASCII()

   Example:


   GTM> FOR i=0:1:3 WRITE !,$A("HI",i)

   -1

   72
   73
   -1

   GTM>

   This loop displays  the  result  of  $ASCII()  specifying  a  character
   position before, first and second positions, and after the string.

2 $Char()
   $CHAR()

   The  $CHAR  function  returns  a  string  of  one  or  more  characters
   corresponding to integer ASCII codes specified in its argument(s).

   The format for the $CHAR function is:


   $C[HAR](intexpr[,...])

   o    The  integer  expression(s)  specify  the  ASCII  codes  of  the
        character(s) $CHAR() returns.

   The M standard does not restrict the number of  arguments  to  $CHAR().
   However, GT.M does limit the number of arguments to a maximum  of  254.
   $CHAR() provides a means of producing non-graphic characters,  as  such
   characters cannot appear directly within an M string literal. Used with
   $ASCII(), $CHAR() can also perform arithmetic operations on  the  codes
   associated with characters.

3 Ex_of_$CHAR()
   Examples of $CHAR()

   Example:


   GTM> WRITE $CHAR(77,85,77,80,83,7)

   MUMPS

   GTM>

   This example uses $CHAR() to  WRITE  the  word  MUMPS  and  signal  the
   terminal "bell."

   Example:


   SET nam=$E(nam,1,$L(nam)-1)_$C($A(nam,$L(nam))-1))

   This example uses $CHAR() and $ASCII() to set the  variable  nam  to  a
   value that immediately precedes  its  previous  value  in  the  set  of
   strings of the same length as nam.

2 $Data()
   $Data()

   The $DATA function returns an integer code  describing  the  value  and
   descendent status of a local or global variable.

   The format for the $DATA function is:


   $D[ATA](glvn)

   o    The subscripted or unsubscripted  global  or  local  variable  name
        specifies the target node.

   o    If the variable is undefined, $DATA() returns 0.

   o    If the variable has a value but no descendants, $DATA() returns 1.

   o    If the variable has descendants but no value, $DATA() returns 10.

   o    If the variable has a value and descendants, $DATA() returns 11.

3 Ex_of_$Data()
   Examples of $DATA()

   Example:


   GTM> KILL WRITE $DATA(a)

   0
   GTM> SET a(1)=1 WRITE $DATA(a(1))

   1
   GTM> WRITE $DATA(a)

   10
   GTM> SET a=0 WRITE $DATA(a)

   11
   GTM>

   This uses $DATA to display all possible $DATA() results.

   Example:

   L ^ACCT(0)

   I '$D(^ACCT(0)) S ^ACCT(0)=0

   S (ACCT,^ACCT(0))=^ACCT(0)+1

   L

   This  uses  $DATA()  to  determine  whether  a  global  node  requires
   initialization.

   Example:

   FOR SET cus=$O(^cus(cus)) Q:cus="" I $D(^(cus))>1 D WORK

   This uses $DATA() to determine whether a global  node  has  descendants
   and requires additional processing.

2 $Extract()
   $EXTRACT()

   The $EXTRACT function returns a substring of a given string.

   The format for the $EXTRACT function is:


   $E[XTRACT](expr[,intexpr1[,intexpr2]])

   o    The expression specifies a string from which $EXTRACT()  derives  a
        substring.

   o    The first optional integer expression (second  argument)  specifies
        the starting character position in the string expr of the substring
        result.  If  the  starting  position  is  beyond  the  end  of  the
        expression, $EXTRACT() returns the null  string.  If  the  starting
        position is zero (0) or negative, $EXTRACT() starts  at  the  first
        position in the expression; if this argument is omitted, $EXTRACT()
        returns the first character of the expression.  $EXTRACT()  numbers
        character positions starting at one (1) (i.e., the first character
        of a string is at position one (1)).

   o    The second optional integer expression (third  argument)  specifies
        the ending  character  position  for  the  result.  If  the  ending
        position is beyond the end of the expression, $EXTRACT() stops with
        the last character  of  the  expression.  If  the  ending  position
        precedes the starting position, $EXTRACT() returns the null string.
        If this argument is omitted, $EXTRACT() returns  one  character  at
        most.

   $EXTRACT() provides a tool for manipulating strings based on character
   positions.

   A SET command argument can have something that  has  the  format  of  a
   $EXTRACT() on the left-hand side of its equal sign (=). This construct
   permits easy maintenance of individual pieces within a string.  It  can
   also be used to right justify a value padded with blank characters. For
   more information on SET $EXTRACT(), refer  to  SET  in  the  "Commands"
   chapter.

3 Ex_of_$Extract()
   Examples of $EXTRACT()

   Example:


   GTM> FOR i=0:1:3 WRITE !,$EXTRACT("HI",i),"<"

<
   H<

   I<

<
   GTM>

   This loop displays the  result  of  $EXTRACT(),  specifying  no  ending
   character position and a beginning character position "before, " first
   and second positions, and "after" the string.

   Example:


   GTM> FOR i=0:1:3 WRITE !,$E("HI",1,i),"<"

<
   H<

   HI<

   HI<

   GTM>

   This loop displays the result  of  $EXTRACT()  specifying  a  beginning
   character position of 1 and an ending  character  position  "before,  "
   first and second positions, and "after" the string.

   Example:


   TRIM(x)

   NEW i,j

   FOR j=$L(x):-1:0 S nx=$E(x,1,j) Q:$EXTRACT(x,j)'=" "

   FOR i=1:1:j S fx=$E(nx,i,$L(x)) Q:$EXTRACT(x,i)'=" "

   QUIT fx


   GTM>SET str=" MUMPS "


   GTM>WRITE $LENGTH(str)

   7
   GTM>WRITE $LENGTH($$TRIM^trim(str))

   5
   This extrinsic function uses $EXTRACT() to  remove  extra  leading  and
   trailing spaces from its argument.

2 $Find()
   $FIND()

   The $FIND function returns an integer character position  that  locates
   the occurrence of a substring within a string.

   The format for the $FIND function is:


   $F[IND](expr1,expr2[,intexpr])

   o    The first expression specifies the string in which $FIND() searches
        for the substring.

   o    The second expression specifies the  substring  for  which  $FIND()
        searches.

   o    The optional integer expression identifies  the  starting  position
        for the $FIND() search. If this argument is missing, zero  (0),  or
        negative, $FIND() begins its search in the first  position  of  the
        string.

   o    If $FIND() locates the substring, it returns the position after the
        last character of the  substring.  If  the  end  of  the  substring
        coincides with the end of the string (expr1), it returns an integer
        equal to the length of the string plus one ($L(expr1)+1).

   o    If $FIND() does not locate the substring, it returns zero (0).

   $FIND() provides a tool to locate characters. The ( [  )  operator  and
   the  two-argument  $LENGTH()  are  other  tools  that  provide  related
   functionality.

3 Ex_of_$Find()
   Examples of $FIND()

   Example:


   GTM> WRITE $FIND("HIFI","I")

   3
   GTM>

   This example uses $FIND() to WRITE the position of the first occurrence
   of the character "I." The return of 3  gives  the  position  after  the
   "found" substring.

   Example:


   GTM> WRITE $FIND("HIFI","I",3)

   5
   GTM>

   This example uses $FIND() to WRITE the position of the next occurrence
   of the character "I" starting in character position three.

   Example:


   GTM> SET t=1 FOR SET t=$FIND("BANANA","AN",t) Q:'t W !,t

   4
   6
   GTM>

   This example uses a loop with $FIND() to locate all occurrences of "AN"
   in "BANANA". The $FIND() returns 4 and 6 giving the positions after the
   two occurrences of "AN".

   Example:


   GTM> SET str="MUMPS databases are hierarchical"


   GTM>WRITE $FIND(str," ")

   7

   GTM>WRITE $FIND(str,"Z")

   0

   GTM>WRITE $FIND(str,"d",1)

   8

   GTM>WRITE $FIND(str,"d",10)

   0
   The above example searches a string for a sub string,  and  returns  an
   integer value which corresponds to the next  character  position  after
   locating the sub string.

2 $FNumber()
   $FNumber()

   The $FNUMBER function returns a string containing a formatted number.

   The format for the $FNUMBER function is:

   $FN[UMBER](numexpr,expr[,intexpr])

   o    The  numeric  expression  specifies  the  number  that  $FNUMBER()
        formats.

   o    The expression (second argument)  specifies  zero  or  more  single
        character format control codes;  if  the  expression  contains  any
        character other than the  defined  codes,  $FNUMBER()  generates  a
        run-time error.

   o    The optional integer  expression  (third  argument)  specifies  the
        number of digits after the decimal point. If the numeric expression
        has more digits than specified by this argument, $FNUMBER() rounds
        to obtain the result. If the numeric expression  has  fewer  digits
        than specified by this argument, $FNUMBER()  zero-fills  to  obtain
        the result.

   o    When the  optional  third  argument  is  specified  and  the  first
        argument evaluates to a  fraction  between  -1  and  1,  $FNUMBER()
        returns a number with a leading zero (0) before the  decimal  point
        (.).

   $FNUMBER() formats or edits numbers, usually for  reporting.  For  more
   information on rounding performed by $FNUMBER(), refer to  the  section
   on $JUSTIFY().

   The formatting codes are:

        + Forces a "+" on positive values.
        - Suppresses the "-" on negative values.
        , Inserts commas every third position to the left  of  the  decimal
        within the number.
        T Represents the number with a  trailing,  rather  than  a  leading
        sign; positive numbers have a trailing space unless the expression
        includes a plus sign (+).
        P Represents negative values in parentheses, positive values with a
        space on either side; combining with any other  code  except  comma
        (,) causes a run-time error.
   M accepts both lower-case and upper-case alphabetic codes. The order of
   the codes does not affect the result.

3 Ex_of_$FNumber()
   Examples of $FNUMBER()

   Example:


   SET X=-100000,Y=2000

   WRITE "SUPPRESS NEGATIVE SIGN:",?35,$FNUMBER(X,"-"),!

   WRITE "TRAILING SIGN:",?35,$FNUMBER(X,"T"),!

   WRITE "NEGATIVE NUMBERS IN ():",?35,$FNUMBER(X,"P"),!

   WRITE "COMMAS IN NUMBER:",?35,$FNUMBER(X,","),!

   WRITE "NUMBER WITH FRACTION:",?35,$FNUMBER(X,"",2),!

   WRITE "FORCE + SIGN IF POSITIVE:",?35,$FNUMBER(Y,"+"),!

   Produces the results:


   SUPPRESS NEGATIVE SIGN: 100000

   TRAILING SIGN: 100000-

   NEGATIVE NUMBERS IN (): (100000)

   COMMAS IN NUMBER: -100,000

   NUMBER WITH FRACTION: -100000.00

   FORCE + SIGN IF POSITIVE: +2000

   Example:


   SET x=$FNUMBER(x,"-")

   This example uses $FNUMBER() to SET x equal to its absolute value.

2 $Get()
   $Get()

   The $GET function 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 a null string.

   The format for the $GET function is:

   $G[ET](glvn[,expr])

   o    The subscripted or unsubscripted  global  or  local  variable  name
        specifies the node for which $GET() returns a value.

   o    If the global or local variable has a data  value,  $GET()  returns
        the value of the variable.

   o    If the global or local variable has no data value,  $GET()  returns
        the value of the optional expression (second argument), or  a  null
        string if the expression is not specified.

   M defines $GET(x,y) as equivalent to:


   $SELECT($DATA(x)[0:y,1:x)

   and $GET(x) as equivalent to:

   $GET(x,"")

   $GET()  provides  a  tool  to  eliminate  separate  initialization  of
   variables. This technique may provide performance benefits when used to
   increase the density of a sparse global array by eliminating nodes that
   would otherwise hold absent optional information. On  the  other  hand,
   some uses of one argument $GET() can mask logic problems.

   GT.M has a "NOUNDEF" mode  of  operation,  which  treats  all  variable
   references as if they were arguments to a one argument $GET(). The VIEW
   command controls "NOUNDEF" mode.

3 Ex_of_$Get()
   Examples of $GET()

   Example:


   I '$D(^PNT(NAME,TSTR)) S STATUS="NEW TEST"

   E I ^PNT(NAME,TSTR)="" S STATUS="WAITING FOR RESULT"

   E S STATUS=^PNT(NAME ,TSTR)

   This example can be reduced to two lines of code by using $GET(), shown
   in the following example. However, by using $GET() in its one-argument
   form, the distinction between an undefined variable and one with a null
   value is lost:


   S STATUS=$G(^PNT(NAME,TSTR))

   I STATUS="" S STATUS="WAITING FOR RESULT"

   This is solved by using the two-argument form of $GET():


   S STATUS=$G(^PNT(NAME,TSTR),"NEW TEST")

   I STATUS="" S STATUS="WAITING FOR RESULT"

2 $Justify()
   $Justify()

   The $JUSTIFY function returns a formatted string.

   The format for the $JUSTIFY function is:


   $J[USTIFY](expr,intexpr1[,intexpr2])

   o    The expression specifies the string formatted by $JUSTIFY().

   o    The  first  integer  expression  (second  argument)  specifies  the
        minimum  size  of  the  resulting  string.  If  the  first  integer
        expression is larger than the length of the expression, $JUSTIFY()
        right justifies the expression to a string of the specified length
        by  adding  leading  spaces.  Otherwise,  $JUSTIFY()  returns  the
        expression  unmodified  unless  specified  by  the  second  integer
        argument.

   o    The optional second integer expression (third  argument)  specifies
        the number of digits to follow the decimal point in the result, and
        forces $JUSTIFY() to evaluate the expression  as  numeric.  If  the
        numeric expression has more digits than  this  argument  specifies,
        $JUSTIFY() rounds to obtain the result. If the expression had fewer
        digits than  this  argument  specifies,  $JUSTIFY()  zero-fills  to
        obtain the result.

   o    When the second  argument  is  specified  and  the  first  argument
        evaluates to a fraction between -1  and  1,  $JUSTIFY()  returns  a
        number with a leading zero (0) before the decimal point (.).

   $JUSTIFY() fills expressions to create fixed length values. However, if
   the length of the specified  expression  exceeds  the  specified  field
   size, $JUSTIFY() does not truncate the result (although  it  may  still
   round based on the third argument). When required, $EXTRACT() performs
   truncation.

   $JUSTIFY() optionally rounds  the  portion  of  the  result  after  the
   decimal point. In the absence of the third  argument,  $JUSTIFY()  does
   not restrict the evaluation of the expression. In the presence  of  the
   third (rounding) argument, $JUSTIFY() evaluates  the  expression  as  a
   numeric value. The rounding algorithm can be understood as follows:

   o    If necessary, the rounding algorithm extends the expression to the
        right with 0s  (zeros)  to  have  at  least  one  more  digit  than
        specified by the rounding argument.

   o    Then, it adds 5 (five)  to  the  digit  position  after  the  digit
        specified by the rounding argument.

   o    Finally, it truncates the result to the specified number of digits.
        The algorithm rounds up when excess digits specify a half  or  more
        of the last retained digit and rounds down when they  specify  less
        than a half.

3 Ex_of_$Justify()
   Examples of $JUSTIFY()

   Example:


   GTM> WRITE $JUSTIFY("HELLO",10),!,$JUSTIFY("GOODBYE",5)

   HELLO

   GOODBYE

   GTM>

   This uses $JUSTIFY() to display "HELLO" in a field  of  10  spaces  and
   "GOODBYE" in a field of 5  spaces.  Because  the  length  of  "GOODBYE"
   exceeds five spaces, the result overflows the specification.

   Example:


   GTM> WRITE "1234567890",!,$JUSTIFY(10.545,10,2)

   1234567890
   10.55

   GTM>

   This uses $JUSTIFY() to WRITE a rounded  value  right  justified  in  a
   field of 10 spaces. Notice that the result has been rounded up.

   Example:


   GTM> WRITE "1234567890",!,$JUSTIFY(10.544,10,2)

   1234567890
   10.54

   GTM>

   Again, this uses $JUSTIFY() to WRITE a rounded value right justified in
   a field of 10 spaces. Notice that the result has been rounded down.

   Example:


   GTM> WRITE "1234567890",!,$JUSTIFY(10.5,10,2)

   1234567890
   10.50

   GTM>

   Once again, this  uses  $JUSTIFY()  to  WRITE  a  rounded  value  right
   justified in a field of 10 spaces. Notice  that  the  result  has  been
   zero-filled to 2 places.

   Example:


   GTM> WRITE $JUSTIFY(.34,0,2)

   0.34
   GTM>

   This example uses $JUSTIFY to ensure that the fraction  has  a  leading
   zero. Note the use of a second  argument  of  zero  in  the  case  that
   rounding is the only function that $JUSTIFY is to perform.

2 $Length()
   $Length()

   The $LENGTH function  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 function is:


   $L[ENGTH](expr1[,expr2])

   o    The  first  expression  specifies  the  string  that  $LENGTH()
        "measures."

   o    The optional second expression specifies the delimiter that defines
        the measure; if this argument is  missing,  $LENGTH()  returns  the
        number of characters in the string.

   o    If the second argument is present and not a  null  string,  $LENGTH
        returns one more than the count of the number of occurrences of the
        second string in the first string; if the second argument is a null
        string, the M standard specifies that $LENGTH() returns a zero (0).

   $LENGTH() provides a tool for determining the lengths of strings in two
   ways, characters and pieces. The two  argument  $LENGTH()  returns  the
   number of existing pieces, while the one argument returns the number of
   characters.

3 Ex_of_$Length()
   Examples of $LENGTH()

   Example:


   GTM> WRITE $LENGTH("KINGSTON")

   8
   GTM>

   This uses $LENGTH() to WRITE the length in  characters  of  the  string
   "KINGSTON".

   Example:


   GTM> SET x="Smith/John/M/124 Main Street/Ourtown/KA/USA"

   GTM> WRITE $LENGTH(x,"/")

   7
   GTM>

   This uses $LENGTH() to WRITE the number  of  pieces  in  a  string,  as
   delimited by /.

   Example:


   GTM> WRITE $LENGTH("/2/3/","/")

   4
   GTM>

   This also uses $LENGTH() to WRITE the number of pieces in a string, as
   delimited by /. Notice that GT.M. adds one count to the final number of
   pieces (in this case 3), in the string (displays 4).

2 $NAme()
   $NAme()

   The $NAME function returns an evaluated representation of some  or  all
   of a local or global variable name.

   The format for the $NAME function is:


   $NA[ME](glvn[,intexpr])

   o    The subscripted or unsubscripted global  or  local  variable  name,
        including naked references, specifies the name  for  which  $NAME()
        returns an evaluated representation.

   o    The optional integer expression  (second  argument)  specifies  the
        maximum number of subscript levels in the  representation.  If  the
        integer expression is not provided or exceeds the actual number of
        subscript levels, $NAME() returns a  representation  of  the  whole
        name. If the integer expression is zero (0), $NAME()  returns  only
        the name. A negative integer expression produces a run-time error.

3 Ex_of_$Name()
   Examples of $NAME()

   Example:


   GTM> SET X="A""B",^Y(1,X,"B",4)=""

   GTM> WRITE $NAME(^(3),3)

   ^Y(1,"A""B","B")

   GTM>

   This example sets up a naked reference and then uses $NAME() to display
   the first three levels of that four-level reference.

   Example:


   GTM> WRITE $NAME(^(3),0)

   ^Y

   GTM>

   This example shows the name level for the same naked reference.

2 $Next()
   $Next()

   The $NEXT  function  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.

        As $NEXT() has been removed from  the  standard  in  the  MDC,  you
        should use $ORDER.

   The format for the $NEXT function is:


   $N[EXT](glvn)

   o    The subscripted global or local variable name  specifies  the  node
        following which $NEXT() searches for the next node with data and/or
        descendants; the number of subscripts  contained  in  the  argument
        implicitly defines the array level.

   o    If $NEXT() finds no node at the specified level after the specified
        global or local variable, it returns negative one (-1).

   o    If the last subscript in a subscripted  global  or  local  variable
        name is null or negative one (-1), $NEXT() returns the  first  node
        at the specified level.

2 $Order()
   $Order()

   The $ORDER function 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 function is:


   $O[RDER](glvn[,expr])

   o    The subscripted global or local variable name  specifies  the  node
        from which $ORDER() searches for the next or previous node that has
        data and/or descendants. The number of subscripts contained in the
        argument implicitly defines the array level.

   o    The optional expression (second argument) specifies  the  direction
        for the $ORDER(); 1 specifies forward operation  and  -1  specifies
        reverse operation. Any other values for the expression  will  cause
        an error.

   o    GT.M extends the M standard to allow unsubscripted names.  In  this
        case, $ORDER() returns the next or previous unsubscripted name.

   o    If $ORDER() finds no node (or name) at the  specified  level  after
        (or before) the specified global or local variable,  it  returns  a
        null string (" ").

   o    If the last subscript in the subscripted global or  local  variable
        name is null, $ORDER() returns the first  (or  last)  node  at  the
        specified level.

   $ORDER() provides a tool for retrieving data from M sparse arrays in an
   ordered fashion, independent of the order in which it was  entered.  In
   M,  routines  generally  sort  by  SETting  data  into  an  array  with
   appropriate  subscripts  and  then  retrieving  the  information  with
   $ORDER().

   $ORDER() returns subscripts, not data values, and does not discriminate
   between nodes that have data values and nodes  that  have  descendants.
   Once  $ORDER()  provides  the  subscript,  the  routine  must  use  the
   subscript to access the data  value,  if  appropriate.  Using  $ORDER()
   maintains the naked reference indicator, even  if  $ORDER()  returns  a
   null.

   GT.M optionally permits the use of null  subscripts.  This  feature  is
   enabled via the VIEW command for local variables and a REGION qualifier
   in GDE for global variables. When an application uses null subscripts,
   they are "invisible" in a $ORDER() loop so the  application  must  test
   for them as a special case, perhaps using $DATA().

3 Ex_of_$Order()
   Examples of $ORDER()

   Example:


   GTM>K S (a(1),a(2000),a("CAT"),a("cat"),a("ALF"), a(12))=1

   GTM>S x="" F S x=$O(a(x)) Q:x="" W !,x

   1
   12
   2000
   ALF

   CAT

   cat

   GTM>K a("CAT") SET a(5,10)="woolworths",a("cat")="last"

   GTM> S x="" F S x=$O(a(x),-1) Q:x="" W !,x

   cat

   ALF

   2000
   12
   5
   1
   GTM>

   This example uses a $ORDER() loop to display all the subscripts at the
   first level of local variable a, make  some  changes  in  a,  and  then
   display all the subscripts  in  reverse  order.  Notice  that  $ORDER()
   returns only the existing subscripts in the sparse  array  and  returns
   them in M collation sequence, regardless of the  order  in  which  they
   were entered. Also, $ORDER() does not differentiate between node A(5),
   which has only descendants (no data value), and the other nodes, which
   have data values.

   Example:


   GTM>k s (%(1),tiva(2),A(3),tiv(4),Q(5),%a(6))=""

   GTM>s x="%"

   GTM>w:$d(@x) !,x f s x=$order(@x) q:x="" w !,x

   %

   %a

   A

   Q

   tiv

   tiva

   x

   GTM>s x="zzzzzzzz"

   GTM>w:$d(@x) !,x f s x=$order(@x,-1) q:x="" w !,x

   x

   tiva

   tiv

   Q

   A

   %a

   %

   GTM>

   This loop uses $ORDER() to display the current local variable names in
   both forward and reverse order. Notice that the first ([^]%)  and  last
   ([^]zzzzzzzz) names require handling as special  cases  and  require  a
   $DATA() function.

   Example:


   SET acct="",cntt=""

   FOR SET acct=$OREDER(^acct(acct)) QUIT:acct="" DO

   . F SET cntt=$ORDER(^acct(acct,cntt)) DO WORK

   QUIT

   This uses two nested $ORDER() loops to cycle through the  ^acct  global
   array and perform some action for each second level node.

2 $Piece()
   $Piece()

   The $PIECE function 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 function is:


   $P[IECE](expr1,expr2[,intexpr1[,intexpr2]])

   o    The first expression specifies the string from which $PIECE() takes
        its result.

   o    The  second  expression  specifies  the  delimiting  string  that
        determines the piece "boundaries";  if  this  argument  is  a  null
        string, $PIECE() returns a null string.

   o    If the second expression does not  appear  anywhere  in  the  first
        expression, $PIECE() returns the entire  first  expression  (unless
        forced to return a null string by the second integer expression).

   o    The optional first integer expression  (third  argument)  specifies
        the beginning  piece  to  return;  if  this  argument  is  missing,
        $PIECE() returns the first piece.

   o    The optional second integer expression (fourth argument) specifies
        the last piece to return. If this  argument  is  missing,  $PIECE()
        returns only one piece unless the first integer expression is zero
        (0) or negative, in which case it returns a null  string.  If  this
        argument is  less  than  the  first  integer  expression,  $PIECE()
        returns a null string.

   o    If the second integer  expression  exceeds  the  actual  number  of
        pieces in  the  first  expression,  $PIECE()  returns  all  of  the
        expression after  the  delimiter  selected  by  the  first  integer
        expression.

   o    The  $PIECE()  result  never  includes  the  "outside"  delimiters;
        however,  when  the  second  integer  argument  specifies  multiple
        pieces,  the  result  contains  the  "inside"  occurrences  of  the
        delimiter.

   $PIECE() provides a tool for  efficiently  using  values  that  contain
   multiple elements or fields, each of which may be variable in length.

   Applications typically use a single character for a $PIECE() delimiter
   (second argument) to minimize storage overhead, and increase efficiency
   at run-time. The delimiter must be chosen  so  the  data  values  never
   contain the delimiter. Failure to enforce  this  convention  with  edit
   checks may result in unanticipated changes in the  position  of  pieces
   within the data value. The caret symbol (^), backward  slash  (\),  and
   asterisk (*) characters are examples  of  popular  visible  delimiters.
   Multiple character delimiters may reduce  the  likelihood  of  conflict
   with field contents. However, they decrease storage efficiency, and are
   processed with less efficiency than single character  delimiters.  Some
   applications use control characters, which reduce the  chances  of  the
   delimiter appearing in the data but sacrifice the readability provided
   by visible delimiters.

   A SET command argument can have something that  has  the  format  of  a
   $PIECE() on the left-hand side of its equal sign  (=).  This  construct
   permits easy maintenance of individual pieces within a string. It also
   can be used to generate a string of delimiters. For more information on
   SET $PIECE(), refer to SET in the "Commands" chapter.

3 Ex_of_$Piece()
   Examples of $PIECE()

   Example:


   GTM> FOR i=0:1:3 WRITE !,$PIECE("1 2"," ",i),"<"

<
   1<
   2<
<
   GTM>

   This loop displays the result of $PIECE(),  specifying  a  space  as  a
   delimiter, a piece position "before," first and second, and "after" the
   string.

   Example:


   GTM> FOR i=-1:1:3 WRITE !,$PIECE("1 2"," ",i,i+1),"<"

<
   1<
   1 2<
   2<
<
   GTM>

   This example is similar to the previous example except that it displays
   two pieces on each iteration. Notice the delimiter  (a  space)  in  the
   middle of the output for  the  third  iteration,  which  displays  both
   pieces.

   Example:


   F p=1:1:$L(x,"/") W ?p-1*10,$piece(x,"/",p)

   This loop uses $LENGTH() and $PIECE() to display all the pieces of x in
   columnar format.

   Example:


   GTM> s $P(x,".",25)="" W x

   ........................
   This SETs the 25th piece of the variable x to null, with a delimiter of
   a period. This produces a string of 24 periods preceding the null.

2 $Qlength()
   $Qlength()

   The $QLENGTH function returns the number of subscripts  in  a  variable
   name. The format is:


   $QL[ENGTH] (namevalue)

   o    The  namevalue  has  the  form  of  an  evaluated  subscripted  or
        unsubscripted global variable (which yields a length of  zero,  and
        which may have an environment -  not  counted)  or  local  variable
        name.

   o    The form returns a  value  which  is  derived  from  namevalue.  If
        namevalue has the form NAME(s1, s2,..., sn), considering  n  to  be
        zero, if there are no subscripts, then the function returns n.

   o    This function only affects the naked indicator  if  the  string  in
        question is stored in a global variable.

3 Ex_of_$Qlength()
   Examples of $Qlength()

   Example:


   WRITE $DATA(^|"XXX"|ABC(1,2,3,4))


   GTM>0


   SET X=$NAME(^(5,6))

   WRITE $QLENGTH(X)

   GTM>5

   Refer to $NAme() section earlier in this chapter for  an  understanding
   of the $NAME function.

2 $Qsubscript()
   $Qsubscript()

   The $QSUBSCRIPT function returns a component of a variable name.

   The format of the $QSUBSCRIPT function is:


   $QS[UBSCRIPT](namevalue, intexpr)

   o    The  namevalue  has  the  form  of  an  evaluated  subscripted  or
        unsubscripted global or local variable name.

   o    The intexpr selects the component of the name as follows:

   -2 is reserved but may be "error",

   -1 for environment,

   0 for the unsubscripted name,
   1 for the first subscript,
   2 for the second subscript, and so on.
   If the second argument selects a component that  is  not  part  of  the
   specified name, $QSUBSCRIPT() returns an empty string ("").

3 Ex_of_$Qsubscript()
   Examples of $Qsubscript()

   Example:

   Assume that X is defined as in the "Examples of $Qlength()" earlier in
   this chapter;


   $QLENGTH (X="^|""XXX""|ABC(1,2,3,5,6)")


   WRITE $QSUBSCRIPT(X,-2)

   GTM>error


   WRITE $QSUBSCRIPT(X,-1)

   GTM>XXX


   WRITE $QSUBSCRIPT(X,0)

   GTM>^ABC


   WRITE $QSUBSCRIPT(X,1)

   GTM>1


   WRITE $QSUBSCRIPT(X,4)

   GTM>5


   WRITE $QSUBSCRIPT(X,7)

   GTM>""

2 $Query()
   $Query()

   The $QUERY function  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 function is:


   $Q[UERY](glvn)

   o    The subscripted or unsubscripted  global  or  local  variable  name
        specifies the starting node from which $QUERY() searches for a node
        with a data value.

   o    If $QUERY() finds no node  after  the  specified  global  or  local
        variable, it returns a null string.

   $QUERY() provides a tool for scanning an entire array  for  nodes  that
   have data values. Because $QUERY() can return  a  result  specifying  a
   different level than its argument, the result provides a full variable
   name. This contrasts with $ORDER(), which returns a subscript value. To
   access the data value at a node, a $ORDER() return can  be  used  as  a
   subscript; however, a $QUERY() return must be  used  with  indirection.
   Because arrays tend to have homogeneous values within a level  but  not
   between levels, $QUERY() is more useful as a tool in  utility  programs
   than in application programs. The $QUERY() is useful in avoiding nested
   $ORDER loops.

   Note that the standard does not unambiguously define the state  of  the
   naked reference  indicator  after  a  $QUERY().  While  in  GT.M  after
   $QUERY(), the naked reference indicator reflects the $QUERY() argument,
   NOT its result.

3 Ex_of_$Query()
   Examples of $QUERY()

   Example:


   SET ^X(1,2,3)="123"

   SET ^X(1,2,3,7)="1237"

   SET ^X(1,2,4)="124"

   SET ^X(1,2,5,9)="1259"

   SET ^X(1,6)="16"

   SET ^X("B",1)="AB"

   The following routine:


   SET y="^X"

   FOR SET y=$QUERY(@y) QUIT:y="" WRITE !,y,"=",@y

   produces the results:


   ^X(1,2,3)=123

   ^X(1,2,3,7)=1237

   ^X(1,2,4)=124

   ^X(1,2,5,9)=1259

   ^X(1,6)=16

   ^X("B",1)=AB

2 $Random()
   $Random()

   The $RANDOM function returns a random integer from a range specified by
   its argument.

   The format for the $RANDOM function is:


   $R[ANDOM](intexpr)

   o    The integer expression specifies the upper  exclusive  limit  of  a
        range of integers from which $RANDOM() may pick a result; $RANDOM()
        never returns a number less than zero (0).

   o    If $RANDOM() has an argument less than  one  (1),  it  generates  a
        run-time error.

   o    $RANDOM can generate numbers up to 2147483646 (that is 2GB - 2).

   $RANDOM() provides a tool for generating pseudo-random patterns useful
   in testing or statistical calculations. $RANDOM() results fall between
   zero (0) and one less than the argument.

   Random number generators use factors from  the  environment  to  create
   sequences of numbers. True random number generation requires  a  source
   of what is known as noise. Pseudo-random  numbers  appear  to  have  no
   pattern, but are developed using interactions between factors that vary
   in ways not guaranteed to be entirely random. In accordance with the M
   standard, the GT.M implementation of $RANDOM()  produces  pseudo-random
   numbers.

3 Ex_of_$Random()
   Examples of $RANDOM()

   Example:


   GTM> FOR i=1:1:10 WRITE $RANDOM(1)

   0000000000
   GTM>

   This shows that when $RANDOM() has an argument of one (1),  the  result
   is too confined to be random.

   Example:


   SET x=$RANDOM(100)+1*.01

   This $RANDOM() example produces a number between 0 and 99. The example
   then shifts with addition, and scales with multiplication to  create  a
   value between .01 and 1.

2 $Reverse()
   $Reverse()

   The $REVERSE function returns a  string  with  the  characters  in  the
   reverse order from that of its argument.

   The format for the $REVERSE function is:


   $RE[VERSE](expr)

   o    The expr in the syntax is the string to be reversed.

3 Ex_of_$Reverse()
   Examples of $REVERSE()

   Example:


   WRITE $REVERSE(123)

   GTM>321


   WRITE $REVERSE("AbCDe")

   GTM>"eDCbA"

2 $Select()
   $Select()

   The $SELECT function returns a value associated  with  the  first  true
   truth-valued expression in a list of paired expression arguments.

   The format for the $SELECT function is:


   $S[ELECT](tvexpr:expr[,...])

   o    $SELECT() evaluates expressions from left to right.

   o    If a truth-valued expression is TRUE  (1),  $SELECT()  returns  the
        corresponding expression after the colon (:) delimiter.

   o    Once $SELECT() finds a TRUE, the  function  does  not  process  any
        remaining arguments.

   o    If $SELECT() finds no TRUE truth-value in its  list  of  arguments,
        the function generates a run-time error.

   $SELECT() is  one  of  a  limited  set  of  functions  that  permit  an
   indefinite number of arguments. $SELECT() provides a means of selecting
   from a list of alternatives.

   Generally, the last $SELECT() argument has numeric literal one (1) for
   a truth-value to prevent run-time errors, and to  provide  a  "default"
   value.

3 Ex_of_$Select()
   Examples of $SELECT()

   Example:


   GTM> F i=3:-1:0 W !,$S(i=1:"here",i=2:"come",i=3: "Watson")

   Watson

   come

   here

   %GTM-E-SELECTFALSE, No argument to $SELECT was true

   GTM>

   This loop uses $SELECT() to WRITE a series of strings. Because there is
   no true argument on the fourth iteration, when i=0, $SELECT() produces
   an error.

   Example:


   SET name=$S(sex="M":"Mr. ",sex="F":"Ms. ",1:"")_name

   This example uses $SELECT() to add a prefix to the name based on a sex
   code held in the variable sex. Notice that the default handles the case
   of a missing or incorrect code.

   Example:


   IF $S(x=+x:x,x="":0,"JANAPRJULOCT"[x:1,1:0) D THING

   This uses $SELECT()  to  perform  complex  logic  as  the  truth-valued
   expression argument to an IF command.

2 $Stack()
   $Stack()

   The $STACK function returns strings describing aspects of the execution
   environment.

   The format for the $STACK function is:


   $ST[ACK](intexpr[,expr])

   o    The intexpr identifies  the  M  virtual  machine  stack  level  (as
        described by the standard), on which the  function  is  to  provide
        information.

   o    The optional  second  argument  is  evaluated  as  a  keyword  that
        specifies a type of information to be returned as follows: "PLACE"
        for position in the code (for which,  GT.M.  due  to  its  compiled
        nature, has  no  information),  "MCODE"  for  the  source  code  if
        available, or "ECODE" for the  $ECODE  value  associated  with  the
        stack level.

   o    When  $STACK  has  only  one  argument,  values  corresponding  to
        available stack levels specify a return value  that  indicates  how
        the level was created, as follows:

   o    If intexpr is zero (0), the function  returns  information  on  how
        GT.M was invoked.

   o    If intexpr is minus one (-1),  the  function  returns  the  highest
        level for which  $STACK  can  return  information.  Note  that,  if
        $ECODE="", $STACK(-1) returns the same value as $STACK.

   o    If intexpr is greater than zero (0)  and  less  than  or  equal  to
        $STACK (-1), indicates how this level of process stack was created
        ("DO", "XECUTE", or "$$". "$$" being for an extrinsic function).

   o    If intexpr is greater than $STACK (-1),  the  function  returns  an
        empty string.

   o    For any integer value of "level" between 0 and max (inclusive), the
        function $STACK(level, type) provides the following information:

        Type Information
        "MCODE" the line of code that was executed
        "PLACE" the address of the above line of  code  or  the  symbol  at
        ("@") to indicate code executed from a string value
        "ECODE" either an empty string, or the error code(s) that was added
        at this execution level.
3 Ex_of_$Stack()
   Examples of $STACK()

   Example:


   WRITE !,$STACK

   XECUTE "WRITE !,$STACK"

   DO Label

   WRITE !,$$ELabel

   WRITE !,$STACK

   QUIT


   Label

   WRITE !,$STACK

   DO DLabel

   QUIT


   ELabel()

   QUIT $STACK


   DLabel

   WRITE !,$STACK

   QUIT

   The above example when executed displays the current M stack level. The
   result of the execution is:


   GTM>0

   1
   1
   2
   1
   0
   Example for error processing:


   For i=$STACK(-1):-1:1 DO

   . WRITE !,$STACK(i,"PLACE"),":"
   . WRITE $STACK(i,"MCODE")
   . QUIT
   The above example can be used to display a trace of the code path that
   led to an error.

2 $Text()
   $Text()

   The $TEXT function returns source text for the line  specified  by  its
   argument.

   The format for the $TEXT function is:


   $T[EXT](entryref)

   o    The entryref specifies the label, offset, and routine of the source
        line that $TEXT() returns.

   o    If the label+offset combination do not  fall  within  the  routine,
        $TEXT returns a null string.

   o    If the entryref explicitly or implicitly  specifies  an  offset  of
        zero (0) from the beginning of the  routine,  $TEXT()  returns  the
        routine name.

   o    If the entryref does  not  specify  a  routine,  GT.M  assumes  the
        current routine, that is, the routine at the top of a ZSHOW "S."

   o    A GT.M extension to  $TEXT()  permits  negative  offsets;  however,
        every offset must still be preceded by a plus sign  (+)  delimiter,
        (for example, LABEL+-3). If a negative  offset  points  to  a  line
        prior to the zero line, $TEXT() generates a run-time error.

   $TEXT() provides a tool for examining routine source code and the name
   of the current routine. $TEXT() assists, along with the ZPRINT command,
   in debugging programs. $TEXT()  also  allows  the  insertion  of  small
   tables of driver information into a routine.  Because  $TEXT()  is  not
   very efficient and the table-driven technique is generally best suited
   to minimal program changes, this approach is best used for prototyping
   and the tables should reside in global variables for production.

   If $TEXT() cannot access the source file for the current object, either
   because it is not in the location from which it was compiled or because
   the process does not have access to some  piece  of  the  path  to  the
   source, or if the located source does not match the object currently in
   use by the process, $TEXT() returns the empty string.

3 Ex_of_$Text()
   Examples of $TEXT()

   Example:


   F i=1:1 S x=$T(+i) Q:x="" W !,x

   This loop uses $TEXT() to write out the entire source for  the  current
   routine.

   Example:


   GTM> WRITE $TEXT(+0)

   GTM$DMOD

   GTM> WRITE $TEXT(+1)

   GTM>

   This uses $TEXT() to WRITE the name of the  current  routine,  then  it
   tries to access the source and returns an  empty  string.  This  occurs
   because the default Direct  Mode  image  is  compiled  by  Sanchez  and
   delivered without source. The exact failure message may vary.

2 $TRanslate()
   $TRanslate()

   The $TRANSLATE function 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 function is:


   $TR[ANSLATE](expr1[,expr2[,expr3]])

   o    The first expression specifies the  string  on  which  $TRANSLATE()
        operates. If the other arguments are omitted, $TRANSLATE() returns
        this expression.

   o    The  optional  second  expression  specifies  the  characters  for
        $TRANSLATE() to replace. If a character occurs more  than  once  in
        the  second  expression,  the  first  occurrence  controls  the
        translation, and $TRANSLATE() ignores  subsequent  occurrences.  If
        this argument is omitted, $TRANSLATE() returns the first expression
        without modification.

   o    The optional third expression specifies the replacement characters
        for the second expression that corresponds  by  position.  If  this
        argument  is  omitted  or  shorter  than  the  second  expression,
        $TRANSLATE() drops all occurrences  of  characters  in  the  second
        expression that have no replacement in the  corresponding  position
        of the third expression.

   $TRANSLATE() provides a tool for tasks such as changing case and doing
   encryption. For examples of case translation, refer to the ^%LCASE and
   ^%UCASE utility routines.

   The $TRANSLATE() algorithm can be understood as follows:

   o    $TRANSLATE() evaluates each  character  in  the  first  expression,
        comparing it  character  by  character  to  the  second  expression
        looking for a match. If there is no match in the second expression,
        the  resulting  expression  contains  the  character  without
        modification.

   o    When it locates a character match, $TRANSLATE() uses  the  position
        of the match in the second expression to identify  the  appropriate
        replacement for the original expression. If the  second  expression
        has  more  characters  than  the  third  expression,  $TRANSLATE()
        replaces the original character with a null,  thereby  deleting  it
        from the result. By extension  of  this  principle,  if  the  third
        expression is missing, $TRANSLATE() deletes all characters from the
        first expression that occur in the second expression.

3 Ex_of_$TRanslate()
   Examples of $TRANSLATE()

   Example:


   GTM> WRITE $TR("ABC","CB","1")

   A1

   GTM>

   o    First, $TRANSLATE() searches for "A" (the first  character  in  the
        first expression, "ABC") within the second expression ("CB"). Since
        "A" does not exist in the second expression, it  appears  unchanged
        in the result.

   o    Next, $TRANSLATE() searches for "B" (the second  character  in  the
        first expression) within the second expression ("CB"). Because "B"
        holds  the  second  position  in  the  second  expression  ("CB"),
        $TRANSLATE() searches for the character holding the second position
        in the third expression. Since there is no second character in the
        third  expression,  $TRANSLATE()  replaces  "B"  with  a  null,
        effectively deleting it from the result.

   o    Finally, $TRANSLATE() searches for "C" (the third character in the
        first expression) within the second expression ("CB"), finds it in
        the first position, and replaces it with the number 1, which is in
        the first position of the third expression. The  translated  result
        is "A1."

   Example:


   GTM> WRITE $TR("A","AA","BC")

   B

   GTM>

   This $TRANSLATE() example finds the first  occurrence  of  "A"  in  the
   second expression,  which  holds  the  first  character  position,  and
   substitutes  the  character  in  the  first  position  of  the  third
   expression.

   Example:


   GTM> WRITE $TR("BACKUP","AEIOU")

   BCKP

   GTM>

   Because the $TRANSLATE() has only two parameters in  this  example,  it
   finds the characters in the first expression that  also  exist  in  the
   second expression and deletes them from the result.

2 $View()
   $View()

   The $VIEW function 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() function is:


   $V[IEW](expr1[,expr2])

   o    The first expression specifies a  keyword  identifying  the  target
        factor for $VIEW() to examine.

   o    The second  expression  differentiates  between  multiple  possible
        targets for some keywords. $VIEW() requires the  second  expression
        for some keywords and does not permit it for others.

   The $VIEW function returns 1 (true) if the region is frozen by MUPIP or
   DSE and returns 0 (false) otherwise.

3 Arg_Key_of_$View()
   Argument Keywords of $VIEW()

   $VIEW() provides a means of accessing GT.M  environmental  information.
   $VIEW() is similar in purpose to Intrinsic Special Variables. When GT.M
   permits modification of the factors accessible with $VIEW(),  the  VIEW
   command generally provides the tool for performing the change.

3 Ex_of_$View()
   Examples of $VIEW()

   Example:


   S len=$L(name)

   S be4=$EXTRACT(name,1,len-1)_$CHAR($ASCII(name,len)-1)

   I $V("RTNNEXT",be4_$E("ZZZZZZZ",1,8-len))=name D

   . ZLINK name
   Given a routine name this uses $VIEW() to determine whether  the  image
   contains the routine. If the routine already exists the ZLINK replaces
   it. Otherwise, auto-ZLINK will bring in a new copy.

2 $ZBIT_Func
   $ZBIT Functions

   A series of functions beginning with $ZBIT  let  you  manipulate  bits.
   Each function is described in its own section, and an  example  at  the
   end of the last section illustrates the use of several of the functions
   in context.

3 $ZBITAND()
   $ZBITAND()

   The $ZBITAND function performs an 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() function is:


   $ZBITAND(expr1,expr2)

   o    The first expression specifies one of the bit strings that is input
        to the AND operation.

   o    The second expression specifies the other bit string that is input
        to the AND operation.

3 $ZBITCOUNT()
   $ZBITCOUNT()

   The $ZBITCOUNT function returns the number of ON bits in a bit string.

   The format for the $ZBITCOUNT function is:


   $ZBITCOUNT(expr)

   o    The expression specifies the bit string to examine.

3 $ZBITFIND()
   $ZBITFIND()

   The $ZBITFIND function performs the analog of the $FIND function  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 function is:


   $ZBITFIND(expr,tvexpr[,intexpr])

   o    The expression specifies the bit string to examine.

   o    The truth-valued expression  specifies  the  bit  value  for  which
        $ZBITFIND() searches (1 or 0).

   o    The optional integer argument specifies the  starting  position  at
        which to begin the search. If this argument is missing, $ZBITFIND()
        begins searching  at  the  first  position  of  the  string.  $ZBIT
        functions count the first bit as position one (1).

   If the optional integer argument exceeds the length of the  string,  or
   if the function finds no  further  bits,  $ZBITFIND()  returns  a  zero
   value.

3 $ZBITGET()
   $ZBITGET()

   The $ZBITGET function returns the value of a specified position in the
   bit string.

   The format for the $ZBITGET function is:


   $ZBITGET(expr,intexpr)

   o    The expression specifies the bit string to examine.

   o    The integer argument specifies the position in the string for which
        the value is requested. If the integer argument is negative, zero,
        or exceeds the length of the bit string,  it  is  rejected  with  a
        run-time error. $ZBIT functions count the first bit as position one
        (1).

3 $ZBITLEN()
   $ZBITLEN()

   The $ZBITLEN function returns the length of a bit string, in bits.

   The format for the $ZBITLEN function is:


   $ZBITLEN(expr)

   o    The expression specifies the bit string to examine.

3 $ZBITNOT()
   $ZBITNOT()

   The $ZBITNOT function returns a copy of the bit string with each input
   bit position inverted.

   The format for the $ZBITNOT function is:


   $ZBITNOT(expr)

   o    The expression specifies the bit string whose inverted bit pattern
        becomes the result of the function.

3 $ZBITOR()
   $ZBITOR()

   The $ZBITOR function performs a bitwise 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 function is:

   $ZBITOR(expr1,expr2)

   o    The first expression specifies one of the bit strings that is input
        to the OR operation.

   o    The second expression specifies the other bit string that is input
        to the OR operation.

3 $ZBITSET()
   $ZBITSET()

   The $ZBITSET function 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 function is:


   $ZBITSET(expr,intexpr,tvexpr)

   o    The expression specifies the input bit string.

   o    The integer  expression  specifies  the  position  of  the  bit  to
        manipulate. Arguments that are negative, zero, or exceed the length
        of the bit string produce a run-time error. $ZBIT  functions  count
        the first bit as position one (1).

   o    The truth-valued expression specifies the value to which to set the
        specified bit (0 or 1).

3 $ZBITSTR()
   $ZBITSTR()

   The $ZBITSTR function returns a bit string of a specified  length  with
   all bit positions initially set to either zero or one.

   The format for the $ZBITSTR function is:


   $ZBITSTR(intexpr[,tvexpr])

   o    The integer expression specifies the length of the  bit  string  to
        return; arguments that exceed the maximum length of 253,952 produce
        a run-time error.

   o    The optional truth-valued expression specifies the value  to  which
        all bit positions should  initially  be  set  (0  or  1).  If  this
        argument is missing, the bits are set to zero.

3 $ZBITXOR()
   $ZBITXOR()

   The $ZBITXOR 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 function is:


   $ZBITXOR(expr1,expr2)

   o    The first expression specifies one of the bit strings that is input
        to the XOR operation.

   o    The second expression specifies the other bit string that is input
        to the XOR operation.

3 Ex_of_$ZBIT_Func
   Examples of $ZBIT Functions

   Example:


   ZCRC(X)

   NEW R,I,J,B,X1,K

   SET R=$ZBITSTR(8,0)

   FOR I=1:1:$L(X) S R=$ZBITXOR(R,$$BITIN($A(X,I)))

   QUIT $$BITOUT(R)

   ;CONVERT A BYTE TO A BIT STRING


   BITIN(X)

   SET X1=$ZBITSTR(8,0)

   FOR J=1:1:8 S B=X#2,X=X\2 i B s X1=$ZBITSET(X1,J,1)

   QUIT X1

   ; CONVERT A BITSTRING TO A NUMBER


   BITOUT(X)

   SET X1=0

   FOR K=1:1:8 I $ZBITGET(X,K) S X1=X1+(2**(K-1))

   QUIT X1

   This uses several $ZBIT functions to turn a character into a bit stream
   and return a coded value.

   While this  example  illustrates  the  use  of  several  of  the  $ZBIT
   functions, the following example produces identical results if you need
   to code the function illustrated above for production.


   ZCRC(X)

   NEW R,I,J,B,X1,K

   SET R=$ZBITSTR(8,0)

   FOR I=1:1:$L(X) S R=$ZBITXOR(R,$C(0)_$E(X,I))

   QUIT $A(R,2)

   This example illustrates the use of $C to specify the number of invalid
   bits that exist at the end of the character string. In this case there
   are zero invalid bits.

2 $ZDate()
   $ZDate()

   The $ZDATE function 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  the  "Intrinsic  Special  Variables"
   chapter in this manual.

   The format for the $ZDATE function is:


   $ZD[ATE](expr1[,expr2[,expr3[,expr4]]]])

   o    The first expression specifies in $HOROLOG format the  date  and/or
        time that $ZDATE() returns in text format. If the  output  requires
        only the date or the time, the other piece of the argument that is
        delimited by a comma (,) may be null.

   o    The  optional  second  expression  specifies  a  string  providing
        $ZDATE() with a "picture" of the desired  output  format.  If  this
        argument is missing or  null,  $ZDATE()  uses  the  default  format
        string "MM/DD/YY". If the optional  second  expression  exceeds  64
        characters, $ZDATE() generates a run-time error.

   o    The optional third expression specifies a list of 12  month  codes,
        separated by commas (,), that  $ZDATE()  uses  in  formatting  text
        months called for by the "MON"  picture,  (i.e.,  $ZDATE()  outputs
        $PIECE(expr3,",",month-number) when "MON"  appears  in  the  second
        expression). If this argument is missing  or  null,  $ZDATE()  uses
        three-character English abbreviations for months.

   o    The optional fourth expression specifies a list of seven day codes,
        separated by commas (,), which $ZDATE()  uses  in  formatting  text
        days of the week called for by the "DAY" picture, $ZDATE() outputs
        $PIECE (expr4,",",day-of-week-number) when  "DAY"  appears  in  the
        second expression; if this argument is missing  or  null,  $ZDATE()
        uses three-character English abbreviations for days of the week.

   $ZDATE() provides an easy and flexible  tool  for  putting  M  internal
   date/time ($HOROLOG) formats into more user-friendly formats.

   The Intrinsic Special Variable $ZDATEFORM determines the output format
   for years. The default value is zero (0), in which case  $ZDATE()  with
   one argument (no format specification) uses a "YY" (two  digit)  format
   for all years. If $ZDATEFORM is one (1), a "YYYY" (four  digit)  format
   is used for years later than 1999. For all other values of $ZDATEFORM,
   "YYYY" (four digit) format is used for all years. $ZDATEFORM  does  not
   affect $ZDATE() when the format argument is specified.

3 $ZDate_Form_Spec_Ele
   $ZDATE Format Specification Elements

   This section lists the $ZDATE() format specification elements. $ZDATE()
   format specifications must appear in upper case.  When  any  alphabetic
   characters  in  format  specifications  are  in  lower  case,  $ZDATE()
   generates a run-time error.

        YY Outputs the rightmost two digits of the year.
        YEAR Outputs the year as a four-digit number.
        MM Outputs the month as a two-digit zero-filled number  between  01
        and 12.
        MON Outputs the month as  a  three-letter  abbreviation.  (You  can
        modify the output further using expr3).
        DD Outputs the day of the month as a two-digit  zero-filled  number
        between 01 and 31.
        DAY Outputs the day of the week  as  a  three-letter  abbreviation.
        (You can modify the output further using expr4).
        24 Outputs the hour of the day as a zero-filled number  between  00
        and 23.
        12 Outputs the hour of the day as a zero-filled number  between  01
        and 12.
        60 Outputs the minute of the hour as a zero-filled  number  between
        00 and 59.
        SS Outputs the second of the minute as a zero-filled number between
        00 and 59.
        AM Outputs the letters AM and PM depending on the time.
        + Inserts a plus sign (+) in the output string
        - Inserts a minus sign (-) in the output string.
        . Inserts a period (.) in the output string.
        , Inserts a comma (,)in the output string.
        / Inserts a slash (/) in the output string.
        : Inserts a colon (:) in the output string.
        ; Inserts a semi-colon (;) in the output string.
        * Inserts an asterisk (*) in the output string.
        A blank space inserts a blank space in the output string.

3 Ex_of_$ZDate()
   Examples of $ZDATE()

   Example:


   GTM> WRITE $H,!,$ZDATE($H)

   55243,43223
   04/01/2002
   GTM>

   This displays $HOROLOG and then uses $ZDATE() to display today's date.
   The output shown would appear if today were the first of April, 2002.

   Example:


   GTM> W $ZDATE($H,"DD-MON-YEAR")

   01-APR-2002
   GTM>

   This uses the second argument to specify a text format  different  from
   the default.

   Example:


   GTM> SET m="Januar,Februar,Marz,April,Mai,Juni,Juli,August,"

   GTM> SET m=m_"September,October,November,Dezember"

   GTM> WRITE $ZDATE($H,"DD-MON-YEAR",m)

   01-April-2002
   GTM>

   This is similar to  the  prior  example,  however  it  uses  the  third
   argument to specify the months in German.

   Example:


   GTM> SET d="Dimanche,Lundi,Mardi,Mercredi,Jeudi,Vendredi,Samedi"

   GTM> WRITE $ZD($H,"DAY, DD/MM/YY","",d)

   Mercredi, 01/04/2002

   GTM>

   This example displays the first of April, however it  uses  the  fourth
   argument to specify the days of the week in French.

   Example:


   GTM> WRITE !,$ZDATE($H,"12:60:55 AM")

   10:35:51 PM
   GTM>

   This example shows hours, minutes, and seconds in a 12 hour clock with
   an AM/PM indicator.

   Example:


   GTM> WRITE !,$ZDATE(",36524","24-60")

   10-08
   GTM>

   This example shows hours and minutes on a 24 hour  clock.  Notice  that
   the first argument must provide the time in the second comma delimiter
   piece to match $HOROLOG format.

   Example:


   GTM>WRITE $ZDATEFORM

   0
   GTM>WRITE $ZDATE($H)

   11/15/02
   GTM>SET $ZDATEFORM=1

   GTM>WRITE $ZDATE($H)

   11/15/2002
   GTM>WRITE $ZDATE($H,"MM/DD/YY")

   11/15/02
   This example converts the output format  for  years  from  the  default
   ("YY") format to the four digit format  ("YYYY")  using  the  Intrinsic
   Special Variable $ZDATEFORM.

2 $ZJOBEXAM()
   $ZJOBEXAM()

   The $ZJOBEXAM function 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_"_"_<cntr>

   Set filespec=$ZPARSE(expr1,"",deffn)

   The $ZJOBEXAM()does not trigger error processing except when there is a
   problem storing its return value,  so  no  error  is  reported  to  the
   process until after any dump is complete. In the  event  of  any  error
   encountered during the $ZJOBEXAM(), GT.M sends an  appropriate  message
   to operator log facility and returns control to the caller.  Note  that
   this special error handling applies only to the $ZJOBEXAM(), and is not
   a property of the $ZINTERRUPT interrupt handler, which uses $ZJOBEXAM()
   by default.

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

3 Ex_of_$ZJOBEXAM()
   Examples of $ZJOBEXAM()

   Example:


   GTM>Set x=$ZJOBEXAM()


   GTM>Write x

   /home/testarea/demo/GTM_JOBEXAM.ZSHOW_DMP_28760_1

   GTM>Set x=$ZJOBEXAM("test.file")


   GTM>write x

   /home/testarea/demo/test.file

   GTM>


   Shows default file name and type of the files  created  containing  the
   zshow dump information and the difference when the name  and  type  are
   specified.

2 $ZMessage()
   $ZMessage()

   The $ZMESSAGE function returns  a  message  string  associated  with  a
   specified status code.

   The format for the $ZMESSAGE function is:


   $ZM[ESSAGE](intexpr)

   o    The  integer  expression  specifies  the  status  code  for  which
        $ZMESSAGE() returns error message text.

   $ZMESSAGE() provides a tool for examining the message associated with a
   particular message code as reported in $ZSTATUS.

   The $ZSTATUS Intrinsic Special Variable holds the message code and the
   message of the last non-Direct Mode GT.M error. For more information on
   $ZSTATUS, refer to the "Intrinsic Special Variables"  chapter  in  GT.M
   Programmer's Guide.

3 Ex_of_$ZMessage()
   Examples of $ZMESSAGE()

   Example:


   GTM> WRITE $ZMESSAGE(36)

   Interrupted system call

   GTM>

   This uses $ZMESSAGE() to display the message  string  corresponding  to
   code 36.

2 $ZPARSE()
   $ZPARSE()

   The $ZPARSE function 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 function is:


   $ZPARSE(expr1[,expr2[,expr3[,expr4[,expr5]]]])

   o    The first expression specifies the file name; if the file  name  is
        not valid, $ZPARSE() returns  a  null  string;  if  the  file  name
        contains a wildcard (* and/or ?), $ZPARSE()  returns  a  file  name
        containing the wildcard(s).

   o    The optional second expression specifies the field of the pathname
        that $ZPARSE() returns;  if  this  argument  is  missing  or  null,
        $ZPARSE() returns a full pathname constructed using default values
        in place of any fields missing for directory, file and extension.

   o    The optional third and fourth expressions specify default values to
        use during file name expansion for missing fields (directory, name,
        or extension), if any, in the original file  name.  For  any  field
        missing in the original file name  specified  in  expr1,  $ZPARSE()
        will attempt to substitute the corresponding field from  expr3;  if
        that field is not present in expr3, $ZPARSE() will attempt  to  use
        the corresponding field from expr4.

   o    If the file extension is missing from all three  of  expr1,  expr3,
        and  expr4,  $ZPARSE()  will  return  a  null  string  for  the
        corresponding field. If the file, or directory is missing from all
        three of expr1, expr3, and expr4,  $ZPARSE()  will  substitute  the
        information from your current working directory.

   o    The optional fifth expression specifies the mode or type  of  parse
        that $ZPARSE() performs.

   $ZPARSE()  provides  a  tool  for  verifying  that  a  file  name  is
   syntactically correct, for examining specific fields of  a  file  name,
   and for filling in missing pieces in a partial specification based on a
   hierarchy of defaults. For information about determining whether a file
   exists, refer to the description of $ZSEARCH().

   $ZPARSE() arguments, after the first, are optional. If you use no other
   arguments, a  single  argument  is  sufficient.  However,  if  you  use
   selected arguments $ZPARSE() requires that null strings ("") be filled
   in for the unspecified arguments.

   The acceptable keywords for the second argument are:

        "DIRECTORY" Directory name
        "NAME" File name (excluding file extension)
        "TYPE" File typeextension
   The keywords may be entered in either upper or  lower  case.  Variables
   that evaluate to these  strings  and  indirection  are  acceptable  for
   argument two. When the keywords themselves appear as  string  literals,
   they must be enclosed in quotation marks (" ").

   The following guidelines must be  followed  in  constructing  arguments
   one, three and four:

   o    Directory specifications must end in a slash;  anything  after  the
        final slash in the directory specification is assumed to be part of
        the name specification.

   o    A file name with an extension must include at least  one  character
        to the left of the period (.). Thus, "/user/.login" refers  to  the
        file named ".login", while "/usr/taxes.c" refers to  a  file  named
        "taxes" with the extension "c". If a file name includes  more  than
        one period, the extension includes all letters to the right of the
        rightmost period.

   The keywords for the fifth argument $ZPARSE() are:

        NULL ("") Returns a full file-specification or device
        "SYNTAX_ONLY"
        Disables checking for the existence of the directory or device.
3 Ex_of_$ZPARSE()
   Examples of $ZPARSE()

   Example:


   GTM> WRITE $ZPARSE("test","","/usr/work/","dust.lis")

   /usr/work/test.lis

   GTM>

   This uses $ZPARSE() to  demonstrate  defaulting  using  the  third  and
   fourth arguments. The result gets the directory field  from  the  third
   expression, the name from the first expression, and the type  from  the
   fourth expression.

   Example:


   GTM>r!,"file :",f w ?20,$zparse(f,"directory")

   file: test.list /usr/work/

   GTM>

   This uses $ZPARSE() to display the directory for the file name entered
   as input at the prompt file:  ,  in  this  case,  the  current  working
   directory.

   Example:


   $ cd /usr/work/me

   $ $gtm

   GTM>W $ZPARSE("test","","x.list","y.c")/usr/work/me/test.lis

   GTM>W $ZPARSE("test","","/usr/work/","/dev/y.c")/usr/work/test.c

   GTM>W $ZPARSE("test","","/usr/work","/dev/y.c")/usr/test.c

   GTM>

   This example illustratest the use of the third and fourth arguments to
   $ZPARSE(). In the first statement, the first argument has no directory
   or extension field, so $ZPARSE() substitutes the extension  field  from
   the third  argument.  Since  neither  the  third  nor  fourth  argument
   specifies a directory, and because the fourth argument does not contain
   any fields that are not present  in  the  third  argument,  the  fourth
   argument is not used.

   In the second statement, the  first  argument  to  $ZPARSE()  is  again
   missing both the directory and extension. In this  instance,  $ZPARSE()
   uses the directory specified in the third argument and, becuase neither
   the first nor third argument specifies a file extension, $ZPARSE() uses
   the file extension from the fourth argument.

   In the third  statement,  because  "/usr/work"  does  not  end  with  a
   backward slash (/), $ZPARSE() interprets the substring "work" as a file
   name. Then, $ZPARSE() substitutes "/usr/" for the directory missing in
   the first argument and substitutes ".c" from the  fourth  argument  for
   the extension missing from both the first and third arguments.

   Example:


   $ cd /usr/work/met

   $ $gtm_dist/mumps -direct

   GTM>f i="DIRECTORY","NAME","TYPE",""d

   . W $zparse("test.m",i),!
   /usr/work/me/

   test

   .m
   /usr/work/me/test.m

   GTM>

   This example illustrates the output produced for each of  the  possible
   values for the second argument.

2 $ZPrevious()
   $ZPrevious()

   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 function is:


   $ZP[REVIOUS](glvn)

   o    The subscripted or unsubscripted  global  or  local  variable  name
        specifies the node prior to which $ZPREVIOUS()  searches  backwards
        for a defined node with data  and/or  descendants.  The  number  of
        subscripts contained in the argument implicitly defines  the  array
        level.

   o    If $ZPREVIOUS() finds no node at the  specified  level  before  the
        specified global or local variable, it returns a null string.

   o    If the last subscript in the subscripted global or  local  variable
        name is null, $ZPREVIOUS() returns the last node at  the  specified
        level.

   $ZPREVIOUS() is equivalent to $ORDER() with a second argument of -1.

2 $ZQGBLMOD()
   $ZQGBLMOD()

   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
   dual-site consistency.

   The format for the $ZQGBLMOD function is:


   $ZQGBLMOD(gvn)

   o    The subscripted  or  non-subscripted  global  variable  name  (gvn)
        specifies the target node.

   o    A return value of zero (0) means the value of the  global  variable
        has not changed since the last synchronization of the  primary  and
        secondary.

   o    A return value of one (1) means the value of  the  global  variable
        may have changed since the last synchronization of the primary and
        secondary.

   $ZQGBLMOD function produces an error if you submit an argument that is
   not a global variable name.

   Internally, $ZQGBLMOD (gvn) compares the GT.M transaction number in the
   database block in which the global variable name  is  stored  with  the
   value in the resync_tn field stored in the database file header.

   For example, if x is the transaction number  of  the  level-0  database
   block in which gvn resides, and y is the value of resync_tn  of  region
   reg containing gvn, then the following is true:

   o    If x £ y, no transaction modified the level-0 database block z in
        which gvn resides since the  databases  at  primary  and  secondary
        became synchronized with each other.  $ZQGBLMOD()  returns  a  zero
        (0).

   o    If x > y, some transaction modified z, but not necessarily
❇❖■
, after the primary and secondary system databases synchronized  with  each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each

   If a transaction is a lost transaction that has been rolled back and it
   is determined that for  all  the  M  globals  set  and  killed  in  the
   transaction $ZQGBLMOD() is zero (0), it is probably safe to  apply  the
   updates automatically. However, this determination of safety  can  only
   be made by the application designer and not by GT.M. If the $ZQGBLMOD()
   is one (1) for any set or kill in the transaction, it is  not  safe  to
   apply the update.

        The  test  of  $ZQGBLMOD()  and  applying  the  updates  must  be
        encapsulated inside a GT.M transaction.

   Another approach to handling lost transactions would be to store in the
   database the initial message sent by a client, as well as  the  outcome
   and the response, and to reprocess the  message  with  normal  business
   logic. If the outcome is  the  same,  the  transaction  can  be  safely
   applied.

        If  restartable  batch  operations  are  implemented,  lost  batch
        transactions can be ignored since a subsequent batch  restart  will
        process them correctly.

2 $ZSEARCH()
   $ZSEARCH()

   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 function is:


   $ZSEARCH(expr[,intexpr])

   o    The expression contains a file name, with or without wildcards, for
        which $ZSEARCH() attempts to  locate  a  matching  file.  Repeating
        $ZSEARCH with the same filename uses the same context and return a
        sequence of matching files when they exist; when  the  sequence  is
        exhausted, $ZSEARCH() returns an empty string (""). Any  change  to
        the file name starts a new context.

   o    $ZSEARCH() uses the  process  current  working  directory,  if  the
        expression does not specify a directory.

   o    The optional integer expression specifies a "stream" number from 0
        to 255 for each search; streams provide a means of having up to 256
        $ZSEARCH() contexts simultaneously in progress.

   o    If a $ZSEARCH() stream has never been used  or  if  the  expression
        differs from the argument to the last $ZSEARCH() of the stream, the
        function resets the context and returns the first pathname matching
        the expression; otherwise, it returns the  next  matching  file  in
        collating sequence; if the last prior  pathname  returned  for  the
        same expression and same stream  was  the  last  one  matching  the
        argument, $ZSEARCH() returns a null string.

   $ZSEARCH() provides a tool  for  verifying  that  a  file  exists.  For
   information to help determine the validity of a file name, refer to the
   section on $ZPARSE()

3 Ex_of_$ZSEARCH()
   Examples of $ZSEARCH()

   Example:


   GTM> WRITE $ZSEARCH("data.dat")

   /usr/staff/ccc/data.dat

   GTM>

   This uses $ZSEARCH() to display the full file path name  of  "data.dat"
   in the process current default directory.

   Example:


   GTM>SET x=$ZSEARCH("*.M")

   GTM>FOR S x=$ZSEARCH("*.M") Q:x="" W !,$ZPARSE(x,"NAME")

   This FOR loop uses $ZSEARCH() and $ZPARSE() to display  M  source  file
   names in the process current working  directory.  To  ensure  that  the
   search starts at the beginning, the example resets the context by first
   searching with a different argument.

2 $ZTRNLNM()
   $ZTRNLNM()

   The $ZTRNLNM function gives  the  value  of  an  environment  variable.
   $ZTRNLNM() does iterative translation in cases  where  one  environment
   variable is set to the name of another environment variable.

   The format for the $ZTRNLNM function is:


   $ZTRNLNM(expr)

   The expression specifies the target environment variable.

3 Ex_of_$ZTRNLNM()
   Examples of ZTRNLNM()

   Example:


   GTM> write $ztrnlnm("gtm_dist")

   /usr/dev/bin

   GTM>

   This uses $ZTRNLNM() to display the translation value for gtm_dist.

1 Intr_Spe_Vars
   Intrinsic Special Variables

   M Intrinsic Special Variables start with a single dollar sign ($). GT.M
   provides such variables for program examination.  In  some  cases,  the
   Intrinsic Special Variables may be set to modify the corresponding part
   of the environment.

        None of the Intrinsic Special Variables can be KILLed.  SETting  or
        NEWing is generally not allowed, but is specifically noted  in  the
        descriptions of those that do.

2 $Device
   $Device

   $D[EVICE] reflects the status of the current device. If the  status  of
   the device does not reflect any error-condition, the value of $DEVICE,
   when interpreted as a truth-value is 0 (FALSE). If the  status  of  the
   device  reflect  any  error-condition,  the  value  of  $DEVICE,  when
   interpreted as a truth-value is 1 (TRUE).

        The initial value of $DEVICE is implementation dependant. However,
        if the initial value of $IO is the empty string, then  the  initial
        value of $DEVICE is also empty string.

   $DEVICE gives status code and meaning, in one access:

   Example:

   1,Connection reset by peer
   The above message is displayed on  the  server  side  when  the  socket
   device is closed on the client side.

2 $ECode
   $ECode

   $EC[ODE] contains a list of error codes for "active" errors -the error
   conditions which are not yet resolved. If there are no  active  errors,
   $ECODE contains the empty string. Whenever an error occurs, a code for
   that error is appended to the value of $ECODE in such a  way  that  the
   value of $ECODE always starts and ends with a comma.

   The value of $ECODE can be SET, and when it is set to a non-NULL value,
   error processing starts.

   List of codes for $ECODE start with comma seperated by commas.  A  code
   starts with "M", "U", or "Z", with rest numeric. "M" codes are assigned
   by MDC (MUMPS Development Committee), "U" by application (programmers),
   and "Z" codes by MUMPS implementors (in this case GT.M).

   An error always has a GT.M specified code and many errors also have an
   ANSI Standard code. The complete list of standardized error  codes  can
   be referenced from  GT.M  Message  and  Recovery  Procedures  Reference
   Manual version 4.3 and onwards.


   IF $ECODE[",M61," WRITE "Undefined local variable"

        The leftmost character of the value of $ECODE is  always  a  comma.
        This means that every error  code  that  is  stored  in  $ECODE  is
        surrounded by commas. If $ECODE was  to  contains  the  error  code
        without the commas (that is, "M61"), the variable would  check  for
        subset "M6" as well. Thus, it is recommended that you  include  the
        commas in the value to check. For  example;  check  whether  $ECODE
        contains ",M61,".

   $ECODE can be SET but not NEW'd. When $ECODE is set to the empty string
   (" "), error handling becomes "inactive" and therefore  QUIT  does  not
   trigger additional error handling.

   When $ECODE is not set to the empty string, M error handling is active,
   which also affects behaviour in some aspects of $STACK.

2 $EStack
   $EStack

   $ES[TACK] contains an integer count of the number of M virtual machine
   stack levels that have been activated and not removed  since  the  last
   time $ESTACK was NEW'd.

   A NEW $ESTACK saves the value of current  $ESTACK  and  then  sets  its
   value to zero (0). If  $ESTACK  has  not  been  NEW'd  in  the  current
   execution path, $ESTACK=$STACK.


   SET $ETRAP="QUIT:$ESTACK GOTO LABEL^ROUTINE"

   $ESTACK maybe used as  a  flag  to  indicate  error  traps  invoked  in
   particular stack levels needed to  perform  some  different  action(s).
   $ESTACK can be most useful in  setting  up  a  layered  error  trapping
   mechanism.

        GT.M does not permit $ESTACK to be  SET,  however  $ESTACK  can  be
        NEWed.

2 $ETrap
   $ETrap

   $ET[RAP] contains a string value that GT.M invokes when an error occurs
   during routine execution. When a process is initiated, but  before  any
   commands are processed, the value of $ETRAP is empty string.

   The value of this variable is the M[UMPS] code that gets executed when
   an error occurs.


   SET $ETRAP="QUIT:$ESTACK GOTO LABEL^ROUTINE"

   The value of $ETRAP is changed with the SET command. Changing the value
   of $ETRAP with the SET command initiates a new trap; it does  not  save
   the old trap.

   For more examples of the  use  of  special  variable  $ETRAP,  see  the
   function $STACK().

2 $Horolog
   $Horolog

   $H[OROLOG] contains a string value specifying the number of days since
   "31 December, 1840," and the number of seconds since  midnight  of  the
   current day, separated by a comma (,).

   At midnight, the piece of the string following the comma resets to zero
   (0) and the piece preceding the comma increments by one (1). GT.M does
   not permit the SET command to modify $HOROLOG.

   Example:


   GTM> WRITE $HOROLOG

   Produces the result 58883,55555 at 3:25:55 pm on 20 March, 2002.

   For further information on formatting $HOROLOG for  external  use,  see
   the section on $ZDATE().

2 $Io
   $IO

   $I[O] contains the name of the current device specified by the last USE
   command. The M standard does not permit the SET command to modify $IO.
   USE 0 produces the  same  $IO  as  USE  $P[RINCIPAL],  but  $P  is  the
   preferred construct.

2 $Job
   $Job

   $J[OB] contains the current process identifier.

   $JOB is guaranteed  to  be  unique  for  every  concurrently  operating
   process on a system. However, operating systems reuse PIDs  over  time.
   GT.M does not permit the SET command to modify $JOB.

   Example:


   LOOP0 FOR SET itm=$O(^tmp($J,itm)) Q:itm="" DO LOOP1

   This uses $J as the first subscript in a  temporary  global  to  insure
   that every process uses separate data space in the global ^tmp.

2 $Key
   $Key

   $K[EY] contains the string that terminated the most recent READ command
   from the current device  (including  any  introducing  and  terminating
   characters). If no READ command s issued to the current device or if no
   terminator is used, the value of $KEY is an empty string. However, when
   input is terminated by typing a function key,  the  value  of  $KEY  is
   equal to the string of characters that is transmitted by that function
   key.

   The effect of a READ *glvn on $KEY is unspecified.

   If a Character Set Profile input-transform is in effect, then  this  is
   also applied to the value stored in $KEY.

2 $Principal
   $Principal

   $P[RINCIPAL] contains the absolute pathname of the  principal  (initial
   $IO) device. $PRINCIPAL is an MDC Type A enhancement to standard M.

   Input and output for a process may come from separate devices, namely,
   the standard input and output. However, the M I/O model allows only one
   device to be USEd (or active) at a time. When and  image  starts,  GT.M
   implicitly OPENs the standard input and standard output  device(s)  and
   assigns the device(s) to $PRINCIPAL. For USE  deviceparameters,  it  is
   the standard input that determines the device type.

   For an image invoked interactively, $PRINCIPAL is the user's terminal.
   For an image invoked from a  terminal  by  means  of  a  shell  script,
   $PRINCIPAL is the shell script's standard input (usually the terminal)
   and standard output (also usually the terminal) for output, unless the
   shell redirects the input or output.

   GT.M provides a mechanism for the user to create a name for $PRINCIPAL
   in  the  shell  before  invoking  GT.M.  The  environment  variable
   gtm_principal, if defined becomes a synonym for the actual  device  and
   the value for $PRINCIPAL. $IO holds the same value as $PRINCIPAL. $ZIO
   in this case, holds the fully expanded name of the actual device. Refer
   to $ZIO section in this chapter for an example of its usage.

   GT.M ignores a CLOSE specifying the principal  device.  GT.M  does  not
   permit the SET command to modify $PRINCIPAL.

2 $Quit
   $Quit

   $Q[UIT] indicates whether the current block of code was  called  as  an
   extrinsic function or as a subroutine.

   If $Q[UIT] contains 1 (when the current process-stack frame is invoked
   by  an  extrinsic  function),  the  QUIT  would  therefore  require  an
   argument.

        When a process is initiated, but before any commands are processed,
        the value of $Q[UIT] is zero (0).

   This special variable is mainly used in error-trapping conditions. Its
   value tells whether the current DO level was  reached  by  means  of  a
   subroutine call (DO xxx) or by a function call (SET variable=$$xxx).

   A typical way of exiting from an error trap is:

   QUIT:$QUIT "" QUIT

        GT.M does not permit $QUIT to be SET or NEWed.

2 $Reference
   $Reference

   $R[EFERENCE] contains the last global reference. Until the first global
   reference is made by an M program, $REFERENCE contains the empty string
   (""). This way it is useful in determining if  the  usage  of  a  naked
   reference is valid.

   A typical way of using this is:


   IF $REFERENCE="" QUIT "<undefined>"

        $R[EFERENCE] being a read-only variable cannot be SET or NEW'd.

2 $STack
   $STack

   $ST[ACK] contains an integer value of zero (0)  or  greater  indicating
   the current level of M execution stack depth.

   When a process is initiated but before any  command  is  executed,  the
   value of $STACK is zero (0).

        The difference between $STACK  and  $ESTACK  is  that  $ESTACK  may
        appear as an argument of the NEW command. NEWing $ESTACK resets its
        value to zero (0), and can be useful to  set  up  a  layered  error
        trapping mechanism.

   The value of $STACK is "absolute" since the start of a  GT.M.  process,
   whereas  the  value  of  $ESTACK  is  "relative"  to  the  most  recent
   "anchoring point".

   For examples on the use of special variable $STACK, refer  to  $STACK()
   in the "Functions" chapter in this manual.

2 $Storage
   $Storage

   $S[TORAGE] contains an integer value  specifying  the  number  of  free
   bytes of address space remaining between  the  memory  currently  under
   management by the process and the theoretical maximum available to the
   process.

   GT.M uses memory for code (instructions) and data.  If  the  amount  of
   virtual memory available to the process exceeds 2,147,483,647 bytes, it
   is reported as 2,147,483,647 bytes.

   Instruction space  starts  out  with  the  original  executable  image.
   However, GT.M may  expand  instruction  space  by  ZLINKing  additional
   routines.

   Data space starts out with stack space that  never  expands,  and  pool
   space which may expand.  Operations  such  as  opening  a  database  or
   creating a local variable may cause an expansion in  pool  space.  GT.M
   expands pool space in fairly large increments. Therefore, SETs of local
   variables may not affect $STORAGE at all or  may  cause  an  apparently
   disproportionate drop in its value.

   Once a GT.M process adds either instruction or  data  space,  it  never
   releases that space.  However,  GT.M  does  reuse  process  space  made
   available by actions such as KILLs of  local  variables.  $STORAGE  can
   neither be SET or NEWed.

2 $SYstem
   $SYstem

   $SY[STEM] contains a string that identifies the executing  M  instance.
   The value of $SYSTEM is a string that starts with a unique numeric code
   that identifies the manufacturer. Codes are assigned by the MDC (MUMPS
   Development Committee).

   $SYSTEM in GT.M starts with "47" followed by a comma and the evaluation
   of the environment variable gtm_sysid. If the name has  no  evaluation,
   the value after the comma is gtm_sysid.

2 $Test
   $Test

   $T[EST] contains a truth value specifying the evaluation of the last IF
   argument or the result of the last operation with timeout. If the last
   timed operation timed out, $TEST  contains  FALSE  (0);  otherwise,  it
   contains TRUE (1).

   $TEST  serves  as  the  implicit  argument  for  ELSE  commands  and
   argumentless IF commands.

   M  stacks  $TEST  when  invoking  an  extrinsic  and  performing  an
   argumentless DO. After these operations complete with  an  implicit  or
   explicit QUIT, M restores the  corresponding  stacked  value.  Because,
   with these two exceptions, $TEST  reflects  the  last  IF  argument  or
   timeout result on a process wide basis. Use  $TEST  only  in  immediate
   proximity to the operation that last updated it.

   M routines cannot modify $TEST with the SET command.

   Example:


   IF x=+x DO ^WORK

   ELSE SET x=0

   The ELSE statement causes M to use the  value  of  $TEST  to  determine
   whether to execute the rest of the line. Because the  code  in  routine
   WORK may use IFs and timeouts, this use of $TEST is not recommended.

   Example:


   SET MYFLG=x=+x

   IF MYFLG DO ^WORK

   IF 'MYFLG SET x=0

   This example introduces a local variable flag to address  the  problems
   of the prior example. Note that its behavior results  in  the  opposite
   $TEST value from the prior example.

   Example:


   IF x=+x DO ^WORK IF 1

   ELSE SET x=0

   This example uses the IF 1 to ensure that the ELSE works counter to the
   IF.

2 $TLevel
   $TLevel

   $TL[EVEL] contains a count  of  executed  TSTARTs  that  are  currently
   unmatched by TCOMMITs. $TLEVEL is zero (0) when there is no TRANSACTION
   in progress. When $TLEVEL is greater than one (>1), it  indicates  that
   there are nested sub-transactions  in  progress.  Sub-transactions  are
   always subject to the completion of the main TRANSACTION and cannot be
   independently acted upon by COMMIT, ROLLBACK, or RESTART.

   $TLEVEL can be used to determine whether  there  is  a  TRANSACTION  in
   progress and to determine the level of nesting of sub-transactions.

   M routines cannot modify $TLEVEL with SET.

   Example:


   IF $TLEVEL TROLLBACK

   This example performs a TROLLBACK if a transaction is  in  progress.  A
   statement like this should  appear  in  any  error  handler  used  with
   transaction processing. For more information on transaction processing
   refer  to  the  "General  Language  Features  of  M"  chapter  in  GT.M
   Programmer's Guide.

2 $TRestart
   $TRestart

   $TR[ESTART] contains a  count  of  the  number  of  times  the  current
   TRANSACTION has been RESTARTed. A RESTART can be explicit (specified in
   M as a TRESTART) or implicit (initiated by GT.M as part of its internal
   concurrency  control  mechanism).  When  there  is  no  TRANSACTION  in
   progress, $TRESTART is zero (0).

   $TRESTART can be used  by  the  application  to  limit  the  number  of
   RESTARTs, or to cause a routine to perform different actions  during  a
   RESTART than during the initial execution.

        GT.M does not permit the SET command to modify $TRESTART.

   Example:


   TRANS TSTART ():SERIAL

   IF $TRESTART>2 WRITE !;"Access Conflict" QUIT

   This example terminates the sub-routine with a message if the number of
   RESTARTs exceeds 2.

   For more information on transaction processing, refer to the section on
   that topic in the "General Language Features  of  M"  chapter  in  GT.M
   Programmer's Guide.

2 $X
   $X

   $X contains an integer value ranging from 0 to 65,535,  specifying  the
   horizontal position of a virtual cursor in the current  output  record.
   $X=0 represents the left-most position of a record or row.

   Every OPEN device has a $X. However, M only accesses $X of the current
   device.  Therefore,  exercise  care  in  sequencing  USE  commands  and
   references to $X.

   Generally, GT.M increments $X for every character written to  and  read
   from the current device. M format control characters, write filtering,
   and the device WIDTH also have an effect on $X.

   $X never equals or exceeds the value of the device WIDTH.  Whenever  it
   reaches the value equal to the device WIDTH, it gets reset to zero (0).

   GT.M follows the MDC Type A recommendation and permits an M routine to
   SET $X. However, SET $X does not automatically issue device commands or
   escape sequences to reposition the physical cursor.

   For more information on $X,  refer  to  the  "Input/Output  Processing"
   chapter in GT.M Programmer's Guide.

2 $Y
   $Y

   $Y contains an integer value ranging from 0 to  65,535  specifying  the
   vertical position of a virtual cursor in the current output page. $Y=0
   represents the top row or line.

   Every OPEN device has a $Y. However, M only accesses $Y of the current
   device.  Therefore,  exercise  care  in  sequencing  USE  commands  and
   references to $Y.

   When GT.M  finishes  the  logical  record  in  progress,  it  generally
   increments $Y. GT.M recognizes the end of  a  logical  record  when  it
   processes certain M format  control  characters,  or  when  the  record
   reaches its maximum size, as determined by the device  WIDTH,  and  the
   device is set to WRAP. The definition of "logical record"  varies  from
   device to device. For an exact definition, see  the  sections  on  each
   device type. Write filtering and the device LENGTH also have an effect
   on $Y.

   $Y never equals or exceeds the value of the device LENGTH. Whenever it
   reaches the value equal to the device LENGTH, it gets reset to zero (0)

   GT.M permits an  M  routine  to  SET  $Y.  However,  SET  $Y  does  not
   automatically issue device commands or escape sequences  to  reposition
   the physical cursor.

   For more information on $Y,  refer  to  the  "Input/Output  Processing"
   chapter in GT.M Programmer's Guide.

2 $ZA
   $ZA

   $ZA contains a status determined by the last read on  the  device.  The
   value is a decimal integer with a meaning determined by the  device  as
   follows:

   For Terminal I/O:

        0 Indicating normal termination of a read operation
        1 Indicating a parity error
        2 Indicating that the terminator sequence was too long
        9 Indicating a default for all other errors
   For Sequential Disk Files I/O:

        0 Indicating normal termination of a read operation
        9 Indicating a failure of a read operation
   For Fifos I/O:

   Decimal representing $JOB (identifier) of the process  that  wrote  the
   last message the current process read
   $ZA refers to the status of the  current  device.  Therefore,  exercise
   care in sequencing USE commands and references to $ZA.

   GT.M does not permit the SET command to modify $ZA.

   For more information on $ZA, refer  to  the  "Input/Output  Processing"
   chapter in GT.M Programmer's Guide.

2 $ZB
   $ZB

   $ZB contains a string specifying the  input  terminator  for  the  last
   terminal READ. $ZB contains null and  is  not  maintained  for  devices
   other than terminals. $ZB may contain any legal input terminator, such
   as <CR> (ASCII 13) or an escape sequence  starting  with  <ESC>  (ASCII
   27), from zero (0) to 15 bytes in length. $ZB  contains  null  for  any
   READ terminated by a timeout or any  fixed-length  READ  terminated  by
   input reaching the maximum length.

   $ZB contains the actual character string, not  a  sequence  of  numeric
   ASCII codes.

   Example:


   SET zb=$ZB FOR i=1:1:$L(zb) WRITE !,i,?5,$A(zb,i)

   This displays the series of ASCII codes for the characters in $ZB.

   $ZB  refers  to  the  last  READ  terminator  of  the  current  device.
   Therefore, exercise care in sequencing USE commands and  references  to
   $ZB.

   GT.M does not permit the SET command to modify $ZB.

   For more information on $ZB, refer  to  the  "Input/Output  Processing"
   chapter in GT.M Programmer's Guide.

2 $ZCMdline
   $ZCMdline

   $ZCM[DLINE] contains a string value specifying the "excess" portion of
   the command line that invoked the GT.M process. By  "excess"  is  meant
   the portion of the command line that is left after GT.M has done all of
   its command line processing. For example, a command line mumps -direct
   extra1 extra2 causes GT.M  to  process  the  command  line  upto  mumps
   -direct and place the "excess" of the command  line,  that  is  "extra1
   extra2" in $ZCMDLINE. $ZCMDLINE gives the M routine access to the shell
   command line input.

   Note  that  the  actual  user  input  command  line  might  have  been
   transformed by the shell (for example, removing one  level  of  quotes,
   filename, and wildcard  substituion,  and  so  on.),  and  it  is  this
   transformed command line that GT.M processes.

   M routines cannot modify $ZCMDLINE.

   Example:


   $ cat > test.m

   write " $ZCMDLINE=",$ZCMDLINE,!

   quit

   $ mumps -run test OTHER information

   $ZCMDLINE=OTHER information

   $

   This creates the program test.m, which writes the value  of  $ZCMDLINE.
   Note how the two spaces specified in OTHER information in  the  command
   line gets transformed  to  just  one  space  in  OTHER  information  in
   $ZCMDLINE due to the shell's pre-processing.

2 $ZCOmpile
   $ZCOmpile

   $ZCO[MPILE] contains a string value composed of one or more qualifiers
   that control the GT.M compiler. Explicit  ZLINKs  and  auto-ZLINKs  use
   these qualifiers as defaults for any compilations that they perform.

   $ZCOMPILE is a read-write ISV, that is, it can appear on the left side
   of the equal sign (=) in the argument to the SET command.  A  $ZCOMPILE
   value has the form of a list of M command qualifiers each separated by
   a space ( ).

   When the environment variable gtmcompile is defined,  GT.M  initializes
   $ZCOMPILE to the translation of gtmcompile. Otherwise GT.M initializes
   $ZCOMPILE to null. Changes to the value  of  $ZCOMPILE  during  a  GT.M
   invocation only last for the current invocation and do not  change  the
   value of the environment variable gtmcompile.

   When $ZCOMPILE is null, GT.M uses  the  default  M  command  qualifiers
   -IGNORE, -LABEL=LOWER, -NOLIST, and  -OBJECT.  Refer  to  the  "Program
   Development Cycle" chapter in this manual for detailed descriptions of
   the M command qualifiers.

   Example:


   $ setenv gtmcompile "-LIST -LENGTH=56 -SPACE=2"

   $ gtm

   GTM>WRITE $ZCOMPILE

   -LIST -LENGTH=56 -SPACE=2

   GTM>SET $ZCOMPILE="-LIST -NOIGNORE"

   GTM>WRITE $ZCOMPILE

   -LIST -NOIGNORE

   GTM>ZLINK "A.m"

   GTM>HALT

   $ echo $gtmcompile

   -LIST -LENGTH=56 -SPACE=2

   This example  uses  the  environment  variable  gtmcompile  to  set  up
   $ZCOMPILE. Then it modifies $ZCOMPILE with the SET command.  The  ZLINK
   argument specifies a file with a .m extension (type),  which  forces  a
   compile. The compile produces a listing for routine A.m  and  does  not
   produce an object module if A.m contains compilation errors. After GT.M
   terminates, the shell command echo $gtmcompile  demonstrates  that  the
   SET command did not change the environment variable.

2 $ZCstatus
   $ZCstatus

   $ZC[STATUS] holds the value of the status code for the last compilation
   performed by a ZCOMPILE command.

   GT.M does not permit the SET command to modify $ZSTATUS.

2 $ZDAteform
   $ZDAteform

   $ZDA[TEFORM] contains an integer  value,  specifying  the  output  year
   format of $ZDATE(). $ZDATEFORM can be modified using the  SET  command.
   GT.M initializes $ZDATEFORM  to  the  translation  of  the  environment
   variable  gtm_zdate_form.  If  gtm_zdate_form  is  not  defined,  GT.M
   initializes $ZDATEFORM to zero (0).

   Refer  to  "Functions"  and  "M  utility  Routines"  chapter  in  GT.M
   Programmer's Guide for more details.

   Example:


   GTM>WRITE $ZDATEFROM

   0
   GTM>WRITE $ZDATE($H)

   11/15/02
   GTM>SET $ZDATEFORM=1

   GTM>WRITE $ZDATE($H)

   11/15/2002
2 $ZDirectory
   $ZDirectory

   $ZD[IRECTORY] contains the string value of the full path of the current
   directory. Initially $ZDIRECTORY contains the default/current directory
   from which the GT.M image/process was activated.

   If the current directory does not exist at the  time  of  GT.M  process
   activation, GT.M errors out.

   Example:


   GTM>WRITE $ZDIR

   /usr/tmp

   GTM>SET $ZDIR=".."

   GTM>WRITE $ZDIR

   /usr

   This example displays the current working directory and  changes  $ZDIR
   to the parent directory.

   $ZDIRECTORY is a read-write Intrinsic Special Variable, that is, it can
   appear on the left side of the equal sign (=) in the argument to a SET
   command. If an attempt is made to set  $ZDIRECTORY  to  a  non-existent
   directory specification, GT.M issues an error and keeps  the  value  of
   $ZDIRECTORY unchanged.

   At image exit, GT.M restores the current  directory  to  the  directory
   that was the current directory when  GT.M  was  invoked  even  if  that
   directory does not exist.

2 $ZEDit
   $ZEDit

   $ZED[IT] holds the value of the status code for the last  edit  session
   invoked by a ZEDIT command.

   GT.M does not permit the SET or NEW command to modify $ZEDIT.

2 $ZEOf
   $ZEOf

   $ZEO[F] contains a truth-valued expression indicating whether the last
   READ operation reached the end-of-file. $ZEOF equals TRUE  (1)  at  EOF
   and FALSE (0) at other positions.

   GT.M does not maintain $ZEOF for terminal devices.

   $ZEOF  refers  to  the  end-of-file  status  of  the  current  device.
   Therefore, exercise care in sequencing USE commands and  references  to
   $ZEOF.

   GT.M does not permit the SET or NEW command to modify $ZEOF.

   For more information on $ZEOF, refer to the  "Input/Output  Processing"
   chapter.

2 $ZError
   $ZError

   $ZE[RROR] is  supposed  to  hold  the  application-specific  error-code
   corresponding to the GT.M error-code stored in  $ECODE/$ZSTATUS  (refer
   to their description in this chapter).

   $ZERROR contains a default value of "Unprocessed $ZERROR, see $ZSTATUS"
   at process startup.

   $ZERROR can be SET but not NEWed.

   The mapping of a GT.M error-code to the application-specific error-code
   is  achieved  as  follows.  Whenever  GT.M  encounters  an  error,
   $ECODE/$ZSTATUS gets set first. It then invokes the code that $ZYERROR
   (see description later in this chapter) points to if it is not null. It
   is intended that the code invoked by $ZYERROR use the value of $ZSTATUS
   to select or construct a value to which it SETs $ZERROR. If an error is
   encountered by the attempt to execute the code specified  in  $ZYERROR,
   GT.M sets $ZERROR to the error status encountered. If $ZYERROR is null,
   GT.M does not change the value of $ZERROR. In all cases, GT.M proceeds
   to return control to the code  specified  by  $ZTRAP/$ETRAP  or  device
   EXCEPTION whichever is applicable.

2 $ZGbldir
   $ZGbldir

   $ZG[BLDIR] contains the value of the current Global Directory filename.
   When $ZGBLDIR specifies an invalid or inaccessible  file,  GT.M  cannot
   successfully perform database operations.

   GT.M  initializes  $ZGBLDIR  to  the  translation  of  the  environment
   variable gtmgbldir. If  gtmgbldir  is  not  defined,  GT.M  initializes
   $ZGBLDIR to null. When $ZGBLDIR is null, GT.M constructs  a  file  name
   for the Global Directory using the name  gtmgbldir  and  the  extension
   .gld in the current working directory. A $ZGBLDIR value may include an
   environment variable.

   $ZGBLDIR is a read-write Intrinsic  Special  Variable,  (i.e.,  it  can
   appear on the left side of the equal sign (=) in the  argument  to  the
   SET command). SET $ZGBLDIR="" causes GT.M to  assign  $ZGBLDIR  to  the
   translation of gtmgbldir if that environment variable is defined. If it
   is not defined, then SET $ZGBLDIR="" causes GT.M to assign  the  string
   gtmgbldir to $ZGBLDIR. This syntax specifies the file gtmgbldir.gld in
   the current directory. GT.M permits $ZGBLDIR to be NEW'd.

   SETting $ZGBLDIR also causes GT.M to  attempt  to  open  the  specified
   file. If the file name is invalid or the  file  is  inaccessible,  GT.M
   triggers an error without changing the value of $ZGBLDIR.

   To establish a value for $ZGBLDIR outside of  M,  use  the  appropriate
   shell command to assign a translation to gtmgbldir. Defining gtmgbldir
   provides a convenient way to use the same  Global  Directory  during  a
   session where you repeatedly invoke and leave GT.M.

   Changes to the value of $ZGBLDIR during a GT.M invocation only last for
   the current invocation and do not change the value of gtmgbldir.

   Example:


   $ gtmgbldir=test.gld

   $ export gtmgbldir

   $ gtm

   GTM> WRITE $zgbldir

   /usr/dev/test.gld

   GTM> SET $zgbldir="mumps.gld"

   GTM> WRITE $zgbldir

   mumps.gld

   GTM> HALT

   $ echo $gtmgbldir

   test.gld

   This example defines the environment variable gtmgbldir. Upon entering
   GT.M Direct Mode, $ZGBLDIR has the value supplied by gtmgbldir. The SET
   command changes the value. After the GT.M image  terminates,  the  echo
   command demonstrates that gtmgbldir was  not  modified  by  the  M  SET
   command.

   Example:


   $ ls test.gld

   test.gld not found

   $ gtm

   GTM> WRITE $zgbldir

   /usr/dev/mumps.gld

   GTM> set $zgbldir="test.gld"

   %GTM-E-ZGBLDIRACC, Cannot access global directory

   "/usr/dev/test.gld". Continuing with

   /usr/dev/mumps.gld"

   %SYSTEM-E-ENO2, No such file or directory

   GTM> WRITE $zgbldir

   /usr/dev/mumps.gld

   GTM> halt

   $

   The SET command attempts to change the value of $ZGBLDIR  to  test.gld.
   Because the file does not exist, GT.M reports an  error  and  does  not
   change the value of $ZGBLDIR.

        Attempting to restore an inaccessible initial Global Directory that
        has been NEW'd, can cause an error.

2 $ZINTerrupt
   $ZINTerrupt

   $ZINT[ERRUPT] specifies the code to be XECUTE'd when an interrupt (for
   example, through a MUPIP INTRPT)  is  processed.  While  a  $ZINTERRUPT
   action is in process, any additional interrupt signals  are  discarded.
   When an interrupt handler is invoked, the current values of $REFERENCE
   is saved and restored when the interrupt handler returns.  The  current
   device ($IO) is neither saved nor restored.

   GT.M permits the SET command to modify the value of $ZINTERRUPT.

   If an interrupt handler changes the current IO device (via USE), it is
   the responsibility of the interrupt handler to restore the  current  IO
   device before returning. There are sufficient legitimate possibilities
   why an interrupt routine would want to change  the  current  IO  device
   (for example; daily log switching),  that  this  part  of  the  process
   context is not saved and restored automatically.

   The initial value for $ZINTERRUPT is taken from  the  UNIX  environment
   variable gtm_zinterrupt if it is specified, otherwise  it  defaults  to
   the following string:

   IF $ZJOBEXAM()

   The IF  statement  executes  the  $ZJOBEXAM  function  but  effectively
   discards the return value.

        If the default value for $ZINTERRUPT is  modified,  no  $ZJOBEXAM()
        will occur unless the  replacement  value  directly  or  indirectly
        invokes that function. In other words, while $ZJOBEXAM() is part of
        the interrupt handling by default, it is not an  implicit  part  of
        the interrupt handling.

3 Inter_Handl_GTM
   Interrupt Handling in GT.M

   The interrupt handler is executed by GT.M when on a statement boundary
   or on an appropriate boundary in a potentially long running COMMAND (in
   the same place as <CTRL>-C is recognized). If a GT.M process  is  in  a
   long running external call (for example; waiting in  a  message  queue)
   the interrupt handler  cannot  be  driven  immediately.  The  interrupt
   request is recognized and the handler is driven after the external call
   returns to GT.M and an appropriate execution boundary is reached.

   Since  sending  an  interrupt  signal  requires  the  sender  to  have
   appropriate permissions from UNIX, the use of  the  interrupt  facility
   itself does not present any inherent security  exposures.  Nonetheless,
   because the dump files created by the default action contain the values
   of every local variable in the context  at  the  time  they  are  made,
   inappropriate access to the dump  files  would  constitute  a  security
   exposure. Make sure the design  and  implementation  of  any  interrupt
   logic includes careful consideration to security issues.

   If an error occurs while compiling the  $ZINTERRUPT  code,  the  action
   taken depends on the process  state  at  the  time  the  interrupt  was
   received and the error handler is not invoked  (the  error  handler  is
   invoked if an error occurs while executing the  $ZINTERRUPT  code).  If
   the GT.M process is at a direct mode prompt or is  executing  a  direct
   mode command (for example, a FOR loop), the error message  is  sent  to
   the user console along with the GTM-ERRWZINTR error (refer to the GT.M
   Error and Message Recovery  Manual).  In  addition,  the  GTM-ERRWZINTR
   error is also sent to the operator log facility. IF the process is not
   at a direct mode  prompt  or  executing  a  direct  mode  command,  the
   GTM-ERRWZINTR message and the compiler error message are  sent  to  the
   operator log facility and nothing is displayed on the  user's  console.
   In both cases, the interrupted process resumes execution.

   If an error occurs during execution of the  interrupt  handler's  stack
   frame (before it calls anything),  that  error  is  prefixed  with  the
   GTM-ERRWZINTR error. The  error  handler  then  executes  normal  error
   processing associated with the module that was interrupted.  Any  other
   errors that occur in code called by the interrupt handler  are  handled
   by normal error handling.

        The interrupt handler does not  operate  "outside"  the  current  M
        environment but rather within the environment of the process.

   If a TP transaction is in progress (0<$TLEVEL), updates to globals are
   not safe since a TP restart can be signaled at any time  prior  to  the
   transaction being committed - even after the interrupt handler returns.
   A TP restart reverses all global updates and unwinds the M stack so it
   is as if the interrupt never occurred. The  interrupt  handler  is  not
   redriven as  part  of  a  transaction  restart.  Referencing  (reading)
   globals inside an interrupt handler can  trigger  a  TP  restart  if  a
   transaction is active.  When  programming  interrupt  handling,  either
   discard interrupts when 0<$TLEVEL (forcing the  interrupting  party  to
   try again), or use local variables that are not restored by a TRESTART
   to defer the interrupt action until after the final TCOMMIT.

   Note that it is possible for the interrupt handler to be executed while
   the process executing the M routine is holding the critical section for
   one or more regions. Use of this feature may create temporary hangs or
   pauses while the interrupt handler executes. For the default case where
   the interrupt handler uses $ZJOBEXAM() to  create  a  dump,  the  pause
   duration depends on the number of local variables in the process at the
   time of the dump and on the speed of the disk  being  written  to.  The
   dumps are slower on a network-mounted disk  than  on  a  disk  directly
   connected to the local system. Any  interrupt  driven  code  should  be
   designed to account for this issue.

2 $ZINInterrupt
   $ZINInterrupt

   $ZINI[NTERRUPT] evaluates to 1 (TRUE) when a process is executing code
   initiated by the interrupt mechanism, and otherwise 0 (FALSE).

   GT.M does not permit the SET or NEW commands to modify $ZININTERRUPT.

2 $ZIO
   $ZIO

   $ZIO contains the translated name of the current device, in contrast to
   $IO, which contains the name as specified by the USE command.

   GT.M does not permit the SET or NEW command to modify $ZIO.

   An example where $ZIO contains a value different from  $IO  is  if  the
   environment variable gtm_principal is defined.

   Example:


   $ gtm_principal="foo"

   $ export gtm_principal

   GTM>WRITE $IO

   foo

   GTM>WRITE $ZIO

   /dev/pts/8

   Notice that $ZIO contains the actual terminal  device  name  while  $IO
   contains  the  string  pointed  to  by  the  environment  variable
   gtm_principal.

2 $ZJob
   $ZJob

   $ZJ[OB] holds the pid of the process created by the  last  JOB  command
   performed by the current process.

   GT.M initializes $ZJOB to zero (0)  at  process  startup.  If  the  JOB
   command fails to spawn a new job, GT.M sets $ZJOB  to  zero  (0).  Note
   that because of the left to right evaluation order of M, using $ZJOB in
   the jobparameter string results in using the value created by the last,
   rather than the current JOB command,  which  is  not  likely  to  match
   common coding practice.

   GT.M does not permit the SET or NEW command to modify $ZJOB.

2 $ZLevel
   $ZLevel

   $ZL[EVEL] contains an integer value indicating the "level  of  nesting"
   caused by DO commands, XECUTE commands, and extrinsic functions in the
   M invocation stack.

   $ZLEVEL has an initial value of one (1) and increments by one with each
   DO, XECUTE or extrinsic function. Any QUIT that does  not  terminate  a
   FOR  loop  decrements  $ZLEVEL.  ZGOTO  may  also  reduce  $ZLEVEL.  In
   accordance with the  M  standard,  a  FOR  command  does  not  increase
   $ZLEVEL. M routines cannot modify $ZLEVEL with the SET or NEW commands.

   Use $ZLEVEL in debugging or in an error-handling mechanism to capture a
   level for later use in a ZGOTO argument.

   Example:


   GTM>ZPRINT ^ZLEV

   A DO B

   WRITE X,!

   QUIT

   B GOTO C

   QUIT

   C DO D

   QUIT

   D SET X=$ZLEVEL

   QUIT

   GTM>DO ^ZLEV

   4
   This program, executed from Direct Mode, produces  a  value  of  4  for
   $ZLEVEL. If you run this program from the shell, the value  of  $ZLEVEL
   is three (3).

2 $ZMAXTPTIme
   $ZMAXTPTIme

   $ZMAXTPTI[ME] contains an integer value indicating  the  time  duration
   GT.M should wait for the completion of all  activities  fenced  by  the
   current transaction's outermost TSTART/TCOMMIT pair.

   $ZMAXTPTIME can be SET but cannot be NEWed.

   The initial value of $ZMAXTPTIME is zero (0) seconds,  which  indicates
   "no  timeout"  (unlimited  time).  The  value  of  $ZMAXTPTIME  when  a
   transaction's  outermost  TSTART  operation  executes  determines  the
   timeout setting for that transaction.

   When a $ZMAXTPTIME expires, GT.M executes the  $ETRAP/$ZTRAP  exception
   handler currently in effect.

        Negative values of $ZMAXTPTIME are also treated  as  "no  timeout".
        Timeouts  apply  only  to  the  outermost  transaction,  that  is,
        $ZMAXTPTIME has no effect when  TSTART  is  nested  within  another
        transaction.

   Example:


   Test ;testing TP timeouts

   set $ZMAXTPTIME=6,^X=0,^Y=0,^Z=0

   write "Start with $ZMAXTPTIME=",$ZMAXTPTIME,":",!

   for sleep=3:2:9 do

   . set retlvl=$zl

   . do longtran ;ztrap on longtran

   ;continues execution

   ;on next line

   . write "(^X,^Y)=(",^X,",",^Y,")",!

   write !,"Done TP Timeout test.",!

   quit

   longtran ;I/O in TP doesn't get rolled back

   set newzt="set $ZT="""" ";avoid recursive ZTRAP

   set $ZT=newzt_" goto err"

   tstart ():serial ;plain tstart works as well

   set ^X=1+^X

   write !,"^X=",^X,",will set ^Y to ",sleep

   write " in ",sleep," seconds..."

   hang sleep

   set ^Y=sleep

   write "^Y=",^Y

   tcommit

   write "...committed.",!

   quit

   err ;

   set $ZT=""

   write !,"In $ZTRAP handler. Error was: "

   write !," ",$zstatus

   if $TLEVEL do ;test allows handler use outside of TP

   . trollback

   . write "Rolled back transaction."

   write !

   zgoto retlvl


   Results:


   Start with $ZMAXTPTIME=6:


   ^X=1,will set ^Y to 3 in 3 seconds...^Y=3...committed.


   ^X=2,will set ^Y to 5 in 5 seconds...^Y=5...committed.


   ^X=3,will set ^Y to 7 in 7 seconds...

   In $ZTRAP handler. Error was:

   150377322,longtran+7^tptime,%GTM-E-TPTIMEOUT, Transaction timeoutRolled
   back transaction.

   ^X=3,will set ^Y to 9 in 9 seconds...

   In $ZTRAP handler. Error was:

   150377322,longtran+7^tptime,%GTM-E-TPTIMEOUT, Transaction timeoutRolled
   back transaction.

   Done TP Timeout test.

2 $ZMOde
   $ZMOde

   $ZMO[DE] contains a string value indicating the process execution mode.

   The mode can be:

   o    INTERACTIVE

   o    OTHER

   M routines cannot modify $ZMODE.

   Example:


   GTM> WRITE $ZMODE

   INTERACTIVE

   This displays the process mode.

2 $ZPOSition
   $ZPOSition

   $ZPOS[ITION] contains a string value specifying the  current  entryref,
   where entryref is [label][+offset]^routine, and the offset is evaluated
   from the closest preceding label.

   GT.M does not permit the SET or NEW commands to modify $ZPOSITION.

   Example:

   GTM>WRITE !,$ZPOS,! ZPRINT @$ZPOS

   This example displays the current location followed by the source code
   for that line.

2 $ZPROMpt
   $ZPROMpt

   $ZPROM[PT] contains a string value specifying the current  Direct  Mode
   prompt. By default, GTM> is the Direct  Mode  prompt.  M  routines  can
   modify $ZPROMPT by means of a SET command. $ZPROMPT  cannot  exceed  16
   characters. If an attempt is  made  to  assign  $ZPROMPT  to  a  longer
   string, only the first 16 characters will be taken.

   Example:


   GTM>SET $ZPROMPT="NEWZPROMPT>"

   NEWZPROMPT>

   This example changes the GT.M prompt to be NEWZPROMPT

2 $ZROutines
   $ZROutines

   $ZRO[UTINES] contains a string value specifying a directory or list of
   directories containing object files. Each  object  directory  may  also
   have an associated directory, or list of  directories,  containing  the
   corresponding source files. These directory lists are used  by  certain
   GT.M functions, primarily  auto-ZLINK,  to  locate  object  and  source
   files. The order in which directories appear in a given list determines
   the order in which they are searched for the appropriate item.

   Searches that use $ZROUTINES treat files as  either  object  or  source
   files. GT.M treats files with an extension of .o as  object  files  and
   files with an extension of .m as source files.

        Paths used in  $ZROUTINES  to  locate  routines  must  not  include
        embedded spaces, as $ZROUTINES uses spaces as delimiters.

3 Est_Val_frm_gtmroutines
   Establishing the Value from gtmroutines

   When the environment variable gtmroutines is defined, GT.M initializes
   $ZROUTINES to the value of  gtmroutines.  Otherwise,  GT.M  initializes
   $ZROUTINES to a null value. When $ZROUTINES is null, GT.M  attempts  to
   locate all source and object files in the  current  working  directory.
   $ZROUTINES="" is equivalent to $ZROUTINES=".".

   Commands or functions such as DO,  GOTO,  ZGOTO,  ZBREAK,  ZPRINT,  and
   $TEXT may auto-ZLINK and thereby indirectly use  $ZROUTINES.  If  their
   argument does not specify a directory, ZEDIT  and  explicit  ZLINK  use
   $ZROUTINES. ZPRINT and $TEXT use $ZROUTINES to locate a source file if
   GT.M cannot find the source file pointed to by  the  object  file.  For
   more information  on  ZLINK  and  auto-ZLINK,  refer  to  the  "Program
   Development Cycle" and "Commands" chapters in GT.M Programmer's Guide.

3 Set_Val_for_$ZRO
   Setting a Value for $ZROUTINES

   $ZRO[UTINES] is a read-write Intrinsic Special Variable, so M can also
   SET the value.

   By default, each directory entry in $ZROUTINES is  assumed  to  contain
   both object and source files. However, each object directory  may  have
   an associated directory or  list  of  directories  to  search  for  the
   corresponding source files. This  is  done  by  specifying  the  source
   directory  list,  in  parentheses,  following  the  object  directory
   specification.

   If the command specifies more than one source directory for  an  object
   directory, the source directories must be separated by spaces, and the
   entire list must be enclosed in parentheses ( )  following  the  object
   directory-specification.  If  the  object  directory  should  also  be
   searched for source, the name of that directory must be included in the
   parentheses,  (usually  as  the  first  element  in  the  list).
   Directory-specifications may also include empty parentheses, directing
   GT.M to proceed as if no source files exist for objects located in the
   qualified directory.

   To set $ZROUTINES outside of M, use the appropriate  shell  command  to
   set gtmroutines. Because gtmroutines is a list, enclose  the  value  in
   quotation marks (" ").

   Changes to the value of $ZROUTINES during a GT.M invocation  only  last
   for the current invocation, and do not change the value of gtmroutines.

   Directory specifications may include an environment variable. When GT.M
   SETs $ZROUTINES, it translates all environment variables  and  verifies
   the  syntax  and  the  existence  of  all  specified  directories.  If
   $ZROUTINES is set to an invalid value, GT.M generates a run-time error
   and does not change the value of $ZROUTINES.  Because  the  environment
   variables are translated when $ZROUTINES is set, any changes  to  their
   definition have no effect until $ZROUTINES is set again.

3 $ZRO_Examples
   $ZROUTINES Examples

   Example:


   GTM> s $zroutines=".(../src) $gtm_dist"

   This example directs GTM to look  for  object  modules  first  in  your
   current directory, then in the distribution directory that contains the
   percent routines. GT.M locates sources  for  objects  in  your  current
   directory in the sibling /src directory.

   Example:

   $ gtmroutines="/usr/jones /usr/smith"

   $ export gtmroutines

   $ gtm

   GTM> write $zroutines

   "/usr/jones /usr/smith"

   GTM> set $zro="/usr/jones/utl /usr/smith/utl"

   GTM> write $zroutines

   "/usr/jones/utl /usr/smith/utl"

   GTM> halt

   $ echo $gtmroutines

   /usr/jones /usr/smith

   This  example  defines  the  environment  variable  gtmroutines.  Upon
   entering  GT.M  Direct  Mode  $zroutines  has  the  value  supplied  by
   gtmroutines. The SET command changes the value.  When  the  GT.M  image
   terminates, the shell echo command demonstrates  that  gtmroutines  has
   not been modified by the M SET command.

   Example:

   GTM> SET $ZRO=". /usr/smith"

   This example sets $zroutines to a list containing two directories.

   Example:


   GTM> set $zro="/usr/smith(/usr/smith/tax /usr/smith/fica)"

   This example specifies that GT.M should search the directory /usr/smith
   for  object  files,  and  the  directories  /usr/smith/tax  and
   /usr/smith/fica for source files. Note that in this example. GT.M does
   not search /usr/smith for source files.

   Example:

   GTM> set $zro="/usr/smith(/usr/smith /usr/smith/tax /usr/smith/fica)"

   This example specifies that GT.M should search the directory /usr/smith
   for object files and the directories /usr/smith/tax and /usr/smith/fica
   for source files. Note that the difference between this example and the
   previous one is that GT.M  searches  /usr/smith  for  both  object  and
   source files.

   Example:


   GTM> set $zro="/usr/smith /usr/smith/tax()

   /usr/smith/fica"

   This specifies that GT.M should search /usr/smith  and  /usr/smith/fica
   for object and source files. However,  because  the  empty  parentheses
   indicate directories searched only for  object  files,  GT.M  does  not
   search /usr/smith/tax for source files.

   Omitting the parentheses indicates that GT.M can search  the  directory
   for both source and object files. $ZROUTINES=/usr/smith  is  equivalent
   to $ZROUTINES=/usr/smith(/usr/smith).

3 $ZRO_Search_Types
   $ZROUTINES Search Types

   GT.M uses $ZRO[UTINES] to perform three types of searches:

   o    Object-only when the command or function using $ZROUTINES requires
        a .o file extension.

   o    Source-only when the command or function using $ZROUTINES requires
        a file extension other than .o.

   o    Object-source match when the command or function  using  $ZROUTINES
        does not specify a file extension.

   An explicit ZLINK that specifies a non .o extension is considered as a
   function that  has  not  specified  a  file  extension  for  the  above
   searching purposes.

   All searches proceed from left to right through $ZROUTINES. By default,
   GT.M searches directories  for  both  source  and  object  files.  GT.M
   searches directories followed by empty parentheses ( ) for object files
   only. GT.M searches directories in parentheses only for source files.

   Once an object-matching search  locates  an  object  file,  the  source
   search becomes limited. If the directory containing the object file has
   an attached parenthetical list of directories, GT.M only  searches  the
   directories in the attached list for  matching  source  files.  If  the
   directory  containing  the  object  files  does  not  have  following
   parentheses, GT.M restricts the search for matching source files to the
   same directory. If the object module is in  a  directory  qualified  by
   empty parentheses, GT.M cannot perform any operation that refers to the
   source file.

3 $ZRO_Search_Ex
   $ZROUTINES Search Examples

   This section describes a model for understanding $ZROUTINES operations
   and the illustrating examples, which may assist  you  if  you  wish  to
   examine the topic closely.

   You may think of $ZROUTINES as supplying a two  dimensional  matrix  of
   places to look for files. The matrix has one or more  rows.  The  first
   row in the matrix contains places to look for object and the second and
   following  rows  contain  places  to  look  for  source.  Each  column
   represents the set of places that contain information  related  to  the
   object modules in the first row of the column.

   Example:


   GTM> s $zro=". /usr/smi/utl() /usr/jon/utl

   (/usr/jon/utl/so /usr/smi/utl)"
3 Sh_Lib_FileSpec_in_$ZRO
   Shared Library File Specification in $ZROUTINES

   The $ZROUTINES ISV allows individual UNIX shared library file names to
   be specified in the search path. During a search for auto-ZLINK, when a
   shared library is encountered, it is probed for a given routine and, if
   found, that routine is linked/loaded into the image. During an explicit
   ZLINK, all shared libraries in  $ZROUTINES  are  ignored  and  are  not
   searched for a given routine.

   Currently GT.M supports this feature on  Tru64  operating  system,  and
   plans to support other UNIX operating system in near future.

   $ZROUTINES  syntax  contains  a  file-specification  indicating  shared
   library file path. GT.M does not require any designated  extension  for
   the shared library component of $ZROUTINES. Any file specification that
   does not name a directory is treated as shared library. However, it is
   recommended that the extension commonly used on a  given  platform  for
   shared library files be given to any GT.M shared libraries.  (Refer  to
   the following section  on  "Linking  GT.M  Shared  Images").  A  shared
   library component cannot specify source directories.  GT.M  reports  an
   error at an attempt to associate any source  directory  with  a  shared
   library in $ZROUTINES.

   The following traits of $ZROUTINES help support shared libraries:

   o    The $ZROUTINES search continues to find objects in the first place,
        processing from left to right, that holds a copy;  it  ignores  any
        copies in subsequent locations. However, now for auto-ZLINK, shared
        libraries are accepted as object repositories with the same ability
        to supply objects as directories.

   o    Explicit ZLINK, never searches Shared Libraries.  This  is  because
        explicit ZLINK is used to link a newly created routine or re-link a
        modified routine and there is no mechanism to load new objects into
        an active shared library.

   o    ZPRINT and $TEXT() of the routines in a shared library, read source
        file path from the header of the loaded routine. If the image does
        not contain the routine, an auto-ZLINK is initiated. If the source
        file path recorded in  the  routine  header  when  the  module  was
        compiled cannot be located, ZPRINT and $TEXT()  initiate  a  search
        from the beginning of $ZROUTINES, skipping over the shared library
        file specifications. If the located source does not match the code
        in image (checked via checksum), ZPRINT generates an object-source
        mismatch status and $TEXT() returns a null string.

   o    ZEDIT, when  searching  $ZROUTINES,  skips  shared  libraries  like
        explicit ZLINK for the same reasons. $ZSOURCE ISV is implicitly set
        to the appropriate source file.

   For  example,  if  libshare.so  is  built  with  foo.o  compiled  from
   ./shrsrc/foo.m, the following commands specify that GT.M should search
   the library ./libshare.so for symbol foo when do ^foo is encountered.


   GTM>SET $ZROUTINES="./libshare.so ./obj(./shrsrc)"

   GTM>DO ^foo ;auto-ZLINK foo - shared

   GTM>ZEDIT "foo" ;edit ./shrsrc/foo.m

   GTM>W $ZSOURCE,! ;prints foo

   GTM>ZPRINT +0^foo ;issues a  source-object  mismatch  status  TXTSRCMAT
   error message
   GTM>ZLINK "foo" ;re-compile ./shrsrc/foo.m to generate ./obj/foo.o.

   GTM>W $TEXT(+0^foo) ;prints foo

   Note that ZPRINT reports an error, as foo.m does not match the routine
   already linked into image. Also note that, to recompile and re-link the
   ZEDITed foo.m, its source directory needs to be attached to the object
   directory [./obj] in $ZROUTINES. The example assumes the shared library
   (libshare.so) has been built using shell  commands.  The  procedure  to
   build a shared library from a list of GT.M generated object (.o) files
   is detailed in the following section on "Linking GT.M Shared Images".

4 Link_GTM_Sh_Image
   Linking GT.M Shared Images

   Following are the steps (UNIX system commands, and GT.M commands) that
   need to be taken to use GT.M shared image linking with $ZROUTINES.

5 Comp_SrcFile_to_ObjFile
   Compile Source (.m) Files to Object (.o) Files

   In order to share M routines, GT.M generates objects (.o) with position
   independent code, a  primary  requirement  for  shared  libraries.  All
   objects must be generated by a release of  GT.M  that  supports  shared
   binaries linking.

5 Creat_ShLib_from_ObjFile
   Create a Shared Library from Object (.o) Files

   On each UNIX platform, the  native  linker  ld  provides  command  line
   options to create a shared  library  from  a  list  of  .o  files.  The
   specific ld options vary depending on the platform.

   Although GT.M does not require a specific  file  extension  for  shared
   libraries, it is recommended that the conventional  extension  (.so  on
   Tru64) be used on a given platform. For example,  the  following  Tru64
   linker command


   $ ld -shared -taso -o libabc.so a.o b.o c.o -lc

   creates a shared library libabc.so from GT.M object files a.o, b.o and
   c.o. The flag -taso directs the linker to generate  32-bit  addressable
   Shared Library. Without this option, Tru64 UNIX ld generates  a  64-bit
   addressable  shared  library  by  default.  Even  though  GT.M  can
   successfully load 64-bit shared library, Sanchez recommends the use of
   the -taso option for best compatibility with the GT.M memory model.

   Notes on Tru64 UNIX linker:

   o    The linker (ld) may have a limit on the number of object files that
        it can accept on the command line. If ld fails to read all objects
        from the command line, users  are  recommended  to  use  -input  to
        specify a text file <command-file> that contains all  object  files
        as if they were specified on the command line.

   o    When creating a shared library, Sanchez suggests linking with the C
        library (-lc at the end of link line) to prevent ld from reporting
        various undefined-symbol warnings. These undefines are not relevant
        to the use of the GT.M shared library routines but linking with the
        C library eliminates the linker warning messages.

   o    See ld manual pages (UNIX shell command - man ld) for more details
        of linker options.

5 Est_$ZRO_frm_gtmroutines
   Establish $ZROUTINES from gtmroutines

   When  the  UNIX  environment  variable  gtmroutines  is  defined,  GT.M
   initializes $ZROUTINES to the value of gtmroutines. The $ZROUTINES ISV
   can also be modified using SET command.

   Example:


   $ gtmroutines="./libabc.so ./obj(./src)"

   $ export gtmroutines

   $ mumps -direct

   GTM>write $ZROUTINES,! ;writes "./libabc.so ./obj(./src)"

   GTM> do ^a ;runs ^a from libabc.so

   GTM> do ^b ;runs ^b from libabc.so

   GTM> do ^c ;runs ^c from libabc.so

   GTM> halt

   $

2 $ZSOurce
   $ZSOurce

   $ZSO[URCE] contains a string value specifying the default pathname for
   the ZEDIT and ZLINK commands. ZEDIT or ZLINK  without  an  argument  is
   equivalent to ZEDIT/ZLINK $ZSOURCE.

   $ZSOURCE initially contains the  null  string.  When  ZEDIT  and  ZLINK
   commands have a pathname for an argument, they implicitly set $ZSOURCE
   to that argument. This ZEDIT/ZLINK argument can include a full pathname
   or a relative one. A relative path could include a file in the current
   directory, or the path to the file from the current working directory.
   In the latter instance, do not  include  the  slash  before  the  first
   directory name. $ZSOURCE will prefix the path to  the  current  working
   directory including that slash.

   The file name may contain a file extension. If the extension is  .m  or
   .o, $ZSOURCE  drops  it.  The  ZEDIT  command  accepts  arguments  with
   extensions other than .m or .o. $ZSOURCE  retains  the  extension  when
   such arguments are passed.

   If $ZSOURCE contains a file with an extension  other  than  .m  or  .o,
   ZEDIT processes it but ZLINK returns an error message

   $ZSOURCE is a read-write Intrinsic  Special  Variable,  (i.e.,  it  can
   appear on the left side of the equal sign (=) in the  argument  to  the
   SET command). A $ZSOURCE value may include an environment variable.

   Example:

   GTM> ZEDIT "subr.m"

   .

   .

   GTM> WRITE $ZSOURCE

   subr

   Example:

   GTM> ZEDIT "test"

   .

   .

   .

   GTM> WRITE $ZSOURCE

   test

   Example:


   GTM> ZEDIT "/usr/smith/report.txt"

   .

   .

   .

   GTM> WRITE $ZSOURCE

   /usr/smith/report.txt

   Example:

   GTM> ZLINK "BASE.O"

   .

   .

   .

   GTM> WRITE $ZSOURCE

   BASE

2 $ZStatus
   $ZStatus

   $ZS[TATUS] contains a string value specifying the error condition code
   and location of the  last  exception  condition  that  occurred  during
   routine execution.

   GT.M maintains $ZSTATUS  as  a  string  consisting  of  three  or  more
   substrings. The string consists of the following:

   o    An error message number as the first substring.

   o    The entryref of the line in error as the second substring; a comma
        (,) separates the first and second substrings.

   o    The message detail as the third substring. The format of this is a
        percent sign (%) identifying the message  facility,  a  hyphen  (-)
        identifying the error  severity,  another  hyphen  identifying  the
        message identification followed by a comma (,), which  is  followed
        by the message text if any:

   Format: %<FAC>-<SEV>-<ID>, <TEXT>

   Example: %GTM-E-DIVZERO, Attempt to divide by zero

   GT.M sets $ZSTATUS when it encounters errors during program execution,
   but not when it encounters errors in a Direct Mode command.

   $ZSTATUS is a read-write Intrinsic  Special  Variable,  (i.e.,  it  can
   occur on the left side of the equal sign (=) in the argument to the SET
   command). While it will accept any string, Sanchez Computer Associates
   recommends setting it to null. M routines cannot modify  $ZSTATUS  with
   the NEW command.

   Example:


   GTM> WRITE $ZSTATUS

   150373110,+1^MYFILE,%GTM-E-DIVZERO,
   Attempt to divide by zero

   This example displays the status generated by a divide by zero (0).

2 $ZSTep
   $ZSTep

   $ZST[EP] contains a string value specifying the default action for the
   ZSTEP command. $ZSTEP provides the ZSTEP action  only  when  the  ZSTEP
   command does not specify an action.

   $ZSTEP initially contains the string "B" to enter direct  mode.  $ZSTEP
   is a read-write Intrinsic Special Variable, (i.e., it can appear on the
   left side of the equal sign (=) in the argument to the SET command).

   Example:

   GTM> WRITE $ZSTEP

   B

   GTM>

   This example displays  the  current  value  of  $ZSTEP,  which  is  the
   default.

   Example:


   GTM> SET $ZSTEP="ZP @$ZPOS B"

   This example sets $ZSTEP to code that displays the contents of the next
   line to execute, and then enters Direct Mode.

2 $ZSYstem
   $ZSYstem

   $ZSY[STEM] holds the value of the status code for the  last  subprocess
   invoked with the ZSYSTEM command.

2 $ZTExit
   $ZTExit

   $ZTE[XIT] contains a string value  that  controls  the  GT.M  interrupt
   facility at the transaction  commit  or  rollback.  At  each  outermost
   TCOMMIT or TROLLBACK, If +$ZTEXIT evaluates to  non-zero  (TRUE),  then
   $ZINTERRUPT is XECUTEd after completing the commit or rollback.

   $ZTEXIT is a read-write ISV, that is, it can appear on the left side of
   the equal sign (=) in the argument  to  the  SET  command.  M  routines
   cannot NEW $ZTEXIT. GT.M initializes $ZTEXIT to  null  at  the  process
   startup. Note that the changes to the value of $ZTEXIT  during  a  GT.M
   invocation last for the entire duration of the process, so  it  is  the
   application’s responsibility to reset $ZTEXIT  after  $ZINTERRUPT  is
   delivered in order to turn off redelivering the  interrupt  each  every
   subsequent transaction commit or rollback.

   Example:

   ztran.m

   foo ;

   set $ztexit=1

   set $zinterrupt="d ^throwint"

   tstart ()

   for i=1:1:10 do

   . set ^ACN(i,"bal")=i*100

   tstart ()

   do ^throwint

   do ^proc

   tcommit:$tlevel=2

   for i=1:1:10 do

   . set ^ACN(i,"int")=i*0.05

   do ^srv

   if $tlevel trollback

   do ^exc

   set $zte="",$zint=""

   quit

   bar ;

   write "Begin Transaction",!

   set $zte=1

   tstart ()

   i '$zsigproc($j,$ztrnlnm("sigusrval")) w "interrupt sent...",!!

   for i=1:1:4 set ^B(i)=i*i

   tcommit

   write "End Transaction",!

   do ^srv

   quit


   throwint.m

   thrint

   set  $zint="write  !,""interrupt  occurred  at  :
   "",$stack($stack-1,""PLACE""),! set $zte=1"
   if  '$zsigproc($j,$ztrnlnm("sigusrval"))  write  "interrupt  sent  to
   process"
   write "***************************************",!!

   quit


   Example:


   GTM>d foo^ztran

   interrupt sent to process

   interrupt occurred at : thrint+3^throwint

***************************************


   interrupt occurred at : foo+13^ztran


   GTM>

   In the above call to foo^ztran, the interrupt handler is a user-defined
   routine,  throwint.  The  process  is  sent  a  signal  (SIGUSR1),  and
   $ZINTERRUPT is executed. At the outermost trollback, the  interrupt  is
   rethrown, causing $ZINTERRUPT to be executed again.

   Example:


   GTM>w $zint

   IF $ZJOBEXAM()

   GTM>zsy "ls GTM*"

   ls: No match.


   GTM>d bar^ztran

   Begin Transaction

   interrupt sent...


   End Transaction


   GTM>zsy "ls GTM*"

   GTM_JOBEXAM.ZSHOW_DMP_22551_1 GTM_JOBEXAM.ZSHOW_DMP_22551_2


   GTM>


   This uses the default value of $ZINTERRUPT to service interrupts issued
   to the process. The $ZJOBEXAM function executes a ZSHOW "*", and stores
   the output in each GTM_ZJOBEXAM_ZSHOW_DMP for  the  initial  interrupt,
   and at tcommit when the interrupt is rethrown.

2 $ZTrap
   $ZTrap

   $ZT[RAP] contains a string value that GT.M XECUTEs when an error occurs
   during routine execution.

        The following discussion assumes  that  $ETRAP  error  handling  is
        simultaneously not in effect (that is, $ETRAP="").

   When the $ZTRAP variable is not  null,  GT.M  executes  $ZTRAP  at  the
   current level. The $ZTRAP variable has the initial value  of  "B,"  and
   puts the process in Direct Mode when an error condition occurs. If the
   value of $ZTRAP is null (""), an exception causes the image to run-down
   with the condition  code  associated  with  the  exception.  If  $ZTRAP
   contains invalid source code, GT.M displays an error message  and  puts
   the process into Direct Mode.

   $ZTRAP is a read-write Intrinsic Special Variable, (i.e., it can appear
   on the left side of the equal sign (=)  in  the  argument  to  the  SET
   command).

   $ZTRAP may also appear as an argument to an inclusive NEW command. NEW
   $ZTRAP causes GT.M to set $ZTRAP to null ($ZTRAP="") and to  stack  the
   old value of $ZTRAP. When the program QUITs from the  invocation  level
   where the NEW occurred, GT.M restores the value previously  stacked  by
   the NEW. NEW $ZTRAP  provides  nesting  of  $ZTRAP.  Because  $ZTRAP=""
   terminates the image  when  an  error  occurs,  SET  $ZTRAP=  generally
   follows immediately after NEW $ZTRAP. You may  use  this  technique  to
   construct error handling strategies corresponding  to  the  nesting  of
   your programs. If the environment variable gtm_ztrap_new  evaluates  to
   boolean TRUE (case  insensitive  string  "TRUE",  or  case  insensitive
   string "YES", or a non-zero number), $ZTRAP is  NEWed  when  $ZTRAP  is
   SET; otherwise $ZTRAP is not stacked when it is SET.

        QUIT from a $ZTRAP terminates the level at  which  the  $ZTRAP  was
        activated.

   Keep $ZTRAP simple and put complicated logic in another routine. If the
   action specified by $ZTRAP results in  another  run-time  error  before
   changing the value of $ZTRAP, GT.M invokes $ZTRAP until it exhausts the
   process stack space, terminating the image. Carefully  debug  exception
   handling.

   Example:


   GTM> S $ZTRAP="ZP @$ZPOS B"

   This example modifies $ZTRAP to display source code for the line where
   GT.M encounters an error before entering Direct Mode.

   There are four accepted behavioural forms of $ZTRAP controlled  by  the
   UNIX environment variable gtm_ztrap_form. If gtm_ztrap_form is defined
   to "code" (or not defined to one of the subsequently described values),
   then GT.M treats $ZTRAP as code and handles it as previously described
   in the documentation.

   The four different behavioural forms of gtm_ztrap_form are:

   o    entryref - If gtm_ztrap_form evaluates  to  "entryref"  then  GT.M
        treats it as an entryref argument to an implicit GOTO command.

   o    adaptive - If  gtm_ztrap_form  evaluates  to  "adaptive"  then  if
        $ZTRAP does not compile to valid M code, then $ZTRAP is treated as
        just described for "entryref." Since  there  is  little  ambiguity,
        code and entryref forms of $ZTRAP can be  intermixed  in  the  same
        application.

   Note that GT.M attempts to compile $ZTRAP before evaluating  $ZTRAP  as
   an entryref. Since GT.M allows commands without arguments such as QUIT,
   ZGOTO, or HANG as valid labels, be careful not to use such keywords as
   labels for error handling code in "adaptive" mode.

   o    pope[ntryref] / popa[daptive] -  If  gtm_ztrap_form  evaluates  to
        "POPE[NTRYREF]" or "POPA[DAPTIVE]" (case  insensitive)  and  $ZTRAP
        value is in the form of entryref, GT.M unwinds the M stack from the
        level at which an error occurred to (but not including)  the  level
        at which $ZTRAP was last SET. Then, GT.M transfers control  to  the
        entryref in $ZTRAP at the level where the $ZTRAP value was SET. If
        the UNIX environment variable gtm_zyerror is  defined  to  a  valid
        entryref, GT.M transfers  control  to  the  entryref  specified  by
        GTM_ZYERROR (with an implicit DO) after  unwinding  the  stack  and
        before transferring control to the entyref specified in $ZTRAP.

2 $ZVersion
   $ZVersion

   $ZV[ERSION] contains a string value specifying the currently installed
   GT.M.  $ZV[ERSION]  is  a  space-delimited  string  with  four  pieces
   described below:

   o    The M product name, for example "GT.M".

   o    The M product version identifier; the format is: the capital letter
        "V" followed by the  major  version  number,  then  a  period  (.),
        followed by the minor version number, then a patch number.

   o    The host operating system name  and  optional  version  identifier;
        this identifier is only included if different versions  of  the  OS
        support different, compatible versions of the M product.

   o    The host hardware designation and optional chipset identifier; this
        identifier is only included if different versions of  the  hardware
        support different compatible versions of the M product.

   M routines cannot modify $ZVERSION.

   Example:


   GTM> WRITE $ZVERSION

   GT.M V4.3-001B AIX RS6000

   This example displays the current version identifier for GT.M.

2 $ZYERror
   $ZYERror

   $ZYER[ROR] is a read/write ISV that contains a string value pointing to
   an entryref. After GT.M encounters an  error,  if  $ZYERROR  is  set  a
   non-null value, GT.M invokes the routine at the entryref  specified  by
   $ZYERROR with an implicit DO. It is intended that the code  invoked  by
   $ZYERROR use the value of $ZSTATUS to select or construct  a  value  to
   which it SETs $ZERROR. If $ZYERROR is not a valid  entryref  or  if  an
   error occurs while executing the entryref specified by  $ZYERROR,  GT.M
   SETs $ZERROR to the error status encountered. GT.M then returns control
   to the M code specified by $ETRAP/$ZTRAP or device EXCEPTION.

   $ZYERROR is implicitly NEWed on  entry  to  the  routine  specified  by
   $ZYERROR. However, if GT.M fails to compile,  GT.M  does  not  transfer
   control to the entryref specified by $ZYERROR.

   GT.M permits $ZYERROR to be modified by the SET and NEW commands.

1 In_Out_Processing
   Input Output Processing

   OPEN, USE,  and  CLOSE  commands  accept  deviceparameters,  which  are
   keywords that permit an GT.M program to control the device state. Some
   deviceparameters accept arguments, and some require them.  The  current
   ANSI standard for GT.M does not define  the  deviceparameters  for  all
   devices.

2 IO_ISV
   I/O Intrinsic Special Variables

   GT.M intrinsic special  variables  provide  a  means  of  communication
   between a device  and  its  device  driver  and  GT.M  routines.  These
   variables allow a GT.M routine to manage  the  I/O  with  a  particular
   device.

3 Device_Nam_Var
   Device Name Variables

   GT.M provides three intrinsic special variables that identify devices.

4 $IO
   $IO

   $I[O] contains the name of the current device specified by the last USE
   command. The M standard does not permit a SET command  to  modify  $IO.
   USE produces the same $IO as USE $PRINCIPAL, but $P  is  the  preferred
   construct.

4 $Principal
   $Principal

   $P[RINCIPAL] contains the absolute pathname of the  principal  (initial
   $IO) device.

   Input and output for a process may come from separate devices, namely,
   the standard input and output. However, the GT.M I/O model allows only
   one device to be USEd (or active) at a time. When an image starts, GT.M
   implicitly OPENs the standard input and standard output  device(s)  and
   assigns the device(s) to $PRINCIPAL. For USE  deviceparameters,  it  is
   the standard input that determines the device type.

   For an image invoked interactively, $PRINCIPAL is the user's terminal.
   For an image invoked from a terminal by a shell script,  $PRINCIPAL  is
   the shell script's standard input (usually the terminal)  and  standard
   output (also usually the terminal),  unless  the  shell  redirects  the
   input or output.

   GT.M ignores a CLOSE command specifying the principal device. GT.M does
   not permit a SET command to modify $PRINCIPAL.

4 $ZIO
   $ZIO

   $ZIO contains the translated name of the current device, in contrast to
   $IO, which contains the name as specified by the USE command.

3 Cur_Position_Var
   Cursor Position Variables

   GT.M provides two  intrinsic  special  variables  for  determining  the
   virtual cursor position. $X refers to  the  current  column,  while  $Y
   refers to the current row.

4 $X
   $X

   $X contains an integer value ranging from 0 to 65,535,  specifying  the
   horizontal position of a virtual cursor in the current  output  record.
   $X=0 represents the left-most position of a record or row.

   Every OPENed device has a $X. However, GT.M only has access  to  $X  of
   the current device. Therefore, be careful when sequencing USE commands
   and references to $X.

   Generally, GT.M increments $X for every character written to  and  read
   from the current device. GT.M format control  characters,  FILTER,  and
   the device WIDTH and WRAP also have an effect on $X.

   SET $X does not automatically issue device commands or escape sequences
   to reposition the physical cursor.

4 $Y
   $Y

   $Y contains an integer value ranging from 0 to 65,535,  specifying  the
   vertical position of a virtual cursor in  the  current  output  record.
   $Y=0 represents the top row or line.

   Every OPEN device has a $Y. However,  GT.M  only  accesses  $Y  of  the
   current device. Therefore, be careful when sequencing USE commands and
   references to $Y.

   When GT.M  finishes  the  logical  record  in  progress,  it  generally
   increments $Y. GT.M recognizes the end of  a  logical  record  when  it
   processes certain GT.M format control characters, or  when  the  record
   reaches its maximum size, as determined by the device  WIDTH,  and  the
   device is set to WRAP. The definition of "logical record"  varies  from
   device to device. For an exact definition, see  the  sections  on  each
   device type. FILTER and the device LENGTH also have an effect on $Y.

   SET $Y does not automatically issue device commands or escape sequences
   to reposition the physical cursor.

4 Maint_of_$X_and_&Y
   Maintenance of $X and $Y

   In GT.M, the following factors affect the maintenance  of  the  virtual
   cursor position ($X and $Y):

   o    The bounds of the virtual "page"

   o    GT.M format control characters

   o    GT.M character filtering

   Each device has a WIDTH and a LENGTH that define  the  virtual  "page."
   The WIDTH determines the maximum size of a record for a  device,  while
   the LENGTH determines how many records fit on a page. GT.M starts a new
   record when the current record size ($X) reaches the maximum WIDTH and
   the device has WRAP enabled. When the current  line  ($Y)  reaches  the
   maximum LENGTH, GT.M starts a new page.

   GT.M has several format control characters that allow the manipulation
   of the virtual cursor. For all I/O devices,  the  GT.M  format  control
   characters do the following:

        ! Sets $X to zero (0) and increments $Y, and terminates the logical
        record in progress. The definition of "logical record" varies from
        device to device, and is discussed in each device section.
        # Sets $X and $Y to zero (0), and terminates the logical record in
        progress.
        ?n If n is greater than $X,  writes  n-$X  spaces  to  the  device,
        bringing $X to n. If n is less than or  equal  to  $X,  ?n  has  no
        effect. When WRAP is enabled and n exceeds the WIDTH of  the  line,
        WRITE ?n increments $Y and sets $X equal to n#WIDTH, where # is the
        GT.M modulo operator.
   GT.M provides two modes  of  character  filtering.  When  filtering  is
   enabled, certain <CTRL> characters and/or escape sequences have special
   effects on the cursor position (e.g., <BS> (ASCII 8) may decrement $X,
   if $X is non-zero). For more information on write filtering,  refer  to
   the section on the [NO]FILTER deviceparameter.

3 Status_Var
   Status Variables

   GT.M provides several I/O  status  variables  that  convey  information
   about the status of individual operations.

4 $ZA
   $ZA

   $ZA contains a status determined by the last read on  the  device.  The
   value is a decimal integer with a meaning determined by the  device  as
   follows:

   For Terminal I/O:

        0 Indicating normal termination of a read operation
        1 Indicating a parity error
        2 Indicating the terminator sequence was too long
        9 Indicating a default for all other errors
   For Sequential Disk:

        0 Indicating normal termination of a read operation
        9 Indicating a failure of a read operation
   For FIFO:

        0 Indicating normal termination or time out
        9 Indicating a failure of a read operation
   For socket:

        0 Indicating normal termination or time out
        9 Indicating failure of a read operation
   $ZA refers to the status of the  current  device.  Therefore,  exercise
   care in sequencing USE commands and references to $ZA.

4 $ZB
   $ZB

   $ZB contains a string specifying the  input  terminator  for  the  last
   terminal READ. $ZB is null, and it is not maintained for devices other
   than terminals. $ZB may contain any legal  input  terminator,  such  as
   <CR> (ASCII 13) or an escape sequence starting with <ESC>  (ASCII  27),
   from zero (0) to  15  bytes  in  length.  $ZB  is  null  for  any  READ
   terminated by a timeout or any fixed-length READ  terminated  by  input
   reaching the maximum length.

   $ZB contains the actual character string, not  a  sequence  of  numeric
   ASCII codes.

   Example:

   SET zb=$ZB FOR i=1:1:$LENGTH(zb) WRITE !,i,?5,$A(zb,i)

   This example displays the series of ASCII codes for the  characters  in
   $ZB.

   $ZB  refers  to  the  last  READ  terminator  of  the  current  device.
   Therefore, be careful when sequencing USE commands  and  references  to
   $ZB.

4 $ZEOF
   $ZEOF

   $ZEOF contains a truth-valued expression indicating  whether  the  last
   READ operation reached the end-of-file. $ZEOF is  TRUE(1)  at  EOF  and
   FALSE (0) at other positions. GT.M does not maintain $ZEOF for terminal
   devices.

   $ZEOF  refers  to  the  end-of-file  status  of  the  current  device.
   Therefore, be careful when sequencing USE commands  and  references  to
   $ZEOF.

2 IO_Devices
   I/O Devices

   Each device type supported by GT.M responds to a particular  subset  of
   deviceparameters, while ignoring others. Devices may be programmed in a
   device-specific  manner,  or  in  a  device-independent  manner.
   Device-specific I/O routines are intended for use with only one type of
   device.  Device-independent  I/O  routines  contain  appropriate
   deviceparameters for all devices to be supported by  the  function,  so
   the user can redirect to a different device output while using the same
   program.

   GT.M supports the following I/O device types:

   o    Terminals and Printers

   o    Sequential Disk Files

   o    FIFOs

   o    Null Devices

   o    Socket Devices

3 IO_Devi_Recog
   I/O Device Recognition

   GT.M  OPEN,  USE,  and  CLOSE  commands  have  an  argument  expression
   specifying a device name. In the operating system environment, a device
   may be referred to either by its physical name or by a name containing
   one or more environment variables, each with a dollar-sign  ($)  prefix
   that expand to its physical name. Because environment variables permit
   program coding independent of  hardware  configuration,  they  tend  to
   isolate the code from hardware changes.

   During an OPEN, GT.M attempts to resolve the specified device names to
   physical names. When GT.M successfully resolves  a  device  name  to  a
   physical device, that device becomes the target of  the  OPEN.  If  the
   device name contains a dollar sign ($), GT.M  attempts  an  environment
   variable translation; the result becomes the name of the device. If it
   does not find such an environment variable, it assumes that the dollar
   sign is a part of the filename, and opens a file by that name.

   Once a device is OPEN,  GT.M  establishes  an  internal  correspondence
   between a name and the device or file. Therefore, while the  device  is
   OPEN, changing the translation of an environment variable in the device
   specification does not change the device.

   The following names identify the original $IO for the process:

   o    $PRINCIPAL

   0

   Some versions of GT.M also treat the empty string  as  identifying  $P.
   However, Sanchez recommends using the empty string to identify  a  null
   device, so it would be wise to avoid or eliminate this behavior.

3 Devi_Spec_Defaults
   Device Specification Defaults

   GT.M uses standard filenames for device specifiers.

   The complete format for a filename is:

   /directory/file

   If the expression specifying a  device  does  not  contain  a  complete
   filename, the expression may start with an  environment  variable  that
   translates to one or more leading  components  of  the  filename.  GT.M
   applies default values for the missing components.

   The GT.M file-name defaults are the following:

        Directory Current working directory
        File No default (user-defined filename)
        Filetype No default (user-defined filetype)
3 How_IO_DeviParam_Work
   How I/O Deviceparameters Work

   I/O deviceparameters either perform actions that cause the device to do
   something (for example, CLEARSCREEN), or specify  characteristics  that
   modify  the  way  the  device  subsequently  behaves  (for  example,
   BLOCKSIZE). When an I/O command has multiple  action  deviceparameters,
   GT.M performs the actions in the order of the  deviceparameters  within
   the  command  argument.  When  a  command  has  characteristic
   deviceparameters, the last occurrence  of  a  repeated  or  conflicting
   deviceparameter determines the characteristic.

   Deviceparameters often relate to a specific device type.  GT.M  ignores
   any deviceparameters that do not  apply  to  the  type  of  the  device
   specified by the command argument. Specified device characteristics are
   in force for the duration of the GT.M image, or until  modified  by  an
   OPEN, USE, or CLOSE command.

   When reopening a device that  it  previously  closed,  a  GT.M  process
   restores all characteristics not specified on the OPEN  to  the  values
   the device had when it was last CLOSEd.  GT.M  treats  sequential  disk
   files differently and uses defaults  for  unspecified  sequential  disk
   file characteristics on every OPEN  (that  is,  GT.M  does  not  retain
   sequential disk file characteristics on a CLOSE).

   The ZSHOW  command  with  an  argument  of  "D"  displays  the  current
   characteristics for all devices OPENed by the process. ZSHOW can direct
   its output into a GT.M variable.

3 Abbv_DeviParam
   Abbreviating Deviceparameters

   GT.M  deviceparameters  do  not  have  predefined  abbreviations.  GT.M
   recognizes  deviceparameters  using  a  minimum  recognizable  prefix
   technique. Most deviceparameters may be  represented  by  four  leading
   characters, except ERASELINE, all deviceparameters starting with WRITE,
   and Z* deviceparameters in a mnemonicspace (such as SOCKET).  The  four
   leading characters recognized do not include a leading NO for negation.


   For compatibility with previous versions, GT.M  may  recognize  certain
   deviceparameters by abbreviations shorter than the minimum. While it is
   convenient  in  Direct  Mode  to  use  shorter  abbreviations,  Sanchez
   Computer Associates may add additional deviceparameters, and therefore,
   recommends all programs use at  least  four  characters.  Because  GT.M
   compiles the code, spelling  out  deviceparameters  completely  has  no
   performance penalty, except  when  used  with  indirection  or  XECUTEd
   arguments.


3 Devi_Independent_Prog
   Device-Independent Programming

   When a user may choose a device for I/O, GT.M routines can take one of
   two basic programming approaches.

   o    The  user  selection  directs  the  program  into  different  code
        branches, each of which handles a different device type.

   o    The user selection identifies the device. There is  a  single  code
        path written with a full complement of deviceparameters  to  handle
        all selectable device types.

   The latter approach is called device-independent programming. To permit
   device independent programming, GT.M uses the same deviceparameter for
   all  devices  that  have  an  equivalent  facility,  and  ignores
   deviceparameters applied  to  a  device  that  does  not  support  that
   facility.

   Example:

   OPEN dev:(EXCE=exc:REWIND:VARIABLE:WRITEONLY)

   This example OPENs a device with deviceparameters that affect different
   devices. The EXCEPTION has an effect for all device types. When dev is
   a terminal or a null device, GT.M ignores the  other  deviceparameters.
   When dev is a sequential file on disk, GT.M uses REWIND  and  VARIABLE.
   This command performs a valid OPEN for all the different device types.

        A file that has been previously  created  and  contains  data  that
        should be retained can also be opened  with  the  device  parameter
        APPEND.

2 Terminals
   Using Terminals

   A typical GT.M application is largely interactive  and  uses  terminals
   extensively. By default, a GT.M process directs  its  terminal  I/O  to
   $PRINCIPAL. $PRINCIPAL identifies the terminal  that  the  user  signed
   onto in UNIX.

   While all terminals support the CTRAP deviceparameter, which optionally
   allows  terminal  input  to  optionally  redirect  program  flow,  only
   $PRINCIPAL supports CENABLE, which optionally allows the terminal user
   to invoke the Direct Mode shell.

   Directly  connected  printers  often  appear  to  GT.M  as  a  terminal
   (although printers  generally  do  not  provide  input)  regardless  of
   whether the printer is connected to the  computer  with  a  high  speed
   parallel interface, or an asynchronous terminal controller.

3 Set_Terminal_Char
   Setting Terminal Characteristics

   GT.M does not isolate its handling of terminal characteristics from the
   operating system environment at  large.  GT.M  inherits  the  operating
   system terminal characteristics in effect at the time the GT.M image is
   invoked. When GT.M exits, the invoking environment retains  the  device
   characteristics established with GT.M.

   However, if the process temporarily leaves the GT.M environment with a
   ZSYSTEM command, GT.M does not recognize any changes  to  the  terminal
   characteristics left  by  the  external  environment.  This  may  cause
   disparities between the physical behavior  of  the  terminal,  and  the
   perceived behavior by GT.M.

   UNIX enforces standard device security for explicit OPENs of terminals
   other than the sign-in terminal ($PRINCIPAL). If you are unable to OPEN
   a terminal, contact your system manager.

   USE of a terminal causes the device driver to flush the output buffer.
   This feature of the USE  command  provides  routine  control  over  the
   timing of output, which is  occasionally  required.  However,  it  also
   means that redundant USE commands may induce an unnecessary performance
   penalty. Therefore, Sanchez Computer Associates recommends restricting
   USE  commands  to  redirecting  I/O,  modifying  deviceparameters,  and
   initiating specifically required flushes.

3 Logical_Rec_for_Term
   Logical Records for Terminals

   A logical record for a terminal equates  to  a  line  on  the  physical
   screen. The WIDTH device characteristic  specifies  the  width  of  the
   screen, while the LENGTH device characteristic specifies the number of
   lines on the screen.

3 READ_Comm_for_Term
   READ* Command for Terminals

   If the terminal has ESCAPE sequencing enabled, and the input contains a
   valid escape sequence or a terminator character,  the  terminal  device
   driver stores  the  entire  sequence  in  $ZB  and  returns  the  ASCII
   representation of the first character.

   Example:

   GTM> KILL

   GTM> USE $P:ESCAPE

   GTM> READ *X SET ZB=$ZB ZWRITE

   (Press the F11 key on the VT220 terminal keyboard)
   x=27

   zb=$C(27)_"[23~"

   This enters an escape sequence in response to a  READ  *.  The  READ  *
   assigns the code for <ESC> to the  variable  X.  The  terminal  handler
   places  the  entire  escape  sequence  in  $ZB.  Because  some  of  the
   characters are not graphic, that is, visible on a terminal, the example
   transfers the contents of $ZB to the  local  variable  ZB  and  uses  a
   ZWRITE so that the non-graphic characters appear in $CHAR() format.

   The READ * command for  terminals  does  not  affect  $ZB  when  escape
   sequencing is not  enabled.  If  the  input  contains  a  valid  escape
   sequence and escape sequencing is not enabled,  the  variable  for  the
   READ * command returns the first character of the escape sequence, for
   example, ASCII 27. The terminal  device  driver  stores  the  remaining
   characters of the escape sequence in the read buffer.  A  READ  command
   following a READ * command returns  the  remaining  characters  of  the
   escape sequence.  An  application  that  operates  with  NOESCAPE  must
   provide successive READ *  commands  to  remove  the  remaining  escape
   characters from the buffer.

   Example:

   GTM> KILL

   GTM> USE $P:(NOESCAPE:TERM=$C(13))

   GTM> READ *X SET ZB=$ZB READ Y:0 ZWRITE

   (Press the F11 key on the terminal keyboard)
   [23~i=5
   x=27

   y="[23~"

   zb=""

   GTM> USE $P:NOECHO READ *X S ZB=$ZB READ Y:0 USE $P:ECHO ZW

   i=5

   x=27

   y="[23~"

   zb=""

   GTM> READ *X SET ZB=$ZB USE $P:FLUSH READ Y:0 ZWRITE

   i=5

   x=27

   y=""

   zb=""

   While the first  READ  Y:0  picks  up  the  sequence  after  the  first
   character, notice how the graphic portion of the  sequence  appears  on
   the terminal - this  is  because  the  READ  *X  separated  the  escape
   character from the  rest  of  the  sequence  thus  preventing  the  VMS
   terminal  driver  logic  from  recognizing  it  as  a  sequence,  and
   suppressing its echo. The explicit suppression  of  echo  removes  this
   visual artifact. In the case of the final READ *X, the FLUSH clears the
   input buffer so that it is empty by the time of the READ Y:0.

3 READmaxlen_Comm_for_Term
   READ X#maxlen Command for Terminals

   Generally, GT.M performs  the  same  maintenance  on  $ZB  for  a  READ
   X#maxlen as for a  READ.  However,  if  the  READ  X#maxlen  terminates
   because the input has reached the maximum  length,  GT.M  sets  $ZB  to
   null. When the terminal has ESCAPE sequencing enabled,  and  the  input
   contains an escape sequence that does not fit in the read buffer, GT.M
   sets $ZB to contain the escape sequence.

3 Term_Examples
   Terminal Examples

   This section contains examples of GT.M terminal handling.

   Example:

   USE $PIECE:(exception="zg "_$zl_":C^MENU")

   This example USEs the  principal  device,  and  sets  up  an  EXCEPTION
   handler. When an EXCEPTION occurs, it transfers control to label  C  in
   the routine ^MENU at the process stack level where  the  EXCEPTION  was
   established.

   Example:

   USE $PIECE:(X=0:Y=0:CLEARSCREEN)

   This example positions the cursor to the  upper  left-hand  corner  and
   clears the entire screen.

   Example:

   USE $PIECE:(NOECHO:WIDTH=132:WRAP)

   This example disables ECHOing, enables automatic WRAPping, and sets the
   line width to 132 characters.

   Example:

   USE $PIECE:NOCENABLE

   This example disables <CTRL-C>.

2 Sequential_Files
   Using Sequential Files

   GT.M provides access to sequential files  both  on  disk.  These  files
   allow linear access to records. Sequential files  are  used  to  create
   programs, store reports, and to communicate with facilities outside of
   GT.M.

3 Setting_Seq_File_Charc
   Setting Sequential File Characteristics

   The ANSI standard specifies that when a process CLOSEs and then reOPENs
   a device, GT.M restores any characteristics  not  explicitly  specified
   with deviceparameters to the values they had prior to the  last  CLOSE.
   However, because it is difficult for a large menu-driven application to
   ensure the previous OPEN state, GT.M always sets unspecified sequential
   file characteristics to their default value on OPEN. This approach also
   reduces potential memory overhead imposed by  OPENing  and  CLOSEing  a
   large number of sequential files during the life of a process.

   GT.M does not restrict multiple OPEN commands. However, if  a  file  is
   already open, GT.M ignores attempts  to  modify  sequential  file  OPEN
   characteristics, except for RECORDSIZE and  for  deviceparameters  that
   also exist for USE.

   Sequential files can be READONLY, or read/write (NOREADONLY).

   Sequential files can be composed of either FIXED or VARIABLE (NOFIXED)
   length records. By default, records have VARIABLE length.

   UNIX enforces its standard security when GT.M OPENs a sequential file.
   This includes any directory access required to  locate  or  create  the
   file. If you are unable to OPEN a file, contact your system manager.

3 SeqFile_Pointers
   Sequential File Pointers

   Sequential file I/O operations use a construct called a  file  pointer.
   The file pointer logically identifies the next record to read or write.
   OPEN commands position the file pointer at the beginning  of  the  file
   (REWIND) or at the end-of-file (APPEND).  APPEND  cannot  reposition  a
   file currently open. Because the position of each record depends on the
   previous record, a WRITE destroys the ability to reliably position the
   file pointer to subsequent records in a  file.  Therefore,  by  default
   (NOTRUNCATE), GT.M  permits  WRITEs  only  when  the  file  pointer  is
   positioned at the end of the file.

   If a device has TRUNCATE enabled, a WRITE issued when the file pointer
   is not at the end of the file causes all  contents  after  the  current
   file pointer to be discarded. This effectively moves  the  end  of  the
   file to the current position and permits the WRITE.

3 SeqFile_Examples
   Sequential File Examples

   This section contains a few brief  examples  of  GT.M  sequential  file
   handling.

   Example:

   FREAD READ "File > ",sd

   OPEN sd:(readonly:exception="g BADOPEN")

   USE sd:exception="G EOF"

   FOR USE sd READ x USE $P WRITE x,!

   EOF IF '

   $ZEOF ZM +$ZS

   CLOSE sd

   QUIT

   BADOPEN IF $P($ZS,",",1)=2 DO QUIT

   . WRITE !,"The file ",sd," does not exist."

   IF $P($ZS,",",1)=13 DO QUIT

   . WRITE !,"The file ",sd," is not accessible."

   ZM +$ZS

   QUIT

   This example OPENs a file READONLY  and  specifies  an  EXCEPTION.  The
   exception  handler  for  the  OPEN  deals  with  file-not-found  and
   file-access errors, and reissues all other  errors  with  the  ZMESSAGE
   command. The first USE sets the EXCEPTION to  handle  end-of-file.  The
   FOR loop reads the file one record at a time and transfers each record
   to the principal device. The GOTO in the EXCEPTION terminates  the  FOR
   loop. At label EOF, if $ZEOF is false, the code reissues the error that
   triggered the exception. Otherwise, the CLOSE releases the file.

   Example:

   SET sd="temp.dat",acct=""

   OPEN sd:newversion U sd:width=132

   FOR SET acct=$O(^ACCT(acct)) QUIT:acct="" DO

   . SET rec=$$FORMAT(acct)

   . WRITE:$Y>55 #,hdr W !,rec

   CLOSE sd

   This OPENs a NEWVERSION of file temp.dat. The FOR loop  cycles  through
   the ^ACCT global formatting (not shown in this code fragment) lines and
   writing them to the  file.  The  FOR  loop  uses  the  argumentless  DO
   construct to break a long line of code into more manageable blocks. The
   program writes a header record (set up in initialization not, shown in
   this code fragment) every 55 lines, because  that  is  the  application
   page length, allowing for top and bottom margins.

2 FIFO_Charc
   FIFO Characteristics

   FIFOs have the same characteristics as other sequential  files,  except
   that READs and WRITEs can occur in any order.

   The following characteristics of FIFO behavior may be helpful in using
   them effectively.

   With
   READ:

   o    If a READ is done while there is no data in the FIFO:

   The process hangs until data is put into the FIFO by  another  process,
   or the READ times out, when a timeout is specified.
   With
   WRITE:

   o    If a process tries into write to a full  FIFO,  the  process  hangs
        until another process reads from the FIFO, emptying enough data to
        make room for the new data.

   While it is hung, the process will not respond to <CTRL-C>.

   With
   CLOSE:

   o    The FIFO is not deleted unless the DELETE qualifier is specified.

   o    If a process closes the FIFO with the DELETE  qualifier,  the  FIFO
        becomes unavailable to new users at that time.

   o    All processes currently USEing the FIFO may  continue  to  use  it,
        until the last process attached to it CLOSES it, and is destroyed.

   o    Any process OPENing a FIFO with the same name  as  a  deleted  FIFO
        creates a new one to which subsequent OPENs attach.

   A process must have read and write privileges on a FIFO to  access  it.
   File permissions have no affect on a process that already has the FIFO
   open.

3 Consider_Impl_FIFOs
   Considerations in Implementing FIFOs

   As  you  establish  FIFOs  for  interprocess  communication,  consider
   whether, and how, the following issues will be addressed:

   o    Do READs occur immediately, or can the process wait?

   o    Are timed READs useful to avoid system hangs and provide a  way  to
        remove the process?

   o    Does the WRITE process need to  know  whether  the  READ  data  was
        received?

   o    Will there be multiple processes READing and WRITEing into a single
        FIFO?

3 GTM_Recog_FIFOs
   GT.M Recognition of FIFOs

   Like other GT.M  devices  a  FIFO  can  be  specified  as  an  argument
   expression to the OPEN, USE, and CLOSE commands. A device OPENed with a
   FIFO qualifier becomes a FIFO unless another device  of  that  name  is
   already OPEN. In that case, OPENing a device that has  previously  been
   OPENed by another process as a FIFO causes  the  process  (the  process
   here is the process trying to open the FIFO) to attach to the existing
   FIFO.

3 FIFO_Devi_Ex
   FIFO Device Examples

   The following two examples represent a master/slave  arrangement  where
   the slave waits in a read state on the FIFO until the master  sends  it
   some data that it then processes.

   Example:

   set x="named.pipe"

   open x:fifo

   do getres

   use x write res,!

   This routine opens the FIFO, performs its own processing which includes
   starting the slave process (not shown in this code fragment).

   Example:

   set x="named.pipe"

   open x:fifo

   use x read res

   do process(res)

   This routine waits for information from the master process, then begins
   processing.

2 NULL_Devices
   Using NULL Devices

   The null device is accessed through /dev/null. A null  device  fulfills
   every input request by returning a null string  and  setting  $ZEOF.  A
   null device discards  all  output.  GT.M  maintains  a  virtual  cursor
   position for null devices as it does for terminals.  Use  null  devices
   for program testing and debugging, or for jobs that permit  I/O  to  be
   discarded under certain circumstances. For example, JOB processes must
   have input and output devices associated with them, even though they do
   not use them. Null devices are low overhead never-fail alternatives.

3 Null_Dev_Ex
   Null Device Examples

   Example:

   SET dev="/dev/null"

   OPEN dev USE dev

   SET x="" WRITE hdr,!,$ZDATE($h),?30,$J,!

   FOR SET x=$O(^tmp($J,x)) q:x="" DO REPORT

   CLOSE dev

   This program produces a report derived  from  the  information  in  the
   global variable ^tmp. The unspecified routine  REPORT  may  potentially
   contain a large amount of code. To see that the basic program functions
   without error, the programmer may discard the output involved in favor
   of watching the function. To run the program normally,  the  programmer
   simply has to change the variable dev to name another device.

   Example:

   JOB ^X:(IN="/dev/null":OUT="/dev/null":ERR= "error.log")

   This example issues a GT.M JOB command to execute  the  routine  ^X  in
   another process. This  routine  processes  a  large  number  of  global
   variables and produces no output. In the example,  the  JOBbed  process
   takes its input from a null device, and sends  its  output  to  a  null
   device. If the JOBbed process encounters an error, it directs the error
   message to error.log.

2 Socket_Devices
   Using Socket Devices

   SOCKET devices are used to access  and  manipulate  sockets.  A  SOCKET
   device can have from zero (0) to 64 associated sockets.  At  any  time,
   only one socket from the collection can be the current socket. If there
   is no current socket, an attempt to READ from, or WRITE to the device,
   generates an error.

   Sockets can be attached and detached from  the  collection  of  sockets
   associated with a device. Detached sockets belong  to  a  pseudo-device
   called the "socketpool". A process can detach a socket  from  a  device
   and later attach it to the same device or another device.

        The GT.M socket device interface does not have the ability to pass
        sockets between related or  unrelated  processes.  Currently  error
        trapping operates on a device, rather than on a socket.

3 Msg_Mgmt
   Message Management

   From an application perspective, the transport layers used by a socket
   device are stream-oriented  media,  with  no  provisions  for  implicit
   application messages. Therefore, the following are two common protocols
   used to segment application messages.

   o    One method is to use  a,  typically  small,  fixed  length  message
        containing the length of the next,  variable  length,  message.  In
        GT.M a simplistic writer might be:

   Write $Justify($Length(x),4),x

   A corresponding simplistic reader might be:

   Read len#4,x#len

   The advantage of this approach is that the message content  (the  value
   of x in the code  fragments  above)  can  contain  any  character.  The
   disadvantage  is  that  detecting  that  the  protocol  has  become
   desynchronized is a problem.
   o    The other common method  is  to  place  a  delimiter  between  each
        application message. The protocol breaks if a message ever includes
        a delimiter as part of its content.

   The SOCKET device has  the  capability  to  handle  delimiters  because
   parsing messages for delimiters is cumbersome.

3 Msg_Delimi
   Message Delimiters

   Each device can have from zero (0) to 64 delimiters associated with it.
   Each delimiter can be from one (1) to 64 characters. All the delimiters
   declared for a device are  valid  for  any  READ  from  any  associated
   socket, which means, any of the defined delimiters terminate the READ.
   The actual terminating delimiter is available in $KEY.  A  WRITE  to  a
   socket associated with a device with one or more delimiters inserts the
   first of the delimiters for any WRITE ! format.

3 Read_Comm
   READ Command

   The READ  command  may  be  used  to  obtain  data  from  a  socket.  A
   non-fixed-length read, with no timeout and  no  delimiters  requires  a
   complex implementation of sequence of READs  to  ensure  a  predictable
   result. This is because the transport layer stream fragments delivered
   to the reader has only accidental correspondence  with  the  operations
   performed by the writer. For example, the following

   Write "Message 1","Message 2"

   is presented to the reader as the stream "Message1Message2" but it can
   take from one (1) to 18 READ commands to retrieve the entire stream.

3 Write_Comm
   WRITE Command

   The WRITE command sends data to a socket.

   The WRITE command for SOCKET devices accepts following controlmnemonics
   on a bound socket:


   /L[ISTEN][(numexpr)]

   Where numexpr is in the range 1-5 and specifies the listen queue depth.


   /W[AIT][(timeout)]

   Where timeout is a "numexpr" that specifies how long a server waits for
   a connect before returning control to the GT.M routine.

   "WRITE !" inserts the character(s) of the first I/O delimiter (if any)
   to the sending  buffer.  If  "ZFF=expr"  has  been  used  to  define  a
   delimiter,  "WRITE  #"  inserts  the  characters  of  that  delimiter.
   Otherwise WRITE # has no effect on the  stream  content.  WRITE  !  and
   WRITE # always maintain $X and $Y in a fashion that emulates a terminal
   cursor position.

3 Socket_Devi_Ops
   Socket Device Operation

   Each socket may be in one of the following states:

   o    Created - indicates that the socket exists.

   o    Bound - indicates that the socket exists and is bound to a port; a
        "Bound socket" needs a listen  queue  which  currently  requires  a
        WRITE /LISTEN [after a USE].

   o    Connected - indicates that the socket exists and has a connection.

   A server socket used for accepting new  connections  goes  through  the
   first two states in one step with a single OPEN or in two steps with an
   OPEN and a USE. When a server does a WRITE /WAIT on a Bound  socket,  a
   client can establish a connection which Creates another  server  socket
   that is Connected. In server operation, $KEY supplies  the  port  value
   when a socket is bound (important when port 0 is specified to  get  the
   system to choose the port), and a socket id when a Connected socket is
   created. A client socket goes through the first and third states with a
   single OPEN or in two steps with an OPEN and a USE.

3 Socket_Devi_Ex
   Socket Device Examples

   This section contains examples on Socket Device usage.


   ;server.m

   Set portno=6321,delim=$c(13)

   Set tcpdev="server$"_$j,timeout=30

   Open tcpdev:(ZLISTEN=portno_":TCP":attach="server"):timeout:"SOCKET"

   Use tcpdev

   Write /listen(1)

   Write /wait(timeout)

   ;
   ;dialogue with the client

   ;
   ;client.m

   Set host="orlando"
   Set portno=6321
   Set delim=$c(13)
   Set tcpdev="client$"_$j,timeout=30
   O
   tcpdev:(connect=host_":"_portno_":TCP":attach="client"):timeout:"SOCKET"
   Use tcpdev
   ;
   ;dialogue with the server

   ;
2 IO_Comm
   I/O Commands

   This section describes the following GT.M I/O commands:

   o    OPEN establishes a connection from a GT.M process to a device.

   o    USE  declares  a  device  as  the  current  source  of  input  and
        destination for output.

   o    READ accepts characters from the current device into  a  global  or
        local variable.

   o    WRITE sends characters to the current device.

   o    CLOSE breaks the connection between a GT.M process and a device.

2 Open
   Open

   The OPEN command establishes a connection from  a  GT.M  process  to  a
   device.

   The format of the OPEN command is:

   O[PEN][:tvexpr] expr[:[(keyword[=expr][:...])][:numexpr][:expr]][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to OPEN.

   o    The optional keywords specify deviceparameters that control device
        behavior; some deviceparameters  take  arguments  delimited  by  an
        equal sign (=); if the argument only contains one deviceparameter,
        the surrounding parentheses are optional.

   o    The optional numeric expression specifies a time in  seconds  after
        which the command should timeout  if  unsuccessful;  0  provides  a
        single attempt to open the device.

   o    When  an  OPEN  command  specifying  a  timeout  contains  no
        deviceparameters, double colons (::) separate the  timeout  numeric
        expression from the device expression.

   o    The optional expression specifies a mnemonicspace  that  selects  a
        device binding. The only mnemonicspace that GT.M currently accepts
        is SOCKET.

   o    When an OPEN command specifies a  mnemonicspace  with  no  timeout,
        double colons separate the mnemonicspace string expression from the
        deviceparameters;  if  there  are  neither  a  timeout  nor
        deviceparameters, triple colons separate the mnemonicspace from the
        device expression.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more OPEN arguments form a legal argument for an OPEN.

   With the exception of FIFOs, UNIX device access is exclusive. READONLY
   sequential disk files may be shared among many readers, but no writers.
   Spooled devices are devices, usually printers, which buffer output from
   multiple sources, processing it after the writing  process  CLOSEs  the
   file. Spooled devices appear to GT.M as a  terminal  type  device.  For
   more information on spooled devices, refer to the UNIX System Manager's
   Manual. When one process successfully OPENs a  device  exclusively,  no
   other process can access that device until  the  first  process  CLOSEs
   that device.

   By default, when  a  device  is  unavailable,  GT.M  retries  the  OPEN
   indefinitely  at  approximately  one  second  intervals.  A  device  is
   unavailable when another process is using it exclusively, or  when  the
   OPENing process does not have the resources left to open the device.

   All other errors on OPEN raise an error condition and interrupt program
   flow. A timeout is a tool that  lets  a  GT.M  routine  regain  program
   control when a device remains unavailable. When the  OPEN  specifies  a
   timeout, GT.M keeps retrying until either  the  OPEN  succeeds  or  the
   timeout expires.

   If OPEN establishes a connection  with  a  device  before  the  timeout
   expires, GT.M sets $TEST to TRUE (1). If the timeout expires, GT.M sets
   $TEST to FALSE (0). If an OPEN command does not specify a timeout, the
   execution of the command does not affect $TEST.

   If a process has not previously OPENed a device within the  context  of
   an image, any deviceparameters not supplied  on  the  OPEN  take  their
   default values. When reOPENing a device that it  previously  closed,  a
   GT.M process restores all characteristics not specified on the OPEN to
   the values the  device  had  when  it  was  last  CLOSEd,  except  with
   sequential disk files. If you have a menu-driven application that OPENs
   and CLOSEs devices based on user selections, take care that every OPEN
   explicitly includes all deviceparameters important to the application.

   GT.M treats sequential disk files differently  and  uses  defaults  for
   unspecified sequential disk file characteristics on every  OPEN  (i.e.,
   GT.M does not retain sequential disk file characteristics on a CLOSE).

   If  a  process  OPENs  an  already  OPEN  device,  GT.M  modifies  any
   characteristics that accept changes when a device is  OPEN  to  reflect
   any new deviceparameter specifications.

3 Ex_of_Open
   Examples of OPEN

   Example:

   SET sd="report.dat" OPEN sd:NEWVERSION

   This OPENs a NEWVERSION of a sequential disk file named report.dat for
   both read and write access.

3 Open_DeviParam
   OPEN Deviceparameters

4 APPEND
   APPEND Applies to: Sequential Files

   Positions the file pointer at  the  end-of-file.  This  deviceparameter
   only affects the device  on  the  first  OPEN  command.  Re-OPENing  an
   already OPEN device with this deviceparameter has no effect.

   By default, OPEN sets the file pointer to the beginning-of-file.

4 ATTACH
   Attach=expr Applies to: Socket Device

   When ATTACH is used and one of ZLISTEN and CONNECT is specified at the
   same time, the value of  expr  becomes  the  identifier  of  the  newly
   created socket. If neither ZLISTEN nor CONNECT is specified, ATTACH is
   ignored.

4 BLOCKSIZE
   BLOCKSIZE=intexpr Applies to: Terminals and Printers

   Specifies the size in bytes of the maximum single read or write for the
   specified device.

4 CANONICAL
   [NO]CANONICAL Applies to: Terminals and Printers

   Enables or  disables  canonical  input  as  controlled  by  the  ICANON
   terminal attribute. See the documentation on your platform for details,
   but in general this would be erase and kill edit functions,  and  lines
   delimited by NL (usually <LF>), EOF (usually ^D), and EOL (usually not
   defined).

   By default, canonical input is enabled.

4 CONNECT
   CONNECT=expr Applies to: Socket Device

   Enables a client connection with a server,  which  is  located  by  the
   information provided by expr. A new socket is allocated for the client
   connection and is made the  current  socket  for  the  device,  if  the
   operation is successful.

   expr  specifies  the  protocol  and  protocol  specific  information.
   Currently, TCP/IP is the only protocol GT.M supports. expr should be of
   the format "<host>:<port>:TCP", where host is either an IP address or a
   hostname like server.sanchez.com.

        CONNECT is not compatible with ZLISTEN.

4 DELIMITER
   [NO]DELIMITER=expr Applies to: Socket Device

   DELIMITER establishes or replaces the list of delimiters  used  by  the
   sockets associated with the device. The default for on a  command  that
   first  OPENs  a  device  is  NODELIMITER.  The  delimiter  list  on  a
   preexisting device remains the same until it is explicitly replaced or
   deleted.

   expr must be a string of the following format:

   ':'  is  used  to  separate  delimiters  (it  is  the  delimiter  for
   delimiters).

   '/' serves as an escape character.

   expr "ab:/:://:bc" is interpreted as four delimiters, which  are  "ab",
   ":", "/", and "bc". One  socket  can  have  0-64  delimiters  and  each
   delimiter can contain 1-64 characters.

4 EXCEPTION
   EXCEPTION=expr Applies to: All devices

   Defines an error handler for an I/O device. The expression must contain
   a fragment of GT.M code (for example, GOTO ERRFILE) that  GT.M  XECUTEs
   when the driver for the device detects an  error,  or  an  entryref  to
   which  GT.M  transfers  control,  as  appropriate  for  the  current
   gtm_ztrap_form.

   For more information on error handling, refer to the "Error Processing"
   chapter in GT.M Programmer's Guide.

4 FIFO
   FIFO Applies to: FIFO

   Specifies that the device for the OPEN is a FIFO name. GT.M creates the
   FIFO if it does not already exist  and  if  the  process  has  adequate
   privileges. However, in the  event  that  the  process  does  not  have
   adequate privileges, the process generates a run-time error. A process
   does not require any privileges to OPEN an existing FIFO.

4 FIXED
   [NO]FIXED Applies to: Sequential Files and FIFO

   Selects a fixed record length format for sequential disk  files.  FIXED
   does not specify the actual length  of  a  record.  Use  RECORDSIZE  to
   specify the record length.

   NOFIXED specifies a variable length record format for  sequential  disk
   files. NOFIXED is a synonym for VARIABLE. FIXED  is  incompatible  with
   STREAM and VARIABLE.

   By default, records have VARIABLE length.

4 GROUP
   GROUP=expr Applies to: Sequential Files and FIFO

   Specifies access permission on a UNIX file for other users in the file
   owner's group. The expression is a character string evaluating to null
   or to any combination of the letters RWX, indicating respectively Read,
   Write, and eXecute access. When  any  of  the  permissions  controlling
   deviceparameters appears on an OPEN of a new file,  any  user  category
   (OWNER, SYSTEM, WORLD), that is not explicitly specified is  given  the
   default access permissions. When  any  one  of  these  deviceparameters
   appears on an OPEN of an existing device, any user category that is not
   explicitly specified remains unchanged.

   In order to modify file security, the user who  issues  the  OPEN  must
   have ownership.

   By default, OPEN does not modify the permissions on an  existing  file.
   Unless  otherwise  specified,  when  OPEN  creates  a  new  file,  it
   establishes security using standard defaulting rules.

4 IOERROR
   IOERROR=expr Applies to: Socket Device

   Enables exception handling in socket devices. expr  specifies  the  I/O
   error trapping mode. A value equal to "TRAP" specifies that I/O errors
   on a device raise error conditions. A value equal to "NOTRAP", or when
   IOERROR is not specified, indicates that I/O error on a device does not
   raise error conditions.

        GT.M currently handles exception handling at device  level  instead
        of socket level.

4 NEWVERSION
   NEWVERSION Applies to: Sequential Files and FIFO

   The NEWVERSION deviceparameter assures that when an  existing  file  is
   used, it is empty upon the OPEN.

   By default, if any version  of  the  file  exists,  OPEN  accesses  the
   current version. If  no  version  of  the  file  exists,  OPEN  without
   READONLY creates a new file.

4 OWNER
   OWNER=expr Applies to: Sequential Files and FIFO

   Specifies access permission on a UNIX file for the owner of  the  file.
   The expression is a character string  evaluating  to  null  or  to  any
   combination of the letters RWX, indicating  Read,  Write,  and  eXecute
   access. When any one of these deviceparameters appears on an OPEN of a
   new file, any user category that is not explicitly specified  is  given
   the default mask. When any one of these deviceparameters appears on an
   OPEN of an existing file, any user category (GROUP, SYSTEM, WORLD) that
   is not explicitly specified remains unchanged.

   To modify file security,  the  user  who  issues  the  OPEN  must  have
   ownership.

   By default, OPEN does not modify the permissions on an  existing  file.
   Unless otherwise specified, OPEN establishes  security  using  standard
   defaulting rules when it creates a new file.

4 READONLY
   [NO]READONLY Applies to: Sequential Files and FIFO

   OPENs a device for reading  only  (READONLY)  or  reading  and  writing
   (NOREADONLY).

   To open a sequential file using the READONLY parameter, the  file  must
   exist on the disk. If it does not, GT.M issues a run-time error.

   When GT.M encounters a WRITE directed to a file OPENed  READONLY,  GT.M
   issues a run-time error.

   By default, OPEN accesses the device or file NOREADONLY (read-write).

4 RECORDSIZE
   RECORDSIZE=intexpr Applies to: Sequential Files and FIFO

   Overrides the default record size for a  disk  and  specifies  the  new
   maximum record size in bytes.

4 REWIND
   REWIND Applies to: Sequential Files

   REWIND positions the file pointer of a sequential  disk  to  the  first
   record.

   By default, OPEN does not REWIND.

5 [NO]STREAM Applies to: SD
4 STREAM
   [NO]STREAM Applies to: Sequential Files

   STREAM and VARIABLE are essentially the same; VARIABLE is preferred.

   The combination of the STREAM and NOWRAP options on disk  files  allows
   you to write a record of arbitrary length. While each WRITE argument is
   truncated if it exceeds the WIDTH, the total record can be of arbitrary
   length. Note that, for efficiency,  the  compiler  combines  sequential
   literal arguments of a single WRITE into a single string  so  that  the
   run-time  system  considers  the  combined  length  of  the  sequence.
   Automatic record termination does not occur when record length exceeds
   the device width.

   By default, records are VARIABLE, NOSTREAM.

4 SYSTEM
   SYSTEM=expr Applies to: Sequential Files

   This deviceparameter is a synonym for OWNER that is maintained in UNIX
   for compatibility with VMS applications.

4 TRUNCATE
   [NO]TRUNCATE Applies to: Sequential Files and FIFO

   Enables or disables overwriting of existing  data  in  sequential  disk
   files. Because the position of each record depends on the prior record,
   a WRITE destroys the ability to reliably position to subsequent records
   in a file. Therefore, by default (NOTRUNCATE), GT.M permits WRITEs only
   when the file pointer is positioned at the end-of-file. When  a  device
   has TRUNCATE enabled, a WRITE issued when the file pointer  is  not  at
   end-of-file truncates the file by destroying all  data  from  the  file
   pointer to the end-of-file.

   By default, OPEN accesses the file NOTRUNCATE.

4 UIC
   UIC=expr Applies to: Sequential Files and FIFO

   Specifies the group that has access to the  file.  The  format  of  the
   string is "g,i" where g is a  decimal  number  representing  the  group
   portion of  the  UIC  and  i  is  a  decimal  number  representing  the
   individual portion. A process with the VMS privilege CMKRNL may set the
   file UIC to a UIC other than the UIC under which it is running, thereby
   giving ownership of the file to another user.

   Specifies the owner and affects access  to  the  file.  The  expression
   evaluates to the numeric identifier of the new owner.

4 VARIABLE
   VARIABLE Applies to: Sequential Files and FIFO

   Specifies the VARIABLE record length format for sequential disk files.

   By default, records have VARIABLE length.

4 WORLD
   WORLD=expr Applies to: Sequential Files and FIFO

   Specifies access permissions for users not in the owner's  group  on  a
   UNIX file. The expression is a character string evaluating to  null  or
   to any combination of the letters RWX,  indicating  respectively  Read,
   Write, and eXecute access.  When  any  one  of  these  deviceparameters
   appears on an OPEN of a  new  file,  any  user  category  that  is  not
   explicitly specified is given the default character  string.  When  any
   one of these deviceparameters appears on an OPEN of an  existing  file,
   any user category  (OWNER,  GROUP,  SYSTEM),  that  is  not  explicitly
   specified remains unchanged.

   To modify file security,  the  user  who  issues  the  OPEN  must  have
   ownership.

   By default, OPEN and CLOSE do not modify the permissions on an existing
   file. Unless otherwise specified, when OPEN  creates  a  new  file,  it
   establishes security using standard defaulting rules.

4 WRAP
   [Z][NO]WRAP Applies to: FIFO, Sequential Devices, and Socket Device

   Enables or disables automatic  record  termination.  When  the  current
   record size ($X) reaches the maximum WIDTH  and  the  device  has  WRAP
   enabled, GT.M starts a new record, as if the routine had issued a WRITE
   ! command.

   NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP
   allows $X to become greater than the device  WIDTH  for  terminals  and
   null devices.

   The combination of STREAM and NOWRAP options on disk files  allows  you
   to write a record of arbitrary length. Without the STREAM  option,  the
   WRAP option determines the action taken when the record length exceeds
   the device WIDTH. NOWRAP causes GT.M to truncate the record, while WRAP
   causes GT.M to insert a format control character.

   By default, records WRAP.

4 ZBFSIZE
   ZBFSIZE Applies to: Socket Devices

   Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE
   deviceparameter should be at  least  as  big  as  the  largest  message
   expected.

   By default, the size of ZBFSIZE is 1024 and the maximum it  can  be  is
   1048576.

4 ZDELAY
   Z[NO]DELAY Applies to: Socket Devices

   Controls buffering of data packets by the system TCP  stack  using  the
   TCP_NODELAY option to the SETSOCKOPT  system  call.  This  behavior  is
   sometimes known as the Nagle algorithm. The  default  is  ZDELAY.  This
   delays sending additional packets until either  an  acknowledgement  of
   previous packets is received or an interval passes. If several packets
   are sent from one end of a connection before the  other  end  responds,
   setting ZNODELAY may be desirable though  at  the  cost  of  additional
   packets being transmitted over the  network.  ZNODELAY  must  be  fully
   spelled out.

4 ZFF
   Z[NO]FF=expr Applies to: Socket Device

   expr specifies a string of characters, typically in $CHAR()  format  to
   send to socket device, whenever a routine issues a  WRITE  #.  When  no
   string is specified or when ZFF="", then no characters  are  sent.  The
   default in GT.M is ZNOFF.

4 ZIBFSIZE
   ZIBFSIZE Applies to: Socket Device

   Sets  the  buffer  size  used  by  the  network  software  (setsockopt
   SO_RCVBUF).

   The default and the maximum values depend on the platform and/or system
   parameters.

4 ZLISTEN
   ZLISTEN=expr Applies to: Socket Device

   A new socket is allocated to listen for a connection. It  is  made  the
   current socket for the device, if the  operation  is  successful.  Upon
   successful completion, $KEY is set to the format of
   "BOUND|<socket handle>|<port number>"

   otherwise, $KEY is assigned the empty string.

   expr  specifies  the  protocol  and  protocol  specific  information.
   Currently, TCP/IP is the only protocol GT.M supports. expr must  be  of
   the format "<port>:TCP", where port specifies the port number at which
   the socket is waiting for a connection.

        ZLISTEN is not compatible  with  ATTACH  in  the  USE  command  and
        CONNECT in both USE and OPEN commands.

2 Use
   Use Command

   The USE command selects the current device for READs (input) and WRITEs
   (output).

   The format of the USE command is:

   U[SE][:tvexpr] expr[:(keyword[=expr][:...])][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to  make  the  current
        device.

   o    A USE that selects a device not currently  OPENed  by  the  process
        causes a run-time error.

   o    The optional keywords specify deviceparameters that control device
        behavior; some deviceparameters  take  arguments  delimited  by  an
        equal  sign  (=).  If  there  is  only  one  deviceparameter,  the
        surrounding parentheses are optional.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more USE arguments form a legal argument for a USE.

   The intrinsic special variable $IO identifies the  current  device,  so
   GT.M directs all READs and WRITEs to $IO. When  a  GT.M  image  starts,
   $PRINCIPAL is implicitly OPENed and USEd. Once the GT.M  image  USEs  a
   device, $IO holds the name of that device until the next USE command.

   A  USE  command  modifies  the  device  in  accordance  with  the
   deviceparameters that apply to the device type and ignores  those  that
   do not apply. Characteristics set  with  USE  deviceparameters  persist
   until  another  USE  for  the  same  device  with  the  corresponding
   deviceparameter. Characteristics persist through USEs of other devices
   and, except for  sequential  files,  through  a  subsequent  CLOSE  and
   re-OPEN.

   Example:

   USE $P:(X=0:Y=$Y-1:NOECHO)

   This example USEs the principal device. If that device is  a  terminal,
   the deviceparameters turn off echo  and  position  the  cursor  to  the
   beginning of the previous line.

3 Use_DeviParam
   Use Deviceparameters

4 ATTACH
   ATTACH=expr Applies to: Socket Device

   When ATTACH is used and one of ZLISTEN and CONNECT is specified at the
   same time, the value of  expr  becomes  the  identifier  of  the  newly
   created socket. If neither  ZLISTEN  nor  CONNECT  is  specified,  expr
   specifies the socket to be moved from  the  socketpool  to  the  socket
   device argument of USE.

4 CANONICAL
   [NO]CANONICAL Applies to: Terminals and Printers

   Enables or  disables  canonical  input  as  controlled  by  the  ICANON
   terminal attribute. See the documentation on your platform for details,
   but in general this would be erase and kill edit functions,  and  lines
   delimited by NL (usually <LF>), EOF (usually ^D), and EOL (usually not
   defined).

   By default, canonical input is enabled (that is  [NO]CANONICAL  is  the
   default).

4 CENABLE
   [NO]CENABLE Applies to: Terminals and Printers

   Enables or disables the ability to  force  GT.M  into  Direct  Mode  by
   entering <CTRL-C> at $PRINCIPAL.

   [NO]CENABLE is subordinate to a CTRAP that includes <CTRL-C> ($C(3)).

   By default, images have CENABLEd.

4 CLEARSCREEN
   CLEARSCREEN Applies to: Terminals and Printers

   Clears the terminal screen from the  present  cursor  position  to  the
   bottom of the screen. The CLEARSCREEN deviceparameter does  not  change
   the cursor position or the $X and $Y variables.

   Example:

   U $P:(X=0:Y=0:CLEAR)

   This example positions the cursor to "home" in the upper left corner of
   a VDT and clears the entire current screen "page."

4 CONNECT
   CONNECT=expr Applies to: Socket Device

   Enables a client connection with a server,  which  is  located  by  the
   information provided by expr. A new socket is allocated for the client
   connection and is made the  current  socket  for  the  device,  if  the
   operation is successful.

   expr  specifies  the  protocol  and  protocol  specific  information.
   Currently, TCP/IP is the only protocol GT.M supports. expr should be of
   the format "<host>:<port>:TCP", where host is either an IP address or a
   hostname like server.sanchez.com.

        CONNECT is not compatible with ZLISTEN.

4 CONVERT
   [NO]CONVERT Applies to: Terminals and Printers

   Enables  or  disables  the  terminal  device  driver  from  converting
   lowercase input to uppercase during READs.

   By default, the terminal device driver operates NOCONVERT.

4 CTRAP
   CTRAP=expr Applies to: Terminals and Printers

   Establishes the <CTRL> characters in the expression as trap characters
   for the current device. When the terminal device driver receives a trap
   character in the input from a device, GT.M issues a run-time exception.
   The device does not have to be the current device, that is $IO.

   The <CTRL> characters are ASCII 0 though 31.

   For example, the command U $P:CTRAP=$C(26,30,7,19) sets a trap for the
   ASCII characters <SUB>, <RS>, <BEL> and <DC3>.

   Specifying CTRAP completely replaces the previous CTRAP  list.  Setting
   CTRAP to the null string ("") disables character trapping.

   A trap character  enabled  by  CTRAP  produces  one  of  the  following
   actions:

   o    If an EXCEPTION deviceparameter has been issued for the device, the
        process executes the EXCEPTION argument.

   o    Otherwise, if $ETRAP is not the empty string, execute $ETRAP.

   o    Otherwise, if $ZTRAP is not the empty string, the process executes
        $ZTRAP.

   o    Otherwise, the GT.M image terminates.

   For more information on error handling, refer to the "Error Processing"
   chapter in GT.M Programmer's Guide.

   When CTRAP includes <CTRL-C>,  [NO]CENABLE  has  no  effect.  CTRAPping
   <CTRL-C> also takes precedence over CENABLE.

4 DELIMITER
   [NO]DELIMITER Applies to: Socket Device

   DELIMITER establishes or replaces the list of delimiters  used  by  the
   sockets associated with the device. The default when the socket device
   is first OPENed is NODELIMITER. The delimiter  list  on  a  preexisting
   device remains the same until it is explicitly replaced or deleted.

   expr must be a string of the following format:

   ':'  is  used  to  separate  delimiters  (it  is  the  delimiter  for
   delimiters).

   '/' serves as an escape character.

   expr "ab:/:://:bc" is interpreted as four delimiters, which  are  "ab",
   ":", "/", and "bc". One  socket  can  have  0-64  delimiters  and  each
   delimiter can contain 1-64 characters.

4 DETACH
   DETACH=expr Applies to: Socket Device

   Removes the socket identified by expr from the current  socket  device,
   without affecting any existing connection of that socket.  The  removed
   socket is placed in the socketpool  and  may  be  attached  to  another
   socket device. If the socket being removed is the current socket, then
   GT.M does the following:

   o    The socket ATTACHed prior to the removed socket, is  made  current,
        if one such exists.

   o    The socket ATTACHed after the removed socket, is made  current,  if
        the removed one was the first socket.

   o    $PRINCIPAL is made the current device ($IO), if the removed socket
        was the only one in the current socket device.

4 DOWNSCROLL
   DOWNSCROLL Applies to: Terminals and Printers

   If $Y=0, DOWNSCROLL  does  nothing.  Otherwise,  DOWNSCROLL  moves  the
   cursor up one line on the terminal screen and  decrements  $Y  by  one.
   DOWNSCROLL does not change the column position  or  $X.  Some  terminal
   hardware may not support DOWNSCROLL.

4 ECHO
   [NO]ECHO Applies to: Terminals and Printers

   Enables or disables terminal device driver echo of input.

   By default, terminal device drivers ECHO.

4 ERASELINE
   ERASELINE Applies to: Terminals and Printers

   Clears the current line from the physical cursor position to the end of
   the line. ERASELINE does not affect the physical cursor position, or $X
   and $Y.

4 ESCAPE
   [NO]ESCAPE Applies to: Terminals and Printers

   Enables  or  disables  terminal  device  driver  processing  of  escape
   sequences.

   The following events result  when  a  terminal  has  ESCAPE  sequencing
   enabled. When an <ESC> or <CSI> arrives  in  the  terminal  input,  the
   device driver verifies the sequence that follows as a valid ANSI escape
   sequence, terminates the READ, and  sets  $ZB  to  contain  the  entire
   escape sequence. In this case, if the sequence starts  with  an  <ESC>,
   READ * returns the decimal ASCII representation for  the  character  of
   the escape introducer.

   When escape processing is disabled, READ *x returns  27  in  x  for  an
   <ESC>. If the escape introducer is also a TERMINATOR, $ZB has a string
   of length one (1), and a value of the $ASCII()  representation  of  the
   escape introducer; otherwise, $ZB holds the empty  string.  For  single
   character and short fixed reads  with  NOESCAPE,  the  terminal  device
   driver places the remaining characters of the escape  sequence  in  the
   input buffer for subsequent READs, regardless of [NO]TYPEAHEAD."

4 EXCEPTION
   EXCEPTION=expr Applies to: All devices

   Defines an error handler for an I/O device. The expression must contain
   a fragment of GT.M code (e.g., GOTO ERRFILE) that GT.M XECUTEs when the
   driver for the device detects an error, or an entryref  to  which  GT.M
   transfers control, as appropriate for the current gtm_ztrap_form.

   For more information on error handling, refer to the "Error Processing"
   chapter in GT.M Programmer's Guide.

4 FILTER
   [NO]FILTER[=expr] Applies to: Terminals and  Printers,  Socket  Device,
   and NULL Device

   Specifies  character  filtering  for  valid  filtering  expressions.
   Filtering requires character by character examination of all output and
   reduces I/O performance.

   Each FILTER  deviceparameter  can  have  only  one  argument.  However,
   multiple FILTER deviceparameters can appear in a  single  USE  command,
   each with different arguments.

   The valid values for expr:

   [NO]CHARACTERS enables or disables maintenance of $X and  $Y  according
   to the M ANSI standard for the characters <BS>, <LF>,  <CR>  and  <FF>.
   CHARACTERS causes the device driver to examine all output for the above
   characters, and to adjust $X  and  $Y  accordingly.  By  default,  GT.M
   performs special maintenance on $X and $Y only  for  M  format  control
   characters, WRAPped records, and certain action deviceparameters.

   [NO]ESCAPE alters the effect of ANSI escape sequences  on  $X  and  $Y.
   ESCAPE causes GT.M to filter the  output,  searching  for  ANSI  escape
   sequences and preventing them from updating $X and $Y. By default, GT.M
   does not screen output for escape sequences.

   By default, GT.M  does  not  perform  output  filtering.  For  GT.M  to
   maintain $X for non-graphic characters as described  by  the  standard,
   FILTER="CHARACTERS" must be enabled. Output filtering  adds  additional
   overhead to I/O processing.

4 HOSTSYNC
   [NO]HOSTSYNC Applies to: Terminals and Printers

   Enables or disables the use of XON/XOFF by the host to  throttle  input
   and  prevent  impending  buffer  overruns  for  a  terminal.  This
   deviceparameter  provides  a  control  mechanism  for  the  host  over
   asynchronous  communication  lines  to  help  prevent  data  loss  when
   hardware is slow and/or processing load is high.

   By default, the device driver operates HOSTSYNC.

4 IOERROR
   IOERROR=expr Applies to: Socket Device

   Enables exception handling in socket devices. expr  specifies  the  I/O
   error trapping mode. A value equal to "TRAP" specifies that I/O errors
   on a device raise error conditions. A value equal to "NOTRAP", or when
   IOERROR is not specified, indicates that I/O error on a device does not
   raise error conditions.

        GT.M currently handles exception handling at device  level  instead
        of socket level.

4 LENGTH
   [Z]LENGTH=intexpr Applies to: Terminals and  Printers,  Socket  Device,
   and NULL Device.

   Sets the  virtual  page  length  for  an  I/O  device  to  the  integer
   expression. The page length controls the  point  at  which  the  device
   driver automatically resets $Y to 0.

   By  default,  GT.M  uses  the  LENGTH  specified  by  the  device
   characteristics at image activation. The terminal  default  depends  on
   the type of terminal. The default length for  null  device  and  socket
   device is 66.

4 PASTHRU
   [NO]PASTHRU Applies to: Terminals and Printers

   Enables or  disables  interpretation  of  the  ERASE  character  for  a
   terminal. PASTHRU shifts management of handling and response  to  ERASE
   characters in the input stream from the driver to the GT.M application
   code.

   Exercise caution with PASTHRU in debugging,  because  using  a  PASTHRU
   terminal in Direct Mode is somewhat awkward.

   [NO]TTSYNC must be used with [NO]PASTHRU to control XON/XOFF handling.

   By default, the device driver operates NOPASTHRU.

4 READSYNC
   [NO]READSYNC Applies to: Terminals and Printers

   Enables or disables automatic output of <XON> before a READ and <XOFF>
   after a READ.

   By default, the terminal drivers operate NOREADSYNC.

4 REWIND
   REWIND Applies to: Sequential Files

   REWIND for a disk file is a logical rather than a physical operation.

   By default, USE does not REWIND.

4 SOCKET
   SOCKET=expr Applies to: Socket Device

   The socket specified in expr is made the current socket.  Specifying  a
   socket that has not been previously OPENed generates an error.

        SOCKET is compatible with DELIMITER only.

4 TERMINATOR
   [NO]TERMINATOR[=expr] Applies to: Terminals and Printers

   Specifies which of the 256  ASCII  characters  terminate  a  READ.  For
   example, TERMINATOR=$C(0) makes <NUL> the terminator.

   When [NO]ESCAPE is in effect, TERMINATOR controls whether or not <ESC>
   or <CSI> are treated as terminators, however, when ESCAPE processing is
   enabled,  the  entire  escape  sequence  is  treated  as  a  terminator
   regardless of the TERMINATOR specification.

   NOTERMINATOR eliminates  all  terminators.  When  a  terminal  has  all
   terminators disabled, fixed length READ and READ * terminate on receipt
   of some number of characters, and a timed READ terminates  on  timeout,
   but any other READ only terminates when the input  fills  the  terminal
   read buffer.

   By default, terminals recognize <CR> and <ESC> as  terminators,  (i.e.,
   TERMINATOR=$C(13,27)). TERMINATOR=""  restores  the  default.  However,
   unless the terminal has PASTHRU, the operating system  interprets  some
   escape sequences rather than passing them to the READ.

   Example:

   GTM> USE $P:TERM=$C(26,13,11,7)

   This example enables the ASCII characters <SUB>, <CR>, <VT>  and  <BEL>
   as READ terminators.

4 TRUNCATE
   [NO]TRUNCATE Applies to: Sequential Files

   Enables or disables overwriting of existing data in  sequential  files.
   Because the position of each record depends  on  the  prior  record,  a
   WRITE destroys the ability to reliably position to  subsequent  records
   in a file. Therefore, by default (NOTRUNCATE), GT.M permits WRITEs only
   when the file pointer is positioned at the end-of-file. When  a  device
   has TRUNCATE enabled, a WRITE issued when the file pointer  is  not  at
   end-of-file truncates the file by destroying all  data  from  the  file
   pointer to the end-of-file.

   By default, OPEN  accesses  files  NOTRUNCATE,  which  does  not  allow
   overwriting of sequential files.

   This deviceparameter may not be supported by your platform.

4 TTSYNC
   [NO]TTSYNC Applies to: Terminals and Printers

        Enables or disables recognition of XON/XOFF for terminal output. A
        terminal may have its own handling of  XON/XOFF,  controlled  by  a
        set-up mode or by switches.  If  an  application  requires  program
        recognition of <CTRL-S> and <CTRL-Q>,  the  terminals  may  require
        reconfiguration.

4 TYPEAHEAD
   [NO]TYPEAHEAD Applies to: Terminals and Printers

   Enables  or  disables  type-ahead  buffering  for  a  terminal.  With
   NOTYPEAHEAD  and  no  outstanding  READ,  the  terminal  device  driver
   discards  input  entered  at  the  terminal.  With  TYPEAHEAD  and  no
   outstanding READ,  the  device  driver  stores  input  entered  at  the
   terminal in a type-ahead buffer. The device driver uses data  from  the
   type-ahead buffer for subsequent READs.

   The size of the type-ahead buffer limits the amount of data entered at
   the terminal that the device driver can store in anticipation of future
   READs.

   By default, the terminal device driver accepts TYPEAHEAD.

4 UPSCROLL
   UPSCROLL Applies to: Terminals and Printers

   Moves the cursor down one line on the terminal screen. If $Y=LENGTH-1,
   UPSCROLL sets $Y=0. Otherwise UPSCROLL increments $Y  by  one.  If  the
   cursor is physically at the bottom of the page, the screen  scrolls  up
   one line. UPSCROLL does not change the column position or $X.

4 WIDTH
   [Z]WIDTH=intexpr Applies to: Terminals  and  Printers,  Socket  Device,
   NULL Device, and Sequential Files

   Sets the device's logical record size and enables WRAP.

   NOWRAP and WIDTH supersede each other. When  WIDTH  and  NOWRAP  appear
   together on the same USE command, the final  one  controls  the  device
   behavior. For a terminal,  WIDTH=0  is  equivalent  to  WIDTH=n:NOWRAP,
   where n is the default length of a logical record on that terminal.

   Terminals inherit their default WIDTH in GT.M from the  invoking  shell
   environment. The default WIDTH for null and socket device is 255.

4 WRAP
   [Z][NO]WRAP Applies to: Terminals and Printers,  FIFO,  Socket  Device,
   NULL Device, and Sequential Files

   Enables or disables automatic  record  termination.  When  the  current
   record size ($X) reaches the maximum WIDTH  and  the  device  has  WRAP
   enabled, GT.M starts a new record, as if the routine had issued a WRITE
   ! command.

   NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP
   allows $X to become greater than the device WIDTH for terminals.

   By default, WIDTH sets WRAP. When WIDTH and NOWRAP appear  together  on
   the same USE command, the last one controls the device behavior.

   By default, records WRAP.

4 X
   X=intexpr Applies to: Terminals and Printers

   $X positions the cursor to a vertical column on the terminal. If NOWRAP
   is  enabled  or  intexpr<WIDTH,  the  terminal  device  driver  sets
   $X=intexpr.  If  WRAP  is  enabled  and  intexpr>WIDTH,  GT.M  sets
   $X=intexpr#WIDTH, where # is the GT.M modulo operator. The resulting $X
   determines the actual physical position.

   To ensure that $Y and $X  match  what  is  occurring  visually  on  the
   terminal, the GT.M deviceparameters and the device characteristics must
   match at all times. For example, if a process  initiates  a  subprocess
   that changes the terminal wrap  setting  from  NOWRAP,  to  WRAP,  GT.M
   returns to the NOWRAP condition  when  the  subprocess  completes,  and
   wraps on the terminal do not reflect in the values of $X and $Y.

   The terminal hardware may affect physical  cursor  positioning.  The  X
   deviceparameter does not change the cursor row or update $Y.

4 Y
   Y=intexpr Applies to: Terminals and Printers

   Positions the cursor to a horizontal row on the terminal.

   The terminal device driver sets $Y=intexpr#LENGTH, where # is the GT.M
   modulo operator. If intexpr<LENGTH, the  resulting  $Y  determines  the
   physical position. If intexpr>LENGTH, the cursor is positioned so that
   $Y=intexpr#LENGTH, where # is the GT.M module  operator.  The  terminal
   hardware may affect physical cursor positioning.

   To ensure that $Y and $X  match  what  is  occurring  visually  on  the
   terminal, the GT.M deviceparameters and the device characteristics must
   match at all times. For example, if a process  initiates  a  subprocess
   that changes the terminal wrap setting from NOWRAP, previously set with
   the GT.M USE command to WRAP, GT.M does not reflect the change when the
   subprocess completes. Therefore, wraps on the terminal do  not  reflect
   in the values of $X and $Y.

   The Y deviceparameter does not change the cursor column or update $X.

4 ZBFSIZE
   ZBFSIZE Applies to: Socket Device

   Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE
   deviceparameter should be at  least  as  big  as  the  largest  message
   expected.

   By default, the size of ZBFSIZE is 1024 and the maximum it  can  be  is
   1048576.

4 ZDELAY
   Z[NO]DELAY Applies to: Socket Device

   Controls buffering of data packets by the system TCP  stack  using  the
   TCP_NODELAY option to the SETSOCKOPT  system  call.  This  behavior  is
   sometimes known as the Nagle algorithm. The  default  is  ZDELAY.  This
   delays sending additional packets until either  an  acknowledgement  of
   previous packets is received or an interval passes. If several packets
   are sent from one end of a connection before the  other  end  responds,
   setting ZNODELAY may be desirable though  at  the  cost  of  additional
   packets being transmitted over the  network.  ZNODELAY  must  be  fully
   spelled out.

4 ZFF
   Z[NO]FF=expr Applies to: Socket Device

   expr specifies a string of characters, typically in $CHAR()  format  to
   send to socket device, whenever a routine issues a  WRITE  #.  When  no
   string is specified or when ZFF="", then no characters  are  sent.  The
   default in GT.M is ZNOFF.

4 ZIBFSIZE
   ZIBFSIZE Applies to: Socket Device

   Sets  the  buffer  size  used  by  the  network  software  (setsockopt
   SO_RCVBUF).

   The default and the maximum values depend on the platform and/or system
   parameters.

4 ZLISTEN
   ZLISTEN=expr Applies to: Socket Device

   A new socket is allocated to listen for a connection. It  is  made  the
   current socket for the device, if the  operation  is  successful.  Upon
   successful completion, $KEY is set to the format of
   "BOUND|<socket handle>|<port number>"

   otherwise, $KEY is assigned the empty string.

   expr  specifies  the  protocol  and  protocol  specific  information.
   Currently, TCP/IP is the only protocol GT.M supports. expr must  be  of
   the format "<port>:TCP", where port specifies the port number at which
   the socket is waiting for a connection.

2 Read
   Read

   The READ command transfers input from the current device to a global or
   local variable specified as a READ argument. For convenience, READ also
   accepts arguments that perform limited output to the current device.

   The format of the READ command is:

   R[EAD][:tvexpr] glvn|*glvn|glvn#intexpr|strlit|fcc[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    A subscripted  or  unsubscripted  global  or  local  variable  name
        specifies a variable into which to store the  input;  the  variable
        does not have to exist prior to the  READ;  if  the  variable  does
        exist prior to the READ, the READ replaces its old value.

   o    When an asterisk (*) immediately precedes the variable  name,  READ
        accepts one character of input and places the ASCII code  for  that
        character in the variable.

   o    When  a  number  sign  (#)  and  a  non-zero  integer  expression
        immediately  follow  the  variable  name,  the  integer  expression
        determines the maximum number of characters accepted  as  input  to
        the read; such reads  terminate  when  GT.M  reads  the  number  of
        characters specified by the integer expression or a  terminator  in
        the input stream, whichever occurs first.

   o    To provide a concise means of issuing prompts,  GT.M  sends  string
        literal and format control character (!,?intexpr,#) arguments of a
        READ to the current device as if they were arguments of a WRITE.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more READ arguments form a legal argument for a READ.

   The maximum length of the input string is the  smaller  of  the  device
   buffer size limitation  or  the  GT.M  maximum  string  length  (32,767
   characters). If a record is longer than the maximum record length, GT.M
   returns the record piece by piece during sequential reads, for devices
   that allow it.

   When a string literal appears as an argument to a READ,  M  writes  the
   literal to the current device. String literals appear as READ arguments
   to serve  as  prompts  for  input.  GT.M  does  not  permit  expression
   arguments on a READ to act as prompts. Variable prompts must appear as
   arguments to a WRITE. If a variable appears as an argument to  a  READ,
   GT.M always interprets it as input, never as output. This  facility  is
   used mostly with terminal I/O.

   The READ commands adjust $X and $Y, based on the length  of  the  input
   read.

3 Read_Comm
   READ * Command

   The READ * command reads one character  from  the  current  device  and
   returns the decimal ASCII representation of  that  character  into  the
   variable specified  for  the  READ  *  command.  READ  *  appears  most
   frequently in communication protocols, or in interactive programs where
   single character answers are appropriate.

   The following example reads the value  "A",  and  returns  the  decimal
   ASCII representation of "A" in the variable X.

   Example:

   GTM> READ *X

   A

   GTM> WRITE X

   65
   If a timeout occurs before GT.M reads a character, the READ * returns a
   negative one (-1) in the variable.

3 Read_maxlen_Comm
   READ X#maxlen Command

   The READ X#maxlen command limits the maximum size of  the  input  to  a
   maximum of "maxlen" characters, where maxlen is an integer expression.

   If a READ follows  a  READ  X#maxlen  command,  the  READ  returns  the
   remainder of the current record.

   If a terminator arrives before maxlen characters are received the READ
   X#maxlen terminates.

2 Write
   Write

   The WRITE  command  transfers  a  character  stream  specified  by  its
   arguments to the current device.

   The format of the WRITE command is:

   W[RITE][:tvexpr] expr|*intexpr|fcc[,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    An expression argument supplies the text of a WRITE.

   o    When a WRITE argument consists of a leading asterisk  (*)  followed
        by an integer expression, WRITE outputs  one  character  associated
        with the ASCII code specified by  the  integer  evaluation  of  the
        expression.

   o    WRITE also accepts format control characters as  arguments;  format
        control characters modify the position  of  a  virtual  cursor:  an
        exclamation  point  (!)  produces  the  device  specific  record
        terminator (for example, new line for a terminal),  a  number  sign
        (#) produces device specific page  terminator  (for  example,  form
        feed for a terminal)  and  a  question  mark  (?)  followed  by  an
        expression moves the virtual cursor to the column specified by the
        integer evaluation of the expression if the virtual  cursor  is  to
        the "left" of the specified column.

   o    When directed to a device bound  to  a  mnemonicspace,  WRITE  also
        accepts  controlmnemonics,  which  are  keywords  specific  to  the
        binding - they are delimited by a slash (/) prefix  and  optionally
        followed by a parenthetical list of arguments. The  parentheses  "(
        )" are optional when there are no arguments, but must  appear  even
        if there is a single argument

   o    An indirection operator and an expression atom evaluating to a list
        of one or more WRITE arguments form a legal argument for a WRITE.

   GT.M can write up to 32,767 bytes (the GT.M maximum string length) as a
   result of a single WRITE argument. GT.M buffers output into a "logical
   record"  for  all  devices  except  sockets  without  DELIMITERs  and
   sequential devices with STREAM enabled. The  WRITE  command  appends  a
   string to the current record of the current device. GT.M does not write
   to the output device until the buffer is full, a  GT.M  format  control
   character forces a write, a USE  command,  a  CLOSE  command,  or,  for
   terminals, the buffer becomes stale.

   Each device has a WIDTH and a LENGTH that define  the  virtual  "page".
   The WIDTH determines the maximum size of a record for a  device,  while
   the LENGTH determines how many records fit on a page. When the current
   record size ($X) reaches the maximum WIDTH  and  the  device  has  WRAP
   enabled, GT.M starts a new record. When the current line  ($Y)  reaches
   the maximum LENGTH, GT.M starts a new page.

   A WRITE with an asterisk preceding the argument, which it would expect
   to  be  a  decimal  ASCII  representation,  writes  the  character
   corresponding to the ASCII representation. The WRITE command  also  has
   several format control characters that allow the  manipulation  of  the
   virtual cursor. For all I/O devices, the GT.M format control characters
   do the following:

        WRITE ! Clears $X and increments  $Y  and  terminates  the  logical
        record in progress. The definition of "logical record" varies from
        device to device, and is discussed in each device section.
        WRITE # Clears $X and $Y  and  terminates  the  logical  record  in
        progress.
        WRITE ?n If n is greater than $X, writes n-$X spaces to the device,
        bringing $X to n. If n is less than or equal to $X, WRITE ?n has no
        effect. When WRAP is enabled and n exceeds the LENGTH of the line,
        WRITE ?n increments $Y.
   For more information, refer to the sections on specific I/O devices.

2 Close
   Close

   The CLOSE command breaks the connection between a process and a device.

   The format of the CLOSE command is:

   C[LOSE][:tvexpr] expr[:(keyword[=expr][:...])][,...]

   o    The optional  truth-valued  expression  immediately  following  the
        command is a command postconditional that controls whether  or  not
        GT.M executes the command.

   o    The required expression specifies the device to CLOSE.

   o    The optional keywords specify deviceparameters that control device
        behavior; some deviceparameters  take  arguments  delimited  by  an
        equal sign (=); if there  is  only  one  keyword,  the  surrounding
        parentheses are optional.

   o    An indirection operator and an expression atom evaluating to a list
        of one or more CLOSE arguments form a legal argument for a CLOSE.

   When a CLOSE is issued, GT.M flushes all pending output to the device,
   and processes any deviceparameters. CLOSEing  a  device  not  currently
   OPEN has no effect.

   GT.M  retains  the  characteristics  of  all  device  types,  except  a
   sequential file, for use in case of subsequent re-OPENs. If the device
   is a sequential file, characteristics  controlled  by  deviceparameters
   are lost after the CLOSE.

   If the device being CLOSEd is $IO,  GT.M  implicitly  USEs  $PRINCIPAL.
   GT.M ignores CLOSE $PRINCIPAL.

   Example:

   CLOSE SD:RENAME=SD_".SAV"

   This closes the device and, if it is a disk file, renames  it  to  have
   the type .SAV.

3 Close_DeviParam
   CLOSE Deviceparamenter

4 DELETE
   DELETE Applies to: Sequential Files, and FIFO

   Instructs GT.M to delete the current version of  the  disk  file  after
   GT.M closes it.

4 EXCEPTION
   EXCEPTION=expr Applies to: All devices

   Defines an error handler for an I/O device. The expression must contain
   a fragment of GT.M code (for example, GOTO ERRFILE) that  GT.M  XECUTEs
   when the driver for the device detects an  error,  or  an  entryref  to
   which  GT.M  transfers  control,  as  appropriate  for  the  current
   gtm_ztrap_form.

   For more information on error handling, refer to the "Error Processing"
   chapter in GT.M Programmer's Guide.

4 GROUP
   GROUP=expr Applies to: Sequential Disk Files, and FIFO

   Specifies access permission on a UNIX file for other users in the file
   owner's group. The expression is a character string evaluating to null
   or to any combination of the letters RWX, indicating respectively Read,
   Write, and eXecute access.  When  any  one  of  these  deviceparameters
   appears on a CLOSE of a  new  file,  any  user  category  that  is  not
   explicitly specified is given the default character  string.  When  any
   one of these deviceparameters appears on a CLOSE of an  existing  file,
   any user category  (OWNER,  SYSTEM,  WORLD),  that  is  not  explicitly
   specified remains unchanged.

   In order to modify file security, the user who issues  the  CLOSE  must
   have ownership.

   By default, CLOSE does not modify the permissions on an existing file.

4 OWNER
   OWNER=expr Applies to: Sequential Disk Files, and FIFO

   Specifies access permission on a UNIX file for the owner of  the  file.
   The expression is a character string  evaluating  to  null  or  to  any
   combination of the letters RWX, indicating  respectively  Read,  Write,
   and eXecute access. When any one of these deviceparameters appears on a
   CLOSE of a new file, any user category that is not explicitly specified
   is given the default mask.  When  any  one  of  these  deviceparameters
   appears on a CLOSE of an  existing  file,  any  user  category  (GROUP,
   SYSTEM, WORLD), that is not explicitly specified remains unchanged.

   In order to modify file security, the user who issues  the  CLOSE  must
   have ownership.

   By default, CLOSE does not modify the permissions on an existing file.

4 RENAME
   RENAME=expr Applies to: Sequential Disk Files

   Changes the file name to the name contained  in  the  argument  string.
   When the expression omits part of the  pathname,  GT.M  constructs  the
   full pathname by applying the defaults  discussed  in  the  section  on
   device specifications.

   If the process has sufficient access permissions, it may use RENAME to
   specify a different directory as well as file name. RENAME cannot move
   a file to a different device.

4 SOCKET
   SOCKET=expr Applies to: Socket Device

   The socket specified in expr is closed. Specifying a  socket  that  has
   not  been  previously  OPENed  generates  an  error.  If  no  SOCKET
   deviceparameter is specified on a CLOSE for a socket device, the socket
   device and all sockets associated with it are closed.

4 SYSTEM
   SYSTEM=expr Applies to: Sequential Disk Files, and FIFO

   This deviceparameter is a synonym for OWNER that is maintained in UNIX
   for compatibility with VMS applications.

   By default, CLOSE does not modify the permissions on an existing file.

4 UIC
   UIC=exprgroup number Applies to: Sequential Disk Files, and FIFO

   Specifies the group that has access to the  file.  The  format  of  the
   string is "g,i" where g is a  decimal  number  representing  the  group
   portion of  the  UIC  and  i  is  a  decimal  number  representing  the
   individual portion. A process with the VMS privilege CMKRNL may set the
   file UIC to a UIC other than the UIC under which it is running, thereby
   giving ownership of the file to another user.

   Specifies the owner and affects access  to  the  file.  The  expression
   evaluates to the numeric identifier of the new owner.

4 WORLD
   WORLD=expr Applies to: Sequential Disk Files, and FIFO

   Specifies access permissions for users not in the owner's  group  on  a
   UNIX file. The expression is a character string evaluating to  null  or
   to any combination of the letters RWX,  indicating  respectively  Read,
   Write, and eXecute access.  When  any  one  of  these  deviceparameters
   appears on a CLOSE of a  new  file,  any  user  category  that  is  not
   explicitly specified is given the default character  string.  When  any
   one of these deviceparameters appears on a CLOSE of an  existing  file,
   any user category  (OWNER,  GROUP,  SYSTEM),  that  is  not  explicitly
   specified remains unchanged.

   In order to modify file security, the user who issues  the  CLOSE  must
   have ownership.

   By default, CLOSE and  CLOSE  do  not  modify  the  permissions  on  an
   existing file. Unless otherwise specified, when  CLOSE  creates  a  new
   file, it establishes security using standard defaulting rules.

   In order to modify file security, the user who issues  the  CLOSE  must
   have ownership.

   By default, CLOSE does not modify the permissions on an existing file.

1 M_Utility_Rtns
   M Utility Routines

   GT.M provides library utilities to perform frequently used  tasks,  and
   to access frequently used information. Most of the  utilities  are  for
   GT.M programmers, but some provide tools for system administration and
   operation.

   The GT.M utilities fall into the following general categories:

   o    Date and time utilities

   o    Conversion utilities

   o    Mathematic utilities

   o    Global utilities

   o    Routine utilities

   o    Internationalization utilities

   o    System Management utilities

   The GT.M distribution includes the source files  for  these  utilities.
   The default installation compiles them to produce object modules in the
   $gtm_dist distribution library.

   You may wish to examine the utilities and include some of them in your
   programs if the programs access the function frequently or you may want
   to modify the utilities to better fit your  particular  needs.  If  you
   modify a utility, store your copy in a directory that precedes gtm_dist
   in the search list $ZROUTINES to prevent a new  release  of  GT.M  from
   overlaying your copy.

2 Using_Util
   Using the Utilities

   You can either use a utility in Direct Mode or include it in  a  source
   application  program  with  one  or  more  of  the  following  formats.
   Italicized items are to be supplied by the user:

   o    DO ^%UTILITYNAME

   o    DO LABEL^%UTILITYNAME

   o    $$FUNC^%UTILITYNAME[(para1,...)]

   Many utilities contain labels  that  invoke  variations  of  the  basic
   utility functionality. Some also provide the label FUNC  to  invoke  an
   extrinsic function with optional or required parameters.

   GT.M passes input to non-extrinsic forms of the utilities interactively
   or by using "input" variables. GT.M passes  output  from  non-extrinsic
   forms of the utilities using "output" variables.  For  extrinsic  entry
   points, the utilities receive input as parameters and  pass  output  as
   the returned result. For  other  entry  points,  GT.M  uses  predefined
   "input" and "output" variables  to  pass  information.  Some  utilities
   interactively request user  inputs  and  display  their  results.  Each
   utility is described individually in  this  chapter  where  appropriate
   labels, input, and output variables are identified.

   By convention, the utilities  use  upper-case  variables  for  external
   input and output. Since M is case-sensitive, when an invocation uses a
   lower-case or misspelled variable name, the routine does not output the
   expected information. Instead it  supplies  a  default  value,  if  one
   exists, or produces an error message.

   Example:


   GTM>SET %ds="11/22/2002"

   GTM>DO INT^%DATE

   GTM>ZWRITE

   %DN=59123

   %ds="11/22/2002"

   This example sets the lowercase variable %ds to  the  date  11/22/2002.
   Since the %DATE routine  expects  the  input  to  be  provided  in  the
   uppercase %DS variable, it  returns  a  default  value  in  the  output
   variable $DN. The default is the $HOROLOG format of the  current  date,
   which is 11/15/2002 in the example.

2 Date_Time_Util
   Date and Time Utilities

   The date and time utilities are:

        %D Displays the current date using the [d]d-mmm-[yy]yy format.
        %DATE Converts input date to the $HOROLOG format.
        %H Converts date and time to and from $HOROLOG format.
        %T Displays the current time in [h]h:mm AM/PM format.
        %TI Converts time to $HOROLOG format.
        %TO Converts the current time from $HOROLOG format to [h]h:mm AM/PM
        format.
        For details and examples, refer to the GT.M Programmer's Guide.

   The  "%"  sign  has  been  removed  from  the  topic  headings  below,
   intentionally.

3 D_
   %D


   The %D utility displays the  current  date  using  the  [d]d-mmm-[yy]yy
   format. If a routine uses this function repetitively, put  the  utility
   code directly into the M program.

4 Util_Labels
   Utility Labels

        INT Sets variable %DAT to current date.
        FUNC[()] Invokes an extrinsic function returning today's date.
4 Output_Vars
   Output Variables

        %DAT Contains the current date.
4 Ex_of_D
   Examples of %D

        For the following examples, $ZDATEFORM is assumed to be one (1).

   Example:


   GTM>DO ^%D

   22-NOV-2002
   This example invokes %D in Direct Mode. Then %D  displays  the  current
   date.

   Example:


   GTM>DO INT^%D

   GTM>ZWRITE

   %DAT="22-NOV-2002"

   This example invokes %D with the label INT (INT^%D). The variable %DAT
   contains the current date. ZWRITE displays the contents of  the  output
   variable.

   Example:


   GTM>WRITE $$FUNC^%D

   22-NOV-2002
   This example invokes %D as an extrinsic function with the  label  FUNC.
   $$FUNC^%D returns today's date.

3 DATE
   %DATE


   The %DATE utility converts an input date to the  $HOROLOG  format.  The
   $HOROLOG format represents time as the number of  days  since  December
   31,  1840.  The  routine  has  entry  points  for  interactive  or
   non-interactive use.

4 Util_Labels
   Utility Labels

        INT Converts %DS input non-interactively, if defined, otherwise the
        current date.
        FUNC(t) Invokes an extrinsic function returning $HOROLOG format of
        the argument.
4 Prompts
   Prompts

        Date: Interactively requests a  date  for  conversion  to  $HOROLOG
        format.
4 Input_Vars
   Input Variables

        %DS Contains input date; refer to %DATE Input Formats table.
4 Output_Vars
   Output Variables

        %DN Contains output date in $HOROLOG format
4 Ex_of_DATE
   Examples of %DATE

   Example:


   GTM>DO ^%DATE

   Date:

   GTM>ZWRITE

   %DN=59105

   This example invokes %DATE at the GTM> prompt. After pressing <RETURN>
   at  the  Date:  prompt,  %DATE  converts  today's  date  (for  example,
   10/28/2002) to the $HOROLOG format. ZWRITE displays the contents of the
   output variable.

   Example:


   GTM>DO INT^%DATE

   GTM>ZWRITE

   %DN=59105

   This  example  invokes  INT^%DATE,  which  converts  the  current  date
   non-interactively into $HOROLOG format. ZWRITE displays the contents of
   the output variable.

   Example:


   GTM>SET %DS="10/20/2002"

   GTM>DO INT^%DATE

   GTM>ZWRITE

   %DN=59097

   %DS="10/20/2002"

   This example sets the input variable %DS prior to  invoking  INT^%DATE,
   which converts that date non-interactively to $HOROLOG format.

   Example:


   GTM>WRITE $$FUNC^%DATE("10/20/2002")

   59097
   This example invokes %DATE with the label FUNC as an extrinsic function
   to convert an input date to $HOROLOG. If the invocation does not supply
   a date for $$FUNC^%DATE, FUNC converts the current date.

   Example:


   GTM>WRITE $ZDATEFORM

   1975
   GTM>WRITE $$FUNC^%DATE("10/20/80")

   51062
   GTM>WRITE $ZDATE(51062)

   10/20/1980
   GTM>WRITE $$FUNC^%DATE("10/20/10")

   62019
   GTM>WRITE $ZDATE(62019)

   10/20/2010
   This example shows the use of a year limit  in  $ZDATEFORM.  Two  digit
   years are  interpreted  to  be  in  the  interval  (1975,  2074)  since
   $ZDATEFORM is 1975; the input year "80"  is  interpreted  as  the  year
   "1980" and "10" is interpreted as the year "2010". The example invokes
   FUNC^%DATE to convert the input date to $HOROLOG  format.  $ZDATE()  is
   used to convert the $HOROLOG format date to mm/dd/yyyy format.

3 H
   %H


   The %H utility converts date and time to and from $HOROLOG format.

4 Util_Labels
   Utility Labels

        %CDS Converts %DT $HOROLOG input date to mm/dd/yyyy format.
        %CTS Converts %TM $HOROLOG input time to external format.
        %CDN Converts %DT input date to $HOROLOG format.
        %CTN Converts %TM input time to $HOROLOG format.
        CDS(dt) Extrinsic entry that  converts  the  $HOROLOG  argument  to
        external date format.
        CTS(tm) Extrinsic entry that  converts  the  $HOROLOG  argument  to
        external time format.
        CDN(dt) Extrinsic entry that  converts  the  argument  to  $HOROLOG
        format.
        CTN(tm) Extrinsic entry that  converts  the  argument  to  $HOROLOG
        format.
4 Input_Vars
   Input Variables

        %DT Contains input date in either $HOROLOG or mm/dd/[yy]yy format,
        depending on the format expected by the utility entry point.
        %TM Contains input time in either $HOROLOG  or  [h]h:mm:ss  format,
        depending on the format expected by the utility entry point.
4 Output_Vars
   Output Variables

        %DAT Contains converted output date,
        %TIM Contains converted output time,
4 Ex_of_H
   Examples of %H

   Example:


   GTM>SET %DT=+$H DO %CDS^%H

   GTM>ZWRITE

   %DAT="10/20/2002"

   %DT=59097

   This example sets %DT to  the  current  date  in  $HOROLOG  format  and
   converts it to mm/dd/yyyy format by invoking %H at the label  %CDS.  %H
   returns the converted date in the variable %DAT.  ZWRITE  displays  the
   contents of the variables.

   Example:


   GTM>SET %DT="10/20/2002" DO %CDN^%H

   GTM>ZWRITE

   %DAT=59097

   %DT="10/20/2002"

   This example sets the variable %DT to a date in mm/dd/yyyy  format  and
   invokes %H at the label %CDN. %H returns  the  converted  date  in  the
   variable %DAT. ZWRITE displays the contents of the variables.

   Example:


   GTM>SET %TM=$P($H,",",2) DO %CTS^%H

   GTM>ZWRITE

   %TIM="17:41:18"

   %TM=63678

   This example sets the variable %TM to  the  current  time  in  $HOROLOG
   format using a $PIECE() function to return only  those  digits  of  the
   $HOROLOG string that represent the time. The example then invokes %H at
   the label %CTS. %H returns the converted time  in  the  variable  %TIM.
   ZWRITE displays the contents of the variables.

   Example:


   GTM>SET %TM="17:41:18" DO %CTN^%H

   GTM>ZWRITE

   %TIM=63678

   %TM="17:41:18"

   This example sets the variable %TM to a time in  hh:mm:ss  format,  and
   invokes %H at the label %CTN. %H returns  the  converted  time  in  the
   variable %TIM. ZWRITE displays the contents of the variables.

   Example:


   GTM>WRITE $$CDS^%H(59130)

   11/22/2002
   This invokes CDS^%H as an extrinsic function to  convert  the  external
   argument to external date format.

   Example:


   GTM>WRITE $ZDATEFORM

   1980
   GTM>WRITE $$CDN^%H("10/20/02")

   59097
   GTM>WRITE $ZDATE(59097)

   10/20/2002
   GTM>WRITE $$CDN^%H("10/20/92")

   55445
   GTM>WRITE $ZDATE(55445)

   10/20/1992
   This example shows the use of a year limit  in  $ZDATEFORM.  Two  digit
   years are interpreted to be in the  interval  of  1980  -  2079;  since
   $ZDATEFORM is 1980, the input year "02" is interpreted  as  "2002"  and
   "92" is interpreted as "1992". This example invokes CDN^%H  to  convert
   the argument in mm/dd/yy format to $HOROLOG format. $ZDATE() is used to
   conver the $HOROLOG format date to mm/dd/yyyy format.

3 T_
   %T


   The %T utility displays the current time in [h]h:mm AM/PM. If a routine
   uses this function repetitively, put the utility code directly into the
   M program.

4 Util_Labels
   Utility Labels

        INT Sets %TIM to current time in [h]h:mm AM/PM format.
        FUNC[()] Invokes an extrinsic function returning the current time.
4 Output_Vars
   Output Variables

   %TIM Contains current time in [h]h:mm AM/PM format.


4 Ex_of_T
   Examples of %T

   Example:


   GTM>DO ^%T

   8:30 AM
   This example invokes %T, which prints the current time and does not set
   %TIM.

   Example:


   GTM>DO INT^%T

   GTM>ZWRITE

   %TIM="8:30 AM"

   This example invokes INT^%T,  which  sets  the  variable  %TIM  to  the
   current time. ZWRITE displays the contents of the variable.

   Example:


   GTM>WRITE $$FUNC^%T

   8:30 AM
   This example invokes FUNC as an extrinsic function, which  returns  the
   current time.

3 TI
   %TI


   The %TI utility converts time to $HOROLOG format. The  $HOROLOG  format
   represents time as the number of seconds since  midnight.  %TI  returns
   the converted time in the variable %TN. The routine  has  entry  points
   for interactive or non-interactive use.

4 Util_Labels
   Utility Labels

        INT Non-interactively converts %TS to $HOROLOG format;  if  %TS  is
        not defined, then current time is converted.
        FUNC[(ts)] Invokes an extrinsic function returning $HOROLOG format
        of the argument, or if no argument,  the  $HOROLOG  format  of  the
        current time.
4 Prompts
   Prompts

        Time: Requests time in [h]h:mm:ss format  to  convert  to  $HOROLOG
        format.
4 Input_Vars
   Input Variables

        %TS Contains input time.
4 Output_Vars
   Output Variables

        %TN Contains output time in $HOROLOG format
4 Ex_of_TI
   Examples of %TI

   Example:


   GTM>DO ^%TI

   Time: 4:02 PM

   GTM>ZWRITE

   %TN=57720

   This example invokes %TI,  which  prompts  for  an  input  time.  Press
   <RETURN> to convert the current time. ZWRITE displays the  contents  of
   the output variable.

   Example:


   GTM>ZWRITE

   GTM>DO INT^%TI

   GTM>ZWRITE

   %TN=40954

   This  example  invokes  INT^%TI  to  convert  the  current  time
   non-interactively. ZWRITE displays the contents of the output variable
   %TN.

   Example:


   GTM>SET %TS="8:30AM"

   GTM>DO INT^%TI

   GTM>ZWRITE

   %TN=30600

   %TS="8:30AM"

   This example sets the variable %TS prior to invoking INT^%TI. %TI uses
   %TS as the input time. ZWRITE displays the contents of the variables.

   Example:


   GTM>WRITE $$FUNC^%TI("8:30AM")

   30600
   This example invokes %TI  as  an  extrinsic  function  to  convert  the
   supplied time to $HOROLOG  format.  If  there  is  no  argument  (i.e.,
   $$FUNC^%TI), %TI converts the current time.

3 TO
   %TO


   The %TO utility converts the input time from $HOROLOG format to [h]h:mm
   AM/PM format. Put the utility code directly into the M program  if  the
   routine uses this function repetitively.

4 Util_Labels
   Utility Labels

        INT Converts non-interactively %TS, or if %TS is  not  defined  the
        current time to [h]h:mm AM/PM format.
4 Input_Vars
   Input Variables

        %TN Contains input time in $HOROLOG format.
4 Output_Vars
   Output Variables

        %TS Contains output time in [h]h:mm AM/PM format.
4 Ex_of_TO
   Examples of %TO

   Example:


   GTM>DO INT^%TI,^%TO

   GTM>ZWRITE

   %TN=62074

   %TS="5:14 PM"

   This example invokes INT^%TI to set %TN to the current time and invokes
   %TO to convert the time contained in %TN to the [h]h:mm  AM/PM  format.
   %TO returns the converted time in the variable %TS. ZWRITE displays the
   contents of the variables.

2 Conversion_Util
   Conversion Utilities

   The conversion utilities are:

        %DH Decimal to hexadecimal conversion.
        %DO Decimal to octal conversion.
        %HD Hexadecimal to decimal conversion.
        %HO Hexadecimal to octal conversion.
        %LCASE Converts a string to all lower case.
        %OD Octal to decimal conversion.
        %OH Octal to hexadecimal conversion.
        %UCASE Converts a string to all upper case.
   The conversion utilities can be invoked as extrinsic functions.

   The  "%"  sign  has  been  removed  from  the  topic  headings  below,
   intentionally.

3 DH
   %DH


   The %DH utility converts numeric values from  decimal  to  hexadecimal.
   %DH defaults the length of its output  to  eight  digits.  However  the
   input variable %DL overrides the default and controls the length of the
   output. The routine has entry points for interactive or non-interactive
   use.

4 Util_Labels
   Utility Labels

        INT Converts interactively entered decimal  number  to  hexadecimal
        number with the number of digits specified.
        FUNC(d[,l]) Invokes %DH as  an  extrinsic  function  returning  the
        hexadecimal equivalent of the argument.
4 Input_Vars
   Input Variables

        %DH As input, contains input decimal number.
        %DL Specifies how many digits appear in  the  output,  defaults  to
        eight.
4 Prompts
   Prompts

        Decimal: Requests a decimal number for conversion to hexadecimal.
        Digits: Requests the length of  the  output  in  digits;  eight  by
        default.
4 Output_Vars
   Output Variables

        %DH As output, contains the converted number in hexadecimal.
4 Ex_of_DH
   Examples of %DH

   Example:


   GTM>DO INT^%DH

   Decimal: 12

   Digits: 1

   GTM>ZWRITE

   %DH="C"

   This example invokes %DH interactively with INT^%DH. %DH prompts for a
   decimal number and output  length,  then  returns  the  result  in  the
   variable %DH. ZWRITE displays the contents of the variables.

   Example:


   GTM>SET %DH=12

   GTM>DO ^%DH

   GTM>ZWRITE

   %DH="0000000C"

   %DL=8

   This example sets the read-write variable %DH to 12 and invokes %DH to
   convert the number to a  hexadecimal  number.  Because  the  number  of
   digits was not specified, %DH used the default of 8 digits. Set %DL to
   specify the number of output digits.

   Example:


   GTM>WRITE $$FUNC^%DH(12,4)

   000C
   This example invokes %DH as an extrinsic function using the FUNC label.
   The first argument specifies the input decimal number and the optional,
   second argument specifies the number of output digits. If the extrinsic
   does not have a second argument, the length of the output  defaults  to
   eight characters.

3 DO
   %DO


   The %DO utility converts numeric values  from  decimal  to  octal.  The
   default length of its output is 12 digits. The value  assigned  to  the
   input variable %DL overrides the default and controls the length of the
   output. The routine has entry points for interactive or non-interactive
   use.

4 Util_Labels
   Utility Labels

        INT Converts the specified decimal number to an octal  number  with
        the specified number of digits, interactively.
        FUNC(d[,ln]) Invokes %DO as an extrinsic  function,  returning  the
        octal equivalent of the argument.
4 Prompts
   Prompts

        Decimal: Requests a decimal number for conversion to octal.
        Digits: Requests the length of the output in digits; 12 by default.
4 Input_Vars
   Input Variables

        %DO As input, contains input decimal number.
        %DL Specifies the number of digits in the output, defaults to 12.
4 Output_Vars
   Output Variables

        %DO As output, contains the converted number in octal.
4 Ex_of_DO
   Examples of %DO

   Example:


   GTM>DO INT^%DO

   Decimal: 12

   Digits: 4

   GTM>ZWRITE

   %DO="0014"

   This example invokes %DO interactively with INT^%DO. %DO prompts for a
   decimal number and an output length. If the output  value  of  %DO  has
   leading zeros, the value is a string. ZWRITE displays the  contents  of
   the variables.

   Example:


   GTM>SET %DO=12

   GTM>DO ^%DO

   GTM>ZWRITE

   %DO="000000000014"

   This example sets the read-write variable %DO to 12 and invokes %DO to
   convert the number non-interactively. Because the number of digits was
   not specified, %DO used the default of 12 digits. Set  %DL  to  specify
   the number of output  digits.  ZWRITE  displays  the  contents  of  the
   variables.

   Example:


   GTM>WRITE $$FUNC^%DO(12,7)

   0000014
   This example invokes %DO as an extrinsic function with the label FUNC.
   The first argument  specifies  the  number  to  be  converted  and  the
   optional, second argument specifies the number of output digits. If the
   second argument is not specified, %DO uses the default of 12 digits.

3 HD
   %HD


   The %HD utility converts numeric values from  hexadecimal  to  decimal.
   %HD returns the decimal number in  the  read-write  variable  %HD.  %HD
   rejects input numbers beginning with a minus (-) sign and returns null
   (""). The routine has entry points for interactive  or  non-interactive
   use.

4 Util_Labels
   Utility Labels

        INT Converts hexadecimal number entered  interactively  to  decimal
        number.
        FUNC(h) Invokes %HD as an extrinsic function returning the decimal
        equivalent of the argument.
4 Prompts
   Prompts

        Hexadecimal:  Requests  a  hexadecimal  number  for  conversion  to
        decimal.
4 Input_Vars
   Input Variables

        %HD As input, contains input hexadecimal number.
4 Output_Vars
   Output Variables

        %HD As output, contains the converted number in decimal.
4 Ex_of_HD
   Examples of %HD

   Example:


   GTM>DO INT^%HD

   Hexadecimal:E

   GTM>ZWRITE

   %HD=14

   This example invokes %HD in interactive mode with INT^%HD. %HD prompts
   for a hexadecimal number, then returns  the  converted  number  in  the
   variable %HD. ZWRITE displays the contents of the variable.

   Example:


   GTM>SET %HD="E"

   GTM>DO ^%HD

   GTM>ZWRITE

   %HD=14

   This example sets the read-write variable %HD to "E" and invokes %HD to
   convert non-interactively the value of %HD to  a  decimal  number.  %HD
   places the converted value into the read-write variable %HD.

   Example:


   GTM>WRITE $$FUNC^%HD("E")

   14
   This example invokes %HD as an extrinsic function with the  label  FUNC
   and writes the results.

3 HO
   %HO


   The %HO utility converts numeric values from hexadecimal to octal. %HO
   returns the octal number in the read-write variable  %HO.  %HO  rejects
   input numbers beginning with a minus (-) sign and  returns  null  ("").
   The routine has entry points for interactive or non-interactive use.

4 Util_Labels
   Utility Labels

        INT Converts hexadecimal  number  entered  interactively  to  octal
        number.
        FUNC(h) Invokes %HO as an extrinsic function  returning  the  octal
        equivalent of the argument.
4 Prompts
   Prompts

        Hexadecimal: Requests a hexadecimal number for conversion to octal.
4 Input_Vars
   Input Variables

        %HO As input, contains input hexadecimal number.
4 Output_Vars
   Output Variables

        %HO As output, contains the converted number in octal.
4 Ex_of_HO
   Examples pf %HO

   Example:


   GTM>DO INT^%HO

   Hexadecimal:C3

   GTM>ZWRITE

   %HO=303

   This example invokes %HO in interactive mode using INT^%HO. %HO prompts
   for a hexadecimal number that it converts to an  octal  number.  ZWRITE
   displays the contents of the variable.

   Example:


   GTM>SET %HO="C3"

   GTM>DO ^%HO

   GTM>ZWRITE

   %HO=303

   This example sets the read-write variable %HO to "C3" and  invokes  %HO
   to convert the value of  %HO  non-interactively.  ZWRITE  displays  the
   contents of the variable.

   Example:


   GTM>WRITE $$FUNC^%HO("C3")

   303
   This example invokes %HO as an extrinsic function with the FUNC label.

3 LCASE
   %LCASE


   The %LCASE utility converts a string to all lower-case  letters.  If  a
   routine uses this function repetitively, put the utility code directly
   into the M program.

4 Util_Labels
   Utility Labels

        INT Converts interactively a string to lower-case.
        FUNC(s) Invokes %LCASE  as  an  extrinsic  function  returning  the
        lower-case form of the argument.
4 Prompts
   Prompts

        String: Requests a string for conversion to lower case.
4 Input_Vars
   Input Variables

        %S As input, contains string to be converted to lower case.
4 Output_Vars
   Output Variables

        %S As output, contains the converted string in lower case.
4 Ex_of_LCASE
   Examples of %LCASE

   Example:


   GTM>DO INT^%LCASE

   String: LABEL

   Lower: label

   This example invokes  %LCASE  in  interactive  mode  using  INT^%LCASE.
   %LCASE prompts for a string that it converts to all lower case.

   Example:


   GTM>SET %S="Hello"

   GTM>do ^%LCASE

   GTM>zwrite

   %S="hello"

   This example sets the variable %S to the  string  "Hello"  and  invokes
   %LCASE non-interactively to convert the string.

   Example:


   GTM>SET ^X="Hello"

   GTM>WRITE $$FUNC^%LCASE(^X)

   hello

   This example sets the variable ^X to the  string  "Hello"  and  invokes
   %LCASE as an extrinsic function that returns "hello" in lower case.

3 OD
   %OD


   The %OD utility converts numeric values  from  octal  to  decimal.  %OD
   returns the decimal number in the read-write variable %OD. %OD rejects
   input numbers beginning with a minus (-) sign and  returns  null  ("").
   The routine has entry points for interactive or non-interactive use.

4 Util_Labels
   Utility Labels

        INT Converts octal number entered interactively to decimal number.
        FUNC(oct) Invokes  %OD  as  an  extrinsic  function  returning  the
        decimal equivalent of the argument.
4 Prompts
   Prompts

        Octal: Requests an octal number for conversion to decimal.
4 Input_Vars
   Input Variables

        %OD As input, contains input octal number.
4 Output_Vars
   Output Variables

        %OD As output, contains the converted number in decimal.
4 Ex_of_OD
   Examples of %OD

   Example:


   GTM>DO INT^%OD

   Octal:14

   GTM>ZWRITE

   %OD=12

   This example invokes INT^%OD to interactively convert the octal number
   entered. %OD prompts for an octal number that it converts to a decimal.
   %OD returns the converted value in the variable %OD.

   Example:


   GTM>SET %OD=14

   GTM>DO ^%OD

   GTM>ZWRITE

   %OD=12

   This example sets the read-write variable %OD to 14 and invokes %OD to
   convert the number non-interactively. ZWRITE displays the  contents  of
   the variables.

   Example:


   GTM>WRITE $$FUNC^%OD(14)

   12
   This example invokes %OD as an extrinsic function with the FUNC label.
   The argument specifies the number to be converted.

3 OH
   %OH


   The %OH utility converts numeric values from octal to hexadecimal. %OH
   returns the hexadecimal number in  the  read-write  variable  %OH.  %OH
   rejects input numbers beginning with a minus (-) sign. The routine has
   entry points for interactive or  non-interactive  use.  In  interactive
   mode, %OH rejects non-octal numbers with the following message, "Input
   must be an octal number". In non-interactive mode, %OH returns  a  null
   string ("") upon encountering a non-octal number.

4 Util_Labels
   Utility Labels

        INT Converts interactively  octal  number  entered  to  hexadecimal
        number.
        FUNC(oct) Invokes  %OH  as  an  extrinsic  function  returning  the
        hexadecimal equivalent of the argument.
4 Prompts
   Prompts

        Octal: Requests an octal number for conversion to hexadecimal.
4 Input_Vars
   Input Variables

        %OH As input, contains input octal number.
4 Output_Vars
   Output Variables

        %OH As output, contains the converted number in hexadecimal.
4 Ex_of_OH
   Examples of %OH

   Example:


   GTM>DO INT^%OH

   Octal:16

   GTM>ZWRITE

   %OH="E"

   This example invokes %OH in interactive mode using INT^%OH. %OH prompts
   for an octal number that it converts to a  hexadecimal  number.  ZWRITE
   displays the contents of the variable.

   Example:


   GTM>SET %OH=16

   GTM>DO ^%OH

   GTM>ZWRITE

   %OH="E"

   This example sets the read-write variable %OH to 16 and invokes %OH to
   convert  the  value  of  %OH  non-interactively.  ZWRITE  displays  the
   contents of the variable.

   Example:


   GTM>WRITE $$FUNC^%OH(16)

   E

   This example invokes %OH as an extrinsic function with the FUNC label.

3 UCASE
   %UCASE


   The %UCASE utility converts a string to all upper-case  letters.  If  a
   routine uses this function repetitively, put the utility code directly
   into the M program.

4 Util_Labels
   Utility Labels

        INT Converts a string to upper case interactively.
        FUNC(s) Invokes %UCASE as  an  extrinsic  function,  returning  the
        upper-case form of the argument.
4 Prompts
   Prompts

        String: Requests a string for conversion to upper case.
4 Input_Vars
   Input Variables

        %S As input, contains string to be converted to upper case.
4 Output_Vars
   Output Variables

        %S As output, contains the converted string in upper case.
4 Ex_of_UCASE
   Examples of %UCASE

   Example:


   GTM>DO INT^%UCASE

   String: test

   Upper: TEST

   This example invokes  %UCASE  in  interactive  mode  using  INT^%UCASE.
   %UCASE prompts for a string that it converts to all upper case.

   Example:


   GTM>SET ^X="hello"

   GTM>WRITE $$FUNC^%UCASE(^X)

   HELLO

   This example sets the variable X to  the  string  "hello"  and  invokes
   %UCASE as an extrinsic function that returns "HELLO" in upper case.

2 Math_Util
   Mathematic Utilities

   The mathematic utilities are:

        %EXP Raises one number to the power of another number.
        %SQROOT Calculates the square root of a number.
   The mathematic utilities can be invoked as extrinsic functions.

   The  "%"  sign  has  been  removed  from  the  topic  headings  below,
   intentionally.

3 EXP
   %EXP


   The %EXP utility raises one number provided to  the  power  of  another
   number provided. While this utility provides an  interactive  interface
   for exponential calculations, most production code would perform inline
   calculation with the "**" operator. The routine has  entry  points  for
   interactive or non-interactive use.

4 Util_Labels
   Utility Labels

        INT  Calculates  a  number  to  the  power  of  another  number
        interactively.
        FUNC(i,j) Invokes %EXP as an extrinsic function returning the first
        argument raised to the power of the second argument.
4 Prompts
   Prompts

        Power: Requests an exponent or power.
        Number: Requests a base number to raise by the power.
4 Input_Vars
   Input Variables

        %I As input, contains number to be raised to a power.
        %J Contains exponential power by which to raise %I.
4 Output_Vars
   Output Variables

        %I As output, contains the result of the exponential calculation.
4 Ex_of_EXP
   Examples of %EXP

   Example:


   GTM>DO INT^%EXP

   Power: 3

   Number: 12

   12 raised to 3 is 1728
   This example invokes %EXP in  interactive  mode  using  INT^%EXP.  %EXP
   prompts for an exponent (power) and a base number.

   Example:


   GTM>SET %I=2,%J=9

   GTM>DO ^%EXP

   GTM>ZWRITE

   %I=512

   %J=9

   This example sets the read-write variable %I to 2, variable  %J  to  9,
   and invokes %EXP to calculate the result. ZWRITE displays the contents
   of the variables. %I contains the result.

   Example:


   GTM>WRITE $$FUNC^%EXP(2,9)

   512
   This example invokes %EXP as an extrinsic function with the label FUNC.


3 SQROOT
   %SQROOT


   The %SQROOT utility calculates the square root of  a  number  provided.
   While this utility provides an interactive interface for taking square
   roots, most production code would perform inline calculation by raising
   a number to the .5 power (n**.5). The  routine  has  entry  points  for
   interactive or non-interactive use.

4 Util_Labels
   Utility Labels

        INT Calculates the square root of a number interactively.
        FUNC(s) Invokes %SQROOT as  an  extrinsic  function  returning  the
        square root of the argument.
4 Prompts
   Prompts

        The square root of: Requests a number.
4 Input_Vars
   Input Variables

        %X Contains the number for which to calculate the square root.
4 Output_Vars
   Output Variables

        %Y Contains the square root of %X.
4 Ex_of_SQROOT
   Examples of %SQROOT

   Example:


   GTM>SET %X=81

   GTM>DO ^%SQROOT

   GTM>ZWRITE

   %X=81

   %Y=9

   This example sets  the  variable  %X  to  81  and  invokes  %SQROOT  to
   calculate  the  square  root  non-interactively.  ZWRITE  displays  the
   contents of the variables.

   Example:


   GTM>DO INT^%SQROOT

   The square root of: 81 is: 9

   The square root of: <RETURN>

   GTM>

   This example invokes  INT^%SQROOT  interactively  that  prompts  for  a
   number. The square root of the number appears on the same line. %SQROOT
   then prompts for another number. Press <RETURN> to exit.

   Example:


   GTM>WRITE $$FUNC^%SQROOT(81)

   9
   This example invokes %SQROOT as an extrinsic function  with  the  label
   FUNC.

2 Glob_Util
   Global Utilities

   The Global utilities are:

        %G Displays global variables and their values.
        %GC Copies a global or global sub-tree.
        %GCE Replaces a specified value or part of a  value  in  a  set  of
        variables.
        %GD Displays existing  globals  in  the  current  global  directory
        without displaying their values or descendants.
        %GED Provides full-screen editing capabilities for global variables
        and values.
        %GI Loads global data from a sequential file into a GT.M database.
        %GO Extracts global data from a GT.M  database  into  a  sequential
        file.
        %GSE Displays global variables and their  values  when  the  values
        contain a specified string or number.
        %GSEL Selects globals.
   The  "%"  sign  has  been  removed  from  the  topic  headings  below,
   intentionally.

3 G_
   %G


   The %G utility  displays  names,  descendants  and  values  of  globals
   currently existing in the database. Use %G to examine global variables
   and their values. Enter a question mark (?) at any  prompt  to  display
   help information.

4 Prompts
   Prompts

        Output Device: <terminal>:
        Requests a destination device; defaults to the principal device.
        List ^ Requests the name, in ZWRITE format, of a global to display.
4 Ex_of_G
   Examples of %G

   Example:


   GTM>do ^%G

   Output Device: <terminal>: <RETURN>

   List ^C

   ^C="CLASS"

   ^C(1)="MARY"

   ^C(1,2)="MATH"

   ^C(1,2,1)=80

   ^C(1,3)="BIO"

   ^C(1,3,1)=90

   ^C(2)="JOHN"

   ^C(3)="PETER"

   List ^ <RETURN>

   GTM>

   This example lists the nodes of global ^C. %G displays the  global  and
   its descendants and values, if the node exists.

   Example:


   GTM>do ^%G

   Output Device: <terminal>: <RETURN>

   List ^C(1)

   ^C(1)="MARY"

   This example lists only the node entered and its value.

   Example:


   GTM>do ^%G

   Output Device: <terminal>: <RETURN>

   List ^C(1,*)

   ^C(1)="MARY"

   ^C(1,2)="MATH"

   ^C(1,2,1)=80

   ^C(1,3)="BIO"

   ^C(1,3,1)=90

   List ^ <RETURN>

   GTM>

   This example uses the asterisk (*) wildcard to  list  node  ^C(1),  its
   descendants and values.

   Example:


   GTM>do ^%G

   Output Device: <terminal>: <RETURN>

   List ^?D

   Global Directory

   Global ^ <RETURN>

   ^C ^D ^S ^Y ^a

   Total of 5 globals.

   List ^

   GTM>

   This example specifies "?D" as the global that invokes the %GD utility.
   %GD displays existing globals in the current global  directory  without
   displaying their values or descendants.

3 GC_
   %GC


   The %GC utility copies values of globals from one global to another. It
   is useful for testing and for moving misfiled data.

4 Prompts
   Prompts

        Show copied nodes <Yes>?
        Asks whether to display the "source nodes" on the principal device.
        From global ^ Requests a global variable name from  which  to  copy
        variable and descendants.
        To global ^ Request a global variable name to receive the copy.
4 Ex_of_GC
   Example:


   GTM>do ^%GC

   Global copy

   Show copied nodes <Yes>? <RETURN>

   From global ^b

   To global ^g

   ^g(1)=1

   ^g(2)=2

   ^g(3)=3

   Total 3 nodes copied.

   From global ^<RETURN>

   GTM>

   This example makes a copy of the nodes  and  values  of  global  ^b  to
   global ^g.

3 GCE
   %GCE


   The %GCE utility changes every occurrence of a string within  the  data
   of selected global nodes to a replacement  string.  ^%GCE  changes  the
   string in each place it occurs, even if  it  forms  part  of  a  longer
   string. For example, changing the string 12 to 55 changes 312 to 355.

4 Prompts
   Prompts

        Global ^ Requests (using %GSEL)  the  name(s)  of  the  globals  to
        change; <RETURN> ends selection.
        Old string: Requests an existing string to find.
        New string: Requests the replacement string.
        Show changed nodes <Yes>?
        Asks whether to display the before and after versions  of  modified
        nodes on the current device.
        Output Device: <terminal>:
        Requests a destination device; defaults to the principal device.
4 Ex_of_GCE
   Examples of %GCE

   Example:


   GTM>DO ^%GCE

   Global Change Every occurrence

   Global ^a:^b

   ^a ^b

   Current total of 2 globals.

   Global ^ <RETURN>

   Old String: hello

   New String: good-bye

   Show changed nodes <Yes>?: <RETURN>

   Output Device: <terminal>: <RETURN>

   ^a

   No changes made in total 1 nodes.

   ^b

   ^b(10)

   Was : hello Adam

   Now : good-bye Adam

   1 changes made in total 25 nodes.
   Global ^ <RETURN>

   GTM>

   This example searches a range of globals and  its  nodes  for  the  old
   string value entered.  GT.M  searches  each  global  and  displays  the
   changes and number of nodes changed and checked.

   Example:


   GTM>set ^b(12)=12

   GTM>set ^b(122)=122

   GTM>set ^b(30)=656

   GTM>set ^b(45)=344

   GTM>set ^b(1212)=012212

   GTM>DO ^%GCE

   Global Change Every occurrence

   Global ^b

   Current total of 1 global.

   Global ^ <RETURN>

   Old String: 12

   New String: 35

   Show changed nodes <Yes>?: <RETURN>

   Output Device: <terminal>: <RETURN>

   ^b(12)

   Was : 12

   Now : 35

   ^b(122)

   Was : 122

   Now : 352

   ^b(1212)

   Was : 12212

   Now : 35235

   5 changes made in total 5 nodes
   Global ^ <RETURN>

   GTM>DO ^%G

   Output device: <terminal>: <RETURN>

   List ^b

   ^b(12)=35

   ^b(30)=656

   ^b(45)=344

   ^b(122)=352

   ^b(1212)=35235

   This example shows that executing %GCE replaces all occurrences of "12"
   in the data stored in the global ^b with "35" and displays the affected
   nodes before and after the change. Then the %G demonstrates  that  "12"
   as data was changed, while "12" in the subscripts remained untouched.

3 GD
   %GD


   The %GD  utility  displays  existing  globals  in  the  current  global
   directory without displaying their values or descendants.

   %GD prompts for a global name and redisplays the name  if  that  global
   exists.

   %GD interprets a percent sign (%) in the first  position  of  a  global
   name literally.

   %GD allows the wildcard characters asterisk (*) and question mark (?).
   The wildcards carry their usual meanings, an  asterisk  (*)  denotes  a
   field or a portion of a field, and a question mark (?) denotes a single
   character.

   A colon (:)  between  two  globals  specifies  a  range.  %GD  displays
   existing globals within that range.

   After each selection %GD reports the number of globals selected by the
   input.

   A question mark (?) entered at  a  prompt  displays  help  information.
   Pressing <RETURN> exits %GD.

4 Prompts
   Prompts

        Global ^  Requests  (using  %GSEL)  a  global  name  with  optional
        wildcards or a range of names; <RETURN> terminates %GD.
4 Ex_of_GD
   Exampels of %GD

   Example:


   GTM>DO ^%GD

   Global directory

   Global ^k

   ^k

   Total of 1 global.

   Global ^ <RETURN>

   GTM>

   This example verifies that ^k exists in the global directory.

   Example:


   GTM>DO ^%GD

   Global directory

   Global ^C:S

   ^C ^D ^S

   Total of 3 globals

   Global ^ <RETURN>

   GTM>

   This example displays a range of globals that exist from ^C to ^S.

   Example:


   GTM>DO ^%GD Global directory

   Global ^*

   ^C ^D ^S ^Y ^a

   Total of 5 globals

   Global ^ <RETURN>

   GTM>

   The asterisk (*) wildcard at the Global ^ prompt displays  all  globals
   in the global directory.

3 GED
   %GED


   The %GED utility enables you to  edit  the  globals  in  a  full-screen
   editor environment. %GED invokes your default editor  as  specified  by
   the EDITOR environment variable. When you  finish  the  edit,  use  the
   [save and] exit command(s) of the editor you are using, to exit.

4 Prompts
   Prompts

        Edit ^ Requests the name, in ZWRITE format, of a global to edit.
   Only one global can be edited at  a  time  with  %GED,  refer  to  GT.M
   Programmer's Guide for descriptions of valid input for subscripts.

4 Ex_of_GED
   Examples of %GED

   Example:


   GTM>DO ^%GED

   edit ^ b

   Beginning screen:

   ^b(1)="melons"

   ^b(2)="oranges"

   ^b(3)="bananas"

   Screen with a change to  ^b(1),  elimination  of  ^b(3),  and  two  new
   entries ^b(4) and ^b(5):

   ^b(1)="apples"

   ^b(2)="oranges"

   ^b(4)=pears

   ^b(5)="grapes"


   %GED responds:


   Invalid syntax: b(4)=pears

   return to continue:

   After screen:

   ^b(1)="apples"

   ^b(2)="oranges"

   ^b(4)="pears"

   ^b(5)="grapes"

   %GED responds:


   node : ^b

   selected : 3

   changed : 1

   added : 2

   killed : 1

   Edit ^ <RETURN>

   GTM>

   This example shows the use of the full-screen editor  to  change,  add,
   and delete (kill) nodes. When you exit from the editor, %GED checks the
   syntax and reports any problems. By pressing <RETURN>,  return  to  the
   full-screen editor to fix the error. At the end of  the  session,  %GED
   reports how many nodes were selected, changed, killed, and added.

3 GI
   %GI


   %GI loads global variable names and  their  corresponding  data  values
   into a GT.M database from  a  sequential  file.  %GI  uses  the  global
   directory to determine which database files to  use.  %GI  may  operate
   concurrently with normal GT.M database access. However, a %GI does not
   use M LOCKs and may produce application-level integrity problems if run
   concurrently with many applications.

   The %GI utility corresponds to MUPIP LOAD. The format of the input file
   (GO or ZWRITE) is automatically detected.

4 Prompts
   Prompts

        Enter input file:
        Requests name of a file; file should be in standard  Global  Output
        (GO) format or Zwrite (ZWR) format .
        OK <Yes>?: Asks for confirmation.
4 Ex_of_GI
   Examples of %GI

   Example:


   GTM>DO ^%GI

   Global Input Utility

   Input device <terminal>: DATA.GBL

   Saved from user's development area

   GT.M 07-MAY-2002 14:14:09

   OK <Yes>? <RETURN>

   ^IB ^INFO

   Restored 10 nodes in 2 globals

   GTM>

3 GO
   %GO


   %GO copies specified globals from the current database to a sequential
   output file in either GO or ZWR format. Use %GO  to  back  up  specific
   globals or when extracting data from the database for  use  by  another
   system. %GO uses the global directory to determine which database files
   to use. %GO may operate concurrently with normal GT.M database access.
   To ensure that a %GO reflects a consistent application  state,  suspend
   database updates to all regions involved in the extract.

   The %GO utility corresponds to MUPIP EXTRACT (FORMAT=GO or FORMAT=ZWR).

4 Prompts
   Prompts

        Global ^ Requests (using %GSEL)  the  name(s)  of  the  globals  to
        search; <RETURN> ends selection.
        Header label: Requests text describing contents of extract file.
        Output Format: GO or ZWR:
        Requests the format to output the data. Defaults to ZWR.
        Output Device: <terminal>:
        Requests destination device, which may be any legal filename.
4 Ex_of_GO
   Examples of %GO

   Example:


   GTM>DO ^%GO

   Global Output Utility

   Global ^A

   ^A

   Current total of 1 global

   Global ^<RETURN>

   Header label: Revenues May, 2002

   Output Format: GO or ZWR: ZWR

   Output device: /usr/dev/out.go

   ^A

   Total of 1 node in 1 global.

   GTM>

3 GSE_
   %GSE


   The %GSE utility finds occurrences of a string within the  data  values
   for selected global nodes and displays the variable name and data on a
   specified output device.

4 Prompts
   Prompts

        Output Device: <terminal>:
        Requests a destination device; defaults to the principal device.
        Global ^ Requests (using %GSEL)  the  name(s)  of  the  globals  to
        search; <RETURN> ends selection.
        String: Requests a search string.
4 Ex_of_GSE
   Examples of %GSE

   Example:


   GTM>do ^%GSE

   Global Search For Every Occurence

   Output device: <terminal>: Test.dat

   Global ^a <RETURN>

   ^a

   Current total of 1 global.

   Global ^ <RETURN>

   String: Hello

   ^a

   ^a(10) Hello Adam

   Total 1 matches found in 25 nodes.

   Global ^ <RETURN>

   GTM>

   This example searches global ^a for the string "Hello" and displays all
   nodes that contain that string.

3 GSEL
   %GSEL


   The %GSEL utility selects globals. %GSEL creates a variable %ZG that is
   a local array of the  selected  globals.  After  each  selection  %GSEL
   displays the number of globals in %ZG.

   %GSEL accepts the wildcard characters asterisk (*),  percent  sign  (%)
   and question mark  (?).  The  wildcards  carry  their  usual  meanings,
   asterisk (*) denoting a field or a portion of  a  field,  and  question
   mark (?) or percent sign (%) denoting a single character. The wildcards
   question mark (?) and percent sign (%) lose their meanings when in the
   first position of a global name. %GSEL interprets a percent sign (%) in
   the first position of a global name literally.

   A colon (:) between two globals specifies a range.

   A minus sign (-) or quotation mark (') preceding a global name removes
   that global from the %ZG array. A question  mark  (?)  provides  online
   help, and "?D" displays global names currently in the array.

4 Util_Labels
   Utility Labels

        CALL Runs %GSEL without reinitializing %ZG.
4 Output_Vars
   Output Variables

        %ZG Contains array of all globals selected.
4 Prompts
   Prompts

        Global ^ Requests a global name with optional wildcards or a range
        of names.
4 Ex_of_GSEL
   Examples of %GSEL

   Example:


   GTM>DO ^%GSEL

   Global ^C

   ^C

   Current total of 1 global

   Global ^*

   ^S ^Y ^c ^class

   Current total of 5 globals

   Global ^-S

   ^S

   Current total of 4 globals

   Global ^'Y

   ^Y

   Current total of 3 globals

   Global ^?D

   ^C ^c ^class

   Current total of 3 globals

   Global ^ <RETURN>

   GTM>ZWRITE

   %ZG=3

   %ZG("^C")=""

   %ZG("^c")=""

   %ZG("^class")=""

   GTM>

   This example adds and subtracts  globals  from  the  list  of  selected
   globals. "?D"  displays  all  globals  selected.  ZWRITE  displays  the
   contents of the %ZG array.

   Example:


   GTM>DO ^%GSEL

   Global ^a

   ^a

   Current total of 1 global.

   Global ^<RETURN>

   GTM>ZWRITE

   %ZG=1

   %ZG("^a")=""

   GTM>DO CALL^%GSEL

   Global ^?d

   ^a

   Global ^iv

   ^iv

   Current total of 2 globals.

   Global ^<RETURN>

   GTM>ZWRITE

   %ZG=2

   %ZG("^a")=""

   %ZG("^iv")=""

   GTM>

   This example uses CALL^%GSEL  to  add  to  an  existing  %ZG  array  of
   selected globals.

2 Rtn_Util
   Routine Utilities

   The routine utilities are:

        %FL Lists the comment lines at the beginning of source programs.
        %RCE Replaces every occurrence of a text string with  another  text
        string in a routine or a list of routines.
        %RD Lists routine names available through $ZROUTINES.
        %RI Loads routines from RO file to *.m files in GT.M format.
        %RO Writes M source code for one or more routines to  a  sequential
        device such as a terminal, or a disk file.
        %RSE Searches for every occurrence of a text string in a routine or
        a list of routines.
        %RSEL Selects M routines and places their directories and names in
        a local array.
   The  "%"  sign  has  been  removed  from  the  topic  headings  below,
   intentionally.

3 FL
   %FL


   The %FL utility lists the comment lines  at  the  beginning  of  source
   programs.  %FL  writes  the  routines  in  alphabetical  order  to  the
   specified device. If the output device is not the principal device, %FL
   displays the name of each routine on the principal device as it writes
   the routine to the output device.

   %FL uses %RSEL to select routines. For more information, refer  to  the
   section on %RSEL in this chapter.

4 Prompts
   Prompts

        Routine: Requests  the  name(s)  of  the  routines  (using  %RSEL);
        <RETURN> ends the selection.
        Output Device: <terminal>:
        Requests a destination device; defaults to the principal device.
4 Ex_of_FL
   Examples of %FL

   Example:


   GTM>DO ^%FL

   First Line Lister

   Routine: %D

   %D

   Current total of 1 routine.

   Routine: %GS*

   %GSE %GSEL

   Current total of 3 routines.

   Routine: - %D

   %D

   Current total of 2 routines.

   Routine: ?D

   %GSE %GSEL

   Routine: <RETURN>

   Output Device: <RETURN>

   Routine First Line Lister Utility

   GT.M 21-MAR-2002 16:44:09

   %GSE

   %GSE ;GT.M %GSE utility - global search

   ;

   %GSEL ;

   %GSEL ;GT.M %GSEL utility - global select into a local array

   ;

   ;invoke ^%GSEL to create %ZG -  a  local  array  of  existing  globals,
   interactively
   ;

   Total 5 lines in of 2 routines.

   GTM>

   This example selects %D, then selects %GSE and %GSEL and deselects %D.
   Because the example enters <RETURN> at the Output  Device:  <terminal>:
   prompt, the output goes to the principal device.

3 RCE
   %RCE


   The %RCE utility replaces  every  occurrence  of  a  text  string  with
   another text string in a routine or a list of routines.

   %RCE uses %RSEL to select routines. For more information, refer to the
   section on %RSEL in this chapter.

   %RCE prompts for a text string to replace  and  its  replacement.  %RCE
   searches for text strings in a case-sensitive  manner.  %RCE  issues  a
   warning message if you specify a control character such as a  <TAB>  in
   the text string or its replacement. %RCE  confirms  your  selection  by
   displaying the text string and its replacement between a left and right
   arrow. The arrows highlight  any  blank  spaces  that  you  might  have
   included in the text string or its replacement.

   Regardless of whether you  select  a  display  of  every  change,  %RCE
   displays the name of each routine as  it  is  processed  and  completes
   processing with a count of replacements and routines changed.

4 Prompts
   Prompts

        Routine: Requests (using %RSEL) the  name(s)  of  the  routines  to
        change; <RETURN> ends the selection.
        Old string: Requests string to be replaced.
        New string: Requests replacement string.
        Show changed lines <Yes>?:
        Asks whether to display  the  before  and  after  versions  of  the
        modified lines on an output device.
        Output Device: <terminal>:
        Requests a destination device; defaults to the principal device.
4 Util_Labels
   Utility Labels

        CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
   Input Variable

   The  following  input  variables  are  only  applicable  when  invoking
   CALL^%RCE.

        %ZR Contains an array of routines provided or generated with %RSEL.
        %ZF Contains string to find.
        %ZN Contains a replacement string.
        %ZD Identifies the device to display the change trail, defaults to
        principal device. Make sure you open the device if  the  device  is
        not the principal device.
        %ZC Truth-value indicating whether to  display  the  change  trail,
        defaults to 0 (no).
4 Ex_of_RCE
   Examples of %RCE

   Example:


   GTM>DO ^%RCE

   Routine Change Every occurrence

   Routine: BES*

   BEST BEST2 BEST3 BEST4

   Current total of 4 routines

   Routine: <RETURN>

   Old string:^NAME

   New string:^STUDENT

   Replace all occurrences of:

>^NAME<
   With

>^STUDENT<
   Show changed lines <Yes>?: <RETURN>

   Output Device: <RETURN>

   /usr/smith/work/BEST.m

   Was: S ^NAME=SMITH

   Now: S ^STUDENT=SMITH

   Was: S ^NAME(1)=JOHN

   Now: S ^STUDENT(1)=JOHN

   /usr/smith/work/BEST2.m

   /usr/smith/work/BEST3.m

   Was: S ^NAME=X

   Now: S ^STUDENT=X

   Was: W ^NAME

   Now: W ^STUDENT

   /usr/smith/work/BEST4.m

   Total of 4 routines parsed.

   4 occurrences changed in 2 routines.
   GTM>

   This example selects a list of routines that change the string "^NAME"
   to the string "^STUDENT," and displays a trail of the changes.

   Example:


   GTM>DO ^%RCE

   Routine Change Every occurrence

   Routine: BES*

   BEST BEST2 BEST3 BEST4

   Current total of 4 routines

   Routine: <RETURN>

   Old String:<TAB>

   The find string contains control characters

   New string: <RETURN>

   Replace all occurrences of:

><TAB><
   With:

><
   Show changed lines <Yes>?: N

   BEST BEST2 BEST3 BEST4

   Total 4 routines parsed.

   4 occurrences changed in 2 routines.
   GTM>

   This example removes all occurrences of the <TAB>  key  from  specified
   routines and suppresses the display trail of changes.

3 RD
   %RD


   The %RD utility lists routine  names  accessible  through  the  current
   $ZROUTINES. %RD  calls  %RSEL  and  displays  any  routines  accessible
   through %RSEL. Use %RD to locate routines.

   %RD accepts the wildcard characters asterisk (*) and question mark (?).
   The wildcards carry their usual meanings, an  asterisk  (*)  denotes  a
   field or a portion of a field, and a question mark (?) denotes a single
   character in positions other than the first.

   A colon (:) between two routine names specifies a  range  of  routines.
   %RD displays only those routine names accessible  through  the  current
   $ZROUTINES.

   After each selection %RD displays the total number of routines listed.

   Pressing <RETURN> exits %RD.

4 Prompts
   Prompts

        Routine: Requests (using %RSEL) the  name(s)  of  the  routines  to
        list; <RETURN> ends the selection.
4 Util_Labels
   Utility Labels

        OBJ Lists object modules accessible through the current $ZROUTINES.
        LIB Lists percent  (%)  routines  accessible  through  the  current
        $ZROUTINES.
        SRC  Lists  the  source  modules  accessible  through  the  current
        $ZROUTINES (same as %RD).
4 Ex_of_RD
   Examples of %RD

   Example:


   GTM>DO ^%RD

   Routine directory

   Routine: TAXES

   TAXES

   Total of 1 routine

   Routine:*

   EMP FICA PAYROLL TAXES YTD

   Total of 5 Routines

   Routine: <RETURN>

   GTM>

   This example invokes  %RD  that  prompts  for  routine  TAXES  and  the
   wildcard (*). %RD lists five routines accessible  through  the  current
   $ZROUTINES.

   Example:


   GTM>DO OBJ^%RD

   Routine directory

   Routine:*

   EMP FICA

   Total of 2 routines

   Routine: <RETURN>

   GTM>

   This example invokes %RD with the label  OBJ  that  lists  only  object
   modules accessible through the current $ZROUTINES.

   Example:


   GTM>DO LIB^%RD

   Routine directory

   %D %DATE %DH %G %GD %GSEL

   GTM>

   This example invokes %RD with the  LIB  label  that  lists  all  the  %
   routines accessible through the current $ZROUTINES.

   Example:


   GTM>DO SRC^%RD

   Routine directory

   Routine:*

   DATACHG

   Total of 1 routines

   Routine: <RETURN>

   GTM>

   This example invokes %RD with the label  SRC  that  lists  only  source
   modules accessible through the current $ZROUTINES.

3 RI
   %RI


   %RI transforms M routines in the sequential  format  described  in  the
   ANSI standard into individual .m files in GT.M format. Use %RI to make
   M RO format accessible as GT.M routines.

4 Prompts
   Prompts

        Formfeed delimited <No>?
        Requests whether lines should be delimited by  formfeed  characters
        rather than carriage returns.
        Input Device: <terminal>:
        Requests name of RO file containing M routines.
        Output Directory:
        Requests name of directory to output M routines.
4 Ex_of_RI
   Examples of %RI

   Example:


   GTM>DO ^%RI

   Routine Input utility - Converts RO file to *.m files

   Formfeed delimited <No>? <RETURN>

   Input device: <terminal>: file.ro

   Files saved from FILEMAN directory

   GT.M 07-MAY-2002 15:17:54

   Output directory: /usr/smith/work/

   DI DIA DIAO DIAI DIB DIBI

   Restored 753 lines in 6 routines.

   GTM>

3 RO
   %RO


   The %RO utility writes M source code for one  or  more  routines  to  a
   sequential device such as a disk file or a printer.

   %RO uses %RSEL to select routines. For more information, refer  to  the
   section on %RSEL in this chapter.

   %RO writes the routines in alphabetical order to the specified device.
   %RO displays the name of each routine as it writes the routine  to  the
   device.

4 Prompts
   Prompts

        Routine: Requests (using %RSEL) the  name(s)  of  the  routines  to
        output; <RETURN> ends selection.
        Output device: <terminal>:
        Requests a destination device; defaults to the principal device.
        Header label: Requests text to place in the first of the two header
        records.
        Strip comments <No>?:
        Asks whether to remove all comment  lines  except  those  with  two
        adjacent semicolons.
4 Util_Labels
   Utility Labels

        CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
   Input Variables

   The  following  input  variables  are  only  applicable  when  invoking
   CALL^%RO.

        %ZR Contains an array of routines provided or generated with %RSEL.
        %ZD Identifies the device to display output, defaults to principal
        device.
4 Ex_of_RO
   Examples of %RO

   Example:


   GTM>DO ^%RO

   Routine Output - Save selected routines into RO file.

   Routine: %D

   %D

   Current total of 1 routines.

   Routine: -%D

   %D

   Current total of 0 routines.

   Routine: BEST*

   BEST BEST1 BEST2

   Current total of 3 routines.

   Routine: ?D

   BEST BEST1 BEST2

   Routine: <RETURN>

   Output Device: <terminal>: output.txt

   Header Label: Source code for the BEST modules.

   Strip comments <No>?:<RETURN>

   BEST BEST1 BEST2

   Total of 53 lines in 3 routines

   GTM>

   This example adds and subtracts %D from the selection,  then  adds  all
   routines starting with "BEST" and confirms the current  selection.  The
   example sends output to the  designated  output  file  output.txt.  %RO
   displays the label at the beginning  of  the  output  file.  The  first
   record of the header label is the  text  entered  at  the  prompt.  The
   second record of the header label consists of the word "GT.M"  and  the
   current date and time.

3 RSE_
   %RSE


   The %RSE utility searches for every occurrence of a text  string  in  a
   routine or a list of routines.

   %RSE uses %RSEL to select routines. For more information, refer to the
   section on %RSEL in this chapter.

   %RSE searches for  text  strings  are  case-sensitive.  %RSE  issues  a
   warning message if you specify a control character such as a  <TAB>  in
   the text string. %RSE confirms your selection by  displaying  the  text
   string between a left and right arrow. The  arrows  display  any  blank
   spaces included in the text string.

   %RSE completes processing with a count of occurrences found.


4 Prompts
   Prompts

        Routine: Requests (using %RSEL) the  name(s)  of  the  routines  to
        search; <RETURN> ends selection.
        Find string: Requests string for which to search.
        Output device: <terminal>:
        Requests a destination device; defaults to the principal device.
4 Util_Labels
   Utility Labels

        CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
   Input Variables

   The  following  input  variables  are  only  applicable  when  invoking
   CALL^%RSE.

        %ZR Contains an array of routines provided or generated with %RSEL.
        %ZF Contains the string to find.
        %ZD Identifies the device  to  display  the  results,  defaults  to
        principal device. Make sure you open the device if  the  device  is
        not the principal device.
4 Ex_of_RSE
   Examples of %RSE

   Example:


   GTM>DO ^%RSE

   Routine Search for Every occurrence

   Routine: BES*

   BEST BEST2 BEST3 BEST4

   Current total of 4 routines

   Routine: <RETURN>

   Find string:^NAME

   Find all occurrences of:

>^NAME<
   Output device: <terminal>:

   /usr/smith/work/BEST.m

   S ^NAME=SMITH

   S ^NAME(1)=JOHN

   /usr/smith/work/BEST2.m

   /usr/smith/work/BEST3.m

   S ^NAME=X

   W ^NAME

   /usr/smith/work/BEST4.m

   Total of 4 routines parsed.

   4 occurrences found in 2 routines.
   GTM>

   This example invokes %RSE that searches and finds a given  string.  The
   output device specifies a terminal display of all lines where the text
   string occurs.

   Example:


   GTM>DO ^%RSE

   Routine Search for Every occurrence

   Routine: BEST

   BEST

   Current total of 1 routine

   Routine: <RETURN>

   Find string:^NAME

   Find all occurrences of:

>^NAME<
   Output Device: out.lis

   BEST

   GTM>

   This example instructs ^%RSE to write all lines where the  text  string
   occurs to an output file, out.lis.

3 RSEL
   %RSEL


   The %RSEL utility selects M  routines.  %RSEL  selects  routines  using
   directories  specified  by  the  GT.M  special  variable  $ZROUTINES.
   $ZROUTINES contains an ordered list of UNIX  directories  that  certain
   GT.M functions use to locate source and object files. If $ZROUTINES is
   not defined, %RSEL searches only the current default  directory.  Other
   GT.M utilities call %RSEL.

   %RSEL prompts for the name of a routine(s).


   %RSEL accepts the wildcard characters asterisk (*)  and  question  mark
   (?). The wildcards carry their usual meanings: an asterisk (*) denotes
   a field or a portion of a field, and a  question  mark  (?)  denotes  a
   single character in positions other than the first.

   A colon (:) between two routines specifies a range.

   %RSEL creates a read-write variable %ZR, which  is  a  local  array  of
   selected routines. After each selection, %RSEL reports  the  number  of
   routines in %ZR. A minus  sign  (-)  or  an  apostrophe  (')  character
   preceding a routine name removes that routine from  the  %ZR  array.  A
   question mark (?) provides online help, and "?D"  displays  M  routines
   currently in the array.

        If a local variable %ZRSET is  defined,  %RSEL  places  the  output
        information into a global variable (^%RSET) instead  of  the  local
        variable %ZR.

4 Prompts
   Prompts

        Routine: Requests  the  name(s)  of  the  routines;  <RETURN>  ends
        selection.
4 Util_Labels
   Utility Labels

        CALL Performs %RSEL without reinitializing %ZR.
        OBJ Searches only object files.
        SRC Searches only source files (same as %RSEL).
4 Input_Vars
   Input Variables

   The following input variables are only valid when invoking CALL^%RSEL:

        %ZE Contains the file extension, usually either .m for source files
        or .o for object files.
        %ZR As input, contains an existing list of routines to be modified.
        %ZRSET On being set, requests %RSEL to  place  the  output  in  the
        global variable ^%RSET.
4 Output_Vars
   Output Variables

        %ZR As output, contains list of  directories  indexed  by  selected
        routine names.
        ^%RSET($JOB) The output global variable ^%RSET is used  instead  of
        the local variable %RD if the input variable %ZRSET is set.  It  is
        indexed by job number $JOB and the selected routine names.
4 Ex_of_RSEL
   Examples of %RSEL

   Example:


   GTM>DO ^%RSEL

   Routine: TES*

   TEST2 TEST3

   Current total of 2 routines

   Routine: <RETURN>

   GTM>DO OBJ^%RSEL

   Routine:TEST?

   Current total of 0 routines

   Routine: <RETURN>

   GTM>ZWRITE

   %ZR=0

   This example selects two source routines starting  with  "TES"  as  the
   first three characters. Then, the example  invokes  %RSEL  at  the  OBJ
   label to select object modules only. OBJ^%RSEL returns a %ZR=0 because
   object modules for the TEST routines do not exist.

   Example:


   GTM>DO ^%RSEL

   Routine: BES*

   BEST BEST2 BEST3 BEST4

   Current total of 4 routines

   Routine: - BEST

   BEST

   Current total of 3 routines

   Routine: ?D

   BEST2 BEST3 BEST4

   Routine: 'BEST2

   BEST2

   Current total of 2 routines

   Routine: ?D

   BEST3 BEST4

   Routine: <RETURN>

   GTM>ZWRITE

   %ZR=2

   %ZR("BEST3")="/usr/smith/work/"

   %ZR("BEST4")="/usr/smith/test/"

   GTM>

   This example selects the routines using the asterisk (*)  wildcard  and
   illustrates how to tailor your selection list. Note that  %ZR  contains
   two routines from different directories.

   By default, %RSEL bases the contents of %ZR on source files that have a
   .m extension.

   Example:


   GTM>DO ^%RSEL

   Routine:BEST*

   BEST2 BEST3

   Current total of 2 routines

   Routine: <RETURN>

   GTM>ZWRITE

   %ZR=2

   %ZR("BEST2")="/usr/smith/test/"

   %ZR("BEST3")="/usr/smith/test/"

   This example creates a %ZR array with BEST2 and BEST3.

   Example:


   GTM>DO ^%RSEL

   Routine:LOCK

   LOCK

   Current total of 1 routine

   Routine: <RETURN>

   GTM>ZWRITE

   %ZR=1

   %ZR("LOCK")="/usr/smith/work/"

   GTM>DO CALL^%RSEL

   Routine:BEST*

   BEST2 BEST3

   Current total of 2 routines

   Routine: <RETURN>

   GTM>ZWRITE

   %ZR=3

   %ZR("BEST2")="/usr/smith/work/"

   %ZR("BEST3")="/usr/smith/work/"

   %ZR("LOCK")="/usr/smith/work/"

   GTM>

   This example creates a %ZR  array  with  LOCK  and  adds  to  it  using
   CALL%RSEL.

2 Internationalization_Util
   Internationalization Utilities

   The internationalization utilities are:

        %GBLDEF Manipulates the collation sequence assigned to a global.
        %LCLCOL  Manipulates  the  collation  sequence  assigned  to  local
        variables in an active process.
        %PATCODE Loads pattern definition files for use  within  an  active
        database.
   These utilities are an integral part of  the  GT.M  functionality  that
   permits  you  to  customize  your  applications  for  use  with  other
   languages.  For  a  description  of  these  utilities,  refer  to  the
   "Internationalization" chapter in GT.M Programmers Guide.

2 Sys_Mgmt_Util
   System Management Utilities

   The System Management utilities are:

        %FREECNT Displays the number of free blocks in the  database  files
        associated with the current global directory.
3 FREECNT
   %FREECNT


   The %FREECNT utility displays the number of free blocks in the database
   files associated with the current global directory.


