Add a Readme.md

README.md

@@ -0,0 +1,333 @@
+# 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. fileciteturn1file1L1-L6 fileciteturn1file2L18-L44 fileciteturn0file0
+
+## 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. fileciteturn1file2L18-L44 fileciteturn1file0
+
+## 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:
+
+```text
+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. fileciteturn1file1L7-L16 fileciteturn1file2L46-L96
+
+## Command reference
+
+### `LOGIN`
+
+Authenticate to an NCP server as a user.
+
+```text
+LOGIN [-u] [user | user password]
+```
+
+- `-u` forces the older unencrypted login path. fileciteturn1file1L9-L11
+- If no username is provided, the tool prompts interactively. fileciteturn1file2L101-L139
+- If no password is provided, it prompts for one after the username. fileciteturn1file2L125-L138
+- Successful login clears and rebuilds NetWare search-path state before running a local post-login script named `login` from the executable directory. fileciteturn1file2L116-L147
+
+### `LOGOUT`
+
+Log out from the current NCP session.
+
+The implementation also removes configured network search paths before performing logout. fileciteturn1file2L150-L159
+
+### `PASSWD`
+
+Change a user password.
+
+```text
+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. fileciteturn1file1L29-L33 fileciteturn1file2L12-L33
+
+### `PROFILE`
+
+Execute a command script.
+
+```text
+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. fileciteturn1file1L21-L27 fileciteturn1file2L202-L323
+
+### `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(...)`. fileciteturn1file1L54-L57 fileciteturn1file2L357-L390
+
+### `MAP`
+
+List current drive mappings or map a DOS drive letter to a network path.
+
+```text
+MAP [d:[=[path]]]
+```
+
+Examples:
+
+```text
+MAP
+MAP F:=SYS:
+MAP H:=HOME:
+```
+
+The implementation lists active mappings, distinguishes local vs. redirected drives, and uses DOS-style drive letters. fileciteturn1file1L43-L49 fileciteturn1file2L1-L178
+
+### `MAPDEL`
+
+Remove an existing drive mapping.
+
+```text
+MAPDEL d:
+```
+
+Example:
+
+```text
+MAPDEL F:
+```
+
+### `PATH`
+
+List or set a search-path entry.
+
+```text
+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. fileciteturn1file1L34-L42 fileciteturn1file2L180-L288
+
+### `PATHINS`
+
+Insert a search-path entry instead of overwriting one.
+
+```text
+PATHINS sn:[=[path]]
+```
+
+### `PATHDEL`
+
+Delete a search-path entry.
+
+```text
+PATHDEL sn:
+```
+
+### `CAPTURE`
+
+List printer captures or redirect a local printer device to a queue.
+
+Typical usage:
+
+```text
+CAPTURE [device [queue]]
+```
+
+Examples:
+
+```text
+CAPTURE
+CAPTURE LPT1 Q1
+CAPTURE PRN Q1
+```
+
+`PRN` is normalized to `LPT1` internally. The command can also display existing captures. fileciteturn1file2L1-L77
+
+### `ENDCAP`
+
+Cancel a printer redirection.
+
+Typical usage:
+
+```text
+ENDCAP device
+```
+
+Example:
+
+```text
+ENDCAP LPT1
+```
+
+### `DEBUG`
+
+Set mars_nwe debug levels for selected server-side modules.
+
+```text
+DEBUG NCPSERV|NWCONN|NWBIND level
+```
+
+- `level` must be between `0` and `99`. fileciteturn1file2L1-L31
+- The original docs say this requires `FUNC_17_02_IS_DEBUG` to be enabled in `mars_nwe/config.h`. fileciteturn1file1L50-L53
+
+### `ECHO`
+
+Print a string, mainly for use inside profile/login scripts. fileciteturn1file2L350-L355
+
+### `CD`
+
+Change the current DOS directory. It also adjusts the active drive if a drive-qualified path is supplied. fileciteturn1file2L329-L348
+
+### `TESTS`
+
+Internal developer test routines. Not intended as a regular end-user command. fileciteturn1file2L39-L43
+
+## 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:
+
+```text
+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. fileciteturn1file1L12-L20 fileciteturn1file2L140-L147
+
+## 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`
+
+fileciteturn1file2L1-L18
+
+### 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. fileciteturn0file0
+
+## 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`. fileciteturn0file0
+
+## 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. fileciteturn1file1L6-L7
+- `SLIST` is not implemented in the provided source snapshot. fileciteturn1file2L36-L39 fileciteturn1file0
+- Parts of the authentication and password-change path still rely on older unencrypted operations when the newer keyed flow is unavailable or disabled. fileciteturn1file2L12-L33
+- 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
+
+fileciteturn1file2L1-L4
+
+## 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. fileciteturn1file2L1-L5