The following rules define the nShell external command interface.
File Types
----------
nShell command files have a creator of ‘NSHA’, and a type of ‘NSHC’.
Code Resource Types
-------------------
The nShell environment supports single-segment code resources. The code resource for a command should have a type of ‘NSHC’ and a name of "command".
Resource Numbers
----------------
With the exception of ‘vers’ resources, all resources within nShell command files have I.D. numbers of 16000 or higher. See the section called “An Example Command” for more about setting up command resources.
The File “nshc.h” Defines The C Interface
-----------------------------------------
The “main” for nShell commands is defined in nshc.h. At run time, this main is passed pointers for two parameter blocks, also defined in nshc.h. The “nshc_calls” block defines the callback interface to the nShell application. The “nshc_parms” block defines the data available to the command.
Passing Arguments
-----------------
Three fields within nshc_parms contain arguments to nShell commands:
argc The number of arguments (including the command itself)
argv An array of indexes into the command line buffer
arg_buf The command line buffer
The arg_buf contains a series of null-terminated strings, one for each command argument. The start of a particular string is arg_buf[ argv[ n ] ], where n is the argument number 0..(argc-1).
The Command Must Accept Start/Continue/Stop Messages From The Application
External commands base their actions upon the “action” scalar within the nshc_parms record:
nsh_idle do nothing
nsh_start do part or all
nsh_continue continue processing
nsh_stop clean up and exit
The Command Must Give Up Time For Multitasking
----------------------------------------------
Task switches in the nShell environment occur only when a command "returns" to the main application. If a command requires more than a small amount of time to execute or if it requires keyboard input from the operator, the command should give time back to the application. In this procedure, a command should set it's action scalar to nsh_continue and return back to the application. When other tasks have been satisfied the application will again call the command. The command should then use the action scalar or custom data to determine what internal actions are required. See the "delay" command for an example.
The Command Must Signal Completion
----------------------------------
Whenever a command completes its task, it must set two variables in the nshc_parms data structure. The ‘action’ scalar must be set to to nsh_idle, and the ‘result’ variable must be set to reflect success or failure ( <0 = error, 0 = success, >0 = non-error return values ).
Data Allocation
---------------
Commands allocate storage in two ways:
First, local variables may be defined within each routine.
Secondly, data may be allocated using NewHandle. Any such data structure must be hung off the “data” handle within nshc_parms. The command is responsible for disposing of this data before going into an nsh_idle state.
