# 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:

```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. 

## Command reference

### `LOGIN`

Authenticate to an NCP server as a user.

```text
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.

```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. 

### `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. 

### `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.

```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. 

### `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. 

### `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. 

### `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`. 
- 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:

```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. 

## 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. 
