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`, `flag.exe`, `flagdir.exe`, `capture.exe`, or `logout.exe`.

The command dispatcher lives in `net.c`, and the install rules deploy the same binary under multiple command names in `SYS:PUBLIC` and selected names in `SYS:LOGIN`.

## Current status

The tree is a modernization of the historical mars_nwe DOS utilities. It still keeps the original Borland-era style and APIs where useful, but now also has an Open Watcom/CMake build path and working DOS Client32 support for the FLAG-family tools.

Validated recently:

- `FLAG` file attribute read/modify through DOS Client32
- `FLAGDIR` directory attribute read/modify through DOS Client32
- Novell-tool comparison for `FLAG`, including `ALL`, `N`, `RO`, `RW`, high bits, and display layout
- Novell-tool comparison for `FLAGDIR`, including `Normal`, `System`, `Hidden`, `DeleteInhibit`, `Purge`, `RenameInhibit`, and combined attributes
- CMake/Open Watcom build using binary-directory object files, so `.obj`/`.o` files are no longer written into the source tree

Still to validate or continue:

- DOSX/VLM/NETX fallback behavior for `FLAG` and `FLAGDIR`
- More complex `FLAGDIR` paths beyond the simple mapped-directory cases already tested
- OS/2 requester/tool behavior
- Additional Novell-like utilities such as `RIGHTS`, `GRANT`, `REVOKE`, `NDIR`, `PURGE`, and `SALVAGE`

## 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`
- Server listing through `SLIST`
- File attribute management through `FLAG`
- Directory attribute management through `FLAGDIR`
- Effective rights display through `RIGHTS`
- Optional mars_nwe debug control hooks
- Developer diagnostics through `TESTS`

## Available commands

The current command dispatcher includes these built-ins:

- `LOGIN`
- `LOGOUT`
- `PASSWD`
- `PROFILE`
- `SPAWN`
- `EXEC`
- `MAP`
- `MAPDEL`
- `PATH`
- `PATHINS`
- `PATHDEL`
- `CAPTURE`
- `ENDCAP`
- `SLIST`
- `FLAG`
- `FLAGDIR`
- `RIGHTS`
- `DEBUG`
- `ECHO`
- `CD`
- `TESTS` developer/testing only

The CMake install rules also install the multi-call `net.exe` under several of those command names.

## 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:
NET FLAG LOGIN.EXE
LOGIN.EXE alice secret
MAP.EXE F:=SYS:
FLAG.EXE LOGIN.EXE A
CAPTURE.EXE LPT1 Q1
```

## Client32 NCP support

The modern Client32 path is implemented through a small reusable helper layer:

- `c32ncp.c`
- `c32ncp.h`
- Client32 assembly entry points in `kern_wasm.asm`

The working sequence is:

```text
C32_MapVar_Probe(4,0)
  -> obtains the active connection reference

C32_OpenRef_Probe()
  -> opens that reference and returns a Client32 handle

C32_NCP87_Raw5_Probe()
  -> sends NCP 87 requests through COMPATNcpRequestReply
```

This path is currently used by:

- `FLAG`
- `FLAGDIR`
- `RIGHTS`

The old `Net_Call` / INT 21h requester path is kept as a fallback where appropriate, but Client32 is now preferred for the validated FLAG-family operations.

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

If no username is supplied, the tool attempts to resolve the currently logged-in user. The password-change code prefers the encrypted/keyed flow where available and keeps older unencrypted calls as fallback.

### `PROFILE`

Execute a command script.

```text
PROFILE <filename>
```

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

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

### `SLIST`

List known NetWare file servers.

Typical usage:

```text
SLIST [server] [/Continue]
```

The current `slist.c` implementation scans bindery file server objects and prints known servers.

### `FLAG`

Display or modify NetWare DOS file attributes.

Typical usage:

```text
FLAG file [option...]
```

Examples:

```text
FLAG LOGIN.EXE
FLAG LOGIN.EXE A
FLAG LOGIN.EXE -A
FLAG LOGIN.EXE P T DI RI CI RA WA
FLAG LOGIN.EXE N
FLAG LOGIN.EXE ALL
FLAG LOGIN.EXE RO
FLAG LOGIN.EXE RW
```

Supported attributes and aliases include:

- `RO`
- `RW`
- `S`
- `A`
- `H`
- `SY`, `SYS`, `SYSTEM`
- `T`
- `P`
- `RA`
- `WA`
- `CI`
- `DI`
- `RI`
- `ALL`
- `N` / `NORMAL`

The output is intentionally close to Novell FLAG formatting:

```text
Ro/Rw S/- A/- - H/- Sy/-- T/- P/- Ra/-- Wa/-- CI/-- DI/-- RI/--
```

The Client32 path handles both low and high NetWare attribute bits. High bits such as `P`, `DI`, `RI`, `CI`, `RA`, and `WA` must be handled as 32-bit values in 16-bit DOS builds.

### `FLAGDIR`

Display or modify NetWare directory attributes.

Typical usage:

```text
FLAGDIR [path [option...]]
```

Supported 386-style options:

- `Normal`
- `System`
- `Hidden`
- `DeleteInhibit`
- `Purge`
- `RenameInhibit`

Examples:

```text
FLAGDIR UDIR
FLAGDIR UDIR SYSTEM
FLAGDIR UDIR HIDDEN
FLAGDIR UDIR DELETEINHIBIT
FLAGDIR UDIR PURGE
FLAGDIR UDIR RENAMEINHIBIT
FLAGDIR UDIR NORMAL
```

For simple mapped paths, the display is kept close to Novell FLAGDIR style:

```text
MARS/SYS:UDIR
        UDIR        System Hidden DeleteInhibit Purge RenameInhibit
