# Introduction

There are many cases when working with the PiDP-8/I where the first problem you have to solve is getting some substantial body of text into the simulation. This article collects many of these methods, because many of them work across multiple software systems, so a central resource is wanted.


# <a id="ssh"></a>SSH

One method is to make use of the fact that many PiDP-8/I builds will be based on a networked Pi, which pretty much excludes only the Pi A+ and the original version of the Pi Zero, and then only if you haven't fixed the lack by adding a USB network adapter.

The [binary OS images](/) shipped by this project have SSH enabled and listening by default, and it's easy to enable it on your own Pi if you built it up from some other OS. For Raspbian Stretch and newer, the commands are:

     $ sudo systemctl enable ssh
     $ sudo systemctl start ssh

Other versions of Linux call this service `sshd` or `opensshd` instead.

Once you have a [secure connection to your Pi, you can often just copy-and-paste the text into whatever program wants it. If you have a text file open in a GUI text editor on the desktop computer that also has the SSH connection open to the PiDP-8/I, you could say Select All and Copy in the text editor, then Alt-Tab over to the SSH window and Paste directly into the program wanting the text.

Beware: This method only works with programs that handle terminal I/O in such a way that they can hold off on accepting each input character until the simulator — which is far slower at handling I/O than your host system — is ready for it. Some PDP-8 programs are simply not built to cope with this, such as U/W FOCAL. If you try this method and the pasted text ends up trashed inside the simulator, you will have to switch to one of the alternatives below, such as [the `PIP` solution](#pip).


# OS/8

There are a number of methods for getting text into the simulator that depend on features of OS/8. These solutions are grouped here in case you're not running OS/8, in which case these options will probably be of no use to you.


## <a id="pip"></a>PIP

Sometimes the program you're running has no way of receiving text directly from the terminal, but needs it from a disk file instead. Other times, the PDP-8 program you're working with does accept terminal input, but only at "high speed" paper tape reader speeds at best. (300 bits per second.) Solving this sort of copy in-to-out problem is the purpose of the OS/8 `PIP` program.


### <a id="pip-paste"></a>Terminal Paste

Starting with the [SSH option](#ssh) above, you can send pasted text to an OS/8 disk file with:

    .R PIP
    *MYFILE.TX<TTY:
    blah blah blah ...         ⇠ paste text in here
    ^Z                         ⇠ press Ctrl-Z to signal EOF
    *                          ⇠ press Escape to exit PIP

That will drop you back into OS/8 with a file called `DSK:MYFILE.TX` containing the pasted text.


### <a id="pip-pt"></a>Simulated Paper Tape

Sometimes you would rather not use the clipboard, but rather send a file on the host side directly into the simulator. With the help of Bill Cattey's `txt2ptp` program, which we've been shipping since the 2017.12.22 release, you can now easily do that.

First, you must convert the host-side text file to the format used by SIMH for its paper tape images:

    $ txt2ptp < myfile.txt > myfile.pt

The `txt2ptp` program (and its inverse, `ptp2txt`) is a [filter][wpf] which takes any ASCII text in and writes it to SIMH paper tape format as output. It converts LF line endings on its input to the CR+LF format expected by pretty much all OS/8 programs. The filter also takes care of details such as prepending a tape leader, coping with EOF characters, etc.

Next, you attach the paper tape to the simulator. From within the simulator, hit <kbd>Ctrl-E</kbd> to escape to the SIMH command prompt, then say:

    sim> attach ptr myfile.pt
    sim> cont

That attaches the paper tape image file you created above to the simulated PDP-8's <b>p</b>aper <b>t</b>ape <b>r</b>eader, then <b>cont</b>inues the simulation. You can abbreviate these commands to `at` and `c`, respectively.

Now we can use [`PIP`](#pip) in a slightly different way than above to pull the text into the simulator:

    .R PIP
    *MYFILE.TX<PTR:
    ^*$                   ⇠ press Escape twice when ^ appears to exit PIP

The `^` output above signals that PIP has found end-of-file on the paper tape input. The `*` is the PIP prompt after you hit <kbd>Escape</kbd> the first time, and the `$` is the result of hitting it the second time. That will drop you back to the OS/8 `.` prompt with a newly-written file called `DSK:MYFILE.TX`.

Beware that SIMH treats its simulated paper tapes the same way a real PDP-8 would: you get a single linear read, then the paper tape "falls out" of the simulator's paper tape reader. You must run the `attach` command again to read that paper tape again.

[wpf]:


## <a id="txt2os8"></a>Create OS/8 Media

Bill Cattey also wrote a script which automates some of the above, which is useful when you've got some number of text files on the host side and simply want them copied to a simulated OS/8 medium image:

    $ txt2os8 --rk05a mydisk.rk05

This creates (or updates) the first sub-device on the RK05 disk image file `mydisk.rk05`, copying in files listed in `mydisk.rk05.list`.

This script can update the second sub-device (`--rk05b`) or a TU56 tape image (`--tu56`) instead.

Once you have this media image, you can `attach` it to the simulator and work with the files on it directly:

    Ctrl-E
    sim> att dt0 mytape.tu56
    sim> cont
    .DIR DTA0:
    ...                                ⇠ list of files on mytape.tu56


## <a id="lang"></a>Programming Environments

Some of the programming language environments available within our OS/8 distribution have their own ways of pulling text in from external media. See for example the [many methods][uwfl] we've cataloged for doing this in U/W FOCAL. Even if you aren't using FOCAL, some of the ideas there may spark ideas you can use in your programming environment of choice.

[uwfl]:


# License

Copyright © 2018 by Warren Young. This document is licensed under the terms of [the SIMH license][sl].

[sl]: