Architecture of the Command Library

Library

A collection of Procedures, Functions, Constants, Mount/\Commands, CmdShorthand, /GlobalSwitches and !GuardNotes implemented in a single file.

Provides an infrastructure to enhance the operation of internal and external scripts.

Infrastructure Facilities include:

    /GlobalSwitches, $Functions, internal .Mount/\Commands and #Constants

    Quiet Mode (display only errors)

    Track Mode (display additional tracking information for troubleshooting or learning)

    Verbose Mode (display additional commands, output and errors as they are processed)

    Advanced error handling and parameter checking

    Advanced Packaging and Indexing of library contents

    Completely self-contained internal help system (customizable for additional languages)

/GlobalSwitch

A switch which affects the entire library rather than any individual task.  GlobalSwitches are specified BEFORE the TaskID and always have a short and a long name which can be used interchangeably (/GS or /GlobalSwitches).

Example Syntax Chart		Where Used
NTCmdLib /GlobalSwitch [TaskID] [TaskSwitches] [TaskParameters]		at the command prompt (library IS NOT initialized)
L /GlobalSwitch [TaskID] [TaskSwitches] [TaskParameters]		at the command prompt (library IS initialized)
CALL NTCmdLib /GlobalSwitch [TaskID] [TaskSwitches] [TaskParameters]		in a script (library IS NOT initialized)
%.Call% /GlobalSwitch [TaskID] [TaskSwitches] [TaskParameters]		in a script (library IS initialized)

Examples of GlobalSwitches are:

  /I or /Init    /Q or /Quiet    /T or /Track    /V or /Verbose

:Procedure

A section of scripting code that performs a single task or multiple related tasks.  Most procedures are really entire standalone scripts that have been modified to exist in the library so they can take advantage of library facilities.

Operation can be modified by GlobalSwitches.

Can also accept procedure-specific command line switches to control or modify procedure operation or output.

Can call other procedures or functions (inside or outside of the library) to complete the requested task(s).

Tracks variables globally, locally and within the procedure itself.  Generally "cleans up" after itself and leaves behind only what is specifically desired/requested.

Procedure names must begin with the colon (:) symbol and should consist of only numbers and letters (A-Z, a-z, 0-9).  All :procedures have two names, a LongName and ShortName.

The LongName can be from two to seven words separated by underscores "_".  The ShortName consists of the Embedded_Capital_Letters (actually the first letter of each word) from the LongName (ECL, for example).

Embedded capital letters are recommended for readability but the name is NOT case sensitive when called.

Return results via exit codes (errorlevels), variables and/or files.

Example Syntax Chart		Where Used
NTCmdLib [/GlobalSwitches] :Procedure_Name [/ProcedureSwitches] [ProcedureParameters]		at the command prompt (library IS NOT initialized)
L [/GlobalSwitches] :Procedure_Name [/ProcedureSwitches] [ProcedureParameters]		at the command prompt (library IS initialized)
CALL NTCmdLib [/GlobalSwitches] :Procedure_Name [/ProcedureSwitches] [ProcedureParameters]		in a script (library IS NOT initialized)
%.Call% [/GlobalSwitches] :PN [/PS] [ProcedureParameters]		in a script (library IS initialized)

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.

$FUNCTION

A (usually very short) section of scripting code that performs a single task.

Does not accept any command line switches.

Obeys library /GlobalSwitches.

Can call other functions (inside the same library) to complete it's task.

Not recommended to call procedures or external scripts (if this is needed, implement the task as a :Procedure rather than a $FUNCTION).

Function names must begin with the dollar ($) symbol and should consist of only numbers and letters (A-Z, a-z, 0-9).  Embedded capital letters are recommended for readability but the name is NOT case sensitive when called.

$FUNCTION, $function and  $Function are all identical.  The first example is the recommended form.

Generally return results via exit codes (errorlevels) or variables.

Quick Syntax Chart		Where Used
NTCmdLib [/GlobalSwitches] $FUNCTION [parameters]		at the command prompt (library IS NOT initialized)
L [/GlobalSwitches] $FUNCTION [parameters]		at the command prompt (library IS initialized)
CALL NTCmdLib [/GlobalSwitches] $FUNCTION [parameters]		in a script (library IS NOT initialized)
%.Call% [/GlobalSwitches] $FUNCTION [parameters]		in a script (library IS initialized)

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.

.Mount/\Command

A specially-formatted segment of mnemonically-named scripting code that can be invoked in a script or on the command line.

Available to external scripts (after a Library Initialization) without calling the library itself.

Greatly enhance the readability and maintainability of scripting code.

Standardize the operation of commands that perform differently on different operating systems (NT/2K/XP/K3).

MountCommand names must begin with the dot (.) symbol and should consist of only numbers "0-9",  letters "A-Z, a-z" and the underscore "_".

Embedded capital letters are recommended for readability but the name itself is NOT case sensitive when called.

Quick Syntax Chart		Where Used
%.MountCommand% [parameters]		in a script or at the command prompt
. MountCommand [parameters]		at the local command prompt only (using the included CmdShorthand ".")

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.

Command ShortHand (CS)

An extremely brief command available only from the local console.  Designed for minimum typing and maximum productivity.

Quick Syntax Chart		Where Used
CS [parameters]		at the local command prompt only

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.

#Constant

Mnemonically-named variables that contain commonly used values.

The variable name is usually shorter than it's content, but not always.
Clarity is given priority over brevity.

Available to external scripts (after a Library Init) without calling the library itself.

Greatly enhance the readability and maintainability of scripting code.

Preload or "cache" commonly used values so they can be referenced directly, and without any additional scripting code or calculations.

Constant names must begin with the pound (#) symbol and should consist of only numbers and letters (A-Z, a-z, 0-9).  Mixed case is strongly recommended for readability but the constant itself is NOT case sensitive when accessed.

#CONSTANT, #constant and  #Constant are all identical.

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.

!GuardNotes

Sections of customizable and expandable text attached to the library file.

Can be implemented as external .cmdnote files or embedded within the library itself (embedding is highly recommended).

Embedded !GuardNotes are not parsed by the command interpreter (Cmd.exe) when executing library $FUNCTIONS and :Procedures.  In fact, they not even visible using normal viewing methods such as "TYPE NTCmdLib.cmd".

!GuardNotes are part of the Library file and will be copied along with the Library whenever it is copied or moved, as long as the file remains on an NTFS drive.

The internal help system of the library is implemented using a special type of !GuardNote (a .cmdhelp file).  As such, it is fully customizable for language translation and/or expansion for environment specific help screens.

Editing the library file directly using most text editors will irrevocably remove all !GuardNotes (including the builtin .cmdhelp files) without warning!  (the standard Notepad.exe that is included with Windows DOES NOT have this limitation)

The above are only examples.  See the main library help page at NTCmdLib /? for complete syntax instructions.