```

`Private` is intentionally rejected for the current NetWare 386-style path.


### `RIGHTS`

Display effective NetWare rights for a file or directory.

Typical usage:

```text
RIGHTS [path]
```

Supported in this first version:

- directory paths
- file paths, using the parent directory rights for the first read-only implementation
- Novell-like display of the effective rights mask

Rights are shown in the traditional order:

```text
S R W C E M F A
Supervisor, Read, Write, Create, Erase, Modify, File scan, Access Control
```

### `DEBUG`

Set mars_nwe debug levels for selected server-side modules.

```text
DEBUG NCPSERV|NWCONN|NWBIND level
```

- `level` must be between `0` and `99`.
- This requires the matching mars_nwe server-side debug call to be enabled.

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

The currently useful Client32 test is:

```text
TESTS NCP87C32ATTR
```

It verifies the working Client32 NCP87 attribute path.

## Login script workflow

A particularly important feature is the automatic execution of a file named `login` located beside the executable after a successful login.

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 historical object list includes the original C sources plus `kern.asm`.

### CMake / Open Watcom maintainer build

The modern CMake build can rebuild `net.exe` with Open Watcom v2 on Linux.

Configure with:

```bash
cmake -S . -B build -DMARS_NWE_BUILD_DOSUTILS=ON
cmake --build build
```

The CMake build:

- assembles `kern_wasm.asm` with `wasm`
- compiles each C file to a binary-directory `.obj`
- links `net.exe` from those binary-directory objects
- keeps `.obj`/`.o` intermediate files out of the source directory

If old object files were produced in the source tree by an earlier build, remove them once:

```bash
cd dosutils
rm -f *.o *.obj
```

### Default install behavior

When `MARS_NWE_BUILD_DOSUTILS` is disabled, CMake installs a prebuilt `net.exe` from the source tree.

That keeps the normal mars_nwe build independent from Open Watcom. Maintainers can enable the Open Watcom build only when they want to regenerate the DOS binary.

## Installation layout

The install rules deploy the same binary multiple times into `SYS/public`, including:

- `net.exe`
- `login.exe`
- `profile.exe`
- `spawn.exe`
- `passwd.exe`
- `path.exe`
- `pathins.exe`
- `pathdel.exe`
- `map.exe`
- `mapdel.exe`
- `logout.exe`
- `slist.exe`
- `flag.exe`
- `flagdir.exe`
- `capture.exe`
- `endcap.exe`

They also install selected copies such as `login.exe`, `map.exe`, and `slist.exe` into `SYS/login` where appropriate.

## Development notes

- `kern_wasm.asm` is the 16-bit Open Watcom assembly implementation used by the modern build.
- `kern.c` was an experimental C-side test wrapper and is no longer required by the current Client32 FLAG/FLAGDIR path.
- `c32ncp.c` and `c32ncp.h` contain reusable Client32 NCP helper functions for DOS tools.
- The verified Client32 path uses NCP 87 subfunction 6 for obtaining DOS information and subfunction 7 for modifying DOS information.
- For modify operations, use the modify information mask `DM_ATTRIBUTES` (`0x00000002`) rather than the read-side `RIM_ATTRIBUTES` mask.
- High NetWare attributes must be stored and displayed as 32-bit values even in 16-bit DOS builds.

## Project status and limitations

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

- The code is tightly coupled to DOS, IPX/NCP behavior, and mars_nwe/NetWare requester semantics.
- Client32 support has been validated for the FLAG-family tools, but not yet generalized to every command.
- DOSX/VLM/NETX fallback testing is still pending.
- `FLAGDIR` currently focuses on the NetWare 386-style attributes and simple mapped directory paths.
- OS/2 requester behavior is still future work.
- Some authentication and password-change paths still keep older calls as compatibility fallbacks.

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