In relation to the Tandy TRS-80 Model 1 and Model III, what are "ISAM" and "PDS"?

Question

While working with the TRS-80 /CMD file format I came across a couple of terms used frequently, but for which I'm struggling to find any definitions. Here's an example from the trscmdff.txt, which may be the definitive guide to the /CMD file format:

08      ISAM directory entry
09
0A      End of ISAM directory
0B
0C      PDS directory entry
0D
0E      End of PDS directory

Googling, I can find the terms used in old magazines etc, but I always pretty much like this, where the reader is either assumed to already know what they mean, or maybe to just treat them as jargon not relevant to them. For instance, I don't actually need them to be able to parse and load \CMD files.

But I didn't turn up any articles about them, or even any definitions. What do they mean?

Answer 1

TL;DR: They are record based structures within LDOS libraries

• ISAM is About Indexing Data while
• PDS Manages the Library Directory

ISAM - Index Sequential Access Method

ISAM is a concept to store records sorted by key allowing a sequential read according to key, like a simple sequential file, but also accessing records direct by their full or partial key value. This can be reached by either structured read (*1) until the desired record is found or use of one or more index hierarchies.

LDOS (*2) uses that idea, but deliver a ... lets say 'more simple' implementation. Here it is only within PDS and only with limited range but still offering a nice additional abstraction layer.

PDS - Partitioned Data Set

In LDOS PDS are what others may call a library. Except, most (non user) files in LDOS are such libraries structured with records of various types. Except the naming is a bit confusing, so we need to take a little detour before seeing how it works

The Bigger Picture:

Naming and concept of PDS is taken from IBM mainframe language, where Data Set is a collection of records - think a stack of punch cards. A Data Set is always structured (at least as records), while a File is an unstructured data blob.

A Partitioned Data Set in turn is a collection of (usually smaller) Data Sets stored into a single file - think a large card stack composed of several smaller. Kind of a ZIP file without compression. The main difference to such is that operations on members do not need a external tools but are part of the base OS. That is one can handle PDS members as if they are Data Sets (files) of their own.

So when THEAPP names a (library) file, THEAPP(STARTUP) would name a member thereof, possible the program (or script) used to start it. With this notation (as well taken from IBM Mainframe *3) each Member can be handled as if it's a program/script/file of it's own. A bit like a directory, except from file system PoV it's a single file, easy to move, copy or have it's access changed.

Such a PDS can store many different things including text (THEAPP(README)), data, sources (THEAPP(SOURCE)), scripts (THEAPP(REPORT)), object modules (THEAPP(OVL1)) or programs(THEAPP(GUI)). Software delivery can be made by one file only, without the need to unpack it or install (well, maybe there's a THEAPP(SETUP) :)). (*4)

This is quite handy for organization and handling of many small files like scripts or parameter lists. Instead of having hundreds of files clustering the directory, a single library file can hold all scripts and programs needed for an application. Saves on space needed and adds execution speed.

LDOS uses the concept of libraries all around. In fact, all system file structures are such libraries as nicely shown by your table (*5). This can be seen for example with

Commands

Systems like CP/M or MS-DOS for example implement commands either as part of the command processor (COMMAND.COM) or rely on external programs, one per command, as anything not hard coded is assumed to be an external program. For example all transient commands are bundled in SYS6 and SYS7 - they are what the command processor searches for 'Build-In' commands. Want to add a new command? Place it in one of those.

Using the PDS/ISAM structures is how LDOS can access the overlay code for that command as fast as possible. An FCB is already prepared for either system library, so no directory search needed, just peek into the file searching the header and jump direct toward loading the code. One reason why LDOS was comparably slim and fast.

How it Works

Which brings us to the question what 'PDS Directory Entry' and 'End of PDS Directory' are about: They are library records markers for the directory of all library members.

0Ch PDS Directory Entry

Each PDS Directory Entry record (type 0Ch) consists of

• 1 Byte Type (0Ch)
• 1 Byte Data Length (usually 0Bh)
• 8 Byte Member Name (there ist no type/extension)
• 1 Byte ISAM Entry Number
• 2 Byte Flags and Date Added

The ISAM Entry Number is what points into the ISAM records for further information.

0Eh End of PDS Directory

The end of the PDS Directory is marked by a single type 0Eh record with data length 1 and a single null-byte as data content (empty data is not allowed). When the searched entry is not found the system continues depending on situation. if its LibA (SYS6) then with LibB (SYS7), otherwise error. Later LDOS versions added more possible search pattern.

What follows is the ISAM Directory (*6).

08h ISAM Directory Entry

Each ISAM Directory Entry record (type 08h) consists of

• 1 Byte Type (08h)
• 1 Byte Data Length (06h or 09h)
• 1 Byte ISAM Number (key)
• 2 Byte Transfer Address (entry point)
• 2 Byte Next Record Number (sector number)
• 1 Byte Relative Byte Offset (in sector)

Important part here are the last 3 bytes pointing to a sector (within this file) and a byte offset where the first record for the addressed member resides. If that's the record looked for, SYS1, the part of DOS reading a member for loading, will simply copy those 3 bytes into the same field of the file's FCB. Next read will be straight from the PDS member. Very nifty (*7).

Later LDOS extended that scheme by adding another 3 Byte NRN/Offset marking the end of the addressed member. This allowed use of binary blobs outside the record structure. Here the value was simply copied into the FCB's file end pointer, enabling fastes possible transparent operation.

0Ah End of ISAM Directory

The end of the ISAM Directory is marked by a single type 0Ah record again with data length 1 and a single null-byte as data content. When reached without finding the 'Key' byte an error is issued.

---

There are way more details than fits this answer - so you may want to check additional manuals :)) (*3)

