# 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, but if you've based your PiDP-8/I on a different Pi OS that does not enable SSH by default, it's easy to fix:

     $ sudo systemctl enable ssh
     $ sudo systemctl start ssh

Once you have a [secure connection to your Pi, you *may* be able to copy-and-paste the text into whatever program wants it. You could 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, then 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.

I wrote "*may*" above because 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.


## <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 assumes it is getting it from a normal PDP-8 peripheral such as the "high speed" paper tape reader, 300 bits per second at fastest, and it will choke when given input much faster than that.

We can solve these problems with 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 Enter then 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.

The Enter keystroke before Ctrl-Z isn't always necessary, but some OS/8 programs won't be happy if they hit EOF on a line without a CR+LF pair.


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

Sometimes you would rather not use the clipboard, but would prefer to send a host-side file 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`. That makes this method most useful for repeated bulk transfers.

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="os8-cp"></a>`os8-cp`

Bill Cattey *also* wrote the [`os8-cp` program][os8cp] to copy individual files into and out of the OS/8 environment from the host side.

I find this method most helpful when programming the PDP-8 as it greatly simplifies the edit-compile-debug cycle. It allows you to edit the file on the host side, re-run the `os8-cp` command you construct once, then build the new software inside the simulator. (And you can automate that final step with an OS/8 BATCH file.)

The `os8-cp` program is inspired by the POSIX `cp` program, but because of assorted complexities in the process, its usage isn't as simple as one would like. To copy the local file to `DSK:` on the OS/8 side, you'd say:

    $ os8-cp -rk0s bin/v3d.rk05 -a dsk:

Shell scripts and shell history makes it easy enough to re-run this moderately complex program with a few keystrokes.

See [the `os8-cp` manual][os8cp] for more details.

[os8cp]:


## <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-2019 by Warren Young. This document is licensed under the terms of [the SIMH license][sl].

[sl]: