mars-dosutils/README.md

mars_dosutils

DOS client-side utilities for mars_nwe and compatible NetWare-style NCP environments.

This repository contains the source for a small DOS utility suite built around a single multi-call executable, net.exe. The program can be used either as:

• net <command> [args...], or
• a renamed executable such as login.exe, map.exe, capture.exe, or logout.exe

That design is explicit in the command table in net.c, and the install rules also deploy the same binary under multiple command names. The original project documentation describes it as a “simple DOS-client program to allow standard NCP network actions, mainly for mars_nwe,” and also notes that it was still incomplete at the time of writing.

Features

• Login and logout against an NCP server
• Password change support
• DOS drive mapping and unmapping
• Search-path management (PATH, PATHINS, PATHDEL)
• Printer capture and release (CAPTURE, ENDCAP)
• Scripted session setup through command files
• External program execution via SPAWN and EXEC
• Optional mars_nwe debug control hooks

Available commands

The current command dispatcher includes these built-ins:

• LOGIN
• LOGOUT
• PASSWD
• PROFILE
• SPAWN
• EXEC
• MAP
• MAPDEL
• PATH
• PATHINS
• PATHDEL
• CAPTURE
• ENDCAP
• DEBUG
• ECHO
• CD
• TESTS (developer/testing only)

SLIST is present in the historical build/install metadata, but the command is disabled in the dispatcher and the provided slist.c is only a stub in this source snapshot.

How it works

The program resolves the command from either:

1. the executable name itself, or
2. the first command-line argument

That means all of the following styles are valid:

NET LOGIN alice secret
NET MAP F:=SYS:
LOGIN.EXE alice secret
MAP.EXE F:=SYS:
CAPTURE.EXE LPT1 Q1

This is one of the key design ideas of the project, and the original README specifically recommends copying or linking net.exe to login.exe for convenience.

Command reference

LOGIN

Authenticate to an NCP server as a user.

LOGIN [-u] [user | user password]

• -u forces the older unencrypted login path.
• If no username is provided, the tool prompts interactively.
• If no password is provided, it prompts for one after the username.
• Successful login clears and rebuilds NetWare search-path state before running a local post-login script named login from the executable directory.

LOGOUT

Log out from the current NCP session.

The implementation also removes configured network search paths before performing logout.

PASSWD

Change a user password.

PASSWD [user]

Notes:

• If no username is supplied, the tool attempts to resolve the currently logged-in user. fileciteturn1file2L162-L190
• The source comments note that password changes currently use the older unencrypted password-change call.

PROFILE

Execute a command script.

PROFILE <filename>

This is a central part of the workflow. The command reader parses non-empty lines, ignores # comments, uppercases the command token, and dispatches it through the same internal command table used for direct invocation. ECHO is treated specially so the rest of the line is preserved as a single string.

SPAWN

Run an external program and wait for it to finish.

EXEC

Execute an external program using overlay-style execution.

Both commands share the same implementation and differ only in whether they use spawnvp(..., P_WAIT, ...) or execvp(...).

MAP

List current drive mappings or map a DOS drive letter to a network path.

MAP [d:[=[path]]]

Examples:

MAP
MAP F:=SYS:
MAP H:=HOME:

The implementation lists active mappings, distinguishes local vs. redirected drives, and uses DOS-style drive letters.

MAPDEL

Remove an existing drive mapping.

MAPDEL d:

Example:

MAPDEL F:

PATH

List or set a search-path entry.

PATH sn:[=[path]]

Where sn is s1 through s16. The original documentation notes that this updates the path environment rather than directly creating a drive mapping.

PATHINS

Insert a search-path entry instead of overwriting one.

PATHINS sn:[=[path]]

PATHDEL

Delete a search-path entry.

PATHDEL sn:

CAPTURE

List printer captures or redirect a local printer device to a queue.

Typical usage:

CAPTURE [device [queue]]

Examples:

CAPTURE
CAPTURE LPT1 Q1
CAPTURE PRN Q1

PRN is normalized to LPT1 internally. The command can also display existing captures.

ENDCAP

Cancel a printer redirection.

Typical usage:

ENDCAP device

Example:

ENDCAP LPT1

DEBUG

Set mars_nwe debug levels for selected server-side modules.

DEBUG NCPSERV|NWCONN|NWBIND level

• level must be between 0 and 99.
• The original docs say this requires FUNC_17_02_IS_DEBUG to be enabled in mars_nwe/config.h.

ECHO

Print a string, mainly for use inside profile/login scripts.

CD

Change the current DOS directory. It also adjusts the active drive if a drive-qualified path is supplied.

TESTS

Internal developer test routines. Not intended as a regular end-user command.

Login script workflow

A particularly important feature is the automatic execution of a file named login located beside the executable after a successful login. The historical README gives this example:

map     f:=SYS:
map     h:=home:
map     z:=SYS:PUBLIC
path    s16:=z:.
capture lpt1 q1
profile h:\profile

This makes the tool suite useful not just for authentication, but for setting up a full DOS network session: drive mappings, search paths, printer capture, and then a user-specific profile script.

Building

Historical DOS build

The included makefile.bcc is the primary historical build file and targets Borland C / Borland tools on DOS.

Key settings from the makefile:

• compiler: bcc
• linker: bcc
• assembler: tasm
• memory model: -ml
• define: -Dmsdos
• output: net.exe

The object list includes:

• net.c
• tools.c
• netcall.c
• ncpcall.c
• login.c
• map.c
• slist.c
• nwcrypt.c
• nwdebug.c
• nwtests.c
• capture.c
• kern.asm

CMake status

A CMakeLists.txt is present, but in this snapshot it is only a partial modern build description. It defines include paths, version-related macros, and install rules, while the actual add_executable(...) line is still commented out. That means it is better understood as packaging metadata than a ready-to-use complete build system.

Installation layout

The CMake install rules deploy the same binary multiple times into SYS/public:

• net.exe
• login.exe
• profile.exe
• spawn.exe
• passwd.exe
• path.exe
• pathins.exe
• pathdel.exe
• map.exe
• mapdel.exe
• logout.exe
• slist.exe
• capture.exe
• endcap.exe

They also install minimal login.exe and map.exe copies into SYS/login.

Project status and limitations

This is legacy DOS networking code from the mid-1990s, and a few caveats are worth keeping in mind:

• The original README explicitly says the program was still incomplete.
• SLIST is not implemented in the provided source snapshot.
• Parts of the authentication and password-change path still rely on older unencrypted operations when the newer keyed flow is unavailable or disabled.
• The code is tightly coupled to DOS, IPX/NCP behavior, and mars_nwe-specific expectations.

Historical metadata

From the included project metadata:

• project: mars_dosutils
• version: 0.10
• entered: 21-May-96
• keywords: mars_nwe, dos, dosemu
• platforms: DOS, DOSEMU
• author/maintainer: Martin Stover

License

No standalone license file is included in the provided snapshot. The source files do contain copyright notices naming Martin Stover. Anyone planning to redistribute or modernize the project should verify licensing status before publishing derivative releases.