#####intro
Introduction to NWShell

        The NWShell NLM is a command processor for the NetWare 3.x server 
environment.  NWShell provides a command interface which is similar to the
DOS command shell, COMMAND.COM.  NWShell provides a batch language with a
number of enhancements over the normal DOS batch language including
predefined system variables, multi-line IF...ELSE...ELIF...ENDIF blocks, and
a WHILE looping structure.  Additional features include support for mapping
drive numbers (0: thru 9:), remote login for up to 10 NetWare 2.x or NetWare
3.x File Servers and job queuing to any NetWare queue.  Commands such as MAP,
WHOAMI and LOGIN are also supported.

#####reserved
NWShell Reserved Words

        Following is a summary of the NWShell script file reserved word list.
Note that all commands MUST be followed by at least one space, and both upper
and lower case words are reserved.  There are four exceptions to the one
space rule; they are CD, MD, RD, and DIR.  These commands do not require a
space between the command and the parameter, so long as the parameter starts
with either a '.', '/' or '\'.

#####command
#####keyword
    ABORT     BREAK      CALL      CAPTURE    CD          CDD
    CHDIR     CLRENV     CLS       CONSOLE    CONTINUE    COPY
    DEL       DELAY      DF        DIR        DUMP        ECHO        ELIF
    ELSE      ENDIF      ERASE     EXEC       EXIST       EXIT
    FLAG      FINDFIRST  FINDNEXT  IF         LIST        LOAD
    LOGIN     LOGOUT     LOWER     MAP        MD          MKDIR
    MODE      MSG        PAUSE     PRINT      PSET        RD
    READLINE  REM        REN       RETURN     RMDIR       SALVAGE
    SAY       MODE       SET       STDERR     STDOUT      STDPRN
    STOP      SYSTEM     TRACE     TYPE       UPPER       USERLIST
    VER       WEND       WHEREIS   WHILE      WHOAMI      YNPROMPT
    #
#####~~~~~~~~~~~~~~~~

        All unrecognized commands are passed to the NetWare loader routine.
If an external program has the same name as an internal NWShell command, you
can use the EXEC keyword to load it.  By the same token, an external script
file with the same name as an internal keyword can be executed using the CALL
command.
#####installing
#####using
Using the NWShell NLM

        To load the NWShell NLM, place a copy into the SYS:SYSTEM directory,
or any path specified in the NetWare SEARCH path, and type the following from
the NetWare 3.x console:

        :LOAD NWSHELL [USERNAME]

If a user name is specified, NWShell will attempt to login as that user
during initialization.  If a password is required, NWShell will prompt the
console operator for the password.  If no user name is specified, NWShell
attempts to login as SUPERVISOR.
#####loginscript
        Whenever the first successful login occurs, NWShell will attempt to
execute a script called "LOGIN.NWS" if one is found.  The users SYS:MAIL
directory is searched for this file.  If this file is not found, NWShell will
map drive 0: to SYS:, and drive 9: to SYS:PUBLIC.  If the SUPERVISOR logs in,
NWShell will instead map drive 9: to SYS:SYSTEM.  Drive 0: will become the
default drive at the beginning of the session.

        The LOGIN.NWS file is a good place to perform initial logins, drive
mappings and environment setup.  It is recommended that you at least set the
NWSINCL environment variable to point to the location of your script files.
This location will be searched if an attempt to locate a script in the
default directory fails, much like the DOS PATH is searched for .BAT files.
You may also want to set the PROMPT environment variable to customize your
command prompt.  See Appendix B for complete explanations of the NWSINCL and
PROMPT environment variables.
#####~~~~~~~~~~~~~~~
NWShell Keyword Descriptions

        Following are the explanations of the NWShell keywords.  Refer to
Appendix A for example scripts illustrating the usage of these keywords.

######
Command: #
         This command is used to imbed comments in a script file.  It must be
         the first non-white character on the line.

Example:
         #      This is a comment line...
         #This is also a comment line...

See also:
         REM

#####abort
Command: ABORT ["message"]
         The ABORT command is used to terminate current execution of a
         script file.  It is normally used in conjunction with an IF verb
         to terminate execution when a particular condition exists.  The
         message text is optional, and if included is displayed to the
         system log file. (By default, this is the NWShell CONSOLE screen).

Example:
         if "%1" == ""
             abort Missing parameter in script!
         endif

#####break
Command: BREAK
         The BREAK command is used to terminate the innermost while loop.
         If there is no while in effect, a syntax error will occur, and
         the process aborted.

Example:
         while "^myvar^" != ""
             call myproc parm1 parm2 parm3
             if +cretc+ != 0
                 say Return code +cretc+ from myproc
                 break
             endif
         wend

#####call
Command: CALL scriptname [args...]
         The CALL command is used to include other script files for
         processing.  There is a call nesting limit of 10 levels.  The
         different formats are explained below.  Each "called" script
         inherits the environment from its parent, and added environment
         strings are kept when control is returned.  Arguments, however,
         are NOT inherited, thus they must be passed from the parent.

         Notes:  If the script is not found in the default directory, then
         the directories specified in the NWSINCL variable are searched.

         This command is normally used to call a script file which has the
         same name as an internal command.  It can also be used to avoid the
         message displayed by NetWare when a load fails.

Example:
         call myproc parm1 parm2 parm3

