mars_nwe/mars-dosutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add a Readme.md

Browse Source
This commit is contained in:
Mario Fetka
2026-04-22 14:41:55 +02:00
parent ad2bc6b02e
commit dcb74331e7
1 changed files with 333 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

333
README.md Normal file
View File

@@ -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