---

*1 - Anything from sequential search to peeking into the file by halved search using O(log n). Maybe better check the German Wiki entry for a nice figure.

*2 - LDOS is used here as short hand for the whole TRSDOS/NewDOS/VDOS/LDOS/... family as the base for all mentioned features originate with Mr. Cook's original TRSDOS.

*3 - Randy Cook, who single handed created TRSDOS and later VDOS, clearly moved mainframe ideas to the micro - way more than any other (DOS) system I know. And as much as I shunned all things x80 and Tandy especially, TRSDOS/VDOS/LDOS was a true beauty. I wish others had copied it instead of primitive CP/M. Personally I also think his high ambitions were part of the reasons original TRSDOS was so bad (that and Tandy's inability to create products). It's a marvel how nice the system is. He put many lessons learned from 20+ years mainframes onto the micro.

*4 - Serious, I do not understand why people even started to fight endless about packaging, delivery, managers or whatever is the delivery buzz of the day.

*5 - In fact, the linked file already explains term and how it works in great detail. It can also be found nicer form here.

*6 - Attentive readers will notice by now that records in a library are not sequenced by their type numbers. While they for sure could do so, and will do so in some ISAM based mainframe library systems, it's way more convenient to have them in an order allowing monotone incremental read.

*7 - Guess that direct access using the stored sector and offset within the file is why they called it ISAM.

Answer 2

The file you linked is about LDOS, an OS for the TRS-80 made by Logical Systems:

LDOS evolved from an operating system called VTOS 4.0, which was written by Randy Cook, the same programmer who wrote the original Model I TRSDOS (up through version 2.1) for Tandy. Lobo couldn't use Model I TRSDOS on their hardware, because they were selling an improved disk interface of their own design (the LX-80) that was not hardware compatible with Radio Shack's disk interface. VTOS had a second boot sector and additional code that enabled it to boot and run on both platforms, and was quite a bit more advanced than TRSDOS.

Lobo had a falling out with Randy Cook, the details of which I wasn't privy to, and they hired Galactic and Misosys to work on fixing bugs in VTOS. They were unable to obtain the source code, so all the work was based on the raw machine code. Fortunately Roy had an excellent disassembler! The project soon expanded from an effort to fix up VTOS for use by LX-80 owners into a joint venture to produce a new version of the operating system, called LDOS, for sale to the TRS-80 public at large.

If you look at the LDOS manual, it contains quite a few concepts carried over from IBM mainframes, for example the name JCL (job control language) for the /CMD files.

In an IBM mainframe context, a "data set" is a file, a "partioned data set" (PDS) is something like a directory and its contents (actually a "structured file", if you want), and ISAM is the IBM security access manager, responsible for access rights.

And indeed, reading through the file description you linked, PDS seems to be some kind of directory (probably inspired by IBM PDS), and there are access rights to files described in the manual (ATTRIBUTE command), which is probably handled by the ISAM entry somehow.