RegisterConsoleCommand

Registers a console command parsing function

Local Servers:nonblocking
Remote Servers:N/A
Classification:3.11, 3.12, 3.2, 4.x, 5.x, 6.x
Service:Advanced

Syntax

  #include <nwadv.h>  
   
  LONG RegisterConsoleCommand  (  
     struct commandParserStructure   *newCommandParser);

Parameters

newCommandParser

(IN) Points to a command parsing function.

Return Values

If RegisterConsoleCommand is successful, it returns 0. Otherwise, it returns 0xFFFFFFFF.

newCommandParser.parseRoutine returns the following values:

0

The command was handled and does not allow any subsequently registered command parser to be envoked.

Nonzero

The command was not handled. The console command thread looks for other command parsers to handle the command. If none does, NetWare displays "??? Unknown Command ???"

Remarks

The command parsing function is called by the operating system whenever an unrecognized console command is entered. The parsing function is called with two parameters: a screen ID and a pointer to the complete console command line (an ASCIIZ string).

The commandParserStructure can be found in the nwadv.h header file and has the following definition:

  struct commandParserStructure  
     {  
     struct commandParserStructure *Link;  
        /* Set by RegisterConsoleCommand */  
     LONG (*parseRoutine) (  /* Parsing routine (user-defined) */  
        LONG screenID,  
        BYTE *commandLine);  
     struct ResourceTagStructure *RTag;/* Set to resource tag */  
     };

The required resource tag is obtained with a call to AllocateResourceTag using the ConsoleCommandSignature constant (defined in nwadv.h) as the signature value.

The function registered by RegisterConsoleCommand runs as a callback (an OS Thread), which is not able to call most of the NetWare API functions, unless it is given CLIB context.

For 3.11 NLM applications, you must manually create the thread group context in your command parser, by calling SetThreadGroupID and passing a valid thread group ID. Before this thread returns, it should reset its context to its original context, by setting the thread group ID back to its original value.

For 4.x, 5.x, and 6.x NLM applications, the context that is given to the callbacks when they are registered is determined by the value in the registering thread’s context specifier. You can set the context specifier to one of the following options:

  • NO_CONTEXT-Callbacks registered with this option are not given CLIB context. The advantage here is that you avoid the overhead needed for setting up CLIB context. The disadvantage is that without the context the callback is only able to call NetWare API functions that manipulate data or manage local semaphores.

    Once inside of your callback, you can manually give your callback thread CLIB context by calling SetThreadGroupID and passing in a valid thread group ID. If you manually set up your context, you need to reset its context to its original context, by setting the thread group ID back to its original value.

  • USE_CURRENT_CONTEXT-Callbacks registered with a thread that has its context specifier set to USE_CURRENT_CONTEXT have the thread group context of the registering thread.

  • A valid thread group ID-This is to be used when you want the callbacks to have a different thread group context than the thread that schedules them.

When a new thread is started with BeginThread, BeginThreadGroup or ScheduleWorkToDo, its context specifier is set to USE_CURRENT_CONTEXT by default.

You can determine the current setting of the registering thread’s context specifier by calling GetThreadContextSpecifier. Use SetThreadContextSpecifier to set the registering thread’s context specifier to one of the above options.

For more information on using CLIB context, see Context Problems with OS Threads (NDK: NLM Threads Management).

See Also

AllocateResourceTag, UnRegisterConsoleCommand