#####capture
Command: CAPTURE [PORT SERVER QUEUE BANNER NAME FLAGS TABSIZE COPIES]
         The CAPTURE command is used to set the capture parameters for
         any of threee logical ports defined in a given NWShell session.
         This works much like the DOS CAPTURE command, except that the
         syntax is different.

         If no parameters are supplied, the current capture settings for
         each of the logical ports is displayed.  To cancel a given
         port's setup, simply supply the port with no parameters.

#####@wait
         The FLAGS parameter is defined as follows:
             128  -  Print a banner
              64  -  If job is a TEXT stream
               8  -  To suppress a form feed at the end of the job

         To get the desired effect, simply add the appropriate flags values
         for the settings you want.  i.e. To print a banner and specify
         a TEXT stream, use 192 for the FLAGS parameter.

         The TABSIZE field specifies the amount of spaces that each TAB
         character will be expanded to.
#####@wait

Example:
         # the following command just lists the current settings
         capture
         # the following command cancels any capture for port 1
         capture 1
         # the following command redirects port 2 to PRINTS1/EPSON
         capture 2 prints1 epson

#####cd
Command: CD path
         CHDIR path
         The CHDIR or CD command is used to change the current directory of
         the current drive.  If the path contains a volume or server/volume,
         the drive will be re-mapped to the new location.

Example:
         set mydir=0:\dir1
         upper mydir
         ^0.1mydir^:
         if +cdrive+: == 0:
             chdir ^mydir^
             if ^mydir^ != +cpath+
                 say error changing to directory ^mydir^
             endif
         else
             say Drive ^0.1mydir^: is not a valid drive!
         endif

#####cdd
Command: CDD <d:path>
         The CDD command is used to change the current drive and at the
         same time, change to a new directory on the new drive.  A full
         volume spec can be specified, so a drive can be remapped to an
         entirely different Server/Volume/Path.  Note that the path is
         relative to the current path on the specified drive.

Example:
         cdd 1:xyz      # make drive 1: current. Change directory to xyz.
         cdd 1:borg:p   # make drive 1: current. remap to BORG:P directory.

#####clrenv
Command: CLRENV
         The CLRENV command deletes all of the current environment strings.

Example:
         clrenv         # this command deletes all strings set with SET

#####cls
Command: CLS
         Clears the NWShell console screen.

Example:
         cls

#####console
Command: CONSOLE "console message"
         This command displays a message on the console.  It is not redirected
         to a disk file, it is displayed on the screen.

         The following escape sequences are supported by the console verb:

                /n - expands to newline
                /a - expands to bell
                /r - expands to carriage return
                /b - expands to backspace
                // - expands to forward slash

Example:
         console /n/tThis is a message to the console/n/a

#####continue
Command: CONTINUE
         This command will continue with the next iteration of the innermost
         while loop.  If there is no while loop, a syntax error will occur
         and the process aborted.

Example:
         do while ^name^. != .
             call myproc parm1 parm2 parm3
             if +cretc+ != 0
                 say Return code +cretc+ from myproc
                 continue
             endif
             say Got return code of zero from myproc
             set name=
         wend

#####copy
Command: COPY SOURCEFILE [DESTINATIONFILE]
         COPY SOURCEWILD [DESTINATIONPATH]
         COPY CON DESTINATIONFILE

         This command is used to copy files.  Both the source and destination
         can reference either NetWare or DOS volumes.  The COPY CON
         destination must be a NetWare volume!  Paths may consist of drive
         letters with full or partial paths, volume specifications or the
         server/volume specification.  DOS paths may be either full or
         partial paths.

#####@wait
Examples:
         The following command copies either a subdirectory called D:/TEST
         or a file called D:/TEST to the current directory 0:/NWS:

             0:/NWS> COPY D:/TEST

         The following command copies a file called 0:/TESTFILE to either
         a directory called 5:/TEST if it exists, or the file 5:/TEST:

             0:/NWS> COPY 0:/TESTFILE 5:/TEST


         The following command copies all of the files in the current
         directory 0:/NWS to the current directory of drive 5:

             0:/NWS> COPY *.* 5:
#####@wait

         The following command copies all of the files in the current
         directory 0:/NWS to the directory 5:/SUBDIR:

             0:/NWS> COPY *.* 5:/SUBDIR

         The following command copies data which will be input from the
         prompt to the file SAMPLE.NWS:

             0:/NWS> COPY CON SAMPLE.NWS

         Input is terminated by typing the CTRL-Z character in column 1
         of any line.

#####del
#####erase
Command: DEL <FILENAME>
         ERASE <FILENAME>
         These commands are used to erase files.  Wildcards are accepted,
         as well as drive specifications and full server/volume specs.

Example:
         del *.NWS
         del 5:../MAP/*.MAP
         del AUS-BO/SYS:BO/*.TXT

#####delay
Command: DELAY <NUM SECONDS>
         Delays for the specified number of seconds.  NWShell delays 1
         second at a time, checking for ESC during each iteration.  All
         other keys are ignored.

Example:
         #
         #  Unload UTILITY.NLM if it is loaded...
         #
         if UTILITY nlm exists
            system unload utility
         endif
         while UTILITY nlm exists
             delay 1    # wait till it is unloaded...
         wend

#####df
Command: DF [VOLUME]
         Displays information about a volume.  If no parameter is given, the
         default volume is used.

Example:
         df
         df borg

#####dir
Command: DIR [FILESPEC] [/W] [/P]
         The DIR command is used to get a directory listing of the files
         in the current or any other directory.  Both NetWare and DOS
         volumes are supported.  The /W switch will display files in a
         wide format, similar to DOS.  The /P switch is used to pause the
         display when the screen becomes full.  Drive specs are valid,
         as are full NetWare server/volume specifications.

Example:
         dir
         dir *.nws
         dir/p
         dir *.nws /w
         dir 1:*.
         dir c:*.c

#####dump
Command: DUMP
         The DUMP command dumps all current level variable definitions and all
         environment strings to stdout.  If stdout is redirected, the output
         will go to the redirected file.  It is useful for debugging script
         files.

         Script parameters are prefixed with an 'P'.  Local environment
         strings are prefixed with an 'L' and globals are prefixed with
         a 'G'.

Example:
         dump

#####echo
#####say
Command: ECHO ON | OFF | "message"
         The ECHO command is used to write messages to the console.  If
         the console is redirected, the messages will go to the redirected
         file.  If ON is the first parameter, batch file statements
         will be traced.  If OFF is the first parameter, batch file
         statements will not be traced.  If no parameters are specified,
         the current trace setting will be displayed.

Example:
         echo This message will go to the log file
         echo on

See also:
         SAY

#####elif
Command: ELIF <expr> [ logical operator <expr2> ... ]
         The ELIF command causes control to be passed to the statements that
         follow, provided <expr> is true.  If there is no preceding IF, a
         syntax error occurs and the process aborted.  If the previous IF
         condition was TRUE, control is passed to the ENDIF.

Example:
         if +cdrive+ == 0
             say Current drive is 0:
         elif +cdrive+ == 1
             say Current drive is 1:
         else
             say Current drive is NOT 0: or 1:!
         endif

#####else
Command: ELSE
         The ELSE command causes control to be passed to the statements that
         follow, if the preceding IF expression was FALSE.  If there was no
         preceding IF, a syntax error occurs and the process aborted.  If the
         previous IF condition was TRUE, control is passed to the ENDIF.

Example:
         if +cdrive+ == 0
             say Current drive is 0:
         else
             say Current drive is NOT 0:
         endif

#####endif
Command: ENDIF
         ENDIF marks the end of an IF ... ELSE block.  It is required that
         each IF statement be matched with an ENDIF statement.

Example:
         if +cdrive+ == 0
             say Current drive is 0:
         endif

#####exec
Command: EXEC [N | W] programname [parms...] [<STDINREDIR] [>STDOUTREDIR]
         EXEC is used to spawn processes.  A return code other than 0 from the
         process causes script processing to be terminated.  Any number of
         parameters may be specified, as long as the total length, including
         space separators, does not exceed 512 bytes.  The 'N' or 'W'
         parameters are used to override the default execution mode.  If 'N'
         is specified, the NLM will be spawned in NOWAIT mode.  The 'W'
         switch will cause the NLM to be spawned in WAIT mode.  For more
         information, see the MODE EXECUTION MODE command.

         Notes: The current setting of EXEC IGNORE MODE determines whether the
         current process will be aborted if the EXECed process returns anything
         other than zero (0).  See MODE EXEC IGNORE MODE command.  Also, the
         current setting of INHERIT CONTEXT determines whether the current
         context is passed to the spawned NLM.  See MODE INHERIT CONTEXT.
#####@wait

         Any unrecognized token is passed to the EXEC loader.  Thus the only
         reasons for using EXEC are to execute commands which have the same
         name as an internal command or when you want to redirect the STDIN
         and/or STDOUT streams of the EXECed NLM.

Example:
         exec utinlm 3:^myfile^
         exec utinlm 3:^myfile^ <2:input
         exec utinlm 3:^myfile^ >2:output
         exec utinlm 3:^myfile^ <2:input >4:output

#####exist
Command: EXIST filename
         The EXIST command checks for the existance of "filename".  If it
         does not exist, the script processing is aborted.

Example:
         exist ^myfile^         # will abort if ^myfile^ doesn't exist!

See also:   IF

#####exit
Command: EXIT [Return Code | SHELL]
         The EXIT command is used to return control to the script file which
         called it.  The optional return code may be passed back to the
         caller.  If no return code is specified, it will be zero (0).  The
         caller can access the return code thru the CRETC system variable.
         If the EXIT command is used from the command line, NWShell is
         terminated.  Also, if the parameter 'SHELL' is given rather than
         a return code, NWShell also terminates.

Example:
         mode exec ignore mode = on
         exec myprog
         mode exec ignore mode = off
         if +eretc+ != 0
             exit 1
         endif
         exit 0

See also:
         RETURN

#####flag
Command: FLAG <FILESPEC> [N|A] [+ATTRIBUTES] [-ATTRIBUTES]

         The FLAG command is used to modify the file attributes of a file.
         If no parameters are given, the attributes of all files in the
         current working directory are displayed.  The 'N' switch causes
         the files to be made normal, that is, Rw or Read/Write.  All other
         attributes will be cleared.  The 'A' switch causes all attributes
         for the given files to be set, except for Execute Only.  The
         'N' or 'A' must be the first switch given, or they will be treated
         as attribute tags.

         Attributes specified after the '+' will be set, while those
         appearing after the '-' are reset.  The default is to set the
         attributes, thus the initial '+' is not required.
#####@wait

         The following list shows the valid attribute tags that may be
         specified:

            3.x Attributes:      2.x Attributes:
            --------------      ---------------
            RO  Read Only        RO  Read Only
            RW  Read Write       RW  Read Write
            S   Shareable        S   Shareable
            H   Hidden           H   Hidden
            Sy  System           Sy  System
            T   Transactional    T   Transactional
            P   Purge            I   Indexed
            RA  Read Audit       RA  Read Audit
            WA  Write Audit      WA  Write Audit
            C   Copy Inhibit
            D   Delete Inhibit
            R   Rename Inhibit
#####@wait

         As expected, the file specifier can contain wildcards, and drive
         letters as well as full volume specifications are supported.

Example:
         flag myfile h        # make myfile hidden
         flag myfile a        # set all of the attributes
         flag myfile ro sy    # set read/only and hidden
         flag myfile pc -s    # set purge immed & copy inhibit, reset share

#####findfirst
Command: FINDFIRST filespec
         The FINDFIRST command begins a search for files matching the
         "filespec" file specification.  A match, if found, will be stored
         in the system variable FFILE.  See FINDNEXT and Section V - NWShell
         System variables.

         Notes: The FINDFIRST call cannot be nested.  However, each called
         script can have its own FINDFIRST search in effect.

Example:
         #
         findfirst ^lookfile^    # search for ^lookfile^
         while "+ffile+" != ""
            say Match is +ffile+
            findnext               # find next match
         wend

#####findnext
Command: FINDNEXT
         The FINDNEXT command searches for the next match using the filespec
         specified in the scripts previous FINDFIRST call.  If there is no
         current FINDFIRST in effect, the command is ignored. Like FINDFIRST,
         the match is placed in the FFILE system variable.  See also
         FINDFIRST.

Example:
         #
         findfirst ^lookfile^    # search for ^lookfile^
         while "+ffile+" != ""
            say Match is +ffile+
            findnext               # find next match
         wend

#####help
Command: HELP <TOPIC>
         Displays help on any of the topics listed.

Example:
         help comm  # display list of keywords

#####if
Command: IF <expr> [ logical operator <expr2> ... ]
         The IF command is used to test for a condition, and if that condition
         is TRUE, execute the statement(s) which follow.  If the expression
         is FALSE, an ELSE or ENDIF is searched for.  In the case of an ELSE
         keyword, the statements following it are executed.  Each IF must have
         a matching ENDIF, however the ELSE is optional.  See Section IV -
         NWShell expressions for a full discussion of valid expressions.

Example:
         set mydir=0:\dir1
         upper mydir
         ^0.1mydir^:
         if +cdrive+: == 0:
             chdir ^mydir^
             if ^mydir^ != +cpath+
                 say error changing to directory ^mydir^
             endif
         else
             say Drive ^0.1mydir^: is not a valid drive!
         endif

#####list
Command: LIST <FILENAME>
         The LIST command is used to list a file on the screen.  It is
         essentially a file browser command.  The following keys are
         used to browse the file:

            Home        -   Top of File
            Page Down   -   Display next screen
            Page Up     -   Display previous screen
            Down Arrow  -   Scroll down one line
            Up Arrow    -   Scroll up one line
            End         -   End of File
            Esc         -   Terminate and return to prompt.

Example:
         LIST LOGIN.NWS
         LIST 4:MYFILE.TXT
         LIST AUS-RD/SYS:USERS/KEN/NWSHELL.TXT

#####login
Command: LOGIN [SERVERNAME/][USERNAME]
         The LOGIN command is used to login to either the local server, or
         a remote 2.x or 3.x server.

         The Server name is optional, if one is not supplied, the default is
         assumed.  The user name is also optional, if one is not supplied,
         you will be prompted for it.  On the initial login, the shell will
         will search for a LOGIN.NWS file in the user's mail directory.  If
         one is found, it will be executed.  Otherwise, an initial mapping
         to the root of the SYS volume will be supplied.

         When only one parameter is given, the shell first looks for a user
         by that name on the default server.  If one isn't found, then a
         server by the same name is searched for.

Example:
         LOGIN BO
         LOGIN AUS-RD
         LOGIN AUS-RD/BO

#####logout
Command: LOGOUT [SERVERNAME]
         The LOGOUT command is used to logout from a server, if specified, or
         all servers if no parameters are given.

         You cannot logout from a script file!

Example:
         logout aus-rd
         logout

#####lower
Command: LOWER <environment variable name>
         The LOWER command is used to convert an environment variable string
         to lower case.

Example:
         #
         set mystr=THIS WILL BE A LOWER CASE STRING
         lower mystr
         # the following will print "this will be a lower case string"
         say "^mystr^"

#####map
Command: MAP [DEL] <d:> [<=>[SERVER/][VOLUME:][PATH]]
         The MAP command is used to assign a logical device to a local or
         remote location.  Devices 0: through 9: can be mapped.  If a mapping
         is in effect, it is deleted and the new map is assigned.  If an
         attempt to map to a remote server is performed and no user is has
         been logged in, the command will prompt for the necessary login
         information.  If no parameters are given, the drive is mapped to
         the current working directory.

Example:
         map 5:=/public
         if +sretc+ != 0
             say Error +sretc+ returned from map command
         endif
         map 6:=BORG:KEN
         map 7:=AUS-RD/SYS:386/CLib
         map 8:=/
         map del 6:
         map 9:=7:
         map 8:=7:src

#####mkdir
Command: MKDIR path
         MD path
         The MKDIR or MD command is used to create a directory.  Absolute
         or relative paths are valid, as well as those contain drive letters
         and full server/volume path specs.

Example:
         md sys:mydir
         md 1:dir1
         md /public/mydir

#####mode
Command: MODE [<parameter> <=> < <ON | OFF> | <TRUE | FALSE> | <YES | NO> >]
         The MODE command is used to control some internal NWShell actions.
         If no parameters are given, the current settings for all modes are
         displayed.  The valid parameters are:

             BREAK
             EXEC IGNORE MODE
             EXECUTION MODE
             MAX STMT COUNT
             DEFAULT LOCAL PORT
             GIVE LOCATION
             DEBUG STATEMENTS
             TRACE STATEMENTS
             SINGLE STEP SCRIPTS
             DEFAULT LOAD SCREEN
             PREPROCESS SCAN COUNT
             PAUSE ON FULL SCREEN
             SCREEN SWITCH BACK
             LOAD REMOTE MODULE
             INHERIT CONTEXT
             PUSH
             POP
#####~~~~~~~~~~~~~~~
    BREAK  -   Ignored for now.  Used to control signal SIGINT.

#####execignoremode
    EXEC IGNORE MODE - Whether to abort script processing if an NLM
                       cannot be found.
#####executionmode
    EXECUTION MODE - Used to set the program execution mode.
                     Can be 'O' for OVERLAY, 'N' for NOWAIT,
                     or 'W' for WAIT.  The default is NOWAIT.
                     'O' is currently ignored.
#####maxstmtcount
    MAX STMT COUNT - Used to set the maximum number of statements
                     that can be executing during processing of
                     script files.  It defaults to 1000.
#####defaultlocalport
    DEFAULT LOCAL PORT - Used to set the port number that is used
                         for spooling print jobs with the PRINT
                         command.  It defaults to 1.
#####givelocation
    GIVE LOCATION - Whether to denote the current script name and
                    line numbers when writing to the Internal Error
                    log.  It defaults to OFF.
#####debugstatements
    DEBUG STATEMENTS - Whether to Display debugging information
                       while line processing is occuring.  This is
                       useful for debugging scripts.
#####tracestatements
    TRACE STATEMENTS - Whether to echo statements.  Similar to the
                       DOS ECHO ON command.
#####singlestepscripts
    SINGLE STEP SCRIPTS - When set to ON, prompts for a keystroke
                          during execution of script files after
                          each line is executed.
#####defaultloadscreen
    DEFAULT LOAD SCREEN - Used to specify the default screen for
                          an NLM that uses the SCREENNAME 'DEFAULT'
                          option in the linker directive file.  The
                          following values can be used: 'Console'
                          for the System Console, 'Main' to specify
                          NWShell's screen, and 'Null' for the
                          alternate screen (Default).
#####pauseonfullscreen
    PAUSE ON FULL SCREEN - Used to specify whether NWShell will
                           pause on the USERLIST and WHOAMI commands
                           if the screen is full.
#####preprocessscancount
    PREPROCESS SCAN COUNT - Used to specify the number of times that
                            NWShell will scan an input line to expand
                            macros.  By default, this is done only once.

#####screenswitchback
    SCREEN SWITCH BACK - Used to specify whether NWShell will
                         switch back to its screen when an NLM
                         that was spawned terminates.  This only
                         works if execution mode is current set
                         to WAIT.
#####loadremotemodule
    LOAD REMOTE MODULE - Used to specify whether NWShell will
                         load NLMs from remote servers.
#####inheritcontext
    INHERIT CONTEXT - Used to specify whether NWShell will pass the
                      current context to the NLM which is spawned
                      when the EXEC or LOAD commands are used.  In
                      other words, whether the spawned NLM will 
                      have the same user login and current working
                      directory as NWShell's default drive.
#####push
    PUSH - Save current mode settings.  All are saved except the Default
           Load Screen.  However, Default Load Screen cannot be changed
           with the current version.  The PUSH command saves the current
           settings in a static variable, so they cannot be nested.
#####pop
    POP - Restores the previous MODE settings saved when the PUSH command
          was executed.
#####~~~~~~~~~~~~~~~

Example:
         mode exec ignore mode = on
         #      The next command will not abort if MYPROG returns non-zero
         #      return code, or the NetWare loader cannot find it.
         exec myprog


#####msg
Command: MSG <Connection# | ALL | ON | OFF | CHECK> Message
         Used to send or retrieve broadcast messages to one or all stations
         currently logged in to the default server.  The default server is
         the server to which the current drive is mapped.

Example:
         # The following sends "This is a test" to all nodes
         msg all This is a test
         # The following sends a message to connection 38
         msg 38 Help, I've fallen and I can't get up!
         # The following checks your mailbox for a message
         msg check

#####pause
Command: PAUSE "message"
         This command is used to pause the NWShell command processor.  It
         will print "message" and then wait for a keystroke.

Example:
         pause Press any key to continue

#####print
Command: PRINT <filename>
         This command is used to print a file.  The default local port is
         used to determine which queue the file will be spooled to.  See
         the MODE command for information on setting the default local port.

Example:
         print 2:myfile.txt

#####pset
Command: PSET envarname=string
         The PSET command is used to set local strings into the environment.
         The environment is used to hold control strings for any purpose.
         Local strings are different from global strings in that their
         scope is the current script, and all scripts called by it.  Once
         the current script returns, the local variable is removed from
         the environment.

         Variables can be dereferenced by placing the name between carets.
         i.e. ^envarname^

Example:
         pset myfile=sys:nws/td140.nws
         say The current setting of the MYFILE variable is "^myfile^".

See Also:
         SET, SETENV

#####readline
Command: READLINE "message"
         This command is used to prompt the user for a line of input.  It
         will print "message" and then wait for a line of input which is
         terminated when the <ENTER> key is pressed.  The result is stored
         in the system variable "READLINE".

Example:
         readline Enter the new directory:
         while "+readline+" == ""
            readline Please enter the new directory:
         wend
         cd +readline+

#####redir
Command: REDIR [STDOUT | STDERR | STDALL] <[@]FILENAME>
         The REDIR command will redirect the output from stdout or stderr
         or both, to a file.  If the optional '@' is prepended to the file
         name, output is appended to that file.  Otherwise, its current
         contents are truncated.  The STDOUT stream is where informational
         messages from all internal commands is written.  Error messages
         are written to the STDERR stream.  These commands are useful to
         redirect output from a sequence of commands in a script file to
         an intermediate file.

Example:
         redir stdout 1:outfile     # redirect stdout to 1:outfile
         redir stdall /nws/outerr   # redirect std out & err to /nws/outerr

#####ren
Command: REN <OLDNAME> <NEWNAME>
         REN <OLDDIR> <NEWDIR>
         The REN command is used to rename a file, move a file, or move a
         directory.  When a directory is moved, all directories below it
         in the tree are also moved.

Example:
         ren sys:vol$log.err sys:vol$log.sav
         ren 1:file 1:file.bak
         ren /public/mydir /mydir
         ren 2:dir 4:dir    # as long as drives 2: and 4: on same volume!

#####return
Command: RETURN [Return Code]
         The RETURN command is used to return control to the script file which
         called it.  The optional return code may be passed back to the
         caller.  If no return code is specified, it will be zero (0).  The
         caller can access the return code thru the CRETC system variable.

Example:
         mode exec ignore mode = on
         exec myprog
         mode exec ignore mode = off
         if +eretc+ != 0
             return 1
         endif
         return 0

See also:
         EXIT

#####rmdir
Command: RMDIR path
         RD path
         The RMDIR or RD command is used to delete a directory.  Absolute
         or relative paths are valid, as well as those contain drive letters
         and full server/volume path specs.

Example:
         rd sys:mydir
         rd 1:dir1
         rd /public/mydir

#####salvage
Command: SALVAGE [DIRECTORY]
         The SALVAGE command is used to salvage files from a NetWare
         directory.  If no parameter is given, the default working directory
         is used.

Example:
         salvage
         salvage 1:
         salvage AUS-RD/SYS:USERS/KEN

#####say
Command: SAY "message"
         The SAY command is used to write messages to the log file.  By
         default, the log file is the CONSOLE.

Example:
         say This message will go to the log file

See also:
         ECHO

#####setenv
Command: SET envarname=string
         SETENV envarname=string
         The SET command is used to set strings into the new environment.
         The environment is used to hold control strings for any purpose.
         Variables can be dereferenced by placing the name between carets.
         i.e. ^envarname^

Example:
         set include=c:/apps/msc51/inc
         say The current setting of the INCLUDE variable is "^include^".

#####stderr
Command: STDERR "message"
         The STDERR command is used to direct output to the STDERR file of
         the NWShell NLM.  Output from this command CANNOT be redirected
         with the REDIR command!

Example:
         stderr This message will go to the STDERR file

#####stdout
Command: STDOUT "message"
         The STDOUT command is used to direct output to the STDOUT file of
         the NWShell NLM.  Output from this command CANNOT be redirected
         with the REDIR command!

Example:
         stdout This message will go to the STDOUT file

#####stop
Command: STOP ["message"]
         The STOP command is used to stop processing of the current script.
         The optional message is printed.

Example:
         stop Processing complete.

#####system
Command: SYSTEM <NetWare Console Command>
         The SYSTEM command is used to execute a NetWare Console Command.
         The command is given to the System Console, and a carridge is
         appended.  The effect is as if the command had been typed at the
         system console, thus all output goes to the system console.

Example:
         system set immediate purge of deleted files = on

#####type
Command: TYPE <FILENAME>
         The TYPE command is used to display the contents of a file.  For
         files on NetWare volumes, 24 lines are displayed at a time.  For
         files on DOS volumes, the entire file is displayed without a pause.
         Use <CTRL-S> to pause the display for DOS files.  Drive letters
         are supported, as are full server/volume path specifications.

Example:
         type c:/autoexec.bat
         type 4:myfile.txt

#####unredir
Command: UNREDIR [STDOUT | STDERR]
         The UNREDIR command will unredirect the stdout and stderr files,
         causing output from these streams to be displayed on the screen.
         This is useful for debugging script files.  If no parameters are
         given, both STDOUT and STDERR are unredirected.

Example:
         unredir        # unredirect both streams

#####upper
Command: UPPER <environment variable name>
         The UPPER command is used to convert an environment variable string
         to upper case.

Example:
         #
         set mystr=this will be an upper case string
         upper mystr
         # The following will print "THIS WILL BE AN UPPER CASE STRING"
         say "^mystr^"

#####userlist
Command: USERLIST
         Displays a list of all users currently logged into the current
         server.

Example:
         userlist

#####version
Command: VER
         Displays the version number of the NWShell NLM currently executing.

Example:
         ver

#####wend
Command: WEND
         WEND marks the end of a WHILE block.  It is required that each
         WHILE statement be matched with an WEND statement.

Example:
         findfirst *.nws
         while "+ffile+" != ""
             say Match is +ffile+.
         wend

#####whereis
Command: WHEREIS [[SERVER/]VOLUME:][PATH]<FILESPEC>
         Locates <FILESPEC> on the specified SERVER/VOLUME.  Wildcards in the
         file specification are allowed.  Drive letters are also allowed.  If
         a directory is given, the search starts from that directory instead
         of the root.

Example:
         whereis lostfile.txt
         whereis 4:lostfile.*
         whereis sys:p/lostf*.txt
         whereis 7:/p/lostf*.t??

#####while
Command: WHILE <expr> [ logical operator <expr2> ... ]
         The WHILE structure begins a loop if the expression which follows
         is TRUE.  This command allows a set instructions to be repeated until
         a user-defined condition becomes false.  There is a nesting limit of
         eight (8) whiles per script file.  See Section IV - NWShell
         expressions for a full discussion of valid expressions.

Example:
         while ^name^. != .
             call myproc parm1 parm2 parm3
             if +cretc+ != 0
                 say Return code +cretc+ from myproc
                 continue
             endif
             say Got return code of zero from myproc
         wend

#####whoami
Command: WHOAMI
         Displays a list of all servers that the current NWShell session
         is logged into.

Example:
         whoami

#####ynprompt
Command: YNPROMPT "message"
         This command is used to prompt the user for a YN response.  It
         will print "message" and then wait for a keystroke.  It will force
         a 'Y' or 'N' to be pressed.  The result is stored in the system
         variable "YNVAR".

Example:
         ynprompt Do you want to continue?
         if +ynvar+ == N
            stop You chose not to continue...
         endif

#####expr
NWShell Expressions

        The following is a discussion of NWShell expressions.  These express-
ions are used in conjunction with IF, ELIF or WHILE.  The following describes
a valid NWShell expression:

        expr := subexpr [ <logical operator> subexpr [...] ]
        subexpr := operand1 operator operand2
        logical operator := "&& ||"
        operand := any string
        operator :=     "==, !=, <=, >=, <, >, FILE, DIR, CONNECTION"
#####@wait

The operands can be any string, however they may not have imbedded white
space. White space is any character from the set { space, newline, tab }.
The comparisons are done lexicographically, so be careful when trying to do
numerical compares.

The logical operators && for logical AND and || for logical OR associate left
to right, and it is guaranteed that evaluation is stopped as soon as truth or
falsehood is known.

#####@wait
The following table summarizes the NWShell operators:

    Operator        Description
    ----------------------------------------------------------------------
       ==           Equality operator.
       !=           Inequality operator.
       <=           Less than or equal relational operator
       >=           Greater than or equal relational
       <            Less than relational
       >            Greater than relational
       FILE         Test for existance or non-existance of file.
                    Operand2 must be "EXISTS" for testing existance, and
                    "NOTEXI" for testing non-existance.
       DIR          Test for existance or non-existance of subdirectory.
                    Like FILE, Op2 must be either "EXISTS" or "NOTEXI".
       CONNECTION   Test for a current login to a server.  Op2 must be
                    either "EXISTS" or "NOTEXI".
       NLM          Test to see if an NLM is running.  Op2 must be
                    either "EXISTS" or "NOTEXI".
    ----------------------------------------------------------------------
#####~~~~~~~~~~~~~~~

Sample expressions:

        if +MAILDIR+ dir exists
            chdir +MAILDIR+
            if LOGIN.NWS file exists
                # display contents of your login script
                list login.nws
            else
                say You don't have a login script!
            endif
        else
            say Your mail directory +MAILDIR+ does not exist!
        endif
        #
        findfirst  *.*
        while +ffile+. != .
            # process all files, but not directories
            if +ffile+ dir exists
                findnext
                continue
            endif
            lc +ffile+
            findnext
        wend
        #
        if This == This && That != That || This != THis
            say What's the deal with that?
        else
            say Bug in expression handler.
        endif
        #
        if aus-rd connection exists
            say I am logged in to server AUS-RD!
        endif

#####sysvar
NWShell System Variables

        Following is a summary of the NWShell system variables.  These
variables are available at all times, to any script.

        ampm    -   AM if in morning, PM in in afternoon
        cdir    -   current directory without volume.
        cdrive  -   current drive letter.
        cpath   -   current default path.
        cretc   -   return code from last call.
        cserver -   current server.
        cuser   -   current user.
        cvol    -   current volume.
        date    -   current system date mm/dd/yy.
        day     -   current weekday, long version. i.e. Monday
        dow     -   current week day number 0-6. 0 is Sunday.
        doy     -   current day of year (1-366).
        eretc   -   return code from last exec.
#####@wait
        ffile   -   ffirst and fnext matching filespec.
        filename-   filename of currently executing script.
        fname   -   ffirst and fnext matching filename only.
        fpath   -   ffirst and fnext matching pathname only.
        locdate -   current locale system date
        loctime -   current locale system time
        maildir -   mail directory of current user.
        month   -   current month, long version. i.e. February
        newline -   carriage return/line feed.
        lserver -   local server.  i.e. the one NWShell is running on.
        readline-   result of last READLINE.
        sday    -   current weekday, short version. i.e. Mon
        smonth  -   current month, short version. i.e. Feb
        sretc   -   return code from session command.
        time    -   current system time hh:mm:ss.
        week    -   current week number (0-51).
        year    -   current year with century.
        ynvar   -   result of last YNPROMPT.
#####@wait

Access these variables by including the name between plus's i.e. +date+.
A substring can also be parsed by using the format for environment variables
described in Section VII, below.
#####linepreprocess
NWShell Line Preprocessing

        By default, each script line is scanned only once during the pre-
processing phase; thus variables should fully evaluate after a single pass. 
i.e. consider the following environment definitions:

        set filename=d:\myfile
        set newfile=%^filename%^

After execution of the preceding statements, the variables FILENAME and NEWFILE
would be defined.  FILENAME would be equated to the string "d:\myfile", and
NEWFILE would be equated to the string "^filename^".  Notice the use of the
percent sign (%) to imbed the caret.  See Section VIII  NWShell Script
Parameters for more information.  Anyway, the following NWShell script illus-
trates the problem which may occur because of NWShell's single scan evaluation:
#####@wait

        exec myprog ^newfile^

This line would expand to:

        exec myprog ^filename^

not this:
        exec myprog d:\myfile

Be careful to avoid this type of problem with your script files!

New to version 3.11b of NWShell, is a mode called the 'Preprocess Scan Count'. mode, which can be set to the number of times
This mode allows you to specify the number of times that NWShell will scan
input lines, thus providing a workaround to the situation above.  Be careful,
however, as the scan count will affect things like the PROMPT environment
variable, giving unwanted results if not reset back to the default value.
#####environment
#####variables
NWShell Environment Variables

        NWShell environment variables are very similar to DOS environment
variables.  There are a couple of enhancements however, including the ability
to convert an environment string to upper or lower case, and the ability to
parse substrings from a given variable.  Also, environment variables of scope
local and global are supported.  See the SET, SETENV and PSET commands for
more information.

        Unlike DOS environment variables, NWShell variables are substituted by
placing the name between caret signs (^). i.e. ^myvar^.

To parse a substring, use the following format:

                ^SKIPAMOUNT.KEEPAMOUNTvariablename^
#####@wait

For example, assume the following definition:

                set VERSION=1.21

The following illustrates parsing substrings:

                say ^0.1version^  <- expands to ->    "say 1"
                say ^2.2version^  <- expands to ->    "say 21"

The substring format can also be applied to system variables, i.e. those
enclosed in plus's '+'.
#####scriptparms
NWShell Script Parameters

        Like DOS, NWShell also supports parameters to scripts.  They are
accessed in the same way DOS parameters are, that is, using the '%#' format.
i.e. %1 would evaluate to the first parameter, %2 to the second...

        Unlike DOS, NWShell allows more than ten parameters without using the
shift keyword.  Thus %10 and %11 would evaluate to the tenth and eleventh
parameters respectively.

        Parameters can be passed from the command line or when calling a
script, i.e. from the command line:

        0:/> myscript parm1 parm2 parm3 ...

or, from within a script:

        call myscript parm1 parm2 parm3 ...
#####~~~~~~~~~~~~~~~
                      Appendix A - Example Script Files

1.  This script file illustrates how to create a generic login to server
    program.  The script will log you into the specified server using the
    current user name, and map a drive.

        if "%1" == ""
            say usage: +filename+ SERVER [drive:]
            return 1
        endif
        pset server=%1
        upper server
        login ^server^/+CUSER+
        if "%2" != ""
            map %2=^server^/sys:
            %2
        else
            map 7:=^server^/sys:
            7:
        endif
        if ^server^ != +cserver+
            say Could not login to server ^server^
        endif
#####~~~~~~~~~~~~~~~
                       Appendix B - Customizing NWShell


#####userloginscript
Creating a Login Script

        For each user that will log in using NWShell, a LOGIN script should
be created and placed into that object names mail directory.  Every time a
user logs in for the first time, i.e. no other logins in effect, NWShell will
search the objects mail directory for a LOGIN.NWS file.  If found, NWShell
will execute the commands within that file.  This provides a convenient way
to create initial mappings, customize the NWShell environment, log in to
commonly accessed servers, etc.

        Create your login script with an ASCII editor.  Copy the file into
your mail directory.  If you don't know what your mail directory is, login
and do the following copy:

        0:/> copy d:login.nws +maildir+
#####prompt
Setting up the Prompt

        The default prompt used by NWShell is the familiar "d:/path".  It
is used if no prompt environment variable has been defined.  To customize
the prompt, any of NWShell's system variables may be used, as well as any
environment variables.  For example, let's create a prompt that displays
the current server and volume on line 1, then displays the familiar colon
prompt on line 2.  Here is what the command would look like:

    SET PROMPT=%+NEWLINE%+[%+CSERVER%+/%+CUSER%+]%+NEWLINE%+:

Notice the use of the '%' sign to imbed the '+' into the environment
variable.  Without it, NWShell would evaluate the line only once, when the
command was entered.  If the '+' is imbedded into the prompt string, NWShell
will evaluate the line each time the prompt is displayed.

#####searchdir
#####nwsincl
#####path
Specifying Script Search Directories

        If a command is given that is not an internal command name, and it
is not an NLM, NWShell attempts to execute it as a batch file.  Unless an
absolute path is specified, NWShell first attempts to open the script in the
default directory.  If it cannot be found there, then each directory
specified in the NWSINCL environment variable is searched.  The NWSINCL
environment variable is very similar to the DOS PATH variable.  Multiple
directories can be specified by separating each with a semicolon ';'.

        You will probably set the NWSINCL variable in your login script with
a command such as:

        SET NWSINCL=KEN386/SYS:NWS;AUS-RD/SYS:SCRIPTS

Notice that the server name is specified on each path.  This is necessary if
you will be using any of the remote facilities built into the shell.
#####~~~~~~~~~~~~~~~~

